@drawbridge/drawbridge-utils 0.0.61 → 0.0.62

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,30 @@ 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 }) => {
+  if (!controller || !organization || !usageId || !type || !key) return;
+  const amount = Number(units);
+  if (!Number.isFinite(amount) || amount === 0) return;
+  try {
+    await controller.create({
+      collection: "action",
+      data: {
+        organization,
+        usage: usageId,
+        type,
+        units: amount,
+        key,
+        meta,
+        ...traceId && { traceId }
+      }
+    });
+  } catch (error) {
+    if (isDuplicateKey(error)) return;
+    throw error;
+  }
+  await incrementUsageTotals({ controller, usageId, $inc: { "totals.actions": amount } });
+};
 var percentage = (value1, value2, decimals = 1) => ((value1 || 0) / (value2 || 0) * 100 || 0).toFixed(decimals);
 var reducers = {
   fields: (data2 = [], callback = () => ({})) => data2.reduce(
@@ -483,10 +509,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,63 @@ 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). 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.
+//   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 }) => {
+
+	if( ! controller || ! organization || ! usageId || ! type || ! key ) return;
+
+	const amount = Number( units );
+
+	if( ! Number.isFinite( amount ) || amount === 0 ) return;
+
+	try {
+
+		await controller.create({
+			collection : 'action',
+			data : {
+				organization,
+				usage : usageId,
+				type,
+				units : amount,
+				key,
+				meta,
+				...( traceId && { traceId })
+			}
+		});
+
+	} 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;
+
+		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 } });
+
+};
+
 const percentage = ( value1, value2, decimals = 1 ) => ( ( ( ( value1 || 0 ) / ( value2 || 0 ) ) * 100 ) || 0 ).toFixed( decimals );
 
 const reducers = {
@@ -477,4 +534,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,63 @@ 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). 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.
+//   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 }) => {
+
+	if( ! controller || ! organization || ! usageId || ! type || ! key ) return;
+
+	const amount = Number( units );
+
+	if( ! Number.isFinite( amount ) || amount === 0 ) return;
+
+	try {
+
+		await controller.create({
+			collection : 'action',
+			data : {
+				organization,
+				usage : usageId,
+				type,
+				units : amount,
+				key,
+				meta,
+				...( traceId && { traceId })
+			}
+		});
+
+	} 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;
+
+		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 } });
+
+};
+
 const percentage = ( value1, value2, decimals = 1 ) => ( ( ( ( value1 || 0 ) / ( value2 || 0 ) ) * 100 ) || 0 ).toFixed( decimals );
 
 const reducers = {
@@ -477,4 +534,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,30 @@ 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 }) => {
+  if (!controller || !organization || !usageId || !type || !key) return;
+  const amount = Number(units);
+  if (!Number.isFinite(amount) || amount === 0) return;
+  try {
+    await controller.create({
+      collection: "action",
+      data: {
+        organization,
+        usage: usageId,
+        type,
+        units: amount,
+        key,
+        meta,
+        ...traceId && { traceId }
+      }
+    });
+  } catch (error) {
+    if (isDuplicateKey(error)) return;
+    throw error;
+  }
+  await incrementUsageTotals({ controller, usageId, $inc: { "totals.actions": amount } });
+};
 var percentage = (value1, value2, decimals = 1) => ((value1 || 0) / (value2 || 0) * 100 || 0).toFixed(decimals);
 var reducers = {
   fields: (data2 = [], callback = () => ({})) => data2.reduce(
@@ -428,10 +452,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.62"
 }