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

package/dist/index.mjs

@@ -1,16 +1 @@
-export { createAdapterRegistry } from './packem_shared/createAdapterRegistry-BuDHFCBc.mjs';
-export { lunoraDatabaseToPaymentDatabase, paymentsFromContext } from './packem_shared/lunoraDatabaseToPaymentDatabase-RlKX3Kcd.mjs';
-export { createPayment } from './packem_shared/createPayment-BccfPGyw.mjs';
-export { createDatabasePaymentStore } from './packem_shared/createDatabasePaymentStore-bYB_HUE6.mjs';
-export { entitlementsForReference, featureNames, hasActivePrice, resolveEntitlements, usagePeriodStart } from './packem_shared/entitlementsForReference-CzZGXPoZ.mjs';
-export { LunoraPaymentError } from './packem_shared/LunoraPaymentError-B3hEzXSs.mjs';
-export { default as idempotencyKey } from './packem_shared/idempotencyKey-BFzDCA7g.mjs';
-export { addMoney, allocateMoney, compareMoney, formatMoney, fromMoneyJSON, isZeroDecimalCurrency, isZeroMoney, money, subtractMoney, toMoneyJSON, zeroMoney } from './packem_shared/addMoney-bCcs1nyw.mjs';
-export { createPolarAdapter } from './packem_shared/createPolarAdapter-CgErk9zo.mjs';
-export { createStripeAdapter } from './packem_shared/createStripeAdapter-oDvMhpeX.mjs';
-export { reconcile } from './packem_shared/reconcile-CI1ukJF9.mjs';
-export { default as paymentTables } from './packem_shared/paymentTables-DccHwWr_.mjs';
-export { PAYMENT_TERMINAL_STATES, SUBSCRIPTION_TERMINAL_STATES, canTransitionPayment, canTransitionSubscription, nextPaymentState, nextSubscriptionState } from './packem_shared/PAYMENT_TERMINAL_STATES-DrxV0clv.mjs';
-export { MemoryPaymentStore } from './packem_shared/MemoryPaymentStore-DvgdWa3C.mjs';
-export { default as applyWebhookAction } from './packem_shared/applyWebhookAction-DpAqf3Lw.mjs';
-export { constantTimeEqual, hmacSha256Hex, parseStripeSignatureHeader, verifyStandardWebhook, verifyStripeSignature } from './packem_shared/constantTimeEqual-CfY0jYcL.mjs';
+import{createAdapterRegistry as r}from"./packem_shared/createAdapterRegistry-DyCsry1Q.mjs";import{lunoraDatabaseToPaymentDatabase as a,paymentsFromContext as n}from"./packem_shared/lunoraDatabaseToPaymentDatabase-CFPYSEu0.mjs";import{createPayment as y,webhookResponse as i}from"./packem_shared/createPayment-Dimez2zY.mjs";import{createDatabasePaymentStore as s}from"./packem_shared/createDatabasePaymentStore-BGcHX1uq.mjs";import{entitlementsForReference as c,featureNames as x,hasActivePrice as S,resolveEntitlements as l,usagePeriodStart as M}from"./packem_shared/entitlementsForReference-PMmhAOWa.mjs";import{LunoraPaymentError as u}from"./packem_shared/LunoraPaymentError-BSxyhWgu.mjs";import{idempotencyKey as b}from"./packem_shared/idempotencyKey-qQJLcEQX.mjs";import{addMoney as A,allocateMoney as E,compareMoney as N,formatMoney as h,fromMoneyJSON as R,isZeroDecimalCurrency as v,isZeroMoney as C,money as D,subtractMoney as I,toMoneyJSON as _,zeroMoney as g}from"./packem_shared/addMoney-B4ufWAnD.mjs";import{reconcile as L}from"./packem_shared/reconcile-fbxX8j9k.mjs";import{default as F}from"./packem_shared/paymentTables-Ve_lJxAt.mjs";import{PAYMENT_TERMINAL_STATES as W,SUBSCRIPTION_TERMINAL_STATES as Z,canTransitionPayment as q,canTransitionSubscription as w,nextPaymentState as z,nextSubscriptionState as B}from"./packem_shared/PAYMENT_TERMINAL_STATES-C-ICZkun.mjs";import{MemoryPaymentStore as K}from"./packem_shared/MemoryPaymentStore-CZbrrEb1.mjs";import{default as Y}from"./packem_shared/applyWebhookAction-CvLpZjKP.mjs";import{constantTimeEqual as G,hmacSha256Hex as Q,verifyCreemSignature as V,verifyStandardWebhook as X}from"./packem_shared/constantTimeEqual-ggrwGvRa.mjs";export{u as LunoraPaymentError,K as MemoryPaymentStore,W as PAYMENT_TERMINAL_STATES,Z as SUBSCRIPTION_TERMINAL_STATES,A as addMoney,E as allocateMoney,Y as applyWebhookAction,q as canTransitionPayment,w as canTransitionSubscription,N as compareMoney,G as constantTimeEqual,r as createAdapterRegistry,s as createDatabasePaymentStore,y as createPayment,c as entitlementsForReference,x as featureNames,h as formatMoney,R as fromMoneyJSON,S as hasActivePrice,Q as hmacSha256Hex,b as idempotencyKey,v as isZeroDecimalCurrency,C as isZeroMoney,a as lunoraDatabaseToPaymentDatabase,D as money,z as nextPaymentState,B as nextSubscriptionState,F as paymentTables,n as paymentsFromContext,L as reconcile,l as resolveEntitlements,I as subtractMoney,_ as toMoneyJSON,M as usagePeriodStart,V as verifyCreemSignature,X as verifyStandardWebhook,i as webhookResponse,g as zeroMoney};

package/dist/packem_shared/LunoraPaymentError-BSxyhWgu.mjs

@@ -0,0 +1 @@
+import{LunoraError as E}from"@lunora/errors";const O={CONFIG_INVALID:500,CURRENCY_MISMATCH:400,FORBIDDEN:403,INVALID_TRANSITION:409,NOT_FOUND:404,PROVIDER_ERROR:502,VALIDATION_ERROR:400,WEBHOOK_EVENT_ID_MISSING:400,WEBHOOK_SIGNATURE_INVALID:400,WEBHOOK_TIMESTAMP_INVALID:400};class R extends E{constructor(I,r){super(I,r,{name:"LunoraPaymentError",status:O[I]})}}export{R as LunoraPaymentError};

package/dist/packem_shared/MemoryPaymentStore-CZbrrEb1.mjs

@@ -0,0 +1 @@
+const a=(i,e)=>`${i}:${e}`,n=(i,e)=>`${i}:${e}`,u=i=>{const e=i.toSorted((t,r)=>t.createdAt-r.createdAt||t.idempotencyKey.localeCompare(r.idempotencyKey));let s=0;for(const t of e)s=t.mode==="set"?t.quantity:s+t.quantity;return s};class d{customers=new Map;processedEvents=new Set;sessions=new Map;subscriptions=new Map;usageEvents=new Map;getCustomerByReference(e,s){return Promise.resolve(this.customers.get(a(e,s)))}getPaymentSession(e,s){return Promise.resolve(this.sessions.get(n(e,s)))}getSubscription(e,s){return Promise.resolve(this.subscriptions.get(n(e,s)))}listSubscriptionsByReference(e){return Promise.resolve([...this.subscriptions.values()].filter(s=>s.referenceId===e))}listUnreportedUsage(e,s){const t=[...this.usageEvents.values()].filter(r=>r.provider===e&&!r.reportedToProvider&&r.mode!=="set"&&r.quantity>0).toSorted((r,o)=>r.createdAt-o.createdAt||r.idempotencyKey.localeCompare(o.idempotencyKey));return Promise.resolve(t.slice(0,Math.max(0,s)))}markEventProcessed(e,s,t){const r=n(e,s);return this.processedEvents.has(r)?Promise.resolve(!1):(this.processedEvents.add(r),Promise.resolve(!0))}releaseEvent(e,s){return this.processedEvents.delete(n(e,s)),Promise.resolve()}markUsageReported(e,s){const t=n(e,s),r=this.usageEvents.get(t);return r&&this.usageEvents.set(t,{...r,reportedToProvider:!0}),Promise.resolve()}recordUsage(e){const s=n(e.provider,e.idempotencyKey);return this.usageEvents.has(s)?Promise.resolve(!1):(this.usageEvents.set(s,e),Promise.resolve(!0))}sumUsage(e,s,t){const r=[];for(const o of this.usageEvents.values())o.referenceId===e&&o.featureId===s&&o.createdAt>=t&&r.push(o);return Promise.resolve(u(r))}sumUsageByFeature(e,s,t){const r=new Map(s.map(o=>[o,[]]));for(const o of this.usageEvents.values())o.referenceId===e&&o.createdAt>=t&&r.get(o.featureId)?.push(o);return Promise.resolve(new Map([...r].map(([o,c])=>[o,u(c)])))}upsertCustomer(e){return this.customers.set(a(e.provider,e.referenceId),e),Promise.resolve()}upsertPaymentSession(e){return this.sessions.set(n(e.provider,e.id),e),Promise.resolve()}upsertSubscription(e){return this.subscriptions.set(n(e.provider,e.id),e),Promise.resolve()}}export{d as MemoryPaymentStore,u as foldUsage};

package/dist/packem_shared/PAYMENT_TERMINAL_STATES-C-ICZkun.mjs

@@ -0,0 +1 @@
+const c={authorized:{cancel:"canceled",capture:"captured",fail:"failed"},canceled:{},captured:{partial_refund:"partially_refunded",refund:"refunded"},failed:{authorize:"authorized",capture:"captured",fail:"failed"},initiated:{authorize:"authorized",cancel:"canceled",capture:"captured",fail:"failed"},partially_refunded:{partial_refund:"partially_refunded",refund:"refunded"},refunded:{refund:"refunded"}},t={active:{cancel:"canceled",mark_past_due:"past_due",pause:"paused",renew:"active"},canceled:{},past_due:{activate:"active",cancel:"canceled",pause:"paused",renew:"active"},paused:{cancel:"canceled",resume:"active"},trialing:{activate:"active",cancel:"canceled",mark_past_due:"past_due",pause:"paused",renew:"active"}},r=new Set(["canceled","refunded"]),i=new Set(["canceled"]),n=(e,a)=>c[e][a],u=(e,a)=>n(e,a)!==void 0,d=(e,a)=>t[e][a],l=(e,a)=>d(e,a)!==void 0;export{r as PAYMENT_TERMINAL_STATES,i as SUBSCRIPTION_TERMINAL_STATES,u as canTransitionPayment,l as canTransitionSubscription,n as nextPaymentState,d as nextSubscriptionState};

package/dist/packem_shared/adapter.d-DytKm_IF.d.mts

@@ -0,0 +1,513 @@
+/**
+ * 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). Ships Stripe/Polar/Autumn/Dodo plus Creem, an EU-friendly MoR.
+ * @experimental
+ */
+type ProviderId = "autumn" | "creem" | "dodopayments" | "polar" | "stripe";
+/**
+ * What a provider can do — encoded in types so tax/UX assumptions aren't tribal knowledge.
+ * @experimental
+ */
+interface ProviderCapabilities {
+  /** True for Polar / Lemon Squeezy / Paddle; false for Stripe (PSP) and Autumn (runs on your own Stripe). 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.
+ * @experimental
+ */
+type PaymentState = "authorized" | "canceled" | "captured" | "failed" | "initiated" | "partially_refunded" | "refunded";
+/**
+ * Lifecycle state of a subscription.
+ * @experimental
+ */
+type SubscriptionState = "active" | "canceled" | "past_due" | "paused" | "trialing";
+/**
+ * `Customer` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+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;
+}
+/**
+ * `PaymentSession` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+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;
+}
+/**
+ * `Subscription` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+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;
+  /** The primary (first) price/product id — `priceIds[0]`. Display and single-item plan changes. */
+  readonly priceId: string;
+  /**
+   * EVERY price/product id the subscription bills, not just the primary one. A Stripe subscription
+   * can carry an add-on or a metered price alongside the base plan, and a customer paying for one is
+   * entitled to it — so entitlements test membership here (see `hasActivePrice`).
+   *
+   * Optional because the webhook path and any pre-existing stored row carry only `priceId`; absent
+   * reads as `[priceId]`, which is exactly right for the single-item case every other provider has.
+   */
+  readonly priceIds?: ReadonlyArray<string>;
+  readonly provider: ProviderId;
+  readonly quantity: number;
+  readonly referenceId: string;
+  readonly state: SubscriptionState;
+  readonly updatedAt: number;
+}
+/**
+ * `CustomerRef` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+interface CustomerRef {
+  readonly email?: string;
+  readonly metadata?: Record<string, string>;
+  readonly referenceId: string;
+}
+/**
+ * `CheckoutInput` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+interface CheckoutInput {
+  readonly cancelUrl: string;
+  /**
+   * Ignored at runtime (kept for backward-compat). The provider customer is always derived from the store for the
+   * authorized `referenceId` (never caller-supplied) to prevent cross-tenant checkout attachment (IDOR).
+   * Retained on the type only for backward compatibility; setting it has no effect.
+   */
+  readonly customerId?: string;
+  /**
+   * Customer email, used when the reference has no provider customer yet. Some Merchant-of-Record
+   * providers (e.g. Dodo Payments) require an email to mint a customer, so pass it on first checkout.
+   */
+  readonly email?: 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;
+}
+/**
+ * `CheckoutResult` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+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 }`.
+ * @experimental
+ */
+interface AttachInput extends Omit<CheckoutInput, "mode"> {
+  readonly mode?: CheckoutInput["mode"];
+}
+/**
+ * `PortalInput` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+interface PortalInput {
+  readonly customerId: string;
+  readonly returnUrl: string;
+}
+/**
+ * A single durable usage record — one metered event for a `(referenceId, featureId)` pair.
+ * @experimental
+ */
+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;
+  /**
+   * How the period total absorbs this event: `"add"` (the default, and the value
+   * assumed for rows written before this field existed) increments it, `"set"`
+   * RESETS it to `quantity` and discards everything recorded earlier in the
+   * period.
+   *
+   * The ledger stays append-only either way — a `"set"` is a marker, not a
+   * computed delta — which is what makes `track({ mode: "set" })` safe to call
+   * concurrently. `PaymentStore.sumUsage` (via `foldUsage`) applies the fold.
+   */
+  readonly mode?: "add" | "set";
+  readonly provider: ProviderId;
+  /** For `"add"`, the increment. For `"set"`, the absolute period total this event declares. */
+  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.
+ * @experimental
+ */
+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`.
+   *
+   * Both are a single append: a `"set"` records the absolute target as a marker that the period fold
+   * resets to, rather than reading the current total and appending a delta. Concurrent `"set"` calls
+   * for the same reference therefore resolve last-writer-wins instead of over- or under-counting, and
+   * a replayed `"set"` is idempotent — neither mode needs a serialized context or a per-reference lock.
+   *
+   * `"set"` reconciles the LOCAL period total only, so `track` rejects it with `VALIDATION_ERROR` on a
+   * provider that meters usage upstream: those meters are additive and cannot take a period total, and
+   * a set that LOWERS usage has no negative delta to forward — the provider would keep billing the
+   * higher figure while the local ledger holds the lower one. Use `"add"` with a metered provider.
+   */
+  readonly mode?: "add" | "set";
+  /**
+   * Usage amount to add, or the absolute period total when `mode` is `"set"` (defaults to `1`).
+   * Must be a non-negative safe integer — a negative value would drive the summed period usage
+   * below zero and hand the reference an unbounded metered balance, so it is rejected.
+   */
+  readonly quantity?: number;
+  readonly referenceId: string;
+}
+/**
+ * Result of a `track` call.
+ * @experimental
+ */
+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).
+ * @experimental
+ */
+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.
+ * @experimental
+ */
+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.
+ * @experimental
+ */
+interface FeatureBalance extends CheckResult {
+  readonly featureId: string;
+}
+/**
+ * Input the adapter forwards to the provider's metering API (Stripe Meter Events / Polar ingestion).
+ * @experimental
+ */
+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;
+}
+/**
+ * `CaptureInput` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+interface CaptureInput {
+  /** Partial capture amount; full capture when omitted. */
+  readonly amount?: Money;
+  readonly idempotencyKey?: string;
+  readonly sessionId: string;
+}
+/**
+ * `RefundInput` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+interface RefundInput {
+  /** Partial refund amount; full refund when omitted. */
+  readonly amount?: Money;
+  readonly idempotencyKey?: string;
+  readonly reason?: string;
+  readonly sessionId: string;
+}
+/**
+ * What an adapter's `refundPayment` returns: the provider-shaped session, plus the provider's own id
+ * for the refund it just issued.
+ *
+ * `RefundResult` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+interface RefundResult extends PaymentSession {
+  /**
+   * The provider accepted the refund but has NOT moved the money yet — Dodo answers
+   * `refunds.create` with `pending`/`review` and settles later via `refund.succeeded`, or never,
+   * via `refund.failed`. The facade leaves its ledger untouched for one of these and lets the
+   * confirming webhook carry the money, because a `refund.failed` reverses nothing. Absent (the
+   * default) means the refund is already settled — Stripe and Polar refund synchronously.
+   */
+  readonly pending?: boolean;
+  /**
+   * The provider's id for THIS refund — Stripe and Polar `Refund.id`, Dodo `refund_id`. It is the
+   * identity the facade keys its local refund marker on, so two in-flight refunds of the same
+   * amount on one session stay distinct. `undefined` only where a provider reports no id, which
+   * falls the marker back to the (colliding) amount.
+   */
+  readonly refundId?: string;
+}
+/**
+ * `CancelSubscriptionOptions` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+interface CancelSubscriptionOptions {
+  /** Cancel at period end instead of immediately. */
+  readonly atPeriodEnd?: boolean;
+  readonly idempotencyKey?: string;
+}
+/**
+ * `SubscriptionPatch` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+interface SubscriptionPatch {
+  /**
+   * Override the outbound idempotency key. Honoured by the Stripe adapter only — no other provider's
+   * plan-change endpoint accepts a key at all (see the `idempotency` module docblock). Stripe
+   * otherwise derives one from the subscription and the target plan/quantity, which is stable across
+   * retries of the same intent; pass your own only to re-issue a target that was already applied and
+   * then changed away from, which a stable key would replay rather than prorate again.
+   */
+  readonly idempotencyKey?: string;
+  readonly priceId?: string;
+  readonly quantity?: number;
+}
+/**
+ * Normalized webhook outcome — the *core state transition* a provider event implies.
+ * @experimental
+ */
+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.
+ * @experimental
+ */
+type RefundAmountKind = "absolute" | "delta";
+/**
+ * `WebhookAction` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+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;
+  /**
+   * EVERY price/product id the subscription bills, when the adapter could establish the whole set.
+   * `sync.ts` applies it as a WHOLESALE replacement, so it must be complete or absent — never a
+   * subset, which would silently drop prices the stored row already had.
+   *
+   * `undefined` leaves the stored set standing (see {@link Subscription.priceIds}). That is the
+   * single-price providers' case, and the fail-closed answer for a provider whose embedded item
+   * list is paginated and whose event carries only the first page.
+   */
+  readonly priceIds?: ReadonlyArray<string>;
+  readonly provider: ProviderId;
+  readonly quantity?: number;
+  /** Raw provider event, retained for the events log / debugging. */
+  readonly raw?: unknown;
+  readonly referenceId?: string;
+  /**
+   * Provider id of the refund this event reports (refund actions only). Carries the per-refund
+   * identity the sync layer matches against the marker `refundPayment` left behind, so a second
+   * facade refund of the same amount is not mistaken for the first one's confirmation.
+   */
+  readonly refundId?: string;
+  readonly sessionId?: string;
+  readonly subscriptionId?: string;
+  readonly type: WebhookActionType;
+}
+/**
+ * Result of applying a webhook action to the store.
+ * @experimental
+ */
+interface ApplyResult {
+  readonly applied: boolean;
+  readonly reason?: "duplicate" | "illegal_transition" | "invalid_refund_amount" | "ok" | "orphaned" | "unhandled";
+}
+/**
+ * A read-only header bag; the platform `Headers` object satisfies it.
+ * @experimental
+ */
+interface WebhookHeaders {
+  get: (name: string) => null | string;
+}
+/**
+ * `WebhookInput` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+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.
+ * @experimental
+ */
+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>;
+  /**
+   * Ask the provider whether a reference may consume `quantity` units of a feature (or holds active
+   * access to a product) right now — for providers that own entitlement truth themselves (e.g.
+   * Autumn computes balances, credits, and limits from its plan config). Optional: when absent, the
+   * facade's `check` evaluates locally from the synced store + the app's `entitlements` config. When
+   * present, the facade delegates `check` to it, so `entitlements` need not be configured.
+   */
+  checkEntitlement?: (input: CheckInput) => Promise<CheckResult>;
+  createCheckout: (input: CheckoutInput) => Promise<CheckoutResult>;
+  createPortalSession: (input: PortalInput) => Promise<{
+    url: string;
+  }>;
+  /**
+   * Resolve every feature allowance for a reference straight from the provider — the optional
+   * companion to `checkEntitlement` that powers `listBalances`. Present only on providers that
+   * own entitlement truth; when absent, the facade evaluates balances locally from the store + the
+   * app's `entitlements` config.
+   */
+  getBalances?: (referenceId: string) => Promise<FeatureBalance[]>;
+  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>;
+  /** Issue the refund and report the provider's id for it (see {@link RefundResult.refundId}). */
+  refundPayment: (input: RefundInput) => Promise<RefundResult>;
+  /**
+   * 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>;
+  /**
+   * Clear a pending cancellation. `options.idempotencyKey` overrides the adapter's own stable key
+   * and is honoured by the Stripe adapter only — no other provider's endpoint accepts one.
+   */
+  resumeSubscription: (subscriptionId: string, options?: {
+    idempotencyKey?: string;
+  }) => Promise<Subscription>;
+  updateSubscription: (subscriptionId: string, patch: SubscriptionPatch) => Promise<Subscription>;
+}
+/**
+ * Registry of adapters keyed by provider id — supports dual-register during provider migration.
+ * @experimental
+ */
+interface AdapterRegistry {
+  all: () => PaymentAdapter[];
+  get: (provider: ProviderId) => PaymentAdapter;
+  has: (provider: ProviderId) => boolean;
+}
+/**
+ * `createAdapterRegistry` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+ * @experimental
+ */
+declare const createAdapterRegistry: (adapters: ReadonlyArray<PaymentAdapter>) => AdapterRegistry;
+export { ApplyResult as A, Customer as C, FeatureBalance as F, Money as M, PaymentAdapter as P, RefundInput as R, Subscription as S, TrackInput as T, UsageEvent as U, WebhookActionType as W, ProviderId as a, PaymentSession as b, AttachInput as c, CheckoutResult as d, CancelSubscriptionOptions as e, CaptureInput as f, CheckInput as g, CheckResult as h, CheckoutInput as i, TrackResult as j, CurrencyCode as k, PaymentState as l, SubscriptionState as m, WebhookAction as n, AdapterRegistry as o, CustomerRef as p, PortalInput as q, ProviderCapabilities as r, RefundAmountKind as s, RefundResult as t, ReportUsageInput as u, SubscriptionPatch as v, WebhookHeaders as w, WebhookInput as x, createAdapterRegistry as y };