@suluk/stripe 0.1.0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@suluk/stripe",
+  "version": "0.1.0",
+  "description": "First-class Stripe via a swappable PaymentProvider: usage-based billing (Billing Meters + meter events), customers, metered prices, subscriptions, webhooks — and a bridge from @suluk/cost to Stripe usage. Other processors follow Stripe. CANDIDATE tooling.",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+  ".": "./src/index.ts"
+},
+"dependencies": {
+"@suluk/cost": "0.1.0"
+},
+"peerDependencies": {
+"stripe": "^17.0.0 || ^18.0.0"
+},
+"peerDependenciesMeta": {
+"stripe": {
+"optional": true
+}
+},
+"devDependencies": {
+"@types/bun": "latest"
+},
+"scripts": {
+"test": "bun test",
+"typecheck": "tsc --noEmit -p ."
+}
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @suluk/stripe — first-class Stripe behind a swappable PaymentProvider. Usage-based billing via the modern
+ * Billing Meters API (meters + meter events + metered prices), customers, subscriptions, and webhooks — plus
+ * a bridge that turns @suluk/cost events into the usage you bill on. Stripe is the reference processor; the
+ * PaymentProvider interface is the swap point for the others that follow it. CANDIDATE tooling.
+ */
+export type { PaymentProvider, StripeLike, Customer, Subscription, WebhookEvent } from "./types";
+export {
+  customerParams, productParams, meterParams, meteredPriceParams, subscriptionParams, meterEventParams,
+  setupUsageBilling, stripeProvider, usageEventsFromCost, reportCostUsage,
+  type UsageBillingConfig, type CostBillingConfig,
+} from "./stripe";

package/src/stripe.ts

@@ -0,0 +1,125 @@
+/**
+ * First-class Stripe. The param builders are PURE (exact Stripe API payloads, testable with no SDK); the
+ * provider + setup call a duck-typed StripeLike client (the real `stripe` SDK satisfies it). Usage-based
+ * billing uses the modern Billing Meters API (meters + meter events + metered prices), which is what other
+ * processors are converging on. The cost bridge turns @suluk/cost events into the usage you bill on.
+ */
+import type { CostEvent } from "@suluk/cost";
+import type { PaymentProvider, StripeLike } from "./types";
+
+type Aggregation = "sum" | "count" | "last";
+
+// ── pure param builders (produce exact Stripe API params) ─────────────────────────────────────────────
+export function customerParams(i: { email?: string; name?: string; metadata?: Record<string, string> }): Record<string, unknown> {
+  const p: Record<string, unknown> = {};
+  if (i.email) p.email = i.email;
+  if (i.name) p.name = i.name;
+  if (i.metadata) p.metadata = i.metadata;
+  return p;
+}
+
+export function productParams(name: string): Record<string, unknown> {
+  return { name };
+}
+
+/** A Billing Meter — aggregates incoming meter events for one event_name (default: sum). */
+export function meterParams(eventName: string, displayName: string, formula: Aggregation = "sum"): Record<string, unknown> {
+  return { display_name: displayName, event_name: eventName, default_aggregation: { formula } };
+}
+
+/** A METERED recurring price tied to a meter (usage_type:"metered"). unitAmountDecimal is per aggregated unit. */
+export function meteredPriceParams(i: { productId: string; currency: string; unitAmountDecimal: string; meterId: string; interval?: "day" | "week" | "month" | "year" }): Record<string, unknown> {
+  return {
+    product: i.productId,
+    currency: i.currency,
+    unit_amount_decimal: i.unitAmountDecimal,
+    recurring: { interval: i.interval ?? "month", usage_type: "metered", meter: i.meterId },
+  };
+}
+
+export function subscriptionParams(i: { customerId: string; priceId: string }): Record<string, unknown> {
+  return { customer: i.customerId, items: [{ price: i.priceId }] };
+}
+
+/** A meter event — reports usage for a customer (the `value` is what you price on). */
+export function meterEventParams(i: { eventName: string; customerId: string; value: number; at?: number }): Record<string, unknown> {
+  const payload: Record<string, unknown> = { stripe_customer_id: i.customerId, value: String(i.value) };
+  const p: Record<string, unknown> = { event_name: i.eventName, payload };
+  if (i.at != null) p.timestamp = Math.floor(i.at / 1000); // unix seconds
+  return p;
+}
+
+// ── flows over a StripeLike client ────────────────────────────────────────────────────────────────────
+export interface UsageBillingConfig {
+  productName: string;
+  eventName: string;
+  currency: string;
+  /** Price per aggregated unit, as a decimal string (e.g. "0.000002" to charge per cost-µ$). */
+  unitAmountDecimal: string;
+  interval?: "day" | "week" | "month" | "year";
+  aggregation?: Aggregation;
+}
+
+/** Wire up usage-based billing: a product + a meter + a metered price. Returns the ids to subscribe customers. */
+export async function setupUsageBilling(client: StripeLike, cfg: UsageBillingConfig): Promise<{ productId: string; meterId: string; priceId: string; eventName: string }> {
+  const product = await client.products.create(productParams(cfg.productName));
+  const meter = await client.billing.meters.create(meterParams(cfg.eventName, `${cfg.productName} usage`, cfg.aggregation ?? "sum"));
+  const price = await client.prices.create(meteredPriceParams({ productId: product.id, currency: cfg.currency, unitAmountDecimal: cfg.unitAmountDecimal, meterId: meter.id, interval: cfg.interval }));
+  return { productId: product.id, meterId: meter.id, priceId: price.id, eventName: cfg.eventName };
+}
+
+/** The Stripe PaymentProvider (the swap point — other processors implement the same interface). */
+export function stripeProvider(client: StripeLike, cfg: { webhookSecret?: string } = {}): PaymentProvider {
+  return {
+    name: "stripe",
+    async createCustomer(i) { return { id: (await client.customers.create(customerParams(i))).id }; },
+    async subscribeMetered(i) { return { id: (await client.subscriptions.create(subscriptionParams(i))).id }; },
+    async reportUsage(i) { await client.billing.meterEvents.create(meterEventParams(i)); },
+    verifyWebhook(body, signature) {
+      const e = client.webhooks.constructEvent(body, signature, cfg.webhookSecret ?? "");
+      return { type: e.type, data: e.data };
+    },
+  };
+}
+
+// ── the cost → Stripe bridge ──────────────────────────────────────────────────────────────────────────
+export interface CostBillingConfig {
+  eventName: string;
+  /** principal id → Stripe customer id. Principals without a customer are skipped. */
+  customerOf: (principal: string) => string | undefined;
+  /** What to meter: the raw cost in µ$ (default — price per-µ$ for a markup) or the request count. */
+  basis?: "cost-micro-usd" | "request-count";
+}
+
+/** Aggregate cost events per principal into Stripe meter-event params — the usage you report to bill on. */
+export function usageEventsFromCost(events: CostEvent[], cfg: CostBillingConfig): Record<string, unknown>[] {
+  const byPrincipal = new Map<string, number>();
+  for (const e of events) {
+    if (!e.principal) continue;
+    const v = cfg.basis === "request-count" ? 1 : e.totalMicroUsd;
+    byPrincipal.set(e.principal, (byPrincipal.get(e.principal) ?? 0) + v);
+  }
+  const out: Record<string, unknown>[] = [];
+  for (const [principal, value] of byPrincipal) {
+    const customerId = cfg.customerOf(principal);
+    if (customerId) out.push(meterEventParams({ eventName: cfg.eventName, customerId, value }));
+  }
+  return out;
+}
+
+/** Report each principal's accrued cost-usage to the provider (one meter event per principal). */
+export async function reportCostUsage(provider: PaymentProvider, events: CostEvent[], cfg: CostBillingConfig): Promise<number> {
+  const byPrincipal = new Map<string, number>();
+  for (const e of events) {
+    if (!e.principal) continue;
+    byPrincipal.set(e.principal, (byPrincipal.get(e.principal) ?? 0) + (cfg.basis === "request-count" ? 1 : e.totalMicroUsd));
+  }
+  let reported = 0;
+  for (const [principal, value] of byPrincipal) {
+    const customerId = cfg.customerOf(principal);
+    if (!customerId) continue;
+    await provider.reportUsage({ customerId, eventName: cfg.eventName, value });
+    reported++;
+  }
+  return reported;
+}

package/src/types.ts

@@ -0,0 +1,38 @@
+/**
+ * The payment abstraction — SWAPPABLE by design. Stripe is the first (and reference) provider because the
+ * other processors largely follow its feature set + API shape. The PaymentProvider interface is processor-
+ * neutral; the Stripe-specific param builders live in ./stripe and produce exact Stripe API payloads.
+ *
+ * A duck-typed `StripeLike` lets the real `stripe` SDK plug in while staying testable with a mock — no hard
+ * dependency on the SDK in this package.
+ */
+
+export interface Customer { id: string }
+export interface Subscription { id: string }
+export interface WebhookEvent { type: string; data: unknown }
+
+/** A processor-neutral payment surface. Other processors implement the same interface. */
+export interface PaymentProvider {
+  name: string;
+  /** Create (or reference) a billing customer for a principal. */
+  createCustomer(input: { email?: string; name?: string; metadata?: Record<string, string> }): Promise<Customer>;
+  /** Start a usage-metered subscription for a customer on a metered price. */
+  subscribeMetered(input: { customerId: string; priceId: string }): Promise<Subscription>;
+  /** Report usage for billing — one meter event (the value you price on). `at` is an input (reproducible). */
+  reportUsage(input: { customerId: string; eventName: string; value: number; at?: number }): Promise<void>;
+  /** Verify + parse a webhook from the raw body + signature. */
+  verifyWebhook(rawBody: string, signature: string): WebhookEvent;
+}
+
+/** The minimal Stripe surface this package calls — satisfied by the real `stripe` SDK and by test mocks. */
+export interface StripeLike {
+  customers: { create(params: Record<string, unknown>): Promise<{ id: string }> };
+  products: { create(params: Record<string, unknown>): Promise<{ id: string }> };
+  prices: { create(params: Record<string, unknown>): Promise<{ id: string }> };
+  subscriptions: { create(params: Record<string, unknown>): Promise<{ id: string }> };
+  billing: {
+    meters: { create(params: Record<string, unknown>): Promise<{ id: string }> };
+    meterEvents: { create(params: Record<string, unknown>): Promise<{ identifier?: string }> };
+  };
+  webhooks: { constructEvent(body: string, sig: string, secret: string): { type: string; data: unknown } };
+}

package/test/stripe.test.ts

@@ -0,0 +1,97 @@
+import { test, expect, describe } from "bun:test";
+import type { CostEvent } from "@suluk/cost";
+import {
+  customerParams, meterParams, meteredPriceParams, subscriptionParams, meterEventParams,
+  setupUsageBilling, stripeProvider, usageEventsFromCost, reportCostUsage, type StripeLike,
+} from "../src/index";
+
+/** A recording mock that satisfies StripeLike — records every call + returns fake ids. */
+function mockStripe() {
+  const calls: { method: string; params: unknown }[] = [];
+  const rec = (method: string, id: string) => async (params: Record<string, unknown>) => { calls.push({ method, params }); return { id, identifier: id }; };
+  const client: StripeLike = {
+    customers: { create: rec("customers.create", "cus_1") },
+    products: { create: rec("products.create", "prod_1") },
+    prices: { create: rec("prices.create", "price_1") },
+    subscriptions: { create: rec("subscriptions.create", "sub_1") },
+    billing: {
+      meters: { create: rec("billing.meters.create", "mtr_1") },
+      meterEvents: { create: rec("billing.meterEvents.create", "evt_1") },
+    },
+    webhooks: { constructEvent: (b, s, secret) => { calls.push({ method: "webhooks.constructEvent", params: { b, s, secret } }); return { type: "invoice.paid", data: { ok: true } }; } },
+  };
+  return { client, calls };
+}
+
+describe("pure param builders → exact Stripe payloads", () => {
+  test("meter uses default_aggregation.formula", () => {
+    expect(meterParams("api_cost", "API usage")).toEqual({ display_name: "API usage", event_name: "api_cost", default_aggregation: { formula: "sum" } });
+  });
+  test("metered price attaches the meter + usage_type metered", () => {
+    const p = meteredPriceParams({ productId: "prod_1", currency: "usd", unitAmountDecimal: "0.000002", meterId: "mtr_1" }) as any;
+    expect(p.recurring).toEqual({ interval: "month", usage_type: "metered", meter: "mtr_1" });
+    expect(p.product).toBe("prod_1");
+  });
+  test("meter event carries stripe_customer_id + a string value (+ unix timestamp)", () => {
+    expect(meterEventParams({ eventName: "api_cost", customerId: "cus_1", value: 4050, at: 2000 })).toEqual({
+      event_name: "api_cost", payload: { stripe_customer_id: "cus_1", value: "4050" }, timestamp: 2,
+    });
+  });
+  test("customer + subscription params", () => {
+    expect(customerParams({ email: "a@b.c" })).toEqual({ email: "a@b.c" });
+    expect(subscriptionParams({ customerId: "cus_1", priceId: "price_1" })).toEqual({ customer: "cus_1", items: [{ price: "price_1" }] });
+  });
+});
+
+describe("flows over a StripeLike client", () => {
+  test("setupUsageBilling creates product → meter → metered price", async () => {
+    const { client, calls } = mockStripe();
+    const out = await setupUsageBilling(client, { productName: "API", eventName: "api_cost", currency: "usd", unitAmountDecimal: "0.000002" });
+    expect(out).toEqual({ productId: "prod_1", meterId: "mtr_1", priceId: "price_1", eventName: "api_cost" });
+    expect(calls.map((c) => c.method)).toEqual(["products.create", "billing.meters.create", "prices.create"]);
+    expect((calls[2].params as any).recurring.meter).toBe("mtr_1"); // the price is tied to the meter
+  });
+
+  test("stripeProvider: customer, metered subscription, usage, webhook", async () => {
+    const { client, calls } = mockStripe();
+    const stripe = stripeProvider(client, { webhookSecret: "whsec_x" });
+    expect(stripe.name).toBe("stripe");
+    expect((await stripe.createCustomer({ email: "a@b.c" })).id).toBe("cus_1");
+    expect((await stripe.subscribeMetered({ customerId: "cus_1", priceId: "price_1" })).id).toBe("sub_1");
+    await stripe.reportUsage({ customerId: "cus_1", eventName: "api_cost", value: 4050 });
+    const evt = stripe.verifyWebhook("{raw}", "sig_1");
+    expect(evt.type).toBe("invoice.paid");
+    expect(calls.find((c) => c.method === "billing.meterEvents.create")!.params).toMatchObject({ event_name: "api_cost", payload: { stripe_customer_id: "cus_1", value: "4050" } });
+    expect(calls.find((c) => c.method === "webhooks.constructEvent")!.params).toMatchObject({ secret: "whsec_x" });
+  });
+});
+
+describe("the @suluk/cost → Stripe bridge", () => {
+  const events: CostEvent[] = [
+    { at: 1, principal: "user_a", operation: "ask", breakdown: [{ source: "openai", microUsd: 3000 }], totalMicroUsd: 3000 },
+    { at: 2, principal: "user_a", operation: "ask", breakdown: [{ source: "openai", microUsd: 1000 }], totalMicroUsd: 1000 },
+    { at: 3, principal: "user_b", operation: "ask", breakdown: [{ source: "openai", microUsd: 500 }], totalMicroUsd: 500 },
+    { at: 4, operation: "ping", breakdown: [], totalMicroUsd: 0 }, // no principal → skipped
+  ];
+  const customerOf = (p: string) => ({ user_a: "cus_a", user_b: "cus_b" }[p]);
+
+  test("usageEventsFromCost aggregates per principal (raw cost-µ$) into meter events", () => {
+    const usage = usageEventsFromCost(events, { eventName: "api_cost", customerOf });
+    expect(usage).toEqual([
+      { event_name: "api_cost", payload: { stripe_customer_id: "cus_a", value: "4000" } },
+      { event_name: "api_cost", payload: { stripe_customer_id: "cus_b", value: "500" } },
+    ]);
+  });
+
+  test("request-count basis meters 1 per request", () => {
+    const usage = usageEventsFromCost(events, { eventName: "api_calls", customerOf, basis: "request-count" }) as any[];
+    expect(usage.find((u) => u.payload.stripe_customer_id === "cus_a").payload.value).toBe("2");
+  });
+
+  test("reportCostUsage pushes one meter event per principal to the provider", async () => {
+    const { client, calls } = mockStripe();
+    const reported = await reportCostUsage(stripeProvider(client), events, { eventName: "api_cost", customerOf });
+    expect(reported).toBe(2);
+    expect(calls.filter((c) => c.method === "billing.meterEvents.create").length).toBe(2);
+  });
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../tsconfig.base.json", "compilerOptions": { "types": ["bun"] }, "include": ["src", "test"] }