@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

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.

// 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:

// 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

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)

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

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