@allisall/sdk 0.0.0-stage → 0.2.0

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 {};

package/dist/pagination.js

@@ -0,0 +1,85 @@
+// A list call's result: a page, and the walk over every following page.
+import { AllisallError } from "./errors.js";
+/**
+ * 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 class Page {
+    /** The page's items. */
+    data;
+    /** The whole decoded response. */
+    body;
+    #next;
+    /** Pages are made by list methods; you do not construct one. */
+    constructor(body, next) {
+        this.body = body;
+        // The envelope was checked as an array of the list's items when the
+        // response was read.
+        this.data = body.data;
+        this.#next = next;
+    }
+    /** Whether another page follows this one: the response's `has_more`. */
+    hasNextPage() {
+        return this.#next !== undefined;
+    }
+    /**
+     * 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) {
+        if (this.#next === undefined) {
+            return Promise.reject(new AllisallError("allisall: this is the last page; no page follows it"));
+        }
+        return this.#next(options);
+    }
+    /** Yields this page's items, then each following page's, fetching each page as it is reached. */
+    async *[Symbol.asyncIterator]() {
+        let page = this;
+        for (;;) {
+            yield* page.data;
+            if (!page.hasNextPage())
+                return;
+            page = await page.getNextPage();
+        }
+    }
+}
+/**
+ * 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 class PagePromise {
+    #load;
+    #first;
+    /** Made by list methods; you do not construct one. */
+    constructor(load) {
+        this.#load = load;
+    }
+    /** The first page, requested once, on first use. */
+    #page() {
+        this.#first ??= this.#load();
+        return this.#first;
+    }
+    /** Resolves with the first page, sending its request on first use. */
+    // biome-ignore lint/suspicious/noThenProperty: a PagePromise is awaitable by design, so it must have then.
+    then(onfulfilled, onrejected) {
+        return this.#page().then(onfulfilled, onrejected);
+    }
+    /** As `Promise.prototype.catch`, on the first page. */
+    catch(onrejected) {
+        return this.#page().catch(onrejected);
+    }
+    /** As `Promise.prototype.finally`, on the first page. */
+    finally(onfinally) {
+        return this.#page().finally(onfinally);
+    }
+    /** Yields every item of every page, from the first. */
+    async *[Symbol.asyncIterator]() {
+        yield* await this.#page();
+    }
+}

package/dist/request.d.ts

@@ -0,0 +1,117 @@
+import type { operations } from "./generated/openapi.js";
+import { type Operation, type OperationId } from "./generated/operations.js";
+import { type MoneyInput } from "./money.js";
+import { type ImportUpload } from "./multipart.js";
+import { type IdempotentRequestOptions, type RequestOptions } from "./options.js";
+import { type ListBody, PagePromise } from "./pagination.js";
+import { type CallPolicy, type TransportConfig } from "./transport.js";
+import type { QueryOf } from "./types.js";
+type Responses<K extends OperationId> = operations[K]["responses"];
+type SuccessStatus = 200 | 201 | 202 | 204;
+/**
+ * The decoded body of an operation's success response, from the generated
+ * types: `undefined` for a response without a body.
+ */
+export type SuccessBody<K extends OperationId> = Responses<K>[Extract<keyof Responses<K>, SuccessStatus>] extends {
+    content: {
+        "application/json": infer B;
+    };
+} ? B : undefined;
+/** What one call sends, beyond what the operation table fixes. */
+export interface CallArgs {
+    /** The path parameters, by the name the path template gives each. */
+    readonly path?: Readonly<Record<string, string>> | undefined;
+    /** The query, written member by member in the object's own order. */
+    readonly query?: object | undefined;
+    /** The body: JSON for a JSON or merge-patch operation, an upload for a multipart one. */
+    readonly body?: unknown;
+    readonly options?: IdempotentRequestOptions | undefined;
+    /**
+     * The share token of a shared report, already checked. Only the shared
+     * report's operation takes one, and it takes nothing else.
+     */
+    readonly shareToken?: string | undefined;
+}
+/**
+ * Whether a retry cannot apply the request twice: a method RFC 9110 defines
+ * as idempotent, an operation sent with an `Idempotency-Key`, or ingest,
+ * whose `event_id`s deduplicate. The version-guarded `PUT` is the exception.
+ */
+export declare function isEligible(id: OperationId, operation: Operation): boolean;
+/**
+ * What one call may do: its operation's retry eligibility, and the call's
+ * options resolved over the client's.
+ *
+ * @throws {AllisallError} for a `timeout` or `maxRetries` the client would refuse.
+ * @throws {TypeError} for headers that are not a plain object of headers, or
+ * that name a header the SDK sets.
+ */
+export declare function policyOf(config: TransportConfig, id: OperationId, operation: Operation, options: RequestOptions): CallPolicy;
+/**
+ * Calls one operation and resolves with its decoded success body.
+ *
+ * Everything the call sends is fixed before the first attempt: its URL, its
+ * body's bytes and its `Idempotency-Key`. Retries follow the operation's
+ * eligibility. A `204` resolves with `undefined`.
+ */
+export declare function request<K extends OperationId>(config: TransportConfig, id: K, args?: CallArgs): Promise<SuccessBody<K>>;
+/** The item type of a list operation's page. */
+type ItemOf<B> = B extends {
+    readonly data: readonly (infer I)[];
+} ? I : never;
+/**
+ * Calls a list operation lazily: nothing is sent until the result is
+ * awaited or iterated. Each following page sends the same query with
+ * `cursor` set to the previous page's `next_cursor` and without `page`.
+ *
+ * The walk remembers every cursor it has sent since the list call, with
+ * the position of the page each requested; a cursor the caller's own query
+ * held requested the first. A page with `has_more` whose `next_cursor` was
+ * sent for a page at another position would walk in a cycle, so it is
+ * unreadable: an `ApiError` with the page's status and no problem. Walking
+ * again from an earlier page sends each cursor for its own position, and is
+ * not refused.
+ */
+export declare function requestPage<K extends OperationId>(config: TransportConfig, id: K, args?: CallArgs): PagePromise<ItemOf<SuccessBody<K>>, Extract<SuccessBody<K>, ListBody>>;
+/**
+ * The arguments of one page's request: the call's own, with the query and
+ * options paging sets for that page. Every other member is carried forward.
+ */
+export declare function pageArgs(args: CallArgs, query: object | undefined, options: RequestOptions): CallArgs;
+/** An operation's path parameters, from the generated types. */
+type PathOf<K extends OperationId> = NonNullable<operations[K]["parameters"]["path"]>;
+/**
+ * The query member of an operation's arguments: required when the
+ * generated types require the query, which they do when any one of its
+ * parameters is required, and optional otherwise.
+ */
+type QueryArgs<K extends OperationId> = undefined extends operations[K]["parameters"]["query"] ? {
+    readonly query?: QueryOf<K> | undefined;
+} : {
+    readonly query: QueryOf<K>;
+};
+/**
+ * The body an operation takes, from the generated types: an `ImportUpload`
+ * for a form, and otherwise the JSON body with its money widened.
+ */
+type BodyOf<K extends OperationId> = operations[K] extends {
+    requestBody: {
+        content: infer C;
+    };
+} ? "multipart/form-data" extends keyof C ? ImportUpload : MoneyInput<C[keyof C]> : never;
+/**
+ * What a resource method passes for one operation, typed from the generated
+ * types. A change to the API that retypes an operation's path, query or
+ * body, or that makes its query required, fails the compile of the method
+ * that calls it.
+ */
+export type OperationArgs<K extends OperationId> = {
+    readonly path?: PathOf<K>;
+    readonly body?: BodyOf<K>;
+    readonly options?: IdempotentRequestOptions | undefined;
+} & QueryArgs<K>;
+/** Calls one operation with arguments typed for it; see `request`. */
+export declare function call<K extends OperationId>(config: TransportConfig, id: K, args: OperationArgs<K>): Promise<SuccessBody<K>>;
+/** Calls one list operation with arguments typed for it; see `requestPage`. */
+export declare function callPage<K extends OperationId>(config: TransportConfig, id: K, args: OperationArgs<K>): PagePromise<ItemOf<SuccessBody<K>>, Extract<SuccessBody<K>, ListBody>>;
+export {};