ghost/readme.md

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

### 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