@worldcoin/idkit-core 4.0.15 → 4.1.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-export { RpSignature, signRequest } from '@worldcoin/idkit-server';
+export { RpSignature, SignRequestParams, signRequest } from '@worldcoin/idkit-server';
 export { hashSignal } from './hashing.cjs';
 
 /**
@@ -47,6 +47,8 @@ type IDKitRequestConfig = {
     action_description?: string;
     /** URL to a third-party bridge to use when connecting to the World App. Optional. */
     bridge_url?: string;
+    /** Optional deep-link callback URL appended as `return_to` on the connector URL. */
+    return_to?: string;
     /**
      * Whether to accept legacy (v3) World ID proofs as fallback.
      *
@@ -77,6 +79,8 @@ type IDKitSessionConfig = {
     action_description?: string;
     /** URL to a third-party bridge to use when connecting to the World App. Optional. */
     bridge_url?: string;
+    /** Optional deep-link callback URL appended as `return_to` on the connector URL. */
+    return_to?: string;
     /** Optional override for the connect base URL (e.g., for staging environments) */
     override_connect_base_url?: string;
     /** Optional environment override. Defaults to "production". */
@@ -169,8 +173,8 @@ interface IDKitResultSession {
     nonce: string;
     /** Action description (only if provided in input) */
     action_description?: string;
-    /** Session ID returned by the World App */
-    session_id: string;
+    /** Opaque session identifier returned by the World App in `session_<hex>` format */
+    session_id: `session_${string}`;
     /** Array of session credential responses */
     responses: ResponseItemSession[];
     /** The environment used for this request ("production" or "staging") */
@@ -293,13 +297,14 @@ declare enum IDKitErrorCodes {
  */
 declare function isInWorldApp(): boolean;
 interface BuilderConfig {
-    type: "request" | "session" | "proveSession";
+    type: "request" | "createSession" | "proveSession";
     app_id: string;
     action?: string;
-    session_id?: string;
+    session_id?: `session_${string}`;
     rp_context?: RpContext;
     action_description?: string;
     bridge_url?: string;
+    return_to?: string;
     allow_legacy_proofs?: boolean;
     override_connect_base_url?: string;
     environment?: string;
@@ -314,7 +319,7 @@ interface BuilderConfig {
 interface WaitOptions {
     /** Milliseconds between polls (default: 1000) */
     pollInterval?: number;
-    /** Total timeout in milliseconds (default: 300000 = 5 minutes) */
+    /** Total timeout in milliseconds (default: 900000 = 15 minutes) */
     timeout?: number;
     /** AbortSignal for cancellation */
     signal?: AbortSignal;
@@ -350,6 +355,74 @@ interface IDKitRequest {
     /** Poll continuously until completion or timeout */
     pollUntilCompletion(options?: WaitOptions): Promise<IDKitCompletionResult>;
 }
+/**
+ * Creates a CredentialRequest for a credential type
+ *
+ * @param credential_type - The type of credential to request (e.g., 'proof_of_human', 'face')
+ * @param options - Optional signal, genesis_issued_at_min, and expires_at_min
+ * @returns A CredentialRequest object
+ *
+ * @example
+ * ```typescript
+ * const orb = CredentialRequest('proof_of_human', { signal: 'user-123' })
+ * const face = CredentialRequest('face')
+ * // Require credential to be valid for at least one year
+ * const withExpiry = CredentialRequest('proof_of_human', { expires_at_min: Date.now() / 1000 + 60 * 60 * 60 * 24 * 365 })
+ * ```
+ */
+declare function CredentialRequest(credential_type: CredentialType, options?: {
+    signal?: string;
+    genesis_issued_at_min?: number;
+    expires_at_min?: number;
+}): CredentialRequestType;
+/**
+ * Creates an OR constraint - at least one child must be satisfied
+ *
+ * @param nodes - Constraint nodes (CredentialRequests or nested constraints)
+ * @returns An "any" constraint node
+ *
+ * @example
+ * ```typescript
+ * const constraint = any(CredentialRequest('proof_of_human'), CredentialRequest('face'))
+ * ```
+ */
+declare function any(...nodes: ConstraintNode[]): {
+    any: ConstraintNode[];
+};
+/**
+ * Creates an AND constraint - all children must be satisfied
+ *
+ * @param nodes - Constraint nodes (CredentialRequests or nested constraints)
+ * @returns An "all" constraint node
+ *
+ * @example
+ * ```typescript
+ * const constraint = all(CredentialRequest('proof_of_human'), any(CredentialRequest('passport'), CredentialRequest('mnc')))
+ * ```
+ */
+declare function all(...nodes: ConstraintNode[]): {
+    all: ConstraintNode[];
+};
+/**
+ * Creates an enumerate constraint - all satisfiable children should be selected
+ *
+ * `enumerate` is satisfied when at least one child is satisfied.
+ *
+ * @param nodes - Constraint nodes (CredentialRequests or nested constraints)
+ * @returns An "enumerate" constraint node
+ *
+ * @example
+ * ```typescript
+ * const constraint = enumerate(
+ *   CredentialRequest('passport'),
+ *   CredentialRequest('mnc'),
+ * )
+ * ```
+ */
+declare function enumerate(...nodes: ConstraintNode[]): {
+    enumerate: ConstraintNode[];
+};
+
 /**
  * Creates an OrbLegacy preset for World ID 3.0 legacy support
  *
@@ -517,6 +590,60 @@ declare class IDKitBuilder {
  * ```
  */
 declare function createRequest(config: IDKitRequestConfig): IDKitBuilder;
+/**
+ * Creates a new session builder (no action, no existing session_id)
+ *
+ * Use this when creating a new session for a user who doesn't have one yet.
+ * The response will include a `session_id` that should be saved for future
+ * session proofs with `proveSession()`.
+ *
+ * @param config - Session configuration (no action field)
+ * @returns IDKitBuilder - A builder instance
+ *
+ * @example
+ * ```typescript
+ * import { IDKit, CredentialRequest, any } from '@worldcoin/idkit-core'
+ *
+ * // Create a new session (user doesn't have session_id yet)
+ * const request = await IDKit.createSession({
+ *   app_id: 'app_staging_xxxxx',
+ *   rp_context: { ... },
+ * }).constraints(any(CredentialRequest('proof_of_human'), CredentialRequest('face')));
+ *
+ * // Display QR, wait for proof
+ * const result = await request.pollUntilCompletion();
+ * // result.session_id -> save this for future sessions
+ * // result.responses[0].session_nullifier -> for session tracking
+ * ```
+ */
+declare function createSession(config: IDKitSessionConfig): IDKitBuilder;
+/**
+ * Creates a builder for proving an existing session (no action, has session_id)
+ *
+ * Use this when a returning user needs to prove they own an existing session.
+ * The `sessionId` should be the opaque `session_<hex>` value previously returned
+ * from `createSession()`.
+ *
+ * @param sessionId - The protocol session ID from a previous session creation
+ * @param config - Session configuration (no action field)
+ * @returns IDKitBuilder - A builder instance
+ *
+ * @example
+ * ```typescript
+ * import { IDKit, CredentialRequest, any } from '@worldcoin/idkit-core'
+ *
+ * // Prove an existing session (user returns)
+ * const request = await IDKit.proveSession(savedSessionId, {
+ *   app_id: 'app_staging_xxxxx',
+ *   rp_context: { ... },
+ * }).constraints(any(CredentialRequest('proof_of_human'), CredentialRequest('face')));
+ *
+ * const result = await request.pollUntilCompletion();
+ * // result.session_id -> same session
+ * // result.responses[0].session_nullifier -> should match for same user
+ * ```
+ */
+declare function proveSession(sessionId: `session_${string}`, config: IDKitSessionConfig): IDKitBuilder;
 /**
  * IDKit namespace providing the main API entry points
  *
@@ -541,6 +668,18 @@ declare function createRequest(config: IDKitRequestConfig): IDKitBuilder;
 declare const IDKit: {
     /** Create a new verification request */
     request: typeof createRequest;
+    /** Create a new session (no action, no existing session_id) */
+    createSession: typeof createSession;
+    /** Prove an existing session (no action, has session_id) */
+    proveSession: typeof proveSession;
+    /** Create a CredentialRequest for a credential type */
+    CredentialRequest: typeof CredentialRequest;
+    /** Create an OR constraint - at least one child must be satisfied */
+    any: typeof any;
+    /** Create an AND constraint - all children must be satisfied */
+    all: typeof all;
+    /** Create an enumerate constraint - all satisfiable children should be selected */
+    enumerate: typeof enumerate;
     /** Create an OrbLegacy preset for World ID 3.0 legacy support */
     orbLegacy: typeof orbLegacy;
     /** Create a SecureDocumentLegacy preset for World ID 3.0 legacy support */
@@ -575,4 +714,7 @@ declare const isWeb: () => boolean;
  */
 declare const isNode: () => boolean;
 
-export { type AbiEncodedValue, type ConstraintNode, type CredentialRequestType, type CredentialType, type DeviceLegacyPreset, type DocumentLegacyPreset, IDKit, type IDKitCompletionResult, type IDKitErrorCode, IDKitErrorCodes, type IDKitRequest, type IDKitRequestConfig, type IDKitResult, type IDKitResultSession, type IDKitSessionConfig, type OrbLegacyPreset, type Preset, type ResponseItemSession, type ResponseItemV3, type ResponseItemV4, type RpContext, type SecureDocumentLegacyPreset, type SelfieCheckLegacyPreset, type Status$1 as Status, type WaitOptions, deviceLegacy, documentLegacy, isInWorldApp, isNode, isReactNative, isWeb, orbLegacy, secureDocumentLegacy, selfieCheckLegacy };
+declare function isDebug(): boolean;
+declare function setDebug(enabled: boolean): void;
+
+export { type AbiEncodedValue, type ConstraintNode, CredentialRequest, type CredentialRequestType, type CredentialType, type DeviceLegacyPreset, type DocumentLegacyPreset, IDKit, type IDKitCompletionResult, type IDKitErrorCode, IDKitErrorCodes, type IDKitRequest, type IDKitRequestConfig, type IDKitResult, type IDKitResultSession, type IDKitSessionConfig, type OrbLegacyPreset, type Preset, type ResponseItemSession, type ResponseItemV3, type ResponseItemV4, type RpContext, type SecureDocumentLegacyPreset, type SelfieCheckLegacyPreset, type Status$1 as Status, type WaitOptions, all, any, deviceLegacy, documentLegacy, enumerate, isDebug, isInWorldApp, isNode, isReactNative, isWeb, orbLegacy, secureDocumentLegacy, selfieCheckLegacy, setDebug };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { RpSignature, signRequest } from '@worldcoin/idkit-server';
+export { RpSignature, SignRequestParams, signRequest } from '@worldcoin/idkit-server';
 export { hashSignal } from './hashing.js';
 
 /**
@@ -47,6 +47,8 @@ type IDKitRequestConfig = {
     action_description?: string;
     /** URL to a third-party bridge to use when connecting to the World App. Optional. */
     bridge_url?: string;
+    /** Optional deep-link callback URL appended as `return_to` on the connector URL. */
+    return_to?: string;
     /**
      * Whether to accept legacy (v3) World ID proofs as fallback.
      *
@@ -77,6 +79,8 @@ type IDKitSessionConfig = {
     action_description?: string;
     /** URL to a third-party bridge to use when connecting to the World App. Optional. */
     bridge_url?: string;
+    /** Optional deep-link callback URL appended as `return_to` on the connector URL. */
+    return_to?: string;
     /** Optional override for the connect base URL (e.g., for staging environments) */
     override_connect_base_url?: string;
     /** Optional environment override. Defaults to "production". */
@@ -169,8 +173,8 @@ interface IDKitResultSession {
     nonce: string;
     /** Action description (only if provided in input) */
     action_description?: string;
-    /** Session ID returned by the World App */
-    session_id: string;
+    /** Opaque session identifier returned by the World App in `session_<hex>` format */
+    session_id: `session_${string}`;
     /** Array of session credential responses */
     responses: ResponseItemSession[];
     /** The environment used for this request ("production" or "staging") */
@@ -293,13 +297,14 @@ declare enum IDKitErrorCodes {
  */
 declare function isInWorldApp(): boolean;
 interface BuilderConfig {
-    type: "request" | "session" | "proveSession";
+    type: "request" | "createSession" | "proveSession";
     app_id: string;
     action?: string;
-    session_id?: string;
+    session_id?: `session_${string}`;
     rp_context?: RpContext;
     action_description?: string;
     bridge_url?: string;
+    return_to?: string;
     allow_legacy_proofs?: boolean;
     override_connect_base_url?: string;
     environment?: string;
@@ -314,7 +319,7 @@ interface BuilderConfig {
 interface WaitOptions {
     /** Milliseconds between polls (default: 1000) */
     pollInterval?: number;
-    /** Total timeout in milliseconds (default: 300000 = 5 minutes) */
+    /** Total timeout in milliseconds (default: 900000 = 15 minutes) */
     timeout?: number;
     /** AbortSignal for cancellation */
     signal?: AbortSignal;
@@ -350,6 +355,74 @@ interface IDKitRequest {
     /** Poll continuously until completion or timeout */
     pollUntilCompletion(options?: WaitOptions): Promise<IDKitCompletionResult>;
 }
+/**
+ * Creates a CredentialRequest for a credential type
+ *
+ * @param credential_type - The type of credential to request (e.g., 'proof_of_human', 'face')
+ * @param options - Optional signal, genesis_issued_at_min, and expires_at_min
+ * @returns A CredentialRequest object
+ *
+ * @example
+ * ```typescript
+ * const orb = CredentialRequest('proof_of_human', { signal: 'user-123' })
+ * const face = CredentialRequest('face')
+ * // Require credential to be valid for at least one year
+ * const withExpiry = CredentialRequest('proof_of_human', { expires_at_min: Date.now() / 1000 + 60 * 60 * 60 * 24 * 365 })
+ * ```
+ */
+declare function CredentialRequest(credential_type: CredentialType, options?: {
+    signal?: string;
+    genesis_issued_at_min?: number;
+    expires_at_min?: number;
+}): CredentialRequestType;
+/**
+ * Creates an OR constraint - at least one child must be satisfied
+ *
+ * @param nodes - Constraint nodes (CredentialRequests or nested constraints)
+ * @returns An "any" constraint node
+ *
+ * @example
+ * ```typescript
+ * const constraint = any(CredentialRequest('proof_of_human'), CredentialRequest('face'))
+ * ```
+ */
+declare function any(...nodes: ConstraintNode[]): {
+    any: ConstraintNode[];
+};
+/**
+ * Creates an AND constraint - all children must be satisfied
+ *
+ * @param nodes - Constraint nodes (CredentialRequests or nested constraints)
+ * @returns An "all" constraint node
+ *
+ * @example
+ * ```typescript
+ * const constraint = all(CredentialRequest('proof_of_human'), any(CredentialRequest('passport'), CredentialRequest('mnc')))
+ * ```
+ */
+declare function all(...nodes: ConstraintNode[]): {
+    all: ConstraintNode[];
+};
+/**
+ * Creates an enumerate constraint - all satisfiable children should be selected
+ *
+ * `enumerate` is satisfied when at least one child is satisfied.
+ *
+ * @param nodes - Constraint nodes (CredentialRequests or nested constraints)
+ * @returns An "enumerate" constraint node
+ *
+ * @example
+ * ```typescript
+ * const constraint = enumerate(
+ *   CredentialRequest('passport'),
+ *   CredentialRequest('mnc'),
+ * )
+ * ```
+ */
+declare function enumerate(...nodes: ConstraintNode[]): {
+    enumerate: ConstraintNode[];
+};
+
 /**
  * Creates an OrbLegacy preset for World ID 3.0 legacy support
  *
@@ -517,6 +590,60 @@ declare class IDKitBuilder {
  * ```
  */
 declare function createRequest(config: IDKitRequestConfig): IDKitBuilder;
+/**
+ * Creates a new session builder (no action, no existing session_id)
+ *
+ * Use this when creating a new session for a user who doesn't have one yet.
+ * The response will include a `session_id` that should be saved for future
+ * session proofs with `proveSession()`.
+ *
+ * @param config - Session configuration (no action field)
+ * @returns IDKitBuilder - A builder instance
+ *
+ * @example
+ * ```typescript
+ * import { IDKit, CredentialRequest, any } from '@worldcoin/idkit-core'
+ *
+ * // Create a new session (user doesn't have session_id yet)
+ * const request = await IDKit.createSession({
+ *   app_id: 'app_staging_xxxxx',
+ *   rp_context: { ... },
+ * }).constraints(any(CredentialRequest('proof_of_human'), CredentialRequest('face')));
+ *
+ * // Display QR, wait for proof
+ * const result = await request.pollUntilCompletion();
+ * // result.session_id -> save this for future sessions
+ * // result.responses[0].session_nullifier -> for session tracking
+ * ```
+ */
+declare function createSession(config: IDKitSessionConfig): IDKitBuilder;
+/**
+ * Creates a builder for proving an existing session (no action, has session_id)
+ *
+ * Use this when a returning user needs to prove they own an existing session.
+ * The `sessionId` should be the opaque `session_<hex>` value previously returned
+ * from `createSession()`.
+ *
+ * @param sessionId - The protocol session ID from a previous session creation
+ * @param config - Session configuration (no action field)
+ * @returns IDKitBuilder - A builder instance
+ *
+ * @example
+ * ```typescript
+ * import { IDKit, CredentialRequest, any } from '@worldcoin/idkit-core'
+ *
+ * // Prove an existing session (user returns)
+ * const request = await IDKit.proveSession(savedSessionId, {
+ *   app_id: 'app_staging_xxxxx',
+ *   rp_context: { ... },
+ * }).constraints(any(CredentialRequest('proof_of_human'), CredentialRequest('face')));
+ *
+ * const result = await request.pollUntilCompletion();
+ * // result.session_id -> same session
+ * // result.responses[0].session_nullifier -> should match for same user
+ * ```
+ */
+declare function proveSession(sessionId: `session_${string}`, config: IDKitSessionConfig): IDKitBuilder;
 /**
  * IDKit namespace providing the main API entry points
  *
@@ -541,6 +668,18 @@ declare function createRequest(config: IDKitRequestConfig): IDKitBuilder;
 declare const IDKit: {
     /** Create a new verification request */
     request: typeof createRequest;
+    /** Create a new session (no action, no existing session_id) */
+    createSession: typeof createSession;
+    /** Prove an existing session (no action, has session_id) */
+    proveSession: typeof proveSession;
+    /** Create a CredentialRequest for a credential type */
+    CredentialRequest: typeof CredentialRequest;
+    /** Create an OR constraint - at least one child must be satisfied */
+    any: typeof any;
+    /** Create an AND constraint - all children must be satisfied */
+    all: typeof all;
+    /** Create an enumerate constraint - all satisfiable children should be selected */
+    enumerate: typeof enumerate;
     /** Create an OrbLegacy preset for World ID 3.0 legacy support */
     orbLegacy: typeof orbLegacy;
     /** Create a SecureDocumentLegacy preset for World ID 3.0 legacy support */
@@ -575,4 +714,7 @@ declare const isWeb: () => boolean;
  */
 declare const isNode: () => boolean;
 
-export { type AbiEncodedValue, type ConstraintNode, type CredentialRequestType, type CredentialType, type DeviceLegacyPreset, type DocumentLegacyPreset, IDKit, type IDKitCompletionResult, type IDKitErrorCode, IDKitErrorCodes, type IDKitRequest, type IDKitRequestConfig, type IDKitResult, type IDKitResultSession, type IDKitSessionConfig, type OrbLegacyPreset, type Preset, type ResponseItemSession, type ResponseItemV3, type ResponseItemV4, type RpContext, type SecureDocumentLegacyPreset, type SelfieCheckLegacyPreset, type Status$1 as Status, type WaitOptions, deviceLegacy, documentLegacy, isInWorldApp, isNode, isReactNative, isWeb, orbLegacy, secureDocumentLegacy, selfieCheckLegacy };
+declare function isDebug(): boolean;
+declare function setDebug(enabled: boolean): void;
+
+export { type AbiEncodedValue, type ConstraintNode, CredentialRequest, type CredentialRequestType, type CredentialType, type DeviceLegacyPreset, type DocumentLegacyPreset, IDKit, type IDKitCompletionResult, type IDKitErrorCode, IDKitErrorCodes, type IDKitRequest, type IDKitRequestConfig, type IDKitResult, type IDKitResultSession, type IDKitSessionConfig, type OrbLegacyPreset, type Preset, type ResponseItemSession, type ResponseItemV3, type ResponseItemV4, type RpContext, type SecureDocumentLegacyPreset, type SelfieCheckLegacyPreset, type Status$1 as Status, type WaitOptions, all, any, deviceLegacy, documentLegacy, enumerate, isDebug, isInWorldApp, isNode, isReactNative, isWeb, orbLegacy, secureDocumentLegacy, selfieCheckLegacy, setDebug };