Packages and contracts

The toolkit is split into a core engine plus focused adapters and sinks, so you can pick only the vendor integrations you use, or write your own on the same two small interfaces.

The adapter contract#

An adapter teaches the engine how to read one OTA vendor. Write one by implementing OtaAdapter:

interface OtaAdapter {
  getActiveUpdateId(): Promise<string | null>; // null = embedded bundle
  getEmbeddedVersion(): Promise<string>;
  onEvent(cb: (e: OtaAdapterEvent) => void): Unsubscribe;
  rollback?(): Promise<boolean>; // optional; omit if the vendor has no client rollback
}

Without rollback(), the engine runs in recommendation-only mode; autoRollback logs a warning instead of failing. Adapters must never throw into the host app: degrade to a safe no-op with a single warning if the vendor SDK is missing. The expo-updates adapter is recommendation-only; the hot-updater adapter implements rollback().

The sink contract#

A sink receives the typed event stream. Write one by implementing Sink:

interface Sink {
  onEvent(event: ReleaseHealthEvent): void;
  flush?(): Promise<void>;
  attach?(context: SinkContext): void; // observe live status, e.g. to tag a crash reporter
}

Sink exceptions are swallowed and logged by the engine; a misbehaving sink cannot take the app down. The HTTP sink batches and posts JSON; the Sentry sink uses attach to keep a crash reporter tagged with the live status. The events themselves are listed on Events and failure detection.

Dependency policy#

The toolkit has a zero-dependency bias. The core package has no runtime dependencies beyond react and react-native as peers; persistence uses UserDefaults and SharedPreferences directly. Adapters and sinks reach their vendor SDKs as duck-typed peers and degrade to safe no-ops with one actionable warning when the peer is missing, so adding an adapter or sink never pulls a vendor SDK into an app that does not already use it.