@allisall/sdk 0.0.0-stage → 0.2.0

package/dist/resources/events.js

@@ -0,0 +1,69 @@
+// The `events` operations: ingest, and the event drill-down.
+import { OPERATIONS } from "../generated/operations.js";
+import { ingest, readIngestResult } from "../ingest.js";
+import { callPage, policyOf } from "../request.js";
+import { post } from "../transport.js";
+/** The `events` operations. */
+export class Events {
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    /**
+     * Ingests any number of events. They are sent in batches of at most 500
+     * events and 4,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, or `options.headers`
+     * names a header the SDK sets, before anything is sent.
+     * @throws {AllisallError} when `options.timeout` or `options.maxRetries` is
+     * one the client would refuse, before anything is sent.
+     */
+    ingest(events, options = {}) {
+        const config = this.#config;
+        let policy;
+        try {
+            policy = policyOf(config, "ingestEvents", OPERATIONS.ingestEvents, options);
+        }
+        catch (err) {
+            return Promise.reject(err);
+        }
+        // Each batch has its own signal; ingest is always eligible for a retry,
+        // because event_id deduplicates, which post() sets.
+        const { timeout, maxRetries, headers } = policy;
+        return ingest(events, (body, count, signal) => post(config, OPERATIONS.ingestEvents.path, body, (value) => readIngestResult(value, count), { timeout, maxRetries, headers, signal }), options.signal);
+    }
+    /**
+     * Lists the events behind a client's totals: the event drill-down, over
+     * the period `from` to `to`.
+     *
+     * Pass `page` or `cursor`, not both; neither means page 1. A `page`
+     * beyond the end returns no rows and the true `total`. Await the result
+     * for one page, whose `body` holds `total` and `period`; iterate it with
+     * `for await` for every event of every page from there.
+     *
+     * Needs the `read` scope. Operation `listClientEvents`.
+     *
+     * @param clientId - the client's id.
+     */
+    listForClient(clientId, query, options) {
+        return callPage(this.#config, "listClientEvents", {
+            path: { id: clientId },
+            query,
+            options,
+        });
+    }
+}

package/dist/resources/health.d.ts

@@ -0,0 +1,14 @@
+import type { RequestOptions } from "../options.js";
+import type { TransportConfig } from "../transport.js";
+import type { Health } from "../types.js";
+/** The `health` operations. */
+export declare class HealthOperations {
+    #private;
+    constructor(config: TransportConfig);
+    /**
+     * Checks liveness. Sends no credential.
+     *
+     * Operation `getHealth`.
+     */
+    get(options?: RequestOptions): Promise<Health>;
+}

package/dist/resources/health.js

@@ -0,0 +1,17 @@
+// The `health` operations.
+import { call } from "../request.js";
+/** The `health` operations. */
+export class HealthOperations {
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    /**
+     * Checks liveness. Sends no credential.
+     *
+     * Operation `getHealth`.
+     */
+    get(options) {
+        return call(this.#config, "getHealth", { options });
+    }
+}

package/dist/resources/imports.d.ts

@@ -0,0 +1,33 @@
+import type { ImportUpload } from "../multipart.js";
+import type { IdempotentRequestOptions, RequestOptions } from "../options.js";
+import type { TransportConfig } from "../transport.js";
+import type { ImportPreview, ImportResult } from "../types.js";
+/** The `imports` operations. */
+export declare class Imports {
+    #private;
+    constructor(config: TransportConfig);
+    /**
+     * Previews a CSV import: parses, maps and validates the file exactly as
+     * `commit` would, and writes nothing.
+     *
+     * Never retried, although it writes nothing; repeat the call to try
+     * again.
+     *
+     * Needs the `ingest` scope. Operation `previewImport`.
+     */
+    preview(upload: ImportUpload, options?: RequestOptions): Promise<ImportPreview>;
+    /**
+     * Imports a CSV file: stores its valid rows and records an import batch.
+     * A problem with one row rejects that row only. The result lists the
+     * problems of the rejected rows, one `errors` entry per problem, up to the
+     * first 1,000; `errors_truncated` says when more were omitted, and the
+     * counts always cover the whole file. Events deduplicate as they do on
+     * ingest.
+     *
+     * Every attempt of the call sends one `Idempotency-Key`, so a retry
+     * cannot record a second import batch.
+     *
+     * Needs the `ingest` scope. Operation `commitImport`.
+     */
+    commit(upload: ImportUpload, options?: IdempotentRequestOptions): Promise<ImportResult>;
+}

package/dist/resources/imports.js

@@ -0,0 +1,37 @@
+// The `imports` operations: a CSV file of events, previewed or committed.
+import { call } from "../request.js";
+/** The `imports` operations. */
+export class Imports {
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    /**
+     * Previews a CSV import: parses, maps and validates the file exactly as
+     * `commit` would, and writes nothing.
+     *
+     * Never retried, although it writes nothing; repeat the call to try
+     * again.
+     *
+     * Needs the `ingest` scope. Operation `previewImport`.
+     */
+    preview(upload, options) {
+        return call(this.#config, "previewImport", { body: upload, options });
+    }
+    /**
+     * Imports a CSV file: stores its valid rows and records an import batch.
+     * A problem with one row rejects that row only. The result lists the
+     * problems of the rejected rows, one `errors` entry per problem, up to the
+     * first 1,000; `errors_truncated` says when more were omitted, and the
+     * counts always cover the whole file. Events deduplicate as they do on
+     * ingest.
+     *
+     * Every attempt of the call sends one `Idempotency-Key`, so a retry
+     * cannot record a second import batch.
+     *
+     * Needs the `ingest` scope. Operation `commitImport`.
+     */
+    commit(upload, options) {
+        return call(this.#config, "commitImport", { body: upload, options });
+    }
+}

package/dist/resources/outcome-types.d.ts

@@ -0,0 +1,25 @@
+import type { RequestOptions } from "../options.js";
+import type { PagePromise } from "../pagination.js";
+import type { TransportConfig } from "../transport.js";
+import type { ListClientOutcomeTypesQuery, ListOutcomeTypesQuery, OutcomeTypeList, OutcomeTypeUsage } from "../types.js";
+/** The `outcomeTypes` operations. */
+export declare class OutcomeTypes {
+    #private;
+    constructor(config: TransportConfig);
+    /**
+     * Lists the workspace's outcome types. Await the result for one page;
+     * iterate it with `for await` for every outcome type of every page.
+     *
+     * Needs the `read` scope. Operation `listOutcomeTypes`.
+     */
+    list(query?: ListOutcomeTypesQuery, options?: RequestOptions): PagePromise<OutcomeTypeUsage, OutcomeTypeList>;
+    /**
+     * Lists a client's outcome types. Await the result for one page; iterate
+     * it with `for await` for every outcome type of every page.
+     *
+     * Needs the `read` scope. Operation `listClientOutcomeTypes`.
+     *
+     * @param clientId - the client's id.
+     */
+    listForClient(clientId: string, query?: ListClientOutcomeTypesQuery, options?: RequestOptions): PagePromise<OutcomeTypeUsage, OutcomeTypeList>;
+}

package/dist/resources/outcome-types.js

@@ -0,0 +1,33 @@
+// The `outcomeTypes` operations.
+import { callPage } from "../request.js";
+/** The `outcomeTypes` operations. */
+export class OutcomeTypes {
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    /**
+     * Lists the workspace's outcome types. Await the result for one page;
+     * iterate it with `for await` for every outcome type of every page.
+     *
+     * Needs the `read` scope. Operation `listOutcomeTypes`.
+     */
+    list(query, options) {
+        return callPage(this.#config, "listOutcomeTypes", { query, options });
+    }
+    /**
+     * Lists a client's outcome types. Await the result for one page; iterate
+     * it with `for await` for every outcome type of every page.
+     *
+     * Needs the `read` scope. Operation `listClientOutcomeTypes`.
+     *
+     * @param clientId - the client's id.
+     */
+    listForClient(clientId, query, options) {
+        return callPage(this.#config, "listClientOutcomeTypes", {
+            path: { id: clientId },
+            query,
+            options,
+        });
+    }
+}

package/dist/resources/reports.d.ts

@@ -0,0 +1,77 @@
+import type { IdempotentRequestOptions, RequestOptions } from "../options.js";
+import type { PagePromise } from "../pagination.js";
+import type { TransportConfig } from "../transport.js";
+import type { ListCalculationReportsQuery, Report, ReportList, ReportPatch, ReportSummary, ReportWithPreview } from "../types.js";
+/** The `reports` operations. */
+export declare class Reports {
+    #private;
+    constructor(config: TransportConfig);
+    /**
+     * Composes a report on a published calculation, with its disclosures
+     * taken from the calculation's coverage.
+     *
+     * Every attempt of the call sends one `Idempotency-Key`, so a retry
+     * cannot create a second report.
+     *
+     * Needs the `write` scope. Operation `createReport`.
+     *
+     * @param calculationId - the calculation's id.
+     */
+    createForCalculation(calculationId: string, options?: IdempotentRequestOptions): Promise<Report>;
+    /**
+     * Lists a calculation's reports. Await the result for one page; iterate
+     * it with `for await` for every report of every page. Each item is a
+     * summary without `disclosures`; `get` reads a report with them.
+     *
+     * Needs the `read` scope. Operation `listCalculationReports`.
+     *
+     * @param calculationId - the calculation's id.
+     */
+    listForCalculation(calculationId: string, query?: ListCalculationReportsQuery, options?: RequestOptions): PagePromise<ReportSummary, ReportList>;
+    /**
+     * Reads a report.
+     *
+     * Needs the `read` scope. Operation `getReport`.
+     */
+    get(id: string, options?: RequestOptions): Promise<ReportWithPreview>;
+    /**
+     * Edits a report with a merge patch: a member left out keeps its value,
+     * `null` clears it, and any other value sets it. An array, such as
+     * `disclosures`, replaces the stored one whole.
+     *
+     * Never retried.
+     *
+     * Needs the `write` scope. Operation `updateReport`.
+     */
+    update(id: string, patch: ReportPatch, options?: RequestOptions): Promise<Report>;
+    /**
+     * Deletes an unshared report. A shared report cannot be deleted; revoke
+     * its link instead.
+     *
+     * A retry after a lost response can answer `404` for a delete that
+     * succeeded.
+     *
+     * Needs the `write` scope. Operation `deleteReport`.
+     */
+    delete(id: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Shares a report: mints its share token and seals the report against
+     * edits. Anyone holding the token can read the report, so handle it like
+     * a secret.
+     *
+     * Needs a session token: sharing is a human trust step. An API key is
+     * refused with `403` `session_required`, as an `ApiError`. Never retried.
+     *
+     * Operation `shareReport`.
+     */
+    share(id: string, options?: RequestOptions): Promise<Report>;
+    /**
+     * Revokes a report's link: its share token stops working.
+     *
+     * Needs a session token: it undoes a human trust step. An API key is
+     * refused with `403` `session_required`, as an `ApiError`. Never retried.
+     *
+     * Operation `revokeReport`.
+     */
+    revoke(id: string, options?: RequestOptions): Promise<Report>;
+}

package/dist/resources/reports.js

@@ -0,0 +1,103 @@
+// The `reports` operations: a report on a published calculation, and the
+// human steps that share it and revoke its link.
+import { call, callPage } from "../request.js";
+/** The `reports` operations. */
+export class Reports {
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    /**
+     * Composes a report on a published calculation, with its disclosures
+     * taken from the calculation's coverage.
+     *
+     * Every attempt of the call sends one `Idempotency-Key`, so a retry
+     * cannot create a second report.
+     *
+     * Needs the `write` scope. Operation `createReport`.
+     *
+     * @param calculationId - the calculation's id.
+     */
+    createForCalculation(calculationId, options) {
+        return call(this.#config, "createReport", {
+            path: { id: calculationId },
+            options,
+        });
+    }
+    /**
+     * Lists a calculation's reports. Await the result for one page; iterate
+     * it with `for await` for every report of every page. Each item is a
+     * summary without `disclosures`; `get` reads a report with them.
+     *
+     * Needs the `read` scope. Operation `listCalculationReports`.
+     *
+     * @param calculationId - the calculation's id.
+     */
+    listForCalculation(calculationId, query, options) {
+        return callPage(this.#config, "listCalculationReports", {
+            path: { id: calculationId },
+            query,
+            options,
+        });
+    }
+    /**
+     * Reads a report.
+     *
+     * Needs the `read` scope. Operation `getReport`.
+     */
+    get(id, options) {
+        return call(this.#config, "getReport", { path: { id }, options });
+    }
+    /**
+     * Edits a report with a merge patch: a member left out keeps its value,
+     * `null` clears it, and any other value sets it. An array, such as
+     * `disclosures`, replaces the stored one whole.
+     *
+     * Never retried.
+     *
+     * Needs the `write` scope. Operation `updateReport`.
+     */
+    update(id, patch, options) {
+        return call(this.#config, "updateReport", {
+            path: { id },
+            body: patch,
+            options,
+        });
+    }
+    /**
+     * Deletes an unshared report. A shared report cannot be deleted; revoke
+     * its link instead.
+     *
+     * A retry after a lost response can answer `404` for a delete that
+     * succeeded.
+     *
+     * Needs the `write` scope. Operation `deleteReport`.
+     */
+    delete(id, options) {
+        return call(this.#config, "deleteReport", { path: { id }, options });
+    }
+    /**
+     * Shares a report: mints its share token and seals the report against
+     * edits. Anyone holding the token can read the report, so handle it like
+     * a secret.
+     *
+     * Needs a session token: sharing is a human trust step. An API key is
+     * refused with `403` `session_required`, as an `ApiError`. Never retried.
+     *
+     * Operation `shareReport`.
+     */
+    share(id, options) {
+        return call(this.#config, "shareReport", { path: { id }, options });
+    }
+    /**
+     * Revokes a report's link: its share token stops working.
+     *
+     * Needs a session token: it undoes a human trust step. An API key is
+     * refused with `403` `session_required`, as an `ApiError`. Never retried.
+     *
+     * Operation `revokeReport`.
+     */
+    revoke(id, options) {
+        return call(this.#config, "revokeReport", { path: { id }, options });
+    }
+}

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/retry.d.ts

@@ -0,0 +1,18 @@
+/** The longest `Retry-After` the SDK honours. A longer one ends the call. */
+export declare const MAX_RETRY_AFTER_MS = 60000;
+/** The statuses worth repeating: a proxy's `408`, `429`, `500`, and a gateway's `502`, `503`, `504`. */
+export declare function isRetryableStatus(status: number): boolean;
+/**
+ * The wait before retry `n` (1 for the first retry) when the response
+ * carried no usable `Retry-After`: `min(0.5 s × 2^(n−1), 8 s)`, multiplied
+ * by a random factor between 0.75 and 1.
+ */
+export declare function backoffMs(retry: number): number;
+/**
+ * Parses a `Retry-After` value, delay-seconds or an HTTP-date (RFC 9110
+ * §10.2.3), into milliseconds from `now`. Returns `undefined` for a value
+ * that does not parse or names a time in the past.
+ */
+export declare function parseRetryAfter(value: string | null, now: number): number | undefined;
+/** Waits `ms` milliseconds, or rejects with the signal's reason when it aborts first. */
+export declare function sleep(ms: number, signal: AbortSignal | undefined): Promise<void>;