@unchainedshop/cockpit-api 2.1.2 → 2.2.1

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;
@@ -48,7 +48,25 @@ export interface CockpitAPIClient {
      */
     imageAssetById(assetId: string, queryParams?: ImageAssetQueryParams): Promise<string | null>;
     getFullRouteForSlug(slug: string): Promise<string | undefined>;
-    clearCache(pattern?: string): void;
+    /**
+     * Clear cache entries matching pattern
+     *
+     * **BREAKING CHANGE (v3.0.0)**: This method is now async and returns a Promise
+     *
+     * @param pattern - Optional pattern to clear specific cache entries
+     * @returns Promise that resolves when clearing is complete
+     *
+     * @example Clear all cache
+     * ```typescript
+     * await client.clearCache();
+     * ```
+     *
+     * @example Clear route cache only
+     * ```typescript
+     * await client.clearCache('ROUTE');
+     * ```
+     */
+    clearCache(pattern?: string): Promise<void>;
 }
 /**
  * Creates a Cockpit API client

package/dist/client.js

@@ -2,7 +2,7 @@
  * Cockpit API Client Factory
  */
 import { createConfig } from "./core/config.js";
-import { createCacheManager } from "./core/cache.js";
+import { createCacheManager, createNoOpCacheManager, } from "./core/cache.js";
 import { createUrlBuilder } from "./core/url-builder.js";
 import { createHttpClient } from "./core/http.js";
 import { createImagePathTransformer } from "./transformers/image-path.js";
@@ -39,19 +39,40 @@ export async function CockpitAPI(options = {}) {
     // Create configuration
     const config = createConfig(options);
     const endpointString = config.endpoint.toString();
-    // Create cache manager - env vars take precedence, then options, then cache.ts defaults
-    const envCacheMax = process.env["COCKPIT_CACHE_MAX"];
-    const envCacheTtl = process.env["COCKPIT_CACHE_TTL"];
-    const cacheOptions = {};
-    const maxValue = options.cache?.max ??
-        (envCacheMax !== undefined ? parseInt(envCacheMax, 10) : undefined);
-    const ttlValue = options.cache?.ttl ??
-        (envCacheTtl !== undefined ? parseInt(envCacheTtl, 10) : undefined);
-    if (maxValue !== undefined)
-        cacheOptions.max = maxValue;
-    if (ttlValue !== undefined)
-        cacheOptions.ttl = ttlValue;
-    const cache = createCacheManager(config.cachePrefix, cacheOptions);
+    // Create cache manager based on options
+    let cache;
+    if (options.cache === false) {
+        // Cache explicitly disabled - use no-op cache
+        cache = createNoOpCacheManager();
+    }
+    else {
+        // Cache enabled - determine options
+        const envCacheMax = process.env["COCKPIT_CACHE_MAX"];
+        const envCacheTtl = process.env["COCKPIT_CACHE_TTL"];
+        const cacheOptions = {};
+        // If custom store provided, use it directly
+        if (options.cache && "store" in options.cache) {
+            cacheOptions.store = options.cache.store;
+        }
+        else {
+            // Use max/ttl from options or env vars (for default LRU store)
+            const maxValue = options.cache && "max" in options.cache
+                ? options.cache.max
+                : envCacheMax !== undefined
+                    ? parseInt(envCacheMax, 10)
+                    : undefined;
+            const ttlValue = options.cache && "ttl" in options.cache
+                ? options.cache.ttl
+                : envCacheTtl !== undefined
+                    ? parseInt(envCacheTtl, 10)
+                    : undefined;
+            if (maxValue !== undefined)
+                cacheOptions.max = maxValue;
+            if (ttlValue !== undefined)
+                cacheOptions.ttl = ttlValue;
+        }
+        cache = createCacheManager(config.cachePrefix, cacheOptions);
+    }
     // Generate route replacements for image path transformer (optional)
     const routeReplacements = options.preloadRoutes === true
         ? await generateCmsRouteReplacements(endpointString, options.tenant, cache)

package/dist/core/cache.d.ts

@@ -1,19 +1,207 @@
 /**
- * Cache management with LRU cache and tenant isolation
+ * Cache management with pluggable async stores and tenant isolation
+ *
+ * v3.0.0 Breaking Change: All cache operations are now async
+ */
+/**
+ * Async cache store interface that custom cache implementations must implement
+ *
+ * @example Redis implementation
+ * ```typescript
+ * import { createClient } from 'redis';
+ * import type { AsyncCacheStore } from '@unchainedshop/cockpit-api';
+ *
+ * const redisClient = createClient({ url: 'redis://localhost:6379' });
+ * 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();
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example Keyv implementation
+ * ```typescript
+ * import Keyv from 'keyv';
+ * import type { AsyncCacheStore } from '@unchainedshop/cockpit-api';
+ *
+ * const keyv = new Keyv('redis://localhost:6379');
+ *
+ * const keyvStore: AsyncCacheStore = {
+ *   async get(key: string) {
+ *     return await keyv.get(key);
+ *   },
+ *   async set(key: string, value: unknown) {
+ *     await keyv.set(key, value, 100000); // 100000ms TTL
+ *   },
+ *   async clear(pattern?: string) {
+ *     if (!pattern) {
+ *       await keyv.clear();
+ *     }
+ *     // Note: Keyv doesn't have native pattern matching
+ *     // Pattern matching requires custom implementation
+ *   }
+ * };
+ * ```
+ */
+export interface AsyncCacheStore {
+    /**
+     * Retrieve a value from cache
+     * @param key - Cache key
+     * @returns Promise resolving to the cached value, or undefined if not found
+     */
+    get(key: string): Promise<unknown>;
+    /**
+     * Store a value in cache
+     * @param key - Cache key
+     * @param value - Value to store (must be serializable for external stores)
+     * @returns Promise that resolves when storage is complete
+     */
+    set(key: string, value: NonNullable<unknown>): Promise<void>;
+    /**
+     * Clear cache entries
+     * @param pattern - Optional pattern to match keys (implementation-specific)
+     *                  If not provided, clears all entries
+     * @returns Promise that resolves when clearing is complete
+     */
+    clear(pattern?: string): Promise<void>;
+}
+/**
+ * Cache configuration options
  */
 export interface CacheOptions {
-    /** Maximum number of entries (default: 100) */
+    /**
+     * Maximum number of entries (default: 100)
+     * Only used with default LRU store. Ignored when custom store is provided.
+     */
     max?: number;
-    /** Time-to-live in milliseconds (default: 100000) */
+    /**
+     * Time-to-live in milliseconds (default: 100000)
+     * Only used with default LRU store. Ignored when custom store is provided.
+     */
     ttl?: number;
+    /**
+     * Custom async cache store implementation
+     * If provided, max and ttl options are ignored
+     *
+     * @example Redis store
+     * ```typescript
+     * import { createClient } from 'redis';
+     *
+     * const redisClient = createClient();
+     * await redisClient.connect();
+     *
+     * const client = await CockpitAPI({
+     *   endpoint: 'https://cms.example.com/api/graphql',
+     *   cache: {
+     *     store: {
+     *       async get(key) {
+     *         const val = await redisClient.get(key);
+     *         return val ? JSON.parse(val) : undefined;
+     *       },
+     *       async set(key, value) {
+     *         await redisClient.set(key, JSON.stringify(value), { EX: 100 });
+     *       },
+     *       async clear(pattern) {
+     *         if (pattern) {
+     *           const keys = await redisClient.keys(`${pattern}*`);
+     *           if (keys.length > 0) await redisClient.del(keys);
+     *         } else {
+     *           await redisClient.flushDb();
+     *         }
+     *       }
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    store?: AsyncCacheStore;
 }
+/**
+ * Async cache manager interface
+ * All cache operations return promises in v3.0.0+
+ */
 export interface CacheManager {
-    get(key: string): unknown;
-    set(key: string, value: NonNullable<unknown>): void;
-    clear(pattern?: string): void;
+    /**
+     * Get a value from cache
+     * @param key - Cache key (will be prefixed internally)
+     * @returns Promise resolving to cached value or undefined if not found
+     */
+    get(key: string): Promise<unknown>;
+    /**
+     * Set a value in cache
+     * @param key - Cache key (will be prefixed internally)
+     * @param value - Value to cache
+     * @returns Promise that resolves when caching is complete
+     */
+    set(key: string, value: NonNullable<unknown>): Promise<void>;
+    /**
+     * Clear cache entries matching pattern
+     * @param pattern - Optional pattern to match (relative to cache prefix)
+     * @returns Promise that resolves when clearing is complete
+     */
+    clear(pattern?: string): Promise<void>;
 }
 /**
- * Creates a cache manager with prefixed keys
- * Each call creates a new LRU cache instance - no shared state
+ * Creates a cache manager with prefixed keys and async operations
+ * Each call creates a new cache instance - no shared state
+ *
+ * @param cachePrefix - Prefix for all cache keys (includes endpoint and tenant)
+ * @param options - Cache configuration options
+ * @returns Async cache manager
+ *
+ * @example Using default LRU cache
+ * ```typescript
+ * const cache = createCacheManager('https://cms.example.com:default:', {
+ *   max: 100,
+ *   ttl: 100000
+ * });
+ *
+ * await cache.set('key1', { data: 'value' });
+ * const value = await cache.get('key1');
+ * await cache.clear('ROUTE');
+ * ```
+ *
+ * @example Using custom Redis store
+ * ```typescript
+ * const redisClient = createClient();
+ * await redisClient.connect();
+ *
+ * const cache = createCacheManager('https://cms.example.com:default:', {
+ *   store: {
+ *     async get(key) { ... },
+ *     async set(key, value) { ... },
+ *     async clear(pattern) { ... }
+ *   }
+ * });
+ * ```
  */
 export declare function createCacheManager(cachePrefix: string, options?: CacheOptions): CacheManager;
+/**
+ * Creates a no-op cache manager that doesn't cache anything
+ * Used when caching is explicitly disabled
+ *
+ * @returns No-op cache manager
+ *
+ * @example
+ * ```typescript
+ * const cache = createNoOpCacheManager();
+ * await cache.set('key', 'value'); // Does nothing
+ * const result = await cache.get('key'); // Always returns undefined
+ * await cache.clear(); // Does nothing
+ * ```
+ */
+export declare function createNoOpCacheManager(): CacheManager;

package/dist/core/cache.js

@@ -1,32 +1,119 @@
 /**
- * Cache management with LRU cache and tenant isolation
+ * Cache management with pluggable async stores and tenant isolation
+ *
+ * v3.0.0 Breaking Change: All cache operations are now async
  */
 import { LRUCache } from "lru-cache";
 /**
- * Creates a cache manager with prefixed keys
- * Each call creates a new LRU cache instance - no shared state
+ * Creates a default LRU-based async cache store
+ * Wraps lru-cache in async interface for consistency
  */
-export function createCacheManager(cachePrefix, options = {}) {
+function createDefaultLRUStore(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));
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async get(key) {
+            return cache.get(key);
         },
-        set(key, value) {
-            cache.set(prefixedKey(key), value);
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async set(key, value) {
+            cache.set(key, value);
         },
-        clear(pattern) {
-            const prefix = pattern !== undefined ? `${cachePrefix}${pattern}` : cachePrefix;
-            for (const key of cache.keys()) {
-                if (key.startsWith(prefix)) {
-                    cache.delete(key);
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async clear(pattern) {
+            if (pattern === undefined) {
+                cache.clear();
+            }
+            else {
+                for (const key of cache.keys()) {
+                    if (key.startsWith(pattern)) {
+                        cache.delete(key);
+                    }
                 }
             }
         },
     };
 }
+/**
+ * Creates a cache manager with prefixed keys and async operations
+ * Each call creates a new cache instance - no shared state
+ *
+ * @param cachePrefix - Prefix for all cache keys (includes endpoint and tenant)
+ * @param options - Cache configuration options
+ * @returns Async cache manager
+ *
+ * @example Using default LRU cache
+ * ```typescript
+ * const cache = createCacheManager('https://cms.example.com:default:', {
+ *   max: 100,
+ *   ttl: 100000
+ * });
+ *
+ * await cache.set('key1', { data: 'value' });
+ * const value = await cache.get('key1');
+ * await cache.clear('ROUTE');
+ * ```
+ *
+ * @example Using custom Redis store
+ * ```typescript
+ * const redisClient = createClient();
+ * await redisClient.connect();
+ *
+ * const cache = createCacheManager('https://cms.example.com:default:', {
+ *   store: {
+ *     async get(key) { ... },
+ *     async set(key, value) { ... },
+ *     async clear(pattern) { ... }
+ *   }
+ * });
+ * ```
+ */
+export function createCacheManager(cachePrefix, options = {}) {
+    // Use custom store if provided, otherwise create default LRU store
+    const store = options.store ?? createDefaultLRUStore(options);
+    const prefixedKey = (key) => `${cachePrefix}${key}`;
+    return {
+        async get(key) {
+            return await store.get(prefixedKey(key));
+        },
+        async set(key, value) {
+            await store.set(prefixedKey(key), value);
+        },
+        async clear(pattern) {
+            const prefix = pattern !== undefined ? `${cachePrefix}${pattern}` : cachePrefix;
+            await store.clear(prefix);
+        },
+    };
+}
+/**
+ * Creates a no-op cache manager that doesn't cache anything
+ * Used when caching is explicitly disabled
+ *
+ * @returns No-op cache manager
+ *
+ * @example
+ * ```typescript
+ * const cache = createNoOpCacheManager();
+ * await cache.set('key', 'value'); // Does nothing
+ * const result = await cache.get('key'); // Always returns undefined
+ * await cache.clear(); // Does nothing
+ * ```
+ */
+export function createNoOpCacheManager() {
+    return {
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async get() {
+            return undefined;
+        },
+        async set() {
+            // No-op
+        },
+        async clear() {
+            // No-op
+        },
+    };
+}

package/dist/core/config.d.ts

@@ -1,6 +1,7 @@
 /**
  * Configuration management for Cockpit API client
  */
+import type { CacheOptions } from "./cache.ts";
 export interface CockpitAPIOptions {
     /** Cockpit CMS endpoint URL (falls back to COCKPIT_GRAPHQL_ENDPOINT env var) */
     endpoint?: string;
@@ -15,13 +16,61 @@ export interface CockpitAPIOptions {
      * When a request uses this language, it will be sent as "default" to Cockpit.
      */
     defaultLanguage?: string | null;
-    /** 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;
-    };
+    /**
+     * Cache configuration
+     *
+     * - Set to `false` to disable caching entirely
+     * - Set to an object to configure cache behavior
+     * - Omit to use default LRU cache with env var fallbacks
+     *
+     * @example Disable cache
+     * ```typescript
+     * const client = await CockpitAPI({
+     *   endpoint: 'https://cms.example.com',
+     *   cache: false
+     * });
+     * ```
+     *
+     * @example Custom cache options
+     * ```typescript
+     * const client = await CockpitAPI({
+     *   endpoint: 'https://cms.example.com',
+     *   cache: { max: 200, ttl: 300000 }
+     * });
+     * ```
+     *
+     * @example Redis store
+     * ```typescript
+     * import { createClient } from 'redis';
+     *
+     * const redisClient = createClient({ url: process.env.REDIS_URL });
+     * await redisClient.connect();
+     *
+     * const client = await CockpitAPI({
+     *   endpoint: 'https://cms.example.com',
+     *   cache: {
+     *     store: {
+     *       async get(key) {
+     *         const val = await redisClient.get(key);
+     *         return val ? JSON.parse(val) : undefined;
+     *       },
+     *       async set(key, value) {
+     *         await redisClient.set(key, JSON.stringify(value), { EX: 100 });
+     *       },
+     *       async clear(pattern) {
+     *         if (pattern) {
+     *           const keys = await redisClient.keys(\`\${pattern}*\`);
+     *           if (keys.length > 0) await redisClient.del(keys);
+     *         } else {
+     *           await redisClient.flushDb();
+     *         }
+     *       }
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    cache?: false | CacheOptions;
     /**
      * Preload route replacements during client initialization.
      * When true, fetches page routes to enable `pages://id` link resolution in responses.

package/dist/core/index.d.ts

@@ -2,8 +2,8 @@
  * Core module exports
  */
 export { buildQueryString, encodeQueryParam } from "./query-string.ts";
-export type { CacheManager, CacheOptions } from "./cache.ts";
-export { createCacheManager } from "./cache.ts";
+export type { CacheManager, CacheOptions, AsyncCacheStore } from "./cache.ts";
+export { createCacheManager, createNoOpCacheManager } from "./cache.ts";
 export type { CockpitConfig } from "./config.ts";
 export { createConfig } from "./config.ts";
 export type { UrlBuilder, UrlBuildOptions } from "./url-builder.ts";

package/dist/core/index.js

@@ -2,7 +2,7 @@
  * Core module exports
  */
 export { buildQueryString, encodeQueryParam } from "./query-string.js";
-export { createCacheManager } from "./cache.js";
+export { createCacheManager, createNoOpCacheManager } from "./cache.js";
 export { createConfig } from "./config.js";
 export { createUrlBuilder } from "./url-builder.js";
 export { createHttpClient } from "./http.js";

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

@@ -6,7 +6,7 @@
 export { CockpitAPI } from "./client.ts";
 export type { CockpitAPIClient } from "./client.ts";
 export type { CockpitAPIOptions } from "./core/config.ts";
-export type { CacheManager, CacheOptions } from "./core/cache.ts";
+export type { CacheManager, CacheOptions, AsyncCacheStore, } from "./core/cache.ts";
 export { getTenantIds, resolveTenantFromUrl, resolveTenantFromSubdomain, } from "./utils/tenant.ts";
 export type { TenantUrlResult, ResolveTenantFromUrlOptions, ResolveTenantFromSubdomainOptions, } from "./utils/tenant.ts";
 export { generateCmsRouteReplacements, generateCollectionAndSingletonSlugRouteMap, } from "./utils/route-map.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/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/menus.d.ts

@@ -24,7 +24,7 @@ export interface CockpitMenuLink {
     meta?: {
         key: string;
         value: string;
-    }[];
+    }[] | Record<string, string>;
 }
 export interface CockpitMenu {
     _id: string;

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,15 @@ 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? }
+            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/system.d.ts

@@ -10,6 +10,24 @@ export interface CockpitHealthCheck {
 }
 export interface SystemMethods {
     healthCheck<T = unknown>(): Promise<T | null>;
-    clearCache(pattern?: string): void;
+    /**
+     * Clear cache entries matching pattern
+     *
+     * **BREAKING CHANGE (v3.0.0)**: This method is now async and returns a Promise
+     *
+     * @param pattern - Optional pattern to clear specific cache entries
+     * @returns Promise that resolves when clearing is complete
+     *
+     * @example Clear all cache
+     * ```typescript
+     * await client.clearCache();
+     * ```
+     *
+     * @example Clear route cache only
+     * ```typescript
+     * await client.clearCache('ROUTE');
+     * ```
+     */
+    clearCache(pattern?: string): Promise<void>;
 }
 export declare function createSystemMethods(ctx: MethodContext): SystemMethods;

package/dist/methods/system.js

@@ -7,8 +7,8 @@ export function createSystemMethods(ctx) {
             const url = ctx.url.build("/system/healthcheck");
             return ctx.http.fetch(url);
         },
-        clearCache(pattern) {
-            ctx.cache.clear(pattern);
+        async clearCache(pattern) {
+            await ctx.cache.clear(pattern);
         },
     };
 }

package/dist/transformers/meta.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Meta transformer for converting Cockpit CMS meta arrays to objects
+ *
+ * This transformer converts meta properties from array format:
+ * meta: [{ key: 'foo', value: 'bar' }]
+ *
+ * To object format:
+ * meta: { foo: 'bar' }
+ */
+import type { ResponseTransformer } from "./image-path.ts";
+/**
+ * Creates a transformer that converts meta arrays to objects.
+ * This transformation affects all meta properties in the response,
+ * including nested ones in children arrays.
+ */
+export declare function createMetaTransformer(): ResponseTransformer;

package/dist/transformers/meta.js

@@ -0,0 +1,52 @@
+/**
+ * Meta transformer for converting Cockpit CMS meta arrays to objects
+ *
+ * This transformer converts meta properties from array format:
+ * meta: [{ key: 'foo', value: 'bar' }]
+ *
+ * To object format:
+ * meta: { foo: 'bar' }
+ */
+import { logger } from "../cockpit-logger.js";
+import { transformCockpitMeta } from "../utils/meta.js";
+/**
+ * Recursively transforms all meta arrays in a data structure to objects
+ */
+function transformMetaRecursive(data) {
+    if (data === null || data === undefined || typeof data !== "object") {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return data.map(transformMetaRecursive);
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (key === "meta" && Array.isArray(value)) {
+            // Transform meta array to object
+            result[key] = transformCockpitMeta(value);
+        }
+        else {
+            // Recursively transform nested objects
+            result[key] = transformMetaRecursive(value);
+        }
+    }
+    return result;
+}
+/**
+ * Creates a transformer that converts meta arrays to objects.
+ * This transformation affects all meta properties in the response,
+ * including nested ones in children arrays.
+ */
+export function createMetaTransformer() {
+    return {
+        transform(originalResponse) {
+            try {
+                return transformMetaRecursive(originalResponse);
+            }
+            catch (error) {
+                logger.warn("Cockpit: Failed to transform meta arrays", error);
+                return originalResponse;
+            }
+        },
+    };
+}

package/dist/utils/meta.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Transforms Cockpit meta array into an object for easier access
+ *
+ * @param meta Array of {key, value} objects from Cockpit API
+ * @returns Object with key-value pairs
+ *
+ * @example
+ * ```typescript
+ * const meta = [
+ *   { key: 'layout', value: 'shop' },
+ *   { key: 'isCallToAction', value: 'true' },
+ * ];
+ * const metaObj = transformCockpitMeta(meta);
+ * if (metaObj.layout === 'shop') {
+ *   // Handle shop layout
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Safe to use with optional meta
+ * const metaObj = transformCockpitMeta(link.meta);
+ * const layout = metaObj.layout ?? 'default';
+ * ```
+ */
+export declare function transformCockpitMeta(meta?: {
+    key: string;
+    value: string;
+}[]): Record<string, string>;

package/dist/utils/meta.js

@@ -0,0 +1,33 @@
+/**
+ * Transforms Cockpit meta array into an object for easier access
+ *
+ * @param meta Array of {key, value} objects from Cockpit API
+ * @returns Object with key-value pairs
+ *
+ * @example
+ * ```typescript
+ * const meta = [
+ *   { key: 'layout', value: 'shop' },
+ *   { key: 'isCallToAction', value: 'true' },
+ * ];
+ * const metaObj = transformCockpitMeta(meta);
+ * if (metaObj.layout === 'shop') {
+ *   // Handle shop layout
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Safe to use with optional meta
+ * const metaObj = transformCockpitMeta(link.meta);
+ * const layout = metaObj.layout ?? 'default';
+ * ```
+ */
+export function transformCockpitMeta(meta) {
+    if (!meta || !Array.isArray(meta))
+        return {};
+    return meta.reduce((acc, { key, value }) => {
+        acc[key] = value;
+        return acc;
+    }, {});
+}

package/dist/utils/route-map.js

@@ -8,7 +8,7 @@ import { logger } from "../cockpit-logger.js";
 export async function generateCmsRouteReplacements(endpoint, tenant, cache) {
     const cacheKey = `ROUTE_REPLACEMENT_MAP:${tenant ?? "default"}`;
     if (cache) {
-        const cached = cache.get(cacheKey);
+        const cached = (await cache.get(cacheKey));
         if (cached)
             return cached;
     }
@@ -31,7 +31,7 @@ export async function generateCmsRouteReplacements(endpoint, tenant, cache) {
             return { ...result, [key]: value };
         }, {});
         if (cache) {
-            cache.set(cacheKey, replacement);
+            await cache.set(cacheKey, replacement);
         }
         return replacement;
     }
@@ -46,7 +46,7 @@ export async function generateCmsRouteReplacements(endpoint, tenant, cache) {
 export async function generateCollectionAndSingletonSlugRouteMap(endpoint, tenant, cache) {
     const cacheKey = `SLUG_ROUTE_MAP:${tenant ?? "default"}`;
     if (cache) {
-        const cached = cache.get(cacheKey);
+        const cached = (await cache.get(cacheKey));
         if (cached)
             return cached;
     }
@@ -75,7 +75,7 @@ export async function generateCollectionAndSingletonSlugRouteMap(endpoint, tenan
             return { ...result, [entityName]: _r };
         }, {});
         if (cache) {
-            cache.set(cacheKey, pageMap);
+            await cache.set(cacheKey, pageMap);
         }
         return pageMap;
     }

package/package.json

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