@allisall/sdk 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+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 { 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

@@ -0,0 +1,5 @@
+// The public surface of @allisall/sdk.
+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

@@ -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 = 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. */
+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 = 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. */
+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 4,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/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;