@bernierllc/contentful-cma-client 1.0.2

package/.eslintrc.cjs

@@ -0,0 +1,34 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+    project: './tsconfig.json',
+    tsconfigRootDir: __dirname
+  },
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:@typescript-eslint/recommended-requiring-type-checking'
+  ],
+  rules: {
+    '@typescript-eslint/no-explicit-any': 'warn',
+    '@typescript-eslint/no-unsafe-assignment': 'warn',
+    '@typescript-eslint/no-unsafe-argument': 'warn',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/no-floating-promises': 'error',
+    '@typescript-eslint/no-misused-promises': 'error'
+  },
+  ignorePatterns: ['dist', 'node_modules', '*.cjs', '**/__tests__/**', '**/*.test.ts']
+};

package/README.md

@@ -0,0 +1,441 @@
+# @bernierllc/contentful-cma-client
+
+Thin wrapper around the official `contentful-management` npm package, providing consistent error handling, logging, and typed interfaces for all CMA (Content Management API) operations.
+
+## Installation
+
+```bash
+npm install @bernierllc/contentful-cma-client
+```
+
+## Features
+
+- ✅ **Typed Interfaces** - Full TypeScript support using `@bernierllc/contentful-types`
+- ✅ **Comprehensive CRUD** - Entries, Assets, Content Types operations
+- ✅ **Bulk Operations** - Batch create, update, publish, delete
+- ✅ **Automatic Pagination** - `getAllEntries()` and `getAllAssets()` handle pagination automatically
+- ✅ **Consistent Logging** - Integrated with `@bernierllc/logger`
+- ✅ **Error Handling** - Graceful error handling with detailed logging
+- ✅ **Publishing Workflow** - Publish, unpublish, archive, unarchive support
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { ContentfulCMAClient } from '@bernierllc/contentful-cma-client';
+
+const client = new ContentfulCMAClient({
+  accessToken: 'your-cma-token',
+  spaceId: 'your-space-id',
+  environmentId: 'master' // optional, defaults to 'master'
+});
+```
+
+### Entry Operations
+
+#### Get Entry
+
+```typescript
+const entry = await client.getEntry<BlogPost>('entry-id');
+console.log(entry.fields.title);
+```
+
+#### Get Entries with Query
+
+```typescript
+const entries = await client.getEntries<BlogPost>({
+  content_type: 'blogPost',
+  limit: 10,
+  skip: 0
+});
+```
+
+#### Get All Entries (with automatic pagination)
+
+```typescript
+const allEntries = await client.getAllEntries<BlogPost>({
+  content_type: 'blogPost'
+});
+```
+
+#### Create Entry
+
+```typescript
+const newEntry = await client.createEntry<BlogPost>(
+  'blogPost',
+  {
+    title: { 'en-US': 'My Blog Post' },
+    body: { 'en-US': 'Content here...' }
+  }
+);
+```
+
+#### Create Entry with Custom ID
+
+```typescript
+const newEntry = await client.createEntry<BlogPost>(
+  'blogPost',
+  {
+    title: { 'en-US': 'My Blog Post' }
+  },
+  { entryId: 'custom-entry-id' }
+);
+```
+
+#### Update Entry
+
+```typescript
+const updatedEntry = await client.updateEntry<BlogPost>(
+  'entry-id',
+  {
+    title: { 'en-US': 'Updated Title' }
+  },
+  2 // version number
+);
+```
+
+#### Publish Entry
+
+```typescript
+const publishedEntry = await client.publishEntry('entry-id', 2);
+```
+
+#### Unpublish Entry
+
+```typescript
+await client.unpublishEntry('entry-id');
+```
+
+#### Archive Entry
+
+```typescript
+await client.archiveEntry('entry-id', 2);
+```
+
+#### Unarchive Entry
+
+```typescript
+await client.unarchiveEntry('entry-id');
+```
+
+#### Delete Entry
+
+```typescript
+await client.deleteEntry('entry-id');
+```
+
+### Asset Operations
+
+#### Get Asset
+
+```typescript
+const asset = await client.getAsset('asset-id');
+console.log(asset.fields.file['en-US'].url);
+```
+
+#### Create Asset
+
+```typescript
+const newAsset = await client.createAsset({
+  title: { 'en-US': 'My Image' },
+  file: {
+    'en-US': {
+      url: 'https://example.com/image.jpg',
+      fileName: 'image.jpg',
+      contentType: 'image/jpeg',
+      details: { size: 12345 }
+    }
+  }
+});
+```
+
+#### Process Asset (after upload)
+
+```typescript
+await client.processAsset('asset-id', 1, 'en-US');
+```
+
+#### Publish Asset
+
+```typescript
+const publishedAsset = await client.publishAsset('asset-id', 2);
+```
+
+#### Delete Asset
+
+```typescript
+await client.deleteAsset('asset-id');
+```
+
+### Content Type Operations
+
+#### Get Content Type
+
+```typescript
+const contentType = await client.getContentType('blogPost');
+console.log(contentType.fields);
+```
+
+#### Get All Content Types
+
+```typescript
+const contentTypes = await client.getContentTypes();
+```
+
+### Bulk Operations
+
+#### Bulk Create Entries
+
+```typescript
+const result = await client.bulkCreateEntries([
+  { contentTypeId: 'blogPost', fields: { title: { 'en-US': 'Post 1' } } },
+  { contentTypeId: 'blogPost', fields: { title: { 'en-US': 'Post 2' } } }
+]);
+
+console.log(`Created: ${result.successful.length}`);
+console.log(`Failed: ${result.failed.length}`);
+
+// Handle failures
+result.failed.forEach(failure => {
+  console.error(`Failed to create:`, failure.error);
+});
+```
+
+#### Bulk Publish Entries
+
+```typescript
+const result = await client.bulkPublishEntries([
+  { entryId: 'entry-1', version: 2 },
+  { entryId: 'entry-2', version: 1 }
+]);
+```
+
+#### Bulk Delete Entries
+
+```typescript
+const result = await client.bulkDeleteEntries([
+  'entry-1',
+  'entry-2',
+  'entry-3'
+]);
+```
+
+## Configuration Options
+
+```typescript
+interface ContentfulCMAConfig {
+  accessToken: string;        // Required: CMA access token
+  spaceId: string;            // Required: Contentful space ID
+  environmentId?: string;     // Optional: defaults to 'master'
+  host?: string;              // Optional: defaults to 'api.contentful.com'
+  retryOnError?: boolean;     // Optional: defaults to true
+  timeout?: number;           // Optional: defaults to 30000ms
+}
+```
+
+## Query Options
+
+```typescript
+interface CMAQueryOptions {
+  skip?: number;              // Number of items to skip
+  limit?: number;             // Number of items to return
+  order?: string;             // Sort order (e.g., '-sys.createdAt')
+  locale?: string;            // Locale filter
+  content_type?: string;      // Content type filter
+  [key: string]: any;         // Additional Contentful query params
+}
+```
+
+## Type Safety
+
+This package uses types from `@bernierllc/contentful-types`:
+
+```typescript
+import type {
+  ContentfulEntry,
+  ContentfulAsset,
+  ContentfulContentType
+} from '@bernierllc/contentful-types';
+
+interface BlogPost {
+  title: { [locale: string]: string };
+  body: { [locale: string]: string };
+  author: { [locale: string]: ContentfulLink<'Entry'> };
+}
+
+const entry = await client.getEntry<BlogPost>('entry-id');
+// entry.fields is typed as BlogPost
+```
+
+## Error Handling
+
+All methods log errors and throw them for you to handle:
+
+```typescript
+try {
+  const entry = await client.getEntry('non-existent-id');
+} catch (error) {
+  console.error('Failed to get entry:', error);
+}
+```
+
+Bulk operations return both successful and failed operations:
+
+```typescript
+const result = await client.bulkCreateEntries(entries);
+
+// Process successful
+result.successful.forEach(entry => {
+  console.log('Created:', entry.sys.id);
+});
+
+// Handle failures
+result.failed.forEach(({ item, error }) => {
+  console.error('Failed to create:', error);
+});
+```
+
+## Logging
+
+This package uses `@bernierllc/logger` for consistent logging:
+
+- **info**: Operation completions, initialization
+- **debug**: Request/response details, operation start
+- **error**: Failures with context
+
+All logs include context (spaceId, environmentId, operation details).
+
+## MECE Principles
+
+This package follows MECE (Mutually Exclusive, Collectively Exhaustive) architecture:
+
+**Includes:**
+- ✅ Content Management API operations (CMA)
+- ✅ CRUD for Entries, Assets, Content Types
+- ✅ Publishing workflow operations
+- ✅ Bulk operations
+
+**Excludes:**
+- ❌ Content Delivery API (use `@bernierllc/contentful-cda-client`)
+- ❌ GraphQL queries (use `@bernierllc/contentful-graphql-client`)
+- ❌ Webhook handling (use `@bernierllc/contentful-webhook-handler`)
+- ❌ OAuth/Auth management (use `@bernierllc/contentful-auth`)
+
+## API
+
+### ContentfulCMAClient
+
+Main client class for interacting with Contentful Content Management API.
+
+**Constructor:**
+```typescript
+new ContentfulCMAClient(config: ContentfulCMAConfig)
+```
+
+**Entry Methods:**
+- `getEntry<T>(entryId: string): Promise<ContentfulEntry<T>>`
+- `getEntries<T>(query?: CMAQueryOptions): Promise<ContentfulCollection<ContentfulEntry<T>>>`
+- `getAllEntries<T>(query?: CMAQueryOptions): Promise<ContentfulEntry<T>[]>`
+- `createEntry<T>(contentTypeId: string, fields: T, options?: CreateEntryOptions): Promise<ContentfulEntry<T>>`
+- `updateEntry<T>(entryId: string, fields: Partial<T>, version: number): Promise<ContentfulEntry<T>>`
+- `publishEntry(entryId: string, version: number): Promise<ContentfulEntry>`
+- `unpublishEntry(entryId: string): Promise<ContentfulEntry>`
+- `archiveEntry(entryId: string, version: number): Promise<ContentfulEntry>`
+- `unarchiveEntry(entryId: string): Promise<ContentfulEntry>`
+- `deleteEntry(entryId: string): Promise<void>`
+
+**Asset Methods:**
+- `getAsset(assetId: string): Promise<ContentfulAsset>`
+- `getAssets(query?: CMAQueryOptions): Promise<ContentfulCollection<ContentfulAsset>>`
+- `getAllAssets(query?: CMAQueryOptions): Promise<ContentfulAsset[]>`
+- `createAsset(fields: AssetFields, options?: CreateAssetOptions): Promise<ContentfulAsset>`
+- `processAsset(assetId: string, version: number, locale: string): Promise<ContentfulAsset>`
+- `publishAsset(assetId: string, version: number): Promise<ContentfulAsset>`
+- `deleteAsset(assetId: string): Promise<void>`
+
+**Content Type Methods:**
+- `getContentType(contentTypeId: string): Promise<ContentfulContentType>`
+- `getContentTypes(): Promise<ContentfulCollection<ContentfulContentType>>`
+
+**Bulk Methods:**
+- `bulkCreateEntries<T>(entries: BulkCreateEntry<T>[]): Promise<BulkOperationResult<ContentfulEntry<T>>>`
+- `bulkPublishEntries(entries: BulkPublishEntry[]): Promise<BulkOperationResult<ContentfulEntry>>`
+- `bulkDeleteEntries(entryIds: string[]): Promise<BulkOperationResult<void>>`
+- `bulkCreateAssets(assets: AssetFields[]): Promise<BulkOperationResult<ContentfulAsset>>`
+
+## Integrations
+
+### Logger Integration
+
+This package integrates with `@bernierllc/logger` for consistent logging across all operations. The logger is initialized automatically and provides:
+
+- **Structured logging** with operation context (spaceId, environmentId, entryId)
+- **Log levels**: info, debug, error
+- **Automatic error tracking** with full error details
+
+```typescript
+// Logger is automatically initialized
+const client = new ContentfulCMAClient(config);
+
+// Logs are emitted for all operations
+await client.getEntry('entry-id');
+// Logs: [INFO] Fetching entry entry-id from space xxx-space-id
+```
+
+### NeverHub Integration
+
+This package does **not** require NeverHub integration as it is a core client library. However, services using this client can integrate with `@bernierllc/neverhub-adapter` for event tracking:
+
+```typescript
+import { ContentfulCMAClient } from '@bernierllc/contentful-cma-client';
+import { NeverHubAdapter } from '@bernierllc/neverhub-adapter';
+
+class ContentfulService {
+  private client: ContentfulCMAClient;
+  private neverhub?: NeverHubAdapter;
+
+  async initialize() {
+    this.client = new ContentfulCMAClient(config);
+
+    // Optional NeverHub integration for event tracking
+    if (await NeverHubAdapter.detect()) {
+      this.neverhub = new NeverHubAdapter();
+      await this.neverhub.register({
+        type: 'contentful-service',
+        capabilities: ['content-management']
+      });
+    }
+  }
+
+  async createEntry<T>(contentTypeId: string, fields: T) {
+    const entry = await this.client.createEntry(contentTypeId, fields);
+
+    // Track event in NeverHub (if available)
+    if (this.neverhub) {
+      await this.neverhub.logEvent({
+        type: 'content.created',
+        data: { entryId: entry.sys.id, contentType: contentTypeId }
+      });
+    }
+
+    return entry;
+  }
+}
+```
+
+**Integration Status:**
+- ✅ Logger integration: Required (built-in)
+- ⚪ NeverHub integration: Optional (consumer responsibility)
+- ✅ Graceful degradation: Works standalone without external services
+
+## Related Packages
+
+- [@bernierllc/contentful-types](../contentful-types) - TypeScript types
+- [@bernierllc/contentful-cda-client](../contentful-cda-client) - Content Delivery API
+- [@bernierllc/contentful-graphql-client](../contentful-graphql-client) - GraphQL API
+- [@bernierllc/contentful-gateway-service](../../service/contentful-gateway-service) - Unified gateway
+
+## License
+
+Copyright (c) 2025 Bernier LLC. See LICENSE.md for details.

package/dist/ContentfulCMAClient.d.ts

@@ -0,0 +1,119 @@
+import { ContentfulEntry, ContentfulAsset, ContentfulContentType, ContentfulCMAConfig } from '@bernierllc/contentful-types';
+import { CMAQueryOptions, CMAEntryCreateOptions, CMAEntryUpdateOptions, CMAAssetCreateOptions, CMABulkOperationResult } from './types';
+export declare class ContentfulCMAClient {
+    private client;
+    private logger;
+    private config;
+    constructor(config: ContentfulCMAConfig);
+    /**
+     * Get entry by ID
+     */
+    getEntry<T = Record<string, unknown>>(entryId: string): Promise<ContentfulEntry<T>>;
+    /**
+     * Get multiple entries with optional query parameters
+     */
+    getEntries<T = Record<string, unknown>>(query?: CMAQueryOptions): Promise<ContentfulEntry<T>[]>;
+    /**
+     * Get all entries with automatic pagination
+     */
+    getAllEntries<T = Record<string, unknown>>(query?: Omit<CMAQueryOptions, 'skip' | 'limit'>): Promise<ContentfulEntry<T>[]>;
+    /**
+     * Create entry
+     */
+    createEntry<T = Record<string, unknown>>(contentTypeId: string, fields: T, options?: CMAEntryCreateOptions): Promise<ContentfulEntry<T>>;
+    /**
+     * Update entry
+     */
+    updateEntry<T = Record<string, unknown>>(entryId: string, fields: T, version: number, _options?: CMAEntryUpdateOptions): Promise<ContentfulEntry<T>>;
+    /**
+     * Publish entry
+     */
+    publishEntry(entryId: string, version: number): Promise<ContentfulEntry>;
+    /**
+     * Unpublish entry
+     */
+    unpublishEntry(entryId: string): Promise<ContentfulEntry>;
+    /**
+     * Archive entry
+     */
+    archiveEntry(entryId: string, version: number): Promise<ContentfulEntry>;
+    /**
+     * Unarchive entry
+     */
+    unarchiveEntry(entryId: string): Promise<ContentfulEntry>;
+    /**
+     * Delete entry
+     */
+    deleteEntry(entryId: string): Promise<void>;
+    /**
+     * Get asset by ID
+     */
+    getAsset(assetId: string): Promise<ContentfulAsset>;
+    /**
+     * Get multiple assets with optional query parameters
+     */
+    getAssets(query?: CMAQueryOptions): Promise<ContentfulAsset[]>;
+    /**
+     * Get all assets with automatic pagination
+     */
+    getAllAssets(query?: Omit<CMAQueryOptions, 'skip' | 'limit'>): Promise<ContentfulAsset[]>;
+    /**
+     * Create asset
+     */
+    createAsset(fields: Record<string, unknown>, options?: CMAAssetCreateOptions): Promise<ContentfulAsset>;
+    /**
+     * Process asset (for uploaded files)
+     */
+    processAsset(assetId: string, version: number, locale?: string): Promise<ContentfulAsset>;
+    /**
+     * Publish asset
+     */
+    publishAsset(assetId: string, version: number): Promise<ContentfulAsset>;
+    /**
+     * Unpublish asset
+     */
+    unpublishAsset(assetId: string): Promise<ContentfulAsset>;
+    /**
+     * Delete asset
+     */
+    deleteAsset(assetId: string): Promise<void>;
+    /**
+     * Get content type by ID
+     */
+    getContentType(contentTypeId: string): Promise<ContentfulContentType>;
+    /**
+     * Get all content types
+     */
+    getContentTypes(query?: CMAQueryOptions): Promise<ContentfulContentType[]>;
+    /**
+     * Bulk create entries
+     */
+    bulkCreateEntries<T = Record<string, unknown>>(entries: Array<{
+        contentTypeId: string;
+        fields: T;
+        entryId?: string;
+    }>): Promise<CMABulkOperationResult<ContentfulEntry<T>>>;
+    /**
+     * Bulk delete entries
+     */
+    bulkDeleteEntries(entryIds: string[]): Promise<CMABulkOperationResult<string>>;
+    /**
+     * Bulk publish entries
+     */
+    bulkPublishEntries(entries: Array<{
+        entryId: string;
+        version: number;
+    }>): Promise<CMABulkOperationResult<ContentfulEntry>>;
+    /**
+     * Helper method to extract error message
+     */
+    private getErrorMessage;
+    /**
+     * Get current space ID
+     */
+    getSpaceId(): string;
+    /**
+     * Get current environment ID
+     */
+    getEnvironmentId(): string;
+}