@billkit-eu/sdk 0.1.0

package/src/retry.ts

@@ -0,0 +1,61 @@
+/**
+ * Retry policy for transient failures.
+ *
+ * Retries 5xx + network errors with jittered exponential backoff.
+ * 4xx (including 409 Idempotency-Key conflicts) are caller-fault and
+ * never retried. The SDK auto-generates an `Idempotency-Key` for every
+ * mutating call so retrying a 5xx never double-charges.
+ */
+
+export interface RetryPolicy {
+  readonly maxAttempts: number;
+  readonly initialBackoffMs: number;
+  readonly backoffMultiplier: number;
+  readonly maxBackoffMs: number;
+  readonly maxRetryAfterMs?: number;
+  readonly jitter: number;
+}
+
+export const DEFAULT_RETRY_POLICY: RetryPolicy = {
+  maxAttempts: 4,
+  initialBackoffMs: 500,
+  backoffMultiplier: 2.0,
+  maxBackoffMs: 8000,
+  maxRetryAfterMs: 30_000,
+  jitter: 0.25,
+};
+
+/**
+ * Backoff before attempt `attempt` (1-indexed: attempt 2 is the first
+ * retry). Caller never asks for attempt=1.
+ */
+export function backoffForMs(attempt: number, policy: RetryPolicy): number {
+  const base = policy.initialBackoffMs * policy.backoffMultiplier ** (attempt - 2);
+  const capped = Math.min(base, policy.maxBackoffMs);
+  const jitterRange = capped * policy.jitter;
+  const jittered = capped + (Math.random() * 2 - 1) * jitterRange;
+  return Math.max(0, jittered);
+}
+
+export function shouldRetry(
+  status: number | null,
+  attempt: number,
+  policy: RetryPolicy,
+  retryAfterMs?: number,
+): boolean {
+  if (attempt >= policy.maxAttempts) return false;
+  if (status === null) return true; // network error
+  if (status === 429) {
+    // 429 is retried only when the server supplies a short, parseable
+    // Retry-After value; otherwise we surface the exception so the
+    // caller can decide. ``maxRetryAfterMs`` may be left ``undefined``
+    // to allow any Retry-After value within budget.
+    if (retryAfterMs === undefined || retryAfterMs < 0) return false;
+    return policy.maxRetryAfterMs === undefined || retryAfterMs <= policy.maxRetryAfterMs;
+  }
+  return status >= 500;
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/transport.ts

@@ -0,0 +1,300 @@
+/**
+ * Fetch-backed transport with retry + error mapping.
+ *
+ * Uses the runtime's native `fetch` (Node 20+, Bun, Deno, Cloudflare
+ * Workers, browsers). The transport is the only place that touches HTTP;
+ * everything else in the SDK speaks to a `Transport` interface so a
+ * caller can inject a mock or replay layer for testing.
+ */
+
+import { APIConnectionError, errorFromResponse, type BillKitError } from "./errors.js";
+import { NOOP_LOGGER, type BillKitLogger } from "./logging.js";
+import {
+  DEFAULT_RETRY_POLICY,
+  type RetryPolicy,
+  backoffForMs,
+  shouldRetry,
+  sleep,
+} from "./retry.js";
+import { VERSION } from "./version.js";
+
+export const DEFAULT_BASE_URL = "https://api.billkit.eu";
+export const DEFAULT_TIMEOUT_MS = 30_000;
+
+export type QueryValue = string | number | boolean | null | undefined;
+
+export interface RequestOptions {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  path: string;
+  // Loosened from ``Record<string, QueryValue>`` so resource methods
+  // can pass a structurally-typed ``ListParams``-style object without
+  // a cast, since TS demands an index signature otherwise.
+  query?: { readonly [key: string]: QueryValue };
+  body?: Record<string, unknown> | undefined;
+  idempotencyKey?: string | undefined;
+  extraHeaders?: Record<string, string>;
+}
+
+export interface TransportConfig {
+  apiKey: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  retryPolicy?: RetryPolicy;
+  fetch?: typeof fetch;
+  /**
+   * Where to send the SDK's request/retry lifecycle. Omitted (the
+   * default) means a no-op: the SDK stays silent and never picks a
+   * destination for you. `console` works as-is; see
+   * {@link BillKitLogger}. Secrets, bodies and query strings are never
+   * passed to it.
+   */
+  logger?: BillKitLogger;
+}
+
+function userAgent(): string {
+  return `billkit-node/${VERSION}`;
+}
+
+function autoIdempotencyKey(method: string, supplied?: string): string | undefined {
+  if (method === "GET") return undefined;
+  if (supplied !== undefined) return supplied;
+  const uuid = globalThis.crypto?.randomUUID?.();
+  if (uuid === undefined) {
+    // Deliberately fail loudly rather than fall back to
+    // `Date.now()-Math.random()`. This key is what makes a retried
+    // mutating call safe: two processes that generate the *same* key send
+    // different requests the server treats as replays of each other, so it
+    // returns the first call's response for the second, silently wrong on
+    // a charge. `Math.random()` is not collision-resistant and is seeded
+    // per-process, so a fleet starting together is exactly the case where
+    // it collides. Every runtime this SDK supports (Node 20+, Bun, Deno,
+    // Workers, modern browsers) has `crypto.randomUUID`.
+    throw new Error(
+      "BillKit: crypto.randomUUID() is unavailable, so a safe Idempotency-Key " +
+        "cannot be generated. Use Node 20+, Bun, Deno, or Cloudflare Workers, " +
+        "or pass your own `idempotencyKey` on this call.",
+    );
+  }
+  return `sdk-${uuid}`;
+}
+
+/**
+ * The URL with the **query string stripped**, for logging only.
+ *
+ * Never log the value {@link buildUrl} returns: list filters routinely
+ * carry `?email=ada@example.com`, and copying customer PII into the
+ * caller's log sink is exactly what this SDK must not do. Keeping the
+ * two builders separate makes that a visible choice rather than an
+ * accident waiting for someone to "simplify" it.
+ */
+function logSafeUrl(baseUrl: string, path: string): string {
+  const normalised = path.startsWith("/") ? path : `/${path}`;
+  return baseUrl.replace(/\/$/, "") + normalised;
+}
+
+function buildUrl(baseUrl: string, path: string, query: RequestOptions["query"]): string {
+  const normalised = path.startsWith("/") ? path : `/${path}`;
+  const url = new URL(baseUrl.replace(/\/$/, "") + normalised);
+  if (query) {
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== null && v !== undefined) {
+        url.searchParams.set(k, String(v));
+      }
+    }
+  }
+  return url.toString();
+}
+
+function buildHeaders(
+  apiKey: string,
+  hasBody: boolean,
+  idempotencyKey: string | undefined,
+  extra: Record<string, string> | undefined,
+): Headers {
+  const headers = new Headers({
+    Authorization: `Bearer ${apiKey}`,
+    "User-Agent": userAgent(),
+    Accept: "application/json",
+  });
+  if (hasBody) headers.set("Content-Type", "application/json");
+  if (idempotencyKey) headers.set("Idempotency-Key", idempotencyKey);
+  if (extra) {
+    for (const [k, v] of Object.entries(extra)) {
+      headers.set(k, v);
+    }
+  }
+  return headers;
+}
+
+async function parseJson(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function parseRetryAfterMs(header: string | null): number | undefined {
+  if (!header) return undefined;
+  const n = Number.parseFloat(header);
+  if (Number.isFinite(n) && n >= 0) return n * 1000;
+
+  const retryAt = Date.parse(header);
+  if (Number.isNaN(retryAt)) return undefined;
+  return Math.max(0, retryAt - Date.now());
+}
+
+function retryDelayMs(
+  status: number | null,
+  attempt: number,
+  policy: RetryPolicy,
+  retryAfterMs?: number,
+): number {
+  if (status === 429 && retryAfterMs !== undefined) return retryAfterMs;
+  return backoffForMs(attempt + 1, policy);
+}
+
+/**
+ * Map a thrown fetch/read error to an {@link APIConnectionError}.
+ *
+ * ``AbortSignal.timeout`` aborts with a ``TimeoutError`` (some runtimes
+ * surface ``AbortError``); we translate that into an explicit, greppable
+ * timeout message instead of the runtime's terse default.
+ */
+function connectionError(err: unknown, timeoutMs: number): APIConnectionError {
+  const e = err as { name?: string; message?: string } | undefined;
+  if (e?.name === "TimeoutError" || e?.name === "AbortError") {
+    return new APIConnectionError(`BillKit request timed out after ${timeoutMs}ms.`);
+  }
+  return new APIConnectionError(e?.message ?? "Network request failed.");
+}
+
+export class Transport {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly timeoutMs: number;
+  private readonly retryPolicy: RetryPolicy;
+  private readonly fetchFn: typeof fetch;
+  private readonly logger: BillKitLogger;
+
+  constructor(config: TransportConfig) {
+    if (!config.apiKey) {
+      throw new Error("BillKit: an API key is required (config.apiKey or BILLKIT_API_KEY env).");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.retryPolicy = config.retryPolicy ?? DEFAULT_RETRY_POLICY;
+    this.logger = config.logger ?? NOOP_LOGGER;
+    const fetchFn = config.fetch ?? globalThis.fetch;
+    if (!fetchFn) {
+      throw new Error(
+        "BillKit: no global fetch implementation found. Use Node 20+, Bun, Deno, " +
+          "Cloudflare Workers, or pass { fetch } in the client options.",
+      );
+    }
+    this.fetchFn = fetchFn.bind(globalThis);
+  }
+
+  async request<T = unknown>(options: RequestOptions): Promise<T> {
+    const idempotencyKey = autoIdempotencyKey(options.method, options.idempotencyKey);
+    const url = buildUrl(this.baseUrl, options.path, options.query);
+    const headers = buildHeaders(
+      this.apiKey,
+      options.body !== undefined,
+      idempotencyKey,
+      options.extraHeaders,
+    );
+    const body = options.body !== undefined ? JSON.stringify(options.body) : undefined;
+    // Query-free; see `logSafeUrl`. Never swap this for `url`.
+    const loggedUrl = logSafeUrl(this.baseUrl, options.path);
+
+    let lastError: BillKitError | null = null;
+    for (let attempt = 1; attempt <= this.retryPolicy.maxAttempts; attempt++) {
+      this.logger.debug("BillKit request", {
+        method: options.method,
+        url: loggedUrl,
+        attempt,
+        maxAttempts: this.retryPolicy.maxAttempts,
+      });
+      const startedAt = Date.now();
+      let response: Response;
+      let parsedBody: unknown;
+      try {
+        // ``body`` is only spread when present so a GET request goes
+        // out without a body field. Some hosts (Cloudflare Workers'
+        // outgoing fetch) refuse ``body: null`` on GET; omitting it
+        // is the portable shape.
+        //
+        // ``AbortSignal.timeout`` stays armed through the *body read*
+        // below, not just until the headers arrive, so a server that
+        // streams headers and then stalls the body is still bounded by
+        // ``timeoutMs`` instead of hanging forever. A fresh signal is
+        // created per attempt because a timed-out signal can't be reused.
+        const init: RequestInit = {
+          method: options.method,
+          headers,
+          signal: AbortSignal.timeout(this.timeoutMs),
+        };
+        if (body !== undefined) init.body = body;
+        response = await this.fetchFn(url, init);
+        parsedBody = await parseJson(response);
+      } catch (err) {
+        lastError = connectionError(err, this.timeoutMs);
+        if (!shouldRetry(null, attempt, this.retryPolicy)) throw lastError;
+        const delayMs = retryDelayMs(null, attempt, this.retryPolicy);
+        this.logger.warn("BillKit retrying", {
+          method: options.method,
+          url: loggedUrl,
+          reason: (err as { name?: string } | undefined)?.name ?? "network error",
+          attempt,
+          delayMs,
+        });
+        await sleep(delayMs);
+        continue;
+      }
+
+      const requestId =
+        response.headers.get("x-request-id") ?? response.headers.get("request-id") ?? undefined;
+      this.logger.debug("BillKit response", {
+        method: options.method,
+        url: loggedUrl,
+        status: response.status,
+        durationMs: Date.now() - startedAt,
+        requestId: requestId ?? null,
+      });
+
+      if (response.ok) {
+        return (parsedBody ?? undefined) as T;
+      }
+
+      const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
+      const error = errorFromResponse({
+        status: response.status,
+        body: parsedBody,
+        requestId,
+        retryAfter: retryAfterMs === undefined ? undefined : retryAfterMs / 1000,
+      });
+
+      if (!shouldRetry(response.status, attempt, this.retryPolicy, retryAfterMs)) {
+        throw error;
+      }
+      lastError = error;
+      const delayMs = retryDelayMs(response.status, attempt, this.retryPolicy, retryAfterMs);
+      this.logger.warn("BillKit retrying", {
+        method: options.method,
+        url: loggedUrl,
+        reason: `HTTP ${response.status}`,
+        attempt,
+        delayMs,
+      });
+      await sleep(delayMs);
+    }
+
+    // Loop exhausted; surface the last seen error.
+    if (lastError) throw lastError;
+    throw new APIConnectionError("Retry budget exhausted with no recorded error.");
+  }
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const VERSION = "0.1.0";

package/src/webhooks.ts

@@ -0,0 +1,171 @@
+/**
+ * Verify `BillKit-Signature: t=<unix>,v1=<hex>` headers.
+ *
+ * Works in Node 20+, Bun, Deno, Cloudflare Workers and the browser:
+ * we use the Web Crypto API (`globalThis.crypto.subtle`) which is
+ * available in all modern runtimes. The verifier:
+ *
+ * 1. Parses the header (rejects malformed shapes). A header may carry
+ *    more than one `v1=` value, because the server emits both the old and new
+ *    signature during a signing-secret rotation, and verification passes
+ *    if any of them matches.
+ * 2. Confirms the timestamp is within `toleranceSeconds` of now
+ *    (replay protection).
+ * 3. Computes the expected HMAC and compares against each candidate in
+ *    constant time.
+ */
+
+export const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+
+export class WebhookVerificationError extends Error {
+  override name = "WebhookVerificationError";
+  constructor(message: string) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export interface VerifyWebhookOptions {
+  payload: string | Uint8Array;
+  signatureHeader: string | null | undefined;
+  secret: string;
+  toleranceSeconds?: number;
+  nowMs?: number; // injectable for tests
+}
+
+const textEncoder = new TextEncoder();
+const V1_HEX_RE = /^[0-9a-fA-F]{64}$/;
+
+function toBytes(payload: string | Uint8Array): Uint8Array {
+  return typeof payload === "string" ? textEncoder.encode(payload) : payload;
+}
+
+function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+  }
+  return diff === 0;
+}
+
+function hexToBytes(hex: string): Uint8Array | null {
+  if (!V1_HEX_RE.test(hex)) return null;
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    const byte = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    if (Number.isNaN(byte)) return null;
+    out[i] = byte;
+  }
+  return out;
+}
+
+function parseSignatureHeader(header: string): { ts: number; v1List: string[] } {
+  let tsRaw: string | undefined;
+  const v1List: string[] = [];
+  for (const chunk of header.split(",")) {
+    const idx = chunk.indexOf("=");
+    if (idx < 0) continue;
+    const key = chunk.slice(0, idx).trim();
+    const value = chunk.slice(idx + 1).trim();
+    // A rotation can carry more than one ``v1=`` (old + new secret);
+    // collect them all and let the verifier accept any match.
+    if (key === "t") tsRaw = value;
+    else if (key === "v1") v1List.push(value);
+  }
+  if (!tsRaw || v1List.length === 0) {
+    throw new WebhookVerificationError(`Malformed BillKit-Signature header: ${header}`);
+  }
+  const ts = Number.parseInt(tsRaw, 10);
+  if (Number.isNaN(ts) || ts <= 0) {
+    throw new WebhookVerificationError(`Malformed timestamp in BillKit-Signature: ${tsRaw}`);
+  }
+  return { ts, v1List };
+}
+
+function toArrayBuffer(view: Uint8Array): ArrayBuffer {
+  // ``Uint8Array.buffer`` is ``ArrayBufferLike`` (could be
+  // ``SharedArrayBuffer``); SubtleCrypto wants a concrete
+  // ``ArrayBuffer``. We copy into a fresh ArrayBuffer to bridge.
+  const out = new ArrayBuffer(view.byteLength);
+  new Uint8Array(out).set(view);
+  return out;
+}
+
+async function computeHmac(secret: string, signed: Uint8Array): Promise<Uint8Array> {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new WebhookVerificationError(
+      "No SubtleCrypto available. The BillKit SDK requires Node 20+, Bun, Deno, " +
+        "Cloudflare Workers, or any runtime that exposes globalThis.crypto.subtle.",
+    );
+  }
+  const key = await subtle.importKey(
+    "raw",
+    toArrayBuffer(textEncoder.encode(secret)),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await subtle.sign("HMAC", key, toArrayBuffer(signed));
+  return new Uint8Array(signature);
+}
+
+export async function verifyWebhookSignature<T = unknown>(
+  options: VerifyWebhookOptions,
+): Promise<T> {
+  const {
+    payload,
+    signatureHeader,
+    secret,
+    toleranceSeconds = DEFAULT_WEBHOOK_TOLERANCE_SECONDS,
+    nowMs = Date.now(),
+  } = options;
+
+  if (signatureHeader === null || signatureHeader === undefined) {
+    throw new WebhookVerificationError("Missing BillKit-Signature header.");
+  }
+
+  const { ts, v1List } = parseSignatureHeader(signatureHeader);
+  if (Math.abs(nowMs / 1000 - ts) > toleranceSeconds) {
+    throw new WebhookVerificationError(
+      `Signature timestamp outside ±${toleranceSeconds}s tolerance.`,
+    );
+  }
+
+  const payloadBytes = toBytes(payload);
+  const signed = new Uint8Array(payloadBytes.length + textEncoder.encode(`${ts}.`).length);
+  const prefix = textEncoder.encode(`${ts}.`);
+  signed.set(prefix, 0);
+  signed.set(payloadBytes, prefix.length);
+
+  const expected = await computeHmac(secret, signed);
+  // Compare against every candidate; don't break on the first match so
+  // the loop's timing doesn't reveal which signature matched.
+  let sawValidHex = false;
+  let matched = false;
+  for (const v1 of v1List) {
+    const received = hexToBytes(v1);
+    if (!received) continue;
+    sawValidHex = true;
+    if (constantTimeEqual(expected, received)) matched = true;
+  }
+  if (!sawValidHex) {
+    throw new WebhookVerificationError(
+      `Malformed v1 hex in BillKit-Signature: ${v1List.join(",")}`,
+    );
+  }
+  if (!matched) {
+    throw new WebhookVerificationError("Signature mismatch.");
+  }
+
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+  const text = decoder.decode(payloadBytes);
+  try {
+    return JSON.parse(text) as T;
+  } catch (err) {
+    throw new WebhookVerificationError(
+      `Webhook body is not valid JSON: ${(err as Error).message}`,
+    );
+  }
+}