@ingram-tech/nk-billing 0.1.0

package/dist/prices.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Prices, resolved by stable `lookup_key` rather than hardcoded IDs. The catalog
+ * (products/prices) is owned by the infra Pulumi program; this only *consumes*
+ * it at runtime. Because a lookup_key resolves to different price IDs in test and
+ * live, the same code path works in both modes with nothing mode-specific in env.
+ */
+import type Stripe from "stripe";
+/** Resolve an active Price by its stable lookup_key. `currency_options` is
+ *  expanded so callers can see (and localise to) the presentment currencies the
+ *  price supports. Throws if no active price carries the key — usually means the
+ *  catalog hasn't been applied to this Stripe mode yet. */
+export declare function priceByLookupKey(key: string, stripe?: Stripe): Promise<Stripe.Price>;
+/** The presentment currencies a price supports: its base plus currency_options. */
+export declare function supportedCurrencies(price: Stripe.Price): Set<string>;
+/** The amount (in minor units) a price charges in `currency`, or null if the
+ *  price offers neither that currency nor a base amount. Falls back to the base
+ *  currency when the requested one isn't carried. Used to display localised
+ *  prices without a hardcoded amount. */
+export declare function displayAmount(key: string, currency: string, stripe?: Stripe): Promise<{
+    amount: number;
+    currency: string;
+} | null>;
+//# sourceMappingURL=prices.d.ts.map

package/dist/prices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prices.d.ts","sourceRoot":"","sources":["../src/prices.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC;;;2DAG2D;AAC3D,wBAAsB,gBAAgB,CACrC,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,MAAoB,GAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAcvB;AAED,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,CAEpE;AAED;;;yCAGyC;AACzC,wBAAsB,aAAa,CAClC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAoB,GAC1B,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAStD"}

package/dist/prices.js

@@ -0,0 +1,45 @@
+/**
+ * Prices, resolved by stable `lookup_key` rather than hardcoded IDs. The catalog
+ * (products/prices) is owned by the infra Pulumi program; this only *consumes*
+ * it at runtime. Because a lookup_key resolves to different price IDs in test and
+ * live, the same code path works in both modes with nothing mode-specific in env.
+ */
+import { getStripe } from "./client.js";
+/** Resolve an active Price by its stable lookup_key. `currency_options` is
+ *  expanded so callers can see (and localise to) the presentment currencies the
+ *  price supports. Throws if no active price carries the key — usually means the
+ *  catalog hasn't been applied to this Stripe mode yet. */
+export async function priceByLookupKey(key, stripe = getStripe()) {
+    const prices = await stripe.prices.list({
+        lookup_keys: [key],
+        active: true,
+        limit: 1,
+        expand: ["data.currency_options"],
+    });
+    const price = prices.data[0];
+    if (!price) {
+        throw new Error(`No active Stripe price for lookup_key '${key}' — has the catalog been applied to this mode?`);
+    }
+    return price;
+}
+/** The presentment currencies a price supports: its base plus currency_options. */
+export function supportedCurrencies(price) {
+    return new Set([price.currency, ...Object.keys(price.currency_options ?? {})]);
+}
+/** The amount (in minor units) a price charges in `currency`, or null if the
+ *  price offers neither that currency nor a base amount. Falls back to the base
+ *  currency when the requested one isn't carried. Used to display localised
+ *  prices without a hardcoded amount. */
+export async function displayAmount(key, currency, stripe = getStripe()) {
+    const price = await priceByLookupKey(key, stripe);
+    if (currency !== price.currency) {
+        const opt = price.currency_options?.[currency]?.unit_amount;
+        if (opt != null)
+            return { amount: opt, currency };
+        // Price doesn't carry that currency — fall through to its base.
+    }
+    if (price.unit_amount == null)
+        return null;
+    return { amount: price.unit_amount, currency: price.currency };
+}
+//# sourceMappingURL=prices.js.map

package/dist/prices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prices.js","sourceRoot":"","sources":["../src/prices.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC;;;2DAG2D;AAC3D,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,GAAW,EACX,SAAiB,SAAS,EAAE;IAE5B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;QACvC,WAAW,EAAE,CAAC,GAAG,CAAC;QAClB,MAAM,EAAE,IAAI;QACZ,KAAK,EAAE,CAAC;QACR,MAAM,EAAE,CAAC,uBAAuB,CAAC;KACjC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACd,0CAA0C,GAAG,gDAAgD,CAC7F,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,mBAAmB,CAAC,KAAmB;IACtD,OAAO,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAChF,CAAC;AAED;;;yCAGyC;AACzC,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,GAAW,EACX,QAAgB,EAChB,SAAiB,SAAS,EAAE;IAE5B,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAClD,IAAI,QAAQ,KAAK,KAAK,CAAC,QAAQ,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,KAAK,CAAC,gBAAgB,EAAE,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC;QAC5D,IAAI,GAAG,IAAI,IAAI;YAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;QAClD,gEAAgE;IACjE,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC3C,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,WAAW,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;AAChE,CAAC"}

package/dist/status.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Subscription-status predicates with **zero dependencies** — no Stripe SDK, no
+ * database. Lives apart from `subscription.ts` (which needs the Stripe client) so
+ * the Postgres credit ledger in `./credits` can import the entitlement set
+ * without dragging Stripe into that bundle.
+ */
+/** Stripe statuses that count as "has access" for gating. `past_due` is included
+ *  deliberately — the customer keeps access during Stripe's dunning retries. */
+export declare const ACTIVE_SUBSCRIPTION_STATUSES: ReadonlySet<string>;
+/** Whether a raw Stripe status grants access. */
+export declare function isActiveStatus(status: string | null | undefined): boolean;
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;gFACgF;AAChF,eAAO,MAAM,4BAA4B,EAAE,WAAW,CAAC,MAAM,CAI3D,CAAC;AAEH,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEzE"}

package/dist/status.js

@@ -0,0 +1,18 @@
+/**
+ * Subscription-status predicates with **zero dependencies** — no Stripe SDK, no
+ * database. Lives apart from `subscription.ts` (which needs the Stripe client) so
+ * the Postgres credit ledger in `./credits` can import the entitlement set
+ * without dragging Stripe into that bundle.
+ */
+/** Stripe statuses that count as "has access" for gating. `past_due` is included
+ *  deliberately — the customer keeps access during Stripe's dunning retries. */
+export const ACTIVE_SUBSCRIPTION_STATUSES = new Set([
+    "active",
+    "trialing",
+    "past_due",
+]);
+/** Whether a raw Stripe status grants access. */
+export function isActiveStatus(status) {
+    return status != null && ACTIVE_SUBSCRIPTION_STATUSES.has(status);
+}
+//# sourceMappingURL=status.js.map

package/dist/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;gFACgF;AAChF,MAAM,CAAC,MAAM,4BAA4B,GAAwB,IAAI,GAAG,CAAC;IACxE,QAAQ;IACR,UAAU;IACV,UAAU;CACV,CAAC,CAAC;AAEH,iDAAiD;AACjD,MAAM,UAAU,cAAc,CAAC,MAAiC;IAC/D,OAAO,MAAM,IAAI,IAAI,IAAI,4BAA4B,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACnE,CAAC"}

package/dist/subscription.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Subscription status — the normalisation every site repeats, in one place.
+ *
+ * Two things are awkward about Stripe subscriptions and handled here: (1) which
+ * raw statuses count as "entitled" (you stay entitled through `past_due` while
+ * Stripe retries the card), and (2) the billing period now lives on the
+ * subscription *item* (`current_period_end`), not the subscription, in current
+ * API versions. {@link summarizeSubscription} flattens a raw subscription into
+ * the handful of fields a site actually persists/displays.
+ */
+import type Stripe from "stripe";
+export { ACTIVE_SUBSCRIPTION_STATUSES, isActiveStatus } from "./status.js";
+/** The flattened view of a subscription a site persists or displays. Epoch fields
+ *  are JS `Date`s (Stripe returns Unix seconds). */
+export interface SubscriptionSummary {
+    subscriptionId: string;
+    customerId: string;
+    status: string;
+    active: boolean;
+    priceId: string | null;
+    /** End of the current billing period (from the subscription item). */
+    currentPeriodEnd: Date | null;
+    cancelAtPeriodEnd: boolean;
+    trialEnd: Date | null;
+}
+/** Flatten a raw Stripe subscription into a {@link SubscriptionSummary}. */
+export declare function summarizeSubscription(sub: Stripe.Subscription): SubscriptionSummary;
+/** Read a customer's most relevant subscription live from Stripe — the first
+ *  active one if any, else the most recent. Returns null when the customer has
+ *  none. Use to back the "webhook lag self-heal" pattern: when your cache says
+ *  not-active, re-check here and backfill the row. */
+export declare function fetchSubscriptionForCustomer(customerId: string, stripe?: Stripe): Promise<Stripe.Subscription | null>;
+/** {@link fetchSubscriptionForCustomer} flattened to a {@link SubscriptionSummary}. */
+export declare function fetchSubscriptionSummary(customerId: string, stripe?: Stripe): Promise<SubscriptionSummary | null>;
+//# sourceMappingURL=subscription.d.ts.map

package/dist/subscription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../src/subscription.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAIjC,OAAO,EAAE,4BAA4B,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE3E;oDACoD;AACpD,MAAM,WAAW,mBAAmB;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,sEAAsE;IACtE,gBAAgB,EAAE,IAAI,GAAG,IAAI,CAAC;IAC9B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;CACtB;AAKD,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,YAAY,GAAG,mBAAmB,CAYnF;AAED;;;sDAGsD;AACtD,wBAAsB,4BAA4B,CACjD,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAAoB,GAC1B,OAAO,CAAC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,CAQrC;AAED,uFAAuF;AACvF,wBAAsB,wBAAwB,CAC7C,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAAoB,GAC1B,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAGrC"}

package/dist/subscription.js

@@ -0,0 +1,47 @@
+/**
+ * Subscription status — the normalisation every site repeats, in one place.
+ *
+ * Two things are awkward about Stripe subscriptions and handled here: (1) which
+ * raw statuses count as "entitled" (you stay entitled through `past_due` while
+ * Stripe retries the card), and (2) the billing period now lives on the
+ * subscription *item* (`current_period_end`), not the subscription, in current
+ * API versions. {@link summarizeSubscription} flattens a raw subscription into
+ * the handful of fields a site actually persists/displays.
+ */
+import { getStripe } from "./client.js";
+import { isActiveStatus } from "./status.js";
+export { ACTIVE_SUBSCRIPTION_STATUSES, isActiveStatus } from "./status.js";
+const toDate = (seconds) => seconds == null ? null : new Date(seconds * 1000);
+/** Flatten a raw Stripe subscription into a {@link SubscriptionSummary}. */
+export function summarizeSubscription(sub) {
+    const item = sub.items.data[0];
+    return {
+        subscriptionId: sub.id,
+        customerId: typeof sub.customer === "string" ? sub.customer : sub.customer.id,
+        status: sub.status,
+        active: isActiveStatus(sub.status),
+        priceId: item?.price.id ?? null,
+        currentPeriodEnd: toDate(item?.current_period_end),
+        cancelAtPeriodEnd: sub.cancel_at_period_end,
+        trialEnd: toDate(sub.trial_end),
+    };
+}
+/** Read a customer's most relevant subscription live from Stripe — the first
+ *  active one if any, else the most recent. Returns null when the customer has
+ *  none. Use to back the "webhook lag self-heal" pattern: when your cache says
+ *  not-active, re-check here and backfill the row. */
+export async function fetchSubscriptionForCustomer(customerId, stripe = getStripe()) {
+    const subs = await stripe.subscriptions.list({
+        customer: customerId,
+        status: "all",
+        limit: 10,
+        expand: ["data.items.data.price"],
+    });
+    return subs.data.find((s) => isActiveStatus(s.status)) ?? subs.data[0] ?? null;
+}
+/** {@link fetchSubscriptionForCustomer} flattened to a {@link SubscriptionSummary}. */
+export async function fetchSubscriptionSummary(customerId, stripe = getStripe()) {
+    const sub = await fetchSubscriptionForCustomer(customerId, stripe);
+    return sub ? summarizeSubscription(sub) : null;
+}
+//# sourceMappingURL=subscription.js.map

package/dist/subscription.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.js","sourceRoot":"","sources":["../src/subscription.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,4BAA4B,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAgB3E,MAAM,MAAM,GAAG,CAAC,OAAkC,EAAe,EAAE,CAClE,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;AAEnD,4EAA4E;AAC5E,MAAM,UAAU,qBAAqB,CAAC,GAAwB;IAC7D,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/B,OAAO;QACN,cAAc,EAAE,GAAG,CAAC,EAAE;QACtB,UAAU,EAAE,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE;QAC7E,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC;QAClC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,IAAI,IAAI;QAC/B,gBAAgB,EAAE,MAAM,CAAC,IAAI,EAAE,kBAAkB,CAAC;QAClD,iBAAiB,EAAE,GAAG,CAAC,oBAAoB;QAC3C,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC;KAC/B,CAAC;AACH,CAAC;AAED;;;sDAGsD;AACtD,MAAM,CAAC,KAAK,UAAU,4BAA4B,CACjD,UAAkB,EAClB,SAAiB,SAAS,EAAE;IAE5B,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC;QAC5C,QAAQ,EAAE,UAAU;QACpB,MAAM,EAAE,KAAK;QACb,KAAK,EAAE,EAAE;QACT,MAAM,EAAE,CAAC,uBAAuB,CAAC;KACjC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAChF,CAAC;AAED,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC7C,UAAkB,EAClB,SAAiB,SAAS,EAAE;IAE5B,MAAM,GAAG,GAAG,MAAM,4BAA4B,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACnE,OAAO,GAAG,CAAC,CAAC,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC"}

package/dist/webhooks.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Webhook verification — the raw-body-read + signature-verify dance every Stripe
+ * route repeats. The stateful half (idempotent dedup of an event before applying
+ * it) lives in `@ingram-tech/nk-billing/credits` (`claimStripeEvent`), so this
+ * module stays free of any database concept.
+ */
+import type Stripe from "stripe";
+/** Result of reading a webhook request: the verified event, or a reason + the
+ *  HTTP status to return. 400 = bad/missing signature (don't retry); 503 = the
+ *  endpoint isn't configured (secret unset). */
+export type WebhookResult = {
+    ok: true;
+    event: Stripe.Event;
+} | {
+    ok: false;
+    status: 400 | 503;
+    message: string;
+};
+/** Verify a raw body + signature against the signing secret. Thin wrapper over
+ *  `stripe.webhooks.constructEvent` that returns a typed result instead of
+ *  throwing on a bad signature. */
+export declare function verifyStripeWebhook(body: string, signature: string | null, secret: string, stripe?: Stripe): WebhookResult;
+/** Read and verify a Stripe webhook from a Fetch `Request` — reads the raw text
+ *  body (required before any JSON parsing), pulls the `stripe-signature` header,
+ *  and verifies. Pass the secret for the relevant mode. Returns a 503 result when
+ *  `secret` is empty so an unconfigured endpoint fails closed without throwing.
+ *
+ * Typical route:
+ *   const res = await readStripeWebhook(request, process.env.STRIPE_WEBHOOK_SECRET ?? "");
+ *   if (!res.ok) return new Response(res.message, { status: res.status });
+ *   // ... dedupe with claimStripeEvent, then handle res.event ...
+ */
+export declare function readStripeWebhook(request: Request, secret: string, stripe?: Stripe): Promise<WebhookResult>;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC;;gDAEgD;AAChD,MAAM,MAAM,aAAa,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAA;CAAE,GACjC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;mCAEmC;AACnC,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,MAAoB,GAC1B,aAAa,CAQf;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACtC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,MAAoB,GAC1B,OAAO,CAAC,aAAa,CAAC,CAOxB"}

package/dist/webhooks.js

@@ -0,0 +1,40 @@
+/**
+ * Webhook verification — the raw-body-read + signature-verify dance every Stripe
+ * route repeats. The stateful half (idempotent dedup of an event before applying
+ * it) lives in `@ingram-tech/nk-billing/credits` (`claimStripeEvent`), so this
+ * module stays free of any database concept.
+ */
+import { getStripe } from "./client.js";
+/** Verify a raw body + signature against the signing secret. Thin wrapper over
+ *  `stripe.webhooks.constructEvent` that returns a typed result instead of
+ *  throwing on a bad signature. */
+export function verifyStripeWebhook(body, signature, secret, stripe = getStripe()) {
+    if (!signature)
+        return { ok: false, status: 400, message: "Missing signature" };
+    try {
+        const event = stripe.webhooks.constructEvent(body, signature, secret);
+        return { ok: true, event };
+    }
+    catch {
+        return { ok: false, status: 400, message: "Invalid signature" };
+    }
+}
+/** Read and verify a Stripe webhook from a Fetch `Request` — reads the raw text
+ *  body (required before any JSON parsing), pulls the `stripe-signature` header,
+ *  and verifies. Pass the secret for the relevant mode. Returns a 503 result when
+ *  `secret` is empty so an unconfigured endpoint fails closed without throwing.
+ *
+ * Typical route:
+ *   const res = await readStripeWebhook(request, process.env.STRIPE_WEBHOOK_SECRET ?? "");
+ *   if (!res.ok) return new Response(res.message, { status: res.status });
+ *   // ... dedupe with claimStripeEvent, then handle res.event ...
+ */
+export async function readStripeWebhook(request, secret, stripe = getStripe()) {
+    if (!secret) {
+        return { ok: false, status: 503, message: "Webhook not configured" };
+    }
+    const body = await request.text();
+    const signature = request.headers.get("stripe-signature");
+    return verifyStripeWebhook(body, signature, secret, stripe);
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AASxC;;mCAEmC;AACnC,MAAM,UAAU,mBAAmB,CAClC,IAAY,EACZ,SAAwB,EACxB,MAAc,EACd,SAAiB,SAAS,EAAE;IAE5B,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAChF,IAAI,CAAC;QACJ,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;QACtE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC;IACjE,CAAC;AACF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACtC,OAAgB,EAChB,MAAc,EACd,SAAiB,SAAS,EAAE;IAE5B,IAAI,CAAC,MAAM,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACtE,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;IAClC,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAC1D,OAAO,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAC7D,CAAC"}

package/migrations/0001_billing.sql

@@ -0,0 +1,42 @@
+-- @ingram-tech/nk-billing — credit ledger + Stripe event-dedup store.
+--
+-- The stateful slice of nk-billing, only for sites that use the credit ledger
+-- (`@ingram-tech/nk-billing/credits`). Sites that only do subscriptions, or use
+-- the Stripe-side wallet (`./balance`), do NOT need this migration.
+--
+-- Tenancy is the consuming site's concern (see credits.ts): these tables are
+-- keyed by an opaque `tenant_id` and carry NO row-level security here. Apply
+-- your own isolation to match your stack:
+--   * RLS sites: add a `tenant_isolation` policy keyed on tenant_id and reach
+--     the rows through nk-db's `withRlsTransaction` / `withTenant`.
+--   * App-layer-filtering sites: every query already passes tenant_id; nothing
+--     extra is required.
+--
+-- Ship this as a Drizzle schema fragment + generated SQL so it composes with the
+-- consuming site's drizzle-kit pipeline (see docs/db-package.md). Adjust the
+-- table names only if they collide; the ledger code hardcodes them.
+
+create table if not exists billing_credits (
+	tenant_id          text         primary key,
+	-- Abstract credits, not money. Bigint so high-volume metering can't overflow.
+	credits_balance    bigint       not null default 0,
+	-- Cached Stripe subscription status (active / trialing / past_due / …), kept
+	-- fresh by the customer.subscription.* webhook via recordSubscriptionStatus().
+	subscription_status text,
+	-- Cached Stripe customer id, backfilled from webhooks. A read-side convenience;
+	-- the authoritative link is the customer's metadata tag (see customers.ts).
+	stripe_customer_id text,
+	-- When the lazy trial clock started (set on first spend when trials are on).
+	trial_started_at   timestamptz,
+	created_at         timestamptz  not null default now(),
+	updated_at         timestamptz  not null default now()
+);
+
+-- Idempotency log for inbound Stripe webhooks. Each event id is inserted once,
+-- in the same transaction as the state change it guards, so retries are no-ops.
+-- Synthetic ids (e.g. `subgrant:<sub>:<periodStart>`) dedupe per-period grants.
+create table if not exists billing_stripe_events (
+	event_id   text        primary key,
+	type       text        not null,
+	created_at timestamptz not null default now()
+);

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@ingram-tech/nk-billing",
+	"version": "0.1.0",
+	"description": "The Ingram billing foundation: composable Stripe primitives (client, customers, prices, currency, checkout, subscriptions, webhooks) plus an injection-based Postgres credit ledger and event-dedup store.",
+	"license": "MIT",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ingram-technologies/nextkit.git",
+		"directory": "packages/nk-billing"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"migrations"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./credits": {
+			"types": "./dist/credits.d.ts",
+			"import": "./dist/credits.js"
+		},
+		"./migrations/*": "./migrations/*"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"type-check": "tsc -p tsconfig.json --noEmit",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"stripe": "^22.0.0",
+		"zod": "^4.0.0"
+	},
+	"devDependencies": {
+		"@ingram-tech/nk-dev": "workspace:*",
+		"@types/node": "^25.0.0",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.6"
+	}
+}