npm package: @faqapp/core
Description: Official TypeScript SDK for TheFAQApp — manage and deliver FAQ content via the v1 API
Latest version: 0.1.1

# @faqapp/core

Official TypeScript SDK for [TheFAQApp](https://www.thefaq.app) — manage and deliver FAQ content via the REST API.

## Install

```bash
npm install @faqapp/core
# or
pnpm add @faqapp/core
```

## Quick Start

```ts
import { FAQClient } from "@faqapp/core";

const faq = new FAQClient({
  apiKey: "your-api-key",
  organizationSlug: "your-org",
});

// List questions (paginated)
const page = await faq.questions.list();
console.log(page.data);        // Question[]
console.log(page.pagination);  // { page, limit, total, pages }

// Get a single question by slug
const { data: question } = await faq.questions.get("how-to-reset");

// Search
const { data: results } = await faq.search.query("how do I...");

// Auto-paginate across all pages
for await (const q of faq.questions.list().iter()) {
  console.log(q.question);
}
```

## API Reference

### Questions

```ts
faq.questions.list(params?)          // List questions (paginated)
faq.questions.get(slug)              // Get question by slug
faq.questions.create(data)           // Create a question
faq.questions.update(slug, data)     // Update a question
faq.questions.delete(slug)           // Delete a question
faq.questions.bulk({ questions })    // Bulk-create questions
faq.questions.export()               // Export all questions
```

### Categories

```ts
faq.categories.list(params?)           // List categories (paginated)
faq.categories.get(slug)              // Get category by slug
faq.categories.create(data)           // Create a category
faq.categories.update(slug, data)     // Update a category
faq.categories.delete(slug)           // Delete a category
```

### Search

```ts
faq.search.query("search term")               // Simple string search
faq.search.query({ q: "billing", limit: 5 })  // Search with options
```

### Feedback

```ts
faq.feedback.submit(slug, { helpful: true })  // Submit feedback
faq.feedback.stats(slug)                      // Get feedback stats
```

### Translations

```ts
faq.translations.list("questions", slug)                              // List translations
faq.translations.get("questions", slug, "nl")                         // Get translation
faq.translations.upsert("questions", slug, "nl", { question, answer }) // Upsert translation
faq.translations.aiTranslate("questions", slug, { targetLanguages: ["nl", "de"] })
faq.translations.completeness()                                       // Translation coverage
```

### Webhooks

```ts
faq.webhooks.list()                                  // List webhooks
faq.webhooks.get(id)                                 // Get webhook by ID
faq.webhooks.create({ url, events })                 // Create webhook
faq.webhooks.update(id, data)                        // Update webhook
faq.webhooks.delete(id)                              // Delete webhook
faq.webhooks.test(id)                                // Send test event
faq.webhooks.deliveries(id)                          // List deliveries
faq.webhooks.replayDelivery(webhookId, deliveryId)   // Replay delivery
```

### Domains

```ts
faq.domains.list()                    // List custom domains
faq.domains.get(id)                   // Get domain
faq.domains.create({ domain })        // Add custom domain
faq.domains.delete(id)                // Remove domain
faq.domains.verify(id)                // Verify DNS
faq.domains.health(id)                // Check domain health
```

### API Keys

```ts
faq.apiKeys.list()                              // List API keys
faq.apiKeys.create({ name, scopes })            // Create API key
faq.apiKeys.revoke(id)                          // Revoke API key
```

### Organization

```ts
faq.organization.get()  // Get organization info
```

## Pagination

List methods return a `PagePromise` that resolves to a `Page` with built-in pagination:

```ts
const page = await faq.questions.list({ limit: 10 });
console.log(page.data);         // Question[]
console.log(page.pagination);   // { page, limit, total, pages }
console.log(page.hasNextPage());

// Iterate item-by-item across all pages
for await (const question of faq.questions.list().iter()) {
  console.log(question.question);
}

// Iterate page-by-page
for await (const p of faq.questions.list().iterPages()) {
  console.log(p.data.length, "questions on page", p.pagination.page);
}
```

## Error Handling

```ts
import { FAQNotFoundError, FAQValidationError, FAQRateLimitError } from "@faqapp/core";

try {
  await faq.questions.get("nonexistent");
} catch (err) {
  if (err instanceof FAQNotFoundError) {
    console.log("Not found:", err.message);
  } else if (err instanceof FAQValidationError) {
    console.log("Validation errors:", err.errors);
  } else if (err instanceof FAQRateLimitError) {
    console.log("Rate limited, retry after:", err.retryAfter);
  }
}
```

## For Next.js

Use `@faqapp/nextjs` for React hooks, components, and SSR/SSG helpers:

```bash
npm install @faqapp/core @faqapp/nextjs
```

## License

MIT