@cube-nl/dmp-sdk 0.0.0-stage → 1.0.0-rc.4

package/dist/auth.js

@@ -0,0 +1,321 @@
+import { DmpError } from './errors.js';
+/**
+ * A fixed token: a personal token (`$user->createToken(...)`) or an API-client token. Pass a
+ * function to read it fresh on every call. Never hardcode one in code that reaches a browser bundle.
+ */
+export function bearer(token) {
+    return {
+        async getAccessToken() {
+            const value = typeof token === 'function' ? await token() : token;
+            return value === undefined || value === '' ? null : value;
+        },
+    };
+}
+const PENDING_KEY = 'cube-dmp-sdk.pending-login';
+/**
+ * OAuth 2.1 authorization code with PKCE (S256) against cube/oauth-server.
+ *
+ * The access token lives in memory unless you pass a `tokenStore`. What survives the redirect is
+ * the verifier and the state, in sessionStorage: useless without the code, and removed as soon as
+ * the callback is handled.
+ */
+export function createOAuth(options) {
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const tokenStore = options.tokenStore ?? memoryTokenStore();
+    const pendingStore = options.pendingStore ?? defaultPendingStore();
+    const leeway = (options.refreshLeewaySeconds ?? 30) * 1000;
+    const scope = typeof options.scopes === 'string' ? options.scopes : options.scopes.join(' ');
+    const overrides = options.metadata ?? {};
+    let metadata = isCompleteMetadata(overrides)
+        ? Promise.resolve({ ...overrides, issuer: overrides.issuer ?? options.issuer })
+        : null;
+    let refreshing = null;
+    const discover = () => {
+        metadata ??= discoverMetadata(options.issuer, doFetch).then((discovered) => ({ ...discovered, ...overrides }), (error) => {
+            metadata = null;
+            throw error;
+        });
+        return metadata;
+    };
+    // RFC 6749 section 5.1: a server may leave `scope` out when it granted exactly what was asked.
+    const tokenRequest = async (form, grantedIfOmitted) => {
+        const { token_endpoint: endpoint } = await discover();
+        const body = new URLSearchParams(form);
+        if (options.clientSecret !== undefined) {
+            body.set('client_secret', options.clientSecret);
+        }
+        // Form-encoded, not JSON: that is what the token endpoint reads.
+        const response = await doFetch(endpoint, {
+            method: 'POST',
+            headers: { Accept: 'application/json', 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: body.toString(),
+        });
+        const json = await readJson(response);
+        if (!response.ok || json === null || typeof json !== 'object' || typeof json.access_token !== 'string') {
+            throw new DmpError(response.status, response.headers, json);
+        }
+        const tokens = {
+            accessToken: json.access_token,
+            refreshToken: typeof json.refresh_token === 'string' ? json.refresh_token : null,
+            expiresAt: typeof json.expires_in === 'number' ? Date.now() + json.expires_in * 1000 : null,
+            scope: typeof json.scope === 'string' ? json.scope : grantedIfOmitted,
+        };
+        await tokenStore.set(tokens);
+        return tokens;
+    };
+    const refresh = () => {
+        refreshing ??= (async () => {
+            const current = await tokenStore.get();
+            if (current?.refreshToken == null) {
+                throw new TypeError('No refresh token: sign in again.');
+            }
+            try {
+                return await tokenRequest({
+                    grant_type: 'refresh_token',
+                    refresh_token: current.refreshToken,
+                    client_id: options.clientId,
+                }, current.scope);
+            }
+            catch (error) {
+                // A refused refresh token is spent or revoked: holding on to it only repeats the refusal.
+                if (error instanceof DmpError && error.status >= 400 && error.status < 500) {
+                    await tokenStore.set(null);
+                }
+                throw error;
+            }
+        })().finally(() => {
+            refreshing = null;
+        });
+        return refreshing;
+    };
+    const authorizationUrl = async (urlOptions = {}) => {
+        const server = await discover();
+        if (!(server.code_challenge_methods_supported ?? []).includes('S256')) {
+            throw new TypeError('The authorization server does not offer PKCE S256; this SDK will not sign in without it.');
+        }
+        const verifier = randomString(64);
+        const state = urlOptions.state ?? randomString(32);
+        const challenge = base64url(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier)));
+        const pending = { verifier, state, redirectUri: options.redirectUri, clientId: options.clientId };
+        pendingStore.setItem(PENDING_KEY, JSON.stringify(pending));
+        const url = new URL(server.authorization_endpoint);
+        url.search = new URLSearchParams({
+            ...urlOptions.extraParams,
+            response_type: 'code',
+            client_id: options.clientId,
+            redirect_uri: options.redirectUri,
+            scope,
+            state,
+            code_challenge: challenge,
+            code_challenge_method: 'S256',
+        }).toString();
+        return url.toString();
+    };
+    return {
+        discover,
+        authorizationUrl,
+        async signIn(signInOptions = {}) {
+            const location = browserLocation();
+            if (location === null) {
+                throw new TypeError('signIn() needs a browser; use authorizationUrl() and redirect yourself.');
+            }
+            location.assign(await authorizationUrl(signInOptions));
+        },
+        async handleCallback(url) {
+            const current = url ?? browserLocation()?.href;
+            if (current === undefined) {
+                throw new TypeError('handleCallback() needs the callback URL outside a browser.');
+            }
+            const parsed = new URL(current);
+            const params = new URLSearchParams(parsed.search);
+            if (!isCallbackUrl(parsed, options.redirectUri) || (!params.has('code') && !params.has('error'))) {
+                return null;
+            }
+            if (url === undefined) {
+                // The code must not stay in the address bar, the history or a bookmark.
+                for (const key of ['code', 'state', 'error', 'error_description', 'iss']) {
+                    parsed.searchParams.delete(key);
+                }
+                globalThis.history?.replaceState(null, '', parsed.pathname + parsed.search + parsed.hash);
+            }
+            const pending = parsePending(pendingStore.getItem(PENDING_KEY));
+            // Checked before an error is surfaced and before the verifier is spent: a forged callback link
+            // must neither pose as the server's answer nor cancel a sign-in that is still underway.
+            if (pending === null || params.get('state') !== pending.state) {
+                throw new TypeError('The state does not match: this callback does not belong to a sign-in started here.');
+            }
+            pendingStore.removeItem(PENDING_KEY);
+            if (params.has('error')) {
+                throw new DmpError(400, new Headers(), {
+                    error: params.get('error') ?? 'access_denied',
+                    error_description: params.get('error_description') ?? undefined,
+                });
+            }
+            return tokenRequest({
+                grant_type: 'authorization_code',
+                code: params.get('code') ?? '',
+                redirect_uri: pending.redirectUri,
+                client_id: pending.clientId,
+                code_verifier: pending.verifier,
+            }, scope);
+        },
+        refresh,
+        async getTokens() {
+            return tokenStore.get();
+        },
+        async setTokens(tokens) {
+            await tokenStore.set(tokens);
+        },
+        async signOut() {
+            await tokenStore.set(null);
+            pendingStore.removeItem(PENDING_KEY);
+        },
+        async getAccessToken() {
+            const tokens = await tokenStore.get();
+            if (tokens === null) {
+                return null;
+            }
+            const expired = tokens.expiresAt !== null && tokens.expiresAt - leeway <= Date.now();
+            if (expired && tokens.refreshToken !== null) {
+                try {
+                    return (await refresh()).accessToken;
+                }
+                catch {
+                    // Send what we have: the 401 that follows is a clearer answer than a refresh error here.
+                    return (await tokenStore.get())?.accessToken ?? null;
+                }
+            }
+            return tokens.accessToken;
+        },
+        async onUnauthorized() {
+            const tokens = await tokenStore.get();
+            if (tokens?.refreshToken == null) {
+                return false;
+            }
+            try {
+                await refresh();
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+function isCompleteMetadata(value) {
+    return typeof value.authorization_endpoint === 'string' && typeof value.token_endpoint === 'string';
+}
+/**
+ * RFC 7591 dynamic client registration, when the DMP turned it on (`registration_endpoint` is then
+ * in discovery). Returns the registration response, with `client_id`.
+ */
+export async function registerClient(server, request, doFetch = globalThis.fetch.bind(globalThis)) {
+    if (server.registration_endpoint === undefined) {
+        throw new TypeError('This DMP does not let apps register themselves (no registration_endpoint in discovery).');
+    }
+    const { clientName, redirectUris, ...extra } = request;
+    const response = await doFetch(server.registration_endpoint, {
+        method: 'POST',
+        headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ...extra, client_name: clientName, redirect_uris: redirectUris }),
+    });
+    const json = await readJson(response);
+    if (!response.ok || json === null || typeof json !== 'object' || typeof json.client_id !== 'string') {
+        throw new DmpError(response.status, response.headers, json);
+    }
+    return json;
+}
+export async function discoverMetadata(issuer, doFetch = globalThis.fetch.bind(globalThis)) {
+    const url = `${issuer.replace(/\/+$/, '')}/.well-known/oauth-authorization-server`;
+    const response = await doFetch(url, { headers: { Accept: 'application/json' } });
+    const json = await readJson(response);
+    if (!response.ok || json === null || typeof json !== 'object') {
+        throw new DmpError(response.status, response.headers, json);
+    }
+    return json;
+}
+export function memoryTokenStore(initial = null) {
+    let tokens = initial;
+    return {
+        get: () => tokens,
+        set: (value) => {
+            tokens = value;
+        },
+    };
+}
+export function memoryKeyValueStore() {
+    const items = new Map();
+    return {
+        getItem: (key) => items.get(key) ?? null,
+        setItem: (key, value) => {
+            items.set(key, value);
+        },
+        removeItem: (key) => {
+            items.delete(key);
+        },
+    };
+}
+function defaultPendingStore() {
+    try {
+        const storage = globalThis.sessionStorage;
+        if (storage !== undefined) {
+            return storage;
+        }
+    }
+    catch {
+        // Blocked storage (a sandboxed iframe, strict privacy settings) throws on access.
+    }
+    return memoryKeyValueStore();
+}
+function browserLocation() {
+    const location = globalThis.location;
+    return location !== undefined && typeof location.assign === 'function' ? location : null;
+}
+/**
+ * Only the registered redirect URI is a callback; other pages may carry a `code` or `error` of their own. A trailing
+ * slash does not count: a static host answers `/callback` with a redirect to `/callback/` when it serves the page from
+ * `callback/index.html`.
+ */
+function isCallbackUrl(url, redirectUri) {
+    const expected = new URL(redirectUri);
+    const path = (pathname) => pathname.replace(/\/+$/, '') || '/';
+    return url.origin === expected.origin && path(url.pathname) === path(expected.pathname);
+}
+function parsePending(raw) {
+    if (raw === null) {
+        return null;
+    }
+    try {
+        const value = JSON.parse(raw);
+        return typeof value.verifier === 'string' && typeof value.state === 'string'
+            && typeof value.redirectUri === 'string' && typeof value.clientId === 'string'
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readJson(response) {
+    const text = await response.text();
+    if (text === '') {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function randomString(bytes) {
+    return base64url(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+export function base64url(buffer) {
+    const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+    let binary = '';
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}

package/dist/browser.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/browser.js

@@ -0,0 +1,3 @@
+import { CubeApp } from './app.js';
+// The entry of dist/cube-sdk.js: one classic script, no imports, `window.CubeApp` for a page without a build step.
+globalThis.CubeApp = CubeApp;

package/dist/client.d.ts

@@ -0,0 +1,102 @@
+import { type AuthStrategy, type TokenSource } from './auth.js';
+import type { AggregateQuery, Capabilities, DmpRecord, DmpResponse, GetQuery, ListQuery, ListResponse, OperationResponse } from './types.js';
+export interface ClientOptions {
+    /**
+     * The API's base URL, prefix included: `https://dmp.example.nl/apps/api/v1` — what the panel's
+     * API → Connect screen and `dmp.instructions.de_api.basis_url` show. A relative one
+     * (`/apps/api/v1`) works in a browser behind a dev-server proxy.
+     */
+    baseUrl: string;
+    /** A token, a function returning one, `bearer(...)`, or an OAuth session from `createOAuth()`. */
+    auth?: TokenSource | AuthStrategy;
+    fetch?: typeof fetch;
+    /** Sent on every request. For example `X-Dmp-Act-As` from a server-side edge function — never a browser. */
+    headers?: Record<string, string>;
+    /**
+     * The fetch `cache` mode. Default `'no-cache'` in a browser (revalidate with the ETag rather than
+     * trust a cached list after a write), unset in Node.
+     */
+    cache?: RequestCache;
+    /** Every completed call, for a log or a devtools panel. Never receives the token. */
+    onResponse?: (entry: {
+        method: string;
+        url: string;
+        status: number;
+        ms: number;
+    }) => void;
+}
+export interface CreateOptions {
+    /**
+     * Send the same key again to get the first attempt's 201 replayed instead of a second record.
+     * Use a fresh one per logical create (`newIdempotencyKey()`), and the same body on a retry.
+     */
+    idempotencyKey?: string;
+    /** `fields[{resource}]` for the 201 body. Part of the idempotency fingerprint: repeat it on a retry. */
+    fields?: readonly string[];
+}
+export interface WriteOptions {
+    /** A `recordVersion` from an earlier response (never the ETag). A stale one answers 409 `conflict`. */
+    ifMatch?: string;
+    fields?: readonly string[];
+}
+export interface OperationOptions {
+    /** Required by the API for an operation `_capabilities` marks `idempotent: false`. */
+    idempotencyKey?: string;
+    /** Record operations only. */
+    ifMatch?: string;
+    fields?: readonly string[];
+}
+export interface RequestOptions {
+    query?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+export interface ResourceClient<T extends DmpRecord = DmpRecord> {
+    readonly name: string;
+    /** `GET /{resource}`. Always paginated; `meta.page` says where you are. */
+    list(query?: ListQuery, init?: {
+        signal?: AbortSignal;
+    }): Promise<ListResponse<T>>;
+    /** Walks every page with the same query, one request per page. Mind the rate limit. */
+    pages(query?: ListQuery, init?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<ListResponse<T>, void, void>;
+    /** Every record of every page. */
+    all(query?: ListQuery, init?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<T, void, void>;
+    /** `GET /{resource}/{id}`. Accepts only fields, include and withCount. Carries `recordVersion`. */
+    get(id: string | number, query?: GetQuery, init?: {
+        signal?: AbortSignal;
+    }): Promise<DmpResponse<T>>;
+    /** `GET /{resource}/_aggregate`. `data` rows are keyed by exactly the `fn`/`group` strings you sent. */
+    aggregate<R extends DmpRecord = DmpRecord>(query: AggregateQuery, init?: {
+        signal?: AbortSignal;
+    }): Promise<DmpResponse<R[]>>;
+    /** `POST /{resource}`: 201 with the record, `location` and `recordVersion`; `replayed` on a replay. */
+    create(body: Partial<T>, options?: CreateOptions): Promise<DmpResponse<T>>;
+    /** `PATCH /{resource}/{id}`: partial, absent fields stay. */
+    update(id: string | number, body: Partial<T>, options?: WriteOptions): Promise<DmpResponse<T>>;
+    /** `DELETE /{resource}/{id}`: 204. Off on the server unless `allow_delete` is on. */
+    delete(id: string | number, options?: {
+        ifMatch?: string;
+    }): Promise<DmpResponse<null>>;
+    /** `POST /{resource}/{id}/{operation}`. A 202 means queued (`accepted`), a 204 done with no body. */
+    operation<R = T>(id: string | number, name: string, input?: Record<string, unknown>, options?: OperationOptions): Promise<OperationResponse<R>>;
+    /** `POST /{resource}/_operations/{operation}`. */
+    collectionOperation<R = T>(name: string, input?: Record<string, unknown>, options?: Omit<OperationOptions, 'ifMatch'>): Promise<OperationResponse<R>>;
+}
+export interface DmpClient {
+    /** `GET /_capabilities`: call it first. What this token and this user may reach, nothing more. */
+    capabilities(init?: {
+        signal?: AbortSignal;
+    }): Promise<Capabilities>;
+    resources<T extends DmpRecord = DmpRecord>(name: string): ResourceClient<T>;
+    /** The escape hatch: any path under the base URL, with the same auth, errors and envelope. */
+    request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<DmpResponse<T>>;
+}
+/** One client, resources as a property (OP-05): `createClient(...).resources('projects').list()`. */
+export declare function createClient(options: ClientOptions): DmpClient;
+/** A fresh key for one logical POST. Reuse it only to retry that same request with that same body. */
+export declare function newIdempotencyKey(): string;

package/dist/client.js

@@ -0,0 +1,220 @@
+import { bearer } from './auth.js';
+import { DmpError } from './errors.js';
+import { buildQuery } from './query.js';
+const RESOURCE_NAME = /^[a-z][a-z0-9_]*$/;
+/** One client, resources as a property (OP-05): `createClient(...).resources('projects').list()`. */
+export function createClient(options) {
+    const baseUrl = options.baseUrl.replace(/\/+$/, '');
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const auth = options.auth === undefined
+        ? null
+        : typeof options.auth === 'string' || typeof options.auth === 'function'
+            ? bearer(options.auth)
+            : options.auth;
+    const cache = options.cache ?? (typeof document !== 'undefined' ? 'no-cache' : undefined);
+    const request = async (method, path, { query, body, headers = {}, signal } = {}) => {
+        const url = `${baseUrl}${path.startsWith('/') ? path : `/${path}`}${query ? `?${query}` : ''}`;
+        const send = async () => {
+            const token = auth === null ? null : await auth.getAccessToken();
+            const init = {
+                method,
+                headers: {
+                    Accept: 'application/json',
+                    ...options.headers,
+                    ...(token !== null ? { Authorization: `Bearer ${token}` } : {}),
+                    ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                    ...headers,
+                },
+            };
+            if (body !== undefined) {
+                init.body = JSON.stringify(body);
+            }
+            if (cache !== undefined) {
+                init.cache = cache;
+            }
+            if (signal !== undefined) {
+                init.signal = signal;
+            }
+            const started = Date.now();
+            const response = await doFetch(url, init);
+            options.onResponse?.({ method, url, status: response.status, ms: Date.now() - started });
+            return response;
+        };
+        let response = await send();
+        // One retry, and only when the strategy says it has a new token: a second 401 is the answer.
+        if (response.status === 401 && auth?.onUnauthorized !== undefined && (await auth.onUnauthorized())) {
+            await response.body?.cancel().catch(() => undefined);
+            response = await send();
+        }
+        const parsed = await readBody(response);
+        if (!response.ok) {
+            throw new DmpError(response.status, response.headers, parsed);
+        }
+        const envelope = isEnvelope(parsed) ? parsed : null;
+        return {
+            status: response.status,
+            data: (envelope !== null ? envelope.data : parsed),
+            meta: envelope?.meta ?? null,
+            headers: response.headers,
+            etag: response.headers.get('ETag'),
+            recordVersion: response.headers.get('X-Dmp-Record-Version'),
+            location: response.headers.get('Location'),
+            replayed: response.headers.get('Idempotency-Replayed') === 'true',
+            rateLimit: rateLimit(response.headers),
+        };
+    };
+    const resources = (name) => {
+        if (!RESOURCE_NAME.test(name)) {
+            throw new TypeError(`'${name}' is not a resource name: cube/api names match [a-z][a-z0-9_]*.`);
+        }
+        const collection = `/${name}`;
+        const record = (id) => {
+            const key = String(id);
+            if (key === '') {
+                throw new TypeError(`${name}: an empty id would address the collection, not a record.`);
+            }
+            if (isDotSegment(key)) {
+                // The URL parser resolves '.' and '..' as path steps, so the request would leave this record.
+                throw new TypeError(`${name}: '${key}' is not an id: it would address another path, not a record.`);
+            }
+            return `${collection}/${encodeURIComponent(key)}`;
+        };
+        const fieldsQuery = (fields) => fields === undefined ? '' : buildQuery(name, { fields });
+        const list = async (query = {}, init = {}) => (await request('GET', collection, withSignal({ query: buildQuery(name, query) }, init)));
+        const pages = async function* (query = {}, init = {}) {
+            let number = query.page?.number ?? 1;
+            while (true) {
+                const page = await list({ ...query, page: { ...query.page, number } }, init);
+                yield page;
+                const meta = page.meta.page;
+                if (meta === undefined || meta === null || meta.number >= meta.pages || page.data.length === 0) {
+                    return;
+                }
+                number = meta.number + 1;
+            }
+        };
+        const runOperation = async (path, input, opts) => {
+            const response = await request('POST', path, {
+                query: fieldsQuery(opts.fields),
+                body: input ?? {},
+                headers: writeHeaders(opts),
+            });
+            return { ...response, data: response.status === 204 ? null : response.data, accepted: response.status === 202 };
+        };
+        return {
+            name,
+            list,
+            pages,
+            async *all(query = {}, init = {}) {
+                for await (const page of pages(query, init)) {
+                    yield* page.data;
+                }
+            },
+            get: (id, query = {}, init = {}) => request('GET', record(id), withSignal({ query: buildQuery(name, query) }, init)),
+            aggregate: (query, init = {}) => request('GET', `${collection}/_aggregate`, withSignal({ query: buildQuery(name, query) }, init)),
+            create: (body, opts = {}) => request('POST', collection, {
+                query: fieldsQuery(opts.fields),
+                body,
+                headers: writeHeaders(opts),
+            }),
+            update: (id, body, opts = {}) => request('PATCH', record(id), {
+                query: fieldsQuery(opts.fields),
+                body,
+                headers: writeHeaders(opts),
+            }),
+            delete: async (id, opts = {}) => {
+                const response = await request('DELETE', record(id), { headers: writeHeaders(opts) });
+                return { ...response, data: null };
+            },
+            operation: (id, operation, input, opts = {}) => runOperation(`${record(id)}/${encodeURIComponent(operationName(operation))}`, input, opts),
+            collectionOperation: (operation, input, opts = {}) => runOperation(`${collection}/_operations/${encodeURIComponent(operationName(operation))}`, input, opts),
+        };
+    };
+    return {
+        async capabilities(init = {}) {
+            const capabilities = (await request('GET', '/_capabilities', withSignal({}, init))).data;
+            return { ...capabilities, resources: capabilities.resources.map(normalizeResource) };
+        },
+        resources,
+        request,
+    };
+}
+/**
+ * PHP writes an empty map as `[]`: a resource without aggregatable fields or relations arrives with
+ * `aggregatable: []` and `relations: []`, and an operation without input fields with `input: []`.
+ * The types promise an object, so give one.
+ */
+function normalizeResource(resource) {
+    return {
+        ...resource,
+        operations: (resource.operations ?? []).map((operation) => ({
+            ...operation,
+            input: emptyListAsMap(operation.input),
+        })),
+        aggregatable: emptyListAsMap(resource.aggregatable),
+        relations: emptyListAsMap(resource.relations),
+    };
+}
+function emptyListAsMap(value) {
+    return Array.isArray(value) || value === undefined || value === null ? {} : value;
+}
+/** A fresh key for one logical POST. Reuse it only to retry that same request with that same body. */
+export function newIdempotencyKey() {
+    return crypto.randomUUID();
+}
+function operationName(name) {
+    if (name === '' || name.startsWith('_')) {
+        throw new TypeError(`'${name}' is not an operation name: the '_' namespace is reserved by the API.`);
+    }
+    if (isDotSegment(name)) {
+        throw new TypeError(`'${name}' is not an operation name: it would address another path.`);
+    }
+    return name;
+}
+/** encodeURIComponent keeps '.' as is, and '%2E' is decoded again by the URL parser, so both forms must go. */
+function isDotSegment(segment) {
+    return segment === '.' || segment === '..';
+}
+function writeHeaders(options) {
+    const headers = {};
+    if (options.idempotencyKey !== undefined) {
+        headers['Idempotency-Key'] = options.idempotencyKey;
+    }
+    if (options.ifMatch !== undefined) {
+        if (options.ifMatch.startsWith('W/')) {
+            // The API refuses a weak tag with 409 anyway; saying why here saves a round trip.
+            throw new TypeError('ifMatch takes recordVersion (X-Dmp-Record-Version), not the weak ETag.');
+        }
+        headers['If-Match'] = options.ifMatch;
+    }
+    return headers;
+}
+function withSignal(options, init) {
+    return init.signal === undefined ? options : { ...options, signal: init.signal };
+}
+async function readBody(response) {
+    const text = await response.text();
+    if (text === '') {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function isEnvelope(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) && 'data' in value;
+}
+function rateLimit(headers) {
+    const number = (name) => {
+        const value = headers.get(name);
+        return value === null || value === '' || !Number.isFinite(Number(value)) ? null : Number(value);
+    };
+    return {
+        limit: number('X-RateLimit-Limit'),
+        remaining: number('X-RateLimit-Remaining'),
+        reset: number('X-RateLimit-Reset'),
+    };
+}