# @apiclient.xyz/ghost An unofficial Ghost API package ## Install To install the @apiclient.xyz/ghost package, you can use npm or yarn. Make sure you're using a package manager that supports ESM and TypeScript. NPM: ```bash npm install @apiclient.xyz/ghost ``` Yarn: ```bash yarn add @apiclient.xyz/ghost ``` ## Usage Below is a detailed guide on how to use the `@apiclient.xyz/ghost` package in your TypeScript projects. We will cover everything from initialization to advanced usage scenarios. ### Initialization First, you need to import the necessary classes and initialize the Ghost instance with the required API keys. ```typescript import { Ghost } from '@apiclient.xyz/ghost'; // Initialize the Ghost instance const ghostInstance = new Ghost({ baseUrl: 'https://your-ghost-url.com', contentApiKey: 'your-content-api-key', adminApiKey: 'your-admin-api-key' }); ``` ### Basic Usage #### Fetching Posts You can fetch posts with the following method. This will give you an array of `Post` instances. ```typescript // Fetch all posts const posts = await ghostInstance.getPosts(); // Print titles of all posts posts.forEach(post => { console.log(post.getTitle()); }); ``` #### Fetching a Single Post by ID To fetch a single post by its ID: ```typescript const postId = 'your-post-id'; const post = await ghostInstance.getPostById(postId); console.log(post.getTitle()); console.log(post.getHtml()); ``` ### Post Class Methods The `Post` class has several methods that can be useful for different scenarios. #### Getting Post Data These methods allow you to retrieve various parts of the post data. ```typescript const postId = post.getId(); const postTitle = post.getTitle(); const postHtml = post.getHtml(); const postExcerpt = post.getExcerpt(); const postFeatureImage = post.getFeatureImage(); console.log(`ID: ${postId}`); console.log(`Title: ${postTitle}`); console.log(`HTML: ${postHtml}`); console.log(`Excerpt: ${postExcerpt}`); console.log(`Feature Image: ${postFeatureImage}`); ``` #### Updating a Post To update a post, you can use the `update` method. Make sure you have the necessary permissions and fields. ```typescript const updatedPostData = { ...post.toJson(), title: 'Updated Title', html: '
Updated HTML content
' }; await post.update(updatedPostData); console.log('Post updated successfully'); ``` #### Deleting a Post To delete a post: ```typescript await post.delete(); console.log('Post deleted successfully'); ``` ### Advanced Scenarios #### Creating a New Post You can create a new post using the `createPost` method of the `Ghost` class. ```typescript const newPostData = { id: 'new-post-id', title: 'New Post Title', html: 'This is the content of the new post.
', excerpt: 'New post excerpt', feature_image: 'https://your-image-url.com/image.jpg' }; const newPost = await ghostInstance.createPost(newPostData); console.log('New post created successfully'); console.log(`ID: ${newPost.getId()}`); console.log(`Title: ${newPost.getTitle()}`); ``` #### Error Handling Both the `Ghost` and `Post` classes throw errors that you can catch and handle. ```typescript try { const posts = await ghostInstance.getPosts(); console.log('Posts fetched successfully'); } catch (error) { console.error('Error fetching posts:', error); } ``` Similarly, for updating or deleting a post: ```typescript try { await post.update({ title: 'Updated Title' }); console.log('Post updated successfully'); } catch (error) { console.error('Error updating post:', error); } try { await post.delete(); console.log('Post deleted successfully'); } catch (error) { console.error('Error deleting post:', error); } ``` #### Fetching Posts with Filters and Options The `getPosts` method can accept various filters and options. ```typescript const filteredPosts = await ghostInstance.getPosts({ limit: 10, include: 'tags,authors' }); filteredPosts.forEach(post => { console.log(post.getTitle()); }); ``` #### Fetching Tags You can fetch all tags from your Ghost site using the `getTags` method. ```typescript const tags = await ghostInstance.getTags(); tags.forEach(tag => { console.log(`${tag.name} (${tag.slug})`); }); ``` #### Fetching Tags with Minimatch Filtering The `getTags` method supports filtering tags using minimatch patterns on tag slugs. ```typescript // Fetch all tags starting with 'tech-' const techTags = await ghostInstance.getTags({ filter: 'tech-*' }); // Fetch all tags containing 'blog' const blogTags = await ghostInstance.getTags({ filter: '*blog*' }); // Fetch with limit const limitedTags = await ghostInstance.getTags({ limit: 10, filter: 'a*' }); limitedTags.forEach(tag => { console.log(tag.name); }); ``` #### Working with Tag Class Fetch individual tags and manage them with the `Tag` class. ```typescript // Get tag by slug const tag = await ghostInstance.getTagBySlug('tech'); console.log(tag.getName()); console.log(tag.getDescription()); // Create a new tag const newTag = await ghostInstance.createTag({ name: 'JavaScript', slug: 'javascript', description: 'Posts about JavaScript' }); // Update a tag await newTag.update({ description: 'All things JavaScript' }); // Delete a tag await newTag.delete(); ``` #### Fetching Authors Manage and filter authors with minimatch patterns. ```typescript // Get all authors const authors = await ghostInstance.getAuthors(); authors.forEach(author => { console.log(`${author.getName()} (${author.getSlug()})`); }); // Filter authors with minimatch const filteredAuthors = await ghostInstance.getAuthors({ filter: 'j*' }); // Get author by slug const author = await ghostInstance.getAuthorBySlug('john-doe'); console.log(author.getBio()); // Update author await author.update({ bio: 'Updated bio information' }); ``` #### Working with Pages Ghost pages are similar to posts but for static content. ```typescript // Get all pages const pages = await ghostInstance.getPages(); pages.forEach(page => { console.log(page.getTitle()); }); // Filter pages with minimatch const filteredPages = await ghostInstance.getPages({ filter: 'about*' }); // Get page by slug const page = await ghostInstance.getPageBySlug('about'); console.log(page.getHtml()); // Create a new page const newPage = await ghostInstance.createPage({ title: 'Contact Us', html: 'Contact information...
' }); // Update a page await newPage.update({ html: 'Updated contact information...
' }); // Delete a page await newPage.delete(); ``` #### Enhanced Post Filtering The `getPosts` method now supports multiple filtering options. ```typescript // Filter by tag const techPosts = await ghostInstance.getPosts({ tag: 'tech', limit: 10 }); // Filter by author const authorPosts = await ghostInstance.getPosts({ author: 'john-doe' }); // Get only featured posts const featuredPosts = await ghostInstance.getPosts({ featured: true }); // Combine multiple filters const filteredPosts = await ghostInstance.getPosts({ tag: 'javascript', featured: true, limit: 5 }); ``` #### Searching Posts Full-text search across post titles and excerpts. ```typescript // Search for posts containing a keyword const searchResults = await ghostInstance.searchPosts('ghost api', { limit: 10 }); searchResults.forEach(post => { console.log(post.getTitle()); console.log(post.getExcerpt()); }); ``` #### Finding Related Posts Get posts with similar tags. ```typescript const post = await ghostInstance.getPostById('some-post-id'); // Get related posts based on tags const relatedPosts = await ghostInstance.getRelatedPosts(post.getId(), 5); relatedPosts.forEach(relatedPost => { console.log(`Related: ${relatedPost.getTitle()}`); }); ``` #### Image Upload Upload images to your Ghost site. ```typescript // Upload an image file const imageUrl = await ghostInstance.uploadImage('/path/to/image.jpg'); // Use the uploaded image URL in a post await ghostInstance.createPost({ title: 'Post with Image', html: 'Content here
', feature_image: imageUrl }); ``` #### Bulk Operations Perform operations on multiple posts at once. ```typescript // Bulk update posts const postIds = ['id1', 'id2', 'id3']; await ghostInstance.bulkUpdatePosts(postIds, { featured: true }); // Bulk delete posts await ghostInstance.bulkDeletePosts(['id4', 'id5']); ``` #### Members Management Manage your Ghost site members (requires Ghost membership features enabled). ```typescript // Get all members const members = await ghostInstance.getMembers({ limit: 100 }); members.forEach(member => { console.log(`${member.getName()} - ${member.getEmail()}`); }); // Filter members with minimatch const filteredMembers = await ghostInstance.getMembers({ filter: '*@gmail.com' }); // Get member by email const member = await ghostInstance.getMemberByEmail('user@example.com'); console.log(member.getStatus()); // Create a new member const newMember = await ghostInstance.createMember({ email: 'newuser@example.com', name: 'New User' }); // Update a member await newMember.update({ name: 'Updated Name', note: 'VIP member' }); // Delete a member await newMember.delete(); ``` #### Webhooks Management Manage webhooks for Ghost events. Note: The Ghost Admin API only supports creating, updating, and deleting webhooks (browsing and reading individual webhooks are not supported by the underlying SDK). ```typescript // Create a webhook const newWebhook = await ghostInstance.createWebhook({ event: 'post.published', target_url: 'https://example.com/webhook', name: 'Post Published Webhook' }); // Update a webhook await ghostInstance.updateWebhook(newWebhook.id, { target_url: 'https://example.com/new-webhook' }); // Delete a webhook await ghostInstance.deleteWebhook(newWebhook.id); ``` ### Example Projects To give you a comprehensive understanding, let's look at a couple of example projects. #### Example 1: A Basic Blog In this scenario, we will create a simple script to fetch all posts and display their titles. ```typescript import { Ghost } from '@apiclient.xyz/ghost'; (async () => { const ghostInstance = new Ghost({ baseUrl: 'https://your-ghost-url.com', contentApiKey: 'your-content-api-key', adminApiKey: 'your-admin-api-key' }); try { const posts = await ghostInstance.getPosts(); posts.forEach(post => console.log(post.getTitle())); } catch (error) { console.error('Error fetching posts:', error); } })(); ``` #### Example 2: Post Management Tool In this example, let's create a tool that can fetch, create, update, and delete posts. ```typescript import { Ghost, Post, IPostOptions } from '@apiclient.xyz/ghost'; const ghostInstance = new Ghost({ baseUrl: 'https://your-ghost-url.com', contentApiKey: 'your-content-api-key', adminApiKey: 'your-admin-api-key' }); (async () => { // Fetch posts const posts = await ghostInstance.getPosts(); console.log('Fetched posts:'); posts.forEach(post => console.log(post.getTitle())); // Create a new post const newPostData: IPostOptions = { id: 'new-post-id', title: 'New Post Title', html: 'This is the content of the new post.
', }; const newPost = await ghostInstance.createPost(newPostData); console.log('New post created:', newPost.getTitle()); // Update the new post const updatedPost = await newPost.update({ title: 'Updated Post Title' }); console.log('Post updated:', updatedPost.getTitle()); // Delete the new post await updatedPost.delete(); console.log('Post deleted'); })(); ``` ### Unit Tests This package includes unit tests written using the `@push.rocks/tapbundle` and `@push.rocks/qenv` libraries. Here is how you can run them. 1. Install the development dependencies: ```bash npm install ``` 2. Run the tests: ```bash npm test ``` ### Conclusion The `@apiclient.xyz/ghost` package provides a comprehensive and type-safe way to interact with the Ghost CMS API using TypeScript. The features provided by the `Ghost` and `Post` classes allow for a wide range of interactions, from basic CRUD operations to advanced filtering and error handling. For more information, please refer to the [documentation](https://apiclient.xyz.gitlab.io/ghost/). undefined