@bernierllc/contentful-cma-client 1.0.2

package/src/ContentfulCMAClient.ts

@@ -0,0 +1,694 @@
+/*
+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.
+*/
+
+import contentfulManagement, {
+  PlainClientAPI
+} from 'contentful-management';
+import {
+  ContentfulEntry,
+  ContentfulAsset,
+  ContentfulContentType,
+  ContentfulCMAConfig
+} from '@bernierllc/contentful-types';
+import { Logger, LogLevel, ConsoleTransport } from '@bernierllc/logger';
+import {
+  CMAQueryOptions,
+  CMAEntryCreateOptions,
+  CMAEntryUpdateOptions,
+  CMAAssetCreateOptions,
+  CMABulkOperationResult
+} from './types';
+
+export class ContentfulCMAClient {
+  private client: PlainClientAPI;
+  private logger: Logger;
+  private config: Required<ContentfulCMAConfig>;
+
+  constructor(config: ContentfulCMAConfig) {
+    // Set defaults
+    this.config = {
+      environmentId: 'master',
+      host: 'api.contentful.com',
+      retryOnError: true,
+      timeout: 30000,
+      ...config
+    } as Required<ContentfulCMAConfig>;
+
+    // Initialize logger
+    this.logger = new Logger({
+      level: LogLevel.INFO,
+      transports: [new ConsoleTransport()],
+      context: {
+        service: 'contentful-cma-client',
+        version: '1.0.0',
+        spaceId: config.spaceId,
+        environmentId: this.config.environmentId
+      }
+    });
+
+    // Create contentful-management client with plain API
+    this.client = contentfulManagement.createClient(
+      {
+        accessToken: config.accessToken,
+        host: this.config.host
+      },
+      {
+        type: 'plain',
+        defaults: {
+          spaceId: config.spaceId,
+          environmentId: this.config.environmentId
+        }
+      }
+    );
+
+    this.logger.info('ContentfulCMAClient initialized', {
+      spaceId: config.spaceId,
+      environmentId: this.config.environmentId,
+      host: this.config.host
+    });
+  }
+
+  /**
+   * Get entry by ID
+   */
+  async getEntry<T = Record<string, unknown>>(
+    entryId: string
+  ): Promise<ContentfulEntry<T>> {
+    try {
+      this.logger.debug('Getting entry', { entryId });
+
+      const entry = await this.client.entry.get({ entryId });
+
+      this.logger.debug('Entry retrieved', { entryId });
+      return entry as unknown as ContentfulEntry<T>;
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to get entry', errorObj, { entryId });
+      throw error;
+    }
+  }
+
+  /**
+   * Get multiple entries with optional query parameters
+   */
+  async getEntries<T = Record<string, unknown>>(
+    query?: CMAQueryOptions
+  ): Promise<ContentfulEntry<T>[]> {
+    try {
+      this.logger.debug('Getting entries', { query: query || {} });
+
+      const response = await this.client.entry.getMany({
+        query: query as Record<string, unknown>
+      });
+
+      this.logger.debug('Entries retrieved', {
+        count: response.items.length,
+        total: response.total
+      });
+
+      return response.items as unknown as ContentfulEntry<T>[];
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to get entries', errorObj, { query: query || {} });
+      throw error;
+    }
+  }
+
+  /**
+   * Get all entries with automatic pagination
+   */
+  async getAllEntries<T = Record<string, unknown>>(
+    query?: Omit<CMAQueryOptions, 'skip' | 'limit'>
+  ): Promise<ContentfulEntry<T>[]> {
+    const all: ContentfulEntry<T>[] = [];
+    let skip = 0;
+    const limit = 100;
+
+    this.logger.debug('Getting all entries with pagination', { query: query || {} });
+
+    let hasMore = true;
+    while (hasMore) {
+      const response = await this.client.entry.getMany({
+        query: { ...query, skip, limit } as Record<string, unknown>
+      });
+
+      all.push(...(response.items as unknown as ContentfulEntry<T>[]));
+
+      this.logger.debug('Retrieved entry batch', {
+        batch: response.items.length,
+        total: all.length,
+        remaining: response.total - (skip + response.items.length)
+      });
+
+      if (skip + response.items.length >= response.total) {
+        hasMore = false;
+      } else {
+        skip += response.items.length;
+      }
+    }
+
+    this.logger.info('All entries retrieved', { totalCount: all.length });
+    return all;
+  }
+
+  /**
+   * Create entry
+   */
+  async createEntry<T = Record<string, unknown>>(
+    contentTypeId: string,
+    fields: T,
+    options?: CMAEntryCreateOptions
+  ): Promise<ContentfulEntry<T>> {
+    try {
+      this.logger.debug('Creating entry', { contentTypeId, options: options || {} });
+
+      const entry = await this.client.entry.create(
+        { contentTypeId, ...(options?.entryId ? { entryId: options.entryId } : {}) },
+        { fields: fields as Record<string, unknown> }
+      );
+
+      this.logger.info('Entry created', {
+        entryId: entry.sys.id,
+        contentTypeId
+      });
+
+      return entry as unknown as ContentfulEntry<T>;
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to create entry', errorObj, { contentTypeId });
+      throw error;
+    }
+  }
+
+  /**
+   * Update entry
+   */
+  async updateEntry<T = Record<string, unknown>>(
+    entryId: string,
+    fields: T,
+    version: number,
+    _options?: CMAEntryUpdateOptions
+  ): Promise<ContentfulEntry<T>> {
+    try {
+      this.logger.debug('Updating entry', { entryId, version });
+
+      // Type assertion needed due to contentful-management strict typing
+      const entry = await this.client.entry.update(
+        { entryId },
+        {
+          sys: { version } as any,
+          fields: fields as Record<string, unknown>
+        } as any
+      );
+
+      this.logger.info('Entry updated', { entryId, newVersion: entry.sys.version });
+      return entry as unknown as ContentfulEntry<T>;
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to update entry', errorObj, { entryId, version });
+      throw error;
+    }
+  }
+
+  /**
+   * Publish entry
+   */
+  async publishEntry(
+    entryId: string,
+    version: number
+  ): Promise<ContentfulEntry> {
+    try {
+      this.logger.debug('Publishing entry', { entryId, version });
+
+      // Type assertion needed due to contentful-management strict typing
+      const entry = await this.client.entry.publish(
+        { entryId },
+        { sys: { version } } as any
+      );
+
+      this.logger.info('Entry published', {
+        entryId,
+        publishedVersion: entry.sys.publishedVersion
+      });
+
+      return entry as unknown as ContentfulEntry;
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to publish entry', errorObj, { entryId, version });
+      throw error;
+    }
+  }
+
+  /**
+   * Unpublish entry
+   */
+  async unpublishEntry(entryId: string): Promise<ContentfulEntry> {
+    try {
+      this.logger.debug('Unpublishing entry', { entryId });
+
+      const entry = await this.client.entry.unpublish({ entryId });
+
+      this.logger.info('Entry unpublished', { entryId });
+      return entry as unknown as ContentfulEntry;
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to unpublish entry', errorObj, { entryId });
+      throw error;
+    }
+  }
+
+  /**
+   * Archive entry
+   */
+  async archiveEntry(
+    entryId: string,
+    version: number
+  ): Promise<ContentfulEntry> {
+    try {
+      this.logger.debug('Archiving entry', { entryId, version });
+
+      // Type assertion needed due to contentful-management strict typing
+      const entry = await this.client.entry.archive({ entryId, version } as any);
+
+      this.logger.info('Entry archived', { entryId });
+      return entry as unknown as ContentfulEntry;
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to archive entry', errorObj, { entryId, version });
+      throw error;
+    }
+  }
+
+  /**
+   * Unarchive entry
+   */
+  async unarchiveEntry(entryId: string): Promise<ContentfulEntry> {
+    try {
+      this.logger.debug('Unarchiving entry', { entryId });
+
+      const entry = await this.client.entry.unarchive({ entryId });
+
+      this.logger.info('Entry unarchived', { entryId });
+      return entry as unknown as ContentfulEntry;
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to unarchive entry', errorObj, { entryId });
+      throw error;
+    }
+  }
+
+  /**
+   * Delete entry
+   */
+  async deleteEntry(entryId: string): Promise<void> {
+    try {
+      this.logger.debug('Deleting entry', { entryId });
+
+      await this.client.entry.delete({ entryId });
+
+      this.logger.info('Entry deleted', { entryId });
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to delete entry', errorObj, { entryId });
+      throw error;
+    }
+  }
+
+  /**
+   * Get asset by ID
+   */
+  async getAsset(assetId: string): Promise<ContentfulAsset> {
+    try {
+      this.logger.debug('Getting asset', { assetId });
+
+      const asset = await this.client.asset.get({ assetId });
+
+      this.logger.debug('Asset retrieved', { assetId });
+      return asset as unknown as ContentfulAsset;
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to get asset', errorObj, { assetId });
+      throw error;
+    }
+  }
+
+  /**
+   * Get multiple assets with optional query parameters
+   */
+  async getAssets(query?: CMAQueryOptions): Promise<ContentfulAsset[]> {
+    try {
+      this.logger.debug('Getting assets', { query: query || {} });
+
+      const response = await this.client.asset.getMany({
+        query: query as Record<string, unknown>
+      });
+
+      this.logger.debug('Assets retrieved', {
+        count: response.items.length,
+        total: response.total
+      });
+
+      return response.items as unknown as ContentfulAsset[];
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to get assets', errorObj, { query: query || {} });
+      throw error;
+    }
+  }
+
+  /**
+   * Get all assets with automatic pagination
+   */
+  async getAllAssets(
+    query?: Omit<CMAQueryOptions, 'skip' | 'limit'>
+  ): Promise<ContentfulAsset[]> {
+    const all: ContentfulAsset[] = [];
+    let skip = 0;
+    const limit = 100;
+
+    this.logger.debug('Getting all assets with pagination', { query: query || {} });
+
+    let hasMore = true;
+    while (hasMore) {
+      const response = await this.client.asset.getMany({
+        query: { ...query, skip, limit } as Record<string, unknown>
+      });
+
+      all.push(...(response.items as unknown as ContentfulAsset[]));
+
+      this.logger.debug('Retrieved asset batch', {
+        batch: response.items.length,
+        total: all.length,
+        remaining: response.total - (skip + response.items.length)
+      });
+
+      if (skip + response.items.length >= response.total) {
+        hasMore = false;
+      } else {
+        skip += response.items.length;
+      }
+    }
+
+    this.logger.info('All assets retrieved', { totalCount: all.length });
+    return all;
+  }
+
+  /**
+   * Create asset
+   */
+  async createAsset(
+    fields: Record<string, unknown>,
+    options?: CMAAssetCreateOptions
+  ): Promise<ContentfulAsset> {
+    try {
+      this.logger.debug('Creating asset', { options: options || {} });
+
+      // Type assertion needed due to contentful-management strict typing
+      const asset = await this.client.asset.create(
+        { ...(options?.assetId ? { assetId: options.assetId } : {}) },
+        { fields } as any
+      );
+
+      this.logger.info('Asset created', { assetId: asset.sys.id });
+      return asset as unknown as ContentfulAsset;
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to create asset', errorObj);
+      throw error;
+    }
+  }
+
+  /**
+   * Process asset (for uploaded files)
+   */
+  async processAsset(
+    assetId: string,
+    version: number,
+    locale: string = 'en-US'
+  ): Promise<ContentfulAsset> {
+    try {
+      this.logger.debug('Processing asset', { assetId, version, locale });
+
+      // Type assertion needed due to contentful-management strict typing
+      const asset = await this.client.asset.processForLocale(
+        { assetId, version } as any,
+        { sys: { version } } as any,
+        locale
+      );
+
+      this.logger.info('Asset processing started', { assetId });
+      return asset as unknown as ContentfulAsset;
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to process asset', errorObj, {
+        assetId,
+        version,
+        locale
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Publish asset
+   */
+  async publishAsset(
+    assetId: string,
+    version: number
+  ): Promise<ContentfulAsset> {
+    try {
+      this.logger.debug('Publishing asset', { assetId, version });
+
+      // Type assertion needed due to contentful-management strict typing
+      const asset = await this.client.asset.publish(
+        { assetId },
+        { sys: { version } } as any
+      );
+
+      this.logger.info('Asset published', {
+        assetId,
+        publishedVersion: asset.sys.publishedVersion
+      });
+
+      return asset as unknown as ContentfulAsset;
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to publish asset', errorObj, { assetId, version });
+      throw error;
+    }
+  }
+
+  /**
+   * Unpublish asset
+   */
+  async unpublishAsset(assetId: string): Promise<ContentfulAsset> {
+    try {
+      this.logger.debug('Unpublishing asset', { assetId });
+
+      const asset = await this.client.asset.unpublish({ assetId });
+
+      this.logger.info('Asset unpublished', { assetId });
+      return asset as unknown as ContentfulAsset;
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to unpublish asset', errorObj, { assetId });
+      throw error;
+    }
+  }
+
+  /**
+   * Delete asset
+   */
+  async deleteAsset(assetId: string): Promise<void> {
+    try {
+      this.logger.debug('Deleting asset', { assetId });
+
+      await this.client.asset.delete({ assetId });
+
+      this.logger.info('Asset deleted', { assetId });
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to delete asset', errorObj, { assetId });
+      throw error;
+    }
+  }
+
+  /**
+   * Get content type by ID
+   */
+  async getContentType(contentTypeId: string): Promise<ContentfulContentType> {
+    try {
+      this.logger.debug('Getting content type', { contentTypeId });
+
+      const contentType = await this.client.contentType.get({ contentTypeId });
+
+      this.logger.debug('Content type retrieved', { contentTypeId });
+      return contentType as unknown as ContentfulContentType;
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to get content type', errorObj, { contentTypeId });
+      throw error;
+    }
+  }
+
+  /**
+   * Get all content types
+   */
+  async getContentTypes(
+    query?: CMAQueryOptions
+  ): Promise<ContentfulContentType[]> {
+    try {
+      this.logger.debug('Getting content types', { query: query || {} });
+
+      const response = await this.client.contentType.getMany({
+        query: query as Record<string, unknown>
+      });
+
+      this.logger.info('Content types retrieved', { count: response.items.length });
+      return response.items as unknown as ContentfulContentType[];
+    } catch (error) {
+      const errorObj = error instanceof Error ? error : new Error(String(error));
+      this.logger.error('Failed to get content types', errorObj, { query: query || {} });
+      throw error;
+    }
+  }
+
+  /**
+   * Bulk create entries
+   */
+  async bulkCreateEntries<T = Record<string, unknown>>(
+    entries: Array<{
+      contentTypeId: string;
+      fields: T;
+      entryId?: string;
+    }>
+  ): Promise<CMABulkOperationResult<ContentfulEntry<T>>> {
+    const results: CMABulkOperationResult<ContentfulEntry<T>> = {
+      successful: [],
+      failed: []
+    };
+
+    this.logger.info('Starting bulk entry creation', { count: entries.length });
+
+    for (const entry of entries) {
+      try {
+        const created = await this.createEntry<T>(
+          entry.contentTypeId,
+          entry.fields,
+          { entryId: entry.entryId }
+        );
+        results.successful.push(created);
+      } catch (error) {
+        results.failed.push({
+          item: { contentTypeId: entry.contentTypeId, fields: entry.fields },
+          error: this.getErrorMessage(error)
+        });
+      }
+    }
+
+    this.logger.info('Bulk entry creation completed', {
+      successful: results.successful.length,
+      failed: results.failed.length
+    });
+
+    return results;
+  }
+
+  /**
+   * Bulk delete entries
+   */
+  async bulkDeleteEntries(
+    entryIds: string[]
+  ): Promise<CMABulkOperationResult<string>> {
+    const results: CMABulkOperationResult<string> = {
+      successful: [],
+      failed: []
+    };
+
+    this.logger.info('Starting bulk entry deletion', { count: entryIds.length });
+
+    for (const entryId of entryIds) {
+      try {
+        await this.deleteEntry(entryId);
+        results.successful.push(entryId);
+      } catch (error) {
+        results.failed.push({
+          item: entryId,
+          error: this.getErrorMessage(error)
+        });
+      }
+    }
+
+    this.logger.info('Bulk entry deletion completed', {
+      successful: results.successful.length,
+      failed: results.failed.length
+    });
+
+    return results;
+  }
+
+  /**
+   * Bulk publish entries
+   */
+  async bulkPublishEntries(
+    entries: Array<{ entryId: string; version: number }>
+  ): Promise<CMABulkOperationResult<ContentfulEntry>> {
+    const results: CMABulkOperationResult<ContentfulEntry> = {
+      successful: [],
+      failed: []
+    };
+
+    this.logger.info('Starting bulk entry publishing', { count: entries.length });
+
+    for (const entry of entries) {
+      try {
+        const published = await this.publishEntry(entry.entryId, entry.version);
+        results.successful.push(published);
+      } catch (error) {
+        results.failed.push({
+          item: entry,
+          error: this.getErrorMessage(error)
+        });
+      }
+    }
+
+    this.logger.info('Bulk entry publishing completed', {
+      successful: results.successful.length,
+      failed: results.failed.length
+    });
+
+    return results;
+  }
+
+  /**
+   * Helper method to extract error message
+   */
+  private getErrorMessage(error: unknown): string {
+    if (error instanceof Error) {
+      return error.message;
+    }
+    if (typeof error === 'string') {
+      return error;
+    }
+    return 'Unknown error';
+  }
+
+  /**
+   * Get current space ID
+   */
+  getSpaceId(): string {
+    return this.config.spaceId;
+  }
+
+  /**
+   * Get current environment ID
+   */
+  getEnvironmentId(): string {
+    return this.config.environmentId;
+  }
+}