Registration and diagnostics types

The global and ready host APIs expose registration records and a read-only configurator snapshot.

Plugin registration

type PluginRegistration = {
  id: string
  version: string
  apiVersion?: string
  status: PluginRegistrationStatus
  source: 'builtin' | 'inline' | 'preboot' | 'late'
  enabled: boolean
  required: boolean
  order: number
  capabilities?: PluginCapability[]
  error?: string
  errorPhase?: string
  timestamps: {
    discoveredAt: number
    setupStartedAt?: number
    readyAt?: number
    failedAt?: number
    disposedAt?: number
  }
}

Status values are queued, registered, setting-up, ready, failed, disabled, and disposed.

Configurator snapshot

type ConfiguratorSnapshot = {
  status: 'idle' | 'booting' | 'ready' | 'failed'
  debugPlugins: boolean
  plugins: PluginRegistration[]
  pluginErrors: PluginDiagnosticError[]
  pluginAssets: PluginAssetLoadRecord[]
  campaigns: MarketingCampaignSnapshot[]
  landingSections: PluginLandingSectionSnapshot[]
  modal: PluginModalSnapshot | null
  route?: SerializableRoute
  configuration: {
    mount: string
    environment?: 'production' | 'staging' | 'local' | 'poc'
    visualizerId?: number
  }
}

Treat every returned record as read-only. A later call returns a fresh view of current status.

Plugin errors

type PluginDiagnosticError = {
  pluginId: string
  phase: string
  message: string
  timestamp: number
}

Messages are public diagnostics and should not include credentials or private configuration.

Loaded plugin files

type PluginAssetLoadRecord = {
  name: string
  url: string
  source: 'icon-managed'
  scope?: 'global' | 'account'
  status: 'loading' | 'loaded' | 'failed'
  startedAt: number
  finishedAt?: number
  error?: string
}

A file can load successfully and then register a plugin that fails. Inspect both pluginAssets and plugins when diagnosing an integration.

See Diagnose plugin registration for the operational workflow.