@zilco/sdk

Official Node.js / TypeScript client for the Zilco catalog sync API.

Use this SDK server-side only with your secret sync API key (sk_live_...). Never expose the key in browser or frontend code.

Requirements

• Node.js 18+ (uses native fetch)

Install

npm install @zilco/sdk

For local monorepo development:

pnpm --filter @zilco/sdk build

Quick start

import { ZilcoClient } from '@zilco/sdk';

const client = new ZilcoClient({
  apiKey: process.env.ZILCO_API_KEY!,
  siteId: process.env.ZILCO_SITE_ID,
  // baseUrl defaults to https://api.zilco.ai
});

await client.items.upsert({
  external_id: 'prod-001',
  language: 'en',
  title: 'Bosch Drill 18V',
  price: 149.99,
  currency: 'EUR',
  active: true,
});

Full sync example

import { ZilcoClient } from '@zilco/sdk';

const client = new ZilcoClient({
  apiKey: process.env.ZILCO_API_KEY!,
  siteId: process.env.ZILCO_SITE_ID,
});

const items = [
  { external_id: 'prod-001', language: 'en', title: 'Item A', active: true },
  { external_id: 'prod-002', language: 'en', title: 'Item B', active: true },
];

const { sync_id } = await client.sync.start();
const upsert = await client.items.bulkUpsert(items, { syncId: sync_id });

for (const jobId of upsert.jobIds) {
  const job = await client.jobs.wait(jobId);
  console.log(`Job ${jobId}: ${job.status}`);
}

await client.sync.finish(sync_id);

API surface

| Resource | Methods | |----------|---------| | client.items | upsert, bulkUpsert, delete, bulkDelete, list | | client.sync | start, finish | | client.jobs | get, wait | | client.search | query |

Options

| Option | Default | Description | |--------|---------|-------------| | apiKey | required | Secret sync API key | | siteId | — | Required for account-wide keys | | baseUrl | https://api.zilco.ai | API origin | | timeoutMs | 60000 | Request timeout | | maxRetries | 5 | Retries for 429/5xx | | validateInput | true | Zod validation before send |

Behavior

• Batches upserts in chunks of 100 and deletes in chunks of 500
• Pauses ~200ms between batches
• Retries rate limits using Retry-After
• Retries server errors with exponential backoff
• Does not retry client errors (4xx)
• Validates payloads against the catalog item schema

Errors

• ZilcoApiError — HTTP/API failures (status, body)
• ZilcoValidationError — invalid input before send
• ZilcoTimeoutError — request timeout

Documentation

This README is the primary reference for the SDK. For the full catalog sync API (endpoints, item schema, rate limits, and Postman collections), sign in to your Zilco dashboard and open Sync API.

Product and onboarding: zilco.ai

License

MIT