@pelican-identity/vanilla 1.0.4 → 1.0.6

package/README.md

@@ -1,319 +1,210 @@
-# Pelican Identity React SDK
+# Pelican Identity Vanilla SDK
 
-React SDK for Pelican authentication and identity verification on the web.
-👉 **Pelican Dashboard:** https://dash.pelicanidentity.com
-
----
+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
 
-### Using npm
+### 1. Via CDN (Easiest)
 
-```bash
-npm install @pelican-identity/react
-```
+Ideal for projects without a build step. Includes the UI and logic in a single file.
 
-### Using yarn
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@pelican-identity/vanilla@1.0.4/dist/pelican.css"
+/>
 
-```bash
-yarn add @pelican-identity/react
-```
+<script src="https://cdn.jsdelivr.net/npm/@pelican-identity/vanilla@1.0.4/dist/index.min.js"></script>
 
-### Using pnpm
+<div id="pelican-auth-root"></div>
 
-```bash
-pnpm add @pelican-identity/react
+<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>
 ```
 
----
-
-## 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)
+### 2. Via NPM/PNPM
 
-If you are using **Next.js, Remix, or similar frameworks**, ensure the SDK is only initialized on the client.
+Ideal for modern web apps (Vue, Svelte, or Vanilla TS) using a bundler like Vite or Webpack.
 
-For Next.js App Router:
+```bash
+npm install @pelican-identity/vanilla
 
-```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);
-      }}
-    />
-  );
-}
+```typescript
+import { createPelicanAuth } from "@pelican-identity/vanilla";
+import "@pelican-identity/vanilla/dist/pelican.css";
+
+const cleanup = createPelicanAuth("container-id", {
+  publicKey: "...",
+  projectId: "...",
+  authType: "login",
+  onSuccess: (identity) => {
+    console.log(identity.user_id);
+  },
+});
+
+// To stop and cleanup the instance
+// cleanup();
 ```
 
----
+```
+<script>
+  import { onMount } from 'svelte';
+
+  onMount(() => {
+    // Pelican is available globally because of the CDN <script> tag
+    const auth = window.Pelican.createPelicanAuth('pelican-container', {
+      publicKey: "your-key",
+      projectId: "your-id",
+      authType: "login",
+      onSuccess: (data) => console.log(data)
+    });
+
+    // Cleanup when component is destroyed
+    return () => auth();
+  });
+</script>
+
+<div id="pelican-container"></div>
+```
 
-## 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>
-  );
-}
+```vue
+<template>
+  <div id="pelican-container"></div>
+</template>
+
+<script setup>
+import { onMounted } from "vue";
+
+onMounted(() => {
+  const auth = window.Pelican.createPelicanAuth("pelican-container", {
+    publicKey: "your-key",
+    projectId: "your-id",
+    authType: "login",
+    onSuccess: (data) => console.log(data),
+  });
+
+  return () => auth();
+});
+</script>
 ```
 
 ---
 
-## 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                                      |
-| `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:
+## UI Wrapper API Reference (`createPelicanAuth`)
 
-- **QR codes** (desktop → mobile)
-- **Deep links** (mobile browsers)
+The `createPelicanAuth` function initializes the Pelican UI inside a target DOM element.
 
-The SDK automatically chooses the best option based on the user’s device.
+| 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            |
 
 ---
 
-## Authentication Response
+## Low-Level Core Usage (Custom UI)
 
-When authentication completes successfully, Pelican returns a structured **identity result** to your application via the `onSuccess` callback.
+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.
 
----
+### Basic Implementation
 
-## Success Callback
+```typescript
+import { PelicanAuthentication } from "@pelican-identity/auth-core";
 
-```ts
-onSuccess: (result: IdentityResult) => void;
-```
+const pelican = new PelicanAuthentication({
+  publicKey: "your-key",
+  projectId: "your-id",
+  authType: "login",
+});
 
----
+// 1. Listen for the QR code
+pelican.on("qr", (qrDataUrl) => {
+  document.getElementById("my-qr").src = qrDataUrl;
+});
 
-## IdentityResult
-
-```ts
-interface IdentityResult {
-  /** Deterministic unique user identifier specific to your business */
-  user_id: string;
+// 2. Listen for Mobile Deep Links
+pelican.on("deeplink", (url) => {
+  document.getElementById("mobile-link").href = url;
+});
 
-  /** Basic user profile and contact information (if available) */
-  user_data?: IUserData;
+// 3. Track State Changes
+pelican.on("state", (state) => {
+  console.log("Current state:", state); // 'initializing', 'paired', etc.
+});
 
-  /** Identity document and liveness verification data */
-  id_verification: IKycData;
+// 4. Handle Completion
+pelican.on("success", (identity) => {
+  alert(`Welcome ${identity.user_id}`);
+});
 
-  /** Download URLs for verified identity documents */
-  id_downloadurls?: {
-    front_of_card?: string;
-    back_of_card?: string;
-  };
-}
+// Start the engine
+pelican.start();
 ```
 
 ---
 
-## `user_id`
+## Authentication Flow logic
 
-- 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).
+The SDK manages the transition between Desktop and Mobile automatically:
 
----
+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.
 
-## 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 Result Structure
 
----
+Regardless of which integration path you choose, the successful authentication returns this object:
 
-## 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;
+```typescript
+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;
+  };
 }
 ```
 
 ---
 
-## 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
+### `crypto.randomUUID is not a function`
 
-- Ensure the browser tab regains focus after mobile authentication
+**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`.
 
-### Unsupported authentication type
+### QR Code not showing
 
-- 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
-
----
+**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.
 
-## Security Notes
+### Styles not applying
 
-- All identity data is transmitted **encrypted**.
-- Pelican never exposes raw credentials.
-- Identifiers are scoped per business.
-- Domains are validated on every authentication request.
+**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.
 
 ---
-
-### 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