diff --git a/packages/api/src/agents/transactions.spec.ts b/packages/api/src/agents/transactions.spec.ts index 8027660a45..3bf5c2f4fa 100644 --- a/packages/api/src/agents/transactions.spec.ts +++ b/packages/api/src/agents/transactions.spec.ts @@ -258,6 +258,39 @@ describe('prepareStructuredTokenSpend', () => { }); describe('bulkWriteTransactions (real DB)', () => { + it('initializes a missing balance with the effective allowance before the bulk debit', async () => { + const balance = { + enabled: true, + startBalance: 1000, + autoRefillEnabled: true, + refillAmount: 1000, + refillMode: 'reset' as const, + refillIntervalValue: 7, + refillIntervalUnit: 'days' as const, + }; + const docs: PreparedEntry[] = [ + { + doc: { user: testUserId, conversationId: 'c1', tokenType: 'prompt', tokenValue: -300 }, + tokenValue: -300, + balance, + }, + ]; + await bulkWriteTransactions( + { user: testUserId, docs }, + { + insertMany: dbMethods.bulkInsertTransactions, + updateBalance: dbMethods.updateBalance, + }, + ); + expect(await Balance.findOne({ user: testUserId }).lean()).toMatchObject({ + tokenCredits: 700, + allotment: 1000, + refillMode: 'reset', + refillAmount: 1000, + }); + expect(await Transaction.countDocuments({ user: testUserId })).toBe(1); + }); + it('should return early for empty docs without DB writes', async () => { const dbOps = { insertMany: dbMethods.bulkInsertTransactions, diff --git a/packages/api/src/agents/transactions.ts b/packages/api/src/agents/transactions.ts index 146c9d5ce1..c5a54abc54 100644 --- a/packages/api/src/agents/transactions.ts +++ b/packages/api/src/agents/transactions.ts @@ -92,7 +92,11 @@ export interface TxMetadata { export interface BulkWriteDeps { insertMany: (docs: TransactionData[]) => Promise; - updateBalance: (params: { user: string; incrementValue: number }) => Promise; + updateBalance: (params: { + user: string; + incrementValue: number; + balanceConfig?: Partial; + }) => Promise; } function calculateTokenValue( @@ -362,10 +366,10 @@ export async function bulkWriteTransactions( } let totalTokenValue = 0; - let balanceEnabled = false; + let balanceConfig: Partial | undefined; const plainDocs = docs.map(({ doc, tokenValue, balance }) => { if (balance?.enabled) { - balanceEnabled = true; + balanceConfig ??= balance; totalTokenValue += tokenValue; } return doc; @@ -377,7 +381,7 @@ export async function bulkWriteTransactions( */ await dbOps.insertMany(plainDocs); - if (balanceEnabled) { - await dbOps.updateBalance({ user, incrementValue: totalTokenValue }); + if (balanceConfig) { + await dbOps.updateBalance({ user, incrementValue: totalTokenValue, balanceConfig }); } } diff --git a/packages/data-schemas/src/methods/spendTokens.ts b/packages/data-schemas/src/methods/spendTokens.ts index 02b338385b..e4a6ffb62c 100644 --- a/packages/data-schemas/src/methods/spendTokens.ts +++ b/packages/data-schemas/src/methods/spendTokens.ts @@ -8,7 +8,7 @@ export interface SpendTxData { model?: string; context?: string; endpointTokenConfig?: Record> | null; - balance?: { enabled?: boolean }; + balance?: TxData['balance']; transactions?: { enabled?: boolean }; valueKey?: string; } diff --git a/packages/data-schemas/src/methods/transaction.initialization.spec.ts b/packages/data-schemas/src/methods/transaction.initialization.spec.ts new file mode 100644 index 0000000000..0d529cdbe3 --- /dev/null +++ b/packages/data-schemas/src/methods/transaction.initialization.spec.ts @@ -0,0 +1,178 @@ +import mongoose from 'mongoose'; +import { MongoMemoryServer } from 'mongodb-memory-server'; +import type { ITransaction } from '~/schema/transaction'; +import type { IBalance } from '~/types'; +import { createSpendTokensMethods } from './spendTokens'; +import { createTransactionMethods } from './transaction'; +import transactionSchema from '~/schema/transaction'; +import balanceSchema from '~/schema/balance'; + +jest.mock('~/config/winston', () => ({ error: jest.fn(), debug: jest.fn() })); + +let server: MongoMemoryServer; +let Balance: mongoose.Model; +let Transaction: mongoose.Model; +let methods: ReturnType; +let spend: ReturnType; + +const policy = { + enabled: true, + startBalance: 1000, + autoRefillEnabled: true, + refillAmount: 1000, + refillMode: 'reset' as const, + refillIntervalValue: 7, + refillIntervalUnit: 'days' as const, +}; + +beforeAll(async () => { + server = await MongoMemoryServer.create(); + await mongoose.connect(server.getUri()); + Balance = mongoose.model('Balance', balanceSchema); + Transaction = mongoose.model('Transaction', transactionSchema); + methods = createTransactionMethods(mongoose, { + getMultiplier: () => 2, + getCacheMultiplier: () => 1, + }); + spend = createSpendTokensMethods(mongoose, methods); +}); + +beforeEach(async () => { + await mongoose.connection.dropDatabase(); +}); + +afterAll(async () => { + await mongoose.disconnect(); + await server?.stop(); +}); + +describe('debit-first balance initialization', () => { + test.each(['regular', 'structured'] as const)( + '%s spending grants the configured start balance before charging a missing record', + async (kind) => { + const user = new mongoose.Types.ObjectId(); + const context = { user, balance: policy }; + if (kind === 'regular') { + await spend.spendTokens(context, { promptTokens: 100, completionTokens: 50 }); + } else { + await spend.spendStructuredTokens(context, { + promptTokens: { input: 100 }, + completionTokens: 50, + }); + } + const balance = await Balance.findOne({ user }).lean(); + expect(balance).toMatchObject({ + tokenCredits: 700, + autoRefillEnabled: true, + refillMode: 'reset', + refillAmount: 1000, + refillIntervalValue: 7, + refillIntervalUnit: 'days', + allotment: 1000, + }); + expect(balance?.allottedAt).toEqual(balance?.lastRefill); + expect(await Balance.countDocuments({ user })).toBe(1); + expect(await Transaction.countDocuments({ user })).toBe(2); + }, + ); + + test('concurrent debits and admission grant the starting allowance only once', async () => { + const user = new mongoose.Types.ObjectId(); + await Promise.all([ + methods.createTransaction({ user, balance: policy, tokenType: 'completion', rawAmount: -10 }), + methods.createStructuredTransaction({ + user, + balance: policy, + tokenType: 'completion', + rawAmount: -20, + }), + methods.reserveBalance({ + user: user.toString(), + reservationId: 'admission', + amount: 0, + expiresAt: new Date(Date.now() + 60000), + initialBalance: { + tokenCredits: 1000, + autoRefillEnabled: true, + refillAmount: 1000, + refillMode: 'reset', + refillIntervalValue: 7, + refillIntervalUnit: 'days', + }, + }), + ]); + expect((await Balance.findOne({ user }).lean())?.tokenCredits).toBe(940); + expect(await Balance.countDocuments({ user })).toBe(1); + }); + + test.each([0, 400])('never restores an existing balance of %s credits', async (tokenCredits) => { + const user = new mongoose.Types.ObjectId(); + const lastRefill = new Date(); + await Balance.create({ user, tokenCredits, lastRefill }); + await methods.createTransaction({ + user, + balance: policy, + tokenType: 'completion', + rawAmount: -10, + }); + const balance = await Balance.findOne({ user }).lean(); + expect(balance?.tokenCredits).toBe(Math.max(0, tokenCredits - 20)); + expect(balance?.lastRefill).toEqual(lastRefill); + }); + + test('preserves legacy zero initialization without a configured starting allowance', async () => { + const user = new mongoose.Types.ObjectId(); + await methods.createTransaction({ + user, + balance: { enabled: true }, + tokenType: 'completion', + rawAmount: -10, + }); + expect((await Balance.findOne({ user }).lean())?.tokenCredits).toBe(0); + }); + + test('an administrative credit grants only the requested amount', async () => { + const user = new mongoose.Types.ObjectId(); + await methods.createTransaction({ + user, + balance: policy, + tokenType: 'credits', + context: 'admin', + rawAmount: 200, + }); + expect((await Balance.findOne({ user }).lean())?.tokenCredits).toBe(400); + }); + + test('an explicitly zero starting allowance stays zero', async () => { + const user = new mongoose.Types.ObjectId(); + await methods.createTransaction({ + user, + balance: { ...policy, startBalance: 0 }, + tokenType: 'completion', + rawAmount: -10, + }); + expect((await Balance.findOne({ user }).lean())?.tokenCredits).toBe(0); + }); + + test('a zero-cost first transaction does not poison the next debit', async () => { + const user = new mongoose.Types.ObjectId(); + await methods.createTransaction({ user, balance: policy, tokenType: 'prompt', rawAmount: 0 }); + await methods.createTransaction({ + user, + balance: policy, + tokenType: 'completion', + rawAmount: -10, + }); + expect((await Balance.findOne({ user }).lean())?.tokenCredits).toBe(980); + }); + + test('a bulk debit can initialize from the effective balance policy', async () => { + const user = new mongoose.Types.ObjectId(); + await methods.updateBalance({ + user: user.toString(), + incrementValue: -300, + balanceConfig: policy, + }); + expect((await Balance.findOne({ user }).lean())?.tokenCredits).toBe(700); + }); +}); diff --git a/packages/data-schemas/src/methods/transaction.ts b/packages/data-schemas/src/methods/transaction.ts index edcce34a1a..57df98cd4d 100644 --- a/packages/data-schemas/src/methods/transaction.ts +++ b/packages/data-schemas/src/methods/transaction.ts @@ -1,5 +1,6 @@ import { isBalanceRefillDue } from 'librechat-data-provider'; import type { AnyBulkWriteOperation, FilterQuery, Model, Types } from 'mongoose'; +import type { TCustomConfig } from 'librechat-data-provider'; import type { BalanceReservationRequest, BalanceReservationRenewal, @@ -70,7 +71,7 @@ export interface TxData { /** Subset of `writeTokens` written to the 1-hour cache */ write1hTokens?: number; readTokens?: number; - balance?: { enabled?: boolean }; + balance?: Partial; transactions?: { enabled?: boolean }; } @@ -84,6 +85,24 @@ export interface TransactionResult { credits?: number; } +function initialDebitBalance(balance: TxData['balance']): IBalanceUpdate | undefined { + if (!balance?.enabled || balance.startBalance == null) { + return; + } + const grantedAt = new Date(); + return { + tokenCredits: balance.startBalance, + allotment: balance.startBalance, + allottedAt: grantedAt, + lastRefill: grantedAt, + autoRefillEnabled: balance.autoRefillEnabled ?? false, + refillAmount: balance.refillAmount, + refillMode: balance.refillMode ?? 'add', + refillIntervalValue: balance.refillIntervalValue, + refillIntervalUnit: balance.refillIntervalUnit, + }; +} + export function createTransactionMethods( mongoose: typeof import('mongoose'), txMethods: { @@ -95,10 +114,12 @@ export function createTransactionMethods( user, incrementValue, setValues, + balanceConfig, }: { user: string; incrementValue: number; setValues?: IBalanceUpdate; + balanceConfig?: TxData['balance']; }) => Promise; bulkInsertTransactions: (docs: TransactionData[]) => Promise; findBalanceByUser: ( @@ -247,10 +268,12 @@ export function createTransactionMethods( user, incrementValue, setValues, + balanceConfig, }: { user: string; incrementValue: number; setValues?: IBalanceUpdate; + balanceConfig?: TxData['balance']; }): Promise { const Balance = mongoose.models.Balance as Model; const maxRetries = 10; @@ -285,7 +308,11 @@ export function createTransactionMethods( } lastError = new Error(`Concurrency conflict for user ${user} on attempt ${attempt}.`); } else { - await upsertBalanceRecord(user, {}, { tokenCredits: 0 }); + await upsertBalanceRecord( + user, + {}, + initialDebitBalance(balanceConfig) ?? { tokenCredits: 0 }, + ); continue; } } catch (error) { @@ -650,6 +677,7 @@ export function createTransactionMethods( const balanceResponse = await updateBalance({ user: transaction.user as string, incrementValue, + balanceConfig: transaction.tokenType === 'credits' ? undefined : balance, }); return { @@ -690,6 +718,7 @@ export function createTransactionMethods( const balanceResponse = await updateBalance({ user: transaction.user as string, incrementValue, + balanceConfig: transaction.tokenType === 'credits' ? undefined : balance, }); return {