@paragraphcms/client 1.6.0 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +41 -498
- package/dist/client.d.ts +1 -1
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +77 -52
- package/dist/types.d.ts +96 -97
- package/dist/types.d.ts.map +1 -1
- package/package.json +3 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Paragraph CMS
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,545 +1,88 @@
|
|
|
1
1
|
# @paragraphcms/client
|
|
2
2
|
|
|
3
|
-
Official TypeScript client for the Paragraph CMS
|
|
3
|
+
Official TypeScript client for the Paragraph CMS API.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
<!--
|
|
6
|
+
Replace this block with the README image.
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+
<p align="center">
|
|
9
|
+
<img src="./assets/paragraph-client.png" alt="@paragraphcms/client" />
|
|
10
|
+
</p>
|
|
11
|
+
-->
|
|
12
|
+
|
|
13
|
+
`@paragraphcms/client` is a small, typed SDK built on top of the standard Fetch API. It runs in Node.js 18+ and other server-side runtimes that expose `fetch`.
|
|
8
14
|
|
|
9
|
-
Install
|
|
15
|
+
## Install
|
|
10
16
|
|
|
11
17
|
```bash
|
|
12
18
|
npm install @paragraphcms/client
|
|
13
|
-
|
|
14
|
-
# Alternative package managers
|
|
19
|
+
# or
|
|
15
20
|
pnpm add @paragraphcms/client
|
|
21
|
+
# or
|
|
16
22
|
yarn add @paragraphcms/client
|
|
17
23
|
```
|
|
18
24
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
```ts
|
|
22
|
-
import { Client } from "@paragraphcms/client";
|
|
23
|
-
|
|
24
|
-
const client = new Client({
|
|
25
|
-
apiKey: process.env.PARAGRAPH_API_KEY!,
|
|
26
|
-
});
|
|
27
|
-
|
|
28
|
-
const pages = await client.pages.list();
|
|
29
|
-
const page = await client.pages.getBySlug("pricing");
|
|
30
|
-
|
|
31
|
-
console.log(pages.meta.total_items);
|
|
32
|
-
console.log(page.id);
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
## Table of Contents
|
|
36
|
-
|
|
37
|
-
- [Requirements](#requirements)
|
|
38
|
-
- [Features](#features)
|
|
39
|
-
- [Creating a Client Instance](#creating-a-client-instance)
|
|
40
|
-
- [Configuration](#configuration)
|
|
41
|
-
- [Per-request Options](#per-request-options)
|
|
42
|
-
- [Error Handling](#error-handling)
|
|
43
|
-
- [Rate Limiting](#rate-limiting)
|
|
44
|
-
- [Return Shapes](#return-shapes)
|
|
45
|
-
- [API](#api)
|
|
46
|
-
- [End-to-end Examples](#end-to-end-examples)
|
|
47
|
-
- [Exported Types](#exported-types)
|
|
48
|
-
- [Testing](#testing)
|
|
49
|
-
- [License](#license)
|
|
50
|
-
|
|
51
|
-
## Requirements
|
|
52
|
-
|
|
53
|
-
- Node.js `18+` for direct Node.js usage.
|
|
54
|
-
- A runtime with standard Fetch API primitives for edge and serverless usage.
|
|
55
|
-
- ESM support. The package is published as an ES module.
|
|
56
|
-
|
|
57
|
-
## Features
|
|
58
|
-
|
|
59
|
-
- Full coverage for the current Paragraph CMS v1 API surface.
|
|
60
|
-
- `new Client({ apiKey })` entrypoint with a compact, typed SDK.
|
|
61
|
-
- Built-in request queue that rate-limits each client instance to `5 req/s` by default.
|
|
62
|
-
- Automatic retries for `429 Too Many Requests` responses using `Retry-After` when available.
|
|
63
|
-
- Runtime-agnostic implementation with no runtime dependencies.
|
|
64
|
-
- First-class TypeScript types for payloads, list metadata, domain models, and API errors.
|
|
65
|
-
- Request cancellation with `AbortSignal`.
|
|
66
|
-
|
|
67
|
-
## Creating a Client Instance
|
|
68
|
-
|
|
69
|
-
`const client = new Client(options)`
|
|
70
|
-
|
|
71
|
-
Initialize the client with your Paragraph API key and optional runtime settings:
|
|
72
|
-
|
|
73
|
-
```ts
|
|
74
|
-
import { Client, type ClientOptions } from "@paragraphcms/client";
|
|
75
|
-
|
|
76
|
-
const config: ClientOptions = {
|
|
77
|
-
apiKey: process.env.PARAGRAPH_API_KEY!,
|
|
78
|
-
timeoutMs: 10_000,
|
|
79
|
-
};
|
|
80
|
-
|
|
81
|
-
export const client = new Client(config);
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
To target a local or staging API, pass `baseUrl` explicitly:
|
|
85
|
-
|
|
86
|
-
```ts
|
|
87
|
-
const client = new Client({
|
|
88
|
-
apiKey: process.env.PARAGRAPH_API_KEY!,
|
|
89
|
-
baseUrl: "http://localhost:3001",
|
|
90
|
-
});
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
Important runtime notes:
|
|
94
|
-
|
|
95
|
-
- The default API base URL is `https://api.paragraphcms.com/v1`.
|
|
96
|
-
- If you pass `baseUrl: "https://api.paragraphcms.com"` or another origin without `/v1`, the client normalizes it to the `/v1` API root automatically.
|
|
97
|
-
- The client authenticates requests with the `x-api-key` header.
|
|
98
|
-
- Request and response field names intentionally mirror the HTTP API, so payload keys remain in `snake_case`.
|
|
99
|
-
|
|
100
|
-
## Configuration
|
|
101
|
-
|
|
102
|
-
```ts
|
|
103
|
-
type ClientOptions = {
|
|
104
|
-
apiKey: string;
|
|
105
|
-
baseUrl?: string;
|
|
106
|
-
fetch?: typeof globalThis.fetch;
|
|
107
|
-
headers?: HeadersInit;
|
|
108
|
-
timeoutMs?: number;
|
|
109
|
-
maxRequestsPerSecond?: number;
|
|
110
|
-
};
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
### `apiKey`
|
|
114
|
-
|
|
115
|
-
Required. Paragraph CMS organization API key.
|
|
116
|
-
|
|
117
|
-
### `baseUrl`
|
|
118
|
-
|
|
119
|
-
Optional. Defaults to `https://api.paragraphcms.com/v1`.
|
|
120
|
-
|
|
121
|
-
Accepted examples:
|
|
122
|
-
|
|
123
|
-
- `https://api.paragraphcms.com/v1`
|
|
124
|
-
- `https://api.paragraphcms.com`
|
|
125
|
-
- `http://localhost:3001/v1`
|
|
126
|
-
|
|
127
|
-
### `fetch`
|
|
128
|
-
|
|
129
|
-
Optional custom fetch implementation. Useful in tests or custom runtimes.
|
|
130
|
-
|
|
131
|
-
### `headers`
|
|
132
|
-
|
|
133
|
-
Optional default headers merged into every request.
|
|
134
|
-
|
|
135
|
-
### `timeoutMs`
|
|
136
|
-
|
|
137
|
-
Optional default request timeout in milliseconds. Per-request options can override it.
|
|
138
|
-
|
|
139
|
-
### `maxRequestsPerSecond`
|
|
140
|
-
|
|
141
|
-
Optional per-client limiter ceiling. Defaults to `5`.
|
|
142
|
-
|
|
143
|
-
### `maxRateLimitRetries`
|
|
144
|
-
|
|
145
|
-
Optional maximum number of automatic retries after a `429 Too Many Requests` response. Defaults to `2`. Set to `0` to disable retries.
|
|
146
|
-
|
|
147
|
-
## Per-request Options
|
|
148
|
-
|
|
149
|
-
Every SDK method accepts an optional final `RequestOptions` argument:
|
|
150
|
-
|
|
151
|
-
```ts
|
|
152
|
-
type RequestOptions = {
|
|
153
|
-
signal?: AbortSignal;
|
|
154
|
-
headers?: HeadersInit;
|
|
155
|
-
timeoutMs?: number;
|
|
156
|
-
maxRateLimitRetries?: number;
|
|
157
|
-
};
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
For methods that also accept a body or query object, pass request options as the last argument:
|
|
161
|
-
|
|
162
|
-
```ts
|
|
163
|
-
const controller = new AbortController();
|
|
164
|
-
|
|
165
|
-
const page = await client.pages.get("page-id", undefined, {
|
|
166
|
-
signal: controller.signal,
|
|
167
|
-
timeoutMs: 10_000,
|
|
168
|
-
});
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
## Error Handling
|
|
25
|
+
## Quick Start
|
|
172
26
|
|
|
173
|
-
|
|
27
|
+
Create a client instance with your API key:
|
|
174
28
|
|
|
175
29
|
```ts
|
|
176
|
-
import {
|
|
177
|
-
Client,
|
|
178
|
-
ParagraphApiError,
|
|
179
|
-
ParagraphClientError,
|
|
180
|
-
} from "@paragraphcms/client";
|
|
181
|
-
|
|
182
|
-
const client = new Client({
|
|
183
|
-
apiKey: process.env.PARAGRAPH_API_KEY!,
|
|
184
|
-
});
|
|
185
|
-
|
|
186
|
-
try {
|
|
187
|
-
await client.pages.get("missing-id");
|
|
188
|
-
} catch (error) {
|
|
189
|
-
if (error instanceof ParagraphApiError) {
|
|
190
|
-
console.error(error.status);
|
|
191
|
-
console.error(error.code);
|
|
192
|
-
console.error(error.message);
|
|
193
|
-
console.error(error.details);
|
|
194
|
-
}
|
|
195
|
-
|
|
196
|
-
if (error instanceof ParagraphClientError) {
|
|
197
|
-
console.error(error.message);
|
|
198
|
-
}
|
|
199
|
-
}
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
## Rate Limiting
|
|
203
|
-
|
|
204
|
-
Paragraph CMS v1 is rate-limited to `5 req/s`. Each `Client` instance includes an internal queue that spaces request starts so the instance stays within that budget by default.
|
|
205
|
-
|
|
206
|
-
Important details:
|
|
207
|
-
|
|
208
|
-
- The limiter is per client instance, not global across containers, lambdas, or workers.
|
|
209
|
-
- If your application creates many `Client` instances, each instance keeps its own queue.
|
|
210
|
-
- The safest production pattern is to reuse one shared `Client` instance per process or isolate when possible.
|
|
211
|
-
- If the API still returns `429 Too Many Requests`, the client retries automatically up to `maxRateLimitRetries` times and honors the `Retry-After` header when it is present.
|
|
212
|
-
- Request timeouts include retry wait time and all retry attempts, not just the first fetch.
|
|
213
|
-
|
|
214
|
-
You can lower the per-instance ceiling if needed:
|
|
30
|
+
import { Client } from "@paragraphcms/client";
|
|
215
31
|
|
|
216
|
-
```ts
|
|
217
32
|
const client = new Client({
|
|
218
33
|
apiKey: process.env.PARAGRAPH_API_KEY!,
|
|
219
|
-
maxRequestsPerSecond: 3,
|
|
220
34
|
});
|
|
221
35
|
```
|
|
222
36
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
- Single-resource endpoints return the unwrapped `data` payload.
|
|
226
|
-
- Paginated endpoints return `{ data, meta }`.
|
|
227
|
-
- `locales.list()` returns a plain `Locale[]` because the underlying API endpoint is not paginated.
|
|
228
|
-
|
|
229
|
-
## API
|
|
230
|
-
|
|
231
|
-
The SDK closely mirrors the Paragraph CMS HTTP API. Resource names stay familiar and request/response bodies are intentionally left in `snake_case` to match the wire format.
|
|
232
|
-
|
|
233
|
-
### Root
|
|
234
|
-
|
|
235
|
-
```ts
|
|
236
|
-
client.getInfo(options?)
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
Returns the public `/v1` info payload:
|
|
240
|
-
|
|
241
|
-
```ts
|
|
242
|
-
{
|
|
243
|
-
version: "v1",
|
|
244
|
-
openapi_url: "/v1/openapi.json",
|
|
245
|
-
authentication: {
|
|
246
|
-
type: "api_key",
|
|
247
|
-
supported_headers: ["x-api-key", "authorization"],
|
|
248
|
-
authorization_format: "Bearer <api-key>",
|
|
249
|
-
},
|
|
250
|
-
resources: [...],
|
|
251
|
-
}
|
|
252
|
-
```
|
|
253
|
-
|
|
254
|
-
### Pages
|
|
255
|
-
|
|
256
|
-
Page listing, detail, mutation, duplication, restore, and translation helpers:
|
|
37
|
+
### Get All Pages or Pages From a Collection
|
|
257
38
|
|
|
258
39
|
```ts
|
|
259
|
-
client.pages.list(
|
|
260
|
-
client.pages.create(body?, options?)
|
|
261
|
-
client.pages.get(pageId, query?, options?)
|
|
262
|
-
client.pages.getBySlug(slug, options?)
|
|
263
|
-
client.pages.update(pageId, body, options?)
|
|
264
|
-
client.pages.delete(pageId, options?)
|
|
265
|
-
client.pages.restore(pageId, options?)
|
|
266
|
-
client.pages.permanentlyDelete(pageId, options?)
|
|
267
|
-
client.pages.duplicate(pageId, options?)
|
|
268
|
-
client.pages.createTranslation(pageId, body, options?)
|
|
269
|
-
client.page.get(pageId, query?, options?)
|
|
270
|
-
client.page.getBySlug(slug, options?)
|
|
271
|
-
```
|
|
272
|
-
|
|
273
|
-
Supported `sort` fields for `pages.list()`:
|
|
40
|
+
const { data: allPages, meta } = await client.pages.list();
|
|
274
41
|
|
|
275
|
-
|
|
276
|
-
-
|
|
277
|
-
- `created_at`
|
|
278
|
-
- `updated_at`
|
|
279
|
-
- `published_at`
|
|
280
|
-
|
|
281
|
-
Notes:
|
|
282
|
-
|
|
283
|
-
- If you omit both `limit` and `page`, `pages.list()` returns the full matching result set.
|
|
284
|
-
- `collection` is a convenience alias for `collection_id` in `pages.list()` queries.
|
|
285
|
-
- `label_id` is passed as `string[]` in the SDK and serialized to the API CSV format automatically.
|
|
286
|
-
- `pages.list()` sends `include_content: false` by default. Set `include_content: true` to include `content` in list responses.
|
|
287
|
-
- Page responses should be treated as Tiptap JSON arrays. `content_format` is no longer required in the response shape.
|
|
288
|
-
- `page.get()` is a short alias for `pages.get()`.
|
|
289
|
-
- `pages.getBySlug()` is an SDK convenience lookup built on top of `pages.list({ slug })`, then fetches the full page details by ID.
|
|
290
|
-
- `page.getBySlug()` is a short alias for the same lookup.
|
|
291
|
-
|
|
292
|
-
### Collections
|
|
293
|
-
|
|
294
|
-
```ts
|
|
295
|
-
client.collections.list(query?, options?)
|
|
296
|
-
client.collections.create(body, options?)
|
|
297
|
-
client.collections.get(collectionId, options?)
|
|
298
|
-
client.collections.update(collectionId, body, options?)
|
|
299
|
-
client.collections.delete(collectionId, options?)
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
Supported `sort` fields for `collections.list()`:
|
|
303
|
-
|
|
304
|
-
- `name`
|
|
305
|
-
- `page_count`
|
|
306
|
-
- `last_modified_at`
|
|
307
|
-
|
|
308
|
-
### Media
|
|
309
|
-
|
|
310
|
-
```ts
|
|
311
|
-
client.media.list(query?, options?)
|
|
312
|
-
client.media.upload(body, options?)
|
|
313
|
-
client.media.get(mediaId, options?)
|
|
314
|
-
client.media.update(mediaId, body, options?)
|
|
315
|
-
client.media.delete(mediaId, options?)
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
Supported `sort` fields for `media.list()`:
|
|
319
|
-
|
|
320
|
-
- `file_name`
|
|
321
|
-
- `size`
|
|
322
|
-
- `created_at`
|
|
323
|
-
- `updated_at`
|
|
324
|
-
|
|
325
|
-
`media.upload()` accepts:
|
|
326
|
-
|
|
327
|
-
- `File`
|
|
328
|
-
- `Blob`
|
|
329
|
-
- `ArrayBuffer`
|
|
330
|
-
- Typed arrays such as `Uint8Array`
|
|
331
|
-
- Node.js `Buffer`
|
|
332
|
-
|
|
333
|
-
Example:
|
|
334
|
-
|
|
335
|
-
```ts
|
|
336
|
-
const file = new File([imageBytes], "hero.png", {
|
|
337
|
-
type: "image/png",
|
|
42
|
+
const { data: collectionPages } = await client.pages.list({
|
|
43
|
+
collectionId: "collection-id",
|
|
338
44
|
});
|
|
339
45
|
|
|
340
|
-
const
|
|
341
|
-
|
|
342
|
-
page_id: "page-id",
|
|
343
|
-
alt: "Homepage hero",
|
|
344
|
-
});
|
|
345
|
-
```
|
|
346
|
-
|
|
347
|
-
If you upload from a raw `Buffer`, `Uint8Array`, or `ArrayBuffer`, you can also pass `file_name` and `content_type`:
|
|
348
|
-
|
|
349
|
-
```ts
|
|
350
|
-
await client.media.upload({
|
|
351
|
-
file: imageBuffer,
|
|
352
|
-
file_name: "hero.png",
|
|
353
|
-
content_type: "image/png",
|
|
354
|
-
page_id: "page-id",
|
|
46
|
+
const { data: pagesWithSlugs } = await client.page.list({
|
|
47
|
+
requiredSlug: true,
|
|
355
48
|
});
|
|
356
|
-
```
|
|
357
49
|
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
client.members.list(query?, options?)
|
|
362
|
-
client.members.get(memberId, options?)
|
|
363
|
-
client.authors.list(query?, options?)
|
|
364
|
-
client.authors.get(authorId, options?)
|
|
365
|
-
client.reviewers.list(query?, options?)
|
|
366
|
-
client.reviewers.get(reviewerId, options?)
|
|
50
|
+
console.log(meta.totalItems);
|
|
51
|
+
console.log(collectionPages.map((page) => page.title));
|
|
52
|
+
console.log(pagesWithSlugs.map((page) => page.slug));
|
|
367
53
|
```
|
|
368
54
|
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
- `name`
|
|
372
|
-
- `email`
|
|
373
|
-
- `created_at`
|
|
374
|
-
|
|
375
|
-
Notes:
|
|
376
|
-
|
|
377
|
-
- `members.get()`, `authors.get()`, and `reviewers.get()` are SDK convenience lookups built on top of paginated list endpoints because the HTTP API does not expose `/members/{id}`, `/authors/{id}`, or `/reviewers/{id}` detail endpoints.
|
|
378
|
-
- `authors` and `reviewers` are aliases of member listing endpoints exposed by the API.
|
|
379
|
-
|
|
380
|
-
### Statuses
|
|
55
|
+
### Get a Page by Slug
|
|
381
56
|
|
|
382
57
|
```ts
|
|
383
|
-
client.
|
|
384
|
-
client.statuses.create(body, options?)
|
|
385
|
-
client.statuses.get(statusId, options?)
|
|
386
|
-
client.statuses.update(statusId, body, options?)
|
|
387
|
-
client.statuses.reorder(body, options?)
|
|
388
|
-
client.statuses.delete(statusId, options?)
|
|
389
|
-
```
|
|
390
|
-
|
|
391
|
-
Supported `sort` fields for `statuses.list()`:
|
|
392
|
-
|
|
393
|
-
- `type`
|
|
394
|
-
- `order`
|
|
395
|
-
- `name`
|
|
396
|
-
- `created_at`
|
|
397
|
-
|
|
398
|
-
### Labels
|
|
399
|
-
|
|
400
|
-
```ts
|
|
401
|
-
client.labels.list(query?, options?)
|
|
402
|
-
client.labels.create(body, options?)
|
|
403
|
-
client.labels.get(labelId, options?)
|
|
404
|
-
client.labels.update(labelId, body, options?)
|
|
405
|
-
client.labels.reorder(body, options?)
|
|
406
|
-
client.labels.delete(labelId, options?)
|
|
407
|
-
```
|
|
408
|
-
|
|
409
|
-
Supported `sort` fields for `labels.list()`:
|
|
410
|
-
|
|
411
|
-
- `order`
|
|
412
|
-
- `name`
|
|
413
|
-
- `created_at`
|
|
414
|
-
|
|
415
|
-
### Data Models
|
|
416
|
-
|
|
417
|
-
```ts
|
|
418
|
-
client.dataModels.list(query?, options?)
|
|
419
|
-
client.dataModels.create(body, options?)
|
|
420
|
-
client.dataModels.get(dataModelId, options?)
|
|
421
|
-
client.dataModels.update(dataModelId, body, options?)
|
|
422
|
-
client.dataModels.delete(dataModelId, options?)
|
|
423
|
-
```
|
|
424
|
-
|
|
425
|
-
Supported `sort` fields for `dataModels.list()`:
|
|
426
|
-
|
|
427
|
-
- `name`
|
|
428
|
-
- `created_at`
|
|
429
|
-
- `updated_at`
|
|
430
|
-
|
|
431
|
-
### Locales
|
|
432
|
-
|
|
433
|
-
```ts
|
|
434
|
-
client.locales.list(options?)
|
|
435
|
-
client.locales.get(code, options?)
|
|
436
|
-
client.locales.create(body, options?)
|
|
437
|
-
client.locales.delete(code, options?)
|
|
438
|
-
```
|
|
439
|
-
|
|
440
|
-
`locales.get()` is an SDK convenience lookup over `locales.list()` because the HTTP API exposes locale listing and deletion by code, but not a dedicated locale detail endpoint.
|
|
441
|
-
|
|
442
|
-
### AI
|
|
443
|
-
|
|
444
|
-
```ts
|
|
445
|
-
client.ai.generateMetaName(body, options?)
|
|
446
|
-
client.ai.generateMetaDescription(body, options?)
|
|
447
|
-
client.ai.generateContent(body, options?)
|
|
448
|
-
```
|
|
449
|
-
|
|
450
|
-
## End-to-end Examples
|
|
451
|
-
|
|
452
|
-
### Create a Page and Upload Its Hero Image
|
|
453
|
-
|
|
454
|
-
```ts
|
|
455
|
-
const pageResult = await client.pages.create({
|
|
456
|
-
title: "About",
|
|
457
|
-
language: "en",
|
|
458
|
-
content: [
|
|
459
|
-
{
|
|
460
|
-
type: "paragraph",
|
|
461
|
-
content: [{ type: "text", text: "About" }],
|
|
462
|
-
},
|
|
463
|
-
],
|
|
464
|
-
});
|
|
465
|
-
|
|
466
|
-
await client.media.upload({
|
|
467
|
-
file: heroBytes,
|
|
468
|
-
file_name: "about-hero.png",
|
|
469
|
-
content_type: "image/png",
|
|
470
|
-
page_id: pageResult.page.id,
|
|
471
|
-
alt: "About page hero image",
|
|
472
|
-
});
|
|
473
|
-
```
|
|
474
|
-
|
|
475
|
-
### Create a Translated Page Variant
|
|
58
|
+
const page = await client.pages.getBySlug("pricing");
|
|
476
59
|
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
language: "de",
|
|
480
|
-
mode: "translate",
|
|
481
|
-
model: "openai/gpt-5.4",
|
|
482
|
-
});
|
|
60
|
+
console.log(page.id);
|
|
61
|
+
console.log(page.title);
|
|
483
62
|
```
|
|
484
63
|
|
|
485
|
-
###
|
|
64
|
+
### Get All Supported Languages
|
|
486
65
|
|
|
487
66
|
```ts
|
|
488
|
-
const
|
|
489
|
-
model: "openai/gpt-5.4",
|
|
490
|
-
title: "Platform overview",
|
|
491
|
-
content: [],
|
|
492
|
-
});
|
|
67
|
+
const locales = await client.locales.list();
|
|
493
68
|
|
|
494
|
-
console.log(
|
|
69
|
+
console.log(locales.map((locale) => locale.code));
|
|
495
70
|
```
|
|
496
71
|
|
|
497
|
-
##
|
|
498
|
-
|
|
499
|
-
The package exports `Client`, `ParagraphApiError`, `ParagraphClientError`, and the main request, response, and domain types used by the SDK, including:
|
|
500
|
-
|
|
501
|
-
- `ClientOptions`
|
|
502
|
-
- `RequestOptions`
|
|
503
|
-
- `ListResponse`
|
|
504
|
-
- `PaginationMeta`
|
|
505
|
-
- `Page`
|
|
506
|
-
- `PageSummary`
|
|
507
|
-
- `Collection`
|
|
508
|
-
- `Media`
|
|
509
|
-
- `MediaDetail`
|
|
510
|
-
- `Status`
|
|
511
|
-
- `Label`
|
|
512
|
-
- `DataModel`
|
|
513
|
-
- `Locale`
|
|
514
|
-
- `Member`
|
|
515
|
-
- `CreatePageRequest`
|
|
516
|
-
- `UpdatePageRequest`
|
|
517
|
-
- `UploadMediaRequest`
|
|
518
|
-
- `GenerateContentRequest`
|
|
519
|
-
|
|
520
|
-
## Testing
|
|
72
|
+
## Framework Guides
|
|
521
73
|
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
- Unit tests for request serialization, multipart uploads, error handling, and rate limiting.
|
|
525
|
-
- Live integration tests that create, update, fetch, reorder, delete, and clean up real resources against the Paragraph API.
|
|
526
|
-
|
|
527
|
-
Commands:
|
|
528
|
-
|
|
529
|
-
```bash
|
|
530
|
-
npm test
|
|
531
|
-
npm run test:unit
|
|
532
|
-
npm run test:integration
|
|
533
|
-
```
|
|
74
|
+
Build with:
|
|
534
75
|
|
|
535
|
-
|
|
76
|
+
- [Next.js](https://paragraphcms.com)
|
|
77
|
+
- [Nuxt](https://paragraphcms.com)
|
|
78
|
+
- [Astro](https://paragraphcms.com)
|
|
79
|
+
- [SvelteKit](https://paragraphcms.com)
|
|
80
|
+
- [Remix](https://paragraphcms.com)
|
|
536
81
|
|
|
537
|
-
|
|
538
|
-
- `PARAGRAPH_API_BASE_URL` optionally overrides the API target for local or staging environments.
|
|
539
|
-
- `PARAGRAPH_AI_MODEL` optionally sets the model used by AI endpoint tests. If omitted, AI integration tests are skipped.
|
|
82
|
+
## Documentation
|
|
540
83
|
|
|
541
|
-
|
|
84
|
+
For full guides and API reference, see [paragraphcms.com](https://paragraphcms.com).
|
|
542
85
|
|
|
543
86
|
## License
|
|
544
87
|
|
|
545
|
-
|
|
88
|
+
MIT
|
package/dist/client.d.ts
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
import type { AiContentResult, AiMetaDescriptionResult, AiMetaNameResult, ApiInfo, ClientOptions, Collection, CollectionListQuery, CollectionMutationResult, CreateCollectionRequest, CreateDataModelRequest, CreateLabelRequest, CreateLocaleRequest, CreatePageRequest, CreatePageTranslationRequest, CreateStatusRequest, DataModel, DataModelListQuery, DataModelMutationResult, DeleteByCodeResult, DeleteResult, GenerateContentRequest, GenerateMetaRequest, GetPageQuery, Label, LabelMutationResult, LabelListQuery, ListResponse, Locale, LocaleMutationResult, Media, MediaDeleteResult, MediaDetail, MediaListQuery, MediaMutationResult, MediaUploadResult, Member, MemberListQuery, Page, PageListQuery, PageSummary, PageMutationResult, PageRestoreResult, PermanentDeleteResult, ReorderLabelsRequest, ReorderResult, ReorderStatusesRequest, RequestOptions, Status, StatusListQuery, StatusMutationResult, UpdateCollectionRequest, UpdateDataModelRequest, UpdateLabelRequest, UpdateMediaRequest, UpdatePageRequest, UpdateStatusRequest, UploadMediaRequest } from "./types.js";
|
|
2
2
|
export declare class Client {
|
|
3
3
|
private readonly apiKey;
|
|
4
|
-
private readonly baseUrl;
|
|
5
4
|
private readonly fetchImpl;
|
|
6
5
|
private readonly defaultHeaders;
|
|
7
6
|
private readonly timeoutMs?;
|
|
@@ -20,6 +19,7 @@ export declare class Client {
|
|
|
20
19
|
createTranslation: (pageId: string, body: CreatePageTranslationRequest, options?: RequestOptions) => Promise<PageMutationResult>;
|
|
21
20
|
};
|
|
22
21
|
readonly page: {
|
|
22
|
+
list: (query?: PageListQuery, options?: RequestOptions) => Promise<ListResponse<PageSummary>>;
|
|
23
23
|
get: (pageId: string, query?: GetPageQuery, options?: RequestOptions) => Promise<Page>;
|
|
24
24
|
getBySlug: (slug: string, options?: RequestOptions) => Promise<Page>;
|
|
25
25
|
};
|
package/dist/client.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,eAAe,EACf,uBAAuB,EACvB,gBAAgB,EAEhB,OAAO,EACP,aAAa,EACb,UAAU,EACV,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,4BAA4B,EAC5B,mBAAmB,EACnB,SAAS,EACT,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,EACtB,mBAAmB,EACnB,YAAY,EACZ,KAAK,EACL,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,MAAM,EACN,oBAAoB,EACpB,KAAK,EACL,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,MAAM,EACN,eAAe,EACf,IAAI,EACJ,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,sBAAsB,EAEtB,cAAc,EACd,MAAM,EACN,eAAe,EACf,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
|