@tiempo/sdk 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Double-Tap Development Ltd
+
+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

@@ -1,3 +1,270 @@
-# Temporary Holding Version
+# @tiempo/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript client for the Tiempo scheduling API. Node 18+, no runtime dependencies
+(uses the global `fetch` and Web Crypto). Ships ES modules and CommonJS, with types.
+
+The types are generated from Tiempo's OpenAPI spec and match the API version the SDK
+pins (`API_VERSION`).
+
+## Install
+
+```bash
+npm install @tiempo/sdk
+```
+
+This package was `@doubletap/tiempo` until 0.1.0. To move, change the dependency and your imports;
+nothing else changes.
+
+```ts
+import { Tiempo } from '@tiempo/sdk';             // ESM
+const { Tiempo } = require('@tiempo/sdk');         // CommonJS
+```
+
+## Quick start: hold and confirm a booking
+
+```ts
+import { Tiempo } from '@tiempo/sdk';
+
+// A test key (tpt_…) while you build. Calls https://api.tiempo.one unless you give a baseUrl.
+const tiempo = new Tiempo(process.env.TIEMPO_API_KEY!);
+
+// One account per business (platform-level call).
+const account = await tiempo.accounts.create({ name: 'Soho Hair', timezone: 'Europe/London' });
+const soho = tiempo.withAccount(account.id);
+
+const ann = await soho.resources.create({ name: 'Ann', type: 'worker' });
+await soho.schedules.create({
+  resource: ann.id,
+  effective_from: '2027-01-04',
+  weeks: [{ monday: [{ start: '09:00', end: '17:00' }] }],
+});
+
+// When can Ann do 45 minutes?
+const { slots } = await soho.availability.search({
+  from: '2027-01-04T00:00:00Z',  // a Monday
+  to: '2027-01-05T00:00:00Z',
+  interval_minutes: 15,
+  segments: [{ resources: [ann.id], duration_minutes: 45 }],
+});
+
+// Hold the first slot (status "pending" until expires_at), then confirm it.
+// A slot's segments are a booking's segments: send them back as they are.
+const hold = await soho.bookings.create({
+  segments: slots[0].segments,
+  metadata: { your_booking_id: 'b_123' },
+});
+const booking = await soho.bookings.confirm(hold.id);
+```
+
+Every method takes path ids first, then its params (the JSON body for writes, the query
+for reads), then optional per-request options:
+
+```ts
+await soho.bookings.cancel(booking.id, { reason: 'customer_request' }, { idempotencyKey: 'cancel-b_123' });
+await soho.attendees.create(sessionId, { seats: 2 });      // POST /v1/bookings/{id}/attendees
+```
+
+### Options
+
+```ts
+new Tiempo(apiKey, {
+  baseUrl: 'https://api.tiempo.one', // the default
+  account: 'acct_…',          // act for one business on every call (same as withAccount)
+  apiVersion: '2026-10-04',   // default: API_VERSION, the version these types describe
+  maxRetries: 2,              // retries after the first attempt
+  timeout: 30_000,            // per attempt, ms
+  fetch: customFetch,         // default: global fetch
+});
+```
+
+Per request (last argument): `{ account, idempotencyKey, maxRetries, timeout, signal }`.
+
+For a complete app built on this SDK (search, holds, Stripe payment, webhooks and a race test),
+see [booking-starter](https://github.com/tiempo-one/booking-starter), a Next.js barbershop you can
+fork.
+
+## Businesses (`withAccount`)
+
+A platform key acts for the platform. Business-scoped calls (resources, schedules,
+bookings, …) need a business, sent as the `Tiempo-Account` header:
+
+```ts
+const soho = tiempo.withAccount('acct_…');       // shares key and settings
+await soho.bookings.list();
+
+await tiempo.bookings.get('bkg_…', { account: 'acct_…' }); // or per request
+```
+
+Platform-level calls (`accounts`, `webhookEndpoints`, `usage`, `events.get`) don't need
+one. `events.list` lists every business's events, or one business's on a scoped client.
+
+## Pagination
+
+List methods return a `ListPromise`. Await it for one page:
+
+```ts
+const page = await soho.bookings.list({ status: 'confirmed', limit: 50 });
+page.data;      // Booking[]
+page.has_more;  // boolean
+```
+
+Or iterate it to walk every page (`starting_after` = the last item's id):
+
+```ts
+for await (const booking of soho.bookings.list({ from: '2027-01-01T00:00:00Z' })) {
+  // …
+}
+
+const first200 = await soho.bookings.list().toArray({ limit: 200 });
+```
+
+If you pass `ending_before`, iteration goes backwards (`ending_before` = each page's first
+item) and yields each page's items last to first.
+
+Filter by metadata with a map; each entry is sent as `metadata[key]=value` and all must
+match:
+
+```ts
+soho.bookings.list({ metadata: { your_booking_id: 'b_123' } });
+```
+
+## Errors
+
+Failed calls throw a subclass of `TiempoError`:
+
+| Class | When |
+|---|---|
+| `TiempoInvalidRequestError` | 400/404: bad params, unknown id |
+| `TiempoAuthenticationError` | 401: missing or bad key |
+| `TiempoPermissionError` | 403 |
+| `TiempoConflictError` | 409: slot taken, wrong state, … |
+| `TiempoIdempotencyError` | key reused with different params, or still in flight |
+| `TiempoRateLimitError` | 429 |
+| `TiempoAPIError` | 5xx |
+| `TiempoConnectionError` | network failure or timeout (no response) |
+| `TiempoSignatureVerificationError` | webhook signature didn't verify |
+
+Each carries `message`, `type`, `code`, `param`, `statusCode`, `headers`, `raw` (the parsed body)
+and `details`: any fields the error carries beyond the first four, such as `conflicts`.
+`TiempoConflictError` has typed shortcuts:
+
+| Shortcut | Set on | What it holds |
+|---|---|---|
+| `conflicts` | `booking_conflict`, `session_conflicted` | why each segment doesn't fit |
+| `occurrences` | `series_update_conflict` | the occurrences an edit couldn't place |
+| `seatsAvailable` | `seats_unavailable` | seats still free |
+
+```ts
+import { TiempoConflictError, TiempoInvalidRequestError } from '@tiempo/sdk';
+
+try {
+  await soho.bookings.create({ segments: [{ resource: ann.id, start, end }] });
+} catch (err) {
+  if (err instanceof TiempoConflictError) {
+    // the slot went: err.code === 'booking_conflict'
+    for (const c of err.conflicts) console.log(c.segment, c.reason); // 0 "capacity_exceeded"
+  } else if (err instanceof TiempoInvalidRequestError) {
+    console.log(err.param, err.message); // "name", "Invalid name: must not be blank."
+  } else {
+    throw err;
+  }
+}
+```
+
+## Idempotency and retries
+
+Every POST carries an `Idempotency-Key` (a random UUID unless you pass
+`idempotencyKey`). Retries of that call reuse the key, so a retried create can't double
+book: the server replays the stored response. Pass your own key when the retry happens
+outside the SDK (a re-run job, a retried Cloud Function):
+
+```ts
+await soho.bookings.create(params, { idempotencyKey: `booking-${yourBookingId}` });
+```
+
+A key reused with different params throws `TiempoIdempotencyError`.
+
+The SDK retries network errors, timeouts, 429, 500, 502, 503, 504 and 409
+`idempotency_key_in_use`, up to `maxRetries` (default 2) times. It never retries other
+4xx. Backoff is 0.5s × 2^n with jitter, capped at 8s; a `Retry-After` header (seconds,
+capped at 60) wins when present. `timeout` applies to each attempt. Pass `signal` to
+abort a call, including any wait between retries; the promise rejects with the signal's
+reason.
+
+## Webhooks
+
+Tiempo signs each delivery with your endpoint's `tpw_…` secret:
+`Tiempo-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`.
+`constructEvent` checks it (constant-time, any `v1` may match, timestamp within
+`tolerance`, default 300s) and returns a typed event. It needs the raw body bytes, not
+re-serialised JSON.
+
+Express:
+
+```ts
+import express from 'express';
+import { constructEvent, TiempoSignatureVerificationError } from '@tiempo/sdk';
+
+const app = express();
+
+app.post('/webhooks/tiempo', express.raw({ type: 'application/json' }), async (req, res) => {
+  let event;
+  try {
+    event = await constructEvent(req.body, req.header('Tiempo-Signature'), process.env.TIEMPO_WEBHOOK_SECRET!);
+  } catch (err) {
+    if (err instanceof TiempoSignatureVerificationError) return res.status(400).send(err.message);
+    throw err;
+  }
+
+  switch (event.type) {
+    case 'booking.confirmed':
+      // event.data.object is a Booking
+      break;
+    case 'booking.expired':
+      break;
+    case 'series.occurrence_skipped':
+      // event.data.object is a SkippedOccurrence
+      break;
+  }
+  res.sendStatus(200);
+});
+```
+
+Firebase HTTPS functions expose the raw body as `req.rawBody`; pass that. It's also
+available on a client as `tiempo.webhooks.constructEvent`.
+
+`TiempoEvent` is a union on `type`; narrowing gives `data.object` its type.
+`data.previous_attributes` holds the old values of the fields a change altered: on
+`*.updated` events; `status` on changes of state (plus `conflicted` and `conflicts` when a
+conflicted booking is cancelled, expires or finishes); `conflicted` and `conflicts` on
+`booking.conflicted` and `booking.conflict_resolved`; and on `booking.rescheduled`, always
+`segments`, `start` and `end` (compare them with `data.object` to see what moved). It's `null`
+on `*.created`. `EVENT_TYPES` lists every type; it and each type's object are
+generated from the spec's `Event` schema, so new event types arrive with `npm run generate`.
+
+Testing your handler:
+
+```ts
+import { generateTestHeader } from '@tiempo/sdk';
+
+const payload = JSON.stringify({ id: 'evt_1', object: 'event', type: 'booking.confirmed', /* … */ });
+const header = await generateTestHeader({ payload, secret: 'tpw_test' });
+await request(app).post('/webhooks/tiempo').set('Tiempo-Signature', header).type('json').send(payload);
+```
+
+## API versions
+
+Tiempo versions its API by date. The SDK sends `Tiempo-Version: API_VERSION` on every
+request, and its types describe that version, so upgrading the SDK is how you move to a
+new API version. Webhook payloads are rendered in your platform's pinned version
+(`event.api_version`); keep the platform pin and the SDK in step.
+
+```ts
+import { API_VERSION } from '@tiempo/sdk';
+```
+
+You can override `apiVersion` in the constructor, but the types won't follow.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

package/dist/cjs/client.d.ts

@@ -0,0 +1,24 @@
+import { type TiempoConfig } from './core.js';
+import { TiempoResources } from './generated/resources.js';
+import { Webhooks } from './webhooks.js';
+/**
+ * The Tiempo API client.
+ *
+ * ```ts
+ * const tiempo = new Tiempo(process.env.TIEMPO_API_KEY!); // https://api.tiempo.one unless you give a baseUrl
+ * const business = tiempo.withAccount('acct_…');
+ * const booking = await business.bookings.create({ segments: [...] });
+ * ```
+ */
+export declare class Tiempo extends TiempoResources {
+    /** Webhook signature verification. */
+    readonly webhooks: Webhooks;
+    private readonly core;
+    constructor(apiKey: string, config?: TiempoConfig);
+    /** A client that acts for one business (`acct_…`), sharing this one's key and settings. */
+    withAccount(account: string): Tiempo;
+    /** The business this client acts for, if any. */
+    get account(): string | undefined;
+    /** The `Tiempo-Version` this client sends. */
+    get apiVersion(): string;
+}

package/dist/cjs/client.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tiempo = void 0;
+const core_js_1 = require("./core.js");
+const resources_js_1 = require("./generated/resources.js");
+const webhooks_js_1 = require("./webhooks.js");
+/**
+ * The Tiempo API client.
+ *
+ * ```ts
+ * const tiempo = new Tiempo(process.env.TIEMPO_API_KEY!); // https://api.tiempo.one unless you give a baseUrl
+ * const business = tiempo.withAccount('acct_…');
+ * const booking = await business.bookings.create({ segments: [...] });
+ * ```
+ */
+class Tiempo extends resources_js_1.TiempoResources {
+    /** Webhook signature verification. */
+    webhooks;
+    core;
+    constructor(apiKey, config, resolved) {
+        const core = new core_js_1.HttpClient(resolved ?? core_js_1.HttpClient.resolve(apiKey, config));
+        super(core);
+        this.core = core;
+        this.webhooks = new webhooks_js_1.Webhooks();
+    }
+    /** A client that acts for one business (`acct_…`), sharing this one's key and settings. */
+    withAccount(account) {
+        if (typeof account !== 'string' || !account)
+            throw new TypeError('Tiempo: withAccount needs an account id (acct_…)');
+        const cfg = this.core.config;
+        return new Tiempo(cfg.apiKey, { baseUrl: cfg.baseUrl }, { ...cfg, account });
+    }
+    /** The business this client acts for, if any. */
+    get account() {
+        return this.core.config.account;
+    }
+    /** The `Tiempo-Version` this client sends. */
+    get apiVersion() {
+        return this.core.config.apiVersion;
+    }
+}
+exports.Tiempo = Tiempo;

package/dist/cjs/core.d.ts

@@ -0,0 +1,72 @@
+import { ListPromise } from './list.js';
+/** Client options. */
+export interface TiempoConfig {
+    /**
+     * Where the API lives. Defaults to {@link DEFAULT_BASE_URL}, Tiempo itself; set it for the test
+     * deployment (`https://api.uat.tiempo.one`) or a local one (`http://localhost:8080`).
+     */
+    baseUrl?: string;
+    /**
+     * The `Tiempo-Version` to send. Defaults to {@link API_VERSION}, the version
+     * this SDK's types describe; change it only if you know the shapes match.
+     */
+    apiVersion?: string;
+    /** Act for this business (`acct_…`) on every request: sends `Tiempo-Account`. */
+    account?: string;
+    /** Retries after the first attempt for retryable failures. Default 2. */
+    maxRetries?: number;
+    /** Per-attempt timeout in milliseconds. Default 30000. */
+    timeout?: number;
+    /** A `fetch` implementation. Defaults to the global one. */
+    fetch?: typeof fetch;
+}
+/** Per-request options; the last argument of every method. */
+export interface RequestOptions {
+    /** Act for this business (`acct_…`), overriding the client's account. */
+    account?: string;
+    /** Idempotency key for a POST. Default: a fresh UUID per call, reused across its retries. */
+    idempotencyKey?: string;
+    /** Overrides the client's `maxRetries` for this call. */
+    maxRetries?: number;
+    /** Overrides the client's per-attempt `timeout` (ms) for this call. */
+    timeout?: number;
+    /** Aborts the call (including any pending retry). The promise rejects with the signal's reason. */
+    signal?: AbortSignal;
+}
+/** An HTTP call, as generated resource methods describe it. */
+export interface RequestSpec {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    query?: object | undefined;
+    body?: unknown;
+    options?: RequestOptions | undefined;
+    /** A POST that only reads (availability search): sent without an Idempotency-Key. */
+    readOnly?: boolean;
+}
+/** What generated resource classes call. */
+export interface Core {
+    request<T>(spec: RequestSpec): Promise<T>;
+    list<T>(spec: RequestSpec, paginates: boolean): ListPromise<T>;
+}
+export interface ResolvedConfig {
+    apiKey: string;
+    baseUrl: string;
+    apiVersion: string;
+    account: string | undefined;
+    maxRetries: number;
+    timeout: number;
+    fetch: typeof fetch | undefined;
+}
+/** Tiempo's API, where the SDK points unless `baseUrl` says otherwise. */
+export declare const DEFAULT_BASE_URL = "https://api.tiempo.one";
+/** Backoff before retry `attempt` (0-based): 0.5s × 2^n, capped at 8s, jittered to 50–100%. */
+export declare function backoffMs(attempt: number, random?: () => number): number;
+/** Parses `Retry-After` (seconds or an HTTP date) into ms; undefined if absent or unparseable. */
+export declare function retryAfterMs(header: string | null | undefined, now?: number): number | undefined;
+export declare class HttpClient implements Core {
+    readonly config: ResolvedConfig;
+    constructor(config: ResolvedConfig);
+    static resolve(apiKey: string, config: TiempoConfig | undefined): ResolvedConfig;
+    list<T>(spec: RequestSpec, paginates: boolean): ListPromise<T>;
+    request<T>(spec: RequestSpec): Promise<T>;
+}

package/dist/cjs/core.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = exports.DEFAULT_BASE_URL = void 0;
+exports.backoffMs = backoffMs;
+exports.retryAfterMs = retryAfterMs;
+const crypto_js_1 = require("./crypto.js");
+const errors_js_1 = require("./errors.js");
+const meta_js_1 = require("./generated/meta.js");
+const list_js_1 = require("./list.js");
+const query_js_1 = require("./query.js");
+/** Tiempo's API, where the SDK points unless `baseUrl` says otherwise. */
+exports.DEFAULT_BASE_URL = 'https://api.tiempo.one';
+const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
+const MAX_RETRY_AFTER_SECONDS = 60;
+/** Backoff before retry `attempt` (0-based): 0.5s × 2^n, capped at 8s, jittered to 50–100%. */
+function backoffMs(attempt, random = Math.random) {
+    const base = Math.min(8000, 500 * 2 ** attempt);
+    return Math.round(base * (0.5 + random() * 0.5));
+}
+/** Parses `Retry-After` (seconds or an HTTP date) into ms; undefined if absent or unparseable. */
+function retryAfterMs(header, now = Date.now()) {
+    if (!header)
+        return undefined;
+    const trimmed = header.trim();
+    let seconds;
+    if (/^\d+(\.\d+)?$/.test(trimmed)) {
+        seconds = Number(trimmed);
+    }
+    else {
+        const at = Date.parse(trimmed);
+        if (Number.isNaN(at))
+            return undefined;
+        seconds = Math.max(0, (at - now) / 1000);
+    }
+    return Math.round(Math.min(seconds, MAX_RETRY_AFTER_SECONDS) * 1000);
+}
+function headersToRecord(headers) {
+    const out = {};
+    headers.forEach((value, key) => {
+        out[key.toLowerCase()] = value;
+    });
+    return out;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+const isBrowser = typeof globalThis.window !== 'undefined';
+class HttpClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    static resolve(apiKey, config) {
+        if (typeof apiKey !== 'string' || apiKey.trim() === '') {
+            throw new TypeError('Tiempo: an API key is required, e.g. new Tiempo(process.env.TIEMPO_API_KEY)');
+        }
+        const baseUrl = config?.baseUrl ?? exports.DEFAULT_BASE_URL;
+        if (typeof baseUrl !== 'string' || !/^https?:\/\//.test(baseUrl)) {
+            throw new TypeError("Tiempo: `baseUrl` must be an http(s) URL, e.g. new Tiempo(key, { baseUrl: 'http://localhost:8080' })");
+        }
+        return {
+            apiKey,
+            baseUrl: baseUrl.replace(/\/+$/, '').replace(/\/v1$/, ''),
+            apiVersion: config?.apiVersion ?? meta_js_1.API_VERSION,
+            account: config?.account,
+            maxRetries: config?.maxRetries ?? 2,
+            timeout: config?.timeout ?? 30_000,
+            fetch: config?.fetch,
+        };
+    }
+    list(spec, paginates) {
+        return new list_js_1.ListPromise((params) => this.request({ ...spec, query: params }), { ...spec.query }, paginates);
+    }
+    async request(spec) {
+        const opts = spec.options ?? {};
+        const cfg = this.config;
+        const doFetch = cfg.fetch ?? globalThis.fetch;
+        if (typeof doFetch !== 'function') {
+            throw new TypeError('Tiempo: no global fetch; pass one with { fetch } (Node 18+ has it built in)');
+        }
+        const maxRetries = Math.max(0, opts.maxRetries ?? cfg.maxRetries);
+        const timeout = opts.timeout ?? cfg.timeout;
+        const account = opts.account ?? cfg.account;
+        const url = cfg.baseUrl + spec.path + (0, query_js_1.encodeQuery)(spec.query);
+        const headers = {
+            Accept: 'application/json',
+            Authorization: `Bearer ${cfg.apiKey}`,
+            'Tiempo-Version': cfg.apiVersion,
+        };
+        if (!isBrowser)
+            headers['User-Agent'] = `tiempo-typescript/${meta_js_1.SDK_VERSION}`;
+        if (account)
+            headers['Tiempo-Account'] = account;
+        let body;
+        if (spec.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            body = JSON.stringify(spec.body);
+        }
+        if (spec.method === 'POST' && !spec.readOnly) {
+            headers['Idempotency-Key'] = opts.idempotencyKey ?? (await (0, crypto_js_1.webCrypto)()).randomUUID();
+        }
+        for (let attempt = 0;; attempt++) {
+            if (opts.signal?.aborted)
+                throw opts.signal.reason;
+            const canRetry = attempt < maxRetries;
+            let response;
+            let text;
+            const controller = new AbortController();
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                controller.abort();
+            }, timeout);
+            const onAbort = () => controller.abort(opts.signal?.reason);
+            opts.signal?.addEventListener('abort', onAbort, { once: true });
+            try {
+                const init = { method: spec.method, headers, signal: controller.signal };
+                if (body !== undefined)
+                    init.body = body;
+                response = await doFetch(url, init);
+                text = await response.text();
+            }
+            catch (err) {
+                if (opts.signal?.aborted)
+                    throw opts.signal.reason;
+                if (canRetry) {
+                    await sleep(backoffMs(attempt), opts.signal);
+                    continue;
+                }
+                throw new errors_js_1.TiempoConnectionError({
+                    message: timedOut
+                        ? `Request to Tiempo timed out after ${timeout}ms (${spec.method} ${spec.path})`
+                        : `Could not connect to Tiempo (${spec.method} ${spec.path}): ${err?.message ?? err}`,
+                    cause: err,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+                opts.signal?.removeEventListener('abort', onAbort);
+            }
+            const responseHeaders = headersToRecord(response.headers);
+            let parsed = text;
+            if (text.length > 0) {
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    // keep text
+                }
+            }
+            if (response.ok) {
+                if (typeof parsed === 'string' && text.length > 0) {
+                    // A 2xx that wasn't JSON: don't hand back a string typed as an object.
+                    throw new errors_js_1.TiempoAPIError({
+                        message: `Expected a JSON response from Tiempo, got: ${text.slice(0, 200)}`,
+                        statusCode: response.status,
+                        headers: responseHeaders,
+                        raw: text,
+                    });
+                }
+                return (text.length > 0 ? parsed : undefined);
+            }
+            const error = (0, errors_js_1.errorFromResponse)(response.status, responseHeaders, parsed);
+            const retryable = RETRYABLE_STATUS.has(response.status) ||
+                (response.status === 409 && error.code === 'idempotency_key_in_use');
+            if (retryable && canRetry) {
+                const delay = retryAfterMs(response.headers.get('retry-after')) ?? backoffMs(attempt);
+                await sleep(delay, opts.signal);
+                continue;
+            }
+            throw error;
+        }
+    }
+}
+exports.HttpClient = HttpClient;

package/dist/cjs/crypto.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Web Crypto: the global `crypto` (Node 19+, browsers, edge runtimes), else
+ * `node:crypto`'s `webcrypto` (Node 18).
+ */
+export declare function webCrypto(): Promise<Crypto>;

package/dist/cjs/crypto.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webCrypto = webCrypto;
+let cached;
+/**
+ * Web Crypto: the global `crypto` (Node 19+, browsers, edge runtimes), else
+ * `node:crypto`'s `webcrypto` (Node 18).
+ */
+async function webCrypto() {
+    if (cached)
+        return cached;
+    const g = globalThis.crypto;
+    if (g?.subtle && typeof g.randomUUID === 'function') {
+        cached = g;
+        return g;
+    }
+    const specifier = 'node:crypto';
+    try {
+        const mod = (await Promise.resolve(`${specifier}`).then(s => require(s)));
+        if (mod.webcrypto?.subtle) {
+            cached = mod.webcrypto;
+            return cached;
+        }
+    }
+    catch {
+        // fall through
+    }
+    throw new Error('Tiempo: Web Crypto is not available in this runtime (need Node 18+ or a runtime with globalThis.crypto).');
+}