payload-rest-client

A typesafe rest api client for the payload cms.

Quick Start

1. Assume you have a users (auth enabled) and a posts collection with following fields:

interface User {
    id: string;
    email: string;
    name: string;
    password: string;
    createdAt: string;
    updatedAt: string;
}

interface Post {
    id: string;
    title: string;
    content: string;
    createdAt: string;
    updatedAt: string;
}

2. Create the client:

import { createClient } from "payload-rest-client";
import { Config } from "./payload-types"; // auto generated types from payload

type Locales = "de" | "en";

const client = createClient<Config, Locales>({
    apiUrl: "http://localhost:4000/api",
});

3. Now you can use all available queries for all collections and globals in a typesafe way:

// if you wan't to use protected routes, use login api...
const loginResponse = await client.collections.users.login({
    email: process.env.PAYLOAD_API_EMAIL,
    password: process.env.PAYLOAD_API_PASSWORD,
});

// ...and create another client with authorization header
const protectedClient = createClient<Config, Locales>({
    apiUrl: "http://localhost:4000/api",
    headers: {
        "Authorization": `Bearer ${loginResponse.token}`,
    },
});

const posts = await protectedClient.collections.posts.find({
    sort: "title", // only top level keys (optionally prefixed with "-") of Post allowed
    locale: "de", // only defined locales allowed
    limit: 10,
    page: 2,
});

console.log(posts); // type of posts is FindResult<Post> 

API

Full documentation of the rest api

Client options

• apiUrl: string;
• cache?: RequestCache;
• headers?: HeadersInit;
• debug?: boolean;
• getAdditionalFetchOptions?: (params: GetAdditionalFetchOptionsParams) => any

Collections

• find: (params?: FindParams<T, LOCALES>) => Promise<FindResult>;
• findById: (params: FindByIdParams) => Promise;
• count: (params: CountParams) => Promise;
• create: (params: CreateParams<T, LOCALES>) => Promise<CreateResult>;
• createDraft: (params: CreateDraftParams<T, LOCALES>) => Promise<CreateDraftResult>;
• update: (params: UpdateParams<T, LOCALES>) => Promise<UpdateResult>;
• updateById: (params: UpdateByIdParams<T, LOCALES>) => Promise<UpdateByIdResult>;
• delete: (params?: DeleteParams<T, LOCALES>) => Promise<DeleteResult>;
• deleteById: (params: DeleteByIdParams) => Promise;

Collections with auth enabled (additional to above)

• login: (params: LoginParams) => Promise<LoginResult>;
• logout: (params: LogoutParams) => Promise;
• unlock: (params: UnlockParams) => Promise;
• refresh-token: (params: RefreshTokenParams) => Promise;
• me: (params: MeParams) => Promise<MeResult>;
• forgot-password: (params: ForgotPasswordParams) => Promise;
• reset-password: (params: ResetPasswordParams) => Promise<ResetPasswordResult>;

Globals

• get: (params?: BaseParams) => Promise;
• update: (params: UpdateGlobalParams<T, LOCALES>) => Promise;