@lunora/payment 1.0.0-alpha.24 → 1.0.0-alpha.25

package/README.md

@@ -10,6 +10,8 @@
 
 <!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
+> **Experimental** — this package is outside the Lunora 1.0 stability promise: its API may change in any release, without a major version bump.
+
 <br />
 
 <div align="center">

package/dist/index.d.mts

@@ -1,7 +1,11 @@
-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 CheckInput, g as CheckResult, h as CheckoutInput, F as FeatureBalance, T as TrackInput, i as TrackResult, j as CurrencyCode, M as Money, k as PaymentState, l as SubscriptionState, m as WebhookAction } from "./packem_shared/adapter.d-SULGy2QF.mjs";
-export { type n as AdapterRegistry, type o as CaptureInput, type p as CustomerRef, type q as PortalInput, type r as ProviderCapabilities, type R as RefundAmountKind, type s as RefundInput, type t as ReportUsageInput, type u as SubscriptionPatch, type v as WebhookHeaders, type w as WebhookInput, x as createAdapterRegistry } from "./packem_shared/adapter.d-SULGy2QF.mjs";
+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 CheckInput, g as CheckResult, h as CheckoutInput, F as FeatureBalance, T as TrackInput, i as TrackResult, j as CurrencyCode, M as Money, k as PaymentState, l as SubscriptionState, m as WebhookAction } from "./packem_shared/adapter.d-BOheUepr.mjs";
+export { type n as AdapterRegistry, type o as CaptureInput, type p as CustomerRef, type q as PortalInput, type r as ProviderCapabilities, type R as RefundAmountKind, type s as RefundInput, type t as ReportUsageInput, type u as SubscriptionPatch, type v as WebhookHeaders, type w as WebhookInput, x as createAdapterRegistry } from "./packem_shared/adapter.d-BOheUepr.mjs";
 import { LunoraError } from '@lunora/errors';
 import { TableDefinition } from '@lunora/server';
+/**
+* `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>;
@@ -33,7 +37,10 @@ interface PaymentStore {
   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;
@@ -53,6 +60,10 @@ declare class MemoryPaymentStore implements PaymentStore {
   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>;
@@ -61,10 +72,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`. */
@@ -78,16 +97,33 @@ interface Entitlements {
 * 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;
@@ -132,9 +168,20 @@ 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. */
+/**
+* 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;
   /**
@@ -148,6 +195,10 @@ 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;
   /**
@@ -180,12 +231,22 @@ interface LunoraPayment {
   */
   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. */
+/**
+* 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>;
@@ -193,8 +254,15 @@ interface PaymentDatabase {
   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).
+* @experimental
+*/
 interface LunoraDatabaseLike {
   delete: (id: string) => Promise<void>;
   findFirst: (table: string, args?: {
@@ -208,13 +276,20 @@ interface LunoraDatabaseLike {
   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. */
@@ -224,41 +299,102 @@ 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;
+/**
+* `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" | "WEBHOOK_SIGNATURE_INVALID" | "WEBHOOK_TIMESTAMP_INVALID";
-/** Typed error for all `@lunora/payment` failures. A `LunoraError` subclass; `status` maps onto an HTTP response. */
+/**
+* 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;
   constructor(code: PaymentErrorCode, message: string);
 }
-/** 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).
+* @experimental
+*/
 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.
+* @experimental
+*/
 declare const money: (minorUnits: bigint | number, currency: CurrencyCode) => Money;
+/**
+* `zeroMoney` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+* @experimental
+*/
 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.
+* @experimental
+*/
 declare const formatMoney: (value: Money, locale?: string) => string;
+/**
+* `addMoney` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+* @experimental
+*/
 declare const addMoney: (a: Money, b: Money) => Money;
+/**
+* `subtractMoney` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+* @experimental
+*/
 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.
+* @experimental
+*/
 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.
+* @experimental
 */
 declare const allocateMoney: (amount: Money, ratios: ReadonlyArray<bigint>) => Money[];
+/**
+* `isZeroMoney` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+* @experimental
+*/
 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).
+* @experimental
+*/
 interface MoneyJSON {
   readonly currency: CurrencyCode;
   readonly minorUnits: string;
 }
+/**
+* `toMoneyJSON` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+* @experimental
+*/
 declare const toMoneyJSON: (m: Money) => MoneyJSON;
+/**
+* `fromMoneyJSON` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+* @experimental
+*/
 declare const fromMoneyJSON: (json: MoneyJSON) => Money;
+/**
+* `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. */
@@ -267,6 +403,10 @@ interface ReconcileInput {
   readonly store: PaymentStore;
   readonly subscriptionIds?: ReadonlyArray<string>;
 }
+/**
+* `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;
@@ -275,23 +415,70 @@ interface ReconcileResult {
   readonly updatedPayments: number;
   readonly updatedSubscriptions: 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>;
+/**
+* `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.
+* @experimental
+*/
 declare const constantTimeEqual: (a: string, b: string) => boolean;
+/**
+* `hmacSha256Hex` is part of the experimental `@lunora/payment` API and may change without a major version bump.
+* @experimental
+*/
 declare const hmacSha256Hex: (secret: string, payload: string) => Promise<string>;
 interface VerifyStandardWebhookInput {
   /** Injectable clock (ms since epoch) for tests. */
@@ -313,6 +500,7 @@ interface VerifyStandardWebhookInput {
 * 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.
+* @experimental
 */
 declare const verifyStandardWebhook: (input: VerifyStandardWebhookInput) => Promise<void>;
 interface VerifyCreemSignatureInput {
@@ -327,6 +515,7 @@ interface VerifyCreemSignatureInput {
 * 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.
+* @experimental
 */
 declare const verifyCreemSignature: (input: VerifyCreemSignatureInput) => Promise<void>;
 export { type ApplyResult, type AttachInput, type AuthorizeReference, type CancelSubscriptionOptions, 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 PaymentRow, type PaymentSession, type PaymentState, type PaymentStore, type PaymentsFromContextOptions, type PlanDefinition, type ProviderId, type ReconcileInput, type ReconcileResult, SUBSCRIPTION_TERMINAL_STATES, type Subscription, type SubscriptionAction, type SubscriptionState, type TrackInput, type TrackResult, type UsageEvent, type WebhookAction, type WebhookActionType, 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, zeroMoney };