ts-ghost

Read

The read method is used to one item from a Ghost Admin API resource, it is the equivalent of the GET /posts/slug/this-is-a-slug endpoint. You have to give it an identity field to fetch the resource.

Options

Options for the read method depends on the resource you are querying. Each resource have a specific identity field that you can use to fetch it.

For example, the Post resource will have id and slug as identity fields but the Member resource will only have id. On the other hand the User resource will have id, and email as identity fields.

Use TypeScript autocomplete to guide you through the available identity fields.

import { TSGhostAdminAPI } from "@ts-ghost/admin-api";
 
const api = new TSGhostAdminAPI(
  "https://demo.ghost.io",
  "1efedd9db174adee2d23d982:4b74dca0219bad629852191af326a45037346c2231240e0f7aec1f9371cc14e8",
  "v5.0"
);
 
let query = api.users.read({
  email: "philippe@ts-ghost.com"
});
 
// or
 
let query = api.users.read({
  id: "edHks74hdKqhs34izzahd45"
});

Not recommended:

You can submit both id and email, but the fetcher will then chose the id in priority if present to make the final URL query to the Ghost API.

let query = api.users.read({
  id: "edHks74hdKqhs34izzahd45", // id will take priority
  email: "philippe@ts-ghost.com",
});

The order of preference is id > slug > email.

Output modifiers

After calling read you get a Fetcher instance that you can use to optionnaly alter the output of the result with methods like include, fields and formats. You can also skip that and use the fetch method directly to get the result.

There is a section dedicated to output modifiers here.

Fetching the data

After using browse query, you will get a ReadFetcher with an async fetch method. That result is a discriminated union with the Boolean success as a discriminator, so a check on success will let you know if the query was successful or not. Generally your workflow will look like that:

let result = await api.posts.read({ slug: "this-is-a-slug" }).fetch();
if (result.success) {
  const posts = result.data;
  //     ^? type Post
} else {
  // errors array of objects
  console.log(result.errors.map((e) => e.message).join("\n"));
}

Result type of .fetch()

The data property of the result will be an object corresponding to the resource you requested. This output schema will be modified according to the output modifiers you used.

Basic example for Post (without output modifiers you get the full Post object):

// example for the read query (the data is an object)
const result: {
    success: true;
    data: Post; // parsed by the Zod Schema and modified by the fields selected
} | {
    success: false;
    errors: {
        message: string;
        type: string;
    }[];
}
Browse
Output Modfiers