@allisall/sdk 0.0.0-stage → 0.2.0

package/dist/request.js

@@ -0,0 +1,363 @@
+// One operation, driven by the operation table: the URL and its query, the
+// headers, the body encoded once, the retries the operation is eligible
+// for, and the decoded response. Every resource method calls `request` or
+// `requestPage`; the ingest helper keeps its own path.
+import { AllisallError } from "./errors.js";
+import { OPERATIONS, } from "./generated/operations.js";
+import { decodeJson, encodeJson } from "./money.js";
+import { formOf } from "./multipart.js";
+import { mergeHeaders, resolveHeaders, resolveMaxRetries, resolveTimeout, } from "./options.js";
+import { Page, PagePromise } from "./pagination.js";
+import { joinURL, send, } from "./transport.js";
+import { hasLoneSurrogate } from "./unicode.js";
+import { uuidv4 } from "./uuid.js";
+const CONTENT_TYPES = {
+    json: "application/json",
+    "merge-patch": "application/merge-patch+json",
+};
+const PATH_PARAMETER = /\{([^{}]+)\}/g;
+/** Fills the path template, each parameter percent-encoded as one segment. */
+function fillPath(template, values) {
+    return template.replace(PATH_PARAMETER, (_, name) => {
+        const value = values[name];
+        if (typeof value !== "string") {
+            throw new TypeError(`allisall: the path parameter ${name} must be a string`);
+        }
+        // These cannot travel as one segment: a URL resolves "." and ".." as
+        // steps through the path, whether or not they are percent-encoded, and
+        // an empty segment changes which path is meant.
+        if (value === "" || value === "." || value === "..") {
+            throw new TypeError(`allisall: the path parameter ${name} is ${JSON.stringify(value)}, which cannot be sent as a path segment`);
+        }
+        // encodeURIComponent would throw a URIError naming nothing.
+        if (hasLoneSurrogate(value)) {
+            throw new TypeError(`allisall: the path parameter ${name} is not valid Unicode (a lone surrogate)`);
+        }
+        return encodeURIComponent(value);
+    });
+}
+/**
+ * A query value's text. A string holding a lone surrogate is refused: the
+ * URL would carry U+FFFD in its place.
+ */
+function queryText(name, value) {
+    if (hasLoneSurrogate(name)) {
+        throw new TypeError("allisall: a query parameter name is not valid Unicode (a lone surrogate)");
+    }
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new TypeError(`allisall: the query parameter ${name} is an invalid Date`);
+        }
+        return value.toISOString();
+    }
+    if (typeof value === "string") {
+        if (hasLoneSurrogate(value)) {
+            throw new TypeError(`allisall: the query parameter ${name} is not valid Unicode (a lone surrogate)`);
+        }
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "bigint") {
+        return String(value);
+    }
+    throw new TypeError(`allisall: the query parameter ${name} is ${value === null ? "null" : `a ${typeof value}`}; it must be a string, a number or a Date`);
+}
+/** Builds the URL: the base, the filled path, and the query in the caller's order. */
+function buildURL(config, operation, path, query) {
+    const url = new URL(joinURL(config.baseURL, fillPath(operation.path, path)));
+    if (query !== undefined) {
+        for (const [name, value] of Object.entries(query)) {
+            // An absent member is left out; the SDK writes no parameter of its own.
+            if (value === undefined)
+                continue;
+            url.searchParams.append(name, queryText(name, value));
+        }
+    }
+    return url.href;
+}
+const utf8 = new TextEncoder();
+/** Encodes the body once, before the first attempt. */
+function encodeBody(operation, body) {
+    switch (operation.body) {
+        case "none":
+            // The API refuses any body here, so one passed is a mistake, not
+            // something to drop in silence.
+            if (body !== undefined) {
+                throw new TypeError("allisall: this operation takes no request body, but one was passed");
+            }
+            return { body: undefined, contentType: undefined };
+        case "json":
+        case "merge-patch":
+            return {
+                body: utf8.encode(encodeJson(body, operation.requestMoney)),
+                contentType: CONTENT_TYPES[operation.body],
+            };
+        case "multipart":
+            // The form's own boundary is written by fetch, with its Content-Type.
+            return {
+                // The operation table's multipart operations take an ImportUpload;
+                // the methods calling them are typed so.
+                body: formOf(body),
+                contentType: undefined,
+            };
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Reads a success body: decoded with exact money, and a JSON object. A
+ * body `accept` refuses is unreadable, as a breached envelope is.
+ */
+function readerFor(operation, accept = () => true) {
+    if (operation.status === 204)
+        return () => ({ value: undefined });
+    return (text) => {
+        let value;
+        try {
+            value = decodeJson(text, operation.responseMoney);
+        }
+        catch (err) {
+            if (err instanceof SyntaxError)
+                return undefined;
+            throw err;
+        }
+        if (!isRecord(value))
+            return undefined;
+        if (operation.list !== null && !isListBody(value))
+            return undefined;
+        if (!accept(value))
+            return undefined;
+        return { value };
+    };
+}
+/**
+ * Checks a list's envelope: an array `data`, a boolean `has_more`, and a
+ * `next_cursor` that is a string or `null`, and a non-empty string when
+ * `has_more` is true.
+ */
+function isListBody(value) {
+    const { data, has_more, next_cursor } = value;
+    if (!Array.isArray(data) || typeof has_more !== "boolean")
+        return false;
+    if (next_cursor !== null && typeof next_cursor !== "string")
+        return false;
+    return !has_more || (typeof next_cursor === "string" && next_cursor !== "");
+}
+/**
+ * The one `PUT` a retry cannot repeat safely. Its `version` guard refuses a
+ * repeat of a write that already landed, as a stale version, so a retry
+ * after a lost response would report a failure for a write that succeeded.
+ */
+const VERSION_GUARDED_PUT = "setValueModelLineItems";
+/**
+ * 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 function isEligible(id, operation) {
+    switch (operation.method) {
+        case "GET":
+        case "DELETE":
+            return true;
+        case "PUT":
+            return id !== VERSION_GUARDED_PUT;
+        case "PATCH":
+            return false;
+        case "POST":
+            return operation.idempotent || id === "ingestEvents";
+    }
+}
+/**
+ * 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 function policyOf(config, id, operation, options) {
+    return {
+        timeout: resolveTimeout(options.timeout, config.timeout),
+        maxRetries: resolveMaxRetries(options.maxRetries, config.maxRetries),
+        headers: resolveHeaders(options.headers, "headers"),
+        signal: options.signal,
+        eligible: isEligible(id, operation),
+        retryKeyInUse: operation.idempotent,
+    };
+}
+function outgoing(config, operation, args, options) {
+    return {
+        method: operation.method,
+        url: buildURL(config, operation, args.path ?? {}, args.query),
+        authorization: authorizationFor(operation, args.shareToken),
+        ...encodeBody(operation, args.body),
+        // One key per call, the same on every attempt.
+        idempotencyKey: operation.idempotent
+            ? (checkedKey(options.idempotencyKey) ?? uuidv4())
+            : undefined,
+    };
+}
+/**
+ * The credential an operation's access policy calls for. A shared report
+ * takes its share token, and only its own function passes one: the client's
+ * credential never reaches it, and a share token reaches nothing else.
+ *
+ * @throws {AllisallError} for a shared report without a share token, or a
+ * share token passed to any other operation.
+ */
+function authorizationFor(operation, shareToken) {
+    if (operation.access === "ShareToken") {
+        if (shareToken === undefined) {
+            throw new AllisallError("allisall: a shared report is read with its share token, not with the client's credential");
+        }
+        return { report: shareToken };
+    }
+    if (shareToken !== undefined) {
+        throw new AllisallError("allisall: a share token is sent only to read a shared report");
+    }
+    return operation.access === "Public" ? "none" : "bearer";
+}
+/**
+ * A caller's `Idempotency-Key`, checked only as far as the platform can
+ * send it. Its syntax is the API's to judge. A key `fetch` cannot send
+ * would fail every attempt before sending, and each failure would read as
+ * a connection error worth retrying.
+ *
+ * @throws {TypeError} when the key is not a string, or not a valid header value.
+ */
+function checkedKey(key) {
+    if (key === undefined)
+        return undefined;
+    if (typeof key !== "string") {
+        throw new TypeError(`allisall: idempotencyKey must be a string, not ${key === null ? "null" : `a ${typeof key}`}`);
+    }
+    try {
+        new Headers({ "Idempotency-Key": key });
+    }
+    catch {
+        throw new TypeError("allisall: idempotencyKey holds a character a header value cannot carry, such as a newline or a character above U+00FF");
+    }
+    return key;
+}
+/**
+ * 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 function request(config, id, args = {}) {
+    return requestAccepting(config, id, args, undefined);
+}
+/** `request`, with a check of the success body beyond the operation's own. */
+async function requestAccepting(config, id, args, accept) {
+    const operation = OPERATIONS[id];
+    const options = args.options ?? {};
+    const policy = policyOf(config, id, operation, options);
+    const out = outgoing(config, operation, args, options);
+    const value = await send(config, out, readerFor(operation, accept), policy);
+    // The reader checked what the SDK relies on: a JSON object, a list's
+    // envelope, and money decoded at the operation's money paths. The rest
+    // is the server's to keep to the generated type.
+    return value;
+}
+/**
+ * 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 function requestPage(config, id, args = {}) {
+    if (OPERATIONS[id].list === null) {
+        throw new TypeError(`allisall: ${id} is not a list operation`);
+    }
+    // The call's options apply to every page; an override passed to
+    // getNextPage applies to that one request, over them.
+    const callOptions = args.options ?? {};
+    // Each cursor sent, with the position of the page it requested: 0 for
+    // the first page, 1 for the next, and so on.
+    const sent = new Map();
+    // A next cursor that requested a page at another position would walk in
+    // a cycle. One recorded at the same position is the same page requested
+    // again, as when a walk restarts from an earlier page.
+    const breaksNoCycle = (nextPosition) => (value) => {
+        if (value.has_more !== true || typeof value.next_cursor !== "string") {
+            return true;
+        }
+        const position = sent.get(value.next_cursor);
+        return position === undefined || position === nextPosition;
+    };
+    const load = async (query, override, position) => {
+        const options = override === undefined ? callOptions : overlay(callOptions, override);
+        const cursor = query === undefined ? undefined : Reflect.get(query, "cursor");
+        if (typeof cursor === "string" && !sent.has(cursor)) {
+            sent.set(cursor, position);
+        }
+        const body = await requestAccepting(config, id, pageArgs(args, query, options), breaksNoCycle(position + 1));
+        // A list operation's reader checked the envelope.
+        const list = body;
+        const next = list.has_more && typeof list.next_cursor === "string"
+            ? nextQuery(query, list.next_cursor)
+            : undefined;
+        return new Page(list, next === undefined
+            ? undefined
+            : (nextOverride) => load(next, nextOverride, position + 1));
+    };
+    return new PagePromise(() => load(args.query, undefined, 0));
+}
+/**
+ * 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 function pageArgs(args, query, options) {
+    return { ...args, query, options };
+}
+/**
+ * Lays one request's options over the call's. A member left out, or set to
+ * `undefined`, keeps the call's; `headers` are laid over the call's
+ * headers name by name, as a call's are over the client's.
+ *
+ * @throws {TypeError} when either set of headers is not a plain object of
+ * headers, or names a header the SDK sets.
+ */
+function overlay(call, override) {
+    const merged = { ...call };
+    if (override.signal !== undefined)
+        merged.signal = override.signal;
+    if (override.timeout !== undefined)
+        merged.timeout = override.timeout;
+    if (override.maxRetries !== undefined) {
+        merged.maxRetries = override.maxRetries;
+    }
+    if (override.headers !== undefined) {
+        const headers = { ...resolveHeaders(call.headers, "headers") };
+        mergeHeaders(headers, resolveHeaders(override.headers, "headers"));
+        merged.headers = headers;
+    }
+    return merged;
+}
+/** The query of the next page: the same members, `page` dropped, `cursor` set. */
+function nextQuery(query, cursor) {
+    const next = {};
+    for (const [name, value] of Object.entries(query ?? {})) {
+        if (name !== "page")
+            next[name] = value;
+    }
+    next.cursor = cursor;
+    return next;
+}
+/** Calls one operation with arguments typed for it; see `request`. */
+export function call(config, id, args) {
+    return request(config, id, args);
+}
+/** Calls one list operation with arguments typed for it; see `requestPage`. */
+export function callPage(config, id, args) {
+    return requestPage(config, id, args);
+}

package/dist/resources/agents.d.ts

@@ -0,0 +1,51 @@
+import type { IdempotentRequestOptions, RequestOptions } from "../options.js";
+import type { PagePromise } from "../pagination.js";
+import type { TransportConfig } from "../transport.js";
+import type { Agent, AgentCreate, AgentDetail, AgentList, AgentListItem, AgentPatch, GetAgentQuery, ListAgentsQuery } from "../types.js";
+/** The `agents` operations. */
+export declare class Agents {
+    #private;
+    constructor(config: TransportConfig);
+    /**
+     * Lists agents. Await the result for one page; iterate it with
+     * `for await` for every agent of every page.
+     *
+     * Needs the `read` scope. Operation `listAgents`.
+     */
+    list(query?: ListAgentsQuery, options?: RequestOptions): PagePromise<AgentListItem, AgentList>;
+    /**
+     * Creates an agent.
+     *
+     * Every attempt of the call sends one `Idempotency-Key`, so a retry
+     * cannot create a second agent.
+     *
+     * Needs the `write` scope. Operation `createAgent`.
+     */
+    create(body: AgentCreate, options?: IdempotentRequestOptions): Promise<Agent>;
+    /**
+     * Reads an agent, with its statistics. `from` and `to` bound the
+     * statistics only; absent bounds mean all time.
+     *
+     * Needs the `read` scope. Operation `getAgent`.
+     */
+    get(id: string, query?: GetAgentQuery, options?: RequestOptions): Promise<AgentDetail>;
+    /**
+     * Updates an agent with a merge patch: a member left out keeps its value,
+     * `null` clears it, and any other value sets it.
+     *
+     * Never retried.
+     *
+     * Needs the `write` scope. Operation `updateAgent`.
+     */
+    update(id: string, patch: AgentPatch, options?: RequestOptions): Promise<Agent>;
+    /**
+     * Deletes an agent. Refused while events reference the agent; set its
+     * status to `retired` instead.
+     *
+     * A retry after a lost response can answer `404` for a delete that
+     * succeeded.
+     *
+     * Needs the `write` scope. Operation `deleteAgent`.
+     */
+    delete(id: string, options?: RequestOptions): Promise<void>;
+}

package/dist/resources/agents.js

@@ -0,0 +1,65 @@
+// The `agents` operations.
+import { call, callPage } from "../request.js";
+/** The `agents` operations. */
+export class Agents {
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    /**
+     * Lists agents. Await the result for one page; iterate it with
+     * `for await` for every agent of every page.
+     *
+     * Needs the `read` scope. Operation `listAgents`.
+     */
+    list(query, options) {
+        return callPage(this.#config, "listAgents", { query, options });
+    }
+    /**
+     * Creates an agent.
+     *
+     * Every attempt of the call sends one `Idempotency-Key`, so a retry
+     * cannot create a second agent.
+     *
+     * Needs the `write` scope. Operation `createAgent`.
+     */
+    create(body, options) {
+        return call(this.#config, "createAgent", { body, options });
+    }
+    /**
+     * Reads an agent, with its statistics. `from` and `to` bound the
+     * statistics only; absent bounds mean all time.
+     *
+     * Needs the `read` scope. Operation `getAgent`.
+     */
+    get(id, query, options) {
+        return call(this.#config, "getAgent", { path: { id }, query, options });
+    }
+    /**
+     * Updates an agent with a merge patch: a member left out keeps its value,
+     * `null` clears it, and any other value sets it.
+     *
+     * Never retried.
+     *
+     * Needs the `write` scope. Operation `updateAgent`.
+     */
+    update(id, patch, options) {
+        return call(this.#config, "updateAgent", {
+            path: { id },
+            body: patch,
+            options,
+        });
+    }
+    /**
+     * Deletes an agent. Refused while events reference the agent; set its
+     * status to `retired` instead.
+     *
+     * A retry after a lost response can answer `404` for a delete that
+     * succeeded.
+     *
+     * Needs the `write` scope. Operation `deleteAgent`.
+     */
+    delete(id, options) {
+        return call(this.#config, "deleteAgent", { path: { id }, options });
+    }
+}

package/dist/resources/analytics.d.ts

@@ -0,0 +1,42 @@
+import type { RequestOptions } from "../options.js";
+import type { TransportConfig } from "../transport.js";
+import type { Anomalies, ClientCost, ClientValue, GetClientAnomaliesQuery, GetClientCostQuery, GetClientRoiQuery, GetClientValueQuery, RoiResult } from "../types.js";
+/** The `analytics` operations. */
+export declare class Analytics {
+    #private;
+    constructor(config: TransportConfig);
+    /**
+     * Computes a client's value.
+     *
+     * Needs the `read` scope. Operation `getClientValue`.
+     *
+     * @param clientId - the client's id.
+     */
+    getValueForClient(clientId: string, query?: GetClientValueQuery, options?: RequestOptions): Promise<ClientValue>;
+    /**
+     * Computes a client's cost over a period. Both bounds are required:
+     * standing charges are prorated day by day, so an open `from` would
+     * prorate each charge from its own start date, however long ago.
+     *
+     * Needs the `read` scope. Operation `getClientCost`.
+     *
+     * @param clientId - the client's id.
+     */
+    getCostForClient(clientId: string, query: GetClientCostQuery, options?: RequestOptions): Promise<ClientCost>;
+    /**
+     * Computes a client's ROI over a period.
+     *
+     * Needs the `read` scope. Operation `getClientRoi`.
+     *
+     * @param clientId - the client's id.
+     */
+    getRoiForClient(clientId: string, query: GetClientRoiQuery, options?: RequestOptions): Promise<RoiResult>;
+    /**
+     * Flags anomalies in a client's period.
+     *
+     * Needs the `read` scope. Operation `getClientAnomalies`.
+     *
+     * @param clientId - the client's id.
+     */
+    getAnomaliesForClient(clientId: string, query: GetClientAnomaliesQuery, options?: RequestOptions): Promise<Anomalies>;
+}

package/dist/resources/analytics.js

@@ -0,0 +1,68 @@
+// The `analytics` operations: a client's value, cost, ROI and anomalies
+// over a period.
+import { call } from "../request.js";
+/** The `analytics` operations. */
+export class Analytics {
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    /**
+     * Computes a client's value.
+     *
+     * Needs the `read` scope. Operation `getClientValue`.
+     *
+     * @param clientId - the client's id.
+     */
+    getValueForClient(clientId, query, options) {
+        return call(this.#config, "getClientValue", {
+            path: { id: clientId },
+            query,
+            options,
+        });
+    }
+    /**
+     * Computes a client's cost over a period. Both bounds are required:
+     * standing charges are prorated day by day, so an open `from` would
+     * prorate each charge from its own start date, however long ago.
+     *
+     * Needs the `read` scope. Operation `getClientCost`.
+     *
+     * @param clientId - the client's id.
+     */
+    getCostForClient(clientId, query, options) {
+        return call(this.#config, "getClientCost", {
+            path: { id: clientId },
+            query,
+            options,
+        });
+    }
+    /**
+     * Computes a client's ROI over a period.
+     *
+     * Needs the `read` scope. Operation `getClientRoi`.
+     *
+     * @param clientId - the client's id.
+     */
+    getRoiForClient(clientId, query, options) {
+        return call(this.#config, "getClientRoi", {
+            path: { id: clientId },
+            query,
+            options,
+        });
+    }
+    /**
+     * Flags anomalies in a client's period.
+     *
+     * Needs the `read` scope. Operation `getClientAnomalies`.
+     *
+     * @param clientId - the client's id.
+     */
+    getAnomaliesForClient(clientId, query, options) {
+        return call(this.#config, "getClientAnomalies", {
+            path: { id: clientId },
+            query,
+            options,
+        });
+    }
+}

package/dist/resources/api-keys.d.ts

@@ -0,0 +1,54 @@
+import type { RequestOptions } from "../options.js";
+import type { PagePromise } from "../pagination.js";
+import type { TransportConfig } from "../transport.js";
+import type { ApiKey, ApiKeyCreate, ApiKeyList, ApiKeyWithToken, ListApiKeysQuery } from "../types.js";
+/** The `apiKeys` operations. */
+export declare class ApiKeys {
+    #private;
+    constructor(config: TransportConfig);
+    /**
+     * Creates an API key, and returns its complete token once. Store the
+     * token at once: no later call returns it, because the API keeps only a
+     * hash.
+     *
+     * Never retried, because a retried create would make a second key. On a
+     * `ConnectionError`, list the keys to learn whether it was created.
+     *
+     * Needs a session token: an API key cannot create a key. An API key is
+     * refused with `403` `session_required`, as an `ApiError`.
+     *
+     * Operation `createApiKey`.
+     */
+    create(body: ApiKeyCreate, options?: RequestOptions): Promise<ApiKeyWithToken>;
+    /**
+     * Lists API keys. Await the result for one page; iterate it with
+     * `for await` for every key of every page.
+     *
+     * Needs a session token. An API key is refused with `403`
+     * `session_required`, as an `ApiError`.
+     *
+     * Operation `listApiKeys`.
+     */
+    list(query?: ListApiKeysQuery, options?: RequestOptions): PagePromise<ApiKey, ApiKeyList>;
+    /**
+     * Reads an API key. Its token is never returned.
+     *
+     * Needs a session token. An API key is refused with `403`
+     * `session_required`, as an `ApiError`.
+     *
+     * Operation `getApiKey`.
+     */
+    get(id: string, options?: RequestOptions): Promise<ApiKey>;
+    /**
+     * Revokes an API key. The next request bearing the key is refused with
+     * `401`.
+     *
+     * Needs a session token. An API key is refused with `403`
+     * `session_required`, as an `ApiError`. Never retried.
+     *
+     * Operation `revokeApiKey`.
+     *
+     * @param id - the key's `id`, not its token.
+     */
+    revoke(id: string, options?: RequestOptions): Promise<ApiKey>;
+}