@pelican-identity/react 2.0.16 → 2.0.18

package/README.md

@@ -144,25 +144,21 @@ Main authentication component.
 | `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.
+> If `appId` is missing or does not match the whitelisted value, Pelican will fail immediately.
 
-## 👉 **Pelican Dashboard:** https://dash.pelicanidentity.com
+### Best practice
 
-## 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.
+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
+# 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
@@ -180,6 +176,10 @@ 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;
 
@@ -203,8 +203,21 @@ interface IdentityResult {
 - 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.
@@ -228,7 +241,31 @@ interface IUserData {
 }
 ```
 
-All contact data returned by Pelican is **verified**.
+### 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.
 
 ---
 
@@ -246,12 +283,50 @@ interface IKycData {
     | "driver's license"
     | "residence permit";
   document_number?: string;
-  nationality?: 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
@@ -259,7 +334,7 @@ interface IKycData {
 | Auth Type         | Returned Data                               |
 | ----------------- | ------------------------------------------- |
 | `signup`          | `user_id`, basic `user_data`                |
-| `login`           | `user_id`                                   |
+| `login`           | `user_id`, previously generated at signup   |
 | `id-verification` | `user_id`, `id_verification`, document URLs |
 
 Returned fields depend on:
@@ -270,6 +345,8 @@ Returned fields depend on:
 
 ---
 
+---
+
 ## Troubleshooting
 
 ### Blank page or no QR code

package/dist/components/PelicanAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PelicanAuth.d.ts","sourceRoot":"","sources":["../../src/components/PelicanAuth.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAElE,QAAA,MAAM,WAAW,GAAI,QAAQ,mBAAmB,4CA6hB/C,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/components/PelicanButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PelicanButton.d.ts","sourceRoot":"","sources":["../../src/components/PelicanButton.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAEvD,QAAA,MAAM,aAAa,GAAI,qBAGpB;IACD,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,4CA+EA,CAAC;AAEF,eAAe,aAAa,CAAC"}

package/dist/hooks/usePelicanAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePelicanAuth.d.ts","sourceRoot":"","sources":["../../src/hooks/usePelicanAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,6BAA6B,CAAC;AAGrC,eAAO,MAAM,cAAc,GAAI,QAAQ,mBAAmB;;;;;;;;;;CAgEzD,CAAC"}

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAElE,mBAAmB,6BAA6B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pelican-identity/react",
-  "version": "2.0.16",
+  "version": "2.0.18",
   "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 || ^19.0.0"
   },
   "dependencies": {
-    "@pelican-identity/auth-core": "1.2.14"
+    "@pelican-identity/auth-core": "1.2.16"
   },
   "devDependencies": {
     "@types/react": "^19.0.4",