Admin SDK

npm install @usethrottle/catalog
# or
pnpm add @usethrottle/catalog

import { createCatalogAdmin } from '@usethrottle/catalog/admin';
import type { PushRow } from '@usethrottle/catalog/admin';

const admin = createCatalogAdmin({ key: process.env.CATALOG_ADMIN_KEY ?? '' });

// The rows of one product must be next to each other, in one batch.
const rows: PushRow[] = [
  {
    externalId: 'hr-1001',
    productHandle: 'ethiopia-guji',
    sku: 'HR-GUJI-250',
    status: 'active',
    product: { title: 'Ethiopia Guji', brand: 'Highland Roasters' },
    variant: { priceMinor: 1850, currency: 'USD', quantity: 40 },
  },
];

// Open a job, stage the batches, close it: nothing applies before the close.
const job = await admin.jobs.run(rows, { mode: 'merge' });

// wait() resolves when the job has finished or expired. A job that failed
// still resolves: read failureCode.
const done = await job.wait();
if (done.failureCode !== null) {
  console.error(done.failureCode);
  console.error(await job.errorsCsv());
} else {
  console.log(done.created, done.updated, done.unchanged, done.rowsFailed);
}

import { createCatalogAdmin } from '@usethrottle/catalog/admin';
import type { PushRow } from '@usethrottle/catalog/admin';

const admin = createCatalogAdmin({ key: process.env.CATALOG_ADMIN_KEY ?? '' });

const feed: PushRow[][] = [
  [{ externalId: 'hr-1001', productHandle: 'ethiopia-guji', sku: 'HR-GUJI-250' }],
  [{ externalId: 'hr-1002', productHandle: 'kenya-aa', sku: 'HR-KAA-250' }],
];

// fullSync runs once, at close, over everything the job sent.
const job = await admin.jobs.open({ mode: 'replace', fullSync: true });

for (const [index, rows] of feed.entries()) {
  // The same key on a retry answers the first answer again. The SDK makes one
  // when you pass none; naming it yourself lets a restarted process resend.
  const batch = await job.send(rows, { idempotencyKey: `${job.jobId}:${index}` });
  if (batch.rowsRefused > 0) console.warn(batch.issues);
}

// Applies every staged batch, in the order they arrived.
await job.close();

// Later, even from another process: no request is sent by resume().
const same = admin.jobs.resume(job.jobId);
const progress = await same.get({ includeBatches: true });
console.log(progress.state, progress.batchesApplied, progress.rowsApplied);

import { createCatalogAdmin, isCatalogError, RateLimitedError } from '@usethrottle/catalog/admin';

const admin = createCatalogAdmin({ key: process.env.CATALOG_ADMIN_KEY ?? '' });

try {
  await admin.inventory.set([{ sku: 'HR-GUJI-250', quantity: 40 }]);
} catch (error) {
  if (error instanceof RateLimitedError) {
    // RATE_LIMITED and PUSH_QUEUE_FULL: wait this long, then send again.
    console.log(error.retryAfterSeconds);
  } else if (isCatalogError(error)) {
    // Branch on the code, and read the per-field problems.
    console.log(error.statusCode, error.code, error.issues, error.retryable);
  } else {
    throw error;
  }
}