@ingram-tech/nk-billing 0.1.0

package/dist/credits.js

@@ -0,0 +1,154 @@
+/**
+ * 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 { BillingError } from "./errors.js";
+import { ACTIVE_SUBSCRIPTION_STATUSES } from "./status.js";
+export { BillingError, denyMessage } from "./errors.js";
+function entitled(row, now, trialWindowMs, activeStatuses) {
+    if (row.subscription_status && activeStatuses.has(row.subscription_status)) {
+        return true;
+    }
+    if (trialWindowMs != null && row.trial_started_at) {
+        const started = new Date(row.trial_started_at).getTime();
+        if (Number.isFinite(started) && now - started <= trialWindowMs)
+            return true;
+    }
+    return false;
+}
+/**
+ * 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 async function spendCredits(db, opts) {
+    const activeStatuses = opts.activeStatuses ?? ACTIVE_SUBSCRIPTION_STATUSES;
+    // First touch: seed the row (with trial credits + clock when trials are on).
+    // ON CONFLICT DO NOTHING makes the trial a one-time grant.
+    await db.query(`insert into billing_credits (tenant_id, credits_balance, trial_started_at)
+		 values ($1, $2, ${opts.trial ? "now()" : "null"})
+		 on conflict (tenant_id) do nothing`, [opts.tenantId, opts.trial?.credits ?? 0]);
+    const { rows } = await db.query(`select credits_balance, subscription_status, trial_started_at, stripe_customer_id
+		 from billing_credits where tenant_id = $1 for update`, [opts.tenantId]);
+    const row = rows[0];
+    if (!row)
+        return { ok: false, reason: "not_entitled" };
+    if (!entitled(row, Date.now(), opts.trial?.windowMs, activeStatuses)) {
+        return { ok: false, reason: "not_entitled" };
+    }
+    if (row.credits_balance < opts.cost) {
+        return { ok: false, reason: "insufficient_credits" };
+    }
+    const { rows: updated } = await db.query(`update billing_credits
+		 set credits_balance = credits_balance - $2, updated_at = now()
+		 where tenant_id = $1
+		 returning credits_balance`, [opts.tenantId, opts.cost]);
+    return { ok: true, balance: updated[0]?.credits_balance ?? 0 };
+}
+/** Like {@link spendCredits} but throws {@link BillingError} on a denial — use in
+ *  API routes that map the error to a 402. */
+export async function requireCredits(db, opts) {
+    const result = await spendCredits(db, opts);
+    if (!result.ok)
+        throw new BillingError(result.reason);
+}
+/** 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 async function refundCredits(db, opts) {
+    if (opts.amount <= 0)
+        return;
+    await db.query(`update billing_credits
+		 set credits_balance = credits_balance + $2, updated_at = now()
+		 where tenant_id = $1`, [opts.tenantId, opts.amount]);
+}
+/**
+ * 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 async function claimStripeEvent(db, eventId, type) {
+    const { rows } = await db.query(`insert into billing_stripe_events (event_id, type) values ($1, $2)
+		 on conflict (event_id) do nothing returning event_id`, [eventId, type]);
+    return rows.length > 0;
+}
+/** 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 async function grantCredits(db, opts) {
+    if (!(await claimStripeEvent(db, opts.eventId, opts.eventType)))
+        return false;
+    await db.query(`insert into billing_credits (tenant_id, credits_balance, stripe_customer_id)
+		 values ($1, $2, $3)
+		 on conflict (tenant_id) do update set
+		   credits_balance = billing_credits.credits_balance + excluded.credits_balance,
+		   stripe_customer_id = coalesce(excluded.stripe_customer_id, billing_credits.stripe_customer_id),
+		   updated_at = now()`, [opts.tenantId, opts.amount, opts.stripeCustomerId ?? null]);
+    return true;
+}
+/** Cache a tenant's subscription status from a webhook, idempotently per event.
+ *  Returns false if the event was already processed. */
+export async function recordSubscriptionStatus(db, opts) {
+    if (!(await claimStripeEvent(db, opts.eventId, opts.eventType)))
+        return false;
+    await db.query(`insert into billing_credits (tenant_id, subscription_status, stripe_customer_id)
+		 values ($1, $2, $3)
+		 on conflict (tenant_id) do update set
+		   subscription_status = excluded.subscription_status,
+		   stripe_customer_id = coalesce(excluded.stripe_customer_id, billing_credits.stripe_customer_id),
+		   updated_at = now()`, [opts.tenantId, opts.status, opts.stripeCustomerId ?? null]);
+    return true;
+}
+/** 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 async function getBillingSummary(db, opts) {
+    const activeStatuses = opts.activeStatuses ?? ACTIVE_SUBSCRIPTION_STATUSES;
+    const { rows } = await db.query(`select credits_balance, subscription_status, trial_started_at, stripe_customer_id
+		 from billing_credits where tenant_id = $1`, [opts.tenantId]);
+    const row = rows[0];
+    if (!row) {
+        return {
+            creditsBalance: 0,
+            subscriptionStatus: null,
+            stripeCustomerId: null,
+            entitled: false,
+            trialEndsAt: null,
+        };
+    }
+    const subscribed = !!row.subscription_status && activeStatuses.has(row.subscription_status);
+    const trialEndsAt = !subscribed && opts.trialWindowMs != null && row.trial_started_at
+        ? new Date(row.trial_started_at).getTime() + opts.trialWindowMs
+        : null;
+    return {
+        creditsBalance: row.credits_balance,
+        subscriptionStatus: row.subscription_status,
+        stripeCustomerId: row.stripe_customer_id,
+        entitled: entitled(row, Date.now(), opts.trialWindowMs, activeStatuses),
+        trialEndsAt,
+    };
+}
+//# sourceMappingURL=credits.js.map

package/dist/credits.js.map

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

package/dist/currency.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Presentment currency. We sell in two — EUR (the home/base currency) and USD —
+ * chosen by where the request comes from. A Stripe Price carries the EUR base
+ * `unit_amount` plus a USD entry in `currency_options`; checkout passes the
+ * resolved currency and Stripe charges the matching amount.
+ *
+ * Currency resolution reads Vercel's edge geolocation header
+ * (`x-vercel-ip-country`). To stay framework-agnostic this module never imports
+ * `next/headers`; the caller passes a `Headers` object (e.g. `await headers()` in
+ * a Next.js Server Component, or `request.headers` in a route handler).
+ */
+/** The two presentment currencies we offer. */
+export type BillingCurrency = "usd" | "eur";
+/** Used when the caller's region is unknown — and the base on the Stripe prices. */
+export declare const DEFAULT_CURRENCY: BillingCurrency;
+/** EU/EEA country codes served in euros (closer to EUR than USD even where the
+ *  local currency isn't the euro — we only offer the two). Everyone else: USD. */
+export declare const EUR_COUNTRIES: ReadonlySet<string>;
+/** Map an ISO-3166 alpha-2 country code to a presentment currency: EU/EEA → EUR,
+ *  any other identified country → USD, and no signal (absent header / local dev)
+ *  → the home base currency. */
+export declare function currencyForCountry(country: string | null | undefined): BillingCurrency;
+/** Resolve the caller's presentment currency from a `Headers` object via Vercel's
+ *  `x-vercel-ip-country` (set at the edge on every request). Falls back to the
+ *  base currency off-Vercel where the header is absent. */
+export declare function resolveCurrencyFromHeaders(headers: Headers): BillingCurrency;
+/** Format a Stripe minor-unit amount (cents) in `currency` for display. Drops the
+ *  trailing ".00" on round figures. */
+export declare function formatAmount(minorUnits: number, currency: BillingCurrency): string;
+//# sourceMappingURL=currency.d.ts.map

package/dist/currency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"currency.d.ts","sourceRoot":"","sources":["../src/currency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,+CAA+C;AAC/C,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,KAAK,CAAC;AAE5C,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,EAAE,eAAuB,CAAC;AAEvD;kFACkF;AAClF,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,CAsC5C,CAAC;AAEH;;gCAEgC;AAChC,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAChC,eAAe,CAGjB;AAED;;2DAE2D;AAC3D,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,CAE5E;AAED;uCACuC;AACvC,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,MAAM,CAMlF"}

package/dist/currency.js

@@ -0,0 +1,78 @@
+/**
+ * Presentment currency. We sell in two — EUR (the home/base currency) and USD —
+ * chosen by where the request comes from. A Stripe Price carries the EUR base
+ * `unit_amount` plus a USD entry in `currency_options`; checkout passes the
+ * resolved currency and Stripe charges the matching amount.
+ *
+ * Currency resolution reads Vercel's edge geolocation header
+ * (`x-vercel-ip-country`). To stay framework-agnostic this module never imports
+ * `next/headers`; the caller passes a `Headers` object (e.g. `await headers()` in
+ * a Next.js Server Component, or `request.headers` in a route handler).
+ */
+/** Used when the caller's region is unknown — and the base on the Stripe prices. */
+export const DEFAULT_CURRENCY = "eur";
+/** EU/EEA country codes served in euros (closer to EUR than USD even where the
+ *  local currency isn't the euro — we only offer the two). Everyone else: USD. */
+export const EUR_COUNTRIES = new Set([
+    // Eurozone
+    "AT",
+    "BE",
+    "HR",
+    "CY",
+    "EE",
+    "FI",
+    "FR",
+    "DE",
+    "GR",
+    "IE",
+    "IT",
+    "LV",
+    "LT",
+    "LU",
+    "MT",
+    "NL",
+    "PT",
+    "SK",
+    "SI",
+    "ES",
+    // Rest of EU (non-euro)
+    "BG",
+    "CZ",
+    "DK",
+    "HU",
+    "PL",
+    "RO",
+    "SE",
+    // EEA + microstates that use the euro
+    "IS",
+    "LI",
+    "NO",
+    "MC",
+    "SM",
+    "VA",
+    "AD",
+]);
+/** Map an ISO-3166 alpha-2 country code to a presentment currency: EU/EEA → EUR,
+ *  any other identified country → USD, and no signal (absent header / local dev)
+ *  → the home base currency. */
+export function currencyForCountry(country) {
+    if (!country)
+        return DEFAULT_CURRENCY;
+    return EUR_COUNTRIES.has(country.toUpperCase()) ? "eur" : "usd";
+}
+/** Resolve the caller's presentment currency from a `Headers` object via Vercel's
+ *  `x-vercel-ip-country` (set at the edge on every request). Falls back to the
+ *  base currency off-Vercel where the header is absent. */
+export function resolveCurrencyFromHeaders(headers) {
+    return currencyForCountry(headers.get("x-vercel-ip-country"));
+}
+/** Format a Stripe minor-unit amount (cents) in `currency` for display. Drops the
+ *  trailing ".00" on round figures. */
+export function formatAmount(minorUnits, currency) {
+    return new Intl.NumberFormat(currency === "eur" ? "en-IE" : "en-US", {
+        style: "currency",
+        currency: currency.toUpperCase(),
+        minimumFractionDigits: minorUnits % 100 === 0 ? 0 : 2,
+    }).format(minorUnits / 100);
+}
+//# sourceMappingURL=currency.js.map

package/dist/currency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"currency.js","sourceRoot":"","sources":["../src/currency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,oFAAoF;AACpF,MAAM,CAAC,MAAM,gBAAgB,GAAoB,KAAK,CAAC;AAEvD;kFACkF;AAClF,MAAM,CAAC,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC;IACzD,WAAW;IACX,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,wBAAwB;IACxB,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,sCAAsC;IACtC,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;CACJ,CAAC,CAAC;AAEH;;gCAEgC;AAChC,MAAM,UAAU,kBAAkB,CACjC,OAAkC;IAElC,IAAI,CAAC,OAAO;QAAE,OAAO,gBAAgB,CAAC;IACtC,OAAO,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;AACjE,CAAC;AAED;;2DAE2D;AAC3D,MAAM,UAAU,0BAA0B,CAAC,OAAgB;IAC1D,OAAO,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;uCACuC;AACvC,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,QAAyB;IACzE,OAAO,IAAI,IAAI,CAAC,YAAY,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE;QACpE,KAAK,EAAE,UAAU;QACjB,QAAQ,EAAE,QAAQ,CAAC,WAAW,EAAE;QAChC,qBAAqB,EAAE,UAAU,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KACrD,CAAC,CAAC,MAAM,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC;AAC7B,CAAC"}

package/dist/customers.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Customer resolution. Every Ingram site keys its Stripe customer to a local
+ * entity (an org or a user) by writing that id into the customer's `metadata`,
+ * then finds it back by metadata search — no local `stripe_customer_id` column is
+ * required just to locate the customer (though sites cache it for speed).
+ *
+ * The metadata key differs per site (`financica_organization_id`,
+ * `integrain_org_id`, …), so it is always passed in explicitly via
+ * {@link CustomerRef} rather than baked in here — that is the framework seam.
+ */
+import type Stripe from "stripe";
+/** Identifies a Stripe customer by a metadata tag → local entity id. */
+export interface CustomerRef {
+    /** The Stripe `metadata` key the local id is stored under, e.g.
+     *  "integrain_org_id". Choose one per site and use it everywhere. */
+    metadataKey: string;
+    /** The local entity id (org id, user id, …). */
+    id: string;
+}
+export interface CustomerDetails {
+    name?: string | null;
+    email?: string | null;
+    /** EU VAT number; recorded as an `eu_vat` tax id (best-effort, non-fatal). */
+    vatNumber?: string | null;
+    address?: {
+        line1?: string | null;
+        city?: string | null;
+        postal_code?: string | null;
+        country?: string | null;
+    } | null;
+}
+/** The customer for `ref`, found by metadata search, or null if none exists yet.
+ *  Read paths use this so merely viewing a billing page never mints an empty
+ *  customer. */
+export declare function findCustomer(ref: CustomerRef, stripe?: Stripe): Promise<Stripe.Customer | null>;
+/** Like {@link findCustomer} but creates the customer on first use (checkout).
+ *  The local id is always written into metadata so {@link findCustomer} can find
+ *  it back. */
+export declare function findOrCreateCustomer(ref: CustomerRef, details?: CustomerDetails, stripe?: Stripe): Promise<Stripe.Customer>;
+/** Whether a customer has a billing address on file. Stripe requires one before
+ *  `tax_id_collection` can be enabled on a Checkout session. */
+export declare function customerHasBillingAddress(customerId: string, stripe?: Stripe): Promise<boolean>;
+/** Update a customer's name and billing address — used when details were missing
+ *  and got collected just before checkout. */
+export declare function updateCustomerBillingAddress(customerId: string, opts: {
+    name?: string | null;
+    address: {
+        line1: string;
+        city: string;
+        postal_code: string;
+        country: string;
+    };
+}, stripe?: Stripe): Promise<void>;
+//# sourceMappingURL=customers.d.ts.map

package/dist/customers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"customers.d.ts","sourceRoot":"","sources":["../src/customers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC3B;yEACqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,eAAe;IAC/B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,EAAE;QACT,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACxB,GAAG,IAAI,CAAC;CACT;AAED;;gBAEgB;AAChB,wBAAsB,YAAY,CACjC,GAAG,EAAE,WAAW,EAChB,MAAM,GAAE,MAAoB,GAC1B,OAAO,CAAC,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC,CAMjC;AAED;;eAEe;AACf,wBAAsB,oBAAoB,CACzC,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,eAAoB,EAC7B,MAAM,GAAE,MAAoB,GAC1B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAiC1B;AAED;gEACgE;AAChE,wBAAsB,yBAAyB,CAC9C,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAAoB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAIlB;AAED;8CAC8C;AAC9C,wBAAsB,4BAA4B,CACjD,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE;QACR,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;KAChB,CAAC;CACF,EACD,MAAM,GAAE,MAAoB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/customers.js

@@ -0,0 +1,73 @@
+/**
+ * Customer resolution. Every Ingram site keys its Stripe customer to a local
+ * entity (an org or a user) by writing that id into the customer's `metadata`,
+ * then finds it back by metadata search — no local `stripe_customer_id` column is
+ * required just to locate the customer (though sites cache it for speed).
+ *
+ * The metadata key differs per site (`financica_organization_id`,
+ * `integrain_org_id`, …), so it is always passed in explicitly via
+ * {@link CustomerRef} rather than baked in here — that is the framework seam.
+ */
+import { getStripe } from "./client.js";
+/** The customer for `ref`, found by metadata search, or null if none exists yet.
+ *  Read paths use this so merely viewing a billing page never mints an empty
+ *  customer. */
+export async function findCustomer(ref, stripe = getStripe()) {
+    const found = await stripe.customers.search({
+        query: `metadata['${ref.metadataKey}']:'${ref.id}'`,
+        limit: 1,
+    });
+    return found.data[0] ?? null;
+}
+/** Like {@link findCustomer} but creates the customer on first use (checkout).
+ *  The local id is always written into metadata so {@link findCustomer} can find
+ *  it back. */
+export async function findOrCreateCustomer(ref, details = {}, stripe = getStripe()) {
+    const existing = await findCustomer(ref, stripe);
+    if (existing)
+        return existing;
+    const params = {
+        name: details.name ?? undefined,
+        email: details.email ?? undefined,
+        metadata: { [ref.metadataKey]: ref.id },
+    };
+    if (details.address?.line1 || details.address?.city) {
+        params.address = {
+            line1: details.address.line1 ?? undefined,
+            city: details.address.city ?? undefined,
+            postal_code: details.address.postal_code ?? undefined,
+            country: details.address.country ?? undefined,
+        };
+    }
+    const customer = await stripe.customers.create(params);
+    if (details.vatNumber) {
+        try {
+            await stripe.customers.createTaxId(customer.id, {
+                type: "eu_vat",
+                value: details.vatNumber,
+            });
+        }
+        catch {
+            // Non-fatal: the VAT number may be in a format Stripe rejects. We don't
+            // fail customer creation over a tax id we can re-attach later.
+        }
+    }
+    return customer;
+}
+/** Whether a customer has a billing address on file. Stripe requires one before
+ *  `tax_id_collection` can be enabled on a Checkout session. */
+export async function customerHasBillingAddress(customerId, stripe = getStripe()) {
+    const customer = await stripe.customers.retrieve(customerId);
+    if (customer.deleted)
+        return false;
+    return Boolean(customer.address?.line1);
+}
+/** Update a customer's name and billing address — used when details were missing
+ *  and got collected just before checkout. */
+export async function updateCustomerBillingAddress(customerId, opts, stripe = getStripe()) {
+    await stripe.customers.update(customerId, {
+        ...(opts.name ? { name: opts.name } : {}),
+        address: opts.address,
+    });
+}
+//# sourceMappingURL=customers.js.map

package/dist/customers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"customers.js","sourceRoot":"","sources":["../src/customers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAwBxC;;gBAEgB;AAChB,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,GAAgB,EAChB,SAAiB,SAAS,EAAE;IAE5B,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC;QAC3C,KAAK,EAAE,aAAa,GAAG,CAAC,WAAW,OAAO,GAAG,CAAC,EAAE,GAAG;QACnD,KAAK,EAAE,CAAC;KACR,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC9B,CAAC;AAED;;eAEe;AACf,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACzC,GAAgB,EAChB,UAA2B,EAAE,EAC7B,SAAiB,SAAS,EAAE;IAE5B,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACjD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAE9B,MAAM,MAAM,GAAgC;QAC3C,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,SAAS;QAC/B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,SAAS;QACjC,QAAQ,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE;KACvC,CAAC;IACF,IAAI,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC;QACrD,MAAM,CAAC,OAAO,GAAG;YAChB,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,SAAS;YACzC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,IAAI,SAAS;YACvC,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,WAAW,IAAI,SAAS;YACrD,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,SAAS;SAC7C,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEvD,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACvB,IAAI,CAAC;YACJ,MAAM,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,EAAE;gBAC/C,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,OAAO,CAAC,SAAS;aACxB,CAAC,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACR,wEAAwE;YACxE,+DAA+D;QAChE,CAAC;IACF,CAAC;IAED,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED;gEACgE;AAChE,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC9C,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,KAAK,CAAC;IACnC,OAAO,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AACzC,CAAC;AAED;8CAC8C;AAC9C,MAAM,CAAC,KAAK,UAAU,4BAA4B,CACjD,UAAkB,EAClB,IAQC,EACD,SAAiB,SAAS,EAAE;IAE5B,MAAM,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,EAAE;QACzC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,OAAO,EAAE,IAAI,CAAC,OAAO;KACrB,CAAC,CAAC;AACJ,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The one error type the credit ledger throws when a charge can't proceed.
+ * API routes turn it into a 402 Payment Required; server actions / chat map it to
+ * a user-facing message. Kept here (not in `credits.ts`) so the error shape can be
+ * imported without pulling in the Postgres-facing ledger code.
+ */
+/** Why a charge was denied. */
+export type DenyReason = "not_entitled" | "insufficient_credits";
+/** Default user-facing copy for a denial — short, actionable, points at the fix.
+ *  Sites can ignore this and write their own from the {@link DenyReason}. */
+export declare function denyMessage(reason: DenyReason): string;
+/** Thrown by the ledger's `requireCredits` when an entity can't pay for an
+ *  action. Carries the machine-readable {@link DenyReason} for status mapping. */
+export declare class BillingError extends Error {
+    readonly reason: DenyReason;
+    constructor(reason: DenyReason, message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+BAA+B;AAC/B,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,sBAAsB,CAAC;AAEjE;6EAC6E;AAC7E,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAItD;AAED;kFACkF;AAClF,qBAAa,YAAa,SAAQ,KAAK;IACtC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;gBAChB,MAAM,EAAE,UAAU,EAAE,OAAO,GAAE,MAA4B;CAKrE"}

package/dist/errors.js

@@ -0,0 +1,24 @@
+/**
+ * The one error type the credit ledger throws when a charge can't proceed.
+ * API routes turn it into a 402 Payment Required; server actions / chat map it to
+ * a user-facing message. Kept here (not in `credits.ts`) so the error shape can be
+ * imported without pulling in the Postgres-facing ledger code.
+ */
+/** Default user-facing copy for a denial — short, actionable, points at the fix.
+ *  Sites can ignore this and write their own from the {@link DenyReason}. */
+export function denyMessage(reason) {
+    return reason === "not_entitled"
+        ? "This workspace needs an active subscription. Subscribe in Settings → Billing."
+        : "You're out of credits. Buy a credit pack in Settings → Billing.";
+}
+/** Thrown by the ledger's `requireCredits` when an entity can't pay for an
+ *  action. Carries the machine-readable {@link DenyReason} for status mapping. */
+export class BillingError extends Error {
+    reason;
+    constructor(reason, message = denyMessage(reason)) {
+        super(message);
+        this.name = "BillingError";
+        this.reason = reason;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;6EAC6E;AAC7E,MAAM,UAAU,WAAW,CAAC,MAAkB;IAC7C,OAAO,MAAM,KAAK,cAAc;QAC/B,CAAC,CAAC,+EAA+E;QACjF,CAAC,CAAC,iEAAiE,CAAC;AACtE,CAAC;AAED;kFACkF;AAClF,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC7B,MAAM,CAAa;IAC5B,YAAY,MAAkB,EAAE,UAAkB,WAAW,CAAC,MAAM,CAAC;QACpE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;CACD"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { type BillingEnv, billingEnv, type StripeMode, stripeConfigured, stripeModeConfigured, } from "./keys.js";
+export { getStripe, resetStripeClients, stripeFor } from "./client.js";
+export { type CustomerDetails, type CustomerRef, customerHasBillingAddress, findCustomer, findOrCreateCustomer, updateCustomerBillingAddress, } from "./customers.js";
+export { displayAmount, priceByLookupKey, supportedCurrencies } from "./prices.js";
+export { type BillingCurrency, currencyForCountry, DEFAULT_CURRENCY, EUR_COUNTRIES, formatAmount, resolveCurrencyFromHeaders, } from "./currency.js";
+export { type CheckoutOptions, createCheckoutSession, createPortalSession, } from "./checkout.js";
+export { ACTIVE_SUBSCRIPTION_STATUSES, fetchSubscriptionForCustomer, fetchSubscriptionSummary, isActiveStatus, type SubscriptionSummary, summarizeSubscription, } from "./subscription.js";
+export { readStripeWebhook, verifyStripeWebhook, type WebhookResult, } from "./webhooks.js";
+export { type Balance, debitBalance, readBalance } from "./balance.js";
+export { BillingError, type DenyReason, denyMessage } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EACN,KAAK,UAAU,EACf,UAAU,EACV,KAAK,UAAU,EACf,gBAAgB,EAChB,oBAAoB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EACN,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,yBAAyB,EACzB,YAAY,EACZ,oBAAoB,EACpB,4BAA4B,GAC5B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EACN,KAAK,eAAe,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,0BAA0B,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,KAAK,eAAe,EACpB,qBAAqB,EACrB,mBAAmB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,4BAA4B,EAC5B,4BAA4B,EAC5B,wBAAwB,EACxB,cAAc,EACd,KAAK,mBAAmB,EACxB,qBAAqB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,aAAa,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+// The Ingram billing foundation. The stateless Stripe primitives are the main
+// entry; the Postgres credit ledger + event-dedup store live behind the
+// "@ingram-tech/nk-billing/credits" subpath so a site that only does
+// subscriptions or a Stripe-side wallet never imports a database concept.
+export { billingEnv, stripeConfigured, stripeModeConfigured, } from "./keys.js";
+export { getStripe, resetStripeClients, stripeFor } from "./client.js";
+export { customerHasBillingAddress, findCustomer, findOrCreateCustomer, updateCustomerBillingAddress, } from "./customers.js";
+export { displayAmount, priceByLookupKey, supportedCurrencies } from "./prices.js";
+export { currencyForCountry, DEFAULT_CURRENCY, EUR_COUNTRIES, formatAmount, resolveCurrencyFromHeaders, } from "./currency.js";
+export { createCheckoutSession, createPortalSession, } from "./checkout.js";
+export { ACTIVE_SUBSCRIPTION_STATUSES, fetchSubscriptionForCustomer, fetchSubscriptionSummary, isActiveStatus, summarizeSubscription, } from "./subscription.js";
+export { readStripeWebhook, verifyStripeWebhook, } from "./webhooks.js";
+export { debitBalance, readBalance } from "./balance.js";
+export { BillingError, denyMessage } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,wEAAwE;AACxE,qEAAqE;AACrE,0EAA0E;AAE1E,OAAO,EAEN,UAAU,EAEV,gBAAgB,EAChB,oBAAoB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAGN,yBAAyB,EACzB,YAAY,EACZ,oBAAoB,EACpB,4BAA4B,GAC5B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAEN,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,0BAA0B,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EAEN,qBAAqB,EACrB,mBAAmB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,4BAA4B,EAC5B,4BAA4B,EAC5B,wBAAwB,EACxB,cAAc,EAEd,qBAAqB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,iBAAiB,EACjB,mBAAmB,GAEnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAgB,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,YAAY,EAAmB,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/keys.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Environment contract for @ingram-tech/nk-billing.
+ *
+ * Following the "each package owns its own env validation" pattern (see
+ * @ingram-tech/nk-db and @ingram-tech/nk-auth). Env vars are external input, so
+ * we parse them with Zod (per docs/code-style.md) rather than reading
+ * `process.env` ad hoc.
+ *
+ * Two deployment shapes are supported, picked per call site, never both at once:
+ *
+ *   1. Single-mode (the default — financica / integrain / thornhill): one
+ *      account, one key. `getStripe()` reads STRIPE_SECRET_KEY and
+ *      `webhookSecret()` reads STRIPE_WEBHOOK_SECRET.
+ *
+ *   2. Dual-mode (cloud.ingram.tech, which is its own merchant of record and
+ *      runs the Stripe sandbox beside live): `stripeFor("test"|"live")` reads
+ *      STRIPE_SECRET_KEY_{TEST,LIVE} and `webhookSecret(mode)` reads
+ *      STRIPE_WEBHOOK_SECRET_{TEST,LIVE}.
+ *
+ * Nothing here hardcodes a price ID. Prices are resolved at runtime by their
+ * stable Stripe `lookup_key` (set on the Price in the infra Pulumi program), so
+ * the same key resolves in test and live even though their price IDs differ.
+ */
+/** Which Stripe account a dual-mode site is talking to. */
+export type StripeMode = "test" | "live";
+export interface BillingEnv {
+    secretKey?: string;
+    webhookSecret?: string;
+    testSecretKey?: string;
+    liveSecretKey?: string;
+    testWebhookSecret?: string;
+    liveWebhookSecret?: string;
+    apiVersion?: string;
+}
+/** Read and validate the billing env vars at once. Every field is optional —
+ *  billing degrades gracefully when unconfigured (see {@link stripeConfigured})
+ *  rather than throwing at import time. */
+export declare const billingEnv: (env?: NodeJS.ProcessEnv) => BillingEnv;
+/** Whether single-mode billing is configured (the secret key is present). Use to
+ *  open dev/local flows when no key is set, e.g. a no-op paywall. */
+export declare const stripeConfigured: (env?: NodeJS.ProcessEnv) => boolean;
+/** Whether the given dual-mode account is configured. */
+export declare const stripeModeConfigured: (mode: StripeMode, env?: NodeJS.ProcessEnv) => boolean;
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,2DAA2D;AAC3D,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAezC,MAAM,WAAW,UAAU;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;2CAE2C;AAC3C,eAAO,MAAM,UAAU,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,UAkBjE,CAAC;AAEF;qEACqE;AACrE,eAAO,MAAM,gBAAgB,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,OACzC,CAAC;AAEhC,yDAAyD;AACzD,eAAO,MAAM,oBAAoB,GAChC,MAAM,UAAU,EAChB,MAAK,MAAM,CAAC,UAAwB,KAClC,OACgF,CAAC"}

package/dist/keys.js

@@ -0,0 +1,64 @@
+/**
+ * Environment contract for @ingram-tech/nk-billing.
+ *
+ * Following the "each package owns its own env validation" pattern (see
+ * @ingram-tech/nk-db and @ingram-tech/nk-auth). Env vars are external input, so
+ * we parse them with Zod (per docs/code-style.md) rather than reading
+ * `process.env` ad hoc.
+ *
+ * Two deployment shapes are supported, picked per call site, never both at once:
+ *
+ *   1. Single-mode (the default — financica / integrain / thornhill): one
+ *      account, one key. `getStripe()` reads STRIPE_SECRET_KEY and
+ *      `webhookSecret()` reads STRIPE_WEBHOOK_SECRET.
+ *
+ *   2. Dual-mode (cloud.ingram.tech, which is its own merchant of record and
+ *      runs the Stripe sandbox beside live): `stripeFor("test"|"live")` reads
+ *      STRIPE_SECRET_KEY_{TEST,LIVE} and `webhookSecret(mode)` reads
+ *      STRIPE_WEBHOOK_SECRET_{TEST,LIVE}.
+ *
+ * Nothing here hardcodes a price ID. Prices are resolved at runtime by their
+ * stable Stripe `lookup_key` (set on the Price in the infra Pulumi program), so
+ * the same key resolves in test and live even though their price IDs differ.
+ */
+import { z } from "zod";
+const schema = z.object({
+    // Single-mode.
+    STRIPE_SECRET_KEY: z.string().min(1).optional(),
+    STRIPE_WEBHOOK_SECRET: z.string().min(1).optional(),
+    // Dual-mode.
+    STRIPE_SECRET_KEY_TEST: z.string().min(1).optional(),
+    STRIPE_SECRET_KEY_LIVE: z.string().min(1).optional(),
+    STRIPE_WEBHOOK_SECRET_TEST: z.string().min(1).optional(),
+    STRIPE_WEBHOOK_SECRET_LIVE: z.string().min(1).optional(),
+    // Optional pin; omitted → the stripe SDK's bundled API version.
+    STRIPE_API_VERSION: z.string().min(1).optional(),
+});
+/** Read and validate the billing env vars at once. Every field is optional —
+ *  billing degrades gracefully when unconfigured (see {@link stripeConfigured})
+ *  rather than throwing at import time. */
+export const billingEnv = (env = process.env) => {
+    const result = schema.safeParse(env);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+            .join(", ");
+        throw new Error(`@ingram-tech/nk-billing: invalid environment — ${issues}`);
+    }
+    const d = result.data;
+    return {
+        secretKey: d.STRIPE_SECRET_KEY,
+        webhookSecret: d.STRIPE_WEBHOOK_SECRET,
+        testSecretKey: d.STRIPE_SECRET_KEY_TEST,
+        liveSecretKey: d.STRIPE_SECRET_KEY_LIVE,
+        testWebhookSecret: d.STRIPE_WEBHOOK_SECRET_TEST,
+        liveWebhookSecret: d.STRIPE_WEBHOOK_SECRET_LIVE,
+        apiVersion: d.STRIPE_API_VERSION,
+    };
+};
+/** Whether single-mode billing is configured (the secret key is present). Use to
+ *  open dev/local flows when no key is set, e.g. a no-op paywall. */
+export const stripeConfigured = (env = process.env) => Boolean(env.STRIPE_SECRET_KEY);
+/** Whether the given dual-mode account is configured. */
+export const stripeModeConfigured = (mode, env = process.env) => Boolean(mode === "live" ? env.STRIPE_SECRET_KEY_LIVE : env.STRIPE_SECRET_KEY_TEST);
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IACvB,eAAe;IACf,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC/C,qBAAqB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACnD,aAAa;IACb,sBAAsB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACpD,sBAAsB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACpD,0BAA0B,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACxD,0BAA0B,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACxD,gEAAgE;IAChE,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAChD,CAAC,CAAC;AAYH;;2CAE2C;AAC3C,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAc,EAAE;IAC9E,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAChC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;aAC3D,IAAI,CAAC,IAAI,CAAC,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,kDAAkD,MAAM,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;IACtB,OAAO;QACN,SAAS,EAAE,CAAC,CAAC,iBAAiB;QAC9B,aAAa,EAAE,CAAC,CAAC,qBAAqB;QACtC,aAAa,EAAE,CAAC,CAAC,sBAAsB;QACvC,aAAa,EAAE,CAAC,CAAC,sBAAsB;QACvC,iBAAiB,EAAE,CAAC,CAAC,0BAA0B;QAC/C,iBAAiB,EAAE,CAAC,CAAC,0BAA0B;QAC/C,UAAU,EAAE,CAAC,CAAC,kBAAkB;KAChC,CAAC;AACH,CAAC,CAAC;AAEF;qEACqE;AACrE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAW,EAAE,CACjF,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;AAEhC,yDAAyD;AACzD,MAAM,CAAC,MAAM,oBAAoB,GAAG,CACnC,IAAgB,EAChB,MAAyB,OAAO,CAAC,GAAG,EAC1B,EAAE,CACZ,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC"}