@duckviz/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,401 @@
+interface DuckvizEndpointFields {
+    /** Personal access token (`dvz_live_...`). Never commit to source control. */
+    token: string;
+    /** Override base URL (defaults to the DuckViz Cloud production host). */
+    baseUrl?: string;
+    /** Injectable fetch — used in tests to mock the transport. */
+    fetch?: typeof fetch;
+    /** Max retry attempts on 5xx / 429 / network error. Default: 2. */
+    maxRetries?: number;
+    /** Per-attempt timeout in ms. Default: 60_000. */
+    timeout?: number;
+}
+interface InvokeOptions {
+    signal?: AbortSignal;
+}
+interface SSEMessage<T = unknown> {
+    event: string;
+    data: T;
+}
+/**
+ * Base class for every DuckViz endpoint wrapper.
+ *
+ * Why a class tree (mirrors LangChain's `BaseChatModel`): each endpoint has
+ * identical auth, retry, abort, and error-mapping semantics — only the URL,
+ * request body, and return shape differ. Subclasses override `invoke` (and
+ * optionally `stream`) and call `postJson` / `postSSE` under the hood.
+ *
+ * Retry policy: exponential backoff for 5xx / 429 / network errors. 4xx
+ * (401/402/400) are terminal. `Retry-After` headers are honored.
+ */
+declare abstract class DuckvizEndpoint<TInput, TOutput> {
+    protected readonly token: string;
+    protected readonly baseUrl: string;
+    protected readonly fetchImpl: typeof fetch;
+    protected readonly maxRetries: number;
+    protected readonly timeout: number;
+    constructor(fields: DuckvizEndpointFields);
+    abstract invoke(input: TInput, options?: InvokeOptions): Promise<TOutput>;
+    protected buildHeaders(): Headers;
+    /**
+     * POST a JSON body and parse a JSON response. Retries transient failures.
+     * Throws a typed `DuckvizError` subclass on non-2xx responses.
+     */
+    protected postJson<TResponse>(path: string, body: unknown, options?: InvokeOptions): Promise<TResponse>;
+    /**
+     * 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.
+     */
+    protected getJson<TResponse>(path: string, params?: Record<string, string | number | boolean | undefined | null>, options?: InvokeOptions): Promise<TResponse>;
+    /**
+     * 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.
+     */
+    protected postSSE<TData = unknown>(path: string, body: unknown, options?: InvokeOptions): AsyncIterable<SSEMessage<TData>>;
+    private requestWithRetry;
+}
+
+/**
+ * Typed error hierarchy for the DuckViz SDK.
+ *
+ * Callers can `catch` either the base `DuckvizError` or a specific subclass.
+ * Every error carries the upstream HTTP status (when applicable) and the
+ * original message from the server, so logging and retry logic stays simple.
+ */
+declare class DuckvizError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/** 401 — token missing, malformed, or revoked. Not retryable. */
+declare class DuckvizAuthError extends DuckvizError {
+    constructor(message?: string);
+}
+/** 402 — token owner is out of credits. Not retryable; UI should prompt top-up. */
+declare class DuckvizQuotaExceededError extends DuckvizError {
+    readonly required?: number | undefined;
+    constructor(message?: string, required?: number | undefined);
+}
+/**
+ * 429 — too many requests. `retryAfterMs` is derived from the `Retry-After`
+ * response header when present, otherwise undefined. The base class's retry
+ * loop honors this automatically.
+ */
+declare class DuckvizRateLimitError extends DuckvizError {
+    readonly retryAfterMs?: number | undefined;
+    constructor(message?: string, retryAfterMs?: number | undefined);
+}
+/** 5xx — upstream crashed. Retried automatically by the base class. */
+declare class DuckvizServerError extends DuckvizError {
+    constructor(message: string, status: number);
+}
+/** fetch() itself threw (DNS, TCP, offline, abort). Retried automatically. */
+declare class DuckvizNetworkError extends DuckvizError {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+
+/**
+ * Public SDK types — mirrored from the app's internal shapes but declared
+ * independently so SDK consumers don't need to install `@duckviz/db` or
+ * `@duckviz/explorer` as peer deps.
+ *
+ * Keep in sync with:
+ *   - apps/app/app/api/widget-flow/fast-recommend/route.ts
+ *   - apps/app/app/api/detect-log-format/route.ts
+ *   - apps/app/app/api/generate-report-sections/route.ts
+ *   - apps/app/app/api/modify-report-section/route.ts
+ */
+interface SchemaColumn {
+    column_name: string;
+    column_type: string;
+}
+interface TableInfo {
+    tableName: string;
+    schema: SchemaColumn[];
+}
+interface RecommendedWidget {
+    type: string;
+    title: string;
+    description: string;
+    duckdbQuery: string;
+    config?: Record<string, unknown>;
+    domain?: string;
+}
+interface VizSuggestion {
+    type: string;
+    title: string;
+    rationale?: string;
+}
+interface WidgetFlowInput {
+    tables: TableInfo[];
+    dateSamples?: Record<string, string[]>;
+    formatName?: string;
+}
+/**
+ * Events emitted by `DuckvizWidgetFlow.stream()`. The exact sequence is:
+ *   thinking → (domain | viz_suggestion | widget)* → done
+ * plus an `error` terminal event on failure.
+ */
+type WidgetFlowEvent = {
+    event: "thinking";
+    data: {
+        message: string;
+    };
+} | {
+    event: "domain";
+    data: {
+        domain: string;
+        source?: string;
+    };
+} | {
+    event: "viz_suggestion";
+    data: VizSuggestion;
+} | {
+    event: "widget";
+    data: RecommendedWidget;
+} | {
+    event: "done";
+    data: null;
+} | {
+    event: "error";
+    data: {
+        message: string;
+    };
+};
+interface LogFormatDetectInput {
+    lines: string[];
+    existingFormats?: unknown[];
+}
+interface DetectedLogFormat {
+    logType: string;
+    formatName: string;
+    explanation: string;
+    [key: string]: unknown;
+}
+interface ReportWidgetRef {
+    title: string;
+    type: string;
+    description: string;
+    duckdbQuery: string;
+}
+interface ReportSectionTemplate {
+    key: string;
+    title: string;
+    promptHint: string;
+    position: "pre" | "post";
+}
+interface ReportsInput {
+    sections: ReportSectionTemplate[];
+    systemPromptHint: string;
+    reportTitle: string;
+    widgets: ReportWidgetRef[];
+}
+/**
+ * Event stream from `DuckvizReports.stream()`. `section-complete` carries the
+ * generated block list for a single section; callers can swap placeholders in
+ * their report editor as each arrives.
+ */
+type ReportsEvent = {
+    event: "section-start";
+    data: {
+        sectionKey: string;
+        sectionTitle: string;
+    };
+} | {
+    event: "section-complete";
+    data: {
+        sectionKey: string;
+        sectionTitle: string;
+        blocks: unknown[];
+        queries: Record<string, string>;
+    };
+} | {
+    event: "section-error";
+    data: {
+        sectionKey: string;
+        message: string;
+    };
+} | {
+    event: "done";
+    data: null;
+} | {
+    event: "error";
+    data: {
+        message: string;
+    };
+};
+interface ReportSection {
+    type: string;
+    [key: string]: unknown;
+}
+interface StructuredReport {
+    title: string;
+    sections: ReportSection[];
+    variables?: string[];
+}
+interface ModifyReportSectionInput {
+    content: StructuredReport;
+    prompt: string;
+}
+
+/**
+ * Widget-flow endpoint wrapper.
+ *
+ * Two modes:
+ *   - `invoke(input)` → collects the fast-recommend SSE stream into a plain
+ *     array of widgets. Good for batch / non-streaming callers.
+ *   - `stream(input)` → yields the raw SSE events (thinking / domain /
+ *     viz_suggestion / widget / done) as they arrive. Good for UIs that want
+ *     to render progress.
+ *
+ * Both modes hit the same backend path (`/api/widget-flow/fast-recommend`) —
+ * there's no separate non-streaming endpoint, because the backend already
+ * short-circuits on cache hits without doing any LLM work.
+ */
+declare class DuckvizWidgetFlow extends DuckvizEndpoint<WidgetFlowInput, RecommendedWidget[]> {
+    private static readonly PATH;
+    invoke(input: WidgetFlowInput, options?: InvokeOptions): Promise<RecommendedWidget[]>;
+    stream(input: WidgetFlowInput, options?: InvokeOptions): AsyncIterable<WidgetFlowEvent>;
+}
+
+/**
+ * LLM-driven log format detection. Given a handful of sample lines, returns
+ * `{ logType, formatName, explanation }`. No streaming — this is a single
+ * classify call on the backend.
+ */
+declare class DuckvizLogFormatDetector extends DuckvizEndpoint<LogFormatDetectInput, DetectedLogFormat> {
+    private static readonly PATH;
+    invoke(input: LogFormatDetectInput, options?: InvokeOptions): Promise<DetectedLogFormat>;
+}
+
+/**
+ * Report generation + modification.
+ *
+ * `stream()` is the primary interface — the backend generates sections in
+ * parallel and emits `section-complete` events as each finishes, so callers
+ * can progressively fill a placeholder scaffold.
+ *
+ * `invoke()` aggregates the stream into a single `StructuredReport`, for
+ * non-UI callers that just want the final object.
+ *
+ * `modifySection()` hits a separate non-streaming endpoint that rewrites the
+ * entire report content in response to a freeform prompt.
+ */
+declare class DuckvizReports extends DuckvizEndpoint<ReportsInput, StructuredReport> {
+    private static readonly GENERATE_PATH;
+    private static readonly MODIFY_PATH;
+    stream(input: ReportsInput, options?: InvokeOptions): AsyncIterable<ReportsEvent>;
+    invoke(input: ReportsInput, options?: InvokeOptions): Promise<StructuredReport>;
+    /** Rewrite an existing structured report via a prompt. */
+    modifySection(input: ModifyReportSectionInput, options?: InvokeOptions): Promise<StructuredReport>;
+}
+
+interface CreditBalance {
+    balance: number;
+    plan: string;
+}
+interface UsageEvent {
+    id: string;
+    ts: string;
+    endpoint: string;
+    credits: number;
+    balanceAfter: number;
+}
+interface UsageListParams {
+    from?: string;
+    to?: string;
+    limit?: number;
+}
+/**
+ * Read-only credits client. Unlike the streaming endpoint classes there's
+ * no natural single "input/output" — `balance()` is a no-arg call — so we
+ * extend the base class with a degenerate `invoke()` that aliases to
+ * `balance()` to satisfy the abstract contract. Most callers will just use
+ * `balance()` directly.
+ */
+declare class DuckvizCredits extends DuckvizEndpoint<void, CreditBalance> {
+    private static readonly PATH;
+    invoke(_input?: void, options?: InvokeOptions): Promise<CreditBalance>;
+    balance(options?: InvokeOptions): Promise<CreditBalance>;
+}
+/**
+ * Read-only usage history client. `list()` returns billed calls in reverse
+ * chronological order, filtered by optional date range.
+ */
+declare class DuckvizUsage extends DuckvizEndpoint<UsageListParams, {
+    events: UsageEvent[];
+}> {
+    private static readonly PATH;
+    invoke(input?: UsageListParams, options?: InvokeOptions): Promise<{
+        events: UsageEvent[];
+    }>;
+    list(params?: UsageListParams, options?: InvokeOptions): Promise<{
+        events: UsageEvent[];
+    }>;
+}
+
+interface ThemeConfig {
+    mode?: "light" | "dark";
+    variables?: Partial<ThemeVariables>;
+}
+interface ThemeVariables {
+    "--app-background-default": string;
+    "--app-background-secondary": string;
+    "--app-background-tertiary": string;
+    "--app-surface-subtle": string;
+    "--app-surface-default": string;
+    "--app-surface-secondary": string;
+    "--app-surface-tertiary": string;
+    "--app-text-default": string;
+    "--app-text-secondary": string;
+    "--app-text-subtle": string;
+    "--app-border-default": string;
+    "--app-border-secondary": string;
+    "--app-border-subtle": string;
+    "--app-primary-default": string;
+    "--app-primary-secondary": string;
+    "--app-color-1": string;
+    "--app-color-2": string;
+    "--app-color-3": string;
+    "--app-color-4": string;
+    "--app-color-5": string;
+    "--app-color-6": string;
+    "--app-color-7": string;
+    "--app-color-8": string;
+}
+interface WidgetConfig {
+    id: string;
+    type: string;
+    title: string;
+    description?: string;
+    dataKey: string;
+    config?: Record<string, unknown>;
+    layout?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+interface DashboardConfig {
+    name?: string;
+    description?: string;
+    dataset?: string;
+    widgets: WidgetConfig[];
+    grid?: {
+        cols?: number;
+        rowHeight?: number;
+        margin?: [number, number];
+    };
+    theme?: ThemeConfig;
+}
+declare class DashboardConfigError extends Error {
+    path: string;
+    constructor(message: string, path: string);
+}
+declare function validateDashboardConfig(input: unknown): DashboardConfig;
+
+export { type CreditBalance, type DashboardConfig, DashboardConfigError, type DetectedLogFormat, DuckvizAuthError, DuckvizCredits, DuckvizError, DuckvizLogFormatDetector, DuckvizNetworkError, type DuckvizEndpointFields as DuckvizOptions, DuckvizQuotaExceededError, DuckvizRateLimitError, DuckvizReports, DuckvizServerError, DuckvizUsage, DuckvizWidgetFlow, type InvokeOptions, type LogFormatDetectInput, type RecommendedWidget, type ReportSection, type ReportSectionTemplate, type ReportWidgetRef, type ReportsEvent, type ReportsInput, type SchemaColumn, type StructuredReport, type UsageEvent, type UsageListParams, type VizSuggestion, type WidgetConfig, type WidgetFlowEvent, type WidgetFlowInput, validateDashboardConfig };

package/dist/index.js

@@ -0,0 +1,195 @@
+import { DuckvizEndpoint } from './chunk-WYWQAALZ.js';
+export { DuckvizAuthError, DuckvizError, DuckvizNetworkError, DuckvizQuotaExceededError, DuckvizRateLimitError, DuckvizServerError } from './chunk-WYWQAALZ.js';
+
+// src/widget-flow.ts
+var DuckvizWidgetFlow = class _DuckvizWidgetFlow extends DuckvizEndpoint {
+  static PATH = "/api/widget-flow/fast-recommend";
+  async invoke(input, options) {
+    const widgets = [];
+    for await (const evt of this.stream(input, options)) {
+      if (evt.event === "widget") {
+        widgets.push(evt.data);
+      } else if (evt.event === "error") {
+        throw new Error(evt.data.message);
+      }
+    }
+    return widgets;
+  }
+  async *stream(input, options) {
+    for await (const msg of this.postSSE(
+      _DuckvizWidgetFlow.PATH,
+      input,
+      options
+    )) {
+      yield msg;
+    }
+  }
+};
+
+// src/log-format-detector.ts
+var DuckvizLogFormatDetector = class _DuckvizLogFormatDetector extends DuckvizEndpoint {
+  static PATH = "/api/detect-log-format";
+  async invoke(input, options) {
+    return this.postJson(
+      _DuckvizLogFormatDetector.PATH,
+      input,
+      options
+    );
+  }
+};
+
+// src/reports.ts
+var DuckvizReports = class _DuckvizReports extends DuckvizEndpoint {
+  static GENERATE_PATH = "/api/generate-report-sections";
+  static MODIFY_PATH = "/api/modify-report-section";
+  async *stream(input, options) {
+    for await (const msg of this.postSSE(
+      _DuckvizReports.GENERATE_PATH,
+      input,
+      options
+    )) {
+      yield msg;
+    }
+  }
+  async invoke(input, options) {
+    const sectionBlocks = [];
+    for await (const evt of this.stream(input, options)) {
+      if (evt.event === "section-complete") {
+        sectionBlocks.push(...evt.data.blocks);
+      } else if (evt.event === "error") {
+        throw new Error(evt.data.message);
+      }
+    }
+    return {
+      title: input.reportTitle,
+      sections: sectionBlocks
+    };
+  }
+  /** Rewrite an existing structured report via a prompt. */
+  async modifySection(input, options) {
+    const result = await this.postJson(
+      _DuckvizReports.MODIFY_PATH,
+      input,
+      options
+    );
+    return result.content;
+  }
+};
+
+// src/credits.ts
+var DuckvizCredits = class _DuckvizCredits extends DuckvizEndpoint {
+  static PATH = "/api/credits/balance";
+  async invoke(_input, options) {
+    return this.balance(options);
+  }
+  async balance(options) {
+    return this.getJson(_DuckvizCredits.PATH, void 0, options);
+  }
+};
+var DuckvizUsage = class _DuckvizUsage extends DuckvizEndpoint {
+  static PATH = "/api/usage";
+  async invoke(input = {}, options) {
+    return this.list(input, options);
+  }
+  async list(params = {}, options) {
+    return this.getJson(
+      _DuckvizUsage.PATH,
+      {
+        from: params.from,
+        to: params.to,
+        limit: params.limit
+      },
+      options
+    );
+  }
+};
+
+// src/dashboard-config.ts
+var DashboardConfigError = class extends Error {
+  constructor(message, path) {
+    super(`DashboardConfig.${path}: ${message}`);
+    this.path = path;
+    this.name = "DashboardConfigError";
+  }
+};
+function assertString(val, path) {
+  if (typeof val !== "string" || val.length === 0) {
+    throw new DashboardConfigError("must be a non-empty string", path);
+  }
+}
+function assertOptionalString(val, path) {
+  if (val !== void 0 && typeof val !== "string") {
+    throw new DashboardConfigError("must be a string", path);
+  }
+}
+function validateWidget(w, idx) {
+  if (w === null || typeof w !== "object") {
+    throw new DashboardConfigError("must be an object", `widgets[${idx}]`);
+  }
+  const obj = w;
+  assertString(obj.id, `widgets[${idx}].id`);
+  assertString(obj.type, `widgets[${idx}].type`);
+  assertString(obj.title, `widgets[${idx}].title`);
+  assertOptionalString(obj.description, `widgets[${idx}].description`);
+  assertString(obj.dataKey, `widgets[${idx}].dataKey`);
+  if (obj.config !== void 0 && (typeof obj.config !== "object" || obj.config === null)) {
+    throw new DashboardConfigError(
+      "must be an object",
+      `widgets[${idx}].config`
+    );
+  }
+  if (obj.layout !== void 0) {
+    if (typeof obj.layout !== "object" || obj.layout === null) {
+      throw new DashboardConfigError(
+        "must be an object",
+        `widgets[${idx}].layout`
+      );
+    }
+    const l = obj.layout;
+    for (const k of ["x", "y", "w", "h"]) {
+      if (typeof l[k] !== "number") {
+        throw new DashboardConfigError(
+          `must be a number`,
+          `widgets[${idx}].layout.${k}`
+        );
+      }
+    }
+  }
+  return obj;
+}
+function validateDashboardConfig(input) {
+  if (input === null || typeof input !== "object") {
+    throw new DashboardConfigError("must be an object", "(root)");
+  }
+  const obj = input;
+  assertOptionalString(obj.name, "name");
+  assertOptionalString(obj.description, "description");
+  assertOptionalString(obj.dataset, "dataset");
+  if (!Array.isArray(obj.widgets)) {
+    throw new DashboardConfigError("must be an array", "widgets");
+  }
+  const widgets = obj.widgets.map((w, i) => validateWidget(w, i));
+  if (obj.grid !== void 0) {
+    if (typeof obj.grid !== "object" || obj.grid === null) {
+      throw new DashboardConfigError("must be an object", "grid");
+    }
+    const g = obj.grid;
+    if (g.cols !== void 0 && typeof g.cols !== "number") {
+      throw new DashboardConfigError("must be a number", "grid.cols");
+    }
+    if (g.rowHeight !== void 0 && typeof g.rowHeight !== "number") {
+      throw new DashboardConfigError("must be a number", "grid.rowHeight");
+    }
+    if (g.margin !== void 0) {
+      if (!Array.isArray(g.margin) || g.margin.length !== 2 || typeof g.margin[0] !== "number" || typeof g.margin[1] !== "number") {
+        throw new DashboardConfigError(
+          "must be a [number, number] tuple",
+          "grid.margin"
+        );
+      }
+    }
+  }
+  return { ...obj, widgets };
+}
+
+export { DashboardConfigError, DuckvizCredits, DuckvizLogFormatDetector, DuckvizReports, DuckvizUsage, DuckvizWidgetFlow, validateDashboardConfig };

package/dist/next.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+var chunkU3PJRXFJ_cjs = require('./chunk-U3PJRXFJ.cjs');
+
+// src/next.ts
+function createDuckvizHandlers(options) {
+  if (!options.token) {
+    throw new Error("createDuckvizHandlers: `token` is required");
+  }
+  const baseUrl = (options.baseUrl ?? chunkU3PJRXFJ_cjs.DEFAULT_BASE_URL).replace(/\/$/, "");
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  async function proxy(request, ctx) {
+    const params = await Promise.resolve(ctx.params);
+    const route = Array.isArray(params.route) ? params.route : [];
+    if (route.length === 0) {
+      return json({ error: "Missing route path" }, 400);
+    }
+    const incomingUrl = new URL(request.url);
+    const qs = incomingUrl.search;
+    const path = `/api/${route.join("/")}${qs}`;
+    if (options.onRequest) {
+      const result = await options.onRequest({ path, request });
+      if (result === false) {
+        return json({ error: "Request rejected" }, 403);
+      }
+    }
+    const method = request.method;
+    const hasBody = method !== "GET" && method !== "HEAD";
+    let upstream;
+    try {
+      const init = {
+        method,
+        headers: {
+          Authorization: `Bearer ${options.token}`,
+          ...hasBody && {
+            "Content-Type": request.headers.get("content-type") ?? "application/json"
+          }
+        },
+        signal: request.signal
+      };
+      if (hasBody) {
+        init.body = request.body;
+        init.duplex = "half";
+      }
+      upstream = await fetchImpl(`${baseUrl}${path}`, init);
+    } catch (err) {
+      return json(
+        {
+          error: err instanceof Error ? `Upstream fetch failed: ${err.message}` : "Upstream fetch failed"
+        },
+        502
+      );
+    }
+    const outHeaders = new Headers();
+    const ct = upstream.headers.get("content-type");
+    if (ct) outHeaders.set("Content-Type", ct);
+    const cc = upstream.headers.get("cache-control");
+    if (cc) outHeaders.set("Cache-Control", cc);
+    const ra = upstream.headers.get("retry-after");
+    if (ra) outHeaders.set("Retry-After", ra);
+    if (ct?.includes("text/event-stream")) {
+      outHeaders.set("Cache-Control", "no-cache, no-transform");
+      outHeaders.set("Connection", "keep-alive");
+      outHeaders.set("X-Accel-Buffering", "no");
+    }
+    return new Response(upstream.body, {
+      status: upstream.status,
+      headers: outHeaders
+    });
+  }
+  return { POST: proxy, GET: proxy };
+}
+function json(body, status) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+
+exports.createDuckvizHandlers = createDuckvizHandlers;