API reference

// Configure the SDK. Pass a FlowPilotConfiguration. No-ops (logs an error) if
// the API key does not start with "fp_", leaving FlowPilot.shared nil.
public static func configure(_ configuration: FlowPilotConfiguration)

// The shared instance. nil until configure(_:) succeeds.
public private(set) static var shared: FlowPilot?

// Merge new key/value pairs into the SDK context for future resolves.
public func updateContext(_ context: SDKContext)

public enum FlowPilotEnvironment: Sendable, Equatable {
    case development   // https://dev-api.flowpilot.io/v1
    case staging       // https://staging-api.flowpilot.io/v1
    case production    // https://api.flowpilot.io/v1
    case custom(url: String)
}

public enum FlowPilotLogLevel: Int, Comparable, Sendable {
    case none = 0
    case error = 1
    case warn = 2
    case info = 3
    case debug = 4
    case verbose = 5
}

public enum PrefetchMediaStrategy: Sendable {
    case none          // JSON + fonts only
    case firstScreen   // + first-screen & persistent-zone images (default)
    case allScreens    // + every screen's images
}

// Host-provided key/value context for variable resolution and targeting.
public typealias SDKContext = [String: Any]

// Resolve and present (UIKit). Returns the result.
@MainActor
public func presentPlacement(
    _ placementKey: String,
    from viewController: UIViewController,
    options: PresentationOptions? = nil
) async throws -> FlowResult

// Resolve and present (UIKit), with a completion closure instead of a return.
@MainActor
public func presentPlacement(
    _ placementKey: String,
    from viewController: UIViewController,
    options: PresentationOptions? = nil,
    completion: ((FlowResult) -> Void)? = nil
) async throws

// Never-throwing present (UIKit). Walks the full fallback chain, then presents
// your `fallback` view controller if FlowPilot has nothing to show.
@MainActor
@discardableResult
public func presentPlacement(
    _ placementKey: String,
    from viewController: UIViewController,
    fallback: @escaping @MainActor () -> UIViewController,
    options: PresentationOptions? = nil
) async -> FlowResult

// SwiftUI: build a session you drive with FlowPresenterView / .flowPresenter.
@MainActor
public func createSession(
    placementKey: String,
    additionalContext: SDKContext? = nil,
    preloadMedia: Bool? = nil
) async throws -> FlowSession

// SwiftUI: non-throwing counterpart. Returns nil when nothing is presentable.
@MainActor
public func resolveSession(
    placementKey: String,
    additionalContext: SDKContext? = nil,
    preloadMedia: Bool? = nil
) async -> FlowSession?

// True if a flow is cached or resolves for this placement. Not @MainActor.
// Routes through the cache-populating path, so the resolve is not wasted: a
// following present hits the cache.
public func isPlacementReady(_ placementKey: String) async -> Bool

// Warm the cache for one or more placements. Best-effort, concurrent, never
// throws; returns a per-placement outcome map. Pass warmMedia: true to also warm
// images (bounded by prefetchMediaStrategy). @discardableResult.
@discardableResult
public func prefetch(
    _ placementKeys: [String],
    warmMedia: Bool? = nil
) async -> [String: PrefetchOutcome]

public struct PrefetchOutcome: Sendable {
    public enum State: Sendable {
        case warmed(fromCache: Bool)   // a presentable flow is cached and ready
        case noFlow                    // resolve ok, backend has nothing to show
        case failed(FlowPilotError)    // resolve failed; nothing warmed
    }
    public let placementKey: String
    public let state: State
    public let mediaWarmed: Bool       // first/all-screen images warmed
    public var isWarmed: Bool          // convenience: true when state is .warmed
}

public struct PresentationOptions: Sendable {
    public let additionalContext: SDKContext?
    public let presentationStyle: PresentationStyle?
    public let animated: Bool

    public init(
        additionalContext: SDKContext? = nil,
        presentationStyle: PresentationStyle? = nil,
        animated: Bool = true
    )
}

public enum PresentationStyle: String, Sendable {
    case fullScreen
    case modal
    case bottomSheet
}

public struct PlacementInfo: Sendable {
    public let placementId: String
    public let placementKey: String
    public let willShow: Bool
    public let flowId: String?
    public let experimentId: String?
    public let variantId: String?
}

public private(set) var flow: ResolvedFlow
public let placementId: String?

@Published public private(set) var currentScreen: ScreenNode?
@Published public private(set) var isActive: Bool
@Published public private(set) var mediaPreloadProgress: Double   // 0.0 ... 1.0
@Published public private(set) var isMediaPreloaded: Bool

public var id: String   // Identifiable

// Variables
public func getVariable(_ key: String) -> VariableValue?
public func getAllVariables() -> [String: VariableValue]
@discardableResult public func setVariable(_ key: String, value: VariableValue) -> Bool
public func resetVariables(sdkContext: SDKContext? = nil)

// Media preloading
public func waitForMediaPreload() async
public func cancelMediaPreload()

// Conversions
public func trackConversion(
    amount: Double,
    currency: String,
    productId: String? = nil,
    metadata: [String: Any]? = nil
)

// Lifecycle
public func startNavigation()
public func waitForCompletion() async -> FlowResult
public func dismiss()
public func failPresentation()
public func navigate(to screenNodeId: String)

// Live mirror hot-replace (used by the preview tooling)
@MainActor public func replaceFlow(_ newDefinition: FlowDefinition, fonts: [FontFile]? = nil)

// Preview-only initializer (skips resolution, suppresses analytics)
public convenience init(
    flow: ResolvedFlow,
    suppressAnalytics: Bool = true,
    sdkContext: SDKContext? = nil
)

// Deprecated: use startNavigation() then waitForCompletion()
@available(*, deprecated)
public func start() async -> FlowResult

// SwiftUI view that renders a session.
@MainActor
public struct FlowPresenterView: View {
    public init(session: FlowSession)
}

// View modifier: present when the bound session is non-nil, clear it on result.
extension View {
    public func flowPresenter(
        session: Binding<FlowSession?>,
        onResult: ((FlowResult) -> Void)? = nil
    ) -> some View
}

// UIKit hosting controller that wraps FlowPresenterView (UIKit only).
@MainActor
public class FlowHostingController: UIHostingController<FlowPresenterView> {
    public init(session: FlowSession)
    public func onCompletion(_ handler: @escaping (FlowResult) -> Void)
}

public struct FlowResult: Sendable {
    public let outcome: FlowOutcome
    public let finalVariables: [String: VariableValue]
    public let screensVisited: [String]
    public let durationMs: Int
    public let experimentAssignments: [String: String]
    public let error: FlowPilotError?
}

public enum FlowOutcome: String, Sendable {
    case completed
    case dismissed
    case error
}

public enum VariableValue: Sendable, Equatable, Codable {
    case string(String)
    case number(Double)
    case boolean(Bool)
    case stringList([String])
    case numberList([Double])
    case booleanList([Bool])

    // Typed accessors (coercing where noted)
    public var stringValue: String?
    public var numberValue: Double?        // coerces a numeric string
    public var intValue: Int?              // coerces a numeric string
    public var boolValue: Bool?            // coerces "true"/"1"/"yes" and numbers
    public var stringListValue: [String]?
    public var numberListValue: [Double]?
    public var booleanListValue: [Bool]?

    // Inspection
    public var isEmpty: Bool
    public var isString: Bool
    public var isNumber: Bool
    public var isBoolean: Bool
    public var isList: Bool
    public var typeName: String
    public var displayString: String
}

public enum VariableType: String, Codable, Sendable {
    case string
    case number
    case boolean
    case list
}

// Used by custom components: an input that is either a bound variable or a constant.
public enum ComponentInputValue: Codable, Sendable {
    case bind(String)
    case value(VariableValue)
}

// Register / unregister a custom component by key (+ version, default 1).
public func registerCustomComponent(
    key: String,
    version: Int = 1,
    definition: CustomComponentDefinition
)
public func unregisterCustomComponent(key: String, version: Int = 1)

// Deprecated bare-key overloads (use version 1).
@available(*, deprecated)
public func registerCustomComponent(_ typeId: String, definition: CustomComponentDefinition)
@available(*, deprecated)
public func unregisterCustomComponent(_ typeId: String)

// Custom screens.
public func registerCustomScreen(_ screenId: String, definition: CustomScreenDefinition)
public func unregisterCustomScreen(_ screenId: String)

public struct CustomComponentDefinition: Sendable {
    public let inputs: [String: VariableType]?
    public let outputs: [String: OutputSchema]?
    public let factory: @Sendable @MainActor (CustomComponentProps, CustomComponentContext) -> AnyView

    public init(
        inputs: [String: VariableType]? = nil,
        outputs: [String: OutputSchema]? = nil,
        factory: @escaping @Sendable @MainActor (CustomComponentProps, CustomComponentContext) -> AnyView
    )
}

public struct OutputSchema: Sendable {
    public let description: String?
    public let payload: [String: VariableType]?
    public init(description: String? = nil, payload: [String: VariableType]? = nil)
}

public struct CustomComponentProps: Sendable {
    public let inputs: [String: VariableValue]
    // Read-only validated accessors (warn in debug on type mismatch):
    public func string(_ key: String) -> String?
    public func string(_ key: String, default defaultValue: String) -> String
    public func number(_ key: String) -> Double?
    public func number(_ key: String, default defaultValue: Double) -> Double
    public func bool(_ key: String) -> Bool?
    public func bool(_ key: String, default defaultValue: Bool) -> Bool
    public func int(_ key: String) -> Int?
    public func int(_ key: String, default defaultValue: Int) -> Int
}

public final class CustomComponentContext: @unchecked Sendable {
    public let containerSize: CGSize
    public let containerConstraints: ContainerConstraints
    public func emit(_ eventName: String, payload: [String: Any]? = nil)
    public func emit(_ eventName: String)

    public struct ContainerConstraints: Sendable {
        public let minWidth: Double?
        public let maxWidth: Double?
        public let minHeight: Double?
        public let maxHeight: Double?
        public let supportsIntrinsicSize: Bool
    }
}

public struct CustomScreenDefinition: Sendable {
    public let inputs: [String: VariableType]?
    public let outputs: [String: OutputSchema]?
    public let factory: @Sendable @MainActor (CustomScreenParams, CustomScreenContext) -> AnyView
    public init(/* same shape as CustomComponentDefinition */)
}

public struct CustomScreenParams: Sendable {
    public let inputs: [String: VariableValue]
    public func string(_ key: String) -> String?
    public func string(_ key: String, default defaultValue: String) -> String
    public func number(_ key: String) -> Double?
    public func number(_ key: String, default defaultValue: Double) -> Double
    public func bool(_ key: String) -> Bool?
    public func bool(_ key: String, default defaultValue: Bool) -> Bool
}

public final class CustomScreenContext: @unchecked Sendable {
    public func emit(_ eventName: String, payload: [String: Any]? = nil)
    public func emit(_ eventName: String)
    public func setZonesVisible(_ visible: Bool)
    @available(*, deprecated) public func setChromeVisible(_ visible: Bool)
}

// Set an additive callback that receives every analytics event the SDK emits.
public func setAnalyticsCallback(_ callback: @escaping AnalyticsCallback)

public typealias AnalyticsCallback = (AnalyticsEvent) -> Void

public struct AnalyticsEvent: Codable, Sendable {
    public let eventId: String          // wire: event_id
    public let appId: String            // wire: app_id
    public let eventName: String        // wire: event_type
    public let timestamp: Date
    public let placementId: String?
    public let flowId: String
    public let flowVersionId: String
    public let userId: String
    public let sessionId: String
    public let devicePlatform: String   // "ios"
    public let sdkVersion: String
    public let flowVersion: Int?
    public let experimentId: String?
    public let variantId: String?
    public let variantName: String?
    public let screenId: String?
    public let screenName: String?
    public let screenIndex: Int?
    public let elementId: String?
    public let elementType: String?
    public let interactionType: String?
    public let revenue: Double?
    public let currency: String?
    public let timeSinceFlowStartMs: Int?
    public let timeOnScreenMs: Int?
    public let appVersion: String?
    public let country: String?
    public let properties: [String: AnyCodable]?
}

// Events the SDK fires automatically.
public enum AutomaticEventType: String, Sendable {
    case flowStarted = "flow_start"
    case flowCompleted = "flow_complete"
    case flowDismissed = "flow_exit"
    case screenViewed = "screen_view"
    case screenExited = "screen_exit"
    case experimentAssigned = "experiment_exposure"
    case elementInteraction = "element_interaction"
}

public func setErrorCallback(_ callback: @escaping ErrorCallback)
public typealias ErrorCallback = (FlowPilotError) -> Void

public struct FlowPilotError: Error, Sendable, CustomStringConvertible {
    public let code: FlowPilotErrorCode
    public let message: String
    public let underlyingError: Error?
    public let context: [String: String]?
    public var description: String
    public var localizedDescription: String
    public var isClientError: Bool     // true for a 4xx status in context
    public var isServerError: Bool     // true for a 5xx status in context
}

// Clear cached flows + fonts + icons.
public func clearCache() async

// Clear cached images + icons.
public func clearImageCache()

// The shared image cache, for advanced use.
public var imageCache: ImageCache { get }

// Register a bundled (offline) default flow for a placement. Four overloads:
public func registerBundledFlow(placementKey: String, json: Data, assets: BundledFlowAssets? = nil)
public func registerBundledFlow(
    placementKey: String,
    resource: String,
    withExtension ext: String = "json",
    in bundle: Bundle = .main,
    assets: BundledFlowAssets? = nil
)
public func registerBundledFlow(
    placementKey: String,
    assetBundle subdirectory: String,
    in bundle: Bundle = .main,
    flowResource: String = "flow",
    manifestResource: String = "manifest"
)
public func registerBundledFlowAssets(placementKey: String, assets: BundledFlowAssets)

public final class ImageCache: @unchecked Sendable {
    public static let shared: ImageCache
    public static let bundledAssetTTL: TimeInterval   // effectively non-expiring
    public var maxMemoryCacheSize: Int                // default 50MB
    public var maxDiskCacheSize: Int                  // default 200MB
    public var defaultTTL: TimeInterval               // default 7 days

    public init(cacheDirectory: String? = nil)
    public func getImage(for url: URL) -> UIImage?
    public func hasImage(for url: URL) -> Bool
    public func setImage(_ image: UIImage, for url: URL, ttl: TimeInterval? = nil)
    public func setImageData(_ data: Data, for url: URL, ttl: TimeInterval? = nil)
    public func removeImage(for url: URL)
    public func clearAll()
    public func cleanExpired()
}

public struct BundledFlowAssets: @unchecked Sendable {
    // Assets in a plain filesystem directory (manifest + files).
    public init(directoryURL: URL, manifest: String = "manifest")
    // Assets in an app bundle, optionally inside a folder-reference subdirectory.
    public init(bundle: Bundle = .main, subdirectory: String? = nil, manifest: String = "manifest")
}

public typealias AnalyticsCallback = (AnalyticsEvent) -> Void
public typealias ErrorCallback = (FlowPilotError) -> Void
public typealias FlowCompletionCallback = (FlowResult) -> Void
public typealias FlowDismissalCallback = (String) -> Void

// Draw debug borders around rendered components.
public static var debugBordersEnabled: Bool

// Raise the log level to .verbose (development only).
public func enableDebugOverlay()
// Restore the configured log level.
public func disableDebugOverlay()
// Log user id, session id, environment, and registry counts.
public func logState()

public protocol FlowPilotDelegate: AnyObject {
    func flowPilotDidComplete(_ flowId: String, result: FlowResult)
    func flowPilotDidDismiss(_ flowId: String)
    func flowPilotDidFail(_ error: FlowPilotError)
}