@dashai/sdk 0.7.0

package/dist/types-BLNQ1S1C.d.cts

@@ -0,0 +1,396 @@
+/**
+ * Public types for the @dashai/sdk data plane.
+ *
+ * These types are the contract between:
+ *   - the runtime HTTP client in this package
+ *   - the per-module generated typed wrappers (see `dashwise module generate`)
+ *   - hand-authored / custom modules that import the SDK directly
+ *
+ * Anything in this file is part of the package's SemVer-stable surface.
+ * Breaking changes require a major version bump.
+ */
+/**
+ * The two columns every DashWise row carries regardless of manifest
+ * configuration: an auto-incrementing primary key + a fractional `order`
+ * string for stable user-defined sort orders.
+ *
+ * Per-module generated row types extend this shape with their
+ * manifest-declared fields.
+ */
+interface BaseRow {
+    id: number;
+    order: string;
+}
+/**
+ * Shape passed to `db.<table>.create()`. The generated typed layer
+ * intersects this with the per-table required-vs-optional field map.
+ */
+type BaseInsert = Record<string, unknown>;
+/** Shape passed to `db.<table>.update()`. Always a `Partial` of insert. */
+type BaseUpdate = Record<string, unknown>;
+/**
+ * Reference to a file stored in DashWise's blob store. Returned in row
+ * payloads for `file` / `multi_file` field types. Mutation goes through
+ * a separate upload endpoint (out of scope for v0.1).
+ */
+interface FileRef {
+    id: number;
+    name: string;
+    mime: string;
+    size: number;
+}
+/**
+ * Filter operators for a `Where<Row>` clause. Each key maps 1:1 to a
+ * backend filter type (see `RowQueryService`'s filter registry in
+ * `dashwise-backend`). Multiple ops on the same field are AND'd
+ * (`{ count: { higher_than: 5, lower_than: 100 } }` →
+ * `count > 5 AND count < 100`). Unknown keys are rejected by the backend
+ * with `FILTER_OP_UNKNOWN`.
+ *
+ * Per-field-type narrowing (e.g. rejecting `contains` on a number field)
+ * is M5+ polish — for now every operator is typed as optional on every
+ * field, and the backend returns a typed 400 if a runtime mismatch happens.
+ */
+interface FilterOps {
+    equal?: unknown;
+    not_equal?: unknown;
+    contains?: string;
+    not_contains?: string;
+    empty?: true;
+    not_empty?: true;
+    higher_than?: number;
+    lower_than?: number;
+    date_equal?: string;
+    date_before?: string;
+    date_after?: string;
+    boolean?: boolean;
+}
+/**
+ * Per-field filter value: either a bare primitive (shorthand for
+ * `{ equal: ... }`) or a `FilterOps` operator object.
+ */
+type FilterValue<V> = V | FilterOps;
+/**
+ * Recursive filter clause for `db.<table>.list()`. Top-level keys are
+ * AND'd together. Use `AND` / `OR` arrays for explicit logical grouping;
+ * nest as deeply as needed (server caps at depth 10).
+ *
+ * @example
+ *   { done: false, title: { contains: 'urgent' } }
+ *   // → WHERE done = false AND title ILIKE '%urgent%'
+ *
+ * @example
+ *   { OR: [{ done: true }, { archived: true }] }
+ *   // → WHERE done = true OR archived = true
+ */
+type Where<Row> = {
+    [K in keyof Row]?: FilterValue<Row[K]>;
+} & {
+    AND?: Where<Row>[];
+    OR?: Where<Row>[];
+};
+type SortDir = 'asc' | 'desc';
+interface SortClause<Row> {
+    field: keyof Row & string;
+    dir: SortDir;
+}
+/**
+ * Options accepted by `db.<table>.list()`. All fields are optional;
+ * server defaults: `limit=50`, no filter, no sort.
+ */
+interface ListOpts<Row> {
+    filter?: Where<Row>;
+    sort?: SortClause<Row>[];
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Paginated response from `db.<table>.list()`. Today the generated typed
+ * layer unwraps this to a bare array for ergonomics; consumers who need
+ * pagination metadata should use the raw client or wait for M5+ when
+ * `.list()` returns the full `Page<Row>`.
+ */
+interface Page<Row> {
+    rows: Row[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * The chainable surface returned by `client.db<Row>('table-slug')`. This
+ * is the generic / untyped face of the data plane — the generated layer
+ * binds the table slug + row type and re-exports a typed wrapper.
+ */
+interface TableClient<Row extends BaseRow, Insert extends BaseInsert = BaseInsert, Update extends BaseUpdate = BaseUpdate> {
+    /** List rows matching `opts.filter`; paginated. */
+    list(opts?: ListOpts<Row>): Promise<Page<Row>>;
+    /** Fetch a single row by primary key. Rejects with `ROW_NOT_FOUND` if absent. */
+    get(id: number): Promise<Row>;
+    /** Insert a row; returns the persisted row including server-assigned id + order. */
+    create(body: Insert): Promise<Row>;
+    /** Partially update a row by id; returns the updated row. */
+    update(id: number, patch: Update): Promise<Row>;
+    /** Soft-delete a row by id; resolves with `void` on success. */
+    delete(id: number): Promise<void>;
+}
+/**
+ * The chainable surface returned by `client.deps('provider').db<Row>('table-slug')`.
+ *
+ * Same `list` + `get` shape as the full {@link TableClient}, but
+ * deliberately omits write operations: cross-module writes flow
+ * through the provider module's published actions (Phase 7+), NOT
+ * through direct INSERT/UPDATE/DELETE. Surfaced as a distinct
+ * interface so the type system enforces the no-cross-module-writes
+ * invariant — `(client.deps('crm').db('contacts') as any).create(...)`
+ * is the only way to bypass it, which is exactly the cost we want.
+ *
+ * See `dashwise-devops-docs/plans/modules-sdk-query-v1.md` §4.3 for
+ * the trust-model rationale.
+ */
+interface ReadOnlyTableClient<Row extends BaseRow> {
+    /** List rows from the provider's table, projected to the consumer's contract. */
+    list(opts?: ListOpts<Row>): Promise<Page<Row>>;
+    /** Fetch a single row by primary key, projected to the consumer's contract. */
+    get(id: number): Promise<Row>;
+}
+/**
+ * Borrowed-table accessor returned by {@link Client.deps}.
+ *
+ * Mirrors `client.db()` shape but the inner `db()` returns a
+ * read-only {@link ReadOnlyTableClient}. The `providerSlug` argument
+ * passed to `client.deps('provider')` must match a `dependencies[]`
+ * entry in the caller's `module.json`; mismatches surface as
+ * `DependencyContractError` on the first call.
+ */
+interface Deps {
+    /**
+     * Return a read-only table client for `tableSlug` exposed by the
+     * provider this {@link Deps} was bound to. The table must be listed
+     * in the caller's `dependencies[].reads[]` block AND the provider's
+     * `exposes[]` block; backend re-validates on every call.
+     */
+    db<Row extends BaseRow>(tableSlug: string): ReadOnlyTableClient<Row>;
+}
+/**
+ * Token resolver. Called once per request. Return `null` for unauthenticated
+ * (the backend will reject most calls); return a JWT or CLI token otherwise.
+ *
+ * Sync or async — the client awaits the result.
+ */
+type TokenResolver = () => string | null | Promise<string | null>;
+/**
+ * Optional fetch implementation override. Defaults to `globalThis.fetch`.
+ * Useful for testing (inject a mock) or for runtimes that need a custom
+ * agent (Node.js + corporate proxy). MUST match the standard `fetch`
+ * signature.
+ */
+type FetchImpl = typeof globalThis.fetch;
+/**
+ * Config passed to `createClient()`.
+ */
+interface ClientConfig {
+    /**
+     * Base URL of the DashWise API. No trailing slash; the client will
+     * append `/api/...` paths. Example: `https://api.dashwise.io`.
+     */
+    baseUrl: string;
+    /**
+     * Token resolver. Called once per request, before the HTTP call.
+     * Resolved tokens are attached as `Authorization: Bearer <token>`.
+     */
+    getToken?: TokenResolver;
+    /**
+     * Installation ID this client is scoped to. Required for module
+     * runtime calls. Typical values:
+     *   - a numeric `module_installations.id` for production modules
+     *   - `'sandbox'` for AI builder draft loops (no installation row yet)
+     *   - `'local'` for `dashwise module dev` against a dev token
+     *
+     * Accepts any string-shaped id (or number) so consumers can pass
+     * `process.env.DASHWISE_INSTALLATION_ID` directly without coercion.
+     * The value is interpolated into the URL path as-is.
+     */
+    installationId: number | string;
+    /**
+     * Optional `fetch` override. Defaults to `globalThis.fetch`. Set this
+     * for tests or runtimes that need a custom HTTP agent.
+     */
+    fetch?: FetchImpl;
+    /**
+     * Optional request timeout in milliseconds. Each call wires up an
+     * `AbortController` that fires at this timeout. Defaults to 30_000.
+     */
+    timeoutMs?: number;
+    /**
+     * Optional custom headers added to every request. Useful for tracing
+     * (`X-Request-Id`, `traceparent`) when integrating with observability
+     * pipelines.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Phase 6 slice 6.3 (2026-05-19): per-call slow-query notification.
+     * When set, the transport invokes this callback after EVERY request
+     * whose round-trip wall time exceeds `slowQueryThresholdMs`. The
+     * callback fires on both success AND error paths so observability
+     * stays consistent.
+     *
+     * Fired synchronously after the response is parsed but BEFORE the
+     * caller's `await` resolves/rejects. Don't do heavy work here —
+     * push to an in-memory queue or telemetry SDK and return quickly.
+     * Errors thrown from the callback are caught + swallowed (a buggy
+     * observability hook must not crash the query path).
+     *
+     * Measures **round-trip** time (just before `fetch()` to just after
+     * the response body is parsed). This includes network + server-side
+     * processing. The backend's `module_query_log.duration_ms` captures
+     * server-side processing only — useful for "is this slow because
+     * of the server or the network?" diagnosis when you cross-reference.
+     *
+     * @example
+     *   const client = createClient({
+     *     baseUrl, installationId,
+     *     slowQueryThresholdMs: 500,
+     *     onSlowQuery: (info) => {
+     *       sentry.captureMessage('Slow query', { extra: info });
+     *     },
+     *   });
+     */
+    onSlowQuery?: (info: SlowQueryInfo) => void;
+    /**
+     * Threshold in milliseconds at which `onSlowQuery` fires. Defaults
+     * to 500ms (matches the backend's partial `module_query_log` slow
+     * index for symmetry — same threshold, same row both server-side +
+     * client-side observability look at). Ignored when `onSlowQuery`
+     * is not set.
+     */
+    slowQueryThresholdMs?: number;
+}
+/**
+ * Phase 6 slice 6.3 (2026-05-19): payload passed to the
+ * {@link ClientConfig.onSlowQuery} callback.
+ *
+ * Carries enough context for an observability sink to log a useful
+ * message + correlate with the backend's `module_query_log` row via
+ * `requestId`. `path` is the SDK-shaped path (relative to the
+ * installation-scoped base URL — e.g. `/query` or `/db/tasks/list`);
+ * combine with the URL the client is configured against if you want
+ * the full URL.
+ *
+ * `success` distinguishes "completed normally but slow" from "failed
+ * AND was slow" — sentry / DataDog typically want to separate these.
+ */
+interface SlowQueryInfo {
+    method: string;
+    path: string;
+    /** Round-trip wall time from `fetch()` call to response body parsed. */
+    durationMs: number;
+    /** HTTP response status code. 0 for transport failures (NetworkError / TimeoutError). */
+    status: number;
+    /** Whether the request succeeded (2xx) or failed (non-2xx or transport error). */
+    success: boolean;
+    /**
+     * Backend trace anchor (echo of the `x-request-id` response header).
+     * Same value the matching {@link DashwiseError}'s `requestId` carries
+     * on error paths. Null when the endpoint doesn't echo the header
+     * yet, or when the failure was client-side (network / timeout).
+     */
+    requestId: string | null;
+}
+/**
+ * The public client returned by `createClient()`. Holds the configured
+ * transport + exposes a `db<Row>(slug)` factory for table clients plus
+ * a low-level `request` escape hatch for endpoints outside the
+ * `db.<table>` CRUD shape (cross-module deps, custom RPC, etc.).
+ *
+ * Thread-safe — the same client can be reused across concurrent requests.
+ */
+interface Client {
+    /** Returns a table client bound to the given table slug + row type. */
+    db<Row extends BaseRow, Insert extends BaseInsert = BaseInsert, Update extends BaseUpdate = BaseUpdate>(tableSlug: string): TableClient<Row, Insert, Update>;
+    /**
+     * Returns a borrowed-table accessor scoped to `providerSlug`. The
+     * `providerSlug` must be the **module slug** (kebab-case, matches
+     * the manifest's `MODULE_SLUG_REGEX`) of a module listed in the
+     * caller's `module.json#dependencies[]`. Calls hit
+     * `POST /api/modules/:installation/deps/:providerSlug/db/:tableSlug/list`
+     * and friends; backend enforces field projection + operation gating
+     * against the declared contract.
+     *
+     * Cross-module access is **read-only** in v1 (the inner `db()` returns
+     * a {@link ReadOnlyTableClient}); writes flow through provider-published
+     * actions in a future phase.
+     *
+     * @example
+     *   const contacts = await client
+     *     .deps('crm')
+     *     .db<ContactRow>('contacts')
+     *     .list({ filter: { company: { equal: 'acme' } } });
+     */
+    deps(providerSlug: string): Deps;
+    /**
+     * Low-level HTTP request escape hatch. Useful for endpoints that
+     * don't match the `db.<table>` CRUD shape — most notably any future
+     * custom RPC endpoints a module exposes.
+     *
+     * The path is appended to the configured installation-scoped base
+     * URL (`<baseUrl>/api/modules/<installationId>`). Token attachment,
+     * timeout, error mapping, and 204 handling all behave identically to
+     * the typed CRUD methods.
+     *
+     * For cross-module reads, prefer `client.deps(providerSlug).db(...)`
+     * — it carries typed errors + the no-write enforcement.
+     */
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+    /**
+     * Phase 6 streaming (2026-05-19): low-level streaming entry that
+     * returns the unparsed `Response`. Used by `qb.from(...).stream()`
+     * to consume the backend's SSE endpoint chunk-by-chunk. Most
+     * consumers should use `.stream()` on the builder rather than
+     * calling this directly — the builder handles SSE parsing + maps
+     * errors to typed `DashwiseError`. `streamRaw` is exposed so
+     * advanced users (custom transports, non-SDK streaming endpoints,
+     * tests) can build on top.
+     *
+     * Differs from `request()`:
+     *   - Returns the raw `Response` regardless of HTTP status (caller
+     *     handles non-2xx + parses the error envelope from the body).
+     *   - Optional `signal` parameter for caller-side cancellation.
+     *     Combined with the transport's own timeout — either trigger
+     *     cancels the fetch.
+     *   - Timeout applies ONLY to the headers-arrival phase. The body
+     *     stream can take arbitrarily long; the stream reader's
+     *     backpressure handles the long tail.
+     */
+    streamRaw(method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<Response>;
+    /**
+     * Phase 7 slice 7.3a (2026-05-20): cross-module action dispatch
+     * helper. Internal — invoked by the codegen-emitted
+     * `qb.deps.<dep>.actions.<name>(input)` factories. Underscore-
+     * prefixed to signal "not for direct use; run `dashwise module
+     * generate` to get the typed surface."
+     *
+     * The factory pattern:
+     * ```ts
+     * // Generated:
+     * export const actions = {
+     *   archiveContact: (input: {...}): Promise<{...}> =>
+     *     client._callAction('crm', 'archiveContact', input),
+     * };
+     * ```
+     *
+     * Sends `POST :installationId/deps/:providerSlug/actions/:actionName`,
+     * unwraps the envelope on success (returns `result`), throws
+     * `DepActionError` on dispatch-layer failure or on action-body
+     * failure (envelope `ok: false`). Drift between codegen + runtime
+     * (provider added/removed an action) surfaces as
+     * `ACTION_NOT_EXPOSED` / `ACTION_NOT_DECLARED`.
+     *
+     * Spec: dashwise-devops-docs/plans/modules-sdk-query-v1-p7-cross-module-writes.md §5.1.
+     */
+    _callAction<TOutput = unknown>(providerSlug: string, actionName: string, input: unknown, opts?: {
+        timeoutMs?: number;
+        idempotencyKey?: string;
+    }): Promise<TOutput>;
+}
+
+export type { BaseInsert as B, ClientConfig as C, Deps as D, FetchImpl as F, ListOpts as L, Page as P, ReadOnlyTableClient as R, SlowQueryInfo as S, TokenResolver as T, Where as W, Client as a, BaseRow as b, BaseUpdate as c, FileRef as d, FilterOps as e, FilterValue as f, SortClause as g, SortDir as h, TableClient as i };