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

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']);

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

readme.md

@apiclient.xyz/ghost

Install

Usage