@allisall/sdk 0.1.0 → 0.4.0

package/README.md

@@ -1,7 +1,10 @@
 # @allisall/sdk
 
-The allisall SDK for TypeScript and JavaScript. Version 0.1 sends events to
-the allisall API. It runs on Node 22 and later, and in current browsers.
+The allisall SDK for TypeScript and JavaScript: a typed client for the
+allisall API, covering events, imports, clients, agents, value models,
+costs, analytics, calculations, reports, the dashboard, API keys and
+shared reports. It runs on Node 22 and later, and in Chrome 114, Firefox
+135 and Safari 18.4 and later.
 
 ## Install
 
@@ -51,8 +54,11 @@ console.log(summary.accepted, summary.duplicates, summary.rejected);
 
 `ingest` takes any number of events. It sends them in batches, retries a
 failure worth retrying, and returns one summary for the whole list. A
-rejected event is listed in `summary.errors`, and the others are still
-stored. Write `cost` with `decimal()` to keep it exact.
+rejected event is counted in `summary.rejected`, its problems are listed in
+`summary.errors`, and the others are still stored. When
+`summary.errors_truncated` is `true`, the list omits some problems, and a
+rejected event may have no entry. Write `cost` with `decimal()` to keep it
+exact.
 
 ### Set your own `event_id` for at-least-once delivery
 
@@ -63,6 +69,135 @@ for example from a queue that redelivers messages, set `event_id`
 yourself, such as to the message's id. The API then stores the event
 once, however often it arrives.
 
+## Call the API
+
+The client groups its methods by resource: `client.clients`,
+`client.agents`, `client.valueModels`, `client.cost`, `client.analytics`,
+`client.calculations`, `client.reports`, `client.dashboard` and more. Each
+method's documentation names the API operation it calls and the scope your
+key needs.
+
+```ts
+import { Allisall } from "@allisall/sdk";
+
+const client = new Allisall();
+
+const created = await client.clients.create({
+  name: "Acme Logistics",
+  status: "active",
+  client_key: "acme",
+});
+
+// An update is a merge patch: a member you leave out keeps its value, and
+// null clears it. This sets the renewal date to one calendar year after
+// today's UTC date; a date before yesterday in UTC is refused.
+const renewal = new Date();
+renewal.setUTCFullYear(renewal.getUTCFullYear() + 1);
+const updated = await client.clients.update(created.id, {
+  renewal_date: renewal.toISOString().slice(0, 10),
+});
+console.log(updated.name, updated.renewal_date);
+```
+
+A call that creates something other than an API key sends an
+`Idempotency-Key`, and sends the same key again on a retry, so a retry
+never creates a second one. Amounts
+of money come back as a `Decimal`, a string holding the exact amount.
+
+## Lists
+
+A list method returns every item of every page when you iterate it with
+`for await`. The SDK fetches each page as the loop reaches it:
+
+```ts
+import { Allisall } from "@allisall/sdk";
+
+const client = new Allisall();
+
+for await (const agent of client.agents.list()) {
+  console.log(agent.agent_key, agent.name);
+}
+```
+
+To work a page at a time, await the call instead. The page holds its items
+in `data`, and `hasNextPage()` and `getNextPage()` move through the rest:
+
+```ts
+import { Allisall } from "@allisall/sdk";
+
+const client = new Allisall();
+
+const page = await client.agents.list({ limit: 50 });
+console.log(page.data.length, page.hasNextPage());
+```
+
+## Errors
+
+Every error from the API or the network is an `AllisallError`. An error
+response from the API is an `ApiError`, with the HTTP `status`, the API's
+error `code` and the `requestId` to quote when you report a problem.
+Branch on `code`:
+
+```ts
+import { Allisall, ApiError } from "@allisall/sdk";
+
+const client = new Allisall();
+
+try {
+  await client.clients.delete("CLIENT_ID");
+} catch (error) {
+  if (error instanceof ApiError && error.code === "client_has_events") {
+    // Events carry the client's key, so mark the client churned instead.
+    await client.clients.update("CLIENT_ID", { status: "churned" });
+  } else {
+    throw error;
+  }
+}
+```
+
+A `ConnectionError` means no response arrived, after any retries. A few
+errors are not an `AllisallError`. An argument the SDK cannot send, such
+as an invalid `Date`, throws a `TypeError` before anything is sent. An
+error thrown by your `tokenProvider` reaches you unchanged. A call you
+abort with `signal` rejects with the signal's reason.
+
+The SDK retries a failure worth retrying, twice by default; set
+`maxRetries` on the client or on one call to change that. It retries only
+a request that cannot take effect twice: a `GET`, `PUT` or `DELETE`;
+ingest, whose event ids deduplicate; and a call that carries an
+`Idempotency-Key`. The SDK sends that key, the same on every attempt,
+when it creates anything but an API key and when it commits an import. A
+`PATCH`, the calculation and report actions (validate, publish, reopen,
+share and revoke), revoking or creating an API key, an import preview,
+and setting a value model's line items are never retried. Setting line
+items is guarded by the model's `version`, which refuses a repeat of a
+write that already landed.
+
+## Sessions
+
+Some operations record a person's decision, such as publishing a
+calculation, sharing a report, or managing API keys. They take a signed-in
+user's session token, and refuse any API key with `403`
+`session_required`. Pass a `tokenProvider` that returns the current token.
+The client calls it before every attempt, so a refreshed token is picked
+up:
+
+```ts
+import { Allisall } from "@allisall/sdk";
+
+// Your sign-in library's way to read the signed-in user's session token.
+declare function currentSessionToken(): Promise<string>;
+
+const client = new Allisall({ tokenProvider: currentSessionToken });
+
+const calculation = await client.calculations.publish("CALCULATION_ID");
+console.log(calculation.state);
+```
+
+`getSharedReport(shareToken)` reads a shared report with its share token.
+It is a function rather than a client method, because it needs no API key
+and no session.
+
 ## Browsers
 
 An API key in a browser can be read by anyone who loads the page. The
@@ -81,6 +216,12 @@ const client = new Allisall({
 
 Prefer calling the API from your server.
 
+The SDK supports Chrome 114, Firefox 135 and Safari 18.4 and later. They are
+the first releases that read and write JSON numbers exactly, which the SDK
+needs for amounts of money. In an older browser, a call that sends a
+`Decimal` or receives an amount fails with an `AllisallError` that names
+the missing feature.
+
 ## Documentation
 
 See [https://docs.allisai.ai](https://docs.allisai.ai).

package/dist/client.d.ts

@@ -1,5 +1,19 @@
+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 { OnboardingOperations } from "./resources/onboarding.js";
+import { OutcomeTypes } from "./resources/outcome-types.js";
+import { Reports } from "./resources/reports.js";
+import { ValueModels } from "./resources/value-models.js";
+import { WorkspaceOperations } from "./resources/workspace.js";
 import { type FetchLike, type TokenProvider, type TransportConfig } from "./transport.js";
-import type { EventInput, IngestSummary } from "./types.js";
 /** The options of `new Allisall()`. Every one is optional. */
 export interface ClientOptions {
     /**
@@ -16,6 +30,10 @@ export interface ClientOptions {
     /**
      * The API's base URL, absolute, `http` or `https`. Defaults to
      * `AIA_BASE_URL` from the environment, then `https://api.allisai.ai`.
+     *
+     * In a browser it may also be a path on the page's own origin, starting
+     * with a single `/`, such as `/api` for a proxy. It is resolved against
+     * the page's address once, when the client is constructed.
      */
     baseURL?: string | undefined;
     /** The timeout of each attempt, in milliseconds. Defaults to 60,000. */
@@ -29,49 +47,81 @@ export interface ClientOptions {
      * read it. Defaults to `false`.
      */
     dangerouslyAllowBrowser?: boolean | undefined;
-}
-/** The options of one call. */
-export interface RequestOptions {
-    /** Cancels the call, including any wait between retries. */
-    signal?: AbortSignal | undefined;
-}
-/** The `events` operations. */
-declare class Events {
-    #private;
-    constructor(config: TransportConfig);
     /**
-     * Ingests any number of events. They are sent in batches of at most 500
-     * events and 5,000,000 bytes, one batch after another, each retried as
-     * the client allows. Every event without an `event_id` gets a generated
-     * one, so a retry never stores an event twice. Your objects are not
-     * modified.
-     *
-     * An event too large to send even alone is not sent, and is reported as a
-     * rejected row with the code `too_large`.
-     *
-     * @returns the combined outcome over the whole list.
-     * @throws {IngestError} when a batch fails; the call stops there, and the
-     * error carries the summary so far and every event from the failed batch
-     * onward, to send again. A batch fails on an error response, on no
-     * response, on the caller's cancellation, or when its token cannot be
-     * had: an error from `tokenProvider`, or, in a browser without
-     * `dangerouslyAllowBrowser`, a provider's token that is an API key. The
-     * error is the `IngestError`'s `cause`.
-     * @throws {TypeError} when an event cannot be encoded, before anything is sent.
+     * Headers sent on every request. They may not name `Authorization`,
+     * `Content-Type`, `Idempotency-Key` or `X-Request-Id`, which the SDK sets.
+     * A call's own `headers` are sent over them.
      */
-    ingest(events: readonly EventInput[], options?: RequestOptions): Promise<IngestSummary>;
+    defaultHeaders?: Readonly<Record<string, string>> | undefined;
 }
-/** The allisall API client. Construct one and reuse it. */
+/** The options a client and a shared-report call resolve alike. */
+export type TransportOptions = Pick<ClientOptions, "baseURL" | "timeout" | "maxRetries" | "fetch">;
+/**
+ * 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 declare function transportSettings(options: TransportOptions, browser: boolean): Pick<TransportConfig, "baseURL" | "timeout" | "maxRetries" | "fetch" | "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 declare function transportConfig(options: ClientOptions): TransportConfig;
+/**
+ * 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 declare class Allisall {
-    /** The `events` operations. */
+    /** Events: ingest, and the events behind a client's totals. */
     readonly events: Events;
+    /** CSV imports of events. */
+    readonly imports: Imports;
+    /** Clients, and the agents assigned to each. */
+    readonly clients: Clients;
+    /** Agents. */
+    readonly agents: Agents;
+    /** Value models, by their own id or by their client's, and value templates. */
+    readonly valueModels: ValueModels;
+    /** Outcome types, for the workspace or for one client. */
+    readonly outcomeTypes: OutcomeTypes;
+    /** Cost line items and the price table. */
+    readonly cost: Cost;
+    /** A client's value, cost, ROI and anomalies over a period. */
+    readonly analytics: Analytics;
+    /** Calculations, and the human steps that validate, publish and reopen them. */
+    readonly calculations: Calculations;
+    /** Reports on calculations, and the human steps that share and revoke them. */
+    readonly reports: Reports;
+    /** The workspace's month, and renewal readiness. */
+    readonly dashboard: DashboardOperations;
+    /** API keys, managed with a session token. */
+    readonly apiKeys: ApiKeys;
+    /** The API's liveness. */
+    readonly health: HealthOperations;
+    /** The workspace the credential belongs to. */
+    readonly workspace: WorkspaceOperations;
+    /** The guided setup's progress, and the steps skipped in it. */
+    readonly onboarding: OnboardingOperations;
     /**
      * @throws {AllisallError} when there is no credential, or both an API key
-     * and a token provider; when the base URL is not an absolute `http` or
-     * `https` URL; when `maxRetries` is negative or `timeout` is not
-     * positive; or when an API key is used in a browser without
-     * `dangerouslyAllowBrowser`.
+     * 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?: ClientOptions);
 }
-export {};

package/dist/client.js

@@ -1,12 +1,25 @@
 // The client: its options, and how the credential and the base URL are
 // resolved at construction.
 import { AllisallError } from "./errors.js";
-import { ingest, readIngestResult } from "./ingest.js";
-import { isBrowser, readEnv, userAgent } from "./runtime.js";
-import { BROWSER_KEY_MESSAGE, isPrintableCredential, post, } from "./transport.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 { OnboardingOperations } from "./resources/onboarding.js";
+import { OutcomeTypes } from "./resources/outcome-types.js";
+import { Reports } from "./resources/reports.js";
+import { ValueModels } from "./resources/value-models.js";
+import { WorkspaceOperations } from "./resources/workspace.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";
-const DEFAULT_TIMEOUT_MS = 60_000;
-const DEFAULT_MAX_RETRIES = 2;
 function resolveCredential(options) {
     const { apiKey, tokenProvider } = options;
     if (apiKey !== undefined && tokenProvider !== undefined) {
@@ -38,93 +51,151 @@ function resolveCredential(options) {
     }
     throw new AllisallError("allisall: no credential; pass apiKey or tokenProvider, or set AIA_API_KEY");
 }
-function resolveBaseURL(option) {
+/** 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 = new URL(raw);
+        url = page === undefined ? new URL(raw) : new URL(raw, page);
     }
     catch {
-        throw new AllisallError(`allisall: the base URL ${JSON.stringify(raw)} is not an absolute URL`);
+        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;
 }
-function resolveTimeout(option) {
-    const timeout = option ?? DEFAULT_TIMEOUT_MS;
-    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;
+/**
+ * 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(),
+    };
 }
-function resolveMaxRetries(option) {
-    const maxRetries = option ?? DEFAULT_MAX_RETRIES;
-    if (!Number.isInteger(maxRetries) || maxRetries < 0) {
-        throw new AllisallError(`allisall: maxRetries must be a whole number, 0 or more, not ${String(maxRetries)}`);
+/**
+ * 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 maxRetries;
+    return {
+        ...transportSettings(options, browser),
+        credential,
+        refuseApiKeys,
+        defaultHeaders: resolveHeaders(options.defaultHeaders, "defaultHeaders"),
+    };
 }
-/** The `events` operations. */
-class Events {
-    #config;
-    constructor(config) {
-        this.#config = config;
-    }
-    /**
-     * Ingests any number of events. They are sent in batches of at most 500
-     * events and 5,000,000 bytes, one batch after another, each retried as
-     * the client allows. Every event without an `event_id` gets a generated
-     * one, so a retry never stores an event twice. Your objects are not
-     * modified.
-     *
-     * An event too large to send even alone is not sent, and is reported as a
-     * rejected row with the code `too_large`.
-     *
-     * @returns the combined outcome over the whole list.
-     * @throws {IngestError} when a batch fails; the call stops there, and the
-     * error carries the summary so far and every event from the failed batch
-     * onward, to send again. A batch fails on an error response, on no
-     * response, on the caller's cancellation, or when its token cannot be
-     * had: an error from `tokenProvider`, or, in a browser without
-     * `dangerouslyAllowBrowser`, a provider's token that is an API key. The
-     * error is the `IngestError`'s `cause`.
-     * @throws {TypeError} when an event cannot be encoded, before anything is sent.
-     */
-    ingest(events, options = {}) {
-        const config = this.#config;
-        return ingest(events, (body, count, signal) => post(config, "/v1/events", body, (value) => readIngestResult(value, count), signal), options.signal);
-    }
-}
-/** The allisall API client. Construct one and reuse it. */
+/**
+ * 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 {
-    /** The `events` operations. */
+    /** 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;
+    /** The workspace the credential belongs to. */
+    workspace;
+    /** The guided setup's progress, and the steps skipped in it. */
+    onboarding;
     /**
      * @throws {AllisallError} when there is no credential, or both an API key
-     * and a token provider; when the base URL is not an absolute `http` or
-     * `https` URL; when `maxRetries` is negative or `timeout` is not
-     * positive; or when an API key is used in a browser without
-     * `dangerouslyAllowBrowser`.
+     * 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 credential = resolveCredential(options);
-        const browser = isBrowser();
-        const refuseApiKeys = browser && options.dangerouslyAllowBrowser !== true;
-        if (refuseApiKeys && credential.kind === "apiKey") {
-            throw new AllisallError(BROWSER_KEY_MESSAGE);
-        }
-        this.events = new Events({
-            baseURL: resolveBaseURL(options.baseURL),
-            credential,
-            timeout: resolveTimeout(options.timeout),
-            maxRetries: resolveMaxRetries(options.maxRetries),
-            fetch: options.fetch,
-            refuseApiKeys,
-            userAgent: userAgent(),
-        });
+        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);
+        this.workspace = new WorkspaceOperations(config);
+        this.onboarding = new OnboardingOperations(config);
     }
 }