@drawbridge/drawbridge-utils 0.0.65 → 0.0.67

package/dist/billing.cjs

@@ -0,0 +1,373 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// lib/billing.js
+var billing_exports = {};
+__export(billing_exports, {
+  MARKUP: () => MARKUP,
+  action: () => action,
+  ai: () => ai,
+  grant: () => grant,
+  scrape: () => scrape
+});
+module.exports = __toCommonJS(billing_exports);
+
+// lib/transactions.js
+var import_drawbridge_telemetry = require("@drawbridge/drawbridge-telemetry");
+var insertTransaction = async ({
+  db,
+  user,
+  type,
+  category,
+  source,
+  amount,
+  _id,
+  stripeInvoiceId,
+  stripeEventId,
+  session,
+  ...rest
+}) => {
+  var _a;
+  const beforeRaw = (_a = user == null ? void 0 : user.balance) == null ? void 0 : _a[type];
+  const balance = typeof beforeRaw === "number" ? { before: beforeRaw, after: beforeRaw + amount } : void 0;
+  const trace = (0, import_drawbridge_telemetry.currentTraceId)();
+  await db.create({
+    authenticated: user,
+    collection: "transaction",
+    data: {
+      ..._id && { _id },
+      user: user == null ? void 0 : user.id,
+      type,
+      category,
+      source,
+      amount,
+      ...balance && { balance },
+      ...trace && { trace },
+      ...rest,
+      ...stripeInvoiceId && { stripeInvoiceId },
+      ...stripeEventId && { stripeEventId }
+    },
+    ...session && { options: { session } }
+  });
+};
+var credit = async ({
+  db,
+  user,
+  amount,
+  type,
+  category,
+  source,
+  _id,
+  stripeInvoiceId,
+  stripeEventId,
+  session,
+  ...rest
+}) => {
+  if (!Number.isInteger(amount) || amount <= 0) {
+    throw new Error(`credit() requires a positive integer amount, got ${amount}`);
+  }
+  if (!type) {
+    throw new Error('credit() requires a type (e.g., "ai")');
+  }
+  if (!source) {
+    throw new Error('credit() requires a source ("system" | "admin" | "user")');
+  }
+  await insertTransaction({
+    db,
+    user,
+    type,
+    category,
+    source,
+    amount,
+    _id,
+    stripeInvoiceId,
+    stripeEventId,
+    session,
+    ...rest
+  });
+};
+var debit = async ({
+  db,
+  user,
+  amount,
+  type,
+  category,
+  source,
+  stripeInvoiceId,
+  stripeEventId,
+  session,
+  ...rest
+}) => {
+  if (!Number.isInteger(amount) || amount <= 0) {
+    throw new Error(`debit() requires a positive integer amount, got ${amount}`);
+  }
+  if (!type) {
+    throw new Error('debit() requires a type (e.g., "ai")');
+  }
+  if (!source) {
+    throw new Error('debit() requires a source ("system" | "admin" | "user")');
+  }
+  await insertTransaction({
+    db,
+    user,
+    type,
+    category,
+    source,
+    amount: -amount,
+    stripeInvoiceId,
+    stripeEventId,
+    session,
+    ...rest
+  });
+};
+
+// lib/usage.js
+var incrementUsageTotals = async ({ controller, usageId, $inc, session }) => {
+  if (!usageId || !$inc) return;
+  const safeInc = Object.fromEntries(
+    Object.entries($inc).filter(([, value]) => {
+      const number = Number(value);
+      return Number.isFinite(number) && number !== 0;
+    })
+  );
+  if (Object.keys(safeInc).length === 0) return;
+  return controller.update({
+    collection: "usage",
+    data: { $inc: safeInc },
+    options: {
+      bypassDocumentValidation: true,
+      ...session && { session }
+    },
+    query: { id: usageId }
+  });
+};
+var isDuplicateKey = (error) => (error == null ? void 0 : error.code) === 11e3 || (error == null ? void 0 : error.code) === "11000" || /E11000|duplicate key/i.test((error == null ? void 0 : error.message) || "");
+var recordAction = async ({ controller, organization, usageId, type, units = 1, key, meta = {}, traceId, session }) => {
+  if (!controller || !organization || !usageId || !type || !key) return;
+  const amount = Number(units);
+  if (!Number.isFinite(amount) || amount === 0) return;
+  let inserted = false;
+  try {
+    const { lastErrorObject } = await controller.update({
+      collection: "action",
+      data: {
+        $setOnInsert: {
+          organization,
+          usage: usageId,
+          type,
+          units: amount,
+          key,
+          meta,
+          ...traceId && { traceId }
+        }
+      },
+      options: {
+        bypassDocumentValidation: true,
+        includeResultMetadata: true,
+        upsert: true,
+        ...session && { session }
+      },
+      query: {
+        key,
+        usage: usageId
+      }
+    });
+    inserted = Boolean(lastErrorObject == null ? void 0 : lastErrorObject.upserted);
+  } catch (error) {
+    if (isDuplicateKey(error) && !session) return;
+    throw error;
+  }
+  if (inserted) {
+    await incrementUsageTotals({ controller, usageId, $inc: { "totals.actions": amount }, session });
+  }
+};
+
+// lib/billing.js
+var import_drawbridge_telemetry2 = require("@drawbridge/drawbridge-telemetry");
+var logger = (0, import_drawbridge_telemetry2.createLogger)();
+var MARKUP = 1.3;
+var cost = {
+  "gemini-2.5-flash": {
+    cached: 3,
+    input: 30,
+    output: 250
+  },
+  "gemini-2.5-flash-image": {
+    cached: 3,
+    input: 30,
+    output: 3e3
+  }
+};
+var toolCost = {
+  search: 3.5
+};
+var toolPricing = Object.fromEntries(
+  Object.entries(toolCost).map(([tool, value]) => [
+    tool,
+    Math.ceil(value * MARKUP)
+  ])
+);
+var pricing = Object.fromEntries(
+  Object.entries(cost).map(([model, rates]) => [
+    model,
+    {
+      cached: Math.round(rates.cached * MARKUP),
+      input: Math.round(rates.input * MARKUP),
+      output: Math.round(rates.output * MARKUP)
+    }
+  ])
+);
+var sumCents = (rates, tokens) => Math.ceil(
+  (Number((tokens == null ? void 0 : tokens.cached) || 0) * rates.cached + Number((tokens == null ? void 0 : tokens.input) || 0) * rates.input + (Number((tokens == null ? void 0 : tokens.output) || 0) + Number((tokens == null ? void 0 : tokens.thinking) || 0)) * rates.output) / 1e6
+);
+var sumToolCents = (table, tools) => Object.entries(tools || {}).reduce(
+  (total, [name, used]) => total + (used && table[name] ? table[name] : 0),
+  0
+);
+var priceForRequest = (model, usage, tools) => {
+  const rates = pricing[model];
+  if (!rates) {
+    throw new Error(`Unknown model for pricing: ${model}`);
+  }
+  return sumCents(rates, usage) + Math.ceil(sumToolCents(toolPricing, tools));
+};
+var costForRequest = (model, usage, tools) => {
+  const rates = cost[model];
+  if (!rates) {
+    throw new Error(`Unknown model for cost: ${model}`);
+  }
+  return sumCents(rates, usage) + Math.ceil(sumToolCents(toolCost, tools));
+};
+var billRequest = async ({ db, user, model, usage, tools }) => {
+  const gross = priceForRequest(model, usage, tools);
+  const cogs = costForRequest(model, usage, tools);
+  await debit({
+    db,
+    user,
+    amount: gross,
+    type: "ai",
+    category: "usage",
+    source: "user",
+    ai: {
+      name: "google",
+      model,
+      tokens: usage,
+      tools,
+      rates: {
+        wholesale: cost[model],
+        retail: pricing[model]
+      },
+      totals: {
+        cost: cogs,
+        net: gross - cogs,
+        gross
+      }
+    }
+  });
+};
+var ai = {
+  // Retail cents for a request (what the user pays).
+  price: priceForRequest,
+  // Wholesale cents for a request (what we pay the provider).
+  cost: costForRequest,
+  // Deferred bill() the caller fires on success, so the debit lands only when
+  // the request succeeds and bundles into that request's Sentry trace. No user
+  // → a no-op.
+  bill: ({ db, user, model, usage, tools }) => (user == null ? void 0 : user.id) ? () => billRequest({ db, user, model, usage, tools }) : () => Promise.resolve()
+};
+var STANDARD_RATE_PER_GB = 8;
+var PREMIUM_RATE_PER_GB = 11;
+var PREMIUM_HOSTS = /* @__PURE__ */ new Set();
+var LOCAL_FLAT_CENTS = 1;
+var REUSE_FLAT_CENTS = 1;
+var ratePerGB = (url) => {
+  try {
+    return PREMIUM_HOSTS.has(new URL(url).hostname) ? PREMIUM_RATE_PER_GB : STANDARD_RATE_PER_GB;
+  } catch {
+    return STANDARD_RATE_PER_GB;
+  }
+};
+var scrapeFee = ({ provider, bytes, url, cold }) => {
+  if (!cold) return REUSE_FLAT_CENTS;
+  if (provider === "brightdata") {
+    return Math.ceil((bytes || 0) / 1e9 * ratePerGB(url) * 100 * MARKUP);
+  }
+  return LOCAL_FLAT_CENTS;
+};
+var scrape = {
+  // Cents for a scrape given its provider/bytes/cold basis.
+  fee: scrapeFee,
+  // Deferred bill(scrapeId) the scrape store's resolve() hands the generation
+  // flow. Atomically claims the cold (first-time) fee via the `charged` flag so
+  // a BrightData scrape's metered cost is recovered ONCE; later reuses pay the
+  // flat rate. Best-effort — a billing hiccup never fails generation.
+  bill: ({ controller, user, page, url }) => async (scrapeId) => {
+    var _a;
+    if (!(user == null ? void 0 : user.id) || !scrapeId) return;
+    try {
+      const claim = await controller.update({
+        collection: "scrape",
+        data: { $set: { charged: true } },
+        options: { bypassDocumentValidation: true },
+        query: { id: scrapeId, charged: { $ne: true } }
+      });
+      const cents = scrapeFee({
+        provider: (_a = page == null ? void 0 : page.provider) == null ? void 0 : _a.name,
+        bytes: page == null ? void 0 : page.bytes,
+        url: (page == null ? void 0 : page.url) || url,
+        cold: Boolean(claim == null ? void 0 : claim.value)
+      });
+      if (cents > 0) await debit({ db: controller, user, amount: cents, type: "ai", category: "usage", source: "user" });
+    } catch (error) {
+      logger.error(error, { extra: { action: "generation.scrape.bill", scrapeId } });
+    }
+  }
+};
+var grant = {
+  // System-issued credit (signup welcome, migration catch-up). Pass `session`
+  // to enroll the credit in the caller's transaction.
+  bonus: ({ db, user, amount, session }) => credit({ db, user, amount, type: "ai", category: "promotional", source: "system", ...session && { session } }),
+  // Admin-issued credit (manual grant). `user` is the recipient, not the admin.
+  admin: ({ db, user, amount }) => credit({ db, user, amount, type: "ai", category: "promotional", source: "admin" })
+};
+var action = {
+  // Append a billable action (idempotent on { usage, key }) + bump the
+  // usage.totals.actions display cache. The proven recordAction primitive.
+  record: recordAction,
+  // Authoritative per-period total to bill — sum(units) over the period's ledger
+  // rows. The Stripe meter emit (in the Stripe/sync layer) reports this number.
+  sum: async ({ controller, usageId }) => {
+    if (!controller || !usageId) return 0;
+    const [row] = await controller.aggregate({
+      collection: "action",
+      pipeline: [
+        { $match: { usage: usageId } },
+        { $group: { _id: null, units: { $sum: "$units" } } }
+      ]
+    }) || [];
+    return (row == null ? void 0 : row.units) || 0;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MARKUP,
+  action,
+  ai,
+  grant,
+  scrape
+});

package/dist/billing.d.cts

@@ -0,0 +1,300 @@
+import { credit, debit } from './transactions.cjs';
+import { recordAction } from './usage.cjs';
+import { createLogger } from '@drawbridge/drawbridge-telemetry';
+
+// Billing — the single source of truth for what Drawbridge charges, and the
+// single public surface for moving money. Namespaced by what's billed, each noun
+// exposing the pure fee math and a deferred bill()/credit:
+//
+//   billing.ai      { price, cost, bill }   AI requests   → credit rail (debit)
+//   billing.scrape  { fee, bill }           scrape fees   → credit rail (debit)
+//   billing.grant   { bonus, admin }        promo credits → credit rail (credit)
+//   billing.action  { record, sum }         usage actions → Stripe meter rail
+//
+// Sits on top of transactions.js (the generic credit/debit money rail) and
+// usage.js (the action-ledger + usage-totals primitives). Shopify order fees are
+// NOT billed here — they meter through @drawbridge/shopify's recordUsage and stay
+// Shopify-only by design. The Stripe meter EMIT for actions also stays in the
+// Stripe layer (utils must not depend on Stripe); billing.action.sum gives that
+// layer the authoritative number to report.
+
+
+const logger = createLogger();
+
+// Markup multiplier applied to provider cost to produce the retail price.
+// 1.3 = 30% margin. Change one number, all pricing updates. Shared across rails
+// (AI tokens + the metered scrape fee).
+const MARKUP = 1.3;
+
+// ─── AI (credit rail) ─────────────────────────────────────────────────────────
+
+// Raw per-model provider rates in cents per 1,000,000 tokens — the wholesale
+// cost. Sync from LiteLLM. Never apply markup here; `pricing` derives retail.
+const cost = {
+	'gemini-2.5-flash' : {
+		cached : 3,
+		input : 30,
+		output : 250
+	},
+	'gemini-2.5-flash-image' : {
+		cached : 3,
+		input : 30,
+		output : 3000
+	}
+};
+
+// Flat per-request fees Google charges when specific tools fire. Search
+// grounding is $35/1k requests → 3.5 cents/request, billed only when the tool
+// actually ran. Add more as Google introduces them.
+const toolCost = {
+	search : 3.5
+};
+
+const toolPricing = Object.fromEntries(
+	Object.entries( toolCost ).map( ( [ tool, value ] ) => [
+		tool,
+		Math.ceil( value * MARKUP )
+	] )
+);
+
+// Derived retail pricing in cents per 1,000,000 tokens — what users pay.
+const pricing = Object.fromEntries(
+	Object.entries( cost ).map( ( [ model, rates ] ) => [
+		model,
+		{
+			cached : Math.round( rates.cached * MARKUP ),
+			input : Math.round( rates.input * MARKUP ),
+			output : Math.round( rates.output * MARKUP )
+		}
+	] )
+);
+
+// Thinking tokens (Gemini 2.5 internal reasoning) bill at the output rate, so
+// they roll into the same multiplier even though they're tracked separately.
+const sumCents = ( rates, tokens ) => Math.ceil(
+	(
+		Number( tokens?.cached || 0 ) * rates.cached +
+		Number( tokens?.input || 0 ) * rates.input +
+		(
+			Number( tokens?.output || 0 ) +
+			Number( tokens?.thinking || 0 )
+		) * rates.output
+	) / 1_000_000
+);
+
+// Sum the per-request flat fees for the tools that actually fired.
+const sumToolCents = ( table, tools ) => Object.entries( tools || {} ).reduce(
+	( total, [ name, used ] ) => total + ( used && table[ name ] ? table[ name ] : 0 ),
+	0
+);
+
+// What we charge the user, rounded up so we never under-bill. Throws on an
+// unknown model so a typo doesn't silently fall back to a wrong price.
+const priceForRequest = ( model, usage, tools ) => {
+
+	const rates = pricing[ model ];
+
+	if( !rates ){
+
+		throw new Error( `Unknown model for pricing: ${ model }` );
+
+	}
+
+	return sumCents( rates, usage ) + Math.ceil( sumToolCents( toolPricing, tools ) );
+
+};
+
+// What we pay the provider. Recorded on each transaction row so margin is
+// computable per request without backfilling from git history.
+const costForRequest = ( model, usage, tools ) => {
+
+	const rates = cost[ model ];
+
+	if( !rates ){
+
+		throw new Error( `Unknown model for cost: ${ model }` );
+
+	}
+
+	return sumCents( rates, usage ) + Math.ceil( sumToolCents( toolCost, tools ) );
+
+};
+
+// Compute gross + cost from response usage and atomically debit the user.
+// Records the full income-statement line on the transaction row's `ai` sub-doc:
+// wholesale + retail per-1M rate snapshots, plus rolled-up cost, net, and gross.
+const billRequest = async ({ db, user, model, usage, tools }) => {
+
+	const gross = priceForRequest( model, usage, tools );
+	const cogs = costForRequest( model, usage, tools );
+
+	await debit({
+		db,
+		user,
+		amount : gross,
+		type : 'ai',
+		category : 'usage',
+		source : 'user',
+		ai : {
+			name : 'google',
+			model,
+			tokens : usage,
+			tools,
+			rates : {
+				wholesale : cost[ model ],
+				retail : pricing[ model ]
+			},
+			totals : {
+				cost : cogs,
+				net : gross - cogs,
+				gross
+			}
+		}
+	});
+
+};
+
+const ai = {
+
+	// Retail cents for a request (what the user pays).
+	price : priceForRequest,
+
+	// Wholesale cents for a request (what we pay the provider).
+	cost : costForRequest,
+
+	// Deferred bill() the caller fires on success, so the debit lands only when
+	// the request succeeds and bundles into that request's Sentry trace. No user
+	// → a no-op.
+	bill : ({ db, user, model, usage, tools }) =>
+		user?.id
+			? () => billRequest({ db, user, model, usage, tools })
+			: () => Promise.resolve()
+
+};
+
+// ─── Scrape (credit rail) ──────────────────────────────────────────────────────
+
+// BrightData (the Scraping Browser fallback) bills by GB, so its fee is METERED
+// to the traffic measured at scrape time; the 30% margin matches MARKUP above. A
+// cold local render and a cache reuse have no external cost, so they're small
+// flat fees (set to 0 to make either free). Tune against real BrightData invoices.
+const STANDARD_RATE_PER_GB = 8;
+const PREMIUM_RATE_PER_GB = 11;
+const PREMIUM_HOSTS = new Set();
+const LOCAL_FLAT_CENTS = 1;
+const REUSE_FLAT_CENTS = 1;
+
+const ratePerGB = ( url ) => {
+
+	try { return PREMIUM_HOSTS.has( new URL( url ).hostname ) ? PREMIUM_RATE_PER_GB : STANDARD_RATE_PER_GB; }
+	catch { return STANDARD_RATE_PER_GB; }
+
+};
+
+// Cents to charge. `cold` = the first generation off this scrape (charge the real
+// cost: metered for BrightData, a flat for a local render); otherwise it's a reuse
+// (flat). Rounded up so we never under-bill a fractional cent.
+const scrapeFee = ({ provider, bytes, url, cold }) => {
+
+	if( ! cold ) return REUSE_FLAT_CENTS;
+
+	if( provider === 'brightdata' ){
+
+		return Math.ceil( ( ( bytes || 0 ) / 1e9 ) * ratePerGB( url ) * 100 * MARKUP );
+
+	}
+
+	return LOCAL_FLAT_CENTS;
+
+};
+
+const scrape = {
+
+	// Cents for a scrape given its provider/bytes/cold basis.
+	fee : scrapeFee,
+
+	// Deferred bill(scrapeId) the scrape store's resolve() hands the generation
+	// flow. Atomically claims the cold (first-time) fee via the `charged` flag so
+	// a BrightData scrape's metered cost is recovered ONCE; later reuses pay the
+	// flat rate. Best-effort — a billing hiccup never fails generation.
+	bill : ({ controller, user, page, url }) => async ( scrapeId ) => {
+
+		if( ! user?.id || ! scrapeId ) return;
+
+		try {
+
+			const claim = await controller.update({
+				collection : 'scrape',
+				data : { $set : { charged : true } },
+				options : { bypassDocumentValidation : true },
+				query : { id : scrapeId, charged : { $ne : true } }
+			});
+
+			const cents = scrapeFee({
+				provider : page?.provider?.name,
+				bytes : page?.bytes,
+				url : page?.url || url,
+				cold : Boolean( claim?.value )
+			});
+
+			if( cents > 0 ) await debit({ db : controller, user, amount : cents, type : 'ai', category : 'usage', source : 'user' });
+
+		} catch ( error ) {
+
+			logger.error( error, { extra : { action : 'generation.scrape.bill', scrapeId } } );
+
+		}
+
+	}
+
+};
+
+// ─── Grants (credit rail) ──────────────────────────────────────────────────────
+
+// Promotional credits to a user's AI balance. `source` captures who acted; the
+// stream listener on the transaction collection does the balance.ai $inc.
+const grant = {
+
+	// System-issued credit (signup welcome, migration catch-up). Pass `session`
+	// to enroll the credit in the caller's transaction.
+	bonus : ({ db, user, amount, session }) =>
+		credit({ db, user, amount, type : 'ai', category : 'promotional', source : 'system', ...( session && { session }) }),
+
+	// Admin-issued credit (manual grant). `user` is the recipient, not the admin.
+	admin : ({ db, user, amount }) =>
+		credit({ db, user, amount, type : 'ai', category : 'promotional', source : 'admin' })
+
+};
+
+// ─── Actions (usage meter rail) ────────────────────────────────────────────────
+
+// The metered-usage rail (distinct from the AI credit rail above): an append-only
+// `action` ledger keyed on organization/period, summed at changeover and reported
+// to the Stripe meter. See the action-ledger design.
+const action = {
+
+	// Append a billable action (idempotent on { usage, key }) + bump the
+	// usage.totals.actions display cache. The proven recordAction primitive.
+	record : recordAction,
+
+	// Authoritative per-period total to bill — sum(units) over the period's ledger
+	// rows. The Stripe meter emit (in the Stripe/sync layer) reports this number.
+	sum : async ({ controller, usageId }) => {
+
+		if( ! controller || ! usageId ) return 0;
+
+		const [ row ] = await controller.aggregate({
+			collection : 'action',
+			pipeline : [
+				{ $match : { usage : usageId } },
+				{ $group : { _id : null, units : { $sum : '$units' } } }
+			]
+		}) || [];
+
+		return row?.units || 0;
+
+	}
+
+};
+
+export { MARKUP, action, ai, grant, scrape };