npm package: @pelican-identity/pelican-rn-sdk
Description: React Native SDK for Pelican authentication and identity verification
Author: Pelican Identity
Latest version: 1.1.0
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# Pelican Identity React Native SDK

React Native SDK for Pelican authentication and identity verification

## Installation

### Using npm

```bash
npm install @pelican-identity/pelican-rn-sdk tweetnacl tweetnacl-util react-native-get-random-values
```

### Using yarn

```bash
yarn add @pelican-identity/pelican-rn-sdk tweetnacl tweetnacl-util react-native-get-random-values
```

### Using pnpm

```bash
pnpm add @pelican-identity/pelican-rn-sdk tweetnacl tweetnacl-util react-native-get-random-values
```

---

## Required Setup

### 1. Set your app’s bundle identifier

You must configure your bundle identifier in your app and pass it explicitly to Pelican.
**Expo (`app.json` or `app.config.js`):**

```json
{
  "expo": {
    "name": "MyApp",
    "ios": {
      "bundleIdentifier": "com.yourcompany.myapp"
    },
    "android": {
      "package": "com.yourcompany.myapp"
    }
  }
}
```

**Bare React Native:**

- **iOS:** Xcode → Target → General → Bundle Identifier
- **Android:** `android/app/build.gradle` → `applicationId`

---

### 2. Import crypto polyfill (Important)

In your app’s entry file (`App.tsx`, `index.js`, or `layout.tsx`), import this **before anything else**:

```ts
import "react-native-get-random-values"; // Must be first
```

---

### 3. Whitelist your app in Pelican Dashboard

Add your app’s bundle identifier (example: `com.yourcompany.myapp`) to your project’s whitelist in the Pelican dashboard.

Pelican validates **explicit app identity** on every authentication attempt.

---

### 4. Callback URL Configuration

The `callBackUrl` defines where the Pelican vault app redirects after authentication, this must be the same page/screen where you have initialized the SDK, if this is not provided, SDK will attempt to authenticate **ONCE** when the app is reopened.

### Expo Go (development)

```ts
callBackUrl = "exp://192.168.1.100:8081";
```

Use your **local IP** and Expo dev server port.

### Expo standalone builds

```ts
callBackUrl = "myapp://auth-callback";
```

In `app.json`:

```json
{
  "expo": {
    "scheme": "myapp"
  }
}
```

### Bare React Native

```ts
callBackUrl = "myapp://auth-callback";
```

Configure deep linking:

- **iOS:** Xcode → Info → URL Types
- **Android:** `AndroidManifest.xml` intent filter

---

## Usage

### Basic Usage

```tsx
import React from "react";
import { View } from "react-native";
import { PelicanAuth } from "@pelican-identity/pelican-rn-sdk";

export default function App() {
  return (
    <View style={{ flex: 1 }}>
      <PelicanAuth
        publicKey="your-business-public-key"
        projectId="your-project-id"
        appId="com.yourcompany.myapp"
        authType="signup"
        callBackUrl="myapp://auth-callback"
        onSuccess={(data) => {
          console.log("Authentication successful:", data);
        }}
        onError={(error) => {
          console.error("Authentication failed:", error);
        }}
      />
    </View>
  );
}
```

---

## Complete Example

```tsx
import React, { useState } from "react";
import { View, Text, StyleSheet } from "react-native";
import { PelicanAuth } from "@pelican-identity/pelican-rn-sdk";

export default function LoginScreen() {
  const [user, setUser] = useState(null);
  const [error, setError] = useState<string | null>(null);

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Login to MyApp</Text>

      <PelicanAuth
        publicKey="your-business-public-key"
        projectId="your-project-id"
        appId="com.yourcompany.myapp"
        authType="login"
        callBackUrl="myapp://auth-callback"
        onSuccess={(data) => {
          setUser(data);
          // Send user data to your backend
          setError(null);
        }}
        onError={(err) => {
          setError(err.message);
          setUser(null);
        }}
      />

      {user && <Text style={styles.success}>Authenticated successfully</Text>}

      {error && <Text style={styles.error}>{error}</Text>}
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", alignItems: "center" },
  title: { fontSize: 22, fontWeight: "bold", marginBottom: 20 },
  success: { color: "green", marginTop: 20 },
  error: { color: "red", marginTop: 20 },
});
```

---

## API Reference

### `PelicanAuth`

Main authentication component.

#### Props

| Prop              | Type                                       | Required | Description                                         |
| ----------------- | ------------------------------------------ | -------- | --------------------------------------------------- |
| `publicKey`       | `string`                                   | ✅       | Business public key from Pelican dashboard          |
| `projectId`       | `string`                                   | ✅       | Project ID from Pelican dashboard                   |
| `appId`           | `string`                                   | ✅       | App bundle identifier                               |
| `authType`        | `"signup" \| "login" \| "id-verification"` | ✅       | Authentication flow                                 |
| `onSuccess`       | `(data: IdentityResult) => void`           | ✅       | Success callback containing authenticated user data |
| `callBackUrl`     | `string`                                   | Optional | Deeplink to return to app                           |
| `onError`         | `(error) => void`                          | Optional | Error callback                                      |
| `onLoading`       | `(loading: boolean) => void`               | Optional | Loading callback, useful for loading stares         |
| `buttonComponent` | `ReactNode`                                | Optional | Custom trigger UI                                   |

> If `appId` is missing or does not match the whitelisted value, Pelican will fail immediately.

## Best practice

Fetch your Pelican configuration (public key, project ID) from your backend at runtime instead of hard-coding them into your mobile app.

---

## Troubleshooting

### “`appId` is required”

- Ensure you passed the `appId` prop
- Ensure it matches the bundle identifier configured in your app

### “App ID not whitelisted”

- Add the `appId` to your Pelican project whitelist
- Ensure there are no typos or environment mismatches

### “crypto.getRandomValues() not supported”

- Ensure `react-native-get-random-values` is imported **before anything else**

### Redirect doesn’t return to app

- Verify `callBackUrl` scheme matches your app configuration
- Confirm deep linking is correctly set up

---

## License

MIT