Test

The first run immediately produced this error for every single batch:

Batch IDs 112, 113, 114, 115, 116:
Unterminated string in JSON at position 3666
(line 33 column 101)

// Before
const PRODUCTS_PER_BATCH = 5;
max_tokens: 1000

// After
const PRODUCTS_PER_BATCH = 2;
max_tokens: 4000

// Add retry logic on JSON parse failure
try {
  parsed = JSON.parse(clean);
} catch {
  for (const p of batch) {
    const r = await callAPI([p]);
    parsed.push(...r);
  }
}

Processing 1,557 products takes time. If the tab closes or the user logs out mid-run, all progress is lost. The solution is to save results to localStorage after every batch.

const STORAGE_KEY = "bc_seo_progress";

localStorage.setItem(STORAGE_KEY, JSON.stringify({
  savedResults:      current,
  savedFileName:     fileName,
  savedProductCount: products.length,
  savedAt:           new Date().toISOString(),
}));

useEffect(() => {
  const raw = localStorage.getItem(STORAGE_KEY);
  if (!raw) return;
  const { savedResults } = JSON.parse(raw);
  if (savedResults) {
    E.results = savedResults;
    setUiStatus("restored");
  }
}, []);

const current = { ...E.results };
const todo = products.filter(p => !current[p.id]);
// Only processes products not yet in results

After the first successful download, re-importing the CSV into BigCommerce added extra rows. Product descriptions containing HTML bullet lists with embedded newlines were being split across multiple rows.

// This is ONE CSV cell — correctly quoted in the original file:
"<ul>
<li>Round necklace & stud earring set</li>
<li>Purple mother of pearl shell</li>
<li>Pendant 15mm high</li>
</ul>"

// Custom JS parser incorrectly split this into 5 separate rows

// ❌ Before — custom parser, breaks on multiline fields
function parseCSV(text) {
  const lines = text.split('\n'); // WRONG
}

// ✅ After — PapaParse handles all edge cases
Papa.parse(file, {
  header: true,
  skipEmptyLines: false, // keep ALL rows
  complete: (parsed) => { ... }
});

// ✅ Write back with proper quoting
const csv = Papa.unparse({ fields, data: updated }, {
  quotes: true,
  newline: "\n",
});

Running 1,557 products in batches of 2 means roughly 780 API calls. On a standard plan this will eventually hit a usage limit. Instead of requiring the user to manually resume, the app should detect the error, wait, and resume automatically.

function isCreditError(msg, httpStatus) {
  return /credit|billing|payment|quota|insufficient/i
    .test(msg || '') || httpStatus === 402;
}
function isRateLimit(msg, httpStatus) {
  return /rate.limit|overloaded/i.test(msg || '')
    || httpStatus === 429 || httpStatus === 529;
}

async function probeCredits() {
  try {
    const res = await fetch(API_URL, { ...body });
    const data = await res.json();
    if (!data.error) return { ok: true }; // ✅ credits restored
    if (isCreditError(data.error.message, res.status))
      return { ok: false, reason: "credit" };
    return { ok: true }; // other API error = billing fine, resume
  } catch {
    return { ok: false, reason: "network" };
  }
}

E.schedulePoll = function(attempt) {
  let secs = 60;
  E.cdTimer = setInterval(() => {
    setUiCountdown(--secs);
  }, 1000);

  E.pollTimer = setTimeout(async () => {
    clearInterval(E.cdTimer);
    const probe = await probeCredits();
    if (probe.ok) {
      E.runLoop(); // ✅ resume immediately
    } else {
      E.schedulePoll(attempt + 1);
    }
  }, 60000);
};

Auto-resume still didn't work. The probe succeeded and called runLoop() — but nothing happened. This was the most subtle bug of the entire build.

// Create the engine once and store in a ref
const engineRef = useRef(null);
if (!engineRef.current) {
  engineRef.current = createEngine(setters);
}

// Inside createEngine() — plain functions, no hooks
function createEngine(setters) {
  const E = { products: null, results: {}, isRunning: false };

  E.schedulePoll = function(attempt) {
    E.pollTimer = setTimeout(async () => {
      // Always calls E.runLoop — the SAME live function
      if ((await probeCredits()).ok) E.runLoop(); // ✅
      else E.schedulePoll(attempt + 1);
    }, 60000);
  };

  E.runLoop = async function() { /* ... */ };
  return E;
}

Use this when building your own version. Each item is a lesson learned from this real build.

• ○
  System prompt ends with "Respond ONLY with valid JSON array" — prevents markdown fences breaking JSON.parse()
• ○
  max_tokens ≥ 4,000 — never use 1,000 for multi-product batches
• ○
  Batch size ≤ 2 for reliability; add individual retry fallback on JSON parse failure
• ○
  Use PapaParse for both reading and writing CSV files — never a custom parser
• ○
  Papa.unparse with quotes: true — safely handles descriptions with newlines, HTML, commas
• ○
  Only overwrite the target columns — spread original row first: { ...row, "Page Title": ... }
• ○
  Save to localStorage after every batch — not just at the end
• ○
  Restore on mount — check localStorage in useEffect, pre-populate results before user does anything
• ○
  Classify errors correctly — credit errors need polling; rate limits need 30s wait; other errors skip and continue
• ○
  probeCredits() must return true for non-credit API errors — only billing errors should keep polling
• ○
  Use the engine pattern for any async loop that calls itself — plain object in useRef, not useCallback
• ○
  Use base64 data URI for CSV download — URL.createObjectURL is blocked in sandboxed iframes
• ○
  isRunning flag — prevents runLoop() from being called twice concurrently
• ○
  Add console.log at probe and runLoop entry — essential for debugging auto-resume