@unchainedshop/cockpit-api 2.2.2 → 2.3.1

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/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

@@ -34,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/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.2",
+  "version": "2.3.1",
   "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",
@@ -55,7 +55,7 @@
   },
   "types": "dist/index.d.ts",
   "peerDependencies": {
-    "@graphql-tools/wrap": "11.1.4",
+    "@graphql-tools/wrap": "^10.0.0 || ^11.0.0",
     "graphql": "^15.0.0 || ^16.0.0"
   },
   "peerDependenciesMeta": {