From 8de7fc795efb570826a3c492712d53b6fd14245b Mon Sep 17 00:00:00 2001 From: Philipp Kunz Date: Mon, 1 Jul 2024 16:34:22 +0200 Subject: [PATCH] fix(docs): Updated the project keywords and readme content for better clarity and SEO --- changelog.md | 6 + npmextra.json | 14 +- package.json | 14 +- readme.md | 279 +++++++++++++++++++++++++++++++++++---- ts/00_commitinfo_data.ts | 4 +- 5 files changed, 287 insertions(+), 30 deletions(-) diff --git a/changelog.md b/changelog.md index 6c691ca..d366194 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,11 @@ # Changelog +## 2024-07-01 - 1.0.3 - fix(docs) +Updated the project keywords and readme content for better clarity and SEO + +- Improved the project description in `package.json` and `npmextra.json`. +- Added comprehensive usage instructions and examples in `readme.md`. + ## 2024-07-01 - 1.0.2 - fix(core) No changes in the project files diff --git a/npmextra.json b/npmextra.json index 8b69a65..431fb5c 100644 --- a/npmextra.json +++ b/npmextra.json @@ -5,10 +5,20 @@ "githost": "code.foss.global", "gitscope": "apiclient.xyz", "gitrepo": "ghost", - "description": "an unofficial ghost api package", + "description": "An unofficial Ghost CMS API package enabling content and admin functionality for managing posts.", "npmPackagename": "@apiclient.xyz/ghost", "license": "MIT", - "projectDomain": "apiclient.xyz" + "projectDomain": "apiclient.xyz", + "keywords": [ + "Ghost CMS", + "API client", + "content management", + "admin API", + "content API", + "TypeScript", + "post management", + "blog management" + ] } }, "npmci": { diff --git a/package.json b/package.json index 01584e0..33541bf 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@apiclient.xyz/ghost", "version": "1.0.2", "private": false, - "description": "an unofficial ghost api package", + "description": "An unofficial Ghost CMS API package enabling content and admin functionality for managing posts.", "main": "dist_ts/index.js", "typings": "dist_ts/index.d.ts", "type": "module", @@ -48,5 +48,15 @@ "cli.js", "npmextra.json", "readme.md" + ], + "keywords": [ + "Ghost CMS", + "API client", + "content management", + "admin API", + "content API", + "TypeScript", + "post management", + "blog management" ] -} +} \ No newline at end of file diff --git a/readme.md b/readme.md index f66cf89..a94dc55 100644 --- a/readme.md +++ b/readme.md @@ -1,31 +1,262 @@ # @apiclient.xyz/ghost -an unofficial ghost api package +An unofficial Ghost API package -## Availabililty and Links -* [npmjs.org (npm package)](https://www.npmjs.com/package/@apiclient.xyz/ghost) -* [gitlab.com (source)](https://code.foss.global/apiclient.xyz/ghost) -* [github.com (source mirror)](https://github.com/apiclient.xyz/ghost) -* [docs (typedoc)](https://apiclient.xyz.gitlab.io/ghost/) +## 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. -## Status for master +NPM: +```bash +npm install @apiclient.xyz/ghost +``` -Status Category | Status Badge --- | -- -GitLab Pipelines | [![pipeline status](https://code.foss.global/apiclient.xyz/ghost/badges/master/pipeline.svg)](https://lossless.cloud) -GitLab Pipline Test Coverage | [![coverage report](https://code.foss.global/apiclient.xyz/ghost/badges/master/coverage.svg)](https://lossless.cloud) -npm | [![npm downloads per month](https://badgen.net/npm/dy/@apiclient.xyz/ghost)](https://lossless.cloud) -Snyk | [![Known Vulnerabilities](https://badgen.net/snyk/apiclient.xyz/ghost)](https://lossless.cloud) -TypeScript Support | [![TypeScript](https://badgen.net/badge/TypeScript/>=%203.x/blue?icon=typescript)](https://lossless.cloud) -node Support | [![node](https://img.shields.io/badge/node->=%2010.x.x-blue.svg)](https://nodejs.org/dist/latest-v10.x/docs/api/) -Code Style | [![Code Style](https://badgen.net/badge/style/prettier/purple)](https://lossless.cloud) -PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@apiclient.xyz/ghost)](https://lossless.cloud) -PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@apiclient.xyz/ghost)](https://lossless.cloud) -BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@apiclient.xyz/ghost)](https://lossless.cloud) +Yarn: +```bash +yarn add @apiclient.xyz/ghost +``` ## Usage -Use TypeScript for best in class intellisense -For further information read the linked docs at the top of this readme. -## Legal -> MIT licensed | **©** [Task Venture Capital GmbH](https://task.vc) -| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy) +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: '

Updated HTML content

' +}; + +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: '

This is the content of the new post.

', + 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: '

This is the content of the new post.

', + }; + + 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 \ No newline at end of file diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index de26e2e..bfaaf43 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@apiclient.xyz/ghost', - version: '1.0.2', - description: 'an unofficial ghost api package' + version: '1.0.3', + description: 'An unofficial Ghost CMS API package enabling content and admin functionality for managing posts.' }