API Reference

Everything is exported from @teardown/force-updates. Adapters live under sub-paths (/expo, /firebase, /wix, /adapters/*) — see Adapters.

TeardownCore

Create one instance and share it via TeardownProvider.

new TeardownCore({
  // Hosted:      { type: "hosted", org_id, project_id, api_key, ingestUrl? }
  // Self-hosted: { type: "self-hosted", ingestUrl }
  config: TeardownConfig;
  storageAdapter: StorageAdapter;   // required — see Adapters
  deviceAdapter: DeviceInfoAdapter; // required — see Adapters
  environment_slug?: string;        // default: "production"
  notificationAdapter?: NotificationAdapter;
  lifecycleAdapter?: LifecycleAdapter;   // e.g. AppStateLifecycleAdapter
  forceUpdate?: {
    checkIntervalMs?: number;       // default: 300000 (5 min). -1 disables checks
    checkOnForeground?: boolean;    // default: true (needs lifecycleAdapter)
    identifyAnonymousDevice?: boolean; // default: false
  };
});

Instance properties: identity, forceUpdate, device, events, notifications?, api, plus setLogLevel() and shutdown().

Hooks

Must be used inside TeardownProvider.

useForceUpdate()

const {
  versionStatus,        // VersionStatus
  isUpdateAvailable,    // boolean
  isUpdateRecommended,  // boolean
  isUpdateRequired,     // boolean
  releaseNotes,         // string | null
} = useForceUpdate();

useSession()

Returns the current Session | null, updating when identity changes.

const session = useSession();

useTeardown()

Returns { core } — the TeardownCore instance for imperative calls.

const { core } = useTeardown();

TeardownProvider

<TeardownProvider core={teardown}>
  {children}
</TeardownProvider>

Identity

Access via teardown.identity.

Method	Signature	Description
`identify`	`(user?: Persona) => AsyncResult<IdentityUser>`	Identify a device/user and refresh version status
`refresh`	`() => AsyncResult<IdentityUser>`	Re-identify the current persona
`signOut`	`(options?: SignOutOptions) => AsyncResult<void>`	Sign out, keeping the device ID
`signOutAll`	`(options?: SignOutOptions) => AsyncResult<void>`	Sign out and reset the device
`getSessionState`	`() => Session \| null`	Current session
`getIdentifyState`	`() => IdentifyState`	Current identity state
`onIdentifyStateChange`	`(listener: (state: IdentifyState) => void) => Unsubscribe`	Subscribe to changes

await teardown.identity.identify({ user_id: "user_123", email: "ada@example.com" });
await teardown.identity.signOut();

Force update

Access via teardown.forceUpdate.

Method	Signature
`getVersionStatus`	`() => VersionStatus`
`onVersionStatusChange`	`(listener: (status: VersionStatus) => void) => Unsubscribe`

Prefer the useForceUpdate hook in React components.

Device

Access via teardown.device.

Method	Signature
`getDeviceId`	`() => Promise<string>`
`getDeviceInfo`	`() => Promise<DeviceInfo>`
`reset`	`() => void` (new device ID on next `getDeviceId`)

Events

Access via teardown.events.

await teardown.events.track({
  event_name: "checkout_completed",
  event_type: "action", // "action" | "screen_view" | "custom"
  properties: { total: 42 },
});

trackBatch(events: EventPayload[]) sends multiple at once.

Notifications

Available as teardown.notifications only when a notificationAdapter is configured.

Method	Signature
`requestPermissions`	`() => Promise<PermissionStatus>`
`getToken`	`() => Promise<string \| null>`
`onTokenChange`	`(listener: (token: string) => void) => Unsubscribe`
`onNotificationReceived`	`(listener: (n: PushNotification) => void) => Unsubscribe`
`onNotificationOpened`	`(listener: (n: PushNotification) => void) => Unsubscribe`
`onDataMessage`	`(listener: (m: DataMessage) => void) => Unsubscribe`

Logging

teardown.setLogLevel("verbose"); // "none" | "error" | "warn" | "info" | "verbose"

Key types

type VersionStatus =
  | { type: "initializing" }
  | { type: "checking" }
  | { type: "up_to_date" }
  | { type: "update_available"; releaseNotes?: string }
  | { type: "update_recommended"; releaseNotes?: string }
  | { type: "update_required"; releaseNotes?: string }
  | { type: "disabled" };

interface Session {
  session_id: string;
  device_id: string;
  user_id: string;
  token: string;
}

type IdentifyState =
  | { type: "unidentified" }
  | { type: "identifying" }
  | { type: "identified"; session: Session; version_info: { /* ... */ } };

interface Persona {
  user_id?: string;
  email?: string;
  name?: string;
}

// AsyncResult<T> is a Promise that resolves to:
type Result<T> =
  | { success: true; data: T }
  | { success: false; error: string };

On this page