@allisall/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+@allisall/sdk
+Copyright 2026 All is AI

package/README.md

@@ -1,3 +1,228 @@
-# Temporary Holding Version
+# @allisall/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+
+```sh
+npm install @allisall/sdk
+```
+
+## Create a client
+
+The client reads your API key from `AIA_API_KEY`:
+
+```sh
+export AIA_API_KEY=aia_...
+```
+
+```ts
+import { Allisall } from "@allisall/sdk";
+
+const client = new Allisall();
+```
+
+You can also pass the key yourself, as `new Allisall({ apiKey })`. Create
+one client and reuse it.
+
+## Ingest events
+
+```ts
+import { Allisall, decimal } from "@allisall/sdk";
+
+const client = new Allisall();
+
+const summary = await client.events.ingest([
+  {
+    timestamp: new Date(),
+    agent_key: "support-bot",
+    category: "model",
+    event_type: "completion",
+    model: "gpt-4o",
+    tokens_in: 1200,
+    tokens_out: 300,
+    cost: decimal("0.0042"),
+  },
+]);
+
+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 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
+
+The SDK gives every event without an `event_id` a new one. That makes a
+retry within one call safe, but it does not catch the same event sent
+again in a later call. If your events can be delivered more than once,
+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.
+const updated = await client.clients.update(created.id, {
+  renewal_date: "2026-12-31",
+});
+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
+client therefore refuses an API key in a browser unless you pass
+`dangerouslyAllowBrowser: true`:
+
+```ts
+import { Allisall } from "@allisall/sdk";
+
+// Only if you accept that anyone who loads the page can read this key.
+const client = new Allisall({
+  apiKey: "aia_...",
+  dangerouslyAllowBrowser: true,
+});
+```
+
+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).
+
+## License
+
+Apache-2.0. See `LICENSE` and `NOTICE`.

package/dist/client.d.ts

@@ -0,0 +1,121 @@
+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 { type FetchLike, type TokenProvider, type TransportConfig } from "./transport.js";
+/** The options of `new Allisall()`. Every one is optional. */
+export interface ClientOptions {
+    /**
+     * The API key. Defaults to `AIA_API_KEY` from the environment. Pass
+     * either this or `tokenProvider`, not both.
+     */
+    apiKey?: string | undefined;
+    /**
+     * A callback returning the bearer token to send, called before every
+     * attempt, retries included. Use it to supply an API key fetched at run
+     * time, for example from a secret store.
+     */
+    tokenProvider?: TokenProvider | undefined;
+    /**
+     * 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. */
+    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 requests with. Defaults to the platform's own. */
+    fetch?: FetchLike | undefined;
+    /**
+     * Allows an API key in a browser, where anyone who loads the page can
+     * read it. Defaults to `false`.
+     */
+    dangerouslyAllowBrowser?: boolean | undefined;
+    /**
+     * 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.
+     */
+    defaultHeaders?: Readonly<Record<string, string>> | undefined;
+}
+/** 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 {
+    /** 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;
+    /**
+     * @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?: ClientOptions);
+}