@drawbridge/drawbridge-utils 0.0.26 → 0.0.28

package/dist/transactions.d.ts

@@ -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 };

package/dist/transactions.js

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

package/package.json

@@ -1,7 +1,8 @@
 {
   "type": "module",
   "dependencies": {
-    "@drawbridge/drawbridge-agents": "0.0.9",
+    "@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.26"
+  "version": "0.0.28"
 }