@allisall/sdk 0.1.0 → 0.2.0

package/dist/resources/value-models.d.ts

@@ -0,0 +1,92 @@
+import type { MoneyInput } from "../money.js";
+import type { IdempotentRequestOptions, RequestOptions } from "../options.js";
+import type { PagePromise } from "../pagination.js";
+import type { TransportConfig } from "../transport.js";
+import type { ListValueModelsQuery, ListValueTemplatesQuery, ValueLineItemsSet, ValueModel, ValueModelCreate, ValueModelList, ValueModelPatch, ValueModelSummary, ValueTemplate, ValueTemplateList } from "../types.js";
+/** The `valueModels` operations. */
+export declare class ValueModels {
+    #private;
+    constructor(config: TransportConfig);
+    /**
+     * Lists value models. Await the result for one page; iterate it with
+     * `for await` for every value model of every page.
+     *
+     * Needs the `read` scope. Operation `listValueModels`.
+     */
+    list(query?: ListValueModelsQuery, options?: RequestOptions): PagePromise<ValueModelSummary, ValueModelList>;
+    /**
+     * Reads a value model by its own id: any model in the workspace,
+     * archived ones included.
+     *
+     * Needs the `read` scope. Operation `getValueModel`.
+     *
+     * @param id - the value model's id, not its client's.
+     */
+    get(id: string, options?: RequestOptions): Promise<ValueModel>;
+    /**
+     * Reads a client's active value model.
+     *
+     * Needs the `read` scope. Operation `getClientValueModel`.
+     *
+     * @param clientId - the client's id.
+     */
+    getForClient(clientId: string, options?: RequestOptions): Promise<ValueModel>;
+    /**
+     * Creates a client's value model.
+     *
+     * Every attempt of the call sends one `Idempotency-Key`, so a retry
+     * cannot create a second value model.
+     *
+     * Needs the `write` scope. Operation `createValueModel`.
+     *
+     * @param clientId - the client's id.
+     */
+    createForClient(clientId: string, body: ValueModelCreate, options?: IdempotentRequestOptions): Promise<ValueModel>;
+    /**
+     * Updates a client's active value model 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 `updateValueModel`.
+     *
+     * @param clientId - the client's id.
+     */
+    updateForClient(clientId: string, patch: ValueModelPatch, options?: RequestOptions): Promise<ValueModel>;
+    /**
+     * Deletes a client's active value model.
+     *
+     * A retry after a lost response can answer `404` for a delete that
+     * succeeded.
+     *
+     * Needs the `write` scope. Operation `deleteValueModel`.
+     *
+     * @param clientId - the client's id.
+     */
+    deleteForClient(clientId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Replaces the line items of a client's active value model, as a whole
+     * set. It is guarded by `version`: a stale version is refused rather
+     * than overwriting a co-editor's change.
+     *
+     * Each `unit_value` takes a `Decimal` or a `number`.
+     *
+     * Never retried, because the `version` guard refuses a repeat of a write
+     * that already landed as a stale version. On a `ConnectionError` the
+     * write may have landed: read the value model again for its current
+     * `version` before trying again.
+     *
+     * Needs the `write` scope. Operation `setValueModelLineItems`.
+     *
+     * @param clientId - the client's id.
+     */
+    setLineItemsForClient(clientId: string, body: MoneyInput<ValueLineItemsSet>, options?: RequestOptions): Promise<ValueModel>;
+    /**
+     * Lists value templates. Await the result for one page; iterate it with
+     * `for await` for every template of every page.
+     *
+     * Needs the `read` scope. Operation `listValueTemplates`.
+     */
+    listTemplates(query?: ListValueTemplatesQuery, options?: RequestOptions): PagePromise<ValueTemplate, ValueTemplateList>;
+}

package/dist/resources/value-models.js

@@ -0,0 +1,126 @@
+// The `valueModels` operations: value models, read by their own id or
+// through the client they belong to, and value templates.
+import { call, callPage } from "../request.js";
+/** The `valueModels` operations. */
+export class ValueModels {
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    /**
+     * Lists value models. Await the result for one page; iterate it with
+     * `for await` for every value model of every page.
+     *
+     * Needs the `read` scope. Operation `listValueModels`.
+     */
+    list(query, options) {
+        return callPage(this.#config, "listValueModels", { query, options });
+    }
+    /**
+     * Reads a value model by its own id: any model in the workspace,
+     * archived ones included.
+     *
+     * Needs the `read` scope. Operation `getValueModel`.
+     *
+     * @param id - the value model's id, not its client's.
+     */
+    get(id, options) {
+        return call(this.#config, "getValueModel", { path: { id }, options });
+    }
+    /**
+     * Reads a client's active value model.
+     *
+     * Needs the `read` scope. Operation `getClientValueModel`.
+     *
+     * @param clientId - the client's id.
+     */
+    getForClient(clientId, options) {
+        return call(this.#config, "getClientValueModel", {
+            path: { id: clientId },
+            options,
+        });
+    }
+    /**
+     * Creates a client's value model.
+     *
+     * Every attempt of the call sends one `Idempotency-Key`, so a retry
+     * cannot create a second value model.
+     *
+     * Needs the `write` scope. Operation `createValueModel`.
+     *
+     * @param clientId - the client's id.
+     */
+    createForClient(clientId, body, options) {
+        return call(this.#config, "createValueModel", {
+            path: { id: clientId },
+            body,
+            options,
+        });
+    }
+    /**
+     * Updates a client's active value model 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 `updateValueModel`.
+     *
+     * @param clientId - the client's id.
+     */
+    updateForClient(clientId, patch, options) {
+        return call(this.#config, "updateValueModel", {
+            path: { id: clientId },
+            body: patch,
+            options,
+        });
+    }
+    /**
+     * Deletes a client's active value model.
+     *
+     * A retry after a lost response can answer `404` for a delete that
+     * succeeded.
+     *
+     * Needs the `write` scope. Operation `deleteValueModel`.
+     *
+     * @param clientId - the client's id.
+     */
+    deleteForClient(clientId, options) {
+        return call(this.#config, "deleteValueModel", {
+            path: { id: clientId },
+            options,
+        });
+    }
+    /**
+     * Replaces the line items of a client's active value model, as a whole
+     * set. It is guarded by `version`: a stale version is refused rather
+     * than overwriting a co-editor's change.
+     *
+     * Each `unit_value` takes a `Decimal` or a `number`.
+     *
+     * Never retried, because the `version` guard refuses a repeat of a write
+     * that already landed as a stale version. On a `ConnectionError` the
+     * write may have landed: read the value model again for its current
+     * `version` before trying again.
+     *
+     * Needs the `write` scope. Operation `setValueModelLineItems`.
+     *
+     * @param clientId - the client's id.
+     */
+    setLineItemsForClient(clientId, body, options) {
+        return call(this.#config, "setValueModelLineItems", {
+            path: { id: clientId },
+            body,
+            options,
+        });
+    }
+    /**
+     * Lists value templates. Await the result for one page; iterate it with
+     * `for await` for every template of every page.
+     *
+     * Needs the `read` scope. Operation `listValueTemplates`.
+     */
+    listTemplates(query, options) {
+        return callPage(this.#config, "listValueTemplates", { query, options });
+    }
+}

package/dist/runtime.d.ts

@@ -1,3 +1,5 @@
+/** Reads a global by name, so a runtime without it is never touched. */
+export declare function globalValue(name: string): unknown;
 /**
  * Reports whether the SDK runs in a browser: a window, where `document`
  * is defined, or a Web Worker, where `globalThis` is an instance of

package/dist/runtime.js

@@ -3,7 +3,8 @@
 // `globalThis` by name, so a runtime without them, such as a browser
 // without `process`, is never touched.
 import { VERSION } from "./version.js";
-function globalValue(name) {
+/** Reads a global by name, so a runtime without it is never touched. */
+export function globalValue(name) {
     const value = Reflect.get(globalThis, name);
     return value;
 }

package/dist/share.d.ts

@@ -0,0 +1,52 @@
+import { type FetchLike } from "./transport.js";
+import type { PublicReport } from "./types.js";
+/** The options of `getSharedReport`. Every one is optional. */
+export interface SharedReportOptions {
+    /**
+     * 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 `/`.
+     */
+    baseURL?: string | undefined;
+    /** The timeout of each attempt, in milliseconds. Defaults to 60,000. */
+    timeout?: number | undefined;
+    /** How many times a failure worth repeating is retried. Defaults to 2; 0 turns retries off. */
+    maxRetries?: number | undefined;
+    /** The `fetch` to send the request with. Defaults to the platform's own. */
+    fetch?: FetchLike | undefined;
+    /** Cancels the call, including any wait between retries. */
+    signal?: AbortSignal | undefined;
+    /**
+     * Extra headers to send. They may not name `Authorization`,
+     * `Content-Type`, `Idempotency-Key` or `X-Request-Id`, which the SDK sets.
+     */
+    headers?: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * Reads a shared report with its share token, as the report's recipient
+ * sees it. Needs no API key and no session, and never reads `AIA_API_KEY`.
+ *
+ * A share token is a bearer capability: anyone holding it can read the
+ * report. Handle it like a secret, and keep it out of URLs and logs. The
+ * SDK sends it only in the `Authorization` header, as
+ * `Authorization: Report <token>`, and keeps it for this call alone.
+ *
+ * Every failure, a missing, unknown or revoked token included, is the same
+ * `404`, as an `ApiError`. Each read stamps the report's view times, and a
+ * retry after a lost response stamps them again.
+ *
+ * Operation `getSharedReport`.
+ *
+ * @param shareToken - the report's share token.
+ * @throws {AllisallError} when the share token is empty or holds a
+ * character other than printable ASCII, or an option is one a client would
+ * refuse, before anything is sent.
+ * @throws {TypeError} when `options.headers` is not a plain object of
+ * header names and string values, or names a header the SDK sets, before
+ * anything is sent.
+ * @throws {ApiError} for an error response, such as the `404` for a token
+ * that reads no report.
+ * @throws {ConnectionError} when no response arrived, after any retries.
+ */
+export declare function getSharedReport(shareToken: string, options?: SharedReportOptions): Promise<PublicReport>;

package/dist/share.js

@@ -0,0 +1,60 @@
+// Reading a shared report with its share token. It is a function, not a
+// client method: its caller, such as a server rendering the report's page,
+// holds no API key and no session, which a client requires.
+import { transportSettings } from "./client.js";
+import { AllisallError } from "./errors.js";
+import { request } from "./request.js";
+import { isBrowser } from "./runtime.js";
+import { isPrintableCredential, } from "./transport.js";
+/** Trims a share token and checks it can travel in a header. */
+function checkedShareToken(shareToken) {
+    const token = typeof shareToken === "string" ? shareToken.trim() : "";
+    if (token === "") {
+        throw new AllisallError("allisall: the share token is empty");
+    }
+    if (!isPrintableCredential(token)) {
+        throw new AllisallError("allisall: the share token holds a character other than printable ASCII, which cannot be sent");
+    }
+    return token;
+}
+/**
+ * Reads a shared report with its share token, as the report's recipient
+ * sees it. Needs no API key and no session, and never reads `AIA_API_KEY`.
+ *
+ * A share token is a bearer capability: anyone holding it can read the
+ * report. Handle it like a secret, and keep it out of URLs and logs. The
+ * SDK sends it only in the `Authorization` header, as
+ * `Authorization: Report <token>`, and keeps it for this call alone.
+ *
+ * Every failure, a missing, unknown or revoked token included, is the same
+ * `404`, as an `ApiError`. Each read stamps the report's view times, and a
+ * retry after a lost response stamps them again.
+ *
+ * Operation `getSharedReport`.
+ *
+ * @param shareToken - the report's share token.
+ * @throws {AllisallError} when the share token is empty or holds a
+ * character other than printable ASCII, or an option is one a client would
+ * refuse, before anything is sent.
+ * @throws {TypeError} when `options.headers` is not a plain object of
+ * header names and string values, or names a header the SDK sets, before
+ * anything is sent.
+ * @throws {ApiError} for an error response, such as the `404` for a token
+ * that reads no report.
+ * @throws {ConnectionError} when no response arrived, after any retries.
+ */
+export async function getSharedReport(shareToken, options = {}) {
+    const token = checkedShareToken(shareToken);
+    const config = {
+        ...transportSettings(options, isBrowser()),
+        // The share token is the call's only credential, and it is not an API
+        // key, so no browser opt-in applies. No client sends default headers.
+        credential: undefined,
+        refuseApiKeys: false,
+        defaultHeaders: {},
+    };
+    return request(config, "getSharedReport", {
+        shareToken: token,
+        options: { signal: options.signal, headers: options.headers },
+    });
+}

package/dist/transport.d.ts

@@ -14,7 +14,11 @@ export type Credential = {
 /** Everything an attempt needs, fixed when the client is constructed. */
 export interface TransportConfig {
     readonly baseURL: URL;
-    readonly credential: Credential;
+    /**
+     * The client's credential. Absent for a shared report, whose call carries
+     * its own share token and sends no client credential.
+     */
+    readonly credential: Credential | undefined;
     readonly timeout: number;
     readonly maxRetries: number;
     readonly fetch: FetchLike | undefined;
@@ -22,6 +26,8 @@ export interface TransportConfig {
     readonly refuseApiKeys: boolean;
     /** The `User-Agent` to send; `undefined` in a browser. */
     readonly userAgent: string | undefined;
+    /** Headers sent on every request, already checked. */
+    readonly defaultHeaders: Readonly<Record<string, string>>;
 }
 /** The message of the error refusing an API key in a browser. */
 export declare const BROWSER_KEY_MESSAGE: string;
@@ -46,8 +52,51 @@ export declare function isPrintableCredential(credential: string): boolean;
  */
 export declare function readProblem(contentType: string | null, text: string): Problem | undefined;
 /**
- * Posts a JSON body, retrying a failure worth repeating. The body is the
- * same bytes on every attempt. Each attempt reads a fresh token and sends
- * a fresh `X-Request-Id`.
+ * How a successful body is read. `undefined` means the body was not the
+ * expected shape, which is an `ApiError` carrying the status.
  */
-export declare function post<T>(config: TransportConfig, path: string, body: Uint8Array, read: (body: unknown) => T | undefined, signal: AbortSignal | undefined): Promise<T>;
+export type ReadBody<T> = (text: string) => {
+    readonly value: T;
+} | undefined;
+/**
+ * The `Authorization` a request sends: the client's credential as a bearer,
+ * none, or a share token under the `Report` scheme.
+ */
+export type Authorization = "bearer" | "none" | {
+    readonly report: string;
+};
+/** One request, fixed before the first attempt and sent unchanged on each. */
+export interface Outgoing {
+    readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    readonly url: string;
+    readonly authorization: Authorization;
+    /** The body: bytes, or a form whose boundary `fetch` writes. */
+    readonly body: Uint8Array | FormData | undefined;
+    /** The body's `Content-Type`; `undefined` for no body, or a form. */
+    readonly contentType: string | undefined;
+    /** The `Idempotency-Key` sent on every attempt, if any. */
+    readonly idempotencyKey: string | undefined;
+}
+/** What one call may do, from its operation and its options. */
+export interface CallPolicy {
+    readonly timeout: number;
+    readonly maxRetries: number;
+    /** The call's headers, already checked. */
+    readonly headers: Readonly<Record<string, string>>;
+    readonly signal: AbortSignal | undefined;
+    /** Whether a retry cannot apply the request twice, so it may be retried at all. */
+    readonly eligible: boolean;
+    /** Whether a `409` `idempotency_key_in_use` is retried: the request carries a reused key. */
+    readonly retryKeyInUse: boolean;
+}
+/**
+ * Sends a request, retrying a failure worth repeating when the request is
+ * eligible. The body is the same on every attempt. Each attempt reads a
+ * fresh token and sends a fresh `X-Request-Id`.
+ */
+export declare function send<T>(config: TransportConfig, out: Outgoing, read: ReadBody<T>, policy: CallPolicy): Promise<T>;
+/**
+ * Posts a JSON body that a retry cannot apply twice, such as an ingest
+ * batch, retrying a failure worth repeating.
+ */
+export declare function post<T>(config: TransportConfig, path: string, body: Uint8Array, read: (body: unknown) => T | undefined, policy: Omit<CallPolicy, "eligible" | "retryKeyInUse">): Promise<T>;

package/dist/transport.js

@@ -1,6 +1,8 @@
 // One HTTP attempt (headers, timeout, reading the response) and the loop
-// that repeats it under the retry rules in retry.ts.
+// that repeats it under the retry rules in retry.ts, for any method and
+// any body.
 import { AllisallError, ApiError, ConnectionError } from "./errors.js";
+import { mergeHeaders } from "./options.js";
 import { backoffMs, isRetryableStatus, MAX_RETRY_AFTER_MS, parseRetryAfter, sleep, } from "./retry.js";
 import { uuidv4 } from "./uuid.js";
 /** The message of the error refusing an API key in a browser. */
@@ -33,6 +35,9 @@ export function isPrintableCredential(credential) {
 }
 async function bearerToken(config) {
     const { credential } = config;
+    if (credential === undefined) {
+        throw new AllisallError("allisall: this call has no client credential");
+    }
     if (credential.kind === "apiKey")
         return credential.apiKey;
     const raw = await credential.provider();
@@ -121,33 +126,41 @@ function headerOrUndefined(headers, name) {
     return headers.get(name) ?? undefined;
 }
 /**
- * Sends one attempt. Resolves with the parsed `2xx` body; throws an
+ * Sends one attempt. Resolves with the read `2xx` body; throws an
  * `ApiError` for any other status or an unreadable `2xx` body, a
  * `ConnectionError` when no response arrived, or the caller's abort reason.
  */
-async function attempt(config, url, body, read, token, requestId, signal) {
-    const headers = {
-        Authorization: `Bearer ${token}`,
-        "Content-Type": "application/json",
-        "X-Request-Id": requestId,
-    };
+async function attempt(config, out, read, authorization, requestId, policy) {
+    const headers = {};
+    if (authorization !== undefined)
+        headers.Authorization = authorization;
+    if (out.contentType !== undefined)
+        headers["Content-Type"] = out.contentType;
+    headers["X-Request-Id"] = requestId;
     if (config.userAgent !== undefined)
         headers["User-Agent"] = config.userAgent;
-    const timeout = AbortSignal.timeout(config.timeout);
+    if (out.idempotencyKey !== undefined) {
+        headers["Idempotency-Key"] = out.idempotencyKey;
+    }
+    mergeHeaders(headers, config.defaultHeaders);
+    mergeHeaders(headers, policy.headers);
+    const { signal } = policy;
+    const timeout = AbortSignal.timeout(policy.timeout);
     const combined = signal === undefined ? timeout : AbortSignal.any([signal, timeout]);
     const doFetch = config.fetch ?? globalThis.fetch;
+    const init = {
+        method: out.method,
+        headers,
+        ...(out.body === undefined ? {} : { body: out.body }),
+        signal: combined,
+        // A redirect is never followed, so Authorization never travels to
+        // another location.
+        redirect: "manual",
+    };
     let response;
     let text;
     try {
-        response = await doFetch(url, {
-            method: "POST",
-            headers,
-            body,
-            signal: combined,
-            // A redirect is never followed, so Authorization never travels to
-            // another location.
-            redirect: "manual",
-        });
+        response = await doFetch(out.url, init);
         text = await response.text();
     }
     catch (err) {
@@ -167,10 +180,9 @@ async function attempt(config, url, body, read, token, requestId, signal) {
         });
     }
     if (status >= 200 && status < 300) {
-        const parsed = parseJSON(text);
-        const value = parsed === undefined ? undefined : read(parsed);
-        if (value !== undefined)
-            return value;
+        const result = read(text);
+        if (result !== undefined)
+            return result.value;
         throw new ApiError({
             status,
             headers: response.headers,
@@ -186,24 +198,43 @@ async function attempt(config, url, body, read, token, requestId, signal) {
         headers: response.headers,
     });
 }
+function worthRepeating(err, policy) {
+    if (err instanceof ConnectionError)
+        return true;
+    if (isRetryableStatus(err.status))
+        return true;
+    // The first request with this key is still running; a later attempt can
+    // collect its outcome.
+    return (policy.retryKeyInUse &&
+        err.status === 409 &&
+        err.code === "idempotency_key_in_use");
+}
+/** The `Authorization` value of one attempt, reading a fresh bearer token. */
+async function authorizationOf(config, out) {
+    const { authorization } = out;
+    if (authorization === "none")
+        return undefined;
+    if (authorization === "bearer")
+        return `Bearer ${await bearerToken(config)}`;
+    return `Report ${authorization.report}`;
+}
 /**
- * Posts a JSON body, retrying a failure worth repeating. The body is the
- * same bytes on every attempt. Each attempt reads a fresh token and sends
- * a fresh `X-Request-Id`.
+ * Sends a request, retrying a failure worth repeating when the request is
+ * eligible. The body is the same on every attempt. Each attempt reads a
+ * fresh token and sends a fresh `X-Request-Id`.
  */
-export async function post(config, path, body, read, signal) {
-    const url = joinURL(config.baseURL, path);
+export async function send(config, out, read, policy) {
+    const maxRetries = policy.eligible ? policy.maxRetries : 0;
     for (let retry = 0;; retry++) {
         // An error from the token provider ends the call unwrapped and unretried.
-        const token = await bearerToken(config);
+        const authorization = await authorizationOf(config, out);
         try {
-            return await attempt(config, url, body, read, token, uuidv4(), signal);
+            return await attempt(config, out, read, authorization, uuidv4(), policy);
         }
         catch (err) {
             if (!(err instanceof ApiError || err instanceof ConnectionError))
                 throw err;
-            const retryable = err instanceof ConnectionError || isRetryableStatus(err.status);
-            if (!retryable || retry >= config.maxRetries)
+            if (!worthRepeating(err, policy) || retry >= maxRetries)
                 throw err;
             let wait;
             if (err instanceof ApiError && err.retryAfter !== undefined) {
@@ -214,7 +245,25 @@ export async function post(config, path, body, read, signal) {
             else {
                 wait = backoffMs(retry + 1);
             }
-            await sleep(wait, signal);
+            await sleep(wait, policy.signal);
         }
     }
 }
+/**
+ * Posts a JSON body that a retry cannot apply twice, such as an ingest
+ * batch, retrying a failure worth repeating.
+ */
+export function post(config, path, body, read, policy) {
+    return send(config, {
+        method: "POST",
+        url: joinURL(config.baseURL, path),
+        authorization: "bearer",
+        body,
+        contentType: "application/json",
+        idempotencyKey: undefined,
+    }, (text) => {
+        const parsed = parseJSON(text);
+        const value = parsed === undefined ? undefined : read(parsed);
+        return value === undefined ? undefined : { value };
+    }, { ...policy, eligible: true, retryKeyInUse: false });
+}