@hello-bill/node

Server-side SDK for the HelloBill Partner API (Revision 1.13) (api_version 2026-05-10). Framework-agnostic core with an Express adapter; ships a webhook verifier and the spec-derived TypeScript types.

• ESM only, bare TypeScript source — no runtime dependencies.
• Subpath imports: @hello-bill/node/express, @hello-bill/node/webhook, @hello-bill/node/types.
• Auto OAuth token caching, single-flight refresh, idempotency, retry with Retry-After, per-attempt timeout.

Install

npm install @hello-bill/node
# or
bun add @hello-bill/node

The package is currently private: true and consumed via the monorepo workspace. See Pre-publish checklist below.

Quick start (Express)

import express from 'express';
import { createHellobillRouter } from '@hello-bill/node/express';

const app = express();

app.use('/api/hellobill', createHellobillRouter({
  clientId: process.env.HELLOBILL_CLIENT_ID!,
  clientSecret: process.env.HELLOBILL_CLIENT_SECRET!,
  apiBaseUrl: process.env.HELLOBILL_API_BASE_URL!,
  buildSessionPayload: async (req) => {
    // Map whatever your host page posted → canonical snake_case SessionPayload.
    const body = req.body as { firstName: string; lastName: string; email: string };
    return {
      customer: {
        first_name: body.firstName,
        last_name: body.lastName,
        email: body.email,
      },
      addresses: { current: { /* ... */ } },
      move: { in: { move_in_date: '2026-06-01' } },
      consent: { data_sharing_accepted: true },
    };
  },
}));

app.listen(3000);

The router applies express.json({ limit: '1mb' }) internally — do not wrap it with another body parser.

Endpoints mounted

createHellobillRouter(opts) mounts these paths under the prefix you choose:

| Method | Path | Upstream | |--------|--------------|-----------------------------------------------------| | POST | /session | POST /partner/sessions | | GET | /products | GET /partner/sessions/:session_id/products | | GET | /loa | GET /partner/sessions/:session_id/loa | | POST | /customers | POST /partner/sessions/:session_id/customers | | GET | /status | GET /partner/customers/:customer_id/status |

/products, /loa, /customers and /status require a session_token Bearer (issued from POST /session). The SDK decodes it without verification to extract session_id and forwards the upstream call with a fresh OAuth access token.

Framework-agnostic core

Partners on Hono / Koa / Fastify / Nitro / raw Node can skip the Express adapter and use the core directly:

import { createHellobillHandler } from '@hello-bill/node';

const handlers = createHellobillHandler({
  clientId: '…', clientSecret: '…', apiBaseUrl: '…',
  buildSessionPayload: async (req) => ({ /* … */ }),
});

// Each handler takes the SDK's portable HellobillRequest / HellobillResponse.
// You write the ~15-line adapter that shapes your framework's req/res into them.
await handlers.session(req, res);

Webhook verification

import express from 'express';
import { verifyWebhook, WebhookVerificationError } from '@hello-bill/node/webhook';

app.post(
  '/api/hellobill/webhooks',
  express.raw({ type: 'application/json' }), // ← raw bytes, not parsed JSON
  (req, res) => {
    try {
      const event = verifyWebhook(
        req.body,
        req.header('x-hellobill-signature')!,
        process.env.HELLOBILL_WEBHOOK_SECRET!,
        { tolerance: 300, supportedVersions: ['v1'] },
      );
      // event is typed as WebhookEvent — switch on event.type
      res.status(204).end();
    } catch (err) {
      if (err instanceof WebhookVerificationError) return res.status(400).end();
      throw err;
    }
  },
);

• Algorithm: HMAC-SHA256 over ${unix_timestamp}.${raw_body} (Stripe-style).
• Header format: t=<unix>,v1=<hex> (and optionally v2=<hex> during rotation).
• Replay window: 300s by default (tolerance).
• Key rotation: pass supportedVersions: ['v1', 'v2'] and accept either; cut over once v2 is verified end-to-end.
• Constant-time compare: implemented via crypto.timingSafeEqual.

Never parse and re-stringify the body before verification — the HMAC is computed over the exact bytes the server sent.

Token management

• Automatic client_credentials OAuth grant against POST /auth/partner/token.
• Cached in-process by default; refreshed at expires_in − 30s.
• Single-flight: parallel API calls during a refresh share one upstream request.
• Pluggable via tokenStorage:

import type { TokenStorage } from '@hello-bill/node';

const redisStorage: TokenStorage = {
  async get() { /* return { accessToken, expiresAt } | null */ },
  async set(tok) { /* persist */ },
};

createHellobillRouter({ /* …, */ tokenStorage: redisStorage });

Retry policy

Applied to every upstream call:

• Retried statuses: 429, 500, 502, 503, 504, plus auth.token_expired (refreshes the token then retries once).
• Backoff: exponential with jitter; honours Retry-After (seconds or HTTP date).
• Attempts: up to 5 per call.
• Timeout: per-attempt, default 30 000 ms; override with upstreamTimeoutMs.
• Network failures: a hung / refused / aborted fetch becomes a clean internal.error envelope (502/504 depending on failure kind).

Idempotency

• The SDK auto-generates a UUID v4 Idempotency-Key for every POST.
• Override with idempotencyKeyFactory: () => string.

Gotcha: the Partner API caches the first response keyed by Idempotency-Key and ignores the body on subsequent requests with the same key. If you reuse the same key for two semantically-different POSTs (e.g. two different customer payloads), you get the first response back — not an error. Partners must mint a distinct key per logical operation.

Types

The full spec surface is re-exported under a stable subpath:

import type {
  SessionPayload,
  SessionResponse,
  ProductsResponse,
  LoaResponse,
  CustomersPayload,
  CustomersResponse,
  StatusResponse,
  WebhookEvent,
} from '@hello-bill/node/types';

Coverage

Measured with bun run test:coverage (vitest + v8). 69 / 69 tests passing.

| Area | Statements | Branches | Functions | Lines | |-----------|------------|----------|-----------|--------| | All | 90.90 % | 84.95 % | 96.49 % | 94.70 % | | core/ | 91.63 % | 85.02 % | 97.43 % | 95.79 % | | express/| 83.33 % | n/a | 90.90 % | 86.20 % | | webhook/| 90.90 % | 89.18 % | 100.00 % | 94.11 % |

Uncovered lines are exhaustively defensive branches (e.g. unreachable else in error envelope shaping, top-level Express error middleware that fires only on developer mis-wiring).

Pre-publish checklist

Before the first npm publish:

• [ ] Remove "private": true from package.json.
• [ ] Confirm the "files" field (currently ["src", "README.md"]) — add a dist/ if you ship compiled output.
• [ ] Add a build step (tsup or tsc) and point "types" at the emitted .d.ts.
• [ ] Verify all "exports" subpaths resolve post-build (., /express, /webhook, /types).
• [ ] Choose a licence + add LICENSE file.
• [ ] Add "repository" and "homepage" fields.
• [ ] Seed CHANGELOG.md (recommend Keep a Changelog).
• [ ] Run npm pack --dry-run and review the tarball contents.

License

TBD.