@unchainedshop/cockpit-api 2.2.1 → 2.3.0

package/dist/client.d.ts

@@ -39,14 +39,14 @@ export interface CockpitAPIClient {
     /**
      * Get a transformed image asset URL.
      *
-     * **Important:** The `w` (width) or `h` (height) parameter is required by the API.
-     * Without it, the API returns a 400 error.
+     * **Important:** At least one of `w` (width) or `h` (height) must be provided.
+     * The Cockpit CMS API requires this and returns a 400 error without it.
      *
      * @param assetId - The asset ID
      * @param queryParams - Image transformation parameters (w or h required)
      * @returns URL string to the generated image, or null if not found
      */
-    imageAssetById(assetId: string, queryParams?: ImageAssetQueryParams): Promise<string | null>;
+    imageAssetById(assetId: string, queryParams: ImageAssetQueryParams): Promise<string | null>;
     getFullRouteForSlug(slug: string): Promise<string | undefined>;
     /**
      * Clear cache entries matching pattern

package/dist/index.d.ts

@@ -26,3 +26,5 @@ export type { CockpitMenuUrl, CockpitMenuLink, CockpitMenu, } from "./methods/me
 export type { CockpitRoute, CockpitRoutesResponse, CockpitSitemapEntry, CockpitPreviewConfig, CockpitSettings, } from "./methods/routes.ts";
 export type { CockpitSearchHit, CockpitSearchResult, } from "./methods/search.ts";
 export type { CockpitHealthCheck } from "./methods/system.ts";
+export { parseCockpitUrl, isCockpitPageUrl, isCockpitAssetUrl, extractPageId, extractAssetId, } from "./utils/url-protocols.ts";
+export type { CockpitProtocol, ParsedCockpitUrl, } from "./utils/url-protocols.ts";

package/dist/index.js

@@ -11,3 +11,4 @@ export { createImagePathTransformer, identityTransformer,
 FixImagePaths, } from "./transformers/image-path.js";
 export { createAssetPathTransformer, createPageLinkTransformer, composeTransformers, } from "./transformers/index.js";
 export { ImageSizeMode, MimeType } from "./methods/assets.js";
+export { parseCockpitUrl, isCockpitPageUrl, isCockpitAssetUrl, extractPageId, extractAssetId, } from "./utils/url-protocols.js";

package/dist/methods/assets.d.ts

@@ -38,28 +38,38 @@ export declare enum MimeType {
     WEBP = "webp",
     BMP = "bmp"
 }
-export interface ImageAssetQueryParams {
+/**
+ * Image transformation parameters for imageAssetById.
+ *
+ * At least one of `w` (width) or `h` (height) must be provided.
+ * The Cockpit CMS API requires this and returns a 400 error without it.
+ */
+export type ImageAssetQueryParams = {
     m?: ImageSizeMode;
-    w?: number;
-    h?: number;
     q?: number;
     mime?: MimeType;
     re?: number;
     t?: string;
     o?: number;
-}
+} & ({
+    w: number;
+    h?: number;
+} | {
+    w?: number;
+    h: number;
+});
 export interface AssetMethods {
     assetById<T = CockpitAsset>(assetId: string): Promise<T | null>;
     /**
      * Get a transformed image asset URL.
      *
-     * **Important:** The `w` (width) or `h` (height) parameter is required by the API.
-     * Without it, the API returns a 400 error.
+     * **Important:** At least one of `w` (width) or `h` (height) must be provided.
+     * The Cockpit CMS API requires this and returns a 400 error without it.
      *
      * @param assetId - The asset ID
      * @param queryParams - Image transformation parameters (w or h required)
      * @returns URL string to the generated image, or null if not found
      */
-    imageAssetById(assetId: string, queryParams?: ImageAssetQueryParams): Promise<string | null>;
+    imageAssetById(assetId: string, queryParams: ImageAssetQueryParams): Promise<string | null>;
 }
 export declare function createAssetMethods(ctx: MethodContext): AssetMethods;

package/dist/methods/pages.d.ts

@@ -10,6 +10,7 @@ export interface PageByIdOptions {
 export interface PageByRouteOptions {
     locale?: string;
     populate?: number;
+    fallbackToDefault?: boolean;
 }
 export type CockpitPageType = "layout" | "collection" | "singleton" | "link";
 export interface CockpitPageMeta {

package/dist/methods/pages.js

@@ -12,6 +12,9 @@ export function createPagesMethods(ctx) {
             });
             const result = await ctx.http.fetch(url);
             // Normalize response to always return { data, meta? }
+            // Note: The Cockpit /api/pages/pages endpoint returns a raw array even when skip
+            // is provided, unlike /api/content/items/{model} which returns { data, meta }.
+            // This means meta.total will not be available for pages() method.
             if (result === null) {
                 return null;
             }
@@ -31,12 +34,34 @@ export function createPagesMethods(ctx) {
         },
         async pageByRoute(route, options = "default") {
             const opts = typeof options === "string" ? { locale: options } : options;
-            const { locale = "default", populate } = opts;
+            const { locale = "default", populate, fallbackToDefault = false } = opts;
+            // Force populate: 0 to prevent route string issues
+            const queryOptions = { populate: populate ?? 0 };
             const url = ctx.url.build("/pages/page", {
                 locale,
-                queryParams: { route, populate },
+                queryParams: { route, ...queryOptions },
             });
-            return ctx.http.fetch(url);
+            const result = await ctx.http.fetch(url);
+            // If found, return it
+            if (result)
+                return result;
+            // If not found and fallback enabled and not in default locale
+            if (fallbackToDefault && locale !== "default") {
+                // Try to find in default locale
+                const defaultUrl = ctx.url.build("/pages/page", {
+                    locale: "default",
+                    queryParams: { route, ...queryOptions },
+                });
+                const defaultResult = await ctx.http.fetch(defaultUrl);
+                // If found in default, get by ID in target locale
+                if (defaultResult?._id != null && defaultResult._id !== "") {
+                    return this.pageById(defaultResult._id, {
+                        locale,
+                        populate: queryOptions.populate,
+                    });
+                }
+            }
+            return null;
         },
     };
 }

package/dist/methods/routes.d.ts

@@ -28,7 +28,7 @@ export interface CockpitSettings {
         logo?: CockpitAsset | null;
         small?: CockpitAsset | null;
         favicon?: CockpitAsset | null;
-        [key: string]: CockpitAsset | null | undefined;
+        [key: string]: CockpitAsset | null;
     };
     scripts?: {
         header?: string | null;

package/dist/utils/index.d.ts

@@ -3,3 +3,4 @@
  */
 export { getTenantIds, resolveApiKey } from "./tenant.ts";
 export { generateCmsRouteReplacements, generateCollectionAndSingletonSlugRouteMap, } from "./route-map.ts";
+export { parseCockpitUrl, isCockpitPageUrl, isCockpitAssetUrl, extractPageId, extractAssetId, } from "./url-protocols.ts";

package/dist/utils/index.js

@@ -3,3 +3,4 @@
  */
 export { getTenantIds, resolveApiKey } from "./tenant.js";
 export { generateCmsRouteReplacements, generateCollectionAndSingletonSlugRouteMap, } from "./route-map.js";
+export { parseCockpitUrl, isCockpitPageUrl, isCockpitAssetUrl, extractPageId, extractAssetId, } from "./url-protocols.js";

package/dist/utils/url-protocols.d.ts

@@ -0,0 +1,91 @@
+/**
+ * URL protocol parsing utilities for Cockpit CMS
+ *
+ * Provides utilities to parse and work with Cockpit CMS URL protocols:
+ * - pages://id - References to pages by ID
+ * - assets://id - References to assets by ID
+ */
+export type CockpitProtocol = "pages" | "assets" | "external";
+export interface ParsedCockpitUrl {
+    protocol: CockpitProtocol;
+    id: string;
+    original: string;
+}
+/**
+ * Parses a Cockpit CMS URL and extracts protocol and ID information.
+ *
+ * @param url - The URL to parse (e.g., "pages://123", "assets://456", or "https://example.com")
+ * @returns Parsed URL object with protocol, id, and original URL, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * parseCockpitUrl("pages://abc123")
+ * // { protocol: "pages", id: "abc123", original: "pages://abc123" }
+ *
+ * parseCockpitUrl("assets://xyz789")
+ * // { protocol: "assets", id: "xyz789", original: "assets://xyz789" }
+ *
+ * parseCockpitUrl("https://example.com")
+ * // { protocol: "external", id: "https://example.com", original: "https://example.com" }
+ *
+ * parseCockpitUrl(null)
+ * // null
+ * ```
+ */
+export declare function parseCockpitUrl(url: string | null | undefined): ParsedCockpitUrl | null;
+/**
+ * Checks if a URL is a Cockpit page reference (pages://id).
+ *
+ * @param url - The URL to check
+ * @returns True if the URL uses the pages:// protocol
+ *
+ * @example
+ * ```typescript
+ * isCockpitPageUrl("pages://123") // true
+ * isCockpitPageUrl("assets://456") // false
+ * isCockpitPageUrl("https://example.com") // false
+ * ```
+ */
+export declare function isCockpitPageUrl(url: string | null | undefined): boolean;
+/**
+ * Checks if a URL is a Cockpit asset reference (assets://id).
+ *
+ * @param url - The URL to check
+ * @returns True if the URL uses the assets:// protocol
+ *
+ * @example
+ * ```typescript
+ * isCockpitAssetUrl("assets://456") // true
+ * isCockpitAssetUrl("pages://123") // false
+ * isCockpitAssetUrl("https://example.com") // false
+ * ```
+ */
+export declare function isCockpitAssetUrl(url: string | null | undefined): boolean;
+/**
+ * Extracts the page ID from a Cockpit page URL.
+ *
+ * @param url - The URL to extract from
+ * @returns The page ID if valid pages:// URL, null otherwise
+ *
+ * @example
+ * ```typescript
+ * extractPageId("pages://abc123") // "abc123"
+ * extractPageId("assets://456") // null
+ * extractPageId("https://example.com") // null
+ * ```
+ */
+export declare function extractPageId(url: string | null | undefined): string | null;
+/**
+ * Extracts the asset ID from a Cockpit asset URL.
+ *
+ * @param url - The URL to extract from
+ * @returns The asset ID if valid assets:// URL, null otherwise
+ *
+ * @example
+ * ```typescript
+ * extractAssetId("assets://xyz789") // "xyz789"
+ * extractAssetId("pages://123") // null
+ * extractAssetId("https://example.com") // null
+ * ```
+ */
+export declare function extractAssetId(url: string | null | undefined): string | null;

package/dist/utils/url-protocols.js

@@ -0,0 +1,110 @@
+/**
+ * URL protocol parsing utilities for Cockpit CMS
+ *
+ * Provides utilities to parse and work with Cockpit CMS URL protocols:
+ * - pages://id - References to pages by ID
+ * - assets://id - References to assets by ID
+ */
+/**
+ * Parses a Cockpit CMS URL and extracts protocol and ID information.
+ *
+ * @param url - The URL to parse (e.g., "pages://123", "assets://456", or "https://example.com")
+ * @returns Parsed URL object with protocol, id, and original URL, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * parseCockpitUrl("pages://abc123")
+ * // { protocol: "pages", id: "abc123", original: "pages://abc123" }
+ *
+ * parseCockpitUrl("assets://xyz789")
+ * // { protocol: "assets", id: "xyz789", original: "assets://xyz789" }
+ *
+ * parseCockpitUrl("https://example.com")
+ * // { protocol: "external", id: "https://example.com", original: "https://example.com" }
+ *
+ * parseCockpitUrl(null)
+ * // null
+ * ```
+ */
+export function parseCockpitUrl(url) {
+    if (url == null || typeof url !== "string")
+        return null;
+    const trimmed = url.trim();
+    if (trimmed === "")
+        return null;
+    if (trimmed.startsWith("pages://")) {
+        const id = trimmed.slice(8).split("?")[0] ?? "";
+        return { protocol: "pages", id, original: trimmed };
+    }
+    if (trimmed.startsWith("assets://")) {
+        const id = trimmed.slice(9).split("?")[0] ?? "";
+        return { protocol: "assets", id, original: trimmed };
+    }
+    return { protocol: "external", id: trimmed, original: trimmed };
+}
+/**
+ * Checks if a URL is a Cockpit page reference (pages://id).
+ *
+ * @param url - The URL to check
+ * @returns True if the URL uses the pages:// protocol
+ *
+ * @example
+ * ```typescript
+ * isCockpitPageUrl("pages://123") // true
+ * isCockpitPageUrl("assets://456") // false
+ * isCockpitPageUrl("https://example.com") // false
+ * ```
+ */
+export function isCockpitPageUrl(url) {
+    return parseCockpitUrl(url)?.protocol === "pages";
+}
+/**
+ * Checks if a URL is a Cockpit asset reference (assets://id).
+ *
+ * @param url - The URL to check
+ * @returns True if the URL uses the assets:// protocol
+ *
+ * @example
+ * ```typescript
+ * isCockpitAssetUrl("assets://456") // true
+ * isCockpitAssetUrl("pages://123") // false
+ * isCockpitAssetUrl("https://example.com") // false
+ * ```
+ */
+export function isCockpitAssetUrl(url) {
+    return parseCockpitUrl(url)?.protocol === "assets";
+}
+/**
+ * Extracts the page ID from a Cockpit page URL.
+ *
+ * @param url - The URL to extract from
+ * @returns The page ID if valid pages:// URL, null otherwise
+ *
+ * @example
+ * ```typescript
+ * extractPageId("pages://abc123") // "abc123"
+ * extractPageId("assets://456") // null
+ * extractPageId("https://example.com") // null
+ * ```
+ */
+export function extractPageId(url) {
+    const parsed = parseCockpitUrl(url);
+    return parsed?.protocol === "pages" ? parsed.id : null;
+}
+/**
+ * Extracts the asset ID from a Cockpit asset URL.
+ *
+ * @param url - The URL to extract from
+ * @returns The asset ID if valid assets:// URL, null otherwise
+ *
+ * @example
+ * ```typescript
+ * extractAssetId("assets://xyz789") // "xyz789"
+ * extractAssetId("pages://123") // null
+ * extractAssetId("https://example.com") // null
+ * ```
+ */
+export function extractAssetId(url) {
+    const parsed = parseCockpitUrl(url);
+    return parsed?.protocol === "assets" ? parsed.id : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unchainedshop/cockpit-api",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "A package to interact with the Cockpit CMS API, including functionalities to handle GraphQL requests and various CMS content manipulations.",
   "main": "dist/index.js",
   "homepage": "https://unchained.shop",