Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import mongoose from 'mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
import type { IBalance } from '..';
import type { ITransaction } from '~/schema/transaction';
import type { TxData } from './transaction';
import { createTxMethods, tokenValues, premiumTokenValues, defaultRate } from './tx';
import { matchModelName, findMatchingPattern } from './test-helpers';
import { createSpendTokensMethods } from './spendTokens';
import { createTransactionMethods } from './transaction';
import { createModels } from '~/models';
jest.mock('~/config/winston', () => ({
error: jest.fn(),
warn: jest.fn(),
info: jest.fn(),
debug: jest.fn(),
}));
let mongoServer: InstanceType<typeof MongoMemoryServer>;
let Balance: mongoose.Model<IBalance>;
let Transaction: mongoose.Model<ITransaction>;
let spendTokens: ReturnType<typeof createSpendTokensMethods>['spendTokens'];
let spendStructuredTokens: ReturnType<typeof createSpendTokensMethods>['spendStructuredTokens'];
let createTransaction: ReturnType<typeof createTransactionMethods>['createTransaction'];
let createStructuredTransaction: ReturnType<
typeof createTransactionMethods
>['createStructuredTransaction'];
let reserveBalance: ReturnType<typeof createTransactionMethods>['reserveBalance'];
let renewBalanceReservation: ReturnType<typeof createTransactionMethods>['renewBalanceReservation'];
let releaseBalanceReservation: ReturnType<
typeof createTransactionMethods
>['releaseBalanceReservation'];
let findBalanceByUser: ReturnType<typeof createTransactionMethods>['findBalanceByUser'];
let upsertBalanceFields: ReturnType<typeof createTransactionMethods>['upsertBalanceFields'];
let updateBalance: ReturnType<typeof createTransactionMethods>['updateBalance'];
let getMultiplier: ReturnType<typeof createTxMethods>['getMultiplier'];
let getCacheMultiplier: ReturnType<typeof createTxMethods>['getCacheMultiplier'];
beforeAll(async () => {
mongoServer = await MongoMemoryServer.create();
const mongoUri = mongoServer.getUri();
// Register models
const models = createModels(mongoose);
Object.assign(mongoose.models, models);
Balance = mongoose.models.Balance;
Transaction = mongoose.models.Transaction;
// Create methods from factories (following the chain in methods/index.ts)
const txMethods = createTxMethods(mongoose, { matchModelName, findMatchingPattern });
getMultiplier = txMethods.getMultiplier;
getCacheMultiplier = txMethods.getCacheMultiplier;
const transactionMethods = createTransactionMethods(mongoose, {
getMultiplier: txMethods.getMultiplier,
getCacheMultiplier: txMethods.getCacheMultiplier,
});
createTransaction = transactionMethods.createTransaction;
createStructuredTransaction = transactionMethods.createStructuredTransaction;
reserveBalance = transactionMethods.reserveBalance;
renewBalanceReservation = transactionMethods.renewBalanceReservation;
releaseBalanceReservation = transactionMethods.releaseBalanceReservation;
findBalanceByUser = transactionMethods.findBalanceByUser;
upsertBalanceFields = transactionMethods.upsertBalanceFields;
updateBalance = transactionMethods.updateBalance;
const spendMethods = createSpendTokensMethods(mongoose, {
createTransaction: transactionMethods.createTransaction,
createStructuredTransaction: transactionMethods.createStructuredTransaction,
});
spendTokens = spendMethods.spendTokens;
spendStructuredTokens = spendMethods.spendStructuredTokens;
await mongoose.connect(mongoUri);
});
afterAll(async () => {
await mongoose.disconnect();
await mongoServer.stop();
});
beforeEach(async () => {
await mongoose.connection.dropDatabase();
});
describe('Regular Token Spending Tests', () => {
test('Balance should decrease when spending tokens with spendTokens', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 10000000; // $10.00
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gpt-3.5-turbo';
const txData = {
user: userId,
conversationId: 'test-conversation-id',
model,
context: 'test',
endpointTokenConfig: null,
balance: { enabled: true },
};
const tokenUsage = {
promptTokens: 100,
completionTokens: 50,
};
// Act
await spendTokens(txData, tokenUsage);
// Assert
const updatedBalance = await Balance.findOne({ user: userId });
const promptMultiplier = getMultiplier({ model, tokenType: 'prompt' });
const completionMultiplier = getMultiplier({ model, tokenType: 'completion' });
const expectedTotalCost = 100 * promptMultiplier + 50 * completionMultiplier;
const expectedBalance = initialBalance - expectedTotalCost;
expect(updatedBalance?.tokenCredits).toBeCloseTo(expectedBalance, 0);
});
test('spendTokens should handle zero completion tokens', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 10000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gpt-3.5-turbo';
const txData = {
user: userId,
conversationId: 'test-conversation-id',
model,
context: 'test',
endpointTokenConfig: null,
balance: { enabled: true },
};
const tokenUsage = {
promptTokens: 100,
completionTokens: 0,
};
// Act
await spendTokens(txData, tokenUsage);
// Assert
const updatedBalance = await Balance.findOne({ user: userId });
const promptMultiplier = getMultiplier({ model, tokenType: 'prompt' });
const expectedCost = 100 * promptMultiplier;
expect(updatedBalance?.tokenCredits).toBeCloseTo(initialBalance - expectedCost, 0);
});
test('spendTokens should handle undefined token counts', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 10000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gpt-3.5-turbo';
const txData = {
user: userId,
conversationId: 'test-conversation-id',
model,
context: 'test',
endpointTokenConfig: null,
balance: { enabled: true },
};
const tokenUsage = {};
// Act
const result = await spendTokens(txData, tokenUsage);
// Assert: No transaction should be created
expect(result).toBeUndefined();
});
test('spendTokens should handle only prompt tokens', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 10000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gpt-3.5-turbo';
const txData = {
user: userId,
conversationId: 'test-conversation-id',
model,
context: 'test',
endpointTokenConfig: null,
balance: { enabled: true },
};
const tokenUsage = { promptTokens: 100 };
// Act
await spendTokens(txData, tokenUsage);
// Assert
const updatedBalance = await Balance.findOne({ user: userId });
const promptMultiplier = getMultiplier({ model, tokenType: 'prompt' });
const expectedCost = 100 * promptMultiplier;
expect(updatedBalance?.tokenCredits).toBeCloseTo(initialBalance - expectedCost, 0);
});
test('spendTokens should not update balance when balance feature is disabled', async () => {
// Arrange: Balance config is now passed directly in txData
const userId = new mongoose.Types.ObjectId();
const initialBalance = 10000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gpt-3.5-turbo';
const txData = {
user: userId,
conversationId: 'test-conversation-id',
model,
context: 'test',
endpointTokenConfig: null,
balance: { enabled: false },
};
const tokenUsage = {
promptTokens: 100,
completionTokens: 50,
};
// Act
await spendTokens(txData, tokenUsage);
// Assert: Balance should remain unchanged.
const updatedBalance = await Balance.findOne({ user: userId });
expect(updatedBalance?.tokenCredits).toBe(initialBalance);
});
});
describe('Structured Token Spending Tests', () => {
test('Balance should decrease and rawAmount should be set when spending a large number of structured tokens', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 17613154.55; // $17.61
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'claude-3-5-sonnet';
const txData = {
user: userId,
conversationId: 'c23a18da-706c-470a-ac28-ec87ed065199',
model,
context: 'message',
endpointTokenConfig: null,
balance: { enabled: true },
};
const tokenUsage = {
promptTokens: {
input: 11,
write: 140522,
read: 0,
},
completionTokens: 5,
};
const promptMultiplier = getMultiplier({ model, tokenType: 'prompt' });
const completionMultiplier = getMultiplier({ model, tokenType: 'completion' });
const writeMultiplier = getCacheMultiplier({ model, cacheType: 'write' }) ?? promptMultiplier;
const readMultiplier = getCacheMultiplier({ model, cacheType: 'read' }) ?? promptMultiplier;
// Act
const result = await spendStructuredTokens(txData, tokenUsage);
// Calculate expected costs.
const expectedPromptCost =
tokenUsage.promptTokens.input * promptMultiplier +
tokenUsage.promptTokens.write * writeMultiplier +
tokenUsage.promptTokens.read * readMultiplier;
const expectedCompletionCost = tokenUsage.completionTokens * completionMultiplier;
const expectedTotalCost = expectedPromptCost + expectedCompletionCost;
const expectedBalance = initialBalance - expectedTotalCost;
// Assert
expect(result?.completion?.balance).toBeLessThan(initialBalance);
const allowedDifference = 100;
expect(Math.abs((result?.completion?.balance ?? 0) - expectedBalance)).toBeLessThan(
allowedDifference,
);
const balanceDecrease = initialBalance - (result?.completion?.balance ?? 0);
expect(balanceDecrease).toBeCloseTo(expectedTotalCost, 0);
const expectedPromptTokenValue = -expectedPromptCost;
const expectedCompletionTokenValue = -expectedCompletionCost;
expect(result?.prompt?.prompt).toBeCloseTo(expectedPromptTokenValue, 1);
expect(result?.completion?.completion).toBe(expectedCompletionTokenValue);
});
test('should handle zero completion tokens in structured spending', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 17613154.55;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'claude-3-5-sonnet';
const txData = {
user: userId,
conversationId: 'test-convo',
model,
context: 'message',
balance: { enabled: true },
};
const tokenUsage = {
promptTokens: {
input: 10,
write: 100,
read: 5,
},
completionTokens: 0,
};
// Act
const result = await spendStructuredTokens(txData, tokenUsage);
// Assert
expect(result.prompt).toBeDefined();
expect(result.completion).toBeUndefined();
expect(result?.prompt?.prompt).toBeLessThan(0);
});
test('should handle only prompt tokens in structured spending', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 17613154.55;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'claude-3-5-sonnet';
const txData = {
user: userId,
conversationId: 'test-convo',
model,
context: 'message',
balance: { enabled: true },
};
const tokenUsage = {
promptTokens: {
input: 10,
write: 100,
read: 5,
},
};
// Act
const result = await spendStructuredTokens(txData, tokenUsage);
// Assert
expect(result.prompt).toBeDefined();
expect(result.completion).toBeUndefined();
expect(result?.prompt?.prompt).toBeLessThan(0);
});
test('should handle undefined token counts in structured spending', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 17613154.55;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'claude-3-5-sonnet';
const txData = {
user: userId,
conversationId: 'test-convo',
model,
context: 'message',
balance: { enabled: true },
};
const tokenUsage = {};
// Act
const result = await spendStructuredTokens(txData, tokenUsage);
// Assert
expect(result).toEqual({
prompt: undefined,
completion: undefined,
});
});
test('should handle incomplete context for completion tokens', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 17613154.55;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'claude-3-5-sonnet';
const txData = {
user: userId,
conversationId: 'test-convo',
model,
context: 'incomplete',
balance: { enabled: true },
};
const tokenUsage = {
promptTokens: {
input: 10,
write: 100,
read: 5,
},
completionTokens: 50,
};
// Act
const result = await spendStructuredTokens(txData, tokenUsage);
// Assert:
// (Assuming a multiplier for completion of 15 and a cancel rate of 1.15 as noted in the original test.)
expect(result?.completion?.completion).toBeCloseTo(-50 * 15 * 1.15, 0);
});
});
describe('NaN Handling Tests', () => {
test('should skip transaction creation when rawAmount is NaN', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 10000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gpt-3.5-turbo';
const txData: TxData = {
user: userId,
conversationId: 'test-conversation-id',
model,
context: 'test',
endpointTokenConfig: null,
rawAmount: NaN,
tokenType: 'prompt',
balance: { enabled: true },
};
// Act
const result = await createTransaction(txData);
// Assert: No transaction should be created and balance remains unchanged.
expect(result).toBeUndefined();
const balance = await Balance.findOne({ user: userId });
expect(balance?.tokenCredits).toBe(initialBalance);
});
});
describe('Transactions Config Tests', () => {
test('createTransaction should not save when transactions.enabled is false', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 10000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gpt-3.5-turbo';
const txData: TxData = {
user: userId,
conversationId: 'test-conversation-id',
model,
context: 'test',
endpointTokenConfig: null,
rawAmount: -100,
tokenType: 'prompt',
transactions: { enabled: false },
};
// Act
const result = await createTransaction(txData);
// Assert: No transaction should be created
expect(result).toBeUndefined();
const transactions = await Transaction.find({ user: userId });
expect(transactions).toHaveLength(0);
const balance = await Balance.findOne({ user: userId });
expect(balance?.tokenCredits).toBe(initialBalance);
});
test('createTransaction should save when transactions.enabled is true', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 10000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gpt-3.5-turbo';
const txData: TxData = {
user: userId,
conversationId: 'test-conversation-id',
model,
context: 'test',
endpointTokenConfig: null,
rawAmount: -100,
tokenType: 'prompt',
transactions: { enabled: true },
balance: { enabled: true },
};
// Act
const result = await createTransaction(txData);
// Assert: Transaction should be created
expect(result).toBeDefined();
expect(result?.balance).toBeLessThan(initialBalance);
const transactions = await Transaction.find({ user: userId });
expect(transactions).toHaveLength(1);
expect(transactions[0].rawAmount).toBe(-100);
});
test('createTransaction should save when balance.enabled is true even if transactions config is missing', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 10000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gpt-3.5-turbo';
const txData: TxData = {
user: userId,
conversationId: 'test-conversation-id',
model,
context: 'test',
endpointTokenConfig: null,
rawAmount: -100,
tokenType: 'prompt',
balance: { enabled: true },
// No transactions config provided
};
// Act
const result = await createTransaction(txData);
// Assert: Transaction should be created (backward compatibility)
expect(result).toBeDefined();
expect(result?.balance).toBeLessThan(initialBalance);
const transactions = await Transaction.find({ user: userId });
expect(transactions).toHaveLength(1);
});
test('createTransaction should save transaction but not update balance when balance is disabled but transactions enabled', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 10000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gpt-3.5-turbo';
const txData: TxData = {
user: userId,
conversationId: 'test-conversation-id',
model,
context: 'test',
endpointTokenConfig: null,
rawAmount: -100,
tokenType: 'prompt',
transactions: { enabled: true },
balance: { enabled: false },
};
// Act
const result = await createTransaction(txData);
// Assert: Transaction should be created but balance unchanged
expect(result).toBeUndefined();
const transactions = await Transaction.find({ user: userId });
expect(transactions).toHaveLength(1);
expect(transactions[0].rawAmount).toBe(-100);
const balance = await Balance.findOne({ user: userId });
expect(balance?.tokenCredits).toBe(initialBalance);
});
test('createStructuredTransaction should not save when transactions.enabled is false', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 10000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'claude-3-5-sonnet';
const txData: TxData = {
user: userId,
conversationId: 'test-conversation-id',
model,
context: 'message',
tokenType: 'prompt',
inputTokens: -10,
writeTokens: -100,
readTokens: -5,
transactions: { enabled: false },
};
// Act
const result = await createStructuredTransaction(txData);
// Assert: No transaction should be created
expect(result).toBeUndefined();
const transactions = await Transaction.find({ user: userId });
expect(transactions).toHaveLength(0);
const balance = await Balance.findOne({ user: userId });
expect(balance?.tokenCredits).toBe(initialBalance);
});
test('createStructuredTransaction should save transaction but not update balance when balance is disabled but transactions enabled', async () => {
// Arrange
const userId = new mongoose.Types.ObjectId();
const initialBalance = 10000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'claude-3-5-sonnet';
const txData: TxData = {
user: userId,
conversationId: 'test-conversation-id',
model,
context: 'message',
tokenType: 'prompt',
inputTokens: -10,
writeTokens: -100,
readTokens: -5,
transactions: { enabled: true },
balance: { enabled: false },
};
// Act
const result = await createStructuredTransaction(txData);
// Assert: Transaction should be created but balance unchanged
expect(result).toBeUndefined();
const transactions = await Transaction.find({ user: userId });
expect(transactions).toHaveLength(1);
expect(transactions[0].inputTokens).toBe(-10);
expect(transactions[0].writeTokens).toBe(-100);
expect(transactions[0].readTokens).toBe(-5);
const balance = await Balance.findOne({ user: userId });
expect(balance?.tokenCredits).toBe(initialBalance);
});
});
describe('Partial endpointTokenConfig fallback', () => {
const endpointTokenConfig = {
'custom-model': { prompt: 1.5, completion: 4.5, read: 0.3 },
};
test('uses override rates for a listed model', () => {
expect(getMultiplier({ model: 'custom-model', tokenType: 'prompt', endpointTokenConfig })).toBe(
1.5,
);
expect(
getCacheMultiplier({ model: 'custom-model', cacheType: 'read', endpointTokenConfig }),
).toBe(0.3);
});
test('falls back to standard tables for a model absent from the override', () => {
const fallbackPrompt = getMultiplier({ model: 'gpt-4', tokenType: 'prompt' });
expect(getMultiplier({ model: 'gpt-4', tokenType: 'prompt', endpointTokenConfig })).toBe(
fallbackPrompt,
);
expect(getMultiplier({ model: 'gpt-4', tokenType: 'prompt', endpointTokenConfig })).not.toBe(
defaultRate,
);
const fallbackCacheRead = getCacheMultiplier({ model: 'claude-3-5-sonnet', cacheType: 'read' });
expect(
getCacheMultiplier({ model: 'claude-3-5-sonnet', cacheType: 'read', endpointTokenConfig }),
).toBe(fallbackCacheRead);
});
});
describe('calculateTokenValue Edge Cases', () => {
test('should derive multiplier from model when valueKey is not provided', async () => {
const userId = new mongoose.Types.ObjectId();
const initialBalance = 100000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gpt-4';
const promptTokens = 1000;
const result = await createTransaction({
user: userId,
conversationId: 'test-no-valuekey',
model,
tokenType: 'prompt',
rawAmount: -promptTokens,
context: 'test',
balance: { enabled: true },
});
const expectedRate = getMultiplier({ model, tokenType: 'prompt' });
expect(result?.rate).toBe(expectedRate);
const tx = await Transaction.findOne({ user: userId });
expect(tx?.tokenValue).toBe(-promptTokens * expectedRate);
expect(tx?.rate).toBe(expectedRate);
});
test('should derive valueKey and apply correct rate for an unknown model with tokenType', async () => {
const userId = new mongoose.Types.ObjectId();
const initialBalance = 100000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
await createTransaction({
user: userId,
conversationId: 'test-unknown-model',
model: 'some-unrecognized-model-xyz',
tokenType: 'prompt',
rawAmount: -500,
context: 'test',
balance: { enabled: true },
});
const tx = await Transaction.findOne({ user: userId });
expect(tx?.rate).toBeDefined();
expect(tx?.rate).toBeGreaterThan(0);
expect(tx?.tokenValue).toBe((tx?.rawAmount ?? 0) * (tx?.rate ?? 0));
});
test('should correctly apply model-derived multiplier without valueKey for completion', async () => {
const userId = new mongoose.Types.ObjectId();
const initialBalance = 100000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'claude-opus-4-6';
const completionTokens = 500;
const result = await createTransaction({
user: userId,
conversationId: 'test-completion-no-valuekey',
model,
tokenType: 'completion',
rawAmount: -completionTokens,
context: 'test',
balance: { enabled: true },
});
const expectedRate = getMultiplier({ model, tokenType: 'completion' });
expect(expectedRate).toBe(tokenValues[model].completion);
expect(result?.rate).toBe(expectedRate);
const updatedBalance = await Balance.findOne({ user: userId });
expect(updatedBalance?.tokenCredits).toBeCloseTo(
initialBalance - completionTokens * expectedRate,
0,
);
});
});
describe('Premium Token Pricing Integration Tests', () => {
test('spendTokens should apply standard pricing when prompt tokens are below premium threshold', async () => {
const userId = new mongoose.Types.ObjectId();
const initialBalance = 100000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gemini-3.1';
const promptTokens = 100000;
const completionTokens = 500;
const txData = {
user: userId,
conversationId: 'test-premium-below',
model,
context: 'test',
endpointTokenConfig: null,
balance: { enabled: true },
};
await spendTokens(txData, { promptTokens, completionTokens });
const standardPromptRate = tokenValues[model].prompt;
const standardCompletionRate = tokenValues[model].completion;
const expectedCost =
promptTokens * standardPromptRate + completionTokens * standardCompletionRate;
const updatedBalance = await Balance.findOne({ user: userId });
expect(updatedBalance?.tokenCredits).toBeCloseTo(initialBalance - expectedCost, 0);
});
test('spendTokens should apply premium pricing when prompt tokens exceed premium threshold', async () => {
const userId = new mongoose.Types.ObjectId();
const initialBalance = 100000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gemini-3.1';
const promptTokens = 250000;
const completionTokens = 500;
const txData = {
user: userId,
conversationId: 'test-premium-above',
model,
context: 'test',
endpointTokenConfig: null,
balance: { enabled: true },
};
await spendTokens(txData, { promptTokens, completionTokens });
const premiumPromptRate = premiumTokenValues[model].prompt;
const premiumCompletionRate = premiumTokenValues[model].completion;
const expectedCost =
promptTokens * premiumPromptRate + completionTokens * premiumCompletionRate;
const updatedBalance = await Balance.findOne({ user: userId });
expect(updatedBalance?.tokenCredits).toBeCloseTo(initialBalance - expectedCost, 0);
});
test('spendTokens should apply standard pricing at exactly the premium threshold', async () => {
const userId = new mongoose.Types.ObjectId();
const initialBalance = 100000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gemini-3.1';
const promptTokens = premiumTokenValues[model].threshold;
const completionTokens = 500;
const txData = {
user: userId,
conversationId: 'test-premium-exact',
model,
context: 'test',
endpointTokenConfig: null,
balance: { enabled: true },
};
await spendTokens(txData, { promptTokens, completionTokens });
const standardPromptRate = tokenValues[model].prompt;
const standardCompletionRate = tokenValues[model].completion;
const expectedCost =
promptTokens * standardPromptRate + completionTokens * standardCompletionRate;
const updatedBalance = await Balance.findOne({ user: userId });
expect(updatedBalance?.tokenCredits).toBeCloseTo(initialBalance - expectedCost, 0);
});
test('spendStructuredTokens should apply premium pricing when total input tokens exceed threshold', async () => {
const userId = new mongoose.Types.ObjectId();
const initialBalance = 100000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gemini-3.1';
const txData = {
user: userId,
conversationId: 'test-structured-premium',
model,
context: 'message',
endpointTokenConfig: null,
balance: { enabled: true },
};
const tokenUsage = {
promptTokens: {
input: 200000,
write: 10000,
read: 5000,
},
completionTokens: 1000,
};
const totalInput =
tokenUsage.promptTokens.input + tokenUsage.promptTokens.write + tokenUsage.promptTokens.read;
await spendStructuredTokens(txData, tokenUsage);
const premiumPromptRate = premiumTokenValues[model].prompt;
const premiumCompletionRate = premiumTokenValues[model].completion;
const promptMultiplier = getMultiplier({
model,
tokenType: 'prompt',
inputTokenCount: totalInput,
});
const writeMultiplier = getCacheMultiplier({ model, cacheType: 'write' }) ?? promptMultiplier;
const readMultiplier = getCacheMultiplier({ model, cacheType: 'read' }) ?? promptMultiplier;
const expectedPromptCost =
tokenUsage.promptTokens.input * premiumPromptRate +
tokenUsage.promptTokens.write * writeMultiplier +
tokenUsage.promptTokens.read * readMultiplier;
const expectedCompletionCost = tokenUsage.completionTokens * premiumCompletionRate;
const expectedTotalCost = expectedPromptCost + expectedCompletionCost;
const updatedBalance = await Balance.findOne({ user: userId });
expect(totalInput).toBeGreaterThan(premiumTokenValues[model].threshold);
expect(updatedBalance?.tokenCredits).toBeCloseTo(initialBalance - expectedTotalCost, 0);
});
test('spendStructuredTokens should apply standard pricing when total input tokens are below threshold', async () => {
const userId = new mongoose.Types.ObjectId();
const initialBalance = 100000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gemini-3.1';
const txData = {
user: userId,
conversationId: 'test-structured-standard',
model,
context: 'message',
endpointTokenConfig: null,
balance: { enabled: true },
};
const tokenUsage = {
promptTokens: {
input: 50000,
write: 10000,
read: 5000,
},
completionTokens: 1000,
};
const totalInput =
tokenUsage.promptTokens.input + tokenUsage.promptTokens.write + tokenUsage.promptTokens.read;
await spendStructuredTokens(txData, tokenUsage);
const standardPromptRate = tokenValues[model].prompt;
const standardCompletionRate = tokenValues[model].completion;
const promptMultiplier = getMultiplier({
model,
tokenType: 'prompt',
inputTokenCount: totalInput,
});
const writeMultiplier = getCacheMultiplier({ model, cacheType: 'write' }) ?? promptMultiplier;
const readMultiplier = getCacheMultiplier({ model, cacheType: 'read' }) ?? promptMultiplier;
const expectedPromptCost =
tokenUsage.promptTokens.input * standardPromptRate +
tokenUsage.promptTokens.write * writeMultiplier +
tokenUsage.promptTokens.read * readMultiplier;
const expectedCompletionCost = tokenUsage.completionTokens * standardCompletionRate;
const expectedTotalCost = expectedPromptCost + expectedCompletionCost;
const updatedBalance = await Balance.findOne({ user: userId });
expect(totalInput).toBeLessThanOrEqual(premiumTokenValues[model].threshold);
expect(updatedBalance?.tokenCredits).toBeCloseTo(initialBalance - expectedTotalCost, 0);
});
test('spendTokens should apply standard pricing for gemini-3.1-pro-preview below threshold', async () => {
const userId = new mongoose.Types.ObjectId();
const initialBalance = 100000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gemini-3.1-pro-preview';
const promptTokens = 100000;
const completionTokens = 500;
const txData = {
user: userId,
conversationId: 'test-gemini31-below',
model,
context: 'test',
endpointTokenConfig: null,
balance: { enabled: true },
};
await spendTokens(txData, { promptTokens, completionTokens });
const standardPromptRate = tokenValues['gemini-3.1'].prompt;
const standardCompletionRate = tokenValues['gemini-3.1'].completion;
const expectedCost =
promptTokens * standardPromptRate + completionTokens * standardCompletionRate;
const updatedBalance = await Balance.findOne({ user: userId });
expect(updatedBalance?.tokenCredits).toBeCloseTo(initialBalance - expectedCost, 0);
});
test('spendTokens should apply premium pricing for gemini-3.1-pro-preview above threshold', async () => {
const userId = new mongoose.Types.ObjectId();
const initialBalance = 100000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gemini-3.1-pro-preview';
const promptTokens = 250000;
const completionTokens = 500;
const txData = {
user: userId,
conversationId: 'test-gemini31-above',
model,
context: 'test',
endpointTokenConfig: null,
balance: { enabled: true },
};
await spendTokens(txData, { promptTokens, completionTokens });
const premiumPromptRate = premiumTokenValues['gemini-3.1'].prompt;
const premiumCompletionRate = premiumTokenValues['gemini-3.1'].completion;
const expectedCost =
promptTokens * premiumPromptRate + completionTokens * premiumCompletionRate;
const updatedBalance = await Balance.findOne({ user: userId });
expect(updatedBalance?.tokenCredits).toBeCloseTo(initialBalance - expectedCost, 0);
});
test('spendTokens should apply standard pricing for gemini-3.1-pro-preview at exactly the threshold', async () => {
const userId = new mongoose.Types.ObjectId();
const initialBalance = 100000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gemini-3.1-pro-preview';
const promptTokens = premiumTokenValues['gemini-3.1'].threshold;
const completionTokens = 500;
const txData = {
user: userId,
conversationId: 'test-gemini31-exact',
model,
context: 'test',
endpointTokenConfig: null,
balance: { enabled: true },
};
await spendTokens(txData, { promptTokens, completionTokens });
const standardPromptRate = tokenValues['gemini-3.1'].prompt;
const standardCompletionRate = tokenValues['gemini-3.1'].completion;
const expectedCost =
promptTokens * standardPromptRate + completionTokens * standardCompletionRate;
const updatedBalance = await Balance.findOne({ user: userId });
expect(updatedBalance?.tokenCredits).toBeCloseTo(initialBalance - expectedCost, 0);
});
test('spendStructuredTokens should apply premium pricing for gemini-3.1 when total input exceeds threshold', async () => {
const userId = new mongoose.Types.ObjectId();
const initialBalance = 100000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'gemini-3.1-pro-preview';
const txData = {
user: userId,
conversationId: 'test-gemini31-structured-premium',
model,
context: 'message',
endpointTokenConfig: null,
balance: { enabled: true },
};
const tokenUsage = {
promptTokens: {
input: 200000,
write: 10000,
read: 5000,
},
completionTokens: 1000,
};
const totalInput =
tokenUsage.promptTokens.input + tokenUsage.promptTokens.write + tokenUsage.promptTokens.read;
await spendStructuredTokens(txData, tokenUsage);
const premiumPromptRate = premiumTokenValues['gemini-3.1'].prompt;
const premiumCompletionRate = premiumTokenValues['gemini-3.1'].completion;
const promptMultiplier = getMultiplier({
model,
tokenType: 'prompt',
inputTokenCount: totalInput,
});
const writeMultiplier = getCacheMultiplier({ model, cacheType: 'write' }) ?? promptMultiplier;
const readMultiplier = getCacheMultiplier({ model, cacheType: 'read' }) ?? promptMultiplier;
const expectedPromptCost =
tokenUsage.promptTokens.input * premiumPromptRate +
tokenUsage.promptTokens.write * writeMultiplier +
tokenUsage.promptTokens.read * readMultiplier;
const expectedCompletionCost = tokenUsage.completionTokens * premiumCompletionRate;
const expectedTotalCost = expectedPromptCost + expectedCompletionCost;
const updatedBalance = await Balance.findOne({ user: userId });
expect(totalInput).toBeGreaterThan(premiumTokenValues['gemini-3.1'].threshold);
expect(updatedBalance?.tokenCredits).toBeCloseTo(initialBalance - expectedTotalCost, 0);
});
test('non-premium models should not be affected by inputTokenCount regardless of prompt size', async () => {
const userId = new mongoose.Types.ObjectId();
const initialBalance = 100000000;
await Balance.create({ user: userId, tokenCredits: initialBalance });
const model = 'claude-opus-4-6';
const promptTokens = 300000;
const completionTokens = 500;
const txData = {
user: userId,
conversationId: 'test-no-premium',
model,
context: 'test',
endpointTokenConfig: null,
balance: { enabled: true },
};
await spendTokens(txData, { promptTokens, completionTokens });
const standardPromptRate = getMultiplier({ model, tokenType: 'prompt' });
const standardCompletionRate = getMultiplier({ model, tokenType: 'completion' });
const expectedCost =
promptTokens * standardPromptRate + completionTokens * standardCompletionRate;
const updatedBalance = await Balance.findOne({ user: userId });
expect(updatedBalance?.tokenCredits).toBeCloseTo(initialBalance - expectedCost, 0);
});
});
describe('Balance Reservations', () => {
const inFuture = () => new Date(Date.now() + 60_000);
const newId = () => new mongoose.Types.ObjectId().toString();
const reserve = (user: string, amount: number, reservationId = newId()) =>
reserveBalance({ user, amount, reservationId, expiresAt: inFuture() });
const readState = (user: mongoose.Types.ObjectId) =>
Balance.findOne({ user }).select('+reservations +reservedCredits +pendingRefill').lean();
/** Runs `interleave` once, immediately before the next `Balance` write executes. */
const interleaveBeforeNextWrite = (interleave: () => Promise<unknown>) => {
let fired = false;
const realUpdateOne = Balance.updateOne.bind(Balance);
const realBulkWrite = Balance.bulkWrite.bind(Balance);
const before = (write: () => unknown): unknown => {
if (fired) {
return write();
}
fired = true;
return interleave().then(() => write());
};
jest
.spyOn(Balance, 'updateOne')
.mockImplementation(((...args: Parameters<typeof Balance.updateOne>) =>
before(() => realUpdateOne(...args))) as unknown as typeof Balance.updateOne);
jest
.spyOn(Balance, 'bulkWrite')
.mockImplementation(((...args: Parameters<typeof Balance.bulkWrite>) =>
before(() => realBulkWrite(...args))) as unknown as typeof Balance.bulkWrite);
};
afterEach(() => {
jest.restoreAllMocks();
});
test('returns null when the user has no balance record and no initial balance', async () => {
await expect(reserve(newId(), 100)).resolves.toBeNull();
});
test('creates a missing record from the initial balance and admits against it', async () => {
const user = new mongoose.Types.ObjectId();
await expect(
reserveBalance({
user: user.toString(),
amount: 400,
reservationId: newId(),
expiresAt: inFuture(),
initialBalance: { user: user.toString(), tokenCredits: 1000 },
}),
).resolves.toEqual({ reserved: true, balance: 1000 });
const stored = await readState(user);
expect(stored?.tokenCredits).toBe(1000);
expect(stored?.reservedCredits).toBe(400);
});
test('never overwrites a record another writer created while initializing', async () => {
const user = new mongoose.Types.ObjectId();
const realFindOneAndUpdate = Balance.findOneAndUpdate.bind(Balance);
jest.spyOn(Balance, 'findOneAndUpdate').mockImplementationOnce(((
...args: Parameters<typeof Balance.findOneAndUpdate>
) => ({
lean: () =>
upsertBalanceFields(user.toString(), { tokenCredits: 50 }).then(() =>
realFindOneAndUpdate(...args).lean(),
),
})) as unknown as typeof Balance.findOneAndUpdate);
await expect(
reserveBalance({
user: user.toString(),
amount: 100,
reservationId: newId(),
expiresAt: inFuture(),
initialBalance: { user: user.toString(), tokenCredits: 1000 },
}),
).resolves.toEqual({ reserved: false, balance: 50 });
expect((await readState(user))?.tokenCredits).toBe(50);
expect(await Balance.countDocuments({ user })).toBe(1);
});
test('creates a missing record under the user id, so racing creators share one record', async () => {
const reserved = new mongoose.Types.ObjectId();
const synced = new mongoose.Types.ObjectId();
const spent = new mongoose.Types.ObjectId();
const racing = new mongoose.Types.ObjectId();
const initialReservation = (user: mongoose.Types.ObjectId) =>
reserveBalance({
user: user.toString(),
amount: 400,
reservationId: newId(),
expiresAt: inFuture(),
initialBalance: { user: user.toString(), tokenCredits: 1000 },
});
await initialReservation(reserved);
await upsertBalanceFields(synced.toString(), { tokenCredits: 50 }, { refillAmount: 5 });
await updateBalance({ user: spent.toString(), incrementValue: 25 });
const racingResults = await Promise.all(
Array.from({ length: 10 }, () => initialReservation(racing)),
);
for (const user of [reserved, synced, spent, racing]) {
const records = await Balance.find({ user }).lean();
expect(records.map((record) => record._id.toString())).toEqual([user.toString()]);
}
expect(await Balance.findById(synced).lean()).toMatchObject({
tokenCredits: 50,
refillAmount: 5,
});
expect((await Balance.findById(spent).lean())?.tokenCredits).toBe(25);
expect(racingResults.filter((result) => result?.reserved)).toHaveLength(2);
});
test('resolves a user with duplicate records to their oldest record on every path', async () => {
const user = new mongoose.Types.ObjectId();
const nowSeconds = Math.floor(Date.now() / 1000);
const newer = mongoose.Types.ObjectId.createFromTime(nowSeconds);
const older = mongoose.Types.ObjectId.createFromTime(nowSeconds - 3600);
await Balance.create({ _id: newer, user, tokenCredits: 5000 });
await Balance.create({ _id: older, user, tokenCredits: 1000 });
expect((await findBalanceByUser(user.toString()))?._id?.toString()).toBe(older.toString());
await expect(reserve(user.toString(), 2000)).resolves.toEqual({
reserved: false,
balance: 1000,
});
await reserve(user.toString(), 400);
await updateBalance({ user: user.toString(), incrementValue: -100 });
await upsertBalanceFields(user.toString(), { refillAmount: 7 });
expect(await Balance.findById(older).select('+reservedCredits').lean()).toMatchObject({
tokenCredits: 900,
reservedCredits: 400,
refillAmount: 7,
});
const untouched = await Balance.findById(newer).select('+reservedCredits').lean();
expect(untouched?.tokenCredits).toBe(5000);
expect(untouched?.reservedCredits).toBeUndefined();
});
test('admits concurrent requests only up to the credits no other request holds', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, tokenCredits: 1000 });
const results = await Promise.all(
Array.from({ length: 10 }, () => reserve(user.toString(), 300)),
);
expect(results.filter((result) => result?.reserved)).toHaveLength(3);
const stored = await readState(user);
expect(stored?.tokenCredits).toBe(1000);
expect(stored?.reservations).toHaveLength(3);
expect(stored?.reservedCredits).toBe(900);
});
test('commits each admission of a funded burst on its first write', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, tokenCredits: 100_000 });
const realUpdateOne = Balance.updateOne.bind(Balance);
const writes = jest
.spyOn(Balance, 'updateOne')
.mockImplementation(((...args: Parameters<typeof Balance.updateOne>) =>
new Promise((resolve) => setTimeout(resolve, 25)).then(() =>
realUpdateOne(...args),
)) as unknown as typeof Balance.updateOne);
const results = await Promise.all(
Array.from({ length: 50 }, () => reserve(user.toString(), 100)),
);
expect(results.every((result) => result?.reserved)).toBe(true);
expect(writes).toHaveBeenCalledTimes(50);
const stored = await readState(user);
expect(stored?.reservations).toHaveLength(50);
expect(stored?.reservedCredits).toBe(5000);
});
test('holds whole credits so the running total stays exact', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, tokenCredits: 1000 });
const reservationId = newId();
await expect(reserve(user.toString(), 0.3, reservationId)).resolves.toEqual({
reserved: true,
balance: 1000,
});
expect((await readState(user))?.reservedCredits).toBe(1);
await releaseBalanceReservation({ user: user.toString(), reservationId, amount: 0.3 });
const stored = await readState(user);
expect(stored?.reservedCredits).toBe(0);
expect(stored?.reservations).toEqual([]);
});
test('releasing a reservation returns its credits to later admissions, once', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, tokenCredits: 1000 });
const firstId = newId();
await expect(reserve(user.toString(), 600, firstId)).resolves.toEqual({
reserved: true,
balance: 1000,
});
await expect(reserve(user.toString(), 600)).resolves.toEqual({
reserved: false,
balance: 400,
});
const release = { user: user.toString(), reservationId: firstId, amount: 600 };
await Promise.all([releaseBalanceReservation(release), releaseBalanceReservation(release)]);
expect((await readState(user))?.reservedCredits).toBe(0);
await expect(reserve(user.toString(), 600)).resolves.toEqual({
reserved: true,
balance: 1000,
});
});
test('prunes expired reservations together with their credits', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({
user,
tokenCredits: 1000,
reservedCredits: 900,
reservations: [{ id: 'stale', amount: 900, expiresAt: new Date(Date.now() - 1000) }],
});
const reservationId = newId();
await expect(reserve(user.toString(), 600, reservationId)).resolves.toEqual({
reserved: true,
balance: 1000,
});
const stored = await readState(user);
expect(stored?.reservations?.map((reservation) => reservation.id)).toEqual([reservationId]);
expect(stored?.reservedCredits).toBe(600);
});
test('prunes a backlog of expired reservations in one bulk write', async () => {
const user = new mongoose.Types.ObjectId();
const expiredAt = new Date(Date.now() - 1000);
await Balance.create({
user,
tokenCredits: 1000,
reservedCredits: 201,
reservations: [
{ id: 'live', amount: 1, expiresAt: inFuture() },
...Array.from({ length: 200 }, (_, i) => ({
id: `stale-${i}`,
amount: 1,
expiresAt: expiredAt,
})),
],
});
const writes = jest.spyOn(Balance, 'updateOne');
const bulkWrites = jest.spyOn(Balance, 'bulkWrite');
const reservationId = newId();
await expect(reserve(user.toString(), 100, reservationId)).resolves.toEqual({
reserved: true,
balance: 999,
});
expect(bulkWrites).toHaveBeenCalledTimes(1);
expect(bulkWrites.mock.calls[0][0]).toHaveLength(200);
expect(writes).toHaveBeenCalledTimes(1);
const stored = await readState(user);
expect(stored?.reservations?.map((reservation) => reservation.id)).toEqual([
'live',
reservationId,
]);
expect(stored?.reservedCredits).toBe(101);
});
test('prunes the rest in the same write when one expired reservation is renewed mid-attempt', async () => {
const user = new mongoose.Types.ObjectId();
const expiredAt = new Date(Date.now() - 1000);
await Balance.create({
user,
tokenCredits: 1000,
reservedCredits: 900,
reservations: [
{ id: 'renewed', amount: 400, expiresAt: expiredAt },
{ id: 'stale', amount: 500, expiresAt: expiredAt },
],
});
interleaveBeforeNextWrite(() =>
renewBalanceReservation({
user: user.toString(),
reservationId: 'renewed',
expiresAt: inFuture(),
}),
);
const reads = jest.spyOn(Balance, 'findOne');
const reservationId = newId();
await expect(reserve(user.toString(), 600, reservationId)).resolves.toEqual({
reserved: true,
balance: 600,
});
expect(reads).toHaveBeenCalledTimes(2);
const stored = await readState(user);
expect(stored?.reservations?.map((reservation) => reservation.id)).toEqual([
'renewed',
reservationId,
]);
expect(stored?.reservedCredits).toBe(1000);
});
test('renews a live reservation and never resurrects a released one', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, tokenCredits: 1000 });
const liveId = newId();
const releasedId = newId();
await reserve(user.toString(), 300, liveId);
await reserve(user.toString(), 200, releasedId);
await releaseBalanceReservation({
user: user.toString(),
reservationId: releasedId,
amount: 200,
});
const renewedUntil = new Date(Date.now() + 3_600_000);
await renewBalanceReservation({
user: user.toString(),
reservationId: liveId,
expiresAt: renewedUntil,
});
await renewBalanceReservation({
user: user.toString(),
reservationId: releasedId,
expiresAt: renewedUntil,
});
const stored = await readState(user);
expect(stored?.reservations).toEqual([{ id: liveId, amount: 300, expiresAt: renewedUntil }]);
expect(stored?.reservedCredits).toBe(300);
});
test('keeps a reservation that was renewed after a pruning read saw it expired', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({
user,
tokenCredits: 1000,
reservedCredits: 900,
reservations: [{ id: 'renewed', amount: 900, expiresAt: new Date(Date.now() - 1000) }],
});
interleaveBeforeNextWrite(() =>
renewBalanceReservation({
user: user.toString(),
reservationId: 'renewed',
expiresAt: inFuture(),
}),
);
await expect(reserve(user.toString(), 600)).resolves.toEqual({
reserved: false,
balance: 100,
});
const stored = await readState(user);
expect(stored?.reservations?.map((reservation) => reservation.id)).toEqual(['renewed']);
expect(stored?.reservedCredits).toBe(900);
});
test('admits a zero-cost request without storing a reservation', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, tokenCredits: 0 });
await expect(reserve(user.toString(), 0)).resolves.toEqual({ reserved: true, balance: 0 });
const stored = await readState(user);
expect(stored?.reservations).toBeUndefined();
expect(stored?.reservedCredits).toBeUndefined();
});
test('reports only unexpired reservations when a read asks for the reserved credits', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({
user,
tokenCredits: 1000,
reservedCredits: 1200,
reservations: [
{ id: 'live', amount: 300, expiresAt: inFuture() },
{ id: 'stale', amount: 900, expiresAt: new Date(Date.now() - 1000) },
],
});
const record = await findBalanceByUser(user.toString(), { includeReservedCredits: true });
expect(record?.tokenCredits).toBe(1000);
expect(record?.reservedCredits).toBe(300);
expect(record).not.toHaveProperty('reservations');
});
test('keeps reservation state out of ordinary balance reads and writes', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, tokenCredits: 1000 });
await reserve(user.toString(), 100);
const hidden = ['reservations', 'reservedCredits', 'pendingRefill'];
const record = await findBalanceByUser(user.toString());
const synced = await upsertBalanceFields(user.toString(), { refillAmount: 5 });
const spent = await updateBalance({ user: user.toString(), incrementValue: -10 });
expect(record?.tokenCredits).toBe(1000);
expect(spent.tokenCredits).toBe(990);
for (const read of [record, synced, spent]) {
for (const field of hidden) {
expect(read).not.toHaveProperty(field);
}
}
});
test('removes a reservation whose write committed but failed to acknowledge', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, tokenCredits: 1000 });
const realUpdateOne = Balance.updateOne.bind(Balance);
jest.spyOn(Balance, 'updateOne').mockImplementationOnce(((
...args: Parameters<typeof Balance.updateOne>
) =>
realUpdateOne(...args).then(() => {
throw new Error('connection reset');
})) as unknown as typeof Balance.updateOne);
await expect(reserve(user.toString(), 400)).rejects.toThrow('connection reset');
const stored = await readState(user);
expect(stored?.reservations).toEqual([]);
expect(stored?.reservedCredits).toBe(0);
});
test('re-reads when a spend lands between the read and the write', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, tokenCredits: 1000 });
interleaveBeforeNextWrite(() =>
Balance.collection.updateOne({ user }, { $inc: { tokenCredits: -800 } }),
);
await expect(reserve(user.toString(), 500)).resolves.toEqual({
reserved: false,
balance: 200,
});
expect((await readState(user))?.reservedCredits).toBeUndefined();
});
test('re-reads when another admission takes the credits between the read and the write', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, tokenCredits: 1000 });
interleaveBeforeNextWrite(() => reserve(user.toString(), 800));
await expect(reserve(user.toString(), 500)).resolves.toEqual({
reserved: false,
balance: 200,
});
expect((await readState(user))?.reservedCredits).toBe(800);
});
describe('auto-refill', () => {
const refillable = {
tokenCredits: 0,
autoRefillEnabled: true,
refillAmount: 1000,
refillIntervalValue: 30,
refillIntervalUnit: 'days' as const,
lastRefill: new Date('2020-01-01T00:00:00.000Z'),
};
describe('reset mode', () => {
const resettable = { ...refillable, refillMode: 'reset' as const };
test.each([500, 1500, -100])(
'replaces %s credits with one allowance on read',
async (credits) => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...resettable, tokenCredits: credits });
const balance = await findBalanceByUser(user.toString());
expect(balance?.tokenCredits).toBe(1000);
expect(balance?.refillMode).toBe('reset');
expect(balance).not.toHaveProperty('pendingRefill');
expect(balance).not.toHaveProperty('reservations');
expect(balance).not.toHaveProperty('reservedCredits');
const resets = await Transaction.find({ user, context: 'balanceReset' }).lean();
expect(resets).toHaveLength(1);
expect(resets[0].rawAmount).toBe(1000 - credits);
expect(resets[0].tokenValue).toBe(1000 - credits);
},
);
test.each([0, -1, 0.0001, 0.5, 1.5])(
'does not grant repeated allowances for invalid interval %s',
async (refillIntervalValue) => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...resettable, refillIntervalValue, tokenCredits: 500 });
await findBalanceByUser(user.toString());
await reserve(user.toString(), 100);
await findBalanceByUser(user.toString());
expect((await readState(user))?.tokenCredits).toBe(500);
expect(await Transaction.countDocuments({ user })).toBe(0);
},
);
test('disabled resets remain disabled on reads and admission', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...resettable, tokenCredits: 500 });
await upsertBalanceFields(user.toString(), { autoRefillEnabled: false });
expect((await findBalanceByUser(user.toString()))?.tokenCredits).toBe(500);
expect(await reserve(user.toString(), 100)).toEqual({ reserved: true, balance: 500 });
expect(await Transaction.countDocuments({ user })).toBe(0);
});
test('resets before admission even when the remaining balance covers the request', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...resettable, tokenCredits: 500 });
expect(await reserve(user.toString(), 100)).toEqual({ reserved: true, balance: 1000 });
expect((await readState(user))?.tokenCredits).toBe(1000);
});
test('preserves reservations and applies one reset across concurrent reads and admissions', async () => {
const user = new mongoose.Types.ObjectId();
const heldId = newId();
await Balance.create({
user,
...resettable,
tokenCredits: 1500,
reservedCredits: 700,
reservations: [{ id: heldId, amount: 700, expiresAt: new Date(Date.now() + 60_000) }],
});
await Promise.all([
findBalanceByUser(user.toString()),
findBalanceByUser(user.toString()),
reserve(user.toString(), 200),
]);
const stored = await readState(user);
expect(stored?.tokenCredits).toBe(1000);
expect(stored?.reservedCredits).toBe(900);
expect(stored?.reservations?.some((held) => held.id === heldId)).toBe(true);
expect(await Transaction.countDocuments({ user, context: 'balanceReset' })).toBe(1);
});
test('does not reset again before the next period or accumulate missed periods', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...resettable, tokenCredits: 400 });
await findBalanceByUser(user.toString());
await Balance.updateOne({ user }, { $set: { tokenCredits: 600 } });
expect((await findBalanceByUser(user.toString()))?.tokenCredits).toBe(600);
expect(await Transaction.countDocuments({ user, context: 'balanceReset' })).toBe(1);
});
test('replays a failed reset ledger write without resetting or duplicating the allowance', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...resettable, tokenCredits: 1500 });
const save = jest
.spyOn(Transaction.prototype, 'save')
.mockRejectedValue(new Error('ledger unavailable'));
expect((await findBalanceByUser(user.toString()))?.tokenCredits).toBe(1000);
save.mockRestore();
expect((await findBalanceByUser(user.toString()))?.tokenCredits).toBe(1000);
expect((await readState(user))?.pendingRefill).toBeUndefined();
const resets = await Transaction.find({ user, context: 'balanceReset' }).lean();
expect(resets).toHaveLength(1);
expect(resets[0].rawAmount).toBe(-500);
});
test('synchronizes a changed allowance before applying a due reset', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...resettable, tokenCredits: 500 });
expect(
(await findBalanceByUser(user.toString(), { applyReset: false }))?.tokenCredits,
).toBe(500);
expect(await Transaction.countDocuments({ user })).toBe(0);
expect(
(await upsertBalanceFields(user.toString(), { refillAmount: 2000 }))?.tokenCredits,
).toBe(2000);
const resets = await Transaction.find({ user, context: 'balanceReset' }).lean();
expect(resets).toHaveLength(1);
expect(resets[0].rawAmount).toBe(1500);
});
test('uses current settings if reset mode changes during its fenced write', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...resettable, tokenCredits: 500 });
interleaveBeforeNextWrite(() =>
Balance.collection.updateOne({ user }, { $set: { refillMode: 'add' } }),
);
expect(await reserve(user.toString(), 100)).toEqual({ reserved: true, balance: 500 });
expect(await Transaction.countDocuments({ user })).toBe(0);
});
});
test('applies one refill per eligibility window across concurrent admissions', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...refillable });
const results = await Promise.all(
Array.from({ length: 10 }, () => reserve(user.toString(), 150)),
);
expect(results.filter((result) => result?.reserved)).toHaveLength(6);
const stored = await readState(user);
expect(stored?.tokenCredits).toBe(1000);
expect(stored?.lastRefill.getTime()).toBeGreaterThan(refillable.lastRefill.getTime());
expect(stored?.pendingRefill).toBeUndefined();
const refills = await Transaction.find({ user, context: 'autoRefill' }).lean();
expect(refills).toHaveLength(1);
expect(refills[0].rawAmount).toBe(1000);
});
test.each([
['lastRefill advances', { lastRefill: new Date() }, 0],
['auto-refill is disabled', { autoRefillEnabled: false }, 0],
['the refill amount changes', { refillAmount: 10 }, 10],
['the refill interval lengthens', { refillIntervalValue: 100_000 }, 0],
])(
'applies the current refill settings when %s mid-attempt',
async (_case, change, credits) => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...refillable });
interleaveBeforeNextWrite(() => Balance.collection.updateOne({ user }, { $set: change }));
await expect(reserve(user.toString(), 150)).resolves.toEqual({
reserved: false,
balance: credits,
});
expect((await readState(user))?.tokenCredits).toBe(credits);
expect(await Transaction.countDocuments({ user, context: 'autoRefill' })).toBe(
credits > 0 ? 1 : 0,
);
},
);
test('does not refill when a release frees enough credits mid-attempt', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...refillable, tokenCredits: 1000 });
const heldId = newId();
await reserve(user.toString(), 900, heldId);
interleaveBeforeNextWrite(() =>
releaseBalanceReservation({ user: user.toString(), reservationId: heldId, amount: 900 }),
);
await expect(reserve(user.toString(), 200)).resolves.toEqual({
reserved: true,
balance: 1000,
});
const stored = await readState(user);
expect(stored?.tokenCredits).toBe(1000);
expect(stored?.lastRefill.getTime()).toBe(refillable.lastRefill.getTime());
expect(await Transaction.countDocuments({ user, context: 'autoRefill' })).toBe(0);
});
test('still applies a due refill when the refilled balance cannot cover the request', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...refillable, refillAmount: 100 });
await expect(reserve(user.toString(), 500)).resolves.toEqual({
reserved: false,
balance: 100,
});
const stored = await readState(user);
expect(stored?.tokenCredits).toBe(100);
expect(stored?.reservations).toBeUndefined();
});
test.each([
['covers the request exactly', 100, true, 100],
['still falls short', 10, false, 10],
])(
'applies a refill whose interval is due again at once only once per admission when it %s',
async (_case, refillAmount, reserved, credits) => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...refillable, refillAmount, refillIntervalValue: 0 });
await expect(reserve(user.toString(), 100)).resolves.toEqual({
reserved,
balance: credits,
});
expect((await readState(user))?.tokenCredits).toBe(credits);
expect(await Transaction.countDocuments({ user, context: 'autoRefill' })).toBe(1);
},
);
test('does not refill while the unreserved balance covers the request', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...refillable, tokenCredits: 500 });
await expect(reserve(user.toString(), 100)).resolves.toEqual({
reserved: true,
balance: 500,
});
expect((await readState(user))?.tokenCredits).toBe(500);
});
test('records the ledger transaction of a refill whose first recording failed', async () => {
const user = new mongoose.Types.ObjectId();
await Balance.create({ user, ...refillable });
const save = jest
.spyOn(Transaction.prototype, 'save')
.mockRejectedValue(new Error('ledger unavailable'));
await expect(reserve(user.toString(), 150)).resolves.toEqual({
reserved: true,
balance: 1000,
});
const applied = await readState(user);
expect(applied?.tokenCredits).toBe(1000);
expect(applied?.pendingRefill?.rawAmount).toBe(1000);
expect(await Transaction.countDocuments({ user, context: 'autoRefill' })).toBe(0);
save.mockRestore();
await reserve(user.toString(), 150);
const settled = await readState(user);
expect(settled?.tokenCredits).toBe(1000);
expect(settled?.pendingRefill).toBeUndefined();
const refills = await Transaction.find({ user, context: 'autoRefill' }).lean();
expect(refills.map((refill) => refill._id.toString())).toEqual([
applied?.pendingRefill?.transactionId.toString(),
]);
});
test('does not duplicate a ledger transaction that was recorded before its marker cleared', async () => {
const user = new mongoose.Types.ObjectId();
const transactionId = new mongoose.Types.ObjectId();
await Transaction.create({
_id: transactionId,
user,
tokenType: 'credits',
context: 'autoRefill',
rawAmount: 1000,
});
await Balance.create({
user,
...refillable,
tokenCredits: 1000,
lastRefill: new Date(),
pendingRefill: { transactionId, rawAmount: 1000 },
});
await reserve(user.toString(), 150);
expect((await readState(user))?.pendingRefill).toBeUndefined();
expect(await Transaction.countDocuments({ user, context: 'autoRefill' })).toBe(1);
});
});
});