@wavehouse/sdk 0.0.0-dev.h825a5d7fa405 → 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,44 @@ 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.
+
+## 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.
+
+**ES module (recommended).** Modern browsers run `type="module"` natively:
+
+```html
+<script type="module">
+  import { createClient } from 'https://esm.sh/@wavehouse/sdk';
+
+  const wh = createClient({ baseURL: 'https://your-wavehouse.example.com' });
+  const { data, error } = await wh.from('clicks').select('page').limit(10);
+  console.log(data ?? error);
+</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.
+
+**Classic global (`<script src>`).** For pages that can't use ES modules, the bundled IIFE build attaches everything to a `WaveHouse` global:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@wavehouse/sdk"></script>
+<script>
+  const wh = WaveHouse.createClient({ baseURL: 'https://your-wavehouse.example.com' });
+  wh.from('clicks').select('page').limit(10).then(({ data }) => console.log(data));
+</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.
+
+Streaming (`.stream()`) runs on `fetch`, so it works in both forms with no polyfill.
+
 ## Quick Start
 
 ```ts
@@ -19,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
@@ -89,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();
@@ -102,13 +144,13 @@ if (error) {
 
 ## Codegen
 
-Generate TypeScript types from your live WaveHouse schema:
+Generate TypeScript types from your live WaveHouse schema. The package ships a `wavehouse-codegen` bin, so after installing you can run it with `npx`:
 
 ```bash
-npm run codegen -- --url http://localhost:8080 --out ./src/db.d.ts
+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>()`.
+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

@@ -0,0 +1,202 @@
+#!/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" };
+  for (let i = 2; i < argv.length; i++) {
+    switch (argv[i]) {
+      case "--url":
+      case "-u":
+        args.url = argv[++i];
+        break;
+      case "--out":
+      case "-o":
+        args.out = argv[++i];
+        break;
+      case "--auth":
+      case "-a":
+        args.auth = argv[++i];
+        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`);
+        process.exit(0);
+    }
+  }
+  return args;
+}
+function chTypeToTS(chType) {
+  if (chType.startsWith("Nullable(") && chType.endsWith(")")) {
+    const inner = chType.slice(9, -1);
+    return `${chTypeToTS(inner)} | null`;
+  }
+  if (chType.startsWith("LowCardinality(") && chType.endsWith(")")) {
+    return chTypeToTS(chType.slice(15, -1));
+  }
+  if (chType === "String" || chType.startsWith("FixedString(") || chType === "UUID" || chType.startsWith("DateTime") || chType.startsWith("Date") || chType.startsWith("Enum8(") || chType.startsWith("Enum16(") || chType === "IPv4" || chType === "IPv6") {
+    return "string";
+  }
+  if (chType === "Bool") return "boolean";
+  if (isNumeric(chType)) return "number";
+  if (chType.startsWith("Array(") && chType.endsWith(")")) {
+    const inner = chType.slice(6, -1);
+    return `${chTypeToTS(inner)}[]`;
+  }
+  if (chType.startsWith("Map(") && chType.endsWith(")")) {
+    const inner = chType.slice(4, -1);
+    const comma = findTopLevelComma(inner);
+    if (comma !== -1) {
+      const keyType = chTypeToTS(inner.slice(0, comma).trim());
+      const valType = chTypeToTS(inner.slice(comma + 1).trim());
+      return `Record<${keyType}, ${valType}>`;
+    }
+    return "Record<string, unknown>";
+  }
+  if (chType.startsWith("Tuple(")) {
+    return "unknown[]";
+  }
+  return "unknown";
+}
+function isNumeric(t) {
+  const numericPrefixes = [
+    "UInt8",
+    "UInt16",
+    "UInt32",
+    "UInt64",
+    "UInt128",
+    "UInt256",
+    "Int8",
+    "Int16",
+    "Int32",
+    "Int64",
+    "Int128",
+    "Int256",
+    "Float32",
+    "Float64",
+    "Decimal"
+  ];
+  return numericPrefixes.some((p) => t === p || t.startsWith(`${p}(`));
+}
+function findTopLevelComma(s) {
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "(") depth++;
+    else if (s[i] === ")") depth--;
+    else if (s[i] === "," && depth === 0) return i;
+  }
+  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(resolveURL(url, "/v1/ops/schema").toString(), { headers });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Schema fetch failed (${res.status}): ${text}`);
+  }
+  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 = [
+    "// Auto-generated by @wavehouse/sdk codegen",
+    `// Generated at: ${(/* @__PURE__ */ new Date()).toISOString()}`,
+    "// Do not edit manually \u2014 re-run: npm run codegen",
+    "",
+    "export interface Database {"
+  ];
+  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 table of tables) {
+    const rowType = `${pascalCase(table.name)}Row`;
+    lines.push(`export interface ${rowType} {`);
+    for (const col of table.columns) {
+      const tsType = chTypeToTS(col.type);
+      const optional = col.has_default ? "?" : "";
+      lines.push(`  ${col.name}${optional}: ${tsType};`);
+    }
+    lines.push("}");
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function pascalCase(s) {
+  return s.split(/[_\-\s]+/).map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join("");
+}
+async function main() {
+  const args = parseArgs(process.argv);
+  console.log(`Fetching schema from ${args.url}...`);
+  const schemas = await fetchSchemas(args.url, args.auth);
+  if (schemas.length === 0) {
+    console.warn("No tables found. Is WaveHouse running with tables in ClickHouse?");
+    process.exit(1);
+  }
+  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");
+  const outPath = resolve(args.out);
+  await writeFile(outPath, output, "utf-8");
+  console.log(`\u2713 Types written to ${outPath}`);
+}
+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
+};