feat(analytics): Adds feature flag support to main SDK

[efahk]

This change brings in the react native feature flag implementation into the main SDK

[greptile-apps]

Confidence Score: 3/5

The core flag evaluation path is functional but has two issues that can cause silent data loss or incorrect fallback behavior in production.

The persistence layer unconditionally deletes stored flag variants when the resolved policy is NETWORK_ONLY — which includes the case where flags are entirely disabled. Any code path that accesses mixpanel.flags without enabled: true would wipe previously persisted data. The pending_variant null-access crash in _processFirstTimeEventCheck (flagged in a prior review cycle but not yet fixed) can also throw on every track() call matching first-time-event criteria if the server omits pending_variant.

javascript/mixpanel-flag-persistence.js (unconditional clear() on disabled-flags access) and javascript/mixpanel-flags-js.js (missing null guard around pendingEvent.pending_variant in _processFirstTimeEventCheck).

Important Files Changed

Filename	Overview
javascript/mixpanel-flag-persistence.js	Flag storage layer with TTL and distinct_id context validation. loadFlagsFromStorage unconditionally calls clear() on NETWORK_ONLY policy, which fires even when flags are entirely disabled, silently deleting persisted variants.
javascript/mixpanel-flags-js.js	Core JS-mode flag implementation: network fetch with W3C traceparent, json-logic first-time-event matching, experiment tracking. Has the unaddressed pending_variant null-access crash when server omits the field.
index.js	Public SDK surface: adds flags lazy getter, featureFlagsOptions plumbing, and flag reset/identify integration. Native mode auto-loads flags during init(); JS mode does not, creating an undocumented async asymmetry.
javascript/mixpanel-flags.js	Thin dispatch layer routing flag calls to native or JS implementation; dual callback/Promise API. Logic looks correct.
javascript/mixpanel-network.js	Refactored to support GET (flags) and POST (events); now forwards headers on retries, fixing the previously flagged Authorization header drop.
javascript/mixpanel-main.js	Adds featureFlagsOptions storage and _flagsJS back-reference for identify/track integration. Logic is correct.
ios/MixpanelReactNative.swift	Adds synchronous and async flag bridge methods for iOS. Synchronous methods correctly use RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD.
android/src/main/java/com/mixpanel/reactnative/MixpanelReactNativeModule.java	Adds flag bridge methods for Android; all sync methods correctly annotated with isBlockingSynchronousMethod = true.
index.d.ts	Adds TypeScript types for all new flag APIs. Types look complete and consistent with the implementation.
javascript/mixpanel-persistent.js	Adds generateUUID helper with proper fallbacks and fixes initializationCompletePromise to return the Promise. Both changes are correct.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant App
    participant Mixpanel
    participant Flags
    participant FlagsJS as MixpanelFlagsJS
    participant Network as MixpanelNetwork
    participant Storage as AsyncStorage

    App->>Mixpanel: "await init(opts, {enabled:true})"
    Mixpanel->>Mixpanel: store featureFlagsOptions
    Mixpanel->>Mixpanel: await mixpanelImpl.initialize()
    Note over Mixpanel: JS mode: skip flag load
    Note over Mixpanel: Native mode: await flags.loadFlags()

    App->>Mixpanel: mixpanel.flags (getter)
    Mixpanel->>Flags: new Flags(token, impl)
    Flags->>FlagsJS: new MixpanelFlagsJS(...)
    Flags->>FlagsJS: init() [not awaited]
    FlagsJS->>Storage: loadFlagsFromStorage(context)
    Storage-->>FlagsJS: persisted variants or null
    FlagsJS->>Network: "GET /flags?context=..."
    Network-->>FlagsJS: flags + pending_first_time_events
    FlagsJS->>Storage: save(context, flags)

    App->>Flags: await getVariant(flag, fallback)
    Flags->>FlagsJS: getVariant(...)
    FlagsJS->>FlagsJS: await persistenceLoadedPromise
    FlagsJS->>FlagsJS: await fetchPromise
    FlagsJS-->>App: variant

    App->>Mixpanel: track(Purchase, props)
    Mixpanel->>FlagsJS: checkFirstTimeEvents(Purchase, props)
    FlagsJS->>FlagsJS: match pendingFirstTimeEvents
    FlagsJS->>Network: "POST /flags/{id}/first-time-events"

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant App
    participant Mixpanel
    participant Flags
    participant FlagsJS as MixpanelFlagsJS
    participant Network as MixpanelNetwork
    participant Storage as AsyncStorage

    App->>Mixpanel: "await init(opts, {enabled:true})"
    Mixpanel->>Mixpanel: store featureFlagsOptions
    Mixpanel->>Mixpanel: await mixpanelImpl.initialize()
    Note over Mixpanel: JS mode: skip flag load
    Note over Mixpanel: Native mode: await flags.loadFlags()

    App->>Mixpanel: mixpanel.flags (getter)
    Mixpanel->>Flags: new Flags(token, impl)
    Flags->>FlagsJS: new MixpanelFlagsJS(...)
    Flags->>FlagsJS: init() [not awaited]
    FlagsJS->>Storage: loadFlagsFromStorage(context)
    Storage-->>FlagsJS: persisted variants or null
    FlagsJS->>Network: "GET /flags?context=..."
    Network-->>FlagsJS: flags + pending_first_time_events
    FlagsJS->>Storage: save(context, flags)

    App->>Flags: await getVariant(flag, fallback)
    Flags->>FlagsJS: getVariant(...)
    FlagsJS->>FlagsJS: await persistenceLoadedPromise
    FlagsJS->>FlagsJS: await fetchPromise
    FlagsJS-->>App: variant

    App->>Mixpanel: track(Purchase, props)
    Mixpanel->>FlagsJS: checkFirstTimeEvents(Purchase, props)
    FlagsJS->>FlagsJS: match pendingFirstTimeEvents
    FlagsJS->>Network: "POST /flags/{id}/first-time-events"

Loading

_{Reviews (10): Last reviewed commit: "upgrade rn for sample app" | Re-trigger Greptile}

[tylerjroach]

A few quick comments while I'm still doing a more thorough review.