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

package/README.md

@@ -1,6 +1,6 @@
 # @wavehouse/sdk
 
-Zero-dependency TypeScript client for [WaveHouse](https://github.com/Wave-RF/WaveHouse) — schema-aware real-time API gateway for ClickHouse.
+TypeScript client for [WaveHouse](https://github.com/Wave-RF/WaveHouse) — schema-aware real-time API gateway for ClickHouse. One runtime dependency (`eventsource-parser`, ~1.4 KB gzipped, itself dependency-free).
 
 ## Installation
 
@@ -8,6 +8,8 @@ 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. 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'`.
 
 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.
@@ -42,7 +44,7 @@ Pin a version for production (`https://esm.sh/@wavehouse/sdk@0.1.0`). jsDelivr (
 
 **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.
 
-Streaming (`.stream()`) uses the browser's native `EventSource`, so it works in both forms with no polyfill.
+Streaming (`.stream()`) runs on `fetch`, so it works in both forms with no polyfill.
 
 ## Quick Start
 
@@ -55,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
@@ -125,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 a terminal `SSE_CONNECT_ERROR`), `.stream()` / `.liveQuery()` in a runtime with no global `fetch` and no `options.fetch`, and an `auth` callback that rejects — a token-refresh failure propagates out of the REST call, and on a stream is reported as a retryable `SSE_AUTH_ERROR`. A dropped stream *is* re-dialed by the SDK, on a jittered backoff; only non-retryable failures end it. One more exception can escape an SDK call, though it is yours rather than ours: a subscriber's `status` handler throwing on the first, synchronous `.subscribe()` / `.liveQuery()` call — see [Error Handling](https://wavehouse.dev/sdk/reference#error-handling).
 
 ```ts
 const { data, error } = await wh.from('clicks').fetch();
@@ -144,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
+};