@drawbridge/drawbridge-utils 0.0.27 → 0.0.29

package/dist/transactions.cjs

@@ -0,0 +1,187 @@
+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,
+  session
+}) => {
+  await db.create({
+    authenticated,
+    collection: "transaction",
+    data: {
+      userId,
+      billable: {
+        item: "ai"
+      },
+      category,
+      tags,
+      amount,
+      balance,
+      ...provider && { provider },
+      ...stripeInvoiceId && { stripeInvoiceId },
+      ...stripeEventId && { stripeEventId }
+    },
+    ...session && { options: { session } }
+  });
+};
+var credit = async ({
+  db,
+  authenticated,
+  userId,
+  amount,
+  category,
+  tags = [],
+  stripeInvoiceId,
+  stripeEventId,
+  session
+}) => {
+  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: "user",
+    query: {
+      id: userId
+    },
+    data: {
+      $inc: {
+        "balance.ai": amount
+      }
+    },
+    ...session && { options: { session } }
+  });
+  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,
+    session
+  });
+  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,
+  session
+}) => {
+  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: "user",
+    query: {
+      id: userId,
+      "balance.ai": {
+        $gte: amount
+      }
+    },
+    data: {
+      $inc: {
+        "balance.ai": -amount
+      }
+    },
+    ...session && { options: { session } }
+  });
+  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,
+    session
+  });
+  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,223 @@
+// Generic ledger primitives — authoritative balance for user.balance.ai lives
+// in Mongo, and every change to that balance is recorded in the `transaction`
+// 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.
+//
+// Both helpers accept an optional `session` so the caller can enroll them in
+// a larger Mongo transaction. When session is omitted, the balance update +
+// transaction insert run as two separate atomic ops (acceptable: balance is
+// always correct, worst case is a missing ledger row on a Mongo blip between
+// the two writes).
+
+// Internal: write a transaction 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,
+	session
+}) => {
+
+	await db.create({
+		authenticated,
+		collection : 'transaction',
+		data : {
+			userId,
+			billable : {
+				item : 'ai'
+			},
+			category,
+			tags,
+			amount,
+			balance,
+			...( provider && { provider }),
+			...( stripeInvoiceId && { stripeInvoiceId }),
+			...( stripeEventId && { stripeEventId })
+		},
+		...( session && { options : { session } })
+	});
+
+};
+
+// 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 transaction 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,
+	session
+}) => {
+
+	if( !Number.isInteger( amount ) || amount <= 0 ){
+
+		throw new Error( `credit() requires a positive integer amount, got ${ amount }` );
+
+	}
+
+	const result = await db.update({
+		authenticated,
+		collection : 'user',
+		query : {
+			id : userId
+		},
+		data : {
+			$inc : {
+				'balance.ai' : amount
+			}
+		},
+		...( session && { options : { session } })
+	});
+
+	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,
+		session
+	});
+
+	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,
+	session
+}) => {
+
+	if( !Number.isInteger( amount ) || amount <= 0 ){
+
+		throw new Error( `debit() requires a positive integer amount, got ${ amount }` );
+
+	}
+
+	const result = await db.update({
+		authenticated,
+		collection : 'user',
+		query : {
+			id : userId,
+			'balance.ai' : {
+				$gte : amount
+			}
+		},
+		data : {
+			$inc : {
+				'balance.ai' : -amount
+			}
+		},
+		...( session && { options : { session } })
+	});
+
+	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,
+		session
+	});
+
+	return {
+		amount : -amount,
+		balance : {
+			before,
+			after
+		}
+	};
+
+};
+
+export { InsufficientCreditsError, credit, debit };

package/dist/transactions.d.ts

@@ -0,0 +1,223 @@
+// Generic ledger primitives — authoritative balance for user.balance.ai lives
+// in Mongo, and every change to that balance is recorded in the `transaction`
+// 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.
+//
+// Both helpers accept an optional `session` so the caller can enroll them in
+// a larger Mongo transaction. When session is omitted, the balance update +
+// transaction insert run as two separate atomic ops (acceptable: balance is
+// always correct, worst case is a missing ledger row on a Mongo blip between
+// the two writes).
+
+// Internal: write a transaction 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,
+	session
+}) => {
+
+	await db.create({
+		authenticated,
+		collection : 'transaction',
+		data : {
+			userId,
+			billable : {
+				item : 'ai'
+			},
+			category,
+			tags,
+			amount,
+			balance,
+			...( provider && { provider }),
+			...( stripeInvoiceId && { stripeInvoiceId }),
+			...( stripeEventId && { stripeEventId })
+		},
+		...( session && { options : { session } })
+	});
+
+};
+
+// 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 transaction 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,
+	session
+}) => {
+
+	if( !Number.isInteger( amount ) || amount <= 0 ){
+
+		throw new Error( `credit() requires a positive integer amount, got ${ amount }` );
+
+	}
+
+	const result = await db.update({
+		authenticated,
+		collection : 'user',
+		query : {
+			id : userId
+		},
+		data : {
+			$inc : {
+				'balance.ai' : amount
+			}
+		},
+		...( session && { options : { session } })
+	});
+
+	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,
+		session
+	});
+
+	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,
+	session
+}) => {
+
+	if( !Number.isInteger( amount ) || amount <= 0 ){
+
+		throw new Error( `debit() requires a positive integer amount, got ${ amount }` );
+
+	}
+
+	const result = await db.update({
+		authenticated,
+		collection : 'user',
+		query : {
+			id : userId,
+			'balance.ai' : {
+				$gte : amount
+			}
+		},
+		data : {
+			$inc : {
+				'balance.ai' : -amount
+			}
+		},
+		...( session && { options : { session } })
+	});
+
+	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,
+		session
+	});
+
+	return {
+		amount : -amount,
+		balance : {
+			before,
+			after
+		}
+	};
+
+};
+
+export { InsufficientCreditsError, credit, debit };

package/dist/transactions.js

@@ -0,0 +1,10 @@
+import {
+  InsufficientCreditsError,
+  credit,
+  debit
+} from "./chunk-H735KDYS.js";
+export {
+  InsufficientCreditsError,
+  credit,
+  debit
+};

package/package.json

@@ -2,6 +2,7 @@
   "type": "module",
   "dependencies": {
     "@drawbridge/drawbridge-agents": "0.0.10",
+    "@google/genai": "1.30.0",
     "axios": "1.16.0",
     "currency-codes": "2.2.0",
     "nanoid": "3.3.8",
@@ -16,6 +17,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./ai": {
+      "types": "./dist/ai.d.ts",
+      "import": "./dist/ai.js",
+      "require": "./dist/ai.cjs"
+    },
     "./encrypt": {
       "types": "./dist/encrypt.d.ts",
       "import": "./dist/encrypt.js",
@@ -75,6 +81,11 @@
       "types": "./dist/token.d.ts",
       "import": "./dist/token.js",
       "require": "./dist/token.cjs"
+    },
+    "./transactions": {
+      "types": "./dist/transactions.d.ts",
+      "import": "./dist/transactions.js",
+      "require": "./dist/transactions.cjs"
     }
   },
   "files": [
@@ -92,5 +103,5 @@
     "build": "tsup && npm publish"
   },
   "types": "dist/index.d.ts",
-  "version": "0.0.27"
+  "version": "0.0.29"
 }