@unchainedshop/cockpit-api 1.0.34 → 2.1.0

package/README.md

@@ -1,36 +1,80 @@
 # Cockpit API
 
-A package to interact with the Cockpit CMS API, including functionalities to handle GraphQL requests and various CMS content manipulations.
-## Installation
+[![npm version](https://img.shields.io/npm/v/@unchainedshop/cockpit-api.svg)](https://www.npmjs.com/package/@unchainedshop/cockpit-api)
+[![CI](https://github.com/unchainedshop/cockpit-api/actions/workflows/ci.yml/badge.svg)](https://github.com/unchainedshop/cockpit-api/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
+
+A TypeScript client for interacting with [Cockpit CMS](https://github.com/Cockpit-HQ/Cockpit), including GraphQL requests, content management, and schema stitching support.
 
-Install the package via npm:
+## Installation
 
 ```sh
 npm install --save @unchainedshop/cockpit-api
 ```
 
-## Usage
+## Package Exports
 
-### Initialization
+This package provides three entry points:
 
-First, set your cockpit graphql endpoint to env
+| Export | Description |
+|--------|-------------|
+| `@unchainedshop/cockpit-api` | Full-featured async API client with caching and response transformation |
+| `@unchainedshop/cockpit-api/schema` | GraphQL schema stitching utilities |
+| `@unchainedshop/cockpit-api/fetch` | Lightweight client for edge/RSC environments |
 
-```bash
-COCKPIT_GRAPHQL_ENDPOINT
-```
-then import and initialize the API:
+## Quick Start
+
+### Main Client
 
-```javascript
+```typescript
 import { CockpitAPI } from '@unchainedshop/cockpit-api';
 
-const cockpit = await CockpitAPI();
+// With explicit endpoint
+const cockpit = await CockpitAPI({
+  endpoint: 'https://your-cockpit-instance.com/api/graphql',
+});
+
+// Or using environment variables
+const cockpit = await CockpitAPI();  // Uses COCKPIT_GRAPHQL_ENDPOINT
 ```
 
-### GraphQL Requests
+### Lightweight Fetch Client (Edge/RSC)
+
+```typescript
+import { createFetchClient } from '@unchainedshop/cockpit-api/fetch';
+
+// Synchronous initialization - no await needed
+const cockpit = createFetchClient({
+  endpoint: process.env.NEXT_PUBLIC_COCKPIT_ENDPOINT,
+  tenant: 'mytenant',
+  cache: 'force-cache',  // Uses platform caching
+});
+
+const page = await cockpit.pageByRoute('/about', { locale: 'en' });
+```
 
-You can make GraphQL requests using the `graphQL` method:
+### GraphQL Schema Stitching
 
-```javascript
+```typescript
+import { makeCockpitGraphQLSchema } from '@unchainedshop/cockpit-api/schema';
+import { stitchSchemas } from '@graphql-tools/stitch';
+
+const cockpitSchema = await makeCockpitGraphQLSchema({
+  tenantHeader: 'x-cockpit-space',
+  filterMutations: true,
+});
+
+const gatewaySchema = stitchSchemas({
+  subschemas: [{ schema: cockpitSchema }],
+});
+```
+
+## Main Client API
+
+### GraphQL Requests
+
+```typescript
 import { gql } from 'graphql-tag';
 
 const query = gql`
@@ -43,67 +87,288 @@ const query = gql`
 `;
 
 const result = await cockpit.graphQL(query, {});
-console.log(result);
 ```
 
 ### Content Operations
 
-You can perform various content operations such as fetching items, aggregating models, and manipulating pages.
-
-Example to get a content item:
-
-```javascript
-const contentItem = await cockpit.getContentItem({ model: 'posts', id: '123' });
-console.log(contentItem);
-```
-
-### CockpitAPI
-
-Provides various methods to interact with the Cockpit CMS.
-
-**Methods:**
-- `graphQL(document, variables)`
-- `getContentItem({ model, id }, locale, queryParams)`
-- `getAggregateModel({ model, pipeline }, locale)`
-- `getContentItems(model, locale, queryParams)`
-- `getContentTree(model, locale, queryParams)`
-- `postContentItem(model, item)`
-- `deleteContentItem(model, id)`
-- `pages(locale, queryParams)`
-- `pageById({ page, id }, locale, queryParams)`
-- `pageByRoute(route, locale)`
-- `pagesMenus(locale)`
-- `pagesMenu(name, locale)`
-- `pagesRoutes(locale)`
-- `pagesSitemap()`
-- `pagesSetting(locale)`
-- `healthCheck()`
-- `lokalize(projectName,locale, nested)`
-- `assetById(assetId)`
-- `imageAssetById(assetId, queryParams)`
-- `getFullRouteForSlug(slug)`
-
-### Optional configuration 
-you can change the caching behavior by setting the envs below
- 
+```typescript
+// Get a single content item
+const post = await cockpit.getContentItem({ model: 'posts', id: '123' });
+
+// With locale and field selection
+const localizedPost = await cockpit.getContentItem({
+  model: 'posts',
+  id: '123',
+  locale: 'en',
+  queryParams: { fields: { title: 1, content: 1 } }
+});
+
+// Get multiple content items with pagination
+const posts = await cockpit.getContentItems('posts', {
+  limit: 10,
+  skip: 0,
+  sort: { _created: -1 },
+  filter: { published: true }
+});
+
+// Get tree structure
+const tree = await cockpit.getContentTree('categories', {
+  parent: 'root-id',
+  populate: 2
+});
+
+// Aggregation pipeline
+const stats = await cockpit.getAggregateModel({
+  model: 'orders',
+  pipeline: [{ $group: { _id: '$status', count: { $sum: 1 } } }]
+});
+
+// Create content item
+const newPost = await cockpit.postContentItem('posts', { title: 'New Post' });
+
+// Delete content item
+await cockpit.deleteContentItem('posts', '123');
+```
+
+### Pages
+
+```typescript
+// List pages
+const allPages = await cockpit.pages({ locale: 'en', limit: 50 });
+
+// Get page by ID
+const page = await cockpit.pageById({ page: 'blog', id: '123', locale: 'en' });
+
+// Get page by route
+const aboutPage = await cockpit.pageByRoute('/about', { locale: 'en', populate: 2 });
+```
+
+### Menus
+
+```typescript
+// Get all menus
+const menus = await cockpit.pagesMenus({ locale: 'en' });
+
+// Get specific menu
+const mainMenu = await cockpit.pagesMenu('main-navigation', { locale: 'en' });
+```
+
+### Routes & Sitemap
+
+```typescript
+const routes = await cockpit.pagesRoutes('en');
+const sitemap = await cockpit.pagesSitemap();
+const settings = await cockpit.pagesSetting('en');
+const fullRoute = await cockpit.getFullRouteForSlug('my-slug');
+```
+
+### Search (Detektivo addon)
+
+```typescript
+const results = await cockpit.search({
+  index: 'products',
+  q: 'search term',
+  limit: 10,
+  offset: 0
+});
+```
+
+### Localization (Lokalize addon)
+
+```typescript
+const translations = await cockpit.localize('my-project', {
+  locale: 'en',
+  nested: true
+});
+```
+
+### Assets
+
+```typescript
+import { ImageSizeMode, MimeType } from '@unchainedshop/cockpit-api';
+
+// Get asset metadata
+const asset = await cockpit.assetById('asset-id');
+
+// Get transformed image
+const image = await cockpit.imageAssetById('asset-id', {
+  m: ImageSizeMode.BestFit,
+  w: 800,
+  h: 600,
+  q: 80,
+  mime: MimeType.WEBP
+});
+```
+
+### System
+
+```typescript
+// Health check
+const health = await cockpit.healthCheck();
+
+// Clear cache
+cockpit.clearCache();  // Clear all
+cockpit.clearCache('pages');  // Clear by pattern
+```
+
+## Lightweight Fetch Client API
+
+The fetch client is designed for edge/RSC environments with minimal overhead:
+
+```typescript
+import { createFetchClient } from '@unchainedshop/cockpit-api/fetch';
+
+const cockpit = createFetchClient({
+  endpoint: process.env.NEXT_PUBLIC_COCKPIT_ENDPOINT,
+  tenant: 'mytenant',
+  cache: 'force-cache',
+  apiKey: 'your-api-key',
+  headers: { 'X-Custom-Header': 'value' }
+});
+
+// Available methods
+const page = await cockpit.pageByRoute('/about', { locale: 'en' });
+const pages = await cockpit.pages({ locale: 'en' });
+const pageById = await cockpit.pageById('blog', '123', { locale: 'en' });
+const items = await cockpit.getContentItems('news', { locale: 'en', limit: 10 });
+const item = await cockpit.getContentItem('news', '123', { locale: 'en' });
+const custom = await cockpit.fetchRaw('/custom/endpoint', { param: 'value' });
+```
+
+## Schema Stitching API
+
+For building GraphQL gateways with Cockpit:
+
+```typescript
+import { makeCockpitGraphQLSchema, createRemoteExecutor } from '@unchainedshop/cockpit-api/schema';
+
+// Create schema for stitching
+const schema = await makeCockpitGraphQLSchema({
+  tenantHeader: 'x-cockpit-space',
+  filterMutations: true,
+  transforms: [],  // Additional GraphQL transforms
+  extractTenant: (ctx) => ctx.req?.headers['x-tenant'],
+  cockpitOptions: {
+    endpoint: 'https://cms.example.com/api/graphql',
+    apiKey: 'your-api-key',
+    useAdminAccess: true
+  }
+});
+
+// Or use the executor directly for custom implementations
+const executor = createRemoteExecutor({
+  tenantHeader: 'x-cockpit-space',
+  cockpitOptions: { endpoint: '...' }
+});
+```
+
+## Configuration Options
+
+```typescript
+const cockpit = await CockpitAPI({
+  endpoint: 'https://...',      // Falls back to COCKPIT_GRAPHQL_ENDPOINT
+  tenant: 'mytenant',           // Optional: for multi-tenant setups
+  apiKey: 'your-api-key',       // Falls back to COCKPIT_SECRET env var
+  useAdminAccess: true,         // Optional: inject api-Key header
+  defaultLanguage: 'de',        // Language that maps to Cockpit's "default" locale (default: "de")
+  preloadRoutes: true,          // Optional: preload route replacements
+  cache: {
+    max: 100,                   // Falls back to COCKPIT_CACHE_MAX (default: 100)
+    ttl: 100000,                // Falls back to COCKPIT_CACHE_TTL (default: 100000)
+  },
+});
+```
+
+## Environment Variables
+
 ```bash
-COCKPIT_CACHE__MAX_LIMIT # number of records to store in before overwriting it
-COCKPIT_CACHE_TTL # caching period in milliseconds
+COCKPIT_GRAPHQL_ENDPOINT=https://your-cockpit-instance.com/api/graphql
+COCKPIT_SECRET=your-api-key                # Default API key
+COCKPIT_SECRET_MYTENANT=tenant-api-key     # Tenant-specific API key
+COCKPIT_CACHE_MAX=100                      # Max cache entries (default: 100)
+COCKPIT_CACHE_TTL=100000                   # Cache TTL in ms (default: 100000)
 ```
 
+## Multi-Tenant Support
+
+```typescript
+// Tenant-specific client
+const cockpit = await CockpitAPI({
+  endpoint: 'https://cms.example.com/api/graphql',
+  tenant: 'mytenant',  // Requests use /:mytenant/api/... path
+});
+
+// Resolve tenant from URL
+import { resolveTenantFromUrl, getTenantIds } from '@unchainedshop/cockpit-api';
+
+const { tenant, slug } = resolveTenantFromUrl('https://mytenant.example.com/page');
+const allTenants = getTenantIds();  // From COCKPIT_SECRET_* env vars
+```
+
+## TypeScript Support
+
+```typescript
+import type {
+  // Client
+  CockpitAPIClient,
+  CockpitAPIOptions,
+  CacheManager,
+  CacheOptions,
+
+  // Query Options
+  ContentItemQueryOptions,
+  ContentListQueryOptions,
+  TreeQueryOptions,
+  PageQueryOptions,
+  SearchQueryOptions,
+  ImageAssetQueryParams,
+
+  // Response Types
+  CockpitPage,
+  CockpitAsset,
+  CockpitMenu,
+  CockpitRoute,
+  CockpitSearchResult,
+  CockpitContentItem,
+
+  // Schema Types
+  MakeCockpitSchemaOptions,
+  CockpitExecutorContext,
+
+  // Fetch Types
+  FetchClientOptions,
+  FetchCacheMode,
+} from '@unchainedshop/cockpit-api';
+
+import { ImageSizeMode, MimeType } from '@unchainedshop/cockpit-api';
+```
+
+## Breaking Changes
+
+### v2.0.0
+
+- `lokalize()` renamed to `localize()`
+- Methods use options objects instead of positional parameters
+- HTTP errors now throw instead of returning `null` (404 still returns `null`)
+- Each client instance has its own cache (no shared state)
+
+### v2.1.0 (New Features)
+
+- `/schema` subpackage for GraphQL schema stitching
+- `/fetch` subpackage for lightweight edge/RSC environments
+- `preloadRoutes` option for preloading route replacements
+- `defaultLanguage` option to configure which language maps to Cockpit's "default" locale
+- Expanded tenant utilities: `resolveTenantFromUrl()`, `resolveTenantFromSubdomain()`
+
+## Peer Dependencies
+
+- `graphql` (optional) - Required for the `graphQL()` method
+- `@graphql-tools/wrap` (optional) - Required for the `/schema` subpackage
+
 ## Contributing
 
 Contributions are welcome! Please open an issue or submit a pull request.
 
-1. Fork the repository.
-2. Create a new branch: `git checkout -b feature-branch-name`.
-3. Make your changes and commit them: `git commit -m 'Add new feature'`.
-4. Push to the branch: `git push origin feature-branch-name`.
-5. Open a pull request.
-
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
-```
-
-This `README.md` covers installation, basic usage, detailed API reference, contribution guidelines, and licensing information. Adjust the details as needed for your specific implementation.

package/dist/client.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Cockpit API Client Factory
+ */
+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 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";
+import { type ImageAssetQueryParams, type CockpitAsset } from "./methods/assets.ts";
+import { type SearchQueryOptions, type CockpitSearchResult } from "./methods/search.ts";
+import { type LocalizeOptions } from "./methods/localize.ts";
+/**
+ * Cockpit API Client interface
+ */
+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>;
+    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>;
+    pageById<T = CockpitPage>(id: string, options?: PageByIdOptions): Promise<T | null>;
+    pageByRoute<T = CockpitPage>(route: string, options?: {
+        locale?: string;
+        populate?: number;
+    } | string): Promise<T | null>;
+    pagesMenus<T = CockpitMenu>(options?: MenuQueryOptions | string): Promise<T[] | null>;
+    pagesMenu<T = CockpitMenu>(name: string, options?: MenuQueryOptions | string): Promise<T | null>;
+    pagesRoutes<T = CockpitRoutesResponse>(locale?: string): Promise<T | null>;
+    pagesSitemap<T = CockpitSitemapEntry>(): Promise<T[] | null>;
+    pagesSetting<T = CockpitSettings>(locale?: string): Promise<T | null>;
+    search<T = CockpitSearchResult>(options: SearchQueryOptions): Promise<T | null>;
+    healthCheck<T = unknown>(): Promise<T | null>;
+    localize<T = unknown>(projectName: string, options?: LocalizeOptions): Promise<T | null>;
+    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.
+     *
+     * @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>;
+    getFullRouteForSlug(slug: string): Promise<string | undefined>;
+    clearCache(pattern?: string): void;
+}
+/**
+ * Creates a Cockpit API client
+ *
+ * @param options - Configuration options (falls back to env vars if not provided)
+ * @returns Promise resolving to the API client
+ *
+ * @example
+ * ```typescript
+ * // With explicit options
+ * const client = await CockpitAPI({
+ *   endpoint: 'https://cms.example.com/api/graphql',
+ *   tenant: 'mytenant',
+ *   useAdminAccess: true,
+ * });
+ *
+ * // Or using environment variables (COCKPIT_GRAPHQL_ENDPOINT, etc.)
+ * const client = await CockpitAPI();
+ * ```
+ */
+export declare function CockpitAPI(options?: CockpitAPIOptions): Promise<CockpitAPIClient>;

package/dist/client.js

@@ -0,0 +1,101 @@
+/**
+ * Cockpit API Client Factory
+ */
+import { createConfig } from "./core/config.js";
+import { createCacheManager } from "./core/cache.js";
+import { createUrlBuilder } from "./core/url-builder.js";
+import { createHttpClient } from "./core/http.js";
+import { createImagePathTransformer } from "./transformers/image-path.js";
+import { generateCmsRouteReplacements } from "./utils/route-map.js";
+import { createContentMethods, } from "./methods/content.js";
+import { createPagesMethods, } from "./methods/pages.js";
+import { createMenuMethods, } from "./methods/menus.js";
+import { createRouteMethods, } from "./methods/routes.js";
+import { createAssetMethods, } from "./methods/assets.js";
+import { createGraphQLMethods } from "./methods/graphql.js";
+import { createSearchMethods, } from "./methods/search.js";
+import { createLocalizeMethods, } from "./methods/localize.js";
+import { createSystemMethods } from "./methods/system.js";
+/**
+ * Creates a Cockpit API client
+ *
+ * @param options - Configuration options (falls back to env vars if not provided)
+ * @returns Promise resolving to the API client
+ *
+ * @example
+ * ```typescript
+ * // With explicit options
+ * const client = await CockpitAPI({
+ *   endpoint: 'https://cms.example.com/api/graphql',
+ *   tenant: 'mytenant',
+ *   useAdminAccess: true,
+ * });
+ *
+ * // Or using environment variables (COCKPIT_GRAPHQL_ENDPOINT, etc.)
+ * const client = await CockpitAPI();
+ * ```
+ */
+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);
+    // Generate route replacements for image path transformer (optional)
+    const routeReplacements = options.preloadRoutes === true
+        ? await generateCmsRouteReplacements(endpointString, options.tenant, cache)
+        : {};
+    // Create response transformer
+    const transformerConfig = {
+        baseUrl: config.endpoint.origin,
+        replacements: routeReplacements,
+    };
+    if (options.tenant !== undefined)
+        transformerConfig.tenant = options.tenant;
+    const transformer = createImagePathTransformer(transformerConfig);
+    // Create URL builder
+    const urlBuilder = createUrlBuilder(config);
+    // Create HTTP client
+    const http = createHttpClient(config, transformer);
+    // Create method context
+    const ctx = {
+        http,
+        url: urlBuilder,
+        cache,
+        endpoint: endpointString,
+        ...(options.tenant !== undefined && { tenant: options.tenant }),
+    };
+    // Create method groups
+    const contentMethods = createContentMethods(ctx);
+    const pagesMethods = createPagesMethods(ctx);
+    const menuMethods = createMenuMethods(ctx);
+    const routeMethods = createRouteMethods(ctx);
+    const assetMethods = createAssetMethods(ctx);
+    const graphqlMethods = createGraphQLMethods(ctx);
+    const searchMethods = createSearchMethods(ctx);
+    const localizeMethods = createLocalizeMethods(ctx);
+    const systemMethods = createSystemMethods(ctx);
+    // Compose the client
+    return {
+        ...contentMethods,
+        ...pagesMethods,
+        ...menuMethods,
+        ...routeMethods,
+        ...assetMethods,
+        ...graphqlMethods,
+        ...searchMethods,
+        ...localizeMethods,
+        ...systemMethods,
+    };
+}

package/dist/cockpit-logger.d.ts

@@ -1,5 +1,8 @@
-import type { Logger } from "@unchainedshop/logger";
-declare let logger: Logger;
-declare const log: (message: any, ...args: any[]) => void;
-export { logger };
-export default log;
+/**
+ * Logger for Cockpit API
+ */
+import { createLogger } from "@unchainedshop/logger";
+type Logger = ReturnType<typeof createLogger>;
+export declare const logger: Logger;
+declare const logInfo: Logger["info"];
+export default logInfo;

package/dist/cockpit-logger.js

@@ -1,20 +1,7 @@
-let logger = {
-    info: console.log,
-    error: console.error,
-    warn: console.warn,
-    debug: console.debug,
-    trace: console.trace,
-};
-async function loadLogger() {
-    try {
-        const { createLogger } = await import("@unchainedshop/logger");
-        logger = createLogger("cockpit") || logger;
-    }
-    catch (e) {
-        // console.warn(e);
-    }
-}
-loadLogger();
-const log = logger.info;
-export { logger };
-export default log;
+/**
+ * Logger for Cockpit API
+ */
+import { createLogger } from "@unchainedshop/logger";
+export const logger = createLogger("cockpit");
+const logInfo = logger.info;
+export default logInfo;

package/dist/core/cache.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cache management with LRU cache and tenant isolation
+ */
+export interface CacheOptions {
+    /** Maximum number of entries (default: 100) */
+    max?: number;
+    /** Time-to-live in milliseconds (default: 100000) */
+    ttl?: number;
+}
+export interface CacheManager {
+    get(key: string): unknown;
+    set(key: string, value: NonNullable<unknown>): void;
+    clear(pattern?: string): void;
+}
+/**
+ * Creates a cache manager with prefixed keys
+ * Each call creates a new LRU cache instance - no shared state
+ */
+export declare function createCacheManager(cachePrefix: string, options?: CacheOptions): CacheManager;