@greatwait/contracts 0.1.0-alpha.1

package/dist/time.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+export declare const timestampSchema: z.ZodString;
+export type Timestamp = z.infer<typeof timestampSchema>;
+/** Formats an instant in the one representation the wire accepts. */
+export declare function toTimestamp(instant: Date): Timestamp;
+/**
+ * Durations are whole seconds, never strings. Bounds belong to the resource
+ * that uses them; this only fixes the representation.
+ */
+export declare const durationSecondsSchema: z.ZodNumber;
+export type DurationSeconds = z.infer<typeof durationSecondsSchema>;
+/**
+ * An IANA timezone name, carried alongside a recurrence rather than encoded
+ * into an instant.
+ *
+ * Two independent requirements, and getting either wrong fires a schedule at
+ * the wrong hour:
+ *
+ * 1. **A region component is required.** This is what refuses ambiguous
+ *    abbreviations without curating a list of the safe ones. `Intl` resolves
+ *    `BST` to `Asia/Dhaka`, so a British caller meaning British Summer Time
+ *    would be scheduled six hours away and every response would look correct.
+ *    `CET`, `GMT`, `EST5EDT`, `Eire`, `Japan` and `Israel` go the same way.
+ * 2. **It must resolve to a zone this runtime knows.** That is what refuses
+ *    fixed offsets: `+01:00` and `Etc/GMT+5` resolve to themselves and are not
+ *    zones but constant offsets with no daylight-saving rules, so a schedule
+ *    carrying one drifts from its owner's wall clock the day the clocks
+ *    change. (`Etc/GMT+5` is also UTC−5, not UTC+5.)
+ *
+ * Resolution happens before the membership test, deliberately.
+ * `Intl.supportedValuesOf` returns CLDR-canonical names, and for a number of
+ * zones CLDR's canonical name is the *deprecated* IANA link: exact membership
+ * accepts `Asia/Calcutta` and refuses `Asia/Kolkata`, the name IANA has used
+ * since 1993 and the one every other language's timezone library emits. The
+ * same holds for `Europe/Kyiv`, `Asia/Ho_Chi_Minh`, `Asia/Yangon`,
+ * `America/Nuuk` and `America/Argentina/Buenos_Aires`. Resolving first accepts
+ * both spellings and is immune to CLDR later migrating to the IANA names.
+ */
+/**
+ * The one spelling of a zone that this contract stores and returns, beside
+ * `toTimestamp` for instants. Throws on a name the runtime does not know.
+ */
+export declare function toTimeZone(value: string): string;
+export declare const timeZoneSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+export type TimeZone = z.infer<typeof timeZoneSchema>;

package/dist/time.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+/**
+ * Time on the wire.
+ *
+ * Every instant is an RFC 3339 timestamp in UTC with millisecond precision and
+ * a literal `Z`. No local offsets, no bare dates, no epoch numbers. A schedule
+ * that fires at the wrong moment is the worst defect this product can have, so
+ * the wire format is deliberately narrow: one representation, no parsing
+ * ambiguity, and no timezone inference anywhere in a client.
+ *
+ * The legacy scheduler accepted any `Date`-parseable string and returned
+ * whatever `toISOString()` produced. Narrowing this is a deliberate break.
+ *
+ * IANA timezones appear only where a human genuinely means a wall clock — the
+ * `cron` recurrence — and are carried as a separate named field, never folded
+ * into the instant.
+ */
+const RFC3339_UTC_MS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+export const timestampSchema = z
+    .string()
+    .regex(RFC3339_UTC_MS, "must be an RFC 3339 UTC timestamp with millisecond precision, e.g. 2026-07-28T15:00:00.000Z")
+    // A regex alone is not enough: JavaScript happily "parses" 2026-02-31 and
+    // silently rolls it forward to 3 March. Round-tripping through Date is the
+    // only check that rejects a well-shaped calendar impossibility, and a
+    // scheduler that accepts a date that does not exist will fire at a time the
+    // customer never asked for.
+    .refine((value) => {
+    const parsed = new Date(value);
+    // Guarded because checks still run after the pattern fails, and
+    // `toISOString` throws rather than returning NaN on an invalid Date.
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString() === value;
+}, { message: "must be a real instant on the calendar" });
+/** Formats an instant in the one representation the wire accepts. */
+export function toTimestamp(instant) {
+    if (Number.isNaN(instant.getTime())) {
+        throw new RangeError("cannot format an invalid Date");
+    }
+    return instant.toISOString().replace(/\.(\d{3})\d*Z$/u, ".$1Z");
+}
+/**
+ * Durations are whole seconds, never strings. Bounds belong to the resource
+ * that uses them; this only fixes the representation.
+ */
+export const durationSecondsSchema = z
+    .number()
+    .int("must be a whole number of seconds")
+    .nonnegative("must not be negative");
+let canonicalZones;
+/**
+ * The zone identifiers this runtime recognizes, plus `UTC`.
+ *
+ * Built lazily so a runtime without `Intl.supportedValuesOf` fails when a
+ * timezone is validated rather than when the contracts package is imported,
+ * which would take every adapter down with it.
+ */
+function zones() {
+    canonicalZones ??= new Set([...Intl.supportedValuesOf("timeZone"), "UTC"]);
+    return canonicalZones;
+}
+/**
+ * An IANA timezone name, carried alongside a recurrence rather than encoded
+ * into an instant.
+ *
+ * Two independent requirements, and getting either wrong fires a schedule at
+ * the wrong hour:
+ *
+ * 1. **A region component is required.** This is what refuses ambiguous
+ *    abbreviations without curating a list of the safe ones. `Intl` resolves
+ *    `BST` to `Asia/Dhaka`, so a British caller meaning British Summer Time
+ *    would be scheduled six hours away and every response would look correct.
+ *    `CET`, `GMT`, `EST5EDT`, `Eire`, `Japan` and `Israel` go the same way.
+ * 2. **It must resolve to a zone this runtime knows.** That is what refuses
+ *    fixed offsets: `+01:00` and `Etc/GMT+5` resolve to themselves and are not
+ *    zones but constant offsets with no daylight-saving rules, so a schedule
+ *    carrying one drifts from its owner's wall clock the day the clocks
+ *    change. (`Etc/GMT+5` is also UTC−5, not UTC+5.)
+ *
+ * Resolution happens before the membership test, deliberately.
+ * `Intl.supportedValuesOf` returns CLDR-canonical names, and for a number of
+ * zones CLDR's canonical name is the *deprecated* IANA link: exact membership
+ * accepts `Asia/Calcutta` and refuses `Asia/Kolkata`, the name IANA has used
+ * since 1993 and the one every other language's timezone library emits. The
+ * same holds for `Europe/Kyiv`, `Asia/Ho_Chi_Minh`, `Asia/Yangon`,
+ * `America/Nuuk` and `America/Argentina/Buenos_Aires`. Resolving first accepts
+ * both spellings and is immune to CLDR later migrating to the IANA names.
+ */
+/**
+ * The one spelling of a zone that this contract stores and returns, beside
+ * `toTimestamp` for instants. Throws on a name the runtime does not know.
+ */
+export function toTimeZone(value) {
+    if (value === "UTC") {
+        return "UTC";
+    }
+    return new Intl.DateTimeFormat("en", { timeZone: value }).resolvedOptions()
+        .timeZone;
+}
+export const timeZoneSchema = z
+    .string()
+    .min(1)
+    .refine((value) => {
+    if (value === "UTC") {
+        return true;
+    }
+    if (!value.includes("/")) {
+        return false;
+    }
+    try {
+        return zones().has(new Intl.DateTimeFormat("en", { timeZone: value }).resolvedOptions()
+            .timeZone);
+    }
+    catch {
+        return false;
+    }
+}, {
+    message: "must be an IANA timezone with a region, such as Europe/London or Asia/Kolkata, or UTC — not an abbreviation like BST or a fixed offset like +01:00",
+})
+    // Canonicalized, for the same reason instants have exactly one spelling.
+    // `Intl` matches zone names case-insensitively and both spellings of a
+    // renamed zone are accepted, so without this `Europe/London`,
+    // `europe/london`, `Asia/Kolkata` and `Asia/Calcutta` would be four distinct
+    // contract values denoting two zones. Nothing fires at the wrong hour, but
+    // schedules meaning the same wall clock would compare unequal, a forecast
+    // breakdown keyed on timezone would split, and an edit changing only the
+    // spelling would bump the optimistic version and write a spurious audit
+    // diff. Deciding this now is free; after W2 persists the first raw string it
+    // is a breaking response change plus a data migration.
+    .transform(toTimeZone);

package/dist/usage.d.ts

@@ -0,0 +1,121 @@
+import { z } from "zod";
+import type { FieldError } from "./problems.js";
+/**
+ * What a customer is charged for, and nothing about what it cost to deliver.
+ *
+ * **One terminal occurrence is one billable unit, however many attempts it
+ * took.** That is the commercial rule the whole runtime is built around — a
+ * retry is our cost, not the customer's — and this surface exists so it is
+ * something a customer can see rather than something they are told. A schedule
+ * that failed four times and succeeded on the fifth appears here once; the
+ * five attempts are on the occurrence's own attempt history, which is the page
+ * that answers "what did it cost us".
+ *
+ * Days are UTC and half-open, aligned to midnight at both ends. A tenant-local
+ * boundary would make every bucket a different width for a different customer
+ * and could not be one index range; the capacity decision states the budget in
+ * UTC days for the same reason.
+ *
+ * A day with no billable occurrence is **absent** rather than zero. The window
+ * says which days the answer covers, so an absent day is unambiguous, and a
+ * quiet month is a short document rather than thirty-one zeroes.
+ */
+export declare const USAGE_BOUNDS: {
+    /** Days a window covers when the caller names neither end. */
+    readonly defaultWindowDays: 31;
+    /**
+     * The widest window this contract will describe.
+     *
+     * A year, because usage is read by a person reconciling a bill and a bill is
+     * never older than that. It is a contract ceiling rather than a plan one: a
+     * plan may bring it closer and may never push it out.
+     */
+    readonly maxWindowDays: 366;
+};
+/** How a billable occurrence ended. The four terminal occurrence states. */
+export declare const BILLABLE_TERMINAL_STATES: readonly ["cancelled", "skipped_stale", "succeeded", "terminal_failed"];
+export declare const billableTerminalStateSchema: z.ZodEnum<{
+    succeeded: "succeeded";
+    cancelled: "cancelled";
+    terminal_failed: "terminal_failed";
+    skipped_stale: "skipped_stale";
+}>;
+export type BillableTerminalStateName = z.infer<typeof billableTerminalStateSchema>;
+export declare const usageRequestSchema: z.ZodObject<{
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type UsageRequest = z.infer<typeof usageRequestSchema>;
+export type UsageRequestParse = {
+    readonly errors: readonly FieldError[];
+    readonly ok: false;
+} | {
+    readonly ok: true;
+    readonly request: UsageRequest;
+};
+/**
+ * Read a usage request off a URL.
+ *
+ * One reader, so the REST service and the published contract mock cannot
+ * disagree about `from=yesterday`. A repeated parameter is a refusal rather
+ * than a last-one-wins guess, for the reason the forecast reader gives: two
+ * different windows in one request is a caller bug, and answering one of them
+ * silently is how it stays a bug.
+ */
+export declare function parseUsageRequest(query: URLSearchParams): UsageRequestParse;
+/** What a caller is told when a usage window is refused rather than served. */
+export declare const USAGE_WINDOW_REASONS: Readonly<Record<UsageWindowRefusal, string>>;
+export declare const usageDaySchema: z.ZodObject<{
+    billableOccurrences: z.ZodNumber;
+    byTerminalState: z.ZodRecord<z.ZodEnum<{
+        succeeded: "succeeded";
+        cancelled: "cancelled";
+        terminal_failed: "terminal_failed";
+        skipped_stale: "skipped_stale";
+    }> & z.core.$partial, z.ZodNumber>;
+    start: z.ZodString;
+}, z.core.$strip>;
+export type UsageDayView = z.infer<typeof usageDaySchema>;
+export declare const usageSchema: z.ZodObject<{
+    days: z.ZodArray<z.ZodObject<{
+        billableOccurrences: z.ZodNumber;
+        byTerminalState: z.ZodRecord<z.ZodEnum<{
+            succeeded: "succeeded";
+            cancelled: "cancelled";
+            terminal_failed: "terminal_failed";
+            skipped_stale: "skipped_stale";
+        }> & z.core.$partial, z.ZodNumber>;
+        start: z.ZodString;
+    }, z.core.$strip>>;
+    freshness: z.ZodObject<{
+        kind: z.ZodLiteral<"authoritative">;
+    }, z.core.$strip>;
+    totalBillableOccurrences: z.ZodNumber;
+    window: z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type UsageView = z.infer<typeof usageSchema>;
+export type UsageWindowRefusal = "window-inverted" | "window-too-wide" | "window-unreadable";
+export type ResolvedUsageWindow = {
+    readonly ok: false;
+    readonly refusal: UsageWindowRefusal;
+} | {
+    readonly fromMs: number;
+    readonly ok: true;
+    readonly toMs: number;
+};
+/** UTC midnight of the day an instant falls in. */
+export declare function utcMidnightMs(instantMs: number): number;
+/**
+ * Resolve the window a usage request names, aligned to UTC days.
+ *
+ * **Both ends are snapped to midnight, and that is not tidiness.** The answer
+ * is bucketed by UTC day; a window beginning at nine in the morning would put a
+ * partial day at the front of the list with no way for a reader to tell it from
+ * a quiet one. Snapping outward — the start of `from`'s day, the start of the
+ * day after `to`'s — means the window always covers whole days and never covers
+ * less than what was asked for.
+ */
+export declare function resolveUsageWindow(request: UsageRequest, nowMs: number): ResolvedUsageWindow;

package/dist/usage.js

@@ -0,0 +1,200 @@
+import { z } from "zod";
+import { timestampSchema } from "./time.js";
+/**
+ * What a customer is charged for, and nothing about what it cost to deliver.
+ *
+ * **One terminal occurrence is one billable unit, however many attempts it
+ * took.** That is the commercial rule the whole runtime is built around — a
+ * retry is our cost, not the customer's — and this surface exists so it is
+ * something a customer can see rather than something they are told. A schedule
+ * that failed four times and succeeded on the fifth appears here once; the
+ * five attempts are on the occurrence's own attempt history, which is the page
+ * that answers "what did it cost us".
+ *
+ * Days are UTC and half-open, aligned to midnight at both ends. A tenant-local
+ * boundary would make every bucket a different width for a different customer
+ * and could not be one index range; the capacity decision states the budget in
+ * UTC days for the same reason.
+ *
+ * A day with no billable occurrence is **absent** rather than zero. The window
+ * says which days the answer covers, so an absent day is unambiguous, and a
+ * quiet month is a short document rather than thirty-one zeroes.
+ */
+export const USAGE_BOUNDS = {
+    /** Days a window covers when the caller names neither end. */
+    defaultWindowDays: 31,
+    /**
+     * The widest window this contract will describe.
+     *
+     * A year, because usage is read by a person reconciling a bill and a bill is
+     * never older than that. It is a contract ceiling rather than a plan one: a
+     * plan may bring it closer and may never push it out.
+     */
+    maxWindowDays: 366,
+};
+/** How a billable occurrence ended. The four terminal occurrence states. */
+export const BILLABLE_TERMINAL_STATES = [
+    "cancelled",
+    "skipped_stale",
+    "succeeded",
+    "terminal_failed",
+];
+export const billableTerminalStateSchema = z.enum(BILLABLE_TERMINAL_STATES);
+export const usageRequestSchema = z
+    .object({
+    /** Inclusive start. Defaults to `defaultWindowDays` before the end. */
+    from: timestampSchema.optional(),
+    /** Exclusive end. Defaults to the start of tomorrow, UTC. */
+    to: timestampSchema.optional(),
+})
+    .strict();
+const USAGE_PARAMETERS = ["from", "to"];
+/**
+ * Read a usage request off a URL.
+ *
+ * One reader, so the REST service and the published contract mock cannot
+ * disagree about `from=yesterday`. A repeated parameter is a refusal rather
+ * than a last-one-wins guess, for the reason the forecast reader gives: two
+ * different windows in one request is a caller bug, and answering one of them
+ * silently is how it stays a bug.
+ */
+export function parseUsageRequest(query) {
+    const errors = [];
+    const raw = {};
+    for (const field of USAGE_PARAMETERS) {
+        const values = query.getAll(field);
+        if (values.length > 1) {
+            errors.push({
+                pointer: `/${field}`,
+                reason: "must be given at most once",
+            });
+            continue;
+        }
+        const value = values[0];
+        if (value === undefined)
+            continue;
+        raw[field] = value;
+    }
+    if (errors.length > 0)
+        return { errors, ok: false };
+    const parsed = usageRequestSchema.safeParse(raw);
+    if (parsed.success)
+        return { ok: true, request: parsed.data };
+    return {
+        errors: parsed.error.issues.map((issue) => ({
+            pointer: `/${issue.path.join("/")}`,
+            reason: issue.message,
+        })),
+        ok: false,
+    };
+}
+/** What a caller is told when a usage window is refused rather than served. */
+export const USAGE_WINDOW_REASONS = {
+    "window-inverted": "must end after it begins",
+    "window-too-wide": `must cover at most ${String(USAGE_BOUNDS.maxWindowDays)} days`,
+    "window-unreadable": "must be an RFC 3339 instant",
+};
+export const usageDaySchema = z.object({
+    billableOccurrences: z.number().int().positive(),
+    /**
+     * How the day's billable occurrences ended.
+     *
+     * Sums to `billableOccurrences`, and a state with no occurrences is absent
+     * rather than zero — the same rule the day list follows, one level down.
+     */
+    byTerminalState: z.partialRecord(billableTerminalStateSchema, z.number().int().positive()),
+    /** UTC midnight of the day this bucket covers. */
+    start: timestampSchema,
+});
+export const usageSchema = z
+    .object({
+    /** Ascending by `start`. Days with no billable occurrence are absent. */
+    days: z.array(usageDaySchema),
+    /**
+     * Authoritative, because this is the committed model the settlement wrote.
+     *
+     * A usage fact is inserted in the same transaction that settles the
+     * occurrence, so there is no projection behind this to be stale — which is
+     * exactly why it is served from the authority and cannot be served from a
+     * summary.
+     */
+    freshness: z.object({ kind: z.literal("authoritative") }),
+    totalBillableOccurrences: z.number().int().nonnegative(),
+    window: z.object({ from: timestampSchema, to: timestampSchema }),
+})
+    // **Three invariants this document promised in prose and nothing checked.**
+    // A reader is shown two numbers that must agree — the total and the days it
+    // is a total of — and a client has to choose one. Without these a service
+    // could publish a total that disagreed with its own breakdown and every
+    // consumer would be right to render either.
+    //
+    // They are refinements rather than schema shape because they are relations
+    // between fields, so they hold at the wire and not in the generated OpenAPI
+    // — which is where the route's own `usageSchema.parse` before serving earns
+    // its place.
+    .refine((usage) => usage.days.reduce((sum, day) => sum + day.billableOccurrences, 0) ===
+    usage.totalBillableOccurrences, {
+    message: "totalBillableOccurrences must be the sum of the days",
+    path: ["totalBillableOccurrences"],
+})
+    .refine((usage) => usage.days.every((day) => Object.values(day.byTerminalState).reduce((sum, count) => sum + count, 0) === day.billableOccurrences), {
+    message: "byTerminalState must account for every billable occurrence",
+    path: ["days"],
+})
+    .refine((usage) => usage.days.every((day) => {
+    const start = Date.parse(day.start);
+    return (start >= Date.parse(usage.window.from) &&
+        start < Date.parse(usage.window.to));
+}), {
+    // Half-open at the end, which is the one boundary worth stating: a day
+    // whose midnight *is* `to` is the first day outside the answer.
+    message: "every day must begin inside the window the answer covers",
+    path: ["days"],
+})
+    // Ascending, because the document says so and a client rendering a chart
+    // reads the array in order. An unsorted answer is not wrong twice — it is
+    // wrong once, in the place nobody looks.
+    .refine((usage) => usage.days.every((day, index) => index === 0 ||
+    Date.parse(day.start) > Date.parse(usage.days[index - 1].start)), {
+    message: "days must ascend by start and appear at most once",
+    path: ["days"],
+});
+const DAY_MS = 86_400_000;
+/** UTC midnight of the day an instant falls in. */
+export function utcMidnightMs(instantMs) {
+    const at = new Date(instantMs);
+    return Date.UTC(at.getUTCFullYear(), at.getUTCMonth(), at.getUTCDate());
+}
+/**
+ * Resolve the window a usage request names, aligned to UTC days.
+ *
+ * **Both ends are snapped to midnight, and that is not tidiness.** The answer
+ * is bucketed by UTC day; a window beginning at nine in the morning would put a
+ * partial day at the front of the list with no way for a reader to tell it from
+ * a quiet one. Snapping outward — the start of `from`'s day, the start of the
+ * day after `to`'s — means the window always covers whole days and never covers
+ * less than what was asked for.
+ */
+export function resolveUsageWindow(request, nowMs) {
+    const defaultToMs = utcMidnightMs(nowMs) + DAY_MS;
+    const requestedToMs = request.to === undefined ? defaultToMs : Date.parse(request.to);
+    if (!Number.isFinite(requestedToMs)) {
+        return { ok: false, refusal: "window-unreadable" };
+    }
+    const toMs = request.to === undefined
+        ? defaultToMs
+        : utcMidnightMs(requestedToMs) + DAY_MS;
+    const requestedFromMs = request.from === undefined
+        ? toMs - USAGE_BOUNDS.defaultWindowDays * DAY_MS
+        : Date.parse(request.from);
+    if (!Number.isFinite(requestedFromMs)) {
+        return { ok: false, refusal: "window-unreadable" };
+    }
+    const fromMs = utcMidnightMs(requestedFromMs);
+    if (fromMs >= toMs)
+        return { ok: false, refusal: "window-inverted" };
+    if (toMs - fromMs > USAGE_BOUNDS.maxWindowDays * DAY_MS) {
+        return { ok: false, refusal: "window-too-wide" };
+    }
+    return { fromMs, ok: true, toMs };
+}

package/dist/webhooks.d.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+/**
+ * Inbound webhook authenticity.
+ *
+ * Clerk delivers organization and membership changes through Svix, which signs
+ * `<svix-id>.<svix-timestamp>.<raw body>` with HMAC-SHA256 under a secret minted
+ * per endpoint. This module owns the encoding and the header vocabulary; the
+ * adapter owns the key material and the constant-time comparison, exactly as
+ * `signatures.ts` splits outbound callback signing.
+ *
+ * The split matters. Keeping the signed-byte construction in the contract layer
+ * means every verifier — the Worker, a test, a future replay tool — signs the
+ * same bytes, and the reasoning below is stated once instead of being
+ * rediscovered by whoever writes the second one.
+ */
+export declare const SVIX_HEADERS: {
+    readonly id: "svix-id";
+    readonly signature: "svix-signature";
+    readonly timestamp: "svix-timestamp";
+};
+/**
+ * Where Clerk delivers organization and membership changes.
+ *
+ * Deliberately outside `/v1`. W1-07 enforces REST/MCP parity over every public
+ * `/v1` operation, and a webhook ingress is not a customer-facing operation —
+ * putting it there would either break that check or require an exception to it.
+ * Follows the internal-route convention set by `/__greatwait/version`.
+ *
+ * **Here rather than in the Worker that serves it, since W4-08.** The smoke
+ * asks a hosted stage whether this route is configured to accept a delivery,
+ * and a script cannot import the API application. A second spelling of an
+ * address Clerk is pointed at is one that can drift while both read as
+ * correct.
+ */
+export declare const CLERK_WEBHOOK_PATH = "/__greatwait/webhooks/clerk";
+/** Only `v1` exists. A new scheme is added alongside, never in place of. */
+export declare const WEBHOOK_SIGNATURE_SCHEME: "v1";
+/**
+ * How far Clerk's clock may differ from ours before a delivery is stale.
+ *
+ * Svix's own guidance is five minutes, and matching it is deliberate: a tighter
+ * window would reject legitimate deliveries during a retry burst, and a wider
+ * one lengthens the replay window for a captured request.
+ */
+export declare const WEBHOOK_TOLERANCE_SECONDS = 300;
+/**
+ * A Svix message id. Deliberately a restricted charset rather than
+ * `z.string().min(1)` — see `webhookSigningInput` for why the absence of `.`
+ * here is a security property and not a formatting preference.
+ */
+export declare const svixIdSchema: z.ZodString;
+/**
+ * Seconds since the Unix epoch, as digits. No sign, no decimal point, no
+ * exponent — `Number.parseInt` would happily accept `+1e9` and `12.5`, and both
+ * would reach the signed bytes in a form we did not intend.
+ */
+export declare const svixTimestampSchema: z.ZodString;
+/**
+ * One `v1,<base64>` pair. Svix sends a space-delimited list so an endpoint can
+ * be verified under both keys during rotation, which is why the verifier must
+ * accept a match against *any* entry rather than parsing a single value.
+ */
+export declare const svixSignatureEntryPattern: RegExp;
+export declare const svixSignatureHeaderSchema: z.ZodString;
+export declare const svixHeadersSchema: z.ZodObject<{
+    "svix-id": z.ZodString;
+    "svix-signature": z.ZodString;
+    "svix-timestamp": z.ZodString;
+}, z.core.$strip>;
+/**
+ * Every `v1` signature offered in the header, base64 still encoded.
+ *
+ * Entries in other schemes are dropped rather than rejected: Svix may add a
+ * scheme before we support it, and a delivery that carries both `v1` and a
+ * future `v2` must still verify under `v1` instead of failing closed on the
+ * presence of something newer.
+ */
+export declare function webhookSignatureCandidates(header: string): readonly string[];
+/**
+ * The exact bytes Svix signs: `<id>.<timestamp>.` followed by the raw body,
+ * with no re-serialization anywhere in the path.
+ *
+ * Both prefix fields are validated rather than trusted, and — as with
+ * `signingInput` for outbound callbacks — that is a security property. The
+ * delimiter is `.`, so if either field could itself contain a `.` the encoding
+ * would not be injective: an attacker holding one legitimate signature could
+ * shift bytes across a delimiter, lengthening the id header while shortening
+ * the body, and still verify.
+ *
+ * The argument here is slightly different from the outbound one, which relies
+ * on both fields being fixed-width. `svixIdSchema` and `svixTimestampSchema`
+ * admit no `.` at all, so splitting the signed content on its first two dots
+ * recovers the id and the timestamp uniquely whatever their lengths. Variable
+ * width is fine; a dot would not be.
+ *
+ * **Throws** on malformed input. Use `tryWebhookSigningInput` when verifying
+ * headers off the wire, or a malformed-header probe becomes a 500.
+ */
+export declare function webhookSigningInput(svixId: string, svixTimestamp: string, rawBody: Uint8Array): Uint8Array;
+/**
+ * `webhookSigningInput` for untrusted input: `undefined` instead of a throw when
+ * the headers are malformed.
+ */
+export declare function tryWebhookSigningInput(svixId: string, svixTimestamp: string, rawBody: Uint8Array): Uint8Array | undefined;
+/**
+ * Whether a delivery's timestamp is close enough to now.
+ *
+ * Rejects the future as firmly as the past. A signature dated an hour ahead is
+ * not a clock-skew inconvenience — accepting it would hand an attacker who
+ * captures one request an hour of replay window, so the comparison is on
+ * absolute difference.
+ *
+ * Replay protection beyond this window belongs to the receiver, keyed on the
+ * Svix message id; freshness alone does not make a delivery unique.
+ */
+export declare function isWebhookTimestampFresh(svixTimestamp: string, nowMs: number, toleranceSeconds?: number): boolean;