@dashai/sdk 0.10.0 → 2.0.0

package/dist/query/index.d.cts

@@ -1,4 +1,4 @@
-import { b as BaseRow, P as Page, W as Where, a as Client } from '../types-BwlzFHbq.cjs';
+import { b as BaseRow, P as Page, W as Where, a as Client } from '../types-CkAfiS4k.cjs';
 
 /**
  * Wire-format Query AST — the JSON shape the SDK serializes and the
@@ -220,7 +220,7 @@ declare const CURRENT_QUERY_AST_VERSION: QueryAstVersion;
 
 /**
  * Typed query builder — fluent API that compiles to a {@link QueryAst}
- * and posts it to `POST /api/modules/<installation>/query`.
+ * and posts it to `POST /api/module-api/query`.
  *
  * Phase 2 slice 1 (this file): the minimum E2E proof — `qb.from(slug).execute()`
  * round-trips through the backend. Future slices extend with
@@ -283,7 +283,7 @@ interface QueryResult {
 }
 /**
  * Result envelope for `.explain()` (Phase 5, 2026-05-19). Returned by
- * `POST /api/modules/:installationId/query/explain`. The backend runs
+ * `POST /api/module-api/query/explain`. The backend runs
  * Postgres `EXPLAIN (FORMAT JSON)` against the SQL it would emit —
  * WITHOUT executing it (no `ANALYZE`, no rows materialized).
  *
@@ -418,7 +418,7 @@ interface Query<Row extends BaseRow = BaseRow> {
     toAst(): QueryAst;
     /**
      * Execute the query. Posts the AST to the backend's
-     * `POST /api/modules/<installation>/query` endpoint and resolves
+     * `POST /api/module-api/query` endpoint and resolves
      * with the standard {@link Page} envelope. Rejects with a
      * {@link DashwiseError} on backend errors (`QUERY_AST_VERSION`,
      * `QUERY_TOO_COMPLEX`, etc.).
@@ -429,7 +429,7 @@ interface Query<Row extends BaseRow = BaseRow> {
      * via Server-Sent Events. Returns an `AsyncIterable<Row>` — use
      * `for await (const row of q.stream())` to consume.
      *
-     * Backend endpoint: `POST /api/modules/<installation>/query/stream`.
+     * Backend endpoint: `POST /api/module-api/query/stream`.
      * Each row arrives as one SSE `data:` event; a terminal `complete`
      * event closes the iterator cleanly. Execution-phase backend
      * errors (RBAC, RESULT_TOO_LARGE, etc.) arrive as in-band `error`
@@ -478,7 +478,7 @@ interface Query<Row extends BaseRow = BaseRow> {
     /**
      * Return the Postgres execution plan for this query — WITHOUT
      * executing it (Phase 5, 2026-05-19). Posts the AST to
-     * `POST /api/modules/<installation>/query/explain`; backend wraps the
+     * `POST /api/module-api/query/explain`; backend wraps the
      * SQL in `EXPLAIN (FORMAT JSON)` and returns the parsed plan tree.
      *
      * **MVP support matrix** (backend slice 5):
@@ -783,7 +783,7 @@ interface AggQuery {
  *   import { createClient } from '@dashai/sdk';
  *   import { makeQb } from '@dashai/sdk/query';
  *
- *   const client = createClient({ baseUrl, installationId, getToken });
+ *   const client = createClient({ baseUrl, apiKey });
  *   const qb = makeQb(client);
  *
  *   const page = await qb.from<TaskRow>('tasks').execute();

package/dist/query/index.d.ts

@@ -1,4 +1,4 @@
-import { b as BaseRow, P as Page, W as Where, a as Client } from '../types-BwlzFHbq.js';
+import { b as BaseRow, P as Page, W as Where, a as Client } from '../types-CkAfiS4k.js';
 
 /**
  * Wire-format Query AST — the JSON shape the SDK serializes and the
@@ -220,7 +220,7 @@ declare const CURRENT_QUERY_AST_VERSION: QueryAstVersion;
 
 /**
  * Typed query builder — fluent API that compiles to a {@link QueryAst}
- * and posts it to `POST /api/modules/<installation>/query`.
+ * and posts it to `POST /api/module-api/query`.
  *
  * Phase 2 slice 1 (this file): the minimum E2E proof — `qb.from(slug).execute()`
  * round-trips through the backend. Future slices extend with
@@ -283,7 +283,7 @@ interface QueryResult {
 }
 /**
  * Result envelope for `.explain()` (Phase 5, 2026-05-19). Returned by
- * `POST /api/modules/:installationId/query/explain`. The backend runs
+ * `POST /api/module-api/query/explain`. The backend runs
  * Postgres `EXPLAIN (FORMAT JSON)` against the SQL it would emit —
  * WITHOUT executing it (no `ANALYZE`, no rows materialized).
  *
@@ -418,7 +418,7 @@ interface Query<Row extends BaseRow = BaseRow> {
     toAst(): QueryAst;
     /**
      * Execute the query. Posts the AST to the backend's
-     * `POST /api/modules/<installation>/query` endpoint and resolves
+     * `POST /api/module-api/query` endpoint and resolves
      * with the standard {@link Page} envelope. Rejects with a
      * {@link DashwiseError} on backend errors (`QUERY_AST_VERSION`,
      * `QUERY_TOO_COMPLEX`, etc.).
@@ -429,7 +429,7 @@ interface Query<Row extends BaseRow = BaseRow> {
      * via Server-Sent Events. Returns an `AsyncIterable<Row>` — use
      * `for await (const row of q.stream())` to consume.
      *
-     * Backend endpoint: `POST /api/modules/<installation>/query/stream`.
+     * Backend endpoint: `POST /api/module-api/query/stream`.
      * Each row arrives as one SSE `data:` event; a terminal `complete`
      * event closes the iterator cleanly. Execution-phase backend
      * errors (RBAC, RESULT_TOO_LARGE, etc.) arrive as in-band `error`
@@ -478,7 +478,7 @@ interface Query<Row extends BaseRow = BaseRow> {
     /**
      * Return the Postgres execution plan for this query — WITHOUT
      * executing it (Phase 5, 2026-05-19). Posts the AST to
-     * `POST /api/modules/<installation>/query/explain`; backend wraps the
+     * `POST /api/module-api/query/explain`; backend wraps the
      * SQL in `EXPLAIN (FORMAT JSON)` and returns the parsed plan tree.
      *
      * **MVP support matrix** (backend slice 5):
@@ -783,7 +783,7 @@ interface AggQuery {
  *   import { createClient } from '@dashai/sdk';
  *   import { makeQb } from '@dashai/sdk/query';
  *
- *   const client = createClient({ baseUrl, installationId, getToken });
+ *   const client = createClient({ baseUrl, apiKey });
  *   const qb = makeQb(client);
  *
  *   const page = await qb.from<TaskRow>('tasks').execute();

package/dist/query/index.js

@@ -16,6 +16,44 @@ var DashwiseErrorCode = {
   TABLE_NOT_IN_CONTRACT: "TABLE_NOT_IN_CONTRACT",
   PROVIDER_TABLE_MISSING: "PROVIDER_TABLE_MISSING",
   OPERATION_NOT_ALLOWED_BY_PROVIDER: "OPERATION_NOT_ALLOWED_BY_PROVIDER",
+  // Cross-module dependency PARK state (Phase 3 modules-platform-v2 —
+  // dependency connect/bind lifecycle). Surfaced at RUNTIME (409) when a
+  // module reads a borrowed table (`client.deps(slug)` / `qb.deps.<slug>`)
+  // or invokes a dep action whose `module_dependencies` row is currently
+  // `status='unbound'` — the dependency is declared but not connected to a
+  // provider installation (no provider in the workspace, version mismatch,
+  // manually unbound, provider uninstalled, etc.). The consumer app should
+  // render a "connect your provider" state rather than treating this as a
+  // hard failure. `err.context` carries `{ provider, range, reason }`.
+  DEP_UNBOUND: "DEP_UNBOUND",
+  // Workspace-table `uses` plane (Phase 4 modules-platform-v2 — the
+  // declared/portable path for a module to read+write a WORKSPACE table
+  // the workspace already owns, as opposed to `deps` = another module's
+  // tables). Surfaced at RUNTIME against `client.uses(slug)` /
+  // `qb.uses.<slug>` / the `POST /api/module-api/uses/:slug/...` REST
+  // plane. The BINDING is the grant on this plane (for sandbox AND
+  // api_key auth alike — a kind-local key does NOT bypass it):
+  //   - USES_UNBOUND         409 — the `uses` slot is declared but its
+  //     `module_table_bindings` row isn't `status='bound'` (never bound,
+  //     ambiguous match, no match, table trashed, ops widened pending
+  //     re-consent, manually unbound). `err.context` carries
+  //     `{ uses_slug, reason }`. Recoverable: a workspace admin binds a
+  //     table (`dashwise bind <uses_slug>`), then the read succeeds.
+  //   - USES_OP_NOT_ALLOWED  403 — the operation isn't in the binding's
+  //     enforcement set (manifest `ops` ∩ `consented_ops`). `err.context`
+  //     carries `{ uses_slug, op }`. Fix: widen the manifest ops +
+  //     re-consent (re-bind), or the admin re-binds to consent.
+  //   - CONTRACT_FIELD_MISSING 409 — a field the binding maps no longer
+  //     exists on the physical table (schema drift). `err.context`
+  //     carries `{ uses_slug, field }`. The binding is best-effort parked
+  //     on detection; an admin re-binds to a table that has the field.
+  USES_UNBOUND: "USES_UNBOUND",
+  USES_OP_NOT_ALLOWED: "USES_OP_NOT_ALLOWED",
+  CONTRACT_FIELD_MISSING: "CONTRACT_FIELD_MISSING",
+  // `uses`-plane query joins are NOT supported in v1 — a
+  // `qb.uses.<slug>.join(...)` / cross-plane join is rejected with a
+  // typed 400. (Joins WITH a uses table as a target are v2 territory.)
+  USES_JOIN_UNSUPPORTED: "USES_JOIN_UNSUPPORTED",
   // Query-plane joins (Phase 3 — see
   // dashwise-devops-docs/plans/modules-sdk-query-v1-p3-execution.md).
   // Surfaced when `.join('<slug>')` / `.leftJoin('<slug>')` can't
@@ -28,8 +66,8 @@ var DashwiseErrorCode = {
   // Cross-module actions (Phase 7 slice 7.3a — see
   // dashwise-devops-docs/plans/modules-sdk-query-v1-p7-cross-module-writes.md).
   // Surfaced when `qb.deps.<dep>.actions.<name>(input)` (generated
-  // factory) dispatches against the new backend endpoint
-  // `POST :installationId/deps/:providerSlug/actions/:actionName`.
+  // factory) dispatches against the backend endpoint
+  // `POST /api/module-api/deps/:providerSlug/actions/:actionName`.
   // Slice 7.2b ships the backend emitter; slice 7.3a (this slice)
   // reserves the codes + maps them to DepActionError in the SDK.
   ACTION_NOT_EXPOSED: "ACTION_NOT_EXPOSED",
@@ -133,6 +171,112 @@ var OperationNotAllowedByProviderError = class extends DashwiseError {
     });
   }
 };
+var DepUnboundError = class extends DashwiseError {
+  constructor(message, context, requestId = null) {
+    super(DashwiseErrorCode.DEP_UNBOUND, message, {
+      status: 409,
+      context,
+      requestId
+    });
+  }
+  /**
+   * 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() {
+    const v = this.context?.provider;
+    return typeof v === "string" ? v : void 0;
+  }
+  /**
+   * 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() {
+    const v = this.context?.range;
+    return typeof v === "string" ? v : void 0;
+  }
+  /**
+   * 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() {
+    const v = this.context?.reason;
+    return typeof v === "string" ? v : void 0;
+  }
+};
+var UsesUnboundError = class extends DashwiseError {
+  constructor(message, context, requestId = null) {
+    super(DashwiseErrorCode.USES_UNBOUND, message, {
+      status: 409,
+      context,
+      requestId
+    });
+  }
+  /**
+   * 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() {
+    const v = this.context?.uses_slug;
+    return typeof v === "string" ? v : void 0;
+  }
+  /**
+   * 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() {
+    const v = this.context?.reason;
+    return typeof v === "string" ? v : void 0;
+  }
+};
+var UsesOpNotAllowedError = class extends DashwiseError {
+  constructor(message, context, requestId = null) {
+    super(DashwiseErrorCode.USES_OP_NOT_ALLOWED, message, {
+      status: 403,
+      context,
+      requestId
+    });
+  }
+  /** The `uses` slot slug the rejected op targeted. Read from `context.uses_slug`. */
+  get usesSlug() {
+    const v = this.context?.uses_slug;
+    return typeof v === "string" ? v : void 0;
+  }
+  /**
+   * The operation that was rejected — one of `create` / `read` /
+   * `update` / `delete`. Read from `context.op`; `undefined` if omitted.
+   */
+  get op() {
+    const v = this.context?.op;
+    return typeof v === "string" ? v : void 0;
+  }
+};
+var ContractFieldMissingError = class extends DashwiseError {
+  constructor(message, context, requestId = null) {
+    super(DashwiseErrorCode.CONTRACT_FIELD_MISSING, message, {
+      status: 409,
+      context,
+      requestId
+    });
+  }
+  /** The `uses` slot slug whose contract broke. Read from `context.uses_slug`. */
+  get usesSlug() {
+    const v = this.context?.uses_slug;
+    return typeof v === "string" ? v : void 0;
+  }
+  /**
+   * The declared field slug (the `uses` side name) whose mapped physical
+   * field is gone. Read from `context.field`; `undefined` if omitted.
+   */
+  get field() {
+    const v = this.context?.field;
+    return typeof v === "string" ? v : void 0;
+  }
+};
 var JoinError = class extends DashwiseError {
   constructor(code, message, context, requestId = null) {
     super(code, message, { status: 400, context, requestId });
@@ -174,9 +318,21 @@ function fromBackendEnvelope(status, envelope, requestId = null) {
       return new ProviderTableMissingError(message, context, requestId);
     case DashwiseErrorCode.OPERATION_NOT_ALLOWED_BY_PROVIDER:
       return new OperationNotAllowedByProviderError(message, context, requestId);
+    case DashwiseErrorCode.DEP_UNBOUND:
+      return new DepUnboundError(message, context, requestId);
+    case DashwiseErrorCode.USES_UNBOUND:
+      return new UsesUnboundError(message, context, requestId);
+    case DashwiseErrorCode.USES_OP_NOT_ALLOWED:
+      return new UsesOpNotAllowedError(message, context, requestId);
+    case DashwiseErrorCode.CONTRACT_FIELD_MISSING:
+      return new ContractFieldMissingError(message, context, requestId);
     case DashwiseErrorCode.LINK_FIELD_NOT_FOUND:
     case DashwiseErrorCode.NOT_A_LINK_FIELD:
     case DashwiseErrorCode.JOIN_NOT_LINKED:
+    // `uses`-plane joins are unsupported in v1; the backend emits a 400
+    // with this code. Map to JoinError so it lands in the same
+    // "your join can't be resolved" family (code preserved for `err.code`).
+    case DashwiseErrorCode.USES_JOIN_UNSUPPORTED:
       return new JoinError(code, message, context, requestId);
     case DashwiseErrorCode.ACTION_NOT_EXPOSED:
     case DashwiseErrorCode.ACTION_NOT_DECLARED: