World ID Kit

https://github.com/worldcoin/idkit-js
Admin
IDKit is a toolkit for easily interacting with the World ID Protocol, enabling developers to...
Tokens:56,983
Snippets:406
Trust Score:9.5
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Run local development servers

Source: https://github.com/worldcoin/idkit-js/blob/main/README.md

Install dependencies and start the local development servers for the examples.

```bash
pnpm i && pnpm dev
```

--------------------------------

### Setup and run development server

Source: https://github.com/worldcoin/idkit-js/blob/main/examples/with-html/README.md

Run these commands in order to set up and start the development server. First build all workspace packages, then install dependencies, and finally start the dev server.

```bash
pnpm run build # build all workspaces packages at root
```

```bash
pnpm install
```

```bash
pnpm run dev
```

--------------------------------

### Run the Expo example locally

Source: https://github.com/worldcoin/idkit-js/blob/main/examples/with-expo/README.md

Commands to install dependencies, prebuild the Expo project, and run the app on a device using a development client. The tunnel host is used for remote testing.

```bash
# Install dependencies
npm install

npx expo prebuild

# Run on device
npx expo start --dev-client --host tunnel

# Run on device
npx expo run:ios|android --device
```

--------------------------------

### Install dependencies

Source: https://github.com/worldcoin/idkit-js/blob/main/examples/with-session/README.md

Install the required project dependencies using npm, yarn, or pnpm.

```bash
npm install
# or
yarn install
# or
pnpm install
```

--------------------------------

### Example usage of IDKit.open()

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-standalone.md

Example of adding a click event listener that logs the initialization state and opens the widget.

```typescript
document.getElementById('open-idkit').addEventListener('click', async () => {
	console.log(IDKit.isInitialized)
	await IDKit.open()
})
```

--------------------------------

### Install @worldcoin/idkit

Source: https://github.com/worldcoin/idkit-js/blob/main/README.md

Install the IDKit package for React using your preferred package manager.

```bash
yarn add @worldcoin/idkit
# or
npm i @worldcoin/idkit
# or
pnpm install @worldcoin/idkit
```

--------------------------------

### Install dependencies with yarn install

Source: https://github.com/worldcoin/idkit-js/blob/main/packages/react/README.md

Installs dependencies for the IDKit JS widget. Run this command in the root folder of the repository.

```bash
# be sure to run this in the root folder of the repo
yarn install
```

--------------------------------

### IDKitSession.create usage example

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-standalone.md

Example of creating a session with app_id, action, and signal. The config parameter is required and must be a full IDKitConfig.

```ts
await IDKitSession.create({
	app_id: 'app_staging_12345',
	action: 'login',
	signal: 'user_123',
})
```

--------------------------------

### Install IDKit Standalone

Source: https://github.com/worldcoin/idkit-js/blob/main/packages/standalone/README.md

Install the IDKit Standalone package for vanilla HTML/JavaScript applications.

```bash
npm install @worldcoin/idkit-standalone
```

--------------------------------

### QRCode component usage example

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-react-internal.md

Shows how to import and use the QRCode component with a data string and custom size.

```tsx
import QRCode from '@worldcoin/idkit/internal'

<QRCode data={sessionURI} size={256} />
```

--------------------------------

### Run the development server with npm, yarn, pnpm, or bun

Source: https://github.com/worldcoin/idkit-js/blob/main/examples/with-next/README.md

Start the Next.js development server using any of the listed package managers. The first command shown is `npm run dev`, with alternatives for yarn, pnpm, and bun.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Install @worldcoin/idkit-react-native

Source: https://github.com/worldcoin/idkit-js/blob/main/README.md

Install the IDKit React Native package using your preferred package manager.

```bash
yarn add @worldcoin/idkit-react-native
# or
npm i @worldcoin/idkit-react-native
# or
pnpm install @worldcoin/idkit-react-native
```

--------------------------------

### Install react-native-quick-crypto polyfill

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-react-native.md

Mandatory prerequisite polyfill for the encrypted bridge channel. Install and call `install` from `react-native-quick-crypto` before using the package.

```typescript
// polyfills.ts
import { install } from 'react-native-quick-crypto'
install()
```

--------------------------------

### Run local test project with yarn dev

Source: https://github.com/worldcoin/idkit-js/blob/main/packages/react/README.md

Starts the local test project. Run from the /idkit folder, then open http://localhost:3000 in the browser.

```bash
# runs in the /idkit folder
yarn dev
```

--------------------------------

### useWorldBridgeStore - createClient and getState

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-core.md

Example of creating a World ID verification session using useWorldBridgeStore's createClient method and accessing the connectorURI.

```APIDOC
## useWorldBridgeStore

### Description
The `useWorldBridgeStore` is a zustand store hook that provides state management for World ID bridge operations. It can be used as a React hook or accessed directly in plain JavaScript via `getState` and `setState`.

### Usage

```ts
// Basic: create a session (plain JS context)
const store = useWorldBridgeStore
await store.getState().createClient({
	app_id: 'app_staging_12345',
	action: 'login',
	signal: 'user_123',
})

console.log(store.getState().connectorURI) // "https://world.org/verify?t=wld&i=...&k=..."
```

### Methods

#### `createClient(config)`
- **Parameters**: `config` (object) - Required - Configuration for the verification session. Must include `app_id` (string) and `action` (string). Optional `signal` (string).
- **Returns**: `Promise<void>` - Resolves when the client is created.

#### `pollForUpdates()`
- **Parameters**: None
- **Returns**: `Promise<void>` - Resolves after polling for updates to the verification state.

### State

- **`connectorURI`** (string) - The URI used to connect to the World ID verification service.
- **`verificationState`** (enum `VerificationState`) - The current state of the verification process. Values include `Confirmed`, `Failed`, and others.
- **`result`** (object) - The proof result when verification is confirmed.
- **`errorCode`** (string) - The error code if verification fails.
```

--------------------------------

### Localization API usage example

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-react.md

Example usage of the localization API. Imports setLocalizationConfig, getCurrentLanguage, and getSupportedLanguages from '@worldcoin/idkit'. Sets the language to 'es', then getCurrentLanguage returns 'es' and getSupportedLanguages returns ['en', 'es', 'th'].

```ts
import { setLocalizationConfig, getCurrentLanguage, getSupportedLanguages } from '@worldcoin/idkit'

setLocalizationConfig({ language: 'es' })
getCurrentLanguage() // 'es'
getSupportedLanguages() // ['en', 'es', 'th']
```

--------------------------------

### __ translation function usage examples

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-react-internal.md

Shows how to import and use the __ function for simple strings and strings with placeholders.

```ts
import { __ } from '@worldcoin/idkit/internal'

__('All set!') // translated for current language
// placeholder form used by the widget:
__('Invalid IDKitStage :stage.', { stage: 'ERROR' })
```

--------------------------------

### Install crypto polyfills for React Native

Source: https://github.com/worldcoin/idkit-js/blob/main/README.md

Install polyfills for crypto functionality required by React Native.

```javascript
// polyfills.ts
import { install } from 'react-native-quick-crypto'

install()
```

--------------------------------

### Usage example for verification_level_to_credential_types

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-core.md

Example usage of `verification_level_to_credential_types` with `VerificationLevel.SecureDocument`, returning `['secure_document', 'orb']`.

```ts
import { VerificationLevel, verification_level_to_credential_types } from '@worldcoin/idkit-core'

verification_level_to_credential_types(VerificationLevel.SecureDocument)
// => ['secure_document', 'orb']
```

--------------------------------

### Set up deep linking with return_to parameter

Source: https://github.com/worldcoin/idkit-js/blob/main/packages/react-native/README.md

Deep linking setup for mobile verification. Uses expo-linking to create a return URL, adds it as a return_to parameter to the connector URL, and opens the URL with Linking.openURL.

```typescript
// In your component
import { createURL } from 'expo-linking' // For Expo projects

const handleVerify = async () => {
	// Create session
	const session = await new Session().create(appId, action)

	// Set up return URL
	const returnTo = createURL('') // Replace with your deep link path

	// Add return_to parameter to connector URL
	if (session.sessionURI) {
		const connectorUrl = new URL(session.sessionURI)
		connectorUrl.searchParams.set('return_to', returnTo)

		// Open the URL
		Linking.openURL(connectorUrl.toString())
	}
}
```

--------------------------------

### Session Management with IDKit Standalone

Source: https://github.com/worldcoin/idkit-js/blob/main/examples/with-html/session-example.html

Complete JavaScript example for managing World ID sessions using the IDKit standalone library. It includes creating a session with app_id, action, signal, action_description, verification_level, and partner flags; polling for status; automatic polling with a 5-second interval; stopping polling; and destroying the session. The code also generates a QR code for the session URI using the 'qrcode' library and updates the UI accordingly.

```javascript
import QRCode from 'qrcode'
import '@worldcoin/idkit-standalone'

// UI Elements
const createBtn = document.getElementById('create-session')
const pollBtn = document.getElementById('poll-session')
const startPollingBtn = document.getElementById('start-polling')
const stopPollingBtn = document.getElementById('stop-polling')
const destroyBtn = document.getElementById('destroy-session')
const statusDisplay = document.getElementById('status-display')
const qrDisplay = document.getElementById('qr-display')
const consoleOutput = document.getElementById('console-output')

let pollingInterval = null

// Utility functions
const log = message => {
  const timestamp = new Date().toLocaleTimeString()
  consoleOutput.textContent += `[${timestamp}] ${message}\n`
  console.log(message)
}

const formatStatus = status => {
  if (!status) return 'No session created'

  // Create a copy and format long fields for better readability
  const formatted = { ...status }
  if (formatted.result?.proof) {
    // Truncate very long proof fields for display
    formatted.result = {
      ...formatted.result,
      proof: formatted.result.proof.length > 100 ? formatted.result.proof.substring(0, 100) + '...(truncated)' : formatted.result.proof,
    }
  }
  return JSON.stringify(formatted, null, 2)
}

const generateQRCode = async sessionURI => {
  try {
    // Create canvas element for QR code
    const canvas = document.createElement('canvas')
    canvas.id = 'qr-canvas'

    // Generate QR code on canvas
    await QRCode.toCanvas(canvas, sessionURI, {
      width: 256,
      margin: 2,
      color: {
        dark: '#000000',
        light: '#FFFFFF',
      },
      errorCorrectionLevel: 'M',
    })
    return canvas
  } catch (error) {
    log(`Error generating QR code: ${error.message}`)
    return null
  }
}

const updateUI = async (status = null) => {
  const hasSession = IDKitSession.isActive

  // Update button states
  createBtn.disabled = hasSession
  pollBtn.disabled = !hasSession
  startPollingBtn.disabled = !hasSession || pollingInterval !== null
  stopPollingBtn.disabled = !hasSession || pollingInterval === null
  destroyBtn.disabled = !hasSession

  // Update status display
  if (status) {
    statusDisplay.textContent = formatStatus(status)
    statusDisplay.className = 'status-box'
    if (status.result) {
      statusDisplay.className += ' success'
    } else if (status.errorCode) {
      statusDisplay.className += ' error'
    }

    // Update QR display
    if (status.sessionURI) {
      // Clear previous content
      qrDisplay.innerHTML = ''

      // Create QR code
      const canvas = await generateQRCode(status.sessionURI)
      if (canvas) {
        // Add header
        const header = document.createElement('p')
        header.innerHTML = '<strong>Scan with World App:</strong>'
        qrDisplay.appendChild(header)

        // Add QR code canvas
        qrDisplay.appendChild(canvas)

        // Add info text
        const info = document.createElement('div')
        info.className = 'qr-info'
        info.innerHTML = `
          <p>Session URI: ${status.sessionURI.substring(0, 50)}...</p>
        `
        qrDisplay.appendChild(info)
      } else {
        // Fallback to text display if QR generation fails
        qrDisplay.innerHTML = `
          <div>
            <p><strong>QR Code generation failed</strong></p>
            <p style="word-break: break-all; font-size: 10px; margin: 10px 0;">${status.sessionURI}</p>
          </div>
        `
      }
    } else {
      qrDisplay.textContent = 'No session URI available'
    }
  } else {
    statusDisplay.textContent = formatStatus(null)
    statusDisplay.className = 'status-box'
    qrDisplay.textContent = 'Session URI will appear here when created'
  }
}

// Event Handlers
createBtn.addEventListener('click', async () => {
  try {
    log('Creating new session...')
    await IDKitSession.create({
      app_id: 'app_ce4cb73cb75fc3b73b71ffb4de178410',
      action: 'test-action',
      signal: 'test_signal_' + Date.now(),
      action_description: 'Test session-based verification',
      verification_level: 'orb',
      partner: true,
    })
    log('Session created successfully!')
    await updateUI()
  } catch (error) {
    log(`Error creating session: ${error.message}`)
  }
})

pollBtn.addEventListener('click', async () => {
  try {
    log('Polling for updates...')
    const status = await IDKitSession.pollStatus()
    log(`Poll result: ${status.state}`)
    await updateUI(status)
  } catch (error) {
    log(`Error polling: ${error.message}`)
  }
})

startPollingBtn.addEventListener('click', async () => {
  log('Starting automatic polling...')
  pollingInterval = setInterval(async () => {
    try {
      // Check if session is still active before polling
      if (!IDKitSession.isActive) {
        log('Session no longer active. Stopping auto-polling.')
        clearInterval(pollingInterval)
        pollingInterval = null
        // Don't clear UI - preserve last status
        return
      }

      const status = await IDKitSession.pollStatus()

      // Stop polling if verification is complete
      if (status.state === 'confirmed' || status.state === 'failed') {
        log(`Verification ${status.state.toLowerCase()}.`,
          language: 'javascript',
          code: "import QRCode from 'qrcode'\nimport '@worldcoin/idkit-standalone'\n\n// UI Elements\nconst createBtn = document.getElementById('create-session')\nconst pollBtn = document.getElementById('poll-session')\nconst startPollingBtn = document.getElementById('start-polling')\nconst stopPollingBtn = document.getElementById('stop-polling')\nconst destroyBtn = document.getElementById('destroy-session')\nconst statusDisplay = document.getElementById('status-display')\nconst qrDisplay = document.getElementById('qr-display')\nconst consoleOutput = document.getElementById('console-output')\n\nlet pollingInterval = null\n\n// Utility functions\nconst log = message => {\n  const timestamp = new Date().toLocaleTimeString()\n  consoleOutput.textContent += `[${timestamp}] ${message}\\n`\n  console.log(message)\n}\n\nconst formatStatus = status => {\n  if (!status) return 'No session created'\n\n  // Create a copy and format long fields for better readability\n  const formatted = { ...status }\n  if (formatted.result?.proof) {\n    // Truncate very long proof fields for display\n    formatted.result = {\n      ...formatted.result,\n      proof: formatted.result.proof.length > 100 ? formatted.result.proof.substring(0, 100) + '...(truncated)' : formatted.result.proof,\n    }\n  }\n  return JSON.stringify(formatted, null, 2)\n}\n\nconst generateQRCode = async sessionURI => {\n  try {\n    // Create canvas element for QR code\n    const canvas = document.createElement('canvas')\n    canvas.id = 'qr-canvas'\n\n    // Generate QR code on canvas\n    await QRCode.toCanvas(canvas, sessionURI, {\n      width: 256,\\n      margin: 2,\\n      color: {\n        dark: '#000000',\n        light: '#FFFFFF',\n      },\\n      errorCorrectionLevel: 'M',\n    })\n    return canvas\n  } catch (error) {\n    log(`Error generating QR code: ${error.message}`)\n    return null\n  }\n}\n\nconst updateUI = async (status = null) => {\n  const hasSession = IDKitSession.isActive\n\n  // Update button states\n  createBtn.disabled = hasSession\n  pollBtn.disabled = !hasSession\n  startPollingBtn.disabled = !hasSession || pollingInterval !== null\n  stopPollingBtn.disabled = !hasSession || pollingInterval === null\n  destroyBtn.disabled = !hasSession\n\n  // Update status display\n  if (status) {\n    statusDisplay.textContent = formatStatus(status)\n    statusDisplay.className = 'status-box'\n    if (status.result) {\n      statusDisplay.className += ' success'\n    } else if (status.errorCode) {\n      statusDisplay.className += ' error'\n    }\n\n    // Update QR display\n    if (status.sessionURI) {\n      // Clear previous content\n      qrDisplay.innerHTML = ''\n\n      // Create QR code\n      const canvas = await generateQRCode(status.sessionURI)\n      if (canvas) {\n        // Add header\n        const header = document.createElement('p')\n        header.innerHTML = '<strong>Scan with World App:</strong>'\n        qrDisplay.appendChild(header)\n\n        // Add QR code canvas\n        qrDisplay.appendChild(canvas)\n\n        // Add info text\n        const info = document.createElement('div')\n        info.className = 'qr-info'\n        info.innerHTML = `\n          <p>Session URI: ${status.sessionURI.substring(0, 50)}...</p>\n        `\n        qrDisplay.appendChild(info)\n      } else {\n        // Fallback to text display if QR generation fails\n        qrDisplay.innerHTML = `\n          <div>\n            <p><strong>QR Code generation failed</strong></p>\n            <p style="word-break: break-all; font-size: 10px; margin: 10px 0;">${status.sessionURI}</p>\n          </div>\n        `\n      }\n    } else {\n      qrDisplay.textContent = 'No session URI available'\n    }\n  } else {\n    statusDisplay.textContent = formatStatus(null)\n    statusDisplay.className = 'status-box'\n    qrDisplay.textContent = 'Session URI will appear here when created'\n  }\n}\n\n// Event Handlers\ncreateBtn.addEventListener('click', async () => {\n  try {\n    log('Creating new session...')\n    await IDKitSession.create({\n      app_id: 'app_ce4cb73cb75fc3b73b71ffb4de178410',\n      action: 'test-action',\n      signal: 'test_signal_' + Date.now(),\n      action_description: 'Test session-based verification',\n      verification_level: 'orb',\n      partner: true,\n    })\n    log('Session created successfully!')\n    await updateUI()\n  } catch (error) {\n    log(`Error creating session: ${error.message}`)\n  }\n})\n\npollBtn.addEventListener('click', async () => {\n  try {\n    log('Polling for updates...')\n    const status = await IDKitSession.pollStatus()\n    log(`Poll result: ${status.state}`)\n    await updateUI(status)\n  } catch (error) {\n    log(`Error polling: ${error.message}`)\n  }\n})\n\nstartPollingBtn.addEventListener('click', async () => {\n  log('Starting automatic polling...')\n  pollingInterval = setInterval(async () => {\n    try {\n      // Check if session is still active before polling\n      if (!IDKitSession.isActive) {\n        log('Session no longer active. Stopping auto-polling.')\n        clearInterval(pollingInterval)\n        pollingInterval = null\n        // Don't clear UI - preserve last status\n        return\n      }\n\n      const status = await IDKitSession.pollStatus()\n\n      // Stop polling if verification is complete\n      if (status.state === 'confirmed' || status.state === 'failed') {\n        log(`Verification ${status.state.toLowerCase()}.`,\n        // ... (rest of the code is truncated in the source)\n      }\n    } catch (error) {\n      log(`Error polling: ${error.message}`)\n    }\n  }, 5000)\n})\n\nstopPollingBtn.addEventListener('click', () => {\n  log('Stopping automatic polling...')\n  if (pollingInterval) {\n    clearInterval(pollingInterval)\n    pollingInterval = null\n  }\n})\n\ndestroyBtn.addEventListener('click', async () => {\n  try {\n    log('Destroying session...')\n    await IDKitSession.destroy()\n    log('Session destroyed successfully!')\n    await updateUI()\n  } catch (error) {\n    log(`Error destroying session: ${error.message}`)\n  }\n})\n
```

--------------------------------

### useWorldBridgeStore - Polling for updates

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-core.md

Example of polling for verification updates and handling success or failure via the store state.

```APIDOC
## useWorldBridgeStore - Polling Example

### Description
This example demonstrates how to poll for verification updates using `pollForUpdates` and handle the terminal states (confirmed or failed) based on the `verificationState`.

### Code Example

```ts
// Poll, and handle failure via the state
import { useWorldBridgeStore, VerificationState } from '@worldcoin/idkit-core'

const store = useWorldBridgeStore
await store.getState().createClient({ app_id: 'app_staging_12345', action: 'login' })

// poll until terminal
while (true) {
	await store.getState().pollForUpdates()
	const state = store.getState()

	if (state.verificationState === VerificationState.Confirmed) {
		console.log('proof:', state.result)
		break
	}
	if (state.verificationState === VerificationState.Failed) {
		console.error('failed:', state.errorCode)
		break
	}
	await new Promise(r => setTimeout(r, 3000))
}
```
```

--------------------------------

### Using hashToField

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-core-hashing.md

Example usage of hashToField. Shows hashing a plain string and a hex-like string, and accessing the digest and hash properties of the result.

```ts
import { hashToField } from '@worldcoin/idkit-core/hashing'

const out = hashToField('hello world')
console.log(out.digest) // 0x...
console.log(out.hash) // bigint

// hex-like strings are hashed as raw bytes
const addr = hashToField('0x0000000000000000000000000000000000000000')
```

--------------------------------

### Using useIDKit to control the widget modal

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-react.md

Example of using the useIDKit hook to control the IDKit widget modal. It imports IDKitWidget and useIDKit, calls useIDKit with an onSuccess callback that logs the proof, and renders a button that opens the modal via setOpen(true). The IDKitWidget is rendered with an empty child function, as the hook drives the modal without rendering children.

```tsx
import { IDKitWidget, useIDKit } from '@worldcoin/idkit'

const { open, setOpen } = useIDKit({ onSuccess: proof => console.log(proof) })

<button onClick={() => setOpen(true)}>Verify</button>
<IDKitWidget app_id="app_staging_123456" action="login">
	{() => <></>}
</IDKitWidget>
```

--------------------------------

### Add crypto polyfill to entry file

Source: https://github.com/worldcoin/idkit-js/blob/main/packages/react-native/README.md

Troubleshooting snippet for crypto not available errors. Add this to your entry file to install the react-native-quick-crypto polyfill. For Expo projects, prebuild is required.

```javascript
// Add to your entry file
import { install } from 'react-native-quick-crypto'

install()
```

--------------------------------

### IDKit.init and IDKitSession.create

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/configuration.md

Documentation for the standalone global state initialization and session creation methods.

```APIDOC
## IDKit.init(config)

### Description
Initializes the IDKit library with the provided configuration.

### Parameters
- **config** (Config) - Required - Configuration object.

### Response
- Returns initialization status.

## IDKitSession.create(config)

### Description
Creates a new IDKit session with the provided configuration.

### Parameters
- **config** (IDKitConfig) - Required - Configuration object.

### Response
- Returns a session object.
```

--------------------------------

### Session.create() with options

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-react-native.md

Shows create() with non-trivial options: signal, verification_level, action_description, and partner.

```ts
// Non-trivial options
const session = await new Session().create('app_staging_12345', 'login', {
	signal: 'user-42',
	verification_level: VerificationLevel.SecureDocument,
	action_description: 'Verify your World ID to log in',
	partner: true,
})
```

--------------------------------

### solidityEncode function, usage, and error handling

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-core-hashing.md

The function definition, a usage example, and an error-handling example for solidityEncode. It validates that the types and values arrays have the same length, throwing an error otherwise. The usage example shows building a signal for IDKitConfig/IDKitWidget, and the error example demonstrates catching the thrown error.

```ts
export const solidityEncode = (types: string[], values: unknown[]): AbiEncodedValue => {
	if (types.length !== values.length) {
		throw new Error('Types and values arrays must have the same length.')
	}

	return { types, values } as AbiEncodedValue
}
```

```ts
import { solidityEncode } from '@worldcoin/idkit-core/hashing'

const signal = solidityEncode(['address'], ['0x0000000000000000000000000000000000000000'])

// then pass `signal` into IDKitConfig / IDKitWidget
```

```ts
// Error handling
import { solidityEncode } from '@worldcoin/idkit-core/hashing'

try {
	solidityEncode(['address'], []) // lengths differ
} catch (e) {
	console.error(e.message) // "Types and values arrays must have the same length."
}
```

--------------------------------

### Using useIDKitStore with ConfigSource.MANUAL

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-react-internal.md

Demonstrates how to use the useIDKitStore singleton to add a success callback and open the modal. The callback logs the proof's nullifier hash when verification succeeds.

```typescript
import { useIDKitStore, ConfigSource } from '@worldcoin/idkit/internal'

useIDKitStore.getState().addSuccessCallback(proof => {
	console.log('proof verified', proof.nullifier_hash)
}, ConfigSource.MANUAL)

useIDKitStore.setState({ open: true })
```

--------------------------------

### IDKitSession.pollStatus usage example

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-standalone.md

Example of polling the session status and logging the result if the verification state is Confirmed.

```ts
const status = await IDKitSession.pollStatus()
if (status.state === VerificationState.Confirmed) console.log(status.result)
```

--------------------------------

### Import and instantiate Session

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-react-native.md

Shows how to import and instantiate a new Session object.

```ts
import { Session } from '@worldcoin/idkit-react-native'
const session = new Session()
```

--------------------------------

### Create a session with useWorldBridgeStore

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-core.md

Shows how to create a session in a plain JavaScript context using the store's getState().createClient() method. The connectorURI is logged after creation.

```ts
// Basic: create a session (plain JS context)
const store = useWorldBridgeStore
await store.getState().createClient({
	app_id: 'app_staging_12345',
	action: 'login',
	signal: 'user_123',
})

console.log(store.getState().connectorURI) // "https://world.org/verify?t=wld&i=...&k=..."
```

--------------------------------

### IDKit.init(config)

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-standalone.md

Initializes the IDKit widget with the provided configuration. Must be called once per page before open(). Throws if already initialized.

```APIDOC
## IDKit.init(config)

### Description
Initializes the IDKit widget with the provided configuration. Must be called once per page before open(). Throws if already initialized.

### Method
init

### Parameters
#### config (Config) - Required
Same shape as IDKitWidget props minus widget-only keys. Runtime errors are caught and logged via console.error.

### Throws
- Error('IDKit is already initialized') when called a second time.

### Returns
void

### Example
```ts
IDKit.init({ app_id: 'app_123', action: 'login' })
```
```

--------------------------------

### Build production bundle with yarn build

Source: https://github.com/worldcoin/idkit-js/blob/main/packages/react/README.md

Builds the production bundle. Run from the /idkit folder.

```bash
# runs in the /idkit folder
yarn build
```

--------------------------------

### useSession hook usage example

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-react.md

Example usage of the useSession hook in a React component. It renders a QR code when waiting for connection, displays the proof on confirmation, shows the error code on failure, and a preparing message otherwise.

```tsx
import { useSession, VerificationState } from '@worldcoin/idkit'
import { QRCodeSVG } from 'qrcode.react'

const { status, sessionURI, result, errorCode } = useSession({
	app_id: 'app_staging_12345',
	action: process.env.NEXT_PUBLIC_ACTION || 'test-action',
	signal: 'test_signal',
})

if (status === VerificationState.WaitingForConnection) {
	return <QRCodeSVG value={sessionURI} size={256} />
}
if (status === VerificationState.Confirmed) {
	return <p>proof: {result.proof}</p>
}
if (status === VerificationState.Failed) {
	return <p>error: {errorCode}</p>
}
return <p>Preparing…</p>
```

--------------------------------

### Session.create()

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/configuration.md

Documentation for the Session.create() method options.

```APIDOC
## Session.create() options

### Description
Creates a new IDKit session with the provided configuration options.

### Method
create

### Endpoint
Session.create(app_id, action, options?)

### Parameters
#### Path Parameters
- **app_id** (IDKitConfig['app_id']) - Required - The application ID.
- **action** (IDKitConfig['action']) - Required - The action to perform.

#### Request Body
- **signal** (IDKitConfig['signal']) - Optional - Signal for the session.
- **bridge_url** (IDKitConfig['bridge_url']) - Optional - Bridge URL.
- **verification_level** (IDKitConfig['verification_level']) - Optional - Verification level.
- **action_description** (IDKitConfig['action_description']) - Optional - Description of the action.
- **partner** (IDKitConfig['partner']) - Optional - Partner identifier.

### Response
#### Success Response
- Returns a session object.

### Notes
Defaults are identical to IDKitConfig.
```

--------------------------------

### packAndEncode function and usage

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-core-hashing.md

The function definition and a usage example for packAndEncode. It takes an array of [type, value] pairs, packs them using AbiParameters.encodePacked, and returns the hash. The example imports from '@worldcoin/idkit-core/hashing' and demonstrates encoding an address and a uint256.

```ts
export function packAndEncode(input: [string, unknown][]): HashFunctionOutput {
	const [types, values] = input.reduce<[string[], unknown[]]>(
		([types, values], [type, value]) => {
			types.push(type)
			values.push(value)
			return [types, values]
		},
		[[], []]
	)

	return hashEncodedBytes(AbiParameters.encodePacked(types, values))
}
```

```ts
import { packAndEncode } from '@worldcoin/idkit-core/hashing'

const packed = packAndEncode([
	['address', '0x0000000000000000000000000000000000000000'],
	['uint256', 12345],
])
```

--------------------------------

### Initialize IDKit Standalone in HTML

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-standalone.md

Use this snippet to set up IDKit standalone in an HTML page. It imports the library, initializes it with a signal, app ID, action, and verification level, and attaches a click handler to open the modal. The handleVerify callback should throw an error to show the error screen, and onSuccess logs the response.

```html
<script type="module">
	import '@worldcoin/idkit-standalone'
	IDKit.init({
		signal: 'test_signal',
		app_id: 'app_ce4cb73cb75fc3b73b71ffb4de178410',
		action: 'test-action',
		action_description: 'Test action description',
		show_modal: true,
		container_id: 'idkit-container',
		partner: true,
		verification_level: 'orb',
		disable_default_modal_behavior: true,
		handleVerify: response => {
			// verify the IDKit proof; throw an error to show the error screen
		},
		onSuccess: response => {
			console.log(response)
		},
	})

	document.getElementById('open-idkit').addEventListener('click', async () => {
		console.log(IDKit.isInitialized)
		await IDKit.open()
	})
</script>
```

--------------------------------

### GET /response: BridgeResponse and BridgeResult type unions

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/endpoints.md

The GET /response/{request_id} response is parsed into the BridgeResponse union; status is 'retrieved', 'initialized', or 'completed'. The decrypted payload is the BridgeResult union, which can be a success result, a legacy credential_type variant, or an error code.

```ts
type BridgeResponse =
	| {
			status: ResponseStatus.Retrieved | ResponseStatus.Initialized
			response: null
	  }
	| {
			status: ResponseStatus.Completed
			response: { iv: string; payload: string }
	  }
```

```ts
type BridgeResult =
	| ISuccessResult
	| (Omit<ISuccessResult, 'verification_level'> & { credential_type: CredentialType })
	| { error_code: AppErrorCodes }
```

--------------------------------

### getLocalizationConfig: Get current localization config

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-react.md

Returns the current LocalizationConfig. The initial value is an empty object {}.

```ts
export const getLocalizationConfig = (): LocalizationConfig => currentConfig
```

--------------------------------

### Using createWorldBridgeStore with polling

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-core.md

Shows how to create a private store instance and use it to create a client and poll for updates. The polling loop checks the verification state and logs the result or error code.

```ts
import { createWorldBridgeStore, VerificationState } from '@worldcoin/idkit-core'

const session = createWorldBridgeStore()

await session.getState().createClient({ app_id: 'app_staging_12345', action: 'my_action' })

const polling = async () => {
	await session.getState().pollForUpdates()
	const state = session.getState()

	if (state.verificationState === VerificationState.Confirmed) {
		console.log('Verified:', state.result)
	} else if (state.verificationState === VerificationState.Failed) {
		console.log('Failed:', state.errorCode)
	}
}

polling()
```

--------------------------------

### Basic Session.create() call

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-react-native.md

Basic usage of create() with an app_id and action.

```ts
const session = await new Session().create('app_id', 'your-action')
```

--------------------------------

### Localization Configuration Functions

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-react-internal.md

Functions to set and get localization configuration, current language, and supported languages for the IDKit widget.

```APIDOC
## Localization Configuration Functions

### Description
Functions to set and get localization configuration, current language, and supported languages for the IDKit widget.

### Functions
- **setLocalizationConfig** - Sets the localization configuration.
- **getLocalizationConfig** - Gets the current localization configuration.
- **getCurrentLanguage** - Gets the current language.
- **getSupportedLanguages** - Gets the list of supported languages.

### Usage
```ts
import { setLocalizationConfig, getLocalizationConfig, getCurrentLanguage, getSupportedLanguages } from '@worldcoin/idkit/internal'

setLocalizationConfig({ /* config */ })
const config = getLocalizationConfig()
const lang = getCurrentLanguage()
const langs = getSupportedLanguages()
```
```

--------------------------------

### IDKit.init(config) implementation

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-standalone.md

Initializes the IDKit widget. Throws an error if already initialized. Waits for DOMContentLoaded if the document is not ready, creates a div, renders the widget, and sets isInitialized to true.

```typescript
const init = (config: Config): void => {
	if (isInitialized) throw new Error(__('IDKit is already initialized'))
	// waits for DOMContentLoaded if document is not ready ('complete'|'interactive'|'loaded')
	// creates a <div>, createRoot(node), renders <IDKitWidget {...config} />, sets isInitialized = true
}
```

--------------------------------

### Next.js API route using verifyCloudProof

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-core-backend.md

Example Next.js API route that verifies a proof server-side and returns the response with status 200 on success or 400 on failure.

```ts
// Next.js API route (mirrors examples/with-next/pages/api/verify.ts)
import { verifyCloudProof } from '@worldcoin/idkit-core/backend'
import { ISuccessResult } from '@worldcoin/idkit-core'

export async function POST(req: Request) {
	const { proof, app_id, action, signal } = await req.json<{
		proof: ISuccessResult
		app_id: `app_${string}`
		action: string
		signal?: string
	}>()

	const response = await verifyCloudProof(proof, app_id, action, signal)
	return Response.json(response, { status: response.success ? 200 : 400 })
}
```

--------------------------------

### Create and manage a verification session in React Native

Source: https://github.com/worldcoin/idkit-js/blob/main/README.md

Create a verification session, get the connector URI, poll for status, and clean up. Handles Confirmed and Failed states.

```typescript
import { Session, VerificationState } from '@worldcoin/idkit-react-native'

// Create a new verification session
const session = await new Session().create('app_id', 'your-action')

// Get the connector URI that redirects user to the World App
// Optional: Add a `return_to` query param that deeplinks back to the app
const connectorUrl = new URL(session.sessionURI)
connectorUrl.searchParams.set('return_to', returnTo)
const connectUrlWithReturnAddress = connectorUrl.toString()

// Poll for updates to check verification status
const checkStatus = async () => {
	const status = await session.status()

	if (status.state === VerificationState.Confirmed) {
		console.log('Verification successful:', status.result)
	} else if (status.state === VerificationState.Failed) {
		console.log('Verification failed:', status.errorCode)
	}
}

// Clean up when done
const cleanup = () => {
	session.destroy()
}
```

--------------------------------

### new Session()

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-react-native.md

Constructs a new Session instance, which initializes an isolated WorldBridgeStore for managing the verification session state.

```APIDOC
## new Session()

### Description
Creates a new Session instance. Each Session owns its own core bridge store, ensuring isolation between multiple sessions.

### Method
Constructor

### Parameters
None

### Example
```ts
import { Session } from '@worldcoin/idkit-react-native'
const session = new Session()
```
```

--------------------------------

### Session.create() options type

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/configuration.md

Defines the optional parameters for Session.create(). The first two positional arguments are app_id and action, and the remaining five IDKitConfig keys are in the options object. Defaults are identical to IDKitConfig.

```ts
options?: {
	signal?: IDKitConfig['signal']
	bridge_url?: IDKitConfig['bridge_url']
	verification_level?: IDKitConfig['verification_level']
	action_description?: IDKitConfig['action_description']
	partner?: IDKitConfig['partner']
}
```

--------------------------------

### GET {bridge_url}/response/{request_id}

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/endpoints.md

Polls the bridge server for the verification result using the request ID obtained from the creation step. Returns the current status of the verification and, when completed, the encrypted result.

```APIDOC
## GET {bridge_url}/response/{request_id}

### Description
Polls the bridge server for the verification result using the request ID obtained from the creation step. Returns the current status of the verification and, when completed, the encrypted result.

### Method
GET

### Endpoint
`{bridge_url}/response/{request_id}`

### Parameters
#### Path Parameters
- `request_id` (string) - Required - The opaque ID returned from the POST /request call.

### Response
#### Success Response (2xx)
- `status` (string) - Required - One of `'retrieved'`, `'initialized'`, or `'completed'`.
- `response` (object|null) - Present only when `status` is `'completed'`; contains `iv` and `payload` (base64 AES-GCM material).

#### Response Example
```json
{
  "status": "completed",
  "response": {
    "iv": "string",
    "payload": "string"
  }
}
```

#### Error Response
- Non-OK HTTP: sets `errorCode: AppErrorCodes.ConnectionFailed` and state to `VerificationState.Failed` (no throw).
```

--------------------------------

### useSession(config: UseSessionConfig): UseSessionResult

Source: https://github.com/worldcoin/idkit-js/blob/main/_autodocs/api-reference/idkit-react.md

A beginner-friendly hook that owns the whole verification lifecycle: creates the client when the store is in PreparingClient, polls every 3000 ms (stopping at terminal states Confirmed/Failed), and exposes the session state.

```APIDOC
## useSession(config: UseSessionConfig): UseSessionResult

### Description
A beginner-friendly hook that owns the whole verification lifecycle: creates the client when the store is in `PreparingClient`, polls every 3000 ms (stopping at terminal states `Confirmed`/`Failed`), and exposes the session state.

### Method
useSession

### Signature
```ts
export function useSession(config: UseSessionConfig): UseSessionResult
```

### Parameters
- **config** (`UseSessionConfig = IDKitConfig`) - Required - Full `IDKitConfig` (see [configuration.md](../configuration.md))

### Returns
`UseSessionResult` — `{ status: VerificationState; sessionURI: string | null; result: ISuccessResult | null; errorCode: AppErrorCodes | null; reset: () => void }`

### Return Fields
- **status** (`VerificationState`) - Current lifecycle state
- **sessionURI** (`string | null`) - Connector URI (`https://world.org/verify?...`) for QR rendering
- **result** (`ISuccessResult | null`) - Verified proof once `status === Confirmed`
- **errorCode** (`AppErrorCodes | null`) - Failure code once `status === Failed`
- **reset** (`() => void`) - Resets the underlying store to start over

### Example
```tsx
import { useSession, VerificationState } from '@worldcoin/idkit'
import { QRCodeSVG } from 'qrcode.react'

const { status, sessionURI, result, errorCode } = useSession({
	app_id: 'app_staging_12345',
	action: process.env.NEXT_PUBLIC_ACTION || 'test-action',
	signal: 'test_signal',
})

if (status === VerificationState.WaitingForConnection) {
	return <QRCodeSVG value={sessionURI} size={256} />
}
if (status === VerificationState.Confirmed) {
	return <p>proof: {result.proof}</p>
}
if (status === VerificationState.Failed) {
	return <p>error: {errorCode}</p>
}
return <p>Preparing…</p>
```
```
Tokens:
Raw