@duckviz/sdk 0.1.0

package/README.md

@@ -0,0 +1,135 @@
+# @duckviz/sdk
+
+Node-only SDK for DuckViz AI endpoints. Composable classes for widget recommendations, log format detection, report generation, and credit management — with built-in retry, auth, and error handling.
+
+## Install
+
+```bash
+npm install @duckviz/sdk
+```
+
+## Quick start
+
+### Next.js App Router (recommended)
+
+The fastest way to connect your app to DuckViz AI. Four lines — token stays server-side.
+
+```ts
+// app/api/duckviz/[...route]/route.ts
+import { createDuckvizHandlers } from "@duckviz/sdk/next";
+
+export const { POST, GET } = createDuckvizHandlers({
+  token: process.env.DUCKVIZ_TOKEN!,
+});
+```
+
+This creates a catch-all proxy that forwards `/api/duckviz/*` requests to DuckViz Cloud with your token attached. SSE responses stream through without buffering.
+
+Wire it up with `@duckviz/explorer`:
+
+```tsx
+// app/page.tsx
+import { Explorer } from "@duckviz/explorer";
+
+const customFetch = (input, init) => {
+  if (typeof input === "string" && input.startsWith("/api/")) {
+    input = input.replace(/^\/api\//, "/api/duckviz/");
+  }
+  return fetch(input, init);
+};
+
+<Explorer datasets={datasets} customFetch={customFetch} authenticated={true} />;
+```
+
+### Programmatic usage
+
+```ts
+import { DuckvizWidgetFlow, DuckvizCredits } from "@duckviz/sdk";
+
+// Generate widget recommendations
+const flow = new DuckvizWidgetFlow({
+  token: process.env.DUCKVIZ_TOKEN!,
+});
+
+const widgets = await flow.invoke({
+  schema: [
+    { name: "date", type: "DATE" },
+    { name: "revenue", type: "DOUBLE" },
+    { name: "region", type: "VARCHAR" },
+  ],
+  tableName: "t_sales",
+});
+
+// Check credit balance
+const credits = new DuckvizCredits({
+  token: process.env.DUCKVIZ_TOKEN!,
+});
+const { balance, plan } = await credits.invoke();
+```
+
+### Streaming (SSE)
+
+```ts
+const flow = new DuckvizWidgetFlow({
+  token: process.env.DUCKVIZ_TOKEN!,
+});
+
+for await (const event of flow.stream({
+  schema,
+  tableName: "t_logs",
+})) {
+  console.log(event.event, event.data);
+}
+```
+
+## API
+
+### Next.js handler
+
+| Export                    | Description                                                |
+| ------------------------- | ---------------------------------------------------------- |
+| `createDuckvizHandlers()` | Creates `{ POST, GET }` handlers for a catch-all API route |
+
+Options: `token` (required), `baseUrl` (override, defaults to `https://app.duckviz.com`), `onRequest` (optional hook).
+
+### Endpoint classes
+
+| Class                      | Description                                 |
+| -------------------------- | ------------------------------------------- |
+| `DuckvizWidgetFlow`        | AI widget recommendations from table schema |
+| `DuckvizLogFormatDetector` | Detect log format from sample lines         |
+| `DuckvizReports`           | Generate structured reports from widgets    |
+| `DuckvizCredits`           | Check credit balance                        |
+| `DuckvizUsage`             | Query usage history                         |
+
+All classes accept `{ token, baseUrl?, maxRetries?, timeout?, fetch? }`.
+
+### Error types
+
+| Error                       | Status | Description              |
+| --------------------------- | ------ | ------------------------ |
+| `DuckvizAuthError`          | 401    | Invalid or missing token |
+| `DuckvizQuotaExceededError` | 402    | Insufficient credits     |
+| `DuckvizRateLimitError`     | 429    | Rate limit exceeded      |
+| `DuckvizServerError`        | 5xx    | Server error             |
+| `DuckvizNetworkError`       | —      | Network/timeout failure  |
+
+### Dashboard config validation
+
+```ts
+import { validateDashboardConfig } from "@duckviz/sdk";
+
+const config = validateDashboardConfig(untrustedInput);
+// Throws DashboardConfigError with path info on invalid input
+```
+
+## Environment variables
+
+| Variable           | Required | Description                                    |
+| ------------------ | -------- | ---------------------------------------------- |
+| `DUCKVIZ_TOKEN`    | Yes      | Personal access token (`dvz_live_...`)         |
+| `DUCKVIZ_BASE_URL` | No       | Override API base URL (defaults to production) |
+
+## License
+
+MIT

package/dist/chunk-U3PJRXFJ.cjs

@@ -0,0 +1,260 @@
+'use strict';
+
+// src/errors.ts
+var DuckvizError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "DuckvizError";
+  }
+};
+var DuckvizAuthError = class extends DuckvizError {
+  constructor(message = "Invalid or missing DuckViz token") {
+    super(message, 401);
+    this.name = "DuckvizAuthError";
+  }
+};
+var DuckvizQuotaExceededError = class extends DuckvizError {
+  constructor(message = "Insufficient credits", required) {
+    super(message, 402);
+    this.required = required;
+    this.name = "DuckvizQuotaExceededError";
+  }
+};
+var DuckvizRateLimitError = class extends DuckvizError {
+  constructor(message = "Rate limit exceeded", retryAfterMs) {
+    super(message, 429);
+    this.retryAfterMs = retryAfterMs;
+    this.name = "DuckvizRateLimitError";
+  }
+};
+var DuckvizServerError = class extends DuckvizError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "DuckvizServerError";
+  }
+};
+var DuckvizNetworkError = class extends DuckvizError {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "DuckvizNetworkError";
+  }
+};
+
+// src/base.ts
+var DEFAULT_BASE_URL = "https://app.duckviz.com";
+var DuckvizEndpoint = class {
+  token;
+  baseUrl;
+  fetchImpl;
+  maxRetries;
+  timeout;
+  constructor(fields) {
+    if (!fields.token) {
+      throw new DuckvizAuthError("token is required");
+    }
+    this.token = fields.token;
+    this.baseUrl = (fields.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.fetchImpl = fields.fetch ?? globalThis.fetch;
+    this.maxRetries = fields.maxRetries ?? 2;
+    this.timeout = fields.timeout ?? 6e4;
+  }
+  // ─── Shared transport helpers (used by subclasses) ──────────────────────
+  buildHeaders() {
+    return new Headers({
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${this.token}`
+    });
+  }
+  /**
+   * POST a JSON body and parse a JSON response. Retries transient failures.
+   * Throws a typed `DuckvizError` subclass on non-2xx responses.
+   */
+  async postJson(path, body, options) {
+    const res = await this.requestWithRetry(path, body, options, "POST");
+    return await res.json();
+  }
+  /**
+   * GET a JSON response. Query params are passed as a plain object and
+   * serialized into the URL — values coerce to strings, arrays repeat the
+   * key, `undefined` / `null` are skipped.
+   */
+  async getJson(path, params, options) {
+    let finalPath = path;
+    if (params) {
+      const qs = new URLSearchParams();
+      for (const [k, v] of Object.entries(params)) {
+        if (v === void 0 || v === null) continue;
+        qs.append(k, String(v));
+      }
+      const q = qs.toString();
+      if (q) finalPath = `${path}?${q}`;
+    }
+    const res = await this.requestWithRetry(
+      finalPath,
+      void 0,
+      options,
+      "GET"
+    );
+    return await res.json();
+  }
+  /**
+   * POST a JSON body and stream back an SSE response, one parsed message at
+   * a time. The raw DuckViz event wire format is
+   *   data: {"event":"...","data":...}\n\n
+   * — this helper yields the parsed `{event, data}` objects directly.
+   */
+  async *postSSE(path, body, options) {
+    const res = await this.requestWithRetry(path, body, options, "POST");
+    if (!res.body) return;
+    for await (const msg of parseSSEStream(res.body)) {
+      yield msg;
+    }
+  }
+  async requestWithRetry(path, body, options, method) {
+    const url = `${this.baseUrl}${path}`;
+    const payload = method === "POST" ? JSON.stringify(body) : void 0;
+    let attempt = 0;
+    while (true) {
+      const attemptController = new AbortController();
+      const timeoutId = setTimeout(
+        () => attemptController.abort(),
+        this.timeout
+      );
+      const mergedSignal = mergeSignals(
+        options?.signal,
+        attemptController.signal
+      );
+      let res;
+      try {
+        const init = {
+          method,
+          headers: this.buildHeaders(),
+          signal: mergedSignal
+        };
+        if (payload !== void 0) init.body = payload;
+        res = await this.fetchImpl(url, init);
+      } catch (err) {
+        clearTimeout(timeoutId);
+        if (options?.signal?.aborted) {
+          throw err;
+        }
+        if (attempt >= this.maxRetries) {
+          throw new DuckvizNetworkError(
+            err instanceof Error ? err.message : String(err),
+            err
+          );
+        }
+        await sleep(backoffMs(attempt));
+        attempt++;
+        continue;
+      }
+      clearTimeout(timeoutId);
+      if (res.ok) return res;
+      const errBody = await safeReadJson(res);
+      const message = (errBody && typeof errBody === "object" && "error" in errBody ? String(errBody.error) : null) ?? `Request failed (${res.status})`;
+      if (res.status === 401) throw new DuckvizAuthError(message);
+      if (res.status === 402) {
+        const required = errBody && typeof errBody === "object" && "required" in errBody ? Number(errBody.required) : void 0;
+        throw new DuckvizQuotaExceededError(
+          message,
+          Number.isFinite(required) ? required : void 0
+        );
+      }
+      if (res.status === 429) {
+        const retryAfterMs = parseRetryAfter(res.headers.get("retry-after"));
+        if (attempt < this.maxRetries) {
+          await sleep(retryAfterMs ?? backoffMs(attempt));
+          attempt++;
+          continue;
+        }
+        throw new DuckvizRateLimitError(message, retryAfterMs);
+      }
+      if (res.status >= 500 && res.status < 600) {
+        if (attempt < this.maxRetries) {
+          await sleep(backoffMs(attempt));
+          attempt++;
+          continue;
+        }
+        throw new DuckvizServerError(message, res.status);
+      }
+      throw new DuckvizError(message, res.status);
+    }
+  }
+};
+function backoffMs(attempt) {
+  const base = 250 * Math.pow(2, attempt);
+  const jitter = base * 0.2 * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(base + jitter));
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseRetryAfter(header) {
+  if (!header) return void 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return seconds * 1e3;
+  const date = Date.parse(header);
+  if (Number.isFinite(date)) return Math.max(0, date - Date.now());
+  return void 0;
+}
+async function safeReadJson(res) {
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+function mergeSignals(...signals) {
+  const real = signals.filter((s) => !!s);
+  if (real.length === 0) return void 0;
+  if (real.length === 1) return real[0];
+  const any = AbortSignal.any;
+  if (typeof any === "function") return any.call(AbortSignal, real);
+  const controller = new AbortController();
+  for (const s of real) {
+    if (s.aborted) {
+      controller.abort(s.reason);
+      break;
+    }
+    s.addEventListener("abort", () => controller.abort(s.reason), {
+      once: true
+    });
+  }
+  return controller.signal;
+}
+async function* parseSSEStream(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (!line.startsWith("data: ")) continue;
+        const raw = line.slice(6).trim();
+        if (!raw) continue;
+        try {
+          yield JSON.parse(raw);
+        } catch {
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.DuckvizAuthError = DuckvizAuthError;
+exports.DuckvizEndpoint = DuckvizEndpoint;
+exports.DuckvizError = DuckvizError;
+exports.DuckvizNetworkError = DuckvizNetworkError;
+exports.DuckvizQuotaExceededError = DuckvizQuotaExceededError;
+exports.DuckvizRateLimitError = DuckvizRateLimitError;
+exports.DuckvizServerError = DuckvizServerError;

package/dist/chunk-WYWQAALZ.js

@@ -0,0 +1,251 @@
+// src/errors.ts
+var DuckvizError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "DuckvizError";
+  }
+};
+var DuckvizAuthError = class extends DuckvizError {
+  constructor(message = "Invalid or missing DuckViz token") {
+    super(message, 401);
+    this.name = "DuckvizAuthError";
+  }
+};
+var DuckvizQuotaExceededError = class extends DuckvizError {
+  constructor(message = "Insufficient credits", required) {
+    super(message, 402);
+    this.required = required;
+    this.name = "DuckvizQuotaExceededError";
+  }
+};
+var DuckvizRateLimitError = class extends DuckvizError {
+  constructor(message = "Rate limit exceeded", retryAfterMs) {
+    super(message, 429);
+    this.retryAfterMs = retryAfterMs;
+    this.name = "DuckvizRateLimitError";
+  }
+};
+var DuckvizServerError = class extends DuckvizError {
+  constructor(message, status) {
+    super(message, status);
+    this.name = "DuckvizServerError";
+  }
+};
+var DuckvizNetworkError = class extends DuckvizError {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "DuckvizNetworkError";
+  }
+};
+
+// src/base.ts
+var DEFAULT_BASE_URL = "https://app.duckviz.com";
+var DuckvizEndpoint = class {
+  token;
+  baseUrl;
+  fetchImpl;
+  maxRetries;
+  timeout;
+  constructor(fields) {
+    if (!fields.token) {
+      throw new DuckvizAuthError("token is required");
+    }
+    this.token = fields.token;
+    this.baseUrl = (fields.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.fetchImpl = fields.fetch ?? globalThis.fetch;
+    this.maxRetries = fields.maxRetries ?? 2;
+    this.timeout = fields.timeout ?? 6e4;
+  }
+  // ─── Shared transport helpers (used by subclasses) ──────────────────────
+  buildHeaders() {
+    return new Headers({
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${this.token}`
+    });
+  }
+  /**
+   * POST a JSON body and parse a JSON response. Retries transient failures.
+   * Throws a typed `DuckvizError` subclass on non-2xx responses.
+   */
+  async postJson(path, body, options) {
+    const res = await this.requestWithRetry(path, body, options, "POST");
+    return await res.json();
+  }
+  /**
+   * GET a JSON response. Query params are passed as a plain object and
+   * serialized into the URL — values coerce to strings, arrays repeat the
+   * key, `undefined` / `null` are skipped.
+   */
+  async getJson(path, params, options) {
+    let finalPath = path;
+    if (params) {
+      const qs = new URLSearchParams();
+      for (const [k, v] of Object.entries(params)) {
+        if (v === void 0 || v === null) continue;
+        qs.append(k, String(v));
+      }
+      const q = qs.toString();
+      if (q) finalPath = `${path}?${q}`;
+    }
+    const res = await this.requestWithRetry(
+      finalPath,
+      void 0,
+      options,
+      "GET"
+    );
+    return await res.json();
+  }
+  /**
+   * POST a JSON body and stream back an SSE response, one parsed message at
+   * a time. The raw DuckViz event wire format is
+   *   data: {"event":"...","data":...}\n\n
+   * — this helper yields the parsed `{event, data}` objects directly.
+   */
+  async *postSSE(path, body, options) {
+    const res = await this.requestWithRetry(path, body, options, "POST");
+    if (!res.body) return;
+    for await (const msg of parseSSEStream(res.body)) {
+      yield msg;
+    }
+  }
+  async requestWithRetry(path, body, options, method) {
+    const url = `${this.baseUrl}${path}`;
+    const payload = method === "POST" ? JSON.stringify(body) : void 0;
+    let attempt = 0;
+    while (true) {
+      const attemptController = new AbortController();
+      const timeoutId = setTimeout(
+        () => attemptController.abort(),
+        this.timeout
+      );
+      const mergedSignal = mergeSignals(
+        options?.signal,
+        attemptController.signal
+      );
+      let res;
+      try {
+        const init = {
+          method,
+          headers: this.buildHeaders(),
+          signal: mergedSignal
+        };
+        if (payload !== void 0) init.body = payload;
+        res = await this.fetchImpl(url, init);
+      } catch (err) {
+        clearTimeout(timeoutId);
+        if (options?.signal?.aborted) {
+          throw err;
+        }
+        if (attempt >= this.maxRetries) {
+          throw new DuckvizNetworkError(
+            err instanceof Error ? err.message : String(err),
+            err
+          );
+        }
+        await sleep(backoffMs(attempt));
+        attempt++;
+        continue;
+      }
+      clearTimeout(timeoutId);
+      if (res.ok) return res;
+      const errBody = await safeReadJson(res);
+      const message = (errBody && typeof errBody === "object" && "error" in errBody ? String(errBody.error) : null) ?? `Request failed (${res.status})`;
+      if (res.status === 401) throw new DuckvizAuthError(message);
+      if (res.status === 402) {
+        const required = errBody && typeof errBody === "object" && "required" in errBody ? Number(errBody.required) : void 0;
+        throw new DuckvizQuotaExceededError(
+          message,
+          Number.isFinite(required) ? required : void 0
+        );
+      }
+      if (res.status === 429) {
+        const retryAfterMs = parseRetryAfter(res.headers.get("retry-after"));
+        if (attempt < this.maxRetries) {
+          await sleep(retryAfterMs ?? backoffMs(attempt));
+          attempt++;
+          continue;
+        }
+        throw new DuckvizRateLimitError(message, retryAfterMs);
+      }
+      if (res.status >= 500 && res.status < 600) {
+        if (attempt < this.maxRetries) {
+          await sleep(backoffMs(attempt));
+          attempt++;
+          continue;
+        }
+        throw new DuckvizServerError(message, res.status);
+      }
+      throw new DuckvizError(message, res.status);
+    }
+  }
+};
+function backoffMs(attempt) {
+  const base = 250 * Math.pow(2, attempt);
+  const jitter = base * 0.2 * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(base + jitter));
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseRetryAfter(header) {
+  if (!header) return void 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return seconds * 1e3;
+  const date = Date.parse(header);
+  if (Number.isFinite(date)) return Math.max(0, date - Date.now());
+  return void 0;
+}
+async function safeReadJson(res) {
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+function mergeSignals(...signals) {
+  const real = signals.filter((s) => !!s);
+  if (real.length === 0) return void 0;
+  if (real.length === 1) return real[0];
+  const any = AbortSignal.any;
+  if (typeof any === "function") return any.call(AbortSignal, real);
+  const controller = new AbortController();
+  for (const s of real) {
+    if (s.aborted) {
+      controller.abort(s.reason);
+      break;
+    }
+    s.addEventListener("abort", () => controller.abort(s.reason), {
+      once: true
+    });
+  }
+  return controller.signal;
+}
+async function* parseSSEStream(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (!line.startsWith("data: ")) continue;
+        const raw = line.slice(6).trim();
+        if (!raw) continue;
+        try {
+          yield JSON.parse(raw);
+        } catch {
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+export { DEFAULT_BASE_URL, DuckvizAuthError, DuckvizEndpoint, DuckvizError, DuckvizNetworkError, DuckvizQuotaExceededError, DuckvizRateLimitError, DuckvizServerError };

package/dist/express.cjs

@@ -0,0 +1,10 @@
+'use strict';
+
+// src/express.ts
+function duckvizExpressMiddleware() {
+  throw new Error(
+    "@duckviz/sdk/express is not implemented yet. Use @duckviz/sdk/next for Next.js App Router, or open an issue if you need Express support."
+  );
+}
+
+exports.duckvizExpressMiddleware = duckvizExpressMiddleware;

package/dist/express.d.cts

@@ -0,0 +1,16 @@
+/**
+ * @duckviz/sdk/express — placeholder.
+ *
+ * Deferred to a later session. The Next.js handler (`./next`) covers the
+ * main target use case (consumer platform plan Stream 5). Express support
+ * needs a different plumbing strategy because the Node http ServerResponse
+ * doesn't speak Web Streams natively, so SSE pass-through has to use
+ * `res.write` in a loop over the upstream body reader. Not hard, just not
+ * blocking Stream 5 v1.
+ *
+ * Importing this subpath throws so the failure is loud rather than a
+ * silently-broken `{}` export.
+ */
+declare function duckvizExpressMiddleware(): never;
+
+export { duckvizExpressMiddleware };

package/dist/express.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @duckviz/sdk/express — placeholder.
+ *
+ * Deferred to a later session. The Next.js handler (`./next`) covers the
+ * main target use case (consumer platform plan Stream 5). Express support
+ * needs a different plumbing strategy because the Node http ServerResponse
+ * doesn't speak Web Streams natively, so SSE pass-through has to use
+ * `res.write` in a loop over the upstream body reader. Not hard, just not
+ * blocking Stream 5 v1.
+ *
+ * Importing this subpath throws so the failure is loud rather than a
+ * silently-broken `{}` export.
+ */
+declare function duckvizExpressMiddleware(): never;
+
+export { duckvizExpressMiddleware };

package/dist/express.js

@@ -0,0 +1,8 @@
+// src/express.ts
+function duckvizExpressMiddleware() {
+  throw new Error(
+    "@duckviz/sdk/express is not implemented yet. Use @duckviz/sdk/next for Next.js App Router, or open an issue if you need Express support."
+  );
+}
+
+export { duckvizExpressMiddleware };