@bernierllc/contentful-export-adapter

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

Installation

``bash
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

$3

`typescript
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);
`

$3

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

$3

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

$3

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

$3

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

$3

`typescript
// 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,
}
);
`

$3

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

$3

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

$3

`typescript
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

$3

Main adapter class for Contentful exports.

#### Methods

##### exportSpace(config: ContentfulExportConfig): Promise

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

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, options: BatchExportOptions): Promise

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

$3

#### ContentfulExportConfig

Configuration for export operations.

`typescript
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.

`typescript
interface ContentfulExportResult {
contentTypes?: Array>;
entries?: Array>;
assets?: Array>;
locales?: Array>;
webhooks?: Array>;
roles?: Array>;
editorInterfaces?: Array>;
tags?: Array>;
}
`

#### ExportProgress

Progress information during export.

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

#### BatchExportOptions

Options for batch export operations.

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

MECE Principles

$3

- ✅ 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

$3

- ❌ 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

$3

All operations are logged with structured context:

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

$3

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

Error Handling

The adapter throws descriptive errors for common issues:

`typescript
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:

`bash
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.