@fonderie/billing 5.3.1 → 6.0.0

package/dist/index.js

@@ -12,10 +12,25 @@ var schemas_exports = {};
 __export(schemas_exports, {
   checkoutSchema: () => checkoutSchema,
   createPlanSchema: () => createPlanSchema,
+  grantWalletSchema: () => grantWalletSchema,
   recordUsageSchema: () => recordUsageSchema,
-  updatePlanSchema: () => updatePlanSchema
+  updatePlanSchema: () => updatePlanSchema,
+  walletCheckoutSchema: () => walletCheckoutSchema
 });
 import { z } from "zod";
+
+// src/types.ts
+var BILLING_INTERVALS = ["month", "year"];
+var BILLING_INTERVAL = {
+  MONTH: "month",
+  YEAR: "year"
+};
+function isBillingInterval(value) {
+  return BILLING_INTERVALS.includes(value);
+}
+var WALLET_LEDGER_TYPES = ["purchase", "grant", "usage", "refund", "adjustment"];
+
+// src/schemas.ts
 var planFields = {
   description: z.string().max(2e3).nullable().optional(),
   tier: z.number().int().min(0).optional(),
@@ -35,12 +50,29 @@ var createPlanSchema = z.object({
 var updatePlanSchema = z.object({ name: z.string().trim().min(1).max(200).optional(), ...planFields }).refine((o) => Object.values(o).some((v) => v !== void 0), "Provide at least one field");
 var checkoutSchema = z.object({
   plan: z.string().min(1, "plan is required"),
-  interval: z.enum(["month", "year"]).optional()
+  interval: z.enum(BILLING_INTERVALS).optional()
 });
 var recordUsageSchema = z.object({
   metric: z.string().min(1, "metric is required").max(100),
   quantity: z.number().min(0).optional()
 });
+var walletAmount = z.union([
+  z.string().regex(/^\d{1,30}$/, "amount must be a positive integer string"),
+  // JSON numbers past 2^53 arrive already rounded — force the digit-string
+  // form for anything larger instead of silently granting a wrong amount.
+  z.number().int().min(1).max(Number.MAX_SAFE_INTEGER)
+]).transform((v) => BigInt(v)).refine((v) => v > 0n, "amount must be positive");
+var walletCheckoutSchema = z.object({
+  packId: z.string().trim().min(1, "packId is required").max(100)
+});
+var grantWalletSchema = z.object({
+  subscriberType: z.enum(["user", "workspace"]),
+  subscriberId: z.string().uuid("subscriberId must be a UUID"),
+  amount: walletAmount,
+  currency: z.string().trim().regex(/^[A-Za-z]{3,20}$/, "currency must be a 3-20 letter code").transform((s) => s.toUpperCase()).optional(),
+  description: z.string().max(500).optional(),
+  idempotencyKey: z.string().min(1, "idempotencyKey is required").max(255)
+});
 
 // src/services/price-cache.ts
 var PriceCache = class {
@@ -93,7 +125,62 @@ var PriceCache = class {
 // src/controllers/plan.controller.ts
 import { setApiResponse, HTTP, stringOrEmpty, numberOrZero } from "@fonderie/core";
 
+// src/utils.ts
+function toSafeNumber(amount) {
+  if (amount > BigInt(Number.MAX_SAFE_INTEGER) || amount < -BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(`[billing] amount ${amount} exceeds Number.MAX_SAFE_INTEGER`);
+  }
+  return Number(amount);
+}
+function normalizeCurrency(currency) {
+  return currency.trim().toUpperCase();
+}
+function parseWindowMs(window) {
+  const n = parseInt(window, 10);
+  const unit = window.slice(String(n).length);
+  switch (unit) {
+    case "h":
+      return n * 36e5;
+    case "d":
+      return n * 864e5;
+    case "m":
+      return n * 6e4;
+    default:
+      throw new Error(`Unknown window unit: '${unit}' in '${window}'`);
+  }
+}
+function resolveSubscriber(ctx) {
+  const wsFromHeader = ctx.request.headers.get("x-workspace-id");
+  if (wsFromHeader) {
+    return {
+      type: "workspace",
+      id: wsFromHeader
+    };
+  }
+  if (ctx.workspace?.id) {
+    return {
+      type: "workspace",
+      id: ctx.workspace.id
+    };
+  }
+  if (ctx.user?.id) {
+    return {
+      type: "user",
+      id: ctx.user.id
+    };
+  }
+  return null;
+}
+
 // src/services/plans.ts
+var planAmount = (v) => v == null ? null : toSafeNumber(BigInt(v));
+function mapPlanRow(row) {
+  return {
+    ...row,
+    monthlyAmount: planAmount(row.monthlyAmount),
+    yearlyAmount: planAmount(row.yearlyAmount)
+  };
+}
 function getPlans(config) {
   return config.plans;
 }
@@ -112,30 +199,33 @@ function resolvePlanNameByPrice(price, plans) {
   }
   return null;
 }
+var walletToJson = (wallet) => wallet == null ? null : JSON.stringify(wallet, (_key, value) => typeof value === "bigint" ? value.toString() : value);
 async function syncPlansToDB(config, store) {
   const plans = config.plans;
   if (plans.length === 0) return;
   const values = plans.map((_, i) => {
-    const b = i * 9;
-    return `($${b + 1}, $${b + 2}, $${b + 3}, $${b + 4}, $${b + 5}, $${b + 6}, $${b + 7}, $${b + 8}, $${b + 9}::jsonb)`;
+    const b = i * 10;
+    return `($${b + 1}, $${b + 2}, $${b + 3}, $${b + 4}, $${b + 5}, $${b + 6}, $${b + 7}, $${b + 8}, $${b + 9}::jsonb, $${b + 10}::jsonb)`;
   });
   const params = plans.flatMap((plan) => [
     plan.name,
     plan.trialDays ?? 0,
-    plan.monthly?.amount ?? null,
+    // bigint params go over the wire as strings; pg casts into the column type.
+    plan.monthly?.amount?.toString() ?? null,
     plan.monthly?.priceId ?? null,
-    plan.yearly?.amount ?? null,
+    plan.yearly?.amount?.toString() ?? null,
     plan.yearly?.priceId ?? null,
     plan.description ?? null,
     plan.tier ?? 0,
-    JSON.stringify(plan.metadata ?? {})
+    JSON.stringify(plan.metadata ?? {}),
+    walletToJson(plan.wallet)
   ]);
   await store.query(
     `INSERT INTO fonderie_plans
 			(name, trial_days,
 			 monthly_amount, monthly_price_id,
 			 yearly_amount,  yearly_price_id,
-			 description, tier, metadata)
+			 description, tier, metadata, wallet)
 		VALUES ${values.join(", ")}
 		ON CONFLICT (name) DO UPDATE SET
 			trial_days       = EXCLUDED.trial_days,
@@ -145,7 +235,8 @@ async function syncPlansToDB(config, store) {
 			yearly_price_id  = EXCLUDED.yearly_price_id,
 			description      = EXCLUDED.description,
 			tier             = EXCLUDED.tier,
-			metadata         = EXCLUDED.metadata`,
+			metadata         = EXCLUDED.metadata,
+			wallet           = EXCLUDED.wallet`,
     params
   );
 }
@@ -165,13 +256,14 @@ var SELECT_PLAN = `
 		metadata
 	FROM fonderie_plans`;
 async function getDBPlans(store) {
-  return store.query(
+  const rows = await store.query(
     `${SELECT_PLAN} WHERE active = true ORDER BY tier ASC, monthly_amount ASC NULLS LAST`
   );
+  return rows.map(mapPlanRow);
 }
 async function getPlanById(id, store) {
   const [row] = await store.query(`${SELECT_PLAN} WHERE id = $1`, [id]);
-  return row ?? null;
+  return row ? mapPlanRow(row) : null;
 }
 async function createPlan(data, store) {
   const [row] = await store.query(
@@ -202,7 +294,7 @@ async function createPlan(data, store) {
     ]
   );
   if (!row) throw new Error("Failed to create plan");
-  return row;
+  return mapPlanRow(row);
 }
 async function updatePlan(id, data, store) {
   const fieldMap = {
@@ -245,7 +337,7 @@ async function updatePlan(id, data, store) {
 			description, tier, features, metadata`,
     params
   );
-  return row ?? null;
+  return row ? mapPlanRow(row) : null;
 }
 async function deletePlan(id, store) {
   const rows = await store.query(
@@ -303,6 +395,7 @@ function toPlanDTO(plan) {
     metadata: plan.metadata && typeof plan.metadata === "object" ? plan.metadata : {}
   };
 }
+var isoOrNull = (value) => value == null ? null : new Date(value).toISOString();
 function toSubscriptionDTO(sub) {
   return {
     id: sub.id,
@@ -312,20 +405,26 @@ function toSubscriptionDTO(sub) {
     interval: sub.interval,
     status: sub.status,
     cancelAtPeriodEnd: sub.cancelAtPeriodEnd,
-    currentPeriodStart: sub.currentPeriodStart,
-    currentPeriodEnd: sub.currentPeriodEnd,
-    trialEndsAt: sub.trialEndsAt,
-    createdAt: sub.createdAt
+    currentPeriodStart: isoOrNull(sub.currentPeriodStart),
+    currentPeriodEnd: isoOrNull(sub.currentPeriodEnd),
+    trialEndsAt: isoOrNull(sub.trialEndsAt),
+    createdAt: isoOrNull(sub.createdAt) ?? ""
   };
 }
-function toUsageRecordDTO(record) {
+function toWalletDTO(balance, currency, precision) {
+  return { balance: balance.toString(), currency, precision };
+}
+function toWalletTransactionDTO(entry) {
   return {
-    id: record.id,
-    subscriberType: record.subscriberType,
-    subscriberId: record.subscriberId,
-    metric: record.metric,
-    quantity: record.quantity,
-    recordedAt: record.recordedAt
+    id: entry.id,
+    type: entry.type,
+    amount: entry.amount.toString(),
+    balanceAfter: entry.balanceAfter.toString(),
+    currency: entry.currency,
+    description: entry.description,
+    providerTxId: entry.providerTxId,
+    metadata: entry.metadata,
+    createdAt: entry.createdAt
   };
 }
 
@@ -345,8 +444,8 @@ async function hydratePricing(dto, plan, config, cache) {
         `[billing] plan "${plan.name}": monthly/yearly currency mismatch (${m.currency} vs ${y.currency})`
       );
     }
-    if (m) dto.pricing.monthly = m.unitAmount;
-    if (y) dto.pricing.yearly = y.unitAmount;
+    if (m) dto.pricing.monthly = toSafeNumber(m.unitAmount);
+    if (y) dto.pricing.yearly = toSafeNumber(y.unitAmount);
     const currency = m?.currency ?? y?.currency;
     if (currency) dto.pricing.currency = currency.toUpperCase();
     if (stale) dto.pricingStale = true;
@@ -529,44 +628,6 @@ var SubscriptionModel = class {
   }
 };
 
-// src/utils.ts
-function parseWindowMs(window) {
-  const n = parseInt(window, 10);
-  const unit = window.slice(String(n).length);
-  switch (unit) {
-    case "h":
-      return n * 36e5;
-    case "d":
-      return n * 864e5;
-    case "m":
-      return n * 6e4;
-    default:
-      throw new Error(`Unknown window unit: '${unit}' in '${window}'`);
-  }
-}
-function resolveSubscriber(ctx) {
-  const wsFromHeader = ctx.request.headers.get("x-workspace-id");
-  if (wsFromHeader) {
-    return {
-      type: "workspace",
-      id: wsFromHeader
-    };
-  }
-  if (ctx.workspace?.id) {
-    return {
-      type: "workspace",
-      id: ctx.workspace.id
-    };
-  }
-  if (ctx.user?.id) {
-    return {
-      type: "user",
-      id: ctx.user.id
-    };
-  }
-  return null;
-}
-
 // src/controllers/subscription.controller.ts
 function subscriptionController(store) {
   const subscriptions = new SubscriptionModel(store);
@@ -597,6 +658,18 @@ function subscriptionController(store) {
 
 // src/controllers/checkout.controller.ts
 import { setApiResponse as setApiResponse3, HTTP as HTTP3 } from "@fonderie/core";
+function planPriceFor(plan, interval) {
+  switch (interval) {
+    case BILLING_INTERVAL.MONTH:
+      return plan.monthly;
+    case BILLING_INTERVAL.YEAR:
+      return plan.yearly;
+    default: {
+      const unhandled = interval;
+      throw new Error(`[billing] unhandled billing interval: ${unhandled}`);
+    }
+  }
+}
 function checkoutController(store, config) {
   const plans = new PlanModel(store);
   const subscriptions = new SubscriptionModel(store);
@@ -604,16 +677,16 @@ function checkoutController(store, config) {
     async createSession(ctx) {
       const body = ctx.meta["body"];
       const planName = body?.["plan"];
-      const interval = body?.["interval"] ?? "month";
+      const interval = body?.["interval"] ?? BILLING_INTERVAL.MONTH;
       const subscriber = resolveSubscriber(ctx);
       if (typeof planName !== "string") {
         return setApiResponse3(HTTP3.UNPROCESSABLE, "INVALID_PARAMETER", "plan is required");
       }
-      if (interval !== "month" && interval !== "year") {
+      if (!isBillingInterval(interval)) {
         return setApiResponse3(
           HTTP3.UNPROCESSABLE,
           "INVALID_PARAMETER",
-          "interval must be month or year"
+          `interval must be one of: ${BILLING_INTERVALS.join(", ")}`
         );
       }
       if (!subscriber) {
@@ -627,7 +700,7 @@ function checkoutController(store, config) {
       if (!plan) {
         return setApiResponse3(HTTP3.UNPROCESSABLE, "INVALID_PARAMETER", `Unknown plan: ${planName}`);
       }
-      const pricing = interval === "year" ? plan.yearly : plan.monthly;
+      const pricing = planPriceFor(plan, interval);
       if (!pricing?.priceId) {
         return setApiResponse3(
           HTTP3.UNPROCESSABLE,
@@ -803,36 +876,701 @@ function usageController(store) {
       return setApiResponse4(HTTP4.OK, "USAGE_FETCHED", "Usage retrieved successfully.", {
         metric,
         total,
-        since
+        // Explicit ISO — the client's IUsageResult.since promises a string.
+        since: since.toISOString()
       });
     }
   };
 }
 
-// src/controllers/webhook.controller.ts
+// src/controllers/wallet.controller.ts
+import { setApiResponse as setApiResponse6, HTTP as HTTP6 } from "@fonderie/core";
+
+// src/errors.ts
+var InsufficientFundsError = class extends Error {
+  constructor(available, required, currency) {
+    super(
+      `[billing:wallet] insufficient funds: available ${available}, required ${required} ${currency}`
+    );
+    this.available = available;
+    this.required = required;
+    this.currency = currency;
+    this.name = "InsufficientFundsError";
+  }
+  available;
+  required;
+  currency;
+};
+var DuplicateTransactionError = class extends Error {
+  constructor(idempotencyKey) {
+    super(
+      `[billing:wallet] idempotency key '${idempotencyKey}' was already used for a different subscriber or currency`
+    );
+    this.idempotencyKey = idempotencyKey;
+    this.name = "DuplicateTransactionError";
+  }
+  idempotencyKey;
+};
+
+// src/services/wallet.ts
+var UNIQUE_VIOLATION = "23505";
+function isIdempotencyConflict(err) {
+  const e = err;
+  if (e?.code !== UNIQUE_VIOLATION) return false;
+  if (typeof e.constraint === "string") return e.constraint.includes("idempotency_key");
+  return typeof e.message === "string" && e.message.includes("idempotency_key");
+}
+async function findByIdempotencyKey(sub, idempotencyKey, store) {
+  const [row] = await store.query(
+    `SELECT
+			subscriber_type AS "subscriberType",
+			subscriber_id   AS "subscriberId",
+			currency
+		FROM fonderie_wallet_ledger
+		WHERE idempotency_key = $1`,
+    [idempotencyKey]
+  );
+  if (!row) return null;
+  if (row.subscriberType !== sub.subscriberType || row.subscriberId !== sub.subscriberId || row.currency !== sub.currency) {
+    throw new DuplicateTransactionError(idempotencyKey);
+  }
+  return row;
+}
+async function readBalance(sub, store) {
+  const [row] = await store.query(
+    `SELECT amount FROM fonderie_wallet_balances
+		WHERE subscriber_type = $1 AND subscriber_id = $2 AND currency = $3`,
+    [sub.subscriberType, sub.subscriberId, sub.currency]
+  );
+  return BigInt(row?.amount ?? "0");
+}
+async function applyBalanceCredit(tx, sub, amount) {
+  const [row] = await tx.query(
+    `INSERT INTO fonderie_wallet_balances (subscriber_type, subscriber_id, currency, amount)
+		VALUES ($1, $2, $3, $4)
+		ON CONFLICT (subscriber_type, subscriber_id, currency) DO UPDATE SET
+			amount     = fonderie_wallet_balances.amount + EXCLUDED.amount,
+			version    = fonderie_wallet_balances.version + 1,
+			updated_at = now()
+		RETURNING amount`,
+    [sub.subscriberType, sub.subscriberId, sub.currency, amount.toString()]
+  );
+  return BigInt(row?.amount ?? "0");
+}
+async function insertLedgerRow(tx, sub, opts) {
+  await tx.query(
+    `INSERT INTO fonderie_wallet_ledger
+			(subscriber_type, subscriber_id, currency, type, amount, balance_after,
+			 description, idempotency_key, metadata, provider_tx_id)
+		VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10)`,
+    [
+      sub.subscriberType,
+      sub.subscriberId,
+      sub.currency,
+      opts.type,
+      opts.amount.toString(),
+      opts.balanceAfter.toString(),
+      opts.description,
+      opts.idempotencyKey,
+      JSON.stringify(opts.metadata),
+      opts.providerTxId
+    ]
+  );
+}
+async function creditWallet(opts, store) {
+  if (opts.amount < 0n) throw new Error("[billing:wallet] credit amount must be positive");
+  if (!opts.idempotencyKey) throw new Error("[billing:wallet] idempotencyKey is required");
+  if (opts.amount === 0n) {
+    return { balance: await readBalance(opts, store), duplicate: false };
+  }
+  try {
+    return await store.transaction(async (tx) => {
+      const existing = await findByIdempotencyKey(opts, opts.idempotencyKey, tx);
+      if (existing) return { balance: await readBalance(opts, tx), duplicate: true };
+      const balance = await applyBalanceCredit(tx, opts, opts.amount);
+      await insertLedgerRow(tx, opts, {
+        type: opts.type ?? "adjustment",
+        amount: opts.amount,
+        balanceAfter: balance,
+        idempotencyKey: opts.idempotencyKey,
+        description: opts.description ?? null,
+        metadata: opts.metadata ?? {},
+        providerTxId: opts.providerTxId ?? null
+      });
+      return { balance, duplicate: false };
+    });
+  } catch (err) {
+    if (isIdempotencyConflict(err)) {
+      return { balance: await readBalance(opts, store), duplicate: true };
+    }
+    throw err;
+  }
+}
+async function debitWallet(opts, store) {
+  if (opts.amount < 0n) throw new Error("[billing:wallet] debit amount must be positive");
+  if (!opts.idempotencyKey) throw new Error("[billing:wallet] idempotencyKey is required");
+  if (opts.amount === 0n) {
+    return { balance: await readBalance(opts, store), duplicate: false };
+  }
+  const floor = -(opts.overdraftLimit ?? 0n);
+  try {
+    return await store.transaction(async (tx) => {
+      const existing = await findByIdempotencyKey(opts, opts.idempotencyKey, tx);
+      if (existing) return { balance: await readBalance(opts, tx), duplicate: true };
+      await tx.query(
+        `INSERT INTO fonderie_wallet_balances (subscriber_type, subscriber_id, currency, amount)
+				VALUES ($1, $2, $3, 0)
+				ON CONFLICT (subscriber_type, subscriber_id, currency) DO NOTHING`,
+        [opts.subscriberType, opts.subscriberId, opts.currency]
+      );
+      const [locked] = await tx.query(
+        `SELECT amount FROM fonderie_wallet_balances
+				WHERE subscriber_type = $1 AND subscriber_id = $2 AND currency = $3
+				FOR UPDATE`,
+        [opts.subscriberType, opts.subscriberId, opts.currency]
+      );
+      const current = BigInt(locked?.amount ?? "0");
+      if (current - opts.amount < floor) {
+        throw new InsufficientFundsError(current, opts.amount, opts.currency);
+      }
+      const [updated] = await tx.query(
+        `UPDATE fonderie_wallet_balances
+				SET amount = amount - $4, version = version + 1, updated_at = now()
+				WHERE subscriber_type = $1 AND subscriber_id = $2 AND currency = $3
+					AND amount - $4 >= $5
+				RETURNING amount`,
+        [
+          opts.subscriberType,
+          opts.subscriberId,
+          opts.currency,
+          opts.amount.toString(),
+          floor.toString()
+        ]
+      );
+      if (!updated) {
+        throw new InsufficientFundsError(current, opts.amount, opts.currency);
+      }
+      const balance = BigInt(updated.amount);
+      await insertLedgerRow(tx, opts, {
+        type: opts.type ?? "usage",
+        amount: -opts.amount,
+        balanceAfter: balance,
+        idempotencyKey: opts.idempotencyKey,
+        description: opts.description ?? null,
+        metadata: opts.metadata ?? {},
+        providerTxId: null
+      });
+      return { balance, duplicate: false };
+    });
+  } catch (err) {
+    if (isIdempotencyConflict(err)) {
+      return { balance: await readBalance(opts, store), duplicate: true };
+    }
+    throw err;
+  }
+}
+async function getWalletBalance(sub, store) {
+  const [row] = await store.query(
+    `SELECT amount, version, updated_at AS "updatedAt"
+		FROM fonderie_wallet_balances
+		WHERE subscriber_type = $1 AND subscriber_id = $2 AND currency = $3`,
+    [sub.subscriberType, sub.subscriberId, sub.currency]
+  );
+  if (!row) return { balance: 0n, version: 0, updatedAt: null };
+  return {
+    balance: BigInt(row.amount),
+    version: Number(row.version),
+    updatedAt: row.updatedAt ? new Date(row.updatedAt).toISOString() : null
+  };
+}
+function encodeLedgerCursor(createdAt, id) {
+  return Buffer.from(JSON.stringify([createdAt, id])).toString("base64url");
+}
+var CURSOR_TS_RE = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}(:?\d{2})?)?$/;
+var CURSOR_ID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+function decodeLedgerCursor(cursor) {
+  if (cursor.length > 256) return null;
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    if (!Array.isArray(parsed) || typeof parsed[0] !== "string" || typeof parsed[1] !== "string") {
+      return null;
+    }
+    if (!CURSOR_TS_RE.test(parsed[0]) || !CURSOR_ID_RE.test(parsed[1])) return null;
+    return { createdAt: parsed[0], id: parsed[1] };
+  } catch {
+    return null;
+  }
+}
+async function getWalletLedger(opts, store) {
+  const limit = Math.min(Math.max(opts.limit ?? 50, 1), 100);
+  const params = [opts.subscriberType, opts.subscriberId, opts.currency];
+  let cursorClause = "";
+  if (opts.cursor) {
+    params.push(opts.cursor.createdAt, opts.cursor.id);
+    cursorClause = `AND (created_at, id) < ($4::timestamptz, $5::uuid)`;
+  }
+  params.push(limit + 1);
+  const rows = await store.query(
+    `SELECT
+			id,
+			subscriber_type AS "subscriberType",
+			subscriber_id   AS "subscriberId",
+			currency,
+			type,
+			amount,
+			balance_after   AS "balanceAfter",
+			description,
+			idempotency_key AS "idempotencyKey",
+			metadata,
+			provider_tx_id  AS "providerTxId",
+			created_at      AS "createdAt",
+			created_at::text AS "createdAtRaw"
+		FROM fonderie_wallet_ledger
+		WHERE subscriber_type = $1 AND subscriber_id = $2 AND currency = $3
+			${cursorClause}
+		ORDER BY created_at DESC, id DESC
+		LIMIT $${params.length}`,
+    params
+  );
+  const page = rows.slice(0, limit);
+  const entries = page.map((r) => ({
+    id: r.id,
+    subscriberType: r.subscriberType,
+    subscriberId: r.subscriberId,
+    currency: r.currency,
+    type: r.type,
+    amount: BigInt(r.amount),
+    balanceAfter: BigInt(r.balanceAfter),
+    description: r.description,
+    idempotencyKey: r.idempotencyKey,
+    metadata: r.metadata ?? {},
+    providerTxId: r.providerTxId,
+    createdAt: new Date(r.createdAt).toISOString()
+  }));
+  const lastRow = page[page.length - 1];
+  const nextCursor = rows.length > limit && lastRow ? encodeLedgerCursor(lastRow.createdAtRaw, lastRow.id) : null;
+  return { entries, nextCursor };
+}
+function resolvePlanWallet(plan, config) {
+  if (!config.wallet || !plan.wallet) return null;
+  return {
+    currency: normalizeCurrency(plan.wallet.currency ?? config.wallet.currency ?? "USD"),
+    precision: plan.wallet.precision ?? config.wallet.precision ?? 2,
+    overdraftLimit: plan.wallet.overdraftLimit ?? 0n,
+    grantAmount: plan.wallet.grantAmount ?? null,
+    grantPeriod: plan.wallet.grantPeriod ?? "month",
+    rates: plan.wallet.rates ?? {}
+  };
+}
+function currentGrantPeriod(period, now = /* @__PURE__ */ new Date()) {
+  const y = now.getUTCFullYear();
+  const m = String(now.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(now.getUTCDate()).padStart(2, "0");
+  if (period === "month") return `${y}-${m}`;
+  if (period === "day") return `${y}-${m}-${d}`;
+  const thursday = new Date(Date.UTC(y, now.getUTCMonth(), now.getUTCDate()));
+  thursday.setUTCDate(thursday.getUTCDate() + 4 - (thursday.getUTCDay() || 7));
+  const isoYear = thursday.getUTCFullYear();
+  const jan4 = new Date(Date.UTC(isoYear, 0, 4));
+  jan4.setUTCDate(jan4.getUTCDate() + 4 - (jan4.getUTCDay() || 7));
+  const week = 1 + Math.round((thursday.getTime() - jan4.getTime()) / (7 * 864e5));
+  return `${isoYear}-W${String(week).padStart(2, "0")}`;
+}
+async function ensurePeriodicGrant(opts, store) {
+  if (opts.amount <= 0n) return { granted: false, balance: null };
+  const [seen] = await store.query(
+    `SELECT period FROM fonderie_wallet_grants
+		WHERE subscriber_type = $1 AND subscriber_id = $2 AND currency = $3 AND period = $4`,
+    [opts.subscriberType, opts.subscriberId, opts.currency, opts.period]
+  );
+  if (seen) return { granted: false, balance: null };
+  try {
+    return await store.transaction(async (tx) => {
+      const [marked] = await tx.query(
+        `INSERT INTO fonderie_wallet_grants (subscriber_type, subscriber_id, currency, period, amount)
+				VALUES ($1, $2, $3, $4, $5)
+				ON CONFLICT (subscriber_type, subscriber_id, currency, period) DO NOTHING
+				RETURNING period`,
+        [
+          opts.subscriberType,
+          opts.subscriberId,
+          opts.currency,
+          opts.period,
+          opts.amount.toString()
+        ]
+      );
+      if (!marked) return { granted: false, balance: null };
+      const balance = await applyBalanceCredit(tx, opts, opts.amount);
+      await insertLedgerRow(tx, opts, {
+        type: "grant",
+        amount: opts.amount,
+        balanceAfter: balance,
+        idempotencyKey: `grant:${opts.subscriberType}:${opts.subscriberId}:${opts.currency}:${opts.period}`,
+        description: opts.description ?? `Periodic grant ${opts.period}`,
+        metadata: { period: opts.period },
+        providerTxId: null
+      });
+      return { granted: true, balance };
+    });
+  } catch (err) {
+    if (isIdempotencyConflict(err)) return { granted: false, balance: null };
+    throw err;
+  }
+}
+
+// src/models/wallet.model.ts
+var WalletModel = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  credit(opts) {
+    return creditWallet(opts, this.store);
+  }
+  debit(opts) {
+    return debitWallet(opts, this.store);
+  }
+  balance(sub) {
+    return getWalletBalance(sub, this.store);
+  }
+  ledger(opts) {
+    return getWalletLedger(opts, this.store);
+  }
+  ensureGrant(opts) {
+    return ensurePeriodicGrant(opts, this.store);
+  }
+};
+
+// src/services/credit-packs.ts
+function findCreditPack(packId, config) {
+  const pack = config.wallet?.creditPacks?.find((p) => p.id === packId);
+  if (!pack || pack.active === false) return null;
+  return pack;
+}
+async function syncCreditPacksToDB(config, store) {
+  const packs = config.wallet?.creditPacks ?? [];
+  if (packs.length === 0) return;
+  const defaultCurrency = normalizeCurrency(config.wallet?.currency ?? "USD");
+  const values = packs.map((_, i) => {
+    const b = i * 8;
+    return `($${b + 1}, $${b + 2}, $${b + 3}, $${b + 4}, $${b + 5}, $${b + 6}, $${b + 7}, $${b + 8}::jsonb)`;
+  });
+  const params = packs.flatMap((pack) => [
+    pack.id,
+    pack.name,
+    normalizeCurrency(pack.currency ?? defaultCurrency),
+    pack.credits.toString(),
+    pack.priceAmount.toString(),
+    pack.priceId ?? null,
+    pack.active !== false,
+    JSON.stringify(pack.metadata ?? {})
+  ]);
+  await store.query(
+    `INSERT INTO fonderie_credit_packs
+			(id, name, currency, credits, price_amount, price_id, active, metadata)
+		VALUES ${values.join(", ")}
+		ON CONFLICT (id) DO UPDATE SET
+			name         = EXCLUDED.name,
+			currency     = EXCLUDED.currency,
+			credits      = EXCLUDED.credits,
+			price_amount = EXCLUDED.price_amount,
+			price_id     = EXCLUDED.price_id,
+			active       = EXCLUDED.active,
+			metadata     = EXCLUDED.metadata`,
+    params
+  );
+}
+
+// src/helpers.ts
 import { setApiResponse as setApiResponse5, HTTP as HTTP5 } from "@fonderie/core";
-function webhookController(store, config, priceCache) {
+function getBillingContext(ctx) {
+  return ctx.meta["billing"] ?? null;
+}
+function hasFeature(ctx, key) {
+  const billing = getBillingContext(ctx);
+  if (!billing) return true;
+  const status = billing.statuses[key];
+  if (!status) return true;
+  if (status.type === "feature") return status.enabled;
+  return true;
+}
+function getPlanLimit(ctx, key) {
+  const billing = getBillingContext(ctx);
+  if (!billing) return null;
+  const status = billing.statuses[key];
+  if (!status || status.type === "feature") return null;
+  return status.limit;
+}
+function getLimitStatus(ctx, key) {
+  const billing = getBillingContext(ctx);
+  if (!billing) return null;
+  return billing.statuses[key] ?? null;
+}
+function getWalletStatus(ctx) {
+  return getBillingContext(ctx)?.wallet ?? null;
+}
+function getWalletRate(ctx, metric) {
+  return getWalletStatus(ctx)?.rates[metric]?.cost ?? null;
+}
+function requireWalletBalance(metric) {
+  return (ctx, next) => {
+    const wallet = getWalletStatus(ctx);
+    const cost = wallet?.rates[metric]?.cost;
+    if (!wallet || cost === void 0 || cost === 0n) return next();
+    if (wallet.balance - cost < -wallet.overdraftLimit) {
+      return Promise.resolve(
+        setApiResponse5(HTTP5.PAYMENT_REQUIRED, "INSUFFICIENT_CREDITS", "Insufficient credits", {
+          metric,
+          cost: cost.toString(),
+          balance: wallet.balance.toString(),
+          currency: wallet.currency
+        })
+      );
+    }
+    return next();
+  };
+}
+async function debitWalletForMetric(ctx, metric, opts, store) {
+  const quantity = opts.quantity ?? 1;
+  if (!Number.isInteger(quantity) || quantity <= 0) {
+    throw new Error("[billing:wallet] quantity must be a positive integer");
+  }
+  const billing = getBillingContext(ctx);
+  const wallet = billing?.wallet;
+  const cost = wallet?.rates[metric]?.cost;
+  if (!billing || !wallet || cost === void 0 || cost === 0n) return null;
+  return debitWallet(
+    {
+      subscriberType: billing.subscriber.type,
+      subscriberId: billing.subscriber.id,
+      currency: wallet.currency,
+      amount: cost * BigInt(quantity),
+      overdraftLimit: wallet.overdraftLimit,
+      idempotencyKey: opts.idempotencyKey,
+      description: opts.description ?? metric,
+      metadata: { metric, quantity, ...opts.metadata ?? {} }
+    },
+    store
+  );
+}
+function insufficientCreditsResponse(err, metric) {
+  return setApiResponse5(HTTP5.PAYMENT_REQUIRED, "INSUFFICIENT_CREDITS", "Insufficient credits", {
+    ...metric ? { metric } : {},
+    cost: err.required.toString(),
+    balance: err.available.toString(),
+    currency: err.currency
+  });
+}
+function requireFeature(key) {
+  return (ctx, next) => {
+    if (!hasFeature(ctx, key)) {
+      return Promise.resolve(
+        setApiResponse5(
+          HTTP5.PAYMENT_REQUIRED,
+          "FEATURE_UNAVAILABLE",
+          `Feature '${key}' is not available on your current plan`
+        )
+      );
+    }
+    return next();
+  };
+}
+
+// src/controllers/wallet.controller.ts
+function walletController(store, config) {
+  const wallet = new WalletModel(store);
   const subscriptions = new SubscriptionModel(store);
+  const defaultCurrency = () => normalizeCurrency(config.wallet?.currency ?? "USD");
+  const currencyOf = (ctx) => {
+    const q = new URL(ctx.request.url).searchParams.get("currency");
+    if (q) return normalizeCurrency(q);
+    return getWalletStatus(ctx)?.currency ?? defaultCurrency();
+  };
+  const precisionOf = (ctx) => getWalletStatus(ctx)?.precision ?? config.wallet?.precision ?? 2;
   return {
-    async handle(ctx) {
-      if (!config.webhookSecret) {
-        return setApiResponse5(HTTP5.SERVER_ERROR, "SERVER_ERROR", "Webhook secret not configured");
+    async get(ctx) {
+      const subscriber = resolveSubscriber(ctx);
+      if (!subscriber) {
+        return setApiResponse6(
+          HTTP6.BAD_REQUEST,
+          "SUBSCRIBER_REQUIRED",
+          "Subscriber context required"
+        );
       }
-      const signature = ctx.request.headers.get("stripe-signature") ?? ctx.request.headers.get("paypal-auth-algo") ?? "";
-      if (!signature) {
-        return setApiResponse5(HTTP5.BAD_REQUEST, "INVALID_REQUEST", "Missing webhook signature");
+      const currency = currencyOf(ctx);
+      const { balance } = await wallet.balance({
+        subscriberType: subscriber.type,
+        subscriberId: subscriber.id,
+        currency
+      });
+      return setApiResponse6(HTTP6.OK, "WALLET_FETCHED", "Wallet retrieved successfully.", {
+        wallet: toWalletDTO(balance, currency, precisionOf(ctx))
+      });
+    },
+    async transactions(ctx) {
+      const subscriber = resolveSubscriber(ctx);
+      if (!subscriber) {
+        return setApiResponse6(
+          HTTP6.BAD_REQUEST,
+          "SUBSCRIBER_REQUIRED",
+          "Subscriber context required"
+        );
       }
-      const payload = await ctx.request.text();
-      let event;
+      const params = new URL(ctx.request.url).searchParams;
+      const rawLimit = params.get("limit");
+      const limit = rawLimit !== null ? Number.parseInt(rawLimit, 10) : 50;
+      if (Number.isNaN(limit) || limit < 1 || limit > 100) {
+        return setApiResponse6(
+          HTTP6.UNPROCESSABLE,
+          "INVALID_PARAMETER",
+          "limit must be an integer between 1 and 100"
+        );
+      }
+      const rawCursor = params.get("cursor");
+      const cursor = rawCursor !== null ? decodeLedgerCursor(rawCursor) : null;
+      if (rawCursor !== null && cursor === null) {
+        return setApiResponse6(HTTP6.UNPROCESSABLE, "INVALID_PARAMETER", "Malformed cursor");
+      }
+      const page = await wallet.ledger({
+        subscriberType: subscriber.type,
+        subscriberId: subscriber.id,
+        currency: currencyOf(ctx),
+        limit,
+        ...cursor ? { cursor } : {}
+      });
+      return setApiResponse6(
+        HTTP6.OK,
+        "WALLET_TRANSACTIONS",
+        `Retrieved ${page.entries.length} wallet transactions`,
+        {
+          transactions: page.entries.map(toWalletTransactionDTO),
+          nextCursor: page.nextCursor
+        }
+      );
+    },
+    // One-time checkout for a credit pack. The pack's credits and the
+    // buyer's WALLET currency are snapshotted into the session metadata at
+    // creation time, so the webhook credits exactly what was bought (even
+    // if config changes later) into the bucket the buyer's spend paths
+    // actually read. pack.currency only prices the provider charge.
+    async checkout(ctx) {
+      const body = ctx.meta["body"];
+      const subscriber = resolveSubscriber(ctx);
+      if (!subscriber) {
+        return setApiResponse6(
+          HTTP6.BAD_REQUEST,
+          "SUBSCRIBER_REQUIRED",
+          "Subscriber context required"
+        );
+      }
+      const pack = findCreditPack(body.packId, config);
+      if (!pack) {
+        return setApiResponse6(
+          HTTP6.UNPROCESSABLE,
+          "INVALID_PARAMETER",
+          `Unknown credit pack: ${body.packId}`
+        );
+      }
+      if (!config.provider.createPaymentCheckoutSession) {
+        return setApiResponse6(
+          HTTP6.NOT_IMPLEMENTED,
+          "PAYMENT_NOT_SUPPORTED",
+          `Provider '${config.provider.name}' does not support one-time payments`
+        );
+      }
+      const creditCurrency = getWalletStatus(ctx)?.currency ?? defaultCurrency();
+      const chargeCurrency = normalizeCurrency(pack.currency ?? creditCurrency);
+      const current = await subscriptions.get(subscriber.type, subscriber.id);
+      const customerId = current?.providerCustomerId ?? (await config.provider.createCustomer({
+        email: ctx.user.email ?? "",
+        subscriberType: subscriber.type,
+        subscriberId: subscriber.id,
+        userId: ctx.user.id
+      })).customerId;
+      const session = await config.provider.createPaymentCheckoutSession({
+        customerId,
+        amount: pack.priceAmount,
+        currency: chargeCurrency,
+        name: pack.name,
+        ...pack.priceId ? { priceId: pack.priceId } : {},
+        metadata: {
+          subscriberType: subscriber.type,
+          subscriberId: subscriber.id,
+          packId: pack.id,
+          credits: pack.credits.toString(),
+          currency: creditCurrency
+        },
+        successUrl: config.successUrl,
+        cancelUrl: config.cancelUrl
+      });
+      return setApiResponse6(HTTP6.OK, "CHECKOUT_URL", "Checkout session created.", {
+        url: session.url,
+        sessionId: session.sessionId
+      });
+    },
+    // Admin-token-guarded manual grant (support/ops). Body is validated and
+    // transformed by grantWalletSchema — amount arrives as a bigint.
+    async grant(ctx) {
+      const body = ctx.meta["body"];
+      const currency = body.currency ? normalizeCurrency(body.currency) : defaultCurrency();
       try {
-        event = await config.provider.constructEvent({
-          payload,
-          signature,
-          secret: config.webhookSecret
+        const result = await wallet.credit({
+          subscriberType: body.subscriberType,
+          subscriberId: body.subscriberId,
+          currency,
+          amount: body.amount,
+          type: "grant",
+          description: body.description ?? "Manual grant",
+          idempotencyKey: body.idempotencyKey
+        });
+        return setApiResponse6(HTTP6.OK, "WALLET_GRANTED", "Credits granted.", {
+          balance: result.balance.toString(),
+          currency,
+          duplicate: result.duplicate
         });
-      } catch {
-        return setApiResponse5(HTTP5.BAD_REQUEST, "INVALID_REQUEST", "Invalid webhook signature");
+      } catch (err) {
+        if (err instanceof DuplicateTransactionError) {
+          return setApiResponse6(HTTP6.CONFLICT, "DUPLICATE_TRANSACTION", err.message);
+        }
+        throw err;
       }
+    }
+  };
+}
+
+// src/controllers/webhook.controller.ts
+import "@fonderie/core";
+
+// src/controllers/webhook-shared.ts
+import { setApiResponse as setApiResponse7, HTTP as HTTP7 } from "@fonderie/core";
+async function readWebhookEvent(ctx, secret, provider, missingSecretMessage) {
+  if (!secret) {
+    return setApiResponse7(HTTP7.SERVER_ERROR, "SERVER_ERROR", missingSecretMessage);
+  }
+  const signature = ctx.request.headers.get("stripe-signature") ?? ctx.request.headers.get("paypal-auth-algo") ?? "";
+  if (!signature) {
+    return setApiResponse7(HTTP7.BAD_REQUEST, "INVALID_REQUEST", "Missing webhook signature");
+  }
+  const payload = await ctx.request.text();
+  try {
+    return await provider.constructEvent({ payload, signature, secret });
+  } catch {
+    return setApiResponse7(HTTP7.BAD_REQUEST, "INVALID_REQUEST", "Invalid webhook signature");
+  }
+}
+
+// src/controllers/webhook.controller.ts
+function webhookController(store, config, priceCache) {
+  const subscriptions = new SubscriptionModel(store);
+  return {
+    async handle(ctx) {
+      const event = await readWebhookEvent(
+        ctx,
+        config.webhookSecret,
+        config.provider,
+        "Webhook secret not configured"
+      );
+      if (event instanceof Response) return event;
       if (priceCache && (event.type.startsWith("price.") || event.type.startsWith("product."))) {
         priceCache.invalidate();
       }
@@ -857,6 +1595,88 @@ function webhookController(store, config, priceCache) {
   };
 }
 
+// src/controllers/payment-webhook.controller.ts
+import { setApiResponse as setApiResponse9, HTTP as HTTP9 } from "@fonderie/core";
+function paymentWebhookController(store, config) {
+  const wallet = new WalletModel(store);
+  return {
+    async handle(ctx) {
+      const event = await readWebhookEvent(
+        ctx,
+        config.wallet?.webhookSecret,
+        config.provider,
+        "Payment webhook secret not configured \u2014 set wallet.webhookSecret"
+      );
+      if (event instanceof Response) return event;
+      const payment = event.payment;
+      if (!payment) return Response.json({ received: true });
+      const meta = payment.metadata;
+      const packId = meta["packId"];
+      if (!packId) return Response.json({ received: true });
+      const subscriberType = meta["subscriberType"];
+      const subscriberId = meta["subscriberId"];
+      const credits = meta["credits"] ?? "";
+      if (subscriberType !== "user" && subscriberType !== "workspace" || !subscriberId || !/^\d{1,30}$/.test(credits)) {
+        return setApiResponse9(
+          HTTP9.UNPROCESSABLE,
+          "INVALID_PARAMETER",
+          "Malformed wallet checkout metadata"
+        );
+      }
+      const status = payment.paymentStatus ?? null;
+      if (status !== null && status !== "paid" && status !== "no_payment_required") {
+        return Response.json({ received: true, pending: true });
+      }
+      const currency = normalizeCurrency(meta["currency"] ?? config.wallet?.currency ?? "USD");
+      try {
+        const result = await wallet.credit({
+          subscriberType,
+          subscriberId,
+          currency,
+          amount: BigInt(credits),
+          type: "purchase",
+          idempotencyKey: `${config.provider.name}:checkout:${payment.sessionId}`,
+          description: `Credit pack ${packId}`,
+          metadata: {
+            packId,
+            amountPaid: payment.amountTotal?.toString() ?? null,
+            paymentCurrency: payment.currency
+          },
+          ...payment.providerTxId ? { providerTxId: payment.providerTxId } : {}
+        });
+        return Response.json({ received: true, duplicate: result.duplicate });
+      } catch (err) {
+        if (err instanceof DuplicateTransactionError) {
+          return setApiResponse9(HTTP9.CONFLICT, "DUPLICATE_TRANSACTION", err.message);
+        }
+        throw err;
+      }
+    }
+  };
+}
+
+// src/middlewares/admin-token.ts
+import { timingSafeEqual } from "crypto";
+import { setApiResponse as setApiResponse10, HTTP as HTTP10 } from "@fonderie/core";
+function safeTokenEqual(a, b) {
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  if (bufA.length !== bufB.length) return false;
+  return timingSafeEqual(bufA, bufB);
+}
+function requireAdminToken(adminToken) {
+  return (ctx, next) => {
+    const header = ctx.request.headers.get("authorization") ?? "";
+    const token = header.startsWith("Bearer ") ? header.slice(7) : "";
+    if (!token || !safeTokenEqual(token, adminToken)) {
+      return Promise.resolve(
+        setApiResponse10(HTTP10.UNAUTHORIZED, "UNAUTHORIZED", "Missing or invalid admin token")
+      );
+    }
+    return next();
+  };
+}
+
 // src/routes.ts
 function buildBillingRoutes(store, config) {
   const priceCache = new PriceCache({
@@ -869,7 +1689,7 @@ function buildBillingRoutes(store, config) {
   const checkout = checkoutController(store, config);
   const usage = usageController(store);
   const webhook = webhookController(store, config, priceCache);
-  return [
+  const routes = [
     // Plans — public read-only
     ["GET", "/plans", plan.list],
     ["GET", "/plans/:planId", plan.get],
@@ -877,8 +1697,10 @@ function buildBillingRoutes(store, config) {
     ["POST", "/plans", validate(createPlanSchema), plan.create],
     ["PUT", "/plans/:planId", validate(updatePlanSchema), plan.update],
     ["DELETE", "/plans/:planId", plan.delete],
-    // Billing — subscriber resolved from X-Workspace-ID header (workspace) or session (user)
-    // Workspace membership is verified automatically by the withBilling global middleware
+    // Billing — subscriber resolved from X-Workspace-ID header (workspace) or session (user).
+    // The withBilling global middleware verifies workspace membership against
+    // fonderie_role_user_workspaces (403 for non-members, fail-closed) before
+    // any billing surface acts on a header-derived workspace id.
     ["GET", "/billing/subscription", requireAuth, subscription.get],
     ["POST", "/billing/checkout", requireAuth, validate(checkoutSchema), checkout.createSession],
     ["POST", "/billing/portal", requireAuth, checkout.createPortal],
@@ -887,10 +1709,32 @@ function buildBillingRoutes(store, config) {
     // Webhook — signature verified inside the handler
     ["POST", "/billing/webhook", webhook.handle]
   ];
+  if (config.wallet) {
+    const wallet = walletController(store, config);
+    const paymentWebhook = paymentWebhookController(store, config);
+    routes.push(
+      ["GET", "/billing/wallet", requireAuth, wallet.get],
+      ["GET", "/billing/wallet/transactions", requireAuth, wallet.transactions],
+      ["POST", "/billing/wallet/checkout", requireAuth, validate(walletCheckoutSchema), wallet.checkout],
+      // Payment webhook — separate endpoint and secret from the
+      // subscription webhook; signature verified inside the handler.
+      ["POST", "/billing/webhook/payment", paymentWebhook.handle]
+    );
+    if (config.wallet.adminToken) {
+      routes.push([
+        "POST",
+        "/billing/wallet/grant",
+        requireAdminToken(config.wallet.adminToken),
+        validate(grantWalletSchema),
+        wallet.grant
+      ]);
+    }
+  }
+  return routes;
 }
 
 // src/middlewares/billing.ts
-import { setApiResponse as setApiResponse6, HTTP as HTTP6 } from "@fonderie/core";
+import { setApiResponse as setApiResponse11, HTTP as HTTP11 } from "@fonderie/core";
 
 // src/config.ts
 var MESSAGE_KEYS = {
@@ -899,6 +1743,25 @@ var MESSAGE_KEYS = {
   limitBlocked: "billing.limit-blocked"
 };
 
+// src/services/membership.ts
+async function isWorkspaceMember(userId, workspaceId, store) {
+  try {
+    const rows = await store.query(
+      `SELECT 1 AS ok
+			 FROM fonderie_role_user_workspaces
+			 WHERE user_id      = $1
+			   AND workspace_id = $2
+			   AND removed      = false
+			   AND suspended    = false
+			 LIMIT 1`,
+      [userId, workspaceId]
+    );
+    return rows.length > 0;
+  } catch {
+    return false;
+  }
+}
+
 // src/services/policy.ts
 function buildBillingContext(opts) {
   const { subscriber, plan, active, counters } = opts;
@@ -933,6 +1796,12 @@ function withBilling(store, config, backend) {
   return async (ctx, next) => {
     const subscriber = resolveSubscriber(ctx);
     if (!subscriber) return next();
+    if (subscriber.type === "workspace" && ctx.workspace?.id !== subscriber.id) {
+      if (!ctx.user) return next();
+      if (!await isWorkspaceMember(ctx.user.id, subscriber.id, store)) {
+        return setApiResponse11(HTTP11.FORBIDDEN, "FORBIDDEN", "Not a member of this workspace");
+      }
+    }
     const subscription = await getSubscription(subscriber.type, subscriber.id, store);
     const planName = subscription?.plan ?? config.plans[0]?.name ?? "free";
     const active = !subscription || subscription.status === "active" || subscription.status === "trialing";
@@ -947,10 +1816,40 @@ function withBilling(store, config, backend) {
     }
     const billingCtx = buildBillingContext({ subscriber, plan, active, counters });
     ctx.meta["billing"] = billingCtx;
+    const planWallet = resolvePlanWallet(plan, config);
+    if (planWallet) {
+      try {
+        const sub = {
+          subscriberType: subscriber.type,
+          subscriberId: subscriber.id,
+          currency: planWallet.currency
+        };
+        if (active && planWallet.grantAmount !== null && planWallet.grantAmount > 0n) {
+          await ensurePeriodicGrant(
+            {
+              ...sub,
+              amount: planWallet.grantAmount,
+              period: currentGrantPeriod(planWallet.grantPeriod)
+            },
+            store
+          );
+        }
+        const { balance } = await getWalletBalance(sub, store);
+        billingCtx.wallet = {
+          balance,
+          currency: planWallet.currency,
+          precision: planWallet.precision,
+          overdraftLimit: planWallet.overdraftLimit,
+          rates: planWallet.rates
+        };
+      } catch (err) {
+        console.error("[billing] wallet context failed:", err.message);
+      }
+    }
     for (const [key, status] of Object.entries(billingCtx.statuses)) {
       if (status.type === "counter" && status.status === "blocked") {
-        return setApiResponse6(
-          HTTP6.TOO_MANY_REQUESTS,
+        return setApiResponse11(
+          HTTP11.TOO_MANY_REQUESTS,
           "RATE_LIMIT_EXCEEDED",
           `Limit exceeded for: ${key}`,
           { key, limit: status.limit, used: status.used, resetsAt: status.resetsAt }
@@ -1081,7 +1980,13 @@ var BillingModule = class {
   name = "@fonderie/billing";
   deps = ["@fonderie/auth"];
   async install(app) {
+    if (!this.config.wallet && this.config.plans.some((p) => p.wallet)) {
+      console.warn(
+        "[billing] plans define wallet economics but config.wallet is not set \u2014 wallet features are disabled"
+      );
+    }
     await syncPlansToDB(this.config, this.store);
+    if (this.config.wallet) await syncCreditPacksToDB(this.config, this.store);
     const backend = createBackend(this.config.rateLimit?.backend, this.store);
     app.use(withBilling(this.store, this.config, backend));
     const routes = buildBillingRoutes(this.store, this.config);
@@ -1091,10 +1996,18 @@ var BillingModule = class {
   }
 };
 
-// src/types.ts
-var BILLING_INTERVAL = { MONTH: "month", YEAR: "year" };
-
 // src/providers/stripe.ts
+function normalizePaymentSession(session) {
+  const pi = session.payment_intent;
+  return {
+    sessionId: session.id,
+    providerTxId: typeof pi === "string" ? pi : pi?.id ?? null,
+    amountTotal: session.amount_total != null ? BigInt(session.amount_total) : null,
+    currency: session.currency ?? null,
+    paymentStatus: session.payment_status ?? null,
+    metadata: session.metadata ?? {}
+  };
+}
 var _client = null;
 async function getClient(secretKey) {
   if (_client) return _client;
@@ -1106,6 +2019,15 @@ async function getClient(secretKey) {
   _client = new Stripe(secretKey, { apiVersion: "2024-11-20.acacia" });
   return _client;
 }
+function toBillingInterval(raw) {
+  if (isBillingInterval(raw)) return raw;
+  if (raw !== void 0) {
+    console.warn(
+      `[billing:stripe] unsupported price interval '${raw}' \u2014 recording as '${BILLING_INTERVAL.MONTH}'`
+    );
+  }
+  return BILLING_INTERVAL.MONTH;
+}
 function normalizeSubscription(sub) {
   const item = sub.items.data[0];
   const periodStart = item?.current_period_start ?? sub.current_period_start;
@@ -1123,16 +2045,16 @@ function normalizeSubscription(sub) {
     currentPeriodEnd: periodEnd ? new Date(periodEnd * 1e3) : /* @__PURE__ */ new Date(),
     cancelAtPeriodEnd: sub.cancel_at_period_end,
     trialEndsAt: sub.trial_end ? new Date(sub.trial_end * 1e3) : null,
-    interval: item?.price.recurring?.interval === BILLING_INTERVAL.YEAR ? BILLING_INTERVAL.YEAR : BILLING_INTERVAL.MONTH
+    interval: toBillingInterval(item?.price.recurring?.interval)
   };
 }
 function toResolvedPrice(p) {
   return {
     priceId: p.id,
     lookupKey: p.lookup_key ?? null,
-    unitAmount: p.unit_amount ?? 0,
+    unitAmount: BigInt(p.unit_amount ?? 0),
     currency: p.currency,
-    interval: p.recurring?.interval === BILLING_INTERVAL.YEAR ? BILLING_INTERVAL.YEAR : BILLING_INTERVAL.MONTH,
+    interval: toBillingInterval(p.recurring?.interval),
     nickname: p.nickname ?? null,
     productId: typeof p.product === "string" ? p.product : p.product?.id ?? "",
     active: p.active ?? true
@@ -1179,6 +2101,28 @@ var StripeProvider = class {
     });
     return { url: session.url ?? "" };
   }
+  async createPaymentCheckoutSession(opts) {
+    const stripe = await this.client();
+    const lineItem = opts.priceId ? { price: opts.priceId, quantity: opts.quantity ?? 1 } : {
+      price_data: {
+        currency: opts.currency.toLowerCase(),
+        // Stripe's SDK takes a JS number; toSafeNumber throws past 2^53
+        // instead of silently rounding.
+        unit_amount: toSafeNumber(opts.amount),
+        product_data: { name: opts.name }
+      },
+      quantity: opts.quantity ?? 1
+    };
+    const session = await stripe.checkout.sessions.create({
+      customer: opts.customerId,
+      mode: "payment",
+      line_items: [lineItem],
+      success_url: opts.successUrl,
+      cancel_url: opts.cancelUrl,
+      metadata: opts.metadata
+    });
+    return { url: session.url ?? "", sessionId: session.id };
+  }
   async resolvePriceById(priceId) {
     const stripe = await this.client();
     try {
@@ -1237,6 +2181,13 @@ var StripeProvider = class {
     } catch {
       throw new Error("[billing:stripe] Invalid webhook signature");
     }
+    if (raw.type === "checkout.session.completed" || raw.type === "checkout.session.async_payment_succeeded") {
+      const session = raw.data.object;
+      if (session.mode === "payment") {
+        return { type: raw.type, subscription: null, payment: normalizePaymentSession(session) };
+      }
+      return { type: raw.type, subscription: null };
+    }
     const isSubscriptionEvent = [
       "customer.subscription.created",
       "customer.subscription.updated",
@@ -1257,29 +2208,29 @@ var StripeProvider = class {
 };
 
 // src/middlewares/require-plan.ts
-import { setApiResponse as setApiResponse7, HTTP as HTTP7 } from "@fonderie/core";
+import { setApiResponse as setApiResponse12, HTTP as HTTP12 } from "@fonderie/core";
 function makeHandler(plans, store) {
   const allowed = Array.isArray(plans) ? plans : [plans];
   return async (ctx, next) => {
     if (!ctx.user) {
-      return setApiResponse7(HTTP7.UNAUTHORIZED, "UNAUTHORIZED", "Unauthorized");
+      return setApiResponse12(HTTP12.UNAUTHORIZED, "UNAUTHORIZED", "Unauthorized");
     }
     const subscriber = resolveSubscriber(ctx);
     if (!subscriber) {
-      return setApiResponse7(HTTP7.BAD_REQUEST, "SUBSCRIBER_REQUIRED", "Subscriber context required");
+      return setApiResponse12(HTTP12.BAD_REQUEST, "SUBSCRIBER_REQUIRED", "Subscriber context required");
     }
     const subscription = await getSubscription(subscriber.type, subscriber.id, store);
     if (!subscription || !allowed.includes(subscription.plan)) {
-      return setApiResponse7(
-        HTTP7.PAYMENT_REQUIRED,
+      return setApiResponse12(
+        HTTP12.PAYMENT_REQUIRED,
         "PLAN_UPGRADE_REQUIRED",
         "Plan upgrade required",
         { required: allowed, current: subscription?.plan ?? "none" }
       );
     }
     if (subscription.status !== "active" && subscription.status !== "trialing") {
-      return setApiResponse7(
-        HTTP7.PAYMENT_REQUIRED,
+      return setApiResponse12(
+        HTTP12.PAYMENT_REQUIRED,
         "SUBSCRIPTION_INACTIVE",
         "Subscription is not active",
         { status: subscription.status }
@@ -1293,55 +2244,26 @@ function requirePlan(plans, store, ctx, next) {
   if (ctx !== void 0 && next !== void 0) return handler(ctx, next);
   return handler;
 }
-
-// src/helpers.ts
-import { setApiResponse as setApiResponse8, HTTP as HTTP8 } from "@fonderie/core";
-function getBillingContext(ctx) {
-  return ctx.meta["billing"] ?? null;
-}
-function hasFeature(ctx, key) {
-  const billing = getBillingContext(ctx);
-  if (!billing) return true;
-  const status = billing.statuses[key];
-  if (!status) return true;
-  if (status.type === "feature") return status.enabled;
-  return true;
-}
-function getPlanLimit(ctx, key) {
-  const billing = getBillingContext(ctx);
-  if (!billing) return null;
-  const status = billing.statuses[key];
-  if (!status || status.type === "feature") return null;
-  return status.limit;
-}
-function getLimitStatus(ctx, key) {
-  const billing = getBillingContext(ctx);
-  if (!billing) return null;
-  return billing.statuses[key] ?? null;
-}
-function requireFeature(key) {
-  return (ctx, next) => {
-    if (!hasFeature(ctx, key)) {
-      return Promise.resolve(
-        setApiResponse8(
-          HTTP8.PAYMENT_REQUIRED,
-          "FEATURE_UNAVAILABLE",
-          `Feature '${key}' is not available on your current plan`
-        )
-      );
-    }
-    return next();
-  };
-}
 export {
   BILLING_INTERVAL,
+  BILLING_INTERVALS,
   BillingModule,
   DBCounterBackend,
+  DuplicateTransactionError,
+  InsufficientFundsError,
   MESSAGE_KEYS,
   MemoryCounterBackend,
   StripeProvider,
+  WALLET_LEDGER_TYPES,
   createPlan,
+  creditWallet,
+  currentGrantPeriod,
+  debitWallet,
+  debitWalletForMetric,
+  decodeLedgerCursor,
   deletePlan,
+  encodeLedgerCursor,
+  ensurePeriodicGrant,
   getDBPlans,
   getLimitStatus,
   getPlanById,
@@ -1350,14 +2272,23 @@ export {
   getPlans,
   getSubscription,
   getUsage,
+  getWalletBalance,
+  getWalletLedger,
+  getWalletRate,
+  getWalletStatus,
   hasFeature,
+  insufficientCreditsResponse,
+  isBillingInterval,
   recordUsage,
   requireFeature,
   requirePlan,
+  requireWalletBalance,
+  resolvePlanWallet,
   schemas_exports as schemas,
   toPlanDTO,
   toSubscriptionDTO,
-  toUsageRecordDTO,
+  toWalletDTO,
+  toWalletTransactionDTO,
   updatePlan,
   withBilling
 };