@paragraphcms/client 1.6.0 → 2.1.0

package/dist/client.js

@@ -1,10 +1,15 @@
 import { ParagraphApiError, ParagraphClientError, } from "./errors.js";
 import { RequestRateLimiter } from "./rate-limiter.js";
-const DEFAULT_BASE_URL = "https://api.paragraphcms.com/v1";
+const API_BASE_URL = "https://api.paragraphcms.com/v1";
 const DEFAULT_REQUESTS_PER_SECOND = 5;
 const DEFAULT_RATE_LIMIT_RETRIES = 2;
 const DEFAULT_RATE_LIMIT_RETRY_DELAY_MS = 1000;
 const LOOKUP_PAGE_SIZE = 100;
+const PRESERVED_TRANSFORM_KEYS = new Set([
+    "content",
+    "editorNode",
+    "fields",
+]);
 function resolveFetchImplementation(customFetch) {
     const fetchImpl = customFetch ?? globalThis.fetch;
     if (typeof fetchImpl !== "function") {
@@ -15,26 +20,48 @@ function resolveFetchImplementation(customFetch) {
     }
     return fetchImpl;
 }
-function normalizeBaseUrl(baseUrl) {
-    const trimmed = baseUrl.trim().replace(/\/+$/, "");
-    if (!trimmed) {
-        throw new ParagraphClientError("`baseUrl` cannot be empty.");
-    }
-    const url = new URL(trimmed);
-    const normalizedPath = url.pathname.replace(/\/+$/, "");
-    if (normalizedPath === "" || normalizedPath === "/") {
-        url.pathname = "/v1";
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
     }
-    else {
-        url.pathname = normalizedPath;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function toCamelCaseKey(key) {
+    return key.replace(/_([a-z])/g, (_match, letter) => letter.toUpperCase());
+}
+function transformKeysDeep(value, transformKey) {
+    if (Array.isArray(value)) {
+        return value.map((item) => transformKeysDeep(item, transformKey));
+    }
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    const transformed = {};
+    for (const [key, nestedValue] of Object.entries(value)) {
+        const transformedKey = transformKey(key);
+        if (PRESERVED_TRANSFORM_KEYS.has(transformedKey)) {
+            transformed[transformedKey] = nestedValue;
+            continue;
+        }
+        transformed[transformedKey] = transformKeysDeep(nestedValue, transformKey);
     }
-    return url.toString().replace(/\/+$/, "");
+    return transformed;
+}
+function toApiPayload(value) {
+    return value;
+}
+function toSdkPayload(value) {
+    return transformKeysDeep(value, toCamelCaseKey);
 }
-function buildUrl(baseUrl, path, query) {
+function buildUrl(path, query) {
     const normalizedPath = path ? `/${path.replace(/^\/+/, "")}` : "";
-    const url = new URL(`${baseUrl}${normalizedPath}`);
-    if (query) {
-        for (const [key, rawValue] of Object.entries(query)) {
+    const url = new URL(`${API_BASE_URL}${normalizedPath}`);
+    const apiQuery = query
+        ? toApiPayload(query)
+        : undefined;
+    if (apiQuery) {
+        for (const [key, rawValue] of Object.entries(apiQuery)) {
             if (rawValue === undefined || rawValue === null) {
                 continue;
             }
@@ -215,11 +242,11 @@ function toBlobPart(file) {
 }
 function buildUploadFilePart(input) {
     const source = toBlobPart(input.file);
-    const fileName = input.file_name ??
+    const fileName = input.fileName ??
         (typeof File !== "undefined" && input.file instanceof File
             ? input.file.name
             : "upload.bin");
-    const contentType = input.content_type ??
+    const contentType = input.contentType ??
         ("type" in source.value &&
             typeof source.value.type === "string" &&
             source.value.type.length > 0
@@ -265,7 +292,7 @@ function createUploadFormData(input) {
     else {
         formData.append("file", filePart.value);
     }
-    formData.append("page_id", input.page_id);
+    formData.append("pageId", input.pageId);
     if (input.alt !== undefined && input.alt !== null) {
         formData.append("alt", input.alt);
     }
@@ -273,7 +300,6 @@ function createUploadFormData(input) {
 }
 export class Client {
     apiKey;
-    baseUrl;
     fetchImpl;
     defaultHeaders;
     timeoutMs;
@@ -312,6 +338,7 @@ export class Client {
         }),
     };
     page = {
+        list: (query, options) => this.pages.list(query, options),
         get: (pageId, query, options) => this.pages.get(pageId, query, options),
         getBySlug: (slug, options) => this.pages.getBySlug(slug, options),
     };
@@ -361,7 +388,7 @@ export class Client {
             options,
         }),
         get: (memberId, options) => this.findListItem("/members", (member) => member.id === memberId, options, {
-            code: "member_not_found",
+            code: "memberNotFound",
             message: "Member not found.",
             details: { memberId },
         }),
@@ -372,7 +399,7 @@ export class Client {
             options,
         }),
         get: (authorId, options) => this.findListItem("/authors", (author) => author.id === authorId, options, {
-            code: "author_not_found",
+            code: "authorNotFound",
             message: "Author not found.",
             details: { authorId },
         }),
@@ -383,7 +410,7 @@ export class Client {
             options,
         }),
         get: (reviewerId, options) => this.findListItem("/reviewers", (reviewer) => reviewer.id === reviewerId, options, {
-            code: "reviewer_not_found",
+            code: "reviewerNotFound",
             message: "Reviewer not found.",
             details: { reviewerId },
         }),
@@ -461,7 +488,7 @@ export class Client {
             options,
         }),
         get: (code, options) => this.findArrayItem("/locales", (locale) => locale.code === code, options, {
-            code: "locale_not_found",
+            code: "localeNotFound",
             message: "Locale not found.",
             details: { code },
         }),
@@ -488,11 +515,15 @@ export class Client {
         }),
     };
     constructor(options) {
-        if (!options.apiKey.trim()) {
+        if ("baseUrl" in options ||
+            "apiUrl" in options) {
+            throw new ParagraphClientError("`baseUrl` and `apiUrl` are not supported. The client always uses the official Paragraph CMS API endpoint.");
+        }
+        if (typeof options.apiKey !== "string" ||
+            !options.apiKey.trim()) {
             throw new ParagraphClientError("`apiKey` is required.");
         }
         this.apiKey = options.apiKey.trim();
-        this.baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
         this.fetchImpl = resolveFetchImplementation(options.fetch);
         this.defaultHeaders = new Headers(options.headers);
         this.timeoutMs = options.timeoutMs;
@@ -510,13 +541,13 @@ export class Client {
         });
         if (pageListQuery.limit !== undefined ||
             pageListQuery.page !== undefined ||
-            !response.meta.has_next_page) {
+            !response.meta.hasNextPage) {
             return response;
         }
         const items = [...response.data];
         let nextPage = response.meta.page + 1;
         let lastMeta = response.meta;
-        while (lastMeta.has_next_page) {
+        while (lastMeta.hasNextPage) {
             const nextResponse = await this.requestList("GET", "/pages", {
                 query: {
                     ...pageListQuery,
@@ -534,25 +565,19 @@ export class Client {
             meta: {
                 page: 1,
                 limit: items.length,
-                total_items: items.length,
-                total_pages: items.length > 0 ? 1 : 0,
-                has_next_page: false,
-                has_prev_page: false,
+                totalItems: items.length,
+                totalPages: items.length > 0 ? 1 : 0,
+                hasNextPage: false,
+                hasPrevPage: false,
             },
         };
     }
     createPageListQuery(query) {
-        const collection = query?.collection_id ?? query?.collection;
-        if (query?.collection !== undefined &&
-            query?.collection_id !== undefined &&
-            query.collection !== query.collection_id) {
-            throw new ParagraphClientError("`collection` and `collection_id` must match when both are provided.");
-        }
+        const { requiredSlug, ...restQuery } = query ?? {};
         return {
-            ...(query ?? {}),
-            collection: undefined,
-            collection_id: collection,
-            include_content: query?.include_content ?? false,
+            ...restQuery,
+            includeContent: restQuery.includeContent ?? false,
+            ...(requiredSlug === true ? { requiredSlug: true } : {}),
         };
     }
     requestData(method, path, config) {
@@ -564,7 +589,7 @@ export class Client {
     async getPageBySlug(slug, options) {
         const query = this.createPageListQuery({ slug });
         const page = await this.findListItem("/pages", (item) => item.slug === slug, options, {
-            code: "page_not_found",
+            code: "pageNotFound",
             message: "Page not found.",
             details: { slug },
         }, query);
@@ -585,7 +610,7 @@ export class Client {
             if (match) {
                 return match;
             }
-            if (!response.meta.has_next_page) {
+            if (!response.meta.hasNextPage) {
                 break;
             }
             page += 1;
@@ -621,11 +646,11 @@ export class Client {
             code: config.code,
             message: config.message,
             details: config.details,
-            request: createRequestDescriptor(method, buildUrl(this.baseUrl, path, config.query)),
+            request: createRequestDescriptor(method, buildUrl(path, config.query)),
         });
     }
     requestJson(method, path, config) {
-        const url = buildUrl(this.baseUrl, path, config?.query);
+        const url = buildUrl(path, config?.query);
         const request = createRequestDescriptor(method, url);
         const headers = new Headers(this.defaultHeaders);
         const timeoutMs = config?.options?.timeoutMs ?? this.timeoutMs;
@@ -644,7 +669,7 @@ export class Client {
             if (!headers.has("content-type")) {
                 headers.set("content-type", "application/json");
             }
-            body = JSON.stringify(config.body);
+            body = JSON.stringify(toApiPayload(config.body));
         }
         const optionHeaders = new Headers(config?.options?.headers);
         for (const [key, value] of optionHeaders.entries()) {
@@ -667,24 +692,24 @@ export class Client {
                     }));
                     const payload = await parseResponse(response);
                     if (response.ok) {
-                        return payload;
+                        return toSdkPayload(payload);
                     }
                     const responseHeaders = new Headers(response.headers);
                     const apiError = isApiErrorPayload(payload)
                         ? new ParagraphApiError({
+                            body: toSdkPayload(payload),
                             status: response.status,
                             code: payload.error.code,
                             message: payload.error.message,
-                            details: payload.error.details,
+                            details: toSdkPayload(payload.error.details),
                             headers: responseHeaders,
                             request,
-                            body: payload,
                         })
                         : new ParagraphApiError({
                             status: response.status,
                             code: response.status === 401
                                 ? "unauthorized"
-                                : "request_failed",
+                                : "requestFailed",
                             message: typeof payload === "string" && payload.length > 0
                                 ? payload
                                 : response.statusText || "Request failed.",

package/dist/types.d.ts

@@ -10,10 +10,10 @@ export type Uploadable = File | Blob | ArrayBuffer | ArrayBufferView;
 export interface PaginationMeta {
     page: number;
     limit: number;
-    total_items: number;
-    total_pages: number;
-    has_next_page: boolean;
-    has_prev_page: boolean;
+    totalItems: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
 }
 export interface ListResponse<T> {
     data: T[];
@@ -21,11 +21,11 @@ export interface ListResponse<T> {
 }
 export interface ApiInfo {
     version: string;
-    openapi_url: string;
+    openapiUrl: string;
     authentication: {
-        type: "api_key";
-        supported_headers: ["x-api-key", "authorization"];
-        authorization_format: "Bearer <api-key>";
+        type: "apiKey";
+        supportedHeaders: ["x-api-key", "authorization"];
+        authorizationFormat: "Bearer <api-key>";
     };
     resources: string[];
 }
@@ -49,7 +49,6 @@ export interface RequestOptions {
 }
 export interface ClientOptions {
     apiKey: string;
-    baseUrl?: string;
     fetch?: typeof globalThis.fetch;
     headers?: HeadersInit;
     timeoutMs?: number;
@@ -64,12 +63,12 @@ export interface ListQuery {
 }
 export interface Member {
     id: string;
-    user_id: string;
+    userId: string;
     role: string;
     name: string | null;
     email: string | null;
-    image_url: string | null;
-    created_at: string | null;
+    imageUrl: string | null;
+    createdAt: string | null;
 }
 export interface Status {
     id: string;
@@ -78,8 +77,8 @@ export interface Status {
     type: StatusType;
     description: string | null;
     order: number;
-    created_at: string | null;
-    updated_at: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
 }
 export interface Label {
     id: string;
@@ -87,8 +86,8 @@ export interface Label {
     color: string;
     description: string | null;
     order: number;
-    created_at: string | null;
-    last_applied_at: string | null;
+    createdAt: string | null;
+    lastAppliedAt: string | null;
 }
 export interface DataModelField {
     id: string;
@@ -104,57 +103,57 @@ export interface DataModelSummary {
 }
 export interface DataModel extends DataModelSummary {
     fields: DataModelField[];
-    created_at: string | null;
-    updated_at: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
 }
 export interface CollectionSummary {
     id: string;
     name: string;
     description: string | null;
-    default_data_model_id: string | null;
-    team_ids: string[];
-    page_count: number;
-    last_modified_at: string | null;
+    defaultDataModelId: string | null;
+    teamIds: string[];
+    pageCount: number;
+    lastModifiedAt: string | null;
 }
 export interface Collection extends CollectionSummary {
-    default_data_model: DataModel | null;
+    defaultDataModel: DataModel | null;
 }
 export interface PageTranslation {
     id: string;
     title: string;
     language: string;
-    deleted_at: string | null;
-    created_at: string | null;
-    updated_at: string | null;
-    is_current: boolean;
+    deletedAt: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+    isCurrent: boolean;
 }
 export interface PageSummary {
     id: string;
     title: string;
     slug: string | null;
     language: string;
-    content_format?: PageContentFormat;
-    hero_url: string | null;
-    collection_id: string | null;
+    contentFormat?: PageContentFormat;
+    heroUrl: string | null;
+    collectionId: string | null;
     collection: Collection | null;
-    translation_group_id: string;
-    data_model_id: string | null;
-    data_model: DataModel | null;
-    status_id: string | null;
+    translationGroupId: string;
+    dataModelId: string | null;
+    dataModel: DataModel | null;
+    statusId: string | null;
     status: Status | null;
-    author_id: string | null;
+    authorId: string | null;
     author: Member | null;
-    reviewer_id: string | null;
+    reviewerId: string | null;
     reviewer: Member | null;
     labels: Label[];
     fields: Record<string, unknown>;
     content?: PageContent;
-    meta_name: string | null;
-    meta_description: string | null;
-    published_at: string | null;
-    deleted_at: string | null;
-    created_at: string | null;
-    updated_at: string | null;
+    metaName: string | null;
+    metaDescription: string | null;
+    publishedAt: string | null;
+    deletedAt: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
 }
 export interface Page extends PageSummary {
     content: PageContent;
@@ -162,30 +161,30 @@ export interface Page extends PageSummary {
 }
 export interface Media {
     id: string;
-    page_id: string | null;
-    file_name: string;
+    pageId: string | null;
+    fileName: string;
     alt: string | null;
-    mime_type: string;
+    mimeType: string;
     size: number;
     width: number | null;
     height: number | null;
     url: string;
-    created_at: string | null;
-    updated_at: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
 }
 export interface MediaReferencePage {
     id: string;
     title: string;
     slug: string | null;
     language: string | null;
-    translation_group_id: string | null;
-    updated_at: string | null;
-    is_unassigned: boolean;
+    translationGroupId: string | null;
+    updatedAt: string | null;
+    isUnassigned: boolean;
 }
 export interface MediaDetail extends Media {
-    reference_page_count: number;
-    last_modified_at: string | null;
-    reference_pages: MediaReferencePage[];
+    referencePageCount: number;
+    lastModifiedAt: string | null;
+    referencePages: MediaReferencePage[];
 }
 export interface Locale {
     id: string;
@@ -206,7 +205,7 @@ export interface CollectionMutationResult {
 export interface MediaUploadResult {
     message: string;
     media: Media;
-    editor_node: EditorNode;
+    editorNode: EditorNode;
 }
 export interface MediaMutationResult {
     message: string;
@@ -215,7 +214,7 @@ export interface MediaMutationResult {
 export interface MediaDeleteResult {
     id: string;
     deleted: boolean;
-    deleted_count: number;
+    deletedCount: number;
     message: string;
 }
 export interface StatusMutationResult {
@@ -228,7 +227,7 @@ export interface LabelMutationResult {
 }
 export interface DataModelMutationResult {
     message: string;
-    data_model: DataModel;
+    dataModel: DataModel;
 }
 export interface LocaleMutationResult {
     message: string;
@@ -240,11 +239,11 @@ export interface LocaleMutationResult {
 }
 export interface AiMetaNameResult {
     message: string;
-    meta_name: string;
+    metaName: string;
 }
 export interface AiMetaDescriptionResult {
     message: string;
-    meta_description: string;
+    metaDescription: string;
 }
 export interface AiContentResult {
     message: string;
@@ -269,7 +268,7 @@ export interface PageRestoreResult {
 }
 export interface PermanentDeleteResult {
     id: string;
-    permanently_deleted: boolean;
+    permanentlyDeleted: boolean;
     message: string;
 }
 export interface ReorderResult {
@@ -277,46 +276,46 @@ export interface ReorderResult {
     message: string;
 }
 export interface PageListQuery extends ListQuery {
-    include_content?: boolean;
-    collection?: string;
+    includeContent?: boolean;
+    collectionId?: string;
     deleted?: DeletedFilter;
-    collection_id?: string;
-    without_collection?: boolean;
-    data_model_id?: string;
-    status_id?: string;
-    status_type?: StatusType;
-    author_id?: string;
-    reviewer_id?: string;
+    withoutCollection?: boolean;
+    dataModelId?: string;
+    statusId?: string;
+    statusType?: StatusType;
+    authorId?: string;
+    reviewerId?: string;
     language?: string;
-    translation_group_id?: string;
+    translationGroupId?: string;
     slug?: string;
-    label_id?: string[];
-    updated_after?: string;
-    updated_before?: string;
-    published_after?: string;
-    published_before?: string;
+    requiredSlug?: boolean;
+    labelIds?: string[];
+    updatedAfter?: string;
+    updatedBefore?: string;
+    publishedAfter?: string;
+    publishedBefore?: string;
     published?: boolean;
 }
 export interface GetPageQuery {
-    include_deleted?: boolean;
+    includeDeleted?: boolean;
 }
 export interface CreatePageRequest {
     title?: string;
-    hero_url?: string | null;
-    collection_id?: string | null;
-    data_model_id?: string | null;
+    heroUrl?: string | null;
+    collectionId?: string | null;
+    dataModelId?: string | null;
     language?: string;
-    status_id?: string | null;
-    author_id?: string | null;
-    reviewer_id?: string | null;
-    published_at?: string | null;
-    content_format?: PageContentFormat;
+    statusId?: string | null;
+    authorId?: string | null;
+    reviewerId?: string | null;
+    publishedAt?: string | null;
+    contentFormat?: PageContentFormat;
     content?: PageContent;
     fields?: Record<string, unknown>;
     slug?: string | null;
-    meta_name?: string | null;
-    meta_description?: string | null;
-    label_ids?: string[];
+    metaName?: string | null;
+    metaDescription?: string | null;
+    labelIds?: string[];
 }
 export type UpdatePageRequest = CreatePageRequest;
 export interface CreatePageTranslationRequest {
@@ -325,28 +324,28 @@ export interface CreatePageTranslationRequest {
     model?: string;
 }
 export interface CollectionListQuery extends ListQuery {
-    default_data_model_id?: string;
+    defaultDataModelId?: string;
 }
 export interface CreateCollectionRequest {
     name: string;
     description?: string | null;
-    default_data_model_id?: string | null;
-    team_ids?: string[];
+    defaultDataModelId?: string | null;
+    teamIds?: string[];
 }
 export type UpdateCollectionRequest = Partial<CreateCollectionRequest>;
 export interface MediaListQuery extends ListQuery {
-    page_id?: string;
-    mime_type?: string;
+    pageId?: string;
+    mimeType?: string;
 }
 export interface UploadMediaRequest {
     file: Uploadable;
-    file_name?: string;
-    content_type?: string;
-    page_id: string;
+    fileName?: string;
+    contentType?: string;
+    pageId: string;
     alt?: string | null;
 }
 export interface UpdateMediaRequest {
-    file_name?: string;
+    fileName?: string;
     alt?: string | null;
 }
 export interface MemberListQuery extends ListQuery {
@@ -364,7 +363,7 @@ export interface CreateStatusRequest {
 export type UpdateStatusRequest = Partial<CreateStatusRequest>;
 export interface ReorderStatusesRequest {
     type: StatusType;
-    status_ids: string[];
+    statusIds: string[];
 }
 export interface CreateLabelRequest {
     name: string;
@@ -375,7 +374,7 @@ export type UpdateLabelRequest = Partial<CreateLabelRequest>;
 export interface LabelListQuery extends ListQuery {
 }
 export interface ReorderLabelsRequest {
-    label_ids: string[];
+    labelIds: string[];
 }
 export interface DataModelListQuery extends ListQuery {
 }