API reference

import { FlowPilot } from '@flowpilotjs/react-native-sdk';

// Validate and apply configuration. Throws on an invalid API key or empty App ID.
FlowPilot.configure(config: FlowPilotConfiguration): void

FlowPilot.isConfigured: boolean   // getter: true after a successful configure
FlowPilot.sdkVersion: string      // getter: e.g. "1.0.2"

type EnvironmentConfig = 'development' | 'staging' | 'production' | { baseUrl: string };
type PrefetchMediaStrategy = 'none' | 'firstScreen' | 'allScreens';
type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug' | 'verbose';

// Resolve and present a full-screen modal. Never rejects; reports via outcome.
presentPlacement(placementId: string): Promise<FlowPresentationResult>

// Resolve and return an unstarted session. Rejects when nothing is presentable.
createSession(placementId: string): Promise<FlowSession>

// Non-throwing counterpart. Returns null when nothing is presentable.
resolveSession(placementId: string): Promise<FlowSession | null>

// Build a session from raw flow JSON (preview/testing). No SDK config / network.
createSessionFromSchema(
  schema: FlowDefinition,
  options?: { suppressAnalytics?: boolean; mediaBaseUrl?: string; iconBaseUrl?: string },
): FlowSession

// True if a presentable flow is available now (warms the cache as a side effect).
isPlacementReady(placementKey: string): Promise<boolean>

// Warm one or more placements. Best-effort, concurrent, never rejects.
prefetch(
  placementIds: string[],
  options?: { warmMedia?: boolean },
): Promise<Record<string, PrefetchOutcome>>

type PrefetchState =
  | { type: 'warmed' }
  | { type: 'noFlow' }
  | { type: 'failed'; error: Error };

interface PrefetchOutcome {
  placementKey: string;
  state: PrefetchState;
  mediaWarmed: boolean;
  isWarmed: boolean;
}

// Full-screen modal presenter (FlowPresenter wrapped in a Modal).
function FlowPilotPresenter(props: FlowPilotPresenterProps): JSX.Element

interface FlowPilotPresenterProps {
  session: FlowSession | null;
  onComplete?: (result: FlowPresentationResult) => void;
  safeAreaInsets?: { top: number; bottom: number; left: number; right: number };
  animationType?: 'none' | 'slide' | 'fade';                                   // default 'slide'
  presentationStyle?: 'fullScreen' | 'pageSheet' | 'formSheet' | 'overFullScreen'; // default 'fullScreen'
  statusBarStyle?: 'default' | 'light-content' | 'dark-content';
  fallback?: React.ReactNode | (() => React.ReactNode);
  onError?: (error: Error) => void;
}

// Lower-level renderer (no Modal wrapper), for custom embedding.
function FlowPresenter(props: FlowPresenterProps): JSX.Element

class FlowSession {
  // Read-only state
  readonly placementId: string;
  readonly resolveResponse: ResolveResponse;
  readonly variableStore: VariableStore;
  readonly actionExecutor: ActionExecutor;
  readonly analyticsBatcher: AnalyticsBatcher;
  readonly mediaBaseUrl: string;
  readonly iconBaseUrl: string;
  suppressAnalytics: boolean;

  get flow(): FlowDefinition;
  get navigationController(): NavigationController;
  get state(): FlowSessionState;            // 'idle'|'loading'|'active'|'completed'|'error'
  get currentScreen(): ScreenNode | null;
  get isFlowClosed(): boolean;

  // Lifecycle
  setDelegate(delegate: FlowSessionDelegate): void;
  start(): void;
  dismiss(): void;
  failPresentation(): void;
  reset(): void;
  replaceFlow(newDefinition: FlowDefinition, fonts?: FontFile[]): Promise<void>;

  // Conversions
  trackConversion(amount: number, currency: string, productId?: string, metadata?: Record<string, unknown>): void;
}

interface FlowPresentationResult {
  outcome: 'completed' | 'dismissed' | 'error';
  error?: Error;
}

type FlowOutcome = 'completed' | 'dismissed' | 'error';
type FlowSessionState = 'idle' | 'loading' | 'active' | 'completed' | 'error';

type FlowSessionDelegate = {
  onScreenChange(screen: ScreenNode, transition: TransitionConfig, direction: 'forward' | 'back'): void;
  onFlowComplete(outcome: FlowOutcome): void;
  onStateChange(state: FlowSessionState): void;
};

type VariableValue = string | number | boolean | string[] | number[] | boolean[];
type VariableTypeName = 'string' | 'number' | 'boolean' | 'list';

interface FlowVariable {
  key: string;
  label?: string;
  type: VariableTypeName;
  listItemType?: 'string' | 'number' | 'boolean';
  scope: 'global';
  lifecycle: 'static' | 'session';
  source: { kind: 'constant'; value: VariableValue } | { kind: 'sdk'; path: string };
  writable: boolean;
  defaultValue?: VariableValue;
}

// Reactive store on each session (advanced).
class VariableStore {
  get(key: string): VariableValue | undefined;
  getByLabelOrKey(labelOrKey: string): VariableValue | undefined;
  getAll(): Record<string, VariableValue>;
  set(key: string, value: VariableValue): boolean;     // false if unknown or read-only
  contains(key: string): boolean;
  interpolate(template: string): string;
  subscribe(listener: () => void): () => void;
  // ...plus batch/reset helpers
}

// Expression / property helpers (advanced)
function evaluateCondition(condition: Condition, store: VariableStore): boolean;
function resolveProperty<T>(value: PropertyValue<T>, store: VariableStore): T | undefined;
function resolveStringProperty(value: PropertyValue<string>, store: VariableStore): string | undefined;

// Custom components (rendered).
registerCustomComponent(key: string, definition: {
  version?: number;
  inputs?: Record<string, VariableTypeName>;
  outputs?: Record<string, { description?: string; payload?: Record<string, VariableTypeName> }>;
  component: React.ComponentType<CustomComponentRenderProps>;
}): void
unregisterCustomComponent(key: string, version?: number): void
getCustomComponent(key: string, version: number): CustomComponentDefinition | undefined

// Custom screens (registered but NOT rendered in this build).
registerCustomScreen(screenId: string, definition: {
  inputs?: Record<string, VariableTypeName>;
  outputs?: Record<string, { description?: string; payload?: Record<string, VariableTypeName> }>;
  component: React.ComponentType<CustomScreenRenderProps>;
}): void

// Custom actions.
registerCustomAction(key: string, handler: CustomActionHandler): void
unregisterCustomAction(key: string): void

interface CustomComponentRenderProps {
  props: { inputs: Record<string, VariableValue> };
  context: CustomComponentContext;
}
interface CustomComponentContext {
  containerSize: { width: number; height: number };
  containerConstraints: {
    minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number;
    supportsIntrinsicSize: boolean;
  };
  emit(eventName: string, payload?: Record<string, unknown>): void;
}

interface CustomScreenRenderProps {
  props: { inputs: Record<string, VariableValue> };
  context: CustomScreenContext;
}
interface CustomScreenContext extends CustomComponentContext {
  screenId: string;
  setZonesVisible(visible: boolean): void;
}

type CustomActionHandler = (
  params: Record<string, unknown> | undefined,
  context: ActionContext,
) => Promise<void>;

interface ActionContext {
  variableStore: VariableStore;
  navigationController: NavigationController;
  analyticsTracker?: { track(eventKey: string, properties?: Record<string, unknown>): void; /* ... */ };
  flowId: string;
  screenId?: string;
  elementId?: string;
  elementType?: string;
  isFlowClosed: boolean;
}

// Additive callback for every analytics event the SDK emits.
setAnalyticsCallback(callback: AnalyticsCallback): void
type AnalyticsCallback = (event: { eventName: string; properties: Record<string, unknown> }) => void

// Conversion attributed to the most-recently-started session.
trackConversion(amount: number, currency: string, productId?: string, metadata?: Record<string, unknown>): void

class FlowPilotError extends Error {
  readonly code: ErrorCode;
  readonly underlyingError?: Error;
  readonly context?: Record<string, string>;
}

type ErrorCode =
  | 'INVALID_API_KEY' | 'SDK_NOT_INITIALIZED' | 'NETWORK_ERROR' | 'API_ERROR'
  | 'TIMEOUT' | 'RATE_LIMITED' | 'PLACEMENT_NOT_FOUND' | 'FLOW_NOT_FOUND'
  | 'UNSUPPORTED_SCHEMA_VERSION' | 'INVALID_FLOW_SCHEMA' | 'COMPONENT_RENDER_ERROR'
  | 'CUSTOM_COMPONENT_NOT_FOUND' | 'NAVIGATION_ERROR' | 'VARIABLE_ERROR'
  | 'ACTION_ERROR' | 'ACTION_CHAIN_TIMEOUT' | 'INTERNAL_ERROR';

clearCache(): void
clearImageCache(): void
registerBundledFlow(placementKey: string, json: object, assets?: BundledFlowAssets): void
registerBundledFlowAssets(placementKey: string, assets: BundledFlowAssets): void

// Which fail-safe tier produced a presented flow (surfaced as delivery_source).
type FlowDeliverySource = 'network' | 'cache' | 'stale_cache' | 'bundled_default';

interface BundledFlowAssets {
  manifest: {
    images: { url?: string; src?: string; resource: string }[];
    icons: { url?: string; name?: string; resource: string }[];
    fonts: { family: string; weight: number; style?: string; resource: string }[];
  };
  resources: Record<string, number | string>; // resource path -> require()'d module or uri
}

class MediaPreloader {
  preload(
    flow: FlowDefinition, mediaBaseUrl: string, iconBaseUrl: string,
    onProgress?: PreloadProgressCallback, options?: { firstScreenOnly?: boolean },
  ): Promise<PreloadProgress>;
  abort(): void;
}
const mediaPreloader: MediaPreloader; // the SDK's shared instance

interface PreloadProgress {
  totalItems: number; completedItems: number; failedItems: number;
  currentScreenIndex: number; progress: number; isComplete: boolean;
}
type PreloadProgressCallback = (progress: PreloadProgress) => void;

// Fonts
class FontManager { /* loadFonts, registerLocalFont, resolveFont, isLoaded, clear, ... */ }
const fontManager: FontManager;
function fontWeightToRN(weight: number | string): string;

function initAccessibility(): void;            // start reduce-motion monitoring (called by configure)
function isReduceMotionEnabled(): boolean;
function useReduceMotion(): boolean;           // React hook
function getAccessibilityRole(componentType: string): string | undefined;
function buildAccessibilityProps(/* ... */): object;
function buildProgressAccessibility(/* ... */): object;