@wavehouse/sdk 0.1.0 → 0.2.0

package/README.md

@@ -10,7 +10,7 @@ npm install @wavehouse/sdk
 
 Requires Node 22 or newer — the only line this SDK is tested against; Node 18 and 20 are past upstream end-of-life. Neither browsers nor Node need a polyfill: streaming runs on `fetch`, like the rest of the SDK — see [Runtime support](https://wavehouse.dev/sdk/#runtime-support).
 
-This works in any framework that uses a bundler — React, Vue, Svelte, Angular, Astro, SolidJS, or plain Vite — with `import { createClient } from '@wavehouse/sdk'`.
+This works in any framework that uses a bundler — React, Vue, Svelte, Angular, Astro, SolidJS, or plain Vite — with `import { createClient } from '@wavehouse/sdk'`. The SDK and the server share the SSE wire protocol, so move them as a **pair** — a skewed pair delivers no usable rows and raises no error ([details](https://wavehouse.dev/sdk/streaming)).
 
 The package is published with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) — npm shows a verified provenance badge on the [package page](https://www.npmjs.com/package/@wavehouse/sdk), and `npm audit signatures` checks the attestation against this repository's signed build.
 
@@ -30,7 +30,7 @@ No bundler, no `npm`, no framework required — drop the SDK straight into an HT
 </script>
 ```
 
-Pin a version for production (`https://esm.sh/@wavehouse/sdk@0.1.0`). jsDelivr (`https://cdn.jsdelivr.net/npm/@wavehouse/sdk/+esm`) and unpkg (`https://unpkg.com/@wavehouse/sdk?module`) serve the same ES module.
+Pin a version for production (`https://esm.sh/@wavehouse/sdk@0.2.0`). jsDelivr (`https://cdn.jsdelivr.net/npm/@wavehouse/sdk/+esm`) and unpkg (`https://unpkg.com/@wavehouse/sdk?module`) serve the same ES module. The SDK and the server share the SSE wire protocol, so pin them as a **pair** — a skewed pair delivers no usable rows and raises no error.
 
 **Classic global (`<script src>`).** For pages that can't use ES modules, the bundled IIFE build attaches everything to a `WaveHouse` global:
 
@@ -42,7 +42,7 @@ Pin a version for production (`https://esm.sh/@wavehouse/sdk@0.1.0`). jsDelivr (
 </script>
 ```
 
-**Versioning.** A bare CDN URL serves the latest published **release**; pin for production (`@wavehouse/sdk@0.1.0`) or float on a range (`@0` for the newest 0.x, `@0.1` for 0.1.x). Builds from `main` are published under the `dev` tag — `@wavehouse/sdk@dev` — for trying unreleased changes.
+**Versioning.** A bare CDN URL serves the latest published **release**; pin for production (`@wavehouse/sdk@0.2.0`) or float on a range (`@0` for the newest 0.x, `@0.2` for 0.2.x). Builds from `main` are published under the `dev` tag — `@wavehouse/sdk@dev` — for trying unreleased changes. Whichever you choose, move the SDK and the server together: they share the SSE wire protocol, and a skewed pair delivers no usable rows and raises no error — a newer SDK drops every row, an older one hands you an event per frame with `data: undefined`.
 
 Streaming (`.stream()`) runs on `fetch`, so it works in both forms with no polyfill.
 
@@ -150,7 +150,7 @@ Generate TypeScript types from your live WaveHouse schema. The package ships a `
 npx wavehouse-codegen --url http://localhost:8080 --out ./src/db.d.ts
 ```
 
-This introspects `/v1/ops/schema`, maps ClickHouse column types to TypeScript, and outputs a `Database` interface you can pass to `createClient<Database>()`. `/v1/ops/schema` is **admin-only** — pass an admin-role token with `--auth <jwt>` (or `-a`) against any non-dev policy.
+This introspects `/v1/ops/schema`, maps ClickHouse column types to TypeScript, and outputs a `Database` interface you can pass to `createClient<Database>()`. `/v1/ops/schema` is **admin-only** — pass an admin-role token with `--auth <jwt>` (or `-a`) against any non-dev policy. Over a nested settings directory the route admits the operator key alone: pass it with `--operator-key <key>` (or `-k`) and name the tenant with `--tenant <id>` (or `-t`); without `--tenant` it reads tenant `0`'s schema.
 
 ## Development & Testing
 
@@ -164,6 +164,10 @@ npm run test:watch     # watch mode
 npm run test:coverage  # coverage report
 ```
 
+### Built Package Smoke Check
+
+`make smoke-ts-dist` (run by `make build-ts`) imports and `require()`s the built package by name (through its `exports` map) and runs the IIFE bundle as a classic script, at the oldest Node that `engines.node` admits, and checks that all three export the same names. It also type-checks a CommonJS and an ESM consumer of the package with `tsc --module node16`, so a CommonJS project (`"type": "commonjs"`) gets its own `.d.cts` declarations rather than TS1479. It downloads that Node once into `.bin/`. `pnpm run smoke:dist` runs the same check on the Node you are running.
+
 ### E2E Integration Tests
 
 E2E tests live in `tests/e2e/sdk/` (repo root) and exercise the full pipeline through the SDK. See `make test-e2e` in the [Development Guide](https://wavehouse.dev/development#e2e-tests-via-sdk).

package/dist/cli/codegen.js

@@ -20,31 +20,61 @@ function resolveURL(base, path, params) {
 }
 
 // src/cli/codegen.ts
+var FLAGS = /* @__PURE__ */ new Set([
+  "--url",
+  "-u",
+  "--out",
+  "-o",
+  "--auth",
+  "-a",
+  "--tenant",
+  "-t",
+  "--operator-key",
+  "-k",
+  "--help",
+  "-h"
+]);
+function operand(value, usage) {
+  if (!value || FLAGS.has(value)) throw new Error(usage);
+  return value;
+}
 function parseArgs(argv) {
   const args = { url: "http://localhost:8080", out: "./wavehouse.d.ts" };
   for (let i = 2; i < argv.length; i++) {
     switch (argv[i]) {
       case "--url":
       case "-u":
-        args.url = argv[++i];
+        args.url = operand(argv[++i], "--url needs a URL");
         break;
       case "--out":
       case "-o":
-        args.out = argv[++i];
+        args.out = operand(argv[++i], "--out needs a file path");
         break;
       case "--auth":
       case "-a":
-        args.auth = argv[++i];
+        args.auth = operand(argv[++i], "--auth needs a token");
+        break;
+      case "--tenant":
+      case "-t":
+        args.tenant = operand(argv[++i], "--tenant needs a tenant id");
+        break;
+      case "--operator-key":
+      case "-k":
+        args.operatorKey = operand(argv[++i], "--operator-key needs a key");
         break;
       case "--help":
       case "-h":
         console.log(`wavehouse codegen \u2014 Generate TypeScript types from WaveHouse schema
 
 Options:
-  --url, -u   WaveHouse base URL (default: http://localhost:8080)
-  --out, -o   Output file path   (default: ./wavehouse.d.ts)
-  --auth, -a  Bearer token for authenticated endpoints
-  --help, -h  Show this help`);
+  --url, -u           WaveHouse base URL (default: http://localhost:8080)
+  --out, -o           Output file path   (default: ./wavehouse.d.ts)
+  --auth, -a          Bearer token for authenticated endpoints
+  --operator-key, -k  Operator key, sent as X-Operator-Key (the credential a
+                      nested settings directory's /v1/ops/* routes admit)
+  --tenant, -t        Tenant whose schema to read, sent as ?tenant=
+                      (default: tenant 0)
+  --help, -h          Show this help`);
         process.exit(0);
     }
   }
@@ -121,10 +151,26 @@ function isTableSchema(value) {
   const table = value;
   return typeof table.name === "string" && Array.isArray(table.columns) && table.columns.every(isColumn);
 }
-async function fetchSchemas(url, auth) {
+async function fetchSchemas(url, opts = {}) {
   const headers = {};
-  if (auth) headers.Authorization = `Bearer ${auth}`;
-  const res = await fetch(resolveURL(url, "/v1/ops/schema").toString(), { headers });
+  if (opts.auth) headers.Authorization = `Bearer ${opts.auth}`;
+  if (opts.operatorKey) headers["X-Operator-Key"] = opts.operatorKey;
+  const target = resolveURL(
+    url,
+    "/v1/ops/schema",
+    opts.tenant ? { tenant: opts.tenant } : void 0
+  );
+  const credentialed = Boolean(opts.auth || opts.operatorKey);
+  const res = await fetch(target.toString(), {
+    headers,
+    redirect: credentialed ? "manual" : "follow"
+  });
+  if (credentialed && res.status >= 300 && res.status < 400) {
+    const location = res.headers.get("location") ?? "an unnamed location";
+    throw new Error(
+      `Schema fetch was redirected (${res.status}) to ${location}, and a request carrying a credential does not follow a redirect: point --url at the final address`
+    );
+  }
   if (!res.ok) {
     const text = await res.text();
     throw new Error(`Schema fetch failed (${res.status}): ${text}`);
@@ -168,7 +214,11 @@ function pascalCase(s) {
 async function main() {
   const args = parseArgs(process.argv);
   console.log(`Fetching schema from ${args.url}...`);
-  const schemas = await fetchSchemas(args.url, args.auth);
+  const schemas = await fetchSchemas(args.url, {
+    auth: args.auth,
+    operatorKey: args.operatorKey,
+    tenant: args.tenant
+  });
   if (schemas.length === 0) {
     console.warn("No tables found. Is WaveHouse running with tables in ClickHouse?");
     process.exit(1);
@@ -198,5 +248,6 @@ if (isDirectInvocation()) {
 export {
   chTypeToTS,
   fetchSchemas,
-  generateTypes
+  generateTypes,
+  parseArgs
 };

package/dist/index.cjs

@@ -24,9 +24,9 @@ __export(src_exports, {
   LiveQuery: () => LiveQuery,
   PipeRef: () => PipeRef,
   PipesNamespace: () => PipesNamespace,
-  PolicyNamespace: () => PolicyNamespace,
   QueryBuilder: () => QueryBuilder,
   SchemaNamespace: () => SchemaNamespace,
+  SettingsNamespace: () => SettingsNamespace,
   StreamController: () => StreamController,
   SysNamespace: () => SysNamespace,
   TableRef: () => TableRef,
@@ -44,10 +44,11 @@ async function parseErrorResponse(res) {
     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;
+  const code = typeof body?.code === "string" && body.code !== "" ? body.code : `HTTP_${res.status}`;
+  const retryable = typeof body?.retryable === "boolean" ? body.retryable : res.status >= 500;
   return {
     status: res.status,
-    code: `HTTP_${res.status}`,
+    code,
     message,
     details: body,
     retryable
@@ -103,6 +104,9 @@ function mergeHeaders(base, extra) {
   }
   return merged;
 }
+function tenantParam(opts) {
+  return opts?.tenant === void 0 ? void 0 : { tenant: opts.tenant };
+}
 function abortedResult() {
   return {
     data: null,
@@ -206,22 +210,26 @@ var DLQNamespace = class {
     this._ctx = ctx;
     this._createStream = createStream;
   }
-  /** Get DLQ statistics (message counts per table). */
+  /**
+   * Get DLQ statistics (message counts per table) — of `opts.tenant`, the
+   * default tenant without it. A tenant with no dead-letter queue is a `404`.
+   */
   async list(opts) {
     const { data, error } = await request(this._ctx, {
       method: "GET",
       path: "/v1/ops/dlq/stats",
+      params: tenantParam(opts),
       signal: opts?.signal
     });
     if (error) return err(error);
     return ok(data);
   }
-  /** Get DLQ stats filtered by table name. */
+  /** Get DLQ stats filtered by table name — of `opts.tenant`, the default tenant without it. */
   async table(name, opts) {
     const { data, error } = await request(this._ctx, {
       method: "GET",
       path: "/v1/ops/dlq/stats",
-      params: { table: name },
+      params: { table: name, ...tenantParam(opts) },
       signal: opts?.signal
     });
     if (error) return err(error);
@@ -276,82 +284,23 @@ var PipesNamespace = class {
   constructor(ctx) {
     this._ctx = ctx;
   }
-  /** List all registered pipes. */
+  /** List all registered pipes — of `opts.tenant`, the default tenant without it. */
   async list(opts) {
     const { data, error } = await request(this._ctx, {
       method: "GET",
       path: "/v1/ops/pipes",
+      params: tenantParam(opts),
       signal: opts?.signal
     });
     if (error) return err(error);
     return ok(data);
   }
-  /** Get a single pipe definition by name. */
+  /** Get a single pipe definition by name — of `opts.tenant`, the default tenant without it. */
   async get(name, opts) {
     const { data, error } = await request(this._ctx, {
       method: "GET",
       path: `/v1/ops/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/ops/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/ops/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/ops/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/ops/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/ops/policy/validate",
-      body: policy,
+      params: tenantParam(opts),
       signal: opts?.signal
     });
     if (error) return err(error);
@@ -365,11 +314,16 @@ var SchemaNamespace = class {
   constructor(ctx) {
     this._ctx = ctx;
   }
-  /** List all table schemas discovered from ClickHouse. */
+  /**
+   * List all table schemas discovered from ClickHouse — `opts.tenant`'s, the
+   * default tenant's without it. A `503` with `Retry-After` is a tenant whose
+   * first discovery has not succeeded yet.
+   */
   async list(opts) {
     const { data, error } = await request(this._ctx, {
       method: "GET",
       path: "/v1/ops/schema",
+      params: tenantParam(opts),
       signal: opts?.signal
     });
     if (error) return err(error);
@@ -386,11 +340,15 @@ var SchemaNamespace = class {
     }
     return ok(schemas);
   }
-  /** Force a schema refresh from ClickHouse system.columns. */
+  /**
+   * Force a schema refresh from ClickHouse system.columns — of `opts.tenant`,
+   * the default tenant without it.
+   */
   async refresh(opts) {
     const { error } = await request(this._ctx, {
       method: "POST",
       path: "/v1/ops/schema/refresh",
+      params: tenantParam(opts),
       signal: opts?.signal
     });
     if (error) return err(error);
@@ -398,11 +356,40 @@ var SchemaNamespace = class {
   }
 };
 
+// src/settings.ts
+var SettingsNamespace = class {
+  _ctx;
+  constructor(ctx) {
+    this._ctx = ctx;
+  }
+  /**
+   * Re-validate and adopt the settings directory (POST /v1/ops/settings/reload).
+   * Resolves with `{ adopted: true, findings }` when adopted (warnings
+   * included); a rejected directory is a 422 error whose `details` carries the
+   * same `{ adopted: false, findings }` body, and the previous settings stay
+   * in effect.
+   *
+   * `opts.tenant` reloads that tenant's folder alone; without it the whole
+   * directory is reloaded.
+   */
+  async reload(opts) {
+    const { data, error } = await request(this._ctx, {
+      method: "POST",
+      path: "/v1/ops/settings/reload",
+      params: tenantParam(opts),
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    return ok(data);
+  }
+};
+
 // src/sql.ts
 async function sql(ctx, query, opts) {
   const { data, error } = await request(ctx, {
     method: "POST",
     path: "/v1/ops/query",
+    params: tenantParam(opts),
     body: { sql: query },
     signal: opts?.signal
   });
@@ -609,6 +596,30 @@ var SSETransport = class {
   _retryFloorMs = 0;
   /** Cuts a reconnect gap short when set — see `_sleep`. */
   _wake = null;
+  /**
+   * Column names for the rows currently arriving, from the most recent
+   * `event: schema` frame. Rows travel positionally, so this is what turns one
+   * back into an object; `null` means none has been announced yet, and a data
+   * frame arriving in that state is unreadable rather than merely unlabeled.
+   *
+   * Reset at the start of every connection attempt: a reconnect re-announces,
+   * and zipping a new connection's rows under the previous one's list would
+   * silently mislabel every value.
+   */
+  _columns = null;
+  /**
+   * Per-cause warning budget for the current connection. A server that predates
+   * the positional wire sends every row without a schema event, so an unbounded
+   * `console.warn` per row floods the console for the whole connection — and so
+   * does any other per-frame warn against a server sending something the reader
+   * cannot use. Every PER-FRAME warn site is bounded, but keyed by CAUSE so a row
+   * with no announcement, a short row, a long row, a non-array row, a malformed
+   * schema frame and unparseable JSON stay individually visible: collapsing them
+   * behind one flag would hide the distinct failures the warning exists to
+   * surface. Reset per attempt. (The per-connect() notices are not per-frame and
+   * are not bounded here.)
+   */
+  _warnBudget = /* @__PURE__ */ new Map();
   onEvent = null;
   onStatus = null;
   onError = null;
@@ -674,10 +685,26 @@ var SSETransport = class {
       attempt++;
     }
   }
+  /**
+   * Warn at most `LIMIT` times per cause per connection, then once more to say
+   * how many were suppressed. Returns nothing — callers warn and bail as before.
+   */
+  _warnBounded(cause, message, data) {
+    const LIMIT = 3;
+    const seen = (this._warnBudget.get(cause) ?? 0) + 1;
+    this._warnBudget.set(cause, seen);
+    if (seen <= LIMIT) {
+      console.warn(message, data);
+    } else if (seen === LIMIT + 1) {
+      console.warn(`${message} \u2014 further occurrences suppressed for this connection`);
+    }
+  }
   /** One connection attempt: request, validate, then pump frames until it ends. */
   async _attempt() {
     const ac = new AbortController();
     this._abort = ac;
+    this._columns = null;
+    this._warnBudget.clear();
     let target;
     try {
       target = this._url();
@@ -839,6 +866,10 @@ var SSETransport = class {
       onEvent: (msg) => {
         if (msg.id) this._lastEventId = msg.id;
         if (!msg.data) return;
+        if (msg.event === "schema") {
+          this._applySchema(msg.data);
+          return;
+        }
         this._dispatch(msg.data);
       },
       onRetry: (ms) => {
@@ -877,9 +908,39 @@ var SSETransport = class {
       });
     }
   }
+  /**
+   * Record the column list an `event: schema` frame announces. Rows that follow
+   * are zipped against it, so a malformed announcement drops the list rather
+   * than keeping a stale one: mislabeling values is worse than delivering none.
+   */
+  _applySchema(data) {
+    try {
+      const msg = JSON.parse(data);
+      if (!Array.isArray(msg.columns) || msg.columns.some((c) => typeof c !== "string")) {
+        throw new Error("columns must be an array of strings");
+      }
+      if (new Set(msg.columns).size !== msg.columns.length) {
+        throw new Error("columns contains a duplicate name");
+      }
+      this._columns = msg.columns;
+    } catch {
+      this._columns = null;
+      this._warnBounded(
+        "bad-schema-frame",
+        "[wavehouse] SSE received a malformed schema event:",
+        data
+      );
+    }
+  }
   /**
    * Turn one frame's `data` into a StreamEvent.
    *
+   * The row arrives positionally — a JSON array — and is zipped back into an
+   * object against the announced column list, so the public API still yields
+   * row objects. A row with no announcement, or one whose length disagrees with
+   * the list, cannot be read: there is no way to say which value is which, so
+   * it is dropped rather than delivered under guessed names.
+   *
    * 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" —
@@ -892,9 +953,34 @@ var SSETransport = class {
     let event;
     try {
       const msg = JSON.parse(data);
-      event = { table: msg.table_name, timestamp: msg.received_timestamp, data: msg.data };
+      const columns = this._columns;
+      if (!columns) {
+        this._warnBounded(
+          "no-schema",
+          "[wavehouse] SSE received a row before any schema event:",
+          data
+        );
+        return;
+      }
+      if (!Array.isArray(msg.row)) {
+        this._warnBounded("row-not-array", "[wavehouse] SSE row is not an array:", data);
+        return;
+      }
+      if (msg.row.length !== columns.length) {
+        this._warnBounded(
+          msg.row.length < columns.length ? "row-short" : "row-long",
+          `[wavehouse] SSE row has ${msg.row.length} value(s) but ${columns.length} column(s) were announced:`,
+          data
+        );
+        return;
+      }
+      const row = /* @__PURE__ */ Object.create(null);
+      for (let i = 0; i < columns.length; i++) {
+        row[columns[i]] = msg.row[i];
+      }
+      event = { table: msg.table_name, timestamp: msg.received_timestamp, data: row };
     } catch {
-      console.warn("[wavehouse] SSE received malformed message:", data);
+      this._warnBounded("bad-json", "[wavehouse] SSE received malformed message:", data);
       return;
     }
     try {
@@ -1280,7 +1366,7 @@ function compareOrdered(actual, expected, cmp) {
   return false;
 }
 function projectColumns(row, columns) {
-  const result = {};
+  const result = /* @__PURE__ */ Object.create(null);
   for (const col of columns) {
     if (col in row) result[col] = row[col];
   }
@@ -1288,6 +1374,7 @@ function projectColumns(row, columns) {
 }
 
 // src/table.ts
+var JSON_CONTENT_TYPE = "application/json";
 var NDJSON_CONTENT_TYPE = "application/x-ndjson";
 async function ndjsonSourceToString(source) {
   if (typeof source === "string") return source;
@@ -1339,8 +1426,10 @@ var TableRef = class {
    * 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
+   * The array path sends one request regardless of size, so it is bound by the
+   * server's 16 MiB request-body cap (an over-cap array is a `413` with nothing
+   * ingested); 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) {
@@ -1355,6 +1444,9 @@ var TableRef = class {
       method: "POST",
       path: `/v1/ingest?table=${encodeURIComponent(this._table)}`,
       body: data,
+      // Ingest requires a declared format — an undeclared Content-Type is a
+      // 415 — so state it here rather than leaning on the request default.
+      contentType: JSON_CONTENT_TYPE,
       signal: opts?.signal
     });
     if (error) return err(error);
@@ -1368,9 +1460,11 @@ var TableRef = class {
    * 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`.
+   * Non-string sources are read fully into memory before sending. The server
+   * buffers the whole body too, so the request-body cap applies to NDJSON
+   * exactly as to any other shape — an upload over it is a `413` with nothing
+   * ingested, and must be split across several calls. Returns the same
+   * per-record batch summary as an array `insert`.
    */
   async insertNDJSON(source, opts) {
     const ndjson = await ndjsonSourceToString(source);
@@ -1402,11 +1496,12 @@ var TableRef = class {
     if (r.results && r.results.length > 0) result.results = r.results;
     return ok(result);
   }
-  /** Fetch the schema for this table. */
+  /** Fetch the schema for this table — under `opts.tenant`, the default tenant without it. */
   async schema(opts) {
     const { data, error } = await request(this._ctx, {
       method: "GET",
-      path: `/v1/ops/schema?table=${encodeURIComponent(this._table)}`,
+      path: "/v1/ops/schema",
+      params: { table: this._table, ...tenantParam(opts) },
       signal: opts?.signal
     });
     if (error) return err(error);
@@ -1424,14 +1519,14 @@ var WaveHouseClient = class {
   _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;
+  /** Settings directory namespace (admin). */
+  settings;
   constructor(config) {
     this._ctx = {
       baseURL: config.baseURL.replace(/\/+$/, ""),
@@ -1444,10 +1539,10 @@ var WaveHouseClient = class {
       }
     };
     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);
+    this.settings = new SettingsNamespace(this._ctx);
   }
   /** Get a table reference for building queries, inserts, and streams. */
   from(table) {
@@ -1467,7 +1562,9 @@ var WaveHouseClient = class {
    * `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.
+   * builder for safe binding. See sql.ts for details. `opts.tenant` names the
+   * tenant whose ClickHouse the SQL runs against, the default tenant without
+   * it.
    */
   sql(query, opts) {
     if (Array.isArray(opts)) {
@@ -1502,9 +1599,9 @@ function createClient(config) {
   LiveQuery,
   PipeRef,
   PipesNamespace,
-  PolicyNamespace,
   QueryBuilder,
   SchemaNamespace,
+  SettingsNamespace,
   StreamController,
   SysNamespace,
   TableRef,