import type { Update } from "./telegram-types.js";
/** default cap on an update's body size — telegram updates are tiny; anything wildly larger is abuse. */
export declare const MAX_BODY: number;
/**
 * constant-time string compare so the secret-token check can't be timed.
 * pure js (no node:crypto / Buffer) so it runs on node, bun, deno and edge/web.
 * shared with the node webhook handler; not part of the public index.
 */
export declare function safeEqual(a: string, b: string): boolean;
/**
 * offered one api call per update: `claim` returns true when the call was taken
 * as the webhook's HTTP response (so it must not go over the network too).
 * created by `webhookCallback` when `reply` is enabled; consumed via
 * `withReplyEnvelope` in the api layer.
 */
export interface WebhookReplyEnvelope {
    claim(method: string, params: Record<string, unknown> | undefined): boolean;
}
/** per-update options for {@link UpdateSink.handleUpdate}. */
export interface HandleUpdateOptions {
    /** route one eligible api call into the webhook's HTTP response instead of its own request. */
    replyEnvelope?: WebhookReplyEnvelope;
}
/** anything that can take a single update — i.e. a `Bot`. */
export interface UpdateSink {
    handleUpdate(update: Update, options?: HandleUpdateOptions): Promise<void>;
    /**
     * resolve the bot's own account (`getMe`) so `ctx.me` and `/cmd@botname`
     * addressing work without `start()`. the webhook handler calls it lazily on
     * the first update; absent (e.g. plain test sinks) it's simply skipped.
     */
    init?(): Promise<unknown>;
}
/**
 * platform escape hatch passed as the handler's second argument: on serverless
 * runtimes that kill work once the response is sent (cloudflare's
 * `ctx.waitUntil`), timed-out updates are handed here so they can finish.
 */
export interface WebhookExecutionContext {
    waitUntil?(promise: Promise<unknown>): void;
}
/** a fetch-style webhook handler. the second argument is optional platform glue. */
export type WebhookHandler = (request: Request, execution?: WebhookExecutionContext) => Promise<Response>;
export interface WebhookOptions {
    /** if set, require telegram's `X-Telegram-Bot-Api-Secret-Token` header to match. */
    secretToken?: string;
    /** only serve this exact pathname; other paths go to `fallback` (or 404). */
    path?: string;
    /**
     * handle requests the webhook doesn't own — wrong path or non-POST method —
     * e.g. health checks. without it those answer 404 / 405.
     */
    fallback?: (request: Request) => Response | Promise<Response>;
    /** max body size in bytes, enforced while streaming (default 1 MiB). */
    maxBodyBytes?: number;
    /**
     * how long an update may run before the webhook answers anyway, in ms
     * (default 10 000; `0` disables). telegram redelivers updates whose request
     * hangs, so answering beats being timed out remotely.
     */
    timeoutMs?: number;
    /**
     * what to answer when `timeoutMs` is exceeded. `"ack"` (default) returns 200
     * and lets the update finish in the background (logged; pass the platform's
     * `waitUntil` on serverless so it survives) — telegram won't redeliver.
     * `"fail"` returns 500 — telegram redelivers later, so the handler must be
     * idempotent. or a custom response.
     */
    onTimeout?: "ack" | "fail" | ((update: Update) => Response | Promise<Response>);
    /**
     * what to answer when handling throws (an error handler that rethrows, a
     * failing `init`). `"fail"` (default) returns 500 — telegram redelivers the
     * update with backoff, which also means a deterministic crash repeats until
     * it ages out. `"ack"` returns 200 — the update is dropped after the log
     * line. or a custom response.
     */
    onError?: "fail" | "ack" | ((error: unknown, update?: Update) => Response | Promise<Response>);
    /**
     * webhook reply: answer the webhook's HTTP request with an api call instead
     * of making a separate request — saves a round trip per update. `true`
     * allows any upload-free call; a predicate restricts it (e.g. only
     * `sendChatAction`). caveats: the call's promise resolves `true` (telegram
     * doesn't return the result), and it's delivered *after* any later direct
     * calls the handler makes.
     */
    reply?: boolean | ((method: string, params?: Record<string, unknown>) => boolean);
}
/** telegram rejects other secrets at `setWebhook` time — fail fast and locally instead. */
export declare function assertSecretToken(secret: string | undefined): void;
/**
 * a fetch-style webhook handler — `(Request) => Response`. works on bun, deno,
 * cloudflare workers, and any runtime with the fetch globals. `@yaebal/web`
 * wraps this into adapters for every mainstream framework/platform.
 */
export declare function webhookCallback(bot: UpdateSink, options?: WebhookOptions): WebhookHandler;
//# sourceMappingURL=webhook.d.ts.map