Complete Public API Reference (package:tk_ota_push/tk_ota_push.dart)

This reference documents all public classes, enums, type definitions (typedef), constructors, methods, properties, and exceptions exported by lib/tk_ota_push.dart.

Library Entrypoint

import 'package:tk_ota_push/tk_ota_push.dart';

Exports provided by lib/tk_ota_push.dart:

• package:shorebird_code_push/shorebird_code_push.dart (show UpdateStatus, UpdateTrack, Patch)
• src/tk_ota_push_sdk.dart
• src/models/ota_remote_config.dart
• src/gatekeeper/remote_config_gatekeeper.dart
• src/security/ota_security_shield.dart
• src/environment/ota_environment.dart
• src/assets/ota_asset_manager.dart

---

1. Primary Orchestrator (src/tk_ota_push_sdk.dart)

Class TkOtaPush (aliases SaraOta, EntrepriseOta)

The central orchestrator for the mobile SDK layered on top of the native Rust ShorebirdUpdater engine.

Backwards-Compatible Aliases

typedef SaraOta = TkOtaPush;
typedef EntrepriseOta = TkOtaPush;

Constructor & Static Initializer

TkOtaPush({
  ShorebirdUpdater? updater,
  String appReleaseVersion = '',
  bool enableGatekeeper = true,
  bool requireWifiForSilentUpdate = false,
  int minBatteryPercentageForSilentUpdate = 20,
  OtaEnvironmentMonitor? environmentMonitor,
  OtaBackgroundScheduler? backgroundScheduler,
  OtaSecurityPolicy? securityPolicy,
  OtaDeviceIntegrityInspector? deviceIntegrityInspector,
  OtaRollbackTracker? rollbackTracker,
  CriticalUpdateHandler? onCriticalUpdateRequired,
  RollbackDetectedHandler? onRollbackDetected,
  SecurityViolationHandler? onSecurityViolation,
})

static TkOtaPush init({
  ShorebirdUpdater? updater,
  required String appReleaseVersion,
  bool enableGatekeeper = true,
  bool requireWifiForSilentUpdate = false,
  int minBatteryPercentageForSilentUpdate = 20,
  OtaEnvironmentMonitor? environmentMonitor,
  OtaBackgroundScheduler? backgroundScheduler,
  OtaSecurityPolicy? securityPolicy,
  OtaDeviceIntegrityInspector? deviceIntegrityInspector,
  OtaRollbackTracker? rollbackTracker,
  CriticalUpdateHandler? onCriticalUpdateRequired,
  RollbackDetectedHandler? onRollbackDetected,
  SecurityViolationHandler? onSecurityViolation,
})

Creates a configured TkOtaPush instance, binds it to the TkOtaPush.instance singleton, and returns it.

Properties and Getters

Property / Getter	Type	Description
static instance	TkOtaPush	Shared instance initialized via TkOtaPush.init (or default fallback instance).
appReleaseVersion	String	Installed release version (e.g., '1.0.0+3').
enableGatekeeper	bool	Enables (true by default) or bypasses RemoteConfigGatekeeper.
requireWifiForSilentUpdate	bool	Defers silent updates when the device is not on Wi-Fi or Ethernet.
minBatteryPercentageForSilentUpdate	int	Minimum battery percentage (default 20) required while not plugged in.
securityPolicy	OtaSecurityPolicy	Active policy for mobile security checks.
onCriticalUpdateRequired	CriticalUpdateHandler?	Callback invoked when remoteConfig.forceUpdate == true.
onRollbackDetected	RollbackDetectedHandler?	Callback invoked when patch regression is detected at boot.
onSecurityViolation	SecurityViolationHandler?	Callback invoked when securityVerdict.isTrusted == false.
track	UpdateTrack	Active distribution channel (UpdateTrack.stable by default).
isAvailable	bool	true if the native Rust engine is present and active (compiled via Shorebird).

Methods of TkOtaPush

enableQaMode() / disableQaMode()

void enableQaMode()
void disableQaMode()

Switches the monitored channel (track) to UpdateTrack.staging (enableQaMode) or returns to UpdateTrack.stable (disableQaMode).

currentPatchNumber()

Future<int?> currentPatchNumber()

Returns the running patch number ((await _updater.readCurrentPatch())?.number), or null if the app runs on the baseline Store binary.

readClientId()

Future<String?> readClientId({String? appSupportDirectoryPath})

Reads the UUID v4 client_id persisted by the Rust engine in shorebird_updater/state.json (or patches_state.json). Inspects appSupportDirectoryPath if supplied, otherwise probes standard Android (files) and iOS (Library/Application Support, Documents) sandbox folders. Returns null if state has not been written yet.

readShortSupportCode()

Future<String?> readShortSupportCode({String? appSupportDirectoryPath})

Returns the 8-character code prefixed by # (e.g., '#6959347F') derived from the first 8 uppercase hexadecimal characters of readClientId(). Returns null if clientId is unavailable.

readDeviceIdentity()

Future<OtaDeviceIdentity?> readDeviceIdentity({String? appSupportDirectoryPath})

Returns an OtaDeviceIdentity object grouping clientId, shortSupportCode, releaseVersion, track, and currentPatchNumber.

checkForUpdate()

Future<UpdateStatus> checkForUpdate()

Queries POST /api/v1/patches/check directly on the active track and returns UpdateStatus.

update()

Future<void> update()

Downloads and stages the latest available patch on the active track.

checkAndUpdate()

Future<bool> checkAndUpdate()

Evaluates if (!isAvailable) return false;, queries checkForUpdate(), and if UpdateStatus.outdated, downloads the patch via update() and returns true; otherwise returns false.

verifyStartupAndHandleRollback()

Future<OtaRollbackEvent?> verifyStartupAndHandleRollback({
  String? overrideAppReleaseVersion,
})

Compares the current patch against the last recorded patch for the release version. If a rollback occurred (current < previous), invokes onRollbackDetected and returns OtaRollbackEvent; returns null otherwise.

syncWithRemoteConfig()

Future<OtaSyncOutcome> syncWithRemoteConfig(
  OtaRemoteConfig remoteConfig, {
  String? overrideAppReleaseVersion,
})

Executes the full evaluation cycle:

1. verifyStartupAndHandleRollback (Step 0a).
2. Evaluates securityPolicy via OtaDeviceIntegrityInspector.evaluatePolicy (Step 0b).
3. Evaluates 3-step RemoteConfigGatekeeper conditions.
4. Executes critical (forceUpdate: true) or silent (forceUpdate: false) update policies subject to network/battery constraints.

---

Class OtaDeviceIdentity

class OtaDeviceIdentity {
  const OtaDeviceIdentity({
    required this.clientId,
    required this.shortSupportCode,
    required this.releaseVersion,
    required this.track,
    this.currentPatchNumber,
  });

  final String clientId;
  final String shortSupportCode;
  final String releaseVersion;
  final String track;
  final int? currentPatchNumber;

  Map<String, dynamic> toJson();
}

Enum OtaUpdateExecutionMode

enum OtaUpdateExecutionMode {
  blockedByGatekeeper,
  blockedBySecurityShield,
  deferredToBackgroundTask,
  silentBackgroundUpdate,
  criticalForcedUpdate,
}

Class OtaSyncOutcome

class OtaSyncOutcome {
  const OtaSyncOutcome({
    required this.executionMode,
    required this.networkCallPerformed,
    required this.patchDownloaded,
    required this.restartRequired,
    this.gatekeeperEvaluation,
    this.securityVerdict,
    this.rollbackEvent,
    this.message,
  });

  final OtaUpdateExecutionMode executionMode;
  final bool networkCallPerformed;
  final bool patchDownloaded;
  final bool restartRequired;
  final GatekeeperEvaluation? gatekeeperEvaluation;
  final OtaSecurityVerdict? securityVerdict;
  final OtaRollbackEvent? rollbackEvent;
  final String? message;
}

Typedef CriticalUpdateHandler

typedef CriticalUpdateHandler = Future<void> Function(
  OtaRemoteConfig config,
  Future<bool> Function() triggerImmediateDownload,
);

---

2. Remote Config & Gatekeeper Models (src/models/ota_remote_config.dart & src/gatekeeper/remote_config_gatekeeper.dart)

Class OtaRemoteConfig

class OtaRemoteConfig {
  const OtaRemoteConfig({
    required this.targetReleaseVersion,
    required this.patchAvailable,
    required this.latestPatchNumber,
    this.forceUpdate = false,
    this.releaseNotes,
  });

  factory OtaRemoteConfig.fromJson(Map<String, dynamic> json);

  final String targetReleaseVersion;
  final bool patchAvailable;
  final int latestPatchNumber;
  final bool forceUpdate;
  final String? releaseNotes;

  Map<String, dynamic> toJson();
}

Enum GatekeeperVerdict

enum GatekeeperVerdict {
  allowed,
  skippedVersionMismatch,
  skippedNoPatchAvailable,
  skippedAlreadyUpToDate,
  bypassedGatekeeperDisabled,
}

Class GatekeeperEvaluation

class GatekeeperEvaluation {
  const GatekeeperEvaluation({
    required this.verdict,
    required this.shouldCallOtaServer,
    required this.installedReleaseVersion,
    required this.targetReleaseVersion,
    required this.currentPatchNumber,
    required this.latestPatchNumber,
    required this.reason,
  });

  final GatekeeperVerdict verdict;
  final bool shouldCallOtaServer;
  final String installedReleaseVersion;
  final String targetReleaseVersion;
  final int currentPatchNumber;
  final int latestPatchNumber;
  final String reason;
}

Class RemoteConfigGatekeeper

class RemoteConfigGatekeeper {
  const RemoteConfigGatekeeper();

  GatekeeperEvaluation evaluate({
    required String installedReleaseVersion,
    required int? currentPatchNumber,
    required OtaRemoteConfig remoteConfig,
  });
}

---

3. Security Shield & Rollback (src/security/ota_security_shield.dart)

Class OtaRollbackEvent & Typedef RollbackDetectedHandler

typedef RollbackDetectedHandler = Future<void> Function(OtaRollbackEvent event);

class OtaRollbackEvent {
  const OtaRollbackEvent({
    required this.releaseVersion,
    required this.previousPatchNumber,
    required this.restoredPatchNumber,
    required this.detectedAt,
  });

  final String releaseVersion;
  final int previousPatchNumber;
  final int restoredPatchNumber;
  final DateTime detectedAt;

  @override
  String toString();
}

Rollback Tracking & Storage (OtaPatchStateStore, InMemoryOtaPatchStateStore, FileOtaPatchStateStore, OtaRollbackTracker)

abstract class OtaPatchStateStore {
  Future<int?> readLastExecutedPatch(String releaseVersion);
  Future<void> writeLastExecutedPatch(String releaseVersion, int patchNumber);
}

class InMemoryOtaPatchStateStore implements OtaPatchStateStore {
  InMemoryOtaPatchStateStore();
  @override
  Future<int?> readLastExecutedPatch(String releaseVersion);
  @override
  Future<void> writeLastExecutedPatch(String releaseVersion, int patchNumber);
}

class FileOtaPatchStateStore implements OtaPatchStateStore {
  FileOtaPatchStateStore(this.stateFile);
  final File stateFile;
  @override
  Future<int?> readLastExecutedPatch(String releaseVersion);
  @override
  Future<void> writeLastExecutedPatch(String releaseVersion, int patchNumber);
}

class OtaRollbackTracker {
  OtaRollbackTracker({OtaPatchStateStore? store});

  Future<OtaRollbackEvent?> evaluateAndRecord({
    required String releaseVersion,
    required int? currentPatchNumber,
  });
}

Mobile Security (OtaSecurityViolationType, OtaSecurityVerdict, OtaSecurityPolicy)

typedef SecurityViolationHandler = Future<void> Function(OtaSecurityVerdict verdict);

enum OtaSecurityViolationType {
  apkSignatureMismatch,
  deviceRootedOrJailbroken,
  tlsCertificatePinningMismatch,
}

class OtaSecurityVerdict {
  const OtaSecurityVerdict({
    required this.isTrusted,
    this.violationType,
    this.reason,
    this.observedApkSignatureSha256,
  });

  const OtaSecurityVerdict.trusted({this.observedApkSignatureSha256});

  final bool isTrusted;
  final OtaSecurityViolationType? violationType;
  final String? reason;
  final String? observedApkSignatureSha256;
}

class OtaSecurityPolicy {
  const OtaSecurityPolicy({
    this.expectedApkSignaturesSha256 = const {},
    this.blockRootedOrJailbrokenDevices = false,
    this.pinnedServerCertSha256Fingerprints = const {},
  });

  final Set<String> expectedApkSignaturesSha256;
  final bool blockRootedOrJailbrokenDevices;
  final Set<String> pinnedServerCertSha256Fingerprints;

  static String normalizeSha256(String fingerprint);
}

Integrity Inspectors (OtaDeviceIntegrityInspector, DefaultOtaDeviceIntegrityInspector)

abstract class OtaDeviceIntegrityInspector {
  Future<String?> readInstalledApkSignatureSha256();
  Future<bool> isDeviceRootedOrJailbroken();
  Future<OtaSecurityVerdict> evaluatePolicy(OtaSecurityPolicy policy);
}

class DefaultOtaDeviceIntegrityInspector extends OtaDeviceIntegrityInspector {
  DefaultOtaDeviceIntegrityInspector({
    this.apkSignatureProvider,
    List<String>? customSuspiciousPaths,
  });

  final Future<String?> Function()? apkSignatureProvider;

  @override
  Future<String?> readInstalledApkSignatureSha256();
  @override
  Future<bool> isDeviceRootedOrJailbroken();
}

TLS Certificate Pinning (OtaCertificatePinner, OtaPinnedHttpOverrides)

class OtaCertificatePinner {
  OtaCertificatePinner({
    required Set<String> pinnedSha256Fingerprints,
    this.enforcedHosts = const {},
  });

  final Set<String> enforcedHosts;

  static String computeDerSha256Hex(List<int> derBytes);
  bool verifyCertificateDer(List<int> derBytes, {String? host});
  bool verifyX509Certificate(X509Certificate cert, {String? host});
}

class OtaPinnedHttpOverrides extends HttpOverrides {
  OtaPinnedHttpOverrides(this.pinner);

  final OtaCertificatePinner pinner;

  @override
  HttpClient createHttpClient(SecurityContext? context);
}

---

4. Environment & Background Scheduling (src/environment/ota_environment.dart)

enum OtaConnectivityType {
  wifi,
  ethernet,
  mobile,
  none,
}

class OtaDeviceConditions {
  const OtaDeviceConditions({
    required this.connectivity,
    this.batteryPercentage = 100,
    this.isCharging = false,
  });

  final OtaConnectivityType connectivity;
  final int batteryPercentage;
  final bool isCharging;

  bool get isUnmeteredWifi;
  bool get isOnline;
}

abstract class OtaEnvironmentMonitor {
  Future<OtaDeviceConditions> checkConditions();
}

class DefaultOtaEnvironmentMonitor implements OtaEnvironmentMonitor {
  const DefaultOtaEnvironmentMonitor({
    this.defaultConnectivity = OtaConnectivityType.wifi,
    this.defaultBatteryPercentage = 100,
  });

  final OtaConnectivityType defaultConnectivity;
  final int defaultBatteryPercentage;

  @override
  Future<OtaDeviceConditions> checkConditions();
}

abstract class OtaBackgroundScheduler {
  Future<void> scheduleSilentUpdateTask({
    required String taskUniqueName,
    required bool requireWifi,
    required bool requireBatteryNotLow,
  });
}

class InMemoryOtaBackgroundScheduler implements OtaBackgroundScheduler {
  InMemoryOtaBackgroundScheduler();

  final List<String> scheduledTasks = [];

  @override
  Future<void> scheduleSilentUpdateTask({
    required String taskUniqueName,
    required bool requireWifi,
    required bool requireBatteryNotLow,
  });
}

---

5. OTA Asset Manager (src/assets/ota_asset_manager.dart)

class OtaAssetIntegrityException implements Exception {
  OtaAssetIntegrityException({
    required this.assetKey,
    required this.expectedSha256,
    required this.actualSha256,
  });

  final String assetKey;
  final String expectedSha256;
  final String actualSha256;

  @override
  String toString();
}

class OtaRemoteAssetDescriptor {
  const OtaRemoteAssetDescriptor({
    required this.assetKey,
    required this.downloadUrl,
    required this.expectedSha256,
  });

  final String assetKey;
  final String downloadUrl;
  final String expectedSha256;
}

class OtaAssetManager {
  OtaAssetManager({
    required this.cacheDirectory,
    http.Client? httpClient,
  });

  final Directory cacheDirectory;

  File cachedFileFor(OtaRemoteAssetDescriptor descriptor);

  /// Throws [HttpException] if HTTP status != 200.
  /// Throws [OtaAssetIntegrityException] if computed SHA-256 != expectedSha256.
  Future<File> getOrDownloadAsset(
    OtaRemoteAssetDescriptor descriptor, {
    Map<String, String>? headers,
  });
}

---

6. Types Re-Exported from shorebird_code_push

lib/tk_ota_push.dart re-exports UpdateStatus, UpdateTrack, and Patch:

class Patch {
  const Patch({required this.number});
  final int number;
}

enum UpdateStatus {
  upToDate,
  outdated,
  restartRequired,
  unavailable,
}

extension type const UpdateTrack(String value) {
  static const staging = UpdateTrack('staging');
  static const beta = UpdateTrack('beta');
  static const stable = UpdateTrack('stable');
  String get name => value;
}