@drawbridge/drawbridge-utils 0.0.70 → 0.0.72

package/dist/billing.cjs

@@ -277,9 +277,35 @@ var scrapeFee = ({ provider, bytes, requests, url, cold }) => {
   }
   return LOCAL_FLAT_CENTS;
 };
+var scrapeBreakdown = ({ provider, bytes, requests, url }) => {
+  if (provider === "brightdata") {
+    return {
+      provider,
+      basis: "bytes",
+      units: bytes || 0,
+      rate: ratePerGB(url),
+      rateUnit: "GB",
+      cents: scrapeFee({ provider, bytes, url, cold: true })
+    };
+  }
+  if (provider === "brightdata-unlocker") {
+    return {
+      provider,
+      basis: "requests",
+      units: requests || 0,
+      // cpmCents is cents-per-request; ×10 expresses it as dollars per 1,000.
+      rate: cpmCents(url) * 10,
+      rateUnit: "1K requests",
+      cents: scrapeFee({ provider, requests, url, cold: true })
+    };
+  }
+  return { provider: provider || "local", basis: "local", units: null, rate: null, rateUnit: null, cents: LOCAL_FLAT_CENTS };
+};
 var scrape = {
   // Cents for a scrape given its provider/bytes/cold basis.
   fee: scrapeFee,
+  // Itemized cold-fee breakdown (basis/units/rate/cents) for display + the scrape doc.
+  breakdown: scrapeBreakdown,
   // 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
@@ -361,6 +387,63 @@ var action = {
       await incrementUsageTotals({ controller, usageId, $inc: { "totals.actions": amount }, session });
     }
   },
+  // Batch variant of record() for a caller writing many ledger rows inside ONE
+  // transaction. A session forbids concurrent ops, so the alternative is a serial
+  // await-loop costing N round-trips; this does a single bulkWrite of idempotent
+  // { usage, key } upserts (ordered:false), then bumps usage.totals.actions by the
+  // summed units of ONLY the genuinely-inserted rows (upsertedIds) — mirroring
+  // record()'s per-row `inserted` gate. Rows are deduped by key within the batch
+  // so two upserts can't target the same { usage, key }. Pass `session` to join
+  // the caller's transaction (the intended path).
+  bulk: async ({ controller, organization, usageId, rows = [], session }) => {
+    if (!controller || !organization || !usageId || !Array.isArray(rows) || rows.length === 0) return;
+    const seen = /* @__PURE__ */ new Set();
+    const valid = [];
+    for (const row of rows) {
+      const { type, units = 1, key, meta = {}, traceId } = row || {};
+      const amount2 = Number(units);
+      if (!type || !key || !Number.isFinite(amount2) || amount2 === 0) continue;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      valid.push({ type, amount: amount2, key, meta, traceId });
+    }
+    if (valid.length === 0) return;
+    const result = await controller.bulk({
+      collection: "action",
+      pipeline: valid.map(({ type, amount: amount2, key, meta, traceId }) => ({
+        updateOne: {
+          filter: { key, usage: usageId },
+          update: {
+            $setOnInsert: {
+              organization,
+              usage: usageId,
+              type,
+              units: amount2,
+              key,
+              meta,
+              ...traceId && { traceId }
+            }
+          },
+          upsert: true
+        }
+      })),
+      options: {
+        bypassDocumentValidation: true,
+        ordered: false,
+        ...session && { session }
+      }
+    });
+    const amount = Object.keys((result == null ? void 0 : result.upsertedIds) || {}).reduce(
+      (sum, index) => {
+        var _a;
+        return sum + (((_a = valid[Number(index)]) == null ? void 0 : _a.amount) || 0);
+      },
+      0
+    );
+    if (amount > 0) {
+      await incrementUsageTotals({ controller, usageId, $inc: { "totals.actions": amount }, session });
+    }
+  },
   // 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 }) => {

package/dist/billing.d.cts

@@ -1,5 +1,5 @@
 import { credit, debit } from './transactions.cjs';
-import { isDuplicateKey, incrementUsageTotals } from './usage.cjs';
+import { incrementUsageTotals, isDuplicateKey } from './usage.cjs';
 import { createLogger } from '@drawbridge/drawbridge-telemetry';
 
 // Billing — the single source of truth for what Drawbridge charges, and the
@@ -9,7 +9,7 @@ import { createLogger } from '@drawbridge/drawbridge-telemetry';
 //   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
+//   billing.action  { record, bulk, 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
@@ -226,11 +226,53 @@ const scrapeFee = ({ provider, bytes, requests, url, cold }) => {
 
 };
 
+// Itemized cold-fee breakdown for the scrape doc / admin dashboard: the same cents
+// scrapeFee charges on a COLD scrape, plus the basis, the metered units, and the
+// wholesale provider rate behind it. Reuse hits aren't represented here — the doc
+// records its cold acquisition cost. `rate` is the wholesale rate in dollars per
+// `rateUnit` (pre-markup, i.e. the BrightData list price); `cents` is the retail fee
+// billed (incl MARKUP). Local renders have no external cost — flat, no rate.
+const scrapeBreakdown = ({ provider, bytes, requests, url }) => {
+
+	if( provider === 'brightdata' ){
+
+		return {
+			provider,
+			basis : 'bytes',
+			units : bytes || 0,
+			rate : ratePerGB( url ),
+			rateUnit : 'GB',
+			cents : scrapeFee({ provider, bytes, url, cold : true })
+		};
+
+	}
+
+	if( provider === 'brightdata-unlocker' ){
+
+		return {
+			provider,
+			basis : 'requests',
+			units : requests || 0,
+			// cpmCents is cents-per-request; ×10 expresses it as dollars per 1,000.
+			rate : cpmCents( url ) * 10,
+			rateUnit : '1K requests',
+			cents : scrapeFee({ provider, requests, url, cold : true })
+		};
+
+	}
+
+	return { provider : provider || 'local', basis : 'local', units : null, rate : null, rateUnit : null, cents : LOCAL_FLAT_CENTS };
+
+};
+
 const scrape = {
 
 	// Cents for a scrape given its provider/bytes/cold basis.
 	fee : scrapeFee,
 
+	// Itemized cold-fee breakdown (basis/units/rate/cents) for display + the scrape doc.
+	breakdown : scrapeBreakdown,
+
 	// 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
@@ -357,6 +399,76 @@ const action = {
 
 	},
 
+	// Batch variant of record() for a caller writing many ledger rows inside ONE
+	// transaction. A session forbids concurrent ops, so the alternative is a serial
+	// await-loop costing N round-trips; this does a single bulkWrite of idempotent
+	// { usage, key } upserts (ordered:false), then bumps usage.totals.actions by the
+	// summed units of ONLY the genuinely-inserted rows (upsertedIds) — mirroring
+	// record()'s per-row `inserted` gate. Rows are deduped by key within the batch
+	// so two upserts can't target the same { usage, key }. Pass `session` to join
+	// the caller's transaction (the intended path).
+	bulk : async ({ controller, organization, usageId, rows = [], session }) => {
+
+		if( ! controller || ! organization || ! usageId || ! Array.isArray( rows ) || rows.length === 0 ) return;
+
+		const seen = new Set();
+		const valid = [];
+
+		for( const row of rows ){
+
+			const { type, units = 1, key, meta = {}, traceId } = row || {};
+			const amount = Number( units );
+
+			if( ! type || ! key || ! Number.isFinite( amount ) || amount === 0 ) continue;
+			if( seen.has( key ) ) continue;
+
+			seen.add( key );
+			valid.push({ type, amount, key, meta, traceId });
+
+		}
+
+		if( valid.length === 0 ) return;
+
+		const result = await controller.bulk({
+			collection : 'action',
+			pipeline : valid.map( ({ type, amount, key, meta, traceId }) => ({
+				updateOne : {
+					filter : { key, usage : usageId },
+					update : {
+						$setOnInsert : {
+							organization,
+							usage : usageId,
+							type,
+							units : amount,
+							key,
+							meta,
+							...( traceId && { traceId })
+						}
+					},
+					upsert : true
+				}
+			})),
+			options : {
+				bypassDocumentValidation : true,
+				ordered : false,
+				...( session && { session })
+			}
+		});
+
+		// upsertedIds = { <opIndex>: _id } for newly-inserted rows; sum their units.
+		const amount = Object.keys( result?.upsertedIds || {} ).reduce(
+			( sum, index ) => sum + ( valid[ Number( index ) ]?.amount || 0 ),
+			0
+		);
+
+		if( amount > 0 ){
+
+			await incrementUsageTotals({ controller, usageId, $inc : { 'totals.actions' : amount }, session });
+
+		}
+
+	},
+
 	// 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 }) => {

package/dist/billing.d.ts

@@ -1,5 +1,5 @@
 import { credit, debit } from './transactions.js';
-import { isDuplicateKey, incrementUsageTotals } from './usage.js';
+import { incrementUsageTotals, isDuplicateKey } from './usage.js';
 import { createLogger } from '@drawbridge/drawbridge-telemetry';
 
 // Billing — the single source of truth for what Drawbridge charges, and the
@@ -9,7 +9,7 @@ import { createLogger } from '@drawbridge/drawbridge-telemetry';
 //   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
+//   billing.action  { record, bulk, 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
@@ -226,11 +226,53 @@ const scrapeFee = ({ provider, bytes, requests, url, cold }) => {
 
 };
 
+// Itemized cold-fee breakdown for the scrape doc / admin dashboard: the same cents
+// scrapeFee charges on a COLD scrape, plus the basis, the metered units, and the
+// wholesale provider rate behind it. Reuse hits aren't represented here — the doc
+// records its cold acquisition cost. `rate` is the wholesale rate in dollars per
+// `rateUnit` (pre-markup, i.e. the BrightData list price); `cents` is the retail fee
+// billed (incl MARKUP). Local renders have no external cost — flat, no rate.
+const scrapeBreakdown = ({ provider, bytes, requests, url }) => {
+
+	if( provider === 'brightdata' ){
+
+		return {
+			provider,
+			basis : 'bytes',
+			units : bytes || 0,
+			rate : ratePerGB( url ),
+			rateUnit : 'GB',
+			cents : scrapeFee({ provider, bytes, url, cold : true })
+		};
+
+	}
+
+	if( provider === 'brightdata-unlocker' ){
+
+		return {
+			provider,
+			basis : 'requests',
+			units : requests || 0,
+			// cpmCents is cents-per-request; ×10 expresses it as dollars per 1,000.
+			rate : cpmCents( url ) * 10,
+			rateUnit : '1K requests',
+			cents : scrapeFee({ provider, requests, url, cold : true })
+		};
+
+	}
+
+	return { provider : provider || 'local', basis : 'local', units : null, rate : null, rateUnit : null, cents : LOCAL_FLAT_CENTS };
+
+};
+
 const scrape = {
 
 	// Cents for a scrape given its provider/bytes/cold basis.
 	fee : scrapeFee,
 
+	// Itemized cold-fee breakdown (basis/units/rate/cents) for display + the scrape doc.
+	breakdown : scrapeBreakdown,
+
 	// 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
@@ -357,6 +399,76 @@ const action = {
 
 	},
 
+	// Batch variant of record() for a caller writing many ledger rows inside ONE
+	// transaction. A session forbids concurrent ops, so the alternative is a serial
+	// await-loop costing N round-trips; this does a single bulkWrite of idempotent
+	// { usage, key } upserts (ordered:false), then bumps usage.totals.actions by the
+	// summed units of ONLY the genuinely-inserted rows (upsertedIds) — mirroring
+	// record()'s per-row `inserted` gate. Rows are deduped by key within the batch
+	// so two upserts can't target the same { usage, key }. Pass `session` to join
+	// the caller's transaction (the intended path).
+	bulk : async ({ controller, organization, usageId, rows = [], session }) => {
+
+		if( ! controller || ! organization || ! usageId || ! Array.isArray( rows ) || rows.length === 0 ) return;
+
+		const seen = new Set();
+		const valid = [];
+
+		for( const row of rows ){
+
+			const { type, units = 1, key, meta = {}, traceId } = row || {};
+			const amount = Number( units );
+
+			if( ! type || ! key || ! Number.isFinite( amount ) || amount === 0 ) continue;
+			if( seen.has( key ) ) continue;
+
+			seen.add( key );
+			valid.push({ type, amount, key, meta, traceId });
+
+		}
+
+		if( valid.length === 0 ) return;
+
+		const result = await controller.bulk({
+			collection : 'action',
+			pipeline : valid.map( ({ type, amount, key, meta, traceId }) => ({
+				updateOne : {
+					filter : { key, usage : usageId },
+					update : {
+						$setOnInsert : {
+							organization,
+							usage : usageId,
+							type,
+							units : amount,
+							key,
+							meta,
+							...( traceId && { traceId })
+						}
+					},
+					upsert : true
+				}
+			})),
+			options : {
+				bypassDocumentValidation : true,
+				ordered : false,
+				...( session && { session })
+			}
+		});
+
+		// upsertedIds = { <opIndex>: _id } for newly-inserted rows; sum their units.
+		const amount = Object.keys( result?.upsertedIds || {} ).reduce(
+			( sum, index ) => sum + ( valid[ Number( index ) ]?.amount || 0 ),
+			0
+		);
+
+		if( amount > 0 ){
+
+			await incrementUsageTotals({ controller, usageId, $inc : { 'totals.actions' : amount }, session });
+
+		}
+
+	},
+
 	// 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 }) => {

package/dist/billing.js

@@ -248,9 +248,35 @@ var scrapeFee = ({ provider, bytes, requests, url, cold }) => {
   }
   return LOCAL_FLAT_CENTS;
 };
+var scrapeBreakdown = ({ provider, bytes, requests, url }) => {
+  if (provider === "brightdata") {
+    return {
+      provider,
+      basis: "bytes",
+      units: bytes || 0,
+      rate: ratePerGB(url),
+      rateUnit: "GB",
+      cents: scrapeFee({ provider, bytes, url, cold: true })
+    };
+  }
+  if (provider === "brightdata-unlocker") {
+    return {
+      provider,
+      basis: "requests",
+      units: requests || 0,
+      // cpmCents is cents-per-request; ×10 expresses it as dollars per 1,000.
+      rate: cpmCents(url) * 10,
+      rateUnit: "1K requests",
+      cents: scrapeFee({ provider, requests, url, cold: true })
+    };
+  }
+  return { provider: provider || "local", basis: "local", units: null, rate: null, rateUnit: null, cents: LOCAL_FLAT_CENTS };
+};
 var scrape = {
   // Cents for a scrape given its provider/bytes/cold basis.
   fee: scrapeFee,
+  // Itemized cold-fee breakdown (basis/units/rate/cents) for display + the scrape doc.
+  breakdown: scrapeBreakdown,
   // 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
@@ -332,6 +358,63 @@ var action = {
       await incrementUsageTotals({ controller, usageId, $inc: { "totals.actions": amount }, session });
     }
   },
+  // Batch variant of record() for a caller writing many ledger rows inside ONE
+  // transaction. A session forbids concurrent ops, so the alternative is a serial
+  // await-loop costing N round-trips; this does a single bulkWrite of idempotent
+  // { usage, key } upserts (ordered:false), then bumps usage.totals.actions by the
+  // summed units of ONLY the genuinely-inserted rows (upsertedIds) — mirroring
+  // record()'s per-row `inserted` gate. Rows are deduped by key within the batch
+  // so two upserts can't target the same { usage, key }. Pass `session` to join
+  // the caller's transaction (the intended path).
+  bulk: async ({ controller, organization, usageId, rows = [], session }) => {
+    if (!controller || !organization || !usageId || !Array.isArray(rows) || rows.length === 0) return;
+    const seen = /* @__PURE__ */ new Set();
+    const valid = [];
+    for (const row of rows) {
+      const { type, units = 1, key, meta = {}, traceId } = row || {};
+      const amount2 = Number(units);
+      if (!type || !key || !Number.isFinite(amount2) || amount2 === 0) continue;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      valid.push({ type, amount: amount2, key, meta, traceId });
+    }
+    if (valid.length === 0) return;
+    const result = await controller.bulk({
+      collection: "action",
+      pipeline: valid.map(({ type, amount: amount2, key, meta, traceId }) => ({
+        updateOne: {
+          filter: { key, usage: usageId },
+          update: {
+            $setOnInsert: {
+              organization,
+              usage: usageId,
+              type,
+              units: amount2,
+              key,
+              meta,
+              ...traceId && { traceId }
+            }
+          },
+          upsert: true
+        }
+      })),
+      options: {
+        bypassDocumentValidation: true,
+        ordered: false,
+        ...session && { session }
+      }
+    });
+    const amount = Object.keys((result == null ? void 0 : result.upsertedIds) || {}).reduce(
+      (sum, index) => {
+        var _a;
+        return sum + (((_a = valid[Number(index)]) == null ? void 0 : _a.amount) || 0);
+      },
+      0
+    );
+    if (amount > 0) {
+      await incrementUsageTotals({ controller, usageId, $inc: { "totals.actions": amount }, session });
+    }
+  },
   // 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 }) => {

package/package.json

@@ -158,5 +158,5 @@
     "build": "tsup && npm publish"
   },
   "types": "dist/index.d.ts",
-  "version": "0.0.70"
+  "version": "0.0.72"
 }