@ingram-tech/nk-billing 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# @ingram-tech/nk-billing
+
+The Ingram billing foundation: composable **Stripe primitives** every site was
+re-implementing, plus an optional **Postgres credit ledger** for usage metering.
+One account-agnostic toolkit, not a billing framework that owns your flows —
+you keep your routes, your schema, and your pricing; nk-billing removes the
+boilerplate in between.
+
+> Part of [nextkit](../../README.md). Stateless Stripe helpers are the main
+> entry; the database-backed credit ledger lives behind the `/credits` subpath so
+> a subscription-only or wallet-only site never imports a DB concept.
+
+## Install
+
+```bash
+bun add @ingram-tech/nk-billing stripe
+```
+
+`stripe` is a direct dependency; bring your own Postgres (`pg` / nk-db) only if
+you use the credit ledger.
+
+## Env contract
+
+Single-mode (most sites): `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`.
+Dual-mode (a merchant-of-record running test beside live, e.g. cloud):
+`STRIPE_SECRET_KEY_{TEST,LIVE}`, `STRIPE_WEBHOOK_SECRET_{TEST,LIVE}`.
+Optional `STRIPE_API_VERSION` to pin ahead of an SDK bump.
+
+Nothing hardcodes a price ID — prices resolve at runtime by stable Stripe
+`lookup_key`, so the same code path works in test and live.
+
+## The three billing models
+
+Pick the one that matches what you sell — they compose:
+
+- **Subscriptions** — `createCheckoutSession({ mode: "subscription" })`,
+  `createPortalSession`, `summarizeSubscription`, `fetchSubscriptionSummary`
+  (the webhook-lag self-heal read).
+- **Stripe-side wallet** (money) — `@ingram-tech/nk-billing` `readBalance` /
+  `debitBalance`: the balance lives in Stripe, no local table.
+- **In-app credits** (abstract units) — `@ingram-tech/nk-billing/credits`:
+  atomic `spendCredits` / `requireCredits`, `grantCredits`,
+  `recordSubscriptionStatus`, all idempotent; ships its own migration.
+
+## Quick start — subscription checkout
+
+```ts
+import { createCheckoutSession, resolveCurrencyFromHeaders } from "@ingram-tech/nk-billing";
+import { headers } from "next/headers";
+
+const url = await createCheckoutSession({
+	customer: { metadataKey: "acme_org_id", id: orgId },
+	customerDetails: { name: org.name, email: user.email },
+	lookupKey: "acme_pro_monthly",
+	mode: "subscription",
+	currency: resolveCurrencyFromHeaders(await headers()),
+	successUrl: `${base}/billing?ok=1`,
+	cancelUrl: `${base}/billing`,
+});
+redirect(url);
+```
+
+## Quick start — webhook (with credit-ledger dedup)
+
+```ts
+import { readStripeWebhook } from "@ingram-tech/nk-billing";
+import { grantCredits, recordSubscriptionStatus } from "@ingram-tech/nk-billing/credits";
+
+export async function POST(request: Request) {
+	const res = await readStripeWebhook(request, process.env.STRIPE_WEBHOOK_SECRET ?? "");
+	if (!res.ok) return new Response(res.message, { status: res.status });
+	// dedupe + apply inside your tenant transaction; retries are no-ops.
+	await withTenant(orgId, (db) => recordSubscriptionStatus(db, { ... }));
+	return Response.json({ received: true });
+}
+```
+
+## Credit ledger & tenancy
+
+The ledger takes the DB connection by **injection** and leaves isolation to you —
+wrap each call in `withTenant(orgId, db => spendCredits(db, …))` under RLS, or a
+plain transaction under app-layer filtering. It owns two tables; apply
+`migrations/0001_billing.sql` (a Drizzle-composable fragment) and add your own
+RLS policy if your stack uses one. See [`src/credits.ts`](./src/credits.ts).
+
+## Full surface
+
+See the [nk-billing guide](../../../nk-billing.md) for the exhaustive,
+per-export reference and migration recipes for each consuming app.
+
+## License
+
+[MIT](../../LICENSE) © Ingram Technologies

package/dist/balance.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Customer-balance wallet — Stripe's own credit ledger, for pay-as-you-go sites
+ * (domains.ingram.tech). Distinct from the in-app credit ledger in
+ * `@ingram-tech/nk-billing/credits`: this stores the balance *in Stripe* as a
+ * signed integer (negative = credit available to the customer), so there is no
+ * local table to keep in sync. Pick this when the unit you sell is money;
+ * pick the credit ledger when the unit is abstract "credits".
+ *
+ * We normalise Stripe's sign convention to "amount available" (positive cents)
+ * so callers never have to remember that a credit is negative.
+ */
+import type Stripe from "stripe";
+export interface Balance {
+    /** Credit available to the customer, in minor units (cents). Positive. */
+    amount: number;
+    currency: string;
+}
+/** Read a customer's available wallet balance (Stripe's negative credit balance,
+ *  sign-flipped to positive). A deleted customer reads as zero. */
+export declare function readBalance(customerId: string, stripe?: Stripe): Promise<Balance>;
+/** Debit the wallet by `amountCents`. Stripe rejects a debit that would push the
+ *  balance positive (the customer would owe us), giving a hard over-spend
+ *  guarantee with no pre-flight check. Idempotency-keyed by `idempotencyTag` so
+ *  retries can't double-debit — tie the tag to the action that triggered the
+ *  spend (e.g. the operation's own idempotency key). */
+export declare function debitBalance(opts: {
+    customerId: string;
+    amountCents: number;
+    currency: string;
+    description: string;
+    idempotencyTag: string;
+    metadata?: Record<string, string>;
+}, stripe?: Stripe): Promise<void>;
+//# sourceMappingURL=balance.d.ts.map

package/dist/balance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance.d.ts","sourceRoot":"","sources":["../src/balance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC,MAAM,WAAW,OAAO;IACvB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED;mEACmE;AACnE,wBAAsB,WAAW,CAChC,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAAoB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAIlB;AAED;;;;wDAIwD;AACxD,wBAAsB,YAAY,CACjC,IAAI,EAAE;IACL,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,EACD,MAAM,GAAE,MAAoB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAWf"}

package/dist/balance.js

@@ -0,0 +1,34 @@
+/**
+ * Customer-balance wallet — Stripe's own credit ledger, for pay-as-you-go sites
+ * (domains.ingram.tech). Distinct from the in-app credit ledger in
+ * `@ingram-tech/nk-billing/credits`: this stores the balance *in Stripe* as a
+ * signed integer (negative = credit available to the customer), so there is no
+ * local table to keep in sync. Pick this when the unit you sell is money;
+ * pick the credit ledger when the unit is abstract "credits".
+ *
+ * We normalise Stripe's sign convention to "amount available" (positive cents)
+ * so callers never have to remember that a credit is negative.
+ */
+import { getStripe } from "./client.js";
+/** Read a customer's available wallet balance (Stripe's negative credit balance,
+ *  sign-flipped to positive). A deleted customer reads as zero. */
+export async function readBalance(customerId, stripe = getStripe()) {
+    const customer = await stripe.customers.retrieve(customerId);
+    if (customer.deleted)
+        return { amount: 0, currency: "eur" };
+    return { amount: -customer.balance, currency: customer.currency ?? "eur" };
+}
+/** Debit the wallet by `amountCents`. Stripe rejects a debit that would push the
+ *  balance positive (the customer would owe us), giving a hard over-spend
+ *  guarantee with no pre-flight check. Idempotency-keyed by `idempotencyTag` so
+ *  retries can't double-debit — tie the tag to the action that triggered the
+ *  spend (e.g. the operation's own idempotency key). */
+export async function debitBalance(opts, stripe = getStripe()) {
+    await stripe.customers.createBalanceTransaction(opts.customerId, {
+        amount: opts.amountCents,
+        currency: opts.currency,
+        description: opts.description,
+        metadata: opts.metadata ?? {},
+    }, { idempotencyKey: `bal_debit_${opts.idempotencyTag}` });
+}
+//# sourceMappingURL=balance.js.map

package/dist/balance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance.js","sourceRoot":"","sources":["../src/balance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAQxC;mEACmE;AACnE,MAAM,CAAC,KAAK,UAAU,WAAW,CAChC,UAAkB,EAClB,SAAiB,SAAS,EAAE;IAE5B,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC7D,IAAI,QAAQ,CAAC,OAAO;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC5D,OAAO,EAAE,MAAM,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,IAAI,KAAK,EAAE,CAAC;AAC5E,CAAC;AAED;;;;wDAIwD;AACxD,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,IAOC,EACD,SAAiB,SAAS,EAAE;IAE5B,MAAM,MAAM,CAAC,SAAS,CAAC,wBAAwB,CAC9C,IAAI,CAAC,UAAU,EACf;QACC,MAAM,EAAE,IAAI,CAAC,WAAW;QACxB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,EAAE;KAC7B,EACD,EAAE,cAAc,EAAE,aAAa,IAAI,CAAC,cAAc,EAAE,EAAE,CACtD,CAAC;AACH,CAAC"}

package/dist/checkout.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Checkout & Customer Portal sessions — the two hosted Stripe flows every
+ * self-serve site uses. {@link createCheckoutSession} covers both a recurring
+ * subscription (`mode: "subscription"`) and a one-time purchase such as a credit
+ * pack (`mode: "payment"`); {@link createPortalSession} opens the management
+ * portal.
+ */
+import type Stripe from "stripe";
+import { type CustomerDetails, type CustomerRef } from "./customers.js";
+export interface CheckoutOptions {
+    /** Identifies (and, if needed, creates) the Stripe customer. */
+    customer: CustomerRef;
+    /** Details used only when the customer is created on this call. */
+    customerDetails?: CustomerDetails;
+    /** Stable price lookup_key for the line item. */
+    lookupKey: string;
+    /** "subscription" for a recurring plan, "payment" for a one-time purchase. */
+    mode: "subscription" | "payment";
+    successUrl: string;
+    cancelUrl: string;
+    /** Line-item quantity (e.g. number of credit packs). Default 1. */
+    quantity?: number;
+    /** Presentment currency; applied only when the price actually offers it,
+     *  otherwise the price's base currency is used. */
+    currency?: string;
+    /** Whether to let customers enter promo codes. Default true. */
+    allowPromotionCodes?: boolean;
+    /** Collect a tax id (e.g. EU VAT) at checkout. The customer must already have
+     *  a billing address — see {@link customerHasBillingAddress}. Default false. */
+    collectTaxId?: boolean;
+    /** Stripe Checkout locale (e.g. "fr", "nl", "auto"). Default "auto". */
+    locale?: Stripe.Checkout.SessionCreateParams["locale"];
+    /** Extra metadata to stamp on the session (and, in subscription mode, the
+     *  subscription) — merged with the customer ref tag. */
+    metadata?: Record<string, string>;
+}
+/** Create a Checkout Session and return its URL. The session is created in the
+ *  caller's currency when the price supports it (Stripe picks the
+ *  currency_options amount), else in the price's base currency. The customer ref
+ *  tag is stamped on the session and — in subscription mode — on the subscription
+ *  too, so `customer.subscription.*` webhooks carry it without a round-trip. */
+export declare function createCheckoutSession(opts: CheckoutOptions, stripe?: Stripe): Promise<string>;
+/** Open a Customer Portal session for managing/cancelling a subscription. */
+export declare function createPortalSession(opts: {
+    customer: CustomerRef;
+    customerDetails?: CustomerDetails;
+    returnUrl: string;
+}, stripe?: Stripe): Promise<string>;
+//# sourceMappingURL=checkout.d.ts.map

package/dist/checkout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC,OAAO,EACN,KAAK,eAAe,EACpB,KAAK,WAAW,EAEhB,MAAM,gBAAgB,CAAC;AAGxB,MAAM,WAAW,eAAe;IAC/B,gEAAgE;IAChE,QAAQ,EAAE,WAAW,CAAC;IACtB,mEAAmE;IACnE,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,IAAI,EAAE,cAAc,GAAG,SAAS,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;uDACmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;oFACgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACvD;4DACwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;gFAIgF;AAChF,wBAAsB,qBAAqB,CAC1C,IAAI,EAAE,eAAe,EACrB,MAAM,GAAE,MAAoB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAqCjB;AAED,6EAA6E;AAC7E,wBAAsB,mBAAmB,CACxC,IAAI,EAAE;IACL,QAAQ,EAAE,WAAW,CAAC;IACtB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;CAClB,EACD,MAAM,GAAE,MAAoB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAWjB"}

package/dist/checkout.js

@@ -0,0 +1,59 @@
+/**
+ * Checkout & Customer Portal sessions — the two hosted Stripe flows every
+ * self-serve site uses. {@link createCheckoutSession} covers both a recurring
+ * subscription (`mode: "subscription"`) and a one-time purchase such as a credit
+ * pack (`mode: "payment"`); {@link createPortalSession} opens the management
+ * portal.
+ */
+import { getStripe } from "./client.js";
+import { findOrCreateCustomer, } from "./customers.js";
+import { priceByLookupKey, supportedCurrencies } from "./prices.js";
+/** Create a Checkout Session and return its URL. The session is created in the
+ *  caller's currency when the price supports it (Stripe picks the
+ *  currency_options amount), else in the price's base currency. The customer ref
+ *  tag is stamped on the session and — in subscription mode — on the subscription
+ *  too, so `customer.subscription.*` webhooks carry it without a round-trip. */
+export async function createCheckoutSession(opts, stripe = getStripe()) {
+    const [customer, price] = await Promise.all([
+        findOrCreateCustomer(opts.customer, opts.customerDetails, stripe),
+        priceByLookupKey(opts.lookupKey, stripe),
+    ]);
+    const currency = opts.currency && supportedCurrencies(price).has(opts.currency)
+        ? opts.currency
+        : undefined;
+    const metadata = {
+        [opts.customer.metadataKey]: opts.customer.id,
+        ...opts.metadata,
+    };
+    const session = await stripe.checkout.sessions.create({
+        mode: opts.mode,
+        customer: customer.id,
+        line_items: [{ price: price.id, quantity: opts.quantity ?? 1 }],
+        allow_promotion_codes: opts.allowPromotionCodes ?? true,
+        locale: opts.locale ?? "auto",
+        ...(currency ? { currency } : {}),
+        ...(opts.collectTaxId
+            ? {
+                tax_id_collection: { enabled: true },
+                customer_update: { name: "auto" },
+            }
+            : {}),
+        success_url: opts.successUrl,
+        cancel_url: opts.cancelUrl,
+        metadata,
+        ...(opts.mode === "subscription" ? { subscription_data: { metadata } } : {}),
+    });
+    if (!session.url)
+        throw new Error("Stripe did not return a checkout URL");
+    return session.url;
+}
+/** Open a Customer Portal session for managing/cancelling a subscription. */
+export async function createPortalSession(opts, stripe = getStripe()) {
+    const customer = await findOrCreateCustomer(opts.customer, opts.customerDetails, stripe);
+    const session = await stripe.billingPortal.sessions.create({
+        customer: customer.id,
+        return_url: opts.returnUrl,
+    });
+    return session.url;
+}
+//# sourceMappingURL=checkout.js.map

package/dist/checkout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.js","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAGN,oBAAoB,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AA8BpE;;;;gFAIgF;AAChF,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAC1C,IAAqB,EACrB,SAAiB,SAAS,EAAE;IAE5B,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC3C,oBAAoB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC;QACjE,gBAAgB,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC;KACxC,CAAC,CAAC;IAEH,MAAM,QAAQ,GACb,IAAI,CAAC,QAAQ,IAAI,mBAAmB,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC;QAC7D,CAAC,CAAC,IAAI,CAAC,QAAQ;QACf,CAAC,CAAC,SAAS,CAAC;IAEd,MAAM,QAAQ,GAAG;QAChB,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE;QAC7C,GAAG,IAAI,CAAC,QAAQ;KAChB,CAAC;IAEF,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;QACrD,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,QAAQ,EAAE,QAAQ,CAAC,EAAE;QACrB,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,CAAC,EAAE,CAAC;QAC/D,qBAAqB,EAAE,IAAI,CAAC,mBAAmB,IAAI,IAAI;QACvD,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,MAAM;QAC7B,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjC,GAAG,CAAC,IAAI,CAAC,YAAY;YACpB,CAAC,CAAC;gBACA,iBAAiB,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE;gBACpC,eAAe,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;aACjC;YACF,CAAC,CAAC,EAAE,CAAC;QACN,WAAW,EAAE,IAAI,CAAC,UAAU;QAC5B,UAAU,EAAE,IAAI,CAAC,SAAS;QAC1B,QAAQ;QACR,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5E,CAAC,CAAC;IAEH,IAAI,CAAC,OAAO,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1E,OAAO,OAAO,CAAC,GAAG,CAAC;AACpB,CAAC;AAED,6EAA6E;AAC7E,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,IAIC,EACD,SAAiB,SAAS,EAAE;IAE5B,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAC1C,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,eAAe,EACpB,MAAM,CACN,CAAC;IACF,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC;QAC1D,QAAQ,EAAE,QAAQ,CAAC,EAAE;QACrB,UAAU,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,GAAG,CAAC;AACpB,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The Stripe client — lazily constructed and memoised so the process (and the
+ * test suite) boots without keys, and the SDK is only instantiated on first use.
+ *
+ * This is the one pattern every Ingram site had hand-rolled identically (the
+ * `getStripe()` singleton); it lives here once now. Single-mode sites call
+ * {@link getStripe}; the dual-mode site (cloud.ingram.tech) calls
+ * {@link stripeFor} with a mode and gets one memoised client per mode.
+ */
+import Stripe from "stripe";
+import { type StripeMode } from "./keys.js";
+/** The single-mode Stripe client (STRIPE_SECRET_KEY). Throws a clear error if no
+ *  key is set — guard read paths with {@link stripeConfigured} when billing is
+ *  optional in the environment. */
+export declare function getStripe(): Stripe;
+/** The Stripe client for a dual-mode account (STRIPE_SECRET_KEY_{TEST,LIVE}).
+ *  Throws if that mode's key is unset. */
+export declare function stripeFor(mode: StripeMode): Stripe;
+/** Reset the memoised clients. Test-only seam; never call in app code. */
+export declare function resetStripeClients(): void;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAexD;;mCAEmC;AACnC,wBAAgB,SAAS,IAAI,MAAM,CAOlC;AAED;0CAC0C;AAC1C,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAelD;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC"}

package/dist/client.js

@@ -0,0 +1,57 @@
+/**
+ * The Stripe client — lazily constructed and memoised so the process (and the
+ * test suite) boots without keys, and the SDK is only instantiated on first use.
+ *
+ * This is the one pattern every Ingram site had hand-rolled identically (the
+ * `getStripe()` singleton); it lives here once now. Single-mode sites call
+ * {@link getStripe}; the dual-mode site (cloud.ingram.tech) calls
+ * {@link stripeFor} with a mode and gets one memoised client per mode.
+ */
+import Stripe from "stripe";
+import { billingEnv } from "./keys.js";
+let single = null;
+const byMode = {};
+function construct(key) {
+    const { apiVersion } = billingEnv();
+    // Cast: the SDK types apiVersion as a literal union it ships with; we accept
+    // any pinned string from the env so a site can pin ahead of an SDK bump.
+    const config = apiVersion
+        ? { apiVersion }
+        : undefined;
+    return new Stripe(key, config);
+}
+/** The single-mode Stripe client (STRIPE_SECRET_KEY). Throws a clear error if no
+ *  key is set — guard read paths with {@link stripeConfigured} when billing is
+ *  optional in the environment. */
+export function getStripe() {
+    if (!single) {
+        const key = process.env.STRIPE_SECRET_KEY;
+        if (!key)
+            throw new Error("STRIPE_SECRET_KEY is not set");
+        single = construct(key);
+    }
+    return single;
+}
+/** The Stripe client for a dual-mode account (STRIPE_SECRET_KEY_{TEST,LIVE}).
+ *  Throws if that mode's key is unset. */
+export function stripeFor(mode) {
+    const cached = byMode[mode];
+    if (cached)
+        return cached;
+    const key = mode === "live"
+        ? process.env.STRIPE_SECRET_KEY_LIVE
+        : process.env.STRIPE_SECRET_KEY_TEST;
+    if (!key) {
+        throw new Error(`STRIPE_SECRET_KEY_${mode.toUpperCase()} is not set (dual-mode billing)`);
+    }
+    const client = construct(key);
+    byMode[mode] = client;
+    return client;
+}
+/** Reset the memoised clients. Test-only seam; never call in app code. */
+export function resetStripeClients() {
+    single = null;
+    delete byMode.test;
+    delete byMode.live;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAmB,MAAM,WAAW,CAAC;AAExD,IAAI,MAAM,GAAkB,IAAI,CAAC;AACjC,MAAM,MAAM,GAAwC,EAAE,CAAC;AAEvD,SAAS,SAAS,CAAC,GAAW;IAC7B,MAAM,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAAC;IACpC,6EAA6E;IAC7E,yEAAyE;IACzE,MAAM,MAAM,GAAG,UAAU;QACxB,CAAC,CAAE,EAAE,UAAU,EAA8C;QAC7D,CAAC,CAAC,SAAS,CAAC;IACb,OAAO,IAAI,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AAChC,CAAC;AAED;;mCAEmC;AACnC,MAAM,UAAU,SAAS;IACxB,IAAI,CAAC,MAAM,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;QAC1C,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAC1D,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC;AAED;0CAC0C;AAC1C,MAAM,UAAU,SAAS,CAAC,IAAgB;IACzC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,GAAG,GACR,IAAI,KAAK,MAAM;QACd,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB;QACpC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;IACvC,IAAI,CAAC,GAAG,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACd,qBAAqB,IAAI,CAAC,WAAW,EAAE,iCAAiC,CACxE,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;IACtB,OAAO,MAAM,CAAC;AACf,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,kBAAkB;IACjC,MAAM,GAAG,IAAI,CAAC;IACd,OAAO,MAAM,CAAC,IAAI,CAAC;IACnB,OAAO,MAAM,CAAC,IAAI,CAAC;AACpB,CAAC"}

package/dist/credits.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The in-app credit ledger — the stateful half of nk-billing, for sites that
+ * meter usage in abstract "credits" rather than money (integrain). It follows
+ * nextkit's Django-app model: this package owns its tables and ships their
+ * migration (`migrations/0001_billing.sql`), and takes the database connection by
+ * **injection** so it never reaches into the consuming site's schema.
+ *
+ * Tenancy is the *caller's* concern, deliberately. Every function takes a
+ * `Queryable` (a `pg` client / pool, or nk-db's query interface) and the caller
+ * wraps the call in whatever isolation it uses — `withTenant(orgId, db => …)`
+ * under RLS, or a plain transaction under app-layer filtering. That is why the
+ * spend path is exposed as `spendCredits(db, …)` you call inside your own
+ * transaction, mirroring how a site charges atomically with the row it inserts.
+ *
+ * The ledger is keyed by an opaque `tenantId` — use whatever the site bills per
+ * (org id, user id). The trial grant is folded into the first spend: the first
+ * touch for a tenant lazily creates its row with the trial credits and stamps the
+ * trial clock, so a brand-new workspace gets its trial without a separate
+ * provisioning step.
+ */
+import { type DenyReason } from "./errors.js";
+export { BillingError, type DenyReason, denyMessage } from "./errors.js";
+/** The minimal database surface the ledger needs — satisfied by a `pg`
+ *  Pool/PoolClient and by nk-db's query helpers. */
+export interface Queryable {
+    query<R = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+}
+/** Trial config for the lazy first-spend grant. Omit to disable trials (a tenant
+ *  with no subscription is then simply never entitled). */
+export interface TrialConfig {
+    /** Credits seeded on the tenant's first spend. */
+    credits: number;
+    /** How long the trial lasts from that first spend, in milliseconds. */
+    windowMs: number;
+}
+export type SpendResult = {
+    ok: true;
+    balance: number;
+} | {
+    ok: false;
+    reason: DenyReason;
+};
+export interface SpendOptions {
+    tenantId: string;
+    /** Credits this action costs. The site keeps its own action→cost table. */
+    cost: number;
+    /** Enable the lazy trial grant on first spend. */
+    trial?: TrialConfig;
+    /** Override which subscription statuses count as entitled. */
+    activeStatuses?: ReadonlySet<string>;
+}
+/**
+ * Atomically charge `cost` credits to a tenant **within the caller's
+ * transaction**. Serialised by `SELECT … FOR UPDATE` on the tenant's row so
+ * concurrent spends can't both pass the balance check and overspend. Grants the
+ * trial on first touch when `trial` is set. Returns the outcome — does not throw
+ * — so callers can branch (use {@link requireCredits} when you want a throw).
+ *
+ * The caller MUST run this inside a transaction scoped to the tenant; otherwise
+ * the row lock spans no surrounding work and the atomicity guarantee is weaker.
+ */
+export declare function spendCredits(db: Queryable, opts: SpendOptions): Promise<SpendResult>;
+/** Like {@link spendCredits} but throws {@link BillingError} on a denial — use in
+ *  API routes that map the error to a 402. */
+export declare function requireCredits(db: Queryable, opts: SpendOptions): Promise<void>;
+/** Return previously-spent credits — call when the work a spend paid for did not
+ *  run (a dedup hit, a hard failure, an aborted enqueue). No-op for non-positive
+ *  amounts. */
+export declare function refundCredits(db: Queryable, opts: {
+    tenantId: string;
+    amount: number;
+}): Promise<void>;
+/**
+ * Mark a Stripe event processed, idempotently. Returns false if the event was
+ * already claimed, so the caller skips re-applying it. Run inside the same
+ * transaction as the state change it guards, so a webhook retry can never apply
+ * the change twice. Backed by `billing_stripe_events`.
+ */
+export declare function claimStripeEvent(db: Queryable, eventId: string, type: string): Promise<boolean>;
+/** Add credits to a tenant, idempotently per Stripe event — the dedupe and the
+ *  balance increment share the caller's transaction, so a webhook retry never
+ *  double-credits. Returns false (no-op) if the event was already processed.
+ *  Pass a synthetic `eventId` (e.g. `subgrant:<sub>:<periodStart>`) to grant a
+ *  subscription's bundled credits once per billing period. */
+export declare function grantCredits(db: Queryable, opts: {
+    tenantId: string;
+    eventId: string;
+    eventType: string;
+    amount: number;
+    stripeCustomerId?: string | null;
+}): Promise<boolean>;
+/** Cache a tenant's subscription status from a webhook, idempotently per event.
+ *  Returns false if the event was already processed. */
+export declare function recordSubscriptionStatus(db: Queryable, opts: {
+    tenantId: string;
+    eventId: string;
+    eventType: string;
+    status: string;
+    stripeCustomerId?: string | null;
+}): Promise<boolean>;
+export interface BillingSummary {
+    creditsBalance: number;
+    subscriptionStatus: string | null;
+    stripeCustomerId: string | null;
+    entitled: boolean;
+    /** Trial window end (epoch ms) when in trial and unsubscribed, else null. */
+    trialEndsAt: number | null;
+}
+/** Read-only entitlement + balance snapshot for the billing UI. Does not create a
+ *  row or grant the trial (that happens on the first spend). */
+export declare function getBillingSummary(db: Queryable, opts: {
+    tenantId: string;
+    trialWindowMs?: number;
+    activeStatuses?: ReadonlySet<string>;
+}): Promise<BillingSummary>;
+//# sourceMappingURL=credits.d.ts.map

package/dist/credits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credits.d.ts","sourceRoot":"","sources":["../src/credits.ts"],"names":[],"mappings":"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"}