@farthershore/backend 0.20.0 → 0.21.0

package/dist/types/index.d.ts

@@ -1,28 +1,29 @@
 import { FartherShore, type FartherShoreInitOptions } from "./core/runtime.js";
-import { type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type MiddlewareOptions, type VerifiedExpressHandler } from "./adapters/express.js";
+import { type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type HandlerOptions, type MiddlewareOptions, type VerifiedExpressHandler } from "./adapters/express.js";
+import { type PermissionCarrier } from "./core/permissions.js";
 export { FartherShore } from "./core/runtime.js";
 export type { FartherShoreInitOptions } from "./core/runtime.js";
 export { FartherShoreError, statusForCode } from "./core/errors.js";
-export { verifyRequest, type VerifyRequestInput, type VerifyRequestDeps, type FartherShoreRequestContext, type HeadersLike, } from "./core/verifyRequest.js";
+export { verifyRequest, type VerifyRequestInput, type VerifyRequestDeps, type FartherShoreContext, type FartherShoreRequestContext, type HeadersLike, } from "./core/verifyRequest.js";
+export { MEASUREMENTS_VERSION } from "./core/report.js";
+export type { ReportInput, ReportResult, ReportTransport, Measurement, MeasurementValues, MeasurementDimensions, QuoteInput, QuoteProposal, } from "./core/report.js";
 export { verifyContext, decodeContextClaims, principalFromContextClaims, } from "./core/verifyContext.js";
 export type { FartherShoreSignedContext, ConsumerPrincipal, } from "./core/verifyContext.js";
 export { requireMember, requireService, credentialKind, isPortalSession, type MemberSubject, type ServiceSubject, type PrincipalCarrier, } from "./core/subject.js";
-export { hasPermission, requirePermission, permissionGrants, permissionSatisfies, FartherShorePermissionError, type PermissionCarrier, } from "./core/permissions.js";
+export { hasPermission, requirePermission, permissionSatisfies, routePermission, READ_METHODS, FartherShorePermissionError, type PermissionCarrier, } from "./core/permissions.js";
 export { JwksClient, type Jwk, type JwksClientOptions } from "./core/jwks.js";
 export { NonceCache, type NonceCacheOptions, type NonceStore, } from "./core/nonceCache.js";
 export { type ReplayProtectionDiagnostic, type ReplayProtectionMode, } from "./core/replay-protection.js";
 export { BootstrapClient, type BootstrapClientOptions, } from "./core/bootstrap.js";
-export { MeteringClient, type MeteringClientOptions, type MeterOptions, } from "./core/metering.js";
-export { PostStreamUsageClient, type PostStreamUsageClientOptions, type ReportUsageInput, type RequestScopedReportUsageInput, type ReportUsageResult, } from "./core/post-stream-usage.js";
 export { buildHealthReport, reportHealth, type HealthSnapshot, type HealthStatus, type HeartbeatOptions, } from "./core/health.js";
 export { ShutdownManager, type ShutdownHook } from "./core/shutdown.js";
 export { CloudflaredSupervisor, nodeSpawn, REDACTED_TOKEN, type SpawnFn, type SpawnedTunnelProcess, type CloudflaredSupervisorOptions, type TunnelState, type TunnelStatus, } from "./core/tunnel.js";
 export type { FartherShoreTunnelOptions } from "./core/runtime.js";
-export { createExpressMiddleware, createExpressHandler, type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type ExpressNext, type MiddlewareOptions, type VerifiedExpressHandler, type VerifiedPrincipalContext, } from "./adapters/express.js";
+export { createExpressMiddleware, createExpressHandler, type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type ExpressNext, type HandlerOptions, type MiddlewareOptions, type VerifiedExpressHandler, type VerifiedPrincipalContext, } from "./adapters/express.js";
 export { FS_RUNTIME_TOKEN_ENV, RUNTIME_TOKEN_PREFIXES, RUNTIME_TOKEN_OPERATIONS, RUNTIME_HEADER_NAMES, RUNTIME_CLOCK_SKEW_SECONDS, RUNTIME_REPLAY_WINDOW_SECONDS, EMPTY_BODY_SHA256, STREAMING_EXEMPT_BODY_HASH, MAX_BODY_BYTES, type RuntimeErrorCode, type RuntimeTokenOperation, type CanonicalSigningInput, type RuntimeBootstrapResponse, type RuntimeMeteringEvent, type RuntimeHealthReport, type TransportMode, RUNTIME_ERROR_CODE_TO_ERROR_CODE, runtimeErrorToErrorCode, type LimitDescriptor, type RuntimeMappedErrorCode, } from "./runtime-types.js";
 export { RUNTIME_ERROR_CODES } from "./generated/runtime-contract.js";
 export { hashBody, buildCanonicalSigningString, canonicalizeQuery, signCanonicalString, verifyCanonicalSignature, runtimeTokenKind, } from "./runtime-signing.js";
-export { createUsage, withUsage, computeMeteringHeaders, MeteringError, METERING_PAYLOAD_HEADER, METERING_SIGNATURE_HEADER, METERING_TOKEN_HEADER, DEFAULT_TOKEN_ENV, type UsageMap, type UsageReporter, type MeteringOptions, type MeteringHeaders, type ComputeMeteringOptions, type ResponseMeteringUsagePayload, } from "./response-metering.js";
+export { computeMeteringHeaders, MeteringError, METERING_PAYLOAD_HEADER, METERING_SIGNATURE_HEADER, METERING_TOKEN_HEADER, DEFAULT_TOKEN_ENV, type MeteringHeaders, type ComputeMeteringOptions, type ResponseMeteringUsagePayload, } from "./response-metering.js";
 /**
  * The conceptual public entrypoint. `fartherShore.initFromEnv()` mirrors the
  * language-neutral spec. The returned instance is augmented with `middleware()`
@@ -38,7 +39,27 @@ export type FartherShoreInstance = FartherShore & {
      * context is absent, `principal_required` when it is identity-less) before the
      * callback runs. Pairs with the strict `middleware()`.
      */
-    handler<Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
+    handler: {
+        <Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
+        /**
+         * Options-first overload: `fs.handler({ permission: "widgets:write" }, cb)`
+         * asserts the permission (fail-closed) before the callback runs,
+         * responding `403 permission_denied` otherwise.
+         */
+        <Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(options: HandlerOptions, handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
+    };
+    /**
+     * In-handler authorization helpers bound to the instance — the SAME shape as
+     * the dev runtime's `rt.authz` (which additionally traces each decision), so
+     * dev and prod code reads identically. Both key ONLY on `ctx.permissions`
+     * with FAIL-CLOSED carrier semantics: an ABSENT permission set DENIES.
+     */
+    authz: {
+        /** True when the acting user holds `key` (`*` / `<subject>:*` / exact). */
+        hasPermission(ctx: PermissionCarrier, key: string): boolean;
+        /** Assert `key` is held; throws `FartherShorePermissionError` (403). */
+        requirePermission(ctx: PermissionCarrier, key: string): void;
+    };
 };
 export declare const fartherShore: {
     /** Derive everything from FS_RUNTIME_TOKEN via bootstrap. */

package/dist/types/internal/index.d.ts

@@ -0,0 +1,2 @@
+export { createReportFn, rawDimsUnitsOf, type ReportChannels, type ResponseSink, type ReportFn, } from "../core/report.js";
+export { PostStreamUsageClient, type PostStreamUsageClientOptions, type ReportUsageInput, type ReportUsageResult, } from "../core/post-stream-usage.js";

package/dist/types/response-metering.d.ts

@@ -1,18 +1,39 @@
-declare const RESPONSE_METERING_ERROR_CODES: {
+/** The response-metering fault codes carried by {@link MeteringError}. */
+export declare const RESPONSE_METERING_ERROR_CODES: {
     readonly missingToken: "missing_token";
     readonly invalidMeterKey: "invalid_meter_key";
     readonly invalidMeterValue: "invalid_meter_value";
+    readonly invalidQuote: "invalid_quote";
 };
-type ResponseMeteringErrorCode = (typeof RESPONSE_METERING_ERROR_CODES)[keyof typeof RESPONSE_METERING_ERROR_CODES];
+export type ResponseMeteringErrorCode = (typeof RESPONSE_METERING_ERROR_CODES)[keyof typeof RESPONSE_METERING_ERROR_CODES];
 /**
  * The signed response-metering payload. `computeMeteringHeaders` accepts one of
  * these directly, so a non-Express / non-Fetch handler (or a Python/Go backend
- * following the wire recipe) can stamp valid headers without `withUsage`.
+ * following the wire recipe) can stamp valid headers with no JS SDK at all.
+ * `ctx.report()` is the JS surface that builds it.
+ *
+ * `measurements` (with its `measurementsVersion`) is the measurement lane the
+ * one reporting verb emits: `{ meter, values, dims }` as declared in the
+ * business release. `rawDimsUnits` remains as the flat projection the gateway's
+ * existing settlement lane reads.
  */
 export type ResponseMeteringUsagePayload = {
     method: string;
     path: string;
-    rawDimsUnits: Record<string, number>;
+    rawDimsUnits?: Record<string, number>;
+    /** Schema version of {@link measurements}; currently `1`. */
+    measurementsVersion?: number;
+    /** Reported measurements — the authoritative rating input. */
+    measurements?: {
+        meter: string;
+        values: Record<string, number>;
+        dims?: Record<string, string>;
+    }[];
+    /** Proposed rate input for a `backendQuoted` pricing rule (core clamps it). */
+    quote?: {
+        currency: string;
+        amountNanos: string;
+    };
     measureContext?: Record<string, unknown>;
     creditUnitsConsumed?: Record<string, number>;
     operationKey?: string;
@@ -43,43 +64,10 @@ export declare const METERING_PAYLOAD_HEADER: "x-fs-metering";
 export declare const METERING_SIGNATURE_HEADER: "x-fs-metering-sig";
 export declare const METERING_TOKEN_HEADER: "x-fs-metering-token";
 export declare const DEFAULT_TOKEN_ENV: "FS_RUNTIME_TOKEN";
-export type UsageMap = Record<string, number>;
-export type BillableUsageMap = UsageMap;
-export type MeteringOptions = {
-    token?: string;
-    env?: Record<string, string | undefined>;
-    /**
-     * Gateway request id for dev-mode trace/usage association (never signed).
-     * Thread the VERIFIED `ctx.requestId` here — the strict middleware strips the
-     * inbound `x-fs-request-id` header, so the request object no longer carries it.
-     * Falls back to the request's `x-fs-request-id` header when unset.
-     */
-    requestId?: string;
-    measureContext?: Record<string, unknown>;
-    creditUnitsConsumed?: BillableUsageMap;
-    /** Gateway-validated operation identity hint. The SDK signs and transports it
-     *  but never decides billing or policy from it. */
-    operationKey?: string;
-    /** Gateway-validated policy hint. Advisory identity only; the gateway remains
-     *  authoritative for customerBillable/provider-cost decisions. */
-    usagePolicyId?: string;
-};
-export type UsageWrapOptions = {
-    measureContext?: Record<string, unknown>;
-    creditUnitsConsumed?: BillableUsageMap;
-    operationKey?: string;
-    usagePolicyId?: string;
-};
-export type UsageReporter = {
-    report(meter: string, value: number): UsageReporter;
-    wrap(response: Response, options?: UsageWrapOptions): Promise<Response>;
-};
 export declare class MeteringError extends Error {
     readonly code: ResponseMeteringErrorCode;
     constructor(code: ResponseMeteringErrorCode, message: string);
 }
-export declare function createUsage(request: Request, options?: MeteringOptions): UsageReporter;
-export declare function withUsage(request: Request, response: Response, usage: UsageMap, options?: MeteringOptions): Promise<Response>;
 /**
  * Compute the three response-metering headers for a payload as a plain
  * name→value map, attachable to ANY response mechanism (Fetch `Response`,
@@ -87,7 +75,9 @@ export declare function withUsage(request: Request, response: Response, usage: U
  * primitive: it NEVER throws at request time — if no token is resolvable (or
  * signing fails) it skips stamping, reports the reason (`onSkip` / dev hook /
  * a `console.warn`), and returns `{}` so the builder's endpoint is never broken.
- * `withUsage`/`createUsage` are thin sugar over it.
+ *
+ * This is the framework-neutral wire recipe: `ctx.report()` is the JS surface
+ * over it, and a Python/Go backend can stamp identical headers by building the
+ * same payload (see `docs/response-metering-wire.md`).
  */
 export declare function computeMeteringHeaders(payload: ResponseMeteringUsagePayload, options?: ComputeMeteringOptions): Promise<MeteringHeaders>;
-export {};

package/dist/types/runtime-types.d.ts

@@ -37,7 +37,7 @@ export type LimitClass = "quota" | "rate" | "concurrency" | "capacity" | "spend"
  *  `LimitReaction`. */
 export type LimitReaction = "none" | "backoff_retry" | "wait_then_retry" | "queue" | "reduce_then_retry" | "fallback" | "upgrade";
 /** Where a limit was decided. Mirrors contracts `LimitOrigin`. */
-export type LimitOrigin = "platform" | "provider";
+export type LimitOrigin = "platform" | "provider" | "subscriber";
 /**
  * F1 — the `_fs` deny envelope a backend stamps on a usage-limit deny body.
  * Structurally identical to the contracts `FsDenyEnvelope`.
@@ -45,6 +45,7 @@ export type LimitOrigin = "platform" | "provider";
 export interface FsDenyEnvelope {
     limitClass: LimitClass;
     scope?: string;
+    actorScope?: "member" | "service_account";
     metric?: string;
     reset?: number;
     remaining?: number;
@@ -75,6 +76,7 @@ export interface FsDenyEnvelope {
 export declare const DENY_ENVELOPE_FIELDS: {
     limitClass: true;
     scope: true;
+    actorScope: true;
     metric: true;
     reset: true;
     remaining: true;
@@ -286,6 +288,19 @@ export type RuntimePostStreamUsageEvent = {
     meters: Record<string, number>;
     creditUnitsConsumed?: Record<string, number>;
     measureContext?: Record<string, unknown>;
+    /** Schema version of {@link measurements}; currently `1`. */
+    measurementsVersion?: number;
+    /** Measurement lane — `{ meter, values, dims }` as declared in the release. */
+    measurements?: {
+        meter: string;
+        values: Record<string, number>;
+        dims?: Record<string, string>;
+    }[];
+    /** Proposed rate input for a `backendQuoted` pricing rule (core clamps it). */
+    quote?: {
+        currency: string;
+        amountNanos: string;
+    };
     signature: string;
 };
 export type RuntimeHealthReport = {

package/dist/types/testing/devRuntime.d.ts

@@ -1,5 +1,5 @@
 import { FartherShore } from "../core/runtime.js";
-import { type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type MiddlewareOptions, type VerifiedExpressHandler } from "../adapters/express.js";
+import { type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type HandlerOptions, type MiddlewareOptions, type VerifiedExpressHandler } from "../adapters/express.js";
 import { type PermissionCarrier } from "../core/permissions.js";
 import { type DevGateway } from "./devGateway.js";
 import { DevUsageSink } from "./usageSink.js";
@@ -14,7 +14,16 @@ export type TracedCarrier = PermissionCarrier & {
 export type FartherShoreDevInstance = FartherShore & {
     middleware(options?: MiddlewareOptions): ExpressMiddleware;
     /** Strict-context handler wrapper (guaranteed non-optional ctx). */
-    handler<Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
+    handler: {
+        <Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
+        /** Options-first overload — declarative `permission` gate. */
+        <Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(options: HandlerOptions, handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
+    };
+    /** Traced authz helpers — the SAME shape as the prod facade's `fs.authz`. */
+    authz: {
+        hasPermission(ctx: TracedCarrier, key: string): boolean;
+        requirePermission(ctx: TracedCarrier, key: string): void;
+    };
     /** The dev harness attached to this runtime. */
     dev: DevRuntime;
 };

package/dist/types/testing/index.d.ts

@@ -6,3 +6,4 @@ export { writeDevKeysFile, readDevKeysFile, personaClientFromKeysFile, DEFAULT_K
 export { DevUsageSink, type DevUsageEvent } from "./usageSink.js";
 export { DevTraceSink, redactValue, type DevTrace, type DevMode, type VerificationOutcome, type AuthzDecisionEntry, type MeteringTraceEntry, } from "./traceSink.js";
 export { isProductionEnv, assertNotProduction, DevModeInProductionError, } from "./prodGuard.js";
+export { signWebhookForTesting, type SignWebhookForTestingInput, type SignedTestWebhook, } from "./webhooks.js";

package/dist/types/testing/usageSink.d.ts

@@ -26,7 +26,7 @@ export type DevUsageEvent = {
 /** In-memory, assertable sink for all dev usage. */
 export declare class DevUsageSink {
     readonly events: DevUsageEvent[];
-    /** Record a signed response-metering payload (withUsage / computeMeteringHeaders). */
+    /** Record a signed response-metering payload (report() in-band / computeMeteringHeaders). */
     recordResponse(payload: Record<string, unknown>, requestId?: string): void;
     /** Record a background `fs.meter()` event captured by the dev gateway. */
     recordMeterEvent(event: RuntimeMeteringEvent): void;

package/dist/types/testing/webhooks.d.ts

@@ -0,0 +1,30 @@
+import type { WebhookEnvelope, WebhookEnvelopeType, WebhookEventData } from "../webhooks/types.js";
+export interface SignWebhookForTestingInput<T extends WebhookEnvelopeType> {
+    /** The endpoint secret(s) the receiver is configured with (current first). */
+    secret: string | readonly string[];
+    type: T;
+    data: WebhookEventData[T];
+    /** Defaults to a random delivery id. */
+    id?: string;
+    businessId?: string;
+    environmentId?: string | null;
+    /** Defaults to now (ISO). */
+    createdAt?: string;
+    /** Signing timestamp (unix seconds); defaults to now. */
+    timestamp?: number;
+}
+export interface SignedTestWebhook<T extends WebhookEnvelopeType> {
+    envelope: WebhookEnvelope<T>;
+    /** The exact bytes to POST. */
+    body: string;
+    /** `webhook-id` / `webhook-timestamp` / `webhook-signature` / event / content-type. */
+    headers: Record<string, string>;
+    /** Convenience: a `Request` you can hand straight to `handler.fetch`. */
+    request(url?: string): Request;
+}
+/**
+ * Build + sign one delivery the way the platform does (Standard Webhooks
+ * over `${id}.${timestamp}.${body}`). Pass several secrets to emulate the
+ * 24 h dual-signing rotation window.
+ */
+export declare function signWebhookForTesting<T extends WebhookEnvelopeType>(input: SignWebhookForTestingInput<T>): SignedTestWebhook<T>;

package/dist/types/webhooks/index.d.ts

@@ -0,0 +1,247 @@
+import { WEBHOOK_EVENT_HEADER, WEBHOOK_EVENT_NAMES, WEBHOOK_ID_HEADER, WEBHOOK_SECRET_PREFIX, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TEST_EVENT, WEBHOOK_TIMESTAMP_HEADER, WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS, type VerifyWebhookInput, type WebhookEnvelope, type WebhookEnvelopeType, type WebhookEventData, type WebhookEventName, type WebhookVerifyFailure, type WebhookVerifyResult } from "./types.js";
+export { WEBHOOK_EVENT_HEADER, WEBHOOK_EVENT_NAMES, WEBHOOK_ID_HEADER, WEBHOOK_SECRET_PREFIX, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TEST_EVENT, WEBHOOK_TIMESTAMP_HEADER, WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS, };
+export type { VerifyWebhookInput, WebhookEnvelope, WebhookEnvelopeType, WebhookEventData, WebhookEventName, WebhookVerifyFailure, WebhookVerifyResult, };
+/**
+ * Verify one delivery's Standard Webhooks signature + timestamp window. The
+ * low-level primitive; `createWebhookHandler` adds dedupe, parsing and routing.
+ */
+export declare function verifyWebhook(input: VerifyWebhookInput): WebhookVerifyResult;
+export declare function isWebhookEnvelopeType(value: unknown): value is WebhookEnvelopeType;
+export type WebhookEventHandler<T extends WebhookEnvelopeType> = (event: WebhookEnvelope<T>) => void | Promise<void>;
+export type WebhookHandlers = {
+    [T in WebhookEnvelopeType]?: WebhookEventHandler<T>;
+};
+/** Why a delivery was rejected (401 / 400) — surfaced through `onRejected`. */
+export type WebhookRejection = {
+    reason: WebhookVerifyFailure;
+} | {
+    reason: "invalid_json";
+} | {
+    reason: "invalid_envelope";
+    detail: string;
+} | {
+    reason: "payload_too_large";
+    limitBytes: number;
+};
+/**
+ * Delivery-id store for deduplication. Unlike the request verifier's
+ * `NonceStore`, a webhook store leases an id: `claim` before the handler and
+ * `settle` after, so a thrown handler releases the id and the platform's retry
+ * (same `webhook-id`) re-runs it instead of being acknowledged as a duplicate,
+ * while a concurrent retry of an in-flight id never double-runs the handler.
+ * See {@link WebhookNonceStore}.
+ */
+export type WebhookClaimOutcome = "fresh" | "in_flight" | "processed" | "saturated";
+/** The result of `claim`. A `token` is present ONLY for a "fresh" claim — it
+ * identifies THIS lease so `settle` cannot act on a lease that has since been
+ * reclaimed by another delivery (see {@link WebhookNonceStore}). */
+export interface WebhookClaim {
+    outcome: WebhookClaimOutcome;
+    token?: string;
+}
+/**
+ * Delivery-id store protocol — an ATOMIC, OWNERSHIP-FENCED claim/settle lease.
+ *
+ * The earlier split `has(id)` … handler … `remember(id)` had a check-then-act
+ * race: two concurrent deliveries of the SAME `webhook-id` could BOTH observe
+ * `has(id) === false` and both run a payment / lifecycle handler. An atomic
+ * claim closes that window.
+ *
+ *   `claim(id)` is taken BEFORE the handler:
+ *     - "fresh"      → unseen; the caller HOLDS the lease (identified by the
+ *                      returned `token`) and must settle() with that token.
+ *     - "in_flight"  → another delivery of this id is mid-handler; the caller
+ *                      answers 503 and NEVER runs the handler. The platform
+ *                      retries; that retry sees "processed" once the first wins.
+ *     - "processed"  → already handled to success; answer 200 without re-running.
+ *     - "saturated"  → the store cannot retain the id; the caller runs the
+ *                      handler best-effort WITHOUT a lease (at-least-once holds).
+ *
+ *   `settle(id, token, outcome)` resolves a "fresh" claim, and is a NO-OP unless
+ *   `token` still identifies the live lease:
+ *     - "processed"  → keep the id so future retries dedupe.
+ *     - "release"    → drop the lease so the platform's retry re-runs the handler.
+ *
+ * The token fences the case where a handler outlives the in-flight lease TTL:
+ * the id becomes reclaimable, a retry re-leases it with a NEW token, and the
+ * original handler's late `settle` (with the OLD token) is ignored rather than
+ * deleting or overwriting the replacement's lease. (A handler that exceeds the
+ * lease TTL still degrades to at-least-once — the receiver dedupes on
+ * webhook-id — but never corrupts another delivery's lease.)
+ *
+ * A shared store (Redis, DB) implements `claim` as an atomic upsert stamping a
+ * unique token, a short in-flight lease TTL (so a crashed handler's id becomes
+ * reclaimable) and a longer processed TTL of at least `WEBHOOK_DEDUPE_TTL_MS`.
+ */
+export interface WebhookNonceStore {
+    claim(id: string): WebhookClaim | Promise<WebhookClaim>;
+    settle(id: string, token: string, outcome: "processed" | "release"): void | Promise<void>;
+}
+/** Capacity of the default in-memory store (ids retained per TTL window). */
+export declare const WEBHOOK_DEDUPE_MAX_ENTRIES = 250000;
+/**
+ * How long an in-flight lease is held before a crashed / hung handler's id
+ * becomes reclaimable. Longer than any reasonable handler, shorter than the
+ * retry horizon, so a genuinely stuck delivery is retried rather than wedged
+ * as a permanent "in_flight".
+ */
+export declare const WEBHOOK_INFLIGHT_LEASE_MS: number;
+/**
+ * Default single-instance delivery-id store: an atomic claim/settle lease,
+ * TTL-bounded, capacity-bounded, and honest about saturation (returns
+ * `"saturated"` rather than lying when it cannot lease a fresh id).
+ */
+export declare class MemoryWebhookNonceStore implements WebhookNonceStore {
+    private readonly options;
+    private readonly seen;
+    private tokenSeq;
+    constructor(options?: {
+        ttlMs?: number;
+        leaseMs?: number;
+        maxEntries?: number;
+        now?: () => number;
+    });
+    private horizonFor;
+    claim(id: string): WebhookClaim;
+    settle(id: string, token: string, outcome: "processed" | "release"): void;
+    get size(): number;
+}
+/**
+ * How long a delivery id is remembered. The platform retries a delivery at
+ * 30 s, 5 min and 30 min after the first attempt (≈ 35.5 min horizon), so the
+ * window must outlast the LAST retry plus clock tolerance — a shorter window
+ * would let the final retry re-run a handler whose 2xx the platform never saw.
+ */
+export declare const WEBHOOK_DEDUPE_TTL_MS: number;
+export interface CreateWebhookHandlerOptions {
+    /** The endpoint's signing secret (`fswh_…`). */
+    secret?: string;
+    /** Several accepted secrets (current first) — use while rolling a rotation. */
+    secrets?: readonly string[];
+    /** Typed per-event handlers. Missing types are acknowledged and ignored. */
+    on: WebhookHandlers;
+    /**
+     * Called for an event `type` this SDK does not know (a newer platform).
+     * Always acknowledged 2xx; use this to log or forward.
+     */
+    onUnknown?: (event: {
+        id: string;
+        type: string;
+        body: unknown;
+    }) => void | Promise<void>;
+    /** Called for every rejected delivery (never throws the request). */
+    onRejected?: (rejection: WebhookRejection) => void;
+    /** Called when a duplicate `webhook-id` is acknowledged without running. */
+    onDuplicate?: (event: {
+        id: string;
+        type: string;
+    }) => void;
+    /**
+     * Delivery-id store for deduplication. Defaults to a bounded in-memory
+     * cache (single instance, `WEBHOOK_DEDUPE_TTL_MS`). Provide a shared store
+     * (Redis, DB) with an atomic `claim`/`settle` lease when the receiver runs on
+     * more than one instance (see {@link WebhookNonceStore}).
+     */
+    nonceStore?: WebhookNonceStore;
+    /**
+     * Largest request body the adapters will buffer (default 1 MiB). Checked
+     * against `Content-Length` and enforced on the stream BEFORE the signature
+     * is verified, so an unauthenticated caller cannot exhaust memory.
+     */
+    maxBodyBytes?: number;
+    /** Override for tests; defaults to `Date.now`. */
+    now?: () => number;
+}
+/** Default cap on a delivery body. Platform envelopes are a few KiB. */
+export declare const WEBHOOK_MAX_BODY_BYTES: number;
+export type WebhookHandleOutcome = {
+    status: 200;
+    kind: "handled";
+    id: string;
+    type: WebhookEnvelopeType;
+} | {
+    status: 200;
+    kind: "ignored";
+    id: string;
+    type: WebhookEnvelopeType;
+} | {
+    status: 200;
+    kind: "unknown_type";
+    id: string;
+    type: string;
+} | {
+    status: 200;
+    kind: "duplicate";
+    id: string;
+    type: string;
+} | {
+    status: 400 | 401;
+    kind: "rejected";
+    rejection: WebhookRejection;
+} | {
+    status: 413;
+    kind: "rejected";
+    rejection: WebhookRejection;
+} | {
+    status: 503;
+    kind: "store_unavailable";
+    id: string;
+    type: string;
+} | {
+    status: 503;
+    kind: "in_flight";
+    id: string;
+    type: string;
+} | {
+    status: 500;
+    kind: "handler_error";
+    id: string;
+    type: string;
+    error: unknown;
+};
+export interface WebhookHandleInput {
+    /** Raw request body, exactly as received. */
+    body: string | Uint8Array;
+    headers: Record<string, string | string[] | undefined> | Headers;
+}
+/** Minimal Express-shaped types so we don't hard-depend on @types/express. */
+export type WebhookExpressRequestLike = {
+    headers: Record<string, string | string[] | undefined>;
+    /** Raw body bytes when captured by a raw parser (`express.raw()`). */
+    body?: unknown;
+    rawBody?: Buffer | Uint8Array;
+};
+export type WebhookExpressResponseLike = {
+    status(code: number): WebhookExpressResponseLike;
+    json(body: unknown): unknown;
+};
+export interface WebhookHandler {
+    /** Framework-neutral: verify, dedupe, parse, route. Never throws. */
+    handle(input: WebhookHandleInput): Promise<WebhookHandleOutcome>;
+    /** Fetch-API handler (Next.js route handlers, Hono, Bun, Workers…). */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Express handler. Mount AFTER a raw-body parser
+     * (`express.raw({ type: "application/json" })`) or set `req.rawBody`; a pre-parsed
+     * JSON body cannot be verified and is rejected 400.
+     */
+    express(): (req: WebhookExpressRequestLike, res: WebhookExpressResponseLike) => Promise<void>;
+}
+/**
+ * Read a Fetch request body without ever buffering more than `limit` bytes:
+ * a declared `Content-Length` over the cap is refused before any allocation,
+ * and a stream that exceeds it mid-flight is abandoned. Returns `null` when
+ * the cap is exceeded.
+ */
+export declare function readBoundedRequestBody(request: Request, limit: number): Promise<Uint8Array | null>;
+export declare function createWebhookHandler(options: CreateWebhookHandlerOptions): WebhookHandler;
+export type DataFieldKind = "string" | "number" | "string|null" | "number|null";
+/**
+ * Runtime mirror of the typed keys in `WebhookEventData` (types.ts). Kept
+ * SDK-local (no zod in the published bundle) and pinned field-by-field to the
+ * contracts schemas (`WEBHOOK_EVENT_DATA_SCHEMAS`) by `contracts-drift.test.ts`
+ * — a wrong `kind` here (e.g. dropping the `|null` from `amount`) would reject
+ * a legitimately-signed delivery, so the pin proves each kind matches the zod
+ * field's null/type behavior. Exported solely so that pin can read it.
+ */
+export declare const DATA_FIELD_TYPES: Record<Exclude<WebhookEnvelopeType, "webhook.test">, Record<string, DataFieldKind>>;

package/dist/types/webhooks/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Event names a webhook endpoint can subscribe to (the platform events
+ * catalog's webhook-deliverable subset), in catalog order.
+ */
+export declare const WEBHOOK_EVENT_NAMES: readonly ["subscription.created", "subscription.updated", "subscription.canceled", "payment.succeeded", "payment.failed", "entitlement.changed", "usage.threshold_reached"];
+export type WebhookEventName = (typeof WEBHOOK_EVENT_NAMES)[number];
+/** The synthetic event a dashboard / CLI "Send test" produces. */
+export declare const WEBHOOK_TEST_EVENT: "webhook.test";
+/** Every `type` a delivery envelope can carry. */
+export type WebhookEnvelopeType = WebhookEventName | typeof WEBHOOK_TEST_EVENT;
+/**
+ * Per-event `data`. The keys listed are what the platform's producers carry
+ * today; extra keys pass through untouched (automation rules may attach
+ * builder-authored fields), so every shape is open.
+ */
+export interface WebhookEventData {
+    "subscription.created": {
+        subscriptionId?: string;
+        compiledPlanId?: string;
+        [key: string]: unknown;
+    };
+    "subscription.updated": {
+        subscriptionId?: string;
+        /** Producer-specific change reason, e.g. `plan_changed`, `trial_ending`. */
+        reason?: string;
+        lifecycle?: string;
+        compiledPlanId?: string;
+        [key: string]: unknown;
+    };
+    "subscription.canceled": {
+        subscriptionId?: string;
+        reason?: string;
+        lifecycle?: string;
+        [key: string]: unknown;
+    };
+    "payment.succeeded": WebhookPaymentData;
+    "payment.failed": WebhookPaymentData;
+    "entitlement.changed": {
+        compiledPlanId?: string;
+        lineageId?: string;
+        status?: string;
+        [key: string]: unknown;
+    };
+    "usage.threshold_reached": {
+        subscriptionId?: string;
+        subscriberId?: string;
+        limitId?: string;
+        threshold?: number;
+        windowStartMs?: number;
+        windowEndMs?: number;
+        [key: string]: unknown;
+    };
+    "webhook.test": {
+        businessId: string;
+        sentAt: string;
+        [key: string]: unknown;
+    };
+}
+export interface WebhookPaymentData {
+    subscriptionId?: string;
+    invoiceId?: string;
+    amount?: number | null;
+    currency?: string | null;
+    reason?: string;
+    [key: string]: unknown;
+}
+/** The JSON body of every delivery. `id` equals the `webhook-id` header. */
+export type WebhookEnvelope<T extends WebhookEnvelopeType = WebhookEnvelopeType> = T extends WebhookEnvelopeType ? {
+    id: string;
+    type: T;
+    /** ISO 8601 — when the event was recorded (stable across retries). */
+    createdAt: string;
+    businessId: string;
+    /** `null` = production. */
+    environmentId: string | null;
+    data: WebhookEventData[T];
+} : never;
+/** Header names on the wire (Standard Webhooks + our convenience header). */
+export declare const WEBHOOK_ID_HEADER = "webhook-id";
+export declare const WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+export declare const WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
+export declare const WEBHOOK_EVENT_HEADER = "x-fs-webhook-event";
+/** Accept deliveries within ±this many seconds of the receiver's clock. */
+export declare const WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS = 300;
+/** Prefix every platform-minted signing secret carries. */
+export declare const WEBHOOK_SECRET_PREFIX = "fswh_";
+export type WebhookVerifyFailure = "missing_headers" | "invalid_timestamp" | "timestamp_out_of_tolerance" | "no_matching_signature";
+export type WebhookVerifyResult = {
+    ok: true;
+    id: string;
+    timestamp: number;
+} | {
+    ok: false;
+    reason: WebhookVerifyFailure;
+};
+export interface VerifyWebhookInput {
+    /** Raw request body, exactly as received. */
+    body: string | Uint8Array;
+    /** Request headers (any case). */
+    headers: Record<string, string | string[] | undefined> | Headers;
+    /**
+     * Accepted signing secrets. Pass `[current, previous]` while you roll a
+     * rotated secret on your side; the platform already dual-signs for 24 h.
+     */
+    secrets: readonly string[];
+    /** Override for tests; defaults to `Date.now()`. */
+    now?: () => number;
+    /** Override for tests; defaults to ±300 s. */
+    toleranceSeconds?: number;
+}