@wavehouse/sdk 0.0.0-dev.hab0797ca5a74 → 0.0.0-dev.hb0c3a577b2f8

package/README.md

@@ -8,6 +8,42 @@ Zero-dependency TypeScript client for [WaveHouse](https://github.com/Wave-RF/Wav
 npm install @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 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()`) uses the browser's native `EventSource`, so it works in both forms with no polyfill.
+
 ## Quick Start
 
 ```ts
@@ -19,6 +55,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 +127,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();
@@ -102,13 +142,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/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.
 
 ## Development & Testing
 

package/dist/cli/codegen.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+// 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;
+}
+async function fetchSchemas(url, auth) {
+  const headers = {};
+  if (auth) headers.Authorization = `Bearer ${auth}`;
+  const res = await fetch(resolveURL(url, "/v1/schema").toString(), { headers });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Schema fetch failed (${res.status}): ${text}`);
+  }
+  return await res.json();
+}
+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 tableNames = Object.keys(schemas).sort();
+  for (const tableName of tableNames) {
+    const _schema = schemas[tableName];
+    const rowType = `${pascalCase(tableName)}Row`;
+    lines.push(`  ${tableName}: ${rowType};`);
+  }
+  lines.push("}");
+  lines.push("");
+  for (const tableName of tableNames) {
+    const schema = schemas[tableName];
+    const rowType = `${pascalCase(tableName)}Row`;
+    lines.push(`export interface ${rowType} {`);
+    for (const col of schema.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);
+  const tableCount = Object.keys(schemas).length;
+  if (tableCount === 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(", ")}`);
+  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}`);
+}
+main().catch((err) => {
+  console.error("Codegen failed:", err.message);
+  process.exit(1);
+});

package/dist/index.cjs

@@ -72,9 +72,24 @@ 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
 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"
@@ -133,15 +148,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);
 }
@@ -558,7 +564,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);
@@ -778,7 +784,7 @@ var QueryBuilder = class _QueryBuilder {
     return this._clone({ cacheTTL: seconds });
   }
   // --- Execution ---
-  /** Default row limit when none is specified. Matches backend DefaultMaxRows. */
+  /** Default row limit when none is specified — deliberately tighter than the backend's DefaultMaxRows (10000) safety cap. */
   static DEFAULT_LIMIT = 1e3;
   async fetch(opts) {
     const effectiveLimit = opts?.limit ?? this._state.limit ?? _QueryBuilder.DEFAULT_LIMIT;