@drawbridge/drawbridge-utils 0.0.26 → 0.0.28

package/dist/index.d.cts

@@ -313,6 +313,44 @@ const getPlanFeature = ( plan, key ) => {
 
 };
 
+// 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 }
+	});
+
+};
+
 const percentage = ( value1, value2, decimals = 1 ) => ( ( ( ( value1 || 0 ) / ( value2 || 0 ) ) * 100 ) || 0 ).toFixed( decimals );
 
 const reducers = {
@@ -411,4 +449,4 @@ const currencies = data.map( ( item ) => ({
 
 const currency = ( val ) => code( val );
 
-export { bytesToGB, bytesToMB, capitalize, constants, currencies, currency, expiredPaymentMethod, formatCurrency, formatDateString, formatNumber, getPlanFeature, gigabyte, infinite, isInfinite, megabyte, nanoid, percentage, reducers, regex, shareUrls, urlRoot };
+export { bytesToGB, bytesToMB, capitalize, constants, currencies, currency, expiredPaymentMethod, formatCurrency, formatDateString, formatNumber, getPlanFeature, gigabyte, incrementUsageTotals, infinite, isInfinite, megabyte, nanoid, percentage, reducers, regex, shareUrls, urlRoot };

package/dist/index.d.ts

@@ -313,6 +313,44 @@ const getPlanFeature = ( plan, key ) => {
 
 };
 
+// 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 }
+	});
+
+};
+
 const percentage = ( value1, value2, decimals = 1 ) => ( ( ( ( value1 || 0 ) / ( value2 || 0 ) ) * 100 ) || 0 ).toFixed( decimals );
 
 const reducers = {
@@ -411,4 +449,4 @@ const currencies = data.map( ( item ) => ({
 
 const currency = ( val ) => code( val );
 
-export { bytesToGB, bytesToMB, capitalize, constants, currencies, currency, expiredPaymentMethod, formatCurrency, formatDateString, formatNumber, getPlanFeature, gigabyte, infinite, isInfinite, megabyte, nanoid, percentage, reducers, regex, shareUrls, urlRoot };
+export { bytesToGB, bytesToMB, capitalize, constants, currencies, currency, expiredPaymentMethod, formatCurrency, formatDateString, formatNumber, getPlanFeature, gigabyte, incrementUsageTotals, infinite, isInfinite, megabyte, nanoid, percentage, reducers, regex, shareUrls, urlRoot };

package/dist/index.js

@@ -266,6 +266,25 @@ var getPlanFeature = (plan, key) => {
     message: granted ? feature : error
   };
 };
+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 percentage = (value1, value2, decimals = 1) => ((value1 || 0) / (value2 || 0) * 100 || 0).toFixed(decimals);
 var reducers = {
   fields: (data2 = [], callback = () => ({})) => data2.reduce(
@@ -356,6 +375,7 @@ export {
   formatNumber,
   getPlanFeature,
   gigabyte,
+  incrementUsageTotals,
   infinite,
   isInfinite,
   megabyte,

package/dist/transactions.cjs

@@ -0,0 +1,179 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// transactions.js
+var transactions_exports = {};
+__export(transactions_exports, {
+  InsufficientCreditsError: () => InsufficientCreditsError,
+  credit: () => credit,
+  debit: () => debit
+});
+module.exports = __toCommonJS(transactions_exports);
+var recordTransaction = async ({
+  db,
+  authenticated,
+  userId,
+  category,
+  tags,
+  amount,
+  balance,
+  provider,
+  stripeInvoiceId,
+  stripeEventId
+}) => {
+  await db.create({
+    authenticated,
+    collection: "transactions",
+    data: {
+      userId,
+      billable: {
+        item: "ai"
+      },
+      category,
+      tags,
+      amount,
+      balance,
+      ...provider && { provider },
+      ...stripeInvoiceId && { stripeInvoiceId },
+      ...stripeEventId && { stripeEventId }
+    }
+  });
+};
+var credit = async ({
+  db,
+  authenticated,
+  userId,
+  amount,
+  category,
+  tags = [],
+  stripeInvoiceId,
+  stripeEventId
+}) => {
+  var _a, _b, _c;
+  if (!Number.isInteger(amount) || amount <= 0) {
+    throw new Error(`credit() requires a positive integer amount, got ${amount}`);
+  }
+  const result = await db.update({
+    authenticated,
+    collection: "users",
+    query: {
+      id: userId
+    },
+    data: {
+      $inc: {
+        "balance.ai": amount
+      }
+    }
+  });
+  const after = ((_b = (_a = result == null ? void 0 : result.value) == null ? void 0 : _a.balance) == null ? void 0 : _b.ai) ?? ((_c = result == null ? void 0 : result.balance) == null ? void 0 : _c.ai);
+  if (typeof after !== "number") {
+    throw new Error(`credit() could not read updated balance for user ${userId}`);
+  }
+  const before = after - amount;
+  await recordTransaction({
+    db,
+    authenticated,
+    userId,
+    category,
+    tags,
+    amount,
+    balance: {
+      before,
+      after
+    },
+    stripeInvoiceId,
+    stripeEventId
+  });
+  return {
+    balance: {
+      before,
+      after
+    }
+  };
+};
+var InsufficientCreditsError = class extends Error {
+  constructor(message = "Insufficient AI credits") {
+    super(message);
+    this.name = "InsufficientCreditsError";
+    this.status = 402;
+  }
+};
+var debit = async ({
+  db,
+  authenticated,
+  userId,
+  amount,
+  category,
+  tags = [],
+  provider,
+  stripeInvoiceId,
+  stripeEventId
+}) => {
+  var _a, _b, _c;
+  if (!Number.isInteger(amount) || amount <= 0) {
+    throw new Error(`debit() requires a positive integer amount, got ${amount}`);
+  }
+  const result = await db.update({
+    authenticated,
+    collection: "users",
+    query: {
+      id: userId,
+      "balance.ai": {
+        $gte: amount
+      }
+    },
+    data: {
+      $inc: {
+        "balance.ai": -amount
+      }
+    }
+  });
+  const after = ((_b = (_a = result == null ? void 0 : result.value) == null ? void 0 : _a.balance) == null ? void 0 : _b.ai) ?? ((_c = result == null ? void 0 : result.balance) == null ? void 0 : _c.ai);
+  if (typeof after !== "number") {
+    throw new InsufficientCreditsError();
+  }
+  const before = after + amount;
+  await recordTransaction({
+    db,
+    authenticated,
+    userId,
+    category,
+    tags,
+    amount: -amount,
+    balance: {
+      before,
+      after
+    },
+    provider,
+    stripeInvoiceId,
+    stripeEventId
+  });
+  return {
+    amount: -amount,
+    balance: {
+      before,
+      after
+    }
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InsufficientCreditsError,
+  credit,
+  debit
+});

package/dist/transactions.d.cts

@@ -0,0 +1,208 @@
+// Generic ledger primitives — authoritative balance for user.balance.ai lives
+// in Mongo, and every change to that balance is recorded in the `transactions`
+// collection. Domain-specific helpers (e.g., LLM pricing in ./ai.js) call into
+// credit/debit with pre-computed amounts.
+//
+//   import { credit, debit } from '@drawbridge/drawbridge-utils/transactions';
+//
+//   await credit({ db, authenticated, userId, amount: 500,
+//                  category: 'promotional', tags: [ 'welcome' ] });
+//
+//   await debit({ db, authenticated, userId, amount: 9,
+//                 category: 'usage', tags: [ 'google', 'gemini-2.5-flash' ],
+//                 provider: { name, model, tokens, snapshot } });
+//
+// `db` is the wrapper returned by @drawbridge/mongodb — credit/debit duck-type
+// against its `.create`, `.update` interface so this module has no hard dep.
+
+// Internal: write a transactions row. The user.balance.ai update happens in the
+// callers (credit/debit) so we can keep the atomic gate-and-decrement contract.
+const recordTransaction = async ({
+	db,
+	authenticated,
+	userId,
+	category,
+	tags,
+	amount,
+	balance,
+	provider,
+	stripeInvoiceId,
+	stripeEventId
+}) => {
+
+	await db.create({
+		authenticated,
+		collection : 'transactions',
+		data : {
+			userId,
+			billable : {
+				item : 'ai'
+			},
+			category,
+			tags,
+			amount,
+			balance,
+			...( provider && { provider }),
+			...( stripeInvoiceId && { stripeInvoiceId }),
+			...( stripeEventId && { stripeEventId })
+		}
+	});
+
+};
+
+// Additive: grant credits to a user. Used by welcome flow, top-up webhook,
+// admin promo, refunds. If stripeEventId is provided, the unique sparse index
+// on the transactions collection makes the insert idempotent against webhook
+// retries — second call no-ops at the Mongo layer.
+const credit = async ({
+	db,
+	authenticated,
+	userId,
+	amount,
+	category,
+	tags = [],
+	stripeInvoiceId,
+	stripeEventId
+}) => {
+
+	if( !Number.isInteger( amount ) || amount <= 0 ){
+
+		throw new Error( `credit() requires a positive integer amount, got ${ amount }` );
+
+	}
+
+	const result = await db.update({
+		authenticated,
+		collection : 'users',
+		query : {
+			id : userId
+		},
+		data : {
+			$inc : {
+				'balance.ai' : amount
+			}
+		}
+	});
+
+	const after = result?.value?.balance?.ai ?? result?.balance?.ai;
+
+	if( typeof after !== 'number' ){
+
+		throw new Error( `credit() could not read updated balance for user ${ userId }` );
+
+	}
+
+	const before = after - amount;
+
+	await recordTransaction({
+		db,
+		authenticated,
+		userId,
+		category,
+		tags,
+		amount,
+		balance : {
+			before,
+			after
+		},
+		stripeInvoiceId,
+		stripeEventId
+	});
+
+	return {
+		balance : {
+			before,
+			after
+		}
+	};
+
+};
+
+// Subtractive: atomic gate-and-decrement against the user's balance. The
+// $gte filter ensures concurrent calls can't drive balance negative — exactly
+// one of N parallel requests with overlapping cost will succeed; the rest
+// throw InsufficientCreditsError. Callers (e.g., ai.js) pre-compute `amount`
+// from their domain-specific pricing.
+class InsufficientCreditsError extends Error {
+
+	constructor( message = 'Insufficient AI credits' ){
+
+		super( message );
+		this.name = 'InsufficientCreditsError';
+		this.status = 402;
+
+	}
+
+}
+
+const debit = async ({
+	db,
+	authenticated,
+	userId,
+	amount,
+	category,
+	tags = [],
+	provider,
+	stripeInvoiceId,
+	stripeEventId
+}) => {
+
+	if( !Number.isInteger( amount ) || amount <= 0 ){
+
+		throw new Error( `debit() requires a positive integer amount, got ${ amount }` );
+
+	}
+
+	const result = await db.update({
+		authenticated,
+		collection : 'users',
+		query : {
+			id : userId,
+			'balance.ai' : {
+				$gte : amount
+			}
+		},
+		data : {
+			$inc : {
+				'balance.ai' : -amount
+			}
+		}
+	});
+
+	const after = result?.value?.balance?.ai ?? result?.balance?.ai;
+
+	if( typeof after !== 'number' ){
+
+		throw new InsufficientCreditsError();
+
+	}
+
+	const before = after + amount;
+
+	await recordTransaction({
+		db,
+		authenticated,
+		userId,
+		category,
+		tags,
+		amount : -amount,
+		balance : {
+			before,
+			after
+		},
+		provider,
+		stripeInvoiceId,
+		stripeEventId
+	});
+
+	return {
+		amount : -amount,
+		balance : {
+			before,
+			after
+		}
+	};
+
+};
+
+export { InsufficientCreditsError, credit, debit };