@allisall/sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,10 @@
-export { Allisall, type ClientOptions, type RequestOptions } from "./client.js";
+export { Allisall, type ClientOptions } from "./client.js";
 export { type Decimal, decimal } from "./decimal.js";
 export { AllisallError, ApiError, ConnectionError, IngestError, } from "./errors.js";
+export type { MoneyInput } from "./money.js";
+export type { ImportUpload } from "./multipart.js";
+export type { IdempotentRequestOptions, RequestOptions } from "./options.js";
+export type { Page, PagePromise } from "./pagination.js";
+export { getSharedReport, type SharedReportOptions } from "./share.js";
 export type { FetchLike, TokenProvider } from "./transport.js";
-export type { ErrorCode, EventCategory, EventInput, FieldError, FieldErrorCode, IngestRowError, IngestSummary, Problem, } from "./types.js";
+export type { Agent, AgentCostLine, AgentCreate, AgentDetail, AgentList, AgentListItem, AgentPatch, AgentStats, AgentStatus, Anomalies, ApiKey, ApiKeyCreate, ApiKeyList, ApiKeyWithToken, AssignedAgent, AttributedEvent, Calculation, CalculationCreate, CalculationList, CalculationSnapshot, CalculationState, CalculationSummary, Checklist, ChecklistInput, Client, ClientAgents, ClientAgentsSet, ClientCost, ClientCreate, ClientDetail, ClientEventList, ClientList, ClientPatch, ClientStatus, ClientValue, CostCoverage, CostLineItem, CostLineItemCreate, CostLineItemList, CostLineItemPatch, CostResult, CostTarget, CostTargetInput, CostTargetKind, Dashboard, Disclosure, DisclosureEdit, DisclosureKind, ErrorCode, EventCategory, EventInput, EventSource, FieldError, FieldErrorCode, GetAgentQuery, GetClientAnomaliesQuery, GetClientCostQuery, GetClientRoiQuery, GetClientValueQuery, GetDashboardQuery, Health, HealthDirection, HealthUnavailable, ImportMapping, ImportPreview, ImportResult, ImportRowError, IngestRowError, IngestSummary, ListAgentsQuery, ListApiKeysQuery, ListCalculationReportsQuery, ListClientCalculationsQuery, ListClientEventsQuery, ListClientOutcomeTypesQuery, ListClientsQuery, ListCostLineItemsQuery, ListOutcomeTypesQuery, ListRenewalsQuery, ListValueModelsQuery, ListValueTemplatesQuery, ManualCostLine, ModelRate, ModelRateInput, OutcomeTypeList, OutcomeTypeUsage, Period, PeriodInput, PortfolioClient, PortfolioExclusionReason, PreviewEvent, PreviewRow, PriceTable, PriceTableSet, Problem, PublicReport, Ratios, Renewal, RenewalList, Report, ReportList, ReportPatch, ReportSummary, ReportWithPreview, RoiResult, Scope, TokenCostLine, UnattributedLineItem, UndefinedReason, ValueCoverage, ValueLine, ValueLineItem, ValueLineItemInput, ValueLineItemsSet, ValueModel, ValueModelCreate, ValueModelList, ValueModelPatch, ValueModelRef, ValueModelStatus, ValueModelSummary, ValueResult, ValueTemplate, ValueTemplateLineItem, ValueTemplateList, } from "./types.js";

package/dist/index.js

@@ -2,3 +2,4 @@
 export { Allisall } from "./client.js";
 export { decimal } from "./decimal.js";
 export { AllisallError, ApiError, ConnectionError, IngestError, } from "./errors.js";
+export { getSharedReport } from "./share.js";

package/dist/ingest.d.ts

@@ -2,7 +2,7 @@ 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;
+export declare const MAX_BODY_BYTES = 4000000;
 /** 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. */

package/dist/ingest.js

@@ -6,7 +6,7 @@ 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;
+export const MAX_BODY_BYTES = 4_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. */
@@ -106,7 +106,7 @@ function tooLarge(p) {
 }
 /**
  * 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
+ * or before an event that would take its body over 4,000,000 bytes. An
  * event too large to send alone joins no batch and becomes a row error.
  */
 function split(prepared) {

package/dist/money.d.ts

@@ -0,0 +1,57 @@
+import { type Decimal } from "./decimal.js";
+import { type JsonPath } from "./generated/operations.js";
+/**
+ * A request type with every `Decimal` in it widened to `Decimal | number`:
+ * what a request accepts where the API takes money. Use it to type a body
+ * you build before passing it to a method, such as
+ * `MoneyInput<CostLineItemCreate>`.
+ *
+ * A `Decimal`, such as one read from an earlier response, is sent with its
+ * own digits. A `number` is sent as its shortest round-trip text, so a
+ * literal such as `12.5` is sent exactly; a computed float such as
+ * `0.1 + 0.2` is sent as `0.30000000000000004`, which the API refuses as
+ * too precise rather than storing it inexactly. Build a `Decimal` with
+ * `decimal()` when the amount must be exact.
+ */
+export type MoneyInput<T> = T extends Decimal ? Decimal | number : T extends Date ? T : T extends (infer U)[] ? MoneyInput<U>[] : T extends object ? {
+    [K in keyof T]: MoneyInput<T[K]>;
+} : T;
+/**
+ * The largest exponent magnitude the decoder writes out in digits. Money is
+ * far smaller; the bound keeps a hostile exponent from building a huge
+ * string.
+ */
+export declare const MAX_EXPONENT = 400;
+/**
+ * The text of a `Decimal` equal to a JSON number's text. A number in
+ * exponent form, such as `1e-7`, is written out in digits; the conversion
+ * moves the decimal point and never rounds.
+ *
+ * @throws {AllisallError} when the exponent's magnitude exceeds
+ * `MAX_EXPONENT`.
+ */
+export declare function decimalOfJsonNumber(text: string): Decimal | undefined;
+/**
+ * Parses a response body. Every number at one of `moneyPaths` becomes a
+ * `Decimal` of the number's text; every other number becomes the `number`
+ * `JSON.parse` would give. A `null` stays `null`.
+ *
+ * @throws {SyntaxError} when `text` is not JSON.
+ * @throws {AllisallError} when the body holds money and the runtime does not
+ * give a reviver a number's text.
+ */
+export declare function decodeJson(text: string, moneyPaths: readonly JsonPath[]): unknown;
+/**
+ * Serialises a request body. At each of `moneyPaths`, a `Decimal` is
+ * written as its own digits and a `number` as its shortest round-trip text.
+ * The caller's object is not changed. Every member it holds is written, as
+ * `JSON.stringify` writes it.
+ *
+ * @throws {TypeError} when a value at a money path is not a `Decimal`, a
+ * finite number or `null`; when any value is an invalid `Date`, a
+ * non-finite number, or text holding a lone surrogate, naming its path; or
+ * when the body has no JSON text, such as `undefined`.
+ * @throws {AllisallError} when the body holds a `Decimal` and the runtime has
+ * no `JSON.rawJSON`.
+ */
+export declare function encodeJson(body: unknown, moneyPaths: readonly JsonPath[]): string;

package/dist/money.js

@@ -0,0 +1,284 @@
+// Exact money in JSON bodies. A `Money` value is a JSON number on the wire.
+// The SDK never lets a binary float hold one: a response's money is decoded
+// from the number's own text into a `Decimal`, and a request's `Decimal` is
+// written as its own text.
+//
+// Both directions work from an operation's `Money` paths, from the operation
+// table. A path, not a member's name, decides whether a number is money:
+// `total` is money in one schema and a count in another.
+//
+// Two platform features make this possible, and TypeScript's own library
+// files declare neither, so this module declares the shapes it reads:
+//
+// - The third argument a `JSON.parse` reviver receives, whose `source` is a
+//   number's text as it appeared in the JSON.
+// - `JSON.rawJSON(text)`, whose result `JSON.stringify` writes as `text`,
+//   unquoted.
+//
+// Both arrived in Chrome 114, Firefox 135, Safari 18.4 and Node 21. Without
+// them, money cannot be handled exactly, and the SDK refuses rather than
+// fall back on a float.
+import { isDecimalText } from "./decimal.js";
+import { AllisallError } from "./errors.js";
+import { ITEMS } from "./generated/operations.js";
+import { hasLoneSurrogate } from "./unicode.js";
+const trees = new WeakMap();
+function treeOf(paths) {
+    const cached = trees.get(paths);
+    if (cached !== undefined)
+        return cached;
+    const root = { money: false, children: new Map() };
+    for (const path of paths) {
+        let node = root;
+        for (const segment of path) {
+            let child = node.children.get(segment);
+            if (child === undefined) {
+                child = { money: false, children: new Map() };
+                node.children.set(segment, child);
+            }
+            node = child;
+        }
+        node.money = true;
+    }
+    trees.set(paths, root);
+    return root;
+}
+function childOf(node, segment) {
+    return node?.children.get(segment);
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+// ---- Decoding a response ----
+/**
+ * A JSON number as the first pass of decoding leaves it: its value, and its
+ * text when the runtime supplied it.
+ */
+class JsonNumber {
+    value;
+    source;
+    constructor(value, source) {
+        this.value = value;
+        this.source = source;
+    }
+}
+/** The text of the number a reviver was called with, when the runtime supplies it. */
+function sourceText(context) {
+    if (typeof context !== "object" || context === null)
+        return undefined;
+    const source = Reflect.get(context, "source");
+    return typeof source === "string" ? source : undefined;
+}
+function keepNumberText(_key, value, context) {
+    return typeof value === "number"
+        ? new JsonNumber(value, sourceText(context))
+        : value;
+}
+/**
+ * The largest exponent magnitude the decoder writes out in digits. Money is
+ * far smaller; the bound keeps a hostile exponent from building a huge
+ * string.
+ */
+export const MAX_EXPONENT = 400;
+const JSON_NUMBER = /^(-?)(0|[1-9][0-9]*)(?:\.([0-9]+))?(?:[eE]([+-]?[0-9]+))?$/;
+/**
+ * The text of a `Decimal` equal to a JSON number's text. A number in
+ * exponent form, such as `1e-7`, is written out in digits; the conversion
+ * moves the decimal point and never rounds.
+ *
+ * @throws {AllisallError} when the exponent's magnitude exceeds
+ * `MAX_EXPONENT`.
+ */
+export function decimalOfJsonNumber(text) {
+    if (isDecimalText(text)) {
+        // The syntax check is the invariant the brand stands for.
+        return text;
+    }
+    const match = JSON_NUMBER.exec(text);
+    if (match === null)
+        return undefined;
+    const [, sign = "", whole = "", fraction = "", exponent = "0"] = match;
+    const digits = whole + fraction;
+    const shift = Number(exponent);
+    if (!(Math.abs(shift) <= MAX_EXPONENT)) {
+        throw new AllisallError(`allisall: the API sent money as ${JSON.stringify(text)}, whose exponent is beyond ±${MAX_EXPONENT}`);
+    }
+    const point = whole.length + shift;
+    let out;
+    if (point <= 0)
+        out = `0.${"0".repeat(-point)}${digits}`;
+    else if (point >= digits.length)
+        out = digits + "0".repeat(point - digits.length);
+    else
+        out = `${digits.slice(0, point)}.${digits.slice(point)}`;
+    // Moving the point can leave leading zeros in the whole part, as `0.5e1`
+    // becomes `05`.
+    out = out.replace(/^0+(?=[0-9])/, "");
+    const result = sign + out;
+    // Every branch above writes decimal text; the check keeps the brand honest.
+    return isDecimalText(result) ? result : undefined;
+}
+function place(value, node) {
+    if (value instanceof JsonNumber) {
+        if (node?.money !== true)
+            return value.value;
+        if (value.source === undefined) {
+            throw new AllisallError("allisall: this runtime does not give a JSON.parse reviver the source text of a number (the reviver's context argument), so the money in this response cannot be read exactly; use Node 21 or later, Chrome 114, Firefox 135 or Safari 18.4 or later");
+        }
+        const amount = decimalOfJsonNumber(value.source);
+        if (amount === undefined) {
+            throw new AllisallError(`allisall: the API sent money as ${JSON.stringify(value.source)}, which is not a decimal number`);
+        }
+        return amount;
+    }
+    if (Array.isArray(value)) {
+        const items = childOf(node, ITEMS);
+        for (let i = 0; i < value.length; i++)
+            value[i] = place(value[i], items);
+        return value;
+    }
+    if (typeof value === "object" && value !== null) {
+        for (const key of Object.keys(value)) {
+            Reflect.set(value, key, place(Reflect.get(value, key), childOf(node, key)));
+        }
+    }
+    return value;
+}
+/**
+ * Parses a response body. Every number at one of `moneyPaths` becomes a
+ * `Decimal` of the number's text; every other number becomes the `number`
+ * `JSON.parse` would give. A `null` stays `null`.
+ *
+ * @throws {SyntaxError} when `text` is not JSON.
+ * @throws {AllisallError} when the body holds money and the runtime does not
+ * give a reviver a number's text.
+ */
+export function decodeJson(text, moneyPaths) {
+    const parsed = JSON.parse(text, keepNumberText);
+    return place(parsed, treeOf(moneyPaths));
+}
+// ---- Encoding a request ----
+/** `JSON.rawJSON`, when the runtime has it. */
+function rawJson() {
+    const fn = Reflect.get(JSON, "rawJSON");
+    if (typeof fn !== "function")
+        return undefined;
+    return (text) => Reflect.apply(fn, JSON, [text]);
+}
+function kindOf(value) {
+    if (Array.isArray(value))
+        return "an array";
+    return typeof value === "object" ? "an object" : `a ${typeof value}`;
+}
+function encodeMoney(value, path) {
+    const where = path.length === 0 ? "the body" : `/${path.join("/")}`;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new TypeError(`allisall: the money at ${where} is ${value}; it must be a finite number`);
+        }
+        return value;
+    }
+    // A money member may be nullable; an absent or undefined one is not sent.
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value !== "string") {
+        throw new TypeError(`allisall: the money at ${where} is ${kindOf(value)}; it must be a Decimal, a finite number or null`);
+    }
+    if (!isDecimalText(value)) {
+        throw new TypeError(`allisall: the money at ${where} is ${JSON.stringify(value)}, which is not a decimal; build it with decimal()`);
+    }
+    const raw = rawJson();
+    if (raw === undefined) {
+        throw new AllisallError("allisall: this runtime has no JSON.rawJSON, so a Decimal cannot be sent exactly; use Node 21 or later, Chrome 114, Firefox 135 or Safari 18.4 or later");
+    }
+    return raw(value);
+}
+function copyAlong(value, node, path) {
+    if (node.money)
+        return encodeMoney(value, path);
+    if (Array.isArray(value)) {
+        const items = node.children.get(ITEMS);
+        if (items === undefined)
+            return value;
+        return value.map((item, i) => copyAlong(item, items, [...path, String(i)]));
+    }
+    if (isPlainObject(value)) {
+        const copy = {};
+        for (const [key, member] of Object.entries(value)) {
+            const child = node.children.get(key);
+            const written = child === undefined ? member : copyAlong(member, child, [...path, key]);
+            Object.defineProperty(copy, key, {
+                value: written,
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        }
+        return copy;
+    }
+    return value;
+}
+/**
+ * A `JSON.stringify` replacer refusing the values it would write as `null`
+ * in silence: an invalid `Date`, and a non-finite number. On a merge patch,
+ * `null` clears a member, so either would change data the caller never
+ * meant to touch. It also refuses text holding a lone surrogate, in a
+ * string or a member name, which the API would store as U+FFFD.
+ *
+ * A replacer sees a member's key and its holder, not its path, so each
+ * object's path is recorded as it is reached, before its members are.
+ */
+function refuseLostValues() {
+    const paths = new WeakMap();
+    return function (key, value) {
+        const holder = typeof this === "object" && this !== null ? this : undefined;
+        const parent = holder === undefined ? undefined : paths.get(holder);
+        // The root's holder is the wrapper JSON.stringify makes, never recorded.
+        // A name is checked before it joins a path, so no message carries it.
+        if (parent !== undefined && hasLoneSurrogate(key)) {
+            throw new TypeError(`allisall: a member name in the object at ${parent === "" ? "the body" : parent} is not valid Unicode (a lone surrogate)`);
+        }
+        const path = parent === undefined ? "" : `${parent}/${key}`;
+        const where = path === "" ? "the body" : path;
+        // The value has been through toJSON already; the holder keeps the Date.
+        const original = holder === undefined ? value : Reflect.get(holder, key);
+        if (original instanceof Date && Number.isNaN(original.getTime())) {
+            throw new TypeError(`allisall: the value at ${where} is an invalid Date`);
+        }
+        if (typeof value === "number" && !Number.isFinite(value)) {
+            throw new TypeError(`allisall: the value at ${where} is ${value}; it must be a finite number`);
+        }
+        if (typeof value === "string" && hasLoneSurrogate(value)) {
+            throw new TypeError(`allisall: the value at ${where} is not valid Unicode (a lone surrogate)`);
+        }
+        if (typeof value === "object" && value !== null)
+            paths.set(value, path);
+        return value;
+    };
+}
+/**
+ * Serialises a request body. At each of `moneyPaths`, a `Decimal` is
+ * written as its own digits and a `number` as its shortest round-trip text.
+ * The caller's object is not changed. Every member it holds is written, as
+ * `JSON.stringify` writes it.
+ *
+ * @throws {TypeError} when a value at a money path is not a `Decimal`, a
+ * finite number or `null`; when any value is an invalid `Date`, a
+ * non-finite number, or text holding a lone surrogate, naming its path; or
+ * when the body has no JSON text, such as `undefined`.
+ * @throws {AllisallError} when the body holds a `Decimal` and the runtime has
+ * no `JSON.rawJSON`.
+ */
+export function encodeJson(body, moneyPaths) {
+    const copy = copyAlong(body, treeOf(moneyPaths), []);
+    // JSON.stringify gives undefined, despite its declared type, for a body
+    // with no JSON text: undefined, a function or a symbol.
+    const text = JSON.stringify(copy, refuseLostValues());
+    if (typeof text !== "string") {
+        throw new TypeError(`allisall: a request body of type ${typeof body} has no JSON text`);
+    }
+    return text;
+}

package/dist/multipart.d.ts

@@ -0,0 +1,27 @@
+import type { components } from "./generated/openapi.js";
+/** A CSV upload: the mapping of its columns, and the file itself. */
+export interface ImportUpload {
+    /** How the file's columns map to event members, sent as the first part. */
+    mapping: components["schemas"]["ImportMapping"];
+    /**
+     * The CSV file, sent as the second part with the type `text/csv`. A
+     * `Blob` is sent without being read into memory first; in Node,
+     * `fs.openAsBlob(path)` gives one for a file on disk. A stream is not
+     * accepted, because a retry must send the same bytes again.
+     */
+    file: Blob | Uint8Array | string;
+    /**
+     * The file name the import records. Defaults to the name of a `File`, and
+     * otherwise to `upload.csv`; an empty name counts as none.
+     */
+    filename?: string | undefined;
+}
+/**
+ * Builds the form once, `mapping` before `file`, as the API reads them. The
+ * same form is the body of every attempt.
+ *
+ * @throws {TypeError} when the upload is not an object, the mapping has no
+ * JSON text, or the file is not a `Blob`, a `Uint8Array` or a string, or
+ * is a string holding a lone surrogate.
+ */
+export declare function formOf(upload: ImportUpload): FormData;

package/dist/multipart.js

@@ -0,0 +1,48 @@
+// A CSV import's body: a form of two parts, the mapping and then the file.
+import { encodeJson } from "./money.js";
+import { hasLoneSurrogate } from "./unicode.js";
+const DEFAULT_FILENAME = "upload.csv";
+function nameOf(file) {
+    const name = Reflect.get(file, "name");
+    return typeof name === "string" && name !== "" ? name : undefined;
+}
+/**
+ * Builds the form once, `mapping` before `file`, as the API reads them. The
+ * same form is the body of every attempt.
+ *
+ * @throws {TypeError} when the upload is not an object, the mapping has no
+ * JSON text, or the file is not a `Blob`, a `Uint8Array` or a string, or
+ * is a string holding a lone surrogate.
+ */
+export function formOf(upload) {
+    if (typeof upload !== "object" || upload === null) {
+        throw new TypeError("allisall: an import takes an object with mapping and file");
+    }
+    const { mapping, file, filename } = upload;
+    const mappingPart = new Blob([encodeJson(mapping, [])], {
+        type: "application/json",
+    });
+    let filePart;
+    let defaultName = DEFAULT_FILENAME;
+    if (file instanceof Blob) {
+        // A File keeps its own name; its type is set to the one the API reads.
+        defaultName = nameOf(file) ?? DEFAULT_FILENAME;
+        filePart = new Blob([file], { type: "text/csv" });
+    }
+    else if (file instanceof Uint8Array || typeof file === "string") {
+        // A Blob writes a lone surrogate as U+FFFD, changing the file in silence.
+        if (typeof file === "string" && hasLoneSurrogate(file)) {
+            throw new TypeError("allisall: the import's file is not valid Unicode (a lone surrogate)");
+        }
+        filePart = new Blob([file], { type: "text/csv" });
+    }
+    else {
+        throw new TypeError("allisall: an import's file must be a Blob, a Uint8Array or a string; a stream cannot be sent again on a retry");
+    }
+    const form = new FormData();
+    form.append("mapping", mappingPart, "mapping.json");
+    // An empty name falls back, as a File with no name does.
+    const name = typeof filename === "string" && filename !== "" ? filename : defaultName;
+    form.append("file", filePart, name);
+    return form;
+}

package/dist/options.d.ts

@@ -0,0 +1,50 @@
+/** The options of one call. Each member left out takes the client's. */
+export interface RequestOptions {
+    /** Cancels the call, including any wait between retries. */
+    signal?: AbortSignal | undefined;
+    /** The timeout of each attempt of this call, in milliseconds. */
+    timeout?: number | undefined;
+    /**
+     * How many times this call is retried. It cannot make a request eligible
+     * that the SDK never retries, such as a `PATCH`.
+     */
+    maxRetries?: number | undefined;
+    /**
+     * Extra headers for this call, sent over the client's `defaultHeaders`.
+     * They may not name `Authorization`, `Content-Type`, `Idempotency-Key` or
+     * `X-Request-Id`, which the SDK sets. In a browser, a header must be one
+     * the API's CORS policy allows.
+     */
+    headers?: Readonly<Record<string, string>> | undefined;
+}
+/** The options of a call that creates something and takes an `Idempotency-Key`. */
+export interface IdempotentRequestOptions extends RequestOptions {
+    /**
+     * The `Idempotency-Key` to send, as given. By default the SDK generates
+     * one per call and sends it on every attempt of that call. Set your own
+     * to make a create safe to repeat across process restarts.
+     *
+     * A second call with the same key and the same request, within 24 hours,
+     * gets the first call's stored response. Only a `2xx` is stored, so a key
+     * whose first call failed can be sent again. The same key with a
+     * different body is refused with `422` `idempotency_key_reused`.
+     *
+     * The key must be a string the platform can send as a header value: a
+     * newline, or a character above U+00FF, is a `TypeError` before sending.
+     */
+    idempotencyKey?: string | undefined;
+}
+export declare const DEFAULT_TIMEOUT_MS = 60000;
+export declare const DEFAULT_MAX_RETRIES = 2;
+export declare function resolveTimeout(option: number | undefined, fallback: number): number;
+export declare function resolveMaxRetries(option: number | undefined, fallback: number): number;
+/**
+ * Checks caller headers and returns a copy. `option` names the option the
+ * headers came from, for the message.
+ *
+ * @throws {TypeError} when the headers are not a plain object, or a header
+ * is one the SDK sets or is not a valid header name and string value.
+ */
+export declare function resolveHeaders(headers: Readonly<Record<string, string>> | undefined, option: string): Readonly<Record<string, string>>;
+/** Sets each of `extra` in `target`, replacing a header of the same name in any case. */
+export declare function mergeHeaders(target: Record<string, string>, extra: Readonly<Record<string, string>>): void;

package/dist/options.js

@@ -0,0 +1,73 @@
+// The options of one call, and how they are checked and combined with the
+// client's.
+import { AllisallError } from "./errors.js";
+export const DEFAULT_TIMEOUT_MS = 60_000;
+export const DEFAULT_MAX_RETRIES = 2;
+/** The headers the SDK sets itself, in lower case. */
+const OWNED_HEADERS = new Set([
+    "authorization",
+    "content-type",
+    "idempotency-key",
+    "x-request-id",
+]);
+export function resolveTimeout(option, fallback) {
+    const timeout = option ?? fallback;
+    if (typeof timeout !== "number" ||
+        !Number.isFinite(timeout) ||
+        timeout <= 0) {
+        throw new AllisallError(`allisall: timeout must be a positive number of milliseconds, not ${String(timeout)}`);
+    }
+    return timeout;
+}
+export function resolveMaxRetries(option, fallback) {
+    const maxRetries = option ?? fallback;
+    if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+        throw new AllisallError(`allisall: maxRetries must be a whole number, 0 or more, not ${String(maxRetries)}`);
+    }
+    return maxRetries;
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Checks caller headers and returns a copy. `option` names the option the
+ * headers came from, for the message.
+ *
+ * @throws {TypeError} when the headers are not a plain object, or a header
+ * is one the SDK sets or is not a valid header name and string value.
+ */
+export function resolveHeaders(headers, option) {
+    if (headers === undefined)
+        return {};
+    if (!isPlainObject(headers)) {
+        throw new TypeError(`allisall: ${option} must be a plain object of header names and string values`);
+    }
+    const copy = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (OWNED_HEADERS.has(name.toLowerCase())) {
+            throw new TypeError(`allisall: ${option} may not set ${name}; the SDK sets it`);
+        }
+        if (typeof value !== "string") {
+            throw new TypeError(`allisall: ${option} sets ${name} to ${typeof value}; a header value must be a string`);
+        }
+        copy[name] = value;
+    }
+    // The platform's own check of names and values, so a malformed header is
+    // refused here rather than failing every attempt as a connection error.
+    new Headers(copy);
+    return copy;
+}
+/** Sets each of `extra` in `target`, replacing a header of the same name in any case. */
+export function mergeHeaders(target, extra) {
+    for (const [name, value] of Object.entries(extra)) {
+        const lower = name.toLowerCase();
+        for (const existing of Object.keys(target)) {
+            if (existing.toLowerCase() === lower)
+                delete target[existing];
+        }
+        target[name] = value;
+    }
+}

package/dist/pagination.d.ts

@@ -0,0 +1,55 @@
+import type { RequestOptions } from "./options.js";
+/** The envelope every list response shares. */
+export interface ListBody {
+    readonly data: readonly unknown[];
+    readonly has_more: boolean;
+    readonly next_cursor: string | null;
+}
+/** Fetches the page after this one; the options apply to that request alone. */
+type NextPage<Item, Body extends ListBody> = (options: RequestOptions | undefined) => Promise<Page<Item, Body>>;
+/**
+ * One page of a list. `data` holds its items and `body` the whole response,
+ * such as the event drill-down's `total`. Iterate it with `for await` to
+ * walk its items and then every following page's.
+ */
+export declare class Page<Item, Body extends ListBody> implements AsyncIterable<Item> {
+    #private;
+    /** The page's items. */
+    readonly data: Item[];
+    /** The whole decoded response. */
+    readonly body: Body;
+    /** Pages are made by list methods; you do not construct one. */
+    constructor(body: Body, next: NextPage<Item, Body> | undefined);
+    /** Whether another page follows this one: the response's `has_more`. */
+    hasNextPage(): boolean;
+    /**
+     * Fetches the next page, with the same query and options as this one.
+     * `options` apply to this request alone, over the call's.
+     *
+     * @throws {AllisallError} when this is the last page.
+     */
+    getNextPage(options?: RequestOptions): Promise<Page<Item, Body>>;
+    /** Yields this page's items, then each following page's, fetching each page as it is reached. */
+    [Symbol.asyncIterator](): AsyncIterator<Item>;
+}
+/**
+ * The result of a list method. Await it for the first `Page`; iterate it
+ * with `for await` for every item of every page.
+ *
+ * Nothing is sent until it is awaited or iterated, so a list call whose
+ * result is never used sends no request.
+ */
+export declare class PagePromise<Item, Body extends ListBody> implements PromiseLike<Page<Item, Body>>, AsyncIterable<Item> {
+    #private;
+    /** Made by list methods; you do not construct one. */
+    constructor(load: () => Promise<Page<Item, Body>>);
+    /** Resolves with the first page, sending its request on first use. */
+    then<R1 = Page<Item, Body>, R2 = never>(onfulfilled?: ((page: Page<Item, Body>) => R1 | PromiseLike<R1>) | null | undefined, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null | undefined): Promise<R1 | R2>;
+    /** As `Promise.prototype.catch`, on the first page. */
+    catch<R = never>(onrejected?: ((reason: unknown) => R | PromiseLike<R>) | null | undefined): Promise<Page<Item, Body> | R>;
+    /** As `Promise.prototype.finally`, on the first page. */
+    finally(onfinally?: (() => void) | null | undefined): Promise<Page<Item, Body>>;
+    /** Yields every item of every page, from the first. */
+    [Symbol.asyncIterator](): AsyncIterator<Item>;
+}
+export {};