@lunora/payment 1.0.0-alpha.13 → 1.0.0-alpha.131

package/dist/index.d.mts

@@ -1,327 +1,84 @@
+import { a as ProviderId, C as Customer, b as PaymentSession, S as Subscription, U as UsageEvent, W as WebhookActionType, A as ApplyResult, P as PaymentAdapter, c as AttachInput, d as CheckoutResult, e as CancelSubscriptionOptions, f as CaptureInput, g as CheckInput, h as CheckResult, i as CheckoutInput, F as FeatureBalance, R as RefundInput, T as TrackInput, j as TrackResult, k as CurrencyCode, M as Money, l as PaymentState, m as SubscriptionState, n as WebhookAction } from "./packem_shared/adapter.d-DytKm_IF.mjs";
+export { type o as AdapterRegistry, type p as CustomerRef, type q as PortalInput, type r as ProviderCapabilities, type s as RefundAmountKind, type t as RefundResult, type u as ReportUsageInput, type v as SubscriptionPatch, type w as WebhookHeaders, type x as WebhookInput, y as createAdapterRegistry } from "./packem_shared/adapter.d-DytKm_IF.mjs";
+import { LunoraError } from '@lunora/errors';
 import { TableDefinition } from '@lunora/server';
 /**
-* Core domain types for `@lunora/payment`.
-*
-* The provider is a stateless translator; the store owns all state. These types are the
-* provider-agnostic vocabulary every adapter normalizes onto.
-*/
-/** ISO-4217 currency code (uppercase, 3 letters). Not enumerated — provider coverage varies. */
-type CurrencyCode = string;
-/**
-* Money as integer minor units + currency. Always carry the two together.
-*
-* `minorUnits` is a `bigint`, which is **not** JSON-serializable — cross the RPC/wire boundary
-* with the `toMoneyJSON` / `fromMoneyJSON` helpers (see `./money`).
-*/
-interface Money {
-  readonly currency: CurrencyCode;
-  readonly minorUnits: bigint;
-}
-/** Stable provider identifier (Medusa-style). Scoped to what Convex ships: Stripe + Polar. */
-type ProviderId = "polar" | "stripe";
-/** What a provider can do — encoded in types so tax/UX assumptions aren't tribal knowledge. */
-interface ProviderCapabilities {
-  /** True for Polar / Lemon Squeezy / Paddle; false for Stripe (PSP). Drives tax/invoice ownership. */
-  readonly merchantOfRecord: boolean;
-  /** Native hosted customer/billing portal. */
-  readonly portal: boolean;
-  /** Usage-based / metered billing. */
-  readonly usageMetering: boolean;
-}
-/** Lifecycle state of a one-time payment session. */
-type PaymentState = "authorized" | "canceled" | "captured" | "failed" | "initiated" | "partially_refunded" | "refunded";
-/** Lifecycle state of a subscription. */
-type SubscriptionState = "active" | "canceled" | "past_due" | "paused" | "trialing";
-interface Customer {
-  readonly createdAt: number;
-  readonly email?: string;
-  /** Provider-side customer id. */
-  readonly id: string;
-  readonly provider: ProviderId;
-  /** App-side owner the customer belongs to (user / org / workspace). Opaque to this package. */
-  readonly referenceId: string;
-}
-interface PaymentSession {
-  readonly amount: Money;
-  readonly capturedAmount: Money;
-  readonly createdAt: number;
-  /** Provider-side payment / intent / session id. */
-  readonly id: string;
-  readonly provider: ProviderId;
-  readonly referenceId: string;
-  readonly refundedAmount: Money;
-  readonly state: PaymentState;
-  readonly updatedAt: number;
-}
-interface Subscription {
-  readonly cancelAtPeriodEnd: boolean;
-  readonly createdAt: number;
-  readonly currentPeriodEnd?: number;
-  /** Start of the current billing period — the window `check` sums metered usage over. */
-  readonly currentPeriodStart?: number;
-  readonly id: string;
-  readonly priceId: string;
-  readonly provider: ProviderId;
-  readonly quantity: number;
-  readonly referenceId: string;
-  readonly state: SubscriptionState;
-  readonly updatedAt: number;
-}
-interface CustomerRef {
-  readonly email?: string;
-  readonly metadata?: Record<string, string>;
-  readonly referenceId: string;
-}
-interface CheckoutInput {
-  readonly cancelUrl: string;
-  /** Existing provider customer id, if known. */
-  readonly customerId?: string;
-  /** Outbound idempotency key for the provider call; auto-derived when omitted. */
-  readonly idempotencyKey?: string;
-  readonly metadata?: Record<string, string>;
-  readonly mode: "payment" | "subscription";
-  readonly priceId: string;
-  readonly quantity?: number;
-  readonly referenceId: string;
-  readonly successUrl: string;
-}
-interface CheckoutResult {
-  readonly id: string;
-  readonly provider: ProviderId;
-  readonly url: string;
-}
-/**
-* `attach` input — subscribe a reference to a plan. A thin, plan-oriented skin over
-* {@link CheckoutInput}: `mode` defaults to `"subscription"` (the common case), so callers pass
-* just `{ referenceId, priceId, successUrl, cancelUrl }`.
-*/
-interface AttachInput extends Omit<CheckoutInput, "mode"> {
-  readonly mode?: CheckoutInput["mode"];
-}
-interface PortalInput {
-  readonly customerId: string;
-  readonly returnUrl: string;
-}
-/** A single durable usage record — one metered event for a `(referenceId, featureId)` pair. */
-interface UsageEvent {
-  readonly createdAt: number;
-  readonly featureId: string;
-  /** Caller-stable dedupe key — recording the same key twice is a no-op (exactly-once `track`). */
-  readonly idempotencyKey: string;
-  readonly provider: ProviderId;
-  readonly quantity: number;
-  readonly referenceId: string;
-  /** Whether the event was successfully forwarded to the provider's metering API. */
-  readonly reportedToProvider: boolean;
-}
-/** `track` input — record metered usage for a reference's feature. */
-interface TrackInput {
-  readonly featureId: string;
-  /** Caller-supplied dedupe key; a fresh one is generated when omitted (so each call records). */
-  readonly idempotencyKey?: string;
-  /** `"add"` (default) increments usage by `quantity`; `"set"` reconciles the period total to `quantity`. */
-  readonly mode?: "add" | "set";
-  /** Usage amount to add, or the absolute period total when `mode` is `"set"` (defaults to `1`). */
-  readonly quantity?: number;
-  readonly referenceId: string;
-}
-/** Result of a `track` call. */
-interface TrackResult {
-  /** True when this call inserted a new usage event; false when deduplicated by idempotency key. */
-  readonly recorded: boolean;
-  /** True when the event was forwarded to the provider's metering API. */
-  readonly reportedToProvider: boolean;
-}
-/**
-* `check` input — is a reference allowed something right now? Pass `featureId` to check a feature
-* grant/allowance, or `priceId` to check active access to a product (one of the two is required).
-*/
-interface CheckInput {
-  /** Feature to check a grant/allowance for. Provide this **or** `priceId`. */
-  readonly featureId?: string;
-  /** Provider price/product id to check active access for. Provide this **or** `featureId`. */
-  readonly priceId?: string;
-  /** Units the caller intends to consume; the check passes only when this many remain (default `1`). */
-  readonly quantity?: number;
-  readonly referenceId: string;
-}
-/** Result of a `check` call. */
-interface CheckResult {
-  /** Whether the reference may consume `quantity` units of the feature right now. */
-  readonly allowed: boolean;
-  /** Remaining units this period (`limit - used`), for metered features only. */
-  readonly balance?: number;
-  /** The plan-granted cap, for metered features only. */
-  readonly limit?: number;
-  /** True for a boolean feature granted without a numeric cap. */
-  readonly unlimited: boolean;
-  /** Usage consumed this period, for metered features only. */
-  readonly used?: number;
-}
-/** One feature's resolved allowance for a reference — a {@link CheckResult} tagged with its feature. */
-interface FeatureBalance extends CheckResult {
-  readonly featureId: string;
-}
-/** Input the adapter forwards to the provider's metering API (Stripe Meter Events / Polar ingestion). */
-interface ReportUsageInput {
-  /** Provider customer id, when known (Stripe meter events key on it). */
-  readonly customerId?: string;
-  readonly featureId: string;
-  readonly idempotencyKey: string;
-  readonly quantity: number;
-  readonly referenceId: string;
-  /** Event time in epoch ms; defaults to now at the provider. */
-  readonly timestamp?: number;
-}
-interface CaptureInput {
-  /** Partial capture amount; full capture when omitted. */
-  readonly amount?: Money;
-  readonly idempotencyKey?: string;
-  readonly sessionId: string;
-}
-interface RefundInput {
-  /** Partial refund amount; full refund when omitted. */
-  readonly amount?: Money;
-  readonly idempotencyKey?: string;
-  readonly reason?: string;
-  readonly sessionId: string;
-}
-interface CancelSubscriptionOptions {
-  /** Cancel at period end instead of immediately. */
-  readonly atPeriodEnd?: boolean;
-  readonly idempotencyKey?: string;
-}
-interface SubscriptionPatch {
-  readonly priceId?: string;
-  readonly quantity?: number;
-}
-/** Normalized webhook outcome — the *core state transition* a provider event implies. */
-type WebhookActionType = "payment.authorized" | "payment.captured" | "payment.failed" | "payment.refunded" | "subscription.active" | "subscription.canceled" | "subscription.past_due" | "subscription.paused" | "subscription.updated" | "unhandled";
-/**
-* How a refund action's {@link WebhookAction.amount} should be interpreted by the sync layer.
-*
-* `"delta"` is an incremental amount added to the running refunded total (Polar `refund.created`,
-* and the historical default), so multiple events accumulate. `"absolute"` is the provider's
-* cumulative refunded-to-date total (Stripe `charge.refunded` carries `amount_refunded`, which
-* already sums all prior partial refunds); the sync layer sets the refunded total to this value
-* rather than adding, so repeated partial-refund events do not over-count.
-*
-* Omitted means `"delta"`, preserving the original behavior for callers that predate this field.
-*/
-type RefundAmountKind = "absolute" | "delta";
-interface WebhookAction {
-  readonly amount?: Money;
-  /**
-  * Interpretation of {@link WebhookAction.amount} for refund actions (`payment.refunded`).
-  * Defaults to `"delta"` when omitted. Ignored for non-refund actions.
-  */
-  readonly amountKind?: RefundAmountKind;
-  readonly cancelAtPeriodEnd?: boolean;
-  readonly currentPeriodEnd?: number;
-  readonly currentPeriodStart?: number;
-  readonly customerId?: string;
-  /** Provider event id — the inbound idempotency key. */
-  readonly eventId: string;
-  readonly priceId?: string;
-  readonly provider: ProviderId;
-  readonly quantity?: number;
-  /** Raw provider event, retained for the events log / debugging. */
-  readonly raw?: unknown;
-  readonly referenceId?: string;
-  readonly sessionId?: string;
-  readonly subscriptionId?: string;
-  readonly type: WebhookActionType;
-}
-/** Result of applying a webhook action to the store. */
-interface ApplyResult {
-  readonly applied: boolean;
-  readonly reason?: "duplicate" | "illegal_transition" | "invalid_refund_amount" | "ok" | "unhandled";
-}
-/** A read-only header bag; the platform `Headers` object satisfies it. */
-interface WebhookHeaders {
-  get: (name: string) => null | string;
-}
-interface WebhookInput {
-  /** Request headers (signature schemes read provider-specific headers from here). */
-  readonly headers: WebhookHeaders;
-  /** Raw request body, exactly as received (required for signature verification). */
-  readonly payload: string;
-}
-/**
-* A stateless translator between the provider API and Lunora's normalized vocabulary.
-*
-* Adapters never own state — they make provider calls and normalize provider events into a
-* `WebhookAction`. All durable state lives in the payment store.
-*/
-interface PaymentAdapter {
-  cancelPayment: (sessionId: string, options?: {
-    idempotencyKey?: string;
-  }) => Promise<PaymentSession>;
-  cancelSubscription: (subscriptionId: string, options?: CancelSubscriptionOptions) => Promise<Subscription>;
-  readonly capabilities: ProviderCapabilities;
-  capturePayment: (input: CaptureInput) => Promise<PaymentSession>;
-  createCheckout: (input: CheckoutInput) => Promise<CheckoutResult>;
-  createPortalSession: (input: PortalInput) => Promise<{
-    url: string;
-  }>;
-  getOrCreateCustomer: (ref: CustomerRef) => Promise<Customer>;
-  /** Fetch the provider's current truth for a payment session — the basis for reconciliation. */
-  getPaymentStatus: (sessionId: string) => Promise<PaymentSession>;
-  /** Fetch the provider's current truth for a subscription — the basis for reconciliation. */
-  getSubscriptionStatus: (subscriptionId: string) => Promise<Subscription>;
-  /** Stable provider identifier (Medusa-style). */
-  readonly identifier: ProviderId;
-  /** Verify the signature over the raw body, then normalize the event. Throws on invalid signature. */
-  parseWebhook: (input: WebhookInput) => Promise<WebhookAction>;
-  refundPayment: (input: RefundInput) => Promise<PaymentSession>;
-  /**
-  * Forward metered usage to the provider's billing API. Optional — present only on providers
-  * whose `capabilities.usageMetering` is `true` and that expose an ingestion endpoint. When
-  * absent, `track` still records usage durably and `check` enforces limits locally.
-  */
-  reportUsage?: (input: ReportUsageInput) => Promise<void>;
-  resumeSubscription: (subscriptionId: string) => Promise<Subscription>;
-  updateSubscription: (subscriptionId: string, patch: SubscriptionPatch) => Promise<Subscription>;
-}
-/** Registry of adapters keyed by provider id — supports dual-register during provider migration. */
-interface AdapterRegistry {
-  all: () => PaymentAdapter[];
-  get: (provider: ProviderId) => PaymentAdapter;
-  has: (provider: ProviderId) => boolean;
-}
-declare const createAdapterRegistry: (adapters: ReadonlyArray<PaymentAdapter>) => AdapterRegistry;
+ * `PaymentStore` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 interface PaymentStore {
   getCustomerByReference: (provider: ProviderId, referenceId: string) => Promise<Customer | undefined>;
   getPaymentSession: (provider: ProviderId, id: string) => Promise<PaymentSession | undefined>;
   getSubscription: (provider: ProviderId, id: string) => Promise<Subscription | undefined>;
   listSubscriptionsByReference: (referenceId: string) => Promise<Subscription[]>;
   /**
-  * Claims a provider event id for processing. Resolves `true` the first time an event is seen
-  * and `false` for a duplicate — the inbound-idempotency primitive.
-  */
-  markEventProcessed: (provider: ProviderId, eventId: string) => Promise<boolean>;
+   * Usage events that still owe an upstream forward, oldest first, at most `limit`.
+   *
+   * "Owes a forward" is narrower than `reportedToProvider === false`: only an
+   * ADDITIVE event with a positive `quantity` qualifies. A `"set"` event's
+   * upstream delta was measured against the period total at the moment it was
+   * recorded and is not recoverable afterwards, and a non-positive quantity was
+   * never sent, so neither is a retry candidate — returning them would make the
+   * sweep re-send the same rows forever (or double-count on an additive meter).
+   *
+   * Read by `reconcile` to retry a forward the provider rejected transiently;
+   * without it a single 5xx loses that metered unit upstream for good, which for
+   * a provider that owns entitlements under-bills and over-entitles the customer.
+   */
+  listUnreportedUsage: (provider: ProviderId, limit: number) => Promise<UsageEvent[]>;
+  /**
+   * Claims a provider event id for processing. Resolves `true` the first time an event is seen
+   * and `false` for a duplicate — the inbound-idempotency primitive.
+   *
+   * `type` is recorded on the claim row so the `events` table is a readable audit log rather than
+   * bare ids and timestamps: a real delivery passes its `WebhookActionType`, and the
+   * internal claim markers (`sync.ts`'s orphan-retry bound, the local-refund ledger) pass a
+   * `marker.*` label so they are distinguishable from provider traffic in the studio.
+   */
+  markEventProcessed: (provider: ProviderId, eventId: string, type: string) => Promise<boolean>;
   /** Flag a recorded usage event as forwarded to the provider's metering API. */
   markUsageReported: (provider: ProviderId, idempotencyKey: string) => Promise<void>;
   /**
-  * Append a usage event. Resolves `true` when newly recorded and `false` when its
-  * `idempotencyKey` was already seen — the exactly-once primitive behind `track`.
-  */
+   * Append a usage event. Resolves `true` when newly recorded and `false` when its
+   * `idempotencyKey` was already seen — the exactly-once primitive behind `track`.
+   */
   recordUsage: (event: UsageEvent) => Promise<boolean>;
   /**
-  * Release a previously-claimed event id (see {@link PaymentStore.markEventProcessed}) so a
-  * provider retry can re-process it. Called only when applying the claimed event *throws* (a
-  * genuine store-write failure): the atomic insert-claim guards concurrent duplicates, but a
-  * claim that outlives a failed apply would dedupe the retry and lose the effect — so the claim
-  * is rolled back on failure. A no-op if the id was never claimed.
-  */
+   * Release a previously-claimed event id (see {@link PaymentStore.markEventProcessed}) so a
+   * provider retry can re-process it. Called only when applying the claimed event *throws* (a
+   * genuine store-write failure): the atomic insert-claim guards concurrent duplicates, but a
+   * claim that outlives a failed apply would dedupe the retry and lose the effect — so the claim
+   * is rolled back on failure. A no-op if the id was never claimed.
+   */
   releaseEvent: (provider: ProviderId, eventId: string) => Promise<void>;
-  /** Sum recorded usage `quantity` for a `(referenceId, featureId)` pair since `since` (epoch ms). */
+  /**
+   * The period total for a `(referenceId, featureId)` pair since `since` (epoch ms).
+   *
+   * NOT a plain sum: events are folded in `createdAt` order (ties broken by
+   * `idempotencyKey`, so every store agrees on the same order for events stamped
+   * in the same millisecond). An `"add"` event increments the running total; a
+   * `"set"` event RESETS it to that event's `quantity`, discarding everything
+   * earlier in the period. Use {@link foldUsage} so the two implementations
+   * cannot drift.
+   *
+   * This fold is what lets `track({ mode: "set" })` be append-only. Reconciling by
+   * writing `target - current` instead would be a read-modify-write across two
+   * un-transacted store calls: two interleaved `set`s would both read the same
+   * total, both append a delta, and leave the period over- or under-counted —
+   * inflating `balance = limit - used`. Here a concurrent pair simply resolves
+   * last-writer-wins, and a replayed `set` is idempotent by construction.
+   */
   sumUsage: (referenceId: string, featureId: string, since: number) => Promise<number>;
+  /** Period usage totals for many features in one read — the batch form of {@link PaymentStore.sumUsage}. */
+  sumUsageByFeature: (referenceId: string, featureIds: ReadonlyArray<string>, since: number) => Promise<ReadonlyMap<string, number>>;
   upsertCustomer: (customer: Customer) => Promise<void>;
   upsertPaymentSession: (session: PaymentSession) => Promise<void>;
   upsertSubscription: (subscription: Subscription) => Promise<void>;
 }
-/** In-memory {@link PaymentStore} for tests and local development. Not durable. */
+/**
+ * In-memory {@link PaymentStore} for tests and local development. Not durable.
+ * @experimental
+ */
 declare class MemoryPaymentStore implements PaymentStore {
   private readonly customers;
   private readonly processedEvents;
@@ -332,15 +89,21 @@ declare class MemoryPaymentStore implements PaymentStore {
   getPaymentSession(provider: ProviderId, id: string): Promise<PaymentSession | undefined>;
   getSubscription(provider: ProviderId, id: string): Promise<Subscription | undefined>;
   listSubscriptionsByReference(referenceId: string): Promise<Subscription[]>;
-  markEventProcessed(provider: ProviderId, eventId: string): Promise<boolean>;
+  listUnreportedUsage(provider: ProviderId, limit: number): Promise<UsageEvent[]>;
+  markEventProcessed(provider: ProviderId, eventId: string, _type: string): Promise<boolean>;
   releaseEvent(provider: ProviderId, eventId: string): Promise<void>;
   markUsageReported(provider: ProviderId, idempotencyKey: string): Promise<void>;
   recordUsage(event: UsageEvent): Promise<boolean>;
   sumUsage(referenceId: string, featureId: string, since: number): Promise<number>;
+  sumUsageByFeature(referenceId: string, featureIds: ReadonlyArray<string>, since: number): Promise<ReadonlyMap<string, number>>;
   upsertCustomer(customer: Customer): Promise<void>;
   upsertPaymentSession(session: PaymentSession): Promise<void>;
   upsertSubscription(subscription: Subscription): Promise<void>;
 }
+/**
+ * `PlanDefinition` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 interface PlanDefinition {
   /** Feature flags this plan grants. */
   readonly features?: ReadonlyArray<string>;
@@ -349,10 +112,18 @@ interface PlanDefinition {
   /** Provider price/product ids that grant this plan. */
   readonly priceIds: ReadonlyArray<string>;
 }
+/**
+ * `EntitlementsConfig` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 interface EntitlementsConfig {
   /** Plan name → definition. */
   readonly plans: Record<string, PlanDefinition>;
 }
+/**
+ * `Entitlements` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 interface Entitlements {
   readonly features: ReadonlySet<string>;
   /** True when an active subscription grants `feature`. */
@@ -363,19 +134,36 @@ interface Entitlements {
   readonly plans: ReadonlyArray<string>;
 }
 /**
-* Start of the window `check` sums metered usage over: the most recent billing-period start among
-* a reference's active subscriptions. `0` (count all-time) when no active subscription reports one
-* — limits still bind, they just never reset until the provider sends a period.
-*/
+ * Start of the window `check` sums metered usage over: the most recent billing-period start among
+ * a reference's active subscriptions. `0` (count all-time) when no active subscription reports one
+ * — limits still bind, they just never reset until the provider sends a period.
+ * @experimental
+ */
 declare const usagePeriodStart: (subscriptions: ReadonlyArray<Subscription>) => number;
-/** Every feature name a config can grant — the union of `features` flags and `limits` keys across all plans, sorted. */
+/**
+ * Every feature name a config can grant — the union of `features` flags and `limits` keys across all plans, sorted.
+ * @experimental
+ */
 declare const featureNames: (config: EntitlementsConfig) => string[];
-/** Whether the reference holds an entitling (active/trialing) subscription on `priceId` — the basis of a product `check`. */
+/**
+ * Whether the reference holds an entitling (active/trialing) subscription on `priceId` — the basis of a product `check`.
+ * @experimental
+ */
 declare const hasActivePrice: (subscriptions: ReadonlyArray<Subscription>, priceId: string) => boolean;
-/** Derive {@link Entitlements} from a reference's subscriptions. Pure — the basis of `check`. */
+/**
+ * Derive {@link Entitlements} from a reference's subscriptions. Pure — the basis of `check`.
+ * @experimental
+ */
 declare const resolveEntitlements: (config: EntitlementsConfig, subscriptions: ReadonlyArray<Subscription>) => Entitlements;
-/** Convenience: resolve entitlements straight from the store for a reference. */
+/**
+ * Convenience: resolve entitlements straight from the store for a reference.
+ * @experimental
+ */
 declare const entitlementsForReference: (store: PaymentStore, config: EntitlementsConfig, referenceId: string) => Promise<Entitlements>;
+/**
+ * `PaymentEvent` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 type PaymentEvent = {
   action: WebhookActionType;
   eventId: string;
@@ -420,15 +208,50 @@ type PaymentEvent = {
   referenceId: string;
   type: "usage.report_failed";
 };
+/**
+ * `PaymentObserver` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 type PaymentObserver = (event: PaymentEvent) => void;
-/** Returns whether the current caller may act on `referenceId`. Throwing is also treated as denial. */
+/**
+ * What a `processWebhook`-shaped internal action hands back to the HTTP route: the
+ * outcome plus the HTTP status the provider must actually see.
+ * @experimental
+ */
+interface WebhookOutcome {
+  /** Whether the event advanced a row. A verified no-op/duplicate is `false`. */
+  applied: boolean;
+  /** The status {@link LunoraPayment.handleWebhook} answered — 500 for an orphaned event. */
+  status: number;
+}
+/**
+ * Turn a {@link WebhookOutcome} back into the HTTP response the provider must see.
+ *
+ * The webhook endpoint runs at the Worker edge (signature verification needs the raw
+ * body) and forwards into the shard via `ctx.runAction`, so `handleWebhook`'s own
+ * `Response` cannot cross the action boundary — only its JSON payload can. A route
+ * that answers `Response.json(result)` therefore collapses every outcome to `200`,
+ * including the deliberate `500` on an orphaned (out-of-order) event: the provider
+ * stops retrying and that event is lost for good. Call this from the route instead
+ * of building the response by hand.
+ * @experimental
+ */
+declare const webhookResponse: (result: WebhookOutcome) => Response;
+/**
+ * Returns whether the current caller may act on `referenceId`. Throwing is also treated as denial.
+ * @experimental
+ */
 type AuthorizeReference = (referenceId: string) => boolean | Promise<boolean>;
+/**
+ * `CreatePaymentOptions` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 interface CreatePaymentOptions {
   readonly adapter: PaymentAdapter;
   /**
-  * Per-caller authorization for every mutation. Return `false` to reject with 403. Omit only
-  * for trusted server-internal callers (e.g. the reconciliation sweep).
-  */
+   * Per-caller authorization for every mutation. Return `false` to reject with 403. Omit only
+   * for trusted server-internal callers (e.g. the reconciliation sweep).
+   */
   readonly authorize?: AuthorizeReference;
   /** Plan → features/limits map. Required for `check`; omit if you don't gate features. */
   readonly entitlements?: EntitlementsConfig;
@@ -436,73 +259,162 @@ interface CreatePaymentOptions {
   readonly observability?: PaymentObserver;
   readonly store: PaymentStore;
 }
+/**
+ * `LunoraPayment` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 interface LunoraPayment {
   readonly adapter: PaymentAdapter;
   /**
-  * Subscribe a reference to a plan — a plan-oriented alias of {@link LunoraPayment.createCheckout}
-  * with `mode` defaulting to `"subscription"`. Returns a hosted-checkout URL to redirect to.
-  */
+   * Subscribe a reference to a plan — a plan-oriented alias of {@link LunoraPayment.createCheckout}
+   * with `mode` defaulting to `"subscription"`. Returns a hosted-checkout URL to redirect to.
+   */
   attach: (input: AttachInput) => Promise<CheckoutResult>;
+  /** Cancel the caller's own uncaptured payment (authorized, derived idempotency key, store synced). */
+  cancelPayment: (sessionId: string, options?: {
+    idempotencyKey?: string;
+  }) => Promise<PaymentSession>;
   cancelSubscription: (subscriptionId: string, options?: CancelSubscriptionOptions) => Promise<Subscription>;
+  /** Capture the caller's own authorized payment (authorized, derived idempotency key, store synced). */
+  capturePayment: (input: CaptureInput) => Promise<PaymentSession>;
   /**
-  * Is a reference allowed something right now? Pass `featureId` to check a grant/allowance (boolean
-  * features check plan grants; metered features subtract usage tracked this period) or `priceId` to
-  * check active access to a product. The feature path requires `entitlements` to be configured.
-  */
+   * Is a reference allowed something right now? Pass `featureId` to check a grant/allowance (boolean
+   * features check plan grants; metered features subtract usage tracked this period) or `priceId` to
+   * check active access to a product. The feature path requires `entitlements` to be configured.
+   */
   check: (input: CheckInput) => Promise<CheckResult>;
   createCheckout: (input: CheckoutInput) => Promise<CheckoutResult>;
   /** Open the provider billing portal for the caller's own customer (derived from the store). */
   createPortalSession: (referenceId: string, returnUrl: string) => Promise<{
     url: string;
   }>;
-  /** Verify + normalize + apply a provider webhook. Always 200 once verified, even on no-op. */
+  /**
+   * Verify + normalize + apply a provider webhook. 200 once verified, even on a no-op — except an
+   * event whose target row doesn't exist yet, which returns 500 so the provider redelivers it once.
+   */
   handleWebhook: (request: Request) => Promise<Response>;
   /** Resolve every configured feature's allowance for a reference in one call. Requires `entitlements`. */
   listBalances: (referenceId: string) => Promise<FeatureBalance[]>;
   listSubscriptions: (referenceId: string) => Promise<Subscription[]>;
+  /**
+   * Refund the caller's own captured payment (authorized, derived idempotency key, store synced).
+   *
+   * The derived key makes "same session, same amount, same reason" ONE operation, so a retried
+   * request cannot refund twice. Two *intentional* refunds of the same amount on one session are
+   * therefore indistinguishable from that retry: pass a distinct `RefundInput.idempotencyKey` for
+   * the second one, or the provider replays the first and the second moves no money.
+   */
+  refundPayment: (input: RefundInput) => Promise<PaymentSession>;
   readonly store: PaymentStore;
   /**
-  * Record metered usage for a reference's feature — durably (exactly-once by idempotency key) and,
-  * when the provider supports it, forwarded to its metering API. Best-effort upstream: a reporting
-  * failure is observed, never thrown, and the local ledger that `check` reads is always updated.
-  */
+   * Record metered usage for a reference's feature — durably (exactly-once by idempotency key) and,
+   * when the provider supports it, forwarded to its metering API. Best-effort upstream: a reporting
+   * failure is observed, never thrown, and the local ledger that `check` reads is always updated.
+   *
+   * `mode: "set"` is rejected with `VALIDATION_ERROR` on a provider that meters usage: its meter is
+   * additive, so a period total is not expressible on it and a lowering set would leave the provider
+   * billing more than the local ledger holds. Use `mode: "add"` there.
+   */
   track: (input: TrackInput) => Promise<TrackResult>;
 }
+/**
+ * `createPayment` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 declare const createPayment: (options: CreatePaymentOptions) => LunoraPayment;
-/** A stored row, carrying Lunora's document id. */
+/**
+ * A stored row, carrying Lunora's document id.
+ * @experimental
+ */
 interface PaymentRow extends Record<string, unknown> {
   readonly _id: string;
 }
-/** Minimal write/read surface this store needs; `ctx.db` satisfies it structurally. */
+/**
+ * Bounded-read arguments for {@link PaymentDatabase.findMany}, mirroring what
+ * Lunora's `ctx.db.findMany` already accepts. `where` stays equality-only — these
+ * are the knobs that let a caller bound the number of rows FETCHED rather than
+ * fetching everything and slicing afterwards.
+ * @experimental
+ */
+interface PaymentPageArgs {
+  /** Keyset cursor from a previous page's {@link PaymentPage.cursor}. */
+  cursor?: string;
+  /** Maximum rows to FETCH. Omit to read every match. */
+  limit?: number;
+  /** Sort keys, pushed down to the store so the keyset cursor is well-defined. */
+  orderBy?: Record<string, "asc" | "desc">[];
+}
+/**
+ * One page of rows plus the cursor that continues it.
+ * @experimental
+ */
+interface PaymentPage {
+  /** Cursor for the next page, or `undefined` when this was the last one. */
+  readonly cursor: string | undefined;
+  readonly rows: PaymentRow[];
+}
+/**
+ * Minimal write/read surface this store needs; `ctx.db` satisfies it structurally.
+ * @experimental
+ */
 interface PaymentDatabase {
   delete: (id: string) => Promise<void>;
   findFirst: (table: string, where: Record<string, unknown>) => Promise<PaymentRow | null>;
-  findMany: (table: string, where: Record<string, unknown>) => Promise<PaymentRow[]>;
+  /**
+   * Equality-only `where`, with optional order/limit/cursor pushed DOWN to the
+   * store (see {@link PaymentPageArgs}). Omitting `page` reads every match — do
+   * that only where the match set is inherently small (one reference's rows).
+   */
+  findMany: (table: string, where: Record<string, unknown>, page?: PaymentPageArgs) => Promise<PaymentPage>;
   insert: (table: string, document: Record<string, unknown>) => Promise<string>;
   patch: (id: string, patch: Record<string, unknown>) => Promise<void>;
 }
+/**
+ * `createDatabasePaymentStore` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 declare const createDatabasePaymentStore: (database: PaymentDatabase) => PaymentStore;
-/** Structural subset of Lunora's `ctx.db` (the `findFirst`/`findMany(tableName, { where })` form). */
+/**
+ * Structural subset of Lunora's `ctx.db` (the `findFirst`/`findMany(tableName, { where })` form).
+ *
+ * `findMany` models the order/limit/cursor knobs too — {@link PaymentDatabase}
+ * pushes them down so a sweep over a large match set reads bounded chunks
+ * instead of materialising the lot. `continueCursor` is REQUIRED here (`ctx.db`
+ * always returns it): a double that omitted it would page exactly once and then
+ * silently report the rest of the table as absent.
+ * @experimental
+ */
 interface LunoraDatabaseLike {
   delete: (id: string) => Promise<void>;
   findFirst: (table: string, args?: {
     where?: Record<string, unknown>;
   }) => Promise<Record<string, unknown> | null>;
   findMany: (table: string, args?: {
+    cursor?: string;
+    limit?: number;
+    orderBy?: Record<string, "asc" | "desc">[];
     where?: Record<string, unknown>;
   }) => Promise<{
+    continueCursor: null | string;
     page: Record<string, unknown>[];
   }>;
   insert: (table: string, document: Record<string, unknown>) => Promise<string>;
   patch: (id: string, patch: Record<string, unknown>) => Promise<void>;
 }
-/** Structural subset of a Lunora function context used to build payments. */
+/**
+ * Structural subset of a Lunora function context used to build payments.
+ * @experimental
+ */
 interface PaymentContextLike {
   auth?: {
     userId?: null | string;
   };
   db: LunoraDatabaseLike;
 }
+/**
+ * `PaymentsFromContextOptions` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 interface PaymentsFromContextOptions {
   readonly adapter: PaymentAdapter;
   /** Override the default "caller owns the referenceId" authorization. */
@@ -512,190 +424,90 @@ interface PaymentsFromContextOptions {
   /** Optional telemetry sink, forwarded to the facade. */
   readonly observability?: PaymentObserver;
 }
-/** Adapt a Lunora `ctx.db` to the {@link PaymentDatabase} port the store writes through. */
+/**
+ * Adapt a Lunora `ctx.db` to the {@link PaymentDatabase} port the store writes through.
+ * @experimental
+ */
 declare const lunoraDatabaseToPaymentDatabase: (database: LunoraDatabaseLike) => PaymentDatabase;
+/**
+ * `paymentsFromContext` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 declare const paymentsFromContext: (context: PaymentContextLike, options: PaymentsFromContextOptions) => LunoraPayment;
-type PaymentErrorCode = "CONFIG_INVALID" | "CURRENCY_MISMATCH" | "FORBIDDEN" | "INVALID_TRANSITION" | "NOT_FOUND" | "PROVIDER_ERROR" | "WEBHOOK_SIGNATURE_INVALID" | "WEBHOOK_TIMESTAMP_INVALID";
-/** Typed error for all `@lunora/payment` failures. `status` maps onto an HTTP response. */
-declare class LunoraPaymentError extends Error {
+/**
+ * `PaymentErrorCode` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+type PaymentErrorCode = "CONFIG_INVALID" | "CURRENCY_MISMATCH" | "FORBIDDEN" | "INVALID_TRANSITION" | "NOT_FOUND" | "PROVIDER_ERROR" | "VALIDATION_ERROR" | "WEBHOOK_EVENT_ID_MISSING" | "WEBHOOK_SIGNATURE_INVALID" | "WEBHOOK_TIMESTAMP_INVALID";
+/**
+ * Typed error for all `@lunora/payment` failures. A `LunoraError` subclass; `status` maps onto an HTTP response.
+ * @experimental
+ */
+declare class LunoraPaymentError extends LunoraError {
   readonly code: PaymentErrorCode;
-  readonly status: number;
   constructor(code: PaymentErrorCode, message: string);
 }
 /**
-* Outbound idempotency keys.
-*
-* Every mutating provider call carries a stable key derived from our own operation + inputs, so
-* a Worker retry can never double-charge. Distinct from inbound webhook dedupe (keyed on the
-* provider event id).
-*/
-/** Build a deterministic idempotency key from an operation name and stable parts. */
+ * Build a deterministic idempotency key from an operation name and stable parts.
+ * @experimental
+ */
 declare const idempotencyKey: (operation: string, ...parts: ReadonlyArray<number | string>) => string;
-/** True when the currency has no minor unit (e.g. JPY). */
+/**
+ * True when the currency has no minor unit (e.g. JPY).
+ */
 declare const isZeroDecimalCurrency: (currency: CurrencyCode) => boolean;
-/** Construct money. Currency is normalized to uppercase; never use floats for amounts. */
+/**
+ * Construct money. Currency is normalized to uppercase; never use floats for amounts.
+ */
 declare const money: (minorUnits: bigint | number, currency: CurrencyCode) => Money;
+/**
+ * Zero in the given currency.
+ */
 declare const zeroMoney: (currency: CurrencyCode) => Money;
-/** Localized currency string for display (e.g. `$19.99`). For UI only — never for arithmetic. */
+/**
+ * Localized currency string for display (e.g. `$19.99`). For UI only — never for arithmetic.
+ */
 declare const formatMoney: (value: Money, locale?: string) => string;
+/**
+ * Sum of two same-currency amounts. Throws `CURRENCY_MISMATCH` otherwise.
+ */
 declare const addMoney: (a: Money, b: Money) => Money;
+/**
+ * Difference of two same-currency amounts. Throws `CURRENCY_MISMATCH` otherwise.
+ */
 declare const subtractMoney: (a: Money, b: Money) => Money;
-/** Compares two same-currency amounts, returning -1, 0, or 1. */
+/**
+ * Compares two same-currency amounts, returning -1, 0, or 1.
+ */
 declare const compareMoney: (a: Money, b: Money) => -1 | 0 | 1;
 /**
-* Split an amount across integer ratios, distributing the remainder to the smallest unit so the
-* parts always sum back to the original. The basis for seat/proration math.
-*/
+ * Split an amount across integer ratios, distributing the remainder to the smallest unit so the
+ * parts always sum back to the original. The basis for seat/proration math.
+ */
 declare const allocateMoney: (amount: Money, ratios: ReadonlyArray<bigint>) => Money[];
+/**
+ * True when the amount is exactly zero minor units.
+ */
 declare const isZeroMoney: (a: Money) => boolean;
-/** JSON-safe wire form of money (bigint encoded as a decimal string). */
+/**
+ * JSON-safe wire form of money (bigint encoded as a decimal string).
+ */
 interface MoneyJSON {
   readonly currency: CurrencyCode;
   readonly minorUnits: string;
 }
+/**
+ * Encode money for the wire — `minorUnits` becomes a decimal string.
+ */
 declare const toMoneyJSON: (m: Money) => MoneyJSON;
+/**
+ * Decode the wire form back to a `bigint`-backed {@link Money}.
+ */
 declare const fromMoneyJSON: (json: MoneyJSON) => Money;
-interface PolarSubscriptionLike {
-  readonly cancelAtPeriodEnd?: boolean;
-  readonly currentPeriodEnd?: null | string;
-  readonly currentPeriodStart?: null | string;
-  readonly customerId?: null | string;
-  readonly id: string;
-  readonly metadata?: Record<string, string>;
-  readonly productId?: string;
-  readonly status: string;
-}
-interface PolarOrderLike {
-  readonly amount?: number;
-  readonly currency?: string;
-  readonly id: string;
-  readonly status: string;
-  readonly totalAmount?: number;
-}
-interface PolarClientLike {
-  readonly checkouts: {
-    create: (parameters: Record<string, unknown>) => Promise<{
-      id: string;
-      url: string;
-    }>;
-  };
-  readonly customers: {
-    create: (parameters: Record<string, unknown>) => Promise<{
-      email: null | string;
-      id: string;
-    }>;
-  };
-  readonly customerSessions: {
-    create: (parameters: Record<string, unknown>) => Promise<{
-      customerPortalUrl: string;
-    }>;
-  };
-  readonly events: {
-    ingest: (parameters: Record<string, unknown>) => Promise<{
-      inserted?: number;
-    }>;
-  };
-  readonly orders: {
-    get: (parameters: Record<string, unknown>) => Promise<PolarOrderLike>;
-  };
-  readonly refunds: {
-    create: (parameters: Record<string, unknown>) => Promise<{
-      id: string;
-    }>;
-  };
-  readonly subscriptions: {
-    get: (parameters: Record<string, unknown>) => Promise<PolarSubscriptionLike>;
-    revoke: (parameters: Record<string, unknown>) => Promise<PolarSubscriptionLike>;
-    update: (parameters: Record<string, unknown>) => Promise<PolarSubscriptionLike>;
-  };
-}
-interface PolarAdapterOptions {
-  readonly client: PolarClientLike;
-  readonly webhookSecret: string;
-  readonly webhookToleranceSeconds?: number;
-}
-declare const createPolarAdapter: (options: PolarAdapterOptions) => PaymentAdapter;
-interface StripeRequestOptions {
-  readonly idempotencyKey?: string;
-}
-interface StripePaymentIntentLike {
-  readonly amount: number;
-  readonly amount_received?: number;
-  readonly currency: string;
-  readonly customer?: null | string;
-  readonly id: string;
-  readonly metadata?: Record<string, string>;
-  readonly status: string;
-}
-interface StripeSubscriptionLike {
-  readonly cancel_at_period_end?: boolean;
-  readonly current_period_end?: number;
-  readonly current_period_start?: number;
-  readonly customer?: null | string;
-  readonly id: string;
-  readonly items?: {
-    data: ReadonlyArray<{
-      price?: {
-        id?: string;
-      };
-      quantity?: number;
-    }>;
-  };
-  readonly metadata?: Record<string, string>;
-  readonly status: string;
-}
-/** The subset of the Stripe SDK surface this adapter calls. A real `Stripe` instance satisfies it. */
-interface StripeClientLike {
-  readonly billing: {
-    meterEvents: {
-      create: (parameters: Record<string, unknown>, options?: StripeRequestOptions) => Promise<{
-        identifier?: string;
-      }>;
-    };
-  };
-  readonly billingPortal: {
-    sessions: {
-      create: (parameters: Record<string, unknown>) => Promise<{
-        url: string;
-      }>;
-    };
-  };
-  readonly checkout: {
-    sessions: {
-      create: (parameters: Record<string, unknown>, options?: StripeRequestOptions) => Promise<{
-        id: string;
-        url: null | string;
-      }>;
-    };
-  };
-  readonly customers: {
-    create: (parameters: Record<string, unknown>, options?: StripeRequestOptions) => Promise<{
-      email: null | string;
-      id: string;
-    }>;
-  };
-  readonly paymentIntents: {
-    cancel: (id: string, parameters?: Record<string, unknown>, options?: StripeRequestOptions) => Promise<StripePaymentIntentLike>;
-    capture: (id: string, parameters?: Record<string, unknown>, options?: StripeRequestOptions) => Promise<StripePaymentIntentLike>;
-    retrieve: (id: string) => Promise<StripePaymentIntentLike>;
-  };
-  readonly refunds: {
-    create: (parameters: Record<string, unknown>, options?: StripeRequestOptions) => Promise<{
-      id: string;
-    }>;
-  };
-  readonly subscriptions: {
-    cancel: (id: string, parameters?: Record<string, unknown>, options?: StripeRequestOptions) => Promise<StripeSubscriptionLike>;
-    retrieve: (id: string) => Promise<StripeSubscriptionLike>;
-    update: (id: string, parameters: Record<string, unknown>, options?: StripeRequestOptions) => Promise<StripeSubscriptionLike>;
-  };
-}
-interface StripeAdapterOptions {
-  readonly client: StripeClientLike;
-  readonly webhookSecret: string;
-  readonly webhookToleranceSeconds?: number;
-}
-declare const createStripeAdapter: (options: StripeAdapterOptions) => PaymentAdapter;
+/**
+ * `ReconcileInput` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 interface ReconcileInput {
   readonly adapter: PaymentAdapter;
   /** Optional telemetry sink — fired per drifted row and once on completion. */
@@ -703,56 +515,107 @@ interface ReconcileInput {
   readonly paymentSessionIds?: ReadonlyArray<string>;
   readonly store: PaymentStore;
   readonly subscriptionIds?: ReadonlyArray<string>;
+  /**
+   * How many unreported usage events to retry forwarding upstream this sweep
+   * (oldest first). Default {@link DEFAULT_USAGE_REPORT_LIMIT}; `0` skips the
+   * usage sweep entirely. Ignored by an adapter that does not meter usage.
+   */
+  readonly usageReportLimit?: number;
 }
+/**
+ * `ReconcileResult` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 interface ReconcileResult {
   readonly checkedPayments: number;
   readonly checkedSubscriptions: number;
+  readonly checkedUsage: number;
   readonly failedPayments: number;
   readonly failedSubscriptions: number;
+  /** Usage events whose retried forward failed again — still pending for the next sweep. */
+  readonly failedUsage: number;
   readonly updatedPayments: number;
   readonly updatedSubscriptions: number;
+  /** Usage events successfully forwarded upstream on this sweep. */
+  readonly updatedUsage: number;
 }
+/**
+ * `reconcile` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 declare const reconcile: (input: ReconcileInput) => Promise<ReconcileResult>;
+/**
+ * The canonical column reference for the payment tables — a value to READ (in a test, a migration
+ * check, or your editor), not one to spread. `defineSchema({ ...paymentTables })` does NOT work:
+ * codegen discovers tables by parsing your `lunora/schema.ts` AST and cannot resolve a
+ * cross-package spread, so declare the same columns inline there (see the module docstring).
+ *
+ * `paymentTables` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 declare const paymentTables: Record<string, TableDefinition>;
-/** Action that may advance a payment session. */
+/**
+ * Action that may advance a payment session.
+ * @experimental
+ */
 type PaymentAction = "authorize" | "cancel" | "capture" | "fail" | "partial_refund" | "refund";
-/** Action that may advance a subscription. */
+/**
+ * Action that may advance a subscription.
+ * @experimental
+ */
 type SubscriptionAction = "activate" | "cancel" | "mark_past_due" | "pause" | "renew" | "resume";
+/**
+ * `PAYMENT_TERMINAL_STATES` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 declare const PAYMENT_TERMINAL_STATES: ReadonlySet<PaymentState>;
+/**
+ * `SUBSCRIPTION_TERMINAL_STATES` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 declare const SUBSCRIPTION_TERMINAL_STATES: ReadonlySet<SubscriptionState>;
-/** Next payment state for an action, or `undefined` if the transition is illegal from `from`. */
+/**
+ * Next payment state for an action, or `undefined` if the transition is illegal from `from`.
+ * @experimental
+ */
 declare const nextPaymentState: (from: PaymentState, action: PaymentAction) => PaymentState | undefined;
+/**
+ * `canTransitionPayment` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 declare const canTransitionPayment: (from: PaymentState, action: PaymentAction) => boolean;
-/** Next subscription state for an action, or `undefined` if the transition is illegal from `from`. */
+/**
+ * Next subscription state for an action, or `undefined` if the transition is illegal from `from`.
+ * @experimental
+ */
 declare const nextSubscriptionState: (from: SubscriptionState, action: SubscriptionAction) => SubscriptionState | undefined;
+/**
+ * `canTransitionSubscription` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 declare const canTransitionSubscription: (from: SubscriptionState, action: SubscriptionAction) => boolean;
+/**
+ * `applyWebhookAction` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
 declare const applyWebhookAction: (store: PaymentStore, action: WebhookAction, observer?: PaymentObserver) => Promise<ApplyResult>;
-/** Constant-time string comparison to avoid leaking byte positions via timing. */
+/**
+ * Constant-time string comparison to avoid leaking byte positions via timing.
+ *
+ * Re-exported from `shared/constant-time-equal` rather than defined here. The
+ * copy that used to live at this spot returned early on a length mismatch, so
+ * an attacker learned the expected signature's LENGTH from the response time —
+ * the exact divergence that shared file was created to stop, and which it
+ * records having already fixed once in the relay hub. It also compared by code
+ * POINT, making timing depend on surrogate boundaries; the canonical one
+ * compares per UTF-16 code unit.
+ */
 declare const constantTimeEqual: (a: string, b: string) => boolean;
-declare const hmacSha256Hex: (secret: string, payload: string) => Promise<string>;
-interface StripeSignatureParts {
-  readonly signatures: string[];
-  readonly timestamp: number;
-}
-/** Parse a Stripe-style `t=...,v1=...,v1=...` signature header. */
-declare const parseStripeSignatureHeader: (header: string) => StripeSignatureParts;
-interface VerifyStripeSignatureInput {
-  /** Injectable clock (ms since epoch) for tests. */
-  readonly now?: number;
-  /** Raw request body, exactly as received. */
-  readonly payload: string;
-  readonly secret: string;
-  /** The `Stripe-Signature` header value. */
-  readonly signatureHeader: string;
-  /** Whole-second tolerance for the signed timestamp (default 300). */
-  readonly toleranceSeconds?: number;
-}
 /**
-* Verify a Stripe-scheme webhook signature: `HMAC_SHA256(secret, "{t}.{payload}")` compared
-* against the header's `v1` values, with a timestamp tolerance to reject replays. Throws a
-* {@link LunoraPaymentError} on any failure.
-*/
-declare const verifyStripeSignature: (input: VerifyStripeSignatureInput) => Promise<void>;
+ * Hex-encoded `HMAC_SHA256(secret, payload)` — the primitive behind the hex-scheme
+ * webhook verifiers.
+ */
+declare const hmacSha256Hex: (secret: string, payload: string) => Promise<string>;
 interface VerifyStandardWebhookInput {
   /** Injectable clock (ms since epoch) for tests. */
   readonly now?: number;
@@ -764,15 +627,29 @@ interface VerifyStandardWebhookInput {
   readonly toleranceSeconds?: number;
   /** `webhook-id` header. */
   readonly webhookId: string;
-  /** `webhook-signature` header — space-separated `v1,&lt;base64>` entries. */
+  /** `webhook-signature` header — space-separated `v1,<base64>` entries. */
   readonly webhookSignature: string;
   /** `webhook-timestamp` header — unix seconds as a string. */
   readonly webhookTimestamp: string;
 }
 /**
-* Verify a Standard Webhooks signature (the scheme Polar and svix use):
-* `base64(HMAC_SHA256(key, "{id}.{timestamp}.{payload}"))` compared against the header's `v1`
-* entries, with a replay-window check. Throws a {@link LunoraPaymentError} on any failure.
-*/
+ * Verify a Standard Webhooks signature (the scheme Polar and svix use):
+ * `base64(HMAC_SHA256(key, "{id}.{timestamp}.{payload}"))` compared against the header's `v1`
+ * entries, with a replay-window check. Throws a {@link LunoraPaymentError} on any failure.
+ */
 declare const verifyStandardWebhook: (input: VerifyStandardWebhookInput) => Promise<void>;
-export { type AdapterRegistry, type ApplyResult, type AttachInput, type AuthorizeReference, type CancelSubscriptionOptions, type CaptureInput, type CheckInput, type CheckResult, type CheckoutInput, type CheckoutResult, type CreatePaymentOptions, type CurrencyCode, type Customer, type CustomerRef, type Entitlements, type EntitlementsConfig, type FeatureBalance, type LunoraDatabaseLike, type LunoraPayment, LunoraPaymentError, MemoryPaymentStore, type Money, type MoneyJSON, PAYMENT_TERMINAL_STATES, type PaymentAction, type PaymentAdapter, type PaymentContextLike, type PaymentDatabase, type PaymentErrorCode, type PaymentEvent, type PaymentObserver, type PaymentRow, type PaymentSession, type PaymentState, type PaymentStore, type PaymentsFromContextOptions, type PlanDefinition, type PolarAdapterOptions, type PolarClientLike, type PortalInput, type ProviderCapabilities, type ProviderId, type ReconcileInput, type ReconcileResult, type RefundAmountKind, type RefundInput, type ReportUsageInput, SUBSCRIPTION_TERMINAL_STATES, type StripeAdapterOptions, type StripeClientLike, type Subscription, type SubscriptionAction, type SubscriptionPatch, type SubscriptionState, type TrackInput, type TrackResult, type UsageEvent, type WebhookAction, type WebhookActionType, type WebhookHeaders, type WebhookInput, addMoney, allocateMoney, applyWebhookAction, canTransitionPayment, canTransitionSubscription, compareMoney, constantTimeEqual, createAdapterRegistry, createDatabasePaymentStore, createPayment, createPolarAdapter, createStripeAdapter, entitlementsForReference, featureNames, formatMoney, fromMoneyJSON, hasActivePrice, hmacSha256Hex, idempotencyKey, isZeroDecimalCurrency, isZeroMoney, lunoraDatabaseToPaymentDatabase, money, nextPaymentState, nextSubscriptionState, parseStripeSignatureHeader, paymentTables, paymentsFromContext, reconcile, resolveEntitlements, subtractMoney, toMoneyJSON, usagePeriodStart, verifyStandardWebhook, verifyStripeSignature, zeroMoney };
+interface VerifyCreemSignatureInput {
+  /** Raw request body, exactly as received. */
+  readonly payload: string;
+  /** Creem webhook signing secret. */
+  readonly secret: string;
+  /** The `creem-signature` header value. */
+  readonly signature: string;
+}
+/**
+ * Verify a Creem webhook signature: `hex(HMAC_SHA256(secret, rawBody))` compared against the
+ * `creem-signature` header. Creem's scheme signs the raw body with no timestamp, so there is no
+ * replay-window check. Throws a {@link LunoraPaymentError} on any failure.
+ */
+declare const verifyCreemSignature: (input: VerifyCreemSignatureInput) => Promise<void>;
+export { type ApplyResult, type AttachInput, type AuthorizeReference, type CancelSubscriptionOptions, type CaptureInput, type CheckInput, type CheckResult, type CheckoutInput, type CheckoutResult, type CreatePaymentOptions, type CurrencyCode, type Customer, type Entitlements, type EntitlementsConfig, type FeatureBalance, type LunoraDatabaseLike, type LunoraPayment, LunoraPaymentError, MemoryPaymentStore, type Money, type MoneyJSON, PAYMENT_TERMINAL_STATES, type PaymentAction, type PaymentAdapter, type PaymentContextLike, type PaymentDatabase, type PaymentErrorCode, type PaymentEvent, type PaymentObserver, type PaymentPage, type PaymentPageArgs, type PaymentRow, type PaymentSession, type PaymentState, type PaymentStore, type PaymentsFromContextOptions, type PlanDefinition, type ProviderId, type ReconcileInput, type ReconcileResult, type RefundInput, SUBSCRIPTION_TERMINAL_STATES, type Subscription, type SubscriptionAction, type SubscriptionState, type TrackInput, type TrackResult, type UsageEvent, type VerifyCreemSignatureInput, type VerifyStandardWebhookInput, type WebhookAction, type WebhookActionType, type WebhookOutcome, addMoney, allocateMoney, applyWebhookAction, canTransitionPayment, canTransitionSubscription, compareMoney, constantTimeEqual, createDatabasePaymentStore, createPayment, entitlementsForReference, featureNames, formatMoney, fromMoneyJSON, hasActivePrice, hmacSha256Hex, idempotencyKey, isZeroDecimalCurrency, isZeroMoney, lunoraDatabaseToPaymentDatabase, money, nextPaymentState, nextSubscriptionState, paymentTables, paymentsFromContext, reconcile, resolveEntitlements, subtractMoney, toMoneyJSON, usagePeriodStart, verifyCreemSignature, verifyStandardWebhook, webhookResponse, zeroMoney };