@paragraphcms/client 1.0.0

package/README.md

@@ -0,0 +1,473 @@
+# Paragraph CMS Client
+
+Official TypeScript client for the Paragraph CMS v1 API.
+
+The package is built on top of the standard Fetch API, so it works in modern Node.js, Cloudflare Workers, Next.js route handlers/server actions, AWS Lambda, and other server-side JavaScript runtimes that expose `fetch`, `Headers`, `FormData`, `Blob`, and `AbortController`.
+
+## Features
+
+- Full coverage for the current Paragraph CMS v1 API surface.
+- `new Client({ apiKey })` entrypoint with a small, typed SDK.
+- Built-in request queue that rate-limits each client instance to `5 req/s` by default.
+- Runtime-agnostic implementation with no runtime dependencies.
+- First-class TypeScript types for request payloads, responses, list metadata, and API errors.
+- Request cancellation with `AbortSignal`.
+
+## Installation
+
+```bash
+npm install @paragraphcms/client
+```
+
+## Quick Start
+
+```ts
+import { Client } from "@paragraphcms/client";
+
+const client = new Client({
+  apiKey: process.env.PARAGRAPH_API_KEY!,
+});
+
+const pages = await client.pages.list({
+  limit: 20,
+  include_content: false,
+  sort: "-updated_at",
+});
+
+const created = await client.pages.create({
+  title: "Pricing",
+  language: "en",
+  content: [
+    {
+      type: "paragraph",
+      content: [{ type: "text", text: "Pricing" }],
+    },
+  ],
+});
+
+console.log(pages.meta.total_items);
+console.log(created.page.id);
+```
+
+## Runtime Notes
+
+- The default API base URL is `https://api.paragraphcms.com/v1`.
+- If you pass `baseUrl: "https://api.paragraphcms.com"`, the client automatically normalizes it to `https://api.paragraphcms.com/v1`.
+- The client uses `x-api-key` authentication by default.
+- Field names in request and response payloads intentionally mirror the HTTP API. That means body/query keys stay in `snake_case`.
+
+## Rate Limiting
+
+Paragraph CMS v1 is rate-limited to `5 req/s`. Each `Client` instance contains an internal queue that spaces request starts so the instance does not exceed that budget by default.
+
+Important details:
+
+- The limiter is per client instance, not global across all containers, lambdas, or workers.
+- If your app creates many `Client` instances, each instance will maintain its own queue.
+- The safest pattern is to reuse one shared `Client` instance per process or isolate when possible.
+
+You can override the per-instance limit if you need a lower ceiling:
+
+```ts
+const client = new Client({
+  apiKey: process.env.PARAGRAPH_API_KEY!,
+  maxRequestsPerSecond: 3,
+});
+```
+
+## Configuration
+
+```ts
+type ClientOptions = {
+  apiKey: string;
+  baseUrl?: string;
+  fetch?: typeof globalThis.fetch;
+  headers?: HeadersInit;
+  timeoutMs?: number;
+  maxRequestsPerSecond?: number;
+};
+```
+
+### `apiKey`
+
+Required. Paragraph CMS organization API key.
+
+### `baseUrl`
+
+Optional. Defaults to `https://api.paragraphcms.com/v1`.
+
+Examples:
+
+- `https://api.paragraphcms.com/v1`
+- `https://api.paragraphcms.com`
+- `http://localhost:3001/v1`
+
+### `fetch`
+
+Optional custom fetch implementation. Useful in tests or custom runtimes.
+
+### `headers`
+
+Optional default headers added to every request.
+
+### `timeoutMs`
+
+Optional default request timeout in milliseconds. Per-call options can override it.
+
+### `maxRequestsPerSecond`
+
+Optional per-client limiter ceiling. Defaults to `5`.
+
+## Per-Request Options
+
+Every SDK method accepts an optional last argument:
+
+```ts
+type RequestOptions = {
+  signal?: AbortSignal;
+  headers?: HeadersInit;
+  timeoutMs?: number;
+};
+```
+
+Example:
+
+```ts
+const controller = new AbortController();
+
+const page = await client.pages.get("page-id", undefined, {
+  signal: controller.signal,
+  timeoutMs: 10_000,
+});
+```
+
+## Error Handling
+
+The client throws `ParagraphApiError` for non-2xx API responses and `ParagraphClientError` for local runtime/configuration problems.
+
+```ts
+import { Client, ParagraphApiError } from "@paragraphcms/client";
+
+const client = new Client({
+  apiKey: process.env.PARAGRAPH_API_KEY!,
+});
+
+try {
+  await client.pages.get("missing-id");
+} catch (error) {
+  if (error instanceof ParagraphApiError) {
+    console.error(error.status);
+    console.error(error.code);
+    console.error(error.message);
+    console.error(error.details);
+  }
+}
+```
+
+## Return Shapes
+
+- Single-resource endpoints return the unwrapped `data` payload.
+- Paginated endpoints return `{ data, meta }`.
+- `locales.list()` returns a plain `Locale[]` because the API endpoint itself is not paginated.
+
+## API Surface
+
+### Root
+
+```ts
+client.getInfo()
+```
+
+Returns the public `/v1` info payload:
+
+```ts
+{
+  version: "v1",
+  openapi_url: "/v1/openapi.json",
+  authentication: {
+    type: "api_key",
+    supported_headers: ["x-api-key", "authorization"],
+    authorization_format: "Bearer <api-key>",
+  },
+  resources: [...]
+}
+```
+
+### Pages
+
+```ts
+client.pages.list(query?, options?)
+client.pages.create(body?, options?)
+client.pages.get(pageId, query?, options?)
+client.pages.update(pageId, body, options?)
+client.pages.delete(pageId, options?)
+client.pages.restore(pageId, options?)
+client.pages.permanentlyDelete(pageId, options?)
+client.pages.duplicate(pageId, options?)
+client.pages.createTranslation(pageId, body, options?)
+```
+
+Supported `sort` fields for `pages.list()`:
+
+- `title`
+- `language`
+- `created_at`
+- `updated_at`
+- `published_at`
+
+Notes:
+
+- `label_id` is passed as `string[]` in the SDK and serialized to the API CSV format automatically.
+- `content` is present in page list results only when `include_content: true`.
+- Page responses should be treated as Tiptap JSON arrays. `content_format` is no longer required in the response shape.
+
+### Collections
+
+```ts
+client.collections.list(query?, options?)
+client.collections.create(body, options?)
+client.collections.get(collectionId, options?)
+client.collections.update(collectionId, body, options?)
+client.collections.delete(collectionId, options?)
+```
+
+Supported `sort` fields for `collections.list()`:
+
+- `name`
+- `page_count`
+- `last_modified_at`
+
+### Media
+
+```ts
+client.media.list(query?, options?)
+client.media.upload(body, options?)
+client.media.get(mediaId, options?)
+client.media.update(mediaId, body, options?)
+client.media.delete(mediaId, options?)
+```
+
+Supported `sort` fields for `media.list()`:
+
+- `file_name`
+- `size`
+- `created_at`
+- `updated_at`
+
+`media.upload()` accepts:
+
+- `File`
+- `Blob`
+- `ArrayBuffer`
+- Typed arrays like `Uint8Array`
+- Node.js `Buffer`
+
+Example:
+
+```ts
+const file = new File([imageBytes], "hero.png", {
+  type: "image/png",
+});
+
+const upload = await client.media.upload({
+  file,
+  page_id: "page-id",
+  alt: "Homepage hero",
+});
+```
+
+If you upload from a raw `Buffer`, `Uint8Array`, or `ArrayBuffer`, you can also pass `file_name` and `content_type`:
+
+```ts
+await client.media.upload({
+  file: imageBuffer,
+  file_name: "hero.png",
+  content_type: "image/png",
+  page_id: "page-id",
+});
+```
+
+### Members, Authors, Reviewers
+
+```ts
+client.members.list(query?, options?)
+client.authors.list(query?, options?)
+client.reviewers.list(query?, options?)
+```
+
+Supported `sort` fields:
+
+- `name`
+- `email`
+- `created_at`
+
+`authors` and `reviewers` are aliases of the member listing endpoints exposed by the API.
+
+### Statuses
+
+```ts
+client.statuses.list(query?, options?)
+client.statuses.create(body, options?)
+client.statuses.get(statusId, options?)
+client.statuses.update(statusId, body, options?)
+client.statuses.reorder(body, options?)
+client.statuses.delete(statusId, options?)
+```
+
+Supported `sort` fields for `statuses.list()`:
+
+- `type`
+- `order`
+- `name`
+- `created_at`
+
+### Labels
+
+```ts
+client.labels.list(query?, options?)
+client.labels.create(body, options?)
+client.labels.get(labelId, options?)
+client.labels.update(labelId, body, options?)
+client.labels.reorder(body, options?)
+client.labels.delete(labelId, options?)
+```
+
+Supported `sort` fields for `labels.list()`:
+
+- `order`
+- `name`
+- `created_at`
+
+### Data Models
+
+```ts
+client.dataModels.list(query?, options?)
+client.dataModels.create(body, options?)
+client.dataModels.get(dataModelId, options?)
+client.dataModels.update(dataModelId, body, options?)
+client.dataModels.delete(dataModelId, options?)
+```
+
+Supported `sort` fields for `dataModels.list()`:
+
+- `name`
+- `created_at`
+- `updated_at`
+
+### Locales
+
+```ts
+client.locales.list(options?)
+client.locales.create(body, options?)
+client.locales.delete(code, options?)
+```
+
+### AI
+
+```ts
+client.ai.generateMetaName(body, options?)
+client.ai.generateMetaDescription(body, options?)
+client.ai.generateContent(body, options?)
+```
+
+## End-to-End Examples
+
+### Create a page and upload its hero image
+
+```ts
+const pageResult = await client.pages.create({
+  title: "About",
+  language: "en",
+  content: [
+    {
+      type: "paragraph",
+      content: [{ type: "text", text: "About" }],
+    },
+  ],
+});
+
+await client.media.upload({
+  file: heroBytes,
+  file_name: "about-hero.png",
+  content_type: "image/png",
+  page_id: pageResult.page.id,
+  alt: "About page hero image",
+});
+```
+
+### Create a translated page variant
+
+```ts
+await client.pages.createTranslation("page-id", {
+  language: "de",
+  mode: "translate",
+  model: "openai/gpt-5.4",
+});
+```
+
+### Generate SEO fields with AI
+
+```ts
+const generatedMeta = await client.ai.generateMetaDescription({
+  model: "openai/gpt-5.4",
+  title: "Platform overview",
+  content: [],
+});
+
+console.log(generatedMeta.meta_description);
+```
+
+## Exported Types
+
+The package exports the `Client` class, both error classes, and the main request/response/domain types used by the SDK, including:
+
+- `ClientOptions`
+- `RequestOptions`
+- `ListResponse`
+- `PaginationMeta`
+- `Page`
+- `PageSummary`
+- `Collection`
+- `Media`
+- `MediaDetail`
+- `Status`
+- `Label`
+- `DataModel`
+- `Locale`
+- `Member`
+- `CreatePageRequest`
+- `UpdatePageRequest`
+- `UploadMediaRequest`
+- `GenerateContentRequest`
+
+## Testing
+
+The repository contains two test layers:
+
+- Unit tests for request serialization, multipart uploads, error handling, and rate limiting.
+- Live integration tests that create, update, fetch, reorder, delete, and clean up real resources against the Paragraph API.
+
+Commands:
+
+```bash
+npm test
+npm run test:unit
+npm run test:integration
+```
+
+Environment variables for integration tests:
+
+- `PARAGRAPH_API_KEY` required to run live API tests.
+- `PARAGRAPH_API_BASE_URL` optional override for local/staging API targets.
+- `PARAGRAPH_AI_MODEL` optional model id for AI endpoint tests. When omitted, AI integration tests are skipped.
+
+The integration suite is self-contained and generates its own resources, so it does not rely on any existing content in the target organization.
+
+## Requirements
+
+- Node.js `18+` for direct Node usage.
+- A runtime with standard Fetch API primitives for edge/serverless usage.
+
+## License
+
+ISC

package/dist/client.d.ts

@@ -0,0 +1,82 @@
+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";
+export declare class Client {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly defaultHeaders;
+    private readonly timeoutMs?;
+    private readonly limiter;
+    readonly pages: {
+        list: (query?: PageListQuery, options?: RequestOptions) => Promise<ListResponse<PageSummary>>;
+        create: (body?: CreatePageRequest, options?: RequestOptions) => Promise<PageMutationResult>;
+        get: (pageId: string, query?: GetPageQuery, options?: RequestOptions) => Promise<Page>;
+        update: (pageId: string, body: UpdatePageRequest, options?: RequestOptions) => Promise<PageMutationResult>;
+        delete: (pageId: string, options?: RequestOptions) => Promise<DeleteResult>;
+        restore: (pageId: string, options?: RequestOptions) => Promise<PageRestoreResult>;
+        permanentlyDelete: (pageId: string, options?: RequestOptions) => Promise<PermanentDeleteResult>;
+        duplicate: (pageId: string, options?: RequestOptions) => Promise<PageMutationResult>;
+        createTranslation: (pageId: string, body: CreatePageTranslationRequest, options?: RequestOptions) => Promise<PageMutationResult>;
+    };
+    readonly collections: {
+        list: (query?: CollectionListQuery, options?: RequestOptions) => Promise<ListResponse<Collection>>;
+        create: (body: CreateCollectionRequest, options?: RequestOptions) => Promise<CollectionMutationResult>;
+        get: (collectionId: string, options?: RequestOptions) => Promise<Collection>;
+        update: (collectionId: string, body: UpdateCollectionRequest, options?: RequestOptions) => Promise<CollectionMutationResult>;
+        delete: (collectionId: string, options?: RequestOptions) => Promise<DeleteResult>;
+    };
+    readonly media: {
+        list: (query?: MediaListQuery, options?: RequestOptions) => Promise<ListResponse<Media>>;
+        upload: (body: UploadMediaRequest, options?: RequestOptions) => Promise<MediaUploadResult>;
+        get: (mediaId: string, options?: RequestOptions) => Promise<MediaDetail>;
+        update: (mediaId: string, body: UpdateMediaRequest, options?: RequestOptions) => Promise<MediaMutationResult>;
+        delete: (mediaId: string, options?: RequestOptions) => Promise<MediaDeleteResult>;
+    };
+    readonly members: {
+        list: (query?: MemberListQuery, options?: RequestOptions) => Promise<ListResponse<Member>>;
+    };
+    readonly authors: {
+        list: (query?: MemberListQuery, options?: RequestOptions) => Promise<ListResponse<Member>>;
+    };
+    readonly reviewers: {
+        list: (query?: MemberListQuery, options?: RequestOptions) => Promise<ListResponse<Member>>;
+    };
+    readonly statuses: {
+        list: (query?: StatusListQuery, options?: RequestOptions) => Promise<ListResponse<Status>>;
+        create: (body: CreateStatusRequest, options?: RequestOptions) => Promise<StatusMutationResult>;
+        get: (statusId: string, options?: RequestOptions) => Promise<Status>;
+        update: (statusId: string, body: UpdateStatusRequest, options?: RequestOptions) => Promise<StatusMutationResult>;
+        reorder: (body: ReorderStatusesRequest, options?: RequestOptions) => Promise<ReorderResult>;
+        delete: (statusId: string, options?: RequestOptions) => Promise<DeleteResult>;
+    };
+    readonly labels: {
+        list: (query?: LabelListQuery, options?: RequestOptions) => Promise<ListResponse<Label>>;
+        create: (body: CreateLabelRequest, options?: RequestOptions) => Promise<LabelMutationResult>;
+        get: (labelId: string, options?: RequestOptions) => Promise<Label>;
+        update: (labelId: string, body: UpdateLabelRequest, options?: RequestOptions) => Promise<LabelMutationResult>;
+        reorder: (body: ReorderLabelsRequest, options?: RequestOptions) => Promise<ReorderResult>;
+        delete: (labelId: string, options?: RequestOptions) => Promise<DeleteResult>;
+    };
+    readonly dataModels: {
+        list: (query?: DataModelListQuery, options?: RequestOptions) => Promise<ListResponse<DataModel>>;
+        create: (body: CreateDataModelRequest, options?: RequestOptions) => Promise<DataModelMutationResult>;
+        get: (dataModelId: string, options?: RequestOptions) => Promise<DataModel>;
+        update: (dataModelId: string, body: UpdateDataModelRequest, options?: RequestOptions) => Promise<DataModelMutationResult>;
+        delete: (dataModelId: string, options?: RequestOptions) => Promise<DeleteResult>;
+    };
+    readonly locales: {
+        list: (options?: RequestOptions) => Promise<Locale[]>;
+        create: (body: CreateLocaleRequest, options?: RequestOptions) => Promise<LocaleMutationResult>;
+        delete: (code: string, options?: RequestOptions) => Promise<DeleteByCodeResult>;
+    };
+    readonly ai: {
+        generateMetaName: (body: GenerateMetaRequest, options?: RequestOptions) => Promise<AiMetaNameResult>;
+        generateMetaDescription: (body: GenerateMetaRequest, options?: RequestOptions) => Promise<AiMetaDescriptionResult>;
+        generateContent: (body: GenerateContentRequest, options?: RequestOptions) => Promise<AiContentResult>;
+    };
+    constructor(options: ClientOptions);
+    getInfo(options?: RequestOptions): Promise<ApiInfo>;
+    private requestData;
+    private requestList;
+    private requestJson;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}