@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());
});

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.

1. Install the development dependencies:

npm install

2. 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