Export Freshdesk knowledge base articles

// export-freshdesk-kb.mjs: export every Freshdesk solution article, with its content, to CSV + one HTML file each.
// Node 22+, no dependencies, read-only (GET requests only). Source: https://tidykb.net/tools/freshdesk-knowledge-base-export
//
//   FRESHDESK_DOMAIN=yourcompany.freshdesk.com FRESHDESK_API_KEY=your_key node export-freshdesk-kb.mjs
//   ... node export-freshdesk-kb.mjs fr        # one translation (language code as in Freshdesk)
//
// Optional: RATE_PER_MINUTE (default 40, stay well under your plan's limit), OUT_DIR (default ./freshdesk-kb-export).
import { mkdir, writeFile } from 'node:fs/promises';
import { join } from 'node:path';

const domain = process.env.FRESHDESK_DOMAIN;
const apiKey = process.env.FRESHDESK_API_KEY;
const lang = process.argv[2] ?? '';
const perMinute = Number(process.env.RATE_PER_MINUTE ?? 40);
const outDir = process.env.OUT_DIR ?? 'freshdesk-kb-export';
if (!domain || !apiKey) {
  console.error('Set FRESHDESK_DOMAIN (yourcompany.freshdesk.com) and FRESHDESK_API_KEY.');
  process.exit(1);
}
const base = process.env.FRESHDESK_API_BASE ?? `https://${domain}/api/v2`;
const auth = `Basic ${Buffer.from(`${apiKey}:X`).toString('base64')}`;
const suffix = lang ? `/${encodeURIComponent(lang)}` : '';
const gapMs = 60000 / perMinute;
let lastCall = 0;
let calls = 0;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// GET with a steady pace, Retry-After on 429 and a few retries on 5xx. 404 = "not there" (e.g. no subfolders).
async function get(path) {
  for (let attempt = 1; ; attempt++) {
    const wait = lastCall + gapMs - Date.now();
    if (wait > 0) await sleep(wait);
    lastCall = Date.now();
    calls++;
    const res = await fetch(base + path, { headers: { Authorization: auth, Accept: 'application/json' } });
    if (res.status === 429 && attempt <= 6) {
      const seconds = Number(res.headers.get('retry-after')) || 60;
      console.error(`Rate limited, waiting ${seconds}s`);
      await sleep(seconds * 1000);
      continue;
    }
    if (res.status >= 500 && attempt <= 3) {
      await sleep(2000 * attempt);
      continue;
    }
    if (res.status === 404) return null;
    if (!res.ok) throw new Error(`${res.status} on GET ${path}: ${(await res.text()).slice(0, 300)}`);
    return res.json();
  }
}

// Every page of a list endpoint (max 100 per page).
async function list(path) {
  const items = [];
  for (let page = 1; ; page++) {
    const batch = await get(`${path}?per_page=100&page=${page}`);
    if (!Array.isArray(batch) || batch.length === 0) break;
    items.push(...batch);
    if (batch.length < 100) break;
  }
  return items;
}

// Folders of a category, then their subfolders (Freshdesk's flexible hierarchy), depth-first.
async function walkFolders(parentPath, trail, into) {
  for (const folder of await list(parentPath)) {
    const path = [...trail, folder.name];
    into.push({ folder, path });
    await walkFolders(`/solutions/folders/${folder.id}/subfolders${suffix}`, path, into);
  }
}

const csvCell = (value) => {
  let s = value == null ? '' : Array.isArray(value) ? value.join('; ') : String(value);
  if (/^[=+\-@\t\r]/.test(s)) s = `'${s}`;
  return /[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
};
const slug = (s) => String(s).toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60) || 'article';
const escapeHtml = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);

const columns = ['id', 'title', 'status', 'category', 'folder_path', 'language', 'portal_url', 'created_at', 'updated_at', 'views', 'thumbs_up', 'thumbs_down', 'tags', 'seo_title', 'seo_description', 'html_file'];
const rows = [];
const htmlDir = join(outDir, lang ? `html-${lang}` : 'html');
await mkdir(htmlDir, { recursive: true });

for (const category of await list(`/solutions/categories${suffix}`)) {
  const folders = [];
  await walkFolders(`/solutions/categories/${category.id}/folders${suffix}`, [], folders);
  for (const { folder, path } of folders) {
    for (const a of await list(`/solutions/folders/${folder.id}/articles${suffix}`)) {
      const file = `${a.id}-${slug(a.title)}.html`;
      const page = `<!doctype html>\n<meta charset="utf-8">\n<title>${escapeHtml(a.title)}</title>\n<h1>${escapeHtml(a.title)}</h1>\n${a.description ?? ''}\n`;
      await writeFile(join(htmlDir, file), page);
      rows.push({
        id: a.id,
        title: a.title,
        status: a.status === 2 ? 'published' : a.status === 1 ? 'draft' : a.status,
        category: category.name,
        folder_path: path.join(' / '),
        language: lang || 'primary',
        portal_url: `https://${domain}/support/solutions/articles/${a.id}`,
        created_at: a.created_at,
        updated_at: a.updated_at,
        views: a.hits,
        thumbs_up: a.thumbs_up,
        thumbs_down: a.thumbs_down,
        tags: a.tags,
        seo_title: a.seo_data?.meta_title,
        seo_description: a.seo_data?.meta_description,
        html_file: join(lang ? `html-${lang}` : 'html', file),
      });
    }
  }
}

const csv = [columns.join(','), ...rows.map((r) => columns.map((c) => csvCell(r[c])).join(','))].join('\r\n');
await writeFile(join(outDir, lang ? `articles-${lang}.csv` : 'articles.csv'), `\uFEFF${csv}\r\n`);
console.log(`Exported ${rows.length} articles with ${calls} API calls to ${outDir}/`);