catalog/ts_web/elements/interfaces/dataprovider.ts

/**
 * Data Provider System Interfaces
 *
 * Data providers are external web apps that can be registered to provide
 * or receive data from ecobridge applications. They communicate via
 * postMessage API in sandboxed iframes.
 */

// Provider feature types - what capabilities a provider can offer
export type TProviderFeature =
  | 'scan-destination'    // Can receive scanned documents
  | 'media-source'        // Can provide media URLs for playback
  | 'document-storage'    // Can store/retrieve documents
  | 'print-destination';  // Can receive print jobs

// Provider connection status
export type TProviderStatus = 'connected' | 'disconnected' | 'loading' | 'error';

/**
 * Data Provider configuration and state
 */
export interface IDataProvider {
  id: string;
  name: string;
  url: string;
  features: TProviderFeature[];          // Features declared by provider
  confirmedFeatures: TProviderFeature[]; // Features user has approved
  icon?: string;                          // Base64 data URL or icon URL
  lastSeen: Date;
  status: TProviderStatus;
  enabled: boolean;
}

/**
 * Provider registration payload (sent by provider on ready)
 */
export interface IProviderRegistration {
  name: string;
  features: TProviderFeature[];
  icon?: string;
  version?: string;
}

/**
 * Message types from Provider to Ecobridge
 */
export type TProviderToEcobridgeMessageType =
  | 'provider-ready'      // Provider loaded and declaring features
  | 'provider-features'   // Provider updating its features
  | 'provider-response'   // Response to an ecobridge request
  | 'provider-error'      // Error occurred in provider
  | 'data-offer';         // Provider offering data (e.g., media URL)

/**
 * Message from Provider to Ecobridge
 */
export interface IProviderMessage {
  type: TProviderToEcobridgeMessageType;
  providerId: string;
  requestId?: string;     // For responses to specific requests
  payload: unknown;
}

/**
 * Provider ready message payload
 */
export interface IProviderReadyPayload {
  name: string;
  features: TProviderFeature[];
  icon?: string;
  version?: string;
}

/**
 * Provider response payload
 */
export interface IProviderResponsePayload {
  success: boolean;
  data?: unknown;
  error?: string;
}

/**
 * Provider data offer payload (e.g., for media-source)
 */
export interface IProviderDataOfferPayload {
  type: 'media-url' | 'document' | 'file-list';
  data: unknown;
  metadata?: Record<string, unknown>;
}

/**
 * Message types from Ecobridge to Provider
 */
export type TEcobridgeToProviderMessageType =
  | 'request-features'    // Ask provider to declare features
  | 'send-data'           // Send data to provider (e.g., scan)
  | 'request-data'        // Request data from provider (e.g., media URL)
  | 'ping';               // Health check

/**
 * Message from Ecobridge to Provider
 */
export interface IEcobridgeMessage {
  type: TEcobridgeToProviderMessageType;
  requestId: string;
  payload?: unknown;
}

/**
 * Send data payload (e.g., sending scan to provider)
 */
export interface ISendDataPayload {
  dataType: 'scan' | 'document' | 'print-job';
  data: string;           // Base64 encoded data
  format: string;         // File format (pdf, jpeg, etc.)
  filename?: string;
  metadata?: Record<string, unknown>;
}

/**
 * Request data payload (e.g., requesting media from provider)
 */
export interface IRequestDataPayload {
  dataType: 'media-url' | 'document' | 'file-list';
  filter?: Record<string, unknown>;
}

/**
 * Feature change event - when provider's features differ from confirmed
 */
export interface IFeatureChangeRequest {
  providerId: string;
  providerName: string;
  addedFeatures: TProviderFeature[];
  removedFeatures: TProviderFeature[];
  currentFeatures: TProviderFeature[];
}

/**
 * Provider store schema for persistence
 */
export interface IProviderStore {
  providers: IDataProvider[];
  lastUpdated: Date;
}

/**
 * Events dispatched by eco-provider-frame
 */
export interface IProviderFrameEvents {
  'provider-ready': CustomEvent<{ provider: IDataProvider }>;
  'provider-features-changed': CustomEvent<{ request: IFeatureChangeRequest }>;
  'provider-response': CustomEvent<{ requestId: string; response: IProviderResponsePayload }>;
  'provider-data-offer': CustomEvent<{ offer: IProviderDataOfferPayload }>;
  'provider-error': CustomEvent<{ error: string }>;
  'provider-disconnected': CustomEvent<{ providerId: string }>;
}