{"_id":"@anby/billing","_rev":"4-4b6990911dee0fea6d53133ee1ff4aa8","name":"@anby/billing","dist-tags":{"latest":"1.1.0"},"versions":{"0.1.0":{"name":"@anby/billing","version":"0.1.0","keywords":["anby","anby-platform","billing","credits","sdk"],"author":{"name":"ANBY"},"license":"MIT","_id":"@anby/billing@0.1.0","maintainers":[{"name":"anby-platform","email":"aie@bravebits.vn"}],"homepage":"https://github.com/bravebits-labs/anby-platform-packages#readme","bugs":{"url":"https://github.com/bravebits-labs/anby-platform-packages/issues"},"dist":{"shasum":"45b1628c050102209da995db07c05a956e7421bc","tarball":"https://registry.npmjs.org/@anby/billing/-/billing-0.1.0.tgz","fileCount":33,"integrity":"sha512-popdR29XA97EYpSERXtxyDK2Isau0gn5fDk1nGkiEalvPn5a0FpNTME/eew8OrS3ky1tnH+xyLEQYqTCDt1l/g==","signatures":[{"sig":"MEUCIBaubs8V2e6VijeU4O0sZJCbvt9SV12o6BG98qM1RNopAiEAupc4OKCSJQ0sjsxdASGBhqB4YC6OMT2YiDBeq2sHnuU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@anby%2fbilling@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":88887},"main":"dist/cjs/index.js","types":"dist/cjs/index.d.ts","module":"dist/esm/index.js","exports":{".":{"types":"./dist/cjs/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"}},"gitHead":"40518253f8f608ed30b319e520be51c933a31749","scripts":{"test":"vitest","build":"tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && node ../fixup-dual.mjs","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"anby-platform","email":"aie@bravebits.vn"},"repository":{"url":"git+https://github.com/bravebits-labs/anby-platform-packages.git","type":"git","directory":"packages/billing"},"_npmVersion":"10.8.2","description":"Anby Billing SDK — debit, credit, balance queries against anby-billing-service. HMAC-signed service-to-service calls.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.23.8","@anby/contracts":"^1.1.0","@anby/platform-sdk":"^1.1.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.5.0"},"_npmOperationalInternal":{"tmp":"tmp/billing_0.1.0_1777448290231_0.9141111288544661","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@anby/billing","version":"1.0.0","keywords":["anby","anby-platform","billing","credits","sdk"],"author":{"name":"ANBY"},"license":"MIT","_id":"@anby/billing@1.0.0","maintainers":[{"name":"anby-platform","email":"aie@bravebits.vn"}],"homepage":"https://github.com/bravebits-labs/anby-platform-packages#readme","bugs":{"url":"https://github.com/bravebits-labs/anby-platform-packages/issues"},"dist":{"shasum":"d0bd21b33543248119ecd5e4bab042e87024cadc","tarball":"https://registry.npmjs.org/@anby/billing/-/billing-1.0.0.tgz","fileCount":33,"integrity":"sha512-PMsNy03Kra5JmltVQ0MttVTMz+9G0CMeT0kaNGT6J0UkS/LeqJxNlXIekiSxbn7E51k7qVSlpAs2mUm9Z0QCMw==","signatures":[{"sig":"MEUCIQDVMEudd2t14794sT7fvnoiy/t2Zw5CEIHpsGXr0j3ChQIgXNopdSW4Y108n32/90MJk5P6SLzAj5/rjszwvPF/wvY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@anby%2fbilling@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":88887},"main":"dist/cjs/index.js","types":"dist/cjs/index.d.ts","module":"dist/esm/index.js","exports":{".":{"types":"./dist/cjs/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"}},"gitHead":"84ef1d7f7afc70b46407003feb03273492e4b63f","scripts":{"test":"vitest","build":"tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && node ../fixup-dual.mjs","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"anby-platform","email":"aie@bravebits.vn"},"repository":{"url":"git+https://github.com/bravebits-labs/anby-platform-packages.git","type":"git","directory":"packages/billing"},"_npmVersion":"10.8.2","description":"Anby Billing SDK — debit, credit, balance queries against anby-billing-service. HMAC-signed service-to-service calls.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.23.8","@anby/contracts":"^1.1.0","@anby/platform-sdk":"^1.1.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.5.0"},"_npmOperationalInternal":{"tmp":"tmp/billing_1.0.0_1777448770119_0.5840492002094955","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@anby/billing","version":"1.0.1","keywords":["anby","anby-platform","billing","credits","sdk"],"author":{"name":"ANBY"},"license":"MIT","_id":"@anby/billing@1.0.1","maintainers":[{"name":"anby-platform","email":"aie@bravebits.vn"}],"homepage":"https://github.com/bravebits-labs/anby-platform-packages#readme","bugs":{"url":"https://github.com/bravebits-labs/anby-platform-packages/issues"},"dist":{"shasum":"46b56ade15989c0542d30713be5ce8a36a87c672","tarball":"https://registry.npmjs.org/@anby/billing/-/billing-1.0.1.tgz","fileCount":33,"integrity":"sha512-4zFjKb8mXZFjRh/kD/mt+d2tdfI+X1QKl4OmLgSPifcQOle2iMag3+8quB7KFesDBoPrnCwyvoDzjW0YwLlQMw==","signatures":[{"sig":"MEQCIDnpENLZD5g8X2Fio2NGbXiCCtK2pFIDIe4RG0n+AEQ4AiAKGGwC8CIRHONd2iRJ/mrSXjqtTCwBaAXaxgUcGxV5lw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@anby%2fbilling@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":94867},"main":"dist/cjs/index.js","types":"dist/cjs/index.d.ts","module":"dist/esm/index.js","exports":{".":{"types":"./dist/cjs/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"}},"gitHead":"32df6b1f943ac59d6df19955bb0bb73bd082447a","scripts":{"test":"vitest","build":"tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && node ../fixup-dual.mjs","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"anby-platform","email":"aie@bravebits.vn"},"repository":{"url":"git+https://github.com/bravebits-labs/anby-platform-packages.git","type":"git","directory":"packages/billing"},"_npmVersion":"10.8.2","description":"Anby Billing SDK — debit, credit, balance queries against anby-billing-service. HMAC-signed service-to-service calls.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.23.8","@anby/contracts":"^1.1.0","@anby/platform-sdk":"^1.1.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.5.0"},"_npmOperationalInternal":{"tmp":"tmp/billing_1.0.1_1777971025638_0.4836975235489873","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@anby/billing","version":"1.1.0","description":"Anby Billing SDK — debit, credit, balance queries against anby-billing-service. HMAC-signed service-to-service calls.","keywords":["anby","anby-platform","billing","credits","sdk"],"license":"MIT","author":{"name":"ANBY"},"homepage":"https://github.com/bravebits-labs/anby-platform-packages#readme","bugs":{"url":"https://github.com/bravebits-labs/anby-platform-packages/issues"},"repository":{"type":"git","url":"git+https://github.com/bravebits-labs/anby-platform-packages.git","directory":"packages/billing"},"main":"dist/cjs/index.js","module":"dist/esm/index.js","types":"dist/cjs/index.d.ts","exports":{".":{"types":"./dist/cjs/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.js"}},"publishConfig":{"access":"public","provenance":true},"scripts":{"build":"tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && node ../fixup-dual.mjs","typecheck":"tsc --noEmit","test":"vitest","prepublishOnly":"npm run build"},"dependencies":{"@anby/contracts":"^1.1.0","@anby/platform-sdk":"^1.1.0","zod":"^3.23.8"},"devDependencies":{"typescript":"^5.5.0","vitest":"^3.0.0"},"_id":"@anby/billing@1.1.0","gitHead":"fb142e19305b0cc7bbada861e2e79b3beceb4518","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-Q8AeHCRqYCVyjsjvrqKpI7Qdp8h2RdnEpkrZNyYvQF3GwoLFFZ5wEdpLyAhpOu/I3mdnZ/JsG3d/K0wZmgF3kg==","shasum":"c2a6d781d3ad9aee0bb77d245fc7ed308a7ee55c","tarball":"https://registry.npmjs.org/@anby/billing/-/billing-1.1.0.tgz","fileCount":33,"unpackedSize":124274,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@anby%2fbilling@1.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDA22iHnxLaYei2jZj+AJJgQeYNArL+Ix4k84nKW5zbtAIhAOnDS73d+Jqx/IGN6VN2GvjXaj9oMXvj9c4nftixuuaP"}]},"_npmUser":{"name":"anby-platform","email":"aie@bravebits.vn"},"directories":{},"maintainers":[{"name":"anby-platform","email":"aie@bravebits.vn"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/billing_1.1.0_1781171798195_0.9377314450272589"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-29T07:38:10.150Z","modified":"2026-06-11T09:56:38.609Z","0.1.0":"2026-04-29T07:38:10.382Z","1.0.0":"2026-04-29T07:46:10.283Z","1.0.1":"2026-05-05T08:50:25.786Z","1.1.0":"2026-06-11T09:56:38.332Z"},"bugs":{"url":"https://github.com/bravebits-labs/anby-platform-packages/issues"},"author":{"name":"ANBY"},"license":"MIT","homepage":"https://github.com/bravebits-labs/anby-platform-packages#readme","keywords":["anby","anby-platform","billing","credits","sdk"],"repository":{"type":"git","url":"git+https://github.com/bravebits-labs/anby-platform-packages.git","directory":"packages/billing"},"description":"Anby Billing SDK — debit, credit, balance queries against anby-billing-service. HMAC-signed service-to-service calls.","maintainers":[{"name":"anby-platform","email":"aie@bravebits.vn"}],"readme":"# @anby/billing\n\nTyped SDK for calling `anby-billing-service` from Anby services. Handles HMAC signing, request shape validation, idempotency derivation, and error mapping.\n\n## Install\n\n```bash\nnpm add @anby/billing @anby/platform-sdk\n```\n\n`@anby/platform-sdk` is a peer dependency — it owns the HMAC signer.\n\n## Bootstrap (once per service)\n\n```ts\nimport { configureAuth } from '@anby/platform-sdk';\nimport { configureBilling } from '@anby/billing';\n\nconfigureAuth({ hmacSecret: process.env.SVC_HMAC_SECRET });\n\nconfigureBilling({\n  baseUrl: process.env.BILLING_SERVICE_URL,     // https://billing.anby.ai\n  hmacSecret: process.env.SVC_HMAC_SECRET,      // 32+ chars, shared with billing-service\n  serviceName: 'meeting',                        // source of debits\n});\n```\n\n## Debit AC\n\n```ts\nimport { debitCredits, InsufficientCreditsError } from '@anby/billing';\n\ntry {\n  const result = await debitCredits({\n    workspaceId: meeting.workspaceId,\n    amount: 5,                                          // integer, whole AC\n    jobId: `meeting-summary:${meeting.id}`,             // business identifier, unique per service\n    sourceService: 'meeting',\n    actorUserId: currentUser.id,\n    metadata: {\n      meetingId: meeting.id,\n      aiModel: 'gpt-5.4',\n      durationMinutes: 60,\n    },\n  });\n  console.log(`AC balance: ${result.totalBalanceAfter}`);\n} catch (err) {\n  if (err instanceof InsufficientCreditsError) {\n    // show paywall / upsell CTA. err.required, err.available available\n  }\n  throw err;\n}\n```\n\nCalling `debitCredits` twice with the same `(jobId, sourceService)` returns the same `ledgerEntryId` both times — safe to retry on transient failures.\n\n## Get balance\n\n```ts\nconst balance = await getBalance(workspaceId);\n// { balanceSubscription, balanceTopup, total, cycle: { planSnapshot, periodEnd, ... } }\n```\n\n## Refund (AI failure / admin adjust)\n\n```ts\nimport { refundCredits } from '@anby/billing';\n\nawait refundCredits({\n  workspaceId,\n  refundForJobId: `meeting-summary:${meeting.id}`,\n  reason: 'AI provider timeout',\n  sourceService: 'meeting',\n});\n```\n\n## Errors\n\nAll errors extend `BillingError` with `.code`, `.status`, `.details`:\n\n| Class | HTTP | When |\n|-------|------|------|\n| `BillingConfigurationError` | — | SDK not configured or invalid config |\n| `InvalidDebitRequestError` | 400 | Zod validation fails locally or server rejects shape |\n| `InsufficientCreditsError` | 402 | Balance below amount. `.required`, `.available` available |\n| `WorkspaceNotFoundError` | 404 | No wallet for workspace |\n| `DuplicateRequestError` | 409 | Same jobId already processed (server returns prior entry in `.details`) |\n| `WalletLockedError` | 423 | Wallet frozen (admin action, fraud review) |\n| `BillingServiceUnavailableError` | 5xx/network | Treat as retryable. SDK does not auto-retry |\n\n## Idempotency\n\n- `jobId` is your **business-meaningful** identifier (e.g. `meeting-summary:<meetingId>`). One debit per `(jobId, sourceService)` globally.\n- `idempotencyKey` is the **API-level** key. SDK derives it as `sha256(jobId + sourceService)` if you don't pass one. 24h TTL server-side.\n- Pass `idempotencyKey` directly only if upstream (queue) already has a stable id. Most callers should only pass `jobId`.\n\n## Design notes\n\n- **No auto-retry**: caller decides. Billing is money-critical; silent retry could obscure balance bugs.\n- **Timeout default 10s**: tunable via `timeoutMs` in `configureBilling`.\n- **Integer AC**: fractional amounts rejected locally. See `docs/billing-system.md` for the \"round up to 1 AC\" policy rationale.\n","readmeFilename":"README.md"}