@crouter/sdk 0.3.377

package/dist/client.js

@@ -0,0 +1,491 @@
+import { APIError, CrtrClient, routes, } from '@crouter/api';
+import { APIConnectionError, APIUserAbortError, AuthenticationError, CrouterError, mapError } from './errors.js';
+import { Bash } from './resources/bash.js';
+import { Canvas } from './resources/canvas.js';
+import { Crons } from './resources/crons.js';
+import { CustomObjects } from './resources/custom-objects.js';
+import { Attachments } from './resources/attachments.js';
+import { Files } from './resources/files.js';
+import { Human } from './resources/human.js';
+import { Models } from './resources/models.js';
+import { NodesResource } from './resources/nodes.js';
+import { nodeId, pathSegment } from './resources/identifiers.js';
+import { NodeStream } from './resources/node-stream.js';
+import { Questions } from './resources/questions.js';
+import { Providers } from './resources/providers.js';
+import { Runs } from './resources/runs.js';
+import { Shares } from './resources/shares.js';
+import { Memory } from './resources/memory.js';
+import { Uploads } from './resources/uploads.js';
+import { resolveJsonSchema } from './schema.js';
+const LOCAL_SOCKET_FETCH = Symbol.for('@crouter/api/local-socket-fetch');
+const DEFAULT_TIMEOUT_MS = 30_000;
+const POLL_WAIT_SECONDS = 25;
+/**
+ * The client, and the only class an application constructs. Each namespace below wraps a
+ * family of daemon routes; `request` is the escape hatch for a route with no wrapper.
+ */
+export class Crouter {
+    /** Create, inspect, message, stream, and wait on nodes. */
+    nodes;
+    /** Run one command in an absolute working directory. */
+    bash;
+    /** Canvas-wide views: attention, snapshot, roster, dashboard, prune, and history. */
+    canvas;
+    /** Scheduled commands. */
+    crons;
+    /** Register, publish, receive, and acknowledge custom canvas objects. */
+    customObjects;
+    /** Human requests and the human inbox. */
+    human;
+    /** Model credentials and model configuration. */
+    models;
+    /** Agent profiles. */
+    profiles;
+    /** Daemon status and health. */
+    system;
+    /** Whether this client can reach a daemon that can run a model. */
+    auth;
+    /** Read, write, and list absolute host paths. */
+    files;
+    runs;
+    /** Uploads to runtime storage, for files a run prompt or message names (app listener only). */
+    uploads;
+    /** Signed links to files a run received as attachments (app listener only). */
+    attachments;
+    /** Public share links to files (app listener only). */
+    shares;
+    /** Questions agents in runs ask the user (app listener only). */
+    questions;
+    /** Read the documents the person owns (`store: 'user'`): an app sees their `public` documents, and every privacy level with a `crtr:memory:manage:user` grant. */
+    memory;
+    /** Scope-filtered provider tools and daemon-mediated calls. */
+    providers;
+    grant;
+    health;
+    eventFetch;
+    bearerToken;
+    connectionToken;
+    tokenSource;
+    onUnauthorized;
+    client;
+    timeout;
+    baseURL;
+    socketPath;
+    constructor(options = {}) {
+        const env = nodeEnvironment();
+        const baseURL = options.baseURL ?? env['CRTR_BASE_URL'];
+        this.baseURL = baseURL;
+        this.socketPath = undefined;
+        if (options.baseURL !== undefined && options.socketPath !== undefined) {
+            throw new TypeError('Crouter accepts either baseURL or socketPath, not both');
+        }
+        if (baseURL !== undefined && options.autostart === true) {
+            throw new CrouterError('autostart is only valid for the local socket transport');
+        }
+        if (options.token !== undefined && options.tokenSource !== undefined)
+            throw new CrouterError('token and tokenSource are mutually exclusive');
+        if (options.tokenSource && baseURL === undefined)
+            throw new CrouterError('tokenSource requires baseURL');
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        const token = options.tokenSource ? undefined : options.token ?? env['CRTRD_TOKEN'];
+        this.bearerToken = token;
+        this.tokenSource = options.tokenSource;
+        this.onUnauthorized = options.onUnauthorized;
+        const headers = {
+            ...options.defaultHeaders,
+            ...options.headers,
+            ...(token === undefined ? {} : { Authorization: `Bearer ${token}` }),
+        };
+        const baseFetch = options.fetch ?? (baseURL === undefined && isNodeRuntime() ? localSocketFetch(options.socketPath ?? env['CRTR_SOCKET']) : fetch);
+        this.eventFetch = options.tokenSource ? (input, init) => {
+            const url = new URL(input instanceof Request ? input.url : String(input));
+            if (url.pathname === '/v1/health')
+                return baseFetch(input, init);
+            return baseFetch(input, {
+                ...init, headers: { ...Object.fromEntries(new Headers(init?.headers)), Authorization: `Bearer ${this.connectionToken}` },
+            });
+        } : baseFetch;
+        if (baseURL !== undefined) {
+            this.client = new CrtrClient({
+                baseUrl: baseURL,
+                fetch: this.eventFetch,
+                headers,
+                timeoutMs: this.timeout,
+                maxRetries: options.maxRetries,
+            });
+        }
+        else {
+            if (!isNodeRuntime()) {
+                if (options.socketPath !== undefined)
+                    throw new CrouterError('socketPath is only available in Node');
+                this.socketPath = undefined;
+                this.client = new CrtrClient({
+                    baseUrl: 'http://localhost',
+                    fetch: options.fetch,
+                    headers,
+                    timeoutMs: this.timeout,
+                    maxRetries: options.maxRetries,
+                });
+            }
+            else {
+                const socketPath = options.socketPath ?? env['CRTR_SOCKET'];
+                this.socketPath = socketPath;
+                const fetch = options.fetch ?? localSocketFetch(socketPath);
+                const autostart = options.autostart ?? true;
+                this.client = new CrtrClient({
+                    baseUrl: 'http://localhost',
+                    fetch,
+                    headers,
+                    timeoutMs: this.timeout,
+                    maxRetries: options.maxRetries,
+                    autostart,
+                    onColdSocket: autostart ? startDaemon : undefined,
+                });
+            }
+        }
+        const request = (method, path, body, options) => this.request(method, path, body, options);
+        const nodes = new NodesResource(request);
+        const phaseOneNodes = {
+            create: (params, options) => this.call(() => this.client.request('POST', routes.nodes(), serializeCreate(params), options)),
+            retrieve: async (id, options) => {
+                const validId = nodeId(id);
+                return this.call(() => this.client.request('GET', routes.node(validId), undefined, options));
+            },
+            list: (query, options) => this.call(() => this.client.request('GET', withQuery(routes.nodes(), query), undefined, options)),
+            outcome: (id, options) => this.outcome(id, options),
+            waitForOutcome: (id, options) => this.waitForOutcome(id, options),
+            createAndWait: (params, options) => this.createAndWait(params, options),
+            parse: (params, options) => this.parse(params, options),
+            message: async (id, body, options) => {
+                const validId = nodeId(id);
+                return this.call(() => this.client.request('POST', routes.nodeMessages(validId), messageBody(body), options));
+            },
+            cancel: async (id, body, options) => {
+                const validId = nodeId(id);
+                return this.call(() => this.client.request('POST', routes.nodeClose(validId), body ?? {}, options));
+            },
+            interrupt: async (id, options) => {
+                const validId = nodeId(id);
+                return this.call(() => this.client.request('POST', routes.nodeInterrupt(validId), {}, options));
+            },
+            stream: (params, options) => this.stream(params, options),
+            events: (id, options) => this.events(id, options),
+            reports: {
+                list: async (id, query, options) => {
+                    const validId = nodeId(id);
+                    return this.call(() => this.client.request('GET', withQuery(routes.nodeReports(validId), query), undefined, options));
+                },
+            },
+        };
+        this.nodes = Object.assign(nodes, phaseOneNodes);
+        this.bash = new Bash(request, this.timeout);
+        this.canvas = new Canvas(request);
+        this.crons = new Crons(request);
+        this.customObjects = new CustomObjects(request, (path, options) => this.openCustomDeliveries(path, options));
+        this.human = new Human(request);
+        this.models = new Models(request);
+        this.profiles = {
+            ensure: async (name, params, options) => {
+                const validName = pathSegment(name, 'profile name');
+                return this.call(() => this.client.request('PUT', routes.profile(validName), params ?? {}, options));
+            },
+            retrieve: async (name, options) => {
+                const validName = pathSegment(name, 'profile name');
+                return this.call(() => this.client.request('GET', routes.profile(validName), undefined, options));
+            },
+            list: (options) => this.call(() => this.client.request('GET', routes.profiles(), undefined, options)),
+        };
+        this.system = {
+            status: (options) => this.call(() => this.client.request('GET', routes.status(), undefined, options)),
+            health: (options) => this.call(() => this.client.request('GET', routes.healthz(), undefined, options)),
+        };
+        this.auth = {
+            status: (params, options) => this.authStatus(params, options),
+        };
+        this.files = new Files(request, (path, options) => this.openDownload(path, options));
+        this.uploads = new Uploads(request);
+        this.attachments = new Attachments(request);
+        this.shares = new Shares(request);
+        this.questions = new Questions(request);
+        this.memory = new Memory(request);
+        this.runs = new Runs(request, (id, after, signal) => this.openRunEvents(id, after, signal), this.questions);
+        this.providers = new Providers(request);
+        this.grant = { get: (options) => this.request('GET', '/v1/grant', undefined, options) };
+        this.health = { get: (options) => this.request('GET', '/v1/health', undefined, options) };
+    }
+    /** Establish NDJSON through the JSON client's cold-socket/retry transport; leave the live body unread. */
+    async openCustomDeliveries(path, options) {
+        const response = await this.call(() => this.client.rawResponse('GET', path, {
+            headers: { accept: 'application/x-ndjson', ...options.headers }, signal: options.signal,
+            timeout: 0, maxRetries: options.maxRetries,
+        }));
+        if (!response.ok)
+            throw mapError(await responseError(response));
+        return response;
+    }
+    openRunEvents(id, after, signal) {
+        const baseURL = this.baseURL;
+        if (!baseURL)
+            throw new CrouterError('Run events require an app listener baseURL');
+        return this.call(() => this.eventFetch(`${baseURL.replace(/\/$/, '')}/v1/runs/${encodeURIComponent(id)}/events?after=${after}`, {
+            headers: { 'accept': 'text/event-stream', ...(this.bearerToken ? { Authorization: `Bearer ${this.bearerToken}` } : {}),
+                ...(after ? { 'Last-Event-ID': String(after) } : {}) }, signal,
+        }));
+    }
+    /** `GET /v1/files/download` as a raw fetch: bytes are not JSON, so it bypasses the JSON client but
+     *  still goes through `call()`, which supplies the connection token and refreshes it once on a 401. */
+    async openDownload(path, options) {
+        const baseURL = this.baseURL;
+        if (!baseURL)
+            throw new CrouterError('File downloads require an app listener baseURL');
+        if (typeof path !== 'string' || path === '')
+            throw new TypeError('path is required');
+        const url = `${baseURL.replace(/\/$/, '')}/v1/files/download?${new URLSearchParams({ path })}`;
+        const response = await this.call(async () => {
+            try {
+                return await this.eventFetch(url, {
+                    headers: { ...(this.bearerToken ? { Authorization: `Bearer ${this.bearerToken}` } : {}), ...(options.range ? { Range: options.range } : {}) },
+                    ...(options.signal ? { signal: options.signal } : {}),
+                });
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw new APIUserAbortError(0, 'request_aborted', 'download aborted by caller');
+                throw new APIConnectionError(0, 'connection_error', error instanceof Error ? error.message : String(error));
+            }
+        });
+        if (response.ok)
+            return response;
+        throw mapError(await responseError(response));
+    }
+    /** Sends one request to any daemon route, for routes the namespaces above do not wrap. */
+    request(method, path, body, options) {
+        return this.call(() => this.client.request(method, path, body, options), path !== '/v1/health');
+    }
+    async authStatus(params = {}, options) {
+        if (this.baseURL === undefined && (!isNodeRuntime() || !await socketIsReachable(this.socketPath))) {
+            return connectStatus('Install crtr, run `crtr sys connect`, and paste the base URL and token it prints.');
+        }
+        let daemon;
+        try {
+            daemon = await this.call(() => this.client.request('GET', routes.status(), undefined, options));
+        }
+        catch (error) {
+            if (!(error instanceof APIError))
+                throw error;
+            const mapped = mapError(error);
+            if (mapped instanceof AuthenticationError) {
+                return connectStatus('The daemon rejected the saved token. Run `crtr sys connect` and paste the new base URL and token it prints.');
+            }
+            if (mapped instanceof APIConnectionError) {
+                const instruction = this.baseURL === undefined
+                    ? 'Run `crtr sys connect` and paste the base URL and token it prints.'
+                    : `The daemon at ${this.baseURL} could not be reached. Run \`crtr sys connect\` and paste the new base URL and token it prints.`;
+                return connectStatus(instruction);
+            }
+            throw mapped;
+        }
+        const daemonStatus = {
+            base_url: this.baseURL ?? daemon.listeners.socket_path,
+            runtime_version: daemon.runtime_version,
+            api_version: daemon.api_version,
+            startup_phase: daemon.startup_phase,
+            tcp: daemon.listeners.tcp,
+        };
+        if (daemon.startup_phase !== 'ready') {
+            return { connected: true, daemon: daemonStatus, model: null, next_step: null, instructions: null };
+        }
+        const model = await this.call(() => this.client.request('GET', withQuery(routes.modelAuthReadiness(), params), undefined, options));
+        if (model.credential !== 'ready') {
+            return {
+                connected: true,
+                daemon: daemonStatus,
+                model,
+                next_step: 'login',
+                instructions: `Run \`${connectCommand(params)}\` to log in to ${model.provider}.`,
+            };
+        }
+        return { connected: true, daemon: daemonStatus, model, next_step: null, instructions: null };
+    }
+    stream(params, options) {
+        const node = this.nodes.create(params, options);
+        const { timeout: _timeout, ...streamOptions } = options ?? {};
+        return new NodeStream(node, async (signal) => {
+            const created = await node;
+            return this.call(() => this.client.getNodeEvents(created.node_id, {}, { ...streamOptions, signal }));
+        }, options?.signal);
+    }
+    events(id, options = {}) {
+        const { after, ...streamOptions } = options;
+        const node = this.nodes.retrieve(id, streamOptions);
+        return new NodeStream(node, async (signal) => {
+            const existing = await node;
+            return this.call(() => this.client.getNodeEvents(existing.node_id, { after }, { ...streamOptions, signal }));
+        }, options.signal);
+    }
+    async outcome(id, options = {}) {
+        const validId = nodeId(id);
+        const { wait, ...requestOptions } = options;
+        if (wait !== undefined && (!Number.isInteger(wait) || wait < 0 || wait > POLL_WAIT_SECONDS)) {
+            throw new RangeError('wait must be an integer between 0 and 25');
+        }
+        const timeout = wait === undefined ? requestOptions.timeout : wait * 1_000 + (requestOptions.timeout ?? this.timeout);
+        return this.call(() => this.client.request('GET', withQuery(routes.nodeOutcome(validId), { wait }), undefined, { ...requestOptions, timeout }));
+    }
+    async waitForOutcome(id, options) {
+        for (;;) {
+            const response = await this.outcome(id, { ...options, wait: POLL_WAIT_SECONDS });
+            if (response.state === 'settled' && response.outcome !== null)
+                return response.outcome;
+        }
+    }
+    async createAndWait(params, options) {
+        const node = await this.nodes.create(params, options);
+        return this.waitForOutcome(node.node_id, options);
+    }
+    async parse(params, options) {
+        const outcome = await this.createAndWait({
+            ...params,
+            ...(params.parent == null && params.root_lifecycle === undefined ? { root_lifecycle: 'terminal' } : {}),
+        }, options);
+        if (outcome.kind === 'result') {
+            return { ...outcome, output_parsed: outcome.structured_result };
+        }
+        return { ...outcome, output_parsed: null };
+    }
+    async call(operation, authenticate = true) {
+        for (let attempt = 0;; attempt++) {
+            // A token refresh refused by the directory surfaces with its status class, like any other API error.
+            if (authenticate && this.tokenSource)
+                this.connectionToken = await this.tokenSource().catch(throwMapped);
+            let result;
+            try {
+                result = await operation();
+            }
+            catch (error) {
+                if (authenticate && attempt === 0 && error instanceof APIError && error.status === 401 && this.onUnauthorized) {
+                    await this.onUnauthorized().catch(throwMapped);
+                    continue;
+                }
+                throw mapError(error);
+            }
+            if (authenticate && attempt === 0 && result instanceof Response && result.status === 401 && this.onUnauthorized) {
+                await result.body?.cancel();
+                await this.onUnauthorized().catch(throwMapped);
+                continue;
+            }
+            return result;
+        }
+    }
+}
+/** Rethrow an `APIError` as its status class; any other error from caller-supplied token hooks passes through unchanged. */
+function throwMapped(error) {
+    throw error instanceof APIError ? mapError(error) : error;
+}
+/** A non-2xx answer's JSON envelope as an `APIError`; a body that is not the envelope keeps the status. */
+async function responseError(response) {
+    let error;
+    try {
+        error = (await response.json()).error;
+    }
+    catch {
+        error = undefined;
+    }
+    return new APIError(response.status, error?.code ?? 'invalid_response', error?.message ?? `HTTP ${response.status}`, error?.details, response.headers, error);
+}
+function serializeCreate(params) {
+    const { output_schema, ...rest } = params;
+    const independentRoot = rest.parent === undefined && rest.root === undefined ? { root: true } : {};
+    if (output_schema === undefined)
+        return { ...independentRoot, ...rest };
+    return {
+        ...independentRoot,
+        ...rest,
+        output_schema: typeof output_schema === 'string' ? output_schema : JSON.stringify(resolveJsonSchema(output_schema)),
+    };
+}
+function messageBody(body) {
+    if (typeof body === 'string')
+        return { body };
+    const { from: _from, ...request } = body;
+    return request;
+}
+function withQuery(path, query) {
+    if (query === undefined)
+        return path;
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined)
+            search.set(key, String(value));
+    }
+    const suffix = search.toString();
+    return suffix === '' ? path : `${path}?${suffix}`;
+}
+function connectStatus(instructions) {
+    return { connected: false, daemon: null, model: null, next_step: 'connect', instructions };
+}
+function connectCommand(params) {
+    const selectors = [
+        ['profile', params.profile],
+        ['cwd', params.cwd],
+        ['kind', params.kind],
+        ['model', params.model],
+    ].flatMap(([name, value]) => value === undefined ? [] : [`--${name}`, shellArgument(value)]);
+    return ['crtr', 'sys', 'connect', ...selectors].join(' ');
+}
+function shellArgument(value) {
+    if (/^[A-Za-z0-9_./:-]+$/.test(value))
+        return value;
+    return `'${value.replaceAll("'", String.fromCharCode(39, 34, 39, 34, 39))}'`;
+}
+async function socketIsReachable(socketPath) {
+    const load = new Function('specifier', 'return import(specifier)');
+    const [{ createConnection }, { defaultSocketPath }] = await Promise.all([
+        load('node:net'),
+        load('@crouter/api/node'),
+    ]);
+    const path = socketPath ?? defaultSocketPath();
+    return new Promise((resolve) => {
+        const socket = createConnection({ path });
+        const finish = (reachable) => {
+            socket.destroy();
+            resolve(reachable);
+        };
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+        socket.setTimeout(100, () => finish(false));
+    });
+}
+function nodeEnvironment() {
+    return isNodeRuntime() ? process.env : {};
+}
+function isNodeRuntime() {
+    return typeof process !== 'undefined' && process.versions?.node !== undefined;
+}
+function localSocketFetch(socketPath) {
+    const load = new Function('specifier', 'return import(specifier)');
+    let fetchPromise;
+    const localFetch = (input, init) => {
+        fetchPromise ??= load('@crouter/api/node').then(({ socketFetch, defaultSocketPath }) => socketFetch(socketPath ?? defaultSocketPath()));
+        return fetchPromise.then((fetch) => fetch(input, init));
+    };
+    localFetch[LOCAL_SOCKET_FETCH] = true;
+    return localFetch;
+}
+async function startDaemon() {
+    const load = new Function('specifier', 'return import(specifier)');
+    const { spawn } = await load('node:child_process');
+    await new Promise((resolve, reject) => {
+        const child = spawn('crtr', ['sys', 'daemon', 'start'], { stdio: ['ignore', 'ignore', 'pipe'] });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+        child.once('error', (error) => reject(new CrouterError(`could not run \`crtr sys daemon start\`: ${error.message}`)));
+        child.once('exit', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new CrouterError(`\`crtr sys daemon start\` exited ${String(code)}${stderr === '' ? '' : `: ${stderr.trim()}`}`));
+        });
+    });
+}

package/dist/error-codes.d.ts

@@ -0,0 +1,7 @@
+export { errorCodes } from '@crouter/api';
+export type { ErrorCode, ErrorEnvelope, ErrorOrigin, ErrorType } from '@crouter/api';
+export { mapError } from './errors.js';
+/** Codes the SDK raises itself rather than reading from a daemon or directory response. */
+export declare const sdkErrorCodes: readonly ["crouter_error", "id_token_invalid", "oauth_nonce_missing", "oauth_state_mismatch", "oauth_exchange_mismatch", "run_idle", "waiting_on_user", "request_aborted", "request_timeout", "connection_error", "transport_error", "daemon_unavailable", "daemon_request_interrupted", "daemon_health_unavailable", "invalid_response", "stream_error", "stream_ended"];
+/** A code the SDK raises itself. An `APIError`'s `code` is one of these or an `ErrorCode` from the contract. */
+export type SdkErrorCode = typeof sdkErrorCodes[number];

package/dist/error-codes.js

@@ -0,0 +1,35 @@
+// The API contract owns the daemon's table; the SDK adds the codes it raises itself.
+export { errorCodes } from '@crouter/api';
+export { mapError } from './errors.js';
+/** Codes the SDK raises itself rather than reading from a daemon or directory response. */
+export const sdkErrorCodes = [
+    /** A `CrouterError` configuration or protocol failure with no more specific code. */
+    'crouter_error',
+    /** An ID token was missing, failed verification, or its nonce did not match. */
+    'id_token_invalid',
+    /** `exchangeIdentity` was called without the nonce `authorizeUrl` returned. */
+    'oauth_nonce_missing',
+    /** The callback's `state` was missing or differed from the saved one. */
+    'oauth_state_mismatch',
+    /** `exchangeCode` got a sign-in-only answer, or `exchangeIdentity` got one carrying a connection. */
+    'oauth_exchange_mismatch',
+    /** `runs.parse`: the run stopped without settling. */
+    'run_idle',
+    /** `runs.parse`: the run waits on a question and no `onQuestion` was given. */
+    'waiting_on_user',
+    /** The caller's `AbortSignal` fired (`APIUserAbortError`). */
+    'request_aborted',
+    /** The request exceeded its timeout (`APIConnectionTimeoutError`). */
+    'request_timeout',
+    /** The daemon could not be reached, or the connection failed (`APIConnectionError`). */
+    'connection_error',
+    'transport_error',
+    'daemon_unavailable',
+    'daemon_request_interrupted',
+    'daemon_health_unavailable',
+    /** A response the SDK could not read as the API's JSON or error envelope. */
+    'invalid_response',
+    /** An event stream failed, or ended before the reply or node it carried did. */
+    'stream_error',
+    'stream_ended',
+];

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+import { APIError } from '@crouter/api';
+import type { SdkErrorCode } from './error-codes.js';
+export { APIError };
+/** An SDK configuration or protocol error, raised by the SDK itself. Its `code` is an `SdkErrorCode`. */
+export declare class CrouterError extends APIError {
+    readonly code: SdkErrorCode;
+    constructor(message: string, code?: SdkErrorCode);
+}
+/** The daemon rejected the request: HTTP 400. */
+export declare class BadRequestError extends APIError {
+}
+/** The token was missing or wrong: HTTP 401. */
+export declare class AuthenticationError extends APIError {
+}
+/** The caller is not allowed to do this: HTTP 403. */
+export declare class PermissionDeniedError extends APIError {
+}
+/** No such node, profile, cron, or other resource: HTTP 404. */
+export declare class NotFoundError extends APIError {
+}
+/** The resource is in a state that forbids the request: HTTP 409. */
+export declare class ConflictError extends APIError {
+}
+/** The request was well-formed but unusable, or too large: HTTP 413 and 422. */
+export declare class UnprocessableEntityError extends APIError {
+}
+/** Too many requests: HTTP 429. */
+export declare class RateLimitError extends APIError {
+}
+/** The daemon failed while handling the request: HTTP 500 and above. */
+export declare class InternalServerError extends APIError {
+}
+/** The daemon could not be reached, or the connection failed mid-request. */
+export declare class APIConnectionError extends APIError {
+}
+/** The request exceeded its timeout before the daemon answered. */
+export declare class APIConnectionTimeoutError extends APIConnectionError {
+}
+/** The caller's `AbortSignal` fired. */
+export declare class APIUserAbortError extends APIError {
+}
+/** Maps a transport failure or a plain `APIError` onto the specific class for its status and code. */
+export declare function mapError(error: unknown): APIError;

package/dist/errors.js

@@ -0,0 +1,76 @@
+import { APIError } from '@crouter/api';
+export { APIError };
+/** An SDK configuration or protocol error, raised by the SDK itself. Its `code` is an `SdkErrorCode`. */
+export class CrouterError extends APIError {
+    constructor(message, code = 'crouter_error') {
+        super(0, code, message);
+        this.name = 'CrouterError';
+    }
+}
+/** The daemon rejected the request: HTTP 400. */
+export class BadRequestError extends APIError {
+}
+/** The token was missing or wrong: HTTP 401. */
+export class AuthenticationError extends APIError {
+}
+/** The caller is not allowed to do this: HTTP 403. */
+export class PermissionDeniedError extends APIError {
+}
+/** No such node, profile, cron, or other resource: HTTP 404. */
+export class NotFoundError extends APIError {
+}
+/** The resource is in a state that forbids the request: HTTP 409. */
+export class ConflictError extends APIError {
+}
+/** The request was well-formed but unusable, or too large: HTTP 413 and 422. */
+export class UnprocessableEntityError extends APIError {
+}
+/** Too many requests: HTTP 429. */
+export class RateLimitError extends APIError {
+}
+/** The daemon failed while handling the request: HTTP 500 and above. */
+export class InternalServerError extends APIError {
+}
+/** The daemon could not be reached, or the connection failed mid-request. */
+export class APIConnectionError extends APIError {
+}
+/** The request exceeded its timeout before the daemon answered. */
+export class APIConnectionTimeoutError extends APIConnectionError {
+}
+/** The caller's `AbortSignal` fired. */
+export class APIUserAbortError extends APIError {
+}
+/** Maps a transport failure or a plain `APIError` onto the specific class for its status and code. */
+export function mapError(error) {
+    if (!(error instanceof APIError) || error.constructor !== APIError) {
+        return error instanceof APIError ? error : new APIConnectionError(0, 'connection_error', error instanceof Error ? error.message : String(error));
+    }
+    const Constructor = error.code === 'request_aborted'
+        ? APIUserAbortError
+        : error.status === 504 || error.code === 'request_timeout'
+            ? APIConnectionTimeoutError
+            : error.code === 'daemon_unavailable' || error.code === 'transport_error' || error.code === 'daemon_request_interrupted' || error.code === 'daemon_health_unavailable'
+                ? APIConnectionError
+                : error.status === 400
+                    ? BadRequestError
+                    : error.status === 401
+                        ? AuthenticationError
+                        : error.status === 403
+                            ? PermissionDeniedError
+                            : error.status === 404
+                                ? NotFoundError
+                                : error.status === 409
+                                    ? ConflictError
+                                    : error.status === 413 || error.status === 422
+                                        ? UnprocessableEntityError
+                                        : error.status === 402 || error.status === 429
+                                            ? RateLimitError
+                                            : error.status >= 500
+                                                ? InternalServerError
+                                                : APIError;
+    return new Constructor(error.status, error.code, error.message, error.details, error.headers, {
+        type: error.type, param: error.param, origin: error.origin, retryable: error.retryable,
+        retry_after_s: error.retryAfterS, reset_at: error.resetAt, request_id: error.requestId, run_id: error.runId,
+        question_id: error.questionId, scope: error.scope, user_action: error.userAction,
+    });
+}