@drawbridge/drawbridge-utils 0.0.61 → 0.0.63

package/dist/index.cjs

@@ -43,10 +43,12 @@ __export(index_exports, {
   gigabyte: () => gigabyte,
   incrementUsageTotals: () => incrementUsageTotals,
   infinite: () => infinite,
+  isDuplicateKey: () => isDuplicateKey,
   isInfinite: () => isInfinite,
   megabyte: () => megabyte,
   nanoid: () => nanoid,
   percentage: () => percentage,
+  recordAction: () => recordAction,
   reducers: () => reducers,
   regex: () => regex,
   shareUrls: () => shareUrls,
@@ -390,6 +392,46 @@ var incrementUsageTotals = async ({ controller, usageId, $inc, 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 });
+  }
+};
 var percentage = (value1, value2, decimals = 1) => ((value1 || 0) / (value2 || 0) * 100 || 0).toFixed(decimals);
 var reducers = {
   fields: (data2 = [], callback = () => ({})) => data2.reduce(
@@ -483,10 +525,12 @@ var currency = (val) => (0, import_currency_codes.code)(val);
   gigabyte,
   incrementUsageTotals,
   infinite,
+  isDuplicateKey,
   isInfinite,
   megabyte,
   nanoid,
   percentage,
+  recordAction,
   reducers,
   regex,
   shareUrls,

package/dist/index.d.cts

@@ -379,6 +379,89 @@ const incrementUsageTotals = async ({ controller, usageId, $inc, session }) => {
 
 };
 
+// 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 });
+
+	}
+
+};
+
 const percentage = ( value1, value2, decimals = 1 ) => ( ( ( ( value1 || 0 ) / ( value2 || 0 ) ) * 100 ) || 0 ).toFixed( decimals );
 
 const reducers = {
@@ -477,4 +560,4 @@ const currencies = data.map( ( item ) => ({
 
 const currency = ( val ) => code( val );
 
-export { bytesToGB, bytesToMB, capitalize, constants, currencies, currency, expiredPaymentMethod, formatCurrency, formatDateString, formatNumber, getPlanFeature, gigabyte, incrementUsageTotals, infinite, isInfinite, megabyte, nanoid, percentage, reducers, regex, shareUrls, urlRoot };
+export { bytesToGB, bytesToMB, capitalize, constants, currencies, currency, expiredPaymentMethod, formatCurrency, formatDateString, formatNumber, getPlanFeature, gigabyte, incrementUsageTotals, infinite, isDuplicateKey, isInfinite, megabyte, nanoid, percentage, recordAction, reducers, regex, shareUrls, urlRoot };

package/dist/index.d.ts

@@ -379,6 +379,89 @@ const incrementUsageTotals = async ({ controller, usageId, $inc, session }) => {
 
 };
 
+// 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 });
+
+	}
+
+};
+
 const percentage = ( value1, value2, decimals = 1 ) => ( ( ( ( value1 || 0 ) / ( value2 || 0 ) ) * 100 ) || 0 ).toFixed( decimals );
 
 const reducers = {
@@ -477,4 +560,4 @@ const currencies = data.map( ( item ) => ({
 
 const currency = ( val ) => code( val );
 
-export { bytesToGB, bytesToMB, capitalize, constants, currencies, currency, expiredPaymentMethod, formatCurrency, formatDateString, formatNumber, getPlanFeature, gigabyte, incrementUsageTotals, infinite, isInfinite, megabyte, nanoid, percentage, reducers, regex, shareUrls, urlRoot };
+export { bytesToGB, bytesToMB, capitalize, constants, currencies, currency, expiredPaymentMethod, formatCurrency, formatDateString, formatNumber, getPlanFeature, gigabyte, incrementUsageTotals, infinite, isDuplicateKey, isInfinite, megabyte, nanoid, percentage, recordAction, reducers, regex, shareUrls, urlRoot };

package/dist/index.js

@@ -336,6 +336,46 @@ var incrementUsageTotals = async ({ controller, usageId, $inc, 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 });
+  }
+};
 var percentage = (value1, value2, decimals = 1) => ((value1 || 0) / (value2 || 0) * 100 || 0).toFixed(decimals);
 var reducers = {
   fields: (data2 = [], callback = () => ({})) => data2.reduce(
@@ -428,10 +468,12 @@ export {
   gigabyte,
   incrementUsageTotals,
   infinite,
+  isDuplicateKey,
   isInfinite,
   megabyte,
   nanoid,
   percentage,
+  recordAction,
   reducers,
   regex,
   shareUrls,

package/package.json

@@ -17,9 +17,6 @@
     "tsup": "8.5.1",
     "typescript": "5.9.3"
   },
-  "overrides": {
-    "esbuild": "0.28.1"
-  },
   "peerDependencies": {
     "@node-oauth/oauth2-server": "^5.3.0"
   },
@@ -160,5 +157,5 @@
     "build": "tsup && npm publish"
   },
   "types": "dist/index.d.ts",
-  "version": "0.0.61"
+  "version": "0.0.63"
 }