@drawbridge/drawbridge-utils 0.0.65 → 0.0.67

package/dist/usage.d.cts

@@ -0,0 +1,129 @@
+// Usage helpers — the per-org `usage` doc totals and the append-only `action`
+// ledger. These are the low-level usage primitives; billing.action.* (lib/
+// billing.js) is the public surface. Kept separate from billing so the generic
+// usage-totals $inc (used for non-billing totals like revenue/submissions/
+// entries too) doesn't live under the billing namespace. Re-exported from
+// index.js for backward compatibility with existing import sites.
+
+// Centralized $inc helper for the per-org usage doc. Replaces inline
+// $inc-with-bypass-validation patterns in drawbridge-api + drawbridge-sync.
+//
+// MongoDB's $inc with 0 / NaN / undefined / null writes the value into the
+// field (zeroing or NaN-ing it) instead of no-op'ing — so we filter the
+// $inc object to keep only finite, non-zero values and callers don't have
+// to remember the guard.
+//
+// `session` is forwarded when present so callers inside a transaction get
+// atomic writes; standalone callers omit it.
+const 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 }
+	});
+
+};
+
+// True for a MongoDB duplicate-key error (unique-index violation).
+const isDuplicateKey = ( error ) =>
+	error?.code === 11000
+	|| error?.code === '11000'
+	|| /E11000|duplicate key/i.test( error?.message || '' );
+
+// Record a billable action as a row in the append-only `action` ledger — the
+// source of truth for usage billing (summed per period at changeover).
+//
+// Idempotent via an UPSERT on the unique { usage, key }: a duplicate event (the
+// segment realtime path AND the sweep firing for the same membership, or a retry)
+// matches the existing row and no-ops — no duplicate-key error — so this is safe
+// to call INSIDE a caller's transaction (a thrown E11000 would abort the whole
+// transaction). The display cache `usage.totals.actions` is bumped ONLY when the
+// upsert actually inserts a new row, so a duplicate never double-counts.
+//
+// Pass `session` to make the ledger row + cache bump atomic with the caller's own
+// writes (e.g. the membership writes in a segment-sweep chunk, or the submission
+// docs) — all-or-nothing. Without a session it runs standalone.
+//   key   deterministic per source event, e.g. 'segment.join:<contact>:<segment>'
+//   units billable units (default 1; N for batch, e.g. accepted entries)
+//   meta  attribution ids { campaign, page, submission, segment, workflow, step, ... }
+const 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?.upserted );
+
+	} catch ( error ) {
+
+		// A concurrent upsert of the same { usage, key } can still race to E11000.
+		// Standalone: the other writer recorded it — skip. Inside a transaction:
+		// the txn is already aborted, so re-throw to let the caller retry the whole
+		// unit (which then sees the row and no-ops).
+		if( isDuplicateKey( error ) && ! session ) return;
+
+		throw error;
+
+	}
+
+	// Only a genuinely new row bumps the display cache (a matched duplicate must
+	// not double-count). Joined to the caller's transaction when a session is given.
+	if( inserted ){
+
+		await incrementUsageTotals({ controller, usageId, $inc : { 'totals.actions' : amount }, session });
+
+	}
+
+};
+
+export { incrementUsageTotals, isDuplicateKey, recordAction };

package/dist/usage.d.ts

@@ -0,0 +1,129 @@
+// Usage helpers — the per-org `usage` doc totals and the append-only `action`
+// ledger. These are the low-level usage primitives; billing.action.* (lib/
+// billing.js) is the public surface. Kept separate from billing so the generic
+// usage-totals $inc (used for non-billing totals like revenue/submissions/
+// entries too) doesn't live under the billing namespace. Re-exported from
+// index.js for backward compatibility with existing import sites.
+
+// Centralized $inc helper for the per-org usage doc. Replaces inline
+// $inc-with-bypass-validation patterns in drawbridge-api + drawbridge-sync.
+//
+// MongoDB's $inc with 0 / NaN / undefined / null writes the value into the
+// field (zeroing or NaN-ing it) instead of no-op'ing — so we filter the
+// $inc object to keep only finite, non-zero values and callers don't have
+// to remember the guard.
+//
+// `session` is forwarded when present so callers inside a transaction get
+// atomic writes; standalone callers omit it.
+const 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 }
+	});
+
+};
+
+// True for a MongoDB duplicate-key error (unique-index violation).
+const isDuplicateKey = ( error ) =>
+	error?.code === 11000
+	|| error?.code === '11000'
+	|| /E11000|duplicate key/i.test( error?.message || '' );
+
+// Record a billable action as a row in the append-only `action` ledger — the
+// source of truth for usage billing (summed per period at changeover).
+//
+// Idempotent via an UPSERT on the unique { usage, key }: a duplicate event (the
+// segment realtime path AND the sweep firing for the same membership, or a retry)
+// matches the existing row and no-ops — no duplicate-key error — so this is safe
+// to call INSIDE a caller's transaction (a thrown E11000 would abort the whole
+// transaction). The display cache `usage.totals.actions` is bumped ONLY when the
+// upsert actually inserts a new row, so a duplicate never double-counts.
+//
+// Pass `session` to make the ledger row + cache bump atomic with the caller's own
+// writes (e.g. the membership writes in a segment-sweep chunk, or the submission
+// docs) — all-or-nothing. Without a session it runs standalone.
+//   key   deterministic per source event, e.g. 'segment.join:<contact>:<segment>'
+//   units billable units (default 1; N for batch, e.g. accepted entries)
+//   meta  attribution ids { campaign, page, submission, segment, workflow, step, ... }
+const 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?.upserted );
+
+	} catch ( error ) {
+
+		// A concurrent upsert of the same { usage, key } can still race to E11000.
+		// Standalone: the other writer recorded it — skip. Inside a transaction:
+		// the txn is already aborted, so re-throw to let the caller retry the whole
+		// unit (which then sees the row and no-ops).
+		if( isDuplicateKey( error ) && ! session ) return;
+
+		throw error;
+
+	}
+
+	// Only a genuinely new row bumps the display cache (a matched duplicate must
+	// not double-count). Joined to the caller's transaction when a session is given.
+	if( inserted ){
+
+		await incrementUsageTotals({ controller, usageId, $inc : { 'totals.actions' : amount }, session });
+
+	}
+
+};
+
+export { incrementUsageTotals, isDuplicateKey, recordAction };

package/dist/usage.js

@@ -0,0 +1,65 @@
+// 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 });
+  }
+};
+export {
+  incrementUsageTotals,
+  isDuplicateKey,
+  recordAction
+};

package/package.json

@@ -37,6 +37,11 @@
       "import": "./dist/ai.js",
       "require": "./dist/ai.cjs"
     },
+    "./billing": {
+      "types": "./dist/billing.d.ts",
+      "import": "./dist/billing.js",
+      "require": "./dist/billing.cjs"
+    },
     "./color": {
       "types": "./dist/color.d.ts",
       "import": "./dist/color.js",
@@ -163,5 +168,5 @@
     "build": "tsup && npm publish"
   },
   "types": "dist/index.d.ts",
-  "version": "0.0.65"
+  "version": "0.0.67"
 }