@unchainedshop/cockpit-api 1.0.33 → 2.1.0

package/dist/core/cache.js

@@ -0,0 +1,32 @@
+/**
+ * Cache management with LRU cache and tenant isolation
+ */
+import { LRUCache } from "lru-cache";
+/**
+ * Creates a cache manager with prefixed keys
+ * Each call creates a new LRU cache instance - no shared state
+ */
+export function createCacheManager(cachePrefix, options = {}) {
+    const cache = new LRUCache({
+        max: options.max ?? 100,
+        ttl: options.ttl ?? 100000,
+        allowStale: false,
+    });
+    const prefixedKey = (key) => `${cachePrefix}${key}`;
+    return {
+        get(key) {
+            return cache.get(prefixedKey(key));
+        },
+        set(key, value) {
+            cache.set(prefixedKey(key), value);
+        },
+        clear(pattern) {
+            const prefix = pattern !== undefined ? `${cachePrefix}${pattern}` : cachePrefix;
+            for (const key of cache.keys()) {
+                if (key.startsWith(prefix)) {
+                    cache.delete(key);
+                }
+            }
+        },
+    };
+}

package/dist/core/config.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Configuration management for Cockpit API client
+ */
+export interface CockpitAPIOptions {
+    /** Cockpit CMS endpoint URL (falls back to COCKPIT_GRAPHQL_ENDPOINT env var) */
+    endpoint?: string;
+    /** Tenant name for multi-tenant setups */
+    tenant?: string;
+    /** API key (falls back to COCKPIT_SECRET env var) */
+    apiKey?: string;
+    /** Use admin access with API key */
+    useAdminAccess?: boolean;
+    /**
+     * Default language that maps to Cockpit's "default" locale.
+     * When a request uses this language, it will be sent as "default" to Cockpit.
+     * @default "de"
+     */
+    defaultLanguage?: string;
+    /** Cache configuration */
+    cache?: {
+        /** Max entries (falls back to COCKPIT_CACHE_MAX env var, default: 100) */
+        max?: number;
+        /** TTL in ms (falls back to COCKPIT_CACHE_TTL env var, default: 100000) */
+        ttl?: number;
+    };
+    /**
+     * Preload route replacements during client initialization.
+     * When true, fetches page routes to enable `pages://id` link resolution in responses.
+     * When false (default), skips the network request for faster cold starts.
+     * @default false
+     */
+    preloadRoutes?: boolean;
+}
+export interface CockpitConfig {
+    readonly endpoint: URL;
+    readonly tenant?: string;
+    readonly apiKey?: string;
+    readonly useAdminAccess: boolean;
+    readonly defaultLanguage: string;
+    readonly cachePrefix: string;
+}
+/**
+ * Creates an immutable configuration object for the Cockpit API client
+ */
+export declare function createConfig(options?: CockpitAPIOptions): CockpitConfig;

package/dist/core/config.js

@@ -0,0 +1,32 @@
+/**
+ * Configuration management for Cockpit API client
+ */
+import { resolveApiKey } from "../utils/tenant.js";
+/** Valid tenant format: alphanumeric, hyphens, underscores only */
+const VALID_TENANT_PATTERN = /^[a-z0-9_-]+$/i;
+/**
+ * Creates an immutable configuration object for the Cockpit API client
+ */
+export function createConfig(options = {}) {
+    const endpointStr = options.endpoint ?? process.env["COCKPIT_GRAPHQL_ENDPOINT"];
+    if (endpointStr === undefined || endpointStr === "") {
+        throw new Error("Cockpit: endpoint is required (provide via options or COCKPIT_GRAPHQL_ENDPOINT env var)");
+    }
+    // Validate tenant format to prevent path traversal
+    if (options.tenant !== undefined &&
+        !VALID_TENANT_PATTERN.test(options.tenant)) {
+        throw new Error("Cockpit: Invalid tenant format (only alphanumeric, hyphens, and underscores allowed)");
+    }
+    const endpoint = new URL(endpointStr);
+    const apiKey = resolveApiKey(options.tenant, options);
+    // Build config object with all properties before freezing
+    const config = Object.freeze({
+        endpoint,
+        useAdminAccess: options.useAdminAccess ?? false,
+        defaultLanguage: options.defaultLanguage ?? "de",
+        cachePrefix: `${endpointStr}:${options.tenant ?? "default"}:`,
+        ...(options.tenant !== undefined && { tenant: options.tenant }),
+        ...(apiKey !== undefined && { apiKey }),
+    });
+    return config;
+}

package/dist/core/http.d.ts

@@ -0,0 +1,34 @@
+/**
+ * HTTP client for Cockpit API requests
+ */
+import type { CockpitConfig } from "./config.ts";
+import type { ResponseTransformer } from "../transformers/image-path.ts";
+/**
+ * Per-request options that can override client-level settings
+ */
+export interface HttpFetchOptions extends RequestInit {
+    /** Override the client-level useAdminAccess setting for this request */
+    useAdminAccess?: boolean;
+}
+export interface HttpClient {
+    /**
+     * Make a GET request expecting JSON response
+     */
+    fetch<T>(url: URL | string, options?: HttpFetchOptions): Promise<T | null>;
+    /**
+     * Make a GET request expecting text response (e.g., URL strings)
+     */
+    fetchText(url: URL | string, options?: HttpFetchOptions): Promise<string | null>;
+    /**
+     * Make a POST request with JSON body
+     */
+    post<T>(url: URL | string, body: unknown, options?: HttpFetchOptions): Promise<T | null>;
+    /**
+     * Make a DELETE request
+     */
+    delete<T>(url: URL | string, options?: HttpFetchOptions): Promise<T | null>;
+}
+/**
+ * Creates an HTTP client with authentication and response transformation
+ */
+export declare function createHttpClient(config: CockpitConfig, transformer: ResponseTransformer): HttpClient;

package/dist/core/http.js

@@ -0,0 +1,98 @@
+/**
+ * HTTP client for Cockpit API requests
+ */
+import { logger } from "../cockpit-logger.js";
+/**
+ * Normalizes headers to Record<string, string>
+ */
+function normalizeHeaders(headers) {
+    if (!headers || typeof headers !== "object" || Array.isArray(headers)) {
+        return {};
+    }
+    return headers;
+}
+/**
+ * Prepares request options for POST/DELETE requests
+ */
+function prepareJsonRequestOptions(options, method, body) {
+    const { useAdminAccess, headers, ...restOptions } = options;
+    const customHeaders = normalizeHeaders(headers);
+    const fetchOpts = {
+        ...restOptions,
+        method,
+        headers: { "Content-Type": "application/json", ...customHeaders },
+    };
+    if (body !== undefined)
+        fetchOpts.body = JSON.stringify(body);
+    if (useAdminAccess !== undefined)
+        fetchOpts.useAdminAccess = useAdminAccess;
+    return fetchOpts;
+}
+/**
+ * Creates an HTTP client with authentication and response transformation
+ */
+export function createHttpClient(config, transformer) {
+    /**
+     * Build headers with optional admin access override
+     * @param custom - Custom headers to include
+     * @param useAdminAccess - Per-request override (undefined = use config default)
+     */
+    const buildHeaders = (custom = {}, useAdminAccess) => {
+        const headers = { ...custom };
+        // Use per-request setting if provided, otherwise fall back to config
+        const shouldUseAdmin = useAdminAccess ?? config.useAdminAccess;
+        if (shouldUseAdmin && config.apiKey !== undefined) {
+            headers["api-Key"] = config.apiKey;
+        }
+        return headers;
+    };
+    const handleErrorResponse = async (response) => {
+        const errorText = await response.text();
+        logger.error(`Cockpit: Error accessing ${response.url}`, {
+            status: response.status,
+            body: errorText,
+        });
+        throw new Error(`Cockpit: Error accessing ${response.url} (${String(response.status)}): ${errorText}`);
+    };
+    const handleJsonResponse = async (response) => {
+        if (response.status === 404)
+            return null;
+        if (!response.ok)
+            return handleErrorResponse(response);
+        const json = await response.json();
+        return transformer.transform(json);
+    };
+    const handleTextResponse = async (response) => {
+        if (response.status === 404)
+            return null;
+        if (!response.ok)
+            return handleErrorResponse(response);
+        return response.text();
+    };
+    const doFetch = async (url, options = {}) => {
+        const { useAdminAccess, ...fetchOptions } = options;
+        logger.debug(`Cockpit: Requesting ${String(url)}`);
+        return fetch(url, {
+            ...fetchOptions,
+            headers: buildHeaders(fetchOptions.headers, useAdminAccess),
+        });
+    };
+    const fetchData = async (url, options = {}) => {
+        const response = await doFetch(url, options);
+        return handleJsonResponse(response);
+    };
+    const fetchTextData = async (url, options = {}) => {
+        const response = await doFetch(url, options);
+        return handleTextResponse(response);
+    };
+    return {
+        fetch: fetchData,
+        fetchText: fetchTextData,
+        async post(url, body, options = {}) {
+            return fetchData(url, prepareJsonRequestOptions(options, "POST", body));
+        },
+        async delete(url, options = {}) {
+            return fetchData(url, prepareJsonRequestOptions(options, "DELETE"));
+        },
+    };
+}

package/dist/core/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Core module exports
+ */
+export { buildQueryString, encodeQueryParam } from "./query-string.ts";
+export type { CacheManager, CacheOptions } from "./cache.ts";
+export { createCacheManager } from "./cache.ts";
+export type { CockpitConfig } from "./config.ts";
+export { createConfig } from "./config.ts";
+export type { UrlBuilder, UrlBuildOptions } from "./url-builder.ts";
+export { createUrlBuilder } from "./url-builder.ts";
+export type { HttpClient } from "./http.ts";
+export { createHttpClient } from "./http.ts";
+export { requireParam, validatePathSegment } from "./validation.ts";
+export { createLocaleNormalizer } from "./locale.ts";

package/dist/core/index.js

@@ -0,0 +1,10 @@
+/**
+ * Core module exports
+ */
+export { buildQueryString, encodeQueryParam } from "./query-string.js";
+export { createCacheManager } from "./cache.js";
+export { createConfig } from "./config.js";
+export { createUrlBuilder } from "./url-builder.js";
+export { createHttpClient } from "./http.js";
+export { requireParam, validatePathSegment } from "./validation.js";
+export { createLocaleNormalizer } from "./locale.js";

package/dist/core/locale.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared locale utilities
+ */
+/**
+ * Creates a locale normalizer for the given default language.
+ * Maps the default language to Cockpit's "default" locale.
+ *
+ * @param defaultLanguage - The language that should map to "default"
+ * @returns A function that normalizes locale strings
+ */
+export declare function createLocaleNormalizer(defaultLanguage: string): (locale?: string) => string;

package/dist/core/locale.js

@@ -0,0 +1,17 @@
+/**
+ * Shared locale utilities
+ */
+/**
+ * Creates a locale normalizer for the given default language.
+ * Maps the default language to Cockpit's "default" locale.
+ *
+ * @param defaultLanguage - The language that should map to "default"
+ * @returns A function that normalizes locale strings
+ */
+export function createLocaleNormalizer(defaultLanguage) {
+    return (locale) => {
+        if (locale === undefined || locale === defaultLanguage)
+            return "default";
+        return locale;
+    };
+}

package/dist/core/query-string.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Query string encoding utilities
+ */
+/** Primitive values that can be used as query parameters */
+export type QueryParamPrimitive = string | number | boolean | null | undefined;
+/** Object values that will be JSON stringified */
+export type QueryParamObject = Record<string, QueryParamPrimitive | QueryParamPrimitive[]>;
+/** All allowed query parameter value types */
+export type QueryParamValue = QueryParamPrimitive | QueryParamObject | QueryParamValue[];
+/**
+ * Encodes a single query parameter key-value pair
+ */
+export declare const encodeQueryParam: (key: string, value: QueryParamValue) => string;
+/**
+ * Builds a query string from an object of parameters
+ * Filters out null and undefined values
+ */
+export declare const buildQueryString: (params: Record<string, QueryParamValue>) => string | null;

package/dist/core/query-string.js

@@ -0,0 +1,20 @@
+/**
+ * Query string encoding utilities
+ */
+/**
+ * Encodes a single query parameter key-value pair
+ */
+export const encodeQueryParam = (key, value) => {
+    const encodedValue = typeof value === "string" ? value : JSON.stringify(value);
+    return `${encodeURIComponent(key)}=${encodeURIComponent(encodedValue)}`;
+};
+/**
+ * Builds a query string from an object of parameters
+ * Filters out null and undefined values
+ */
+export const buildQueryString = (params) => {
+    const entries = Object.entries(params).filter(([, v]) => v !== undefined && v !== null);
+    if (!entries.length)
+        return null;
+    return entries.map(([key, value]) => encodeQueryParam(key, value)).join("&");
+};

package/dist/core/url-builder.d.ts

@@ -0,0 +1,22 @@
+/**
+ * URL construction utilities
+ */
+import type { CockpitConfig } from "./config.ts";
+export interface UrlBuildOptions {
+    locale?: string;
+    queryParams?: Record<string, unknown>;
+}
+export interface UrlBuilder {
+    /**
+     * Build a URL for an API endpoint
+     */
+    build(path: string, options?: UrlBuildOptions): URL;
+    /**
+     * Get the GraphQL endpoint URL
+     */
+    graphqlEndpoint(): URL;
+}
+/**
+ * Creates a URL builder for the given configuration
+ */
+export declare function createUrlBuilder(config: CockpitConfig): UrlBuilder;

package/dist/core/url-builder.js

@@ -0,0 +1,35 @@
+/**
+ * URL construction utilities
+ */
+import { buildQueryString } from "./query-string.js";
+import { createLocaleNormalizer } from "./locale.js";
+/**
+ * Creates a URL builder for the given configuration
+ */
+export function createUrlBuilder(config) {
+    const apiBasePath = config.tenant !== undefined ? `/:${config.tenant}/api` : "/api";
+    const normalizeLocale = createLocaleNormalizer(config.defaultLanguage);
+    return {
+        build(path, options = {}) {
+            const { locale = "default", queryParams = {} } = options;
+            const normalizedLocale = normalizeLocale(locale);
+            const url = new URL(config.endpoint);
+            url.pathname = `${apiBasePath}${path}`;
+            const queryString = buildQueryString({
+                ...queryParams,
+                locale: normalizedLocale,
+            });
+            if (queryString !== null) {
+                url.search = queryString;
+            }
+            return url;
+        },
+        graphqlEndpoint() {
+            const url = new URL(config.endpoint);
+            if (config.tenant !== undefined) {
+                url.pathname = `/:${config.tenant}${url.pathname}`;
+            }
+            return url;
+        },
+    };
+}

package/dist/core/validation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared validation utilities
+ */
+/**
+ * Validates that a required parameter is present
+ * @throws Error if value is undefined, null, or empty string
+ */
+export declare const requireParam: (value: unknown, name: string) => void;
+/**
+ * Validates path segment format to prevent path traversal
+ * @throws Error if value contains invalid characters
+ */
+export declare const validatePathSegment: (value: string, name: string) => void;

package/dist/core/validation.js

@@ -0,0 +1,22 @@
+/**
+ * Shared validation utilities
+ */
+/** Valid path segment format: alphanumeric, hyphens, underscores only */
+const VALID_PATH_SEGMENT = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Validates that a required parameter is present
+ * @throws Error if value is undefined, null, or empty string
+ */
+export const requireParam = (value, name) => {
+    if (value === undefined || value === null || value === "")
+        throw new Error(`Cockpit: Please provide ${name}`);
+};
+/**
+ * Validates path segment format to prevent path traversal
+ * @throws Error if value contains invalid characters
+ */
+export const validatePathSegment = (value, name) => {
+    if (!VALID_PATH_SEGMENT.test(value)) {
+        throw new Error(`Cockpit: Invalid ${name} format (only alphanumeric, hyphens, and underscores allowed)`);
+    }
+};

package/dist/fetch/client.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Lightweight fetch client for Cockpit CMS
+ *
+ * Designed for edge/RSC environments where the full CockpitAPI
+ * factory is too heavy. This client:
+ * - Has no async initialization
+ * - No caching (relies on platform caching)
+ * - No response transformation
+ * - Minimal memory footprint
+ */
+import type { CockpitPage } from "../methods/pages.ts";
+import type { CockpitContentItem } from "../methods/content.ts";
+/**
+ * Request cache mode for fetch requests
+ */
+export type FetchCacheMode = "default" | "force-cache" | "no-cache" | "no-store" | "only-if-cached" | "reload";
+/**
+ * Options for creating a lightweight fetch client
+ */
+export interface FetchClientOptions {
+    /** Cockpit CMS endpoint URL */
+    endpoint?: string;
+    /** Tenant ID for multi-tenant setups */
+    tenant?: string | null;
+    /**
+     * Default language that maps to Cockpit's "default" locale.
+     * When a request uses this language, it will be sent as "default" to Cockpit.
+     * @default "de"
+     */
+    defaultLanguage?: string;
+    /** Request cache mode (default: "no-store") */
+    cache?: FetchCacheMode;
+    /** Additional request headers */
+    headers?: Record<string, string>;
+    /** API key for authenticated requests */
+    apiKey?: string;
+}
+/**
+ * Query parameters for page/content requests
+ */
+export interface PageFetchParams {
+    /** Locale for the request (the configured defaultLanguage maps to "default") */
+    locale?: string;
+    /** Populate depth for linked content */
+    populate?: number;
+    /** Additional query parameters */
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Lightweight fetch client interface
+ */
+export interface FetchClient {
+    /** Fetch a page by route */
+    pageByRoute<T = CockpitPage>(route: string, params?: PageFetchParams): Promise<T | null>;
+    /** Fetch pages list */
+    pages<T = CockpitPage>(params?: PageFetchParams): Promise<T[] | null>;
+    /** Fetch a page by ID */
+    pageById<T = CockpitPage>(id: string, params?: PageFetchParams): Promise<T | null>;
+    /** Fetch content items */
+    getContentItems<T = CockpitContentItem>(model: string, params?: PageFetchParams): Promise<T[] | null>;
+    /** Fetch a single content item */
+    getContentItem<T = unknown>(model: string, id?: string, params?: PageFetchParams): Promise<T | null>;
+    /** Raw fetch for custom paths */
+    fetchRaw<T = unknown>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;
+}
+/**
+ * Creates a lightweight fetch client for Cockpit CMS
+ *
+ * @example
+ * ```typescript
+ * import { createFetchClient } from "@unchainedshop/cockpit-api/fetch";
+ *
+ * const cockpit = createFetchClient({
+ *   endpoint: process.env.NEXT_PUBLIC_COCKPIT_ENDPOINT,
+ *   tenant: "mytenant",
+ * });
+ *
+ * // Fetch a page by route
+ * const page = await cockpit.pageByRoute("/about", { locale: "en" });
+ *
+ * // Fetch content items
+ * const items = await cockpit.getContentItems("news", { locale: "de", limit: 10 });
+ * ```
+ */
+export declare function createFetchClient(options?: FetchClientOptions): FetchClient;

package/dist/fetch/client.js

@@ -0,0 +1,143 @@
+/**
+ * Lightweight fetch client for Cockpit CMS
+ *
+ * Designed for edge/RSC environments where the full CockpitAPI
+ * factory is too heavy. This client:
+ * - Has no async initialization
+ * - No caching (relies on platform caching)
+ * - No response transformation
+ * - Minimal memory footprint
+ */
+import { createLocaleNormalizer } from "../core/locale.js";
+/**
+ * Build the API base URL for the given endpoint and tenant
+ */
+function buildApiBaseUrl(endpoint, tenant) {
+    const url = new URL(endpoint);
+    const basePath = tenant !== undefined && tenant !== null ? `/:${tenant}/api` : "/api";
+    return `${url.origin}${basePath}`;
+}
+/**
+ * Build query string from params object, filtering undefined values
+ */
+function buildQueryString(params) {
+    const filtered = Object.entries(params)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => [key, String(value)]);
+    return new URLSearchParams(filtered).toString();
+}
+/**
+ * Creates a lightweight fetch client for Cockpit CMS
+ *
+ * @example
+ * ```typescript
+ * import { createFetchClient } from "@unchainedshop/cockpit-api/fetch";
+ *
+ * const cockpit = createFetchClient({
+ *   endpoint: process.env.NEXT_PUBLIC_COCKPIT_ENDPOINT,
+ *   tenant: "mytenant",
+ * });
+ *
+ * // Fetch a page by route
+ * const page = await cockpit.pageByRoute("/about", { locale: "en" });
+ *
+ * // Fetch content items
+ * const items = await cockpit.getContentItems("news", { locale: "de", limit: 10 });
+ * ```
+ */
+export function createFetchClient(options = {}) {
+    const { endpoint = process.env["COCKPIT_GRAPHQL_ENDPOINT"] ??
+        process.env["NEXT_PUBLIC_COCKPIT_ENDPOINT"], tenant = null, defaultLanguage = "de", cache = "no-store", headers = {}, apiKey, } = options;
+    if (endpoint === undefined || endpoint === "") {
+        throw new Error("Cockpit: endpoint is required (provide via options or COCKPIT_GRAPHQL_ENDPOINT env var)");
+    }
+    const baseUrl = buildApiBaseUrl(endpoint, tenant);
+    const normalizeLocale = createLocaleNormalizer(defaultLanguage);
+    const requestHeaders = { ...headers };
+    if (apiKey !== undefined) {
+        requestHeaders["api-Key"] = apiKey;
+    }
+    /**
+     * Fetch raw JSON from a Cockpit API path
+     */
+    async function fetchRaw(path, params = {}) {
+        const queryString = buildQueryString(params);
+        const url = queryString
+            ? `${baseUrl}${path}?${queryString}`
+            : `${baseUrl}${path}`;
+        const fetchInit = { cache };
+        if (Object.keys(requestHeaders).length > 0) {
+            fetchInit.headers = requestHeaders;
+        }
+        const response = await fetch(url, fetchInit);
+        if (!response.ok) {
+            if (response.status === 404) {
+                return null;
+            }
+            throw new Error(`Cockpit: Error fetching ${url} (${String(response.status)})`);
+        }
+        return response.json();
+    }
+    return {
+        /**
+         * Fetch a page by route
+         */
+        async pageByRoute(route, params = {}) {
+            const { locale, populate, ...rest } = params;
+            return fetchRaw("/pages/page", {
+                route,
+                locale: normalizeLocale(locale),
+                populate,
+                ...rest,
+            });
+        },
+        /**
+         * Fetch pages list
+         */
+        async pages(params = {}) {
+            const { locale, ...rest } = params;
+            return fetchRaw("/pages/pages", {
+                locale: normalizeLocale(locale),
+                ...rest,
+            });
+        },
+        /**
+         * Fetch a page by ID
+         */
+        async pageById(id, params = {}) {
+            const { locale, populate, ...rest } = params;
+            return fetchRaw(`/pages/page/${id}`, {
+                locale: normalizeLocale(locale),
+                populate,
+                ...rest,
+            });
+        },
+        /**
+         * Fetch content items
+         */
+        async getContentItems(model, params = {}) {
+            const { locale, ...rest } = params;
+            return fetchRaw(`/content/items/${model}`, {
+                locale: normalizeLocale(locale),
+                ...rest,
+            });
+        },
+        /**
+         * Fetch a single content item
+         */
+        async getContentItem(model, id, params = {}) {
+            const { locale, ...rest } = params;
+            const path = id !== undefined
+                ? `/content/item/${model}/${id}`
+                : `/content/item/${model}`;
+            return fetchRaw(path, {
+                locale: normalizeLocale(locale),
+                ...rest,
+            });
+        },
+        /**
+         * Raw fetch for custom paths
+         */
+        fetchRaw: fetchRaw,
+    };
+}