12 KiB
@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:
npm install @apiclient.xyz/ghost
Yarn:
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.
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.
// 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:
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.
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.
const updatedPostData = {
...post.toJson(),
title: 'Updated Title',
html: '<p>Updated HTML content</p>'
};
await post.update(updatedPostData);
console.log('Post updated successfully');
Deleting a Post
To delete a post:
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.
const newPostData = {
id: 'new-post-id',
title: 'New Post Title',
html: '<p>This is the content of the new post.</p>',
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.
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:
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.
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.
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.
// 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.
// 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.
// 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.
// 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: '<p>Contact information...</p>'
});
// Update a page
await newPage.update({
html: '<p>Updated contact information...</p>'
});
// Delete a page
await newPage.delete();
Enhanced Post Filtering
The getPosts method now supports multiple filtering options.
// 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.
// 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.
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.
// 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: '<p>Content here</p>',
feature_image: imageUrl
});
Bulk Operations
Perform operations on multiple posts at once.
// 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).
// 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).
// 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.
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.
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: '<p>This is the content of the new post.</p>',
};
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.
- Install the development dependencies:
npm install
- Run the tests:
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. undefined