@binoban/react-native 1.0.0

package/src/binobanClient.ts

@@ -0,0 +1,199 @@
+import BinobanReactNative, {
+  type InternalConfig,
+  type NotificationInteractionEvent,
+  type NativeErrorEvent,
+} from './NativeBinobanReactNative';
+import type {
+  UserTraits,
+  BinobanError,
+  JsonMap,
+  NotificationInteraction,
+  NotificationInteractionType,
+  NotificationInteractionSubscription,
+} from './types';
+
+type OnError = (error: BinobanError) => void;
+
+const noopSubscription: NotificationInteractionSubscription = {
+  remove: () => {},
+};
+
+// Native event → public shape. customData arrives as an untyped map (UnsafeObject);
+// normalize it to a string→string record and leave nullables as-is.
+const toInteraction = (
+  e: NotificationInteractionEvent
+): NotificationInteraction => ({
+  notificationUuid: e.notificationUuid,
+  type: e.type as NotificationInteractionType,
+  actionId: e.actionId ?? null,
+  uri: e.uri ?? null,
+  customData: (e.customData as Record<string, string> | null) ?? null,
+  reason: e.reason ?? null,
+});
+
+export class BinobanClient {
+  private config: InternalConfig;
+  private onError?: OnError;
+
+  constructor({
+    config,
+    onError,
+  }: {
+    config: InternalConfig;
+    onError?: OnError;
+  }) {
+    this.config = config;
+    this.onError = onError;
+  }
+
+  private safe<T>(method: string, fn: () => T, fallback?: T): T | undefined {
+    try {
+      return fn();
+    } catch (e) {
+      this.onError?.({
+        method,
+        message: e instanceof Error ? e.message : String(e),
+        cause: e,
+      });
+      if (this.config.debug) {
+        console.warn(`[binoban] ${method}() failed`, e);
+      }
+      return fallback;
+    }
+  }
+
+  async init() {
+    return this.safe(
+      'init',
+      () => {
+        if (!BinobanReactNative) return true;
+        // Subscribe before setup() so an error the native SDK reports during
+        // initialization (e.g. a disabled instance from invalid config) is caught.
+        this.subscribeToNativeErrors();
+        return BinobanReactNative.setup(this.config);
+      },
+      false
+    );
+  }
+
+  // Bridge the KMP Configuration.errorHandler to the onError callback. Only wired
+  // when an onError was provided — otherwise there is nothing to route errors to.
+  private subscribeToNativeErrors() {
+    if (!BinobanReactNative || !this.onError) return;
+    this.safe('subscribeToNativeErrors', () => {
+      BinobanReactNative?.onNativeError((e: NativeErrorEvent) => {
+        this.onError?.({
+          method: e.name ? `native:${e.name}` : 'native',
+          message: e.message,
+        });
+      });
+    });
+  }
+
+  async track(eventName: string, properties?: Object) {
+    this.safe('track', () => {
+      if (BinobanReactNative) BinobanReactNative.track(eventName, properties);
+    });
+  }
+
+  async identify(userId: string, userTraits?: UserTraits) {
+    this.safe('identify', () => {
+      if (BinobanReactNative) BinobanReactNative.identify(userId, userTraits);
+    });
+  }
+
+  async flush() {
+    this.safe('flush', () => {
+      if (BinobanReactNative) BinobanReactNative.flush();
+    });
+  }
+
+  async reset() {
+    this.safe('reset', () => {
+      if (BinobanReactNative) BinobanReactNative.reset();
+    });
+  }
+
+  anonymousId() {
+    return this.safe('anonymousId', () => BinobanReactNative?.anonymousId());
+  }
+
+  userId() {
+    return this.safe('userId', () => BinobanReactNative?.userId());
+  }
+
+  deviceId() {
+    return this.safe('deviceId', () => BinobanReactNative?.deviceId());
+  }
+
+  notify(payloadData: Object) {
+    this.safe('notify', () => {
+      if (BinobanReactNative) BinobanReactNative.notify(payloadData);
+    });
+  }
+
+  setDeviceToken(token: string) {
+    this.safe('setDeviceToken', () => {
+      if (BinobanReactNative) BinobanReactNative.setDeviceToken(token);
+    });
+  }
+
+  // Subscribe to notification interactions (body/action-button taps, dismissals,
+  // delivery). Returns a subscription; call remove() to stop listening.
+  onNotificationInteraction(
+    listener: (interaction: NotificationInteraction) => void
+  ): NotificationInteractionSubscription {
+    return (
+      this.safe('onNotificationInteraction', () => {
+        if (!BinobanReactNative) return noopSubscription;
+        return BinobanReactNative.onNotificationInteraction(
+          (e: NotificationInteractionEvent) => {
+            this.safe('onNotificationInteraction:listener', () =>
+              listener(toInteraction(e))
+            );
+          }
+        );
+      }) ?? noopSubscription
+    );
+  }
+
+  // The interaction that cold-started the app (a tap delivered before JS could
+  // subscribe), consumed once. Resolves null when there is none.
+  async getInitialNotificationInteraction(): Promise<NotificationInteraction | null> {
+    return (
+      this.safe('getInitialNotificationInteraction', async () => {
+        const e = await BinobanReactNative?.getInitialNotificationInteraction();
+        return e ? toInteraction(e) : null;
+      }) ?? Promise.resolve(null)
+    );
+  }
+
+  // iOS only — forward UNUserNotificationCenter callbacks from the host (a native
+  // AppDelegate or a JS push library). No-ops on Android, where the SDK's
+  // notification trampoline delivers interactions on its own.
+  didReceiveNotificationResponse(
+    userInfo: JsonMap,
+    actionId?: string | null,
+    dismissed?: boolean
+  ) {
+    this.safe('didReceiveNotificationResponse', () => {
+      BinobanReactNative?.didReceiveNotificationResponse(
+        userInfo,
+        actionId ?? null,
+        dismissed ?? false
+      );
+    });
+  }
+
+  willPresentNotification(userInfo: JsonMap) {
+    this.safe('willPresentNotification', () => {
+      BinobanReactNative?.willPresentNotification(userInfo);
+    });
+  }
+
+  didReceiveRemoteNotification(userInfo: JsonMap) {
+    this.safe('didReceiveRemoteNotification', () => {
+      BinobanReactNative?.didReceiveRemoteNotification(userInfo);
+    });
+  }
+}

package/src/constants.ts

@@ -0,0 +1,30 @@
+import type { Config } from './NativeBinobanReactNative';
+
+export const defaultConfig: Config = {
+  credentials: {
+    android: {
+      apiKey: '',
+      sourceIdentifier: '',
+    },
+    iOS: {
+      apiKey: '',
+      sourceIdentifier: '',
+    },
+  },
+  apiHost: '',
+  debug: false,
+  collectDeviceId: true,
+  trackAppLifecycleEvents: true,
+  useLifecycleObserver: true,
+  trackDeepLinks: true,
+  flushAt: 20,
+  flushInterval: 30,
+  autoAddSegmentDestination: true,
+  disableTelemetry: false,
+  telemetryHost: '',
+  uploadMaxRetries: 3,
+  backoffBaseMillis: 1000,
+  backoffFactor: 2.0,
+  backoffMaxMillis: 60000,
+  maxFilesPerFlush: 20,
+};

package/src/index.tsx

@@ -0,0 +1,105 @@
+import React, { createContext, useContext } from 'react';
+import type { Config, InternalConfig } from './NativeBinobanReactNative';
+import type { ClientMethods } from './types';
+import { defaultConfig } from './constants';
+import { BinobanClient } from './binobanClient';
+import { Platform } from 'react-native';
+
+export const createClient = (config: Config) => {
+  const clientConfig = { ...defaultConfig, ...config };
+  const onError = config.onError;
+
+  const platformCreds =
+    Platform.OS === 'android'
+      ? clientConfig.credentials?.android
+      : clientConfig.credentials?.iOS;
+
+  const internalConfig: InternalConfig = {
+    apiHost: clientConfig.apiHost,
+    debug: clientConfig.debug,
+    collectDeviceId: clientConfig.collectDeviceId,
+    trackAppLifecycleEvents: clientConfig.trackAppLifecycleEvents,
+    useLifecycleObserver: clientConfig.useLifecycleObserver,
+    trackDeepLinks: clientConfig.trackDeepLinks,
+    flushAt: clientConfig.flushAt,
+    flushInterval: clientConfig.flushInterval,
+    autoAddSegmentDestination: clientConfig.autoAddSegmentDestination,
+    disableTelemetry: clientConfig.disableTelemetry,
+    telemetryHost: clientConfig.telemetryHost,
+    uploadMaxRetries: clientConfig.uploadMaxRetries,
+    backoffBaseMillis: clientConfig.backoffBaseMillis,
+    backoffFactor: clientConfig.backoffFactor,
+    backoffMaxMillis: clientConfig.backoffMaxMillis,
+    maxFilesPerFlush: clientConfig.maxFilesPerFlush,
+    apiKey: platformCreds?.apiKey ?? '',
+    sourceIdentifier: platformCreds?.sourceIdentifier ?? '',
+  };
+
+  const client = new BinobanClient({ config: internalConfig, onError });
+
+  const credsValid =
+    !!platformCreds?.apiKey && !!platformCreds?.sourceIdentifier;
+
+  if (credsValid) {
+    // Fire-and-forget; init() is internally guarded and never throws.
+    void client.init();
+  } else {
+    const message = `Missing Binoban credentials for platform "${Platform.OS}". SDK will be inert.`;
+    onError?.({ method: 'createClient', message });
+    if (clientConfig.debug) {
+      console.warn(`[binoban] ${message}`);
+    }
+  }
+
+  return client;
+};
+
+const Context = createContext<BinobanClient | null>(null);
+
+export const BinobanProvider = ({
+  client,
+  children,
+}: {
+  client?: BinobanClient;
+  children?: React.ReactNode;
+}) => {
+  if (!client) {
+    return null;
+  }
+
+  return <Context.Provider value={client}>{children}</Context.Provider>;
+};
+
+export const useBinoban = (): ClientMethods => {
+  const client = useContext(Context);
+  return React.useMemo(() => {
+    if (!client) {
+      console.error(
+        'Binoban client not configured!',
+        'To use the useBinoban() hook, pass an initialized Binoban client into the BinobanProvider'
+      );
+    }
+
+    return {
+      track: async (...args) => client?.track(...args),
+      identify: async (...args) => client?.identify(...args),
+      flush: async () => client?.flush(),
+      reset: async () => client?.reset(),
+      anonymousId: () => client?.anonymousId(),
+      userId: () => client?.userId(),
+      deviceId: () => client?.deviceId(),
+      notify: (...args) => client?.notify(...args),
+      setDeviceToken: (token) => client?.setDeviceToken(token),
+      onNotificationInteraction: (listener) =>
+        client?.onNotificationInteraction(listener) ?? { remove: () => {} },
+      getInitialNotificationInteraction: () =>
+        client?.getInitialNotificationInteraction() ?? Promise.resolve(null),
+      didReceiveNotificationResponse: (...args) =>
+        client?.didReceiveNotificationResponse(...args),
+      willPresentNotification: (...args) =>
+        client?.willPresentNotification(...args),
+      didReceiveRemoteNotification: (...args) =>
+        client?.didReceiveRemoteNotification(...args),
+    };
+  }, [client]);
+};

package/src/types.ts

@@ -0,0 +1,78 @@
+export type JsonValue =
+  | boolean
+  | number
+  | string
+  | null
+  | JsonList
+  | JsonMap
+  | undefined;
+export interface JsonMap {
+  [key: string]: JsonValue;
+  [index: number]: JsonValue;
+}
+export type JsonList = Array<JsonValue>;
+
+export type UserTraits = JsonMap & {
+  firstName?: string;
+  lastName?: string;
+  phone?: string;
+  birthday?: string;
+  email?: string;
+  gender?: string;
+  id?: string;
+  name?: string;
+  title?: string;
+  username?: string;
+  website?: string;
+};
+
+export type NotificationInteractionType =
+  | 'DELIVERED'
+  | 'CLICKED'
+  | 'CLOSED'
+  | 'FAILED'
+  | 'OPENED';
+
+// Public shape of a notification interaction delivered to JS. Mirrors the KMP
+// NotificationInteraction, with customData narrowed to a string→string map.
+export type NotificationInteraction = {
+  notificationUuid: string;
+  type: NotificationInteractionType;
+  actionId?: string | null;
+  uri?: string | null;
+  customData?: Record<string, string> | null;
+  reason?: string | null;
+};
+
+export type NotificationInteractionSubscription = { remove: () => void };
+
+export type ClientMethods = {
+  track: (event: string, properties?: JsonMap) => void;
+  identify: (userId: string, userTraits?: UserTraits) => void;
+  flush: () => void;
+  reset: () => void;
+  anonymousId: () => string | undefined;
+  userId: () => string | undefined;
+  deviceId: () => string | undefined;
+  notify: (payloadData: JsonMap) => void;
+  setDeviceToken: (token: string) => void;
+  // Notification interactions
+  onNotificationInteraction: (
+    listener: (interaction: NotificationInteraction) => void
+  ) => NotificationInteractionSubscription;
+  getInitialNotificationInteraction: () => Promise<NotificationInteraction | null>;
+  // iOS-only host forwarding (no-ops on Android)
+  didReceiveNotificationResponse: (
+    userInfo: JsonMap,
+    actionId?: string | null,
+    dismissed?: boolean
+  ) => void;
+  willPresentNotification: (userInfo: JsonMap) => void;
+  didReceiveRemoteNotification: (userInfo: JsonMap) => void;
+};
+
+export type BinobanError = {
+  method: string;
+  message: string;
+  cause?: unknown;
+};