### Start Metro Bundler

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/example/README.md

Starts the Metro development server, which is essential for bundling JavaScript code for React Native applications. This command is typically run from the project's root directory.

```sh
# Using npm
npm start

# OR using Yarn
yarn start
```

--------------------------------

### Install CocoaPods Dependencies

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/example/README.md

Installs the necessary Ruby dependencies for iOS development using CocoaPods. This is a prerequisite for building and running the iOS app.

```ruby
bundle install
```

--------------------------------

### Start Example App Packager

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/CONTRIBUTING.md

Starts the Metro server for the example application, allowing for development and testing of the SDK.

```sh
yarn example start
```

--------------------------------

### Update CocoaPods and Install iOS Dependencies

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/example/README.md

Updates CocoaPods and installs the project's native dependencies for iOS development. This command should be run after updating native dependencies or on the first clone.

```ruby
bundle exec pod install
```

--------------------------------

### Build and Run iOS App

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/example/README.md

Builds and runs the React Native application on an iOS simulator or device. This command assumes that CocoaPods dependencies have been installed.

```sh
# Using npm
npm run ios

# OR using Yarn
yarn ios
```

--------------------------------

### Build and Run Android App

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/example/README.md

Builds and runs the React Native application on an Android device or emulator. This command initiates the Gradle build process and deploys the app.

```sh
# Using npm
npm run android

# OR using Yarn
yarn android
```

--------------------------------

### Install @octopus-community/react-native

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/README.md

Installs the React Native module using npm.

```sh
npm install @octopus-community/react-native
```

--------------------------------

### Run Example App on iOS

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/CONTRIBUTING.md

Builds and runs the example application on an iOS simulator or device.

```sh
yarn example ios
```

--------------------------------

### Run Example App on Android

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/CONTRIBUTING.md

Builds and runs the example application on an Android device or emulator.

```sh
yarn example android
```

--------------------------------

### iOS Setup with Podfile

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/README.md

Configures the Podfile for static or dynamic framework linkage in iOS projects.

```ruby
# Podfile
linkage = :static # or :dynamic
if linkage != nil
  Pod::UI.puts "Configuring Pod with #{linkage}ally linked Frameworks".green
  use_frameworks! :linkage => linkage.to_sym
end
```

--------------------------------

### Install Dependencies

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/CONTRIBUTING.md

Installs all project dependencies using Yarn workspaces. This command must be run in the root directory.

```sh
yarn
```

--------------------------------

### Octopus SDK initialize() API Documentation

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/initialize.md

API documentation for the initialize function, detailing its parameters and return type.

```APIDOC
initialize(params: InitializeParams): Promise<void>
  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.

  Parameters:
    params: InitializeParams - An object containing the initialization parameters.
      apiKey: string - Your Octopus API key.
      connectionMode: {
        type: "sso" | "octopus";
        appManagedFields?: string[]; // Required when type is "sso"
      } - The connection mode configuration.

  Returns:
    Promise<void> - A promise that resolves when the SDK is successfully initialized.
```

--------------------------------

### Initialize SDK with Octopus Authentication

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/README.md

Initializes the Octopus SDK with an API key and Octopus-handled authentication.

```typescript
import { initialize } from '@octopus-community/react-native';

await initialize({
  apiKey: 'YOUR_OCTOPUS_API_KEY',
  connectionMode: { type: 'octopus' }
});
```

--------------------------------

### Initialize SDK with SSO and App-Managed Fields

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/README.md

Initializes the Octopus SDK for SSO, specifying app-managed profile fields.

```typescript
import {
  initialize,
  addEditUserListener,
  addLoginRequiredListener,
  connectUser,
  disconnectUser,
  useUserTokenProvider,
  closeUI,
} from '@octopus-community/react-native';

// Initialize with SSO mode
await initialize({
  apiKey: 'YOUR_OCTOPUS_API_KEY',
  connectionMode: {
    type: 'sso',
    appManagedFields: ['username', 'profilePicture', 'biography']
  }
});
```

--------------------------------

### Octopus SDK Core Functions

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/README.md

Provides core functionalities for interacting with the Octopus SDK, including user connection, disconnection, UI management, and initialization.

```typescript
/**
 * Initializes the Octopus SDK.
 * @param params - Initialization parameters.
 */
initialize(params: InitializeParams): Promise<void>;

/**
 * Opens the Octopus UI.
 */
openUI(): Promise<void>;

/**
 * Closes the Octopus UI.
 */
closeUI(): Promise<void>;

/**
 * Connects a user to the Octopus service.
 * @param params - Parameters for connecting the user.
 */
connectUser(params: ConnectUserParams): Promise<void>;

/**
 * Disconnects the currently connected user.
 */
disconnectUser(): Promise<void>;

```

--------------------------------

### Initialize Octopus SDK

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/initialize.md

Initializes the Octopus SDK with the provided configuration, including API key and connection mode. This function must be called before using any other Octopus SDK features.

```typescript
import { initialize } from "@octopus-community/react-native";

// Initialize with SSO mode
await initialize({
  apiKey: "your-api-key",
  connectionMode: {
    type: "sso",
    appManagedFields: ["username", "profilePicture"],
  },
});

// Initialize with Octopus authentication
await initialize({
  apiKey: "your-api-key",
  connectionMode: {
    type: "octopus",
  },
});
```

--------------------------------

### Run Unit Tests

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/CONTRIBUTING.md

Executes the unit tests using Jest to verify the functionality of the library.

```sh
yarn test:unit
```

--------------------------------

### InitializeParams Interface

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/interfaces/InitializeParams.md

Defines the configuration parameters required for initializing the Octopus SDK in a React Native application. Includes API key and connection mode settings.

```APIDOC
InitializeParams:
  apiKey: string
    Your Octopus API key obtained from the Octopus dashboard
  connectionMode: {
    appManagedFields: UserProfileField[];
    type: "sso";
  } | {
    type: "octopus";
  }
    The connection mode determines how user authentication is handled.
    - sso: Use Single Sign-On with your existing user system
    - octopus: Let Octopus handle user authentication

    connectionMode.sso:
      appManagedFields: UserProfileField[]
        List of user profile fields that your app manages directly
      type: "sso"
        SSO mode configuration

    connectionMode.octopus:
      type: "octopus"
        Octopus-managed authentication mode
```

--------------------------------

### Publish New Version

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/CONTRIBUTING.md

Publishes a new version of the SDK to npm using release-it. This handles version bumping, tagging, and release creation.

```sh
yarn release
```

--------------------------------

### Handle Login Required and Edit User Events

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/README.md

Sets up listeners for login requirements and user profile editing events, and provides a token for SSO.

```typescript
// Listen for when authentication is required
const loginRequiredSubscription = addLoginRequiredListener(() => {
  // Navigate to your app's login screen
  console.log('User needs to log in');
  closeUI();
});

// Listen for when users want to edit their profile
const editUserSubscription = addEditUserListener(({ fieldToEdit }) => {
  // Navigate to your app's profile editing screen
  // for the specific field (username, profilePicture, etc.)
  console.log(`User wants to edit: ${fieldToEdit}`);
  closeUI();
});

// Set up token provider (in a React component)
useUserTokenProvider(async () => {
  const token = await refreshUserToken();
  return token;
});

// Connect a user after they log in
await connectUser({
  userId: 'unique-user-id',
  profile: {
    username: 'john_doe',
    profilePicture: 'https://example.com/avatar.jpg',
    biography: 'Software developer',
    legalAgeReached: true,
  },
});

// Disconnect the user when they log out
await disconnectUser();

// Cleanup listeners when appropriate (eg. in return of a useEffect)
loginRequiredSubscription.remove();
editUserSubscription.remove();
```

--------------------------------

### Linting

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/CONTRIBUTING.md

Checks the code for style and potential errors using ESLint.

```sh
yarn test:lint
```

--------------------------------

### Open Octopus UI Home Screen

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/openUI.md

The openUI function is used to launch the Octopus UI home screen within the React Native application. It returns a Promise that resolves when the UI is opened.

```javascript
/**
 * Opens the Octopus UI home screen.
 * @returns {Promise<void>}
 */
openUI(): Promise<void>;
```

--------------------------------

### Octopus SDK Logging Functions

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/README.md

Provides functionalities for managing the SDK's logger, including setting a custom logger, resetting it, and setting the log level.

```typescript
/**
 * Sets a custom logger function for the SDK.
 * @param logger - The logger function to use.
 */
setLogger(logger: LoggerFunction): void;

/**
 * Resets the logger to its default state.
 */
resetLogger(): void;

/**
 * Sets the log level for the SDK.
 * @param level - The desired log level.
 */
setLogLevel(level: LogLevel): void;

/**
 * Gets the current log level of the SDK.
 * @returns The current log level.
 */
getLogLevel(): LogLevel;

```

--------------------------------

### Octopus SDK User Token Provider Hook

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/README.md

A React hook for providing user token information within the application.

```typescript
/**
 * A React hook that provides the user token provider.
 * @returns The user token provider.
 */
useUserTokenProvider(): UserTokenProvider;

```

--------------------------------

### connectUser Function

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/connectUser.md

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`.

```APIDOC
connectUser(params: ConnectUserParams): Promise<void>
  Parameters:
    params: ConnectUserParams - An object containing parameters for connecting the user.
  Returns:
    Promise<void> - A promise that resolves when the user connection is established.
```

--------------------------------

### Octopus SDK Event Listeners

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/README.md

Functions for adding and managing listeners for user-related events, such as user edits and login requirements.

```typescript
/**
 * Adds a listener for user edit events.
 * @param callback - The callback function to execute when a user is edited.
 */
addEditUserListener(callback: EditUserListenerCallback): void;

/**
 * Adds a listener for login required events.
 * @param callback - The callback function to execute when login is required.
 */
addLoginRequiredListener(callback: LoginRequiredListenerCallback): void;

/**
 * Adds a listener for user token request events.
 * @param callback - The callback function to execute when a user token is requested.
 */
addUserTokenRequestListener(callback: UserTokenRequestListenerCallback): void;

```

--------------------------------

### Fix Linting Errors

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/CONTRIBUTING.md

Automatically fixes formatting and style errors detected by ESLint.

```sh
yarn test:lint --fix
```

--------------------------------

### Type Checking

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/CONTRIBUTING.md

Verifies the code against TypeScript type definitions to ensure type safety.

```sh
yarn test:types
```

--------------------------------

### ConnectUserParams Interface

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/interfaces/ConnectUserParams.md

Defines the structure for user connection parameters, including optional profile information and a mandatory user identifier. The 'legalAgeReached' property is crucial for age-appropriate content filtering.

```APIDOC
ConnectUserParams:
  profile?: {
    biography?: string
    legalAgeReached?: boolean
    profilePicture?: string
    username?: string
  }
  userId: string

Properties:
  profile: Optional object containing user profile details.
    biography: Optional string for user's biography.
    legalAgeReached: Optional boolean indicating if the user has reached legal age. Used for age-appropriate content filtering and compliance.
    profilePicture: Optional string for the URL or local file path to the user's profile picture. Supports HTTP/HTTPS URLs and local file paths.
    username: Optional string for the user's username.
  userId: Required string representing the unique identifier for the user in your system. This should be a stable, unique ID that won't change for the user.
```

--------------------------------

### UserTokenProvider Type Definition

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/useUserTokenProvider.md

Defines the signature for the user token provider function. This function is expected to return a Promise that resolves to the user's authentication token.

```APIDOC
UserTokenProvider: () => Promise<string>
  - Description: A function that returns a Promise resolving to the user's authentication token.
  - Parameters: None
  - Returns: Promise<string> - The user's authentication token.
```

--------------------------------

### LogLevel Enumeration

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/getLogLevel.md

Defines the possible log levels that can be returned by the getLogLevel function. This enumeration specifies the granularity of logging messages.

```APIDOC
LogLevel:
  - DEBUG
  - INFO
  - WARN
  - ERROR
  - OFF
```

--------------------------------

### resetLogger Function

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/resetLogger.md

Resets the logger to its default implementation. This function does not take any arguments and returns void.

```javascript
resetLogger(): void
```

--------------------------------

### Register User Token Provider (React Hook)

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/useUserTokenProvider.md

Registers a user token provider function for SSO authentication. This hook is essential for enabling the Octopus SDK to fetch user tokens when needed, managing subscriptions and updates automatically.

```typescript
import { useUserTokenProvider } from '@octopus-community/react-native';

// Define your token provider function
const myTokenProvider = async (): Promise<string> => {
  // Logic to fetch or retrieve the user token
  const token = await fetch('/api/token').then(res => res.json()).then(data => data.token);
  return token;
};

// Use the hook in your React component
useUserTokenProvider(myTokenProvider);
```

--------------------------------

### Set Custom Logger

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/setLogger.md

Allows the integration of a custom logging function to manage all log outputs within the React Native application using the Octopus SDK.

```APIDOC
setLogger(logger: LoggerFunction): void

Set a custom logger function to handle all logs.

Parameters:
  logger: LoggerFunction - A function that takes a log level and message and handles the logging.

Returns:
  void
```

--------------------------------

### UserTokenProvider Type Alias

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/type-aliases/UserTokenProvider.md

Defines the signature for a function that asynchronously provides a user token. This function is expected to return a Promise resolving to a string token or throw an error if the token cannot be obtained.

```APIDOC
UserTokenProvider:
  () => Promise<string>
  Description: A function that provides user tokens for authentication.
  Returns:
    Promise<string>: A promise that resolves to a valid user token string.
  Throws:
    Should throw an error if the token cannot be provided (e.g., user not logged in).
```

--------------------------------

### addEditUserListener Function

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/addEditUserListener.md

Adds a listener for edit user events. This listener is triggered when the Octopus SDK needs the host app to handle user profile editing for fields marked as app-managed in SSO mode. It returns an EmitterSubscription.

```APIDOC
addEditUserListener(callback: EditUserListenerCallback): EmitterSubscription
  Adds a listener for edit user events.
  Parameters:
    callback: EditUserListenerCallback - The callback function to be executed when an edit user event occurs.
  Returns:
    EmitterSubscription - An object representing the subscription to the event.
```

--------------------------------

### Close Octopus UI Home Screen

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/closeUI.md

Closes the Octopus UI home screen. This function returns a Promise that resolves when the UI is closed.

```javascript
closeUI(): Promise<void>
```

--------------------------------

### getLogLevel Function

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/getLogLevel.md

Retrieves the current log level configured for the Octopus SDK in a React Native application. This function does not take any arguments and returns a value of type LogLevel.

```javascript
getLogLevel(): LogLevel
```

--------------------------------

### LogLevel Enumeration

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/enumerations/LogLevel.md

Defines the severity levels for log messages. Each level is assigned a numeric value representing its importance.

```APIDOC
LogLevel:
  Enumeration for log message severity.

  Members:
    DEBUG: 0
      Represents debug-level messages, typically verbose information for troubleshooting.
    INFO: 1
      Represents informational messages, indicating normal operation.
    WARN: 2
      Represents warning messages, indicating potential issues that do not stop execution.
    ERROR: 3
      Represents error messages, indicating critical failures that may stop execution.
```

--------------------------------

### addUserTokenRequestListener API

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/addUserTokenRequestListener.md

Adds a listener for user token requests events. This listener is triggered when the Octopus SDK needs a new user token. You may use this listener directly if you prefer not to use the useUserTokenProvider hook.

```APIDOC
addUserTokenRequestListener(callback)
  Parameters:
    callback: UserTokenRequestListenerCallback
  Returns:
    EmitterSubscription
```

--------------------------------

### UserTokenRequestListenerCallback Type Alias

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/type-aliases/UserTokenRequestListenerCallback.md

This type alias defines the signature for a callback function that is expected to return a Promise which resolves to a string. This is commonly used in authentication flows where a token needs to be asynchronously fetched.

```typescript
type UserTokenRequestListenerCallback = () => Promise<string>;
```

--------------------------------

### LoginRequiredListenerCallback Type Alias

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/type-aliases/LoginRequiredListenerCallback.md

Defines the signature for a callback function that is invoked when a login is required. This callback does not return any value.

```typescript
type LoginRequiredListenerCallback = () => void;
```

--------------------------------

### Set Logging Level

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/setLogLevel.md

Configures the verbosity of logs generated by the Octopus SDK. Accepts a LogLevel enum value.

```APIDOC
setLogLevel(level: LogLevel): void

Parameters:
  level: LogLevel - The desired logging level (e.g., DEBUG, INFO, WARN, ERROR).

Returns:
  void

Description:
  Sets the global logging level for the Octopus SDK. This affects the amount of detail that will be printed to the console or other logging destinations.
```

--------------------------------

### EditUserListenerCallback Type Alias

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/type-aliases/EditUserListenerCallback.md

Defines the signature for a callback function that is invoked when a user editing event occurs. It accepts a single parameter, `params`, which is of type `EditUserEventParams`, and does not return any value.

```typescript
type EditUserListenerCallback = (params: EditUserEventParams) => void;
```

--------------------------------

### EditUserEventParams Interface

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/interfaces/EditUserEventParams.md

Defines the structure for parameters used in editing user events. It includes a property to specify which user profile field is being targeted for modification.

```typescript
interface EditUserEventParams {
  fieldToEdit: null | UserProfileField;
}
```

--------------------------------

### LoggerFunction Type Alias

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/type-aliases/LoggerFunction.md

Defines the signature for logging functions used within the SDK. It accepts a log level, a message string, and optional data which can be an Error object, a Record, or any unknown type. The function does not return any value.

```APIDOC
LoggerFunction:
  (level: LogLevel, message: string, data?: Error | Record<string, unknown> | unknown) => void

Parameters:
  level: LogLevel - The severity level of the log message.
  message: string - The main log message.
  data?: Error | Record<string, unknown> | unknown - Optional additional data associated with the log entry, such as an error object or context.

Returns:
  void - This function does not return a value.
```

--------------------------------

### Disconnect User

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/disconnectUser.md

The disconnectUser function is used to terminate the current user's session with the Octopus SDK. It returns a Promise that resolves when the disconnection is complete.

```javascript
import { disconnectUser } from '@octopus-community/react-native';

// To disconnect the user:
disconnectUser();
```

--------------------------------

### addLoginRequiredListener Function

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/functions/addLoginRequiredListener.md

Adds a listener for login required events. This listener is triggered when the Octopus SDK detects that user authentication is required, typically in SSO mode when the user session has expired or the user is not logged in. It returns an EmitterSubscription object.

```APIDOC
addLoginRequiredListener(callback: LoginRequiredListenerCallback): EmitterSubscription
  - Adds a listener for login required events.
  - Parameters:
    - callback: LoginRequiredListenerCallback - The function to call when a login is required.
```

--------------------------------

### UserProfileField Type Definition

Source: https://github.com/octopus-community/octopus-sdk-react-native/blob/main/docs/api/type-aliases/UserProfileField.md

Defines the UserProfileField type alias, which is a union of string literals representing user profile fields. These fields are used in SSO mode to specify which profile data your app will handle directly.

```typescript
type UserProfileField = "username" | "biography" | "profilePicture";
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.