@paragraphcms/client 1.5.0 → 2.0.0

package/dist/client.js

@@ -1,8 +1,21 @@
 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",
+]);
+const SPECIAL_API_KEY_MAP = {
+    labelIds: "label_id",
+};
+const SPECIAL_SDK_KEY_MAP = {
+    label_id: "labelIds",
+};
 function resolveFetchImplementation(customFetch) {
     const fetchImpl = customFetch ?? globalThis.fetch;
     if (typeof fetchImpl !== "function") {
@@ -13,26 +26,59 @@ function resolveFetchImplementation(customFetch) {
     }
     return fetchImpl;
 }
-function normalizeBaseUrl(baseUrl) {
-    const trimmed = baseUrl.trim().replace(/\/+$/, "");
-    if (!trimmed) {
-        throw new ParagraphClientError("`baseUrl` cannot be empty.");
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
     }
-    const url = new URL(trimmed);
-    const normalizedPath = url.pathname.replace(/\/+$/, "");
-    if (normalizedPath === "" || normalizedPath === "/") {
-        url.pathname = "/v1";
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function toCamelCaseKey(key) {
+    const mappedKey = SPECIAL_SDK_KEY_MAP[key];
+    if (mappedKey) {
+        return mappedKey;
     }
-    else {
-        url.pathname = normalizedPath;
+    return key.replace(/_([a-z])/g, (_match, letter) => letter.toUpperCase());
+}
+function toSnakeCaseKey(key) {
+    const mappedKey = SPECIAL_API_KEY_MAP[key];
+    if (mappedKey) {
+        return mappedKey;
     }
-    return url.toString().replace(/\/+$/, "");
+    return key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
 }
-function buildUrl(baseUrl, path, query) {
+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 transformed;
+}
+function toApiPayload(value) {
+    return transformKeysDeep(value, toSnakeCaseKey);
+}
+function toSdkPayload(value) {
+    return transformKeysDeep(value, toCamelCaseKey);
+}
+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;
             }
@@ -123,9 +169,67 @@ function createRequestSignal(signal, timeoutMs) {
         didTimeout: () => timedOut,
     };
 }
+function waitForDelay(delayMs, signal) {
+    if (delayMs <= 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        let timeoutId;
+        const cleanup = () => {
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+            if (signal) {
+                signal.removeEventListener("abort", onAbort);
+            }
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(signal?.reason ??
+                new DOMException("The operation was aborted.", "AbortError"));
+        };
+        if (signal) {
+            if (signal.aborted) {
+                onAbort();
+                return;
+            }
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+        timeoutId = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, delayMs);
+    });
+}
 function isAbortError(error) {
     return (error instanceof DOMException && error.name === "AbortError");
 }
+function resolveMaxRateLimitRetries(value, fallback = DEFAULT_RATE_LIMIT_RETRIES) {
+    const resolved = value ?? fallback;
+    if (!Number.isInteger(resolved) ||
+        resolved < 0) {
+        throw new ParagraphClientError("`maxRateLimitRetries` must be a non-negative integer.");
+    }
+    return resolved;
+}
+function parseRetryAfterMs(headerValue) {
+    if (!headerValue) {
+        return undefined;
+    }
+    const seconds = Number(headerValue);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.ceil(seconds * 1000);
+    }
+    const retryAt = Date.parse(headerValue);
+    if (Number.isNaN(retryAt)) {
+        return undefined;
+    }
+    return Math.max(0, retryAt - Date.now());
+}
+function resolveRateLimitRetryDelayMs(headers, retryCount) {
+    return (parseRetryAfterMs(headers.get("retry-after")) ??
+        DEFAULT_RATE_LIMIT_RETRY_DELAY_MS * 2 ** retryCount);
+}
 function toBlobPart(file) {
     if (typeof File !== "undefined" && file instanceof File) {
         return {
@@ -155,11 +259,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
@@ -205,7 +309,7 @@ function createUploadFormData(input) {
     else {
         formData.append("file", filePart.value);
     }
-    formData.append("page_id", input.page_id);
+    formData.append("page_id", input.pageId);
     if (input.alt !== undefined && input.alt !== null) {
         formData.append("alt", input.alt);
     }
@@ -213,10 +317,10 @@ function createUploadFormData(input) {
 }
 export class Client {
     apiKey;
-    baseUrl;
     fetchImpl;
     defaultHeaders;
     timeoutMs;
+    maxRateLimitRetries;
     limiter;
     pages = {
         list: (query, options) => this.listPages(query, options),
@@ -251,6 +355,7 @@ export class Client {
         }),
     };
     page = {
+        get: (pageId, query, options) => this.pages.get(pageId, query, options),
         getBySlug: (slug, options) => this.pages.getBySlug(slug, options),
     };
     collections = {
@@ -426,14 +531,19 @@ 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;
+        this.maxRateLimitRetries = resolveMaxRateLimitRetries(options.maxRateLimitRetries);
         this.limiter = new RequestRateLimiter(options.maxRequestsPerSecond ?? DEFAULT_REQUESTS_PER_SECOND);
     }
     getInfo(options) {
@@ -447,13 +557,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,
@@ -471,17 +581,17 @@ 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) {
         return {
             ...(query ?? {}),
-            include_content: query?.include_content ?? false,
+            includeContent: query?.includeContent ?? false,
         };
     }
     requestData(method, path, config) {
@@ -514,7 +624,7 @@ export class Client {
             if (match) {
                 return match;
             }
-            if (!response.meta.has_next_page) {
+            if (!response.meta.hasNextPage) {
                 break;
             }
             page += 1;
@@ -550,71 +660,85 @@ 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);
-        return this.limiter.schedule(async () => {
-            const headers = new Headers(this.defaultHeaders);
-            const timeoutMs = config?.options?.timeoutMs ?? this.timeoutMs;
-            headers.set("accept", "application/json");
-            if (!headers.has("x-api-key") &&
-                !headers.has("authorization")) {
-                headers.set("x-api-key", this.apiKey);
-            }
-            let body;
-            if (config?.formData) {
-                headers.delete("content-type");
-                body = config.formData;
-            }
-            else if (config?.body !== undefined) {
-                if (!headers.has("content-type")) {
-                    headers.set("content-type", "application/json");
-                }
-                body = JSON.stringify(config.body);
-            }
-            const optionHeaders = new Headers(config?.options?.headers);
-            for (const [key, value] of optionHeaders.entries()) {
-                headers.set(key, value);
-            }
-            if (config?.formData) {
-                headers.delete("content-type");
+        const headers = new Headers(this.defaultHeaders);
+        const timeoutMs = config?.options?.timeoutMs ?? this.timeoutMs;
+        const maxRateLimitRetries = resolveMaxRateLimitRetries(config?.options?.maxRateLimitRetries, this.maxRateLimitRetries);
+        headers.set("accept", "application/json");
+        if (!headers.has("x-api-key") &&
+            !headers.has("authorization")) {
+            headers.set("x-api-key", this.apiKey);
+        }
+        let body;
+        if (config?.formData) {
+            headers.delete("content-type");
+            body = config.formData;
+        }
+        else if (config?.body !== undefined) {
+            if (!headers.has("content-type")) {
+                headers.set("content-type", "application/json");
             }
-            const requestSignal = createRequestSignal(config?.options?.signal, timeoutMs);
+            body = JSON.stringify(toApiPayload(config.body));
+        }
+        const optionHeaders = new Headers(config?.options?.headers);
+        for (const [key, value] of optionHeaders.entries()) {
+            headers.set(key, value);
+        }
+        if (config?.formData) {
+            headers.delete("content-type");
+        }
+        const requestSignal = createRequestSignal(config?.options?.signal, timeoutMs);
+        return (async () => {
+            let retryCount = 0;
             try {
                 const fetchImpl = this.fetchImpl;
-                const response = await fetchImpl(url, {
-                    method,
-                    headers,
-                    body,
-                    signal: requestSignal.signal,
-                });
-                const payload = await parseResponse(response);
-                if (!response.ok) {
-                    if (isApiErrorPayload(payload)) {
-                        throw new ParagraphApiError({
+                while (true) {
+                    const response = await this.limiter.schedule(() => fetchImpl(url, {
+                        method,
+                        headers,
+                        body,
+                        signal: requestSignal.signal,
+                    }));
+                    const payload = await parseResponse(response);
+                    if (response.ok) {
+                        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,
-                            headers: new Headers(response.headers),
+                            details: toSdkPayload(payload.error.details),
+                            headers: responseHeaders,
+                            request,
+                        })
+                        : new ParagraphApiError({
+                            status: response.status,
+                            code: response.status === 401
+                                ? "unauthorized"
+                                : "request_failed",
+                            message: typeof payload === "string" && payload.length > 0
+                                ? payload
+                                : response.statusText || "Request failed.",
+                            headers: responseHeaders,
                             request,
-                            body: payload,
                         });
+                    if (response.status === 429 &&
+                        retryCount < maxRateLimitRetries) {
+                        const retryDelayMs = resolveRateLimitRetryDelayMs(responseHeaders, retryCount);
+                        retryCount += 1;
+                        await waitForDelay(retryDelayMs, requestSignal.signal);
+                        continue;
                     }
-                    throw new ParagraphApiError({
-                        status: response.status,
-                        code: response.status === 401 ? "unauthorized" : "request_failed",
-                        message: typeof payload === "string" && payload.length > 0
-                            ? payload
-                            : response.statusText || "Request failed.",
-                        headers: new Headers(response.headers),
-                        request,
-                    });
+                    throw apiError;
                 }
-                return payload;
             }
             catch (error) {
                 if (error instanceof ParagraphApiError ||
@@ -627,7 +751,8 @@ export class Client {
                         cause: error,
                     });
                 }
-                if (isAbortError(error)) {
+                if (isAbortError(error) ||
+                    config?.options?.signal?.aborted) {
                     throw error;
                 }
                 throw new ParagraphClientError("Request failed.", {
@@ -638,6 +763,6 @@ export class Client {
             finally {
                 requestSignal.cleanup();
             }
-        });
+        })();
     }
 }