@wavehouse/sdk 0.1.1 → 0.2.0

package/dist/index.js

@@ -7,10 +7,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
@@ -66,6 +67,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,
@@ -169,22 +173,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);
@@ -239,82 +247,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);
@@ -328,11 +277,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);
@@ -349,11 +303,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);
@@ -361,11 +319,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
   });
@@ -572,6 +559,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;
@@ -637,10 +648,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();
@@ -802,6 +829,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) => {
@@ -840,9 +871,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" —
@@ -855,9 +916,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 {
@@ -1243,7 +1329,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];
   }
@@ -1251,6 +1337,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;
@@ -1302,8 +1389,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) {
@@ -1318,6 +1407,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);
@@ -1331,9 +1423,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);
@@ -1365,11 +1459,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);
@@ -1387,14 +1482,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(/\/+$/, ""),
@@ -1407,10 +1502,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) {
@@ -1430,7 +1525,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)) {
@@ -1464,9 +1561,9 @@ export {
   LiveQuery,
   PipeRef,
   PipesNamespace,
-  PolicyNamespace,
   QueryBuilder,
   SchemaNamespace,
+  SettingsNamespace,
   StreamController,
   SysNamespace,
   TableRef,