@drawbridge/drawbridge-utils 0.0.29 → 0.0.32

package/dist/transactions.d.ts

@@ -1,56 +1,62 @@
-// 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.
+// Ledger transaction insert helpers — no balance writes happen here.
+//
+// User-balance updates are the exclusive job of drawbridge-sync's
+// stream/transaction.js change-stream listener: every insert into the
+// `transaction` collection triggers an atomic $inc on user.balance.<type>
+// (guarded against going negative). This decouples the API surface from
+// the balance arithmetic and makes the `transaction` collection the single
+// source of truth for both audit history and balance derivation.
 //
 //   import { credit, debit } from '@drawbridge/drawbridge-utils/transactions';
 //
-//   await credit({ db, authenticated, userId, amount: 500,
-//                  category: 'promotional', tags: [ 'welcome' ] });
+//   await credit({ db, user, amount: 500,
+//                  type: 'ai', category: 'promotional', source: 'system' });
 //
-//   await debit({ db, authenticated, userId, amount: 9,
-//                 category: 'usage', tags: [ 'google', 'gemini-2.5-flash' ],
-//                 provider: { name, model, tokens, snapshot } });
+//   await debit({ db, user, amount: 6,
+//                 type: 'ai', category: 'usage', source: 'user',
+//                 ai: { name, model, tokens, rates, totals } });
 //
-// `db` is the wrapper returned by @drawbridge/mongodb — credit/debit duck-type
-// against its `.create`, `.update` interface so this module has no hard dep.
+// `db` is the wrapper returned by @drawbridge/mongodb — credit/debit
+// duck-type against its `.create` 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 ({
+// `user` is the user the transaction is being recorded against. The helper
+// reads `user.balance.<type>` to stamp `balance: { before, after }` on the
+// row as an audit snapshot of what the actor saw at action time — useful
+// for support / dispute resolution. When `balance.<type>` isn't on the user
+// (fresh signup, webhook-initiated row), the snapshot is omitted, which is
+// the honest representation of "no prior view to record".
+
+const insertTransaction = async ({
 	db,
-	authenticated,
-	userId,
+	user,
+	type,
 	category,
-	tags,
+	source,
 	amount,
-	balance,
-	provider,
+	_id,
 	stripeInvoiceId,
 	stripeEventId,
-	session
+	session,
+	...rest
 }) => {
 
+	const beforeRaw = user?.balance?.[ type ];
+	const balance = typeof beforeRaw === 'number'
+		? { before : beforeRaw, after : beforeRaw + amount }
+		: undefined;
+
 	await db.create({
-		authenticated,
+		authenticated : user,
 		collection : 'transaction',
 		data : {
-			userId,
-			billable : {
-				item : 'ai'
-			},
+			...( _id && { _id }),
+			userId : user?.id,
+			type,
 			category,
-			tags,
+			source,
 			amount,
-			balance,
-			...( provider && { provider }),
+			...( balance && { balance }),
+			...rest,
 			...( stripeInvoiceId && { stripeInvoiceId }),
 			...( stripeEventId && { stripeEventId })
 		},
@@ -59,20 +65,22 @@ const recordTransaction = async ({
 
 };
 
-// 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.
+// Additive: record a credit. The stream handler does the $inc separately.
+// Optional `_id` lets callers pre-generate the transaction's ObjectId — the
+// top-up route stamps it onto the Stripe invoice metadata so Stripe-side and
+// Mongo-side IDs match for cross-system reconciliation.
 const credit = async ({
 	db,
-	authenticated,
-	userId,
+	user,
 	amount,
+	type,
 	category,
-	tags = [],
+	source,
+	_id,
 	stripeInvoiceId,
 	stripeEventId,
-	session
+	session,
+	...rest
 }) => {
 
 	if( !Number.isInteger( amount ) || amount <= 0 ){
@@ -81,83 +89,56 @@ const credit = async ({
 
 	}
 
-	const result = await db.update({
-		authenticated,
-		collection : 'user',
-		query : {
-			id : userId
-		},
-		data : {
-			$inc : {
-				'balance.ai' : amount
-			}
-		},
-		...( session && { options : { session } })
-	});
+	if( !type ){
 
-	const after = result?.value?.balance?.ai ?? result?.balance?.ai;
+		throw new Error( 'credit() requires a type (e.g., "ai")' );
 
-	if( typeof after !== 'number' ){
+	}
 
-		throw new Error( `credit() could not read updated balance for user ${ userId }` );
+	if( !source ){
 
-	}
+		throw new Error( 'credit() requires a source ("system" | "admin" | "user")' );
 
-	const before = after - amount;
+	}
 
-	await recordTransaction({
+	await insertTransaction({
 		db,
-		authenticated,
-		userId,
+		user,
+		type,
 		category,
-		tags,
+		source,
 		amount,
-		balance : {
-			before,
-			after
-		},
+		_id,
 		stripeInvoiceId,
 		stripeEventId,
-		session
+		session,
+		...rest
 	});
 
-	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;
-
-	}
-
-}
-
+// Subtractive: record a debit (negative amount). The stream handler's $inc
+// is guarded against negative balance — if the resulting balance would be
+// less than zero, the $inc is skipped and the row stays as audit-only.
+// Callers (e.g., ai.js) pre-compute `amount` from their domain-specific
+// pricing.
+//
+// Note: there is no synchronous gate here. The atomic gate-and-decrement
+// pattern moves to the AI middleware (`balance.<type> >= MAX_REQUEST_CENTS`)
+// plus the stream-side $inc guard. Concurrent debits with low balance can
+// race past the middleware check but the stream guard prevents the actual
+// balance from going negative.
 const debit = async ({
 	db,
-	authenticated,
-	userId,
+	user,
 	amount,
+	type,
 	category,
-	tags = [],
-	provider,
+	source,
 	stripeInvoiceId,
 	stripeEventId,
-	session
+	session,
+	...rest
 }) => {
 
 	if( !Number.isInteger( amount ) || amount <= 0 ){
@@ -166,58 +147,31 @@ const debit = async ({
 
 	}
 
-	const result = await db.update({
-		authenticated,
-		collection : 'user',
-		query : {
-			id : userId,
-			'balance.ai' : {
-				$gte : amount
-			}
-		},
-		data : {
-			$inc : {
-				'balance.ai' : -amount
-			}
-		},
-		...( session && { options : { session } })
-	});
+	if( !type ){
+
+		throw new Error( 'debit() requires a type (e.g., "ai")' );
 
-	const after = result?.value?.balance?.ai ?? result?.balance?.ai;
+	}
 
-	if( typeof after !== 'number' ){
+	if( !source ){
 
-		throw new InsufficientCreditsError();
+		throw new Error( 'debit() requires a source ("system" | "admin" | "user")' );
 
 	}
 
-	const before = after + amount;
-
-	await recordTransaction({
+	await insertTransaction({
 		db,
-		authenticated,
-		userId,
+		user,
+		type,
 		category,
-		tags,
+		source,
 		amount : -amount,
-		balance : {
-			before,
-			after
-		},
-		provider,
 		stripeInvoiceId,
 		stripeEventId,
-		session
+		session,
+		...rest
 	});
 
-	return {
-		amount : -amount,
-		balance : {
-			before,
-			after
-		}
-	};
-
 };
 
-export { InsufficientCreditsError, credit, debit };
+export { credit, debit };

package/dist/transactions.js

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

package/package.json

@@ -103,5 +103,5 @@
     "build": "tsup && npm publish"
   },
   "types": "dist/index.d.ts",
-  "version": "0.0.29"
+  "version": "0.0.32"
 }

package/dist/chunk-H735KDYS.js

@@ -1,162 +0,0 @@
-// transactions.js
-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
-    }
-  };
-};
-
-export {
-  credit,
-  InsufficientCreditsError,
-  debit
-};