@pelican-identity/react 1.2.0 → 1.2.2

package/README.md

@@ -0,0 +1,320 @@
+# Pelican Identity React SDK
+
+React SDK for Pelican authentication and identity verification on the web.
+👉 **Pelican Dashboard:** https://dash.pelicanidentity.com
+
+---
+
+## Installation
+
+### Using npm
+
+```bash
+npm install @pelican-identity/react
+```
+
+### Using yarn
+
+```bash
+yarn add @pelican-identity/react
+```
+
+### Using pnpm
+
+```bash
+pnpm add @pelican-identity/react
+```
+
+---
+
+## Requirements
+
+- React **17, 18, or 19**
+- A modern browser environment
+- A Pelican project configured in the Pelican dashboard
+
+> This SDK is **browser-only** and must be used in client-side React components.
+
+---
+
+## Required Setup
+
+### 1. Whitelist your domain in Pelican Dashboard
+
+You must add your website’s domain (e.g. `example.com`, `app.example.com`, or `localhost`) to your project’s whitelist in the Pelican dashboard.
+
+Pelican validates **explicit domain ownership** on every authentication attempt.
+👉 **Pelican Dashboard:** https://dash.pelicanidentity.com
+
+---
+
+### 2. Client-side usage only (important)
+
+If you are using **Next.js, Remix, or similar frameworks**, ensure the SDK is only initialized on the client.
+
+For Next.js App Router:
+
+```tsx
+"use client";
+```
+
+---
+
+## Usage
+
+### Basic Usage
+
+```tsx
+import { PelicanAuth } from "@pelican-identity/react";
+
+export default function LoginPage() {
+  return (
+    <PelicanAuth
+      publicKey="your-business-public-key"
+      projectId="your-project-id"
+      authType="login"
+      onSuccess={(data) => {
+        console.log("Authentication successful:", data);
+      }}
+      onError={(error) => {
+        console.error("Authentication failed:", error);
+      }}
+    />
+  );
+}
+```
+
+---
+
+## Complete Example
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { PelicanAuth } from "@pelican-identity/react";
+
+export default function Login() {
+  const [user, setUser] = useState(null);
+  const [error, setError] = useState<string | null>(null);
+
+  return (
+    <div style={{ maxWidth: 400, margin: "auto" }}>
+      <h2>Login to MyApp</h2>
+
+      <PelicanAuth
+        publicKey="your-business-public-key"
+        projectId="your-project-id"
+        authType="login"
+        onSuccess={(data) => {
+          setUser(data);
+          setError(null);
+        }}
+        onError={(err) => {
+          setError(err.message);
+          setUser(null);
+        }}
+      />
+
+      {user && <p>Authenticated successfully</p>}
+      {error && <p style={{ color: "red" }}>{error}</p>}
+    </div>
+  );
+}
+```
+
+---
+
+## 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                   |
+| `authType`        | `"signup" \| "login" \| "id-verification"` | ✅       | Authentication flow                                 |
+| `onSuccess`       | `(data: IdentityResult) => void`           | ✅       | Success callback containing authenticated user data |
+| `onError`         | `(error: Error) => void`                   | Optional | Error callback                                      |
+| `onStateChange`   | `(state: AuthState) => void`               | Optional | State change callback                               |
+| `buttonComponent` | `ReactNode`                                | Optional | Custom trigger UI                                   |
+| `forceQRCode`     | `boolean`                                  | Optional | Always show QR code instead of deep link            |
+| `continuousMode`  | `boolean`                                  | Optional | Automatically restart auth after completion         |
+
+> If `publicKey` or `projectId` is invalid, Pelican will fail immediately.
+
+## 👉 **Pelican Dashboard:** https://dash.pelicanidentity.com
+
+## Authentication Flow
+
+Pelican Web authentication works using:
+
+- **QR codes** (desktop → mobile)
+- **Deep links** (mobile browsers)
+
+The SDK automatically chooses the best option based on the user’s device.
+
+---
+
+## Authentication Response
+
+When authentication completes successfully, Pelican returns a structured **identity result** to your application via the `onSuccess` callback.
+
+---
+
+## Success Callback
+
+```ts
+onSuccess: (result: IdentityResult) => void;
+```
+
+---
+
+## IdentityResult
+
+```ts
+interface IdentityResult {
+  /** Deterministic unique user identifier specific to your business */
+  user_id: string;
+
+  /** Basic user profile and contact information (if available) */
+  user_data?: IUserData;
+
+  /** Identity document and liveness verification data */
+  id_verification: IKycData;
+
+  /** Download URLs for verified identity documents */
+  id_downloadurls?: {
+    front_of_card?: string;
+    back_of_card?: string;
+  };
+}
+```
+
+---
+
+## `user_id`
+
+- A **stable, deterministic identifier** generated by Pelican.
+- Unique **per business**, not global.
+- Safe to store and use as your internal user reference.
+- Does **not** expose personally identifiable information (PII).
+
+---
+
+## User Data (`user_data`)
+
+Returned when available and permitted by the authentication flow.
+
+```ts
+interface IUserData {
+  first_name?: string;
+  last_name?: string;
+  other_names?: string;
+  email?: IEmail;
+  phone?: IPhone;
+  dob?: string | Date;
+  gender?: "male" | "female" | "other";
+  country?: string;
+  state?: string;
+  city?: string;
+  address?: string;
+  occupation?: string;
+  company?: string;
+  website?: string;
+}
+```
+
+All contact data returned by Pelican is **verified**.
+
+---
+
+## Identity Verification (`id_verification`)
+
+Returned for flows involving identity verification or KYC.
+
+```ts
+interface IKycData {
+  id: number;
+  status?: "Approved" | "Declined" | "In Review";
+  document_type?:
+    | "national id card"
+    | "passport"
+    | "driver's license"
+    | "residence permit";
+  document_number?: string;
+  nationality?: string;
+  age?: number;
+  verified_at?: string | Date;
+}
+```
+
+---
+
+## Authentication Flow Differences
+
+| Auth Type         | Returned Data                               |
+| ----------------- | ------------------------------------------- |
+| `signup`          | `user_id`, basic `user_data`                |
+| `login`           | `user_id`                                   |
+| `id-verification` | `user_id`, `id_verification`, document URLs |
+
+Returned fields depend on:
+
+- User consent
+- Project configuration
+- Regulatory requirements
+
+---
+
+## Troubleshooting
+
+### Blank page or no QR code
+
+- Ensure the SDK is running client-side
+- Confirm your domain is whitelisted
+
+### Authentication never completes
+
+- Ensure the browser tab regains focus after mobile authentication
+
+### Unsupported authentication type
+
+- Ensure `authType` is valid
+
+### Billing issues, please contact this site owner
+
+- Ensure your business wallet has sufficient balance
+- Low balance alerts can be configured in the Pelican dashboard
+  👉 **Pelican Dashboard:** https://dash.pelicanidentity.com
+
+---
+
+## Security Notes
+
+- All identity data is transmitted **encrypted**.
+- Pelican never exposes raw credentials.
+- Identifiers are scoped per business.
+- Domains are validated on every authentication request.
+
+---
+
+### Final note
+
+Pelican deliberately separates:
+
+- **Identity** (who the user is)
+- **Authentication** (this session)
+- **Verification** (confidence level)
+
+This ensures your web application remains secure, flexible, and compliant.
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pelican-identity/react",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "React components for Pelican Identity authentication",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -21,7 +21,7 @@
     "react-dom": "^17.0.0 || ^18.0.0"
   },
   "dependencies": {
-    "@pelican-identity/auth-core": "1.2.0"
+    "@pelican-identity/auth-core": "1.2.2"
   },
   "devDependencies": {
     "@types/react": "^18.2.45",