@octopus-community/react-native 1.0.8 → 1.9.1

package/src/OctopusUIView.tsx

@@ -0,0 +1,57 @@
+import {
+  requireNativeComponent,
+  StyleSheet,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+
+export interface OctopusUIViewProps {
+  /**
+   * When `true`, URLs tapped inside the community UI are not opened by the SDK.
+   * Instead, a `navigateToUrl` event is emitted. Subscribe with
+   * `addNavigateToUrlListener` to receive the URL.
+   *
+   * @default false
+   */
+  interceptUrls?: boolean;
+  style?: StyleProp<ViewStyle>;
+}
+
+const NativeOctopusUIView =
+  requireNativeComponent<OctopusUIViewProps>('OctopusUIView');
+
+/**
+ * Embeds the Octopus Community UI as a native view inside your screen.
+ * Use this when you want to keep your app navigation (e.g. bottom tab bar) visible
+ * instead of opening the SDK in fullscreen with `openUI()`.
+ *
+ * You must call `initialize()` before rendering this component.
+ *
+ * @example
+ * ```tsx
+ * function CommunityTab() {
+ *   return (
+ *     <View style={{ flex: 1 }}>
+ *       <OctopusUIView interceptUrls={true} style={StyleSheet.absoluteFill} />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function OctopusUIView({
+  interceptUrls = false,
+  style,
+}: OctopusUIViewProps) {
+  return (
+    <NativeOctopusUIView
+      interceptUrls={interceptUrls}
+      style={StyleSheet.flatten([styles.default, style])}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  default: {
+    flex: 1,
+  },
+});

package/src/addHasAccessToCommunityListener.ts

@@ -0,0 +1,38 @@
+import { eventEmitter } from './internals/eventEmitter';
+
+export type HasAccessToCommunityListenerCallback = (hasAccess: boolean) => void;
+
+/**
+ * Adds a listener for community access changes.
+ *
+ * This listener receives the **Octopus-managed** access state: the cohort value that determines
+ * whether the user has access to the community (when the SDK manages the A/B logic). It is triggered
+ * when that state changes — e.g. after you call `overrideCommunityAccess`, or when the cohort is
+ * updated by Octopus. Use it to show or hide community entry points in your UI. If your app manages
+ * access itself (and only reports it via `trackCommunityAccess`), this listener is less relevant,
+ * since the SDK is not the source of the access decision.
+ *
+ * @param callback - Function called when the access status changes
+ * @returns A subscription object with a `remove()` method to unsubscribe
+ * @see {@link overrideCommunityAccess} – set the cohort when Octopus manages A/B.
+ * @see {@link trackCommunityAccess} – report access for analytics when your app manages access.
+ *
+ * @example
+ * ```typescript
+ * const subscription = addHasAccessToCommunityListener((hasAccess) => {
+ *   console.log(`Has access to community: ${hasAccess}`);
+ *   // Show or hide community features based on access
+ * });
+ * subscription.remove();
+ * ```
+ */
+export function addHasAccessToCommunityListener(
+  callback: HasAccessToCommunityListenerCallback
+) {
+  return eventEmitter.addListener(
+    'hasAccessToCommunityChanged',
+    (data: { hasAccess: boolean }) => {
+      callback(data.hasAccess);
+    }
+  );
+}

package/src/addNavigateToUrlListener.ts

@@ -0,0 +1,54 @@
+import { eventEmitter } from './internals/eventEmitter';
+import { OctopusReactNativeSdk } from './internals/nativeModule';
+import {
+  type UrlOpeningStrategy,
+  UrlOpeningStrategy as UrlOpeningStrategyEnum,
+} from './types/urlOpeningStrategy';
+
+export type NavigateToUrlListenerCallback = (
+  url: string
+) => UrlOpeningStrategy | Promise<UrlOpeningStrategy>;
+
+/**
+ * Adds a listener for URL navigation events from the Octopus Community UI.
+ *
+ * Only has an effect when the UI was opened with `openUI({ interceptUrls: true })`.
+ * When the user taps a link, this callback is invoked with the URL. Return
+ * `handledByApp` if your app handles the URL (e.g. in-app web view), or
+ * `handledByOctopus` to let the SDK open it in the system browser.
+ *
+ * @param callback - Function called with the tapped URL. Can be async.
+ *   Return `UrlOpeningStrategy.handledByApp` or `UrlOpeningStrategy.handledByOctopus`.
+ * @returns A subscription object with a `remove()` method to unsubscribe.
+ *
+ * @example
+ * ```typescript
+ * const subscription = addNavigateToUrlListener(async (url) => {
+ *   if (url.startsWith('https://myapp.com/')) {
+ *     // Handle deep link in-app
+ *     Linking.openURL(url);
+ *     return UrlOpeningStrategy.handledByApp;
+ *   }
+ *   return UrlOpeningStrategy.handledByOctopus; // Open in system browser
+ * });
+ *
+ * // Later, to unsubscribe:
+ * subscription.remove();
+ * ```
+ */
+export function addNavigateToUrlListener(
+  callback: NavigateToUrlListenerCallback
+) {
+  return eventEmitter.addListener(
+    'navigateToUrl',
+    async (data: { url: string }) => {
+      const strategy = await Promise.resolve(callback(data.url));
+      if (strategy === UrlOpeningStrategyEnum.handledByOctopus) {
+        OctopusReactNativeSdk.handleUrlStrategy(
+          data.url,
+          UrlOpeningStrategyEnum.handledByOctopus
+        );
+      }
+    }
+  );
+}

package/src/addNotSeenNotificationsCountListener.ts

@@ -0,0 +1,35 @@
+import { eventEmitter } from './internals/eventEmitter';
+
+export type NotSeenNotificationsCountListenerCallback = (count: number) => void;
+
+/**
+ * Adds a listener for not seen notifications count changes.
+ *
+ * This listener is triggered whenever the count of unseen notifications changes.
+ * The count is automatically updated by the SDK, but can also be manually refreshed
+ * using `updateNotSeenNotificationsCount()`.
+ *
+ * @param callback - Function called when the notification count changes
+ * @returns A subscription object with a `remove()` method to unsubscribe
+ *
+ * @example
+ * ```typescript
+ * const subscription = addNotSeenNotificationsCountListener((count) => {
+ *   console.log(`Unseen notifications: ${count}`);
+ *   // Update your app's badge or UI
+ * });
+ *
+ * // Later, to unsubscribe:
+ * subscription.remove();
+ * ```
+ */
+export function addNotSeenNotificationsCountListener(
+  callback: NotSeenNotificationsCountListenerCallback
+) {
+  return eventEmitter.addListener(
+    'notSeenNotificationsCountChanged',
+    (data: { count: number }) => {
+      callback(data.count);
+    }
+  );
+}

package/src/addSDKEventListener.ts

@@ -0,0 +1,49 @@
+import { eventEmitter } from './internals/eventEmitter';
+import type { SDKEvent } from './types/sdkEvents';
+
+export type SDKEventListenerCallback = (event: SDKEvent) => void;
+
+/**
+ * Adds a listener for SDK events.
+ *
+ * This listener receives all SDK events including:
+ * - Content creation (posts, comments, replies)
+ * - Content deletion
+ * - Reactions and interactions
+ * - Gamification events
+ * - Screen navigation
+ * - Profile modifications
+ * - Session events
+ * - And more...
+ *
+ * Use TypeScript type guards to narrow down specific event types:
+ *
+ * @param callback - Function called when any SDK event occurs
+ * @returns A subscription object with a `remove()` method to unsubscribe
+ *
+ * @example
+ * ```typescript
+ * const subscription = addSDKEventListener((event) => {
+ *   switch (event.type) {
+ *     case 'postCreated':
+ *       console.log(`Post created: ${event.postId}`);
+ *       break;
+ *     case 'reactionModified':
+ *       console.log(`Reaction changed on ${event.contentId}`);
+ *       break;
+ *     case 'gamificationPointsGained':
+ *       console.log(`Gained ${event.points} points for ${event.action}`);
+ *       break;
+ *     // ... handle other event types
+ *   }
+ * });
+ *
+ * // Later, to unsubscribe:
+ * subscription.remove();
+ * ```
+ */
+export function addSDKEventListener(callback: SDKEventListenerCallback) {
+  return eventEmitter.addListener('sdkEvent', (data: SDKEvent) => {
+    callback(data);
+  });
+}

package/src/connectUser.ts

@@ -14,20 +14,36 @@ export interface ConnectUserParams {
      */
     profilePicture?: string;
     biography?: string;
-    /**
-     * Whether the user has reached legal age.
-     * Used for age-appropriate content filtering and compliance.
-     */
-    legalAgeReached?: boolean;
   };
 }
 
 /**
  * Connects a user using SSO authentication.
  *
- * This function establishes a connection between your app's user and Octopus.
- * It requires that you have configured SSO mode during SDK initialization
- * and have set up a token provider using `useUserTokenProvider` or `addUserTokenRequestListener`.
+ * This function establishes a connection between your app's user and Octopus. It requires that you
+ * have configured SSO mode during SDK initialization and have set up a token provider using
+ * `useUserTokenProvider` or `addUserTokenRequestListener`. The token is obtained via your token
+ * provider; you do not pass it directly to `connectUser`. Call `connectUser` after the user logs in;
+ * call `disconnectUser` when they log out.
+ *
+ * @param params - User id and optional profile (username, profilePicture, biography). See {@link ConnectUserParams}.
+ * @returns A promise that resolves when the user is connected. Rejects if the SDK is not initialized,
+ *          SSO is not configured, or the token provider fails.
+ * @see {@link useUserTokenProvider} – provide JWT from React components.
+ * @see {@link addUserTokenRequestListener} – provide JWT without React.
+ * @see {@link disconnectUser} – disconnect the current user.
+ *
+ * @example
+ * ```typescript
+ * await connectUser({
+ *   userId: 'unique-user-id-from-your-backend',
+ *   profile: {
+ *     username: 'john_doe',
+ *     profilePicture: 'https://example.com/avatar.jpg',
+ *     biography: 'Software developer'
+ *   }
+ * });
+ * ```
  */
 export function connectUser(params: ConnectUserParams): Promise<void> {
   return OctopusReactNativeSdk.connectUser(params);

package/src/index.ts

@@ -3,10 +3,23 @@ export * from './openUI';
 export * from './closeUI';
 export * from './connectUser';
 export * from './disconnectUser';
+export * from './trackCustomEvent';
+export * from './overrideDefaultLocale';
+export * from './updateNotSeenNotificationsCount';
+export * from './overrideCommunityAccess';
+export * from './trackCommunityAccess';
 export * from './addUserTokenRequestListener';
 export * from './useUserTokenProvider';
 export * from './addLoginRequiredListener';
 export * from './addEditUserListener';
+export * from './addNotSeenNotificationsCountListener';
+export * from './addHasAccessToCommunityListener';
+export * from './addSDKEventListener';
+export * from './addNavigateToUrlListener';
 export * from './types/userProfileField';
+export * from './types/sdkEvents';
+export * from './types/urlOpeningStrategy';
 export * from './logger';
 export * from './enums/LogLevel.enum';
+export { OctopusUIView } from './OctopusUIView';
+export type { OctopusUIViewProps } from './OctopusUIView';

package/src/initialize.ts

@@ -144,26 +144,23 @@ export interface InitializeParams {
 /**
  * Initializes the Octopus SDK with the provided configuration.
  *
- * This function must be called before using any other Octopus SDK features.
- * It sets up the SDK with your API key and configures the authentication mode.
+ * This function must be called before using any other Octopus SDK features. It sets up the SDK
+ * with your API key, connection mode (SSO or Octopus-managed authentication), and optional theme
+ * and UI options. For SSO, you also need to set up a token provider with `useUserTokenProvider` or
+ * `addUserTokenRequestListener` before calling `connectUser`.
+ *
+ * @param params - See {@link InitializeParams} (including `theme`, `ui`). For theming guide see the main README.
+ * @see {@link connectUser} – connect a user after initialization (SSO mode).
  *
  * @example
  * ```typescript
- * // Initialize with SSO mode
  * await initialize({
  *   apiKey: 'your-api-key',
- *   connectionMode: {
- *     type: 'sso',
- *     appManagedFields: ['username', 'profilePicture']
- *   }
+ *   connectionMode: { type: 'sso', appManagedFields: ['username', 'profilePicture'] }
  * });
- *
- * // Initialize with Octopus authentication
  * await initialize({
  *   apiKey: 'your-api-key',
- *   connectionMode: {
- *     type: 'octopus'
- *   }
+ *   connectionMode: { type: 'octopus' }
  * });
  * ```
  */

package/src/openUI.ts

@@ -1,8 +1,38 @@
 import { OctopusReactNativeSdk } from './internals/nativeModule';
 
+/**
+ * Options for opening the Octopus UI.
+ */
+export interface OpenUIOptions {
+  /**
+   * When `true`, URLs tapped inside the community UI are not opened by the SDK.
+   * Instead, a `navigateToUrl` event is emitted. Subscribe with
+   * `addNavigateToUrlListener` to receive the URL and decide whether to handle
+   * it in-app or delegate back to the SDK (system browser).
+   *
+   * @default false
+   */
+  interceptUrls?: boolean;
+}
+
 /**
  * Opens the Octopus UI home screen.
+ *
+ * @param options - Optional configuration. Use `interceptUrls: true` to receive
+ *   URL taps via `addNavigateToUrlListener` instead of having the SDK open them.
+ * @returns A promise that resolves when the UI has been opened.
+ *
+ * @example
+ * ```typescript
+ * // Open UI with default behaviour (SDK opens links in system browser)
+ * await openUI();
+ *
+ * // Open UI with URL interception (app receives links via addNavigateToUrlListener)
+ * await openUI({ interceptUrls: true });
+ * ```
  */
-export function openUI(): Promise<void> {
-  return OctopusReactNativeSdk.openUI();
+export function openUI(options?: OpenUIOptions): Promise<void> {
+  const opts = options ?? {};
+  const interceptUrls = opts.interceptUrls === true;
+  return OctopusReactNativeSdk.openUI({ interceptUrls });
 }

package/src/overrideCommunityAccess.ts

@@ -0,0 +1,33 @@
+import { OctopusReactNativeSdk } from './internals/nativeModule';
+
+/**
+ * Override the community access cohort for the current user.
+ *
+ * **When to use:** When the **Octopus SDK manages the A/B logic** — i.e. Octopus assigns
+ * the cohort and decides who has access to the community. In that case, the "Has access
+ * to community" state is the cohort value. Use this function to override that cohort
+ * (e.g. for testing or feature gating). The new state is reflected via `addHasAccessToCommunityListener`.
+ *
+ * **When not to use:** If **your app** decides who has access (e.g. your own feature flag or A/B logic),
+ * do not use `overrideCommunityAccess`. Use `trackCommunityAccess` instead to report the access
+ * value to Octopus for analytics only; that does not change the actual access state in the SDK.
+ *
+ * @param hasAccess - `true` to grant access, `false` to deny access.
+ * @returns A promise that resolves when the override has been applied.
+ * @throws An error if the SDK is not initialized or the call fails.
+ * @see {@link addHasAccessToCommunityListener} – subscribe to the Octopus-managed community access state.
+ * @see {@link trackCommunityAccess} – when your app manages access, report it for analytics only (no change to SDK state).
+ *
+ * @example
+ * ```typescript
+ * const subscription = addHasAccessToCommunityListener((hasAccess) => {
+ *   console.log(`Has access to community: ${hasAccess}`);
+ * });
+ * await overrideCommunityAccess(true);
+ * await overrideCommunityAccess(false);
+ * subscription.remove();
+ * ```
+ */
+export function overrideCommunityAccess(hasAccess: boolean): Promise<void> {
+  return OctopusReactNativeSdk.overrideCommunityAccess(hasAccess);
+}

package/src/overrideDefaultLocale.ts

@@ -0,0 +1,88 @@
+import { OctopusReactNativeSdk } from './internals/nativeModule';
+
+/**
+ * Parameters for overriding the default locale used by the Octopus SDK UI.
+ * Uses ISO 639-1 language code and optional ISO 3166-1 alpha-2 country code.
+ */
+export interface OverrideLocaleParams {
+  /** ISO 639-1 language code (e.g. `"en"`, `"fr"`). */
+  languageCode: string;
+  /** Optional ISO 3166-1 alpha-2 country code (e.g. `"US"`, `"FR"`). */
+  countryCode?: string;
+}
+
+/** ISO 639-1: exactly 2 alphabetic characters (case-insensitive, normalized to lowercase). */
+const LANGUAGE_CODE_REGEX = /^[a-zA-Z]{2}$/;
+
+/** ISO 3166-1 alpha-2: exactly 2 alphabetic characters (case-insensitive, normalized to uppercase). */
+const COUNTRY_CODE_REGEX = /^[a-zA-Z]{2}$/;
+
+function validateAndNormalizeLocale(locale: OverrideLocaleParams): {
+  languageCode: string;
+  countryCode: string | null;
+} {
+  const lang = locale.languageCode?.trim() ?? '';
+  if (!LANGUAGE_CODE_REGEX.test(lang)) {
+    throw new Error(
+      "overrideDefaultLocale: languageCode must be a 2-letter ISO 639-1 code (e.g. 'en', 'fr')"
+    );
+  }
+  const country = locale.countryCode?.trim();
+  if (country !== undefined && country !== '') {
+    if (!COUNTRY_CODE_REGEX.test(country)) {
+      throw new Error(
+        "overrideDefaultLocale: countryCode must be a 2-letter ISO 3166-1 alpha-2 code (e.g. 'US', 'FR')"
+      );
+    }
+    return {
+      languageCode: lang.toLowerCase(),
+      countryCode: country.toUpperCase(),
+    };
+  }
+  return {
+    languageCode: lang.toLowerCase(),
+    countryCode: null,
+  };
+}
+
+/**
+ * Override the default locale used by the Octopus SDK for its UI.
+ *
+ * The change takes effect immediately for subsequently displayed SDK screens.
+ * Pass `null` to reset to the system default locale.
+ *
+ * @param locale - Object with `languageCode` and optional `countryCode`
+ *   (e.g. `{ languageCode: 'fr' }` or `{ languageCode: 'en', countryCode: 'US' }`).
+ *   Pass `null` to use the system default (no override).
+ * @returns A promise that resolves when the override has been applied.
+ * @throws An error if the SDK is not initialized or the call fails.
+ * @throws An error if locale is invalid (e.g. non-ISO language/country codes).
+ *
+ * @example
+ * ```typescript
+ * // Use French
+ * await overrideDefaultLocale({ languageCode: 'fr' });
+ *
+ * // Use English (US)
+ * await overrideDefaultLocale({ languageCode: 'en', countryCode: 'US' });
+ *
+ * // Reset to system default
+ * await overrideDefaultLocale(null);
+ * ```
+ */
+export function overrideDefaultLocale(
+  locale: OverrideLocaleParams | null
+): Promise<void> {
+  if (locale === null) {
+    return OctopusReactNativeSdk.overrideDefaultLocale(null, null);
+  }
+  try {
+    const { languageCode, countryCode } = validateAndNormalizeLocale(locale);
+    return OctopusReactNativeSdk.overrideDefaultLocale(
+      languageCode,
+      countryCode
+    );
+  } catch (e) {
+    return Promise.reject(e);
+  }
+}

package/src/trackCommunityAccess.ts

@@ -0,0 +1,30 @@
+import { OctopusReactNativeSdk } from './internals/nativeModule';
+
+/**
+ * Track community access for analytics without changing the actual access.
+ *
+ * **When to use:** When **your app manages its own A/B logic** — i.e. your app decides who can see
+ * the community (e.g. via your own feature flag or experiment). Call this to report that decision
+ * to Octopus for analytics only. It does not grant or restrict access in the SDK; it only records
+ * the value for reporting.
+ *
+ * **When not to use:** If the **Octopus SDK manages the cohort** (Octopus assigns who has access),
+ * use `overrideCommunityAccess` to change the cohort and `addHasAccessToCommunityListener` to react
+ * to it. Use `trackCommunityAccess` only when the access decision is owned by your app and you just
+ * need to report it.
+ *
+ * @param hasAccess - The access value to report (e.g. the variant your app decided).
+ * @returns A promise that resolves when the tracking call has completed.
+ * @throws An error if the SDK is not initialized or the call fails.
+ * @see {@link overrideCommunityAccess} – when Octopus manages the cohort, override it (and use addHasAccessToCommunityListener to react).
+ * @see {@link addHasAccessToCommunityListener} – subscribe to the Octopus-managed access state (relevant when Octopus or override sets it).
+ *
+ * @example
+ * ```typescript
+ * await trackCommunityAccess(true);
+ * await trackCommunityAccess(false);
+ * ```
+ */
+export function trackCommunityAccess(hasAccess: boolean): Promise<void> {
+  return OctopusReactNativeSdk.trackCommunityAccess(hasAccess);
+}

package/src/trackCustomEvent.ts

@@ -0,0 +1,36 @@
+import { OctopusReactNativeSdk } from './internals/nativeModule';
+
+/**
+ * Track custom events that are merged into Octopus analytics reports.
+ *
+ * Use this to send app-specific business events (e.g. purchases, feature usage)
+ * so they appear alongside Octopus Community analytics.
+ *
+ * All property values must be strings. Non-string values should be stringified
+ * before calling (e.g. numbers as `"123"`, booleans as `"true"`).
+ *
+ * @param name - The name of the custom event (e.g. `"purchase"`, `"screen_view"`).
+ * @param properties - Optional map of string key-value pairs attached to the event.
+ * @returns A promise that resolves when the event has been tracked.
+ * @throws An error if the SDK is not initialized or tracking fails.
+ *
+ * @example
+ * ```typescript
+ * await trackCustomEvent('purchase', {
+ *   product_id: '123',
+ *   price: '9.99',
+ *   currency: 'EUR',
+ * });
+ *
+ * await trackCustomEvent('feature_used', {
+ *   feature: 'community_search',
+ *   source: 'home_screen',
+ * });
+ * ```
+ */
+export function trackCustomEvent(
+  name: string,
+  properties?: Record<string, string>
+): Promise<void> {
+  return OctopusReactNativeSdk.trackCustomEvent(name, properties ?? {});
+}