@pelican-identity/auth-core 1.2.7 → 1.2.9

package/README.md

@@ -1,570 +1,174 @@
-# Pelican Auth SDK
+This documentation provides a comprehensive guide for using the Pelican Identity Vanilla SDK. It covers three integration paths: using the pre-built UI via CDN, using the UI wrapper via NPM, and building a custom UI using the Core Engine.
 
-A modern, event-driven JavaScript/TypeScript SDK for integrating Pelican Vault authentication into your web applications.
+---
 
-## Features
+# Pelican Identity Vanilla SDK
 
-- 🎯 **Event-Driven Architecture** - Subscribe to authentication lifecycle events
-- 🔄 **Continuous Mode** - Automatic session restart for repeated authentication
-- 📱 **Multi-Platform** - Supports both QR code (desktop) and deep linking (mobile)
-- 🔐 **Secure** - End-to-end encrypted authentication using TweetNaCl
-- 🔌 **WebSocket Transport** - Real-time communication with Pelican Vault
-- 🎨 **Framework Agnostic** - Works with React, Vue, Svelte, or vanilla JS
-- 📦 **Type-Safe** - Full TypeScript support with comprehensive type definitions
+The Vanilla SDK provides a framework-agnostic way to integrate Pelican authentication. It includes a high-level UI wrapper that mirrors the React experience and a low-level Core Engine for custom implementations.
 
 ## Installation
 
-```bash
-npm @pelican-identity/sdk
-# or
-yarn add @pelican-identity/sdk
-# or
-pnpm add @pelican-identity/sdk
-```
-
-## Quick Start
-
-### Basic Usage
-
-```typescript
-import { PelicanAuth } from "@pelican-identity/sdk";
-
-// Initialize the SDK
-const auth = new PelicanAuth({
-  publicKey: "your-public-key",
-  projectId: "your-project-id",
-  authType: "login", // 'login' | 'signup' | 'id-verification'
-});
-
-// Listen for authentication success
-auth.on("success", (identity) => {
-  console.log("User authenticated:", identity);
-  // Handle successful authentication
-});
-
-// Listen for errors
-auth.on("error", (error) => {
-  console.error("Authentication failed:", error);
-});
-
-// Listen for QR code (desktop) or deep link (mobile)
-auth.on("qr", (qrDataUrl) => {
-  // Display QR code image
-  document.getElementById("qr").src = qrDataUrl;
-});
-
-auth.on("deeplink", (url) => {
-  // Redirect to Pelican Vault app
-  window.location.href = url;
-});
-
-// Start authentication
-auth.start();
-```
-
-## API Reference
-
-### Constructor
-
-```typescript
-new PelicanAuth(config: PelicanAuthConfig)
-```
-
-#### Configuration Options
+### 1. Via CDN (Easiest)
 
-| Option           | Type                                       | Required | Default | Description                          |
-| ---------------- | ------------------------------------------ | -------- | ------- | ------------------------------------ |
-| `publicKey`      | `string`                                   | ✅ Yes   | -       | Your Pelican Vault public key        |
-| `projectId`      | `string`                                   | ✅ Yes   | -       | Your project identifier              |
-| `authType`       | `'login' \| 'signup' \| 'id-verification'` | ✅ Yes   | -       | Type of authentication flow          |
-| `continuousMode` | `boolean`                                  | ❌ No    | `false` | Auto-restart after successful auth   |
-| `forceQRCode`    | `boolean`                                  | ❌ No    | `false` | Force QR code even on mobile devices |
+Ideal for projects without a build step. Includes the UI and logic in a single file.
 
-### Methods
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@pelican-identity/vanilla@1.0.2/dist/pelican.css"
+/>
 
-#### `start(): Promise<void>`
+<script src="https://cdn.jsdelivr.net/npm/@pelican-identity/vanilla@1.0.2/dist/index.min.js"></script>
 
-Initiates the authentication flow.
-
-```typescript
-await auth.start();
-```
-
-#### `stop(): void`
-
-Stops the authentication flow and cleans up resources.
-
-```typescript
-auth.stop();
-```
+<div id="pelican-auth-root"></div>
 
-#### `on<K>(event: K, callback: Listener<K>): () => void`
-
-Subscribe to authentication events. Returns an unsubscribe function.
-
-```typescript
-const unsubscribe = auth.on("success", (identity) => {
-  console.log(identity);
-});
-
-// Later: unsubscribe
-unsubscribe();
-```
-
-#### `destroy(): void`
-
-Completely destroys the SDK instance, removing all listeners and cleanup.
-
-```typescript
-auth.destroy();
+<script>
+  const auth = Pelican.createPelicanAuth("pelican-auth-root", {
+    publicKey: "your-business-public-key",
+    projectId: "your-project-id",
+    authType: "login",
+    onSuccess: (data) => console.log("Success:", data),
+    onError: (err) => console.error("Error:", err),
+  });
+</script>
 ```
 
-### Events
+### 2. Via NPM/PNPM
 
-The SDK emits the following events:
+Ideal for modern web apps (Vue, Svelte, or Vanilla TS) using a bundler like Vite or Webpack.
 
-#### `state`
-
-Emitted when the authentication state changes.
+```bash
+npm install @pelican-identity/vanilla
 
-```typescript
-auth.on("state", (state) => {
-  console.log("Current state:", state);
-});
 ```
 
-**States:**
-
-- `idle` - Initial state
-- `initializing` - Fetching relay server
-- `awaiting-pair` - Waiting for mobile device to scan
-- `paired` - Device connected
-- `authenticated` - User authenticated
-- `confirmed` - Authentication confirmed
-- `terminated` - Session ended
-- `error` - Error occurred
-
-#### `success`
-
-Emitted when authentication succeeds.
-
 ```typescript
-auth.on("success", (identity: IdentityResult) => {
-  console.log("User ID:", identity.user_id);
-  console.log("Email:", identity.user_data.email.value);
-  console.log("Phone:", identity.user_data.phone.number);
-  console.log("First Name:", identity.user_data.first_name);
+import { createPelicanAuth } from "@pelican-identity/vanilla";
+import "@pelican-identity/vanilla/dist/pelican.css";
 
-  console.log("ID Verification:", identity.id_verification);
+const cleanup = createPelicanAuth("container-id", {
+  publicKey: "...",
+  projectId: "...",
+  authType: "login",
+  onSuccess: (identity) => {
+    console.log(identity.user_id);
+  },
 });
-```
-
-**IdentityResult:**
-
-```typescript
-interface IdentityResult {
-  user_id: string;
-  user_data: IUserData;
-  id_verification: IKycData;
-  id_downloadurls?: { front_of_card?: string; back_of_card?: string };
-}
-```
-
-#### `error`
-
-Emitted when an error occurs.
 
-```typescript
-auth.on("error", (error: Error) => {
-  console.error("Error:", error.message);
-});
+// To stop and cleanup the instance
+// cleanup();
 ```
 
-#### `qr`
+---
 
-Emitted on desktop with QR code data URL.
+## UI Wrapper API Reference (`createPelicanAuth`)
 
-```typescript
-auth.on("qr", (dataUrl: string) => {
-  // Display in an <img> tag
-  document.getElementById("qr").src = dataUrl;
-});
-```
+The `createPelicanAuth` function initializes the Pelican UI inside a target DOM element.
 
-#### `deeplink`
+| Option           | Type       | Required | Description                                   |
+| ---------------- | ---------- | -------- | --------------------------------------------- |
+| `publicKey`      | `string`   | ✅       | Business public key from Pelican dashboard    |
+| `projectId`      | `string`   | ✅       | Project ID from Pelican dashboard             |
+| `authType`       | `AuthType` | ✅       | `"signup"`, `"login"`, or `"id-verification"` |
+| `onSuccess`      | `Function` | ✅       | Callback with `IdentityResult`                |
+| `onError`        | `Function` | ❌       | Callback for errors                           |
+| `onClose`        | `Function` | ❌       | Callback when the user closes the modal       |
+| `continuousMode` | `boolean`  | ❌       | Auto-restart auth after completion            |
+| `forceQRCode`    | `boolean`  | ❌       | Always show QR even on mobile                 |
+| `buttonText`     | `string`   | ❌       | Custom text for the Pelican button            |
 
-Emitted on mobile with deep link URL.
+---
 
-```typescript
-auth.on("deeplink", (url: string) => {
-  // Open Pelican Vault app
-  window.location.href = url;
-  // Or use as href in a button
-  document.getElementById("login-btn").href = url;
-});
-```
+## Low-Level Core Usage (Custom UI)
 
-## Usage Examples
+If you want to build your own UI from scratch, use the `@pelican-identity/auth-core` package directly. This provides the event-driven state machine without any HTML/CSS.
 
-### React Hook
+### Basic Implementation
 
 ```typescript
-import { useEffect, useState } from "react";
-import { PelicanAuth } from "@pelican-identity/sdk";
-
-function usePelicanAuth(config) {
-  const [state, setState] = useState("idle");
-  const [qrCode, setQrCode] = useState(null);
-  const [deepLink, setDeepLink] = useState(null);
-  const [error, setError] = useState(null);
-
-  useEffect(() => {
-    const auth = new PelicanAuth(config);
-
-    auth.on("state", setState);
-    auth.on("qr", setQrCode);
-    auth.on("deeplink", setDeepLink);
-    auth.on("error", setError);
+import { PelicanAuthentication } from "@pelican-identity/auth-core";
 
-    auth.on("success", (identity) => {
-      console.log("Authenticated:", identity);
-      config.onSuccess?.(identity);
-    });
-
-    return () => auth.destroy();
-  }, []);
-
-  return { state, qrCode, deepLink, error };
-}
-
-// Usage
-function LoginButton() {
-  const { state, qrCode, deepLink } = usePelicanAuth({
-    publicKey: "your-key",
-    projectId: "your-project",
-    authType: "login",
-    onSuccess: (identity) => {
-      // Handle login
-    },
-  });
-
-  if (qrCode) {
-    return <img src={qrCode} alt="Scan to login" />;
-  }
-
-  if (deepLink) {
-    return <a href={deepLink}>Open Pelican App</a>;
-  }
-
-  return <button onClick={() => auth.start()}>Login</button>;
-}
-```
-
-### Vue Composition API
-
-```vue
-<script setup>
-import { ref, onMounted, onUnmounted } from "vue";
-import { PelicanAuth } from "@pelican-identity/pelican-sdk";
-
-const props = defineProps(["publicKey", "projectId", "authType"]);
-const emit = defineEmits(["success", "error"]);
-
-const state = ref("idle");
-const qrCode = ref(null);
-const deepLink = ref(null);
-
-let auth;
-
-onMounted(() => {
-  auth = new PelicanAuth({
-    publicKey: props.publicKey,
-    projectId: props.projectId,
-    authType: props.authType,
-  });
-
-  auth.on("state", (s) => (state.value = s));
-  auth.on("qr", (qr) => (qrCode.value = qr));
-  auth.on("deeplink", (link) => (deepLink.value = link));
-  auth.on("success", (identity) => emit("success", identity));
-  auth.on("error", (err) => emit("error", err));
-
-  auth.start();
-});
-
-onUnmounted(() => {
-  auth?.destroy();
-});
-</script>
-
-<template>
-  <div>
-    <img v-if="qrCode" :src="qrCode" alt="QR Code" />
-    <a v-else-if="deepLink" :href="deepLink">Open App</a>
-    <p v-else>{{ state }}</p>
-  </div>
-</template>
-```
-
-### Vanilla JavaScript
-
-```javascript
-import { PelicanAuth } from "@pelican-identity/sdk";
-
-// Create container
-const container = document.getElementById("auth-container");
-
-// Initialize
-const auth = new PelicanAuth({
+const pelican = new PelicanAuthentication({
   publicKey: "your-key",
-  projectId: "your-project",
+  projectId: "your-id",
   authType: "login",
 });
 
-// Handle QR code
-auth.on("qr", (dataUrl) => {
-  container.innerHTML = `
-    <img src="${dataUrl}" alt="Scan to login" />
-    <p>Scan with Pelican Vault app</p>
-  `;
+// 1. Listen for the QR code
+pelican.on("qr", (qrDataUrl) => {
+  document.getElementById("my-qr").src = qrDataUrl;
 });
 
-// Handle deep link
-auth.on("deeplink", (url) => {
-  container.innerHTML = `
-    <a href="${url}" class="btn">Open Pelican App</a>
-  `;
+// 2. Listen for Mobile Deep Links
+pelican.on("deeplink", (url) => {
+  document.getElementById("mobile-link").href = url;
 });
 
-// Handle success
-auth.on("success", (identity) => {
-  console.log("Logged in as:", identity.user_id);
-  // Redirect or update UI
-  window.location.href = "/dashboard";
+// 3. Track State Changes
+pelican.on("state", (state) => {
+  console.log("Current state:", state); // 'initializing', 'paired', etc.
 });
 
-// Handle errors
-auth.on("error", (error) => {
-  container.innerHTML = `
-    <p class="error">${error.message}</p>
-    <button onclick="auth.start()">Retry</button>
-  `;
+// 4. Handle Completion
+pelican.on("success", (identity) => {
+  alert(`Welcome ${identity.user_id}`);
 });
 
-// Start authentication
-auth.start();
-
-// Cleanup on page unload
-window.addEventListener("beforeunload", () => {
-  auth.destroy();
-});
+// Start the engine
+pelican.start();
 ```
 
-## Advanced Features
+---
 
-### Continuous Mode
+## Authentication Flow logic
 
-Automatically restart authentication sessions after completion. Useful for kiosks or multi-user scenarios.
+The SDK manages the transition between Desktop and Mobile automatically:
 
-```typescript
-const auth = new PelicanAuth({
-  publicKey: "your-key",
-  projectId: "your-project",
-  authType: "login",
-  continuousMode: true, // Enable continuous mode
-});
+1. **Desktop:** Emits a `qr` event containing a Base64 Data URL.
+2. **Mobile:** Emits a `deeplink` event. Browsers should provide a "Open App" button using this URL.
+3. **Paired:** Once the user scans/clicks, the state moves to `paired`.
+4. **Success:** After biometric/PIN approval in the Pelican app, the `success` event fires with user data.
 
-auth.on("success", (identity) => {
-  // Process user
-  console.log("User authenticated:", identity);
-  // Session will automatically restart after ~300ms
-});
+---
 
-auth.start();
-```
-
-### Force QR Code on Mobile
+## Identity Result Structure
 
-By default, mobile devices use deep links. Force QR code display instead:
+Regardless of which integration path you choose, the successful authentication returns this object:
 
 ```typescript
-const auth = new PelicanAuth({
-  publicKey: "your-key",
-  projectId: "your-project",
-  authType: "login",
-  forceQRCode: true, // Show QR even on mobile
-});
-```
-
-### Session Recovery
-
-The SDK automatically handles session recovery when users return from the Pelican Vault app:
-
-```typescript
-// Session is automatically cached when deep link is opened
-auth.on("deeplink", (url) => {
-  // User clicks and goes to Pelican app
-  window.location.href = url;
-});
-
-// When user returns (visibility change), session is recovered automatically
-// Success event will fire if authentication completed
-auth.on("success", (identity) => {
-  console.log("Recovered session:", identity);
-});
-```
-
-### State Machine Tracking
-
-Track the complete authentication lifecycle:
-
-```typescript
-auth.on("state", (state) => {
-  switch (state) {
-    case "idle":
-      console.log("Ready to start");
-      break;
-    case "initializing":
-      console.log("Connecting to server...");
-      break;
-    case "awaiting-pair":
-      console.log("Waiting for device...");
-      break;
-    case "paired":
-      console.log("Device connected!");
-      break;
-    case "authenticated":
-      console.log("User authenticated!");
-      break;
-    case "confirmed":
-      console.log("Session confirmed");
-      break;
-    case "error":
-      console.log("Error occurred");
-      break;
-  }
-});
-```
-
-## Error Handling
-
-The SDK provides detailed error information:
-
-```typescript
-auth.on("error", (error) => {
-  console.error("Error type:", error.message);
-
-  // Common errors:
-  // - "Failed to fetch relay URL" - Server connection issue
-  // - "WebSocket connection failed" - Network issue
-  // - "Invalid authentication payload" - Data corruption
-  // - "Failed to decrypt authentication data" - Crypto error
-  // - "Authenticating device terminated the connection" - User cancelled
-  // - "Session recovery failed" - Invalid cached session
-});
+interface IdentityResult {
+  user_id: string; // Unique business-scoped identifier
+  user_data?: {
+    first_name?: string;
+    email?: { value: string; verified: boolean };
+    phone?: { number: string; verified: boolean };
+  };
+  id_verification?: {
+    status: "Approved" | "Declined";
+    document_type: string;
+  };
+}
 ```
 
-## Security Considerations
-
-1. **Public Key and Project ID**: It is recommended to use environment variables or fetch from a secure server for production.
-2. **HTTPS Required**: Always use HTTPS in production
-3. **Session Expiry**: Sessions expire after 5 minutes by default
-4. **End-to-End Encryption**: All data is encrypted using TweetNaCl (NaCl crypto)
-5. **No Password Storage**: Authentication happens entirely through the Pelican Vault app
-
-## Browser Support
-
-- Chrome/Edge 90+
-- Firefox 88+
-- Safari 14+
-- Opera 76+
-
-**Required APIs:**
-
-- WebSocket
-- Crypto API (`crypto.randomUUID()`)
-- sessionStorage
-- Visibility API
+---
 
 ## Troubleshooting
 
-### QR Code Not Displaying
-
-```typescript
-auth.on("qr", (dataUrl) => {
-  if (!dataUrl) {
-    console.error("QR code generation failed");
-  }
-});
-```
+### `crypto.randomUUID is not a function`
 
-### WebSocket Connection Issues
-
-```typescript
-// Check network connectivity
-auth.on("error", (error) => {
-  if (error.message.includes("WebSocket")) {
-    console.log("Check network connection");
-    // Retry logic
-    setTimeout(() => auth.start(), 5000);
-  }
-});
-```
-
-### Session Recovery Not Working
-
-Ensure visibility change detection is working:
-
-```typescript
-document.addEventListener("visibilitychange", () => {
-  console.log("Visibility changed:", document.visibilityState);
-});
-```
-
-## TypeScript Support
-
-Full TypeScript definitions included:
-
-```typescript
-import type {
-  IEmail,
-  IKycData,
-  IPhone,
-  IUserData,
-  IdentityResult,
-  IdCardTypes,
-} from "@pelican-identity/sdk";
-import {
-  AuthType,
-  ISocketMessage,
-  PelicanAuthConfig,
-  PelicanAuthEventMap,
-  PelicanAuthState,
-} from "@pelican-identity/sdk";
-
-const config: PelicanAuthConfig = {
-  publicKey: "your-key",
-  projectId: "your-project",
-  authType: "login",
-};
-
-const auth = new PelicanAuth(config);
-
-auth.on("success", (identity: IdentityResult) => {
-  const userId: string = identity.user_id;
-});
-```
+**Cause:** Browsers only allow the Crypto API in **Secure Contexts** (HTTPS or localhost).
+**Fix:** Ensure you are serving your site over HTTPS or using `http://localhost`.
 
-## License
+### QR Code not showing
 
-MIT
+**Cause:** The engine might be in `initializing` state or the domain isn't whitelisted.
+**Fix:** Check your Pelican Dashboard and ensure your current domain (including port if applicable) is added to the project whitelist.
 
-## Support
+### Styles not applying
 
-- Documentation: https://docs.pelicanidentity.com
-- Issues: https://github.com/pelican-identity/sdk/issues
-- Email: support@pelicanidentity.com
+**Cause:** The CSS file is missing.
+**Fix:** If using NPM, ensure you import `@pelican-identity/vanilla/dist/pelican.css`. If using the CDN `.min.js` version with `injectStyle: true`, this should be automatic.
 
-## Changelog
+---
 
-See [CHANGELOG.md](CHANGELOG.md) for release history.
+**Would you like me to help you create a "Getting Started" guide specifically for the Pelican Dashboard setup to complement this SDK documentation?**

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const BASEURL = "https://identityapi.pelicanidentity.com";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,4CAA4C,CAAC"}

package/dist/constants.js

@@ -0,0 +1,2 @@
+export const BASEURL = "https://identityapi.pelicanidentity.com";
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,yCAAyC,CAAC"}