@wavehouse/sdk 0.0.0-dev.0f8826c

package/dist/index.cjs

@@ -0,0 +1,1107 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  DLQNamespace: () => DLQNamespace,
+  LiveQuery: () => LiveQuery,
+  PipeRef: () => PipeRef,
+  PipesNamespace: () => PipesNamespace,
+  PolicyNamespace: () => PolicyNamespace,
+  QueryBuilder: () => QueryBuilder,
+  SchemaNamespace: () => SchemaNamespace,
+  StreamController: () => StreamController,
+  SysNamespace: () => SysNamespace,
+  TableRef: () => TableRef,
+  WaveHouseClient: () => WaveHouseClient,
+  createClient: () => createClient
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/errors.ts
+async function parseErrorResponse(res) {
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    body = void 0;
+  }
+  const message = typeof body?.error === "string" ? body.error : typeof body?.message === "string" ? body.message : res.statusText;
+  const retryable = res.status === 503 || res.status >= 500;
+  return {
+    status: res.status,
+    code: `HTTP_${res.status}`,
+    message,
+    details: body,
+    retryable
+  };
+}
+function networkError(cause) {
+  const message = cause instanceof Error ? cause.message : String(cause);
+  return {
+    status: 0,
+    code: "NETWORK_ERROR",
+    message,
+    retryable: true
+  };
+}
+function ok(data) {
+  return { ok: true, data, error: null };
+}
+function okPage(data, hasMore, next) {
+  return { ok: true, data, error: null, hasMore, next };
+}
+function err(error) {
+  return { ok: false, data: null, error };
+}
+
+// src/http.ts
+async function request(ctx, opts) {
+  const url = buildURL(ctx.baseURL, opts.path, opts.params);
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "application/json"
+  };
+  if (ctx.auth) {
+    const token = await ctx.auth();
+    if (token) {
+      headers.Authorization = `Bearer ${token}`;
+    }
+  }
+  let lastError = null;
+  const maxAttempts = ctx.options.maxRetries + 1;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      const res = await fetch(url, {
+        method: opts.method,
+        headers,
+        body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0,
+        signal: opts.signal
+      });
+      if (res.ok) {
+        const text = await res.text();
+        const data = text ? JSON.parse(text) : void 0;
+        return { data, error: null, headers: res.headers };
+      }
+      const error = await parseErrorResponse(res);
+      if (res.status === 503) {
+        const retryAfter = res.headers.get("Retry-After");
+        if (retryAfter && attempt < maxAttempts - 1) {
+          const delay = parseInt(retryAfter, 10) * 1e3 || 3e4;
+          await sleep(delay, opts.signal);
+          lastError = error;
+          continue;
+        }
+      }
+      if (error.retryable && attempt < maxAttempts - 1) {
+        await sleep(backoff(attempt), opts.signal);
+        lastError = error;
+        continue;
+      }
+      return { data: null, error, headers: res.headers };
+    } catch (e) {
+      if (e instanceof DOMException && e.name === "AbortError") {
+        return {
+          data: null,
+          error: { status: 0, code: "ABORTED", message: "Request aborted", retryable: false },
+          headers: new Headers()
+        };
+      }
+      lastError = networkError(e);
+      if (attempt < maxAttempts - 1) {
+        await sleep(backoff(attempt), opts.signal);
+      }
+    }
+  }
+  return { data: null, error: lastError, headers: new Headers() };
+}
+function buildURL(base, path, params) {
+  const url = new URL(path, base.endsWith("/") ? base : `${base}/`);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      url.searchParams.set(k, v);
+    }
+  }
+  return url.toString();
+}
+function backoff(attempt) {
+  return Math.min(1e3 * 2 ** attempt, 3e4);
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException("Aborted", "AbortError"));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(new DOMException("Aborted", "AbortError"));
+      },
+      { once: true }
+    );
+  });
+}
+
+// src/dlq.ts
+var DLQNamespace = class {
+  _ctx;
+  _createStream;
+  constructor(ctx, createStream) {
+    this._ctx = ctx;
+    this._createStream = createStream;
+  }
+  /** Get DLQ statistics (message counts per table). */
+  async list(opts) {
+    const { data, error } = await request(this._ctx, {
+      method: "GET",
+      path: "/v1/dlq/stats",
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    return ok(data);
+  }
+  /** Get DLQ stats filtered by table name. */
+  async table(name, opts) {
+    const { data, error } = await request(this._ctx, {
+      method: "GET",
+      path: "/v1/dlq/stats",
+      params: { table: name },
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    return ok(data);
+  }
+  /** Subscribe to live DLQ events. */
+  stream(opts) {
+    return this._createStream("dlq", opts);
+  }
+};
+
+// src/pipes.ts
+var PipeRef = class {
+  _ctx;
+  _name;
+  _params;
+  _createStream;
+  constructor(ctx, name, params, createStream) {
+    this._ctx = ctx;
+    this._name = name;
+    this._params = params;
+    this._createStream = createStream;
+  }
+  /** Execute the pipe and return results. */
+  async fetch(opts) {
+    const { data, error } = await request(this._ctx, {
+      method: "POST",
+      path: `/v1/pipes/${encodeURIComponent(this._name)}`,
+      body: this._params ?? {},
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    return ok(data);
+  }
+  /** Subscribe to live events from the pipe's underlying query. */
+  stream(opts) {
+    return this._createStream(this._name, opts);
+  }
+  then(onfulfilled, onrejected) {
+    return this.fetch().then(onfulfilled, onrejected);
+  }
+};
+var PipesNamespace = class {
+  _ctx;
+  constructor(ctx) {
+    this._ctx = ctx;
+  }
+  /** List all registered pipes. */
+  async list(opts) {
+    const { data, error } = await request(this._ctx, {
+      method: "GET",
+      path: "/v1/admin/pipes",
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    return ok(data);
+  }
+  /** Get a single pipe definition by name. */
+  async get(name, opts) {
+    const { data, error } = await request(this._ctx, {
+      method: "GET",
+      path: `/v1/admin/pipes/${encodeURIComponent(name)}`,
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    return ok(data);
+  }
+  /** Create or update a pipe. */
+  async set(name, def, opts) {
+    const { error } = await request(this._ctx, {
+      method: "PUT",
+      path: `/v1/admin/pipes/${encodeURIComponent(name)}`,
+      body: def,
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    return ok(void 0);
+  }
+  /** Delete a pipe by name. */
+  async delete(name, opts) {
+    const { error } = await request(this._ctx, {
+      method: "DELETE",
+      path: `/v1/admin/pipes/${encodeURIComponent(name)}`,
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    return ok(void 0);
+  }
+};
+
+// src/policy.ts
+var PolicyNamespace = class {
+  _ctx;
+  constructor(ctx) {
+    this._ctx = ctx;
+  }
+  /** Get the current access control policy. */
+  async get(opts) {
+    const { data, error } = await request(this._ctx, {
+      method: "GET",
+      path: "/v1/admin/policy",
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    return ok(data);
+  }
+  /** Replace the entire access control policy. */
+  async set(policy, opts) {
+    const { error } = await request(this._ctx, {
+      method: "PUT",
+      path: "/v1/admin/policy",
+      body: policy,
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    return ok(void 0);
+  }
+  /** Validate a policy without applying it (dry run). */
+  async validate(policy, opts) {
+    const { data, error } = await request(this._ctx, {
+      method: "POST",
+      path: "/v1/admin/policy/validate",
+      body: policy,
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    return ok(data);
+  }
+};
+
+// src/schema.ts
+var SchemaNamespace = class {
+  _ctx;
+  constructor(ctx) {
+    this._ctx = ctx;
+  }
+  /** List all table schemas discovered from ClickHouse. */
+  async list(opts) {
+    const { data, error } = await request(this._ctx, {
+      method: "GET",
+      path: "/v1/schema",
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    let schemas;
+    if (Array.isArray(data)) {
+      schemas = {};
+      for (const table of data) {
+        if (table && typeof table === "object" && "name" in table) {
+          schemas[table.name] = table;
+        }
+      }
+    } else {
+      schemas = data;
+    }
+    return ok(schemas);
+  }
+  /** Force a schema refresh from ClickHouse system.columns. */
+  async refresh(opts) {
+    const { error } = await request(this._ctx, {
+      method: "POST",
+      path: "/v1/schema/refresh",
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    return ok(void 0);
+  }
+};
+
+// src/sql.ts
+async function sql(ctx, query, opts) {
+  const { data, error } = await request(ctx, {
+    method: "POST",
+    path: "/v1/admin/query",
+    body: { sql: query },
+    signal: opts?.signal
+  });
+  if (error) return err(error);
+  return ok(data);
+}
+
+// src/stream/controller.ts
+var StreamController = class {
+  _transport;
+  _subscribers = /* @__PURE__ */ new Set();
+  _status = "connecting";
+  _buffer = [];
+  _waiters = [];
+  _done = false;
+  constructor(transport) {
+    this._transport = transport;
+    this._transport.onEvent = (event) => {
+      for (const sub of this._subscribers) {
+        sub.next(event);
+      }
+      const waiter = this._waiters.shift();
+      if (waiter) {
+        waiter.resolve({ value: event, done: false });
+      } else {
+        this._buffer.push(event);
+      }
+    };
+    this._transport.onStatus = (status) => {
+      if (status === this._status) return;
+      this._status = status;
+      for (const sub of this._subscribers) {
+        sub.status?.(status);
+      }
+      if (status === "closed") {
+        this._done = true;
+        for (const w of this._waiters) {
+          w.resolve({ value: void 0, done: true });
+        }
+        this._waiters = [];
+      }
+    };
+    this._transport.onError = (error) => {
+      for (const sub of this._subscribers) {
+        sub.error?.(error);
+      }
+    };
+    this._transport.connect();
+  }
+  /** Current connection status. */
+  get status() {
+    return this._status;
+  }
+  /**
+   * 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 = 5e3) {
+    if (this._status === "live") return Promise.resolve();
+    if (this._status === "closed") return Promise.reject(new Error("Stream is closed"));
+    if (this._done) return Promise.reject(new Error("Stream closed before connecting"));
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        this._subscribers.delete(watcher);
+        reject(new Error(`Stream did not connect within ${timeoutMs}ms`));
+      }, timeoutMs);
+      const watcher = {
+        next: () => {
+        },
+        status: (s) => {
+          if (s === "live") {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            this._subscribers.delete(watcher);
+            resolve();
+          } else if (s === "closed") {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            this._subscribers.delete(watcher);
+            reject(new Error("Stream closed before connecting"));
+          }
+        }
+      };
+      this._subscribers.add(watcher);
+    });
+  }
+  /** Subscribe to stream events via callbacks. Returns an unsubscribe function. */
+  subscribe(subscriber) {
+    this._subscribers.add(subscriber);
+    subscriber.status?.(this._status);
+    return () => {
+      this._subscribers.delete(subscriber);
+      if (this._subscribers.size === 0 && this._waiters.length === 0) {
+        this.close();
+      }
+    };
+  }
+  /** Attach an AbortSignal — when aborted, the stream is closed. */
+  attachSignal(signal) {
+    if (signal.aborted) {
+      this.close();
+      return;
+    }
+    signal.addEventListener("abort", () => this.close(), { once: true });
+  }
+  /** Close the stream and release resources. */
+  close() {
+    this._transport.disconnect();
+    if (this._status !== "closed") {
+      this._status = "closed";
+      for (const sub of this._subscribers) {
+        sub.status?.("closed");
+      }
+    }
+    this._done = true;
+    for (const w of this._waiters) {
+      w.resolve({ value: void 0, done: true });
+    }
+    this._waiters = [];
+  }
+  /** Async iterator protocol — enables `for await (const event of stream)`. */
+  [Symbol.asyncIterator]() {
+    const self = this;
+    return {
+      next() {
+        if (self._buffer.length > 0) {
+          return Promise.resolve({ value: self._buffer.shift(), done: false });
+        }
+        if (self._done) {
+          return Promise.resolve({ value: void 0, done: true });
+        }
+        return new Promise((resolve) => {
+          self._waiters.push({ resolve });
+        });
+      },
+      return() {
+        self.close();
+        return Promise.resolve({ value: void 0, done: true });
+      },
+      [Symbol.asyncIterator]() {
+        return this;
+      }
+    };
+  }
+};
+
+// src/stream/sse.ts
+var activeSSEConnections = 0;
+var SSE_WARN_THRESHOLD = 5;
+var SSETransport = class {
+  _opts;
+  _es = null;
+  onEvent = null;
+  onStatus = null;
+  onError = null;
+  constructor(opts) {
+    this._opts = opts;
+  }
+  connect() {
+    if (typeof EventSource === "undefined") {
+      throw new Error(
+        "[wavehouse] EventSource is not available in this environment. Please provide a global polyfill (e.g., `globalThis.EventSource = require('eventsource')`)."
+      );
+    }
+    this._doConnect().catch((err2) => {
+      this.onError?.({
+        status: 0,
+        code: "SSE_CONNECT_ERROR",
+        message: err2 instanceof Error ? err2.message : String(err2),
+        retryable: true
+      });
+    });
+  }
+  disconnect() {
+    if (this._es) {
+      this._es.close();
+      this._es = null;
+      activeSSEConnections = Math.max(0, activeSSEConnections - 1);
+    }
+    this.onStatus?.("closed");
+  }
+  async _doConnect() {
+    const url = new URL("/v1/stream", this._opts.baseURL);
+    url.searchParams.set("table", this._opts.table);
+    if (this._opts.since) {
+      url.searchParams.set("since", this._opts.since);
+    }
+    if (this._opts.auth) {
+      const token = await this._opts.auth();
+      if (token) {
+        url.searchParams.set("token", token);
+      }
+    }
+    activeSSEConnections++;
+    if (activeSSEConnections > SSE_WARN_THRESHOLD) {
+      console.warn(
+        `[wavehouse] ${activeSSEConnections} SSE connections open. Browsers limit HTTP/1.1 to 6 connections per domain.`
+      );
+    }
+    this._es = new EventSource(url.toString());
+    this._es.onopen = () => {
+      this.onStatus?.("live");
+    };
+    this._es.onmessage = (e) => {
+      try {
+        const msg = JSON.parse(e.data);
+        const event = {
+          table: msg.table_name,
+          timestamp: msg.received_timestamp,
+          data: msg.data
+        };
+        this.onEvent?.(event);
+      } catch {
+        console.warn("[wavehouse] SSE received malformed message:", e.data);
+      }
+    };
+    this._es.onerror = () => {
+      if (this._es?.readyState === EventSource.CONNECTING) {
+        this.onStatus?.("reconnecting");
+      } else if (this._es?.readyState === EventSource.CLOSED) {
+        this.onStatus?.("closed");
+      } else if (this._es?.readyState === EventSource.OPEN) {
+        this.onStatus?.("live");
+      } else {
+        this.onError?.({
+          status: 0,
+          code: "SSE_ERROR",
+          message: "SSE connection error",
+          retryable: true
+        });
+      }
+    };
+  }
+};
+
+// src/sys.ts
+var SysNamespace = class {
+  _ctx;
+  constructor(ctx) {
+    this._ctx = ctx;
+  }
+  /**
+   * 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.
+   */
+  async health(opts) {
+    const { error } = await request(this._ctx, {
+      method: "GET",
+      path: "/v1/health",
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    return ok(void 0);
+  }
+};
+
+// src/stream/live-query.ts
+var LiveQuery = class {
+  _stream;
+  _subscriber;
+  _buffer = [];
+  _buffering = true;
+  _unsubStream = null;
+  _closed = false;
+  constructor(stream, fetchFn, subscriber, _filters) {
+    this._stream = stream;
+    this._subscriber = subscriber;
+    this._unsubStream = stream.subscribe({
+      next: (event) => {
+        if (this._closed) return;
+        if (this._buffering) {
+          this._buffer.push(event);
+        } else {
+          subscriber.next(event);
+        }
+      },
+      status: (s) => subscriber.status?.(s),
+      error: (e) => subscriber.error?.(e)
+    });
+    this._runBackfill(fetchFn);
+  }
+  async _runBackfill(fetchFn) {
+    try {
+      const result = await fetchFn();
+      if (this._closed) return;
+      this._subscriber.initial?.(result);
+      if (result.error) {
+        this._buffering = false;
+        return;
+      }
+      const rows = result.data;
+      let lastTimestamp;
+      if (rows.length > 0) {
+        const lastRow = rows[rows.length - 1];
+        lastTimestamp = lastRow?.received_timestamp;
+      }
+      this._buffering = false;
+      for (const event of this._buffer) {
+        if (this._closed) break;
+        if (lastTimestamp && event.timestamp <= lastTimestamp) {
+          continue;
+        }
+        this._subscriber.next(event);
+      }
+      this._buffer = [];
+    } catch {
+      this._buffering = false;
+      this._buffer = [];
+    }
+  }
+  /** Close the live query and the underlying stream. */
+  close() {
+    this._closed = true;
+    this._buffering = false;
+    this._buffer = [];
+    this._unsubStream?.();
+    this._stream.close();
+  }
+};
+
+// src/query-builder.ts
+var OP_MAP = {
+  "=": "eq",
+  "!=": "neq",
+  ">": "gt",
+  ">=": "gte",
+  "<": "lt",
+  "<=": "lte",
+  in: "in",
+  like: "like",
+  not_like: "not_like"
+};
+var QueryBuilder = class _QueryBuilder {
+  /** @internal */
+  _state;
+  /** @internal */
+  _ctx;
+  /** @internal */
+  _createStream;
+  constructor(ctx, state, createStream) {
+    this._ctx = ctx;
+    this._state = Object.freeze({ ...state });
+    this._createStream = createStream;
+  }
+  // --- Builder methods (each returns a new QueryBuilder) ---
+  select(...columns) {
+    return this._clone({ columns: [...this._state.columns, ...columns] });
+  }
+  where(column, op, value) {
+    const filter = { column, op: OP_MAP[op], value };
+    return this._clone({ filters: [...this._state.filters, filter] });
+  }
+  count(column = "*", alias = "count") {
+    return this._addAgg("count", column, alias);
+  }
+  sum(column, alias = `sum_${column}`) {
+    return this._addAgg("sum", column, alias);
+  }
+  avg(column, alias = `avg_${column}`) {
+    return this._addAgg("avg", column, alias);
+  }
+  min(column, alias = `min_${column}`) {
+    return this._addAgg("min", column, alias);
+  }
+  max(column, alias = `max_${column}`) {
+    return this._addAgg("max", column, alias);
+  }
+  countDistinct(column, alias = `count_distinct_${column}`) {
+    return this._addAgg("countDistinct", column, alias);
+  }
+  aggregate(fn, column, alias) {
+    return this._addAgg(fn, column, alias);
+  }
+  groupBy(...columns) {
+    return this._clone({ groupBy: [...this._state.groupBy, ...columns] });
+  }
+  orderBy(column, dir = "asc") {
+    return this._clone({ orderBy: [...this._state.orderBy, { column, dir }] });
+  }
+  limit(n) {
+    return this._clone({ limit: n });
+  }
+  timeRange(column, since, until) {
+    return this._clone({ timeRange: { column, since, until } });
+  }
+  cacheTTL(seconds) {
+    return this._clone({ cacheTTL: seconds });
+  }
+  // --- Execution ---
+  /** Default row limit when none is specified. Matches backend DefaultMaxRows. */
+  static DEFAULT_LIMIT = 1e3;
+  async fetch(opts) {
+    const effectiveLimit = opts?.limit ?? this._state.limit ?? _QueryBuilder.DEFAULT_LIMIT;
+    const ast = this._buildAST(effectiveLimit);
+    const { data, error } = await request(this._ctx, {
+      method: "POST",
+      path: `/v1/query?table=${encodeURIComponent(this._state.table)}`,
+      body: ast,
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    const rows = data;
+    const hasMore = effectiveLimit != null && rows.length >= effectiveLimit;
+    if (hasMore) {
+      const nextFn = () => this._fetchNext(rows, effectiveLimit, opts);
+      return okPage(rows, true, nextFn);
+    }
+    return okPage(rows, false);
+  }
+  stream(opts) {
+    const raw = this._createStream(this._state.table, opts);
+    const filters = this._state.filters;
+    const columns = this._state.columns;
+    if (filters.length === 0 && columns.length === 0) {
+      return raw;
+    }
+    return new FilteredStreamController(raw, filters, columns);
+  }
+  /**
+   * 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, opts) {
+    const stream = this.stream(opts);
+    const fetchFn = () => this.fetch();
+    return new LiveQuery(stream, fetchFn, subscriber, this._state.filters);
+  }
+  // --- PromiseLike implementation ---
+  then(onfulfilled, onrejected) {
+    return this.fetch().then(onfulfilled, onrejected);
+  }
+  // --- Private helpers ---
+  _clone(overrides) {
+    return new _QueryBuilder(this._ctx, { ...this._state, ...overrides }, this._createStream);
+  }
+  _addAgg(fn, column, alias) {
+    const agg = { fn, column, alias };
+    return this._clone({ aggregations: [...this._state.aggregations, agg] });
+  }
+  _buildAST(effectiveLimit) {
+    const ast = {};
+    if (this._state.columns.length > 0) ast.columns = this._state.columns;
+    if (this._state.aggregations.length > 0) ast.aggregations = this._state.aggregations;
+    if (this._state.filters.length > 0) ast.filters = this._state.filters;
+    if (this._state.groupBy.length > 0) ast.group_by = this._state.groupBy;
+    if (this._state.orderBy.length > 0) {
+      ast.order_by = this._state.orderBy;
+    } else if (effectiveLimit != null && this._state.aggregations.length === 0) {
+      ast.order_by = [{ column: "received_timestamp", dir: "desc" }];
+    }
+    if (effectiveLimit != null) ast.limit = effectiveLimit;
+    if (this._state.timeRange) ast.time_range = this._state.timeRange;
+    return ast;
+  }
+  async _fetchNext(prevRows, _limit, opts) {
+    const orderCol = this._state.orderBy[0]?.column ?? "received_timestamp";
+    const orderDir = this._state.orderBy[0]?.dir ?? "desc";
+    const lastRow = prevRows[prevRows.length - 1];
+    const lastValue = lastRow?.[orderCol];
+    if (lastValue === void 0) return okPage([], false);
+    const cursorOp = orderDir === "desc" ? "lt" : "gt";
+    const cursorFilter = { column: orderCol, op: cursorOp, value: lastValue };
+    const orderBy = this._state.orderBy.length > 0 ? this._state.orderBy : [{ column: orderCol, dir: orderDir }];
+    const nextBuilder = this._clone({
+      filters: [...this._state.filters, cursorFilter],
+      orderBy
+    });
+    return nextBuilder.fetch(opts);
+  }
+};
+var FilteredStreamController = class extends StreamController {
+  constructor(inner, filters, columns) {
+    const transport = {
+      onEvent: null,
+      onStatus: null,
+      onError: null,
+      connect() {
+        inner.subscribe({
+          next: (event) => {
+            if (!matchesFilters(event.data, filters)) {
+              return;
+            }
+            const projected = columns.length > 0 ? {
+              ...event,
+              data: projectColumns(event.data, columns)
+            } : event;
+            this.onEvent?.(projected);
+          },
+          status: (s) => this.onStatus?.(s),
+          error: (e) => this.onError?.(e)
+        });
+      },
+      disconnect() {
+        inner.close();
+      }
+    };
+    super(transport);
+  }
+};
+function matchesFilters(row, filters) {
+  for (const f of filters) {
+    const val = row[f.column];
+    if (!evaluateFilter(val, f.op, f.value)) return false;
+  }
+  return true;
+}
+function evaluateFilter(actual, op, expected) {
+  switch (op) {
+    case "eq":
+      return actual === expected;
+    case "neq":
+      return actual !== expected;
+    case "gt":
+      return compareOrdered(actual, expected, (a, b) => a > b);
+    case "gte":
+      return compareOrdered(actual, expected, (a, b) => a >= b);
+    case "lt":
+      return compareOrdered(actual, expected, (a, b) => a < b);
+    case "lte":
+      return compareOrdered(actual, expected, (a, b) => a <= b);
+    case "in":
+      return Array.isArray(expected) && expected.includes(actual);
+    case "like": {
+      if (typeof actual !== "string" || typeof expected !== "string") return false;
+      const escaped = expected.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const pattern = escaped.replace(/%/g, ".*").replace(/_/g, ".");
+      return new RegExp(`^${pattern}$`, "i").test(actual);
+    }
+    case "not_like": {
+      if (typeof actual !== "string" || typeof expected !== "string") return false;
+      const escaped = expected.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const pattern = escaped.replace(/%/g, ".*").replace(/_/g, ".");
+      return !new RegExp(`^${pattern}$`, "i").test(actual);
+    }
+    default:
+      return true;
+  }
+}
+function compareOrdered(actual, expected, cmp) {
+  if (typeof actual === "number" && typeof expected === "number") {
+    return cmp(actual, expected);
+  }
+  if (typeof actual === "string" && typeof expected === "string") {
+    return cmp(actual, expected);
+  }
+  return false;
+}
+function projectColumns(row, columns) {
+  const result = {};
+  for (const col of columns) {
+    if (col in row) result[col] = row[col];
+  }
+  return result;
+}
+
+// src/table.ts
+var TableRef = class {
+  _ctx;
+  _table;
+  _createStream;
+  constructor(ctx, table, createStream) {
+    this._ctx = ctx;
+    this._table = table;
+    this._createStream = createStream;
+  }
+  /** SELECT * shortcut — fetches rows with optional pagination. */
+  async fetch(opts) {
+    return this.select().limit(opts?.limit ?? 1e3).fetch(opts);
+  }
+  /** Start building a typed query. Returns an immutable, PromiseLike QueryBuilder. */
+  select(...columns) {
+    return new QueryBuilder(
+      this._ctx,
+      {
+        table: this._table,
+        columns,
+        aggregations: [],
+        filters: [],
+        groupBy: [],
+        orderBy: []
+      },
+      this._createStream
+    );
+  }
+  /** Insert one or more rows into this table. */
+  async insert(data, opts) {
+    if (Array.isArray(data)) {
+      const promises = data.map(
+        (row) => request(this._ctx, {
+          method: "POST",
+          path: `/v1/ingest?table=${encodeURIComponent(this._table)}`,
+          body: row,
+          signal: opts?.signal
+        })
+      );
+      const results = await Promise.all(promises);
+      for (const res2 of results) {
+        if (res2.error) return err(res2.error);
+      }
+      return ok({ ok: true });
+    }
+    const { data: res, error } = await request(this._ctx, {
+      method: "POST",
+      path: `/v1/ingest?table=${encodeURIComponent(this._table)}`,
+      body: data,
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    const result = { ok: res?.ok ?? true };
+    if (res?.duplicate != null) result.duplicate = res.duplicate;
+    return ok(result);
+  }
+  /** Fetch the schema for this table. */
+  async schema(opts) {
+    const { data, error } = await request(this._ctx, {
+      method: "GET",
+      path: `/v1/schema?table=${encodeURIComponent(this._table)}`,
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    return ok(data);
+  }
+  /** Subscribe to live events for this table. */
+  stream(opts) {
+    return this._createStream(this._table, opts);
+  }
+};
+
+// src/client.ts
+var WaveHouseClient = class {
+  /** @internal */
+  _ctx;
+  /** Schema introspection namespace. */
+  schema;
+  /** Access control policy namespace (admin). */
+  policy;
+  /** Dead Letter Queue namespace. */
+  dlq;
+  /** System health/readiness namespace. */
+  sys;
+  /** Named query pipes admin namespace. */
+  pipes;
+  constructor(config) {
+    this._ctx = {
+      baseURL: config.baseURL.replace(/\/+$/, ""),
+      auth: config.auth,
+      options: {
+        maxRetries: config.options?.maxRetries ?? 2
+      }
+    };
+    this.schema = new SchemaNamespace(this._ctx);
+    this.policy = new PolicyNamespace(this._ctx);
+    this.dlq = new DLQNamespace(this._ctx, (table, opts) => this._createStream(table, opts));
+    this.sys = new SysNamespace(this._ctx);
+    this.pipes = new PipesNamespace(this._ctx);
+  }
+  /** Get a table reference for building queries, inserts, and streams. */
+  from(table) {
+    return new TableRef(
+      this._ctx,
+      table,
+      (t, opts) => this._createStream(t, opts)
+    );
+  }
+  /** Get a reference to a named query pipe. PromiseLike — `await` it to execute. */
+  pipe(name, params) {
+    return new PipeRef(this._ctx, name, params, (t, opts) => this._createStream(t, opts));
+  }
+  /**
+   * 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(query, opts) {
+    if (Array.isArray(opts)) {
+      throw new Error(
+        "[WaveHouse SDK] client.sql(sql, params) was removed. The /v1/admin/query endpoint does not accept positional `?` params. Inline literals into the SQL, or use the structured query builder (wh.from(table)\u2026) for safe binding from user input."
+      );
+    }
+    return sql(this._ctx, query, opts);
+  }
+  /** @internal Create a stream for the given table. */
+  _createStream(table, opts) {
+    if (typeof EventSource === "undefined") {
+      throw new Error(
+        "[WaveHouse SDK] Native EventSource is not available in this environment. Please provide a global polyfill (e.g., `globalThis.EventSource = require('eventsource')`)."
+      );
+    }
+    const transport = new SSETransport({
+      baseURL: this._ctx.baseURL,
+      table,
+      since: opts?.since,
+      auth: this._ctx.auth
+    });
+    const controller = new StreamController(transport);
+    if (opts?.signal) controller.attachSignal(opts.signal);
+    return controller;
+  }
+};
+function createClient(config) {
+  return new WaveHouseClient(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DLQNamespace,
+  LiveQuery,
+  PipeRef,
+  PipesNamespace,
+  PolicyNamespace,
+  QueryBuilder,
+  SchemaNamespace,
+  StreamController,
+  SysNamespace,
+  TableRef,
+  WaveHouseClient,
+  createClient
+});
+//# sourceMappingURL=index.cjs.map