@bernierllc/contentful-export-adapter

Wrapper around contentful-export library for full Contentful space exports with progress tracking, filtering, and structured output.

Installation

npm install @bernierllc/contentful-export-adapter

Features

• Full Space Export: Export all content types, entries, assets, and locales
• Filtered Exports: Export specific content types or date ranges
• Progress Tracking: Monitor export progress via callbacks
• Asset Download: Optionally download asset files alongside metadata
• Flexible Output: Export to file or return in memory
• Batch Operations: Export multiple content types in one operation
• Type Safety: Full TypeScript support with comprehensive types

Usage

Basic Export

import { ContentfulExportAdapter } from '@bernierllc/contentful-export-adapter';

const adapter = new ContentfulExportAdapter();

const result = await adapter.exportSpace({
  spaceId: 'your-space-id',
  managementToken: 'CFPAT-your-token',
});

console.log(`Exported ${result.entries?.length} entries`);

Export to File

await adapter.exportSpace({
  spaceId: 'your-space-id',
  managementToken: 'CFPAT-your-token',
  outputFile: './exports/my-space-export.json',
});

Filtered Export by Content Type

const blogPosts = await adapter.exportSpace({
  spaceId: 'your-space-id',
  managementToken: 'CFPAT-your-token',
  contentType: 'blogPost',
});

Export with Progress Tracking

const result = await adapter.exportSpaceWithProgress(
  {
    spaceId: 'your-space-id',
    managementToken: 'CFPAT-your-token',
  },
  (progress) => {
    console.log(`Progress: ${progress.done}/${progress.total} - ${progress.operation}`);
  }
);

Export with Asset Download

await adapter.exportSpace({
  spaceId: 'your-space-id',
  managementToken: 'CFPAT-your-token',
  downloadAssets: true,
  exportDir: './exports/assets',
});

Batch Export Multiple Content Types

// Export multiple content types separately
const results = await adapter.exportBatch(
  {
    spaceId: 'your-space-id',
    managementToken: 'CFPAT-your-token',
  },
  {
    contentTypes: ['blogPost', 'author', 'category'],
    merge: false,
  }
);

// Or merge into a single result
const merged = await adapter.exportBatch(
  {
    spaceId: 'your-space-id',
    managementToken: 'CFPAT-your-token',
  },
  {
    contentTypes: ['blogPost', 'author'],
    merge: true,
  }
);

Custom Environment

await adapter.exportSpace({
  spaceId: 'your-space-id',
  environmentId: 'staging',
  managementToken: 'CFPAT-your-token',
});

Include Archived and Draft Content

await adapter.exportSpace({
  spaceId: 'your-space-id',
  managementToken: 'CFPAT-your-token',
  includeArchived: true,
  includeDrafts: true,
});

Configuration Validation

try {
  adapter.validateConfig({
    spaceId: 'my-space',
    managementToken: 'CFPAT-token',
    maxAllowedLimit: 500,
  });
  console.log('Configuration is valid');
} catch (error) {
  console.error('Invalid configuration:', error.message);
}

API Reference

ContentfulExportAdapter

Main adapter class for Contentful exports.

Methods

exportSpace(config: ContentfulExportConfig): Promise<ContentfulExportResult>

Export a full Contentful space or filtered subset.

Parameters:

• config.spaceId (string, required): Contentful space ID
• config.managementToken (string, required): Contentful Management API token
• config.environmentId (string, optional): Environment ID (defaults to 'master')
• config.outputFile (string, optional): File path to write export JSON
• config.downloadAssets (boolean, optional): Download asset files (default: false)
• config.contentType (string, optional): Filter by content type ID
• config.skipContentModel (boolean, optional): Skip content types and editor interfaces
• config.skipRoles (boolean, optional): Skip roles (default: true)
• config.skipWebhooks (boolean, optional): Skip webhooks (default: true)
• config.maxAllowedLimit (number, optional): Max items per request (default: 1000, max: 1000)
• config.exportDir (string, optional): Directory for asset downloads
• config.includeArchived (boolean, optional): Include archived entries
• config.includeDrafts (boolean, optional): Include draft entries

Returns: Export result containing content types, entries, assets, locales, etc.

exportSpaceWithProgress(config: ContentfulExportConfig, onProgress: (progress: ExportProgress) => void): Promise<ContentfulExportResult>

Export space with progress tracking via callback.

Parameters:

• config: Export configuration (same as exportSpace)
• onProgress: Callback invoked with progress updates

Returns: Export result

exportBatch(config: Omit<ContentfulExportConfig, 'contentType'>, options: BatchExportOptions): Promise<ContentfulExportResult | ContentfulExportResult[]>

Export multiple content types in batch.

Parameters:

• config: Base export configuration (without contentType)
• options.contentTypes: Array of content type IDs to export
• options.merge: Whether to merge results into single export (default: false)

Returns: Array of results (if merge=false) or merged result (if merge=true)

validateConfig(config: ContentfulExportConfig): boolean

Validate export configuration before running.

Parameters:

• config: Configuration to validate

Returns: true if valid, throws error if invalid

Types

ContentfulExportConfig

Configuration for export operations.

interface ContentfulExportConfig {
  spaceId: string;
  environmentId?: string;
  managementToken: string;
  outputFile?: string;
  downloadAssets?: boolean;
  contentType?: string;
  skipContentModel?: boolean;
  skipRoles?: boolean;
  skipWebhooks?: boolean;
  maxAllowedLimit?: number;
  exportDir?: string;
  includeArchived?: boolean;
  includeDrafts?: boolean;
}

ContentfulExportResult

Result of an export operation.

interface ContentfulExportResult {
  contentTypes?: Array<Record<string, unknown>>;
  entries?: Array<Record<string, unknown>>;
  assets?: Array<Record<string, unknown>>;
  locales?: Array<Record<string, unknown>>;
  webhooks?: Array<Record<string, unknown>>;
  roles?: Array<Record<string, unknown>>;
  editorInterfaces?: Array<Record<string, unknown>>;
  tags?: Array<Record<string, unknown>>;
}

ExportProgress

Progress information during export.

interface ExportProgress {
  done: number;
  total: number;
  operation?: string;
}

BatchExportOptions

Options for batch export operations.

interface BatchExportOptions {
  contentTypes: string[];
  merge?: boolean;
}

MECE Principles

Includes

• ✅ Full space export (content types, entries, assets, locales)
• ✅ Progress tracking and callbacks
• ✅ Export filtering by content type
• ✅ Asset download support
• ✅ Export to file or memory
• ✅ Multi-space support

Excludes

• ❌ Incremental sync (use @bernierllc/contentful-cda-client Sync API)
• ❌ Import operations (use contentful-import separately)
• ❌ Database storage (use @bernierllc/contentful-sync-service)

Dependencies

• @bernierllc/contentful-types: TypeScript types for Contentful data
• @bernierllc/logger: Structured logging
• @bernierllc/file-handler: File operations
• contentful-export: Official Contentful export library

Related Packages

• @bernierllc/contentful-cda-client: Content Delivery API client with Sync API
• @bernierllc/contentful-sync-service: Continuous synchronization service
• @bernierllc/contentful-types: Shared TypeScript types

Integration Points

Logger Integration

All operations are logged with structured context:

// Automatic logging included
const adapter = new ContentfulExportAdapter();
// Logs: "Starting Contentful export", "Export completed successfully", etc.

NeverHub Integration

Not applicable - this is a core utility package focused on export operations.

Error Handling

The adapter throws descriptive errors for common issues:

try {
  await adapter.exportSpace(config);
} catch (error) {
  // Error: "Contentful export failed: Invalid token"
  // Error: "Contentful export failed: Space not found"
  console.error(error.message);
}

Common errors:

• Invalid management token
• Space not found
• Insufficient permissions
• Rate limiting
• Network errors

Performance Considerations

• Rate Limits: Contentful enforces API rate limits (7 requests/sec)
• Large Exports: Use maxAllowedLimit to control batch size
• Asset Downloads: Can significantly increase export time
• Progress Tracking: Minimal overhead for progress callbacks

Best Practices

1. Use Content Type Filters: Export specific content types to reduce payload size
2. Skip Unnecessary Data: Use skipRoles, skipWebhooks for faster exports
3. Progress Tracking: Monitor long-running exports with progress callbacks
4. File Output: Write large exports to disk to avoid memory issues
5. Batch Operations: Use exportBatch to organize related content types

Testing

Run tests with coverage:

npm test
npm run test:coverage

Coverage Target: 90%+ (core package requirement)

License

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.

Support

For issues or questions, contact Bernier LLC or file an issue in the repository.