@lunora/payment

@lunora/payment is one provider-agnostic API over Stripe, Polar, Autumn, Dodo Payments, and Creem. Webhook events are verified, normalized, and applied through an explicit payment/subscription state machine that makes duplicate and out-of-order deliveries safe by construction, and synced into a durable store that rides the request's ctx.db. Switching providers is a configuration change: the provider is a stateless translator; the store owns all state.

Outbound calls carry idempotency keys (no double-charge), and every mutation is authorized per-caller. Each adapter takes the provider's SDK client by injection. The provider SDKs are optional peer dependencies, so you install (and bundle) only the providers you actually use.

pnpm add @lunora/payment stripe

Configure

ctx.payments is wired by codegen onto ActionCtx whenever a lunora/ source imports @lunora/payment or reads ctx.payments. The adapter, which carries provider secrets, comes from a config.payment(env) thunk you pass to createShardDO(). The store is built per request from ctx.db, and the default authorizer ties referenceId to ctx.auth.userId.

import { createStripeAdapter } from "@lunora/payment/stripe";
import { createShardDO } from "./_generated/shard";
import Stripe from "stripe";

export const ShardDO = createShardDO({
    payment: (env) => ({
        adapter: createStripeAdapter({
            // The adapter types its client as the real `Stripe` instance (an optional peer dependency),
            // so it's passed straight through — the fetch HTTP client is required on workerd.
            client: new Stripe(env.STRIPE_SECRET_KEY, { httpClient: Stripe.createFetchHttpClient() }),
            webhookSecret: env.STRIPE_WEBHOOK_SECRET,
        }),
        // Override the default "caller owns the referenceId" rule for org/workspace keys.
        // authorize: (referenceId) => referenceId === ctx.auth.orgId,
        entitlements: {
            plans: {
                pro: { features: ["export"], limits: { api_calls: 1000 }, priceIds: ["price_123"] },
            },
        },
        observability: (event) => console.log("[payment]", event.type, event),
    }),
});

The thunk returns PaymentsFromContextOptions:

Provider adapters

Every adapter takes its client by injection and verifies inbound webhooks. Each lives at its own subpath so importing one never loads another provider's SDK:

import { createAutumnAdapter } from "@lunora/payment/autumn";
import { createCreemAdapter } from "@lunora/payment/creem";
import { createDodoPaymentsAdapter } from "@lunora/payment/dodopayments";
import { createPolarAdapter } from "@lunora/payment/polar";
import { createStripeAdapter } from "@lunora/payment/stripe";

const stripe = createStripeAdapter({ client, webhookSecret, webhookToleranceSeconds: 300 });
const polar = createPolarAdapter({ client, webhookSecret });
const autumn = createAutumnAdapter({ client, webhookSecret });
const dodo = createDodoPaymentsAdapter({ client, webhookSecret });
const creem = createCreemAdapter({ client, webhookSecret });

Stripe is a PSP (manual authorize/capture available). Polar, Dodo Payments, and Creem are Merchants-of-Record: merchantOfRecord is true and they own tax/invoices, so manual capture isn't part of their flow. Stripe webhooks use Stripe's signature scheme; Polar, Autumn, and Dodo Payments use Standard Webhooks (webhook-id / webhook-timestamp / webhook-signature); Creem uses a single creem-signature HMAC-SHA256 header.

Creem

Creem is a Merchant-of-Record for software with an EU-friendly global footprint. Unlike a raw PSP, it is product-based (real product ids), so it slots into the priceId interface directly like Polar/Dodo: hosted checkout sessions, first-class subscriptions (cancel at period end, pause/resume, plan upgrades), and a genuine hosted billing portal via customers.generateBillingLinks (portal is true). Refunds are issued from the Creem dashboard (no SDK endpoint), so refundPayment throws. Webhooks are verified with the creem-signature HMAC-SHA256 header.

import type { CreemClientLike } from "@lunora/payment/creem";
import { createCreemAdapter } from "@lunora/payment/creem";
import { Creem } from "creem";

const creem = createCreemAdapter({
    client: new Creem() as unknown as CreemClientLike,
    webhookSecret: env.CREEM_WEBHOOK_SECRET,
});

Autumn

Autumn is an entitlement-first billing layer that runs on your own Stripe account, so it is not a Merchant-of-Record, but, like Polar, it abstracts the money movement, so manual authorize/capture/refund throw. It keys a subscription on the (customerId, planId) pair, which the adapter encodes as the composite id "<customerId>::<planId>".

Autumn owns entitlement truth: balances, credits, limits, and rollovers are computed on its side from your plan config. The adapter implements the optional checkEntitlement / getBalances hooks, so the facade delegates check and listBalances straight to Autumn's live API, and you do not need to configure entitlements for an Autumn app. Because of that, the authoritative sync path is live queries + reconcile, not webhook fan-in (the autumn-js SDK models no outbound webhook stream). Autumn's dashboard can still emit Standard Webhooks (Svix) events, so parseWebhook is provided as a best-effort convenience; reconcile remains the reliable path for subscription drift.

Construct the client from autumn-js and inject it (the cast keeps the package free of a hard autumn-js dependency):

import type { AutumnClientLike } from "@lunora/payment/autumn";
import { createAutumnAdapter } from "@lunora/payment/autumn";
import { Autumn } from "autumn-js";

const autumn = createAutumnAdapter({
    client: new Autumn({ secretKey: env.AUTUMN_SECRET_KEY }) as unknown as AutumnClientLike,
    webhookSecret: env.AUTUMN_WEBHOOK_SECRET,
});

A companion facade, createAutumnFeatures, holds the Autumn-native concepts that have no cross-provider equivalent: entities (per-seat/per-workspace sub-customers), referrals, usage-events analytics, the plan catalog, and a native checkout (prepaid feature quantities, entity scoping, reward codes, opting out of a plan's trial). It is kept separate so the provider-agnostic surface stays generic. Share the same injected client between the two. (Credit systems need no extra method: Autumn models them as features, so their balances flow through check / listBalances like any other.)

import type { AutumnFeaturesClientLike } from "@lunora/payment/autumn-features";
import { createAutumnFeatures } from "@lunora/payment/autumn-features";

const autumnFeatures = createAutumnFeatures({ client: client as unknown as AutumnFeaturesClientLike });

await autumnFeatures.entities.create(userId, { featureId: "seats", id: "workspace_a", name: "Workspace A" });
const usage = await autumnFeatures.events.aggregate(userId, { featureId: "api_calls", range: "30d" });
const { url } = await autumnFeatures.checkout(userId, { planId: "pro" });

Dodo Payments

Dodo Payments is a Merchant-of-Record: like Polar, it is the legal seller of record and calculates, collects, and remits tax across 190+ jurisdictions, and owns chargebacks and disputes. So merchantOfRecord is true and manual authorize/capture throw, but refunds are first-class (refunds.create). The flow is checkout-session → subscription/payment, synced from Standard Webhooks (the dodopayments SDK exposes the full, verified event catalog: payment.*, subscription.*, refund.*, …). It supports usage-based billing, so reportUsage ingests Dodo usage-events.

Construct the client from dodopayments and inject it (the cast keeps the package free of a hard dodopayments dependency):

import type { DodoPaymentsClientLike } from "@lunora/payment/dodopayments";
import { createDodoPaymentsAdapter } from "@lunora/payment/dodopayments";
import DodoPayments from "dodopayments";

const dodo = createDodoPaymentsAdapter({
    client: new DodoPayments({ bearerToken: env.DODO_PAYMENTS_API_KEY }) as unknown as DodoPaymentsClientLike,
    webhookSecret: env.DODO_PAYMENTS_WEBHOOK_KEY,
});

The ctx.payments API

Call the facade from an action. Every method authorizes the caller against the referenceId first.

import { action, query, v } from "./_generated/server";

export const checkout = action.input({ priceId: v.string() }).action(async ({ ctx, args: { priceId } }): Promise<{ url: string }> => {
    const { url } = await ctx.payments.createCheckout({
        referenceId: ctx.auth.userId,
        priceId,
        mode: "subscription",
        successUrl: "https://app.test/done",
        cancelUrl: "https://app.test/cancel",
    });

    return { url };
});

createCheckout reuses a reference's stored provider customer, minting a new one only on first checkout, and attaches an outbound idempotency key automatically (override via input.idempotencyKey).

Entitlements: check and track

Entitlements are derived from already-synced subscription state, which is cheap and in-Worker and needs no external billing service. A plan is granted when an active (or trialing) subscription holds one of its priceIds. When several active plans cap the same limit, the most-generous value wins.

• A product check (priceId) is allowed when the reference holds an active subscription on that price.
• A boolean feature check (featureId, no numeric limit) returns unlimited: true when granted.
• A metered feature check (featureId with a plan limit) subtracts usage tracked this period and returns { allowed, balance, limit, used }.

export const recordApiCall = action.action(async ({ ctx }): Promise<{ recorded: boolean }> => {
    // `mode: "add"` (default) increments; `"set"` reconciles the period total.
    // Both are a single append — a `"set"` records the absolute target as a marker
    // the period fold resets to, so concurrent or replayed `"set"` calls resolve
    // last-writer-wins instead of double-applying. Neither mode needs a lock.
    const result = await ctx.payments.track({ referenceId: ctx.auth.userId, featureId: "api_calls" });

    return { recorded: result.recorded };
});

export const apiCallsRemaining = action.action(async ({ ctx }): Promise<{ allowed: boolean; balance?: number }> => {
    const result = await ctx.payments.check({ referenceId: ctx.auth.userId, featureId: "api_calls" });

    return { allowed: result.allowed, balance: result.balance };
});

track writes a durable, append-only usage ledger (exactly-once by idempotency key) that check sums over the current billing period. When the provider advertises usage metering, the event is also forwarded to its metering API. That forward is best-effort: a reporting failure is observed, never thrown, and the local ledger check reads is always updated.

Webhooks

Signature verification needs the raw request body, so the webhook endpoint runs at the Worker edge via httpAction (no ctx.db). It forwards the raw body and signature into the shard via ctx.runAction, where ctx.payments and its store exist:

// lunora/http.ts
import { httpAction, httpRouter } from "lunorash/server";
import { processWebhook } from "./billing";

export const app = httpRouter();

app.post(
    "/payment/webhook",
    httpAction(async (ctx, request) => {
        const body = await request.text();
        const signature = request.headers.get("stripe-signature") ?? "";

        return Response.json(await ctx.runAction(processWebhook, { body, signature }));
    }),
);

// lunora/billing.ts
import { internalAction, v } from "./_generated/server";

export const processWebhook = internalAction
    .input({ body: v.string(), signature: v.string() })
    .action(async ({ ctx, args: { body, signature } }): Promise<{ applied: boolean; status: number }> => {
        const request = new Request("https://internal/payment/webhook", {
            body,
            headers: { "stripe-signature": signature },
            method: "POST",
        });
        const response = await ctx.payments.handleWebhook(request);
        const result = (await response.json()) as { applied?: boolean };

        return { applied: result.applied ?? false, status: response.status };
    });

handleWebhook verifies the signature, normalizes the event into a WebhookAction (e.g. subscription.active, payment.captured, payment.refunded), and applies it through the state machine. Once verified it always returns 200 so the provider stops retrying; a duplicate or no-op event is acknowledged, not re-applied. The inbound provider event id keys an append-only events log for idempotency and audit.

Data it stores

Codegen discovers tables by parsing your lunora/schema.ts AST, so it cannot resolve a cross-package defineSchema({ ...paymentTables }) spread. Declare the tables you use inline in your own lunora/schema.ts, mirroring the columns in @lunora/payment's exported paymentTables (the canonical column reference the store reads/writes). Declaring them locally also lets you chain .global() on read-heavy tables (e.g. subscriptions) for cross-region reads from D1.

paymentTables covers: products, prices, customers, subscriptions, checkouts, paymentSessions, payments, captures, refunds, invoices, events (the append-only webhook log), and usageEvents (the metered-usage ledger). Money is stored as (amountMinor: bigint, currency: string) columns; every row carries a provider discriminator so multiple providers can coexist during a migration. Captures and refunds are append-only records linked to a payment, not booleans.

Backfilling money columns written before the storage fix

Rows written between 2026-08-03 and the v.bigint() storage fix stored their money columns in a form SQL could not read. Such a row reads back correctly (ctx.db.get returns the right bigint) but is invisible to comparison:

// A settled session whose amountMinor was written in the affected window.
await ctx.db
    .query("paymentSessions")
    .filter((q) => q.gte("amountMinor", 1000n))
    .collect();
// ^ silently omits it. `ORDER BY amountMinor` mis-sorts it, and `sum` counts it as 0.

Any write heals the row, so the exposure is the rows nobody writes again, which for paymentSessions is precisely the settled sessions, the ones most likely to be queried by amount and least likely to be touched.

A reserved data migration re-projects them, one per affected table. Preview it first:

lunora migrate up __lunora_reproject__paymentSessions --dry-run
lunora migrate up __lunora_reproject__paymentSessions
lunora migrate status __lunora_reproject__paymentSessions

It runs through the normal writer path, so triggers fire and live subscribers are notified; it is resumable and safe to interrupt, and rows already in the current form are skipped rather than rewritten. Repeat for any other shard-local table of yours declaring a v.bigint() or v.bytes() column; the id is always __lunora_reproject__<table>.

.global() tables were never affected: their rows live in the D1/Hyperdrive store, which has always had a per-column codec. Running the migration against one returns MIGRATION_NOT_FOUND, which is the expected answer, not a problem to work around.

Confirming it is complete: a second --dry-run reporting 0 rows to change means nothing is left in the old form. Apps that only ever ran on the fixed version have nothing to do and the dry run reports 0 on the first try.

Studio

The Studio Payments panel (under Operations) shows synced customers, subscriptions, and webhook events for the app. The panel only appears once codegen detects payments in use.