@wavehouse/sdk 0.0.0-dev.0f8826c → 0.0.0-dev.h514be5522d89

package/README.md

@@ -8,6 +8,40 @@ 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'`.
+
+## 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
@@ -102,13 +136,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
 
@@ -124,13 +158,12 @@ npm run test:coverage  # coverage report
 
 ### E2E Integration Tests
 
-E2E tests live in `tests/sdk/` (repo root) and exercise the full pipeline through the SDK. See `make test-e2e` in the [Development Guide](../../docs/development.md#e2e-tests-via-sdk).
+E2E tests live in `tests/e2e/sdk/` (repo root) and exercise the full pipeline through the SDK. See `make test-e2e` in the [Development Guide](https://wavehouse.dev/development#e2e-tests-via-sdk).
 
 ## API Reference
 
-See the full [SDK API Reference](../../docs/sdk.md) for detailed documentation of every method, type, and option.
+See the full [SDK API Reference](https://wavehouse.dev/sdk) for detailed documentation of every method, type, and option.
 
 ## License
 
 Apache-2.0 © Wave RF — see [LICENSE](./LICENSE).
-

package/dist/cli/codegen.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+// 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(`${url.replace(/\/+$/, "")}/v1/schema`, { 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

@@ -76,9 +76,10 @@ function err(error) {
 async function request(ctx, opts) {
   const url = buildURL(ctx.baseURL, opts.path, opts.params);
   const headers = {
-    "Content-Type": "application/json",
+    "Content-Type": opts.contentType ?? "application/json",
     Accept: "application/json"
   };
+  const requestBody = opts.rawBody !== void 0 ? opts.rawBody : opts.body !== void 0 ? JSON.stringify(opts.body) : void 0;
   if (ctx.auth) {
     const token = await ctx.auth();
     if (token) {
@@ -92,7 +93,7 @@ async function request(ctx, opts) {
       const res = await fetch(url, {
         method: opts.method,
         headers,
-        body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0,
+        body: requestBody,
         signal: opts.signal
       });
       if (res.ok) {
@@ -727,6 +728,15 @@ var QueryBuilder = class _QueryBuilder {
   select(...columns) {
     return this._clone({ columns: [...this._state.columns, ...columns] });
   }
+  /**
+   * Select every column the caller's role is allowed to read (the all-columns
+   * wildcard). Use this instead of `.select(...)` when you want a full-row read;
+   * a bare `.fetch()` with no `.select()` does this implicitly. Mutually
+   * exclusive with `.select(...)`.
+   */
+  selectAll() {
+    return this._clone({ selectAll: true });
+  }
   where(column, op, value) {
     const filter = { column, op: OP_MAP[op], value };
     return this._clone({ filters: [...this._state.filters, filter] });
@@ -768,7 +778,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;
@@ -782,11 +792,11 @@ var QueryBuilder = class _QueryBuilder {
     if (error) return err(error);
     const rows = data;
     const hasMore = effectiveLimit != null && rows.length >= effectiveLimit;
-    if (hasMore) {
+    if (hasMore && this._state.orderBy.length > 0) {
       const nextFn = () => this._fetchNext(rows, effectiveLimit, opts);
       return okPage(rows, true, nextFn);
     }
-    return okPage(rows, false);
+    return okPage(rows, hasMore);
   }
   stream(opts) {
     const raw = this._createStream(this._state.table, opts);
@@ -825,31 +835,35 @@ var QueryBuilder = class _QueryBuilder {
   }
   _buildAST(effectiveLimit) {
     const ast = {};
-    if (this._state.columns.length > 0) ast.columns = this._state.columns;
-    if (this._state.aggregations.length > 0) ast.aggregations = this._state.aggregations;
+    const hasColumns = this._state.columns.length > 0;
+    const hasAggs = this._state.aggregations.length > 0;
+    if (this._state.selectAll) {
+      ast.select_all = true;
+    } else if (hasColumns) {
+      ast.columns = this._state.columns;
+    } else if (!hasAggs) {
+      ast.select_all = true;
+    }
+    if (hasAggs) ast.aggregations = this._state.aggregations;
     if (this._state.filters.length > 0) ast.filters = this._state.filters;
     if (this._state.groupBy.length > 0) ast.group_by = this._state.groupBy;
-    if (this._state.orderBy.length > 0) {
-      ast.order_by = this._state.orderBy;
-    } else if (effectiveLimit != null && this._state.aggregations.length === 0) {
-      ast.order_by = [{ column: "received_timestamp", dir: "desc" }];
-    }
+    if (this._state.orderBy.length > 0) ast.order_by = this._state.orderBy;
     if (effectiveLimit != null) ast.limit = effectiveLimit;
     if (this._state.timeRange) ast.time_range = this._state.timeRange;
     return ast;
   }
   async _fetchNext(prevRows, _limit, opts) {
-    const orderCol = this._state.orderBy[0]?.column ?? "received_timestamp";
-    const orderDir = this._state.orderBy[0]?.dir ?? "desc";
+    const cursor = this._state.orderBy[0];
+    if (cursor == null) return okPage([], false);
+    const { column: orderCol, dir: orderDir } = cursor;
     const lastRow = prevRows[prevRows.length - 1];
     const lastValue = lastRow?.[orderCol];
     if (lastValue === void 0) return okPage([], false);
     const cursorOp = orderDir === "desc" ? "lt" : "gt";
     const cursorFilter = { column: orderCol, op: cursorOp, value: lastValue };
-    const orderBy = this._state.orderBy.length > 0 ? this._state.orderBy : [{ column: orderCol, dir: orderDir }];
     const nextBuilder = this._clone({
       filters: [...this._state.filters, cursorFilter],
-      orderBy
+      orderBy: this._state.orderBy
     });
     return nextBuilder.fetch(opts);
   }
@@ -940,6 +954,12 @@ function projectColumns(row, columns) {
 }
 
 // src/table.ts
+var NDJSON_CONTENT_TYPE = "application/x-ndjson";
+async function ndjsonSourceToString(source) {
+  if (typeof source === "string") return source;
+  if (source instanceof Uint8Array) return new TextDecoder().decode(source);
+  return new Response(source).text();
+}
 var TableRef = class {
   _ctx;
   _table;
@@ -968,22 +988,34 @@ var TableRef = class {
       this._createStream
     );
   }
-  /** Insert one or more rows into this table. */
+  /**
+   * Start a query that selects every column the caller's role is allowed to read
+   * (the all-columns wildcard). Use instead of `.select(...)` for an explicit
+   * full-row read; `.fetch()` does this implicitly.
+   */
+  selectAll() {
+    return this.select().selectAll();
+  }
+  /**
+   * Insert one or more rows into this table.
+   *
+   * A single object is sent as a JSON `POST /v1/ingest`. An **array** is
+   * serialized to NDJSON (one record per line) and sent as a single
+   * `application/x-ndjson` request: a bad record no longer fails or hides the
+   * 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
+   * already have (a file or stream), use {@link insertNDJSON}.
+   */
   async insert(data, opts) {
     if (Array.isArray(data)) {
-      const promises = data.map(
-        (row) => request(this._ctx, {
-          method: "POST",
-          path: `/v1/ingest?table=${encodeURIComponent(this._table)}`,
-          body: row,
-          signal: opts?.signal
-        })
-      );
-      const results = await Promise.all(promises);
-      for (const res2 of results) {
-        if (res2.error) return err(res2.error);
+      if (data.length === 0) {
+        return ok({ ok: true, total: 0, succeeded: 0, failed: 0, duplicates: 0, results: [] });
       }
-      return ok({ ok: true });
+      const ndjson = data.map((row) => JSON.stringify(row)).join("\n");
+      return this._sendNDJSON(ndjson, opts);
     }
     const { data: res, error } = await request(this._ctx, {
       method: "POST",
@@ -996,6 +1028,46 @@ var TableRef = class {
     if (res?.duplicate != null) result.duplicate = res.duplicate;
     return ok(result);
   }
+  /**
+   * Insert pre-formatted NDJSON (newline-delimited JSON, one record per line)
+   * from a string, raw bytes, a Blob/File, or a byte stream — e.g. a `.ndjson`
+   * 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`.
+   */
+  async insertNDJSON(source, opts) {
+    const ndjson = await ndjsonSourceToString(source);
+    return this._sendNDJSON(ndjson, opts);
+  }
+  /**
+   * @internal Send an NDJSON body and map the server's batch response onto an
+   * {@link InsertResult}. A transport / whole-request failure surfaces as the
+   * Result error arm; a processed batch (even with rejected records) surfaces
+   * as the success arm with `ok = failed === 0`.
+   */
+  async _sendNDJSON(ndjson, opts) {
+    const { data, error } = await request(this._ctx, {
+      method: "POST",
+      path: `/v1/ingest?table=${encodeURIComponent(this._table)}`,
+      rawBody: ndjson,
+      contentType: NDJSON_CONTENT_TYPE,
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    const r = data ?? { total: 0, succeeded: 0, failed: 0, duplicates: 0 };
+    const result = {
+      ok: r.failed === 0,
+      total: r.total,
+      succeeded: r.succeeded,
+      failed: r.failed,
+      duplicates: r.duplicates
+    };
+    if (r.results && r.results.length > 0) result.results = r.results;
+    return ok(result);
+  }
   /** Fetch the schema for this table. */
   async schema(opts) {
     const { data, error } = await request(this._ctx, {