546 lines
12 KiB
Markdown
546 lines
12 KiB
Markdown
# @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: '<p>Updated HTML content</p>'
|
|
};
|
|
|
|
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: '<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.
|
|
|
|
```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: '<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.
|
|
|
|
```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: '<p>Content here</p>',
|
|
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();
|
|
```
|
|
|
|
#### Site Settings
|
|
|
|
Read and update Ghost site settings.
|
|
|
|
```typescript
|
|
// Get all settings
|
|
const settings = await ghostInstance.getSettings();
|
|
console.log(settings);
|
|
|
|
// Update settings
|
|
await ghostInstance.updateSettings([
|
|
{
|
|
key: 'title',
|
|
value: 'My Updated Site Title'
|
|
},
|
|
{
|
|
key: 'description',
|
|
value: 'My site description'
|
|
}
|
|
]);
|
|
```
|
|
|
|
#### Webhooks Management
|
|
|
|
Manage webhooks for Ghost events.
|
|
|
|
```typescript
|
|
// Get all webhooks
|
|
const webhooks = await ghostInstance.getWebhooks();
|
|
webhooks.forEach(webhook => {
|
|
console.log(`${webhook.name}: ${webhook.target_url}`);
|
|
});
|
|
|
|
// Get webhook by ID
|
|
const webhook = await ghostInstance.getWebhookById('webhook-id');
|
|
|
|
// 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: '<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.
|
|
|
|
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 |