@citeflow/sdk

Official Node.js SDK for the CiteFlow Partner API — programmatic SEO, AEO, and GEO audits.

CiteFlow is an AI-visibility scanner: it audits how well a website can be crawled, understood, and cited by AI search engines (ChatGPT, Claude, Perplexity, Google AI Overviews). This SDK lets partners run those audits from their own products via the CiteFlow Partner API.

• Website: https://citeflow.io
• API docs & getting started: https://citeflow.io/help/partner-api
• Dashboard (API keys, billing, webhooks): https://citeflow.io/dashboard/api

Install

npm install @citeflow/sdk
# or: pnpm add @citeflow/sdk, yarn add @citeflow/sdk

Node 18+ required (uses the global fetch).

Quickstart

import { Citeflow } from '@citeflow/sdk';

const client = new Citeflow({ apiKey: process.env.CITEFLOW_API_KEY! });

// Create an audit and wait for the result (~30s for SEO).
const audit = await client.audits.create({
  url: 'https://example.com',
  type: 'seo',
});

const result = await client.audits.waitForCompletion(audit.audit_id, {
  timeoutMs: 90_000,
});

if (result.status === 'complete') {
  console.log('Scores:', result.scores);
} else if (result.status === 'failed') {
  console.error('Failure:', result.failure_reason);
}

// Check remaining balance.
const { balance, balance_usd } = await client.balance.retrieve();
console.log(`Balance: ${balance_usd} (${balance} credits)`);

Features

• Auto-retry on 429 and 5xx with exponential back-off + jitter. Honors Retry-After.
• Auto Idempotency-Key on every POST — safe to retry on network failure without double-charging.
• waitForCompletion polling helper with configurable timeout.
• HMAC webhook verification with timestamp tolerance + rotation grace handling.

Webhook verification

import { verifyWebhookSignature, parseWebhookEvent } from '@citeflow/sdk';

// In your webhook handler (Express, Next.js Route Handler, …):
const rawBody = await readRawBody(req); // do NOT JSON-parse first
try {
  const event = parseWebhookEvent({
    rawBody,
    headers: req.headers,
    secret: process.env.CITEFLOW_WEBHOOK_SECRET!,
  });
  // event.type === 'audit.completed' | 'audit.failed' | 'audit.cancelled' | 'balance.low'
  console.log(event.id, event.type, event.data);
  res.status(200).end();
} catch (err) {
  // CiteflowSignatureError → 400
  res.status(400).end();
}

Errors

import { CiteflowError } from '@citeflow/sdk';

try {
  await client.audits.create({ url: 'invalid', type: 'seo' });
} catch (err) {
  if (err instanceof CiteflowError) {
    console.error(err.code, err.message, err.requestId);
    if (err.code === 'INSUFFICIENT_CREDITS') {
      console.error(`Need ${err.required} more credits`);
    }
  }
}

Full error catalog: https://citeflow.io/help/partner-api#troubleshooting.

Configuration

new Citeflow({
  apiKey: 'ckf_…',
  baseUrl: 'https://www.citeflow.io/api/v1', // default; override only for staging/self-hosted
  timeoutMs: 30_000,                     // per-request
  maxRetries: 3,                         // for 429 + 5xx + network
});

License

MIT. CiteFlow API itself is a paid service — see https://citeflow.io/terms-of-service.