@zocomputer/system-api 0.0.0-stage → 0.1.1

package/dist/core/envelope.d.ts

@@ -0,0 +1,45 @@
+import { type JsonObject } from "./json.ts";
+export interface InvocationOptions {
+    readonly version: number;
+    /**
+     * A list query: paging, order and filters. On a success, the query the
+     * server applied, echoed only when the request carried one.
+     */
+    readonly query?: JsonObject;
+}
+export interface InvocationRequestOptions extends InvocationOptions {
+    readonly idempotency_key?: string;
+}
+export interface InvocationEnvelope {
+    readonly action: string;
+    readonly input: JsonObject;
+    readonly options: InvocationRequestOptions;
+}
+export interface InvocationSuccess {
+    readonly request_id: string;
+    readonly action: string;
+    readonly options: InvocationOptions;
+    readonly result: unknown;
+}
+export interface InvocationErrorBody {
+    readonly request_id: string;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+        readonly details?: unknown;
+    };
+}
+/** Read the correlation id from any object-shaped body, for error reporting. */
+export declare function readRequestId(body: unknown): string | undefined;
+/** True when a decoded body is a well-formed, closed error envelope. */
+export declare function isErrorBody(body: unknown): body is InvocationErrorBody;
+/**
+ * Validate a decoded success body against the sent envelope and return it.
+ * Throws `invalid_response` when the body is not a closed success envelope or
+ * its echoed action/version does not match what was requested — a mismatched
+ * echo means the correlation cannot be trusted, so the result is not returned.
+ * `httpStatus` is the status of the (2xx) response the body came from; it is
+ * carried onto the error so a malformed success body is not mistaken for a
+ * transport failure that never reached the server.
+ */
+export declare function parseSuccess(body: unknown, sent: Pick<InvocationEnvelope, "action" | "options">, httpStatus: number): InvocationSuccess;

package/dist/core/envelope.js

@@ -0,0 +1,112 @@
+/**
+ * Invocation wire types and bounded trust-boundary validation.
+ *
+ * These mirror the merged Python contract (`InvocationEnvelope`,
+ * `InvocationSuccess`, error body), which are closed models (`extra=forbid`):
+ * the validators here reject unknown properties, non-positive/out-of-range
+ * versions, and malformed error codes rather than trusting the body because the
+ * server is expected to sanitize it. `options` is REQUIRED on the wire and
+ * always carries the resolved integer `version`. This path checks the envelope
+ * shape and the echoed action/version correlation only — never per-action
+ * input/output schemas — so it pulls in no validator.
+ */
+import { SystemAPIError } from "./errors.js";
+import { isJsonObject } from "./json.js";
+/** Matches the merged contract's `PositiveVersion` (gt 0, le int32 max). */
+const MAX_WIRE_VERSION = 2_147_483_647;
+/** Wire error-code grammar, mirroring contracts.py error-code pattern. */
+const ERROR_CODE_PATTERN = /^[a-z][a-z0-9_]*$/;
+/** True when `obj` carries no properties outside `allowed` (closed model). */
+function hasOnlyKeys(obj, allowed) {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.includes(key))
+            return false;
+    }
+    return true;
+}
+/** A positive, in-range integer version, matching the contract's `PositiveVersion`. */
+function isWireVersion(value) {
+    return (typeof value === "number" &&
+        Number.isInteger(value) &&
+        value > 0 &&
+        value <= MAX_WIRE_VERSION);
+}
+function isOptions(value) {
+    return (isJsonObject(value) &&
+        isWireVersion(value["version"]) &&
+        hasOnlyKeys(value, ["version", "query"]) &&
+        (!("query" in value) || isJsonObject(value["query"])));
+}
+function isWireErrorCode(value) {
+    // Parity with contracts.py: only the error-code grammar (which already
+    // requires a non-empty leading-letter code). No SDK-only length cap — the
+    // total response byte limit bounds the code, and the merged Python contract
+    // imposes no separate per-code length bound.
+    return typeof value === "string" && ERROR_CODE_PATTERN.test(value);
+}
+/** Read the correlation id from any object-shaped body, for error reporting. */
+export function readRequestId(body) {
+    if (isJsonObject(body) && typeof body["request_id"] === "string")
+        return body["request_id"];
+    return undefined;
+}
+/** True when a decoded body is a well-formed, closed error envelope. */
+export function isErrorBody(body) {
+    if (!isJsonObject(body))
+        return false;
+    if (typeof body["request_id"] !== "string")
+        return false;
+    if (!hasOnlyKeys(body, ["request_id", "error"]))
+        return false;
+    const error = body["error"];
+    return (isJsonObject(error) &&
+        isWireErrorCode(error["code"]) &&
+        typeof error["message"] === "string" &&
+        hasOnlyKeys(error, ["code", "message", "details"]));
+}
+/**
+ * Validate a decoded success body against the sent envelope and return it.
+ * Throws `invalid_response` when the body is not a closed success envelope or
+ * its echoed action/version does not match what was requested — a mismatched
+ * echo means the correlation cannot be trusted, so the result is not returned.
+ * `httpStatus` is the status of the (2xx) response the body came from; it is
+ * carried onto the error so a malformed success body is not mistaken for a
+ * transport failure that never reached the server.
+ */
+export function parseSuccess(body, sent, httpStatus) {
+    const fail = (message) => {
+        throw new SystemAPIError({
+            code: "invalid_response",
+            message,
+            requestId: readRequestId(body),
+            httpStatus,
+            outcome: "unknown",
+        });
+    };
+    if (!isJsonObject(body))
+        return fail("response body is not a JSON object");
+    if (!hasOnlyKeys(body, ["request_id", "action", "options", "result"])) {
+        return fail("response envelope carries unknown properties");
+    }
+    if (typeof body["request_id"] !== "string")
+        return fail("response is missing a string request_id");
+    if (!("result" in body))
+        return fail("response is missing a result");
+    if (typeof body["action"] !== "string" || !isOptions(body["options"])) {
+        return fail("response is missing action/version correlation");
+    }
+    if (body["action"] !== sent.action ||
+        body["options"].version !== sent.options.version) {
+        return fail("response action/version does not match the request");
+    }
+    // The server echoes the applied query exactly when the request sent one.
+    if ("query" in body["options"] !== (sent.options.query !== undefined)) {
+        return fail("response query echo does not match the request");
+    }
+    return {
+        request_id: body["request_id"],
+        action: body["action"],
+        options: body["options"],
+        result: body["result"],
+    };
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Structured, safe client errors.
+ *
+ * Every failure the SDK surfaces is a `SystemAPIError`. The public ergonomics
+ * are Promise/throw (no `Result` type crosses the boundary), so a caller either
+ * gets the unwrapped result or a thrown `SystemAPIError`.
+ *
+ * We distinguish three failure origins (decision 5 of the seam):
+ *   - transport failures (`network`): the request never produced an HTTP
+ *     response — `httpStatus` is absent.
+ *   - malformed protocol responses (`invalid_response`): an HTTP response
+ *     arrived but its body is not a well-formed invocation envelope.
+ *   - server errors: a well-formed error envelope; its `code` is preserved
+ *     verbatim, including custom action-declared failure codes we do not know.
+ */
+/**
+ * Stable client/server error codes. Known codes are enumerated for
+ * autocomplete; `(string & {})` preserves any other well-formed server code
+ * (e.g. a custom action failure) rather than collapsing it to a known value.
+ */
+export type SystemAPIErrorCode = "invalid_envelope" | "unauthenticated" | "insufficient_scope" | "permission_denied" | "missing_grants" | "approval_required" | "resource_not_found" | "action_not_found" | "conflict" | "revision_not_ready" | "workflow_has_open_runs" | "catalog_changed" | "authorization_changed" | "payload_too_large" | "invalid_input" | "invalid_query" | "invalid_definition" | "unsupported_version" | "rate_limited" | "invalid_implementation_output" | "output_limit_exceeded" | "implementation_unavailable" | "execution_deadline_exceeded" | "network" | "invalid_response" | "version_required" | "unknown" | (string & {});
+/**
+ * Whether a side effect may have occurred. Set only when genuinely uncertain
+ * (e.g. a disconnect or deadline after the request was sent); never inferred
+ * from an arbitrary HTTP status.
+ */
+export type Outcome = "not_started" | "unknown";
+export interface SystemAPIErrorInit {
+    code: SystemAPIErrorCode;
+    message: string;
+    /** Server correlation id, when the response carried one. */
+    requestId?: string;
+    /** HTTP status; absent when no HTTP response was produced (transport failure). */
+    httpStatus?: number;
+    /** Code-specific, already server-sanitized detail payload. */
+    details?: unknown;
+    /** Bounded, non-negative seconds parsed from a `Retry-After` header. */
+    retryAfterSeconds?: number;
+    /** Explicit effect uncertainty after a send/network/output failure. */
+    outcome?: Outcome;
+    /** Underlying cause (e.g. the fetch rejection), for debugging. */
+    cause?: unknown;
+}
+export declare class SystemAPIError extends Error {
+    readonly code: SystemAPIErrorCode;
+    readonly requestId?: string;
+    readonly httpStatus?: number;
+    readonly details?: unknown;
+    readonly retryAfterSeconds?: number;
+    readonly outcome?: Outcome;
+    constructor(init: SystemAPIErrorInit);
+}

package/dist/core/errors.js

@@ -0,0 +1,33 @@
+/**
+ * Structured, safe client errors.
+ *
+ * Every failure the SDK surfaces is a `SystemAPIError`. The public ergonomics
+ * are Promise/throw (no `Result` type crosses the boundary), so a caller either
+ * gets the unwrapped result or a thrown `SystemAPIError`.
+ *
+ * We distinguish three failure origins (decision 5 of the seam):
+ *   - transport failures (`network`): the request never produced an HTTP
+ *     response — `httpStatus` is absent.
+ *   - malformed protocol responses (`invalid_response`): an HTTP response
+ *     arrived but its body is not a well-formed invocation envelope.
+ *   - server errors: a well-formed error envelope; its `code` is preserved
+ *     verbatim, including custom action-declared failure codes we do not know.
+ */
+export class SystemAPIError extends Error {
+    code;
+    requestId;
+    httpStatus;
+    details;
+    retryAfterSeconds;
+    outcome;
+    constructor(init) {
+        super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.name = "SystemAPIError";
+        this.code = init.code;
+        this.requestId = init.requestId;
+        this.httpStatus = init.httpStatus;
+        this.details = init.details;
+        this.retryAfterSeconds = init.retryAfterSeconds;
+        this.outcome = init.outcome;
+    }
+}

package/dist/core/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@zocomputer/system-api/core` — the generic System API client runtime.
+ *
+ * This entry has no dependency on any released built-in catalog and pulls in no
+ * schema validator: a typed-only consumer imports just this.
+ */
+export { createClient, type ClientConfig, type JsonCallOptions, type JsonCallResult, type RuntimeClient, type TypedClient, } from "./client.ts";
+export { defineCatalog, defineRuntimeCatalog, type ActionEntry, type DefaultVersionsShape, type DefaultsOf, type OperationsOf, type OperationsShape, type RuntimeCatalog, type TypedActions, type TypedCatalog, type VersionEntry, } from "./catalog.ts";
+export { SystemAPIError, type Outcome, type SystemAPIErrorCode, type SystemAPIErrorInit, } from "./errors.ts";
+export { type InvocationEnvelope, type InvocationErrorBody, type InvocationOptions, type InvocationRequestOptions, type InvocationSuccess, } from "./envelope.ts";
+export { DEFAULT_BASE_URL, type AccessTokenProvider, type FetchLike, } from "./transport.ts";
+export { isJsonObject, type JsonObject, type JsonScalar, type JsonValue, } from "./json.ts";
+export type { InvocationTarget, InvocationValidator } from "./validator.ts";
+export { DatabaseDate, DatabaseTimestamp, decodeDatabaseRows, decodeDatabaseValue, type DatabaseColumn, type DatabaseDateFields, type DatabaseDecodeOptions, type DatabaseResult, type DatabaseTimestampFields, type DatabaseValue, } from "./database.ts";

package/dist/core/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@zocomputer/system-api/core` — the generic System API client runtime.
+ *
+ * This entry has no dependency on any released built-in catalog and pulls in no
+ * schema validator: a typed-only consumer imports just this.
+ */
+export { createClient, } from "./client.js";
+export { defineCatalog, defineRuntimeCatalog, } from "./catalog.js";
+export { SystemAPIError, } from "./errors.js";
+export {} from "./envelope.js";
+export { DEFAULT_BASE_URL, } from "./transport.js";
+export { isJsonObject, } from "./json.js";
+export { DatabaseDate, DatabaseTimestamp, decodeDatabaseRows, decodeDatabaseValue, } from "./database.js";

package/dist/core/json-call.d.ts

@@ -0,0 +1,4 @@
+import type { JsonCallOptions, JsonCallResult } from "./client.ts";
+import { type Transport } from "./transport.ts";
+import type { InvocationTarget } from "./validator.ts";
+export declare function invokeJson(transport: Transport, target: InvocationTarget, inputJson: string, options?: JsonCallOptions): Promise<JsonCallResult>;

package/dist/core/json-call.js

@@ -0,0 +1,109 @@
+import { JsonError, JsonNumber, MAX_JSON_DEPTH, checkJsonValue, dumpsJson, loadsJson, } from "../json/index.js";
+import { SystemAPIError } from "./errors.js";
+import { MAX_REQUEST_BYTES, MAX_RESPONSE_BYTES, } from "./transport.js";
+function isObject(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        !(value instanceof JsonNumber));
+}
+function parseObject(text, name) {
+    const value = loadsJson(text, { maxBytes: MAX_REQUEST_BYTES });
+    if (!isObject(value))
+        throw new Error(`${name} must be a JSON object`);
+    return value;
+}
+export async function invokeJson(transport, target, inputJson, options) {
+    let requestBody;
+    try {
+        parseObject(inputJson, "input");
+        if (options?.queryJson !== undefined)
+            parseObject(options.queryJson, "query");
+        const wireOptions = JSON.stringify({
+            version: target.version,
+            ...(options?.idempotencyKey !== undefined
+                ? { idempotency_key: options.idempotencyKey }
+                : {}),
+        });
+        const query = options?.queryJson === undefined ? "" : `,"query":${options.queryJson}`;
+        requestBody = `{"action":${JSON.stringify(target.action)},"input":${inputJson},"options":${wireOptions.slice(0, -1)}${query}}}`;
+    }
+    catch (cause) {
+        throw new SystemAPIError({
+            code: cause instanceof JsonError && cause.code === "too_large"
+                ? "payload_too_large"
+                : "invalid_input",
+            message: "input and query must be bounded JSON objects",
+            outcome: "not_started",
+            cause,
+        });
+    }
+    let responseValue;
+    const { success, text, httpStatus } = await transport.invokeText(requestBody, {
+        action: target.action,
+        options: {
+            version: target.version,
+            ...(options?.queryJson !== undefined ? { query: {} } : {}),
+        },
+    }, target, (responseText) => {
+        responseValue = loadsJson(responseText, {
+            maxBytes: MAX_RESPONSE_BYTES,
+            maxDepth: MAX_JSON_DEPTH + 2,
+            maxNodes: null,
+        });
+        if (!isObject(responseValue))
+            return responseValue;
+        const wireOptions = responseValue["options"];
+        if (!isObject(wireOptions))
+            return responseValue;
+        const version = wireOptions["version"];
+        // Existing validator hooks expect ordinary JS query values. Their exact
+        // comparison source is responseText; responseValue keeps the output exact.
+        return {
+            ...responseValue,
+            options: {
+                ...wireOptions,
+                ...("query" in wireOptions
+                    ? {
+                        query: isObject(wireOptions["query"])
+                            ? JSON.parse(dumpsJson(wireOptions["query"]))
+                            : null,
+                    }
+                    : {}),
+                version: version instanceof JsonNumber && version.isInteger
+                    ? Number(version.text)
+                    : undefined,
+            },
+        };
+    });
+    // parseSuccess has checked these fields; the original tree retains numbers.
+    if (!isObject(responseValue) || responseValue["result"] === undefined)
+        throw new Error("validated response lost its result");
+    const result = responseValue["result"];
+    const appliedOptions = responseValue["options"];
+    const query = isObject(appliedOptions) ? appliedOptions["query"] : undefined;
+    try {
+        checkJsonValue(result);
+        if (query !== undefined)
+            checkJsonValue(query);
+    }
+    catch (cause) {
+        throw new SystemAPIError({
+            code: "invalid_response",
+            message: "response result or query exceeds JSON bounds",
+            requestId: success.request_id,
+            httpStatus,
+            outcome: "unknown",
+            cause,
+        });
+    }
+    return {
+        envelopeJson: text,
+        resultJson: dumpsJson(result),
+        requestId: success.request_id,
+        action: success.action,
+        version: success.options.version,
+        ...(query !== undefined ? { queryJson: dumpsJson(query) } : {}),
+        httpStatus,
+    };
+}

package/dist/core/json.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Bounded JSON value types mirroring the Python contract's `JsonValue`.
+ *
+ * The wire is JSON, so every value the SDK sends or receives is one of these.
+ * `JsonObject` is the shape of an action input and of the invocation envelope's
+ * object fields; `JsonValue` is any bounded finite JSON value (the shape of an
+ * `x-zo-json-value` field and of a successful `result`).
+ */
+export type JsonScalar = string | number | boolean | null;
+export type JsonValue = JsonScalar | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/** Narrow an `unknown` decoded body to a JSON object without an `as`-cast. */
+export declare function isJsonObject(value: unknown): value is JsonObject;

package/dist/core/json.js

@@ -0,0 +1,4 @@
+/** Narrow an `unknown` decoded body to a JSON object without an `as`-cast. */
+export function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/core/transport.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Fetch transport for the single `/invoke` route.
+ *
+ * Browser-safe: uses `fetch` only, no Node built-ins. Invoke is never retried
+ * automatically — a disconnect, deadline, or malformed result after a mutation
+ * may mean the effect happened, so uncertainty is surfaced rather than replayed.
+ * The request is serialized, size-checked, and the token obtained and validated
+ * BEFORE any network call, so a pre-flight failure reports `outcome:
+ * "not_started"`; `network` is used solely for a `fetch` rejection. Response
+ * bodies are read under a byte cap before parsing, and redirects are refused so
+ * a bearer credential is never replayed to a redirected origin.
+ */
+import { type InvocationEnvelope, type InvocationSuccess } from "./envelope.ts";
+import type { InvocationTarget, InvocationValidator } from "./validator.ts";
+export type FetchLike = typeof fetch;
+export type AccessTokenProvider = () => string | Promise<string>;
+export interface TransportConfig {
+    readonly accessToken: AccessTokenProvider;
+    readonly baseUrl?: string;
+    readonly workspaceId?: string;
+    readonly fetch?: FetchLike;
+    /**
+     * Optional validation. When present, its hooks run on the exact request and
+     * response bytes; when absent, the two call sites are no-ops and nothing from
+     * a validator is imported or bundled.
+     */
+    readonly validator?: InvocationValidator;
+}
+export declare const DEFAULT_BASE_URL = "https://api.zo.computer/zo-system-api/v1";
+/**
+ * Total serialized request-body cap: 5 MiB. Inline file content may be up to
+ * 4 MiB of UTF-8, but the whole body as sent must fit here: JSON escaping
+ * (quotes, backslashes, control characters) counts, so heavily escaped
+ * content may need a prepared upload.
+ */
+export declare const MAX_REQUEST_BYTES: number;
+export declare const MAX_RESPONSE_BYTES: number;
+export interface TransportResponse {
+    readonly success: InvocationSuccess;
+    readonly text: string;
+    readonly httpStatus: number;
+}
+export interface Transport {
+    invokeText(requestBody: string, sent: Pick<InvocationEnvelope, "action" | "options">, target: InvocationTarget, decodeBody?: (text: string) => unknown): Promise<TransportResponse>;
+    invoke(envelope: InvocationEnvelope, target: InvocationTarget): Promise<InvocationSuccess>;
+}
+export declare function createTransport(config: TransportConfig): Transport;