@allisall/sdk 0.0.0-stage → 0.2.0

package/dist/client.js

@@ -0,0 +1,193 @@
+// The client: its options, and how the credential and the base URL are
+// resolved at construction.
+import { AllisallError } from "./errors.js";
+import { DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, resolveHeaders, resolveMaxRetries, resolveTimeout, } from "./options.js";
+import { Agents } from "./resources/agents.js";
+import { Analytics } from "./resources/analytics.js";
+import { ApiKeys } from "./resources/api-keys.js";
+import { Calculations } from "./resources/calculations.js";
+import { Clients } from "./resources/clients.js";
+import { Cost } from "./resources/cost.js";
+import { DashboardOperations } from "./resources/dashboard.js";
+import { Events } from "./resources/events.js";
+import { HealthOperations } from "./resources/health.js";
+import { Imports } from "./resources/imports.js";
+import { OutcomeTypes } from "./resources/outcome-types.js";
+import { Reports } from "./resources/reports.js";
+import { ValueModels } from "./resources/value-models.js";
+import { globalValue, isBrowser, readEnv, userAgent } from "./runtime.js";
+import { BROWSER_KEY_MESSAGE, isPrintableCredential, } from "./transport.js";
+const DEFAULT_BASE_URL = "https://api.allisai.ai";
+function resolveCredential(options) {
+    const { apiKey, tokenProvider } = options;
+    if (apiKey !== undefined && tokenProvider !== undefined) {
+        throw new AllisallError("allisall: pass either apiKey or tokenProvider, not both");
+    }
+    if (tokenProvider !== undefined) {
+        if (typeof tokenProvider !== "function") {
+            throw new AllisallError("allisall: tokenProvider must be a function");
+        }
+        return { kind: "provider", provider: tokenProvider };
+    }
+    if (apiKey !== undefined) {
+        const key = typeof apiKey === "string" ? apiKey.trim() : "";
+        if (key === "") {
+            throw new AllisallError("allisall: apiKey is empty");
+        }
+        if (!isPrintableCredential(key)) {
+            throw new AllisallError("allisall: apiKey holds a character other than printable ASCII, which cannot be sent");
+        }
+        return { kind: "apiKey", apiKey: key };
+    }
+    // A variable of white space alone counts as unset.
+    const fromEnv = readEnv("AIA_API_KEY")?.trim();
+    if (fromEnv !== undefined && fromEnv !== "") {
+        if (!isPrintableCredential(fromEnv)) {
+            throw new AllisallError("allisall: AIA_API_KEY holds a character other than printable ASCII, which cannot be sent");
+        }
+        return { kind: "apiKey", apiKey: fromEnv };
+    }
+    throw new AllisallError("allisall: no credential; pass apiKey or tokenProvider, or set AIA_API_KEY");
+}
+/** Reads `globalThis.location.href`, where it exists. */
+function pageAddress() {
+    const location = globalValue("location");
+    if (typeof location !== "object" || location === null)
+        return undefined;
+    const href = Reflect.get(location, "href");
+    return typeof href === "string" ? href : undefined;
+}
+/**
+ * Resolves the base URL: the option, else `AIA_BASE_URL`, else the API's
+ * own host. In a browser, a path starting with a single `/` is resolved
+ * against the page's address and must keep its origin.
+ *
+ * @throws {AllisallError} for a base URL the client refuses.
+ */
+function resolveBaseURL(option, browser) {
+    const raw = option ?? readEnv("AIA_BASE_URL") ?? DEFAULT_BASE_URL;
+    // A path on the page's own origin, such as "/api". A leading "//" names
+    // another host, so it is not a path.
+    const pathOnly = typeof raw === "string" && raw.startsWith("/") && !raw.startsWith("//");
+    const page = browser && pathOnly ? pageAddress() : undefined;
+    let url;
+    try {
+        url = page === undefined ? new URL(raw) : new URL(raw, page);
+    }
+    catch {
+        throw new AllisallError(pathOnly && browser
+            ? `allisall: the base URL ${JSON.stringify(raw)} is a path, and the page's address could not be read to resolve it`
+            : `allisall: the base URL ${JSON.stringify(raw)} is not an absolute URL`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new AllisallError(`allisall: the base URL ${JSON.stringify(raw)} is not http or https`);
+    }
+    // URL parsing reads a backslash as "/" and drops tabs and newlines, so a
+    // value such as "/\other.example/api" passes the "//" check above and
+    // still names another host. Only the resolved origin settles it.
+    if (page !== undefined && url.origin !== new URL(page).origin) {
+        throw new AllisallError(`allisall: the base URL ${JSON.stringify(raw)} is a path, but resolves to another origin, ${url.origin}`);
+    }
+    return url;
+}
+/**
+ * Resolves what every request needs apart from its credential and default
+ * headers: the base URL, timeout, retries, `fetch` and `User-Agent`, which
+ * a browser does not send.
+ *
+ * @throws {AllisallError} for a base URL, timeout or `maxRetries` the
+ * client refuses.
+ */
+export function transportSettings(options, browser) {
+    return {
+        baseURL: resolveBaseURL(options.baseURL, browser),
+        timeout: resolveTimeout(options.timeout, DEFAULT_TIMEOUT_MS),
+        maxRetries: resolveMaxRetries(options.maxRetries, DEFAULT_MAX_RETRIES),
+        fetch: options.fetch,
+        userAgent: userAgent(),
+    };
+}
+/**
+ * Checks the client's options and fixes everything a request needs.
+ *
+ * @throws {AllisallError} for an option the client refuses.
+ * @throws {TypeError} when `defaultHeaders` is not a plain object of
+ * header names and string values, names a header the SDK sets, or holds a
+ * name or value the platform cannot send.
+ */
+export function transportConfig(options) {
+    const credential = resolveCredential(options);
+    const browser = isBrowser();
+    const refuseApiKeys = browser && options.dangerouslyAllowBrowser !== true;
+    if (refuseApiKeys && credential.kind === "apiKey") {
+        throw new AllisallError(BROWSER_KEY_MESSAGE);
+    }
+    return {
+        ...transportSettings(options, browser),
+        credential,
+        refuseApiKeys,
+        defaultHeaders: resolveHeaders(options.defaultHeaders, "defaultHeaders"),
+    };
+}
+/**
+ * The allisall API client. Construct one and reuse it.
+ *
+ * Its operations are grouped by what they act on, one property per group,
+ * such as `client.clients.list()`. A failed call rejects with an `ApiError`
+ * for an error response, or a `ConnectionError` when no response arrived.
+ */
+export class Allisall {
+    /** Events: ingest, and the events behind a client's totals. */
+    events;
+    /** CSV imports of events. */
+    imports;
+    /** Clients, and the agents assigned to each. */
+    clients;
+    /** Agents. */
+    agents;
+    /** Value models, by their own id or by their client's, and value templates. */
+    valueModels;
+    /** Outcome types, for the workspace or for one client. */
+    outcomeTypes;
+    /** Cost line items and the price table. */
+    cost;
+    /** A client's value, cost, ROI and anomalies over a period. */
+    analytics;
+    /** Calculations, and the human steps that validate, publish and reopen them. */
+    calculations;
+    /** Reports on calculations, and the human steps that share and revoke them. */
+    reports;
+    /** The workspace's month, and renewal readiness. */
+    dashboard;
+    /** API keys, managed with a session token. */
+    apiKeys;
+    /** The API's liveness. */
+    health;
+    /**
+     * @throws {AllisallError} when there is no credential, or both an API key
+     * and a token provider; when the base URL is neither an absolute `http`
+     * or `https` URL nor, in a browser, a path starting with a single `/`
+     * that resolves to the page's own origin; when `maxRetries` is negative
+     * or `timeout` is not positive; or when an API key is used in a browser
+     * without `dangerouslyAllowBrowser`.
+     * @throws {TypeError} when `defaultHeaders` is not a plain object of
+     * header names and string values, names a header the SDK sets, or holds a
+     * name or value the platform cannot send.
+     */
+    constructor(options = {}) {
+        const config = transportConfig(options);
+        this.events = new Events(config);
+        this.imports = new Imports(config);
+        this.clients = new Clients(config);
+        this.agents = new Agents(config);
+        this.valueModels = new ValueModels(config);
+        this.outcomeTypes = new OutcomeTypes(config);
+        this.cost = new Cost(config);
+        this.analytics = new Analytics(config);
+        this.calculations = new Calculations(config);
+        this.reports = new Reports(config);
+        this.dashboard = new DashboardOperations(config);
+        this.apiKeys = new ApiKeys(config);
+        this.health = new HealthOperations(config);
+    }
+}

package/dist/decimal.d.ts

@@ -0,0 +1,20 @@
+declare const decimalBrand: unique symbol;
+/**
+ * An exact decimal amount, such as a `cost`. It is a string at run time,
+ * branded so that only `decimal()` produces one. The SDK writes its text
+ * into the request unchanged, as a JSON number, so no binary float ever
+ * rounds it.
+ */
+export type Decimal = string & {
+    readonly [decimalBrand]: true;
+};
+/** Reports whether `text` has the syntax of a `Decimal`. */
+export declare function isDecimalText(text: string): boolean;
+/**
+ * Makes a `Decimal` from its text, such as `decimal("0.3683")`.
+ *
+ * @throws {TypeError} when `text` is not an optional `-`, digits without a
+ * leading zero (or a single `0`), and optional decimal places after a `.`.
+ */
+export declare function decimal(text: string): Decimal;
+export {};

package/dist/decimal.js

@@ -0,0 +1,23 @@
+/**
+ * The syntax a `Decimal` accepts: an optional `-`, digits without a leading
+ * zero (or a single `0`), and optional decimal places after a `.`. Every
+ * string it accepts is a valid JSON number.
+ */
+const DECIMAL_SYNTAX = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/;
+/** Reports whether `text` has the syntax of a `Decimal`. */
+export function isDecimalText(text) {
+    return DECIMAL_SYNTAX.test(text);
+}
+/**
+ * Makes a `Decimal` from its text, such as `decimal("0.3683")`.
+ *
+ * @throws {TypeError} when `text` is not an optional `-`, digits without a
+ * leading zero (or a single `0`), and optional decimal places after a `.`.
+ */
+export function decimal(text) {
+    if (typeof text !== "string" || !isDecimalText(text)) {
+        throw new TypeError(`allisall: ${JSON.stringify(text)} is not a decimal; write it as digits with an optional "-" and decimal places, such as "12.5"`);
+    }
+    // The syntax check above is the invariant the brand stands for.
+    return text;
+}

package/dist/errors.d.ts

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

package/dist/errors.js

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