@unchainedshop/cockpit-api 2.2.0 → 2.2.2

package/README.md

@@ -103,13 +103,17 @@ const localizedPost = await cockpit.getContentItem({
   queryParams: { fields: { title: 1, content: 1 } }
 });
 
-// Get multiple content items with pagination
-const posts = await cockpit.getContentItems('posts', {
+// Get multiple content items - always returns { data, meta? }
+const response = await cockpit.getContentItems('posts', {
   limit: 10,
-  skip: 0,
   sort: { _created: -1 },
   filter: { published: true }
 });
+// response: { data: Post[], meta?: { total: number } } | null
+
+// Access items and metadata
+const items = response?.data || [];
+const total = response?.meta?.total;
 
 // Get tree structure
 const tree = await cockpit.getContentTree('categories', {
@@ -133,8 +137,10 @@ await cockpit.deleteContentItem('posts', '123');
 ### Pages
 
 ```typescript
-// List pages
-const allPages = await cockpit.pages({ locale: 'en', limit: 50 });
+// List pages - always returns { data, meta? }
+const response = await cockpit.pages({ locale: 'en', limit: 50 });
+const allPages = response?.data || [];
+const total = response?.meta?.total;
 
 // Get page by ID
 const page = await cockpit.pageById({ page: 'blog', id: '123', locale: 'en' });
@@ -206,9 +212,9 @@ const image = await cockpit.imageAssetById('asset-id', {
 // Health check
 const health = await cockpit.healthCheck();
 
-// Clear cache
-cockpit.clearCache();  // Clear all
-cockpit.clearCache('pages');  // Clear by pattern
+// Clear cache (async in v2.2.0+)
+await cockpit.clearCache();  // Clear all
+await cockpit.clearCache('pages');  // Clear by pattern
 ```
 
 ## Lightweight Fetch Client API
@@ -228,9 +234,16 @@ const cockpit = createFetchClient({
 
 // Available methods
 const page = await cockpit.pageByRoute('/about', { locale: 'en' });
-const pages = await cockpit.pages({ locale: 'en' });
+
+// List methods return { data, meta? }
+const pagesResponse = await cockpit.pages({ locale: 'en' });
+const pages = pagesResponse?.data || [];
+
 const pageById = await cockpit.pageById('blog', '123', { locale: 'en' });
-const items = await cockpit.getContentItems('news', { locale: 'en', limit: 10 });
+
+const itemsResponse = await cockpit.getContentItems('news', { locale: 'en', limit: 10 });
+const items = itemsResponse?.data || [];
+
 const item = await cockpit.getContentItem('news', '123', { locale: 'en' });
 const custom = await cockpit.fetchRaw('/custom/endpoint', { param: 'value' });
 ```
@@ -275,7 +288,10 @@ const cockpit = await CockpitAPI({
   cache: {
     max: 100,                   // Falls back to COCKPIT_CACHE_MAX (default: 100)
     ttl: 100000,                // Falls back to COCKPIT_CACHE_TTL (default: 100000)
+    store: customStore,         // Optional: custom async cache store (Redis, Keyv, etc.)
   },
+  // Or disable caching entirely
+  // cache: false,
 });
 ```
 
@@ -305,6 +321,79 @@ const { tenant, slug } = resolveTenantFromUrl('https://mytenant.example.com/page
 const allTenants = getTenantIds();  // From COCKPIT_SECRET_* env vars
 ```
 
+## Custom Cache Stores
+
+v2.2.0+ supports pluggable async cache stores for Redis, Keyv, or custom implementations:
+
+```typescript
+import { createClient } from 'redis';
+import type { AsyncCacheStore } from '@unchainedshop/cockpit-api';
+
+// Redis example
+const redisClient = createClient({ url: process.env.REDIS_URL });
+await redisClient.connect();
+
+const redisStore: AsyncCacheStore = {
+  async get(key: string) {
+    const value = await redisClient.get(key);
+    return value ? JSON.parse(value) : undefined;
+  },
+  async set(key: string, value: unknown) {
+    await redisClient.set(key, JSON.stringify(value), { EX: 100 });
+  },
+  async clear(pattern?: string) {
+    if (pattern) {
+      const keys = await redisClient.keys(`${pattern}*`);
+      if (keys.length > 0) await redisClient.del(keys);
+    } else {
+      await redisClient.flushDb();
+    }
+  }
+};
+
+const cockpit = await CockpitAPI({
+  endpoint: 'https://cms.example.com/api/graphql',
+  cache: { store: redisStore }
+});
+```
+
+## Response Format (v3.0.0+)
+
+All list methods return a **consistent response format** regardless of parameters:
+
+```typescript
+interface CockpitListResponse<T> {
+  data: T[];
+  meta?: CockpitListMeta;  // Present when using pagination (skip parameter)
+}
+```
+
+### Methods with Consistent Response Format
+
+- `getContentItems()` - Always returns `CockpitListResponse<T> | null`
+- `pages()` - Always returns `CockpitListResponse<T> | null`
+- Fetch client methods - Always return `CockpitListResponse<T> | null`
+
+### Usage Example
+
+```typescript
+import type { CockpitListResponse } from '@unchainedshop/cockpit-api';
+
+// Always get { data, meta? } format
+const response = await cockpit.getContentItems('posts', { limit: 10, skip: 0 });
+
+// Access items
+const items = response?.data || [];
+
+// Access metadata (available when using skip parameter)
+const total = response?.meta?.total;
+```
+
+**Benefits:**
+- No need to check if response is array or object
+- Predictable type signatures
+- Easier to work with pagination
+
 ## TypeScript Support
 
 ```typescript
@@ -314,6 +403,7 @@ import type {
   CockpitAPIOptions,
   CacheManager,
   CacheOptions,
+  AsyncCacheStore,
 
   // Query Options
   ContentItemQueryOptions,
@@ -330,6 +420,8 @@ import type {
   CockpitRoute,
   CockpitSearchResult,
   CockpitContentItem,
+  CockpitListResponse,   // New: for paginated content responses
+  CockpitListMeta,       // New: metadata in paginated responses
 
   // Schema Types
   MakeCockpitSchemaOptions,
@@ -360,6 +452,77 @@ import { ImageSizeMode, MimeType } from '@unchainedshop/cockpit-api';
 - `defaultLanguage` option to configure which language maps to Cockpit's "default" locale
 - Expanded tenant utilities: `resolveTenantFromUrl()`, `resolveTenantFromSubdomain()`
 
+### v2.2.0 (Breaking Changes)
+
+**Async Cache Operations:**
+- All cache operations are now async and return Promises
+- `await cockpit.clearCache()` is now required (was synchronous in v2.1.x)
+- Custom cache stores can be provided via `cache.store` option
+- Cache can be explicitly disabled with `cache: false`
+
+**Migration:**
+```typescript
+// Before (v2.1.x)
+cockpit.clearCache();
+cockpit.clearCache('ROUTE');
+
+// After (v2.2.0)
+await cockpit.clearCache();
+await cockpit.clearCache('ROUTE');
+```
+
+### v3.0.0 (Breaking Changes)
+
+**Consistent List Response Format:**
+
+All list methods now return `CockpitListResponse<T> | null` instead of varying between arrays and wrapped responses:
+
+**Changed Methods:**
+- `getContentItems()` - Now always returns `{ data: T[], meta?: {...} } | null`
+- `pages()` - Now always returns `{ data: T[], meta?: {...} } | null`
+- Fetch client `getContentItems()` and `pages()` - Now always return `{ data: T[], meta?: {...} } | null`
+
+**Migration:**
+```typescript
+// Before (v2.x)
+const items = await cockpit.getContentItems('posts', { limit: 10 });
+// items could be Post[] or null
+
+const pages = await cockpit.pages({ limit: 10 });
+// pages could be Page[] or null
+
+// After (v3.0.0)
+const itemsResponse = await cockpit.getContentItems('posts', { limit: 10 });
+const items = itemsResponse?.data || [];
+const total = itemsResponse?.meta?.total;
+
+const pagesResponse = await cockpit.pages({ limit: 10 });
+const pages = pagesResponse?.data || [];
+const total = pagesResponse?.meta?.total;
+```
+
+**Benefits:**
+- Single, predictable return type for all list methods
+- No need to check `Array.isArray()` or normalize responses
+- Cleaner TypeScript types
+- Metadata always accessible via `.meta` property
+
+**TreeQueryOptions Type Correction:**
+
+`TreeQueryOptions` no longer incorrectly includes `limit` and `skip` parameters (which were always ignored). Tree structures use `parent`, `populate`, `filter`, and `fields` instead.
+
+```typescript
+// Before (v2.x) - allowed but ignored
+await cockpit.getContentTree('categories', { limit: 10 });  // ❌ TypeScript allowed this
+
+// After (v3.0.0) - TypeScript prevents invalid usage
+await cockpit.getContentTree('categories', {
+  parent: 'root-id',  // ✅ Correct
+  populate: 2,        // ✅ Correct
+  filter: { active: true }  // ✅ Correct
+});
+```
+
 ## Peer Dependencies
 
 - `graphql` (optional) - Required for the `graphQL()` method

package/dist/client.d.ts

@@ -3,7 +3,7 @@
  */
 import type { DocumentNode } from "graphql";
 import { type CockpitAPIOptions } from "./core/config.ts";
-import { type ContentItemQueryOptions, type ContentListQueryOptions, type TreeQueryOptions, type AggregateQueryOptions, type CockpitContentItem, type CockpitTreeNode } from "./methods/content.ts";
+import { type ContentItemQueryOptions, type ContentListQueryOptions, type TreeQueryOptions, type AggregateQueryOptions, type CockpitContentItem, type CockpitTreeNode, type CockpitListResponse } from "./methods/content.ts";
 import { type PageByIdOptions, type CockpitPage } from "./methods/pages.ts";
 import { type MenuQueryOptions, type CockpitMenu } from "./methods/menus.ts";
 import { type CockpitRoutesResponse, type CockpitSitemapEntry, type CockpitSettings } from "./methods/routes.ts";
@@ -16,12 +16,12 @@ import { type LocalizeOptions } from "./methods/localize.ts";
 export interface CockpitAPIClient {
     graphQL<T = unknown>(document: DocumentNode, variables?: Record<string, unknown>): Promise<T | null>;
     getContentItem<T = unknown>(options: ContentItemQueryOptions): Promise<T | null>;
-    getContentItems<T = CockpitContentItem>(model: string, options?: ContentListQueryOptions): Promise<T[] | null>;
+    getContentItems<T = CockpitContentItem>(model: string, options?: ContentListQueryOptions): Promise<CockpitListResponse<T> | null>;
     getContentTree<T = CockpitContentItem>(model: string, options?: TreeQueryOptions): Promise<CockpitTreeNode<T>[] | null>;
     getAggregateModel<T = unknown>(options: AggregateQueryOptions): Promise<T[] | null>;
     postContentItem<T = unknown>(model: string, item: Record<string, unknown>): Promise<T | null>;
     deleteContentItem<T = unknown>(model: string, id: string): Promise<T | null>;
-    pages<T = CockpitPage>(options?: ContentListQueryOptions): Promise<T[] | null>;
+    pages<T = CockpitPage>(options?: ContentListQueryOptions): Promise<CockpitListResponse<T> | null>;
     pageById<T = CockpitPage>(id: string, options?: PageByIdOptions): Promise<T | null>;
     pageByRoute<T = CockpitPage>(route: string, options?: {
         locale?: string;
@@ -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/fetch/client.d.ts

@@ -9,7 +9,7 @@
  * - Minimal memory footprint
  */
 import type { CockpitPage } from "../methods/pages.ts";
-import type { CockpitContentItem } from "../methods/content.ts";
+import type { CockpitContentItem, CockpitListResponse } from "../methods/content.ts";
 /**
  * Request cache mode for fetch requests
  */
@@ -52,12 +52,12 @@ export interface PageFetchParams {
 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 pages list. Always returns { data, meta? } or null. */
+    pages<T = CockpitPage>(params?: PageFetchParams): Promise<CockpitListResponse<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 content items. Always returns { data, meta? } or null. */
+    getContentItems<T = CockpitContentItem>(model: string, params?: PageFetchParams): Promise<CockpitListResponse<T> | null>;
     /** Fetch a single content item */
     getContentItem<T = unknown>(model: string, id?: string, params?: PageFetchParams): Promise<T | null>;
     /** Raw fetch for custom paths */

package/dist/fetch/client.js

@@ -96,10 +96,18 @@ export function createFetchClient(options = {}) {
          */
         async pages(params = {}) {
             const { locale, ...rest } = params;
-            return fetchRaw("/pages/pages", {
+            const result = await fetchRaw("/pages/pages", {
                 locale: normalizeLocale(locale),
                 ...rest,
             });
+            // Normalize response to always return { data, meta? }
+            if (result === null) {
+                return null;
+            }
+            if (Array.isArray(result)) {
+                return { data: result };
+            }
+            return result;
         },
         /**
          * Fetch a page by ID
@@ -117,10 +125,18 @@ export function createFetchClient(options = {}) {
          */
         async getContentItems(model, params = {}) {
             const { locale, ...rest } = params;
-            return fetchRaw(`/content/items/${model}`, {
+            const result = await fetchRaw(`/content/items/${model}`, {
                 locale: normalizeLocale(locale),
                 ...rest,
             });
+            // Normalize response to always return { data, meta? }
+            if (result === null) {
+                return null;
+            }
+            if (Array.isArray(result)) {
+                return { data: result };
+            }
+            return result;
         },
         /**
          * Fetch a single content item

package/dist/index.d.ts

@@ -18,7 +18,7 @@ export type { PageByIdOptions, PageByRouteOptions } from "./methods/pages.ts";
 export type { MenuQueryOptions } from "./methods/menus.ts";
 export type { SearchQueryOptions } from "./methods/search.ts";
 export type { LocalizeOptions } from "./methods/localize.ts";
-export type { CockpitContentItem, CockpitNewsItem, CockpitTreeNode, } from "./methods/content.ts";
+export type { CockpitContentItem, CockpitNewsItem, CockpitTreeNode, CockpitListResponse, CockpitListMeta, } from "./methods/content.ts";
 export { ImageSizeMode, MimeType } from "./methods/assets.ts";
 export type { CockpitAsset, ImageAssetQueryParams } from "./methods/assets.ts";
 export type { CockpitPageType, CockpitPageMeta, CockpitPageSeo, CockpitLayoutBlock, CockpitPage, } from "./methods/pages.ts";

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/content.d.ts

@@ -30,9 +30,15 @@ export interface ContentItemQueryOptions extends ListQueryOptions {
 export interface ContentListQueryOptions extends ListQueryOptions {
     queryParams?: Record<string, unknown>;
 }
-export interface TreeQueryOptions extends ListQueryOptions {
+export interface TreeQueryOptions {
     parent?: string;
+    filter?: Record<string, unknown>;
+    fields?: Record<string, 0 | 1>;
+    populate?: number;
+    locale?: string;
     queryParams?: Record<string, unknown>;
+    /** Override the client-level useAdminAccess setting for this request */
+    useAdminAccess?: boolean;
 }
 export interface AggregateQueryOptions {
     model: string;
@@ -66,9 +72,35 @@ export interface CockpitTreeNode<T = CockpitContentItem> {
     children?: CockpitTreeNode<T>[];
     data?: T;
 }
+/**
+ * Metadata returned with paginated content responses
+ */
+export interface CockpitListMeta {
+    total?: number;
+    [key: string]: unknown;
+}
+/**
+ * Wrapper response format returned by Cockpit when using pagination (skip parameter)
+ */
+export interface CockpitListResponse<T> {
+    data: T[];
+    meta?: CockpitListMeta;
+}
 export interface ContentMethods {
     getContentItem<T = unknown>(options: ContentItemQueryOptions): Promise<T | null>;
-    getContentItems<T = CockpitContentItem>(model: string, options?: ContentListQueryOptions): Promise<T[] | null>;
+    /**
+     * Get multiple content items from a collection.
+     *
+     * @returns Always returns `CockpitListResponse<T>` with data and optional meta.
+     * Returns `null` if collection doesn't exist.
+     *
+     * @example
+     * const response = await cockpit.getContentItems('posts', { limit: 10 });
+     * // response: { data: Post[], meta?: { total: number } } | null
+     * const items = response?.data || [];
+     * const total = response?.meta?.total;
+     */
+    getContentItems<T = CockpitContentItem>(model: string, options?: ContentListQueryOptions): Promise<CockpitListResponse<T> | null>;
     getContentTree<T = CockpitContentItem>(model: string, options?: TreeQueryOptions): Promise<CockpitTreeNode<T>[] | null>;
     getAggregateModel<T = unknown>(options: AggregateQueryOptions): Promise<T[] | null>;
     postContentItem<T = unknown>(model: string, item: Record<string, unknown>): Promise<T | null>;

package/dist/methods/content.js

@@ -33,7 +33,15 @@ export function createContentMethods(ctx) {
                     populate,
                 },
             });
-            return ctx.http.fetch(url, buildFetchOptions(useAdminAccess));
+            const result = await ctx.http.fetch(url, buildFetchOptions(useAdminAccess));
+            // Normalize response to always return { data, meta? }
+            if (result === null) {
+                return null;
+            }
+            if (Array.isArray(result)) {
+                return { data: result };
+            }
+            return result;
         },
         async getContentTree(model, options = {}) {
             requireParam(model, "a model");

package/dist/methods/pages.d.ts

@@ -1,7 +1,7 @@
 /**
  * Pages API methods
  */
-import type { MethodContext, ContentListQueryOptions } from "./content.ts";
+import type { MethodContext, ContentListQueryOptions, CockpitListResponse } from "./content.ts";
 import type { CockpitAsset } from "./assets.ts";
 export interface PageByIdOptions {
     locale?: string;
@@ -42,7 +42,19 @@ export interface CockpitPage extends CockpitPageMeta {
     _p?: string;
 }
 export interface PagesMethods {
-    pages<T = CockpitPage>(options?: ContentListQueryOptions): Promise<T[] | null>;
+    /**
+     * Get pages list.
+     *
+     * @returns Always returns `CockpitListResponse<T>` with data and optional meta.
+     * Returns `null` if pages cannot be fetched.
+     *
+     * @example
+     * const response = await cockpit.pages({ limit: 10, skip: 0 });
+     * // response: { data: CockpitPage[], meta?: { total: number } } | null
+     * const pages = response?.data || [];
+     * const total = response?.meta?.total;
+     */
+    pages<T = CockpitPage>(options?: ContentListQueryOptions): Promise<CockpitListResponse<T> | null>;
     pageById<T = CockpitPage>(id: string, options?: PageByIdOptions): Promise<T | null>;
     pageByRoute<T = CockpitPage>(route: string, options?: PageByRouteOptions | string): Promise<T | null>;
 }

package/dist/methods/pages.js

@@ -10,7 +10,18 @@ export function createPagesMethods(ctx) {
                 locale,
                 queryParams: { ...queryParams, limit, skip, sort, filter, fields },
             });
-            return ctx.http.fetch(url);
+            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;
+            }
+            if (Array.isArray(result)) {
+                return { data: result };
+            }
+            return result;
         },
         async pageById(id, options = {}) {
             requireParam(id, "a page id");

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unchainedshop/cockpit-api",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "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",