Overview

@duckviz/sdk is a Node.js SDK that proxies AI requests to DuckViz from your server. It keeps your API token out of the browser and lets you attach access control, logging, and billing to every request.

Installation

npm install @duckviz/sdk

The SDK has optional peer dependencies for each framework adapter (hono, fastify, express) — install only the one you use.

What you get

Authentication

The SDK uses Personal Access Tokens (PAT) for authentication. Generate a token from the DuckViz app:

1. Go to app.duckviz.com/settings/tokens
2. Click Create Token
3. Copy the token (starts with dvz_live_)

Store it in an environment variable:

DUCKVIZ_API_TOKEN=dvz_live_abc123...

Every SDK class accepts this token via its constructor:

import { DuckvizWidgetFlow } from "@duckviz/sdk";

const widgetFlow = new DuckvizWidgetFlow({
  token: process.env.DUCKVIZ_API_TOKEN!,
});

Token security

PAT format is dvz_live_<24 base62 chars> — 24 random characters of unbiased entropy. Tokens are shown to you exactly once at creation and cannot be retrieved later; lose the original and you must mint a new one.

On the server we store a salted hash, never the token itself:

• Algorithm: PBKDF2-SHA256, 100,000 iterations, 16-byte random salt, 32-byte output
• Storage format: Django-style — pbkdf2_sha256$100000$<salt_b64>$<hash_b64>
• Why PBKDF2: it runs natively in the Cloudflare Workers Web Crypto API. Argon2 would need WASM and a meaningful cold-start cost we'd rather avoid

Verification adds about 10–50 ms per request — acceptable because tokens are long-lived and verifications are infrequent compared to general traffic.

For O(1) lookup without a full table scan, the first 8 characters of the random portion are stored in a partial index (WHERE revoked_at IS NULL); the rare prefix collision is resolved by iterating active rows. Revocation flips revoked_at and the next request fails 401 — no stale-cache window.

Common constructor options

All SDK classes share the same constructor shape:

Quick start with Next.js

The fastest path is the Next.js App Router catch-all handler:

// app/api/duckviz/[...route]/route.ts
import { createDuckvizHandlers } from "@duckviz/sdk/next";

export const { POST, GET } = createDuckvizHandlers({
  token: process.env.DUCKVIZ_API_TOKEN!,
});

Then configure the Explorer to use your proxy:

<Explorer
  customFetch={(input, init) => {
    const url = typeof input === "string" ? input : input.url;
    const proxied = url.replace(/^\/api\//, "/api/duckviz/");
    return fetch(proxied, init);
  }}
  authenticated={true}
  // ... other props
/>

See Adapters for the full Next.js, Hono, Fastify, and Express guides, or Server Proxy Setup for access control patterns.