@allisall/sdk 0.0.0-stage → 0.1.0

package/dist/errors.js

@@ -0,0 +1,98 @@
+/**
+ * The base of every error the SDK throws. Catch it to handle any SDK
+ * failure; catch `ApiError`, `ConnectionError` or `IngestError` to handle
+ * one condition.
+ */
+export class AllisallError extends Error {
+    name = "AllisallError";
+}
+/**
+ * An error response from the API, or a successful response whose body was
+ * not the expected shape. Branch on `code`; for a code you do not
+ * recognise, fall back on `status`.
+ */
+export class ApiError extends AllisallError {
+    name = "ApiError";
+    /** The HTTP status. */
+    status;
+    /** The problem's `code`. Absent when the body was not a problem document. */
+    code;
+    /** The whole problem document. Absent when the body was not one. */
+    problem;
+    /** The problem's `request_id`, or else the response's `X-Request-Id`. */
+    requestId;
+    /**
+     * The response's `Retry-After`, in milliseconds from when the response
+     * arrived. Absent when the response had none, or one that did not parse
+     * or named a time in the past.
+     */
+    retryAfter;
+    /** The response headers. */
+    headers;
+    constructor(init) {
+        super(init.message ?? apiErrorMessage(init.status, init.problem));
+        this.status = init.status;
+        this.problem = init.problem;
+        this.code = init.problem?.code;
+        const problemId = init.problem?.request_id;
+        this.requestId =
+            problemId !== undefined && problemId !== "" ? problemId : init.requestId;
+        this.retryAfter = init.retryAfter;
+        this.headers = init.headers;
+    }
+}
+function apiErrorMessage(status, problem) {
+    const parts = [`allisall: the API answered ${status}`];
+    if (problem?.code !== undefined)
+        parts.push(problem.code);
+    if (problem?.detail !== undefined)
+        parts.push(problem.detail);
+    return parts.join(": ");
+}
+/**
+ * A request that got no response: the connection failed, was reset, or the
+ * attempt timed out. `cause` holds the underlying error.
+ */
+export class ConnectionError extends AllisallError {
+    name = "ConnectionError";
+    /** The `X-Request-Id` the SDK sent on the last attempt, to quote when reporting it. */
+    requestId;
+    constructor(requestId, cause) {
+        super(`allisall: no response from the API (request ${requestId}): ${causeText(cause)}`, { cause });
+        this.requestId = requestId;
+    }
+}
+function causeText(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * A batch of an `ingest` call failed, so the call stopped and sent nothing
+ * after it. `cause` holds what failed the batch: an `ApiError`, a
+ * `ConnectionError`, the caller's cancellation, or the error from getting
+ * the token: the token provider's own error, unchanged, or the
+ * `AllisallError` refusing a provider's API key in a browser. To recover,
+ * send `remaining` again: every event in it keeps the `event_id` it was
+ * sent with, so any the failed batch stored come back as duplicates.
+ */
+export class IngestError extends AllisallError {
+    name = "IngestError";
+    /** The combined outcome of the batches that succeeded before the failed one. */
+    summary;
+    /**
+     * Copies of every event from the failed batch onward, each with its
+     * `event_id`, less any event too large to send: those are rows of
+     * `summary.errors` and never in `remaining`. To map `remaining` back to
+     * your list, walk it from `remainingFrom` and skip the `index` of every
+     * `summary.errors` row at or past `remainingFrom`. With no such row,
+     * `remaining[i]` is your event `remainingFrom + i`.
+     */
+    remaining;
+    /** The index, in the list passed to `ingest`, of the first event in `remaining`. */
+    remainingFrom;
+    constructor(cause, summary, remaining, remainingFrom) {
+        super(`allisall: an ingest batch failed and the call stopped; send the ${remaining.length} event(s) in remaining, from index ${remainingFrom}, again: ${causeText(cause)}`, { cause });
+        this.summary = summary;
+        this.remaining = remaining;
+        this.remainingFrom = remainingFrom;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Allisall, type ClientOptions, type RequestOptions } from "./client.js";
+export { type Decimal, decimal } from "./decimal.js";
+export { AllisallError, ApiError, ConnectionError, IngestError, } from "./errors.js";
+export type { FetchLike, TokenProvider } from "./transport.js";
+export type { ErrorCode, EventCategory, EventInput, FieldError, FieldErrorCode, IngestRowError, IngestSummary, Problem, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+// The public surface of @allisall/sdk.
+export { Allisall } from "./client.js";
+export { decimal } from "./decimal.js";
+export { AllisallError, ApiError, ConnectionError, IngestError, } from "./errors.js";

package/dist/ingest.d.ts

@@ -0,0 +1,28 @@
+import type { EventInput, IngestResult, IngestSummary } from "./types.js";
+/** The most events one batch holds. */
+export declare const MAX_BATCH_EVENTS = 500;
+/** The API's body limit for a batch, in bytes, inclusive. */
+export declare const MAX_BODY_BYTES = 5000000;
+/** The largest event that fits in a batch alone. */
+export declare const MAX_EVENT_BYTES: number;
+/** Sends one batch body of `count` events and resolves with the API's outcome for it. */
+export type SendBatch = (body: Uint8Array, count: number, signal: AbortSignal | undefined) => Promise<IngestResult>;
+/**
+ * Encodes one event as compact JSON. Every member the object holds is
+ * written, in its own order; a member set to `undefined` is omitted, as
+ * `JSON.stringify` omits it.
+ */
+export declare function encodeEvent(event: EventInput, index: number): string;
+/**
+ * Reads a `2xx` ingest body for a batch of `count` events as an
+ * `IngestResult`, or `undefined` when it is not one. A row error whose
+ * `index` is not a position in the batch makes the body unreadable, as a
+ * body of the wrong shape is.
+ */
+export declare function readIngestResult(value: unknown, count: number): IngestResult | undefined;
+/**
+ * Sends any number of events in as many batches as the limits require,
+ * one after another, and combines their outcomes. Stops at the first batch
+ * that fails, throwing an `IngestError`.
+ */
+export declare function ingest(events: readonly EventInput[], send: SendBatch, signal: AbortSignal | undefined): Promise<IngestSummary>;

package/dist/ingest.js

@@ -0,0 +1,247 @@
+// The ingest helper: assigning ids, serialising, splitting into batches,
+// sending them one at a time, and combining the outcomes.
+import { isDecimalText } from "./decimal.js";
+import { IngestError } from "./errors.js";
+import { uuidv4 } from "./uuid.js";
+/** The most events one batch holds. */
+export const MAX_BATCH_EVENTS = 500;
+/** The API's body limit for a batch, in bytes, inclusive. */
+export const MAX_BODY_BYTES = 5_000_000;
+/** The bytes of `{"events":[` and `]}` around a batch's events. */
+const ENVELOPE_BYTES = 13;
+/** The largest event that fits in a batch alone. */
+export const MAX_EVENT_BYTES = MAX_BODY_BYTES - ENVELOPE_BYTES;
+const encoder = new TextEncoder();
+const PREFIX = encoder.encode('{"events":[');
+const SUFFIX = encoder.encode("]}");
+const COMMA = 0x2c;
+// A UTF-16 surrogate without its partner, which UTF-8 cannot encode.
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+function checkText(text, index) {
+    if (LONE_SURROGATE.test(text)) {
+        throw new TypeError(`allisall: event ${index} holds text that is not valid Unicode (a lone surrogate)`);
+    }
+}
+/** `JSON.stringify`, refusing text that is not valid Unicode. */
+function stringify(value, index) {
+    const text = JSON.stringify(value, (key, inner) => {
+        checkText(key, index);
+        if (typeof inner === "string")
+            checkText(inner, index);
+        return inner;
+    });
+    return text;
+}
+const NUMERIC_MEMBERS = new Set([
+    "quantity",
+    "cost",
+    "tokens_in",
+    "tokens_out",
+]);
+function encodeMember(name, value, index) {
+    if (typeof value === "number" && NUMERIC_MEMBERS.has(name)) {
+        if (!Number.isFinite(value)) {
+            throw new TypeError(`allisall: event ${index} has ${name} ${value}; it must be a finite number`);
+        }
+        return JSON.stringify(value);
+    }
+    if (name === "cost" && typeof value === "string") {
+        // A Decimal is written unquoted, so its syntax is checked again here:
+        // an unbranded string from untyped code must not inject JSON.
+        if (!isDecimalText(value)) {
+            throw new TypeError(`allisall: event ${index} has cost ${JSON.stringify(value)}, which is not a decimal; build it with decimal()`);
+        }
+        return value;
+    }
+    if (name === "timestamp" && value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new TypeError(`allisall: event ${index} has an invalid Date as its timestamp`);
+        }
+        return JSON.stringify(value.toISOString());
+    }
+    return stringify(value, index);
+}
+/**
+ * Encodes one event as compact JSON. Every member the object holds is
+ * written, in its own order; a member set to `undefined` is omitted, as
+ * `JSON.stringify` omits it.
+ */
+export function encodeEvent(event, index) {
+    const members = [];
+    for (const [name, value] of Object.entries(event)) {
+        if (value === undefined)
+            continue;
+        const text = encodeMember(name, value, index);
+        if (text === undefined)
+            continue;
+        members.push(`${stringify(name, index)}:${text}`);
+    }
+    return `{${members.join(",")}}`;
+}
+function needsId(id) {
+    return id === undefined || id === null || id === "";
+}
+function prepare(events) {
+    return events.map((original, index) => {
+        if (typeof original !== "object" ||
+            original === null ||
+            Array.isArray(original)) {
+            throw new TypeError(`allisall: event ${index} is not an object`);
+        }
+        const event = { ...original };
+        if (needsId(event.event_id))
+            event.event_id = uuidv4();
+        return { index, event, bytes: encoder.encode(encodeEvent(event, index)) };
+    });
+}
+function tooLarge(p) {
+    return {
+        index: p.index,
+        code: "too_large",
+        pointer: `/events/${p.index}`,
+        detail: `The event serialises to ${p.bytes.length} bytes and was not sent. ` +
+            `The SDK sends an event of at most ${MAX_EVENT_BYTES} bytes, so that a batch holding it alone ` +
+            `stays within the API's body limit of ${MAX_BODY_BYTES} bytes.`,
+    };
+}
+/**
+ * Packs events into batches in input order. A batch closes at 500 events,
+ * or before an event that would take its body over 5,000,000 bytes. An
+ * event too large to send alone joins no batch and becomes a row error.
+ */
+function split(prepared) {
+    const batches = [];
+    const rejected = [];
+    let current;
+    for (const p of prepared) {
+        const size = p.bytes.length;
+        if (size > MAX_EVENT_BYTES) {
+            rejected.push(tooLarge(p));
+            continue;
+        }
+        if (current !== undefined &&
+            (current.events.length >= MAX_BATCH_EVENTS ||
+                current.size + 1 + size > MAX_BODY_BYTES)) {
+            current = undefined;
+        }
+        if (current === undefined) {
+            current = { events: [p], size: ENVELOPE_BYTES + size };
+            batches.push(current);
+        }
+        else {
+            current.events.push(p);
+            current.size += 1 + size;
+        }
+    }
+    return { batches, rejected };
+}
+/** Writes a batch as `{"events":[e1,e2,…,en]}`, reusing each event's bytes. */
+function body(batch) {
+    const out = new Uint8Array(batch.size);
+    out.set(PREFIX, 0);
+    let at = PREFIX.length;
+    batch.events.forEach((p, i) => {
+        if (i > 0)
+            out[at++] = COMMA;
+        out.set(p.bytes, at);
+        at += p.bytes.length;
+    });
+    out.set(SUFFIX, at);
+    return out;
+}
+const POINTER_ROW = /^\/events\/(\d+)(?=\/|$)/;
+/** Rewrites a batch's row error to the caller's list. */
+function rewrite(error, batch) {
+    const toCaller = (i) => batch.events[i]?.index ?? i;
+    const pointer = error.pointer.replace(POINTER_ROW, (_, row) => `/events/${toCaller(Number(row))}`);
+    return { ...error, index: toCaller(error.index), pointer };
+}
+/**
+ * Reads a `2xx` ingest body for a batch of `count` events as an
+ * `IngestResult`, or `undefined` when it is not one. A row error whose
+ * `index` is not a position in the batch makes the body unreadable, as a
+ * body of the wrong shape is.
+ */
+export function readIngestResult(value, count) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const accepted = Reflect.get(value, "accepted");
+    const duplicates = Reflect.get(value, "duplicates");
+    const rejected = Reflect.get(value, "rejected");
+    const errors = Reflect.get(value, "errors");
+    const truncated = Reflect.get(value, "errors_truncated");
+    if (typeof accepted !== "number" ||
+        typeof duplicates !== "number" ||
+        typeof rejected !== "number" ||
+        typeof truncated !== "boolean" ||
+        !Array.isArray(errors)) {
+        return undefined;
+    }
+    const rows = [];
+    for (const e of errors) {
+        if (typeof e !== "object" || e === null)
+            return undefined;
+        const index = Reflect.get(e, "index");
+        const code = Reflect.get(e, "code");
+        const pointer = Reflect.get(e, "pointer");
+        const detail = Reflect.get(e, "detail");
+        if (typeof index !== "number" ||
+            typeof code !== "string" ||
+            typeof pointer !== "string" ||
+            typeof detail !== "string") {
+            return undefined;
+        }
+        if (!Number.isInteger(index) || index < 0 || index >= count) {
+            return undefined;
+        }
+        rows.push({ index, code, pointer, detail });
+    }
+    return {
+        accepted,
+        duplicates,
+        rejected,
+        errors: rows,
+        errors_truncated: truncated,
+    };
+}
+/**
+ * Sends any number of events in as many batches as the limits require,
+ * one after another, and combines their outcomes. Stops at the first batch
+ * that fails, throwing an `IngestError`.
+ */
+export async function ingest(events, send, signal) {
+    const { batches, rejected } = split(prepare(events));
+    const summary = {
+        accepted: 0,
+        duplicates: 0,
+        rejected: rejected.length,
+        errors: [...rejected],
+        errors_truncated: false,
+        batches: 0,
+    };
+    const finish = () => {
+        // Stable, so a row's entries keep the order the API gave them.
+        summary.errors.sort((a, b) => a.index - b.index);
+        return summary;
+    };
+    for (const [i, batch] of batches.entries()) {
+        let result;
+        try {
+            result = await send(body(batch), batch.events.length, signal);
+        }
+        catch (err) {
+            // Every failure of a batch is wrapped, the token provider's included,
+            // so the caller keeps the summary and the generated ids in remaining.
+            const remaining = batches.slice(i).flatMap((b) => b.events);
+            throw new IngestError(err, finish(), remaining.map((p) => p.event), remaining[0]?.index ?? 0);
+        }
+        summary.accepted += result.accepted;
+        summary.duplicates += result.duplicates;
+        summary.rejected += result.rejected;
+        summary.errors_truncated ||= result.errors_truncated;
+        for (const error of result.errors)
+            summary.errors.push(rewrite(error, batch));
+        summary.batches++;
+    }
+    return finish();
+}

package/dist/retry.d.ts

@@ -0,0 +1,18 @@
+/** The longest `Retry-After` the SDK honours. A longer one ends the call. */
+export declare const MAX_RETRY_AFTER_MS = 60000;
+/** The statuses worth repeating: a proxy's `408`, `429`, `500`, and a gateway's `502`, `503`, `504`. */
+export declare function isRetryableStatus(status: number): boolean;
+/**
+ * The wait before retry `n` (1 for the first retry) when the response
+ * carried no usable `Retry-After`: `min(0.5 s × 2^(n−1), 8 s)`, multiplied
+ * by a random factor between 0.75 and 1.
+ */
+export declare function backoffMs(retry: number): number;
+/**
+ * Parses a `Retry-After` value, delay-seconds or an HTTP-date (RFC 9110
+ * §10.2.3), into milliseconds from `now`. Returns `undefined` for a value
+ * that does not parse or names a time in the past.
+ */
+export declare function parseRetryAfter(value: string | null, now: number): number | undefined;
+/** Waits `ms` milliseconds, or rejects with the signal's reason when it aborts first. */
+export declare function sleep(ms: number, signal: AbortSignal | undefined): Promise<void>;

package/dist/retry.js

@@ -0,0 +1,105 @@
+// The retry decision and the wait between attempts.
+/** The longest `Retry-After` the SDK honours. A longer one ends the call. */
+export const MAX_RETRY_AFTER_MS = 60_000;
+const INITIAL_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 8_000;
+/** The statuses worth repeating: a proxy's `408`, `429`, `500`, and a gateway's `502`, `503`, `504`. */
+export function isRetryableStatus(status) {
+    return (status === 408 ||
+        status === 429 ||
+        status === 500 ||
+        status === 502 ||
+        status === 503 ||
+        status === 504);
+}
+/**
+ * The wait before retry `n` (1 for the first retry) when the response
+ * carried no usable `Retry-After`: `min(0.5 s × 2^(n−1), 8 s)`, multiplied
+ * by a random factor between 0.75 and 1.
+ */
+export function backoffMs(retry) {
+    const base = Math.min(INITIAL_BACKOFF_MS * 2 ** (retry - 1), MAX_BACKOFF_MS);
+    return base * (1 - Math.random() * 0.25);
+}
+const MONTHS = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+];
+// RFC 9110 §5.6.7: IMF-fixdate, and the two obsolete forms a recipient must accept.
+const IMF_FIXDATE = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (\d{2}) ([A-Z][a-z]{2}) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
+const RFC850_DATE = /^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\d{2})-([A-Z][a-z]{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
+const ASCTIME_DATE = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) ([A-Z][a-z]{2}) ([ \d]\d) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/;
+function utc(year, month, day, hour, minute, second) {
+    const m = MONTHS.indexOf(month);
+    if (m < 0)
+        return undefined;
+    const ms = Date.UTC(year, m, Number(day.trim()), Number(hour), Number(minute), Number(second));
+    return Number.isNaN(ms) ? undefined : ms;
+}
+function parseHttpDate(value, now) {
+    let match = IMF_FIXDATE.exec(value);
+    if (match !== null) {
+        const [, day = "", month = "", year = "", h = "", m = "", s = ""] = match;
+        return utc(Number(year), month, day, h, m, s);
+    }
+    match = RFC850_DATE.exec(value);
+    if (match !== null) {
+        const [, day = "", month = "", yy = "", h = "", m = "", s = ""] = match;
+        // RFC 9110 §5.6.7: a two-digit year more than 50 years in the future is in the past century.
+        const thisYear = new Date(now).getUTCFullYear();
+        let year = 2000 + Number(yy);
+        if (year > thisYear + 50)
+            year -= 100;
+        return utc(year, month, day, h, m, s);
+    }
+    match = ASCTIME_DATE.exec(value);
+    if (match !== null) {
+        const [, month = "", day = "", h = "", m = "", s = "", year = ""] = match;
+        return utc(Number(year), month, day, h, m, s);
+    }
+    return undefined;
+}
+/**
+ * Parses a `Retry-After` value, delay-seconds or an HTTP-date (RFC 9110
+ * §10.2.3), into milliseconds from `now`. Returns `undefined` for a value
+ * that does not parse or names a time in the past.
+ */
+export function parseRetryAfter(value, now) {
+    if (value === null)
+        return undefined;
+    const text = value.trim();
+    if (/^\d+$/.test(text))
+        return Number(text) * 1000;
+    const at = parseHttpDate(text, now);
+    if (at === undefined || at < now)
+        return undefined;
+    return at - now;
+}
+/** Waits `ms` milliseconds, or rejects with the signal's reason when it aborts first. */
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/runtime.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reports whether the SDK runs in a browser: a window, where `document`
+ * is defined, or a Web Worker, where `globalThis` is an instance of
+ * `WorkerGlobalScope`. Node, Deno, Bun and edge runtimes define neither.
+ */
+export declare function isBrowser(): boolean;
+/**
+ * Reads an environment variable from `globalThis.process.env`, where it
+ * exists. Returns `undefined` for a variable that is unset or empty.
+ */
+export declare function readEnv(name: string): string | undefined;
+/**
+ * The `User-Agent` to send: `allisall-ts/<version> node/<node version>`.
+ * A server runtime that reports no Node version, such as an edge runtime,
+ * sends `allisall-ts/<version>` alone. A browser sends none.
+ */
+export declare function userAgent(): string | undefined;

package/dist/runtime.js

@@ -0,0 +1,60 @@
+// What the SDK learns about the runtime it runs in: whether it is a
+// browser, the environment, and the User-Agent. Globals are read through
+// `globalThis` by name, so a runtime without them, such as a browser
+// without `process`, is never touched.
+import { VERSION } from "./version.js";
+function globalValue(name) {
+    const value = Reflect.get(globalThis, name);
+    return value;
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Reports whether the SDK runs in a browser: a window, where `document`
+ * is defined, or a Web Worker, where `globalThis` is an instance of
+ * `WorkerGlobalScope`. Node, Deno, Bun and edge runtimes define neither.
+ */
+export function isBrowser() {
+    if (globalValue("document") !== undefined)
+        return true;
+    const scope = globalValue("WorkerGlobalScope");
+    return typeof scope === "function" && globalThis instanceof scope;
+}
+/**
+ * Reads an environment variable from `globalThis.process.env`, where it
+ * exists. Returns `undefined` for a variable that is unset or empty.
+ */
+export function readEnv(name) {
+    const process = globalValue("process");
+    if (!isObject(process))
+        return undefined;
+    const env = Reflect.get(process, "env");
+    if (!isObject(env))
+        return undefined;
+    const value = Reflect.get(env, name);
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+function nodeVersion() {
+    const process = globalValue("process");
+    if (!isObject(process))
+        return undefined;
+    const versions = Reflect.get(process, "versions");
+    if (!isObject(versions))
+        return undefined;
+    const node = Reflect.get(versions, "node");
+    return typeof node === "string" && node !== "" ? node : undefined;
+}
+/**
+ * The `User-Agent` to send: `allisall-ts/<version> node/<node version>`.
+ * A server runtime that reports no Node version, such as an edge runtime,
+ * sends `allisall-ts/<version>` alone. A browser sends none.
+ */
+export function userAgent() {
+    if (isBrowser())
+        return undefined;
+    const node = nodeVersion();
+    return node === undefined
+        ? `allisall-ts/${VERSION}`
+        : `allisall-ts/${VERSION} node/${node}`;
+}

package/dist/transport.d.ts

@@ -0,0 +1,53 @@
+import type { Problem } from "./types.js";
+/** A `fetch`-compatible function. */
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+/** A callback returning the bearer token to send, called before every attempt. */
+export type TokenProvider = () => string | Promise<string>;
+/** Where the bearer token comes from. */
+export type Credential = {
+    readonly kind: "apiKey";
+    readonly apiKey: string;
+} | {
+    readonly kind: "provider";
+    readonly provider: TokenProvider;
+};
+/** Everything an attempt needs, fixed when the client is constructed. */
+export interface TransportConfig {
+    readonly baseURL: URL;
+    readonly credential: Credential;
+    readonly timeout: number;
+    readonly maxRetries: number;
+    readonly fetch: FetchLike | undefined;
+    /** Whether a token that is an API key is refused: a browser without the opt-in. */
+    readonly refuseApiKeys: boolean;
+    /** The `User-Agent` to send; `undefined` in a browser. */
+    readonly userAgent: string | undefined;
+}
+/** The message of the error refusing an API key in a browser. */
+export declare const BROWSER_KEY_MESSAGE: string;
+/** Reports whether a bearer token is an API key, which starts `aia_`. */
+export declare function isApiKey(token: string): boolean;
+/** Joins the base URL and an operation's path with exactly one `/`. */
+export declare function joinURL(base: URL, path: string): string;
+/**
+ * Reports whether every character of a credential, already trimmed, is
+ * printable ASCII (U+0021 to U+007E), as a bearer credential is. Anything
+ * else, a control character, an inner space or a non-ASCII character,
+ * cannot travel in the header. The check never quotes the credential, so
+ * no error built from it can leak the secret.
+ */
+export declare function isPrintableCredential(credential: string): boolean;
+/**
+ * Reads an `application/problem+json` body as a problem document. Returns
+ * `undefined` for any other body, or one that is not a JSON object. A
+ * member of the wrong type is left out on its own, as is a malformed
+ * entry of `errors`; the rest of the problem is kept. Members the SDK does
+ * not know are ignored.
+ */
+export declare function readProblem(contentType: string | null, text: string): Problem | undefined;
+/**
+ * Posts a JSON body, retrying a failure worth repeating. The body is the
+ * same bytes on every attempt. Each attempt reads a fresh token and sends
+ * a fresh `X-Request-Id`.
+ */
+export declare function post<T>(config: TransportConfig, path: string, body: Uint8Array, read: (body: unknown) => T | undefined, signal: AbortSignal | undefined): Promise<T>;