@boxline/sdk 1.1.0

package/dist/errors.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Errors. Every failed call throws a BoxlineError (or a subclass) with the HTTP status, the API's stable
+ * snake_case `code`, a message for people, the API's `requestId` to quote when asking for support, and your own
+ * `clientRequestId` if you sent one.
+ */
+/** Stable error codes the SDK gives its own class to (docs/CONTRACT.md "Errors"). */
+export declare const ErrorCode: {
+    readonly rateLimited: "rate_limited";
+    readonly concurrencyLimit: "concurrency_limit";
+    readonly featureNotInPlan: "feature_not_in_plan";
+    readonly projectSuspended: "project_suspended";
+    readonly idempotencyMismatch: "idempotency_mismatch";
+    readonly idempotencyInProgress: "idempotency_in_progress";
+    readonly invalidCursor: "invalid_cursor";
+    readonly captchaTimeout: "captcha_timeout";
+    readonly pageUnreachable: "page_unreachable";
+    readonly pageTimeout: "page_timeout";
+    readonly notAWebPage: "not_a_web_page";
+    readonly modelRefused: "model_refused";
+    readonly searchUnavailable: "search_unavailable";
+    readonly outOfViewport: "out_of_viewport";
+    readonly webhookUrlNotAllowed: "webhook_url_not_allowed";
+    readonly webhooksUnavailable: "webhooks_unavailable";
+    readonly webhookDisabled: "webhook_disabled";
+    readonly payloadExpired: "payload_expired";
+    /** A delivery's errorCode (never an HTTP error): the project already had 10,000 deliveries waiting. */
+    readonly queueFull: "queue_full";
+    readonly invalidSignature: "invalid_signature";
+    readonly variablesWithExtensions: "variables_with_extensions";
+    readonly extensionDenied: "extension_denied";
+    readonly crossSiteRequest: "cross_site_request";
+    readonly invalidExtension: "invalid_extension";
+    readonly payloadTooLarge: "payload_too_large";
+    readonly limitReached: "limit_reached";
+    readonly missingVariables: "missing_variables";
+    readonly planLimit: "plan_limit";
+    readonly tooManySecretValues: "too_many_secret_values";
+    readonly secretExists: "secret_exists";
+    readonly secretNotForAi: "secret_not_for_ai";
+    readonly secretNotForShell: "secret_not_for_shell";
+    readonly machineTooOld: "machine_too_old";
+    /**
+     * An agent or task run's errorCode (never an HTTP error): the answer did not match the run's output schema after the
+     * repair try (the run's `error` lists the problems).
+     */
+    readonly outputInvalid: "output_invalid";
+    /**
+     * Agent-run errorCodes (never HTTP errors) for a run that stopped at one of its limits and can be continued
+     * (agent.continueRun) while its `continuable` is set: its maxSteps, its maxCostUsd, maxConsecutiveErrors tool errors in
+     * a row, or the same call with the same result 5 times in a row.
+     */
+    readonly maxSteps: "max_steps";
+    readonly maxCost: "max_cost";
+    readonly tooManyErrors: "too_many_errors";
+    readonly noProgress: "no_progress";
+    /**
+     * Agent-run errorCode (continuable like the limits): the API server running the loop stopped (a restart, a deploy)
+     * while its session went on; agent.continueRun picks it up in the same browser.
+     */
+    readonly serverRestarted: "server_restarted";
+    /** Agent-run errorCodes: its session reached its time limit, or ended another way, while it worked (not continuable). */
+    readonly sessionTimeout: "session_timeout";
+    readonly sessionEnded: "session_ended";
+    /** 409: agent.continueRun on a run that did not stop at a limit, was continued already, or whose window passed. */
+    readonly notContinuable: "not_continuable";
+    /** 409: agent.sendMessage after 50 messages to one run. */
+    readonly tooManyMessages: "too_many_messages";
+    /** 409: takeover, handBack or sendMessage on a run whose server stopped (continue it instead). */
+    readonly runNotLive: "run_not_live";
+    /** 400: project.setModelKey when the provider does not accept the key (nothing is saved). */
+    readonly invalidModelKey: "invalid_model_key";
+    /** 400: a call on the project's own model key was refused by the provider (a run ends with this errorCode); never falls back to Boxline's key. */
+    readonly modelKeyRejected: "model_key_rejected";
+    /** 502: another failure of a call on the project's own model key (the provider's text, key scrubbed). */
+    readonly modelError: "model_error";
+    /** 413: contexts.create({fromSession}) when the session's cookies and site storage exceed 16 MB. */
+    readonly contextTooLarge: "context_too_large";
+    /** 409: the session has ended (e.g. an agent run or continueRun in it). */
+    readonly sessionNotRunning: "session_not_running";
+    readonly unauthorized: "unauthorized";
+    readonly notFound: "not_found";
+    readonly connectionError: "connection_error";
+    readonly timeout: "timeout";
+};
+export interface ErrorDetails {
+    /** The API's request id (error body, else the X-Request-Id header); null when no response came back. */
+    requestId?: string | null;
+    /** Your own id for the request (RequestOptions.clientRequestId), as the API echoed it in X-Client-Request-Id. */
+    clientRequestId?: string | null;
+    headers?: Headers;
+    /** The parsed error body, when there was one. */
+    body?: unknown;
+    cause?: unknown;
+}
+export declare class BoxlineError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** The API's id for the request: quote it when asking for support. */
+    readonly requestId: string | null;
+    /** Your own id for the request, if you sent one (RequestOptions.clientRequestId). */
+    readonly clientRequestId: string | null;
+    /** Response headers (RateLimit-*, Retry-After, …); undefined when no response came back. */
+    readonly headers?: Headers;
+    readonly body?: unknown;
+    constructor(status: number, code: string, message: string, details?: ErrorDetails);
+    /** Whether trying the same call again later can succeed (rate limits, server errors, network trouble). */
+    get retryable(): boolean;
+}
+/** 429: too many requests (`rate_limited`) or all of the plan's concurrent sessions in use (`concurrency_limit`). */
+export declare class RateLimitError extends BoxlineError {
+    /** Seconds the server asked to wait (Retry-After), when it said. */
+    readonly retryAfter: number | null;
+    constructor(status: number, code: string, message: string, details?: ErrorDetails);
+}
+/** 402 `feature_not_in_plan`: the project's plan does not include this. */
+export declare class FeatureNotInPlanError extends BoxlineError {
+    name: string;
+}
+/** 403 `project_suspended`: an admin suspended the project; the message says why. */
+export declare class ProjectSuspendedError extends BoxlineError {
+    name: string;
+}
+/**
+ * 422 `idempotency_mismatch`: this Idempotency-Key was already used for a different request (another body or route),
+ * or, for a new API key, by another caller (another API key or console login).
+ */
+export declare class IdempotencyMismatchError extends BoxlineError {
+    name: string;
+}
+/** 409 `idempotency_in_progress`: the first request with this key is still being answered (retried automatically). */
+export declare class IdempotencyInProgressError extends BoxlineError {
+    name: string;
+}
+/** 400 `invalid_cursor`: `after` is not a `next` value of that list. */
+export declare class InvalidCursorError extends BoxlineError {
+    name: string;
+}
+/** `captcha_timeout`: a CAPTCHA kept waiting for a person (a plain-English step, or waitForHuman). */
+export declare class CaptchaTimeoutError extends BoxlineError {
+    name: string;
+}
+/** 502 `page_unreachable` (fetch, screenshot, pdf, extract): the page could not be loaded; the message says why. */
+export declare class PageUnreachableError extends BoxlineError {
+    name: string;
+}
+/** 504 `page_timeout` (fetch, screenshot, pdf, extract): the page did not finish loading within `timeoutMs`. */
+export declare class PageTimeoutError extends BoxlineError {
+    name: string;
+}
+/** 422 `not_a_web_page` (fetch, extract, search, crawl): the address is a file Chrome only displays (a PDF), with no page text. */
+export declare class NotAWebPageError extends BoxlineError {
+    name: string;
+}
+/** 422 `model_refused` (extract): the model declined to extract from these pages. */
+export declare class ModelRefusedError extends BoxlineError {
+    name: string;
+}
+/**
+ * 503 `search_unavailable`: web search is not set up on this server, or its provider did not answer or is limiting
+ * the platform (then `retryable`, with Retry-After).
+ */
+export declare class SearchUnavailableError extends BoxlineError {
+    name: string;
+}
+/** 400 `out_of_viewport`: a mouse action's point is outside the page (or the computer-use screenshot). */
+export declare class OutOfViewportError extends BoxlineError {
+    name: string;
+}
+/** 400 `webhook_url_not_allowed`: webhook endpoints must be public HTTPS addresses (the message says what is wrong). */
+export declare class WebhookUrlNotAllowedError extends BoxlineError {
+    name: string;
+}
+/** 503 `webhooks_unavailable`: webhook delivery is not set up on this server. */
+export declare class WebhooksUnavailableError extends BoxlineError {
+    name: string;
+}
+/** 409 `webhook_disabled`: the endpoint is switched off; turn it on (update enabled: true) first. */
+export declare class WebhookDisabledError extends BoxlineError {
+    name: string;
+}
+/** 409 `payload_expired`: the event's body is kept 7 days; that delivery can no longer be sent again. */
+export declare class PayloadExpiredError extends BoxlineError {
+    name: string;
+}
+/** 400 `variables_with_extensions`: an agent run with variables in a session with extensions (see allowWithExtensions). */
+export declare class VariablesWithExtensionsError extends BoxlineError {
+    name: string;
+}
+/** 403 `extension_denied`: the operator does not allow this extension. */
+export declare class ExtensionDeniedError extends BoxlineError {
+    name: string;
+}
+/** 403 `cross_site_request`: a console-login upload that did not come from the platform's own sites. */
+export declare class CrossSiteRequestError extends BoxlineError {
+    name: string;
+}
+/** 400 `invalid_extension`: the zip is not an acceptable Manifest V3 extension (the message says why). */
+export declare class InvalidExtensionError extends BoxlineError {
+    name: string;
+}
+/** 413 `payload_too_large`: the body is larger than the route allows (an extension zip: 10 MB). */
+export declare class PayloadTooLargeError extends BoxlineError {
+    name: string;
+}
+/** 409 `limit_reached`: the project has as many as it may (e.g. 100 extensions). */
+export declare class LimitReachedError extends BoxlineError {
+    name: string;
+}
+/** 400 `missing_variables`: a task run (or its schedule) has no value for a variable without a default; the message names them. */
+export declare class MissingVariablesError extends BoxlineError {
+    name: string;
+}
+/**
+ * `plan_limit`: the plan allows no more of this (402: tasks, schedules switched on, searches on Free, project
+ * secrets beyond `maxSecrets`, a session longer than the plan allows); the message says the limit.
+ */
+export declare class PlanLimitError extends BoxlineError {
+    name: string;
+}
+/**
+ * 409 `too_many_secret_values`: the session already hides as many earlier secret values in its output as it can (256
+ * values or 256 KB); a session create, exec, agent run or step adding more is refused. Start a new session.
+ */
+export declare class TooManySecretValuesError extends BoxlineError {
+    name: string;
+}
+/** 409 `secret_exists`: the project has a secret with that name; change it with secrets.update. */
+export declare class SecretExistsError extends BoxlineError {
+    name: string;
+}
+/**
+ * 400 `secret_not_for_ai` / `secret_not_for_shell`: the secret's scope does not allow this use (scope "shell" is not for
+ * the AI; a secret goes into a shell only with scope "shell" or "all", or shell: true).
+ */
+export declare class SecretNotAllowedError extends BoxlineError {
+    name: string;
+}
+/**
+ * 409 `machine_too_old`: the session's machine comes from an image older than the API (during a deploy) and cannot take
+ * `env` or `secrets`; start a new session.
+ */
+export declare class MachineTooOldError extends BoxlineError {
+    name: string;
+}
+/**
+ * 409 `not_continuable`: agent.continueRun on a run that did not stop at one of its limits, was already continued (the
+ * message names the run that did), or whose continue window has passed.
+ */
+export declare class NotContinuableError extends BoxlineError {
+    name: string;
+}
+/** 409 `too_many_messages`: a run takes at most 50 messages (agent.sendMessage). */
+export declare class TooManyMessagesError extends BoxlineError {
+    name: string;
+}
+/**
+ * 409 `run_not_live`: agent.takeover, handBack or sendMessage on a run whose API server stopped (a restart, a deploy):
+ * no loop is left to act on it. Continue it (agent.continueRun) once it shows as failed with `server_restarted`.
+ */
+export declare class RunNotLiveError extends BoxlineError {
+    name: string;
+}
+/** 409 `session_not_running`: the session has ended (an agent run started or continued in it, a command, …). */
+export declare class SessionNotRunningError extends BoxlineError {
+    name: string;
+}
+/** Why verifyWebhook refused a delivery. */
+export type WebhookSignatureFailure = "malformed" | "timestamp_out_of_range" | "no_matching_signature";
+/**
+ * verifyWebhook refused a delivery (not an API error: answer the sender 400). `reason`: the Boxline-Signature header
+ * is missing or malformed, its timestamp is too far from now (a replay), or no signature matches the secret(s).
+ */
+export declare class WebhookSignatureError extends BoxlineError {
+    readonly reason: WebhookSignatureFailure;
+    constructor(reason: WebhookSignatureFailure, message: string);
+    get retryable(): boolean;
+}
+/** 401: missing or invalid API key. */
+export declare class AuthenticationError extends BoxlineError {
+    name: string;
+}
+/** 404: no such thing in this project. */
+export declare class NotFoundError extends BoxlineError {
+    name: string;
+}
+/** No response: the network failed or the server went away (retried automatically where safe). */
+export declare class BoxlineConnectionError extends BoxlineError {
+    constructor(message: string, details?: ErrorDetails);
+    get retryable(): boolean;
+}
+/** The request took longer than its time limit (`timeoutMs`). */
+export declare class BoxlineTimeoutError extends BoxlineConnectionError {
+    constructor(message: string, details?: ErrorDetails);
+}
+/** The error class for an API error: by its code first, then by its status. */
+export declare function makeError(status: number, code: string, message: string, details?: ErrorDetails): BoxlineError;
+/** Retry-After in seconds (a number of seconds or an HTTP date); null when absent or unreadable. */
+export declare function retryAfterSeconds(headers?: Headers): number | null;
+/** Turns an error response into a typed error. The body is read here (it is small JSON); this never throws. */
+export declare function errorFromResponse(res: Response, method: string, path: string, sentClientId?: string): Promise<BoxlineError>;