Skip to main content

Types

Every type the Swiftpatch SDK exports. Fully documented and stable across minor versions.

Config​

SwiftPatchUserConfig​

The simple config most apps use. Passed to <SwiftPatchProvider config={...}> or new SwiftPatch(...).

interface SwiftPatchUserConfig {
  deploymentKey?: string;
  debug?: boolean;
  onUpdate?: (release: ReleaseInfo) => void;
}

SwiftPatchConfig​

The full config surface. Every field optional; see Configuration for defaults and recommended values.

interface SwiftPatchConfig extends SwiftPatchUserConfig {
  appId?: string;
  serverUrl?: string;
  checkOnResume?: boolean;
  checkInterval?: number;
  installMode?: InstallMode;
  mandatoryInstallMode?: InstallMode;
  customHeaders?: Record<string, string>;
  publicKey?: string;
  autoStabilizeAfterLaunches?: number;
  crashDetectionWindowMs?: number;
  maxCrashesBeforeRollback?: number;
  autoStagingInDev?: boolean;
}

Enums​

InstallMode​

enum InstallMode {
  IMMEDIATE = 'immediate',
  ON_NEXT_RESTART = 'onNextRestart',
  ON_NEXT_RESUME = 'onNextResume',
}

UpdateStatus​

The lifecycle state exposed on the useSwiftPatch() hook (legacy).

enum UpdateStatus {
  CHECKING = 'checking',
  UP_TO_DATE = 'upToDate',
  UPDATE_AVAILABLE = 'updateAvailable',
  DOWNLOADING = 'downloading',
  READY_TO_INSTALL = 'readyToInstall',
  INSTALLING = 'installing',
  RESTART_REQUIRED = 'restartRequired',
  ERROR = 'error',
}

SwiftPatchErrorCode​

High-level error categories on the SwiftPatchError type. See Error codes for the full 33-code taxonomy.

enum SwiftPatchErrorCode {
  NETWORK_ERROR = 'NETWORK_ERROR',
  DOWNLOAD_ERROR = 'DOWNLOAD_ERROR',
  VERIFICATION_ERROR = 'VERIFICATION_ERROR',
  PATCH_ERROR = 'PATCH_ERROR',
  INSTALL_ERROR = 'INSTALL_ERROR',
  CONFIG_ERROR = 'CONFIG_ERROR',
  STABILIZE_ERROR = 'STABILIZE_ERROR',
  ENVIRONMENT_ERROR = 'ENVIRONMENT_ERROR',
  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
}

Release + bundle types​

ReleaseInfo​

The release descriptor the server returns from a check.

interface ReleaseInfo {
  id: string;
  version: string;       // Semver, e.g., '1.2.3'
  releaseNote: string | null;
  isMandatory: boolean;
  bundleHash: string;    // SHA-256 of the bundle
  downloadUrl: string;   // Signed URL
  downloadSize: number;  // Bytes
  isPatch: boolean;      // True when delta patch, false when full bundle
  signature?: string;    // Ed25519 signature (base64)
  releasedAt: string;    // ISO 8601 timestamp
}

UpdateInfo is re-exported as an alias for ReleaseInfo:

type UpdateInfo = ReleaseInfo;

BundleInfo​

The currently installed bundle.

interface BundleInfo {
  hash: string;          // SHA-256
  version: string;
  installedAt: string;
  isOriginal: boolean;   // True when the store-bundled JS is active
  slot: SlotState;
  environment: EnvironmentMode;
}

DownloadProgress​

interface DownloadProgress {
  downloadedBytes: number;
  totalBytes: number;
  percentage: number;    // 0–100
}

Orchestrator types​

UpdatePhase​

type UpdatePhase =
  | 'idle'
  | 'checking'
  | 'downloading'
  | 'ready'
  | 'applying'
  | 'error';

UpdateState​

interface UpdateState {
  phase: UpdatePhase;
  current?: BundleInfo | null;
  pending?: UpdateInfo | null;
  lastCheckedAt?: Date | null;
  lastError?: SwiftPatchError | null;
}

UpdatePolicy​

interface UpdatePolicy {
  prompt: 'always' | 'mandatory-only' | 'silent';
  applyTiming: 'immediate' | 'on-resume' | 'on-next-launch';
}

Event types​

SwiftpatchEvent​

Discriminated union of every event on the bus. See Events for details.

type SwiftpatchEvent =
  | { type: 'update-available'; update: UpdateInfo }
  | { type: 'download-started'; hash: string; sizeBytes: number }
  | { type: 'download-progress'; hash: string; loaded: number; total: number }
  | { type: 'download-complete'; hash: string }
  | { type: 'update-ready'; update: UpdateInfo }
  | { type: 'update-applied'; update: UpdateInfo }
  | { type: 'update-dismissed'; update: UpdateInfo }
  | { type: 'rollback'; reason: string }
  | { type: 'error'; error: SwiftPatchError };

type SwiftpatchEventType = SwiftpatchEvent['type'];

type Unsubscribe = () => void;

Error shapes​

SwiftPatchError​

interface SwiftPatchError {
  code: SwiftPatchErrorCode;
  message: string;
  details?: unknown;
}

Breadcrumb / BreadcrumbSink / BreadcrumbLevel​

type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error';

interface Breadcrumb {
  level: BreadcrumbLevel;
  category: string;              // e.g. 'swiftpatch.download'
  message: string;
  data?: Record<string, string | number | boolean>;
  timestamp: number;             // ms since epoch
}

type BreadcrumbSink = (crumb: Breadcrumb) => void;

Native config​

interface NativeConfig {
  projectId: string | null;
  appToken: string | null;
  appId: string | null;
  deploymentKey: string | null;
  serverUrl: string | null;
  publicKey: string | null;
}

Next steps​

  • Methods — how to call the APIs that use these types.
  • Events — what triggers SwiftpatchEvent payloads.
  • Error codes — the full 33-code taxonomy behind SwiftPatchError.code.
On this page