My first post!
',\n status: 'published'\n});\n\n// Update it\nawait newPost.update({\n title: 'Hello World - Updated!'\n});\n```\n\nThat's it. No complicated setup, no boilerplate. Just pure Ghost API goodness. π\n\n## π Core API\n\n### π Authentication & Setup\n\nInitialize the Ghost client with your API credentials:\n\n```typescript\nconst ghost = new Ghost({\n baseUrl: 'https://your-ghost-site.com',\n contentApiKey: 'your_content_api_key', // For reading public content\n adminApiKey: 'your_admin_api_key' // For write operations\n});\n```\n\n## π Posts\n\n### Get All Posts\n\n```typescript\nconst posts = await ghost.getPosts();\n\nposts.forEach(post => {\n console.log(post.getTitle());\n console.log(post.getExcerpt());\n console.log(post.getFeatureImage());\n});\n```\n\n### Filter Posts\n\n```typescript\nconst techPosts = await ghost.getPosts({ \n tag: 'technology',\n limit: 10 \n});\n\nconst featuredPosts = await ghost.getPosts({ \n featured: true,\n limit: 5 \n});\n\nconst authorPosts = await ghost.getPosts({ \n author: 'john-doe' \n});\n```\n\n### Get Single Post\n\n```typescript\nconst post = await ghost.getPostById('post-id');\nconsole.log(post.getTitle());\nconsole.log(post.getHtml());\nconsole.log(post.getAuthor());\n```\n\n### Create Post\n\n```typescript\nconst newPost = await ghost.createPost({\n title: 'My Awesome Post',\n html: 'This is the content of my post.
',\n feature_image: 'https://example.com/image.jpg',\n tags: [{ id: 'tag-id' }],\n excerpt: 'A brief summary of the post'\n});\n```\n\nOr create from HTML specifically:\n\n```typescript\nconst post = await ghost.createPostFromHtml({\n title: 'My HTML Post',\n html: 'Content here
'\n});\n```\n\n### Update Post\n\n```typescript\nconst post = await ghost.getPostById('post-id');\nawait post.update({\n ...post.toJson(),\n title: 'Updated Title',\n html: 'Updated content
'\n});\n```\n\n### Delete Post\n\n```typescript\nconst post = await ghost.getPostById('post-id');\nawait post.delete();\n```\n\n### Search Posts\n\nFull-text search across post titles:\n\n```typescript\nconst results = await ghost.searchPosts('typescript tutorial', { limit: 10 });\nresults.forEach(post => console.log(post.getTitle()));\n```\n\n### Related Posts\n\nGet posts with similar tags:\n\n```typescript\nconst post = await ghost.getPostById('post-id');\nconst related = await ghost.getRelatedPosts(post.getId(), 5);\nrelated.forEach(p => console.log(`Related: ${p.getTitle()}`));\n```\n\n### Bulk Operations\n\n```typescript\nawait ghost.bulkUpdatePosts(['id1', 'id2', 'id3'], {\n featured: true\n});\n\nawait ghost.bulkDeletePosts(['id4', 'id5', 'id6']);\n```\n\n## π Pages\n\nPages work similarly to posts but are for static content:\n\n```typescript\nconst pages = await ghost.getPages();\n\nconst aboutPage = await ghost.getPageBySlug('about');\nconsole.log(aboutPage.getHtml());\n\nconst newPage = await ghost.createPage({\n title: 'Contact',\n html: 'Contact information...
'\n});\n\nawait newPage.update({\n html: 'Updated content
'\n});\n\nawait newPage.delete();\n```\n\nFilter pages with minimatch patterns:\n\n```typescript\nconst filteredPages = await ghost.getPages({ \n filter: 'about*',\n limit: 10 \n});\n```\n\n## π·οΈ Tags\n\n### Get All Tags\n\n```typescript\n// Get ALL tags (including those with zero posts)\nconst tags = await ghost.getTags();\ntags.forEach(tag => console.log(`${tag.name} (${tag.slug})`));\n```\n\n**Note**: Uses Admin API to fetch ALL tags, including tags with zero posts. Previous versions using Content API would omit tags with no associated content.\n\n### Filter by Visibility\n\nGhost supports two tag types:\n- **Public tags**: Standard tags visible to readers\n- **Internal tags**: Tags prefixed with `#` for internal organization (not visible publicly)\n\n```typescript\n// Get only public tags\nconst publicTags = await ghost.getPublicTags();\n\n// Get only internal tags (e.g., #feature, #urgent)\nconst internalTags = await ghost.getInternalTags();\n\n// Get all tags with explicit visibility filter\nconst publicTags = await ghost.getTags({ visibility: 'public' });\nconst internalTags = await ghost.getTags({ visibility: 'internal' });\nconst allTags = await ghost.getTags({ visibility: 'all' }); // default\n```\n\n### Filter Tags with Minimatch\n\n```typescript\nconst techTags = await ghost.getTags({ filter: 'tech-*' });\nconst blogTags = await ghost.getTags({ filter: '*blog*' });\n\n// Combine visibility and pattern filtering\nconst internalNews = await ghost.getTags({\n filter: 'news-*',\n visibility: 'internal'\n});\n```\n\n### Get Single Tag\n\n```typescript\nconst tag = await ghost.getTagBySlug('javascript');\nconsole.log(tag.getName());\nconsole.log(tag.getDescription());\nconsole.log(tag.getVisibility()); // 'public' or 'internal'\n\n// Check visibility\nif (tag.isInternal()) {\n console.log('This is an internal tag');\n}\n```\n\n### Create, Update, Delete Tags\n\n```typescript\n// Create a public tag\nconst newTag = await ghost.createTag({\n name: 'TypeScript',\n slug: 'typescript',\n description: 'All about TypeScript',\n visibility: 'public'\n});\n\n// Create an internal tag (note the # prefix)\nconst internalTag = await ghost.createTag({\n name: '#feature',\n slug: 'hash-feature',\n visibility: 'internal'\n});\n\n// Update tag\nawait newTag.update({\n description: 'Everything TypeScript related'\n});\n\n// Delete tag (now works reliably!)\nawait newTag.delete();\n```\n\n## π€ Authors\n\n### Get Authors\n\n```typescript\nconst authors = await ghost.getAuthors();\nauthors.forEach(author => {\n console.log(`${author.getName()} (${author.getSlug()})`);\n});\n```\n\n### Filter Authors\n\n```typescript\nconst filteredAuthors = await ghost.getAuthors({ \n filter: 'j*',\n limit: 10 \n});\n```\n\n### Get Single Author\n\n```typescript\nconst author = await ghost.getAuthorBySlug('john-doe');\nconsole.log(author.getBio());\nconsole.log(author.getProfileImage());\n```\n\n### Update Author\n\n```typescript\nawait author.update({\n bio: 'Updated bio information',\n website: 'https://johndoe.com'\n});\n```\n\n## π₯ Members\n\nManage your Ghost site members (requires Ghost membership features):\n\n### Get Members\n\n```typescript\nconst members = await ghost.getMembers({ limit: 100 });\nmembers.forEach(member => {\n console.log(`${member.getName()} - ${member.getEmail()}`);\n console.log(`Status: ${member.getStatus()}`);\n});\n```\n\n### Filter Members\n\n```typescript\nconst gmailMembers = await ghost.getMembers({ \n filter: '*@gmail.com' \n});\n```\n\n### Get Single Member\n\n```typescript\nconst member = await ghost.getMemberByEmail('user@example.com');\nconsole.log(member.getStatus());\nconsole.log(member.getLabels());\n```\n\n### Create Member\n\n```typescript\nconst newMember = await ghost.createMember({\n email: 'newuser@example.com',\n name: 'New User',\n note: 'VIP member'\n});\n```\n\n### Update and Delete Members\n\n```typescript\nawait member.update({\n name: 'Updated Name',\n note: 'Premium member'\n});\n\nawait member.delete();\n```\n\n## πͺ Webhooks\n\nManage webhooks for Ghost events:\n\n```typescript\nconst webhook = await ghost.createWebhook({\n event: 'post.published',\n target_url: 'https://example.com/webhook',\n name: 'Post Published Webhook'\n});\n\nawait ghost.updateWebhook(webhook.id, {\n target_url: 'https://example.com/new-webhook'\n});\n\nawait ghost.deleteWebhook(webhook.id);\n```\n\n**Note:** The Ghost Admin API only supports creating, updating, and deleting webhooks. Browsing and reading individual webhooks are not supported by the underlying SDK.\n\n## πΌοΈ Image Upload\n\nUpload images to your Ghost site:\n\n```typescript\nconst imageUrl = await ghost.uploadImage('/path/to/image.jpg');\n\nawait ghost.createPost({\n title: 'Post with Image',\n html: 'Content here
',\n feature_image: imageUrl\n});\n```\n\n## π Multi-Instance Synchronization\n\nThe `SyncedInstance` class enables you to synchronize content across multiple Ghost instances - perfect for staging environments, multi-region deployments, or content distribution.\n\n**Key Features:**\n- π **Same-Instance Protection** - Automatically prevents circular syncs that would cause excessive API calls\n- π·οΈ **Slug Congruence** - Ensures slugs remain consistent across all synced instances\n- πΊοΈ **ID Mapping** - Tracks source-to-target ID mappings for efficient updates\n- π **Detailed Reporting** - Get comprehensive sync reports with success/failure counts\n\n### Setup\n\n```typescript\nimport { Ghost, SyncedInstance } from '@apiclient.xyz/ghost';\n\nconst sourceGhost = new Ghost({\n baseUrl: 'https://source.ghost.com',\n contentApiKey: 'source_content_key',\n adminApiKey: 'source_admin_key'\n});\n\nconst targetGhost1 = new Ghost({\n baseUrl: 'https://target1.ghost.com',\n contentApiKey: 'target1_content_key',\n adminApiKey: 'target1_admin_key'\n});\n\nconst targetGhost2 = new Ghost({\n baseUrl: 'https://target2.ghost.com',\n contentApiKey: 'target2_content_key',\n adminApiKey: 'target2_admin_key'\n});\n\n// This will throw an error if you accidentally try to sync an instance to itself\nconst synced = new SyncedInstance(sourceGhost, [targetGhost1, targetGhost2]);\n```\n\n**Safety Note:** SyncedInstance validates that the source and target instances are different. Attempting to sync an instance to itself will throw an error immediately, preventing circular syncs and rate limit issues.\n\n### Sync Content\n\n```typescript\nconst tagReport = await synced.syncTags();\nconsole.log(`Synced ${tagReport.totalItems} tags`);\nconsole.log(`Duration: ${tagReport.duration}ms`);\n\nconst postReport = await synced.syncPosts();\nconsole.log(`Success: ${postReport.targetReports[0].successCount}`);\nconsole.log(`Failed: ${postReport.targetReports[0].failureCount}`);\n\nconst pageReport = await synced.syncPages();\n```\n\n### Sync Options\n\n```typescript\nconst report = await synced.syncPosts({\n filter: 'featured-*',\n dryRun: true,\n incremental: true\n});\n\nreport.targetReports.forEach(targetReport => {\n console.log(`Target: ${targetReport.targetUrl}`);\n targetReport.results.forEach(result => {\n console.log(` ${result.sourceSlug}: ${result.status}`);\n });\n});\n```\n\n### Sync Everything\n\n```typescript\nconst reports = await synced.syncAll({\n types: ['tags', 'posts', 'pages'],\n syncOptions: {\n dryRun: false\n }\n});\n\nreports.forEach(report => {\n console.log(`${report.contentType}: ${report.totalItems} items`);\n});\n```\n\n### Sync Status & History\n\n```typescript\nconst status = synced.getSyncStatus();\nconsole.log(`Total mappings: ${status.totalMappings}`);\nconsole.log(`Recent syncs: ${status.recentSyncs.length}`);\n\nstatus.mappings.forEach(mapping => {\n console.log(`Source: ${mapping.sourceSlug}`);\n mapping.targetMappings.forEach(tm => {\n console.log(` -> ${tm.targetUrl} (${tm.targetId})`);\n });\n});\n\nsynced.clearSyncHistory();\nsynced.clearMappings();\n```\n\n## π¨ Complete Example\n\nHere's a comprehensive example showing various operations:\n\n```typescript\nimport { Ghost, SyncedInstance } from '@apiclient.xyz/ghost';\n\nconst ghost = new Ghost({\n baseUrl: 'https://your-ghost-site.com',\n contentApiKey: 'your_content_key',\n adminApiKey: 'your_admin_key'\n});\n\nasync function createBlogPost() {\n // Upload a feature image\n const imageUrl = await ghost.uploadImage('./banner.jpg');\n\n // Create a tag for categorization\n const tag = await ghost.createTag({\n name: 'Tutorial',\n slug: 'tutorial',\n description: 'Step-by-step guides',\n visibility: 'public'\n });\n\n // Create a comprehensive blog post\n const post = await ghost.createPost({\n title: 'Getting Started with Ghost CMS',\n slug: 'getting-started-ghost-cms',\n html: 'This is an introduction to Ghost CMS...
',\n feature_image: imageUrl,\n tags: [{ id: tag.getId() }],\n featured: true,\n status: 'published',\n meta_title: 'Getting Started with Ghost CMS | Tutorial',\n meta_description: 'Learn how to get started with Ghost CMS in this comprehensive guide',\n custom_excerpt: 'A beginner-friendly guide to Ghost CMS'\n });\n\n console.log(`β Created post: ${post.getTitle()}`);\n console.log(`π Published at: ${post.postData.published_at}`);\n\n // Find related content\n const related = await ghost.getRelatedPosts(post.getId(), 5);\n console.log(`π Found ${related.length} related posts`);\n\n // Search functionality\n const searchResults = await ghost.searchPosts('getting started', { limit: 10 });\n console.log(`π Search found ${searchResults.length} posts`);\n\n // Get all public tags\n const publicTags = await ghost.getPublicTags();\n console.log(`π·οΈ Public tags: ${publicTags.length}`);\n\n return post;\n}\n\nasync function syncToStaging() {\n // Sync content to staging environment\n const production = new Ghost({\n baseUrl: 'https://production.ghost.com',\n adminApiKey: process.env.PROD_ADMIN_KEY,\n contentApiKey: process.env.PROD_CONTENT_KEY\n });\n\n const staging = new Ghost({\n baseUrl: 'https://staging.ghost.com',\n adminApiKey: process.env.STAGING_ADMIN_KEY,\n contentApiKey: process.env.STAGING_CONTENT_KEY\n });\n\n const synced = new SyncedInstance(production, [staging]);\n\n // Sync everything\n const reports = await synced.syncAll({\n types: ['tags', 'posts', 'pages']\n });\n\n reports.forEach(report => {\n console.log(`β Synced ${report.totalItems} ${report.contentType} in ${report.duration}ms`);\n });\n}\n\n// Run the examples\ncreateBlogPost().catch(console.error);\n// syncToStaging().catch(console.error);\n```\n\n## β‘ Performance & Best Practices\n\n### Rate Limiting\n\nGhost enforces rate limits on API requests (~100 requests per IP per hour for Admin API). Keep these tips in mind:\n\n```typescript\n// β Good: Batch operations\nawait ghost.bulkUpdatePosts(['id1', 'id2', 'id3'], { featured: true });\n\n// β Bad: Individual requests in a loop\nfor (const id of postIds) {\n await ghost.getPostById(id).then(p => p.update({ featured: true }));\n}\n\n// β Good: Use pagination efficiently\nconst posts = await ghost.getPosts({ limit: 15 });\n\n// β Good: Filter on the server side\nconst featuredPosts = await ghost.getPosts({ featured: true, limit: 10 });\n```\n\n### Multi-Instance Sync Safety\n\nThe library automatically prevents common pitfalls:\n\n```typescript\n// β This works - different instances\nconst synced = new SyncedInstance(sourceGhost, [targetGhost]);\n\n// β This throws an error - prevents circular sync!\nconst synced = new SyncedInstance(ghost, [ghost]); // Error: Cannot sync to same instance\n```\n\n### Content API vs Admin API\n\n- **Content API**: Read-only, public content, no authentication required (with Content API key)\n- **Admin API**: Full read/write access, requires Admin API key\n- **Tags**: This library uses Admin API for tags to fetch ALL tags (Content API only returns tags with posts)\n\n### Dry Run Mode\n\nTest your sync operations without making changes:\n\n```typescript\nconst report = await synced.syncAll({\n types: ['posts', 'pages', 'tags'],\n syncOptions: {\n dryRun: true // Preview changes without applying them\n }\n});\n\nconsole.log(`Would sync ${report[0].totalItems} items`);\n```\n\n## π Error Handling\n\nAll methods throw errors that you can catch and handle:\n\n```typescript\ntry {\n const post = await ghost.getPostById('invalid-id');\n} catch (error) {\n console.error('Failed to fetch post:', error);\n}\n\ntry {\n await post.update({ title: 'New Title' });\n} catch (error) {\n console.error('Failed to update post:', error);\n}\n```\n\n## π API Reference\n\n### Ghost Class\n\n| Method | Description | Returns |\n|--------|-------------|---------|\n| `getPosts(options?)` | Get all posts with optional filtering | `Promise