@paragraphcms/client 1.0.0

package/dist/client.js

@@ -0,0 +1,506 @@
+import { ParagraphApiError, ParagraphClientError, } from "./errors.js";
+import { RequestRateLimiter } from "./rate-limiter.js";
+const DEFAULT_BASE_URL = "https://api.paragraphcms.com/v1";
+const DEFAULT_REQUESTS_PER_SECOND = 5;
+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";
+    }
+    else {
+        url.pathname = normalizedPath;
+    }
+    return url.toString().replace(/\/+$/, "");
+}
+function buildUrl(baseUrl, path, query) {
+    const normalizedPath = path ? `/${path.replace(/^\/+/, "")}` : "";
+    const url = new URL(`${baseUrl}${normalizedPath}`);
+    if (query) {
+        for (const [key, rawValue] of Object.entries(query)) {
+            if (rawValue === undefined || rawValue === null) {
+                continue;
+            }
+            if (Array.isArray(rawValue)) {
+                if (rawValue.length === 0) {
+                    continue;
+                }
+                url.searchParams.set(key, rawValue.map((value) => String(value)).join(","));
+                continue;
+            }
+            url.searchParams.set(key, String(rawValue));
+        }
+    }
+    return url;
+}
+function isApiErrorPayload(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const maybeError = value.error;
+    if (typeof maybeError !== "object" || maybeError === null) {
+        return false;
+    }
+    const code = maybeError.code;
+    const message = maybeError.message;
+    return typeof code === "string" && typeof message === "string";
+}
+async function parseResponse(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+        return response.json();
+    }
+    const text = await response.text();
+    if (!text) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function createRequestDescriptor(method, url) {
+    return {
+        method,
+        url: url.toString(),
+    };
+}
+function createRequestSignal(signal, timeoutMs) {
+    if (!signal && (!timeoutMs || timeoutMs <= 0)) {
+        return {
+            signal: undefined,
+            cleanup: () => { },
+            didTimeout: () => false,
+        };
+    }
+    const controller = new AbortController();
+    let timedOut = false;
+    let timeoutId;
+    const onAbort = () => {
+        controller.abort(signal?.reason);
+    };
+    if (signal) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+        }
+        else {
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+    }
+    if (timeoutMs && timeoutMs > 0) {
+        timeoutId = setTimeout(() => {
+            timedOut = true;
+            controller.abort(new Error(`Request timed out after ${timeoutMs}ms.`));
+        }, timeoutMs);
+    }
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+            if (signal) {
+                signal.removeEventListener("abort", onAbort);
+            }
+        },
+        didTimeout: () => timedOut,
+    };
+}
+function isAbortError(error) {
+    return (error instanceof DOMException && error.name === "AbortError");
+}
+function toBlobPart(file) {
+    if (typeof File !== "undefined" && file instanceof File) {
+        return {
+            value: file,
+            fileName: undefined,
+        };
+    }
+    if (file instanceof Blob) {
+        return {
+            value: file,
+            fileName: undefined,
+        };
+    }
+    if (ArrayBuffer.isView(file)) {
+        const source = new Uint8Array(file.buffer, file.byteOffset, file.byteLength);
+        const view = new Uint8Array(source.byteLength);
+        view.set(source);
+        return {
+            value: new Blob([view]),
+            fileName: undefined,
+        };
+    }
+    return {
+        value: new Blob([file]),
+        fileName: undefined,
+    };
+}
+function buildUploadFilePart(input) {
+    const source = toBlobPart(input.file);
+    const fileName = input.file_name ??
+        (typeof File !== "undefined" && input.file instanceof File
+            ? input.file.name
+            : "upload.bin");
+    const contentType = input.content_type ??
+        ("type" in source.value &&
+            typeof source.value.type === "string" &&
+            source.value.type.length > 0
+            ? source.value.type
+            : "application/octet-stream");
+    if (typeof File !== "undefined") {
+        if (source.value instanceof File) {
+            if (source.value.name === fileName &&
+                source.value.type === contentType) {
+                return {
+                    value: source.value,
+                    fileName: undefined,
+                };
+            }
+            return {
+                value: new File([source.value], fileName, {
+                    type: contentType,
+                    lastModified: source.value.lastModified,
+                }),
+                fileName: undefined,
+            };
+        }
+        return {
+            value: new File([source.value], fileName, {
+                type: contentType,
+            }),
+            fileName: undefined,
+        };
+    }
+    return {
+        value: new Blob([source.value], {
+            type: contentType,
+        }),
+        fileName,
+    };
+}
+function createUploadFormData(input) {
+    const formData = new FormData();
+    const filePart = buildUploadFilePart(input);
+    if (filePart.fileName) {
+        formData.append("file", filePart.value, filePart.fileName);
+    }
+    else {
+        formData.append("file", filePart.value);
+    }
+    formData.append("page_id", input.page_id);
+    if (input.alt !== undefined && input.alt !== null) {
+        formData.append("alt", input.alt);
+    }
+    return formData;
+}
+export class Client {
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    defaultHeaders;
+    timeoutMs;
+    limiter;
+    pages = {
+        list: (query, options) => this.requestList("GET", "/pages", {
+            query,
+            options,
+        }),
+        create: (body = {}, options) => this.requestData("POST", "/pages", {
+            body,
+            options,
+        }),
+        get: (pageId, query, options) => this.requestData("GET", `/pages/${pageId}`, {
+            query,
+            options,
+        }),
+        update: (pageId, body, options) => this.requestData("PATCH", `/pages/${pageId}`, {
+            body,
+            options,
+        }),
+        delete: (pageId, options) => this.requestData("DELETE", `/pages/${pageId}`, {
+            options,
+        }),
+        restore: (pageId, options) => this.requestData("POST", `/pages/${pageId}/restore`, {
+            options,
+        }),
+        permanentlyDelete: (pageId, options) => this.requestData("DELETE", `/pages/${pageId}/permanent`, {
+            options,
+        }),
+        duplicate: (pageId, options) => this.requestData("POST", `/pages/${pageId}/duplicate`, {
+            options,
+        }),
+        createTranslation: (pageId, body, options) => this.requestData("POST", `/pages/${pageId}/translations`, {
+            body,
+            options,
+        }),
+    };
+    collections = {
+        list: (query, options) => this.requestList("GET", "/collections", {
+            query,
+            options,
+        }),
+        create: (body, options) => this.requestData("POST", "/collections", {
+            body,
+            options,
+        }),
+        get: (collectionId, options) => this.requestData("GET", `/collections/${collectionId}`, {
+            options,
+        }),
+        update: (collectionId, body, options) => this.requestData("PATCH", `/collections/${collectionId}`, {
+            body,
+            options,
+        }),
+        delete: (collectionId, options) => this.requestData("DELETE", `/collections/${collectionId}`, {
+            options,
+        }),
+    };
+    media = {
+        list: (query, options) => this.requestList("GET", "/media", {
+            query,
+            options,
+        }),
+        upload: (body, options) => this.requestData("POST", "/media", {
+            formData: createUploadFormData(body),
+            options,
+        }),
+        get: (mediaId, options) => this.requestData("GET", `/media/${mediaId}`, {
+            options,
+        }),
+        update: (mediaId, body, options) => this.requestData("PATCH", `/media/${mediaId}`, {
+            body,
+            options,
+        }),
+        delete: (mediaId, options) => this.requestData("DELETE", `/media/${mediaId}`, {
+            options,
+        }),
+    };
+    members = {
+        list: (query, options) => this.requestList("GET", "/members", {
+            query,
+            options,
+        }),
+    };
+    authors = {
+        list: (query, options) => this.requestList("GET", "/authors", {
+            query,
+            options,
+        }),
+    };
+    reviewers = {
+        list: (query, options) => this.requestList("GET", "/reviewers", {
+            query,
+            options,
+        }),
+    };
+    statuses = {
+        list: (query, options) => this.requestList("GET", "/statuses", {
+            query,
+            options,
+        }),
+        create: (body, options) => this.requestData("POST", "/statuses", {
+            body,
+            options,
+        }),
+        get: (statusId, options) => this.requestData("GET", `/statuses/${statusId}`, {
+            options,
+        }),
+        update: (statusId, body, options) => this.requestData("PATCH", `/statuses/${statusId}`, {
+            body,
+            options,
+        }),
+        reorder: (body, options) => this.requestData("POST", "/statuses/reorder", {
+            body,
+            options,
+        }),
+        delete: (statusId, options) => this.requestData("DELETE", `/statuses/${statusId}`, {
+            options,
+        }),
+    };
+    labels = {
+        list: (query, options) => this.requestList("GET", "/labels", {
+            query,
+            options,
+        }),
+        create: (body, options) => this.requestData("POST", "/labels", {
+            body,
+            options,
+        }),
+        get: (labelId, options) => this.requestData("GET", `/labels/${labelId}`, {
+            options,
+        }),
+        update: (labelId, body, options) => this.requestData("PATCH", `/labels/${labelId}`, {
+            body,
+            options,
+        }),
+        reorder: (body, options) => this.requestData("POST", "/labels/reorder", {
+            body,
+            options,
+        }),
+        delete: (labelId, options) => this.requestData("DELETE", `/labels/${labelId}`, {
+            options,
+        }),
+    };
+    dataModels = {
+        list: (query, options) => this.requestList("GET", "/data-models", {
+            query,
+            options,
+        }),
+        create: (body, options) => this.requestData("POST", "/data-models", {
+            body,
+            options,
+        }),
+        get: (dataModelId, options) => this.requestData("GET", `/data-models/${dataModelId}`, {
+            options,
+        }),
+        update: (dataModelId, body, options) => this.requestData("PATCH", `/data-models/${dataModelId}`, {
+            body,
+            options,
+        }),
+        delete: (dataModelId, options) => this.requestData("DELETE", `/data-models/${dataModelId}`, {
+            options,
+        }),
+    };
+    locales = {
+        list: (options) => this.requestData("GET", "/locales", {
+            options,
+        }),
+        create: (body, options) => this.requestData("POST", "/locales", {
+            body,
+            options,
+        }),
+        delete: (code, options) => this.requestData("DELETE", `/locales/${code}`, {
+            options,
+        }),
+    };
+    ai = {
+        generateMetaName: (body, options) => this.requestData("POST", "/ai/meta-name", {
+            body,
+            options,
+        }),
+        generateMetaDescription: (body, options) => this.requestData("POST", "/ai/meta-description", {
+            body,
+            options,
+        }),
+        generateContent: (body, options) => this.requestData("POST", "/ai/content", {
+            body,
+            options,
+        }),
+    };
+    constructor(options) {
+        if (!options.apiKey.trim()) {
+            throw new ParagraphClientError("`apiKey` is required.");
+        }
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== "function") {
+            throw new ParagraphClientError("No fetch implementation available. Pass `fetch` in the client options.");
+        }
+        this.apiKey = options.apiKey.trim();
+        this.baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+        this.fetchImpl = fetchImpl;
+        this.defaultHeaders = new Headers(options.headers);
+        this.timeoutMs = options.timeoutMs;
+        this.limiter = new RequestRateLimiter(options.maxRequestsPerSecond ?? DEFAULT_REQUESTS_PER_SECOND);
+    }
+    getInfo(options) {
+        return this.requestData("GET", "", { options });
+    }
+    requestData(method, path, config) {
+        return this.requestJson(method, path, config).then((response) => response.data);
+    }
+    requestList(method, path, config) {
+        return this.requestJson(method, path, config);
+    }
+    requestJson(method, path, config) {
+        const url = buildUrl(this.baseUrl, 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 requestSignal = createRequestSignal(config?.options?.signal, timeoutMs);
+            try {
+                const response = await this.fetchImpl(url, {
+                    method,
+                    headers,
+                    body,
+                    signal: requestSignal.signal,
+                });
+                const payload = await parseResponse(response);
+                if (!response.ok) {
+                    if (isApiErrorPayload(payload)) {
+                        throw new ParagraphApiError({
+                            status: response.status,
+                            code: payload.error.code,
+                            message: payload.error.message,
+                            details: payload.error.details,
+                            headers: new Headers(response.headers),
+                            request,
+                            body: payload,
+                        });
+                    }
+                    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,
+                    });
+                }
+                return payload;
+            }
+            catch (error) {
+                if (error instanceof ParagraphApiError ||
+                    error instanceof ParagraphClientError) {
+                    throw error;
+                }
+                if (requestSignal.didTimeout()) {
+                    throw new ParagraphClientError(`Request timed out after ${timeoutMs}ms.`, {
+                        request,
+                        cause: error,
+                    });
+                }
+                if (isAbortError(error)) {
+                    throw error;
+                }
+                throw new ParagraphClientError("Request failed.", {
+                    request,
+                    cause: error,
+                });
+            }
+            finally {
+                requestSignal.cleanup();
+            }
+        });
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+import type { ApiErrorPayload, RequestDescriptor } from "./types.js";
+export declare class ParagraphApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: unknown;
+    readonly headers: Headers;
+    readonly request: RequestDescriptor;
+    readonly body?: ApiErrorPayload;
+    constructor(options: {
+        status: number;
+        code: string;
+        message: string;
+        details?: unknown;
+        headers?: Headers;
+        request: RequestDescriptor;
+        body?: ApiErrorPayload;
+    });
+}
+export declare class ParagraphClientError extends Error {
+    readonly request?: RequestDescriptor;
+    readonly cause?: unknown;
+    constructor(message: string, options?: {
+        request?: RequestDescriptor;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;gBAEpB,OAAO,EAAE;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,OAAO,EAAE,iBAAiB,CAAC;QAC3B,IAAI,CAAC,EAAE,eAAe,CAAC;KACxB;CAUF;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC;IACrC,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAGhC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,iBAAiB,CAAC;QAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAOJ"}

package/dist/errors.js

@@ -0,0 +1,28 @@
+export class ParagraphApiError extends Error {
+    status;
+    code;
+    details;
+    headers;
+    request;
+    body;
+    constructor(options) {
+        super(options.message);
+        this.name = "ParagraphApiError";
+        this.status = options.status;
+        this.code = options.code;
+        this.details = options.details;
+        this.headers = options.headers ?? new Headers();
+        this.request = options.request;
+        this.body = options.body;
+    }
+}
+export class ParagraphClientError extends Error {
+    request;
+    cause;
+    constructor(message, options) {
+        super(message, options?.cause ? { cause: options.cause } : undefined);
+        this.name = "ParagraphClientError";
+        this.request = options?.request;
+        this.cause = options?.cause;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Client } from "./client.js";
+export { ParagraphApiError, ParagraphClientError, } from "./errors.js";
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EACL,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,mBAAmB,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Client } from "./client.js";
+export { ParagraphApiError, ParagraphClientError, } from "./errors.js";

package/dist/rate-limiter.d.ts

@@ -0,0 +1,9 @@
+export declare class RequestRateLimiter {
+    private readonly minIntervalMs;
+    private nextAvailableAt;
+    private scheduling;
+    constructor(requestsPerSecond: number);
+    schedule<T>(task: () => Promise<T>): Promise<T>;
+    private reserveSlot;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"AAQA,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,UAAU,CAAoC;gBAE1C,iBAAiB,EAAE,MAAM;IAarC,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;IAKlC,OAAO,CAAC,WAAW;CAiBpB"}

package/dist/rate-limiter.js

@@ -0,0 +1,35 @@
+import { ParagraphClientError } from "./errors.js";
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export class RequestRateLimiter {
+    minIntervalMs;
+    nextAvailableAt = 0;
+    scheduling = Promise.resolve();
+    constructor(requestsPerSecond) {
+        if (!Number.isFinite(requestsPerSecond) ||
+            requestsPerSecond <= 0) {
+            throw new ParagraphClientError("`maxRequestsPerSecond` must be a positive number.");
+        }
+        this.minIntervalMs = Math.ceil(1000 / requestsPerSecond);
+    }
+    schedule(task) {
+        const slot = this.reserveSlot();
+        return slot.then(task);
+    }
+    reserveSlot() {
+        const slot = this.scheduling.then(async () => {
+            const now = Date.now();
+            const scheduledAt = Math.max(now, this.nextAvailableAt);
+            const delayMs = scheduledAt - now;
+            this.nextAvailableAt = scheduledAt + this.minIntervalMs;
+            if (delayMs > 0) {
+                await sleep(delayMs);
+            }
+        });
+        this.scheduling = slot.catch(() => { });
+        return slot;
+    }
+}