@octopus-community/react-native 1.0.7 → 1.9.1

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 ?? {});
+}

package/src/types/sdkEvents.ts

@@ -0,0 +1,315 @@
+/**
+ * Types for SDK events emitted by Octopus SDK.
+ * These events represent various user interactions and system events within the Octopus community.
+ */
+
+/**
+ * Content types that can be included in a post
+ */
+export type PostContentType = 'text' | 'image' | 'poll';
+
+/**
+ * Content kind (post, comment, or reply)
+ */
+export type ContentKind = 'post' | 'comment' | 'reply';
+
+/**
+ * Reaction kinds
+ */
+export type ReactionKind =
+  | 'heart'
+  | 'joy'
+  | 'mouthOpen'
+  | 'clap'
+  | 'cry'
+  | 'rage'
+  | 'unknown';
+
+/**
+ * Report reasons for content or profile reporting
+ */
+export type ReportReason =
+  | 'hateSpeech'
+  | 'explicit'
+  | 'violence'
+  | 'spam'
+  | 'suicide'
+  | 'fakeProfile'
+  | 'childExploitation'
+  | 'intellectualProperty'
+  | 'other';
+
+/**
+ * Gamification actions that can gain points
+ */
+export type GamificationPointsGainedAction =
+  | 'post'
+  | 'comment'
+  | 'reply'
+  | 'reaction'
+  | 'vote'
+  | 'postCommented'
+  | 'profileCompleted'
+  | 'dailySession';
+
+/**
+ * Gamification actions that can remove points
+ */
+export type GamificationPointsRemovedAction =
+  | 'postDeleted'
+  | 'commentDeleted'
+  | 'replyDeleted'
+  | 'reactionDeleted';
+
+/**
+ * Source of a post click
+ */
+export type PostClickedSource = 'feed' | 'profile';
+
+/**
+ * Screen types displayed in the Octopus UI
+ */
+export type ScreenType =
+  | 'postsFeed'
+  | 'postDetail'
+  | 'commentDetail'
+  | 'createPost'
+  | 'profile'
+  | 'otherUserProfile'
+  | 'editProfile'
+  | 'reportContent'
+  | 'reportProfile'
+  | 'validateNickname'
+  | 'settingsList'
+  | 'settingsAccount'
+  | 'settingsAbout'
+  | 'reportExplanation'
+  | 'deleteAccount';
+
+/**
+ * Base interface for all SDK events
+ */
+export interface BaseSDKEvent {
+  type: string;
+}
+
+/**
+ * Event emitted when a post is created
+ */
+export interface PostCreatedEvent extends BaseSDKEvent {
+  type: 'postCreated';
+  postId: string;
+  content: PostContentType[];
+  topicId: string | null;
+  textLength: number;
+}
+
+/**
+ * Event emitted when a comment is created
+ */
+export interface CommentCreatedEvent extends BaseSDKEvent {
+  type: 'commentCreated';
+  commentId: string;
+  postId: string;
+  textLength: number;
+}
+
+/**
+ * Event emitted when a reply is created
+ */
+export interface ReplyCreatedEvent extends BaseSDKEvent {
+  type: 'replyCreated';
+  replyId: string;
+  commentId: string;
+  textLength: number;
+}
+
+/**
+ * Event emitted when content is deleted
+ */
+export interface ContentDeletedEvent extends BaseSDKEvent {
+  type: 'contentDeleted';
+  contentId: string;
+  contentKind: ContentKind;
+}
+
+/**
+ * Event emitted when a reaction is modified (added, changed, or removed)
+ */
+export interface ReactionModifiedEvent extends BaseSDKEvent {
+  type: 'reactionModified';
+  contentId: string;
+  contentKind: ContentKind;
+  previousReaction: ReactionKind | null;
+  newReaction: ReactionKind | null;
+}
+
+/**
+ * Event emitted when a poll is voted on
+ */
+export interface PollVotedEvent extends BaseSDKEvent {
+  type: 'pollVoted';
+  contentId: string;
+  optionId: string;
+}
+
+/**
+ * Event emitted when content is reported
+ */
+export interface ContentReportedEvent extends BaseSDKEvent {
+  type: 'contentReported';
+  contentId: string;
+  reasons: ReportReason[];
+}
+
+/**
+ * Event emitted when a profile is reported
+ */
+export interface ProfileReportedEvent extends BaseSDKEvent {
+  type: 'profileReported';
+  profileId: string;
+  reasons: ReportReason[];
+}
+
+/**
+ * Event emitted when gamification points are gained
+ */
+export interface GamificationPointsGainedEvent extends BaseSDKEvent {
+  type: 'gamificationPointsGained';
+  points: number;
+  action: GamificationPointsGainedAction;
+}
+
+/**
+ * Event emitted when gamification points are removed
+ */
+export interface GamificationPointsRemovedEvent extends BaseSDKEvent {
+  type: 'gamificationPointsRemoved';
+  points: number;
+  action: GamificationPointsRemovedAction;
+}
+
+/**
+ * Screen information for screen displayed events
+ */
+export interface ScreenInfo {
+  type: ScreenType;
+  feedId?: string;
+  relatedTopicId?: string | null;
+  postId?: string;
+  commentId?: string;
+  profileId?: string;
+}
+
+/**
+ * Event emitted when a screen is displayed
+ */
+export interface ScreenDisplayedEvent extends BaseSDKEvent {
+  type: 'screenDisplayed';
+  screen: ScreenInfo;
+}
+
+/**
+ * Event emitted when a notification is clicked
+ */
+export interface NotificationClickedEvent extends BaseSDKEvent {
+  type: 'notificationClicked';
+  notificationId: string;
+  contentId: string | null;
+}
+
+/**
+ * Event emitted when a post is clicked
+ */
+export interface PostClickedEvent extends BaseSDKEvent {
+  type: 'postClicked';
+  postId: string;
+  source: PostClickedSource;
+}
+
+/**
+ * Event emitted when the translation button is clicked
+ */
+export interface TranslationButtonClickedEvent extends BaseSDKEvent {
+  type: 'translationButtonClicked';
+  contentId: string;
+  viewTranslated: boolean;
+  contentKind: ContentKind;
+}
+
+/**
+ * Event emitted when the comment button is clicked
+ */
+export interface CommentButtonClickedEvent extends BaseSDKEvent {
+  type: 'commentButtonClicked';
+  postId: string;
+}
+
+/**
+ * Event emitted when the reply button is clicked
+ */
+export interface ReplyButtonClickedEvent extends BaseSDKEvent {
+  type: 'replyButtonClicked';
+  commentId: string;
+}
+
+/**
+ * Event emitted when the "see replies" button is clicked
+ */
+export interface SeeRepliesButtonClickedEvent extends BaseSDKEvent {
+  type: 'seeRepliesButtonClicked';
+  commentId: string;
+}
+
+/**
+ * Event emitted when a profile is modified
+ */
+export interface ProfileModifiedEvent extends BaseSDKEvent {
+  type: 'profileModified';
+  nicknameUpdated: boolean;
+  bioUpdated: boolean;
+  bioLength: number | null;
+  pictureUpdated: boolean;
+  hasPicture: boolean | null;
+}
+
+/**
+ * Event emitted when a session starts
+ */
+export interface SessionStartedEvent extends BaseSDKEvent {
+  type: 'sessionStarted';
+  sessionId: string;
+}
+
+/**
+ * Event emitted when a session stops
+ */
+export interface SessionStoppedEvent extends BaseSDKEvent {
+  type: 'sessionStopped';
+  sessionId: string;
+}
+
+/**
+ * Union type of all possible SDK events
+ */
+export type SDKEvent =
+  | PostCreatedEvent
+  | CommentCreatedEvent
+  | ReplyCreatedEvent
+  | ContentDeletedEvent
+  | ReactionModifiedEvent
+  | PollVotedEvent
+  | ContentReportedEvent
+  | ProfileReportedEvent
+  | GamificationPointsGainedEvent
+  | GamificationPointsRemovedEvent
+  | ScreenDisplayedEvent
+  | NotificationClickedEvent
+  | PostClickedEvent
+  | TranslationButtonClickedEvent
+  | CommentButtonClickedEvent
+  | ReplyButtonClickedEvent
+  | SeeRepliesButtonClickedEvent
+  | ProfileModifiedEvent
+  | SessionStartedEvent
+  | SessionStoppedEvent;

package/src/types/urlOpeningStrategy.ts

@@ -0,0 +1,20 @@
+/**
+ * Strategy for handling URLs tapped inside the Octopus Community UI.
+ *
+ * When URL interception is enabled via `openUI({ interceptUrls: true })`,
+ * the app receives each tapped URL via `addNavigateToUrlListener`. The callback
+ * returns one of these strategies to decide who handles the URL.
+ */
+export enum UrlOpeningStrategy {
+  /**
+   * The URL has been handled by the app. The SDK will not open it.
+   * Use this when you open the URL in an in-app web view or handle it yourself.
+   */
+  handledByApp = 'handledByApp',
+
+  /**
+   * The URL should be opened by the Octopus SDK (system browser).
+   * The native layer will open the URL in the default browser when this is returned.
+   */
+  handledByOctopus = 'handledByOctopus',
+}

package/src/updateNotSeenNotificationsCount.ts

@@ -0,0 +1,30 @@
+import { OctopusReactNativeSdk } from './internals/nativeModule';
+
+/**
+ * Force refresh the unseen notification count from the server.
+ *
+ * This method triggers a manual update of the notification badge count.
+ * The updated count will be emitted via the notSeenNotificationsCountChanged event.
+ * Use `addNotSeenNotificationsCountListener` to listen for count changes.
+ *
+ * @returns A promise that resolves when the update is complete.
+ * @throws An error if the SDK is not initialized or if the update fails.
+ *
+ * @example
+ * ```typescript
+ * // Listen to count changes
+ * const subscription = addNotSeenNotificationsCountListener((count) => {
+ *   console.log(`Unseen notifications: ${count}`);
+ *   // Update your badge UI
+ * });
+ *
+ * // Manually refresh the count
+ * await updateNotSeenNotificationsCount();
+ *
+ * // Later, unsubscribe
+ * subscription.remove();
+ * ```
+ */
+export function updateNotSeenNotificationsCount(): Promise<void> {
+  return OctopusReactNativeSdk.updateNotSeenNotificationsCount();
+}