zixflow-reactnative 1.1.2 → 1.1.4

package/src/utils/param-validation.ts

@@ -1,6 +1,7 @@
 // Argument validation utilities for SDK internal use
 // Ensures input safety and throws clear errors when validation fails
 
+import { ZixflowColorScheme } from '../types';
 import type { ZixflowConfig, CustomAttributes } from '../types';
 
 /**
@@ -32,6 +33,16 @@ function failIf(condition: boolean, message: () => string): void {
   }
 }
 
+/**
+ * Logs a warning if the condition is true.
+ * Use this for misconfigurations that degrade behavior but must not fail initialization.
+ */
+function warnIf(condition: boolean, message: () => string): void {
+  if (__DEV__ && condition) {
+    console.warn(`[Zixflow] ${message()}`);
+  }
+}
+
 /**
  * Validates that a value is defined (not undefined or null).
  * Useful for checking required fields.
@@ -137,6 +148,92 @@ function validateAttributes(
   return attributes as CustomAttributes;
 }
 
+/**
+ * The placeholder the SDK substitutes with the unread count when rendering
+ * `bellWithUnreadCount`.
+ */
+const COUNT_PLACEHOLDER = '{count}';
+
+/**
+ * Warns when `bellWithUnreadCount` is missing its `{count}` placeholder.
+ *
+ * The label is a template, not a finished string. A misspelled placeholder (`{COUNT}`,
+ * `{{count}}`, `%d`) matches nothing, so the template is announced verbatim — braces and all —
+ * and the count is never spoken. The check lives here rather than in either native layer
+ * because neither can report it usefully: Android logs at `debug`, which the default `ERROR`
+ * level discards, and iOS does not check at all. Warning from JavaScript reaches the
+ * developer's console on both platforms, whatever the SDK log level.
+ */
+function validateInboxAccessibilityLabels(value: unknown): void {
+  if (isUndefined(value) || typeof value !== 'object') {
+    return;
+  }
+
+  const template = (value as { bellWithUnreadCount?: unknown })
+    .bellWithUnreadCount;
+  warnIf(
+    typeof template === 'string' && !template.includes(COUNT_PLACEHOLDER),
+    () =>
+      `"inApp.notificationInboxAccessibilityLabels.bellWithUnreadCount" has no ` +
+      `"${COUNT_PLACEHOLDER}" placeholder, so the unread count will not be announced.`
+  );
+}
+
+/**
+ * Warns when a value is not one of the `ZixflowColorScheme` values.
+ *
+ * TypeScript rejects a bad value already, but JavaScript callers reach both entry points
+ * untyped, and neither native layer reports the mistake at the default log level. The
+ * failure mode is a message rendered in the wrong theme with no error attached, so
+ * JavaScript is the only place the developer reliably sees it.
+ *
+ * `consequence` differs per entry point because the native fallback does: an unrecognized
+ * value at initialization resolves to `auto`, while the runtime setter leaves whatever
+ * scheme the app already chose in place.
+ */
+function warnIfNotColorScheme(
+  value: unknown,
+  fieldName: string,
+  consequence: string
+): void {
+  const allowed: string[] = Object.values(ZixflowColorScheme);
+  warnIf(
+    !(typeof value === 'string' && allowed.includes(value)),
+    () =>
+      `"${fieldName}" is not a valid ZixflowColorScheme (expected one of ` +
+      `${allowed.join(', ')}), so ${consequence}.`
+  );
+}
+
+/**
+ * Validates `inApp.colorScheme`. An absent value is legitimate here — the native SDKs
+ * already default to `auto` — so only a value the host actually set is checked.
+ */
+function validateConfigColorScheme(value: unknown): void {
+  if (isUndefined(value)) {
+    return;
+  }
+
+  warnIfNotColorScheme(
+    value,
+    'inApp.colorScheme',
+    'in-app messages will follow the device appearance'
+  );
+}
+
+/**
+ * Validates the argument to `setColorScheme`. Unlike the config field, an absent value is
+ * itself the mistake: the caller asked for a scheme change and named none, and there is no
+ * default to fall back to, so null and undefined are reported rather than skipped.
+ */
+function validateColorSchemeArgument(value: unknown): void {
+  warnIfNotColorScheme(
+    value,
+    'colorScheme',
+    'the color scheme will be left unchanged'
+  );
+}
+
 /**
  * Validates that the given value is a valid ZixflowConfig object.
  * Throws if required fields are missing or incorrectly typed.
@@ -151,10 +248,14 @@ function validateConfig(value: unknown): asserts value is ZixflowConfig {
   });
 
   const obj = value as ZixflowConfig;
-  validateString(obj.cdpApiKey, `${fieldName}.cdpApiKey`, {
+  validateString(obj.apiKey, `${fieldName}.apiKey`, {
     allowEmpty: false,
     usage: usage,
   });
+  validateConfigColorScheme(obj.inApp?.colorScheme);
+  validateInboxAccessibilityLabels(
+    obj.inApp?.notificationInboxAccessibilityLabels
+  );
 }
 
 // For type safety, we define a ConfigValidator type that asserts the value is a ZixflowConfig
@@ -166,11 +267,13 @@ export const assert: {
   record: typeof validateRecord;
   attributes: typeof validateAttributes;
   config: ConfigValidator;
+  colorScheme: typeof validateColorSchemeArgument;
 } = {
   string: validateString,
   record: validateRecord,
   attributes: validateAttributes,
   config: validateConfig,
+  colorScheme: validateColorSchemeArgument,
 };
 
 export const validate = {

package/src/zixflow-cdp.ts

@@ -1,4 +1,6 @@
+import { ZixflowGeofence } from './zixflow-geofence';
 import { ZixflowInAppMessaging } from './zixflow-inapp';
+import { ZixflowLiveActivities } from './zixflow-liveactivities';
 import { ZixflowLocation } from './zixflow-location';
 import { ZixflowPushMessaging } from './zixflow-push';
 import { NativeLoggerListener } from './native-logger-listener';
@@ -17,10 +19,26 @@ import type { NativeSDKArgs } from './types/internal';
 import { callNativeModule, ensureNativeModule } from './utils/native-bridge';
 import { assert, validate } from './utils/param-validation';
 
-const packageJson = require('../../package.json');
+const packageJson = require('../package.json');
 
 // Track whether Zixflow SDK has been initialized to prevent usage before setup
 let _initialized = false;
+let deepLinkHandlerSubscription: DeepLinkHandlerSubscription | undefined;
+
+/**
+ * Handles a Zixflow deep-link destination delivered from iOS.
+ * @public
+ */
+export type DeepLinkHandler = (url: string) => boolean | Promise<boolean>;
+
+/**
+ * Removes a Zixflow deep-link handler.
+ * @public
+ */
+export interface DeepLinkHandlerSubscription {
+  /** Stop routing Zixflow deep links through this handler. */
+  remove(): void;
+}
 
 // Reference to the native Zixflow Data Pipelines module for SDK operations
 const nativeModule = ensureNativeModule(NativeModule);
@@ -36,18 +54,8 @@ export class Zixflow {
   static readonly initialize = async (config: ZixflowConfig) => {
     assert.config(config);
 
-    // Auto-derive inApp.siteId from cdpApiKey if not explicitly set
-    if (config.inApp && !config.inApp.siteId) {
-      config.inApp.siteId = config.cdpApiKey;
-      console.log('[Zixflow] Auto-derived inApp.siteId from cdpApiKey');
-    }
-
-    // Warn if siteId doesn't match cdpApiKey (Customer.io legacy issue)
-    if (config.inApp && config.inApp.siteId && config.inApp.siteId !== config.cdpApiKey) {
-      console.warn(
-        '[Zixflow] Warning: inApp.siteId should equal cdpApiKey for Zixflow. ' +
-        'Using different values may cause in-app messaging to fail.'
-      );
+    if (config.inApp) {
+      (config.inApp as any).siteId = config.apiKey;
     }
 
     if (config.logLevel && config.logLevel !== ZixflowLogLevel.None) {
@@ -68,6 +76,102 @@ export class Zixflow {
     });
   };
 
+  /**
+   * Signal that the app's React Native Linking listener is ready to receive Zixflow URLs.
+   *
+   * This is only needed by UIScene hosts that initialize Zixflow natively, such as Expo
+   * config-plugin auto-initialization. Call it after registering the Linking listener.
+   */
+  static readonly setDeepLinkRoutingReady = () => {
+    return withNativeModule<void>((native) => native.setDeepLinkRoutingReady());
+  };
+
+  /**
+   * Register an acknowledged deep-link handler for an iOS UIScene host.
+   *
+   * This API only handles Zixflow destinations delivered through an iOS UIScene lifecycle.
+   * In a native React Native scene host, pair this with
+   * `NativeZixflow.configureAcknowledgedSceneDeepLinkRouting()` in the SceneDelegate. Register
+   * this before `initialize` when possible. Return `true` after routing a URL. Returning `false`,
+   * throwing, or rejecting lets the native SDK try the host AppDelegate, then React Native Linking
+   * for a host-owned custom scheme or the system for other URLs. Cold URLs are buffered until this
+   * handler is registered, subject to the native timeout. After delivery, the handler has ten
+   * seconds to settle. Once that timeout runs the native fallback, a late handler cannot cancel it
+   * and may cause a second navigation if it also routes the URL.
+   */
+  static readonly setDeepLinkHandler = (
+    handler: DeepLinkHandler
+  ): DeepLinkHandlerSubscription => {
+    if (typeof handler !== 'function') {
+      throw new Error('[Zixflow] "handler" must be a function.');
+    }
+
+    // Native unregister is tokenless and removes the current native handler. Remove the old
+    // subscription first so its cleanup cannot unregister the replacement.
+    deepLinkHandlerSubscription?.remove();
+
+    return withNativeModule<DeepLinkHandlerSubscription>((native) => {
+      const nativeSubscription = native.onDeepLinkReceived(async (data) => {
+        const event = data as { id?: unknown; url?: unknown };
+        if (typeof event.id !== 'string' || typeof event.url !== 'string') {
+          NativeLoggerListener.warn(
+            'Received an invalid native deep-link event.'
+          );
+          return;
+        }
+
+        let handled = false;
+        try {
+          handled = (await handler(event.url)) === true;
+        } catch (error) {
+          NativeLoggerListener.warn('Deep-link handler failed:', error);
+        }
+
+        try {
+          native.acknowledgeDeepLink(event.id, handled);
+        } catch (error) {
+          NativeLoggerListener.warn(
+            'Failed to acknowledge a deep-link result:',
+            error
+          );
+        }
+      });
+
+      let removed = false;
+      const subscription: DeepLinkHandlerSubscription = {
+        remove: () => {
+          if (removed) {
+            return;
+          }
+          removed = true;
+          try {
+            native.unregisterDeepLinkHandler();
+          } finally {
+            nativeSubscription.remove();
+            if (deepLinkHandlerSubscription === subscription) {
+              deepLinkHandlerSubscription = undefined;
+            }
+          }
+        },
+      };
+
+      try {
+        native.registerDeepLinkHandler();
+      } catch (error) {
+        try {
+          native.unregisterDeepLinkHandler();
+        } catch {
+          // Preserve the registration error; the native timeout still owns pending URLs.
+        }
+        nativeSubscription.remove();
+        throw error;
+      }
+
+      deepLinkHandlerSubscription = subscription;
+      return subscription;
+    });
+  };
+
   /** Identify a user to start tracking their activity. Requires userId, traits, or both. */
   static readonly identify = async ({
     userId,
@@ -192,7 +296,9 @@ export class Zixflow {
    */
   static readonly isInitialized = () => _initialized;
 
+  static readonly geofence = new ZixflowGeofence();
   static readonly inAppMessaging = new ZixflowInAppMessaging();
+  static readonly liveActivities = new ZixflowLiveActivities();
   static readonly location = new ZixflowLocation();
   static readonly pushMessaging = new ZixflowPushMessaging();
 }

package/src/zixflow-geofence.ts

@@ -0,0 +1,56 @@
+import { type TurboModule } from 'react-native';
+import {
+  default as NativeModule,
+  type Spec as CodegenSpec,
+} from './specs/modules/NativeZixflowGeofence';
+
+/**
+ * Ensures all methods defined in codegen spec are implemented by the public module
+ *
+ * @internal
+ */
+interface NativeGeofenceSpec extends Omit<CodegenSpec, keyof TurboModule> {}
+
+// Geofence is an optional module — NativeModule may be null when geofence is not enabled.
+// Methods silently no-op when the native module is unavailable, with a one-time dev warning.
+let hasWarnedNotEnabled = false;
+const withNativeModule = (fn: (native: CodegenSpec) => void): void => {
+  if (NativeModule) {
+    fn(NativeModule);
+  } else if (__DEV__ && !hasWarnedNotEnabled) {
+    hasWarnedNotEnabled = true;
+    console.warn(
+      'Zixflow: Geofence module is not enabled. ' +
+        'To use geofence features, set zixflow_geofence_enabled=true in ' +
+        'gradle.properties (Android) or add the geofence subspec to your Podfile (iOS).'
+    );
+  }
+};
+
+/**
+ * Public entry point for the optional Geofence module.
+ *
+ * Geofence runs automatically once enabled. Apps opt in by passing a `geofence` config to
+ * `initialize` and enabling the module at build time: set `zixflow_geofence_enabled=true`
+ * in `gradle.properties` (Android) or add the `geofence` subspec to your Podfile (iOS).
+ * Enabling geofence also enables the Location module, which geofence depends on.
+ *
+ * @public
+ */
+export class ZixflowGeofence implements NativeGeofenceSpec {
+  /**
+   * Requests a one-shot location fix and refreshes the nearby geofence set from it,
+   * without sending a location analytics event (unlike
+   * `Zixflow.location.requestLocationUpdate()`) and without caching the fix.
+   *
+   * Call this after the host app has been granted location permission — the SDK never
+   * requests permission itself. It is the primary way to drive geofencing when the module
+   * is configured with `MANUAL` location mode; with the default `AUTOMATIC` the SDK acquires
+   * location on its own and this only forces an immediate refresh.
+   *
+   * No-ops if the geofence module is not enabled or a user has not been identified.
+   */
+  refreshFromCurrentLocation(): void {
+    return withNativeModule((native) => native.refreshFromCurrentLocation());
+  }
+}

package/src/zixflow-inapp.ts

@@ -3,13 +3,16 @@ import { InlineInAppMessageView } from './components';
 import { NativeLoggerListener } from './native-logger-listener';
 import {
   NotificationInbox,
+  parseInboxMessage,
   type NotificationInboxSpec,
 } from './notification-inbox';
 import NativeZixflowMessagingInApp, {
   type Spec as CodegenSpec,
 } from './specs/modules/NativeZixflowMessagingInApp';
-import type { InAppMessageEventType } from './types';
+import type { ZixflowColorScheme, InAppMessageEventType } from './types';
+import { InboxEventType, InboxMessageEvent } from './types';
 import { callNativeModule, ensureNativeModule } from './utils/native-bridge';
+import { assert } from './utils/param-validation';
 
 /**
  * Ensures all methods defined in codegen spec are implemented by the public module
@@ -18,7 +21,12 @@ import { callNativeModule, ensureNativeModule } from './utils/native-bridge';
  */
 interface NativeInAppSpec extends Omit<
   CodegenSpec,
-  keyof TurboModule | NotificationInboxSpec | 'onInAppEventReceived'
+  | keyof TurboModule
+  | NotificationInboxSpec
+  | 'onInAppEventReceived'
+  | 'registerInboxEventListener'
+  | 'unregisterInboxEventListener'
+  | 'onInboxEventReceived'
 > {}
 
 // Reference to the native Zixflow Data Pipelines module for SDK operations
@@ -37,6 +45,13 @@ const withNativeModule = <R>(fn: (native: CodegenSpec) => R): R => {
 class ZixflowInAppMessaging implements NativeInAppSpec {
   private _notificationInbox?: NotificationInbox;
 
+  /**
+   * Live inbox subscriptions. The SDK's inbox forwarder is a SINGLE global listener, so it is
+   * registered when the first subscription is created and unregistered when the last one goes away —
+   * never per subscription, or one `remove()` would tear it out from under the others.
+   */
+  private _inboxListenerCount = 0;
+
   registerEventsListener(
     listener: (event: InAppMessageEvent) => void
   ): EventSubscription {
@@ -74,6 +89,91 @@ class ZixflowInAppMessaging implements NativeInAppSpec {
     });
   }
 
+  /**
+   * Registers a listener for Visual Notification Inbox events (action taken,
+   * shown, opened, dismissed).
+   *
+   * While a listener is registered the host owns action navigation: the native
+   * SDK suppresses its default action handling and forwards the event here.
+   * Call `.remove()` on the returned subscription to unregister and restore the
+   * SDK's default behavior.
+   *
+   * @param listener - callback invoked with an {@link InboxMessageEvent}
+   * @returns an EventSubscription; call `.remove()` to stop listening
+   */
+  registerInboxEventListener(
+    listener: (event: InboxMessageEvent) => void
+  ): EventSubscription {
+    const emitter = (data: any) => {
+      // Convert raw native payload to InboxMessageEvent with a parsed message
+      const event = new InboxMessageEvent(
+        data.eventType as InboxEventType,
+        parseInboxMessage(data.message),
+        data.actionName,
+        data.actionValue
+      );
+      listener(event);
+    };
+
+    return withNativeModule((native) => {
+      let registeredNativeForwarder = false;
+      try {
+        // Register the native forwarder with the SDK, then subscribe to the
+        // codegen-generated event emitter.
+        // Wrapped in try-catch due to previous reports of crashes on certain Android architectures.
+        if (this._inboxListenerCount === 0) {
+          native.registerInboxEventListener();
+          registeredNativeForwarder = true;
+        }
+        const subscription = native.onInboxEventReceived(emitter);
+        this._inboxListenerCount += 1;
+
+        // Wrap remove() so unregistering the LAST JS listener also unregisters the native forwarder
+        // (restoring the SDK's default action handling). Guarded so a double remove() cannot
+        // unbalance the count and drop the forwarder while other subscriptions are still live.
+        const originalRemove = subscription.remove.bind(subscription);
+        let removed = false;
+        subscription.remove = () => {
+          if (removed) {
+            return;
+          }
+          removed = true;
+          originalRemove();
+          this._inboxListenerCount -= 1;
+          if (this._inboxListenerCount === 0) {
+            withNativeModule((n) => n.unregisterInboxEventListener());
+          }
+        };
+        return subscription;
+      } catch (error) {
+        // If the forwarder was registered and subscribing then failed, roll it back. Otherwise the
+        // SDK keeps suppressing its own action handling while nothing in JS is listening, so inbox
+        // actions are reported as handled and silently go nowhere.
+        if (registeredNativeForwarder) {
+          try {
+            native.unregisterInboxEventListener();
+          } catch (rollbackError) {
+            NativeLoggerListener.warn(
+              'Failed to roll back inbox listener registration:',
+              rollbackError
+            );
+          }
+        }
+        NativeLoggerListener.warn(
+          'Failed to attach inbox event listener:',
+          error
+        );
+        // Return a no-op subscription to maintain backwards compatibility
+        return {
+          remove: () => {},
+          eventType: '',
+          key: 0,
+          subscriber: null as any,
+        } as EventSubscription;
+      }
+    });
+  }
+
   /**
    * Dismisses any currently displayed in-app message
    */
@@ -81,6 +181,23 @@ class ZixflowInAppMessaging implements NativeInAppSpec {
     withNativeModule((native) => native.dismissMessage());
   }
 
+  /**
+   * Overrides the color scheme used to render in-app messages.
+   *
+   * Takes effect immediately: messages already on screen — inline views included — are
+   * re-themed in place, so this can be called whenever the app's appearance setting
+   * changes rather than only before a message is shown.
+   *
+   * @param colorScheme - scheme to render with; `ZixflowColorScheme.Auto` returns to following
+   * the device appearance
+   */
+  setColorScheme(colorScheme: ZixflowColorScheme) {
+    // Validated here as well as in `initialize`: this is a public method reachable from
+    // untyped JavaScript, and without it a bad value reaches the native fallback silently.
+    assert.colorScheme(colorScheme);
+    withNativeModule((native) => native.setColorScheme(colorScheme));
+  }
+
   /**
    * Gets the message inbox instance for managing inbox messages
    *
@@ -122,6 +239,12 @@ class InAppMessageEvent {
 
 // Export in-app messaging types and components for simplified imports
 export type { InlineInAppMessageViewProps } from './components';
+export type {
+  NotificationInboxBellViewProps,
+  NotificationInboxViewProps,
+} from './components';
+export { NotificationInboxBellView, NotificationInboxView } from './components';
 export { NotificationInbox } from './notification-inbox';
 export type { InboxMessage, NotificationInboxChangeListener } from './types';
+export { InboxEventType, InboxMessageEvent } from './types';
 export { ZixflowInAppMessaging, InAppMessageEvent, InlineInAppMessageView };

package/src/zixflow-liveactivities.ts

@@ -0,0 +1,86 @@
+import { type TurboModule } from 'react-native';
+import {
+  default as NativeModule,
+  type Spec as CodegenSpec,
+} from './specs/modules/NativeZixflowLiveActivities';
+import type { LiveActivityPayload } from './types/live-activities';
+
+/**
+ * Ensures all methods defined in codegen spec are implemented by the public module
+ *
+ * @internal
+ */
+interface NativeLiveActivitiesSpec extends Omit<
+  CodegenSpec,
+  keyof TurboModule
+> {}
+
+/**
+ * Live Activities (iOS) / Live Notifications (Android).
+ *
+ * Start, update, and end live, updating notifications from built-in templates
+ * (Segments, Countdown Timer). Enable the activity types via the `liveNotifications`
+ * key of the SDK config passed to {@link Zixflow.initialize}.
+ *
+ * @public
+ */
+export class ZixflowLiveActivities implements NativeLiveActivitiesSpec {
+  /**
+   * Report an opened Live Activity and return the URL the app should route.
+   *
+   * Zixflow tracking URLs are unwrapped to their destination after attribution is recorded.
+   * A tracking URL without a destination returns `null`; any other URL is returned unchanged.
+   * This method never rejects, so it can safely compose with Expo Router's
+   * `redirectSystemPath` hook. On Android it is a pass-through.
+   *
+   * Use this in exactly one URL-routing layer. Calling it more than once for the same Zixflow
+   * tracking URL reports more than one opened event.
+   *
+   * @param url - The incoming URL from the host's linking lifecycle.
+   * @returns The URL to route, or `null` when the Zixflow URL has no destination.
+   */
+  async handleWidgetUrl(url: string): Promise<string | null> {
+    try {
+      return await NativeModule.handleWidgetUrl(url);
+    } catch {
+      return url;
+    }
+  }
+
+  /**
+   * Start a built-in-template activity.
+   *
+   * @param payload - Template payload; `payload.type` selects the template.
+   * @returns The SDK-minted activity id, used for later `update`/`end`.
+   */
+  start(payload: LiveActivityPayload): Promise<string> {
+    return NativeModule.start(payload);
+  }
+
+  /**
+   * Replace the whole content-state of a running activity.
+   *
+   * ActivityKit (iOS) replaces content-state wholesale, so pass the **full** desired
+   * state — not just the changed fields. Static attributes (e.g. `header`) cannot
+   * change after start and are ignored on iOS.
+   *
+   * @param activityId - Id returned by {@link ZixflowLiveActivities.start}.
+   * @param payload - The complete desired state.
+   */
+  update(activityId: string, payload: LiveActivityPayload): Promise<void> {
+    return NativeModule.update(activityId, payload);
+  }
+
+  /**
+   * End a running activity, optionally rendering a final content-state.
+   *
+   * @param activityId - Id returned by {@link ZixflowLiveActivities.start}.
+   * @param payload - **iOS only.** The final content-state to render as the activity ends.
+   *   ActivityKit keeps the last content-state on screen when none is given, so pass one to show
+   *   a terminal state (e.g. all segments complete). Android renders its own terminal state and
+   *   ignores this.
+   */
+  end(activityId: string, payload?: LiveActivityPayload): Promise<void> {
+    return NativeModule.end(activityId, payload);
+  }
+}

package/src/zixflow.ts

@@ -1,9 +1,3 @@
-/**
- * Zixflow SDK - Main entry point
- *
- * This provides the Zixflow-branded API.
- */
-
 export { Zixflow } from './zixflow-cdp';
 export { ZixflowInAppMessaging } from './zixflow-inapp';
 export { ZixflowLocation } from './zixflow-location';

package/zixflow-reactnative-richpush.podspec

@@ -2,7 +2,7 @@ require "json"
 
 package = JSON.parse(File.read(File.join(__dir__, "package.json")))
 
-# Used by customers to install native iOS dependencies inside their Notification Service Extension (NSE) target to setup rich push.
+# Used to install native iOS dependencies inside the Notification Service Extension (NSE) target to setup rich push.
 # Note: We need a unique podspec for rich push because the other podspecs in this project install too many dependencies that should not be installed inside of a NSE target. We need this podspec which installs minimal dependencies that are only included in the NSE target.
 Pod::Spec.new do |s|
   s.name         = "zixflow-reactnative-richpush"
@@ -15,7 +15,10 @@ Pod::Spec.new do |s|
 
   s.source       = { :git => "https://github.com/zixflow/zixflow-reactnative.git", :tag => "#{s.version}" }
 
-  s.source_files = "ios/**/*.{h,m,mm,swift}"
+  # Dependency-only pod: installed into the NSE target, whose job is purely to pull in the minimal
+  # CIO push dependency below. It must NOT compile any sources — everything under ios/ is the React
+  # Native bridge (React + DataPipelines + InApp + Inbox), none of which the NSE target has or should
+  # have. Globbing them here made the NSE compile the whole bridge and fail on React headers.
 
   # Note: Zixflow iOS SDK dependencies need to be added to NSE target via CocoaPods
   # Add these pods to your NotificationServiceExtension target in your Podfile:
@@ -24,7 +27,7 @@ Pod::Spec.new do |s|
   # pod "ZixflowDataPipelines", "= 1.0.0"
   # pod "ZixflowCommon", "= 1.0.0"
 
-  # Subspecs allow customers to choose between multiple options of what type of version of this rich push package they would like to install.
+  # Subspecs allow choosing between APN or FCM for rich push notifications.
   # Set default subspec to 'apn' to prevent both APN and FCM dependencies from being installed by default.
   #
   # To override the default subspec, specify the desired subspec in your Podfile. For example: