Welcome to our documentation!
',\n status: 'published'\n});\n\n// Categories\nconst { categories } = await client.categories.listCategories({\n collectionId: 'abc123'\n});\n\n// Collections\nconst { collections } = await client.collections.listCollections();\n\n// Assets\nconst asset = await client.assets.createArticleAsset({\n articleId: article.id,\n assetType: 'image',\n file: imageBuffer,\n fileName: 'screenshot.png'\n});\n```\n\n### Modular Imports (Advanced)\n\nFor even better tree-shaking, import only the modules you need:\n\n```typescript\nimport { createArticlesClient } from '@damianhodgkiss/helpscout-docs-api/articles';\nimport { createCategoriesClient } from '@damianhodgkiss/helpscout-docs-api/categories';\n\nconst articlesClient = createArticlesClient(apiKey);\nconst categoriesClient = createCategoriesClient(apiKey);\n\nawait articlesClient.createArticle({ ... });\nawait categoriesClient.listCategories({ ... });\n```\n\n### Functional API (Alternative)\n\nYou can also use the functional API if you prefer:\n\n```typescript\nimport { createArticle } from '@damianhodgkiss/helpscout-docs-api/articles';\n\nconst result = await createArticle(apiKey, {\n collectionId: 'abc123',\n name: 'Getting Started',\n text: 'Welcome!
'\n});\n```\n\n## API Reference\n\n### Articles Client\n\n#### `createArticle`\n\nCreate a new article.\n\n```typescript\nconst { article } = await client.articles.createArticle({\n collectionId: string; // Required: Collection ID\n name: string; // Required: Article title\n text: string; // Required: Article content (HTML or plain text)\n status?: 'published' | 'notpublished'; // Optional: Publication status\n slug?: string; // Optional: SEO-friendly URL slug\n categories?: string[]; // Optional: Category IDs\n related?: string[]; // Optional: Related article IDs\n keywords?: string[]; // Optional: Search keywords\n reload?: boolean; // Optional: Return created article in response\n});\n```\n\n#### `getArticle`\n\nGet an article by ID or number.\n\n```typescript\nconst { article } = await client.articles.getArticle({\n articleIdOrNumber: string | number; // Required: Article ID or number\n draft?: boolean; // Optional: Get draft version\n});\n```\n\n#### `listArticles`\n\nList articles in a collection or category.\n\n```typescript\nconst { articles } = await client.articles.listArticles({\n collectionId?: string; // Required if categoryId not provided\n categoryId?: string; // Required if collectionId not provided\n page?: number; // Optional: Page number (default: 1)\n status?: 'all' | 'published' | 'notpublished'; // Optional: Filter by status\n sort?: 'number' | 'status' | 'name' | 'popularity' | 'createdAt' | 'updatedAt';\n order?: 'asc' | 'desc'; // Optional: Sort order\n pageSize?: number; // Optional: Results per page (max 100)\n});\n```\n\n#### `updateArticle`\n\nUpdate an existing article.\n\n```typescript\nconst { article } = await client.articles.updateArticle({\n articleId: string; // Required: Article ID\n status?: 'published' | 'notpublished';\n slug?: string;\n name?: string;\n text?: string;\n categories?: string[] | null; // null removes all categories\n related?: string[] | null; // null removes all related articles\n keywords?: string[] | null; // null removes all keywords\n reload?: boolean;\n});\n```\n\n#### `deleteArticle`\n\nDelete an article permanently.\n\n```typescript\nawait client.articles.deleteArticle({\n articleId: string; // Required: Article ID\n});\n```\n\n#### `searchArticles`\n\nSearch for articles.\n\n```typescript\nconst { articles } = await client.articles.searchArticles({\n query: string; // Required: Search query\n page?: number;\n collectionId?: string; // Optional: Filter to specific collection\n siteId?: string; // Optional: Filter to specific site\n status?: 'all' | 'published' | 'notpublished';\n visibility?: 'all' | 'public' | 'private';\n});\n```\n\n#### `saveArticleDraft`\n\nSave a draft version of an article.\n\n```typescript\nawait client.articles.saveArticleDraft({\n articleId: string; // Required: Article ID\n text: string; // Required: Draft content\n});\n```\n\n#### `deleteArticleDraft`\n\nDelete an article draft.\n\n```typescript\nawait client.articles.deleteArticleDraft({\n articleId: string; // Required: Article ID\n});\n```\n\n### Categories Client\n\n#### `createCategory`\n\nCreate a new category.\n\n```typescript\nconst { category } = await client.categories.createCategory({\n collectionId: string; // Required: Collection ID\n name: string; // Required: Category name\n slug?: string;\n visibility?: 'public' | 'private';\n order?: number;\n defaultSort?: 'popularity' | 'name';\n reload?: boolean;\n});\n```\n\n#### `getCategory`\n\nGet a category by ID or number.\n\n```typescript\nconst { category } = await client.categories.getCategory({\n categoryIdOrNumber: string | number; // Required: Category ID or number\n});\n```\n\n#### `listCategories`\n\nList categories in a collection.\n\n```typescript\nconst { categories } = await client.categories.listCategories({\n collectionId: string; // Required: Collection ID\n page?: number;\n sort?: 'number' | 'order' | 'name' | 'articleCount' | 'createdAt' | 'updatedAt';\n order?: 'asc' | 'desc';\n});\n```\n\n#### `updateCategory`\n\nUpdate an existing category.\n\n```typescript\nconst { category } = await client.categories.updateCategory({\n categoryId: string; // Required: Category ID\n name: string; // Required: Category name\n slug?: string;\n visibility?: 'public' | 'private';\n order?: number;\n defaultSort?: 'popularity' | 'name';\n reload?: boolean;\n});\n```\n\n#### `deleteCategory`\n\nDelete a category.\n\n```typescript\nawait client.categories.deleteCategory({\n categoryId: string; // Required: Category ID\n});\n```\n\n### Collections Client\n\n#### `createCollection`\n\nCreate a new collection.\n\n```typescript\nconst { collection } = await client.collections.createCollection({\n siteId: string; // Required: Site ID\n name: string; // Required: Collection name\n visibility?: 'public' | 'private';\n order?: number;\n description?: string; // Optional: Max 45 characters\n reload?: boolean;\n});\n```\n\n#### `getCollection`\n\nGet a collection by ID or number.\n\n```typescript\nconst { collection } = await client.collections.getCollection({\n collectionIdOrNumber: string | number; // Required: Collection ID or number\n});\n```\n\n#### `listCollections`\n\nList all collections.\n\n```typescript\nconst { collections } = await client.collections.listCollections({\n page?: number;\n siteId?: string; // Optional: Filter to specific site\n visibility?: 'all' | 'public' | 'private';\n sort?: 'number' | 'visibility' | 'order' | 'name' | 'createdAt' | 'updatedAt';\n order?: 'asc' | 'desc';\n});\n```\n\n#### `updateCollection`\n\nUpdate an existing collection.\n\n```typescript\nconst { collection } = await client.collections.updateCollection({\n collectionId: string; // Required: Collection ID\n name: string; // Required: Collection name\n visibility?: 'public' | 'private';\n order?: number;\n description?: string;\n siteId?: string; // Optional: Move to different site\n reload?: boolean;\n});\n```\n\n#### `deleteCollection`\n\nDelete a collection.\n\n```typescript\nawait client.collections.deleteCollection({\n collectionId: string; // Required: Collection ID\n});\n```\n\n### Assets Client\n\n#### `createArticleAsset`\n\nUpload an image or attachment for an article.\n\n```typescript\nconst asset = await client.assets.createArticleAsset({\n articleId: string; // Required: Article ID\n assetType: 'image' | 'attachment'; // Required: Asset type\n file: Buffer | Blob; // Required: File content\n fileName?: string; // Optional: File name\n});\n```\n\n### Sites Client\n\n#### `listSites`\n\nList all sites.\n\n```typescript\nconst { sites } = await client.sites.listSites({\n page?: number; // Optional: Page number (default: 1)\n});\n```\n\n#### `getSite`\n\nGet a site by ID.\n\n```typescript\nconst { site } = await client.sites.getSite({\n siteId: string; // Required: Site ID\n});\n```\n\n#### `updateSite`\n\nUpdate an existing site.\n\n```typescript\nconst { site } = await client.sites.updateSite({\n siteId: string; // Required: Site ID\n subDomain?: string; // Optional: Subdomain (must be unique if provided)\n title?: string; // Optional: Site title\n status?: string; // Optional: Site status\n cname?: string; // Optional: Custom domain\n hasPublicSite?: boolean; // Optional: Public availability\n logoUrl?: string; // Optional: Logo URL\n logoWidth?: number; // Optional: Logo width in pixels\n logoHeight?: number; // Optional: Logo height in pixels\n favIconUrl?: string; // Optional: Favicon URL\n touchIconUrl?: string; // Optional: Touch icon URL\n homeUrl?: string; // Optional: Company website URL\n homeLinkText?: string; // Optional: Navigation link text\n bgColor?: string; // Optional: Background color (hex)\n description?: string; // Optional: Meta description\n hasContactForm?: boolean; // Optional: Contact form display\n mailboxId?: number; // Optional: Help Scout mailbox ID\n contactEmail?: string; // Optional: Contact form email\n styleSheetUrl?: string; // Optional: Custom stylesheet URL\n headerCode?: string; // Optional: Custom HTML/JavaScript\n reload?: boolean; // Optional: Return updated site in response\n});\n```\n\n## TypeScript Support\n\nAll methods are fully typed with TypeScript. The SDK exports all request and response types:\n\n```typescript\nimport type {\n Article,\n ArticleRef,\n Category,\n Collection,\n CreateArticleRequest,\n CreateArticleResponse,\n // ... and many more\n} from '@damianhodgkiss/helpscout-docs-api/articles';\n```\n\n## Error Handling\n\nAll methods throw standard errors for HTTP failures:\n\n```typescript\ntry {\n await client.articles.createArticle({ ... });\n} catch (error) {\n if (error instanceof Error) {\n console.error('API error:', error.message);\n }\n}\n```\n\nCommon HTTP status codes:\n- `400` - Bad Request: Invalid parameters\n- `401` - Unauthorized: Invalid API key\n- `403` - Forbidden: Access denied\n- `404` - Not Found: Resource doesn't exist\n- `500` - Internal Server Error\n\n## Rate Limiting\n\nHelp Scout Docs API has rate limits based on the number of sites:\n- 1 site: 2,000 requests per 10 minutes\n- 2 sites: 3,000 requests per 10 minutes\n- 3+ sites: 4,000 requests per 10 minutes\n\n## Requirements\n\n- Node.js 18.0.0 or higher (for native fetch support)\n- TypeScript 5.0+ (for best type experience)\n\n## License\n\nMIT\n\n## Resources\n\n- [Help Scout Docs API Documentation](https://developer.helpscout.com/docs-api/)\n- [TypeScript Documentation](https://www.typescriptlang.org/)\n","readmeFilename":"README.md"}