@drawbridge/drawbridge-utils 0.0.62 → 0.0.63

package/dist/index.cjs

@@ -393,28 +393,44 @@ 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 }) => {
+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 {
-    await controller.create({
+    const { lastErrorObject } = await controller.update({
       collection: "action",
       data: {
-        organization,
-        usage: usageId,
-        type,
-        units: amount,
+        $setOnInsert: {
+          organization,
+          usage: usageId,
+          type,
+          units: amount,
+          key,
+          meta,
+          ...traceId && { traceId }
+        }
+      },
+      options: {
+        bypassDocumentValidation: true,
+        includeResultMetadata: true,
+        upsert: true,
+        ...session && { session }
+      },
+      query: {
         key,
-        meta,
-        ...traceId && { traceId }
+        usage: usageId
       }
     });
+    inserted = Boolean(lastErrorObject == null ? void 0 : lastErrorObject.upserted);
   } catch (error) {
-    if (isDuplicateKey(error)) return;
+    if (isDuplicateKey(error) && !session) return;
     throw error;
   }
-  await incrementUsageTotals({ controller, usageId, $inc: { "totals.actions": amount } });
+  if (inserted) {
+    await incrementUsageTotals({ controller, usageId, $inc: { "totals.actions": amount }, session });
+  }
 };
 var percentage = (value1, value2, decimals = 1) => ((value1 || 0) / (value2 || 0) * 100 || 0).toFixed(decimals);
 var reducers = {

package/dist/index.d.cts

@@ -386,18 +386,22 @@ const isDuplicateKey = ( error ) =>
 	|| /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). The unique
-// `key` makes recording idempotent: a duplicate (the segment realtime path AND the
-// sweep firing for the same membership, or a job retry) hits the unique index and
-// is skipped, so it can never double-count. On a genuinely new row we bump the
-// display cache `usage.totals.actions` by the same units; the billed number always
-// comes from summing the ledger, so a missed cache $inc is only cosmetic (it
-// self-heals at changeover). No transaction needed — the unique index is the
-// atomic dedup.
+// 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 }) => {
+const recordAction = async ({ controller, organization, usageId, type, units = 1, key, meta = {}, traceId, session }) => {
 
 	if( ! controller || ! organization || ! usageId || ! type || ! key ) return;
 
@@ -405,34 +409,56 @@ const recordAction = async ({ controller, organization, usageId, type, units = 1
 
 	if( ! Number.isFinite( amount ) || amount === 0 ) return;
 
+	let inserted = false;
+
 	try {
 
-		await controller.create({
+		const { lastErrorObject } = await controller.update({
 			collection : 'action',
 			data : {
-				organization,
-				usage : usageId,
-				type,
-				units : amount,
+				$setOnInsert : {
+					organization,
+					usage : usageId,
+					type,
+					units : amount,
+					key,
+					meta,
+					...( traceId && { traceId })
+				}
+			},
+			options : {
+				bypassDocumentValidation : true,
+				includeResultMetadata : true,
+				upsert : true,
+				...( session && { session })
+			},
+			query : {
 				key,
-				meta,
-				...( traceId && { traceId })
+				usage : usageId
 			}
 		});
 
+		inserted = Boolean( lastErrorObject?.upserted );
+
 	} catch ( error ) {
 
-		// Duplicate key = this exact action was already recorded — skip silently.
-		// This is the dedup that makes billing drift-proof. Re-throw anything else.
-		if( isDuplicateKey( error ) ) return;
+		// 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;
 
 	}
 
-	// New row only — keep the display cache in step. Billing sums the ledger, so
-	// this is cosmetic and self-heals at changeover if it ever fails.
-	await incrementUsageTotals({ controller, usageId, $inc : { 'totals.actions' : amount } });
+	// 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 });
+
+	}
 
 };
 

package/dist/index.d.ts

@@ -386,18 +386,22 @@ const isDuplicateKey = ( error ) =>
 	|| /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). The unique
-// `key` makes recording idempotent: a duplicate (the segment realtime path AND the
-// sweep firing for the same membership, or a job retry) hits the unique index and
-// is skipped, so it can never double-count. On a genuinely new row we bump the
-// display cache `usage.totals.actions` by the same units; the billed number always
-// comes from summing the ledger, so a missed cache $inc is only cosmetic (it
-// self-heals at changeover). No transaction needed — the unique index is the
-// atomic dedup.
+// 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 }) => {
+const recordAction = async ({ controller, organization, usageId, type, units = 1, key, meta = {}, traceId, session }) => {
 
 	if( ! controller || ! organization || ! usageId || ! type || ! key ) return;
 
@@ -405,34 +409,56 @@ const recordAction = async ({ controller, organization, usageId, type, units = 1
 
 	if( ! Number.isFinite( amount ) || amount === 0 ) return;
 
+	let inserted = false;
+
 	try {
 
-		await controller.create({
+		const { lastErrorObject } = await controller.update({
 			collection : 'action',
 			data : {
-				organization,
-				usage : usageId,
-				type,
-				units : amount,
+				$setOnInsert : {
+					organization,
+					usage : usageId,
+					type,
+					units : amount,
+					key,
+					meta,
+					...( traceId && { traceId })
+				}
+			},
+			options : {
+				bypassDocumentValidation : true,
+				includeResultMetadata : true,
+				upsert : true,
+				...( session && { session })
+			},
+			query : {
 				key,
-				meta,
-				...( traceId && { traceId })
+				usage : usageId
 			}
 		});
 
+		inserted = Boolean( lastErrorObject?.upserted );
+
 	} catch ( error ) {
 
-		// Duplicate key = this exact action was already recorded — skip silently.
-		// This is the dedup that makes billing drift-proof. Re-throw anything else.
-		if( isDuplicateKey( error ) ) return;
+		// 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;
 
 	}
 
-	// New row only — keep the display cache in step. Billing sums the ledger, so
-	// this is cosmetic and self-heals at changeover if it ever fails.
-	await incrementUsageTotals({ controller, usageId, $inc : { 'totals.actions' : amount } });
+	// 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 });
+
+	}
 
 };
 

package/dist/index.js

@@ -337,28 +337,44 @@ 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 }) => {
+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 {
-    await controller.create({
+    const { lastErrorObject } = await controller.update({
       collection: "action",
       data: {
-        organization,
-        usage: usageId,
-        type,
-        units: amount,
+        $setOnInsert: {
+          organization,
+          usage: usageId,
+          type,
+          units: amount,
+          key,
+          meta,
+          ...traceId && { traceId }
+        }
+      },
+      options: {
+        bypassDocumentValidation: true,
+        includeResultMetadata: true,
+        upsert: true,
+        ...session && { session }
+      },
+      query: {
         key,
-        meta,
-        ...traceId && { traceId }
+        usage: usageId
       }
     });
+    inserted = Boolean(lastErrorObject == null ? void 0 : lastErrorObject.upserted);
   } catch (error) {
-    if (isDuplicateKey(error)) return;
+    if (isDuplicateKey(error) && !session) return;
     throw error;
   }
-  await incrementUsageTotals({ controller, usageId, $inc: { "totals.actions": amount } });
+  if (inserted) {
+    await incrementUsageTotals({ controller, usageId, $inc: { "totals.actions": amount }, session });
+  }
 };
 var percentage = (value1, value2, decimals = 1) => ((value1 || 0) / (value2 || 0) * 100 || 0).toFixed(decimals);
 var reducers = {

package/package.json

@@ -157,5 +157,5 @@
     "build": "tsup && npm publish"
   },
   "types": "dist/index.d.ts",
-  "version": "0.0.62"
+  "version": "0.0.63"
 }