@arnaudjnn/billing-tools 0.14.0

package/dist/machine-payment/index.js

@@ -0,0 +1,117 @@
+import { randomBytes } from "node:crypto";
+const PROBLEM_TYPE = "https://paymentauth.org/problems/payment-required";
+function challengeHeader(c) {
+    const parts = [
+        `id="${c.id}"`,
+        `method="${c.method}"`,
+        `intent="${c.intent}"`,
+        `amount="${c.amount}"`,
+        `currency="${c.currency}"`,
+        ...(c.payTo ? [`payTo="${c.payTo}"`] : []),
+    ];
+    return `Payment ${parts.join(", ")}`;
+}
+/** Read the payment credential the client presents on retry. MPP clients send
+ *  it in an `Authorization: Payment <credential>` header (we also accept the
+ *  common `X-Payment` header). */
+function readCredential(request) {
+    const auth = request.headers.get("authorization");
+    if (auth?.startsWith("Payment "))
+        return auth.slice(8).trim();
+    return request.headers.get("x-payment");
+}
+/** Build the MPP payment gate. Returns `requirePayment(request)` → either a 402
+ *  `Response` (payment needed / rejected / not-settled) or `{ paid: true,
+ *  challenge, receipt }` when settlement succeeds — the caller then serves the
+ *  paid resource. */
+export function createMachinePaymentHandler(opts) {
+    const methods = opts.methods ?? ["stripe"];
+    const currency = opts.currency ?? "usd";
+    async function buildChallenges(request) {
+        const amount = typeof opts.amount === "function" ? await opts.amount(request) : opts.amount;
+        return methods.map((method) => ({
+            id: `chal_${randomBytes(12).toString("hex")}`,
+            method,
+            intent: "charge",
+            amount,
+            currency,
+            payTo: method === "stripe" ? opts.networkId : opts.payToAddress,
+        }));
+    }
+    function paymentRequired(challenges, detail) {
+        const headers = new Headers({ "Content-Type": "application/problem+json", "Cache-Control": "no-store" });
+        for (const c of challenges)
+            headers.append("WWW-Authenticate", challengeHeader(c));
+        return new Response(JSON.stringify({
+            type: PROBLEM_TYPE,
+            title: "Payment Required",
+            status: 402,
+            detail,
+            challengeId: challenges[0]?.id,
+            accepts: challenges.map((c) => ({ method: c.method, amount: c.amount, currency: c.currency, payTo: c.payTo })),
+        }), { status: 402, headers });
+    }
+    async function requirePayment(request) {
+        const credential = readCredential(request);
+        const challenges = await buildChallenges(request);
+        if (!credential)
+            return paymentRequired(challenges, "Payment is required.");
+        if (!opts.settle) {
+            return paymentRequired(challenges, "Payment settlement is not enabled on this account yet.");
+        }
+        // Settle against the first challenge (single-method retries are typical).
+        const challenge = challenges[0];
+        try {
+            const result = await opts.settle(credential, challenge);
+            if (!result)
+                return paymentRequired(challenges, "Payment was declined.");
+            await opts.onPaid?.(challenge, result.receipt, request);
+            return { paid: true, challenge, receipt: result.receipt };
+        }
+        catch (e) {
+            return paymentRequired(challenges, `Payment failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return { requirePayment, buildChallenges };
+}
+/** `/payment.md` — the agent-facing "how to pay per request" narrative; the
+ *  payment equivalent of auth.md. */
+export function createPaymentMd(opts) {
+    return function paymentMd(request) {
+        const b = typeof opts.baseUrl === "function"
+            ? opts.baseUrl(request)
+            : (opts.baseUrl ??
+                (() => {
+                    const h = request.headers;
+                    const host = h.get("x-forwarded-host") ?? h.get("host") ?? new URL(request.url).host;
+                    const proto = h.get("x-forwarded-proto") ?? (host.startsWith("localhost") ? "http" : "https");
+                    return `${proto}://${host}`;
+                })());
+        const methods = (opts.methods ?? ["stripe"]).join(", ");
+        const path = opts.resourcePath ?? "/mcp";
+        const body = `# ${opts.productName} — payment.md
+
+This service accepts per-request machine payments via [MPP](https://mpp.dev) (the Machine Payments Protocol). As an agent you can pay for a resource on demand — no account or API key required.
+
+## Flow
+
+1. Request the paid resource:
+   \`\`\`http
+   POST ${b}${path}
+   \`\`\`
+2. If payment is required you get **HTTP 402** with one \`WWW-Authenticate: Payment …\` header per accepted method and an \`application/problem+json\` body describing the amount, currency, and \`payTo\`.
+3. Authorize the payment (methods: ${methods}) and retry the request with the credential:
+   \`\`\`http
+   POST ${b}${path}
+   Authorization: Payment <credential>
+   \`\`\`
+4. On success you get the resource plus a \`Payment-Receipt\` header.
+
+Accepted currency: ${opts.currency ?? "usd"}. See https://docs.stripe.com/payments/machine for client tooling.
+`;
+        return new Response(body, {
+            headers: { "content-type": "text/markdown; charset=utf-8", "cache-control": "public, max-age=3600" },
+        });
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/machine-payment/index.js.map

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

package/dist/magic-auth.d.ts

@@ -0,0 +1,4 @@
+import type { BillingUser } from "./types.js";
+export declare function sendMagicAuth(email: string): Promise<void>;
+export declare function verifyMagicAuth(email: string, code: string): Promise<BillingUser>;
+//# sourceMappingURL=magic-auth.d.ts.map

package/dist/magic-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"magic-auth.d.ts","sourceRoot":"","sources":["../src/magic-auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAQ9C,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhE;AAGD,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAcvF"}

package/dist/magic-auth.js

@@ -0,0 +1,30 @@
+import { getWorkOS as workos } from "./workos.js";
+// WorkOS magic-auth — the common auth substrate for billing-tools. The host
+// app's storage (WorkOS orgs vs Postgres) only matters *after* the user is
+// verified; that post-auth step is the adapter's ensureOrgForUser.
+// Step 1: ensure the user exists in WorkOS and email them a 6-digit code.
+export async function sendMagicAuth(email) {
+    const wos = workos();
+    const users = await wos.userManagement.listUsers({ email });
+    if (users.data.length === 0) {
+        await wos.userManagement.createUser({ email, emailVerified: false });
+    }
+    await wos.userManagement.createMagicAuth({ email });
+}
+// Step 2: verify the code, returning the WorkOS user.
+export async function verifyMagicAuth(email, code) {
+    const res = await workos().userManagement.authenticateWithMagicAuth({
+        code,
+        email,
+        clientId: process.env.WORKOS_CLIENT_ID,
+    });
+    const u = res.user;
+    return {
+        id: u.id,
+        email: u.email,
+        firstName: u.firstName,
+        lastName: u.lastName,
+        profilePictureUrl: u.profilePictureUrl,
+    };
+}
+//# sourceMappingURL=magic-auth.js.map

package/dist/magic-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"magic-auth.js","sourceRoot":"","sources":["../src/magic-auth.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAElD,4EAA4E;AAC5E,2EAA2E;AAC3E,mEAAmE;AAEnE,0EAA0E;AAC1E,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAa;IAC/C,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;IACrB,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5D,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,GAAG,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,GAAG,CAAC,cAAc,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AACtD,CAAC;AAED,sDAAsD;AACtD,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAAa,EAAE,IAAY;IAC/D,MAAM,GAAG,GAAG,MAAM,MAAM,EAAE,CAAC,cAAc,CAAC,yBAAyB,CAAC;QAClE,IAAI;QACJ,KAAK;QACL,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAiB;KACxC,CAAC,CAAC;IACH,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC;IACnB,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,iBAAiB,EAAE,CAAC,CAAC,iBAAiB;KACvC,CAAC;AACJ,CAAC"}

package/dist/mirror.d.ts

@@ -0,0 +1,35 @@
+export type MirrorQueryResult = {
+    rows: Array<Record<string, unknown>>;
+    rowCount: number | null;
+};
+export type MirrorQuery = (sql: string, params: unknown[]) => Promise<MirrorQueryResult>;
+export interface MirrorOptions {
+    /** Table name (identifier — validated). */
+    table: string;
+    /** WorkOS id column, e.g. "workos_org_id" or "workos_user_id". */
+    idColumn: string;
+    /** JSON metadata column. Default "workos_metadata". */
+    metadataColumn?: string;
+    /** Optional map of WorkOS-resource field → DB column, synced by syncResource
+     *  (e.g. { name: "name" } to keep a workspaces.name column in sync). */
+    columns?: Record<string, string>;
+    /** Query executor returning { rows, rowCount }. Keeps this package pg-free. */
+    query: MirrorQuery;
+}
+export interface Mirror {
+    /** Insert the row from id + metadata if absent (no-op if it exists). */
+    ensure(workosId: string, metadata?: Record<string, unknown>): Promise<void>;
+    /** Full row, or null. */
+    get(workosId: string): Promise<Record<string, unknown> | null>;
+    /** Just the metadata blob, or null if the row is absent. */
+    getMetadata(workosId: string): Promise<Record<string, unknown> | null>;
+    /** Overwrite the metadata blob on an existing row. */
+    setMetadata(workosId: string, metadata: Record<string, unknown>): Promise<void>;
+    /** Sync a WorkOS resource onto the existing row: the mapped `columns` fields
+     *  + the metadata blob. Update-only (rows are created by the app). */
+    syncResource(workosId: string, resource: Record<string, unknown>): Promise<void>;
+    /** Delete the row. */
+    remove(workosId: string): Promise<void>;
+}
+export declare function createMirror(opts: MirrorOptions): Mirror;
+//# sourceMappingURL=mirror.d.ts.map

package/dist/mirror.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirror.d.ts","sourceRoot":"","sources":["../src/mirror.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,iBAAiB,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAClG,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEzF,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;4EACwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,+EAA+E;IAC/E,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,MAAM,WAAW,MAAM;IACrB,wEAAwE;IACxE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,yBAAyB;IACzB,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IAC/D,4DAA4D;IAC5D,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACvE,sDAAsD;IACtD,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChF;0EACsE;IACtE,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjF,sBAAsB;IACtB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAMD,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAiDxD"}

package/dist/mirror.js

@@ -0,0 +1,63 @@
+// Generic, table-agnostic DB mirror for WorkOS entities. WorkOS stays the
+// source of truth; an app that keeps a database shadows each WorkOS org/user in
+// a local row so it can join/query without a round-trip. This helper owns just
+// two columns — the WorkOS id and a `workos_metadata` JSON blob — and leaves
+// every other column on the table to the app.
+//
+// It's DB-free: you pass a `query` executor (e.g. a thin wrapper over `pg`), so
+// billing-tools never depends on a database driver. Two conventional shapes:
+//   - org mirror:  { workos_org_id, workos_metadata }
+//   - user mirror: { workos_user_id, workos_metadata }
+//
+// `ensure` inserts a row from the id + metadata alone, so it only fits tables
+// whose other columns are nullable/defaulted (e.g. a users table). For a table
+// with required app columns (e.g. a workspaces table the app inserts itself),
+// use `setMetadata` to update the blob on the already-created row.
+// Identifiers are developer config (not user input), but validate anyway since
+// they're interpolated into SQL.
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export function createMirror(opts) {
+    const { table, idColumn, query } = opts;
+    const meta = opts.metadataColumn ?? "workos_metadata";
+    const columns = opts.columns ?? {};
+    for (const ident of [table, idColumn, meta, ...Object.values(columns)]) {
+        if (!IDENTIFIER.test(ident)) {
+            throw new Error(`createMirror: invalid SQL identifier "${ident}"`);
+        }
+    }
+    return {
+        async ensure(workosId, metadata = {}) {
+            await query(`INSERT INTO ${table} (${idColumn}, ${meta}) VALUES ($1, $2)
+         ON CONFLICT (${idColumn}) DO NOTHING`, [workosId, JSON.stringify(metadata)]);
+        },
+        async get(workosId) {
+            const r = await query(`SELECT * FROM ${table} WHERE ${idColumn} = $1`, [workosId]);
+            return r.rows[0] ?? null;
+        },
+        async getMetadata(workosId) {
+            const r = await query(`SELECT ${meta} AS metadata FROM ${table} WHERE ${idColumn} = $1`, [workosId]);
+            return r.rows[0]?.metadata ?? null;
+        },
+        async setMetadata(workosId, metadata) {
+            await query(`UPDATE ${table} SET ${meta} = $2 WHERE ${idColumn} = $1`, [
+                workosId,
+                JSON.stringify(metadata),
+            ]);
+        },
+        async syncResource(workosId, resource) {
+            const params = [workosId];
+            const sets = [];
+            for (const [field, column] of Object.entries(columns)) {
+                params.push(resource[field] ?? null);
+                sets.push(`${column} = $${params.length}`);
+            }
+            params.push(JSON.stringify(resource.metadata ?? {}));
+            sets.push(`${meta} = $${params.length}`);
+            await query(`UPDATE ${table} SET ${sets.join(", ")} WHERE ${idColumn} = $1`, params);
+        },
+        async remove(workosId) {
+            await query(`DELETE FROM ${table} WHERE ${idColumn} = $1`, [workosId]);
+        },
+    };
+}
+//# sourceMappingURL=mirror.js.map

package/dist/mirror.js.map

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

package/dist/plans.d.ts

@@ -0,0 +1,38 @@
+export interface PlanDef {
+    /** Max members per workspace. null = unlimited. */
+    seats: number | null;
+    /** Included tokens granted per seat, per billing cycle. */
+    tokensPerSeat: number;
+    /** Recurring price in the smallest currency unit (cents). 0 = free (no Stripe price). */
+    price: {
+        monthly: number;
+        yearly: number;
+    };
+}
+export type PlansConfig = Record<string, PlanDef>;
+export type BillingInterval = "monthly" | "yearly";
+export declare const lookupKeyFor: (plan: string, interval: BillingInterval) => string;
+export interface EnsuredPrice {
+    plan: string;
+    interval: BillingInterval;
+    priceId: string;
+    productId: string;
+    amount: number;
+    lookupKey: string;
+}
+/** Idempotently create/reconcile Stripe products + prices for the paid plans.
+ *  Returns the resolved price for every paid plan × interval. Free plans (both
+ *  prices 0) create no Stripe objects. Safe to call on every boot / first use. */
+export declare function ensurePlans(plans: PlansConfig, opts?: {
+    currency?: string;
+}): Promise<EnsuredPrice[]>;
+/** Resolve the current Stripe price id for a plan + interval (via lookup_key).
+ *  Returns null for a free/absent price. */
+export declare function planPriceId(plan: string, interval: BillingInterval): Promise<string | null>;
+/** Reverse-map a Stripe price id → plan key (via the price's metadata). */
+export declare function planForPriceId(priceId: string): Promise<string | null>;
+/** Seat limit for a plan (null = unlimited, undefined plan = null). */
+export declare function seatLimit(plans: PlansConfig, plan: string): number | null;
+/** Included tokens for `seatCount` members on a plan (per cycle). */
+export declare function includedTokens(plans: PlansConfig, plan: string, seatCount: number): number;
+//# sourceMappingURL=plans.d.ts.map

package/dist/plans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plans.d.ts","sourceRoot":"","sources":["../src/plans.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,OAAO;IACtB,mDAAmD;IACnD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5C;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAClD,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,QAAQ,CAAC;AASnD,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,EAAE,UAAU,eAAe,KAAG,MAChD,CAAC;AAExB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,eAAe,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAsBD;;kFAEkF;AAClF,wBAAsB,WAAW,CAC/B,KAAK,EAAE,WAAW,EAClB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,YAAY,EAAE,CAAC,CAsDzB;AAwBD;4CAC4C;AAC5C,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,eAAe,GACxB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOxB;AAED,2EAA2E;AAC3E,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAO5E;AAED,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEzE;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,MAAM,CAIR"}

package/dist/plans.js

@@ -0,0 +1,132 @@
+import { getStripe } from "./billing.js";
+const INTERVALS = ["monthly", "yearly"];
+const STRIPE_INTERVAL = {
+    monthly: "month",
+    yearly: "year",
+};
+const MANAGED_BY = "billing-tools";
+export const lookupKeyFor = (plan, interval) => `${plan}_${interval}`;
+const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+/** The single managed Stripe product for a plan (reuse across price versions),
+ *  discovered via any existing managed price's product. */
+async function findPlanProduct(stripe, plan) {
+    for (const interval of INTERVALS) {
+        const found = await stripe.prices.list({
+            lookup_keys: [lookupKeyFor(plan, interval)],
+            limit: 1,
+            expand: ["data.product"],
+        });
+        const p = found.data[0];
+        if (p)
+            return typeof p.product === "string" ? p.product : p.product.id;
+    }
+    return null;
+}
+/** Idempotently create/reconcile Stripe products + prices for the paid plans.
+ *  Returns the resolved price for every paid plan × interval. Free plans (both
+ *  prices 0) create no Stripe objects. Safe to call on every boot / first use. */
+export async function ensurePlans(plans, opts = {}) {
+    const stripe = getStripe();
+    const currency = (opts.currency ?? "usd").toLowerCase();
+    const result = [];
+    const wanted = new Set();
+    for (const [plan, def] of Object.entries(plans)) {
+        let productId = await findPlanProduct(stripe, plan);
+        for (const interval of INTERVALS) {
+            const amount = def.price[interval];
+            if (!amount || amount <= 0)
+                continue; // free interval — no Stripe price
+            const lookupKey = lookupKeyFor(plan, interval);
+            wanted.add(lookupKey);
+            const existing = (await stripe.prices.list({ lookup_keys: [lookupKey], active: true, limit: 1 })).data[0];
+            const matches = existing &&
+                existing.unit_amount === amount &&
+                existing.currency === currency &&
+                existing.recurring?.interval === STRIPE_INTERVAL[interval];
+            if (existing && matches) {
+                productId =
+                    typeof existing.product === "string" ? existing.product : existing.product.id;
+                result.push({ plan, interval, priceId: existing.id, productId, amount, lookupKey });
+                continue;
+            }
+            if (!productId) {
+                const product = await stripe.products.create({
+                    name: cap(plan),
+                    metadata: { managedBy: MANAGED_BY, plan },
+                });
+                productId = product.id;
+            }
+            // Create the new price and move the lookup_key onto it (frees it from the
+            // old price), then archive the old price. Subscribers on it are untouched.
+            const created = await stripe.prices.create({
+                product: productId,
+                currency,
+                unit_amount: amount,
+                recurring: { interval: STRIPE_INTERVAL[interval] },
+                lookup_key: lookupKey,
+                transfer_lookup_key: true,
+                metadata: { managedBy: MANAGED_BY, plan, interval },
+            });
+            if (existing)
+                await stripe.prices.update(existing.id, { active: false });
+            result.push({ plan, interval, priceId: created.id, productId, amount, lookupKey });
+        }
+    }
+    await archiveOrphans(stripe, wanted);
+    return result;
+}
+/** Archive managed prices whose lookup_key is no longer configured (a plan or
+ *  interval you removed), and deactivate now-empty managed products. */
+async function archiveOrphans(stripe, wanted) {
+    const managedProducts = new Set();
+    for await (const price of stripe.prices.list({ active: true, limit: 100 })) {
+        if (price.metadata?.managedBy !== MANAGED_BY)
+            continue;
+        const productId = typeof price.product === "string" ? price.product : price.product.id;
+        if (price.lookup_key && wanted.has(price.lookup_key)) {
+            managedProducts.add(productId);
+            continue;
+        }
+        await stripe.prices.update(price.id, { active: false });
+    }
+    // A managed product with no remaining wanted price → archive it.
+    for await (const product of stripe.products.list({ active: true, limit: 100 })) {
+        if (product.metadata?.managedBy !== MANAGED_BY)
+            continue;
+        if (!managedProducts.has(product.id)) {
+            await stripe.products.update(product.id, { active: false }).catch(() => { });
+        }
+    }
+}
+/** Resolve the current Stripe price id for a plan + interval (via lookup_key).
+ *  Returns null for a free/absent price. */
+export async function planPriceId(plan, interval) {
+    const r = await getStripe().prices.list({
+        lookup_keys: [lookupKeyFor(plan, interval)],
+        active: true,
+        limit: 1,
+    });
+    return r.data[0]?.id ?? null;
+}
+/** Reverse-map a Stripe price id → plan key (via the price's metadata). */
+export async function planForPriceId(priceId) {
+    try {
+        const price = await getStripe().prices.retrieve(priceId);
+        return price.metadata?.plan ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Seat limit for a plan (null = unlimited, undefined plan = null). */
+export function seatLimit(plans, plan) {
+    return plans[plan]?.seats ?? null;
+}
+/** Included tokens for `seatCount` members on a plan (per cycle). */
+export function includedTokens(plans, plan, seatCount) {
+    const def = plans[plan];
+    if (!def)
+        return 0;
+    return def.tokensPerSeat * Math.max(1, seatCount);
+}
+//# sourceMappingURL=plans.js.map

package/dist/plans.js.map

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

package/dist/routes/mcp.d.ts

@@ -0,0 +1,19 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { BillingAdapter } from "../types.js";
+export interface McpTransportOptions {
+    register: (server: McpServer) => void;
+    adapter: BillingAdapter;
+    realm?: string;
+    /** Prefix that marks a raw API key (vs an OAuth JWT). Default "sk_". */
+    apiKeyPrefix?: string;
+    maxDuration?: number;
+    /** Advertise the auth.md PRM discovery doc in the 401 WWW-Authenticate header
+     *  (`resource_metadata="…"`) so agents can bootstrap. String or per-request. */
+    resourceMetadata?: string | ((request: Request) => string);
+}
+export declare function createMcpTransport(opts: McpTransportOptions): {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+    maxDuration: number;
+};
+//# sourceMappingURL=mcp.d.ts.map

package/dist/routes/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/routes/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQlD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC;IACtC,OAAO,EAAE,cAAc,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;oFACgF;IAChF,gBAAgB,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,CAAC;CAC5D;AAOD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB;mBAqB1B,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;oBAA3B,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;;EAgB5D"}

package/dist/routes/mcp.js

@@ -0,0 +1,39 @@
+import { runWithAuth, runWithResolvedOrg } from "../auth.js";
+function wwwAuth(realm, resourceMetadata) {
+    const base = `Bearer realm="${realm}", error="invalid_token"`;
+    return resourceMetadata ? `${base}, resource_metadata="${resourceMetadata}"` : base;
+}
+export function createMcpTransport(opts) {
+    const realm = opts.realm ?? "billing-tools";
+    const apiKeyPrefix = opts.apiKeyPrefix ?? "sk_";
+    let handlerPromise = null;
+    async function getHandler() {
+        if (!handlerPromise) {
+            handlerPromise = import("mcp-handler").then(({ createMcpHandler }) => createMcpHandler((server) => opts.register(server), {}, { basePath: "/", maxDuration: opts.maxDuration ?? 60 }));
+        }
+        return handlerPromise;
+    }
+    async function withAuthHeader(res, rm) {
+        if (res.status !== 401)
+            return res;
+        const headers = new Headers(res.headers);
+        if (!headers.has("WWW-Authenticate"))
+            headers.set("WWW-Authenticate", wwwAuth(realm, rm));
+        return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+    }
+    async function handler(request) {
+        const mcp = await getHandler();
+        const authHeader = request.headers.get("authorization");
+        const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : null;
+        const rm = typeof opts.resourceMetadata === "function" ? opts.resourceMetadata(request) : opts.resourceMetadata;
+        if (token && !token.startsWith(apiKeyPrefix) && opts.adapter.resolveOauthOrg) {
+            const orgId = await opts.adapter.resolveOauthOrg(token);
+            if (orgId)
+                return runWithResolvedOrg(authHeader, orgId, () => mcp(request));
+        }
+        const res = await runWithAuth(authHeader, () => mcp(request));
+        return withAuthHeader(res, rm);
+    }
+    return { GET: handler, POST: handler, maxDuration: opts.maxDuration ?? 60 };
+}
+//# sourceMappingURL=mcp.js.map

package/dist/routes/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/routes/mcp.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAmB7D,SAAS,OAAO,CAAC,KAAa,EAAE,gBAAyB;IACvD,MAAM,IAAI,GAAG,iBAAiB,KAAK,0BAA0B,CAAC;IAC9D,OAAO,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI,wBAAwB,gBAAgB,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACtF,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAyB;IAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,eAAe,CAAC;IAC5C,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,KAAK,CAAC;IAChD,IAAI,cAAc,GAAwD,IAAI,CAAC;IAE/E,KAAK,UAAU,UAAU;QACvB,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,cAAc,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,gBAAgB,EAAE,EAAE,EAAE,CACnE,gBAAgB,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC,CAChH,CAAC;QACJ,CAAC;QACD,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,KAAK,UAAU,cAAc,CAAC,GAAa,EAAE,EAAW;QACtD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,GAAG,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;QAC1F,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7F,CAAC;IAED,KAAK,UAAU,OAAO,CAAC,OAAgB;QACrC,MAAM,GAAG,GAAG,MAAM,UAAU,EAAE,CAAC;QAC/B,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,UAAU,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7E,MAAM,EAAE,GACN,OAAO,IAAI,CAAC,gBAAgB,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC;QAEvG,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;YAC7E,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;YACxD,IAAI,KAAK;gBAAE,OAAO,kBAAkB,CAAC,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QAC9E,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QAC9D,OAAO,cAAc,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC;AAC9E,CAAC"}

package/dist/routes/rest.d.ts

@@ -0,0 +1,20 @@
+export interface Dispatcher {
+    dispatchTool(name: string, args: Record<string, unknown>): Promise<unknown>;
+    getToolNames(): string[];
+}
+export declare function createToolListHandler(opts: {
+    dispatcher: Dispatcher;
+    toolCosts?: Record<string, number>;
+}): (request: Request) => Promise<Response>;
+export declare function createToolDispatchHandler(opts: {
+    dispatcher: Dispatcher;
+    realm?: string;
+    /** Advertise the auth.md PRM discovery doc in the 401 WWW-Authenticate header
+     *  (`resource_metadata="…"`) so agents can bootstrap. String or per-request. */
+    resourceMetadata?: string | ((request: Request) => string);
+}): (request: Request, ctx: {
+    params: Promise<{
+        tool: string;
+    }>;
+}) => Promise<Response>;
+//# sourceMappingURL=rest.d.ts.map

package/dist/routes/rest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest.d.ts","sourceRoot":"","sources":["../../src/routes/rest.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5E,YAAY,IAAI,MAAM,EAAE,CAAC;CAC1B;AAQD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC,IACe,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAanD;AAUD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;oFACgF;IAChF,gBAAgB,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,CAAC;CAC5D,IAGG,SAAS,OAAO,EAChB,KAAK;IAAE,MAAM,EAAE,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,KACzC,OAAO,CAAC,QAAQ,CAAC,CA+BrB"}

package/dist/routes/rest.js

@@ -0,0 +1,66 @@
+import { runWithAuth } from "../auth.js";
+import { ToolValidationError } from "../dispatch.js";
+function wwwAuth(realm, resourceMetadata) {
+    const base = `Bearer realm="${realm}", error="invalid_token"`;
+    return resourceMetadata ? `${base}, resource_metadata="${resourceMetadata}"` : base;
+}
+// GET /api/v0 → { tools: [{ name, cost }] }
+export function createToolListHandler(opts) {
+    return async (request) => {
+        const authHeader = request.headers.get("authorization");
+        return runWithAuth(authHeader, async () => {
+            try {
+                const names = opts.dispatcher.getToolNames();
+                return Response.json({
+                    tools: names.map((name) => ({ name, cost: opts.toolCosts?.[name] ?? 0 })),
+                });
+            }
+            catch (err) {
+                return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 500 });
+            }
+        });
+    };
+}
+function isUnauthorizedResult(result) {
+    if (!result || typeof result !== "object")
+        return false;
+    const r = result;
+    if (!r.isError || !Array.isArray(r.content))
+        return false;
+    return r.content.some((c) => typeof c.text === "string" && /\bUnauthorized\b/i.test(c.text));
+}
+// POST /api/v0/[tool] → dispatch. Next passes ctx.params as a Promise.
+export function createToolDispatchHandler(opts) {
+    const realm = opts.realm ?? "billing-tools";
+    return async (request, ctx) => {
+        const { tool } = await ctx.params;
+        const authHeader = request.headers.get("authorization");
+        const rm = typeof opts.resourceMetadata === "function" ? opts.resourceMetadata(request) : opts.resourceMetadata;
+        return runWithAuth(authHeader, async () => {
+            try {
+                const body = await request.json().catch(() => ({}));
+                const result = await opts.dispatcher.dispatchTool(tool, body);
+                if (result && typeof result === "object" && result.status === "try_again_later") {
+                    const retryAfter = result.retry_after_seconds;
+                    return Response.json(result, {
+                        status: 429,
+                        headers: retryAfter ? { "Retry-After": String(retryAfter) } : undefined,
+                    });
+                }
+                if (isUnauthorizedResult(result)) {
+                    return Response.json(result, { status: 401, headers: { "WWW-Authenticate": wwwAuth(realm, rm) } });
+                }
+                return Response.json(result);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                if (/\bUnauthorized\b|\b401\b/i.test(message)) {
+                    return Response.json({ error: message }, { status: 401, headers: { "WWW-Authenticate": wwwAuth(realm, rm) } });
+                }
+                const status = err instanceof ToolValidationError ? 400 : message.includes("Unknown tool") ? 404 : 500;
+                return Response.json({ error: message }, { status });
+            }
+        });
+    };
+}
+//# sourceMappingURL=rest.js.map