@wavehouse/sdk 0.0.0-dev.h514be5522d89 → 0.0.0-dev.h70dbf5d8f5ed

package/README.md

@@ -8,8 +8,12 @@ Zero-dependency TypeScript client for [WaveHouse](https://github.com/Wave-RF/Wav
 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. Browsers need no polyfill, and Node needs an `EventSource` polyfill only for streaming — 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'`.
 
+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.
+
 ## Use without a build step (CDN)
 
 No bundler, no `npm`, no framework required — drop the SDK straight into an HTML file you deploy over FTP, object storage, or any static host.
@@ -53,6 +57,8 @@ const wh = createClient({
 });
 ```
 
+`baseURL` may include a path prefix (`https://app.example.com/api/warehouse`) when WaveHouse is served under one — see [Serving under a path prefix](https://wavehouse.dev/sdk#serving-under-a-path-prefix).
+
 ### Query Data
 
 ```ts
@@ -123,7 +129,9 @@ const { data } = await wh.from('clicks').select('page').limit(10);
 
 ## Error Handling
 
-All operations return `{ data, error }` tuples — the SDK never throws.
+Async request methods return a `Result<T>` object — destructure it as `{ data, error }` — and never throw for anything the server returns. `.stream()` and `.liveQuery()` return controllers instead, reporting failures through the subscriber's `error` callback.
+
+The SDK does throw on caller and environment errors: a non-absolute `baseURL` (REST calls reject with a `TypeError`; streams report `SSE_CONNECT_ERROR`, and despite that error's `retryable: true` the SDK never re-dials the stream itself), `.stream()` / `.liveQuery()` in a runtime with no `EventSource`, and an `auth` callback that rejects — a token-refresh failure propagates out of the REST call.
 
 ```ts
 const { data, error } = await wh.from('clicks').fetch();
@@ -142,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/schema`, maps ClickHouse column types to TypeScript, and outputs a `Database` interface you can pass to `createClient<Database>()`. `/v1/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.
 
 ## Development & Testing
 

package/dist/cli/codegen.js

@@ -1,5 +1,24 @@
 #!/usr/bin/env node
 
+// src/cli/codegen.ts
+import { realpathSync } from "fs";
+import { pathToFileURL } from "url";
+
+// 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/cli/codegen.ts
 function parseArgs(argv) {
   const args = { url: "http://localhost:8080", out: "./wavehouse.d.ts" };
@@ -92,15 +111,29 @@ function findTopLevelComma(s) {
   }
   return -1;
 }
+function isColumn(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const col = value;
+  return typeof col.name === "string" && typeof col.type === "string";
+}
+function isTableSchema(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const table = value;
+  return typeof table.name === "string" && Array.isArray(table.columns) && table.columns.every(isColumn);
+}
 async function fetchSchemas(url, auth) {
   const headers = {};
   if (auth) headers.Authorization = `Bearer ${auth}`;
-  const res = await fetch(`${url.replace(/\/+$/, "")}/v1/schema`, { headers });
+  const res = await fetch(resolveURL(url, "/v1/ops/schema").toString(), { headers });
   if (!res.ok) {
     const text = await res.text();
     throw new Error(`Schema fetch failed (${res.status}): ${text}`);
   }
-  return await res.json();
+  const body = await res.json();
+  if (!Array.isArray(body) || !body.every(isTableSchema)) {
+    throw new Error("Unexpected /v1/ops/schema response: expected a JSON array of table schemas");
+  }
+  return body;
 }
 function generateTypes(schemas) {
   const lines = [
@@ -110,19 +143,16 @@ function generateTypes(schemas) {
     "",
     "export interface Database {"
   ];
-  const tableNames = Object.keys(schemas).sort();
-  for (const tableName of tableNames) {
-    const _schema = schemas[tableName];
-    const rowType = `${pascalCase(tableName)}Row`;
-    lines.push(`  ${tableName}: ${rowType};`);
+  const tables = [...schemas].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  for (const table of tables) {
+    lines.push(`  ${table.name}: ${pascalCase(table.name)}Row;`);
   }
   lines.push("}");
   lines.push("");
-  for (const tableName of tableNames) {
-    const schema = schemas[tableName];
-    const rowType = `${pascalCase(tableName)}Row`;
+  for (const table of tables) {
+    const rowType = `${pascalCase(table.name)}Row`;
     lines.push(`export interface ${rowType} {`);
-    for (const col of schema.columns) {
+    for (const col of table.columns) {
       const tsType = chTypeToTS(col.type);
       const optional = col.has_default ? "?" : "";
       lines.push(`  ${col.name}${optional}: ${tsType};`);
@@ -139,12 +169,11 @@ async function main() {
   const args = parseArgs(process.argv);
   console.log(`Fetching schema from ${args.url}...`);
   const schemas = await fetchSchemas(args.url, args.auth);
-  const tableCount = Object.keys(schemas).length;
-  if (tableCount === 0) {
+  if (schemas.length === 0) {
     console.warn("No tables found. Is WaveHouse running with tables in ClickHouse?");
     process.exit(1);
   }
-  console.log(`Found ${tableCount} table(s): ${Object.keys(schemas).join(", ")}`);
+  console.log(`Found ${schemas.length} table(s): ${schemas.map((t) => t.name).join(", ")}`);
   const output = generateTypes(schemas);
   const { writeFile } = await import("fs/promises");
   const { resolve } = await import("path");
@@ -152,7 +181,22 @@ async function main() {
   await writeFile(outPath, output, "utf-8");
   console.log(`\u2713 Types written to ${outPath}`);
 }
-main().catch((err) => {
-  console.error("Codegen failed:", err.message);
-  process.exit(1);
-});
+function isDirectInvocation() {
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+}
+if (isDirectInvocation()) {
+  main().catch((err) => {
+    console.error("Codegen failed:", err.message);
+    process.exit(1);
+  });
+}
+export {
+  chTypeToTS,
+  fetchSchemas,
+  generateTypes
+};

package/dist/index.cjs

@@ -72,9 +72,39 @@ 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;
+}
 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": opts.contentType ?? "application/json",
     Accept: "application/json"
@@ -86,16 +116,20 @@ async function request(ctx, opts) {
       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,
+        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;
@@ -133,15 +167,6 @@ async function request(ctx, opts) {
   }
   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);
 }
@@ -175,7 +200,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);
@@ -185,7 +210,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
     });
@@ -210,7 +235,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",
@@ -238,7 +270,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);
@@ -248,7 +280,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);
@@ -258,7 +290,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
     });
@@ -269,7 +301,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);
@@ -287,7 +319,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);
@@ -297,7 +329,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
     });
@@ -308,7 +340,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
     });
@@ -327,7 +359,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);
@@ -348,7 +380,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);
@@ -360,7 +392,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
   });
@@ -558,7 +590,7 @@ var SSETransport = class {
     this.onStatus?.("closed");
   }
   async _doConnect() {
-    const url = new URL("/v1/stream", this._opts.baseURL);
+    const url = resolveURL(this._opts.baseURL, "/v1/stream");
     url.searchParams.set("table", this._opts.table);
     if (this._opts.since) {
       url.searchParams.set("since", this._opts.since);
@@ -1072,7 +1104,7 @@ var TableRef = class {
   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);
@@ -1103,7 +1135,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);
@@ -1135,7 +1170,7 @@ 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);