@dashai/sdk 0.7.0

package/dist/errors-BV75u7b9.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Error model for @dashai/sdk.
+ *
+ * The backend speaks a structured error envelope:
+ *
+ *   {
+ *     "code": "ROW_NOT_FOUND",
+ *     "message": "Row 123 not found in tasks",
+ *     "retriable": false,
+ *     "context": { ... }
+ *   }
+ *
+ * This module wraps that envelope in a typed `DashwiseError` plus a small
+ * set of subclasses for the codes consumers most commonly want to branch
+ * on (network errors, auth failures, row-not-found, contract violations).
+ *
+ * Anything not matched by a specific subclass becomes a plain
+ * `DashwiseError` carrying the raw `code`. Branch on `.code` for codes
+ * we don't have a class for; use `instanceof` for the common cases.
+ */
+/**
+ * Known error codes. Not exhaustive — the backend emits many codes
+ * specific to individual modules / endpoints. Use these constants when
+ * you want compile-time safety; otherwise treat `err.code` as a string.
+ *
+ * The list is curated to the codes a module author is most likely to
+ * branch on. Adding a new code here is a non-breaking change.
+ */
+declare const DashwiseErrorCode: {
+    readonly UNAUTHENTICATED: "UNAUTHENTICATED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
+    readonly INSTALLATION_NOT_FOUND: "INSTALLATION_NOT_FOUND";
+    readonly INSTALLATION_MODE_UNSUPPORTED: "INSTALLATION_MODE_UNSUPPORTED";
+    readonly CONTRACT_VIOLATION: "CONTRACT_VIOLATION";
+    readonly FIELD_NOT_READABLE: "FIELD_NOT_READABLE";
+    readonly FILTER_OP_UNKNOWN: "FILTER_OP_UNKNOWN";
+    readonly OPERATION_NOT_ALLOWED: "OPERATION_NOT_ALLOWED";
+    readonly DEPENDENCY_NOT_DECLARED: "DEPENDENCY_NOT_DECLARED";
+    readonly TABLE_NOT_IN_CONTRACT: "TABLE_NOT_IN_CONTRACT";
+    readonly PROVIDER_TABLE_MISSING: "PROVIDER_TABLE_MISSING";
+    readonly OPERATION_NOT_ALLOWED_BY_PROVIDER: "OPERATION_NOT_ALLOWED_BY_PROVIDER";
+    readonly LINK_FIELD_NOT_FOUND: "LINK_FIELD_NOT_FOUND";
+    readonly NOT_A_LINK_FIELD: "NOT_A_LINK_FIELD";
+    readonly JOIN_NOT_LINKED: "JOIN_NOT_LINKED";
+    readonly ACTION_NOT_EXPOSED: "ACTION_NOT_EXPOSED";
+    readonly ACTION_NOT_DECLARED: "ACTION_NOT_DECLARED";
+    readonly ACTION_INPUT_INVALID: "ACTION_INPUT_INVALID";
+    readonly ACTION_OUTPUT_INVALID: "ACTION_OUTPUT_INVALID";
+    readonly ACTION_RATE_LIMITED: "ACTION_RATE_LIMITED";
+    readonly ACTION_EXECUTION_FAILED: "ACTION_EXECUTION_FAILED";
+    readonly ROW_NOT_FOUND: "ROW_NOT_FOUND";
+    readonly TABLE_NOT_FOUND: "TABLE_NOT_FOUND";
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    readonly ROW_LIMIT_EXCEEDED: "ROW_LIMIT_EXCEEDED";
+    readonly STORAGE_LIMIT_EXCEEDED: "STORAGE_LIMIT_EXCEEDED";
+    readonly OUTBOUND_NOT_ALLOWED: "OUTBOUND_NOT_ALLOWED";
+    readonly OUTBOUND_CONCURRENCY_LIMITED: "OUTBOUND_CONCURRENCY_LIMITED";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+type DashwiseErrorCode = (typeof DashwiseErrorCode)[keyof typeof DashwiseErrorCode];
+/**
+ * Base class for every error thrown by @dashai/sdk. Carries the
+ * structured envelope from the backend (or a synthetic one for
+ * client-side failures like network errors / timeouts).
+ *
+ * Always thrown — never returned as a value. The async client methods
+ * `.list()` / `.get()` etc. reject with one of these on failure.
+ */
+declare class DashwiseError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly retriable: boolean;
+    readonly context: Record<string, unknown> | undefined;
+    /**
+     * Backend-issued trace anchor (Phase 6 slice 6.2, 2026-05-19).
+     * Mirrors the `x-request-id` response header. Populated whenever
+     * the backend's `RuntimeQueryController` (or any future endpoint
+     * that echoes the header) is the origin of this error. `null` when
+     * the failure is client-side (NetworkError / TimeoutError — the
+     * request never reached the server, so there's no server-issued
+     * ID to surface).
+     *
+     * Use this as a debugging trace anchor when filing a bug against a
+     * specific failed query — the matching row in `module_query_log`
+     * carries the full backend context (ast_hash, error_code,
+     * duration_ms, etc.).
+     */
+    readonly requestId: string | null;
+    constructor(code: string, message: string, options?: {
+        status?: number;
+        retriable?: boolean;
+        context?: Record<string, unknown>;
+        cause?: unknown;
+        /**
+         * Phase 6 slice 6.2: backend `x-request-id` response header,
+         * captured by the transport before throwing. Pass `undefined`
+         * (or omit) for client-side errors that never hit the server.
+         */
+        requestId?: string | null;
+    });
+}
+/** Network-level failure (DNS, connection refused, TLS, fetch threw). */
+declare class NetworkError extends DashwiseError {
+    constructor(message: string, cause?: unknown);
+}
+/** Request exceeded the configured timeout (`timeoutMs`). */
+declare class TimeoutError extends DashwiseError {
+    constructor(message: string, timeoutMs: number);
+}
+/** 401 — token missing/invalid. */
+declare class UnauthenticatedError extends DashwiseError {
+    constructor(message?: string, requestId?: string | null);
+}
+/** 403 — caller lacks the role/scope for this operation. */
+declare class ForbiddenError extends DashwiseError {
+    constructor(message: string, context?: Record<string, unknown>, requestId?: string | null);
+}
+/** 404 — `GET /db/<table>/<id>` for a missing or soft-deleted row. */
+declare class RowNotFoundError extends DashwiseError {
+    constructor(message: string, context?: Record<string, unknown>, requestId?: string | null);
+}
+/**
+ * Schema-level rejection: dep contract violated, table not exposed, field
+ * not readable, filter op not allowed. Covers the family of "you asked for
+ * something the manifest doesn't permit" errors.
+ */
+declare class ContractViolationError extends DashwiseError {
+    constructor(message: string, context?: Record<string, unknown>, requestId?: string | null);
+}
+/** 422-ish — request body failed validation. Inspect `context` for field-level errors. */
+declare class ValidationError extends DashwiseError {
+    constructor(message: string, context?: Record<string, unknown>, requestId?: string | null);
+}
+/**
+ * 404 — the caller's `module.json#dependencies` doesn't declare a
+ * dependency on the requested provider module, OR the declared dep
+ * exists but its `reads[]` block doesn't include the requested table.
+ *
+ * Either way the fix is on the **caller's** side: update the manifest
+ * to declare the dep / add the table to `reads[]`, then re-publish.
+ *
+ * Covers both `DEPENDENCY_NOT_DECLARED` and `TABLE_NOT_IN_CONTRACT` —
+ * inspect `err.code` to distinguish if you need different UX per case.
+ */
+declare class DependencyContractError extends DashwiseError {
+    constructor(code: string, message: string, context?: Record<string, unknown>, requestId?: string | null);
+}
+/**
+ * 404 — the provider's physical table no longer exists. This means the
+ * provider published a version that dropped the table while the
+ * consumer's installation still pinned the old contract. Recovery is
+ * on the **provider's** side (republish with the table) or the
+ * workspace admin's (downgrade the provider, or upgrade the consumer
+ * to a version whose `dependencies[]` no longer references it).
+ */
+declare class ProviderTableMissingError extends DashwiseError {
+    constructor(message: string, context?: Record<string, unknown>, requestId?: string | null);
+}
+/**
+ * 403 — the provider's `exposes.operations.<verb>.allowed` is explicitly
+ * `false` for the requested verb. Distinct from `OPERATION_NOT_ALLOWED`
+ * (which is the **owner's** own-table policy) — `OPERATION_NOT_ALLOWED_BY_PROVIDER`
+ * is the provider opting out of letting depending modules use a verb.
+ *
+ * No caller-side fix; either the provider needs to flip the gate, or
+ * the consumer needs to find a different way to satisfy the use case.
+ */
+declare class OperationNotAllowedByProviderError extends DashwiseError {
+    constructor(message: string, context?: Record<string, unknown>, requestId?: string | null);
+}
+/**
+ * 400 — `.join()` / `.leftJoin()` referenced a target the manifest
+ * can't resolve. Covers the three sub-cases above; inspect
+ * `err.code` to distinguish.
+ *
+ * Author-side fix in every case: either correct the slug, or pass
+ * an explicit `on` argument to bypass link-field inference.
+ */
+declare class JoinError extends DashwiseError {
+    constructor(code: string, message: string, context?: Record<string, unknown>, requestId?: string | null);
+}
+interface BackendErrorEnvelope {
+    code?: string;
+    message?: string;
+    retriable?: boolean;
+    context?: Record<string, unknown>;
+}
+/**
+ * Build a typed `DashwiseError` from the backend's response envelope.
+ *
+ * The mapping picks the most specific subclass for codes we have a class
+ * for; everything else becomes a plain `DashwiseError` carrying the raw
+ * code. This keeps the type set small while still letting consumers
+ * branch on string codes when they want to.
+ *
+ * Phase 6 slice 6.2 (2026-05-19): accepts an optional `requestId` —
+ * the backend's `x-request-id` response header — and threads it onto
+ * every produced error so consumers can use it as a debugging trace
+ * anchor. Default `null` for backward compat; the transport always
+ * passes it through.
+ */
+declare function fromBackendEnvelope(status: number, envelope: BackendErrorEnvelope | null, requestId?: string | null): DashwiseError;
+
+export { ContractViolationError as C, DependencyContractError as D, ForbiddenError as F, JoinError as J, NetworkError as N, OperationNotAllowedByProviderError as O, ProviderTableMissingError as P, RowNotFoundError as R, TimeoutError as T, UnauthenticatedError as U, ValidationError as V, DashwiseError as a, DashwiseErrorCode as b, fromBackendEnvelope as f };