https://github.com/dkirchhof/payload-rest-client
https://github.com/dkirchhof/payload-rest-client
payload-plugin
Last synced: over 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/dkirchhof/payload-rest-client
- Owner: dkirchhof
- Created: 2023-10-14T15:34:22.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-18T10:24:38.000Z (almost 2 years ago)
- Last Synced: 2024-09-12T11:09:56.610Z (over 1 year ago)
- Topics: payload-plugin
- Language: TypeScript
- Homepage:
- Size: 45.9 KB
- Stars: 31
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# payload-rest-client
A typesafe rest api client for the [payload cms](https://payloadcms.com).
## Quick Start
1. Assume you have a users (auth enabled) and a posts collection with following fields:
```ts
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:
```ts
import { createClient } from "payload-rest-client";
import { Config } from "./payload-types"; // auto generated types from payload
type Locales = "de" | "en";
const client = createClient({
apiUrl: "http://localhost:4000/api",
});
```
3. Now you can use all available queries for all collections and globals in a typesafe way:
```ts
// 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({
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
```
## Custom Endpoints
1. Define input and output types for alle custom endpoints:
```ts
import { CustomEndpoint } from "payload-rest-client";
/**
* shape of generic CustomEndpoint type
*
* type Input = {
* params?: Record;
* query?: Record;
* body?: any;
* };
*
* type Output = any;
*
* type CustomEndpoint;
*/
type CustomEndpoints = {
greet: CustomEndpoint<{
params: { name: string };
query: { locale: Locales };
}, string>,
};
```
2. Add it to `createClient` function:
```diff
-const client = createClient({
- apiUrl: "http://localhost:4000/api",
-});
+const client = createClient({
+ apiUrl: "http://localhost:4000/api",
+ customEndpoints: {
+ greet: { method: "GET", path: params => `hello/${params.name}` },
+ },
+});
```
3. Call custom endpoints like this:
```ts
const greeting = await client.custom.greet({
params: { name: "John Doe" },
query: { locale: "en" },
});
```
## API
[Full documentation of the rest api](https://payloadcms.com/docs/rest-api/overview)
### Client options
- apiUrl: string;
- cache?: RequestCache;
- headers?: HeadersInit;
- debug?: boolean;
- getAdditionalFetchOptions?: (params: GetAdditionalFetchOptionsParams) => any;
- customFetchFn? (input: RequestInfo | URL, init?: RequestInit): Promise;
- customEndpoints?: Record;
### Collections
- find: (params?: FindParams) => Promise>;
- findById: (params: FindByIdParams) => Promise;
- count: (params: CountParams) => Promise;
- create: (params: CreateParams) => Promise>;
- createDraft: (params: CreateDraftParams) => Promise>;
- update: (params: UpdateParams) => Promise>;
- updateById: (params: UpdateByIdParams) => Promise>;
- delete: (params?: DeleteParams) => Promise>;
- deleteById: (params: DeleteByIdParams) => Promise;
### Collections with auth enabled (additional to above)
- login: (params: LoginParams) => Promise>;
- logout: (params: LogoutParams) => Promise;
- unlock: (params: UnlockParams) => Promise;
- refresh-token: (params: RefreshTokenParams) => Promise;
- me: (params: MeParams) => Promise>;
- forgot-password: (params: ForgotPasswordParams) => Promise;
- reset-password: (params: ResetPasswordParams) => Promise>;
### Globals
- get: (params?: BaseParams) => Promise;
- update: (params: UpdateGlobalParams) => Promise;
### Others
- access: () => Promise;
## Changelog
### v 3.0.5
- Infer id params (`string` or `number`) from type.
### v 3.0.4
- Added custom endpoints
### v 3.0.3
- Added option to use custom fetch function
### v 3.0.2
- Export error types
- Added access api
### v 3.0.1
- Better type inference for joins
### v 3.0.0
- Payload 3 (for Payload 2 use older versions)
- Added `select`, `populate` and `join` params
- Added `count` api