@wavehouse/sdk 0.0.0-dev.h825a5d7fa405 → 0.0.0-dev.h9539004107f0

package/dist/index.d.cts

@@ -1,7 +1,15 @@
 /** User-provided database schema mapping table names to row types. */
 type Database = Record<string, Record<string, unknown>>;
 /**
- * Discriminated union for all async SDK operations. Never throws.
+ * Discriminated union for the async SDK calls that return one. Never throws for
+ * anything the server returns; a non-absolute `baseURL` and a rejecting `auth`
+ * callback do throw, while a runtime with no `fetch` at all surfaces instead as
+ * a retried `NETWORK_ERROR` result.
+ *
+ * `.stream()` and `.liveQuery()` return no `Result` and report the same three
+ * differently: a non-absolute `baseURL` reaches the subscriber's `error`
+ * callback as a terminal `SSE_CONNECT_ERROR`, a rejecting `auth` as a retryable
+ * `SSE_AUTH_ERROR`, and only a missing `fetch` throws from the call itself.
  *
  * Discriminated on `ok`: `if (result.ok)` narrows to the success arm (and tells
  * the compiler `data` is present), while `error` is always available for
@@ -47,19 +55,162 @@ interface StreamSubscriber<T = Record<string, unknown>> {
     error?: (err: WaveHouseError) => void;
 }
 interface ClientConfig<_DB extends Database = Database> {
-    /** Base URL of the WaveHouse server (e.g. "http://localhost:8080"). */
+    /**
+     * Base URL of the WaveHouse server (e.g. "http://localhost:8080"). May include
+     * a path prefix ("https://app.example.com/api/warehouse") for a WaveHouse
+     * behind a backend-for-frontend (BFF), app-server route, or path-routed
+     * ingress; request paths are appended to it. The proxy in front must strip
+     * the prefix before forwarding.
+     *
+     * Must be **absolute** — scheme and host included. The transports report a
+     * relative value such as "/api/warehouse" differently: a REST call rejects
+     * with a `TypeError` instead of returning a `Result`, while a stream reports
+     * `SSE_CONNECT_ERROR` to the subscriber's `error` callback. Build an absolute
+     * one: `` `${location.origin}/api/warehouse` ``.
+     */
     baseURL: string;
     /** Auth token provider. Omit for public/unauthenticated access. */
     auth?: () => Promise<string> | string;
     /** Additional client options. */
     options?: ClientOptions;
 }
+/**
+ * A `fetch`-compatible function.
+ *
+ * Spelled out rather than written `typeof fetch`, which resolves differently
+ * depending on whether the consumer's TypeScript `lib` includes DOM — the same
+ * signature either way, but stable across configurations.
+ *
+ * The parameter is `string` rather than `typeof fetch`'s wider union because a
+ * string URL is all the SDK ever passes. Since parameters are contravariant,
+ * narrowing it *widens* what can be assigned: the global `fetch` still fits, and
+ * so does hand-written `(url: string, init?: RequestInit) => Promise<Response>`
+ * middleware, which the wider spelling rejects at compile time.
+ *
+ * On REST the SDK reads `.ok` and `.headers` always, `.text()` on success, and
+ * `.status`, `.statusText` plus `.json()` when the response is not `ok`. A
+ * rejection becomes a `NETWORK_ERROR` result and is retried with backoff —
+ * unless the `AbortSignal` you passed has been aborted, in which case the
+ * result is `ABORTED` and nothing is retried. That is decided from the signal
+ * rather than the rejection's type, so an implementation that throws something
+ * other than a `DOMException` named `AbortError` — `AbortSignal.timeout()`,
+ * `node-fetch` — is reported the same way.
+ *
+ * **Streaming needs more.** `.stream()` and `.liveQuery()` read the response as
+ * it arrives, via `.body.getReader()`, so an implementation used with them must
+ * return a response carrying a live `ReadableStream` — something the type cannot
+ * enforce, since `Response.body` is legitimately nullable. A response handed
+ * back with an absent or already-consumed body fails fast with
+ * `SSE_NO_STREAM_BODY`. What the SDK *cannot* rescue is an implementation that
+ * awaits the body before returning — `await res.text()`, or the
+ * `res.clone().text()` a logging wrapper reaches for — because on a stream that
+ * never ends, that never resolves and your function never returns. Both satisfy
+ * every REST call, which is what makes the trap easy to walk into.
+ *
+ * Implementations shipping their own request/response declarations (undici,
+ * `node-fetch`) need casts on the init and the return value, since those types
+ * are separate from the ones behind your global `fetch`; the narrow runtime
+ * contract above is what makes them safe.
+ */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 interface ClientOptions {
     /** Maximum retry attempts for failed requests. Default: 2. */
     maxRetries?: number;
+    /**
+     * HTTP implementation used for every request, REST and streaming alike.
+     * Defaults to the global `fetch`.
+     *
+     * Provide one to route through a proxy, attach client certificates, add
+     * middleware (logging, tracing, circuit breaking), or bypass a transport bug
+     * in the runtime's bundled HTTP stack by routing through an implementation
+     * you install yourself — e.g. an undici new enough to be free of
+     * {@link https://github.com/nodejs/undici/issues/5600 | undici #5600}:
+     *
+     * ```ts
+     * import { Agent, fetch as undiciFetch } from "undici"; // npm install undici — 8.10.0+
+     * // Pass the dispatcher explicitly: undici's pool lives on a shared
+     * // globalThis symbol claimed by whichever copy loaded first, so an implied
+     * // dispatcher can still be the runtime's affected one.
+     * const dispatcher = new Agent();
+     * createClient({
+     *   baseURL,
+     *   options: {
+     *     fetch: (url, init) =>
+     *       undiciFetch(url, { ...init, dispatcher } as never) as unknown as Promise<Response>,
+     *   },
+     * });
+     * ```
+     *
+     * `.stream()` and `.liveQuery()` go through it too, which imposes the extra
+     * streaming requirement described on {@link FetchLike} — read that before
+     * supplying a wrapper that touches the response body.
+     */
+    fetch?: FetchLike;
+    /**
+     * Headers added to every request, REST and streaming alike — for a
+     * header-gated proxy in front of WaveHouse, such as a Cloudflare Access
+     * service token.
+     *
+     * Matched case-insensitively, as HTTP headers are. Applied underneath the
+     * SDK's own headers: `auth` still owns `Authorization`, and the
+     * `Content-Type` and `Accept` a given request needs are not overridable
+     * here — a global `Content-Type` that outranked the request's own is a
+     * documented way to break uploads.
+     *
+     * In a browser these are subject to CORS: a header outside the safelist adds
+     * it to the preflight, which the origin must allow. WaveHouse's own CORS
+     * advertises a fixed set, so custom headers reach it cross-origin only when
+     * a proxy in front terminates the preflight — which is the deployment they
+     * exist for. Server-side callers never preflight.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Extra `RequestInit` fields merged into every request — `credentials` for a
+     * cookie-authenticated origin, `mode`, `cache`, `keepalive`, or a
+     * runtime-specific extension such as Next.js's `next: { tags }`.
+     *
+     * Fields the SDK controls (`method`, `headers`, `body`, `signal`) always
+     * win, so this cannot corrupt the request itself. Non-standard fields may
+     * need a cast, since `RequestInit` only declares the standard ones.
+     *
+     * The streaming transport additionally owns `cache` and `redirect`, where the
+     * values are load-bearing rather than preference: a `Cache-Control` header
+     * would fail cross-origin preflight, and following a redirect would strip the
+     * `Authorization` header on a cross-origin hop and silently downgrade the
+     * stream to the default role instead of failing. So a request carrying an
+     * `auth` token, or configured `headers` that may hold a proxy secret, refuses
+     * redirects (`SSE_REDIRECT`); without either it follows them, so CDN
+     * canonicalization and an http→https upgrade still work. Note the test is
+     * that concrete pair, not "is this authenticated" — **cookies are invisible
+     * to it**. A cookie is re-derived from the cookie store at each hop rather
+     * than carried, so under the default `same-origin` credentials mode a
+     * redirect keeps the stream authenticated only while the hop stays inside
+     * both the request's origin and the cookie's `Path`; a hop outside either
+     * arrives with no cookie and gets a `default_role` view rather than an error.
+     * With `credentials: "include"` the origin half is replaced rather than
+     * lifted: ordinary cookie scoping decides, so the cookie crosses a
+     * CORS-allowed cross-origin hop only if its own `Domain` covers the target —
+     * a host-only cookie, the default, still stops at its host. Spelled out
+     * under "Supplying your own `fetch`" in the SDK guide; see #478.
+     * `credentials` itself is honored in browsers and dropped elsewhere, since
+     * some runtimes throw if it is set.
+     */
+    fetchOptions?: RequestInit;
 }
 interface StructuredQuery {
+    /**
+     * Explicit columns to project. A literal "*" is a column named "*", not a
+     * wildcard. Omitting columns (with no aggregations and no select_all) selects
+     * nothing — use select_all for a full-row read. Mutually exclusive with
+     * select_all.
+     */
     columns?: string[];
+    /**
+     * Request every column the caller's role may read (the all-columns wildcard,
+     * expanded server-side to the allowed/denied set). Mutually exclusive with a
+     * non-empty columns list.
+     */
+    select_all?: boolean;
     aggregations?: Aggregation[];
     filters?: QueryFilter[];
     group_by?: string[];
@@ -97,9 +248,36 @@ interface TableSchema {
     columns: Column[];
 }
 type Schemas = Record<string, TableSchema>;
+/**
+ * A per-record outcome from a batch (array / NDJSON) insert. Mirrors the
+ * single-object response shape plus the record's position. Exactly one of
+ * `ok` / `duplicate` / `error` is set.
+ */
+interface InsertRecordResult {
+    /** 1-based index of the record within the submitted batch. */
+    index: number;
+    /** Set when the record was validated and published. */
+    ok?: boolean;
+    /** Set when dedup skipped the record. */
+    duplicate?: boolean;
+    /** Set (with `ok`/`duplicate` absent) when the record was rejected. */
+    error?: string;
+}
 interface InsertResult {
+    /** True for a fully successful insert: a single row, or a batch with no rejected records (`failed === 0`). */
     ok: boolean;
+    /** Single insert only: set when dedup skipped the row. */
     duplicate?: boolean;
+    /** Batch insert (array / NDJSON): number of records submitted. */
+    total?: number;
+    /** Batch insert: records validated and published. */
+    succeeded?: number;
+    /** Batch insert: records rejected — see `results`. */
+    failed?: number;
+    /** Batch insert: records skipped by dedup. */
+    duplicates?: number;
+    /** Batch insert: per-record outcomes, each `{index, ok|duplicate|error}` (may be truncated for very large batches; the counts stay authoritative). */
+    results?: InsertRecordResult[];
 }
 interface DLQStats {
     tables: Record<string, number>;
@@ -133,8 +311,22 @@ interface RolePermissions {
     check?: Record<string, PolicyFilter>;
     allowed_aggregations?: string[];
     denied_aggregations?: string[];
+    /** Caps the query result LIMIT. 0 = no limit. */
     max_rows?: number;
-    max_execution_time_ms?: number;
+    /**
+     * Max query execution time, enforced server-side by ClickHouse. Set it as a
+     * duration string ("5s", "500ms") or a number of milliseconds; reads always
+     * return the number of milliseconds.
+     */
+    max_execution_time?: number | string;
+    /** Max rows scanned from storage, enforced server-side by ClickHouse. 0 = no limit. */
+    max_rows_to_read?: number;
+    /**
+     * Max peak query memory, enforced server-side by ClickHouse. Set it as a size
+     * string ("4GiB", "512MiB") or a number of bytes; reads always return the
+     * number of bytes.
+     */
+    max_memory_usage?: number | string;
 }
 interface PolicyFilter {
     _eq?: string;
@@ -146,10 +338,32 @@ interface PolicyFilter {
 interface ValidationResult {
     valid: boolean;
 }
-interface FetchOptions {
+/**
+ * Options for a single call, passed to `.fetch()`.
+ *
+ * Note that `await`ing a builder directly (`await wh.from("t").select("*")`)
+ * takes no options — use the explicit `.fetch({ … })` form for those.
+ */
+interface RequestOptions {
     signal?: AbortSignal;
     limit?: number;
 }
+/**
+ * Options for a single `PipeRef.fetch()` call.
+ *
+ * `limit` is declared `never` rather than simply left out. Omitting it would
+ * still admit a `RequestOptions` value that carries one — excess-property
+ * checking only rejects fresh object literals, so a variable would pass and the
+ * limit would be silently dropped, which is the whole defect this prevents.
+ *
+ * A pipe's row cap belongs in its SQL as a `{{limit}}` parameter, supplied via
+ * `wh.pipe(name, { limit })`.
+ */
+interface PipeRequestOptions {
+    signal?: AbortSignal;
+    /** Not supported on pipes — pass `limit` as a pipe parameter instead. */
+    limit?: never;
+}
 interface StreamOptions {
     since?: string;
     signal?: AbortSignal;
@@ -160,6 +374,9 @@ interface HttpContext {
     auth?: () => Promise<string> | string;
     options: {
         maxRetries: number;
+        fetch?: FetchLike;
+        headers?: Record<string, string>;
+        fetchOptions?: RequestInit;
     };
 }
 
@@ -236,8 +453,15 @@ declare class PipeRef<Row = Record<string, unknown>> implements PromiseLike<Resu
     private readonly _params?;
     private readonly _createStream;
     constructor(ctx: HttpContext, name: string, params: Record<string, unknown> | undefined, createStream: CreateStreamFn$2<Row>);
-    /** Execute the pipe and return results. */
-    fetch(opts?: FetchOptions): Promise<Result<Row[]>>;
+    /**
+     * Execute the pipe and return results.
+     *
+     * Takes only `signal` — deliberately narrower than the `RequestOptions` the
+     * query builder accepts. The pipes endpoint binds the body as the pipe's
+     * parameters, so there is no row cap to forward; give the pipe a `{{limit}}`
+     * parameter in its SQL and pass it via `wh.pipe(name, { limit })`.
+     */
+    fetch(opts?: PipeRequestOptions): Promise<Result<Row[]>>;
     /** Subscribe to live events from the pipe's underlying query. */
     stream(opts?: StreamOptions): StreamController<Row>;
     then<TResult1 = Result<Row[]>, TResult2 = never>(onfulfilled?: ((value: Result<Row[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
@@ -339,6 +563,7 @@ declare class LiveQuery<T = Record<string, unknown>> {
 interface QueryState {
     table: string;
     columns: string[];
+    selectAll?: boolean;
     aggregations: Aggregation[];
     filters: QueryFilter[];
     groupBy: string[];
@@ -361,6 +586,13 @@ declare class QueryBuilder<Row = Record<string, unknown>> implements PromiseLike
     private readonly _createStream;
     constructor(ctx: HttpContext, state: QueryState, createStream: CreateStreamFn$1<Row>);
     select(...columns: string[]): QueryBuilder<Row>;
+    /**
+     * Select every column the caller's role is allowed to read (the all-columns
+     * wildcard). Use this instead of `.select(...)` when you want a full-row read;
+     * a bare `.fetch()` with no `.select()` does this implicitly. Mutually
+     * exclusive with `.select(...)`.
+     */
+    selectAll(): QueryBuilder<Row>;
     where(column: string, op: FilterOp, value: unknown): QueryBuilder<Row>;
     count(column?: string, alias?: string): QueryBuilder<Row>;
     sum(column: string, alias?: string): QueryBuilder<Row>;
@@ -374,9 +606,9 @@ declare class QueryBuilder<Row = Record<string, unknown>> implements PromiseLike
     limit(n: number): QueryBuilder<Row>;
     timeRange(column: string, since: string, until?: string): QueryBuilder<Row>;
     cacheTTL(seconds: number): QueryBuilder<Row>;
-    /** Default row limit when none is specified. Matches backend DefaultMaxRows. */
+    /** Default row limit when none is specified — deliberately tighter than the backend's DefaultMaxRows (10000) safety cap. */
     static readonly DEFAULT_LIMIT = 1000;
-    fetch(opts?: FetchOptions): Promise<Result<Row[]>>;
+    fetch(opts?: RequestOptions): Promise<Result<Row[]>>;
     stream(opts?: StreamOptions): StreamController<Row>;
     /**
      * Start a live query: fetches historical data, then streams live updates.
@@ -396,6 +628,12 @@ declare class QueryBuilder<Row = Record<string, unknown>> implements PromiseLike
 }
 
 type CreateStreamFn<Row> = (table: string, opts?: StreamOptions) => StreamController<Row>;
+/**
+ * Accepted sources for {@link TableRef.insertNDJSON}: a string, raw bytes, a
+ * Blob/File (browser file inputs), or a byte stream. Non-string sources are
+ * read fully before sending.
+ */
+type NDJSONSource = string | Uint8Array | Blob | ReadableStream<Uint8Array>;
 /**
  * Reference to a table. NOT thenable — safe to pass around without triggering requests.
  * Use `.fetch()`, `.select()`, `.insert()`, `.schema()`, or `.stream()` to act on it.
@@ -406,13 +644,51 @@ declare class TableRef<Row = Record<string, unknown>> {
     private readonly _createStream;
     constructor(ctx: HttpContext, table: string, createStream: CreateStreamFn<Row>);
     /** SELECT * shortcut — fetches rows with optional pagination. */
-    fetch(opts?: FetchOptions): Promise<Result<Row[]>>;
+    fetch(opts?: RequestOptions): Promise<Result<Row[]>>;
     /** Start building a typed query. Returns an immutable, PromiseLike QueryBuilder. */
     select(...columns: string[]): QueryBuilder<Row>;
-    /** Insert one or more rows into this table. */
+    /**
+     * Start a query that selects every column the caller's role is allowed to read
+     * (the all-columns wildcard). Use instead of `.select(...)` for an explicit
+     * full-row read; `.fetch()` does this implicitly.
+     */
+    selectAll(): QueryBuilder<Row>;
+    /**
+     * Insert one or more rows into this table.
+     *
+     * A single object is sent as a JSON `POST /v1/ingest`. An **array** is
+     * serialized to NDJSON (one record per line) and sent as a single
+     * `application/x-ndjson` request: a bad record no longer fails or hides the
+     * rest of the batch — per-record outcomes come back in the result
+     * (`failed` / `results`), and `ok` is true only when every record succeeded.
+     *
+     * The array path sends one request regardless of size; bounded-concurrency
+     * chunking of very large arrays is tracked separately (#196). For NDJSON you
+     * already have (a file or stream), use {@link insertNDJSON}.
+     */
     insert(data: Partial<Row> | Partial<Row>[], opts?: {
         signal?: AbortSignal;
     }): Promise<Result<InsertResult>>;
+    /**
+     * Insert pre-formatted NDJSON (newline-delimited JSON, one record per line)
+     * from a string, raw bytes, a Blob/File, or a byte stream — e.g. a `.ndjson`
+     * file or a stream produced by another system. For in-memory rows, prefer
+     * {@link insert}.
+     *
+     * Non-string sources are read fully into memory before sending (the server
+     * streams the parse). Returns the same per-record batch summary as an array
+     * `insert`.
+     */
+    insertNDJSON(source: NDJSONSource, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<InsertResult>>;
+    /**
+     * @internal Send an NDJSON body and map the server's batch response onto an
+     * {@link InsertResult}. A transport / whole-request failure surfaces as the
+     * Result error arm; a processed batch (even with rejected records) surfaces
+     * as the success arm with `ok = failed === 0`.
+     */
+    private _sendNDJSON;
     /** Fetch the schema for this table. */
     schema(opts?: {
         signal?: AbortSignal;
@@ -458,4 +734,4 @@ declare class WaveHouseClient<DB extends Database = Database> {
 /** Create a new WaveHouse client instance. */
 declare function createClient<DB extends Database = Database>(config: ClientConfig<DB>): WaveHouseClient<DB>;
 
-export { type Aggregation, type ClientConfig, type ClientOptions, type Column, DLQNamespace, type DLQStats, type Database, type FetchOptions, type FilterOp, type InsertResult, LiveQuery, type OrderClause, type ParamDef, type Pipe, PipeRef, PipesNamespace, type Policy, type PolicyFilter, PolicyNamespace, QueryBuilder, type QueryFilter, type Result, type RolePermissions, SchemaNamespace, type Schemas, StreamController, type StreamEvent, type StreamOptions, type StreamStatus, type StreamSubscriber, type StructuredQuery, SysNamespace, type TablePolicy, TableRef, type TableSchema, type TimeRange, type ValidationResult, WaveHouseClient, type WaveHouseError, createClient };
+export { type Aggregation, type ClientConfig, type ClientOptions, type Column, DLQNamespace, type DLQStats, type Database, type FetchLike, type FilterOp, type InsertRecordResult, type InsertResult, LiveQuery, type NDJSONSource, type OrderClause, type ParamDef, type Pipe, PipeRef, type PipeRequestOptions, PipesNamespace, type Policy, type PolicyFilter, PolicyNamespace, QueryBuilder, type QueryFilter, type RequestOptions, type Result, type RolePermissions, SchemaNamespace, type Schemas, StreamController, type StreamEvent, type StreamOptions, type StreamStatus, type StreamSubscriber, type StructuredQuery, SysNamespace, type TablePolicy, TableRef, type TableSchema, type TimeRange, type ValidationResult, WaveHouseClient, type WaveHouseError, createClient };