@wavehouse/sdk 0.0.0-dev.0f8826c

package/dist/index.d.ts

@@ -0,0 +1,461 @@
+/** 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 on `ok`: `if (result.ok)` narrows to the success arm (and tells
+ * the compiler `data` is present), while `error` is always available for
+ * debugging on failure. `data`/`error` remain populated as before.
+ */
+type Result<T> = {
+    ok: true;
+    data: T;
+    error: null;
+    hasMore?: boolean;
+    next?: () => Promise<Result<T>>;
+} | {
+    ok: false;
+    data: null;
+    error: WaveHouseError;
+    hasMore?: false;
+    next?: undefined;
+};
+/** Structured error returned by all SDK operations. */
+interface WaveHouseError {
+    status: number;
+    code: string;
+    message: string;
+    details?: unknown;
+    retryable: boolean;
+}
+/** SDK filter operators (translated to backend equivalents). */
+type FilterOp = "=" | "!=" | ">" | ">=" | "<" | "<=" | "in" | "like" | "not_like";
+type StreamStatus = "connecting" | "live" | "reconnecting" | "closed";
+interface StreamEvent<T = Record<string, unknown>> {
+    table: string;
+    timestamp: string;
+    data: T;
+}
+interface StreamSubscriber<T = Record<string, unknown>> {
+    /** Called once with historical backfill data. */
+    initial?: (result: Result<T[]>) => void;
+    /** Called for each live event. */
+    next: (event: StreamEvent<T>) => void;
+    /** Called when stream connection status changes. */
+    status?: (state: StreamStatus) => void;
+    /** Called on stream errors. */
+    error?: (err: WaveHouseError) => void;
+}
+interface ClientConfig<_DB extends Database = Database> {
+    /** Base URL of the WaveHouse server (e.g. "http://localhost:8080"). */
+    baseURL: string;
+    /** Auth token provider. Omit for public/unauthenticated access. */
+    auth?: () => Promise<string> | string;
+    /** Additional client options. */
+    options?: ClientOptions;
+}
+interface ClientOptions {
+    /** Maximum retry attempts for failed requests. Default: 2. */
+    maxRetries?: number;
+}
+interface StructuredQuery {
+    columns?: string[];
+    aggregations?: Aggregation[];
+    filters?: QueryFilter[];
+    group_by?: string[];
+    order_by?: OrderClause[];
+    limit?: number;
+    time_range?: TimeRange;
+}
+interface Aggregation {
+    fn: string;
+    column: string;
+    alias: string;
+}
+interface QueryFilter {
+    column: string;
+    op: string;
+    value: unknown;
+}
+interface OrderClause {
+    column: string;
+    dir: "asc" | "desc";
+}
+interface TimeRange {
+    column: string;
+    since: string;
+    until?: string;
+}
+interface Column {
+    name: string;
+    type: string;
+    is_nullable: boolean;
+    has_default: boolean;
+}
+interface TableSchema {
+    name: string;
+    columns: Column[];
+}
+type Schemas = Record<string, TableSchema>;
+interface InsertResult {
+    ok: boolean;
+    duplicate?: boolean;
+}
+interface DLQStats {
+    tables: Record<string, number>;
+    total: number;
+}
+interface Pipe {
+    name: string;
+    sql: string;
+    parameters?: ParamDef[];
+    description?: string;
+    allowed_roles?: string[];
+}
+interface ParamDef {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+}
+interface Policy {
+    default_role?: string;
+    tables: Record<string, TablePolicy>;
+}
+interface TablePolicy {
+    select?: Record<string, RolePermissions>;
+    insert?: Record<string, RolePermissions>;
+}
+interface RolePermissions {
+    allow_columns?: string[];
+    deny_columns?: string[];
+    filter?: Record<string, PolicyFilter>;
+    check?: Record<string, PolicyFilter>;
+    allowed_aggregations?: string[];
+    denied_aggregations?: string[];
+    max_rows?: number;
+    max_execution_time_ms?: number;
+}
+interface PolicyFilter {
+    _eq?: string;
+    _neq?: string;
+    _gt?: string;
+    _lt?: string;
+    _in?: string;
+}
+interface ValidationResult {
+    valid: boolean;
+}
+interface FetchOptions {
+    signal?: AbortSignal;
+    limit?: number;
+}
+interface StreamOptions {
+    since?: string;
+    signal?: AbortSignal;
+}
+/** @internal */
+interface HttpContext {
+    baseURL: string;
+    auth?: () => Promise<string> | string;
+    options: {
+        maxRetries: number;
+    };
+}
+
+/** @internal Transport abstraction for SSE backend. */
+interface StreamTransport<T = Record<string, unknown>> {
+    connect(): void;
+    disconnect(): void;
+    onEvent: ((event: StreamEvent<T>) => void) | null;
+    onStatus: ((status: StreamStatus) => void) | null;
+    onError: ((error: WaveHouseError) => void) | null;
+}
+/**
+ * Controls a live event stream. NOT thenable.
+ * Use `.subscribe()` for callback-based consumption or `for await` for async iteration.
+ */
+declare class StreamController<T = Record<string, unknown>> {
+    private _transport;
+    private _subscribers;
+    private _status;
+    private _buffer;
+    private _waiters;
+    private _done;
+    constructor(transport: StreamTransport<T>);
+    /** Current connection status. */
+    get status(): StreamStatus;
+    /**
+     * Returns a promise that resolves when the stream status reaches `'live'`,
+     * rejects immediately if the stream is already `'closed'`, or rejects after
+     * `timeoutMs` milliseconds (default: 5 000) if it never connects.
+     *
+     * Safe to call before `.subscribe()` — does not trigger auto-close when
+     * the internal waiter is removed.
+     *
+     * `@example`
+     * const stream = client.from('events').stream();
+     * const unsub = stream.subscribe({ next: (e) => console.log(e) });
+     * await stream.connected();   // waits until the transport is live
+     * await client.from('events').insert({ ... });
+     */
+    connected(timeoutMs?: number): Promise<void>;
+    /** Subscribe to stream events via callbacks. Returns an unsubscribe function. */
+    subscribe(subscriber: StreamSubscriber<T>): () => void;
+    /** Attach an AbortSignal — when aborted, the stream is closed. */
+    attachSignal(signal: AbortSignal): void;
+    /** Close the stream and release resources. */
+    close(): void;
+    /** Async iterator protocol — enables `for await (const event of stream)`. */
+    [Symbol.asyncIterator](): AsyncIterableIterator<StreamEvent<T>>;
+}
+
+type CreateStreamFn$3 = (table: string, opts?: StreamOptions) => StreamController;
+/** Namespace for Dead Letter Queue operations. */
+declare class DLQNamespace {
+    private readonly _ctx;
+    private readonly _createStream;
+    constructor(ctx: HttpContext, createStream: CreateStreamFn$3);
+    /** Get DLQ statistics (message counts per table). */
+    list(opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<DLQStats>>;
+    /** Get DLQ stats filtered by table name. */
+    table(name: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<DLQStats>>;
+    /** Subscribe to live DLQ events. */
+    stream(opts?: StreamOptions): StreamController;
+}
+
+type CreateStreamFn$2<Row> = (table: string, opts?: StreamOptions) => StreamController<Row>;
+/** Reference to a named query pipe — PromiseLike for convenient `await`. */
+declare class PipeRef<Row = Record<string, unknown>> implements PromiseLike<Result<Row[]>> {
+    private readonly _ctx;
+    private readonly _name;
+    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[]>>;
+    /** 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>;
+}
+/** Admin namespace for managing named query pipes. */
+declare class PipesNamespace {
+    private readonly _ctx;
+    constructor(ctx: HttpContext);
+    /** List all registered pipes. */
+    list(opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<Pipe[]>>;
+    /** Get a single pipe definition by name. */
+    get(name: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<Pipe>>;
+    /** Create or update a pipe. */
+    set(name: string, def: Omit<Pipe, "name">, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<void>>;
+    /** Delete a pipe by name. */
+    delete(name: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<void>>;
+}
+
+/** Namespace for access control policy management. Requires the admin role (the configured `admin_role`, `"admin"` by default). */
+declare class PolicyNamespace {
+    private readonly _ctx;
+    constructor(ctx: HttpContext);
+    /** Get the current access control policy. */
+    get(opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<Policy>>;
+    /** Replace the entire access control policy. */
+    set(policy: Policy, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<void>>;
+    /** Validate a policy without applying it (dry run). */
+    validate(policy: Policy, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<ValidationResult>>;
+}
+
+/** Namespace for schema introspection. */
+declare class SchemaNamespace {
+    private readonly _ctx;
+    constructor(ctx: HttpContext);
+    /** List all table schemas discovered from ClickHouse. */
+    list(opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<Schemas>>;
+    /** Force a schema refresh from ClickHouse system.columns. */
+    refresh(opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<void>>;
+}
+
+/** Namespace for the SDK's content-free server-online check. */
+declare class SysNamespace {
+    private readonly _ctx;
+    constructor(ctx: HttpContext);
+    /**
+     * Liveness ping — resolves with no error when the server is reachable and
+     * past boot. Hits the public, content-free `/v1/health` route (200/503, no
+     * body), kept intentionally distinct from the `/livez` Kubernetes probe so
+     * it stays reachable even in deployments that filter probe paths at the
+     * reverse proxy. Use it to check a server is online before sending data, or
+     * to pick among servers in a distributed setup.
+     */
+    health(opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<void>>;
+}
+
+/**
+ * Stream-first live query orchestrator.
+ *
+ * 1. Opens a live stream immediately (buffers events).
+ * 2. Fetches historical data.
+ * 3. Calls `subscriber.initial(result)` with the historical snapshot.
+ * 4. Deduplicates buffered events against the fetch result.
+ * 5. Flushes remaining buffered events through `subscriber.next()`.
+ * 6. Resumes live: pipes stream events directly to `subscriber.next()`.
+ */
+declare class LiveQuery<T = Record<string, unknown>> {
+    private _stream;
+    private _subscriber;
+    private _buffer;
+    private _buffering;
+    private _unsubStream;
+    private _closed;
+    constructor(stream: StreamController<T>, fetchFn: () => Promise<Result<T[]>>, subscriber: StreamSubscriber<T>, _filters: QueryFilter[]);
+    private _runBackfill;
+    /** Close the live query and the underlying stream. */
+    close(): void;
+}
+
+interface QueryState {
+    table: string;
+    columns: string[];
+    aggregations: Aggregation[];
+    filters: QueryFilter[];
+    groupBy: string[];
+    orderBy: OrderClause[];
+    limit?: number;
+    timeRange?: TimeRange;
+    cacheTTL?: number;
+}
+type CreateStreamFn$1<Row> = (table: string, opts?: StreamOptions) => StreamController<Row>;
+/**
+ * Immutable, PromiseLike query builder.
+ * Every chain method returns a new instance. `await builder` auto-executes `.fetch()`.
+ */
+declare class QueryBuilder<Row = Record<string, unknown>> implements PromiseLike<Result<Row[]>> {
+    /** @internal */
+    private readonly _state;
+    /** @internal */
+    private readonly _ctx;
+    /** @internal */
+    private readonly _createStream;
+    constructor(ctx: HttpContext, state: QueryState, createStream: CreateStreamFn$1<Row>);
+    select(...columns: string[]): 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>;
+    avg(column: string, alias?: string): QueryBuilder<Row>;
+    min(column: string, alias?: string): QueryBuilder<Row>;
+    max(column: string, alias?: string): QueryBuilder<Row>;
+    countDistinct(column: string, alias?: string): QueryBuilder<Row>;
+    aggregate(fn: string, column: string, alias: string): QueryBuilder<Row>;
+    groupBy(...columns: string[]): QueryBuilder<Row>;
+    orderBy(column: string, dir?: "asc" | "desc"): QueryBuilder<Row>;
+    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. */
+    static readonly DEFAULT_LIMIT = 1000;
+    fetch(opts?: FetchOptions): Promise<Result<Row[]>>;
+    stream(opts?: StreamOptions): StreamController<Row>;
+    /**
+     * Start a live query: fetches historical data, then streams live updates.
+     *
+     * The subscriber's `initial()` is called once with the fetch result, then
+     * `next()` fires for each live event. Events that arrived during the fetch
+     * are deduplicated and flushed automatically.
+     *
+     * Returns a LiveQuery handle with a `.close()` method.
+     */
+    liveQuery(subscriber: StreamSubscriber<Row>, opts?: StreamOptions): LiveQuery<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>;
+    private _clone;
+    private _addAgg;
+    private _buildAST;
+    private _fetchNext;
+}
+
+type CreateStreamFn<Row> = (table: string, opts?: StreamOptions) => StreamController<Row>;
+/**
+ * Reference to a table. NOT thenable — safe to pass around without triggering requests.
+ * Use `.fetch()`, `.select()`, `.insert()`, `.schema()`, or `.stream()` to act on it.
+ */
+declare class TableRef<Row = Record<string, unknown>> {
+    private readonly _ctx;
+    private readonly _table;
+    private readonly _createStream;
+    constructor(ctx: HttpContext, table: string, createStream: CreateStreamFn<Row>);
+    /** SELECT * shortcut — fetches rows with optional pagination. */
+    fetch(opts?: FetchOptions): 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. */
+    insert(data: Partial<Row> | Partial<Row>[], opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<InsertResult>>;
+    /** Fetch the schema for this table. */
+    schema(opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<TableSchema>>;
+    /** Subscribe to live events for this table. */
+    stream(opts?: StreamOptions): StreamController<Row>;
+}
+
+type TableName<DB> = DB extends Database ? Extract<keyof DB, string> : string;
+type RowType<DB, T extends string> = DB extends Database ? T extends keyof DB ? DB[T] : Record<string, unknown> : Record<string, unknown>;
+declare class WaveHouseClient<DB extends Database = Database> {
+    /** @internal */
+    readonly _ctx: HttpContext;
+    /** Schema introspection namespace. */
+    readonly schema: SchemaNamespace;
+    /** Access control policy namespace (admin). */
+    readonly policy: PolicyNamespace;
+    /** Dead Letter Queue namespace. */
+    readonly dlq: DLQNamespace;
+    /** System health/readiness namespace. */
+    readonly sys: SysNamespace;
+    /** Named query pipes admin namespace. */
+    readonly pipes: PipesNamespace;
+    constructor(config: ClientConfig<DB>);
+    /** Get a table reference for building queries, inserts, and streams. */
+    from<T extends TableName<DB>>(table: T): TableRef<RowType<DB, T>>;
+    /** Get a reference to a named query pipe. PromiseLike — `await` it to execute. */
+    pipe<Row = Record<string, unknown>>(name: string, params?: Record<string, unknown>): PipeRef<Row>;
+    /**
+     * Execute a raw SQL query against ClickHouse. Requires the admin role (the
+     * configured `admin_role`, `"admin"` by default; there is no separate
+     * `service` role). The endpoint proxies straight to ClickHouse's HTTP
+     * interface so any ClickHouse-accepted SQL works; positional `?` param
+     * binding is NOT supported — inline literals or use the structured query
+     * builder for safe binding. See sql.ts for details.
+     */
+    sql<Row = Record<string, unknown>>(query: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<Row[]>>;
+    /** @internal Create a stream for the given table. */
+    private _createStream;
+}
+/** 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 };