@dashai/sdk 0.9.0 → 2.0.0

package/dist/index.cjs

@@ -34,23 +34,39 @@ function makeDeps(transport, providerSlug) {
   };
 }
 function makeBorrowedTableClient(transport, providerSlug, tableSlug) {
-  const root = `/deps/${providerSlug}/db/${tableSlug}`;
+  const tablesRoot = `/deps/${providerSlug}/tables/${tableSlug}`;
   return {
     async list(opts) {
-      const body = opts ?? {};
-      const result = await transport.request("POST", `${root}/list`, body);
+      const ast = {
+        v: 1,
+        from: { kind: "dep", module: providerSlug, slug: tableSlug }
+      };
+      if (opts?.filter !== void 0) ast.where = opts.filter;
+      if (opts?.sort !== void 0 && opts.sort.length > 0) {
+        ast.orderBy = opts.sort;
+      }
+      if (typeof opts?.limit === "number") ast.limit = opts.limit;
+      if (typeof opts?.offset === "number") ast.offset = opts.offset;
+      const result = await transport.request("POST", "/query", { ast });
       if (Array.isArray(result)) {
         return {
           rows: result,
           total: result.length,
-          limit: body.limit ?? result.length,
-          offset: body.offset ?? 0
+          limit: opts?.limit ?? result.length,
+          offset: opts?.offset ?? 0
         };
       }
       return result;
     },
     async get(id) {
-      return transport.request("GET", `${root}/${id}`);
+      const result = await transport.request(
+        "GET",
+        `${tablesRoot}/${id}`
+      );
+      if (result && typeof result === "object" && "row" in result) {
+        return result.row;
+      }
+      return result;
     }
   };
 }
@@ -75,6 +91,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
@@ -87,8 +141,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",
@@ -214,6 +268,132 @@ var OperationNotAllowedByProviderError = class extends DashwiseError {
     });
   }
 };
+var DepUnboundReason = {
+  MISSING_DEPENDENCY: "MISSING_DEPENDENCY",
+  DEPENDENCY_VERSION_MISMATCH: "DEPENDENCY_VERSION_MISMATCH",
+  PROVIDER_VERSION_RECORD_MISSING: "PROVIDER_VERSION_RECORD_MISSING",
+  EXPOSES_MISSING: "EXPOSES_MISSING",
+  EXPOSES_PRIVATE: "EXPOSES_PRIVATE",
+  ACTION_NOT_EXPOSED: "ACTION_NOT_EXPOSED",
+  PROVIDER_NOT_PRODUCTION: "PROVIDER_NOT_PRODUCTION",
+  MANUALLY_UNBOUND: "MANUALLY_UNBOUND",
+  PROVIDER_UPGRADE_BROKE_CONTRACT: "PROVIDER_UPGRADE_BROKE_CONTRACT",
+  PROVIDER_UNINSTALLED: "PROVIDER_UNINSTALLED"
+};
+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 UsesUnboundReason = {
+  NOT_BOUND_YET: "NOT_BOUND_YET",
+  AMBIGUOUS_MATCH: "AMBIGUOUS_MATCH",
+  NO_MATCH: "NO_MATCH",
+  TABLE_DELETED: "TABLE_DELETED",
+  OPS_WIDENED_PENDING_CONSENT: "OPS_WIDENED_PENDING_CONSENT",
+  MANUALLY_UNBOUND: "MANUALLY_UNBOUND"
+};
+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 });
@@ -255,9 +435,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:
@@ -292,12 +484,13 @@ var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_SLOW_QUERY_THRESHOLD_MS = 500;
 var TRAILING_SLASH = /\/+$/;
 var LEADING_SLASH = /^\/+/;
-function buildBaseUrl(baseUrl, installationId) {
-  if (!baseUrl) {
-    throw new Error("@dashai/sdk: `baseUrl` is required");
+var MODULE_API_PREFIX = "/api/module-api";
+function buildBaseUrl(apiUrl) {
+  if (!apiUrl) {
+    throw new Error("@dashai/sdk: `apiUrl` is required");
   }
-  const trimmed = baseUrl.replace(TRAILING_SLASH, "");
-  return `${trimmed}/api/modules/${installationId}`;
+  const trimmed = apiUrl.replace(TRAILING_SLASH, "");
+  return `${trimmed}${MODULE_API_PREFIX}`;
 }
 function resolveFetch(custom) {
   if (custom) return custom;
@@ -325,7 +518,7 @@ async function readBody(res) {
   }
 }
 function createHttp(config) {
-  const base = buildBaseUrl(config.baseUrl, config.installationId);
+  const base = buildBaseUrl(config.apiUrl ?? config.baseUrl);
   const doFetch = resolveFetch(config.fetch);
   const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const staticHeaders = {
@@ -344,7 +537,7 @@ function createHttp(config) {
   }
   async function request(method, path, body) {
     const normalizedPath = `/${path.replace(LEADING_SLASH, "")}`;
-    const url = normalizedPath.startsWith("/api/") ? `${config.baseUrl.replace(/\/+$/, "")}${normalizedPath}` : `${base}${normalizedPath}`;
+    const url = `${base}${normalizedPath}`;
     const token = (config.getToken ? await config.getToken() : null) ?? config.apiKey ?? null;
     const headers = { ...staticHeaders };
     if (body !== void 0) {
@@ -539,9 +732,7 @@ function createClient(config) {
     async _callAction(providerSlug, actionName, input, opts) {
       assertValidModuleSlug(providerSlug);
       assertValidActionName(actionName);
-      const path = `/api/modules/runtime/installations/${config.installationId}/deps/${encodeURIComponent(
-        providerSlug
-      )}/actions/${encodeURIComponent(actionName)}`;
+      const path = `/deps/${encodeURIComponent(providerSlug)}/actions/${encodeURIComponent(actionName)}`;
       const body = { input };
       if (opts?.idempotencyKey !== void 0) {
         body.idempotency_key = opts.idempotencyKey;
@@ -600,8 +791,12 @@ function makeDatahubClient(transport) {
       assertValidTableId(tableId);
       const root = `/datahub/tables/${tableId}/rows`;
       return {
-        async list(query) {
-          const qs = query ? new URLSearchParams(query).toString() : "";
+        async list(opts) {
+          const arg = opts;
+          const flat = isDatahubListOpts(
+            arg
+          ) ? compileDatahubListOpts(arg) : arg;
+          const qs = flat ? new URLSearchParams(flat).toString() : "";
           const path = qs ? `${root}?${qs}` : root;
           return transport.request("GET", path);
         },
@@ -638,6 +833,100 @@ function assertValidTableId(tableId) {
     );
   }
 }
+var DATAHUB_LIST_OPT_KEYS = /* @__PURE__ */ new Set([
+  "filter",
+  "sort",
+  "search",
+  "limit",
+  "page"
+]);
+var FILTER_GROUP_KEYS = /* @__PURE__ */ new Set(["AND", "OR"]);
+function isDatahubListOpts(opts) {
+  if (opts === void 0 || opts === null || typeof opts !== "object") {
+    return false;
+  }
+  return Object.keys(opts).some((k) => DATAHUB_LIST_OPT_KEYS.has(k));
+}
+function compileDatahubListOpts(opts) {
+  const out = {};
+  if (opts.filter !== void 0) {
+    const where = opts.filter;
+    if (hasFilterGrouping(where)) {
+      out.filters = JSON.stringify(whereToBackendTree(where));
+    } else {
+      for (const [field, value] of Object.entries(where)) {
+        if (value === void 0) continue;
+        if (isFilterOpsObject(value)) {
+          for (const [op, opValue] of Object.entries(value)) {
+            if (opValue === void 0) continue;
+            out[`filter__${field}__${op}`] = stringifyFilterValue(opValue);
+          }
+        } else {
+          out[`filter__${field}__equal`] = stringifyFilterValue(value);
+        }
+      }
+    }
+  }
+  if (opts.sort !== void 0 && opts.sort.length > 0) {
+    out.order_by = opts.sort.map(
+      (s) => s.dir === "desc" ? `-${s.field}` : s.field
+    ).join(",");
+  }
+  if (opts.search !== void 0) out.search = opts.search;
+  if (typeof opts.limit === "number") out.size = String(opts.limit);
+  if (typeof opts.page === "number") out.page = String(opts.page);
+  if (opts.filter !== void 0 || opts.sort !== void 0 && opts.sort.length > 0) {
+    out.user_field_names = "true";
+  }
+  return out;
+}
+function hasFilterGrouping(where) {
+  return Object.keys(where).some((k) => FILTER_GROUP_KEYS.has(k));
+}
+function isFilterGroupNode(node) {
+  return Object.keys(node).some((k) => FILTER_GROUP_KEYS.has(k));
+}
+function fieldLeaves(node) {
+  const leaves = [];
+  for (const [field, value] of Object.entries(node)) {
+    if (FILTER_GROUP_KEYS.has(field) || value === void 0) continue;
+    if (isFilterOpsObject(value)) {
+      for (const [op, opValue] of Object.entries(value)) {
+        if (opValue === void 0) continue;
+        leaves.push({ field, type: op, value: stringifyFilterValue(opValue) });
+      }
+    } else {
+      leaves.push({ field, type: "equal", value: stringifyFilterValue(value) });
+    }
+  }
+  return leaves;
+}
+function whereToBackendTree(where, defaultType = "AND") {
+  const obj = where;
+  const groupKey = Object.keys(obj).find((k) => FILTER_GROUP_KEYS.has(k));
+  if (groupKey) {
+    const children = obj[groupKey] ?? [];
+    const filters = [];
+    const filter_groups = [];
+    for (const child of children) {
+      const childObj = child;
+      if (isFilterGroupNode(childObj)) {
+        filter_groups.push(whereToBackendTree(child));
+      } else {
+        filters.push(...fieldLeaves(childObj));
+      }
+    }
+    return { filter_type: groupKey, filters, filter_groups };
+  }
+  return { filter_type: defaultType, filters: fieldLeaves(obj), filter_groups: [] };
+}
+function isFilterOpsObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringifyFilterValue(value) {
+  if (value === null) return "";
+  return String(value);
+}
 function makeTableClient(transport, tableSlug) {
   const root = `/db/${tableSlug}`;
   return {
@@ -688,14 +977,12 @@ function createDevClient(overrides = {}) {
     );
   }
   const moduleEntry = overrides.moduleSlug ? fileConfig?.modules?.[overrides.moduleSlug] : void 0;
-  const runtimeToken = readEnv("DASHWISE_RUNTIME_TOKEN") ?? moduleEntry?.runtimeToken ?? null;
-  const installationId = overrides.installationId ?? readEnv("DASHWISE_INSTALLATION_ID") ?? (runtimeToken !== null ? "sandbox" : "local");
-  const snapshotToken = runtimeToken ?? readEnv("DASHWISE_API_KEY") ?? readEnv("DASHWISE_API_TOKEN") ?? fileConfig?.token ?? null;
+  const devModuleToken = moduleEntry?.apiKey ?? moduleEntry?.runtimeToken ?? null;
+  const snapshotToken = devModuleToken ?? readEnv("DASHWISE_API_KEY") ?? fileConfig?.token ?? null;
   const resolvedGetToken = overrides.getToken ?? (() => snapshotToken);
   return createClient({
     ...overrides,
     baseUrl,
-    installationId,
     getToken: resolvedGetToken
   });
 }
@@ -748,11 +1035,14 @@ function isPlausibleFileShape(v) {
 }
 
 // src/index.ts
-var VERSION = "0.9.0" ;
+var VERSION = "2.0.0" ;
 
+exports.ContractFieldMissingError = ContractFieldMissingError;
 exports.ContractViolationError = ContractViolationError;
 exports.DashwiseError = DashwiseError;
 exports.DashwiseErrorCode = DashwiseErrorCode;
+exports.DepUnboundError = DepUnboundError;
+exports.DepUnboundReason = DepUnboundReason;
 exports.DependencyContractError = DependencyContractError;
 exports.ForbiddenError = ForbiddenError;
 exports.JoinError = JoinError;
@@ -762,6 +1052,9 @@ exports.ProviderTableMissingError = ProviderTableMissingError;
 exports.RowNotFoundError = RowNotFoundError;
 exports.TimeoutError = TimeoutError;
 exports.UnauthenticatedError = UnauthenticatedError;
+exports.UsesOpNotAllowedError = UsesOpNotAllowedError;
+exports.UsesUnboundError = UsesUnboundError;
+exports.UsesUnboundReason = UsesUnboundReason;
 exports.VERSION = VERSION;
 exports.ValidationError = ValidationError;
 exports.createClient = createClient;