Registry / auth-security / persona

persona

JSON →
library0.0.1jsnpmunverified

The `persona` package offers the official JavaScript SDK for integrating Persona's identity verification Inquiry Flow into web applications. As of version 5.8.0, it provides a robust client library designed to embed and manage the entire inquiry process directly within the user's browser environment. Key functionalities include configuring inquiry templates, selecting runtime environments (e.g., sandbox, production), and handling critical lifecycle events through callbacks for completion, cancellation, and errors. The SDK abstracts away the complexities of direct API interaction, offering a streamlined integration experience for front-end developers. It ships with built-in TypeScript types, enhancing developer experience and type safety. Persona maintains an active development pace, regularly releasing updates and fixes, and explicitly recommends staying up-to-date. Its primary differentiation lies in being the official, fully supported client for Persona services, ensuring compatibility with the latest features and security standards.

npm install persona
INSTALL
IMPORT
SIG · PERSONA
P
persona
auth-securityjavascriptv0.0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client
import { Client } from 'persona';
const Client = require('persona');
The Client class is a named export. CommonJS users should use destructuring from require().
PersonaInquiryOptions
import type { PersonaInquiryOptions } from 'persona';
TypeScript type for the configuration object passed to the Client constructor.
ClientCallbacks
import type { ClientCallbacks } from 'persona';
TypeScript type for the various event callback functions (onComplete, onCancel, onError, onEvent).

Demonstrates how to initialize the Persona `Client` for an embedded inquiry flow, configure its environment, and set up essential event callbacks for `onReady`, `onComplete`, `onCancel`, and `onError` to manage the user journey.

import { Client } from 'persona'; // Initialize the Persona client for an embedded inquiry flow. const client = new Client({ // Replace with your actual template ID, or use the provided demo template for testing. templateId: 'itmpl_Ygs16MKTkA6obnF8C3Rb17dm', // Use 'sandbox' for development and testing, 'production' for live applications. environment: 'sandbox', // Callback executed when the Persona flow is ready to be opened. onReady: () => { console.log('Persona client is ready, opening flow...'); client.open(); }, // Callback for when the inquiry process is successfully completed. onComplete: ({ inquiryId, status, fields }) => { console.log('Inquiry completed:', { inquiryId, status, fields }); // Handle post-completion logic, e.g., notify your backend, update UI. }, // Callback for when the user cancels the inquiry flow. onCancel: ({ inquiryId, sessionToken }) => { console.log('Inquiry cancelled:', { inquiryId, sessionToken }); // Handle cancellation, e.g., log, return user to previous state. }, // Callback for any errors encountered during the inquiry process. onError: (error) => { console.error('Persona inquiry error:', error); // Implement robust error handling and user feedback. }, // Optional: Set allowed events for the onEvent callback (e.g., ['step-transitioned', 'click']). // eventsAllowlist: ['all'] }); console.log('Persona client initialized.');
Debug
Known issues
breakingStarting with `persona@5.0.0`, the `Inquiry` export (previously used for React integration) has been moved to a separate package, `persona-react`. Direct imports of `Inquiry` from `persona` will fail.
fix
If using React, install `persona-react` and change `import { Inquiry } from 'persona'` to `import Inquiry from 'persona-react'`.
affects: >=5.0.0
breakingThe `onComplete` callback signature was significantly changed in `persona@5.0.0`. It now uses keyword arguments `{ inquiryId, status, fields }` instead of positional arguments. The `onFail` callback was removed entirely.
fix
Update your `onComplete` callback function signature to accept destructuring `({ inquiryId, status, fields }) => { ... }` and migrate any logic from `onFail` into `onComplete` by checking the `status` parameter.
affects: >=5.0.0
breakingThe `onStart` callback was removed in `persona@5.0.0`. `onExit` and `client.exit()` were renamed to `onCancel` and `client.cancel()` respectively. The `accessToken` parameter was renamed to `sessionToken`.
fix
Replace `onStart` with the `onEvent` callback (listening for `Event.Start`), rename `onExit` to `onCancel` and `client.exit()` to `client.cancel()`, and update references of `accessToken` to `sessionToken` in callback arguments.
affects: >=5.0.0
deprecatedFeatures such as `prefill`, `lockedAttributes`, `themeId`, and the `InquiryAttributes` type export, which were deprecated in `persona@4.0.0`, have been completely removed in `persona@5.0.0`.
fix
Migrate to using the `fields` parameter for prefilling and attribute locking, and rely on template-level configuration for themes. Remove any usage of `InquiryAttributes` type.
affects: >=5.0.0
gotchaThe package `persona` provides its own TypeScript type definitions. Installing `@types/persona` is unnecessary and the `@types` package is deprecated, which can lead to type conflicts or confusion.
fix
Uninstall `@types/persona` if it is present in your project. The types are included directly with the `persona` package.
affects: All versions
Errors
Common errors & fixes
ReferenceError: Inquiry is not defined
Attempting to import `Inquiry` from 'persona' when it has been moved to 'persona-react' (since v5.0.0).
fix
If using React, install `persona-react` (`npm install persona-react`) and update your import to `import Inquiry from 'persona-react'`.
TypeError: Cannot read properties of undefined (reading 'inquiryId')
Using the old positional argument signature for the `onComplete` callback after upgrading to `persona@5.0.0` or later.
fix
Update your `onComplete` callback to use destructuring keyword arguments: `onComplete: ({ inquiryId, status, fields }) => { ... }`.
TypeError: Client is not a constructor
Incorrectly importing `Client` in a CommonJS environment or mixing CommonJS `require()` syntax with ES Modules `import` syntax.
fix
For CommonJS, use `const { Client } = require('persona');`. Ensure your build setup correctly handles ES Modules if you intend to use `import` statements.
Persona: Invalid configuration. Missing 'templateId'.
The `templateId` option is a required parameter for initializing the Persona `Client`.
fix
Ensure the `templateId` property is correctly provided in the `Client` constructor options, for example: `templateId: 'your_template_id'`.
Upgrade
Version history
0.0.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
31 hits · last 30 days
node
30
OpenAI (training)
1
Resources
persona — npm install persona · libregistry