@faqai/sdk

Official TypeScript/JavaScript client for FAQai.app — turn any document into production-ready RAG datasets (Canonical Q&A, Query Variants, Evaluation, Adversarial, and RAG Chunks) and export to 16 formats including Pinecone, Qdrant, pgvector, Chroma, Weaviate, Milvus, LanceDB, and Upstash.

Large files just work. Uploads above ~4 MB are automatically routed through the FAQai upload proxy, so you never hit the serverless 4.5 MB body limit and never see a 413 — up to your plan's 25 MB maximum, in a single call.

Works in Node 18+, Deno, Bun, Cloudflare Workers, and modern browsers (anywhere with global fetch).

Install

npm install @faqai/sdk

Quickstart

import { FaqaiClient } from "@faqai/sdk";

const client = new FaqaiClient("faq_your_api_key"); // or set FAQAI_API_KEY

// Upload (any size up to your plan limit) and wait for processing
const doc = await client.upload("large-report.pdf", { wait: true });
console.log(doc.status); // "completed"

// List generated datasets
const { datasets } = await client.listDatasets(doc.id);
for (const ds of datasets) console.log(ds.dataset_type, ds.item_count);

// Export a dataset for your vector DB
const content = await client.export(datasets[0].id, "pinecone");

// Search your generated Q&A
const hits = await client.search("refund policy", { datasetType: "canonical_qa" });
console.log(hits.total);

// Coverage report
const cov = await client.coverage(datasets[0].id);
console.log(cov.coverage_percent);

Uploading from bytes or a Blob

// Bytes (filename required)
await client.upload(new Uint8Array(buf), { filename: "doc.pdf" });

// Browser File input
await client.upload(fileFromInput); // File has a name already

Ingesting from a URL or website

No file needed — point FAQai at a public web page, or crawl a whole same-domain site (discovered via its sitemap, or a breadth-first walk if there is none). Crawling honors robots.txt and your plan's per-crawl page cap (Free 5, Basic 50, Starter 150, Pro 500). Only static HTML is read, so JavaScript-rendered pages may yield little content.

// Single page
const doc = await client.ingestUrl("https://example.com/docs/faq", { wait: true });

// Crawl a site (up to 50 same-domain pages), steer generation, and wait
const site = await client.ingestUrl("https://example.com/", {
  crawl: true,
  maxPages: 50,
  generationContext: "customer_support_bot",
  wait: true,
});
console.log(site.crawl); // { discovered, capped_to, estimated_pages, mode }

Configuration

| Option / env var | Default | Purpose | | --------------------------------------------- | ---------------------- | -------------------------------- | | apiKey / FAQAI_API_KEY | — | Your faq_... API key (required) | | baseUrl / FAQAI_BASE_URL | https://faqai.app | API base URL | | uploadProxyUrl / FAQAI_UPLOAD_PROXY_URL | FAQai production proxy | Large-file upload proxy URL | | timeoutMs | 60000 | Per-request timeout | | maxRetries | 3 | Retries for 429/5xx with backoff |

const client = new FaqaiClient({ apiKey: "faq_...", timeoutMs: 120_000 });

Error handling

All failures throw a FaqaiError (or a subclass: AuthenticationError, PermissionError, NotFoundError, PayloadTooLargeError, RateLimitError, TimeoutError). Each carries .status, .code, and .responseBody.

import { FaqaiClient, RateLimitError } from "@faqai/sdk";

try {
  await client.upload("doc.pdf");
} catch (e) {
  if (e instanceof RateLimitError) console.log("Slow down:", e.message);
}

How large-file uploads work

Files ≤ 4 MB are sent directly to POST /api/v1/documents. Larger files are sent to the FAQai upload proxy (a Supabase Edge Function), which performs the 3-step presigned upload flow on your behalf and returns the same document record. It's automatic — no code changes needed.

License

MIT