![\"@bymax-one/nest-ai-tokens\"](\"https://img.shields.io/badge/%40bymax--one-nest--ai--tokens-000000?style=for-the-badge&logo=nestjs&logoColor=E0234E\"){kind=icon}
\n\n
\n AI token metering and usage-based billing for NestJS
\n 9 Provider Normalizers · Exact bigint nano-USD · Append-only Ledger · Hash-chain Integrity · Prepaid Wallets · Budgets · Streaming · Zero Runtime Dependencies\n
\n ![\"npm](\"https://img.shields.io/npm/v/@bymax-one/nest-ai-tokens?style=flat-square&colorA=000000&colorB=000000\")
![\"npm](\"https://img.shields.io/npm/dm/@bymax-one/nest-ai-tokens?style=flat-square&colorA=000000&colorB=000000\")
![\"CI](\"https://img.shields.io/github/actions/workflow/status/bymaxone/nest-ai-tokens/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI\")
![\"coverage\"](\"https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000\"){kind=icon}
![\"mutation](\"https://img.shields.io/badge/mutation-100%25-brightgreen?style=flat-square&colorA=000000\"){kind=icon}
\n
![\"license\"](\"https://img.shields.io/github/license/bymaxone/nest-ai-tokens?style=flat-square&colorA=000000&colorB=000000\")
![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white\"){kind=icon}
![\"Node.js\"](\"https://img.shields.io/badge/Node.js-24%2B-339933?style=flat-square&logo=node.js&logoColor=white\"){kind=icon}
\n GitHub ·\n Issues ·\n Quick Start ·\n API Reference ·\n Example App\n
\n\n---\n\n## ✨ Overview\n\n`@bymax-one/nest-ai-tokens` meters AI usage and bills it, in-process. Instead of assembling a\nproxy for enforcement, a ledger for accounting, a price table for rating and a wallet for\nprepaid credit — four systems that must agree on what a call cost — you install one library\nand get all of it behind a NestJS guard and interceptor.\n\nThe library has **zero direct dependencies**. NestJS, Prisma, `ioredis`, the event emitter and\nOpenTelemetry all arrive as peer dependencies, and the optional ones are never imported unless\nthe feature that needs them is enabled.\n\n### Why nest-ai-tokens?\n\n- **Enforcement happens in the request.** A guard refuses the call before the handler runs\n and an interceptor settles the actual usage after it — no proxy to deploy, no sidecar to\n keep alive, no external hop that can fail open.\n- **Money is exact by construction.** Every persisted amount is `bigint` nano-USD. There is no\n float arithmetic on a money path, because a rounding difference there is a number a customer\n is charged.\n- **The ledger is evidence, not state.** Entries are appended and corrections are compensating\n records; with the optional hash chain on, a row edited in the database stops matching the\n chain that follows it.\n- **Charging twice is prevented by the database.** The idempotency key carries a unique\n constraint, and the replay path is that violation being recognized as a conflict — not\n application care that someone can forget.\n\n---\n\n## 🔥 Features\n\n### 📊 Metering\n\n- ✅ **Nine provider normalizers** — OpenAI Chat, OpenAI Responses, OpenAI-compatible\n (DeepSeek / xAI / Groq / Azure), Anthropic, Gemini, Bedrock Converse, Mistral, OpenRouter\n and the Vercel AI SDK, all folded into one usage shape\n- ✅ **Provider-agnostic by construction** — normalizers consume plain objects, so no provider\n SDK is a dependency and this library never makes the model call itself\n- ✅ **Every billing dimension** — cached tokens, reasoning tokens, audio and image units, and\n the write/read split providers report separately\n- ✅ **Streaming capture** — `StreamUsageCollector` accumulates chunks and prefers the\n provider's final usage, falling back to its own count when a stream is cut short\n\n### 💰 Money & Ledger\n\n- ✅ **Exact `bigint` nano-USD** — on every persisted amount; no float arithmetic on a money\n path\n- ✅ **Point-in-time rating** — an entry is priced at the rate in effect at the call\n timestamp, and never re-rated by a later price change\n- ✅ **Append-only ledger** — corrections are compensating records that point at what they\n reverse; nothing is updated in place\n- ✅ **Hash-chain integrity** — optional per-entry chain over the previous posted entry, so a\n row edited directly in the database is detectable\n- ✅ **Exactly-once accounting** — a unique constraint on the idempotency key; the violation\n is what the replay path recognizes as a conflict\n- ✅ **Markup as configuration** — a fixed multiplier or a per-call `IMarkupPolicy`, applied\n in both rating modes, so the resale spread is not application code\n\n### 🛡️ Enforcement\n\n- ✅ **Hold → capture lifecycle** — the guard places a spend hold before the handler runs when\n an estimate is declared; the interceptor settles it to actuals afterwards\n- ✅ **Multi-dimension budgets** — cap spend, token count and operation count per scope per\n window (daily / weekly / monthly), hard or soft\n- ✅ **Atomic budget counter** — the optional `RedisBudgetCounterStore` runs check and\n increment as one Lua script, so two concurrent requests cannot both fit under a cap that\n holds one\n- ✅ **Prepaid wallets** — append-only grant / debit / refund / adjust entries, with a\n configurable burn order (expiry, priority, FIFO)\n\n### 🧩 Developer Experience\n\n- ✅ **Zero runtime dependencies** — Prisma, `ioredis`, the event emitter and OpenTelemetry\n all arrive as peers, and the optional ones are imported only when enabled\n- ✅ **Five subpaths** — `.` server · `./shared` zero-dependency contracts · `./prices` seed\n data · `./prisma` the PostgreSQL store · `./redis` the budget counter\n- ✅ **Usage reports** — summarize by scope, feature, model or date, with currency conversion\n and CSV or JSON export\n- ✅ **Typed events** — ten emitted event types over `@nestjs/event-emitter`, optional\n (`wallet.low_balance` is declared in the catalog and reserved; nothing emits it yet)\n- ✅ **OpenTelemetry** — an optional sink that traces every metering call, carrying model and\n operation and never prompt or completion text\n- ✅ **Typed end to end** — TypeScript `strict` with `exactOptionalPropertyTypes` and\n `noUncheckedIndexedAccess`; zero `any`\n\n---\n\n## 📦 Subpath Exports\n\n| Subpath | What it contains | Runtime deps |\n| ---------------------------------- | ---------------------------------------------------------------------------------- | ----------------------- |\n| `@bymax-one/nest-ai-tokens` | Dynamic module, services, guard, interceptor, decorators, collector, ports, errors | NestJS (peer) |\n| `@bymax-one/nest-ai-tokens/shared` | Normalizers, pure cost math, types, catalogs, error codes | Zero |\n| `@bymax-one/nest-ai-tokens/prices` | `MODEL_PRICES_SEED` — pinned price snapshot (data-only, large; imported lazily) | Zero |\n| `@bymax-one/nest-ai-tokens/prisma` | `PrismaAiTokensStore` — the official PostgreSQL adapter | `@prisma/client` (peer) |\n| `@bymax-one/nest-ai-tokens/redis` | `RedisBudgetCounterStore` — optional fast budget counter | `ioredis` (peer) |\n\n> The `./shared` subpath is framework-free and edge-safe — use it in frontends, workers, and edge functions that must not pull NestJS.\n> The `./prices` subpath exists so `./shared` stays within the family's tiny-bundle budget.\n\n### Artifact sizes (brotli)\n\n| Artifact | Brotli size | Budget |\n| ------------------------------------------- | ----------- | ------- |\n| server (`@bymax-one/nest-ai-tokens`) | 37 KB | < 40 KB |\n| shared (`@bymax-one/nest-ai-tokens/shared`) | 5 KB | < 10 KB |\n| prisma (`@bymax-one/nest-ai-tokens/prisma`) | 10 KB | < 15 KB |\n| redis (`@bymax-one/nest-ai-tokens/redis`) | 1.1 KB | < 5 KB |\n| prices (data-only, exempt from budget) | 1.3 KB | exempt |\n\n---\n\n## 🚀 Quick Start\n\n### 1 — Install\n\n```bash\nnpm i @bymax-one/nest-ai-tokens\n```\n\nRequired peers (if not already present):\n\n```bash\nnpm i @nestjs/common @nestjs/core reflect-metadata rxjs\n# Persistence:\nnpm i @prisma/client\n# Prisma 7 only — the client is opened through a driver adapter:\nnpm i @prisma/adapter-pg\n```\n\n> **Prisma 6 and 7 are both supported.** The adapter talks to PostgreSQL through\n> parameterized raw SQL and never touches a generated model delegate, so the same\n> code runs on either. What differs is how _your application_ builds the client it\n> hands over:\n>\n> ```typescript\n> // Prisma 6\n> const prisma = new PrismaClient({ datasourceUrl: process.env.DATABASE_URL })\n>\n> // Prisma 7 — `datasourceUrl` was removed; open through a driver adapter\n> import { PrismaPg } from '@prisma/adapter-pg'\n> const prisma = new PrismaClient({\n> adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }),\n> })\n> ```\n>\n> Prisma 7 also removed `url` from `datasource` blocks in `schema.prisma`; it\n> moves to a `prisma.config.ts` at your project root. Neither change reaches this\n> library's API — `PrismaAiTokensStore` receives whatever client you built.\n\n### 2 — Register the module\n\n```typescript\nimport { Module } from '@nestjs/common'\nimport { BymaxAiTokensModule } from '@bymax-one/nest-ai-tokens'\nimport { PrismaAiTokensStore } from '@bymax-one/nest-ai-tokens/prisma'\n\n@Module({\n imports: [\n BymaxAiTokensModule.forRootAsync({\n imports: [PrismaModule],\n inject: [PrismaService],\n useFactory: (prisma: PrismaService) => ({\n store: new PrismaAiTokensStore(prisma),\n // The resale lever — end-users pay 4× provider cost:\n markup: 4.0,\n wallets: { creditRateNanoUsd: 5_000_000_000n }, // 1 credit = $5\n budgets: { defaultPolicy: 'block', alertThresholds: [0.8, 1.0] },\n pricing: { seedFromSnapshot: true }, // seed price table on first boot\n }),\n }),\n ],\n})\nexport class AppModule {}\n```\n\n### 3 — Record usage (post-hoc, observe-only)\n\n```typescript\nimport { Injectable } from '@nestjs/common'\nimport { MeteringService, providerPresets } from '@bymax-one/nest-ai-tokens'\nimport { deriveIdempotencyKey } from '@bymax-one/nest-ai-tokens/shared'\n\n@Injectable()\nexport class WorkoutAiService {\n constructor(private readonly metering: MeteringService) {}\n\n async generate(tenantId: string, userId: string, jobId: string) {\n const res = await this.openai.chat.completions.create({ model: 'gpt-4o', messages: [] })\n await this.metering.record({\n usage: res.usage,\n preset: providerPresets.openaiChat,\n context: {\n tenantId,\n scope: { type: 'user', id: userId },\n feature: 'workout.generate',\n idempotencyKey: deriveIdempotencyKey({ jobId }), // retry-safe\n },\n })\n return res.choices[0]?.message.content\n }\n}\n```\n\n### 4 — Enforced metering via guard + interceptor\n\n```typescript\nimport { Controller, Post, Get, Body, UseGuards, UseInterceptors, Req } from '@nestjs/common'\nimport {\n BudgetGuard,\n MeteringInterceptor,\n Meter,\n RequireBudget,\n MeteringService,\n toJsonSafe,\n providerPresets,\n} from '@bymax-one/nest-ai-tokens'\n\n@Controller('ai')\n@UseGuards(BudgetGuard)\n@UseInterceptors(MeteringInterceptor)\nexport class AiController {\n constructor(private readonly metering: MeteringService) {}\n\n @Post('summarize')\n @RequireBudget({ scope: 'tenant', estimate: { tokens: 3_000 } })\n @Meter({\n feature: 'doc.summarize',\n scope: 'tenant',\n preset: providerPresets.anthropic,\n exposeHeaders: true,\n })\n async summarize(@Body() dto: { content: string }) {\n // Guard checks budget and places a hold; interceptor settles it with the handler's actual usage.\n return this.ai.summarize(dto.content) // returns { summary, usage }\n }\n\n @Get('me/usage')\n async myUsage(@Req() req: { user: { tenantId: string; id: string } }) {\n const status = await this.metering.getStatus(req.user.tenantId, {\n type: 'user',\n id: req.user.id,\n })\n return toJsonSafe(status) // bigint → decimal strings for JSON serialization\n }\n}\n```\n\n---\n\n## ⚙️ Configuration\n\n`BymaxAiTokensModule.forRoot(options)` / `.forRootAsync({ useFactory })` accept `BymaxAiTokensModuleOptions`:\n\n| Option | Type | Default | Purpose |\n| --------------------------- | ------------------------------------- | -------------- | ----------------------------------------------------------------------------- |\n| `store` | `IAiTokensStore` | — (required) | Persistence adapter (use `PrismaAiTokensStore`) |\n| `scopeResolver` | `(ctx) => MeteringContext` | — | Resolves the caller's scope from the request (required for guard/interceptor) |\n| `ratingMode` | `'rate-table' \\| 'provider-reported'` | `'rate-table'` | Default cost rating mode |\n| `markup` | `number \\| IMarkupPolicy` | `1.0` | The resale multiplier (e.g. `4.0` = 4× provider cost) |\n| `pricing.seedFromSnapshot` | `boolean` | `false` | Seed `MODEL_PRICES_SEED` into the registry on first boot |\n| `wallets.creditRateNanoUsd` | `bigint` | — | Exchange rate: 1 credit = this many nano-USD |\n| `wallets.burnOrder` | `'expiry' \\| 'priority' \\| 'fifo'` | `'expiry'` | Order in which grants are consumed |\n| `budgets.defaultPolicy` | `'block' \\| 'alert'` | `'alert'` | Default enforcement when a budget is exhausted |\n| `budgets.alertThresholds` | `number[]` | `[0.8, 1.0]` | Soft-threshold events at these fractions |\n| `holds.ttlSeconds` | `number` | `300` | Spend-hold TTL; the reaper voids expired holds |\n| `telemetry` | `ITelemetrySink` | no-op | OpenTelemetry sink (pass `OtelTelemetrySink`) |\n\n---\n\n## 🧩 Providers Matrix\n\n| Provider | API | Normalizer |\n| ----------------- | --------------------------------- | ---------------------------------------------------------------------------------- |\n| OpenAI | Chat Completions | `normalizeOpenAiChatUsage` / `providerPresets.openaiChat` |\n| OpenAI | Responses API | `normalizeOpenAiResponsesUsage` / `providerPresets.openaiResponses` |\n| OpenAI-compatible | DeepSeek, xAI, Groq, Azure OpenAI | `normalizeOpenAiCompatibleUsage` / `providerPresets.openaiCompatible` |\n| Anthropic | Messages API | `normalizeAnthropicUsage` / `providerPresets.anthropic` |\n| Google | Gemini / Vertex AI | `normalizeGeminiUsage` / `providerPresets.gemini` |\n| AWS | Bedrock Converse | `normalizeBedrockConverseUsage` / `providerPresets.bedrockConverse` |\n| Mistral | Chat API | `normalizeMistralUsage` / `providerPresets.mistral` |\n| OpenRouter | Chat | `normalizeOpenRouterUsage` / `providerPresets.openrouter` (provider-reported cost) |\n| Vercel | AI SDK v5/v6 | `normalizeVercelAiSdkUsage` / `providerPresets.vercelAiSdk` |\n\nAll normalizers are pure functions over plain objects — no provider SDK peer dependency. Pass the raw response object and get back a `NormalizedUsage`.\n\n---\n\n## 💰 Pricing & Markup\n\nThe fundamental difference between \"what the provider charged you\" and \"what you charge your users\" is the **markup multiplier**. This library makes that multiplier a first-class configuration option.\n\n```typescript\n// Configure at module level:\nBymaxAiTokensModule.forRootAsync({\n useFactory: (prisma) => ({\n store: new PrismaAiTokensStore(prisma),\n markup: 4.0, // 4× resale margin\n wallets: { creditRateNanoUsd: 5_000_000_000n }, // sell credits at $5 each\n }),\n})\n\n// Example ledger entry:\n// Provider cost: $0.005 (5_000_000n nano-USD)\n// Billed to user: $0.020 (20_000_000n nano-USD, after 4× markup)\n// Margin: $0.015 per call\n```\n\nFor per-tenant or per-feature pricing, implement `IMarkupPolicy`:\n\n```typescript\nclass MyMarkupPolicy implements IMarkupPolicy {\n resolve(ctx: MeteringContext): number | Promise\n Built with ❤️ by Bymax One\n
\n","readmeFilename":"README.md"}