@dashai/sdk 0.7.0

package/dist/query/index.cjs

@@ -0,0 +1,621 @@
+'use strict';
+
+// src/data/errors.ts
+var DashwiseErrorCode = {
+  // Auth / authz
+  UNAUTHENTICATED: "UNAUTHENTICATED",
+  FORBIDDEN: "FORBIDDEN",
+  TOKEN_EXPIRED: "TOKEN_EXPIRED",
+  // Contract enforcement
+  CONTRACT_VIOLATION: "CONTRACT_VIOLATION",
+  FIELD_NOT_READABLE: "FIELD_NOT_READABLE",
+  FILTER_OP_UNKNOWN: "FILTER_OP_UNKNOWN",
+  OPERATION_NOT_ALLOWED: "OPERATION_NOT_ALLOWED",
+  // Cross-module dependencies (Phase 1 of the SDK query plane —
+  // see dashwise-devops-docs/plans/modules-sdk-query-v1.md).
+  // Surfaced when reading borrowed tables via `client.deps(slug)`.
+  DEPENDENCY_NOT_DECLARED: "DEPENDENCY_NOT_DECLARED",
+  TABLE_NOT_IN_CONTRACT: "TABLE_NOT_IN_CONTRACT",
+  PROVIDER_TABLE_MISSING: "PROVIDER_TABLE_MISSING",
+  OPERATION_NOT_ALLOWED_BY_PROVIDER: "OPERATION_NOT_ALLOWED_BY_PROVIDER",
+  // 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
+  // resolve the target. Pre-declared in slice 3.1 so slice 3.2's
+  // backend translator can emit them through fromBackendEnvelope
+  // without an SDK roundtrip.
+  LINK_FIELD_NOT_FOUND: "LINK_FIELD_NOT_FOUND",
+  NOT_A_LINK_FIELD: "NOT_A_LINK_FIELD",
+  JOIN_NOT_LINKED: "JOIN_NOT_LINKED",
+  // 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`.
+  // 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",
+  ACTION_NOT_DECLARED: "ACTION_NOT_DECLARED",
+  ACTION_INPUT_INVALID: "ACTION_INPUT_INVALID",
+  ACTION_OUTPUT_INVALID: "ACTION_OUTPUT_INVALID",
+  ACTION_RATE_LIMITED: "ACTION_RATE_LIMITED",
+  ACTION_EXECUTION_FAILED: "ACTION_EXECUTION_FAILED",
+  // Data plane
+  ROW_NOT_FOUND: "ROW_NOT_FOUND",
+  VALIDATION_FAILED: "VALIDATION_FAILED",
+  // Server
+  INTERNAL_ERROR: "INTERNAL_ERROR"
+};
+var DashwiseError = class extends Error {
+  code;
+  status;
+  retriable;
+  context;
+  /**
+   * 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.).
+   */
+  requestId;
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.status = options.status ?? 0;
+    this.retriable = options.retriable ?? false;
+    this.context = options.context;
+    this.requestId = options.requestId ?? null;
+    if (options.cause !== void 0) {
+      this.cause = options.cause;
+    }
+  }
+};
+var UnauthenticatedError = class extends DashwiseError {
+  constructor(message = "Authentication required", requestId = null) {
+    super(DashwiseErrorCode.UNAUTHENTICATED, message, { status: 401, requestId });
+  }
+};
+var ForbiddenError = class extends DashwiseError {
+  constructor(message, context, requestId = null) {
+    super(DashwiseErrorCode.FORBIDDEN, message, { status: 403, context, requestId });
+  }
+};
+var RowNotFoundError = class extends DashwiseError {
+  constructor(message, context, requestId = null) {
+    super(DashwiseErrorCode.ROW_NOT_FOUND, message, { status: 404, context, requestId });
+  }
+};
+var ContractViolationError = class extends DashwiseError {
+  constructor(message, context, requestId = null) {
+    super(DashwiseErrorCode.CONTRACT_VIOLATION, message, {
+      status: 403,
+      context,
+      requestId
+    });
+  }
+};
+var ValidationError = class extends DashwiseError {
+  constructor(message, context, requestId = null) {
+    super(DashwiseErrorCode.VALIDATION_FAILED, message, {
+      status: 400,
+      context,
+      requestId
+    });
+  }
+};
+var DependencyContractError = class extends DashwiseError {
+  constructor(code, message, context, requestId = null) {
+    super(code, message, { status: 404, context, requestId });
+  }
+};
+var ProviderTableMissingError = class extends DashwiseError {
+  constructor(message, context, requestId = null) {
+    super(DashwiseErrorCode.PROVIDER_TABLE_MISSING, message, {
+      status: 404,
+      context,
+      requestId
+    });
+  }
+};
+var OperationNotAllowedByProviderError = class extends DashwiseError {
+  constructor(message, context, requestId = null) {
+    super(DashwiseErrorCode.OPERATION_NOT_ALLOWED_BY_PROVIDER, message, {
+      status: 403,
+      context,
+      requestId
+    });
+  }
+};
+var JoinError = class extends DashwiseError {
+  constructor(code, message, context, requestId = null) {
+    super(code, message, { status: 400, context, requestId });
+  }
+};
+var DepActionError = class extends DashwiseError {
+  constructor(code, message, status, context, requestId = null) {
+    super(code, message, {
+      status,
+      retriable: code === DashwiseErrorCode.ACTION_RATE_LIMITED,
+      context,
+      requestId
+    });
+  }
+};
+function fromBackendEnvelope(status, envelope, requestId = null) {
+  const code = envelope?.code ?? codeFromStatus(status);
+  const message = envelope?.message ?? `HTTP ${status}`;
+  const context = envelope?.context;
+  switch (code) {
+    case DashwiseErrorCode.UNAUTHENTICATED:
+    case DashwiseErrorCode.TOKEN_EXPIRED:
+      return new UnauthenticatedError(message, requestId);
+    case DashwiseErrorCode.FORBIDDEN:
+      return new ForbiddenError(message, context, requestId);
+    case DashwiseErrorCode.ROW_NOT_FOUND:
+      return new RowNotFoundError(message, context, requestId);
+    case DashwiseErrorCode.CONTRACT_VIOLATION:
+    case DashwiseErrorCode.FIELD_NOT_READABLE:
+    case DashwiseErrorCode.FILTER_OP_UNKNOWN:
+    case DashwiseErrorCode.OPERATION_NOT_ALLOWED:
+      return new ContractViolationError(message, context, requestId);
+    case DashwiseErrorCode.VALIDATION_FAILED:
+      return new ValidationError(message, context, requestId);
+    case DashwiseErrorCode.DEPENDENCY_NOT_DECLARED:
+    case DashwiseErrorCode.TABLE_NOT_IN_CONTRACT:
+      return new DependencyContractError(code, message, context, requestId);
+    case DashwiseErrorCode.PROVIDER_TABLE_MISSING:
+      return new ProviderTableMissingError(message, context, requestId);
+    case DashwiseErrorCode.OPERATION_NOT_ALLOWED_BY_PROVIDER:
+      return new OperationNotAllowedByProviderError(message, context, requestId);
+    case DashwiseErrorCode.LINK_FIELD_NOT_FOUND:
+    case DashwiseErrorCode.NOT_A_LINK_FIELD:
+    case DashwiseErrorCode.JOIN_NOT_LINKED:
+      return new JoinError(code, message, context, requestId);
+    case DashwiseErrorCode.ACTION_NOT_EXPOSED:
+    case DashwiseErrorCode.ACTION_NOT_DECLARED:
+      return new DepActionError(code, message, 403, context, requestId);
+    case DashwiseErrorCode.ACTION_INPUT_INVALID:
+      return new DepActionError(code, message, 400, context, requestId);
+    case DashwiseErrorCode.ACTION_OUTPUT_INVALID:
+      return new DepActionError(code, message, 500, context, requestId);
+    case DashwiseErrorCode.ACTION_RATE_LIMITED:
+      return new DepActionError(code, message, 429, context, requestId);
+    case DashwiseErrorCode.ACTION_EXECUTION_FAILED:
+      return new DepActionError(code, message, 200, context, requestId);
+    default:
+      return new DashwiseError(code, message, {
+        status,
+        retriable: envelope?.retriable ?? false,
+        context,
+        requestId
+      });
+  }
+}
+function codeFromStatus(status) {
+  if (status === 401) return DashwiseErrorCode.UNAUTHENTICATED;
+  if (status === 403) return DashwiseErrorCode.FORBIDDEN;
+  if (status === 404) return DashwiseErrorCode.ROW_NOT_FOUND;
+  if (status >= 500) return DashwiseErrorCode.INTERNAL_ERROR;
+  return "HTTP_ERROR";
+}
+
+// src/query/ast.ts
+function isQueryAst(v) {
+  if (!v || typeof v !== "object") return false;
+  const a = v;
+  if (a.v !== 1) return false;
+  if (!a.from || typeof a.from !== "object") return false;
+  const f = a.from;
+  if (typeof f.kind !== "string") return false;
+  if (f.kind === "owned" || f.kind === "view") {
+    return typeof f.slug === "string";
+  }
+  if (f.kind === "dep") {
+    return typeof f.module === "string" && typeof f.slug === "string";
+  }
+  return false;
+}
+var CURRENT_QUERY_AST_VERSION = 1;
+
+// src/query/builder.ts
+var TABLE_SLUG_REGEX = /^[a-z][a-z0-9_]*[a-z0-9]$/;
+var MODULE_SLUG_REGEX = /^[a-z][a-z0-9-]*[a-z0-9]$/;
+function assertValidTableSlug(slug) {
+  if (typeof slug !== "string" || !TABLE_SLUG_REGEX.test(slug)) {
+    throw new Error(
+      `@dashai/sdk/query: invalid table slug "${slug}". Slugs must match /^[a-z][a-z0-9_]*[a-z0-9]$/ (snake_case).`
+    );
+  }
+}
+function assertValidModuleSlug(slug) {
+  if (typeof slug !== "string" || !MODULE_SLUG_REGEX.test(slug)) {
+    throw new Error(
+      `@dashai/sdk/query: invalid module slug "${slug}". Module slugs must match /^[a-z][a-z0-9-]*[a-z0-9]$/ (kebab-case).`
+    );
+  }
+}
+function makeQb(client) {
+  return {
+    // Single runtime function backs all three overloads — TypeScript
+    // narrows at the call site, but at runtime we discriminate on the
+    // input shape:
+    //   string                 → own-table slug
+    //   { kind: 'dep', ... }   → cross-module dep ref (slice 4.1b)
+    //   { kind: 'view', slug } → view ref (slice 5.4b)
+    from(target) {
+      let ref;
+      if (typeof target === "string") {
+        assertValidTableSlug(target);
+        ref = { kind: "owned", slug: target };
+      } else if (target && typeof target === "object" && target.kind === "dep") {
+        assertValidModuleSlug(target.module);
+        assertValidTableSlug(target.slug);
+        ref = { kind: "dep", module: target.module, slug: target.slug };
+      } else if (target && typeof target === "object" && target.kind === "view") {
+        assertValidTableSlug(target.slug);
+        ref = { kind: "view", slug: target.slug };
+      } else {
+        throw new Error(
+          `@dashai/sdk/query: qb.from() expects a string table slug, { kind: 'dep', module, slug }, or { kind: 'view', slug }; got ${JSON.stringify(target)}.`
+        );
+      }
+      const ast = {
+        v: CURRENT_QUERY_AST_VERSION,
+        from: ref
+      };
+      return makeQuery(client, ast);
+    }
+  };
+}
+async function postExplain(client, ast) {
+  return client.request("POST", "/query/explain", { ast });
+}
+async function* streamRowsViaSSE(client, ast, signal) {
+  const res = await client.streamRaw("POST", "/query/stream", { ast }, signal);
+  const requestId = res.headers.get("x-request-id");
+  if (!res.ok) {
+    const envelope = await readErrorEnvelope(res);
+    throw fromBackendEnvelope(res.status, envelope, requestId);
+  }
+  const reader = res.body?.getReader();
+  if (!reader) {
+    throw new Error(
+      "@dashai/sdk/query: streaming response has no readable body \u2014 backend bug or misconfigured fetch impl."
+    );
+  }
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        if (buffer.trim().length > 0) {
+          const last = parseSseBlock(buffer);
+          if (last && last.event === "message") {
+            yield last.data;
+          }
+        }
+        return;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      const parts = buffer.split("\n\n");
+      buffer = parts.pop() ?? "";
+      for (const block of parts) {
+        if (!block.trim()) continue;
+        const parsed = parseSseBlock(block);
+        if (!parsed) continue;
+        if (parsed.event === "message") {
+          yield parsed.data;
+        } else if (parsed.event === "complete") {
+          return;
+        } else if (parsed.event === "error") {
+          const err = parsed.data;
+          throw fromBackendEnvelope(
+            500,
+            { code: err.code, message: err.message },
+            requestId
+          );
+        }
+      }
+    }
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+    }
+  }
+}
+function parseSseBlock(block) {
+  const trimmed = block.trim();
+  if (trimmed.length === 0) return null;
+  let event = "message";
+  const dataLines = [];
+  for (const line of trimmed.split("\n")) {
+    if (line.startsWith("event:")) {
+      event = line.slice(6).trim();
+    } else if (line.startsWith("data:")) {
+      const v = line.slice(5);
+      dataLines.push(v.startsWith(" ") ? v.slice(1) : v);
+    }
+  }
+  if (dataLines.length === 0) return null;
+  const joined = dataLines.join("\n");
+  let data;
+  try {
+    data = JSON.parse(joined);
+  } catch {
+    data = joined;
+  }
+  return { event, data };
+}
+async function readErrorEnvelope(res) {
+  try {
+    const parsed = await res.json();
+    if (parsed && typeof parsed === "object") {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function makeQuery(client, ast) {
+  const fork = (patch) => makeQuery(client, { ...ast, ...patch });
+  return {
+    toAst() {
+      return JSON.parse(JSON.stringify(ast));
+    },
+    where(clause) {
+      return fork({ where: clause });
+    },
+    orderBy(clauses) {
+      return fork({ orderBy: [...clauses] });
+    },
+    limit(n) {
+      if (!Number.isInteger(n) || n < 1) {
+        throw new Error(
+          `@dashai/sdk/query: .limit(${n}) must be a positive integer.`
+        );
+      }
+      return fork({ limit: n });
+    },
+    offset(n) {
+      if (!Number.isInteger(n) || n < 0) {
+        throw new Error(
+          `@dashai/sdk/query: .offset(${n}) must be a non-negative integer.`
+        );
+      }
+      return fork({ offset: n });
+    },
+    select(fields) {
+      return fork({ select: [...fields] });
+    },
+    async count() {
+      const minimalAst = {
+        ...ast,
+        limit: ast.limit ?? 1
+      };
+      const result = await client.request(
+        "POST",
+        "/query",
+        { ast: minimalAst }
+      );
+      if (Array.isArray(result)) {
+        return result.length;
+      }
+      return result.total;
+    },
+    async execute() {
+      const result = await client.request(
+        "POST",
+        "/query",
+        { ast }
+      );
+      if (Array.isArray(result)) {
+        return {
+          rows: result,
+          total: result.length,
+          limit: ast.limit ?? result.length,
+          offset: ast.offset ?? 0
+        };
+      }
+      return result;
+    },
+    async explain() {
+      return postExplain(client, ast);
+    },
+    stream(opts) {
+      return streamRowsViaSSE(client, ast, opts?.signal);
+    },
+    groupBy(fields) {
+      return makeAggQuery(client, { ...ast, groupBy: [...fields] });
+    },
+    agg(expressions) {
+      return makeAggQuery(client, { ...ast, agg: expressions });
+    },
+    // ── Join entries (Phase 3 slice 3.3) ──────────────────────────
+    //
+    // .join() / .leftJoin() transition to JoinedQuery whose surface
+    // omits write methods + the aggregation suite. The SDK delegates
+    // shape validation to the backend's AST validator + the
+    // join-translator; today's slice 3.2b-1 cap means combinations
+    // with where/orderBy/limit/offset/agg backend-reject with clear
+    // "lands in slice X" errors.
+    join(target, opts) {
+      return makeJoinedQuery(client, {
+        ...ast,
+        joins: [...ast.joins ?? [], buildJoinNode(target, opts, "inner")]
+      });
+    },
+    leftJoin(target, opts) {
+      return makeJoinedQuery(client, {
+        ...ast,
+        joins: [...ast.joins ?? [], buildJoinNode(target, opts, "left")]
+      });
+    }
+  };
+}
+function makeJoinedQuery(client, ast) {
+  const fork = (patch) => makeJoinedQuery(client, { ...ast, ...patch });
+  return {
+    toAst() {
+      return JSON.parse(JSON.stringify(ast));
+    },
+    where(clause) {
+      return fork({ where: clause });
+    },
+    orderBy(clauses) {
+      return fork({ orderBy: [...clauses] });
+    },
+    limit(n) {
+      if (!Number.isInteger(n) || n < 1) {
+        throw new Error(
+          `@dashai/sdk/query: .limit(${n}) must be a positive integer.`
+        );
+      }
+      return fork({ limit: n });
+    },
+    offset(n) {
+      if (!Number.isInteger(n) || n < 0) {
+        throw new Error(
+          `@dashai/sdk/query: .offset(${n}) must be a non-negative integer.`
+        );
+      }
+      return fork({ offset: n });
+    },
+    join(target, opts) {
+      return makeJoinedQuery(client, {
+        ...ast,
+        joins: [...ast.joins ?? [], buildJoinNode(target, opts, "inner")]
+      });
+    },
+    leftJoin(target, opts) {
+      return makeJoinedQuery(client, {
+        ...ast,
+        joins: [...ast.joins ?? [], buildJoinNode(target, opts, "left")]
+      });
+    },
+    flatten() {
+      return makeJoinedQuery(client, {
+        ...ast,
+        flatten: true
+      });
+    },
+    async execute() {
+      const result = await client.request(
+        "POST",
+        "/query",
+        { ast }
+      );
+      if (Array.isArray(result)) {
+        return {
+          rows: result,
+          total: result.length,
+          limit: ast.limit ?? result.length,
+          offset: ast.offset ?? 0
+        };
+      }
+      return result;
+    },
+    async explain() {
+      return postExplain(client, ast);
+    },
+    stream(opts) {
+      return streamRowsViaSSE(client, ast, opts?.signal);
+    }
+  };
+}
+function buildJoinNode(target, opts, defaultKind) {
+  let to;
+  let displaySlug;
+  if (typeof target === "string") {
+    assertValidTableSlug(target);
+    to = { kind: "owned", slug: target };
+    displaySlug = target;
+  } else if (target && typeof target === "object" && target.kind === "dep") {
+    assertValidModuleSlug(target.module);
+    assertValidTableSlug(target.slug);
+    to = { kind: "dep", module: target.module, slug: target.slug };
+    displaySlug = `${target.module}:${target.slug}`;
+  } else {
+    throw new Error(
+      `@dashai/sdk/query: .join() target must be a table slug string or { kind: 'dep', module, slug }; got ${JSON.stringify(target)}.`
+    );
+  }
+  if (!opts.on || Object.keys(opts.on).length === 0) {
+    throw new Error(
+      `@dashai/sdk/query: .join('${displaySlug}') requires an \`on\` clause with at least one field pair. Link-field-derived \`on\` inference lands in a follow-up slice.`
+    );
+  }
+  return {
+    kind: opts.kind ?? defaultKind,
+    to,
+    on: opts.on,
+    ...opts.as !== void 0 ? { as: opts.as } : {}
+  };
+}
+function makeAggQuery(client, ast) {
+  const fork = (patch) => makeAggQuery(client, { ...ast, ...patch });
+  return {
+    toAst() {
+      return JSON.parse(JSON.stringify(ast));
+    },
+    where(clause) {
+      return fork({ where: clause });
+    },
+    groupBy(fields) {
+      return fork({ groupBy: [...fields] });
+    },
+    agg(expressions) {
+      return fork({ agg: expressions });
+    },
+    limit(n) {
+      if (!Number.isInteger(n) || n < 1) {
+        throw new Error(
+          `@dashai/sdk/query: .limit(${n}) must be a positive integer.`
+        );
+      }
+      return fork({ limit: n });
+    },
+    offset(n) {
+      if (!Number.isInteger(n) || n < 0) {
+        throw new Error(
+          `@dashai/sdk/query: .offset(${n}) must be a non-negative integer.`
+        );
+      }
+      return fork({ offset: n });
+    },
+    async execute() {
+      const result = await client.request(
+        "POST",
+        "/query",
+        { ast }
+      );
+      if (Array.isArray(result)) {
+        return {
+          rows: result,
+          total: result.length
+        };
+      }
+      return result;
+    },
+    async explain() {
+      return postExplain(client, ast);
+    }
+  };
+}
+
+exports.CURRENT_QUERY_AST_VERSION = CURRENT_QUERY_AST_VERSION;
+exports.isQueryAst = isQueryAst;
+exports.makeQb = makeQb;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map