@abloatai/ablo 0.35.0 → 0.37.0

package/dist/transaction/errors.d.ts

@@ -1,428 +0,0 @@
-/**
- * The typed error hierarchy for this package. Every error the SDK throws is an
- * {@link AbloError} or one of its subclasses, so a consumer can catch broadly or
- * narrowly. There are two equivalent ways to tell errors apart:
- *
- * ```ts
- * // By class, with instanceof
- * if (err instanceof AbloRateLimitError) backoff(err.retryAfterSeconds);
- *
- * // By discriminator string, for cases where class identity is lost —
- * // for example after an error crosses a web worker boundary
- * if (err.type === 'AbloRateLimitError') { ... }
- * ```
- *
- * Both work on every subclass.
- */
-import { z } from 'zod';
-import type { ErrorCode } from './errorCodes.js';
-import { type WireClaimSummary, type ModelClaim, type ModelTarget, type ParticipantKind } from './coordination/schema.js';
-export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errorCodes.js';
-export { ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errorCodes.js';
-/**
- * The base class for every error this SDK throws. It carries the fields common
- * to all of them — a {@link type} discriminator, an optional stable {@link code},
- * and optional HTTP and diagnostic metadata — and defines the shared JSON and
- * string serialization. Every other error class extends it.
- */
-export declare class AbloError extends Error {
-    /** A discriminator string equal to the class name. Switch on `error.type` to
-     *  distinguish error kinds when `instanceof` is unreliable, such as after an
-     *  error has crossed a serialization boundary. */
-    readonly type: string;
-    /** A stable, machine-readable identifier for the error, drawn from the
-     *  {@link ErrorCode} registry — for example `'apikey_invalid'` or
-     *  `'capability_scope_denied'` — suitable for logs, metrics, and `switch`
-     *  handling. It is typed as a plain `string` rather than {@link ErrorCode} so
-     *  this client can still surface a code from a newer server that it does not
-     *  yet recognize; code producers are constrained at the constructor instead. */
-    readonly code?: string;
-    /** HTTP status code, when the error originated from an HTTP response. */
-    readonly httpStatus?: number;
-    /** A correlation id for tracing a request through the server, present when the
-     *  server returned one on the `x-request-id` header. Include it in support
-     *  requests. */
-    readonly requestId?: string;
-    /** The specific input that caused the error, as a model or field path such as
-     *  `'dataroomMember.grants.subject'`, so tooling can point at the exact
-     *  offending value. */
-    readonly param?: string;
-    /** A link to the documentation for this error's {@link code}. When not set
-     *  explicitly, it is derived from the code by {@link docUrlForCode}. */
-    readonly docUrl?: string;
-    /** Extra structured data specific to this error, merged into the serialized
-     *  envelope — for example a schema push's `{ warnings, unexecutable }`, or the
-     *  conflicting rows of a stale write. This detail is preserved through
-     *  {@link toJSON} rather than flattened into the message. */
-    readonly details?: Readonly<Record<string, unknown>>;
-    constructor(message: string, options?: {
-        code?: ErrorCode;
-        httpStatus?: number;
-        requestId?: string;
-        cause?: unknown;
-        param?: string;
-        docUrl?: string;
-        details?: Readonly<Record<string, unknown>>;
-    });
-    /**
-     * Serializes the error to its wire shape: `{ type, code, param, message,
-     * doc_url, request_id }`, with any {@link details} merged in. This is the same
-     * JSON shape the SDK uses across HTTP bodies, WebSocket frames, and logs, so a
-     * consumer parses every Ablo error the same way.
-     */
-    toJSON(): {
-        type: string;
-        code?: string;
-        param?: string;
-        message: string;
-        doc_url?: string;
-        request_id?: string;
-        [key: string]: unknown;
-    };
-    /**
-     * Formats the error as a single line for logs and string interpolation:
-     * `AbloValidationError [code]: message (see docs) [request_id: …]`.
-     *
-     * It intentionally omits {@link details}, the cause, and the stack, which are
-     * what turn a logged rich error into an unreadable wall of text. The full
-     * structured payload remains available through {@link toJSON}; this is the
-     * concise human-readable form.
-     */
-    toString(): string;
-}
-/**
- * Builds the documentation URL for a stable error {@link ErrorCode}. This is the
- * single place the URL convention lives, so every error that carries a code gets
- * a `doc_url` automatically.
- */
-export declare function docUrlForCode(code: ErrorCode): string;
-/** 401 — invalid/missing/expired credentials. */
-export declare class AbloAuthenticationError extends AbloError {
-    readonly type: "AbloAuthenticationError";
-}
-/** 403 — credentials were valid but the action is forbidden (scope
- *  denial, revoked capability, role not authorized). */
-export declare class AbloPermissionError extends AbloError {
-    readonly type: "AbloPermissionError";
-}
-/** 429 — rate limit exceeded. Consumers should back off before retry. */
-export declare class AbloRateLimitError extends AbloError {
-    readonly type: "AbloRateLimitError";
-    readonly retryAfterSeconds?: number;
-    constructor(message: string, options?: {
-        code?: ErrorCode;
-        httpStatus?: number;
-        requestId?: string;
-        cause?: unknown;
-        retryAfterSeconds?: number;
-        details?: Readonly<Record<string, unknown>>;
-    });
-}
-/** 409 — same `Idempotency-Key` reused with a different request body. */
-export declare class AbloIdempotencyError extends AbloError {
-    readonly type: "AbloIdempotencyError";
-}
-/** Network / transport failure — TCP reset, DNS, timeout, abort. */
-export declare class AbloConnectionError extends AbloError {
-    readonly type: "AbloConnectionError";
-}
-/** 400 / 422 — request payload was invalid. */
-export declare class AbloValidationError extends AbloError {
-    readonly type: "AbloValidationError";
-}
-/**
- * An update or delete addressed a row that does not exist, or lies outside the
- * caller's organization (HTTP 404). Raw commit responses may report those
- * targets as `missingIds`; typed model methods raise this error instead of
- * returning a successful result for a write that quietly matched zero rows.
- * The absent ids are carried on {@link missingIds}.
- */
-export declare class AbloNotFoundError extends AbloError {
-    readonly type: "AbloNotFoundError";
-    /** The id(s) that matched no row. */
-    readonly missingIds: readonly string[];
-    constructor(message: string, missingIds: readonly string[], options?: {
-        requestId?: string;
-    });
-}
-/** 5xx — server-side error. Usually retryable with backoff. */
-export declare class AbloServerError extends AbloError {
-    readonly type: "AbloServerError";
-}
-/**
- * A write carried a `readAt` watermark, but the target row has changed since
- * that point (HTTP 409). The snapshot the caller reasoned from is stale, so the
- * safe response is to re-read the row and regenerate the write.
- *
- * {@link conflicts} lists the specific model-and-id pairs that changed during
- * the window between the read and the write, which lets a caller regenerate only
- * the rows that actually moved rather than everything.
- */
-export declare class AbloStaleContextError extends AbloError {
-    readonly type: "AbloStaleContextError";
-    /** Sync id at the caller's `readAt` when the write was attempted. */
-    readonly readAt?: number;
-    /** Entities that received deltas between `readAt` and the write. */
-    readonly conflicts?: readonly {
-        readonly model: string;
-        readonly id: string;
-        readonly observedSyncId: number;
-    }[];
-    constructor(message: string, options?: {
-        code?: ErrorCode;
-        httpStatus?: number;
-        requestId?: string;
-        cause?: unknown;
-        readAt?: number;
-        conflicts?: readonly {
-            readonly model: string;
-            readonly id: string;
-            readonly observedSyncId: number;
-        }[];
-    });
-}
-/**
- * The functional `update(id, current => next)` form gave up after exhausting its
- * reconcile budget, because the row stayed continuously contended under
- * sustained concurrent writes and no attempt could land its compare-and-swap.
- *
- * The SDK reaches this only at the extreme: it has already re-read, recomputed,
- * and retried on every intervening conflict on the caller's behalf. Catch it to
- * back off and retry later, raise the `retries` budget, or move the row to the
- * WebSocket transport, which queues writers fairly instead of racing them. The
- * last underlying conflict is available on `cause`.
- */
-export declare class AbloContentionError extends AbloError {
-    readonly type: "AbloContentionError";
-    /** The contended model + row that could not be written. */
-    readonly model: string;
-    readonly id: string;
-    /** How many reconcile rounds were attempted before giving up. */
-    readonly attempts: number;
-    constructor(model: string, id: string, attempts: number, options?: {
-        cause?: unknown;
-    });
-}
-export interface ClaimContext {
-    readonly id?: string;
-    readonly claimId?: string;
-    readonly actor?: string;
-    readonly participantKind?: ParticipantKind;
-    /** Human-readable phase the holder is in (`'editing'`). */
-    readonly reason?: string;
-    readonly description?: string;
-    readonly field?: string;
-    readonly status?: string;
-    readonly position?: number;
-    /** The epoch-milliseconds timestamp at which the claim expires. */
-    readonly expiresAt?: number;
-    readonly declaredAt?: number;
-    readonly entityType?: string;
-    readonly entityId?: string;
-    readonly target?: Partial<ModelTarget>;
-    readonly meta?: Record<string, unknown>;
-}
-export type ClaimErrorClaim = WireClaimSummary | ClaimContext;
-export declare function formatClaimedErrorMessage(args: {
-    readonly targetLabel: string;
-    readonly heldBy?: string;
-    readonly claim?: ClaimErrorClaim;
-    readonly policyReason?: string;
-    readonly fallback?: string;
-}): string;
-/**
- * The target entity is currently claimed by another participant and the caller
- * asked the SDK not to read/write through that claim.
- *
- * Pass `ifClaimed: 'return'` to inspect active claims yourself instead of
- * throwing; to wait for the claim to clear, take `ablo.<model>.claim({ id })`
- * (it queues fairly) rather than blocking the read.
- */
-export declare class AbloClaimedError extends AbloError {
-    readonly type: "AbloClaimedError";
-    readonly claims?: readonly ClaimErrorClaim[];
-    constructor(message: string, options?: {
-        code?: ErrorCode;
-        httpStatus?: number;
-        requestId?: string;
-        cause?: unknown;
-        claims?: readonly ClaimErrorClaim[];
-    });
-}
-/**
- * Builds a human-readable label for a claim target by joining its `model`, `id`,
- * and `field` with `/`, omitting any absent parts and falling back to `'target'`
- * when none are present.
- */
-export declare function claimTargetLabel(target: {
-    readonly model?: string;
-    readonly id?: string;
-    readonly field?: string;
-}): string;
-/**
- * Builds the {@link AbloClaimedError} for a write that was rejected because the
- * row is claimed. The first entry in `claims` is treated as the current holder,
- * and its metadata shapes the error message.
- */
-export declare function claimedError(target: {
-    readonly model?: string;
-    readonly id?: string;
-    readonly field?: string;
-}, claims: readonly ModelClaim[], code: 'model_claimed' | 'model_claimed_timeout' | 'queue_too_deep'): AbloClaimedError;
-/**
- * A structured description of the capability that would be needed to satisfy a
- * denied request. The server emits enough detail for the client to request, or
- * narrow an existing capability into, one that would pass on retry.
- */
-export interface RequiredCapability {
-    /** The operation or capability scope, for example `"report.update"` or
-     *  `"subscribe"`. */
-    readonly scope: string;
-    /** The concrete constraints the capability must satisfy — for example
-     *  `{ syncGroup: ["org_abc"] }` for a rejected subscription. Treat unknown
-     *  keys as forward-compatible additions and ignore them. */
-    readonly constraints?: Readonly<Record<string, readonly string[] | string>>;
-    /** A hint at the issuer — a public-key fingerprint or well-known URL
-     *  fragment. */
-    readonly issuer?: string;
-    /** The maximum lifetime, in seconds, the server suggests for the narrowed
-     *  capability. */
-    readonly ttlSeconds?: number;
-    /** A single-use value to embed in the retried request's capability, which
-     *  ties the retry to this specific denial and prevents replaying an old
-     *  capability. */
-    readonly nonce?: string;
-}
-/**
- * A scoped credential was denied, either because the key is unknown, revoked, or
- * expired (`capability_invalid`), or because the connection's scope does not
- * cover the attempted action (`capability_scope_denied`). For restricted (`rk_`)
- * API keys this is a server-side check against the key's granted sync groups and
- * operations.
- *
- * It extends {@link AbloPermissionError}, so it is caught both by code that
- * specifically checks for `CapabilityError` and by code that only distinguishes
- * the broader permission category. When present, {@link requiredCapability}
- * describes the scope a key would need to carry for the request to succeed on
- * retry.
- */
-export declare class CapabilityError extends AbloPermissionError {
-    readonly requiredCapability?: RequiredCapability;
-    constructor(code: 'capability_scope_denied' | 'capability_invalid', message: string, requiredCapability?: RequiredCapability);
-}
-/**
- * Thrown when the login session itself is invalid or expired, signaling that the
- * user should be sent to sign in again rather than offered a generic retry.
- *
- * It extends {@link AbloAuthenticationError}, so it is caught both by code using
- * the {@link AbloSessionError.isSessionError} check and by code that catches the
- * authentication category in general.
- */
-export declare class AbloSessionError extends AbloAuthenticationError {
-    readonly isSessionError = true;
-    readonly statusCode: number;
-    constructor(message: string, statusCode?: number);
-    /**
-     * Returns true when a value is a {@link AbloSessionError}, or any error-like
-     * object that reports itself as a session error through an `isSessionError`
-     * flag.
-     */
-    static isSessionError(error: unknown): error is AbloSessionError;
-    /**
-     * Determines whether an HTTP response means the login session has expired and
-     * the user should sign in again. When the body carries a structured Ablo error
-     * code, the decision is made from that code's recovery class; otherwise a bare
-     * 401 is treated as an expiry and a 403 is not.
-     */
-    static isSessionErrorResponse(status: number, body?: string): boolean;
-}
-/**
- * @deprecated Renamed to {@link AbloSessionError} — the one engine-named class
- * in the Ablo* hierarchy, brought in line with the family. Same class, same
- * `instanceof` identity. Removed in 0.36.0.
- */
-export declare const SyncSessionError: typeof AbloSessionError;
-/**
- * @deprecated Renamed to {@link AbloSessionError}. Removed in 0.36.0.
- */
-export type SyncSessionError = AbloSessionError;
-/**
- * The WebSocket-close counterpart to {@link AbloSessionError.isSessionErrorResponse}:
- * returns true for close reasons that mean the short-lived access credential
- * (`ek_` or `rk_`) has expired. The server closes such sockets with code 4001
- * and reason `'credential_expired'`. Because the credential is re-mintable from
- * the still-valid login, the connection layer re-mints it and reconnects rather
- * than signing the user out or clearing local data. Every other session close
- * reason, such as a revoked key or a genuinely lost login, stays terminal.
- */
-export declare function isAccessCredentialExpiryCloseReason(reason: string): boolean;
-/**
- * The one definition of the {@link RequiredCapability} wire shape. Every
- * boundary that carries a denial's capability detail — the error body parsed
- * here, and the rejected commit receipt in `wire/commit.ts` — composes this
- * schema rather than restating the fields, so a new member cannot reach one
- * boundary and miss the other.
- *
- * Unknown keys pass through: the server may describe a capability in more
- * detail than this build knows, and dropping those keys would leave a caller
- * unable to act on a denial it could otherwise satisfy.
- */
-export declare const requiredCapabilityWireSchema: z.ZodObject<{
-    scope: z.ZodString;
-    constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodString]>>>;
-    issuer: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
-    ttlSeconds: z.ZodPreprocess<z.ZodOptional<z.ZodNumber>>;
-    nonce: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
-}, z.core.$loose>;
-/**
- * Coerces any thrown value into an {@link AbloError}, so a consumer never catches
- * an untyped error from the SDK. An error that is already an {@link AbloError}
- * passes through unchanged, preserving its subclass, `code`, and `httpStatus`; a
- * plain `Error` keeps its message and is retained as the `cause` (carrying any
- * `code` attached to it); anything else is stringified.
- *
- * The SDK applies this at its public async boundaries so that `instanceof
- * AbloError` and `error.type` hold for whatever a consumer catches, no matter
- * which internal layer — transport, local storage, bootstrap, or a third-party
- * throw — produced the original error.
- */
-export declare function toAbloError(err: unknown): AbloError;
-/**
- * Builds the appropriate typed {@link AbloError} from a wire error. This is the
- * single code-to-class mapping shared by every transport that can reject a
- * request — HTTP responses through {@link translateHttpError}, WebSocket result
- * frames, and agent-job receipts.
- *
- * It decides by code first, then by status. Because a known {@link ErrorCode}
- * carries its canonical HTTP status in the registry, a transport that has no
- * status of its own (such as the WebSocket commit path) still produces the right
- * subclass, with its `code`, status, and retryability intact.
- */
-export declare function errorFromWire(message: string, opts?: {
-    code?: string;
-    /** Explicit transport status (HTTP). When omitted, derived from the
-     *  registry spec for `code` so frame transports map correctly too. */
-    httpStatus?: number;
-    requestId?: string;
-    requiredCapability?: RequiredCapability;
-    claims?: readonly ClaimErrorClaim[];
-    /** Everything the producer attached beyond the envelope's own fields. */
-    details?: Readonly<Record<string, unknown>>;
-}): AbloError;
-export declare function translateHttpError(status: number, body: unknown, requestId?: string): AbloError;
-/**
- * Reports whether an HTTP error body carries a code that {@link translateHttpError}
- * can read — a top-level `code`, a nested `error.code`, or a string `error`. A
- * caller that has a meaningful fallback code uses this to choose between routing
- * a structured body through {@link translateHttpError} and throwing its own typed
- * error with the fallback when the body is bare, rather than producing an error
- * with no code.
- */
-export declare function hasWireCode(body: unknown): boolean;
-/**
- * Extracts the canonical error `code` from a raw HTTP error body string — the
- * top-level `code` or a nested `error.code` — returning `undefined` for a
- * non-JSON or code-less body. Session-error detection uses it to tell a genuine
- * session expiry apart from other authentication failures.
- */
-export declare function extractWireCode(body?: string): string | undefined;