zixflow-reactnative 1.1.3 → 1.1.5

package/src/types/inbox.ts

@@ -0,0 +1,110 @@
+import type { InboxMessage } from './in-app';
+
+/**
+ * Enum representing the type of event triggered by an inbox event callback.
+ *
+ * Mirrors the native `InboxEventListener` contract on iOS and Android.
+ *
+ * @public
+ */
+export enum InboxEventType {
+  /** A non-dismiss action (e.g. a button/link) was taken on an inbox message. */
+  messageActionTaken = 'messageActionTaken',
+  /** An inbox message was first shown/rendered in the visible inbox view. */
+  messageShown = 'messageShown',
+  /** An inbox message was marked opened (e.g. when the panel opens). */
+  messageOpened = 'messageOpened',
+  /** An inbox message was dismissed/removed from the inbox. */
+  messageDismissed = 'messageDismissed',
+}
+
+/**
+ * Event delivered to a registered inbox event listener.
+ *
+ * `messageActionTaken` carries `actionName`/`actionValue`; the observational
+ * events (`messageShown`, `messageOpened`, `messageDismissed`) carry only the
+ * message.
+ *
+ * @public
+ */
+export class InboxMessageEvent {
+  /** The type of inbox event. */
+  eventType: InboxEventType;
+  /** The inbox message the event relates to. */
+  message: InboxMessage;
+  /** The Jist action name (only present for `messageActionTaken`). */
+  actionName?: string;
+  /** The resolved action value, typically a url (only present for `messageActionTaken`). */
+  actionValue?: string;
+
+  constructor(
+    eventType: InboxEventType,
+    message: InboxMessage,
+    actionName?: string,
+    actionValue?: string
+  ) {
+    this.eventType = eventType;
+    this.message = message;
+    this.actionName = actionName;
+    this.actionValue = actionValue;
+  }
+}
+
+/**
+ * Host-provided accessibility labels for the Visual Notification Inbox UI.
+ *
+ * The SDK ships no text of its own in the visual inbox — the empty state is an icon and the
+ * loading state is a spinner — so accessibility labels are the one place a string is still
+ * needed. Because the SDK cannot know your app's language, every label is optional and unset by
+ * default, and an omitted label leaves that element unlabeled rather than falling back to
+ * English. Pass strings already localized for the user's language.
+ *
+ * @example
+ * ```ts
+ * Zixflow.initialize({
+ *   apiKey: '...',
+ *   inApp: {
+ *     siteId: '...',
+ *     notificationInboxAccessibilityLabels: {
+ *       bell: t('inbox.bell'),
+ *       bellWithUnreadCount: t('inbox.unread'), // e.g. "{count} unread notifications"
+ *       loadingIndicator: t('inbox.loading'),
+ *       emptyState: t('inbox.empty'),
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export type NotificationInboxAccessibilityLabels = {
+  /**
+   * Label for the inbox bell button. Also used when the bell shows an unread badge but
+   * `bellWithUnreadCount` is not provided. Unset → the bell is announced as an unnamed button
+   * (it stays focusable and tappable; hiding it would leave screen reader users no way in).
+   */
+  bell?: string;
+  /**
+   * Label for the bell while it shows an unread badge. Include `{count}` where the number of
+   * unread messages should appear; it is substituted at render time. Unset → falls back to `bell`.
+   *
+   * The badge itself is always hidden from assistive technologies, so the count is announced
+   * only through this label, never as bare digits appended to the button.
+   *
+   * This is a template rather than a function because configuration crosses the native bridge,
+   * which carries data but not callbacks. One template cannot express languages whose plural
+   * rules need a distinct form per count.
+   */
+  bellWithUnreadCount?: string;
+  /**
+   * Label announced for the loading spinner.
+   *
+   * Unset behaves differently per platform: on Android the spinner keeps its indeterminate
+   * progress role, which TalkBack describes in the device's own language, while on iOS it is not
+   * an accessibility element at all, so VoiceOver skips it rather than focusing an unnamed
+   * control. Set a label if you want the loading state announced on both.
+   */
+  loadingIndicator?: string;
+  /** Label announced for the empty-state icon. Unset → the icon is treated as decorative. */
+  emptyState?: string;
+};

package/src/types/index.ts

@@ -1,3 +1,5 @@
 export * from './data-pipelines';
 export * from './in-app';
+export * from './inbox';
+export * from './live-activities';
 export * from './push';

package/src/types/live-activities.ts

@@ -0,0 +1,170 @@
+/**
+ * Public types for the Live Activities module.
+ *
+ * Live Activities (iOS) / Live Notifications (Android) render live, updating
+ * notifications from built-in templates. Two templates ship today: Segments and
+ * Countdown Timer. Field names and identifiers are identical across platforms.
+ */
+
+/**
+ * Built-in activity type identifiers usable from the wrapper.
+ *
+ * The values are the reverse-DNS identifiers Zixflow uses everywhere — the
+ * `notificationType` on the wire, Android's `LiveNotificationType`, and iOS's
+ * `CIOSegmentsAttributes.identifier` — so JS, both native SDKs, and the backend
+ * share one vocabulary.
+ *
+ * Use these enum members (not raw strings) for `LiveActivitiesConfig.types` and a
+ * payload's `type` to avoid typos.
+ *
+ * @public
+ */
+export enum LiveActivityTemplate {
+  Segments = 'com.zixflow.livenotifications.segments',
+  CountdownTimer = 'com.zixflow.livenotifications.countdowntimer',
+  /**
+   * Your own activity type, rendered by SwiftUI you write.
+   *
+   * Unlike the members above, this value is a marker rather than an identifier — your activity is
+   * named by {@link LiveActivitiesConfig.customType}, and the SDK reports it under that name. It
+   * belongs in a payload's `type`, never in {@link LiveActivitiesConfig.types}.
+   */
+  Custom = 'custom',
+}
+
+/**
+ * Segments template — a progress activity split into N segments.
+ * `header` is a static attribute (fixed at start); the rest are content-state.
+ *
+ * @public
+ */
+export interface LiveActivitySegmentsPayload {
+  type: LiveActivityTemplate.Segments;
+  /** Static header line (set at start, never changes). */
+  header: string;
+  /** Primary status line. */
+  status: string;
+  /** Optional secondary status line. */
+  substatus?: string;
+  /** Total number of segments. */
+  segmentsTotal: number;
+  /** Number of completed segments (clamped to 0..segmentsTotal). */
+  segmentsComplete: number;
+  /** Optional trailing text (e.g. an ETA). */
+  trailingText?: string;
+}
+
+/**
+ * Custom template — your own activity type, rendered by SwiftUI you write.
+ *
+ * Unlike the built-in templates there is no schema: `data` is an untyped map, because a bridge
+ * payload carries nothing for the SDK to validate against. Every value is a string, so your widget
+ * parses whichever ones it needs.
+ *
+ * Requires {@link LiveActivitiesConfig.customType} to be set. On iOS you must also render
+ * `CIOCustomAttributes` in your Widget Extension; on Android your `createLiveNotification`
+ * callback receives the same map.
+ *
+ * @public
+ */
+export interface LiveActivityCustomPayload {
+  type: LiveActivityTemplate.Custom;
+  /**
+   * The full content-state, re-sent in its entirety on every update. Neither platform keeps a
+   * static/dynamic split for custom types, so include anything your widget needs each time.
+   *
+   * Values must be strings. Numbers and booleans are coerced, but nested objects and arrays are
+   * not supported and the platforms disagree on them — iOS drops them, Android stringifies them —
+   * so flatten anything structured before sending it.
+   */
+  data: Record<string, string>;
+}
+
+/**
+ * Countdown Timer template — a live countdown to a target time.
+ * `header` is a static attribute (fixed at start); the rest are content-state.
+ *
+ * @public
+ */
+export interface LiveActivityCountdownTimerPayload {
+  type: LiveActivityTemplate.CountdownTimer;
+  /** Static header line (set at start, never changes). */
+  header: string;
+  /** Primary title line. */
+  title: string;
+  /** Optional status message. */
+  statusMessage?: string;
+  /** Target time as epoch **seconds**. Omit to render the finished state. */
+  endTime?: number;
+}
+
+/**
+ * Payload for {@link ZixflowLiveActivities.start} and
+ * {@link ZixflowLiveActivities.update}.
+ *
+ * Because ActivityKit replaces content-state wholesale on update, `update` takes the
+ * same full payload as `start` — pass the complete desired state each time.
+ *
+ * @public
+ */
+export type LiveActivityPayload =
+  | LiveActivitySegmentsPayload
+  | LiveActivityCountdownTimerPayload
+  | LiveActivityCustomPayload;
+
+/**
+ * Live Activities branding (Android only). On iOS, branding is compiled into the
+ * widget extension's SwiftUI, so these values are ignored there.
+ *
+ * @public
+ */
+export interface LiveActivitiesBranding {
+  /** Reserved for future use. */
+  companyName?: string;
+  /** Accent color as "#RRGGBB". */
+  accentColorHex?: string;
+  /**
+   * Bundled Android drawable resource name for the logo, resolved natively.
+   * Preferred over {@link LiveActivitiesBranding.logoUrl} when both are set — it
+   * needs no network.
+   */
+  logoResource?: string;
+  /** Remote logo URL (downloaded and cached natively). */
+  logoUrl?: string;
+  /** Android drawable resource name, resolved natively. */
+  smallIconResource?: string;
+}
+
+/**
+ * Live Activities configuration, passed under the `liveNotifications` key of the SDK config.
+ *
+ * @public
+ */
+export interface LiveActivitiesConfig {
+  /**
+   * Built-in activity types to enable. Enables the matching native type on each
+   * platform and registers push-to-start for it. Unrecognized identifiers are
+   * ignored, so a newer native template can't break an older wrapper build.
+   *
+   * `Custom` is excluded on purpose — it is enabled by {@link LiveActivitiesConfig.customType},
+   * and both platforms would silently drop it from this list.
+   */
+  types?: Exclude<LiveActivityTemplate, LiveActivityTemplate.Custom>[];
+  /**
+   * Your own reverse-DNS identifier for the custom activity type, e.g.
+   * `'com.myapp.rideshare'`. Setting it enables the custom template on both platforms.
+   *
+   * Start one with `{ type: LiveActivityTemplate.Custom, data: { … } }`; the SDK reports it
+   * under this identifier, and your campaigns target it by the same name.
+   *
+   * Singular by design: iOS resolves an activity's type from its Swift attributes type, and
+   * every custom activity shares one. A second identifier could not be told apart, so one
+   * identifier is the limit rather than a silent mis-attribution.
+   *
+   * You must also render it yourself — `CIOCustomAttributes` in an iOS Widget Extension, and
+   * the `createLiveNotification` callback on Android.
+   */
+  customType?: string;
+  /** Android Live Notification branding (ignored on iOS). */
+  branding?: LiveActivitiesBranding;
+}

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.
@@ -155,6 +252,10 @@ function validateConfig(value: unknown): asserts value is ZixflowConfig {
     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);
@@ -58,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,
@@ -182,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());
+  }
+}