npm package: @pelican-identity/auth-core
Description: Framework-agnostic authentication SDK for Pelican Identity
Latest version: 1.2.45

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.

---

# Pelican Identity Vanilla SDK

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

### 1. Via CDN (Easiest)

Ideal for projects without a build step. Includes the UI and logic in a single file.

```html
<script src="https://cdn.jsdelivr.net/npm/@pelican-identity/vanilla@1.0.2/dist/index.min.js"></script>

<div id="pelican-auth-root"></div>

<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>
```

### 2. Via NPM/PNPM

Ideal for modern web apps (Vue, Svelte, or Vanilla TS) using a bundler like Vite or Webpack.

```bash
npm install @pelican-identity/vanilla

```

```typescript
import { createPelicanAuth } from "@pelican-identity/vanilla";

const cleanup = createPelicanAuth("container-id", {
  publicKey: "...",
  projectId: "...",
  authType: "login",
  onSuccess: (identity) => {
    console.log(identity.user_id);
  },
});

// To stop and cleanup the instance
// cleanup();
```

---

## UI Wrapper API Reference (`createPelicanAuth`)

The `createPelicanAuth` function initializes the Pelican UI inside a target DOM element.

| 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            |

---

## Low-Level Core Usage (Custom UI)

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

```typescript
import { PelicanAuthentication } from "@pelican-identity/auth-core";

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;
});

// 2. Listen for Mobile Deep Links
pelican.on("deeplink", (url) => {
  document.getElementById("mobile-link").href = url;
});

// 3. Track State Changes
pelican.on("state", (state) => {
  console.log("Current state:", state); // 'initializing', 'paired', etc.
});

// 4. Handle Completion
pelican.on("success", (identity) => {
  alert(`Welcome ${identity.user_id}`);
});

// Start the engine
pelican.start();
```

---

## Authentication Flow logic

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.

---

## Identity Result Structure

Regardless of which integration path you choose, the successful authentication returns this object:

```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;
  };
}
```

---

## Troubleshooting

### `crypto.randomUUID is not a function`

**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`.

### QR Code not showing

**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.

**Would you like me to help you create a "Getting Started" guide specifically for the Pelican Dashboard setup to complement this SDK documentation?**