Data API: CMS

POST /v2/collections/REPLACE_WITH_PLANTS_COLLECTION_ID/items/insert HTTP/1.1
Host: api.webflow.com
Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json

{
  "items": [
    {
      "isDraft": true,
      "fieldData": {
        "name": "English lavender",
        "slug": "english-lavender",
        "nursery-sku": "NUR-0042",
        "latin-name": "Lavandula angustifolia",
        "care-notes": "<p>Full sun and dry, well-drained soil.</p>",
        "is-endangered": false,
        "bloom-month": "REPLACE_WITH_OPTION_ID",
        "hardiness-zone": "REPLACE_WITH_ZONE_ITEM_ID"
      }
    }
  ]
}

PATCH /v2/collections/REPLACE_WITH_PLANTS_COLLECTION_ID/items HTTP/1.1
Host: api.webflow.com
Authorization: Bearer REPLACE_WITH_API_TOKEN
Content-Type: application/json

{
  "items": [
    {
      "id": "REPLACE_WITH_ITEM_ID",
      "fieldData": { "care-notes": "<p>Prune after flowering.</p>" }
    },
    {
      "id": "REPLACE_WITH_ITEM_ID",
      "cmsLocaleId": "REPLACE_WITH_SPANISH_CMS_LOCALE_ID",
      "fieldData": { "name": "Lavanda inglesa" }
    }
  ]
}

{
  "items": [
    { "id": "REPLACE_WITH_ITEM_ID", "cmsLocaleIds": ["REPLACE_WITH_EN_ID", "REPLACE_WITH_ES_ID", "REPLACE_WITH_DE_ID"] }
  ]
}

curl -X DELETE "https://api.webflow.com/v2/collections/REPLACE_WITH_PLANTS_COLLECTION_ID/items/live" \
  -H "Authorization: Bearer $WEBFLOW_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "items": [ { "id": "REPLACE_WITH_ITEM_ID" } ] }'

# Endangered plants whose SKU starts a nursery batch, newest first, 20 per page
curl -G "https://api.webflow.com/v2/collections/REPLACE_WITH_PLANTS_COLLECTION_ID/items" \
  -H "Authorization: Bearer $WEBFLOW_API_TOKEN" \
  --data-urlencode "filter[is-endangered][eq]=true" \
  --data-urlencode "filter[nursery-sku][contains]=NUR-" \
  --data-urlencode "sort[name]=asc" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"

{
  "name": "fernbrook-sync",
  "private": true,
  "type": "module",
  "scripts": {
    "sync": "tsx fernbrook-sync.ts",
    "check": "tsc --noEmit"
  },
  "devDependencies": {
    "@types/node": "26.6.6",
    "tsx": "4.23.15",
    "typescript": "7.0.2"
  }
}

export WEBFLOW_API_TOKEN="REPLACE_WITH_SITE_TOKEN"
export WEBFLOW_SITE_ID="REPLACE_WITH_SITE_ID"
export WEBFLOW_PLANTS_COLLECTION_ID="REPLACE_WITH_PLANTS_COLLECTION_ID"
export WEBFLOW_ZONES_COLLECTION_ID="REPLACE_WITH_GARDEN_ZONES_COLLECTION_ID"

npm install
npx tsx fernbrook-sync.ts --feed ./nursery-feed.json --dry-run     # report only, no writes
npx tsx fernbrook-sync.ts --feed ./nursery-feed.json --publish     # write and publish what changed
npx tsx fernbrook-sync.ts --feed ./nursery-feed.json --publish --archive-missing

// fernbrook-sync.ts - keeps the Fernbrook Gardens Plants Collection in step with the nursery feed.
import { createHash } from "node:crypto";
import { readFile, writeFile } from "node:fs/promises";

const API = "https://api.webflow.com/v2";
const MAX_ITEMS_PER_REQUEST = 100; // create, update, publish and unpublish accept up to 100 items
const MAX_RETRIES = 6;
const MAP_FILE = ".fernbrook-sync-map.json";

type FieldData = Record<string, unknown>;

interface Item {
  id: string;
  cmsLocaleId?: string;
  isArchived?: boolean;
  isDraft?: boolean;
  lastPublished?: string | null;
  fieldData: FieldData;
}

interface ItemPage {
  items: Item[];
  pagination: { total: number; limit: number; offset: number };
}

interface FeedPlant {
  sku: string;
  slug: string;
  name: string;
  latinName: string;
  careNotesHtml: string;
  endangered: boolean;
  zoneCode: string;
  bloomMonth?: string;
  translations?: Record<string, { name: string; careNotesHtml: string }>;
}

interface Locale {
  cmsLocaleId: string;
  tag: string;
}

class WebflowError extends Error {
  constructor(
    readonly status: number,
    readonly code: string | undefined,
    message: string,
    readonly details: unknown,
  ) {
    super(`HTTP ${status} ${code ?? ""} ${message}`.trim());
  }
}

const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing environment variable ${name}`);
  return value;
}

function chunk<T>(list: T[], size: number): T[][] {
  const out: T[][] = [];
  for (let i = 0; i < list.length; i += size) out.push(list.slice(i, i + size));
  return out;
}

// --- HTTP client: timeout, Retry-After on 429, exponential backoff with jitter on 5xx and network errors ---
async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
  const token = env("WEBFLOW_API_TOKEN");
  for (let attempt = 0; ; attempt++) {
    let res: Response;
    try {
      res = await fetch(`${API}${path}`, {
        method,
        headers: {
          Authorization: `Bearer ${token}`,
          Accept: "application/json",
          ...(body === undefined ? {} : { "Content-Type": "application/json" }),
        },
        body: body === undefined ? undefined : JSON.stringify(body),
        signal: AbortSignal.timeout(30_000),
      });
    } catch (error) {
      if (attempt >= MAX_RETRIES) throw error;
      await sleep(backoff(attempt)); // network error or timeout
      continue;
    }

    if (res.ok) {
      if (res.headers.get("X-RateLimit-Remaining") === "0") await sleep(61_000); // the minute budget is spent; wait for the window to reset
      return (res.status === 204 ? undefined : await res.json()) as T;
    }

    const payload = (await res.json().catch(() => ({}))) as {
      code?: string;
      message?: string;
      details?: unknown;
    };
    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || attempt >= MAX_RETRIES) {
      throw new WebflowError(res.status, payload.code, payload.message ?? res.statusText, payload.details);
    }
    const retryAfter = Number(res.headers.get("Retry-After"));
    const wait = res.status === 429 ? (Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 60_000) : backoff(attempt);
    console.warn(`  ${res.status} on ${method} ${path}; retry ${attempt + 1} in ${Math.round(wait / 1000)} s`);
    await sleep(wait);
  }
}

function backoff(attempt: number): number {
  return Math.min(30_000, 1000 * 2 ** attempt) + Math.floor(Math.random() * 500);
}

// --- Schema lookups ---
async function getLocales(siteId: string): Promise<{ primary: Locale; secondary: Locale[] }> {
  const site = await request<{ locales: { primary: Locale; secondary?: Locale[] } }>("GET", `/sites/${siteId}`);
  return { primary: site.locales.primary, secondary: site.locales.secondary ?? [] };
}

async function getOptionIds(collectionId: string, fieldSlug: string): Promise<Map<string, string>> {
  const collection = await request<{
    fields: { slug: string; validations?: { options?: { id: string; name: string }[] } }[];
  }>("GET", `/collections/${collectionId}`);
  const field = collection.fields.find((f) => f.slug === fieldSlug);
  return new Map((field?.validations?.options ?? []).map((o) => [o.name, o.id]));
}

async function listAll(collectionId: string): Promise<Item[]> {
  const items: Item[] = [];
  for (let offset = 0; ; ) {
    const page = await request<ItemPage>("GET", `/collections/${collectionId}/items?limit=100&offset=${offset}`);
    items.push(...page.items);
    offset += page.items.length;
    if (page.items.length === 0 || offset >= page.pagination.total) return items;
  }
}

// --- Planning ---
const hashOf = (plant: FeedPlant): string => createHash("sha256").update(JSON.stringify(plant)).digest("hex").slice(0, 32);

function toFieldData(plant: FeedPlant, zoneIds: Map<string, string>, bloomIds: Map<string, string>): FieldData {
  const zoneId = zoneIds.get(plant.zoneCode);
  if (!zoneId) throw new Error(`Unknown zone code ${plant.zoneCode} for ${plant.sku}`);
  const data: FieldData = {
    name: plant.name,
    slug: plant.slug,
    "nursery-sku": plant.sku,
    "latin-name": plant.latinName,
    "care-notes": plant.careNotesHtml,
    "is-endangered": plant.endangered,
    "hardiness-zone": zoneId,
    "sync-hash": hashOf(plant),
  };
  if (plant.bloomMonth) {
    const optionId = bloomIds.get(plant.bloomMonth);
    if (!optionId) throw new Error(`Unknown bloom month ${plant.bloomMonth} for ${plant.sku}`);
    data["bloom-month"] = optionId;
  }
  return data;
}

interface Plan {
  create: FeedPlant[];
  update: { plant: FeedPlant; id: string }[];
  skip: number;
  archive: Item[];
}

function plan(feed: FeedPlant[], existing: Item[], map: Record<string, string>, archiveMissing: boolean): Plan {
  const bySku = new Map<string, Item>();
  const bySlug = new Map<string, Item>();
  for (const item of existing) {
    const sku = item.fieldData["nursery-sku"];
    if (typeof sku === "string" && sku) bySku.set(sku, item);
    bySlug.set(String(item.fieldData.slug), item);
  }
  const byId = new Map(existing.map((i) => [i.id, i]));
  const result: Plan = { create: [], update: [], skip: 0, archive: [] };
  const seen = new Set<string>();

  for (const plant of feed) {
    if (seen.has(plant.sku)) throw new Error(`Duplicate SKU ${plant.sku} in the feed`);
    seen.add(plant.sku);
    const found = bySku.get(plant.sku) ?? (map[plant.sku] ? byId.get(map[plant.sku]) : undefined) ?? bySlug.get(plant.slug);
    if (!found) result.create.push(plant);
    else if (found.fieldData["sync-hash"] === hashOf(plant) && !found.isArchived) result.skip++;
    else result.update.push({ plant, id: found.id });
  }
  if (archiveMissing) {
    result.archive = existing.filter((i) => {
      const sku = i.fieldData["nursery-sku"];
      return typeof sku === "string" && sku && !seen.has(sku) && !i.isArchived;
    });
  }
  return result;
}

// --- Writes ---
async function main(): Promise<void> {
  const args = process.argv.slice(2);
  const flag = (name: string) => args.includes(name);
  const feedPath = args[args.indexOf("--feed") + 1] ?? "./nursery-feed.json";
  const dryRun = flag("--dry-run");
  const publish = flag("--publish");

  const siteId = env("WEBFLOW_SITE_ID");
  const plantsId = env("WEBFLOW_PLANTS_COLLECTION_ID");
  const zonesId = env("WEBFLOW_ZONES_COLLECTION_ID");

  const feed = JSON.parse(await readFile(feedPath, "utf8")) as FeedPlant[];
  const map: Record<string, string> = await readFile(MAP_FILE, "utf8").then(JSON.parse, () => ({}));

  const { primary, secondary } = await getLocales(siteId);
  const allLocales = [primary, ...secondary];
  const bloomIds = await getOptionIds(plantsId, "bloom-month");
  const zoneIds = new Map(
    (await listAll(zonesId)).map((z) => [String(z.fieldData["short-code"]), z.id] as [string, string]),
  );
  const existing = (await listAll(plantsId)).filter((i) => !i.cmsLocaleId || i.cmsLocaleId === primary.cmsLocaleId);

  const p = plan(feed, existing, map, flag("--archive-missing"));
  console.log(`feed ${feed.length}: create ${p.create.length}, update ${p.update.length}, skip ${p.skip}, archive ${p.archive.length}`);
  if (dryRun) return;

  const changedIds = new Set<string>();
  const translations: { id: string; localeId: string; data: FieldData }[] = [];
  const addTranslations = (plant: FeedPlant, id: string) => {
    for (const locale of secondary) {
      const t = plant.translations?.[locale.tag.split("-")[0]];
      if (t) translations.push({ id, localeId: locale.cmsLocaleId, data: { name: t.name, "care-notes": t.careNotesHtml } });
    }
  };

  // 1. Create: every locale counts toward the limit of 100 items per request
  const createBatch = Math.max(1, Math.floor(MAX_ITEMS_PER_REQUEST / allLocales.length));
  for (const batch of chunk(p.create, createBatch)) {
    const res = await request<{ items: Item[] }>("POST", `/collections/${plantsId}/items/insert`, {
      items: batch.map((plant) => ({ isDraft: true, allCmsLocales: true, fieldData: toFieldData(plant, zoneIds, bloomIds) })),
    });
    for (const item of res.items) {
      const sku = String(item.fieldData["nursery-sku"]);
      map[sku] = item.id;
      changedIds.add(item.id);
    }
    for (const plant of batch) if (map[plant.sku]) addTranslations(plant, map[plant.sku]);
  }

  // 2. Update the primary locale (the slug is not sent again)
  for (const batch of chunk(p.update, MAX_ITEMS_PER_REQUEST)) {
    await request("PATCH", `/collections/${plantsId}/items`, {
      items: batch.map(({ plant, id }) => {
        const { slug: _slug, ...rest } = toFieldData(plant, zoneIds, bloomIds);
        return { id, isArchived: false, fieldData: rest };
      }),
    });
    for (const { plant, id } of batch) {
      map[plant.sku] = id;
      changedIds.add(id);
      addTranslations(plant, id);
    }
  }

  // 3. Translations: one entry per item and locale, each with its own cmsLocaleId
  for (const batch of chunk(translations, MAX_ITEMS_PER_REQUEST)) {
    await request("PATCH", `/collections/${plantsId}/items`, {
      items: batch.map((t) => ({ id: t.id, cmsLocaleId: t.localeId, fieldData: t.data })),
    });
  }

  // 4. Archive items that vanished from the feed (opt-in)
  for (const batch of chunk(p.archive, MAX_ITEMS_PER_REQUEST)) {
    await request("PATCH", `/collections/${plantsId}/items`, {
      items: batch.map((i) => ({ id: i.id, isArchived: true })),
    });
  }

  // 5. Publish exactly the items that changed, in every locale
  let publishErrors: string[] = [];
  if (publish && changedIds.size > 0) {
    for (const batch of chunk([...changedIds], createBatch)) {
      const res = await request<{ publishedItemIds?: string[]; errors?: string[] }>(
        "POST",
        `/collections/${plantsId}/items/publish`,
        { items: batch.map((id) => ({ id, cmsLocaleIds: allLocales.map((l) => l.cmsLocaleId) })) },
      );
      publishErrors = publishErrors.concat(res.errors ?? []);
    }
  }

  await writeFile(MAP_FILE, JSON.stringify(map, null, 2) + "\n");
  console.log(`written ${changedIds.size} items, published ${publish ? changedIds.size - publishErrors.length : 0}`);
  if (publishErrors.length > 0) {
    console.error("Publish errors:", publishErrors);
    process.exitCode = 1;
  }
}

main().catch((error) => {
  if (error instanceof WebflowError) console.error(error.message, JSON.stringify(error.details));
  else console.error(error);
  process.exitCode = 1;
});