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

package/dist/index.js

@@ -35,29 +35,71 @@ function err(error) {
   return { ok: false, data: null, error };
 }
 
+// src/url.ts
+function resolveURL(base, path, params) {
+  const root = new URL(base);
+  root.search = "";
+  root.hash = "";
+  if (!root.pathname.endsWith("/")) root.pathname += "/";
+  const url = new URL(path.replace(/^\/+/, ""), root);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      url.searchParams.set(k, v);
+    }
+  }
+  return url;
+}
+
 // src/http.ts
+function mergeHeaders(base, extra) {
+  if (!extra) return base;
+  const sdkNames = new Set(Object.keys(base).map((k) => k.toLowerCase()));
+  const merged = { ...base };
+  const configured = /* @__PURE__ */ new Map();
+  for (const [name, value] of Object.entries(extra)) {
+    const lower = name.toLowerCase();
+    if (sdkNames.has(lower)) continue;
+    const prior = configured.get(lower);
+    if (prior !== void 0) delete merged[prior];
+    merged[name] = value;
+    configured.set(lower, name);
+  }
+  return merged;
+}
+function abortedResult() {
+  return {
+    data: null,
+    error: { status: 0, code: "ABORTED", message: "Request aborted", retryable: false },
+    headers: new Headers()
+  };
+}
 async function request(ctx, opts) {
-  const url = buildURL(ctx.baseURL, opts.path, opts.params);
+  const url = resolveURL(ctx.baseURL, opts.path, opts.params).toString();
   const headers = {
-    "Content-Type": "application/json",
+    "Content-Type": opts.contentType ?? "application/json",
     Accept: "application/json"
   };
+  const requestBody = opts.rawBody !== void 0 ? opts.rawBody : opts.body !== void 0 ? JSON.stringify(opts.body) : void 0;
   if (ctx.auth) {
     const token = await ctx.auth();
     if (token) {
       headers.Authorization = `Bearer ${token}`;
     }
   }
+  const finalHeaders = mergeHeaders(headers, ctx.options.headers);
   let lastError = null;
   const maxAttempts = ctx.options.maxRetries + 1;
   for (let attempt = 0; attempt < maxAttempts; attempt++) {
     try {
-      const res = await fetch(url, {
+      const init = {
+        ...ctx.options.fetchOptions,
         method: opts.method,
-        headers,
-        body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0,
+        headers: finalHeaders,
+        body: requestBody,
         signal: opts.signal
-      });
+      };
+      const doFetch = ctx.options.fetch;
+      const res = doFetch ? await doFetch(url, init) : await fetch(url, init);
       if (res.ok) {
         const text = await res.text();
         const data = text ? JSON.parse(text) : void 0;
@@ -80,30 +122,24 @@ async function request(ctx, opts) {
       }
       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()
-        };
+      if (opts.signal?.aborted) {
+        return abortedResult();
       }
       lastError = networkError(e);
       if (attempt < maxAttempts - 1) {
-        await sleep(backoff(attempt), opts.signal);
+        try {
+          await sleep(backoff(attempt), opts.signal);
+        } catch (abort) {
+          if (opts.signal?.aborted) {
+            return abortedResult();
+          }
+          throw abort;
+        }
       }
     }
   }
   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);
 }
@@ -137,7 +173,7 @@ var DLQNamespace = class {
   async list(opts) {
     const { data, error } = await request(this._ctx, {
       method: "GET",
-      path: "/v1/dlq/stats",
+      path: "/v1/ops/dlq/stats",
       signal: opts?.signal
     });
     if (error) return err(error);
@@ -147,7 +183,7 @@ var DLQNamespace = class {
   async table(name, opts) {
     const { data, error } = await request(this._ctx, {
       method: "GET",
-      path: "/v1/dlq/stats",
+      path: "/v1/ops/dlq/stats",
       params: { table: name },
       signal: opts?.signal
     });
@@ -172,7 +208,14 @@ var PipeRef = class {
     this._params = params;
     this._createStream = createStream;
   }
-  /** Execute the pipe and return results. */
+  /**
+   * 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 })`.
+   */
   async fetch(opts) {
     const { data, error } = await request(this._ctx, {
       method: "POST",
@@ -200,7 +243,7 @@ var PipesNamespace = class {
   async list(opts) {
     const { data, error } = await request(this._ctx, {
       method: "GET",
-      path: "/v1/admin/pipes",
+      path: "/v1/ops/pipes",
       signal: opts?.signal
     });
     if (error) return err(error);
@@ -210,7 +253,7 @@ var PipesNamespace = class {
   async get(name, opts) {
     const { data, error } = await request(this._ctx, {
       method: "GET",
-      path: `/v1/admin/pipes/${encodeURIComponent(name)}`,
+      path: `/v1/ops/pipes/${encodeURIComponent(name)}`,
       signal: opts?.signal
     });
     if (error) return err(error);
@@ -220,7 +263,7 @@ var PipesNamespace = class {
   async set(name, def, opts) {
     const { error } = await request(this._ctx, {
       method: "PUT",
-      path: `/v1/admin/pipes/${encodeURIComponent(name)}`,
+      path: `/v1/ops/pipes/${encodeURIComponent(name)}`,
       body: def,
       signal: opts?.signal
     });
@@ -231,7 +274,7 @@ var PipesNamespace = class {
   async delete(name, opts) {
     const { error } = await request(this._ctx, {
       method: "DELETE",
-      path: `/v1/admin/pipes/${encodeURIComponent(name)}`,
+      path: `/v1/ops/pipes/${encodeURIComponent(name)}`,
       signal: opts?.signal
     });
     if (error) return err(error);
@@ -249,7 +292,7 @@ var PolicyNamespace = class {
   async get(opts) {
     const { data, error } = await request(this._ctx, {
       method: "GET",
-      path: "/v1/admin/policy",
+      path: "/v1/ops/policy",
       signal: opts?.signal
     });
     if (error) return err(error);
@@ -259,7 +302,7 @@ var PolicyNamespace = class {
   async set(policy, opts) {
     const { error } = await request(this._ctx, {
       method: "PUT",
-      path: "/v1/admin/policy",
+      path: "/v1/ops/policy",
       body: policy,
       signal: opts?.signal
     });
@@ -270,7 +313,7 @@ var PolicyNamespace = class {
   async validate(policy, opts) {
     const { data, error } = await request(this._ctx, {
       method: "POST",
-      path: "/v1/admin/policy/validate",
+      path: "/v1/ops/policy/validate",
       body: policy,
       signal: opts?.signal
     });
@@ -289,7 +332,7 @@ var SchemaNamespace = class {
   async list(opts) {
     const { data, error } = await request(this._ctx, {
       method: "GET",
-      path: "/v1/schema",
+      path: "/v1/ops/schema",
       signal: opts?.signal
     });
     if (error) return err(error);
@@ -310,7 +353,7 @@ var SchemaNamespace = class {
   async refresh(opts) {
     const { error } = await request(this._ctx, {
       method: "POST",
-      path: "/v1/schema/refresh",
+      path: "/v1/ops/schema/refresh",
       signal: opts?.signal
     });
     if (error) return err(error);
@@ -322,7 +365,7 @@ var SchemaNamespace = class {
 async function sql(ctx, query, opts) {
   const { data, error } = await request(ctx, {
     method: "POST",
-    path: "/v1/admin/query",
+    path: "/v1/ops/query",
     body: { sql: query },
     signal: opts?.signal
   });
@@ -485,11 +528,50 @@ var StreamController = class {
 };
 
 // src/stream/sse.ts
+import { createParser } from "eventsource-parser";
 var activeSSEConnections = 0;
 var SSE_WARN_THRESHOLD = 5;
+var MAX_BUFFER_CHARS = 16 * 1024 * 1024;
+var MAX_BACKOFF_MS = 3e4;
+var STABLE_CONNECTION_MS = 3e3;
+function backoff2(attempt, retryFloorMs) {
+  const nominal = Math.max(retryFloorMs, Math.min(1e3 * 2 ** attempt, MAX_BACKOFF_MS));
+  const low = Math.max(retryFloorMs, nominal / 2);
+  return low + Math.random() * (nominal - low);
+}
+function releaseBody(res) {
+  if (res.body && !res.body.locked) res.body.cancel().catch(() => {
+  });
+}
 var SSETransport = class {
   _opts;
-  _es = null;
+  _abort = null;
+  /**
+   * Set by `disconnect()` before it calls `abort()` — both synchronously — so
+   * a rejection caused by our own abort always observes this as `true`. That
+   * makes it a complete and precise test for "did we cause this?", which is
+   * why the catch blocks read it directly instead of matching on the error
+   * type: an `AbortError` we *didn't* raise (a custom `fetch` enforcing a
+   * per-attempt deadline, an `auth()` call cancelled by its own controller) is
+   * a transient failure to re-dial, exactly as on the REST path. Treating one
+   * as a teardown killed the stream permanently, and silently.
+   */
+  _closed = false;
+  _started = false;
+  _counted = false;
+  /**
+   * Most recent non-empty event id, replayed as `Last-Event-ID` on reconnect.
+   *
+   * Deliberately ignores empty ids. The server emits a blank `id:` line for
+   * passthrough payloads, and per the SSE spec an empty `id` field *clears* the
+   * last-event-id — so tracking it faithfully would silently discard the
+   * resumption point mid-stream and re-open from the beginning.
+   */
+  _lastEventId = null;
+  /** Reconnect floor most recently requested by the server via `retry:`. */
+  _retryFloorMs = 0;
+  /** Cuts a reconnect gap short when set — see `_sleep`. */
+  _wake = null;
   onEvent = null;
   onStatus = null;
   onError = null;
@@ -497,79 +579,332 @@ var SSETransport = class {
     this._opts = opts;
   }
   connect() {
-    if (typeof EventSource === "undefined") {
+    if (this._closed || this._started) return;
+    this._started = true;
+    if (!this._opts.fetch && typeof fetch === "undefined") {
       throw new Error(
-        "[wavehouse] EventSource is not available in this environment. Please provide a global polyfill (e.g., `globalThis.EventSource = require('eventsource')`)."
+        "[wavehouse] global fetch is not available in this environment. Upgrade to Node 22+ or supply one via `options.fetch`."
+      );
+    }
+    activeSSEConnections++;
+    this._counted = true;
+    if (activeSSEConnections > SSE_WARN_THRESHOLD) {
+      console.warn(
+        `[wavehouse] ${activeSSEConnections} SSE connections open. Browsers limit HTTP/1.1 to 6 connections per domain.`
       );
     }
-    this._doConnect().catch((err2) => {
-      this.onError?.({
+    this._run().catch((err2) => {
+      this._emitError({
         status: 0,
         code: "SSE_CONNECT_ERROR",
         message: err2 instanceof Error ? err2.message : String(err2),
-        retryable: true
+        retryable: false
       });
+      this.disconnect();
     });
   }
   disconnect() {
-    if (this._es) {
-      this._es.close();
-      this._es = null;
-      activeSSEConnections = Math.max(0, activeSSEConnections - 1);
+    if (!this._closed) {
+      this._closed = true;
+      this._abort?.abort();
+      this._abort = null;
+      this._wake?.();
+      if (this._counted) {
+        activeSSEConnections = Math.max(0, activeSSEConnections - 1);
+        this._counted = false;
+      }
+      try {
+        this.onStatus?.("closed");
+      } catch (e) {
+        console.error("[wavehouse] SSE status handler threw:", e);
+      }
+    }
+  }
+  /** Connect/read/reconnect until the stream is closed or hits a terminal error. */
+  async _run() {
+    await Promise.resolve();
+    let attempt = 0;
+    while (!this._closed) {
+      const { liveMs, terminal } = await this._attempt();
+      if (this._closed) return;
+      if (terminal) {
+        this.disconnect();
+        return;
+      }
+      if (liveMs >= STABLE_CONNECTION_MS) attempt = 0;
+      this._emitStatus("reconnecting");
+      await this._sleep(backoff2(attempt, this._retryFloorMs));
+      attempt++;
     }
-    this.onStatus?.("closed");
   }
-  async _doConnect() {
-    const url = new URL("/v1/stream", this._opts.baseURL);
+  /** One connection attempt: request, validate, then pump frames until it ends. */
+  async _attempt() {
+    const ac = new AbortController();
+    this._abort = ac;
+    let target;
+    try {
+      target = this._url();
+    } catch (e) {
+      this._emitError({
+        status: 0,
+        code: "SSE_CONNECT_ERROR",
+        message: e instanceof Error ? e.message : String(e),
+        retryable: false
+      });
+      return { liveMs: 0, terminal: true };
+    }
+    let init;
+    try {
+      init = await this._init(ac.signal);
+    } catch (e) {
+      if (this._closed) return { liveMs: 0, terminal: true };
+      this._emitError({
+        status: 0,
+        code: "SSE_AUTH_ERROR",
+        message: e instanceof Error ? e.message : String(e),
+        retryable: true
+      });
+      return { liveMs: 0, terminal: false };
+    }
+    let res;
+    try {
+      const doFetch = this._opts.fetch;
+      res = doFetch ? await doFetch(target, init) : await fetch(target, init);
+    } catch (e) {
+      if (this._closed) return { liveMs: 0, terminal: true };
+      this._emitError({
+        status: 0,
+        code: "SSE_NETWORK_ERROR",
+        message: e instanceof Error ? e.message : String(e),
+        retryable: true
+      });
+      return { liveMs: 0, terminal: false };
+    }
+    if (res.type === "opaqueredirect" || res.status >= 300 && res.status < 400) {
+      this._emitError({
+        status: res.status,
+        code: "SSE_REDIRECT",
+        message: "The stream endpoint redirected and the SDK did not follow it. Redirects are refused when the request carries a credential \u2014 an `auth` token or configured `headers` \u2014 because a cross-origin hop strips the Authorization header, and this endpoint answers an unauthenticated caller with a reduced view instead of an error, while forwarding any configured headers to wherever the redirect points. If this request carries neither, `fetch` was left to follow the redirect itself, so arriving here means a response it will not follow (a 304, or a 3xx with no Location header) or an `options.fetch` that returned the redirect verbatim. Either way, set `baseURL` to the final URL; most often this is an http\u2192https upgrade or a canonical-host redirect at a proxy. To follow a credentialed redirect anyway, supply an `options.fetch` that overrides `redirect`.",
+        retryable: false
+      });
+      releaseBody(res);
+      return { liveMs: 0, terminal: true };
+    }
+    if (!res.ok) {
+      const error = await parseErrorResponse(res);
+      this._emitError(error);
+      return { liveMs: 0, terminal: !error.retryable };
+    }
+    const contentType = res.headers.get("content-type") ?? "";
+    if (!contentType.toLowerCase().split(";")[0].trim().startsWith("text/event-stream")) {
+      this._emitError({
+        status: res.status,
+        code: "SSE_BAD_CONTENT_TYPE",
+        message: `Expected \`text/event-stream\`, got \`${contentType || "(none)"}\`. Something between the client and WaveHouse answered this request \u2014 an auth gateway's login page is the usual cause.`,
+        retryable: false
+      });
+      releaseBody(res);
+      return { liveMs: 0, terminal: true };
+    }
+    const body = res.body;
+    if (!body || typeof body.getReader !== "function" || body.locked || res.bodyUsed) {
+      this._emitError({
+        status: res.status,
+        code: "SSE_NO_STREAM_BODY",
+        message: "Streaming requires a response with a readable body. The configured `options.fetch` returned one whose body is absent or already read \u2014 an implementation that buffers or consumes the response cannot be used for `.stream()` or `.liveQuery()`.",
+        retryable: false
+      });
+      releaseBody(res);
+      return { liveMs: 0, terminal: true };
+    }
+    this._emitStatus("live");
+    const openedAt = Date.now();
+    await this._pump(body);
+    return { liveMs: Date.now() - openedAt, terminal: false };
+  }
+  /** Resolve the stream URL. Throws on a `baseURL` that isn't a usable http(s) origin. */
+  _url() {
+    const url = resolveURL(this._opts.baseURL, "/v1/stream");
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new Error(
+        `baseURL must use http or https, got "${url.protocol}". Streaming is plain HTTP \u2014 there is no WebSocket endpoint.`
+      );
+    }
     url.searchParams.set("table", this._opts.table);
     if (this._opts.since) {
       url.searchParams.set("since", this._opts.since);
     }
+    return url.toString();
+  }
+  /** Build the request init, minting a token for this attempt. */
+  async _init(signal) {
+    const base = { Accept: "text/event-stream" };
     if (this._opts.auth) {
       const token = await this._opts.auth();
       if (token) {
-        url.searchParams.set("token", token);
+        base.Authorization = `Bearer ${token}`;
       }
     }
-    activeSSEConnections++;
-    if (activeSSEConnections > SSE_WARN_THRESHOLD) {
-      console.warn(
-        `[wavehouse] ${activeSSEConnections} SSE connections open. Browsers limit HTTP/1.1 to 6 connections per domain.`
-      );
+    if (this._lastEventId) {
+      base["Last-Event-ID"] = this._lastEventId;
     }
-    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);
-      }
+    const credentialed = base.Authorization !== void 0 || Object.keys(this._opts.headers ?? {}).length > 0;
+    const init = {
+      ...this._opts.fetchOptions,
+      method: "GET",
+      headers: mergeHeaders(base, this._opts.headers),
+      signal,
+      // Owned by the SDK rather than left to `fetchOptions`, unlike the REST
+      // path, because on a stream these are correctness rather than preference:
+      //
+      //   cache    — as an init field, not a `Cache-Control` header. The header
+      //              form is not in the server's Access-Control-Allow-Headers,
+      //              so it would fail every cross-origin preflight.
+      //   redirect — followed only when this request carries no credential.
+      //              Platforms strip `Authorization` on a cross-origin redirect
+      //              (whatwg/fetch#1544) and forward other headers intact, so a
+      //              credentialed hop either silently downgrades the stream to
+      //              the default role — this endpoint answers an unauthenticated
+      //              caller rather than rejecting them — or delivers a configured
+      //              secret to whatever the redirect names. Neither is worth a
+      //              convenience. Without either, redirects are followed, so CDN
+      //              canonicalization, geo/LB indirection, and an http→https
+      //              upgrade all just work. The test is deliberately that
+      //              concrete pair and not "is this authenticated": cookies do
+      //              not appear in it. A cookie is re-derived per
+      //              destination rather than carried, so under the default
+      //              same-origin credentials mode it survives a redirect only
+      //              while the hop stays inside both the request's origin and
+      //              the cookie's Path; outside either the stream is
+      //              silently unauthed. See #478 and the SDK guide under
+      //              "Supplying your own fetch".
+      //              `manual` over `error` for the credentialed case so the
+      //              outcome stays inspectable: `error` rejects with a bare
+      //              TypeError indistinguishable from a connection failure, which
+      //              the loop above would retry forever against a redirect that
+      //              is never going to stop happening.
+      cache: "no-store",
+      redirect: credentialed ? "manual" : "follow",
+      // Neutralized like the REST path does, and for a sharper reason here: a
+      // body on a GET makes `fetch` throw, which reads as a network failure and
+      // would be retried forever against a request that can never be built.
+      body: void 0
     };
-    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?.({
+    if (!("window" in globalThis)) {
+      delete init.credentials;
+    }
+    return init;
+  }
+  /** Decode and parse frames until the stream ends, aborts, or errors. */
+  async _pump(body) {
+    let overflowed = false;
+    const parser = createParser({
+      onEvent: (msg) => {
+        if (msg.id) this._lastEventId = msg.id;
+        if (!msg.data) return;
+        this._dispatch(msg.data);
+      },
+      onRetry: (ms) => {
+        this._retryFloorMs = Math.min(Math.max(ms, 0), MAX_BACKOFF_MS);
+      },
+      onError: (err2) => {
+        if (err2.type === "max-buffer-size-exceeded") overflowed = true;
+        this._emitError({
           status: 0,
-          code: "SSE_ERROR",
-          message: "SSE connection error",
+          code: "SSE_PARSE_ERROR",
+          message: err2.message,
           retryable: true
         });
+      },
+      maxBufferSize: MAX_BUFFER_CHARS
+    });
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) return;
+        parser.feed(decoder.decode(value, { stream: true }));
+        if (overflowed) return;
       }
-    };
+    } catch (e) {
+      if (this._closed) return;
+      this._emitError({
+        status: 0,
+        code: "SSE_READ_ERROR",
+        message: e instanceof Error ? e.message : String(e),
+        retryable: true
+      });
+    } finally {
+      reader.cancel().catch(() => {
+      });
+    }
+  }
+  /**
+   * Turn one frame's `data` into a StreamEvent.
+   *
+   * Guarded like `_emitError` and `_emitStatus`: `parser.feed()` dispatches
+   * every complete frame in a chunk synchronously, so a subscriber that closes
+   * from inside its own `next` — "read until I see my event, then stop" —
+   * would otherwise keep receiving the rest of that chunk. `EventSource` ended
+   * delivery on `close()`, and gap-fill replay routinely lands many frames in
+   * one chunk.
+   */
+  _dispatch(data) {
+    if (this._closed) return;
+    let event;
+    try {
+      const msg = JSON.parse(data);
+      event = { table: msg.table_name, timestamp: msg.received_timestamp, data: msg.data };
+    } catch {
+      console.warn("[wavehouse] SSE received malformed message:", data);
+      return;
+    }
+    try {
+      this.onEvent?.(event);
+    } catch (e) {
+      console.error("[wavehouse] SSE event handler threw:", e);
+    }
+  }
+  /** Suppress callbacks that race a `disconnect()`. */
+  _emitError(error) {
+    if (this._closed) return;
+    try {
+      this.onError?.(error);
+    } catch (e) {
+      console.error("[wavehouse] SSE error handler threw:", e);
+    }
+  }
+  /**
+   * Same guard for status. Aborting does not retract an already-resolved
+   * `Response`, so a `disconnect()` landing between the fetch settling and the
+   * "live" below would otherwise flip a closed controller back to live — and it
+   * stays there, since the loop then exits without emitting anything further.
+   * `disconnect()` calls `onStatus` directly; that terminal "closed" is the one
+   * status that must always get through.
+   */
+  _emitStatus(status) {
+    if (this._closed) return;
+    try {
+      this.onStatus?.(status);
+    } catch (e) {
+      console.error("[wavehouse] SSE status handler threw:", e);
+    }
+  }
+  /** Wait out a reconnect gap, cut short by `disconnect()`. */
+  _sleep(ms) {
+    if (this._closed) return Promise.resolve();
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this._wake = null;
+        resolve();
+      }, ms);
+      this._wake = () => {
+        clearTimeout(timer);
+        this._wake = null;
+        resolve();
+      };
+    });
   }
 };
 
@@ -690,6 +1025,15 @@ var QueryBuilder = class _QueryBuilder {
   select(...columns) {
     return this._clone({ columns: [...this._state.columns, ...columns] });
   }
+  /**
+   * 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() {
+    return this._clone({ selectAll: true });
+  }
   where(column, op, value) {
     const filter = { column, op: OP_MAP[op], value };
     return this._clone({ filters: [...this._state.filters, filter] });
@@ -731,7 +1075,7 @@ var QueryBuilder = class _QueryBuilder {
     return this._clone({ cacheTTL: seconds });
   }
   // --- Execution ---
-  /** 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 DEFAULT_LIMIT = 1e3;
   async fetch(opts) {
     const effectiveLimit = opts?.limit ?? this._state.limit ?? _QueryBuilder.DEFAULT_LIMIT;
@@ -788,8 +1132,16 @@ var QueryBuilder = class _QueryBuilder {
   }
   _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;
+    const hasColumns = this._state.columns.length > 0;
+    const hasAggs = this._state.aggregations.length > 0;
+    if (this._state.selectAll) {
+      ast.select_all = true;
+    } else if (hasColumns) {
+      ast.columns = this._state.columns;
+    } else if (!hasAggs) {
+      ast.select_all = true;
+    }
+    if (hasAggs) 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;
@@ -899,6 +1251,12 @@ function projectColumns(row, columns) {
 }
 
 // src/table.ts
+var NDJSON_CONTENT_TYPE = "application/x-ndjson";
+async function ndjsonSourceToString(source) {
+  if (typeof source === "string") return source;
+  if (source instanceof Uint8Array) return new TextDecoder().decode(source);
+  return new Response(source).text();
+}
 var TableRef = class {
   _ctx;
   _table;
@@ -927,22 +1285,34 @@ var TableRef = class {
       this._createStream
     );
   }
-  /** 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() {
+    return this.select().selectAll();
+  }
+  /**
+   * 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}.
+   */
   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);
+      if (data.length === 0) {
+        return ok({ ok: true, total: 0, succeeded: 0, failed: 0, duplicates: 0, results: [] });
       }
-      return ok({ ok: true });
+      const ndjson = data.map((row) => JSON.stringify(row)).join("\n");
+      return this._sendNDJSON(ndjson, opts);
     }
     const { data: res, error } = await request(this._ctx, {
       method: "POST",
@@ -955,11 +1325,51 @@ var TableRef = class {
     if (res?.duplicate != null) result.duplicate = res.duplicate;
     return ok(result);
   }
+  /**
+   * 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`.
+   */
+  async insertNDJSON(source, opts) {
+    const ndjson = await ndjsonSourceToString(source);
+    return this._sendNDJSON(ndjson, opts);
+  }
+  /**
+   * @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`.
+   */
+  async _sendNDJSON(ndjson, opts) {
+    const { data, error } = await request(this._ctx, {
+      method: "POST",
+      path: `/v1/ingest?table=${encodeURIComponent(this._table)}`,
+      rawBody: ndjson,
+      contentType: NDJSON_CONTENT_TYPE,
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    const r = data ?? { total: 0, succeeded: 0, failed: 0, duplicates: 0 };
+    const result = {
+      ok: r.failed === 0,
+      total: r.total,
+      succeeded: r.succeeded,
+      failed: r.failed,
+      duplicates: r.duplicates
+    };
+    if (r.results && r.results.length > 0) result.results = r.results;
+    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)}`,
+      path: `/v1/ops/schema?table=${encodeURIComponent(this._table)}`,
       signal: opts?.signal
     });
     if (error) return err(error);
@@ -990,7 +1400,10 @@ var WaveHouseClient = class {
       baseURL: config.baseURL.replace(/\/+$/, ""),
       auth: config.auth,
       options: {
-        maxRetries: config.options?.maxRetries ?? 2
+        maxRetries: config.options?.maxRetries ?? 2,
+        fetch: config.options?.fetch,
+        headers: config.options?.headers,
+        fetchOptions: config.options?.fetchOptions
       }
     };
     this.schema = new SchemaNamespace(this._ctx);
@@ -1022,23 +1435,21 @@ var WaveHouseClient = class {
   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."
+        "[WaveHouse SDK] client.sql(sql, params) was removed. The /v1/ops/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
+      auth: this._ctx.auth,
+      fetch: this._ctx.options.fetch,
+      headers: this._ctx.options.headers,
+      fetchOptions: this._ctx.options.fetchOptions
     });
     const controller = new StreamController(transport);
     if (opts?.signal) controller.attachSignal(opts.signal);