@getpassage/react-native/README.md

Passage React Native SDK for mobile authentication

# Passage React Native SDK

A React Native SDK for integrating Passage into your iOS and Android applications.

## Installation

```bash
npm install @getpassage/react-native react-native-webview @react-native-cookies/cookies
# or
yarn add @getpassage/react-native react-native-webview @react-native-cookies/cookies
```

### iOS Setup

```bash
cd ios && pod install
```

## Usage

### 1. Wrap your app with the Provider

```tsx
import { PassageProvider } from "@getpassage/react-native";

function App() {
  return (
    <PassageProvider
      config={{
        debug: false,
      }}
    >
      <YourAppContent />
    </PassageProvider>
  );
}
```

### 2. Use the hook in your components

```tsx
import React from "react";
import { Button, View } from "react-native";
import { usePassage } from "@getpassage/react-native";

function ConnectButton() {
  const passage = usePassage();

  const handleConnect = async () => {
    try {
      // Step 1: Initialize with your publishable key
      await passage.initialize({
        publishableKey: "your-publishable-key",
        prompts: [
          {
            identifier: "welcome",
            prompt: "Welcome to our app!",
            integrationid: "your-integration-id",
            forceRefresh: false,
          },
        ],
        onConnectionComplete: (connection) => {
          console.log("Connection established:", connection);
        },
        onConnectionError: (error) => {
          console.error("Connection error:", error);
        },
        onDataComplete: (data) => {
          console.log("Data received:", data);
        },
        onPromptComplete: (prompt) => {
          console.log("Prompt completed:", prompt);
        },
        onExit: (reason) => {
          console.log("User exited:", reason);
        },
      });

      // Step 2: Open the modal
      await passage.open({
        presentationStyle: "modal", // or "fullScreen");
      });
    } catch (error) {
      console.error("Failed to connect:", error);
    }
  };

  return (
    <View>
      <Button title="Connect with Passage" onPress={handleConnect} />
    </View>
  );
}
```

### 3. Headless Connection (Optional)

You can also connect without opening a modal:

```tsx
const handleHeadlessConnect = async () => {
  try {
    await passage.connect({
      intentToken: "your-intent-token",
      onMessage: (message) => {
        console.log("Received message:", message);
      },
      onError: (error) => {
        console.error("Connection error:", error);
      },
      onClose: () => {
        console.log("Connection closed");
      },
    });
  } catch (error) {
    console.error("Failed to connect:", error);
  }
};

const handleDisconnect = () => {
  passage.disconnect();
};
```

## API Reference

### PassageProvider

The provider component that manages the Passage state.

```tsx
interface PassageConfig {
  baseUrl?: string; // Default: varies by environment
  socketUrl?: string; // Default: varies by environment
  socketNamespace?: string; // Default: "/ws"
  debug?: boolean; // Default: false
}

<PassageProvider config={config}>{children}</PassageProvider>;
```

### usePassage

Hook that provides access to Passage functionality.

**Returns an object with these methods:**

#### `initialize(options: PassageInitializeOptions)`

Initialize Passage with your publishable key and configuration. Must be called before `open()`.

```tsx
interface PassageInitializeOptions {
  publishableKey: string;
  prompts?: PassagePrompt[];
  onConnectionComplete?: (data: PassageSuccessData) => void;
  onError?: (error: PassageErrorData) => void;
  onDataComplete?: (data: PassageDataResult) => void;
  onPromptComplete?: (prompt: PassagePromptResponse) => void;
  onExit?: (reason?: string) => void;
}
```

#### `open(options?: PassageOpenOptions)`

Open the Passage modal. Must call `initialize()` first.

```tsx
interface PassageOpenOptions {
  intentToken?: string; // Optional - uses internal token if not provided
  onConnectionComplete?: (data: PassageSuccessData) => void;
  onConnectionError?: (error: PassageErrorData) => void;
  onDataComplete?: (data: PassageDataResult) => void;
  onPromptComplete?: (prompt: PassagePromptResponse) => void;
  onExit?: (reason?: string) => void;
  presentationStyle?: "modal" | "fullScreen"; // Default: "modal"
}
```

#### `close()`

Close the Passage modal.

#### `getData()`

Get stored session data and prompts.

#### `connect(options: PassageConnectOptions)`

Connect to Passage in headless mode (no UI).

```tsx
interface PassageConnectOptions {
  intentToken: string;
  onMessage?: (message: any) => void;
  onError?: (error: PassageErrorData) => void;
  onClose?: () => void;
}
```

#### `disconnect()`

Disconnect from Passage.

### Type Definitions

```typescript
interface PassagePrompt {
  identifier: string;
  prompt: string;
  integrationid: string;
  forceRefresh: boolean;
}

interface PassageConnection {
  id: string;
  integrationId?: string;
  data?: any;
  sessionInfo?: {
    cookies: any[];
    localStorage: any[];
    sessionStorage: any[];
  };
}

interface PassageErrorData {
  error: string;
  data?: any;
}

interface PassageDataResult {
  data?: any;
  prompts?: Array<{
    prompt: string;
    results: any;
  }>;
}
```

## Features

- **TypeScript Support**: Full TypeScript support with type definitions
- **Cookie Management**: Automatic cookie handling via `@react-native-cookies/cookies`
- **Remote Control**: Built-in support for automation and remote control
- **Modal & Full Screen**: Support for both modal and full-screen presentation
- **Cross-Platform**: Works on both iOS and Android

## Requirements

- React Native >= 0.60.0
- React >= 16.8.0 (Hooks support)
- react-native-webview >= 11.0.0
- @react-native-cookies/cookies >= 6.0.0

## Support

For issues and questions, please visit our [GitHub repository](https://github.com/tailriskai/passage-react-native).

## License

MIT © Passage