Bridge SDK Interface

Every bridge must implement the BridgeImplementation interface from @orderly/shared. This ensures a consistent API across all integrations.

BridgeImplementation

interface BridgeImplementation {
  readonly manifest: BridgeManifest;
  initialize(config: BridgeRuntimeConfig): Promise<void>;
  validateConfig(config: BridgeRuntimeConfig): Promise<{ valid: boolean; error?: string }>;
  executeTask(taskName: string, context: BridgeTaskContext, input: Record<string, unknown>): Promise<BridgeTaskResult>;
  handleWebhook?(event: string, payload: Record<string, unknown>, context: BridgeTaskContext): Promise<BridgeTaskResult>;
  destroy?(): Promise<void>;
}

manifest

The bridge’s metadata, declared as a readonly property. See Manifest.

initialize(config)

Called once when the bridge is activated. Use this to set up API clients, validate tokens, etc.

validateConfig(config)

Tests that the provided credentials and settings are valid. Called when a user first configures the bridge. Should return { valid: true } or { valid: false, error: "message" }.

executeTask(taskName, context, input)

The main workhorse. Called to run any task defined in the manifest. Route by taskName:

async executeTask(taskName, context, input) {
  switch (taskName) {
    case 'grab-orders': return this.grabOrders(context, input);
    case 'get-order': return this.getOrder(context, input);
    case 'push-fulfillment': return this.pushFulfillment(context, input);
    default: return { success: false, error: { code: 'UNKNOWN_TASK', message: `Unknown task: ${taskName}` } };
  }
}

handleWebhook(event, payload, context)

Optional. Handles incoming webhooks from the platform. Only implement if your bridge declares webhooks in its manifest.

destroy()

Optional. Called when the bridge is deactivated. Use this to clean up connections, timers, etc.

BridgeTaskContext

Every task execution receives a context object:

BridgeTaskResult

All tasks return a standard result:

BridgeRuntimeConfig

BridgeStorage

The storage interface lets bridges persist data between executions:

interface BridgeStorage {
  get<T>(key: string): Promise<T | null>;
  set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
  delete(key: string): Promise<void>;
}

Common uses:

• Store pagination cursors for incremental syncs
• Cache OAuth refresh tokens
• Track the last sync timestamp