@allisall/sdk 0.0.0-stage → 0.1.0

package/dist/transport.js

@@ -0,0 +1,220 @@
+// One HTTP attempt (headers, timeout, reading the response) and the loop
+// that repeats it under the retry rules in retry.ts.
+import { AllisallError, ApiError, ConnectionError } from "./errors.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. */
+export const BROWSER_KEY_MESSAGE = "allisall: refusing to use an API key in a browser, where it is readable by anyone who loads the page. " +
+    "Call the API from your server instead, or pass dangerouslyAllowBrowser: true if you accept that risk.";
+/** Reports whether a bearer token is an API key, which starts `aia_`. */
+export function isApiKey(token) {
+    return token.startsWith("aia_");
+}
+/** Joins the base URL and an operation's path with exactly one `/`. */
+export function joinURL(base, path) {
+    const url = new URL(base.href);
+    url.pathname = url.pathname.replace(/\/+$/, "") + path;
+    return url.href;
+}
+/**
+ * Reports whether every character of a credential, already trimmed, is
+ * printable ASCII (U+0021 to U+007E), as a bearer credential is. Anything
+ * else, a control character, an inner space or a non-ASCII character,
+ * cannot travel in the header. The check never quotes the credential, so
+ * no error built from it can leak the secret.
+ */
+export function isPrintableCredential(credential) {
+    for (let i = 0; i < credential.length; i++) {
+        const c = credential.charCodeAt(i);
+        if (c < 0x21 || c > 0x7e)
+            return false;
+    }
+    return true;
+}
+async function bearerToken(config) {
+    const { credential } = config;
+    if (credential.kind === "apiKey")
+        return credential.apiKey;
+    const raw = await credential.provider();
+    const token = typeof raw === "string" ? raw.trim() : raw;
+    if (token === "") {
+        throw new AllisallError("allisall: the token provider returned an empty token");
+    }
+    if (typeof token === "string" && !isPrintableCredential(token)) {
+        throw new AllisallError("allisall: the token provider returned a token holding a character other than printable ASCII, which cannot be sent");
+    }
+    if (config.refuseApiKeys && typeof token === "string" && isApiKey(token)) {
+        throw new AllisallError(BROWSER_KEY_MESSAGE);
+    }
+    return token;
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseJSON(text) {
+    try {
+        const value = JSON.parse(text);
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+const OPTIONAL_LOCATORS = [
+    "pointer",
+    "parameter",
+    "header",
+    "part",
+    "column",
+];
+function readFieldError(value) {
+    if (!isObject(value))
+        return undefined;
+    const { code, detail } = value;
+    if (typeof code !== "string" || typeof detail !== "string")
+        return undefined;
+    const out = { code, detail };
+    for (const name of OPTIONAL_LOCATORS) {
+        const locator = value[name];
+        if (typeof locator === "string")
+            out[name] = locator;
+    }
+    return out;
+}
+const PROBLEM_STRINGS = [
+    "type",
+    "title",
+    "detail",
+    "code",
+    "request_id",
+];
+/**
+ * Reads an `application/problem+json` body as a problem document. Returns
+ * `undefined` for any other body, or one that is not a JSON object. A
+ * member of the wrong type is left out on its own, as is a malformed
+ * entry of `errors`; the rest of the problem is kept. Members the SDK does
+ * not know are ignored.
+ */
+export function readProblem(contentType, text) {
+    const mediaType = contentType?.split(";")[0]?.trim().toLowerCase();
+    if (mediaType !== "application/problem+json")
+        return undefined;
+    const body = parseJSON(text);
+    if (!isObject(body))
+        return undefined;
+    const problem = {};
+    for (const name of PROBLEM_STRINGS) {
+        const value = body[name];
+        if (typeof value === "string")
+            problem[name] = value;
+    }
+    if (typeof body.status === "number")
+        problem.status = body.status;
+    if (Array.isArray(body.errors)) {
+        problem.errors = body.errors
+            .map(readFieldError)
+            .filter((e) => e !== undefined);
+    }
+    return problem;
+}
+function headerOrUndefined(headers, name) {
+    return headers.get(name) ?? undefined;
+}
+/**
+ * Sends one attempt. Resolves with the parsed `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,
+    };
+    if (config.userAgent !== undefined)
+        headers["User-Agent"] = config.userAgent;
+    const timeout = AbortSignal.timeout(config.timeout);
+    const combined = signal === undefined ? timeout : AbortSignal.any([signal, timeout]);
+    const doFetch = config.fetch ?? globalThis.fetch;
+    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",
+        });
+        text = await response.text();
+    }
+    catch (err) {
+        if (signal?.aborted)
+            throw signal.reason;
+        throw new ConnectionError(requestId, err);
+    }
+    const status = response.status;
+    const responseId = headerOrUndefined(response.headers, "X-Request-Id");
+    // A 3xx, or a browser's opaque redirect, whose status is 0.
+    if ((status >= 300 && status < 400) || response.type === "opaqueredirect") {
+        throw new ApiError({
+            status,
+            headers: response.headers,
+            requestId: responseId,
+            message: `allisall: the API answered ${status} with a redirect, which the SDK does not follow`,
+        });
+    }
+    if (status >= 200 && status < 300) {
+        const parsed = parseJSON(text);
+        const value = parsed === undefined ? undefined : read(parsed);
+        if (value !== undefined)
+            return value;
+        throw new ApiError({
+            status,
+            headers: response.headers,
+            requestId: responseId,
+            message: `allisall: the API answered ${status} with a body the SDK could not read`,
+        });
+    }
+    throw new ApiError({
+        status,
+        problem: readProblem(response.headers.get("Content-Type"), text),
+        requestId: responseId,
+        retryAfter: parseRetryAfter(response.headers.get("Retry-After"), Date.now()),
+        headers: response.headers,
+    });
+}
+/**
+ * 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`.
+ */
+export async function post(config, path, body, read, signal) {
+    const url = joinURL(config.baseURL, path);
+    for (let retry = 0;; retry++) {
+        // An error from the token provider ends the call unwrapped and unretried.
+        const token = await bearerToken(config);
+        try {
+            return await attempt(config, url, body, read, token, uuidv4(), signal);
+        }
+        catch (err) {
+            if (!(err instanceof ApiError || err instanceof ConnectionError))
+                throw err;
+            const retryable = err instanceof ConnectionError || isRetryableStatus(err.status);
+            if (!retryable || retry >= config.maxRetries)
+                throw err;
+            let wait;
+            if (err instanceof ApiError && err.retryAfter !== undefined) {
+                if (err.retryAfter > MAX_RETRY_AFTER_MS)
+                    throw err;
+                wait = err.retryAfter;
+            }
+            else {
+                wait = backoffMs(retry + 1);
+            }
+            await sleep(wait, signal);
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,135 @@
+import type { Decimal } from "./decimal.js";
+/** The known request-level error codes, in the API's catalogue order. */
+export declare const ERROR_CODES: readonly ["invalid_json", "validation_failed", "unauthenticated", "insufficient_scope", "session_required", "account_not_provisioned", "not_found", "no_active_value_model", "method_not_allowed", "idempotency_key_in_use", "client_key_in_use", "agent_key_in_use", "client_has_events", "client_has_calculations", "agent_has_events", "client_key_has_events", "value_model_exists", "value_model_version_stale", "calculation_transition_invalid", "calculation_not_draft", "calculation_not_published", "report_shared", "report_not_shared", "api_key_revoked", "payload_too_large", "uri_too_long", "unsupported_media_type", "idempotency_key_reused", "rate_limited", "internal_error"];
+/** The known field-level error codes, in the API's catalogue order. */
+export declare const FIELD_ERROR_CODES: readonly ["required", "unknown_field", "immutable", "invalid_type", "invalid_format", "invalid_value", "too_long", "too_many", "out_of_range", "too_precise", "duplicate", "too_large", "mutually_exclusive", "unknown_reference", "client_key_required", "currency_mismatch"];
+/** The event categories. */
+export declare const EVENT_CATEGORIES: readonly ["session", "task", "model", "outcome", "exception"];
+/** The members of `EventInput`, in the API's order. */
+export declare const EVENT_INPUT_MEMBERS: readonly ["event_id", "timestamp", "agent_key", "client_key", "category", "event_type", "outcome_type", "quantity", "cost", "tokens_in", "tokens_out", "model", "currency", "metadata"];
+/**
+ * A request-level error code. New codes are additive, so any other string
+ * is possible too: branch on the codes you handle, and fall back on the
+ * HTTP status for the rest.
+ */
+export type ErrorCode = (typeof ERROR_CODES)[number] | (string & {});
+/**
+ * A field-level error code, as in a rejected ingest row. New codes are
+ * additive, so any other string is possible too.
+ */
+export type FieldErrorCode = (typeof FIELD_ERROR_CODES)[number] | (string & {});
+/** An event category. */
+export type EventCategory = (typeof EVENT_CATEGORIES)[number];
+/**
+ * One event to ingest. Members keep the API's snake_case names. The SDK
+ * sends every member the object holds, so a misspelt member reaches the
+ * API and is reported as a rejected row rather than dropped.
+ */
+export interface EventInput {
+    /**
+     * A sender-chosen id; a repeat within the workspace is a duplicate. When
+     * it is absent, `null` or `""`, the SDK generates a UUID. Set your own
+     * when the same event may be sent again in a later call, such as after a
+     * queue redelivers a message.
+     */
+    event_id?: string | null;
+    /** When the event happened: a `Date`, or an RFC 3339 instant with an offset. */
+    timestamp: Date | string;
+    /** The agent that acted. */
+    agent_key: string;
+    /** The client the event belongs to. */
+    client_key?: string | null;
+    /** The event's category. */
+    category: EventCategory;
+    /** What the agent did. */
+    event_type: string;
+    /** Required when `category` is `outcome`. */
+    outcome_type?: string | null;
+    /** Absent, `null` or `0` means 1. */
+    quantity?: number | null;
+    /** In `currency`, or the workspace currency: a `Decimal`, or a finite number. */
+    cost?: Decimal | number | null;
+    /** Tokens in. */
+    tokens_in?: number | null;
+    /** Tokens out. */
+    tokens_out?: number | null;
+    /** The model the agent invoked. */
+    model?: string | null;
+    /** The currency of `cost`. Absent means the workspace currency. */
+    currency?: string | null;
+    /** Free-form members, at most 8 KB serialised. */
+    metadata?: Record<string, unknown> | null;
+}
+/** One problem with a rejected ingest row. */
+export interface IngestRowError {
+    /** The zero-based position of the row in the list passed to `ingest`. */
+    index: number;
+    /** The field-level code. */
+    code: FieldErrorCode;
+    /** An RFC 6901 JSON Pointer to the problem, starting `/events/<index>`. */
+    pointer: string;
+    /** Human text. Its wording may change at any time. */
+    detail: string;
+}
+/** The outcome of one ingest batch, as the API sends it. */
+export interface IngestResult {
+    accepted: number;
+    duplicates: number;
+    rejected: number;
+    errors: IngestRowError[];
+    errors_truncated: boolean;
+}
+/** The combined outcome of one `ingest` call, over the whole list. */
+export interface IngestSummary {
+    /** Events stored. */
+    accepted: number;
+    /** Events already stored, by `event_id` or content hash. */
+    duplicates: number;
+    /** Events refused, counted once each, including any too large to send. */
+    rejected: number;
+    /** One entry per problem, in the order of the list passed to `ingest`. */
+    errors: IngestRowError[];
+    /** Whether any rejected row had more problems than `errors` holds. */
+    errors_truncated: boolean;
+    /** The number of batches sent. */
+    batches: number;
+}
+/** One problem in a request, from a problem document's `errors`. */
+export interface FieldError {
+    /** The field-level code. */
+    code: FieldErrorCode;
+    /** An RFC 6901 JSON Pointer into the request body. */
+    pointer?: string;
+    /** A query parameter, by name. */
+    parameter?: string;
+    /** A request header, by name. */
+    header?: string;
+    /** A multipart part, by its form field name. */
+    part?: string;
+    /** A column of a CSV part. */
+    column?: string;
+    /** Human text. Its wording may change at any time. */
+    detail: string;
+}
+/**
+ * An RFC 9457 problem document, as the API sends it with an error status.
+ * The API sends every member but `errors`; each is optional here because a
+ * member of the wrong type, such as one from a proxy, is left out rather
+ * than failing the whole document.
+ */
+export interface Problem {
+    /** A URI identifying the problem; it maps one to one onto `code`. */
+    type?: string;
+    /** The fixed summary for `code`. */
+    title?: string;
+    /** The response status. */
+    status?: number;
+    /** Human text about this occurrence. Its wording may change at any time. */
+    detail?: string;
+    /** The error code. Branch on it. */
+    code?: ErrorCode;
+    /** The request's id, to quote when reporting the problem. */
+    request_id?: string;
+    /** Every problem found. Present only with `validation_failed`. */
+    errors?: FieldError[];
+}

package/dist/types.js

@@ -0,0 +1,80 @@
+// The wire types the SDK uses, written by hand from the API's OpenAPI
+// document. A test reads that document and holds every list below to it,
+// until types generated from the document replace this file.
+/** The known request-level error codes, in the API's catalogue order. */
+export const ERROR_CODES = [
+    "invalid_json",
+    "validation_failed",
+    "unauthenticated",
+    "insufficient_scope",
+    "session_required",
+    "account_not_provisioned",
+    "not_found",
+    "no_active_value_model",
+    "method_not_allowed",
+    "idempotency_key_in_use",
+    "client_key_in_use",
+    "agent_key_in_use",
+    "client_has_events",
+    "client_has_calculations",
+    "agent_has_events",
+    "client_key_has_events",
+    "value_model_exists",
+    "value_model_version_stale",
+    "calculation_transition_invalid",
+    "calculation_not_draft",
+    "calculation_not_published",
+    "report_shared",
+    "report_not_shared",
+    "api_key_revoked",
+    "payload_too_large",
+    "uri_too_long",
+    "unsupported_media_type",
+    "idempotency_key_reused",
+    "rate_limited",
+    "internal_error",
+];
+/** The known field-level error codes, in the API's catalogue order. */
+export const FIELD_ERROR_CODES = [
+    "required",
+    "unknown_field",
+    "immutable",
+    "invalid_type",
+    "invalid_format",
+    "invalid_value",
+    "too_long",
+    "too_many",
+    "out_of_range",
+    "too_precise",
+    "duplicate",
+    "too_large",
+    "mutually_exclusive",
+    "unknown_reference",
+    "client_key_required",
+    "currency_mismatch",
+];
+/** The event categories. */
+export const EVENT_CATEGORIES = [
+    "session",
+    "task",
+    "model",
+    "outcome",
+    "exception",
+];
+/** The members of `EventInput`, in the API's order. */
+export const EVENT_INPUT_MEMBERS = [
+    "event_id",
+    "timestamp",
+    "agent_key",
+    "client_key",
+    "category",
+    "event_type",
+    "outcome_type",
+    "quantity",
+    "cost",
+    "tokens_in",
+    "tokens_out",
+    "model",
+    "currency",
+    "metadata",
+];

package/dist/uuid.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns a new UUID version 4 (RFC 9562 §5.4), lowercase, in the
+ * 8-4-4-4-12 form. It uses `crypto.getRandomValues`, which, unlike
+ * `crypto.randomUUID`, every browser offers outside secure contexts too.
+ */
+export declare function uuidv4(): string;

package/dist/uuid.js

@@ -0,0 +1,20 @@
+const HEX = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"));
+/**
+ * Returns a new UUID version 4 (RFC 9562 §5.4), lowercase, in the
+ * 8-4-4-4-12 form. It uses `crypto.getRandomValues`, which, unlike
+ * `crypto.randomUUID`, every browser offers outside secure contexts too.
+ */
+export function uuidv4() {
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    // Version 4 in the high nibble of byte 6; variant 10 in the top bits of byte 8.
+    bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+    bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+    let out = "";
+    for (let i = 0; i < 16; i++) {
+        if (i === 4 || i === 6 || i === 8 || i === 10)
+            out += "-";
+        out += HEX[bytes[i] ?? 0];
+    }
+    return out;
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The SDK's version. The release tooling updates it; never edit it by hand. */
+export declare const VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** The SDK's version. The release tooling updates it; never edit it by hand. */
+export const VERSION = "0.1.0"; // x-release-please-version

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@allisall/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The allisall SDK for TypeScript and JavaScript: send events to the allisall API.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/All-is-AI/allisall-typescript.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "biome check . && tsc --noEmit -p tsconfig.json",
+    "test": "vitest run && npm run test:consumer",
+    "test:consumer": "tsc -p tsconfig.build.json && node test/consumer/extract-readme.mjs && node node_modules/typescript-5.0/bin/tsc -p test/consumer/tsconfig.bundler.json && node node_modules/typescript-5.0/bin/tsc -p test/consumer/tsconfig.node16.json && node node_modules/typescript-5.0/bin/tsc -p test/consumer/tsconfig.node-types.json"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.4",
+    "@types/node": "^22.20.5",
+    "typescript": "~5.9.3",
+    "typescript-5.0": "npm:typescript@5.0.4",
+    "vitest": "^4.1.10",
+    "yaml": "2.9.0"
+  }
+}