@hello-bill/node 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to `@hello-bill/node` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2026-05-16
+
+### Added
+
+- Initial pre-release surface of the HelloBill Partner API SDK.
+- `core` entry (`@hello-bill/node`): framework-agnostic
+  `createHellobillHandler` returning a handler set (`init`, `session`,
+  `loa`, `customer`, callbacks), plus `TokenManager`, `InMemoryTokenStorage`,
+  retry/idempotency helpers, and typed error classes.
+- `express` entry (`@hello-bill/node/express`): `createHellobillRouter`
+  Express 4/5 adapter (peer-dep, optional) that wires the handler set onto
+  an `express.Router`.
+- `webhook` entry (`@hello-bill/node/webhook`): `verifyWebhook` with
+  `WebhookVerificationError` and timing-safe HMAC checks; raw-body verifier
+  matching the Partner API signature header format.
+- `types` entry (`@hello-bill/node/types`): spec-derived TypeScript surface
+  for Partner API v11 (sessions, products, LOA, customers, webhooks,
+  envelopes, error shapes).
+- ESM + CJS dual build via `tsup` with per-entry `.d.ts` declarations and
+  sourcemaps. ESM-first; CJS provided for server-side consumers on older
+  bundlers.
+
+### Notes
+
+- `0.0.x` releases are pre-release and may change without notice. Promote
+  to `0.1.0` once the public surface is frozen.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Bunch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# @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
+
+```bash
+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)
+
+```ts
+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:
+
+```ts
+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
+
+```ts
+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`:
+
+```ts
+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:
+
+```ts
+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.

package/dist/express/index.d.cts

@@ -0,0 +1,34 @@
+import { C as CreateHellobillHandlerOptions } from '../index-BrfG82zs.cjs';
+import '../webhooks-DPpqf7d2.cjs';
+
+/**
+ * Express adapter for the framework-agnostic SDK core.
+ *
+ * Usage:
+ *   import { createHellobillRouter } from '@hello-bill/node/express';
+ *   app.use('/api/hellobill', createHellobillRouter({ ... }));
+ *
+ * `express` is an OPTIONAL peer dependency — it's loaded lazily via `require`
+ * so consumers that never import this adapter pay nothing.
+ */
+
+type AnyRouter = any;
+/**
+ * Creates an Express Router that mounts the HelloBill endpoints:
+ *   POST /webhooks          (optional — only when opts.webhook is provided)
+ *   POST /session
+ *   GET  /loa
+ *   POST /customers
+ *   GET  /status
+ *   GET  /products
+ *   GET  /property
+ *   POST /bank-details
+ *   GET  /bank-details
+ *   GET  /sessions          (additive — spec §3.6 + §9.2.1)
+ *   GET  /sessions/:id      (additive — spec §3.7 + §9.2.1)
+ *
+ * Mount it under a path of your choice, e.g. `/api/hellobill`.
+ */
+declare function createHellobillRouter(opts: CreateHellobillHandlerOptions): AnyRouter;
+
+export { createHellobillRouter };

package/dist/express/index.d.ts

@@ -0,0 +1,34 @@
+import { C as CreateHellobillHandlerOptions } from '../index-EXetQn1f.js';
+import '../webhooks-DPpqf7d2.js';
+
+/**
+ * Express adapter for the framework-agnostic SDK core.
+ *
+ * Usage:
+ *   import { createHellobillRouter } from '@hello-bill/node/express';
+ *   app.use('/api/hellobill', createHellobillRouter({ ... }));
+ *
+ * `express` is an OPTIONAL peer dependency — it's loaded lazily via `require`
+ * so consumers that never import this adapter pay nothing.
+ */
+
+type AnyRouter = any;
+/**
+ * Creates an Express Router that mounts the HelloBill endpoints:
+ *   POST /webhooks          (optional — only when opts.webhook is provided)
+ *   POST /session
+ *   GET  /loa
+ *   POST /customers
+ *   GET  /status
+ *   GET  /products
+ *   GET  /property
+ *   POST /bank-details
+ *   GET  /bank-details
+ *   GET  /sessions          (additive — spec §3.6 + §9.2.1)
+ *   GET  /sessions/:id      (additive — spec §3.7 + §9.2.1)
+ *
+ * Mount it under a path of your choice, e.g. `/api/hellobill`.
+ */
+declare function createHellobillRouter(opts: CreateHellobillHandlerOptions): AnyRouter;
+
+export { createHellobillRouter };