Build with Zapi,
fully typed.

Overview

zpi-sdk is a universal, zero-runtime-dependency TypeScript SDK for Zapi. It ships a dual ESM + CJS build (sideEffects: false) and runs on Node ≥ 20, Bun, Deno, and in the browser behind a proxy. MIT-licensed, source at github.com/zeative/zpi-sdk.

Installation

npm i zpi-sdk

pnpm add zpi-sdk

yarn add zpi-sdk

bun add zpi-sdk

import { ZpiClient } from "npm:zpi-sdk";

Quickstart

Create a client with your API key and call run() with a project key in category:scraper format:

import { ZpiClient } from "zpi-sdk";

const client = new ZpiClient({ apiKey: "zpi_..." });

// projectKey is "category:scraper" — no HTTP method needed,
// the SDK detects and remembers the right verb per endpoint
const profile = await client.run("social:instagram", "profile", {
  username: "instagram",
});
console.log(profile);

The response envelope is { project, data, timestamp } — the SDK unwraps and returns data directly.

Authentication

apiKey is the only required option — the constructor throws if it's missing. It's sent as the x-api-key header on every request. Create a key at Dashboard → API Keys and copy it once — the full key can't be recovered later.

import { ZpiClient } from "zpi-sdk";

const client = new ZpiClient({ apiKey: process.env.ZPI_API_KEY });

// The key lives in a private field and never leaks through serialization:
JSON.stringify(client); // "{}"

Configuration

Everything new ZpiClient(options) accepts:

run()

run<T = unknown>(projectKey, endpoint, params?, opts?): Promise<T> issues a single scraper call. The request URL is {baseURL}/v1/{projectKey}/{endpoint}[/{pathRest}]. You don't pick an HTTP method — the SDK auto-detects the endpoint's verb (a wrong first guess is flipped once on 405 and the learned verb is memoized per endpoint). GET params become the query string, POST params the JSON body. Path params like :slug are plain fields in params — no URL templating needed.

// No method to pick — auto-detected (and memoized) per endpoint.
const spot = await client.run("finance:goldprice", "spot", {});

// Endpoints with path params (e.g. article/:slug)? Path params are
// just regular fields in params — all of these are equivalent:
await client.run("finance:goldprice", "article", { slug: "gold-hits-ath" });
await client.run("finance:goldprice", "article/:slug", { slug: "gold-hits-ath" });

// Explicit method still works and skips auto-detection:
const data = await client.run(
  "social:instagram",
  "profile",
  { username: "instagram" },
  { method: "GET" }
);

Streaming

stream(projectKey, endpoint, params?, opts?) returns an AsyncIterable<StreamEvent> for SSE and chunked endpoints. text/event-stream responses yield SseEvent objects ({ event?, data, id? }); any other body yields raw text chunks.

for await (const event of client.stream("ai:chat", "completions", {
  prompt: "hi",
})) {
  // SSE responses yield { event?, data, id? }; other bodies yield raw text
  console.log(typeof event === "string" ? event : event.data);
}

Bulk

client.bulk.submit(projectKey, endpoint, items) POSTs to /v1/{projectKey}/{endpoint}/bulk and returns a BulkJob handle. The SDK attaches an automatic Idempotency-Key (crypto.randomUUID) so retries never double-submit. client.bulk.status(jobId) does a single poll.

const job = await client.bulk.submit("social:instagram", "profile", [
  { url: "https://instagram.com/a" },
  { url: "https://instagram.com/b" },
]);

const result = await job.wait({
  onProgress: (j) => console.log(j.succeeded, "/", j.total),
});
for (const item of result.items ?? []) {
  console.log(item.status, item.data ?? item.error);
}

job.wait({ signal?, timeoutMs?, pollIntervalMs?, onProgress? }) polls with backoff (base 500 ms, capped at 5 s) until the job is terminal. Job statuses: QUEUED | RUNNING | COMPLETED | FAILED | CANCELLED; per-item statuses: QUEUED | RUNNING | SUCCEEDED | FAILED.

Catalog

client.catalog reads the public scraper catalog — no auth required, served outside /v1:

const { items } = await client.catalog.list({ cat: "social", limit: 20 });
const detail = await client.catalog.get("social:instagram");
const schema = await client.catalog.schema("social:instagram", "profile");

Error handling

Every failure throws ZpiError or a subclass. The base class carries status, code?, raw, and requestId? (from the x-request-id header) — include the request id when reporting issues.

import {
  ZpiError,
  ZpiPlanGateError,
  ZpiRateLimitError,
} from "zpi-sdk";

try {
  const data = await client.run("social:instagram", "profile", {
    username: "instagram",
  });
} catch (e) {
  if (e instanceof ZpiPlanGateError) {
    console.log("upgrade:", e.requiredPlan, e.upgradeUrl);
  } else if (e instanceof ZpiRateLimitError) {
    console.log("retry after", e.retryAfterSec, "s");
  } else if (e instanceof ZpiError) {
    console.log(e.status, e.code, e.raw);
  }
}

Retries & timeouts

The client retries only network errors and HTTP 429 / 502 / 503 / 504, with exponential backoff (base × 2ⁿ plus jitter). Other 4xx responses are never retried.

• The Retry-After header and the 429 body's retryAfterSec are honored — the server-provided delay wins over the backoff schedule.
• POST requests are retried only when you pass an idempotencyKey; the same key is reused across attempts so nothing runs twice.
• Streams are never retried.
• Timeouts use an AbortController composed with your external signal — a timeout throws ZpiTimeoutError, your own abort throws ZpiAbortError.

Typed results

run() is generic, and the ScraperMap interface supports declaration merging — register a scraper's shape once and every call to it is fully typed. Params are enforced: a missing required field is a compile error, not a runtime 400.

// The export {} makes this file a module AUGMENTATION —
// without it the block would shadow the real package types.
export {};

declare module "zpi-sdk" {
  interface ScraperMap {
    "social:instagram": {
      profile: {
        params: { username: string };
        result: { id: string; name: string };
      };
    };
  }
}

You rarely write this by hand — the codegen CLI below emits it from the live catalog.

Codegen CLI

npx zpi codegen crawls the catalog (concurrency 5) and emits a types-only .d.ts with zero runtime imports. Endpoints with unusable schemas fall back to Record<string, unknown> — never any.

npx zpi codegen --base https://api.zpi.web.id --out ./zpi-sdk.gen.d.ts

# narrow to one category, authenticate for gated schemas
npx zpi codegen --filter social --key zpi_xxx

Programmatic use: generate({ baseURL, out, fetch?, filter?, key? }) from zpi-sdk/codegen resolves to { written, scrapers, endpoints }.

Webhooks

Webhooks push events to your server — bulk.completed / bulk.failed / bulk.item, quota.warning / quota.exceeded, request.error, key.created / key.disabled / key.deleted, and webhook.test. Manage endpoints at Dashboard → Webhooks. Every delivery is signed: X-Zpi-Signature: sha256=<hex(hmac_sha256(secret, body))>, with the event name in X-Zpi-Event.

zpi-sdk/webhooks verifies and parses deliveries in one call — Web Crypto with a timing-safe compare, so the same code runs on Node, Bun, Deno, and edge runtimes:

import { parseWebhook } from "zpi-sdk/webhooks";

// In your HTTP handler — pass the RAW body string, not parsed JSON:
const event = await parseWebhook(rawBody, {
  signature: req.headers["x-zpi-signature"],
  secret: process.env.ZPI_WEBHOOK_SECRET,
});
// → { id, event: "bulk.completed" | ..., data, deliveredAt }
// Throws ZpiWebhookVerifyError on a bad signature or malformed payload.

switch (event.event) {
  case "bulk.completed":
    console.log("job done:", event.data);
    break;
  case "quota.warning":
    console.log("almost out of quota");
    break;
}

MCP client

zpi-sdk/mcp is a zero-dependency JSON-RPC client for the remote Zapi MCP server (Streamable HTTP, protocol 2025-06-18, session via mcp-session-id). RPC failures throw ZpiMcpError.

import { createMcpClient } from "zpi-sdk/mcp";

const mcp = createMcpClient({
  apiKey: "zpi_...",
  baseURL: "https://api.zpi.web.id",
});
const tools = await mcp.listTools();
const result = await mcp.callTool("run_scraper", { /* ... */ });

Connecting an AI client (Claude, Cursor, VS Code, …) instead? See the MCP server docs — tools reference, per-client setup, and limits.

REST API

The SDK wraps a plain REST API — usable from any language. Base URL https://api.zpi.web.id, scraper calls at /v1/{category:scraper}/{endpoint}, authenticated with the x-api-key header:

curl -X POST "https://api.zpi.web.id/v1/social:instagram/profile" \
  -H "x-api-key: zpi_xxx" \
  -H "content-type: application/json" \
  -d '{"username":"instagram"}'

# response envelope — the SDK unwraps .data for you
# { "project": "social:instagram", "data": { ... }, "timestamp": ... }

Error statuses match the error table above — 401 bad key, 403 plan gate, 429 rate limit (respect Retry-After), 5xx retry with backoff. Bulk jobs live at POST /v1/{category:scraper}/{endpoint}/bulk and GET /v1/bulk/{jobId}.

Next steps