@dashx/react-native 1.4.0 → 1.5.0

package/.claude/worktrees/autocapture-conventions-review-78f665/index.d.ts

@@ -0,0 +1,321 @@
+import { EmitterSubscription } from 'react-native';
+
+/**
+ * Error codes returned by native SDKs in promise rejections.
+ * Consistent across iOS and Android.
+ */
+export enum DashXErrorCode {
+  /** An unspecified error occurred. */
+  EUNSPECIFIED = 'EUNSPECIFIED',
+  /** The operation is not supported on this platform. */
+  EUNSUPPORTED = 'EUNSUPPORTED',
+}
+
+export interface ConfigureOptions {
+  publicKey: string;
+  baseURI?: string;
+  targetEnvironment?: string;
+}
+
+export interface IdentifyOptions {
+  firstName?: string;
+  lastName?: string;
+  email?: string;
+  phone?: string;
+  [key: string]: string | undefined;
+}
+
+export type LogLevel = 0 | 1 | 2;
+
+export interface FetchRecordOptions {
+  preview?: boolean;
+  language?: string;
+  fields?: Record<string, unknown>[];
+  include?: Record<string, unknown>[];
+  exclude?: Record<string, unknown>[];
+}
+
+export interface SearchRecordsOptions {
+  filter?: Record<string, unknown>;
+  order?: Record<string, unknown>[];
+  limit?: number;
+  page?: number;
+  preview?: boolean;
+  language?: string;
+  fields?: Record<string, unknown>[];
+  include?: Record<string, unknown>[];
+  exclude?: Record<string, unknown>[];
+}
+
+export interface AssetData {
+  status?: string;
+  url?: string;
+  playbackIds?: { id?: string; policy?: string }[];
+}
+
+export interface AssetResponse {
+  status?: string;
+  data?: { asset?: AssetData };
+}
+
+/**
+ * Mirrors UNAuthorizationStatus integer values:
+ * 0 = notDetermined, 1 = denied, 2 = authorized, 3 = provisional, 4 = ephemeral
+ */
+export type NotificationPermissionStatus = 0 | 1 | 2 | 3 | 4;
+
+export interface NotificationMessage {
+  [key: string]: unknown;
+}
+
+export type NavigationAction =
+  | { type: 'deepLink'; url: string }
+  | { type: 'screen'; name: string; data?: Record<string, string> }
+  | { type: 'richLanding'; url: string }
+  | { type: 'clickAction'; action: string };
+
+export interface NotificationClickedEvent {
+  notification: NotificationMessage;
+  action: NavigationAction | null;
+  actionIdentifier: string;
+}
+
+export interface ProcessURLOptions {
+  source?: string;
+  forwardToLinkHandler?: boolean;
+}
+
+export interface NavigationRouteLike {
+  name: string;
+  params?: object;
+}
+
+/**
+ * The subset of a React Navigation `NavigationContainer` ref used by
+ * `trackNavigation`, so this package does not depend on `@react-navigation/*`.
+ */
+export interface NavigationContainerLike {
+  addListener(event: 'state', callback: (event: unknown) => void): () => void;
+  getCurrentRoute(): NavigationRouteLike | undefined;
+  isReady?(): boolean;
+}
+
+export interface DashXInstance {
+  /**
+   * Initialize the SDK with your public key and optional configuration.
+   * Call this as early as possible, e.g. in your root component.
+   */
+  configure(options: ConfigureOptions): void;
+
+  /**
+   * Identify the current user with traits such as name and email.
+   */
+  identify(options: IdentifyOptions): void;
+
+  /**
+   * Set user identity using a UID and authentication token. Both are
+   * nullable — passing `null` clears that field on the native SDK. Empty
+   * strings are forwarded as-is (no coercion to `null`).
+   */
+  setIdentity(uid: string | null, token?: string | null): void;
+
+  /**
+   * Clear the current user identity and reset SDK state.
+   */
+  reset(): void;
+
+  /**
+   * Track a named event with optional metadata.
+   */
+  track(event: string, data?: Record<string, unknown>): void;
+
+  /**
+   * Track a screen view with optional metadata.
+   */
+  screen(screenName: string, data?: Record<string, unknown>): void;
+
+  /**
+   * Fetch a single record by URN (e.g. "article/123") with optional preview, language, fields, include, exclude.
+   * Returns a promise resolving to the record object.
+   */
+  fetchRecord(
+    urn: string,
+    options?: FetchRecordOptions
+  ): Promise<Record<string, unknown>>;
+
+  /**
+   * Search records by resource with optional filter, order, limit, preview, language, fields, include, exclude.
+   * Returns a promise resolving to an array of record objects.
+   */
+  searchRecords(
+    resource: string,
+    options?: SearchRecordsOptions
+  ): Promise<Record<string, unknown>[]>;
+
+  /**
+   * Subscribe the current device to push notifications.
+   */
+  subscribe(): void;
+
+  /**
+   * Unsubscribe the current device from push notifications.
+   *
+   * Resolves with `{ success: true }` when the backend found and updated a
+   * matching subscribed contact, or `{ success: false }` when no match was
+   * found (anonymous UID rotated since subscribe, FCM token is stale,
+   * contact already unsubscribed, or this device never subscribed in the
+   * current session). The device ends up unsubscribed in both cases; the
+   * boolean is useful for diagnostics and analytics.
+   *
+   * Rejects on transport / SDK-state failures: native module not configured,
+   * Firebase token-delete failure, GraphQL or network error.
+   */
+  unsubscribe(): Promise<{ success: boolean }>;
+
+  /**
+   * Fetch stored notification preferences for the current user.
+   */
+  fetchStoredPreferences(): Promise<Record<string, unknown>>;
+
+  /**
+   * Save notification preferences for the current user.
+   */
+  saveStoredPreferences(
+    data: Record<string, unknown>
+  ): Promise<Record<string, unknown>>;
+
+  /**
+   * Set SDK log verbosity. 0 = off, 1 = errors, 2 = debug.
+   */
+  setLogLevel(level: LogLevel): void;
+
+  /**
+   * Register a listener for incoming push notifications.
+   * Returns a subscription that can be removed via `.remove()`.
+   */
+  onPushNotificationReceived(
+    callback: (message: NotificationMessage) => void
+  ): EmitterSubscription;
+
+  /**
+   * @deprecated Use `onPushNotificationReceived` instead.
+   * Will be removed in the next major version.
+   */
+  onMessageReceived(
+    callback: (message: NotificationMessage) => void
+  ): EmitterSubscription;
+
+  /**
+   * Upload a local file to DashX. Returns an AssetResponse with the asset status and URL.
+   * @param filePath Absolute path to the local file.
+   */
+  uploadAsset(
+    filePath: string,
+    resource: string,
+    attribute: string
+  ): Promise<AssetResponse>;
+
+  /**
+   * Fetch details of a previously uploaded asset by its ID.
+   */
+  fetchAsset(assetId: string): Promise<AssetResponse>;
+
+  /**
+   * Enable automatic app lifecycle events (install, update, open, background)
+   * on iOS and Android. Call after `configure`.
+   */
+  enableLifecycleTracking(): void;
+
+  /**
+   * Send a screen view for each React Navigation route change. Sends the
+   * current route once the container is ready, then `screen(route.name)`
+   * whenever the focused route's name changes (params are not sent).
+   * Returns a function that stops tracking.
+   *
+   * Call it from `NavigationContainer`'s `onReady` so the first screen is
+   * captured. A ref from `useNavigationContainerRef()` or
+   * `createNavigationContainerRef()` may also be passed before the container
+   * mounts.
+   *
+   * @example
+   * const navigationRef = useNavigationContainerRef();
+   *
+   * <NavigationContainer
+   *   ref={navigationRef}
+   *   onReady={() => DashX.trackNavigation(navigationRef)}
+   * >
+   *   ...
+   * </NavigationContainer>
+   */
+  trackNavigation(
+    navigationRef:
+      | NavigationContainerLike
+      | { current: NavigationContainerLike | null }
+  ): () => void;
+
+  /**
+   * Enable IDFA/ATT ad tracking and request the App Tracking Transparency permission (iOS only).
+   */
+  enableAdTracking(): void;
+
+  /**
+   * Track a deep link open event and optionally forward the URL to the link handler (iOS only).
+   * @param url The deep link URL string.
+   * @param options.source Optional attribution source (e.g. "universal_link", "notification").
+   * @param options.forwardToLinkHandler Whether to forward to the link handler callback (default: true).
+   */
+  processURL(url: string, options?: ProcessURLOptions): void;
+
+  /**
+   * Track a notification navigation event when the user taps a notification (iOS only).
+   * @param action The navigation action taken, or null/undefined for default.
+   * @param notificationId Optional notification ID to associate with the event.
+   */
+  trackNotificationNavigation(
+    action?: NavigationAction | null,
+    notificationId?: string
+  ): void;
+
+  /**
+   * Request push notification permission from the user.
+   *
+   * @param options.fallbackToSettings — when `true`, if the user has previously
+   *   granted or denied permission, opens the system notification settings
+   *   page so they can enable Time Sensitive notifications (or re-enable
+   *   notifications). Defaults to `false`. Use this to recover users who
+   *   granted permission before the SDK started requesting `.timeSensitive`,
+   *   since iOS won't silently add new options to an existing grant.
+   *
+   * Resolves with a NotificationPermissionStatus integer.
+   */
+  requestNotificationPermission(options?: {
+    fallbackToSettings?: boolean
+  }): Promise<NotificationPermissionStatus>;
+
+  /**
+   * Get the current push notification permission status without prompting.
+   * Resolves with a NotificationPermissionStatus integer.
+   */
+  getNotificationPermissionStatus(): Promise<NotificationPermissionStatus>;
+
+  /**
+   * Register a listener for deep link / universal link events dispatched by the SDK.
+   * Returns a subscription that can be removed via `.remove()`.
+   */
+  onLinkReceived(callback: (url: string) => void): EmitterSubscription;
+
+  /**
+   * Register a listener for notification tap events. Fired when the user taps
+   * a DashX notification or one of its action buttons. The callback receives
+   * the full notification payload, the resolved `NavigationAction` (parsed
+   * from the payload; `null` if no navigation intent could be resolved), and
+   * the raw `actionIdentifier` from `UNNotificationResponse`.
+   * Returns a subscription that can be removed via `.remove()`.
+   */
+  onNotificationClicked(
+    callback: (event: NotificationClickedEvent) => void
+  ): EmitterSubscription;
+}
+
+declare const DashX: DashXInstance;
+export default DashX;

package/.claude/worktrees/autocapture-conventions-review-78f665/index.js

@@ -0,0 +1,300 @@
+import { NativeEventEmitter, NativeModules, Platform } from 'react-native';
+import NativeDashXReactNative from './src/NativeDashXReactNative';
+
+function getLinkingError() {
+  return (
+    `The package 'dashx-react-native' doesn't seem to be linked. Make sure: \n\n` +
+    Platform.select({ ios: "- You have run 'pod install'\n", default: '' }) +
+    '- You rebuilt the app after installing the package\n' +
+    '- You are not using Expo Go\n'
+  );
+}
+
+let _nativeDashX = null;
+function getNativeDashX() {
+  if (!_nativeDashX) {
+    const nativeModule =
+      NativeDashXReactNative || NativeModules.DashXReactNative;
+    _nativeDashX = nativeModule
+      ? nativeModule
+      : new Proxy(
+          {},
+          {
+            get() {
+              throw new Error(getLinkingError());
+            },
+          }
+        );
+  }
+  return _nativeDashX;
+}
+
+let _onMessageReceivedDeprecationWarned = false;
+
+let _eventEmitter = null;
+function getEventEmitter() {
+  if (!_eventEmitter) {
+    _eventEmitter = new NativeEventEmitter(getNativeDashX());
+  }
+  return _eventEmitter;
+}
+
+const DashX = {
+  configure(options) {
+    if (!options || typeof options !== 'object') {
+      throw new Error('DashX.configure: options must be an object');
+    }
+    if (!options.publicKey || typeof options.publicKey !== 'string') {
+      throw new Error(
+        'DashX.configure: publicKey is required and must be a string'
+      );
+    }
+    return getNativeDashX().configure(options);
+  },
+
+  identify(options) {
+    if (!options || typeof options !== 'object') {
+      throw new Error('DashX.identify: options must be an object');
+    }
+    return getNativeDashX().identify(options);
+  },
+
+  setIdentity(uid, token) {
+    // Both uid and token are nullable passthroughs to the native SDK. Only
+    // validate TYPE here — the native side decides semantics. `undefined` is
+    // normalized to `null` because the RN bridge can't carry undefined.
+    if (uid !== null && uid !== undefined && typeof uid !== 'string') {
+      throw new Error('DashX.setIdentity: uid must be a string or null');
+    }
+    if (token !== null && token !== undefined && typeof token !== 'string') {
+      throw new Error('DashX.setIdentity: token must be a string or null');
+    }
+    return getNativeDashX().setIdentity(uid ?? null, token ?? null);
+  },
+
+  reset() {
+    return getNativeDashX().reset();
+  },
+
+  track(event, data) {
+    if (!event || typeof event !== 'string') {
+      throw new Error('DashX.track: event is required and must be a string');
+    }
+    return getNativeDashX().track(event, data || null);
+  },
+
+  screen(screenName, data) {
+    if (!screenName || typeof screenName !== 'string') {
+      throw new Error(
+        'DashX.screen: screenName is required and must be a string'
+      );
+    }
+    return getNativeDashX().screen(screenName, data || null);
+  },
+
+  fetchRecord(urn, options = {}) {
+    if (!urn || typeof urn !== 'string') {
+      throw new Error(
+        'DashX.fetchRecord: urn is required and must be a string (e.g. "article/123")'
+      );
+    }
+    if (options !== null && typeof options !== 'object') {
+      throw new Error('DashX.fetchRecord: options must be an object');
+    }
+    return getNativeDashX().fetchRecord(urn, options || null);
+  },
+
+  searchRecords(resource, options = {}) {
+    if (!resource || typeof resource !== 'string') {
+      throw new Error(
+        'DashX.searchRecords: resource is required and must be a string'
+      );
+    }
+    if (options !== null && typeof options !== 'object') {
+      throw new Error('DashX.searchRecords: options must be an object');
+    }
+    return getNativeDashX().searchRecords(resource, options || null);
+  },
+
+  fetchStoredPreferences() {
+    return getNativeDashX().fetchStoredPreferences();
+  },
+
+  saveStoredPreferences(preferenceData) {
+    if (!preferenceData || typeof preferenceData !== 'object') {
+      throw new Error(
+        'DashX.saveStoredPreferences: preferenceData is required and must be an object'
+      );
+    }
+    return getNativeDashX().saveStoredPreferences(preferenceData);
+  },
+
+  subscribe() {
+    return getNativeDashX().subscribe();
+  },
+
+  unsubscribe() {
+    return getNativeDashX().unsubscribe();
+  },
+
+  setLogLevel(level) {
+    if (typeof level !== 'number') {
+      throw new Error('DashX.setLogLevel: level must be a number');
+    }
+    return getNativeDashX().setLogLevel(level);
+  },
+
+  onPushNotificationReceived(callback) {
+    if (typeof callback !== 'function') {
+      throw new Error(
+        'DashX.onPushNotificationReceived: callback must be a function'
+      );
+    }
+    return getEventEmitter().addListener('messageReceived', callback);
+  },
+
+  onMessageReceived(callback) {
+    if (!_onMessageReceivedDeprecationWarned) {
+      console.warn(
+        'DashX.onMessageReceived is deprecated and will be removed in the next major version. Use DashX.onPushNotificationReceived instead.'
+      );
+      _onMessageReceivedDeprecationWarned = true;
+    }
+    return DashX.onPushNotificationReceived(callback);
+  },
+
+  uploadAsset(filePath, resource, attribute) {
+    if (!filePath || typeof filePath !== 'string') {
+      throw new Error('DashX.uploadAsset: filePath must be a string');
+    }
+    if (!resource || typeof resource !== 'string') {
+      throw new Error('DashX.uploadAsset: resource must be a string');
+    }
+    if (!attribute || typeof attribute !== 'string') {
+      throw new Error('DashX.uploadAsset: attribute must be a string');
+    }
+    return getNativeDashX().uploadAsset(filePath, resource, attribute);
+  },
+
+  fetchAsset(assetId) {
+    if (!assetId || typeof assetId !== 'string') {
+      throw new Error('DashX.fetchAsset: assetId must be a string');
+    }
+    return getNativeDashX().fetchAsset(assetId);
+  },
+
+  enableLifecycleTracking() {
+    return getNativeDashX().enableLifecycleTracking();
+  },
+
+  trackNavigation(navigationRef) {
+    if (!navigationRef || typeof navigationRef !== 'object') {
+      throw new Error(
+        'DashX.trackNavigation: navigationRef must be a NavigationContainer ref'
+      );
+    }
+
+    // A ref from createNavigationContainerRef / useNavigationContainerRef
+    // queues listeners until the container mounts; a plain useRef does not.
+    const navigation =
+      typeof navigationRef.addListener === 'function'
+        ? navigationRef
+        : navigationRef.current;
+
+    if (!navigation) {
+      console.warn(
+        'DashX.trackNavigation: navigationRef.current is null. Call it from NavigationContainer onReady, or pass a ref from useNavigationContainerRef().'
+      );
+      return () => {};
+    }
+    if (
+      typeof navigation.addListener !== 'function' ||
+      typeof navigation.getCurrentRoute !== 'function'
+    ) {
+      throw new Error(
+        'DashX.trackNavigation: navigationRef must be a NavigationContainer ref'
+      );
+    }
+
+    let lastRouteName = null;
+    let active = true;
+
+    const trackCurrentRoute = () => {
+      if (!active) return;
+      // getCurrentRoute() logs an error on a container ref that is not ready.
+      if (typeof navigation.isReady === 'function' && !navigation.isReady()) {
+        return;
+      }
+      const route = navigation.getCurrentRoute();
+      const routeName = route && route.name;
+      if (!routeName || routeName === lastRouteName) return;
+      lastRouteName = routeName;
+      DashX.screen(routeName);
+    };
+
+    const removeListener = navigation.addListener('state', trackCurrentRoute);
+    trackCurrentRoute();
+
+    return () => {
+      active = false;
+      if (typeof removeListener === 'function') removeListener();
+    };
+  },
+
+  enableAdTracking() {
+    if (Platform.OS !== 'ios') return;
+    return getNativeDashX().enableAdTracking();
+  },
+
+  processURL(url, options = {}) {
+    if (Platform.OS !== 'ios') return;
+    if (!url || typeof url !== 'string') {
+      throw new Error('DashX.processURL: url is required and must be a string');
+    }
+    return getNativeDashX().processURL(
+      url,
+      options.source || null,
+      options.forwardToLinkHandler !== false
+    );
+  },
+
+  trackNotificationNavigation(action, notificationId) {
+    if (Platform.OS !== 'ios') return;
+    if (action != null && typeof action !== 'object') {
+      throw new Error(
+        'DashX.trackNotificationNavigation: action must be an object or null'
+      );
+    }
+    return getNativeDashX().trackNotificationNavigation(
+      action || null,
+      notificationId || null
+    );
+  },
+
+  requestNotificationPermission(options) {
+    const fallbackToSettings = Boolean(options && options.fallbackToSettings);
+    return getNativeDashX().requestNotificationPermission(fallbackToSettings);
+  },
+
+  getNotificationPermissionStatus() {
+    return getNativeDashX().getNotificationPermissionStatus();
+  },
+
+  onLinkReceived(callback) {
+    if (typeof callback !== 'function') {
+      throw new Error('DashX.onLinkReceived: callback must be a function');
+    }
+    return getEventEmitter().addListener('linkReceived', callback);
+  },
+
+  onNotificationClicked(callback) {
+    if (typeof callback !== 'function') {
+      throw new Error(
+        'DashX.onNotificationClicked: callback must be a function'
+      );
+    }
+    return getEventEmitter().addListener('notificationClicked', callback);
+  },
+};
+
+export default DashX;

package/.claude/worktrees/autocapture-conventions-review-78f665/ios/DashXEventEmitter.swift

@@ -0,0 +1,15 @@
+class DashXEventEmitter {
+    static let instance = DashXEventEmitter()
+    private static var eventEmitter: DashXReactNative?
+
+    private init() {}
+
+    func registerEventEmitter(eventEmitter: DashXReactNative) {
+        DashXEventEmitter.eventEmitter = eventEmitter
+    }
+
+    func dispatch(name: String, body: Any?) {
+        guard let emitter = DashXEventEmitter.eventEmitter else { return }
+        emitter.sendEvent(withName: name, body: body)
+    }
+}