@drawbridge/drawbridge-utils 0.0.67 → 0.0.69

package/dist/billing.cjs

@@ -157,45 +157,6 @@ var incrementUsageTotals = async ({ controller, usageId, $inc, session }) => {
   });
 };
 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");
@@ -346,9 +307,52 @@ var grant = {
   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,
+  // Append a billable action to the ledger (idempotent UPSERT on { usage, key }:
+  // a duplicate event — the segment realtime path AND the sweep, or a retry —
+  // matches the existing row and no-ops, so it's safe inside a caller's
+  // transaction), then bump the usage.totals.actions display cache ONLY on a
+  // genuinely new row. Pass `session` to join the caller's transaction.
+  //   key   deterministic per source event, e.g. 'segment.join:<contact>:<segment>'
+  //   units billable units (default 1; N for batch, e.g. accepted entries)
+  record: 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 });
+    }
+  },
   // 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 { recordAction } from './usage.cjs';
+import { isDuplicateKey, incrementUsageTotals } from './usage.cjs';
 import { createLogger } from '@drawbridge/drawbridge-telemetry';
 
 // Billing — the single source of truth for what Drawbridge charges, and the
@@ -273,9 +273,70 @@ const grant = {
 // 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,
+	// Append a billable action to the ledger (idempotent UPSERT on { usage, key }:
+	// a duplicate event — the segment realtime path AND the sweep, or a retry —
+	// matches the existing row and no-ops, so it's safe inside a caller's
+	// transaction), then bump the usage.totals.actions display cache ONLY on a
+	// genuinely new row. Pass `session` to join the caller's transaction.
+	//   key   deterministic per source event, e.g. 'segment.join:<contact>:<segment>'
+	//   units billable units (default 1; N for batch, e.g. accepted entries)
+	record : 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 unit.
+			if( isDuplicateKey( error ) && ! session ) return;
+
+			throw error;
+
+		}
+
+		if( inserted ){
+
+			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.

package/dist/billing.d.ts

@@ -1,5 +1,5 @@
 import { credit, debit } from './transactions.js';
-import { recordAction } from './usage.js';
+import { isDuplicateKey, incrementUsageTotals } from './usage.js';
 import { createLogger } from '@drawbridge/drawbridge-telemetry';
 
 // Billing — the single source of truth for what Drawbridge charges, and the
@@ -273,9 +273,70 @@ const grant = {
 // 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,
+	// Append a billable action to the ledger (idempotent UPSERT on { usage, key }:
+	// a duplicate event — the segment realtime path AND the sweep, or a retry —
+	// matches the existing row and no-ops, so it's safe inside a caller's
+	// transaction), then bump the usage.totals.actions display cache ONLY on a
+	// genuinely new row. Pass `session` to join the caller's transaction.
+	//   key   deterministic per source event, e.g. 'segment.join:<contact>:<segment>'
+	//   units billable units (default 1; N for batch, e.g. accepted entries)
+	record : 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 unit.
+			if( isDuplicateKey( error ) && ! session ) return;
+
+			throw error;
+
+		}
+
+		if( inserted ){
+
+			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.

package/dist/billing.js

@@ -128,45 +128,6 @@ var incrementUsageTotals = async ({ controller, usageId, $inc, session }) => {
   });
 };
 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
 import { createLogger } from "@drawbridge/drawbridge-telemetry";
@@ -317,9 +278,52 @@ var grant = {
   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,
+  // Append a billable action to the ledger (idempotent UPSERT on { usage, key }:
+  // a duplicate event — the segment realtime path AND the sweep, or a retry —
+  // matches the existing row and no-ops, so it's safe inside a caller's
+  // transaction), then bump the usage.totals.actions display cache ONLY on a
+  // genuinely new row. Pass `session` to join the caller's transaction.
+  //   key   deterministic per source event, e.g. 'segment.join:<contact>:<segment>'
+  //   units billable units (default 1; N for batch, e.g. accepted entries)
+  record: 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 });
+    }
+  },
   // 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/usage.cjs

@@ -20,8 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var usage_exports = {};
 __export(usage_exports, {
   incrementUsageTotals: () => incrementUsageTotals,
-  isDuplicateKey: () => isDuplicateKey,
-  recordAction: () => recordAction
+  isDuplicateKey: () => isDuplicateKey
 });
 module.exports = __toCommonJS(usage_exports);
 var incrementUsageTotals = async ({ controller, usageId, $inc, session }) => {
@@ -44,48 +43,8 @@ var incrementUsageTotals = async ({ controller, usageId, $inc, session }) => {
   });
 };
 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 });
-  }
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   incrementUsageTotals,
-  isDuplicateKey,
-  recordAction
+  isDuplicateKey
 });

package/dist/usage.d.cts

@@ -1,9 +1,8 @@
-// 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.
+// Usage helpers — the per-org `usage` doc totals $inc and a duplicate-key guard.
+// Generic, non-billing primitives (incrementUsageTotals is used for revenue /
+// submissions / entries totals too), so they live here rather than under the
+// billing namespace; billing.action.record (lib/billing.js) uses both to write
+// the action ledger. Re-exported from index.js for existing import sites.
 
 // Centralized $inc helper for the per-org usage doc. Replaces inline
 // $inc-with-bypass-validation patterns in drawbridge-api + drawbridge-sync.
@@ -49,81 +48,4 @@ const isDuplicateKey = ( error ) =>
 	|| 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 };
+export { incrementUsageTotals, isDuplicateKey };

package/dist/usage.d.ts

@@ -1,9 +1,8 @@
-// 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.
+// Usage helpers — the per-org `usage` doc totals $inc and a duplicate-key guard.
+// Generic, non-billing primitives (incrementUsageTotals is used for revenue /
+// submissions / entries totals too), so they live here rather than under the
+// billing namespace; billing.action.record (lib/billing.js) uses both to write
+// the action ledger. Re-exported from index.js for existing import sites.
 
 // Centralized $inc helper for the per-org usage doc. Replaces inline
 // $inc-with-bypass-validation patterns in drawbridge-api + drawbridge-sync.
@@ -49,81 +48,4 @@ const isDuplicateKey = ( error ) =>
 	|| 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 };
+export { incrementUsageTotals, isDuplicateKey };

package/dist/usage.js

@@ -19,47 +19,7 @@ var incrementUsageTotals = async ({ controller, usageId, $inc, session }) => {
   });
 };
 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
+  isDuplicateKey
 };