@idpass/data-collect-core / ExternalSyncManager

Class: ExternalSyncManager

Defined in: components/ExternalSyncManager.ts:105

Manages synchronization with external third-party systems using pluggable adapters.

This class provides a unified interface for syncing DataCollect data with various external systems (e.g., OpenSPP, custom APIs) by utilizing a Strategy pattern with pluggable adapters.

Key features:

• Pluggable Adapters: Support for multiple external systems via adapter pattern.
• Dynamic Loading: Adapters are instantiated based on configuration type.
• Credential Management: Secure handling of authentication credentials.
• Error Handling: Graceful handling of adapter initialization and sync failures.
• Configuration-Driven: Flexible configuration per external system.

Architecture:

• Uses Strategy pattern for different external system integrations.
• Adapters are registered in the adaptersMapping registry.
• Each adapter implements the ExternalSyncAdapter interface.
• Configuration determines which adapter to instantiate and how to configure it.

Examples

Basic usage with mock adapter:

const config: ExternalSyncConfig = {
  type: 'mock-sync-server',
  url: 'http://mock.example.com',
  timeout: 30000
};

const externalSync = new ExternalSyncManager(
  eventStore,
  eventApplierService,
  config
);

await externalSync.initialize();
await externalSync.synchronize();

With authentication credentials:

const credentials: ExternalSyncCredentials = {
  username: 'sync_user',
  password: 'secure_password'
};

await externalSync.synchronize(credentials);

Custom adapter registration:

// In adaptersMapping (requires code modification):
const adaptersMapping = {
  "mock-sync-server": MockSyncServerAdapter,
  "openspp": OpenSppSyncAdapter,
  "custom-api": CustomApiSyncAdapter
};

// Then use with config:
const opensppConfig: ExternalSyncConfig = {
  type: 'openspp',
  url: 'http://openspp.example.com',
  database: 'openspp_db'
};

Constructors

Constructor

new ExternalSyncManager(eventStore, eventApplierService, config): ExternalSyncManager

Defined in: components/ExternalSyncManager.ts:131

Creates a new ExternalSyncManager instance.

Parameters

eventStore

EventStore

Store for managing events and audit logs.

eventApplierService

EventApplierService

Service for applying events to entities.

config

ExternalSyncConfig

Configuration object specifying the external system type and settings.

Returns

ExternalSyncManager

Example

const config: ExternalSyncConfig = {
  type: 'openspp',
  url: 'http://openspp.example.com',
  database: 'openspp_production',
  timeout: 60000
};

const manager = new ExternalSyncManager(
  eventStore,
  eventApplierService,
  config
);

Methods

initialize()

initialize(): Promise<void>

Defined in: components/ExternalSyncManager.ts:163

Initializes the external sync manager by instantiating the appropriate adapter.

Looks up the adapter class based on the configuration type and creates an instance with the provided dependencies. If the adapter type is not found in the registry, the manager remains uninitialized (adapter will be null).

This method must be called before attempting synchronization.

Returns

Promise<void>

A Promise that resolves when the adapter is initialized.

Throws

When adapter instantiation fails.

Example

const manager = new ExternalSyncManager(eventStore, eventApplierService, config);

await manager.initialize();

// Check if adapter was successfully loaded
if (manager.isInitialized()) {
  await manager.synchronize();
} else {
  console.log('No adapter available for type:', config.type);
}

---

synchronize()

synchronize(credentials?): Promise<void>

Defined in: components/ExternalSyncManager.ts:216

Performs synchronization with the external system using the configured adapter.

Delegates the actual sync operation to the loaded adapter, which handles the system-specific integration logic.

Parameters

credentials?

ExternalSyncCredentials

Optional authentication credentials for the external system.

Returns

Promise<void>

A Promise that resolves when the synchronization is complete.

Throws

When adapter is not initialized or sync operation fails.

Examples

// Simple sync without credentials (if adapter doesn't require them)
await manager.synchronize();

// Sync with basic authentication
await manager.synchronize({
  username: 'integration_user',
  password: 'secure_password'
});

Error handling:

try {
  await manager.synchronize(credentials);
  console.log('External sync completed successfully');
} catch (error) {
  if (error.message === 'Adapter not initialized') {
    console.log('Please call initialize() first');
  } else {
    console.error('External sync failed:', error.message);
  }
}

---

isInitialized()

isInitialized(): boolean

Defined in: components/ExternalSyncManager.ts:260

Checks if the external sync manager has been properly initialized with an adapter.

Returns

boolean

true if an adapter is loaded and ready for synchronization, false otherwise.

Example

const manager = new ExternalSyncManager(eventStore, eventApplierService, config);
await manager.initialize();

if (manager.isInitialized()) {
  console.log('Ready for external sync');
} else {
  console.log('No adapter available for:', config.type);
}