@backendfree/core 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# @backendfree/core
 
-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.
+The client every other `@backendfree` package is built on. On its own it
+gives you the project manifest and a typed way to call anything else `/v1`
+offers.
+
+`fetch`, `AbortSignal` and `crypto.randomUUID` and nothing else, so the same
+import works in a build script, a Next.js route, a Worker at the edge and a
+browser bundle. No dependencies.
+
+```sh
+npm install @backendfree/core
+```
+
+```ts
+import { Client } from '@backendfree/core';
+
+const client = new Client({
+  origin: 'https://backendfree.com',
+  key: 'pk_live_...',
+});
+
+const project = await client.project();
+// { id, name, timezone, currency, modules, cache_version, livemode }
+
+if (project.modules.includes('bookings')) {
+  // ...
+}
+```
+
+## Keys
+
+A key identifies the project, which is why no path here names one and why there
+is no project option to get wrong.
+
+| | `pk_live_...` | `sk_live_...` |
+|---|---|---|
+| read services, staff, availability, published content | yes | yes |
+| create a booking | yes | yes |
+| read, cancel, move or pay for one booking | with its token | yes |
+| list bookings, read payments, start a checkout | no | yes |
+| safe in a browser bundle | yes | **never** |
+
+Neither key refunds a payment or changes the catalogue, the hours or the
+content: those happen in the dashboard, where the account owner signs in. A
+leaked secret key can read the books, and it cannot empty them.
+
+Constructing a client with an `sk_` key throws when `window` exists. It is the
+one mistake with this product a deploy cannot take back: a secret key in a
+bundle is every customer and every payment handed to whoever opens the network
+tab.
+
+## Errors
+
+Every `/v1` failure arrives in one envelope, and this package keeps its
+vocabulary rather than inventing a second one.
+
+```ts
+import { BackendFreeError, isNotFound, isRateLimited, isRetryable } from '@backendfree/core';
+
+try {
+  await client.get('/services/' + id);
+} catch (error) {
+  if (isNotFound(error)) { /* not there, not yours, or not switched on */ }
+  if (isRateLimited(error)) { /* error.retryAfter seconds */ }
+  if (isRetryable(error)) { /* send it again with the same idempotency key */ }
+  if (error instanceof BackendFreeError) {
+    error.type;    // 'invalid_request' | 'rate_limit' | ...
+    error.code;    // 'slot_unavailable', and what to branch on
+    error.param;   // 'starts_at', or null
+  }
+}
+```
+
+`message` is written for a person and may be reworded at any time. Branching on
+it will break; branching on `code` will not.
+
+## Caching
+
+Reads of the catalogue, free times, content and the project carry an ETag, so a
+repeat read costs a 304 with no body until something changes. It is on by
+default, with the last 100 responses kept. The diary and one booking are read
+fresh every time, since a stale one sends somebody to an appointment that moved.
+
+```ts
+new Client({ origin, key, cache: false });     // off
+new Client({ origin, key, cache: myStore });   // your own
+await client.send('/project', { cache: false }); // just this one
+```
+
+## Writes
+
+Every method that is not GET carries an `Idempotency-Key`, generated for you. A
+retried booking that arrived twice would be two appointments in one slot, so
+this is not something a developer should have to remember.
+
+Pass your own to make a retry from a different process count as the same
+request. Make it one nobody could guess, such as a UUID your order already
+carries rather than its number:
+
+```ts
+await client.post('/bookings', booking, { idempotencyKey: order.uuid });
+```
+
+## Webhooks
+
+The other direction: the platform posts to a URL you gave it, and this says
+whether to believe it. Your endpoint is public, so anybody can post to it, and
+`payment.succeeded` is a message that marks an order paid.
+
+```ts
+import { verifyWebhook } from '@backendfree/core';
+
+const event = await verifyWebhook({
+  body: await request.text(),   // the raw body, before anything parses it
+  headers: request.headers,
+  secret: process.env.BACKENDFREE_WEBHOOK_SECRET!,
+});
+
+event.name;      // 'payment.succeeded', from the signed body
+event.delivery;  // this delivery's id, from the signed body
+event.data;      // the payload
+```
+
+It verifies whatever a project emits, not just payments, so one handler covers
+every module. It throws a `WebhookError` when the signature is missing, wrong,
+or older than five minutes; answer 400 and log it.
+
+The name and the id are read from the body, never from the
+`X-BackendFree-Event` and `X-BackendFree-Delivery` headers. The signature covers
+the timestamp and the body and nothing else, so on a captured delivery those two
+headers could be rewritten and the signature would still pass.
+
+The body must be the bytes that arrived. The signature covers them exactly, so
+anything that parses first breaks every delivery:
+
+```ts
+app.post('/hooks', express.raw({ type: '*/*' }), handler);  // yes
+app.use(express.json());                                    // not on this route
+```
+
+Two more things follow from how delivery works. Answer quickly and do the work
+afterwards, because a timeout, a refused connection and a 408, 429 or 5xx are
+all retried. And make the handler idempotent on `event.delivery`, because
+delivery is at least once and never exactly once.
+
+## Anything else
+
+`request()`, `get()`, `post()` and `send()` reach any endpoint with the same
+auth, timeout, errors, caching and idempotency, so the SDK never blocks you on
+an endpoint it has not learned yet.
+
+```ts
+const slots = await client.get('/availability', {
+  query: { service: id, from: '2026-06-10', to: '2026-06-17' },
+});
+```
+
+`send()` returns the status, the ETag and whether the API replayed a stored
+answer, when you need more than the body.

package/dist/client.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The client every other @backendfree package is built on.
+ *
+ * `fetch`, `AbortSignal` and `crypto.randomUUID` and nothing else, so the same
+ * import works in a build script, a Next.js route, a Worker at the edge and a
+ * browser bundle.
+ *
+ * Five things are worth knowing before reading further.
+ *
+ * **No path names a project.** The key says which one, which is why there is no
+ * site or project option to get wrong and no way to read one project with
+ * another's key.
+ *
+ * **A secret key in a browser throws.** It is the one mistake with this product
+ * that cannot be undone by a deploy: a publishable key in a bundle is the
+ * design, and a secret one there is every booking, every customer and every
+ * payment handed to whoever opens the network tab.
+ *
+ * **Errors keep the API's own vocabulary.** No second set of names to learn, and
+ * `code` is what a caller branches on.
+ *
+ * **Conditional reads are on by default.** Every response carries an ETag, so a
+ * repeat read costs a 304 with no body until something changes.
+ *
+ * **Writes carry an idempotency key whether or not you pass one.** A retried
+ * booking must never be a second appointment, and the header is the only thing
+ * that makes a retry safe, so no developer should have to remember it.
+ */
+import type { CacheEntry, CacheStore, Manifest, Response as Envelope } from './types.js';
+/** Where `/v1` lives under an origin. */
+export declare const API_PREFIX = "/api/v1";
+/** Ten seconds. Long enough for a cold start, short enough to fail a build fast. */
+export declare const DEFAULT_TIMEOUT = 10000;
+/** How many ETagged responses the built-in cache keeps before evicting. */
+export declare const DEFAULT_CACHE_SIZE = 100;
+/** The API's own ceiling. Asking for more is capped server side. */
+export declare const MAX_PAGE_SIZE = 100;
+export interface ClientOptions {
+    /**
+     * Where the platform runs, with no trailing path: `https://backendfree.com`.
+     * The client appends `/api/v1` itself.
+     *
+     * Required rather than defaulted. The same client talks to production, to a
+     * local server and to any other copy of the platform, and a default would
+     * quietly send whatever forgot to set it to production.
+     */
+    origin: string;
+    /**
+     * `pk_live_...` in anything a browser can read, `sk_live_...` on a server.
+     * The prefix is in the key so it can be told apart at a glance.
+     */
+    key: string;
+    /**
+     * Swap in your own `fetch`: a test double, a Worker's bound fetcher, or
+     * Next.js's caching one with `{next: {revalidate}}` already baked in.
+     */
+    fetch?: typeof globalThis.fetch;
+    /** Per-request timeout in milliseconds. `0` disables it. */
+    timeout?: number;
+    /** ETag caching: on (default), off, or your own store. */
+    cache?: boolean | CacheStore;
+    /** Extra headers on every request: a proxy, a tunnel's bypass. */
+    headers?: Record<string, string>;
+}
+export interface RequestOptions {
+    method?: string;
+    /** `undefined` and `null` are dropped rather than sent as the string. */
+    query?: Record<string, string | number | boolean | undefined | null>;
+    /** Serialised as JSON. Anything but GET may carry one. */
+    body?: unknown;
+    headers?: Record<string, string>;
+    /**
+     * One request is one write, however many times it is sent. Generated for you
+     * on every method that is not GET; pass your own to make a retry from a
+     * different process count as the same request.
+     */
+    idempotencyKey?: string;
+    /** Pass `false` to bypass the ETag cache for this call. */
+    cache?: boolean;
+    signal?: AbortSignal;
+}
+export declare class Client {
+    #private;
+    readonly origin: string;
+    readonly publishable: boolean;
+    constructor(options: ClientOptions);
+    /**
+     * What this key can reach: the project, its clock, its currency and which
+     * modules are switched on.
+     *
+     * Worth calling first. It is the difference between "bookings is not enabled
+     * for this project" and a 404 from an endpoint the developer was told exists.
+     */
+    project(options?: RequestOptions): Promise<Manifest>;
+    /**
+     * Whether a module is switched on, without a second call.
+     *
+     * Reads the manifest, so it costs a 304 once the first read is cached.
+     */
+    has(module: string, options?: RequestOptions): Promise<boolean>;
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Any call, typed by the caller.
+     *
+     * Deliberately public. The typed methods on this and every other package are
+     * conveniences over it, and when the API grows something the SDK has not
+     * learned yet this still reaches it, with the same auth, timeout, errors,
+     * caching and idempotency.
+     */
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    /** The same call, with the status, the ETag and whether it was replayed. */
+    send<T>(path: string, options?: RequestOptions): Promise<Envelope<T>>;
+}
+/**
+ * The default ETag store: the last `DEFAULT_CACHE_SIZE` responses, oldest out.
+ *
+ * A Map keeps insertion order, so re-inserting on read makes this least
+ * recently used without a second structure.
+ */
+export declare class MemoryCache implements CacheStore {
+    #private;
+    constructor(limit?: number);
+    get(key: string): CacheEntry | undefined;
+    set(key: string, entry: CacheEntry): void;
+    delete(key: string): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAWH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,IAAI,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEzF,yCAAyC;AACzC,eAAO,MAAM,UAAU,YAAY,CAAC;AAEpC,oFAAoF;AACpF,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,oEAAoE;AACpE,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC7B,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;IACrE,0DAA0D;IAC1D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,qBAAa,MAAM;;IACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;gBAQlB,OAAO,EAAE,aAAa;IA4ClC;;;;;;OAMG;IACG,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI9D;;;;OAIG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAOzE,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAI9D,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAI/E;;;;;;;OAOG;IACG,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAKxE,4EAA4E;IACtE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;CAoFhF;AAyID;;;;;GAKG;AACH,qBAAa,WAAY,YAAW,UAAU;;gBAIhC,KAAK,SAAqB;IAItC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IASxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IASzC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAG1B"}

package/dist/client.js

@@ -0,0 +1,367 @@
+/**
+ * The client every other @backendfree package is built on.
+ *
+ * `fetch`, `AbortSignal` and `crypto.randomUUID` and nothing else, so the same
+ * import works in a build script, a Next.js route, a Worker at the edge and a
+ * browser bundle.
+ *
+ * Five things are worth knowing before reading further.
+ *
+ * **No path names a project.** The key says which one, which is why there is no
+ * site or project option to get wrong and no way to read one project with
+ * another's key.
+ *
+ * **A secret key in a browser throws.** It is the one mistake with this product
+ * that cannot be undone by a deploy: a publishable key in a bundle is the
+ * design, and a secret one there is every booking, every customer and every
+ * payment handed to whoever opens the network tab.
+ *
+ * **Errors keep the API's own vocabulary.** No second set of names to learn, and
+ * `code` is what a caller branches on.
+ *
+ * **Conditional reads are on by default.** Every response carries an ETag, so a
+ * repeat read costs a 304 with no body until something changes.
+ *
+ * **Writes carry an idempotency key whether or not you pass one.** A retried
+ * booking must never be a second appointment, and the header is the only thing
+ * that makes a retry safe, so no developer should have to remember it.
+ */
+import { ApiError, AuthError, ConfigError, NotFoundError, RateLimitError, UnreachableError, } from './errors.js';
+/** Where `/v1` lives under an origin. */
+export const API_PREFIX = '/api/v1';
+/** Ten seconds. Long enough for a cold start, short enough to fail a build fast. */
+export const DEFAULT_TIMEOUT = 10_000;
+/** How many ETagged responses the built-in cache keeps before evicting. */
+export const DEFAULT_CACHE_SIZE = 100;
+/** The API's own ceiling. Asking for more is capped server side. */
+export const MAX_PAGE_SIZE = 100;
+export class Client {
+    origin;
+    publishable;
+    #key;
+    #fetch;
+    #timeout;
+    #headers;
+    #cache;
+    constructor(options) {
+        const origin = (options.origin ?? '').trim().replace(/\/+$/, '');
+        if (!origin) {
+            throw new ConfigError('origin_required', 'Pass the origin the platform runs on.');
+        }
+        const key = (options.key ?? '').trim();
+        if (!key) {
+            throw new ConfigError('key_required', 'Pass a project API key.');
+        }
+        // The one mistake this SDK refuses to let anybody make. A publishable key in
+        // a bundle is how the product is meant to work; a secret one there hands
+        // over every customer's name, address and appointment to anybody who opens
+        // the network tab, and no deploy takes it back once it has shipped.
+        if (key.startsWith('sk_') && typeof window !== 'undefined') {
+            throw new ConfigError('secret_key_in_browser', 'A secret key must never reach a browser. Use a publishable key (pk_) in ' +
+                'anything shipped to the client, and keep sk_ on a server.');
+        }
+        this.origin = origin;
+        this.publishable = key.startsWith('pk_');
+        this.#key = key;
+        // Bound to the global, and that is load-bearing rather than tidy. Stored
+        // unbound, `this.#fetch(...)` calls it with the Client as its receiver, and
+        // a browser's `fetch` refuses any receiver but the window: every request
+        // from a browser fails with "Illegal invocation" before it reaches the
+        // network. Node's fetch has no such check, so nothing in this suite could
+        // see it and the failure only ever appeared in the one place the SDK is
+        // most meant to work.
+        //
+        // A caller's own fetch is left exactly as they passed it: binding somebody
+        // else's method to the global would break a client that is a method of
+        // something.
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.#timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        this.#headers = { ...options.headers };
+        this.#cache = resolveCache(options.cache);
+    }
+    // --- what a key can reach ---------------------------------------------------
+    /**
+     * What this key can reach: the project, its clock, its currency and which
+     * modules are switched on.
+     *
+     * Worth calling first. It is the difference between "bookings is not enabled
+     * for this project" and a 404 from an endpoint the developer was told exists.
+     */
+    async project(options = {}) {
+        return this.get('/project', options);
+    }
+    /**
+     * Whether a module is switched on, without a second call.
+     *
+     * Reads the manifest, so it costs a 304 once the first read is cached.
+     */
+    async has(module, options = {}) {
+        const manifest = await this.project(options);
+        return manifest.modules.includes(module);
+    }
+    // --- the escape hatch --------------------------------------------------------
+    get(path, options = {}) {
+        return this.request(path, { ...options, method: 'GET' });
+    }
+    post(path, body, options = {}) {
+        return this.request(path, { ...options, method: 'POST', body });
+    }
+    /**
+     * Any call, typed by the caller.
+     *
+     * Deliberately public. The typed methods on this and every other package are
+     * conveniences over it, and when the API grows something the SDK has not
+     * learned yet this still reaches it, with the same auth, timeout, errors,
+     * caching and idempotency.
+     */
+    async request(path, options = {}) {
+        const { data } = await this.send(path, options);
+        return data;
+    }
+    /** The same call, with the status, the ETag and whether it was replayed. */
+    async send(path, options = {}) {
+        const method = (options.method ?? 'GET').toUpperCase();
+        const url = this.#url(path, options.query);
+        const cacheable = method === 'GET' && options.cache !== false && this.#cache !== null;
+        const cached = cacheable ? this.#cache.get(url) : undefined;
+        const headers = {
+            accept: 'application/json',
+            authorization: `Bearer ${this.#key}`,
+            ...this.#headers,
+            ...lower(options.headers),
+        };
+        if (cached)
+            headers['if-none-match'] = cached.etag;
+        let body;
+        if (options.body !== undefined && method !== 'GET') {
+            body = JSON.stringify(options.body);
+            headers['content-type'] = 'application/json';
+        }
+        if (method !== 'GET') {
+            // Generated rather than asked for. A retried booking that arrived twice
+            // is two appointments in one slot, and the header is the only thing that
+            // makes the retry safe.
+            //
+            // An empty string falls back to a generated one rather than being sent as
+            // an empty header, which the API reads as no key at all: there is no
+            // reason to want a write that cannot be safely retried.
+            headers['idempotency-key'] = options.idempotencyKey || newIdempotencyKey();
+        }
+        const response = await this.#fetch2(url, { method, headers, body, signal: options.signal });
+        if (response.status === 304 && cached) {
+            return { data: cached.body, status: 304, etag: cached.etag, replayed: false };
+        }
+        if (!response.ok) {
+            throw await toError(response, url);
+        }
+        const etag = response.headers.get('etag');
+        const data = response.status === 204 ? undefined : (await readJson(response, url));
+        if (cacheable && etag)
+            this.#cache.set(url, { etag, body: data });
+        return {
+            data,
+            status: response.status,
+            etag,
+            replayed: response.headers.get('idempotency-replayed') === 'true',
+        };
+    }
+    #url(path, query) {
+        const url = new URL(`${API_PREFIX}${path.startsWith('/') ? path : `/${path}`}`, this.origin);
+        for (const [name, value] of Object.entries(query ?? {})) {
+            // Dropped rather than sent as "undefined", which the API would read as a
+            // filter nobody asked for.
+            if (value === undefined || value === null || value === '')
+                continue;
+            url.searchParams.set(name, String(value));
+        }
+        return url.toString();
+    }
+    async #fetch2(url, init) {
+        const controller = this.#timeout > 0 ? new AbortController() : null;
+        const timer = controller ? setTimeout(() => controller.abort(), this.#timeout) : null;
+        const signal = mergeSignals(init.signal ?? null, controller?.signal ?? null);
+        try {
+            return await this.#fetch(url, { ...init, signal });
+        }
+        catch (cause) {
+            // Every way of not getting an answer, told apart from an answer that says
+            // no. A build script should shrug at this one and keep what it has.
+            const timedOut = controller?.signal.aborted ?? false;
+            throw new UnreachableError(url, timedOut
+                ? `No answer from ${url} within ${this.#timeout}ms.`
+                : `Could not reach ${url}.`, cause);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+}
+// --- turning a response into an error ---------------------------------------
+const TYPES = new Set([
+    'invalid_request',
+    'authentication_error',
+    'permission_error',
+    'not_found',
+    'conflict',
+    'rate_limit',
+    'api_error',
+]);
+async function toError(response, url) {
+    const envelope = await readEnvelope(response);
+    const status = response.status;
+    const options = { url, status, param: envelope.param };
+    const type = (TYPES.has(envelope.type) ? envelope.type : fallbackType(status));
+    if (type === 'authentication_error' || type === 'permission_error') {
+        return new AuthError(type, envelope.code, envelope.message, options);
+    }
+    if (type === 'not_found') {
+        return new NotFoundError(type, envelope.code, envelope.message, options);
+    }
+    if (type === 'rate_limit') {
+        return new RateLimitError(envelope.code, envelope.message, {
+            url,
+            status,
+            retryAfter: retryAfter(response),
+        });
+    }
+    return new ApiError(type, envelope.code, envelope.message, options);
+}
+/**
+ * The envelope, or something that stands in for it.
+ *
+ * A 502 from a proxy in front of the platform never went through the error
+ * handler, so it answers HTML or nothing at all. That is still a failure a
+ * caller has to handle, so it gets the same shape rather than a parse error.
+ */
+async function readEnvelope(response) {
+    const fallback = {
+        type: fallbackType(response.status),
+        code: `http_${response.status}`,
+        message: `${response.status} ${response.statusText}`.trim(),
+        param: null,
+    };
+    try {
+        const payload = (await response.json());
+        const error = payload?.error;
+        if (!error)
+            return fallback;
+        return {
+            type: typeof error.type === 'string' ? error.type : fallback.type,
+            code: typeof error.code === 'string' ? error.code : fallback.code,
+            message: typeof error.message === 'string' ? error.message : fallback.message,
+            param: typeof error.param === 'string' ? error.param : null,
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
+function fallbackType(status) {
+    if (status === 401)
+        return 'authentication_error';
+    if (status === 403)
+        return 'permission_error';
+    if (status === 404)
+        return 'not_found';
+    if (status === 409)
+        return 'conflict';
+    if (status === 429)
+        return 'rate_limit';
+    if (status >= 500)
+        return 'api_error';
+    return 'invalid_request';
+}
+function retryAfter(response) {
+    const header = response.headers.get('retry-after');
+    if (!header)
+        return null;
+    const seconds = Number.parseInt(header, 10);
+    return Number.isFinite(seconds) ? seconds : null;
+}
+async function readJson(response, url) {
+    try {
+        return await response.json();
+    }
+    catch (cause) {
+        throw new ApiError('api_error', 'malformed_response', `${url} answered with something that is not JSON.`, {
+            url,
+            status: response.status,
+            cause,
+        });
+    }
+}
+// --- small parts --------------------------------------------------------------
+function newIdempotencyKey() {
+    const crypto = globalThis.crypto;
+    if (typeof crypto?.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    // A browser offers `randomUUID` only on a page served over https, and
+    // `getRandomValues` everywhere. Never `Math.random`: a key somebody can
+    // guess is one they can send first, and whoever sends a key with the same
+    // body is answered with what it made, a booking's manage token included.
+    // Not a v4 UUID and does not need to be: the API treats it as an opaque
+    // string scoped to one project.
+    if (typeof crypto?.getRandomValues === 'function') {
+        const bytes = crypto.getRandomValues(new Uint8Array(16));
+        return `k_${[...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('')}`;
+    }
+    throw new ConfigError('crypto_unavailable', 'This runtime has no Web Crypto, so a write cannot carry an unguessable Idempotency-Key. ' +
+        'Pass idempotencyKey yourself.');
+}
+function lower(headers) {
+    const out = {};
+    for (const [name, value] of Object.entries(headers ?? {}))
+        out[name.toLowerCase()] = value;
+    return out;
+}
+function mergeSignals(a, b) {
+    if (!a)
+        return b ?? undefined;
+    if (!b)
+        return a;
+    // Both a caller's cancellation and the timeout have to be able to stop this.
+    return AbortSignal.any([a, b]);
+}
+function resolveCache(cache) {
+    if (cache === false)
+        return null;
+    if (cache && typeof cache === 'object')
+        return cache;
+    return new MemoryCache();
+}
+/**
+ * The default ETag store: the last `DEFAULT_CACHE_SIZE` responses, oldest out.
+ *
+ * A Map keeps insertion order, so re-inserting on read makes this least
+ * recently used without a second structure.
+ */
+export class MemoryCache {
+    #entries = new Map();
+    #limit;
+    constructor(limit = DEFAULT_CACHE_SIZE) {
+        this.#limit = limit;
+    }
+    get(key) {
+        const entry = this.#entries.get(key);
+        if (entry) {
+            this.#entries.delete(key);
+            this.#entries.set(key, entry);
+        }
+        return entry;
+    }
+    set(key, entry) {
+        this.#entries.delete(key);
+        this.#entries.set(key, entry);
+        if (this.#entries.size > this.#limit) {
+            const oldest = this.#entries.keys().next();
+            if (!oldest.done)
+                this.#entries.delete(oldest.value);
+        }
+    }
+    delete(key) {
+        this.#entries.delete(key);
+    }
+}
+//# sourceMappingURL=client.js.map