@anby/billing

Typed SDK for calling anby-billing-service from Anby services. Handles HMAC signing, request shape validation, idempotency derivation, and error mapping.

Install

npm add @anby/billing @anby/platform-sdk

@anby/platform-sdk is a peer dependency — it owns the HMAC signer.

Bootstrap (once per service)

import { configureAuth } from '@anby/platform-sdk';
import { configureBilling } from '@anby/billing';

configureAuth({ hmacSecret: process.env.SVC_HMAC_SECRET });

configureBilling({
  baseUrl: process.env.BILLING_SERVICE_URL,     // https://billing.anby.ai
  hmacSecret: process.env.SVC_HMAC_SECRET,      // 32+ chars, shared with billing-service
  serviceName: 'meeting',                        // source of debits
});

Debit AC

import { debitCredits, InsufficientCreditsError } from '@anby/billing';

try {
  const result = await debitCredits({
    workspaceId: meeting.workspaceId,
    amount: 5,                                          // integer, whole AC
    jobId: `meeting-summary:${meeting.id}`,             // business identifier, unique per service
    sourceService: 'meeting',
    actorUserId: currentUser.id,
    metadata: {
      meetingId: meeting.id,
      aiModel: 'gpt-5.4',
      durationMinutes: 60,
    },
  });
  console.log(`AC balance: ${result.totalBalanceAfter}`);
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    // show paywall / upsell CTA. err.required, err.available available
  }
  throw err;
}

Calling debitCredits twice with the same (jobId, sourceService) returns the same ledgerEntryId both times — safe to retry on transient failures.

Get balance

const balance = await getBalance(workspaceId);
// { balanceSubscription, balanceTopup, total, cycle: { planSnapshot, periodEnd, ... } }

Refund (AI failure / admin adjust)

import { refundCredits } from '@anby/billing';

await refundCredits({
  workspaceId,
  refundForJobId: `meeting-summary:${meeting.id}`,
  reason: 'AI provider timeout',
  sourceService: 'meeting',
});

Errors

All errors extend BillingError with .code, .status, .details:

| Class | HTTP | When | |-------|------|------| | BillingConfigurationError | — | SDK not configured or invalid config | | InvalidDebitRequestError | 400 | Zod validation fails locally or server rejects shape | | InsufficientCreditsError | 402 | Balance below amount. .required, .available available | | WorkspaceNotFoundError | 404 | No wallet for workspace | | DuplicateRequestError | 409 | Same jobId already processed (server returns prior entry in .details) | | WalletLockedError | 423 | Wallet frozen (admin action, fraud review) | | BillingServiceUnavailableError | 5xx/network | Treat as retryable. SDK does not auto-retry |

Idempotency

• jobId is your business-meaningful identifier (e.g. meeting-summary:<meetingId>). One debit per (jobId, sourceService) globally.
• idempotencyKey is the API-level key. SDK derives it as sha256(jobId + sourceService) if you don't pass one. 24h TTL server-side.
• Pass idempotencyKey directly only if upstream (queue) already has a stable id. Most callers should only pass jobId.

Design notes

• No auto-retry: caller decides. Billing is money-critical; silent retry could obscure balance bugs.
• Timeout default 10s: tunable via timeoutMs in configureBilling.
• Integer AC: fractional amounts rejected locally. See docs/billing-system.md for the "round up to 1 AC" policy rationale.