### Install Dependencies (npm)

Source: https://github.com/ronasit/react-native-common-modules/blob/main/CONTRIBUTING.md

Installs project dependencies using npm. This is a prerequisite for starting development.

```bash
npm install
```

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

### Setup Reactotron Debugger with Redux Integration (TypeScript)

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

Configures and initializes the Reactotron debugger with Redux integration for development. It supports custom plugins like MMKV storage inspector and networking plugins, and only activates in development mode. This setup requires @reduxjs/toolkit and reactotron-react-native.

```typescript
import { setupReactotron } from '@ronas-it/react-native-common-modules/reactotron';
import { configureStore, Reducer } from '@reduxjs/toolkit';
import type { ReactotronReactNative } from 'reactotron-react-native';
import mmkvPlugin from 'reactotron-react-native-mmkv';
import { storage } from './mmkv-storage';
import { rootReducer, AppState } from './root-reducer';

// Setup with custom plugins
const reactotron = setupReactotron('MyApp', [
  // Add MMKV storage inspector
  (reactotron) => mmkvPlugin<ReactotronReactNative>({ storage }),
  // Add custom networking plugin
  (reactotron) => reactotron.use(networkingPlugin()),
]);

// Create Redux store with Reactotron enhancer
const enhancers = reactotron ? [reactotron.createEnhancer()] : [];

export const store = configureStore({
  reducer: rootReducer,
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware({
      serializableCheck: false,
    }),
  enhancers: (getDefaultEnhancers) =>
    getDefaultEnhancers().concat(enhancers),
});

// Basic setup without plugins
const simpleReactotron = setupReactotron('SimpleApp');
const simpleEnhancers = simpleReactotron ? [simpleReactotron.createEnhancer()] : [];

export const simpleStore = configureStore({
  reducer: rootSimpleReducer, // Assuming rootSimpleReducer is defined elsewhere
  enhancers: (getDefaultEnhancers) =>
    getDefaultEnhancers().concat(simpleEnhancers),
});

```

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

### Email and OTP Authentication with useAuthWithIdentifier

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

Handles email-based authentication using one-time passwords (OTP). It supports starting authorization, verifying the OTP code, and managing loading states. Dependencies include React Native components and SecureStore for token management.

```typescript
import { useAuthWithIdentifier } from '@ronas-it/react-native-common-modules/clerk';
import { useState } from 'react';
import { View, TextInput, Button, Alert, ActivityIndicator } from 'react-native';

// Email + OTP authentication
function EmailOtpAuth() {
  const [email, setEmail] = useState('');
  const [code, setCode] = useState('');
  const [step, setStep] = useState<'email' | 'verify'>('email');

  const {
    startSignUp,
    startSignIn,
    startAuthorization,
    verifyCode,
    isLoading,
    isVerifying
  } = useAuthWithIdentifier('emailAddress', 'otp');

  const handleSubmitEmail = async () => {
    // Automatically determines sign-up vs sign-in
    const result = await startAuthorization({ identifier: email });

    if (result.error) {
      Alert.alert('Error', 'Failed to send verification code');
      return;
    }

    if (result.isSuccess) {
      setStep('verify');
    }
  };

  const handleVerifyCode = async () => {
    const result = await verifyCode({
      code,
      tokenTemplate: 'my-jwt-template' // optional
    });

    if (result?.sessionToken) {
      // Store token and navigate
      await SecureStore.setItemAsync('token', result.sessionToken);
      navigation.replace('Home');
    } else {
      Alert.alert('Error', 'Invalid verification code');
    }
  };

  if (step === 'email') {
    return (
      <View style={styles.container}>
        <TextInput
          placeholder="Email address"
          value={email}
          onChangeText={setEmail}
          keyboardType="email-address"
          autoCapitalize="none"
        />
        <Button
          title={isLoading ? 'Sending...' : 'Continue'}
          onPress={handleSubmitEmail}
          disabled={isLoading || !email}
        />
      </View>
    );
  }

  return (
    <View style={styles.container}>
      <TextInput
        placeholder="Enter 6-digit code"
        value={code}
        onChangeText={setCode}
        keyboardType="number-pad"
        maxLength={6}
      />
      <Button
        title={isVerifying ? 'Verifying...' : 'Verify'}
        onPress={handleVerifyCode}
        disabled={isVerifying || code.length !== 6}
      />
      <Button title="Back" onPress={() => setStep('email')} />
    </View>
  );
}

```

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

### Username and Password Authentication with useAuthWithIdentifier

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

Enables username and password-based authentication. It supports starting sign-in operations and handling the session token upon successful authentication. Dependencies include React Native components and a function to store the token.

```typescript
import { useAuthWithIdentifier } from '@ronas-it/react-native-common-modules/clerk';
import { useState } from 'react';
import { View, TextInput, Button, Alert, ActivityIndicator } from 'react-native';

// Username + Password authentication
function UsernamePasswordAuth() {
  const [username, setUsername] = useState('');
  const [password, setPassword] = useState('');

  const { startSignIn, startSignUp, isLoading } = useAuthWithIdentifier('username', 'password');

  const handleLogin = async () => {
    const result = await startSignIn({
      identifier: username,
      password,
      tokenTemplate: 'api-token'
    });

    if (result.sessionToken) {
      await storeToken(result.sessionToken);
      navigation.replace('Dashboard');
    }
  };

  return (
    <View>
      <TextInput placeholder="Username" value={username} onChangeText={setUsername} />
      <TextInput placeholder="Password" value={password} onChangeText={setPassword} secureTextEntry />
      <Button title="Log In" onPress={handleLogin} disabled={isLoading} />
    </View>
  );
}

```

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

### Manage Push Notifications with API Config (React)

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

This example demonstrates using the `usePushNotifications` hook with the `apiConfig` option. It automatically handles subscribing and unsubscribing devices by making requests to the provided URLs. The `onNotificationResponse` callback is used to navigate the user based on notification data, and `apiErrorHandler` logs API errors.

```typescript
import { usePushNotifications } from '@ronas-it/react-native-common-modules/push-notifications';
import { useSelector } from 'react-redux';
import { useRouter } from 'expo-router';

// Using API config (recommended for simple use cases)
export function App() {
  const authToken = useSelector((state) => state.auth.token);
  const router = useRouter();

  usePushNotifications({
    isAuthenticated: !!authToken,
    apiConfig: {
      subscribeDeviceUrl: 'https://api.example.com/push/subscribe',
      unsubscribeDeviceUrl: 'https://api.example.com/push/unsubscribe',
      accessToken: authToken,
      method: 'POST', // optional, defaults to POST
    },
    onNotificationResponse: (notification) => {
      const data = notification.request.content.data;
      if (data.type === 'message') {
        router.push(`/chat/${data.conversationId}`);
      } else if (data.type === 'order') {
        router.push(`/orders/${data.orderId}`);
      }
    },
    apiErrorHandler: (response) => {
      console.error('Push notification API error:', response.status);
    },
  });

  return <MainNavigator />;
}
```

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

### Manage Push Notifications with Custom Handlers (React)

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

This example shows how to use the `usePushNotifications` hook with custom `subscribeDevice` and `unsubscribeDevice` functions. This approach offers more control over the subscription process, allowing for complex logic and data handling. It also includes a `getTokenErrorHandler` to manage cases where notification permissions are denied.

```typescript
import { usePushNotifications } from '@ronas-it/react-native-common-modules/push-notifications';
import { useSelector, useDispatch } from 'react-redux';
import { Platform } from 'react-native';
import Device from 'react-native-device-info';

// Using custom subscribe/unsubscribe functions
export function AppWithCustomHandlers() {
  const authToken = useSelector((state) => state.auth.token);
  const dispatch = useDispatch();

  usePushNotifications({
    isAuthenticated: !!authToken,
    subscribeDevice: async ({ expoToken }) => {
      const response = await fetch('https://api.example.com/devices/register', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${authToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          token: expoToken,
          platform: Platform.OS,
          deviceName: Device.deviceName,
        }),
      });
      dispatch(setDeviceRegistered(true));
      return response;
    },
    unsubscribeDevice: async ({ expoToken }) => {
      const response = await fetch('https://api.example.com/devices/unregister', {
        method: 'DELETE',
        headers: {
          'Authorization': `Bearer ${authToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ token: expoToken }),
      });
      dispatch(setDeviceRegistered(false));
      return response;
    },
    getTokenErrorHandler: (permissionResponse) => {
      dispatch(showPermissionModal('notifications'));
    },
  });

  return <MainNavigator />;
}
```

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

### ImagePickerService: Profile Photo Uploader Component (TypeScript)

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

A React Native component example demonstrating how to use `imagePickerService` to select a profile photo from either the camera or gallery and upload it. It manages an uploading state and uses a placeholder `api.uploadProfilePhoto` function.

```typescript
import {
  imagePickerService,
  ImagePickerSource
} from '@ronas-it/react-native-common-modules/image-picker';
import React, { useState } from 'react';
import { View, Button } from 'react-native';

// Profile photo component example
function ProfilePhotoUploader({ userId }: { userId: string }) {
  const [uploading, setUploading] = useState(false);

  const handleImageSelect = async (source: ImagePickerSource) => {
    const result = await imagePickerService.getImage(source);

    if (typeof result === 'string') return; // Error case
    if (result.canceled || !result.assets?.[0]) return;

    setUploading(true);
    try {
      const formData = imagePickerService.getFormData(result.assets[0].uri, 'photo');
      formData.append('userId', userId);

      await api.uploadProfilePhoto(formData); // Assuming 'api' is defined elsewhere
    } finally {
      setUploading(false);
    }
  };

  return (
    <View>
      <Button title="Take Photo" onPress={() => handleImageSelect(ImagePickerSource.CAMERA)} />
      <Button title="Choose from Gallery" onPress={() => handleImageSelect(ImagePickerSource.GALLERY)} />
    </View>
  );
}
```

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

### Image Picker Service for React Native

Source: https://github.com/ronasit/react-native-common-modules/blob/main/README.md

Provides access to the device's camera and image gallery. It requires the 'expo-image-picker' dependency. The service offers methods to get images, launch the gallery or camera, request permissions, and format image data as FormData.

```typescript
import { imagePickerService, ImagePickerSource } from '@ronas-it/react-native-common-modules/image-picker';

const handlePickImage = async (source: ImagePickerSource) => {
  const image = await imagePickerService.getImage(source);
  const asset = image?.assets?.[0];

  if (!asset) {
    return;
  }

  const data = imagePickerService.getFormData(asset.uri);

  // API call
  createMedia(data);
};
```

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

### Manage Translations with i18n Module

Source: https://github.com/ronasit/react-native-common-modules/blob/main/README.md

The `i18n` module provides utilities for setting the application language and using translations via `i18n-js`. It requires `i18n-js` and `expo-localization` as dependencies. The example demonstrates setting up translations and using them within React components.

```typescript
import { setLanguage, useTranslation } from '@ronas-it/react-native-common-modules/i18n';
import { AppSafeAreaView } from '@ronas-it/react-native-common-modules/safe-area-view';
import { ReactElement, useState, useContext, createContext } from 'react';
import { View, Text, Alert, Pressable } from 'react-native';

const translations = {
  en: {
    ...require('i18n/example/en.json')
  },
  fr: {
    ...require('i18n/example/fr.json')
  }
};

const useLanguage = setLanguage(translations, 'en');

interface LanguageContextProps {
  language: string;
  onLanguageChange?: (language: keyof typeof translations) => void;
}

export const LanguageContext = createContext<LanguageContextProps>({ language: 'en' });

function App(): ReactElement {
  return (
    <Stack>
      <Stack.Screen name='index' />
    </Stack>
  );
}

export default function RootLayout(): ReactElement | null {
  const [language, setLanguageState] = useState<keyof typeof translations>('en');

  useLanguage(language);

  return (
    <LanguageContext.Provider value={{ language, onLanguageChange: setLanguageState }}>
      <App />
    </LanguageContext.Provider>
  );
}

// screen example
export function RootScreen(): ReactElement {
  const translate = useTranslation('EXAMPLE');
  const { language, onLanguageChange } = useContext(LanguageContext);

  const onPress = () => Alert.alert(translate('TEXT_PRESSED'));

  const handleLanguageChange = (): void => {
    onLanguageChange?.(language === 'en' ? 'fr' : 'en');
  };

  return (
    <AppSafeAreaView edges={['bottom']} style={styles.safeAreaContainer}>
      <View style={styles.container}>
        <Pressable onPress={onPress} hitSlop={10}>
        <Text>{translate('BUTTON_PRESS_ME')}</Text>
        </Pressable>
        <Pressable onPress={handleLanguageChange} hitSlop={10}>
          <Text>{translate('BUTTON_LANGUAGE')}</Text>
        </Pressable>
      </View>
    </AppSafeAreaView>
  );
}
```

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

### Email Password Reset Flow with useResetPassword Hook

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

Implements a password reset flow using email verification. It handles sending a reset code to the user's email and then verifying the code to set a new password. This example demonstrates state management for different steps of the reset process and utilizes the 'useResetPassword' hook with the 'emailAddress' method.

```typescript
import { useResetPassword } from '@ronas-it/react-native-common-modules/clerk';
import { useState } from 'react';
import { View, TextInput, Button, Alert } from 'react-native';

function PasswordResetScreen() {
  const [step, setStep] = useState<'email' | 'verify' | 'complete'>('email');
  const [email, setEmail] = useState('');
  const [code, setCode] = useState('');
  const [newPassword, setNewPassword] = useState('');
  const [confirmPassword, setConfirmPassword] = useState('');

  const {
    startResetPassword,
    resetPassword,
    isCodeSending,
    isResetting
  } = useResetPassword({ method: 'emailAddress' });

  const handleSendCode = async () => {
    const result = await startResetPassword({ identifier: email });

    if (result.isSuccess) {
      setStep('verify');
      Alert.alert('Success', 'Reset code sent to your email');
    } else {
      Alert.alert('Error', 'Failed to send reset code. Check your email address.');
    }
  };

  const handleResetPassword = async () => {
    if (newPassword !== confirmPassword) {
      Alert.alert('Error', 'Passwords do not match');
      return;
    }

    if (newPassword.length < 8) {
      Alert.alert('Error', 'Password must be at least 8 characters');
      return;
    }

    const result = await resetPassword({
      code,
      password: newPassword,
      tokenTemplate: 'api-token',
    });

    if (result.isSuccess && result.sessionToken) {
      await SecureStore.setItemAsync('token', result.sessionToken);
      Alert.alert('Success', 'Password reset successfully');
      navigation.replace('Home');
    } else {
      Alert.alert('Error', result.error?.message || 'Failed to reset password');
    }
  };

  if (step === 'email') {
    return (
      <View style={styles.container}>
        <Text style={styles.title}>Reset Password</Text>
        <Text>Enter your email to receive a reset code</Text>
        <TextInput
          placeholder="Email address"
          value={email}
          onChangeText={setEmail}
          keyboardType="email-address"
          autoCapitalize="none"
        />
        <Button
          title={isCodeSending ? 'Sending...' : 'Send Reset Code'}
          onPress={handleSendCode}
          disabled={isCodeSending || !email}
        />
      </View>
    );
  }

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Enter New Password</Text>
      <TextInput
        placeholder="Verification code"
        value={code}
        onChangeText={setCode}
        keyboardType="number-pad"
      />
      <TextInput
        placeholder="New password"
        value={newPassword}
        onChangeText={setNewPassword}
        secureTextEntry
      />
      <TextInput
        placeholder="Confirm password"
        value={confirmPassword}
        onChangeText={setConfirmPassword}
        secureTextEntry
      />
      <Button
        title={isResetting ? 'Resetting...' : 'Reset Password'}
        onPress={handleResetPassword}
        disabled={isResetting || !code || !newPassword}
      />
      <Button title="Back" onPress={() => setStep('email')} />
    </View>
  );
}

```

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

### Use Get Session Token Hook for React Native

Source: https://github.com/ronasit/react-native-common-modules/blob/main/README.md

The `useGetSessionToken` hook is a utility for retrieving session tokens in React Native applications. It exposes a function that can optionally accept a token template for customized token generation.

```typescript
import { useGetSessionToken } from '@ronas-it/react-native-common-modules/clerk';

// Inside a React component:
const { getSessionToken } = useGetSessionToken();

// Example usage:
// const fetchToken = async () => {
//   const token = await getSessionToken({ template: 'your_template_name' });
//   console.log('Session Token:', token);
// };
```

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

### Push Notifications Hook Setup in React Native

Source: https://github.com/ronasit/react-native-common-modules/blob/main/README.md

Shows how to set up the usePushNotifications hook for managing Expo push notifications. This hook automatically subscribes/unsubscribes devices based on authentication status and handles notification responses. It requires several Expo packages and can be configured with API endpoints for subscription/unsubscription.

```typescript
// Somewhere in a root component of your app:
import { usePushNotifications } from '@ronas-it/react-native-common-modules/push-notifications';

...
const authToken = useSelector(authSelectors.token);
...
usePushNotifications({
  apiConfig: {
    subscribeDeviceUrl: 'https://your-api.com/api/v1/push-notifications/subscribe',
    unsubscribeDeviceUrl: 'https://your-api.com/api/v1/push-notifications/unsubscribe',
    accessToken: authToken,
  },
  isAuthenticated: !!authToken,
})
```

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

### Use Auth With Identifier Hook for React Native Authentication

Source: https://github.com/ronasit/react-native-common-modules/blob/main/README.md

The `useAuthWithIdentifier` hook handles user sign-up and sign-in using an identifier (email, phone, username) and supports OTP or password verification. It returns functions to start authentication flows, verify codes, and loading states.

```typescript
import React, { useState } from 'react';
import { View, TextInput, Button } from 'react-native';
import { useAuthWithIdentifier } from '@ronas-it/react-native-common-modules/clerk';

export const AuthWithIdentifierComponent = () => {
  const [identifier, setIdentifier] = useState('');
  const [verificationCode, setVerificationCode] = useState('');
  const { startSignUp, verifyCode, isLoading, isVerifying } = useAuthWithIdentifier('emailAddress', 'otp');

  const handleSignUp = async () => {
    await startSignUp({ identifier });
  };

  const handleVerifyCode = async () => {
    const result = await verifyCode({ code: verificationCode });
    console.log(result.sessionToken)
  };

  return (
    <View>
      <TextInput
        placeholder="Enter your email"
        value={identifier}
        onChangeText={setIdentifier}
        keyboardType="email-address"
      />
      <TextInput
        placeholder="Enter verification code"
        value={verificationCode}
        onChangeText={setVerificationCode}
      />
      <Button onPress={handleSignUp} title="Sign Up" disabled={isLoading || isVerifying} />
      <Button onPress={handleVerifyCode} title="Verify code" disabled={isLoading || isVerifying} />
    </View>
  );
};
```

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

### Phone Number Password Reset Flow with useResetPassword Hook

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

Demonstrates initiating a password reset flow using a phone number. This snippet shows how to use the 'useResetPassword' hook with the 'phoneNumber' method to start the reset process. The actual implementation for handling the code verification and setting a new password would be similar to the email-based flow.

```typescript
// Phone-based password reset
function PhonePasswordReset() {
  const { startResetPassword, resetPassword, isCodeSending, isResetting } = 
    useResetPassword({ method: 'phoneNumber' });

  const handleSendCode = async () => {
    await startResetPassword({ identifier: '+15551234567' });
  };

  // ... similar flow for verification and setting new password
}

```

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

### Configure Reactotron Debugger with setupReactotron

Source: https://github.com/ronasit/react-native-common-modules/blob/main/README.md

The `setupReactotron` function configures and initializes the Reactotron debugger for development. It requires dependencies like `@reduxjs/toolkit`, `reactotron-react-native`, `reactotron-react-js`, and `reactotron-redux`. The function accepts a project name and an array of Reactotron plugins, such as `reactotron-react-native-mmkv`.

```typescript
import { setupReactotron } from '@ronas-it/react-native-common-modules/reactotron';
import { createStoreInitializer } from '@ronas-it/rtkq-entity-api';
import Reactotron from 'reactotron-react-native';
import mmkvPlugin from 'reactotron-react-native-mmkv';
import type { ReactotronReactNative } from 'reactotron-react-native';
import { storage } from './mmkv/storage/instance/location'; // <--- update this to your mmkv instance.

const reactotron = setupReactotron('your-app', [
  // You can add an array of Reactotron plugins here
  (reactotron) => mmkvPlugin<ReactotronReactNative>({ storage }),
]);
const enhancers = reactotron ? [reactotron.createEnhancer()] : [];

const initStore = createStoreInitializer({
  rootReducer: rootReducer as unknown as Reducer<AppState>,
  middlewares,
  enhancers,
});
```

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

### Initialize and Manage WebSocket Connections with TypeScript

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

Demonstrates how to initialize, connect, subscribe to channels, and disconnect a WebSocketService instance using TypeScript. It includes type-safe channel naming, event handling, and integration with Redux for state management. Dependencies include the '@ronas-it/react-native-common-modules/websocket' library and a Redux store.

```typescript
import { WebSocketService, PusherEvent } from '@ronas-it/react-native-common-modules/websocket';
import { store } from './store';
import { useEffect } from 'react';

// Define typed channel names for type safety
type AppChannelName = 
  | `private-conversations.${number}`
  | `private-users.${number}`
  | 'public-announcements';

// Create service instance
const webSocketService = new WebSocketService<AppChannelName>({
  apiKey: 'your-pusher-app-key',
  cluster: 'us2',
  authURL: 'https://api.example.com/broadcasting/auth',
  useTLS: true,
  activityTimeout: 30000, // 30 seconds
  pongTimeout: 10000,     // 10 seconds
  authorizerTimeoutInSeconds: 60,
});

// Initialize and connect after user authentication
function initializeWebSocket() {
  // Token getter function - always returns current token
  const tokenGetter = () => store.getState().auth.accessToken;

  webSocketService.init(tokenGetter, {
    onConnectionStateChange: (currentState, previousState) => {
      console.log(`WebSocket: ${previousState} -> ${currentState}`);
      // Assuming setConnectionStatus is a Redux action creator
      // store.dispatch(setConnectionStatus(currentState)); 
    },
    onError: (message, code, error) => {
      console.error('WebSocket error:', { message, code, error });
    },
  });

  webSocketService.connect();
}

// Subscribe to conversation channel
function subscribeToConversation(conversationId: number) {
  const channelName = `private-conversations.${conversationId}` as const;

  const handleEvent = (event: PusherEvent) => {
    const data = JSON.parse(event.data);

    switch (event.eventName) {
      case 'message.created':
        // Assuming addMessage is a Redux action creator
        // store.dispatch(addMessage(data)); 
        break;
      case 'message.deleted':
        // Assuming removeMessage is a Redux action creator
        // store.dispatch(removeMessage(data.id)); 
        break;
      case 'user.typing':
        // Assuming setTypingIndicator is a Redux action creator
        // store.dispatch(setTypingIndicator(data)); 
        break;
    }
  };

  webSocketService.subscribeToChannel(channelName, handleEvent);

  // Return cleanup function
  return () => {
    webSocketService.unsubscribeFromChannel(channelName, handleEvent);
  };
}

// React hook for conversation subscription
function useConversationWebSocket(conversationId: number) {
  useEffect(() => {
    const unsubscribe = subscribeToConversation(conversationId);
    return unsubscribe;
  }, [conversationId]);
}

// Cleanup on logout
function handleLogout() {
  webSocketService.disconnect();
  // Assuming clearAuth is a Redux action creator
  // store.dispatch(clearAuth()); 
}

export { webSocketService, initializeWebSocket };

```

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

### ImagePickerService: Take Photo with Camera (TypeScript)

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

Shows how to take a photo using the device's camera with the `imagePickerService`. It includes a custom callback for handling permission denial and returns the captured asset if successful.

```typescript
import {
  imagePickerService,
  ImagePickerSource
} from '@ronas-it/react-native-common-modules/image-picker';

// Take photo with camera
async function takePhoto() {
  const result = await imagePickerService.getImage(
    ImagePickerSource.CAMERA,
    () => {
      // Custom permission denied callback
      navigation.navigate('PermissionSettings', { type: 'camera' });
    }
  );

  if (typeof result !== 'string' && !result.canceled) {
    return result.assets[0];
  }
  return null;
}
```

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

### Handle SSO Authentication with useAuthWithSSO Hook (React Native)

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

Implements Single Sign-On (SSO) authentication using various OAuth providers like Google, Apple, and Facebook. It leverages the `useAuthWithSSO` hook from `@ronas-it/react-native-common-modules/clerk`. Requires `expo-web-browser` and `expo-linking` for OAuth redirect handling. The hook returns `startSSOFlow` and `isLoading` states. Input is an object with `strategy`, `redirectUrl`, and optional `tokenTemplate`. Output includes success status, session token, or error information.

```typescript
import { useAuthWithSSO } from '@ronas-it/react-native-common-modules/clerk';
import { View, Button, ActivityIndicator } from 'react-native';
import * as WebBrowser from 'expo-web-browser';
import * as Linking from 'expo-linking';

// Required for OAuth redirect handling
WebBrowser.maybeCompleteAuthSession();

function SocialLoginScreen() {
  const { startSSOFlow, isLoading } = useAuthWithSSO();
  const redirectUrl = Linking.createURL('/oauth-callback');

  const handleGoogleSignIn = async () => {
    const result = await startSSOFlow({
      strategy: 'oauth_google',
      redirectUrl,
      tokenTemplate: 'api-access-token', // optional
    });

    if (result.isSuccess && result.sessionToken) {
      await SecureStore.setItemAsync('authToken', result.sessionToken);
      navigation.replace('Home');
    } else if (result.error) {
      Alert.alert('Error', 'Google sign-in failed');
    }
  };

  const handleAppleSignIn = async () => {
    const result = await startSSOFlow({
      strategy: 'oauth_apple',
      redirectUrl,
    });

    if (result.sessionToken) {
      navigation.replace('Home');
    }
  };

  const handleFacebookSignIn = async () => {
    const result = await startSSOFlow({
      strategy: 'oauth_facebook',
      redirectUrl,
    });

    if (result.isSuccess) {
      // Access signIn/signUp objects if needed for additional data
      console.log('Sign up object:', result.signUp);
      navigation.replace('Home');
    }
  };

  if (isLoading) {
    return (
      <View style={styles.centered}>
        <ActivityIndicator size="large" />
      </View>
    );
  }

  return (
    <View style={styles.container}>
      <Button title="Continue with Google" onPress={handleGoogleSignIn} />
      <Button title="Continue with Apple" onPress={handleAppleSignIn} />
      <Button title="Continue with Facebook" onPress={handleFacebookSignIn} />
    </View>
  );
}

```

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

### Run Code Checks (npm)

Source: https://github.com/ronasit/react-native-common-modules/blob/main/CONTRIBUTING.md

Executes code style and correctness checks using npm scripts. This helps maintain code quality.

```bash
npm run lint
npm run format
```

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

### Push Changes and Tags (Git)

Source: https://github.com/ronasit/react-native-common-modules/blob/main/CONTRIBUTING.md

Pushes local commits and tags to the remote repository. This is part of the release process.

```bash
git push && git push --tags
```

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

### ImagePickerService: Select Multiple Images (TypeScript)

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

Illustrates how to request gallery access and launch the gallery to select multiple images with custom options like `allowsMultipleSelection`, `selectionLimit`, and `quality`. It returns an array of selected assets.

```typescript
import {
  imagePickerService
} from '@ronas-it/react-native-common-modules/image-picker';

// Direct gallery launch with custom options
async function selectMultipleImages() {
  const permission = await imagePickerService.requestGalleryAccess();

  if (permission.granted) {
    const result = await imagePickerService.launchGallery({
      allowsMultipleSelection: true,
      selectionLimit: 5,
      quality: 0.8,
      allowsEditing: false,
    });

    return result.assets || [];
  }
  return [];
}
```

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

### Access Clerk Authentication Resources with useClerkResources Hook

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

Provides access to essential Clerk authentication methods such as signIn, signUp, setActive, and signOut. This hook serves as a foundational element for implementing custom authentication flows and integrating Clerk into React Native applications. It requires the Clerk SDK to be initialized.

```typescript
import { useClerkResources } from '@ronas-it/react-native-common-modules/clerk';

// Basic usage for custom authentication flows
function CustomAuthScreen() {
  const { signIn, signUp, setActive, signOut } = useClerkResources();

  const handleCustomSignIn = async (email: string, password: string) => {
    try {
      const result = await signIn?.create({
        identifier: email,
        password,
      });

      if (result?.status === 'complete') {
        await setActive({ session: result.createdSessionId });
        navigation.navigate('Home');
      }
    } catch (error) {
      console.error('Sign in failed:', error);
    }
  };

  const handleSignOut = async () => {
    await signOut();
    navigation.navigate('Login');
  };

  return (
    <View>
      <Button title="Sign In" onPress={() => handleCustomSignIn(email, password)} />
      <Button title="Sign Out" onPress={handleSignOut} />
    </View>
  );
}

```

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

### Use Clerk Resources Hook for React Native

Source: https://github.com/ronasit/react-native-common-modules/blob/main/README.md

The `useClerkResources` hook provides access to essential Clerk methods and objects like signUp, signIn, setActive, and signOut. It simplifies managing user authentication states within a React Native application.

```typescript
import { useClerkResources } from '@ronas-it/react-native-common-modules/clerk';

// Inside a React component:
const { signUp, signIn, setActive, signOut } = useClerkResources();

// Example usage:
// signUp.create({ emailAddress: 'test@example.com', password: 'password123' });
// signIn.create({ identifier: 'test@example.com', password: 'password123' });
// setActive({ sessionToken: 'your_session_token' });
// signOut();
```

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

### AppSafeAreaView Usage in React Native

Source: https://github.com/ronasit/react-native-common-modules/blob/main/README.md

Demonstrates how to use the AppSafeAreaView component for granular control of safe area edges. It requires the 'react-native-safe-area-context' dependency and allows specifying which edges to respect and applying custom styles.

```jsx
import { AppSafeAreaView } from '@ronas-it/react-native-common-modules/safe-area-view';

<AppSafeAreaView edges={['top', 'bottom']} style={styles.container}>
  <Text>Content goes here</Text>
</AppSafeAreaView>
```

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

### ImagePickerService: Pick and Upload Image (TypeScript)

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

Demonstrates picking an image from the gallery, handling permission errors, and uploading the selected image using FormData. It utilizes the `imagePickerService` and `ImagePickerSource` from '@ronas-it/react-native-common-modules/image-picker'.

```typescript
import {
  imagePickerService,
  ImagePickerSource,
  ImagePickerError
} from '@ronas-it/react-native-common-modules/image-picker';

// Pick image from gallery and upload
async function pickAndUploadImage() {
  const result = await imagePickerService.getImage(ImagePickerSource.GALLERY);

  // Handle permission errors
  if (result === ImagePickerError.PERMISSION_DENIED) {
    Alert.alert('Permission Required', 'Please enable gallery access in settings');
    return;
  }
  if (result === ImagePickerError.UNAVAILABLE) {
    console.log('Permission not yet granted, will prompt user');
    return;
  }

  // Handle successful image selection
  if (!result.canceled && result.assets?.[0]) {
    const asset = result.assets[0];
    const formData = imagePickerService.getFormData(asset.uri, 'avatar');

    await fetch('https://api.example.com/upload', {
      method: 'POST',
      body: formData,
      headers: { 'Content-Type': 'multipart/form-data' },
    });
  }
}
```

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

### Handle Ticket-Based Authentication with useAuthWithTicket Hook (React Native)

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

Facilitates ticket-based authentication, commonly used for magic link implementations. It utilizes the `useAuthWithTicket` hook from `@ronas-it/react-native-common-modules/clerk`. This hook requires a ticket generated by the backend API. It integrates with `expo-linking` to handle incoming magic link URLs. The hook provides `startAuthorization` and `isLoading` states. Input is the `ticket` and an optional `tokenTemplate`. Output includes success status, session token, or error messages.

```typescript
import { useAuthWithTicket } from '@ronas-it/react-native-common-modules/clerk';
import { useEffect } from 'react';
import * as Linking from 'expo-linking';

// Magic link handler component
function MagicLinkHandler() {
  const { startAuthorization, isLoading } = useAuthWithTicket();
  const url = Linking.useURL();

  useEffect(() => {
    if (url) {
      handleMagicLink(url);
    }
  }, [url]);

  const handleMagicLink = async (linkUrl: string) => {
    // Extract ticket from magic link URL
    const { queryParams } = Linking.parse(linkUrl);
    const ticket = queryParams?.ticket as string;

    if (!ticket) return;

    const result = await startAuthorization({
      ticket,
      tokenTemplate: 'session-token',
    });

    if (result.isSuccess && result.sessionToken) {
      await SecureStore.setItemAsync('token', result.sessionToken);
      navigation.replace('Home');
    } else {
      Alert.alert('Error', 'Invalid or expired magic link');
      navigation.replace('Login');
    }
  };

  if (isLoading) {
    return (
      <View style={styles.centered}>
        <ActivityIndicator size="large" />
        <Text>Authenticating...</Text>
      </View>
    );
  }

  return null;
}

// Backend generates ticket via Clerk Backend API
// POST https://api.clerk.dev/v1/sign_in_tokens
// { user_id: "user_xxx" }

```

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

### Phone Number and OTP Authentication with useAuthWithIdentifier

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

Facilitates phone number-based authentication using one-time passwords (OTP). It allows initiating sign-up and verifying the OTP code, with loading state management. Requires React Native components and navigation.

```typescript
import { useAuthWithIdentifier } from '@ronas-it/react-native-common-modules/clerk';
import { useState } from 'react';
import { View, TextInput, Button, Alert, ActivityIndicator } from 'react-native';

// Phone + OTP authentication
function PhoneOtpAuth() {
  const [phone, setPhone] = useState('');
  const { startSignUp, verifyCode, isLoading } = useAuthWithIdentifier('phoneNumber', 'otp');

  const handleSignUp = async () => {
    const result = await startSignUp({ identifier: phone });
    if (result.isSuccess) {
      navigation.navigate('VerifyPhone');
    }
  };

  return (
    <View>
      <TextInput
        placeholder="+1 (555) 123-4567"
        value={phone}
        onChangeText={setPhone}
        keyboardType="phone-pad"
      />
      <Button title="Send Code" onPress={handleSignUp} disabled={isLoading} />
    </View>
  );
}

```

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

### WebSocket Service for React Native and Web

Source: https://github.com/ronasit/react-native-common-modules/blob/main/README.md

Manages WebSocket connections using Pusher for both web and mobile applications. It requires '@pusher/pusher-websocket-react-native' for mobile and 'pusher-js' for web. The service handles initialization, connection, disconnection, and channel subscriptions with optional authentication.

```typescript
import { WebSocketService } from '@ronas-it/react-native-common-modules/websocket';

// Create a service instance
type ChannelName = `private-conversations.${number}` | `private-users.${number}`;
const webSocketService = new WebSocketService<ChannelName>({
  apiKey: '1234567890qwertyuiop',
  cluster: 'eu',
  authURL: 'https://your-api.com/api/v1/broadcasting/auth',
});

// Callback to get your app auth token for private channels
const tokenGetter = () => authSelectors.token(getState());
// Initialize Pusher, e.g. after an app initialization or successful authorization
webSocketService.init(
  tokenGetter, // Always get actual token
  {
    // Optional handlers
    onConnectionStateChange: (currentState) => {
      // Do something with the connection state
    },
  },
);
// Connect to Pusher instance
webSocketService.connect();

// Subscribe to a channel when it's necessary
webSocketService.subscribeToChannel('private-conversations.123', (event) => {
  console.log('Received event:', event);
});

// Unsubscribe from a channel, e.g. before an app closing or logging out
webSocketService.unsubscribeFromChannel('private-conversations.123', (event) => {
  console.log('Received event:', event);
});
```

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

### Bump Version (npm)

Source: https://github.com/ronasit/react-native-common-modules/blob/main/CONTRIBUTING.md

Increments the package version using npm. This command updates the version number in package.json and creates a Git commit and tag.

```bash
npm version patch
npm version minor
npm version major
```

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

### Initialize and Use Translations with i18n-js

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

Manages internationalization using i18n-js and Expo Localization. The `setLanguage` function initializes translations and provides a hook for language changes, while `useTranslation` offers namespaced access to translation strings. It supports multiple languages and dynamic language switching.

```typescript
// translations/index.ts
export const translations = {
  en: {
    COMMON: {
      LOADING: 'Loading...',
      ERROR: 'An error occurred',
      RETRY: 'Retry',
    },
    AUTH: {
      LOGIN: 'Log In',
      LOGOUT: 'Log Out',
      EMAIL_PLACEHOLDER: 'Enter your email',
      PASSWORD_PLACEHOLDER: 'Enter your password',
      WELCOME: 'Welcome, {{name}}!',
    },
    PROFILE: {
      TITLE: 'Profile',
      EDIT: 'Edit Profile',
      SETTINGS: 'Settings',
    },
  },
  es: {
    COMMON: {
      LOADING: 'Cargando...', 
      ERROR: 'Ocurrio un error',
      RETRY: 'Reintentar',
    },
    AUTH: {
      LOGIN: 'Iniciar sesion',
      LOGOUT: 'Cerrar sesion',
      EMAIL_PLACEHOLDER: 'Ingresa tu correo',
      PASSWORD_PLACEHOLDER: 'Ingresa tu contrasena',
      WELCOME: 'Bienvenido, {{name}}!',
    },
    PROFILE: {
      TITLE: 'Perfil',
      EDIT: 'Editar Perfil',
      SETTINGS: 'Configuracion',
    },
  },
};

// app/_layout.tsx
import { setLanguage } from '@ronas-it/react-native-common-modules/i18n';
import { translations } from '../translations';
import { createContext, useState, ReactElement } from 'react';
import { Stack } from 'expo-router';

const useLanguage = setLanguage(translations, 'en');

interface LanguageContextType {
  language: keyof typeof translations;
  setLanguage: (lang: keyof typeof translations) => void;
}

export const LanguageContext = createContext<LanguageContextType>({
  language: 'en',
  setLanguage: () => {},
});

export default function RootLayout(): ReactElement {
  const [language, setLanguageState] = useState<keyof typeof translations>('en');

  // Apply language change
  useLanguage(language);

  return (
    <LanguageContext.Provider value={{ language, setLanguage: setLanguageState }}>
      <Stack>
        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
        <Stack.Screen name="auth" options={{ headerShown: false }} />
      </Stack>
    </LanguageContext.Provider>
  );
}

// screens/LoginScreen.tsx
import { useTranslation } from '@ronas-it/react-native-common-modules/i18n';
import { View, Text, TextInput, Button } from 'react-native';

export function LoginScreen() {
  const t = useTranslation('AUTH');
  const tCommon = useTranslation('COMMON');

  return (
    <View style={styles.container}>
      <TextInput placeholder={t('EMAIL_PLACEHOLDER')} />
      <TextInput placeholder={t('PASSWORD_PLACEHOLDER')} secureTextEntry />
      <Button title={t('LOGIN')} onPress={handleLogin} />
      {isLoading && <Text>{tCommon('LOADING')}</Text>}
    </View>
  );
}

// screens/ProfileScreen.tsx
import { useTranslation } from '@ronas-it/react-native-common-modules/i18n';
import { useContext } from 'react';
import { LanguageContext } from '../app/_layout';

export function ProfileScreen({ user }) {
  const t = useTranslation('PROFILE');
  const tAuth = useTranslation('AUTH');
  const { language, setLanguage } = useContext(LanguageContext);

  return (
    <View>
      <Text style={styles.title}>{t('TITLE')}</Text>
      <Text>{tAuth('WELCOME', { name: user.name })}</Text>

      <Button title={t('EDIT')} onPress={() => navigate('EditProfile')} />
      <Button title={t('SETTINGS')} onPress={() => navigate('Settings')} />

      {/* Language switcher */}
      <Button
        title={language === 'en' ? 'Espanol' : 'English'}
        onPress={() => setLanguage(language === 'en' ? 'es' : 'en')}
      />
    </View>
  );
}

```

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

### Implement User Authentication with Clerk

Source: https://github.com/ronasit/react-native-common-modules/blob/main/README.md

This section covers hooks and helpers for integrating user authentication using the Clerk Expo SDK. It requires dependencies such as `@clerk/clerk-expo`, `expo-web-browser`, and `expo-auth-session`. Refer to the Clerk Expo documentation for detailed integration steps.

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

### AppSafeAreaView Component for React Native

Source: https://context7.com/ronasit/react-native-common-modules/llms.txt

AppSafeAreaView provides granular control over safe area insets, adding padding to internal elements rather than the entire screen. It allows for flexible layout customization and supports specifying edges for inset application. This component is useful for ensuring content is not obscured by system UI elements like notches or status bars.

```tsx
import { AppSafeAreaView } from '@ronas-it/react-native-common-modules/safe-area-view';
import { Text, View, StyleSheet } from 'react-native';

// Basic usage with specific edges
export function HomeScreen() {
  return (
    <AppSafeAreaView edges={['top', 'bottom']} style={styles.container}>
      <Text>This content respects top and bottom safe areas</Text>
    </AppSafeAreaView>
  );
}

// Full screen with all edges (default)
export function ProfileScreen() {
  return (
    <AppSafeAreaView style={styles.fullScreen}>
      <View style={styles.header}>
        <Text>Header</Text>
      </View>
      <View style={styles.content}>
        <Text>Main content area</Text>
      </View>
    </AppSafeAreaView>
  );
}

// Custom padding that combines with safe area insets
export function SettingsScreen() {
  return (
    <AppSafeAreaView
      edges={['top', 'left', 'right']}
      style={{ paddingTop: 20, paddingHorizontal: 16 }}
    >
      <Text>Custom padding is added to safe area insets</Text>
    </AppSafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, backgroundColor: '#fff' },
  fullScreen: { flex: 1 },
  header: { height: 60, backgroundColor: '#007AFF' },
  content: { flex: 1, padding: 16 },
});
```