@dashai/sdk 0.10.0 → 2.0.0

package/dist/index-BsSFz58g.d.ts

@@ -0,0 +1,431 @@
+/**
+ * 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 DEP_UNBOUND: "DEP_UNBOUND";
+    readonly USES_UNBOUND: "USES_UNBOUND";
+    readonly USES_OP_NOT_ALLOWED: "USES_OP_NOT_ALLOWED";
+    readonly CONTRACT_FIELD_MISSING: "CONTRACT_FIELD_MISSING";
+    readonly USES_JOIN_UNSUPPORTED: "USES_JOIN_UNSUPPORTED";
+    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);
+}
+/**
+ * The vocabulary of `unbound_reason` values a parked dependency can
+ * carry, surfaced in {@link DepUnboundError.reason}. Mirrors the
+ * backend's `module_dependencies.unbound_reason` enum (Phase 3
+ * modules-platform-v2). Not exhaustive by design — treat `.reason` as a
+ * string and branch on these constants when you want compile-time
+ * safety. Adding a new reason is a non-breaking change.
+ *
+ * Resolve/bind-time reasons (why the dep never bound):
+ *   - `MISSING_DEPENDENCY`            no install of the provider module in the workspace
+ *   - `DEPENDENCY_VERSION_MISMATCH`   an install exists but its version is outside the declared range
+ *   - `PROVIDER_VERSION_RECORD_MISSING` the provider's version row is gone (data-integrity edge)
+ *   - `EXPOSES_MISSING`               the provider no longer exposes a table/field the dep reads
+ *   - `EXPOSES_PRIVATE`               the exposed surface is `private` to the consumer
+ *   - `ACTION_NOT_EXPOSED`            a declared dep action isn't exposed by the provider (Rule #11)
+ *   - `PROVIDER_NOT_PRODUCTION`       kind hygiene: a production consumer can only bind a production provider
+ *
+ * Lifecycle reasons (the dep bound once, then got parked):
+ *   - `MANUALLY_UNBOUND`              a workspace admin ran `deps unbind` / the unbind endpoint
+ *   - `PROVIDER_UPGRADE_BROKE_CONTRACT` a provider upgrade (with `force`) broke this consumer's contract
+ *   - `PROVIDER_UNINSTALLED`          the provider was uninstalled with `park_consumers`
+ */
+declare const DepUnboundReason: {
+    readonly MISSING_DEPENDENCY: "MISSING_DEPENDENCY";
+    readonly DEPENDENCY_VERSION_MISMATCH: "DEPENDENCY_VERSION_MISMATCH";
+    readonly PROVIDER_VERSION_RECORD_MISSING: "PROVIDER_VERSION_RECORD_MISSING";
+    readonly EXPOSES_MISSING: "EXPOSES_MISSING";
+    readonly EXPOSES_PRIVATE: "EXPOSES_PRIVATE";
+    readonly ACTION_NOT_EXPOSED: "ACTION_NOT_EXPOSED";
+    readonly PROVIDER_NOT_PRODUCTION: "PROVIDER_NOT_PRODUCTION";
+    readonly MANUALLY_UNBOUND: "MANUALLY_UNBOUND";
+    readonly PROVIDER_UPGRADE_BROKE_CONTRACT: "PROVIDER_UPGRADE_BROKE_CONTRACT";
+    readonly PROVIDER_UNINSTALLED: "PROVIDER_UNINSTALLED";
+};
+type DepUnboundReason = (typeof DepUnboundReason)[keyof typeof DepUnboundReason];
+/**
+ * 409 — a runtime read (borrowed-table `list` / `get`, query-plane
+ * `qb.deps.<slug>.<table>`, or a cross-module action) targeted a
+ * dependency whose `module_dependencies` row is `status='unbound'`
+ * (Phase 3 modules-platform-v2 dependency connect lifecycle).
+ *
+ * "Unbound" means the dependency is *declared* in the consumer's
+ * manifest but not *connected* to a provider installation. It happens
+ * when the resolver PARKED the dep at install/apply time (no provider
+ * in the workspace, version mismatch, exposes/action coverage gap) or
+ * when the dependency was later parked (manually unbound, provider
+ * upgrade broke the contract, provider uninstalled).
+ *
+ * This is a *recoverable* state, not a bug in the consumer. Catch it and
+ * render a "connect your provider" prompt — a workspace admin resolves it
+ * by installing/binding the provider (`dashwise deps bind <slug>` or the
+ * `POST /api/installations/:id/dependencies/:providerSlug/bind` endpoint).
+ * Once bound, the same read succeeds with no code change.
+ *
+ * Convenience accessors ({@link DepUnboundError.provider},
+ * {@link DepUnboundError.range}, {@link DepUnboundError.reason}) read the
+ * backend's `context: { provider, range, reason }` so callers don't have
+ * to reach into `err.context` by hand.
+ *
+ * @example
+ * ```ts
+ * import { DepUnboundError } from '@dashai/sdk';
+ *
+ * try {
+ *   const contacts = await client.deps('crm').db<ContactRow>('contacts').list();
+ *   // …or the typed builder: await qb.deps.crm.contacts.execute();
+ * } catch (err) {
+ *   if (err instanceof DepUnboundError) {
+ *     // Declared but not connected — show a connect-your-provider CTA.
+ *     return <ConnectProvider provider={err.provider} range={err.range} reason={err.reason} />;
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+declare class DepUnboundError extends DashwiseError {
+    constructor(message: string, context?: Record<string, unknown>, requestId?: string | null);
+    /**
+     * The provider module slug the parked dependency points at (kebab-case,
+     * e.g. `crm`). Read from `context.provider`; `undefined` if the backend
+     * omitted it.
+     */
+    get provider(): string | undefined;
+    /**
+     * The SemVer range the consumer's manifest declared for this dependency
+     * (e.g. `^1.2.0`). Read from `context.range`; `undefined` if omitted.
+     */
+    get range(): string | undefined;
+    /**
+     * Why the dependency is unbound — one of {@link DepUnboundReason} (but
+     * typed as `string` for forward-compat with reasons the backend may add).
+     * Read from `context.reason`; `undefined` if omitted.
+     */
+    get reason(): string | undefined;
+}
+/**
+ * The vocabulary of `reason` values a parked `uses` binding can carry,
+ * surfaced in {@link UsesUnboundError.reason}. Mirrors the backend's
+ * `module_table_bindings` unbound_reason enum for this plane
+ * (Phase 4 modules-platform-v2). Not exhaustive by design — treat
+ * `.reason` as a string; branch on these constants for compile-time
+ * safety. Adding a new reason is non-breaking.
+ *
+ *   - `NOT_BOUND_YET`                the slot has never been bound (declared
+ *                                    but no workspace table connected yet)
+ *   - `AMBIGUOUS_MATCH`             auto-match found >1 candidate table; a
+ *                                    human must pick one (`dashwise bind`)
+ *   - `NO_MATCH`                     auto-match found no candidate table
+ *   - `TABLE_DELETED`               the bound table was trashed (or a mapped
+ *                                    field drifted away) → the row parked
+ *   - `OPS_WIDENED_PENDING_CONSENT` the manifest widened `ops` beyond what
+ *                                    was consented at bind time; re-bind to
+ *                                    refresh consent
+ *   - `MANUALLY_UNBOUND`            a workspace admin ran `dashwise unbind`
+ */
+declare const UsesUnboundReason: {
+    readonly NOT_BOUND_YET: "NOT_BOUND_YET";
+    readonly AMBIGUOUS_MATCH: "AMBIGUOUS_MATCH";
+    readonly NO_MATCH: "NO_MATCH";
+    readonly TABLE_DELETED: "TABLE_DELETED";
+    readonly OPS_WIDENED_PENDING_CONSENT: "OPS_WIDENED_PENDING_CONSENT";
+    readonly MANUALLY_UNBOUND: "MANUALLY_UNBOUND";
+};
+type UsesUnboundReason = (typeof UsesUnboundReason)[keyof typeof UsesUnboundReason];
+/**
+ * 409 — a runtime read/write against a `uses` table whose
+ * `module_table_bindings` row is not `status='bound'` (Phase 4
+ * modules-platform-v2 workspace-table binding lifecycle).
+ *
+ * "Unbound" means the workspace-table slot is *declared* in the module's
+ * manifest `uses` block but not *connected* to a physical workspace
+ * table. It happens when install-time auto-match parked the slot (no
+ * candidate / ambiguous candidates / a write contract that never
+ * auto-binds), the bound table was later trashed, the manifest widened
+ * `ops` beyond consent, or an admin manually unbound it.
+ *
+ * A *recoverable* state, not a bug. Catch it and render a "connect a
+ * table" prompt — a workspace admin resolves it by binding a workspace
+ * table to the slot (`dashwise bind <uses_slug>` / the
+ * `PUT /api/installations/:id/bindings/:usesSlug` endpoint). Once bound,
+ * the same call succeeds with no code change.
+ *
+ * Convenience accessors read the backend's `context: { uses_slug, reason }`.
+ *
+ * @example
+ * ```ts
+ * import { UsesUnboundError } from '@dashai/sdk';
+ *
+ * try {
+ *   const staff = await client.uses('employees').db<EmployeeRow>('employees').list();
+ *   // …or the typed builder: await qb.uses.employees.execute();
+ * } catch (err) {
+ *   if (err instanceof UsesUnboundError) {
+ *     return <BindWorkspaceTable slot={err.usesSlug} reason={err.reason} />;
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+declare class UsesUnboundError extends DashwiseError {
+    constructor(message: string, context?: Record<string, unknown>, requestId?: string | null);
+    /**
+     * The manifest `uses[].tables[].slug` of the unbound slot (kebab-case,
+     * e.g. `employees`). Read from `context.uses_slug`; `undefined` if the
+     * backend omitted it.
+     */
+    get usesSlug(): string | undefined;
+    /**
+     * Why the slot is unbound — one of {@link UsesUnboundReason} (typed as
+     * `string` for forward-compat with reasons the backend may add). Read
+     * from `context.reason`; `undefined` if omitted.
+     */
+    get reason(): string | undefined;
+}
+/**
+ * 403 — a `uses`-plane operation that isn't in the binding's enforced
+ * operation set (the manifest's declared `ops` INTERSECT the admin's
+ * `consented_ops` at bind time). E.g. the manifest declares
+ * `ops: ['read','update']` but the admin consented only to `read` when
+ * binding, so an `update` is rejected.
+ *
+ * Fix: either narrow the call to a consented op, or widen the manifest
+ * `ops` + have an admin re-bind (which refreshes `consented_ops`).
+ *
+ * `err.op` / `err.usesSlug` read the backend's `context: { uses_slug, op }`.
+ */
+declare class UsesOpNotAllowedError extends DashwiseError {
+    constructor(message: string, context?: Record<string, unknown>, requestId?: string | null);
+    /** The `uses` slot slug the rejected op targeted. Read from `context.uses_slug`. */
+    get usesSlug(): string | undefined;
+    /**
+     * The operation that was rejected — one of `create` / `read` /
+     * `update` / `delete`. Read from `context.op`; `undefined` if omitted.
+     */
+    get op(): string | undefined;
+}
+/**
+ * 409 — a field the `uses` binding's `field_map` points at no longer
+ * exists on the physical workspace table (schema drift: the table owner
+ * deleted or renamed the column after the bind). The backend best-effort
+ * parks the binding (reason `TABLE_DELETED`/field-drift) on detection.
+ *
+ * Recovery is the workspace admin's: re-bind the slot to a table that
+ * still has the field, or re-map the field (`dashwise bind <uses_slug>
+ * --map <usesField>=<physicalField>`).
+ *
+ * `err.field` / `err.usesSlug` read the backend's
+ * `context: { uses_slug, field }`.
+ */
+declare class ContractFieldMissingError extends DashwiseError {
+    constructor(message: string, context?: Record<string, unknown>, requestId?: string | null);
+    /** The `uses` slot slug whose contract broke. Read from `context.uses_slug`. */
+    get usesSlug(): string | undefined;
+    /**
+     * The declared field slug (the `uses` side name) whose mapped physical
+     * field is gone. Read from `context.field`; `undefined` if omitted.
+     */
+    get field(): string | undefined;
+}
+/**
+ * 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 { ContractFieldMissingError as C, DepUnboundError 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, DepUnboundReason as a, DependencyContractError as b, ContractViolationError as c, DashwiseError as d, DashwiseErrorCode as e, UsesOpNotAllowedError as f, UsesUnboundError as g, UsesUnboundReason as h, fromBackendEnvelope as i };