JavaScript SDK

@zapinner/sdk is a typed, dependency-free client for Node.js 18+ and modern browsers. It wraps the same HTTPS + JSON API with auth, timeouts, and transient-failure retries built in.

Install

@zapinner/sdk is implemented and package-ready but not yet published to npm. Until it ships, vendor the SDK source or install from a git ref; the command below is the intended install once publication happens.

shell

npm install @zapinner/sdk

Initialize

client.ts

import { Zapinner } from "@zapinner/sdk"

const zap = new Zapinner({
  apiKey: process.env.ZAPINNER_API_KEY, // required
  // baseUrl: "https://zapinner.com",   // optional
  // timeoutMs: 30_000,                 // optional
  // maxRetries: 2,                     // optional (429/5xx/network)
})

Use the SDK from your server. A live key must never ship in client-side browser code. In the browser, proxy requests through your own backend.

Calling capabilities

Every capability has a typed method:

examples.ts

// Normalize messy fields
const normalized = await zap.normalize({
  data: { company: " ACME, INC. ", amount: "$1,245.00" },
})

// Verify a claim against evidence
const verdict = await zap.verify({
  claim: "Invoice was paid in full",
  evidence: [{ source: "payment_ledger", value: "Payment of $11,840 received" }],
})

// Score, match, compare, dedupe, anomalies, analyze,
// reconcile, revenueLeak, leadRecovery, explain ...

normalize, dedupe, match, compare, explain, anomalies
score, verify, analyze, reconcile, revenueLeak, leadRecovery
transform, validate, extract, webExtract
Async batch jobs: submitJob, getJob, waitForJob
Limited preview (enabled per account): execute, workflowRun

Error handling

Every failure throws a typed ZapinnerError with the API's error code, HTTP status, request id, and any structured details (like the usage-limit payload):

errors.ts

import { isZapinnerError } from "@zapinner/sdk"

try {
  await zap.reconcile({ source_a, source_b, matching })
} catch (err) {
  if (isZapinnerError(err)) {
    console.error(err.code, err.status, err.requestId, err.details)
    if (err.isRateLimited) {
      // back off, or prompt an upgrade
    }
  }
}

Escape hatch

Need an endpoint the typed methods don't cover yet? Call request directly:

request.ts

await zap.request("/api/v1/normalize", { data: { name: "acme" } })

Prefer raw HTTP? See the API reference. Building an agent? See MCP.