npm package: @pelican-identity/vanilla
Description: JavaScript components for Pelican Identity authentication
Latest version: 1.0.42

# 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.6/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();
```

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

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

---

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

---

> 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.
👉 **Pelican Dashboard:** https://dash.pelicanidentity.com

---

# Authentication Response

When authentication completes successfully, Pelican returns a structured **identity result** to your application via the `onSuccess` callback.

This response contains a **deterministic user identifier** for your business, along with optional verified user data and identity verification (KYC) information depending on the authentication flow used.

---

## Success Callback

```ts
onSuccess: (result: IdentityResult) => void;
```

---

## IdentityResult

```ts
interface IdentityResult {
  /** Deterministic unique user identifier specific to your business */
  user_id: string;

  /** Authentication Assurance level */
  /** AAL1 - Passcode */
  /** AAL2 - Biometric */
  assurance_level: { level: number; type: "passcode" | "biometric" };
  /** 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;
  };
  /** Location data from the user's device */
  location?: { latitude: number; longitude: number } | null;
}
```

---

## `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).

> This identifier remains the same for the same user across future authentications within your business.

---

## Assurance Level (`assurance_level`)

Pelican will prompt users to authenticate using the required assurance level configured in the project settings when possible. Authentication may still succeed with a lower level, but the achieved assurance level is always returned in the response. Your application is responsible for enforcing access based on this level.

```ts
interface AssuranceLevel {
  level: number;
  type: "passcode" | "biometric";
}
```

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

### Email

```ts
interface IEmail {
  id: number;
  value: string;
  verifiedAt: string;
  verificationProvider: string;
}
```

### Phone

```ts
interface IPhone {
  id: number;
  country: string;
  callingCode: string;
  number: string;
  verifiedAt: string;
  verificationProvider: string;
}
```

All contact data returned by Pelican is **verified** and includes the service used for verification.

---

## 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;
  personal_number?: string;
  date_of_birth?: string | Date;
  age?: number;
  expiration_date?: string | Date;
  date_of_issue?: string | Date;
  issuing_state?: string;
  issuing_state_name?: string;
  first_name?: string;
  last_name?: string;
  full_name?: string;
  gender?: string;
  address?: string;
  formatted_address?: string;
  nationality?: string;
  liveness_percentage?: number;
  face_match_percentage?: number;
  verified_at?: string | Date;
}
```

### Verification Scores

- `liveness_percentage`: Confidence score (0–100) from face liveness detection.
- `face_match_percentage`: Confidence score (0–100) matching selfie to document photo.

---

## Document Downloads

If document access is enabled for your project (NB: your business must be verified and KYB completed), Pelican provides secure download URLs valid for 24 hours as Pelican does not store documents and only provides access to them from the Pelican vault for a limited time. You are required to download and store the documents on your backend for compliance and security reasons according to your local data protection regulations:

```ts
id_downloadurls?: {
  front_of_card?: string;
  back_of_card?: string;
};
```

These URLs are:

- Short-lived
- Access-controlled
- Intended for secure backend or compliance workflows

---

## Authentication Flow Differences

| Auth Type         | Returned Data                               |
| ----------------- | ------------------------------------------- |
| `signup`          | `user_id`, basic `user_data`                |
| `login`           | `user_id`, previously generated at signup   |
| `id-verification` | `user_id`, `id_verification`, document URLs |

Returned fields depend on:

- User consent
- Project configuration
- Regulatory requirements

---

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

---