@zkproofport-app/sdk 0.1.2-beta.1

package/dist/ProofportSDK.d.ts

@@ -0,0 +1,1011 @@
+/**
+ * Proofport SDK - Main class
+ */
+import type { ProofRequest, ProofResponse, CircuitType, CircuitInputs, ProofportConfig, QRCodeOptions, AuthCredentials, AuthToken, RelayProofRequest, RelayProofResult } from './types';
+import type { SDKEnvironment } from './types';
+/**
+ * Main SDK class for interacting with the ZKProofport mobile app.
+ *
+ * Provides methods for creating proof requests, generating QR codes and deep links,
+ * verifying proofs on-chain, and handling proof responses from the mobile app.
+ *
+ * @example
+ * ```typescript
+ * import { ProofportSDK } from '@zkproofport-app/sdk';
+ *
+ * // Initialize SDK (uses production relay by default)
+ * const sdk = ProofportSDK.create();
+ *
+ * // Authenticate
+ * await sdk.login({ clientId: 'your-id', apiKey: 'your-key' });
+ *
+ * // Create proof request via relay
+ * const relay = await sdk.createRelayRequest('coinbase_attestation', {
+ *   scope: 'myapp.com'
+ * });
+ *
+ * // Generate QR code for desktop users
+ * const qrDataUrl = await sdk.generateQRCode(relay.deepLink);
+ *
+ * // Wait for proof via WebSocket (primary) or polling (fallback)
+ * const result = await sdk.waitForProof(relay.requestId);
+ * if (result.status === 'completed') {
+ *   console.log('Proof received:', result.proof);
+ * }
+ * ```
+ */
+export declare class ProofportSDK {
+    private config;
+    private pendingRequests;
+    private authToken;
+    private relayUrl;
+    private nullifierRegistry?;
+    private socket;
+    /**
+     * Creates a new ProofportSDK instance.
+     *
+     * For most use cases, prefer the static factory with environment presets:
+     * ```typescript
+     * const sdk = ProofportSDK.create('production');
+     * ```
+     *
+     * @param config - SDK configuration options
+     * @param config.scheme - Custom deep link scheme (default: 'zkproofport')
+     * @param config.relayUrl - Relay server URL (required for relay features)
+     * @param config.verifiers - Custom verifier contract addresses per circuit
+     *
+     * @example
+     * ```typescript
+     * const sdk = new ProofportSDK({
+     *   relayUrl: 'https://relay.zkproofport.app',
+     *   verifiers: {
+     *     coinbase_attestation: {
+     *       verifierAddress: '0x...',
+     *       chainId: 1
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    constructor(config?: ProofportConfig);
+    /**
+     * @internal
+     * Creates a Coinbase KYC verification proof request.
+     *
+     * Generates a proof request for verifying Coinbase KYC status without revealing
+     * the actual attestation data. The proof confirms the user has passed Coinbase KYC
+     * while maintaining privacy through zero-knowledge proofs.
+     *
+     * @param inputs - Circuit inputs for Coinbase KYC
+     * @param inputs.scope - Application-specific scope (e.g., domain name)
+     * @param options - Request configuration options
+  
+     * @param options.message - Custom message to display to user
+     * @param options.dappName - Application name shown in ZKProofport app
+     * @param options.dappIcon - Application icon URL shown in ZKProofport app
+     * @param options.expiresInMs - Request expiration time in milliseconds (default: 10 minutes)
+     *
+     * @returns ProofRequest object with unique requestId and all request details
+     *
+     * @throws Error if scope is not provided
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({
+     *   scope: 'myapp.com'
+     * }, {
+     *   dappName: 'My DApp',
+     *   message: 'Verify your KYC status to access this feature'
+     * });
+     *
+     * const deepLink = sdk.getDeepLinkUrl(request);
+     * ```
+     */
+    private createCoinbaseKycRequest;
+    /**
+     * @internal
+     * Creates a Coinbase Country attestation proof request.
+     *
+     * Generates a proof request for verifying country eligibility through Coinbase
+     * attestation without revealing the actual country data. The proof confirms the
+     * user's country status while maintaining privacy through zero-knowledge proofs.
+     *
+     * @param inputs - Circuit inputs for Coinbase Country attestation
+     * @param inputs.scope - Application-specific scope (e.g., domain name)
+     * @param options - Request configuration options
+  
+     * @param options.message - Custom message to display to user
+     * @param options.dappName - Application name shown in ZKProofport app
+     * @param options.dappIcon - Application icon URL shown in ZKProofport app
+     * @param options.expiresInMs - Request expiration time in milliseconds (default: 10 minutes)
+     *
+     * @returns ProofRequest object with unique requestId and all request details
+     *
+     * @throws Error if scope is not provided
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseCountryRequest({
+     *   scope: 'myapp.com'
+     * }, {
+     *   dappName: 'My DApp',
+     *   message: 'Verify your country eligibility'
+     * });
+     * ```
+     */
+    private createCoinbaseCountryRequest;
+    /**
+     * @internal
+     * Creates a generic proof request for any supported circuit type.
+     *
+     * Routes to the appropriate circuit-specific request creation method based on
+     * the circuit type. Use this for dynamic circuit selection or when the circuit
+     * type is determined at runtime.
+     *
+     * @param circuit - Circuit type identifier ('coinbase_attestation' | 'coinbase_country_attestation')
+     * @param inputs - Circuit-specific inputs
+     * @param options - Request configuration options
+  
+     * @param options.message - Custom message to display to user
+     * @param options.dappName - Application name shown in ZKProofport app
+     * @param options.dappIcon - Application icon URL shown in ZKProofport app
+     * @param options.expiresInMs - Request expiration time in milliseconds (default: 15 minutes)
+     *
+     * @returns ProofRequest object with unique requestId and all request details
+     *
+     * @throws Error if required inputs are missing for the specified circuit
+     *
+     * @example
+     * ```typescript
+     * const circuitType = userSelection; // Dynamic selection
+     * const request = sdk.createProofRequest(
+     *   circuitType,
+     *   { scope: 'myapp.com' },
+     *   { dappName: 'My DApp' }
+     * );
+     * ```
+     */
+    private createProofRequest;
+    /**
+     * @internal
+     * Generates a deep link URL for a proof request.
+     *
+     * Creates a zkproofport:// URL that opens the ZKProofport mobile app with the
+     * specified proof request. The URL contains all request details encoded as query
+     * parameters.
+     *
+     * @param request - ProofRequest object to encode as deep link
+     *
+     * @returns Deep link URL string (e.g., 'zkproofport://proof?requestId=...')
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * const url = sdk.getDeepLinkUrl(request);
+     * // url: 'zkproofport://proof?requestId=abc123&circuit=coinbase_attestation&...'
+     * ```
+     */
+    private getDeepLinkUrl;
+    /**
+     * @internal
+     * Opens the ZKProofport mobile app with a proof request.
+     *
+     * Redirects the browser to the deep link URL, which opens the ZKProofport app
+     * if installed. Only works in mobile browser environments. For desktop, use
+     * requestProof() to display a QR code instead.
+     *
+     * @param request - ProofRequest object to send to the app
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * if (ProofportSDK.isMobile()) {
+     *   sdk.openProofRequest(request); // Opens app directly
+     * }
+     * ```
+     */
+    private openProofRequest;
+    /**
+     * @internal
+     * Requests a proof with automatic platform detection.
+     *
+     * Detects whether the user is on mobile or desktop and automatically chooses
+     * the appropriate flow:
+     * - Mobile: Opens the deep link directly to launch the ZKProofport app
+     * - Desktop: Generates a QR code data URL for the user to scan
+     *
+     * @param request - ProofRequest object to send
+     * @param qrOptions - QR code generation options (size, colors, logo) for desktop
+     *
+     * @returns Object containing deep link URL, optional QR code data URL, and platform detection result
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * const result = await sdk.requestProof(request);
+     *
+     * if (result.mobile) {
+     *   console.log('Opening app directly');
+     * } else {
+     *   // Display QR code for desktop users
+     *   document.getElementById('qr').src = result.qrDataUrl;
+     * }
+     * ```
+     */
+    private requestProof;
+    /**
+     * Generates a QR code as a data URL for a proof request.
+     *
+     * Creates a PNG image data URL that can be directly set as an img src attribute.
+     * Suitable for embedding QR codes in web pages for desktop users to scan with
+     * their mobile device.
+     *
+     * @param requestOrUrl - ProofRequest object or deep link URL string
+     * @param options - QR code customization options
+     * @param options.size - QR code size in pixels (default: 256)
+     * @param options.margin - Quiet zone margin in modules (default: 4)
+     * @param options.darkColor - Color for dark modules (default: '#000000')
+     * @param options.lightColor - Color for light modules (default: '#ffffff')
+     * @param options.logoUrl - Optional center logo image URL
+     * @param options.logoSize - Logo size as fraction of QR code (default: 0.2)
+     *
+     * @returns Promise resolving to PNG data URL (e.g., 'data:image/png;base64,...')
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * const qrUrl = await sdk.generateQRCode(request, {
+     *   size: 400,
+     *   darkColor: '#1a1a1a',
+     *   logoUrl: 'https://myapp.com/logo.png'
+     * });
+     * document.getElementById('qr-image').src = qrUrl;
+     * ```
+     */
+    generateQRCode(requestOrUrl: ProofRequest | string, options?: QRCodeOptions): Promise<string>;
+    /**
+     * Generates a QR code as an SVG string for a proof request.
+     *
+     * Creates a scalable vector graphics representation of the QR code, ideal for
+     * high-resolution displays or when vector format is preferred over raster images.
+     *
+     * @param requestOrUrl - ProofRequest object or deep link URL string
+     * @param options - QR code customization options
+     * @param options.size - QR code size in pixels (default: 256)
+     * @param options.margin - Quiet zone margin in modules (default: 4)
+     * @param options.darkColor - Color for dark modules (default: '#000000')
+     * @param options.lightColor - Color for light modules (default: '#ffffff')
+     *
+     * @returns Promise resolving to SVG string
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * const svgString = await sdk.generateQRCodeSVG(request);
+     * document.getElementById('qr-container').innerHTML = svgString;
+     * ```
+     */
+    generateQRCodeSVG(requestOrUrl: ProofRequest | string, options?: QRCodeOptions): Promise<string>;
+    /**
+     * Renders a QR code directly to an HTML canvas element.
+     *
+     * Draws the QR code onto the provided canvas element, useful for custom
+     * rendering workflows or when you need direct canvas manipulation.
+     *
+     * @param canvas - HTML canvas element to render to
+     * @param requestOrUrl - ProofRequest object or deep link URL string
+     * @param options - QR code customization options
+     * @param options.size - QR code size in pixels (default: 256)
+     * @param options.margin - Quiet zone margin in modules (default: 4)
+     * @param options.darkColor - Color for dark modules (default: '#000000')
+     * @param options.lightColor - Color for light modules (default: '#ffffff')
+     *
+     * @returns Promise that resolves when rendering is complete
+     *
+     * @example
+     * ```typescript
+     * const canvas = document.getElementById('qr-canvas') as HTMLCanvasElement;
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * await sdk.renderQRCodeToCanvas(canvas, request, { size: 400 });
+     * ```
+     */
+    renderQRCodeToCanvas(canvas: HTMLCanvasElement, requestOrUrl: ProofRequest | string, options?: QRCodeOptions): Promise<void>;
+    /**
+     * Checks if a proof request fits within QR code size limits.
+     *
+     * Estimates the encoded data size and validates it against QR code capacity limits.
+     * Useful for validating requests before generating QR codes, especially when
+     * including large custom messages or metadata.
+     *
+     * @param requestOrUrl - ProofRequest object or deep link URL string
+     *
+     * @returns Object with size in bytes and whether it fits within limits
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * const check = sdk.checkQRCodeSize(request);
+     * if (!check.withinLimit) {
+     *   console.warn(`Request too large: ${check.size} bytes`);
+     * }
+     * ```
+     */
+    checkQRCodeSize(requestOrUrl: ProofRequest | string): {
+        size: number;
+        withinLimit: boolean;
+    };
+    /**
+     * @internal
+     * Parses a proof response from a callback URL.
+     *
+     * Extracts and decodes proof response data from the callback URL query parameters
+     * after the user completes proof generation in the ZKProofport app. The app
+     * redirects to your callback URL with the proof data encoded as query parameters.
+     *
+     * @param url - Callback URL containing proof response data
+     *
+     * @returns ProofResponse object with status, proof data, and public inputs, or null if invalid
+     *
+     * @example
+     * ```typescript
+     * // In your callback endpoint handler
+     * app.get('/callback', (req, res) => {
+     *   const callbackUrl = req.url;
+     *   const response = sdk.parseResponse(callbackUrl);
+     *
+     *   if (response?.status === 'completed') {
+     *     console.log('Proof received:', response.proof);
+     *     console.log('Public inputs:', response.publicInputs);
+     *   } else if (response?.status === 'rejected') {
+     *     console.log('User rejected the request');
+     *   }
+     * });
+     * ```
+     */
+    private parseResponse;
+    /**
+     * @internal
+     * Checks if a URL is a ZKProofport proof response callback.
+     *
+     * Validates whether the given URL contains the required query parameters for a
+     * proof response. Useful for filtering and routing callback requests.
+     *
+     * @param url - URL to check
+     *
+     * @returns True if the URL appears to be a ZKProofport response callback
+     *
+     * @example
+     * ```typescript
+     * app.get('/callback', (req, res) => {
+     *   const fullUrl = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
+     *   if (sdk.isProofportResponse(fullUrl)) {
+     *     const response = sdk.parseResponse(fullUrl);
+     *     // Handle proof response
+     *   }
+     * });
+     * ```
+     */
+    private isProofportResponse;
+    /**
+     * @internal
+     * Retrieves a pending proof request by its ID.
+     *
+     * Looks up a previously created proof request from the SDK's internal cache.
+     * Useful for validating callback responses and maintaining request state.
+     *
+     * @param requestId - Unique request identifier
+     *
+     * @returns ProofRequest object if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * app.get('/callback', (req, res) => {
+     *   const response = sdk.parseResponse(req.url);
+     *   const originalRequest = sdk.getPendingRequest(response.requestId);
+     *
+     *   if (originalRequest) {
+     *     console.log('Original request:', originalRequest);
+     *     sdk.clearPendingRequest(response.requestId);
+     *   }
+     * });
+     * ```
+     */
+    private getPendingRequest;
+    /**
+     * @internal
+     * Clears a pending proof request from the internal cache.
+     *
+     * Removes a proof request from the SDK's pending requests map. Should be called
+     * after successfully processing a proof response to prevent memory leaks.
+     *
+     * @param requestId - Unique request identifier to remove
+     *
+     * @example
+     * ```typescript
+     * app.get('/callback', (req, res) => {
+     *   const response = sdk.parseResponse(req.url);
+     *   if (response?.status === 'completed') {
+     *     // Process proof...
+     *     sdk.clearPendingRequest(response.requestId);
+     *   }
+     * });
+     * ```
+     */
+    private clearPendingRequest;
+    /**
+     * Verifies a zero-knowledge proof on-chain using the deployed verifier contract.
+     *
+     * Calls the Solidity verifier contract to cryptographically verify the proof's
+     * validity. This ensures the proof was generated correctly and the public inputs
+     * match the claimed values.
+     *
+     * @param circuit - Circuit type identifier
+     * @param proof - Hex-encoded proof string from the ZKProofport app
+     * @param publicInputs - Array of hex-encoded public input strings
+     * @param providerOrSigner - ethers v6 Provider or Signer (defaults to base mainnet public RPC)
+     *
+     * @returns Promise resolving to verification result with valid boolean and optional error message
+     *
+     * @example
+     * ```typescript
+     * import { ethers } from 'ethers';
+     *
+     * const response = sdk.parseResponse(callbackUrl);
+     * if (response?.status === 'completed') {
+     *   const provider = new ethers.JsonRpcProvider('https://mainnet.base.org');
+     *   const result = await sdk.verifyOnChain(
+     *     response.circuit,
+     *     response.proof,
+     *     response.publicInputs,
+     *     provider
+     *   );
+     *
+     *   if (result.valid) {
+     *     console.log('Proof verified on-chain!');
+     *   } else {
+     *     console.error('Verification failed:', result.error);
+     *   }
+     * }
+     * ```
+     */
+    verifyOnChain(circuit: CircuitType, proof: string, publicInputs: string[], providerOrSigner?: any): Promise<{
+        valid: boolean;
+        error?: string;
+    }>;
+    /**
+     * Verifies a proof response on-chain using the deployed verifier contract.
+     *
+     * Convenience method that extracts proof data from a ProofResponse object and
+     * verifies it on-chain. Automatically handles incomplete or rejected responses.
+     *
+     * @param response - ProofResponse object from parseResponse()
+     * @param providerOrSigner - ethers v6 Provider or Signer (defaults to base mainnet public RPC)
+     *
+     * @returns Promise resolving to verification result with valid boolean and optional error message
+     *
+     * @example
+     * ```typescript
+     * import { ethers } from 'ethers';
+     *
+     * app.get('/callback', async (req, res) => {
+     *   const response = sdk.parseResponse(req.url);
+     *
+     *   if (response?.status === 'completed') {
+     *     const provider = new ethers.JsonRpcProvider('https://mainnet.base.org');
+     *     const result = await sdk.verifyResponseOnChain(response, provider);
+     *
+     *     if (result.valid) {
+     *       // Grant access to user
+     *       res.json({ success: true, verified: true });
+     *     } else {
+     *       res.status(400).json({ error: result.error });
+     *     }
+     *   } else {
+     *     res.status(400).json({ error: 'Proof generation failed or rejected' });
+     *   }
+     * });
+     * ```
+     */
+    verifyResponseOnChain(response: ProofResponse, providerOrSigner?: any): Promise<{
+        valid: boolean;
+        error?: string;
+    }>;
+    /**
+     * Gets the deployed verifier contract address for a circuit.
+     *
+     * Returns the Ethereum address of the Solidity verifier contract for the
+     * specified circuit. Uses custom verifier if configured, otherwise returns
+     * the default deployed address.
+     *
+     * @param circuit - Circuit type identifier
+     *
+     * @returns Ethereum address of the verifier contract (0x...)
+     *
+     * @example
+     * ```typescript
+     * const address = sdk.getVerifierAddress('coinbase_attestation');
+     * console.log('Verifier deployed at:', address);
+     * ```
+     */
+    getVerifierAddress(circuit: CircuitType): string;
+    /**
+     * Gets the blockchain chain ID where the verifier contract is deployed.
+     *
+     * Returns the EIP-155 chain ID for the network where the verifier contract
+     * is deployed. Uses custom verifier if configured, otherwise returns the
+     * default chain ID (Base mainnet: 8453).
+     *
+     * @param circuit - Circuit type identifier
+     *
+     * @returns Chain ID number (e.g., 8453 for Base mainnet)
+     *
+     * @example
+     * ```typescript
+     * const chainId = sdk.getVerifierChainId('coinbase_attestation');
+     * console.log('Verifier on chain:', chainId); // 8453 (Base mainnet)
+     * ```
+     */
+    getVerifierChainId(circuit: CircuitType): number;
+    /**
+     * Gets metadata for a specific circuit type.
+     *
+     * Returns circuit metadata including display name, description, required inputs,
+     * and other configuration details.
+     *
+     * @param circuit - Circuit type identifier
+     *
+     * @returns Circuit metadata object with name, description, and configuration
+     *
+     * @example
+     * ```typescript
+     * const metadata = sdk.getCircuitMetadata('coinbase_attestation');
+     * console.log('Circuit name:', metadata.name);
+     * console.log('Description:', metadata.description);
+     * ```
+     */
+    getCircuitMetadata(circuit: CircuitType): {
+        name: string;
+        description: string;
+        publicInputsCount: number;
+        publicInputNames: string[];
+    };
+    /**
+     * Gets all supported circuit types.
+     *
+     * Returns an array of all circuit type identifiers that are currently supported
+     * by the SDK and ZKProofport app.
+     *
+     * @returns Array of supported circuit type identifiers
+     *
+     * @example
+     * ```typescript
+     * const circuits = sdk.getSupportedCircuits();
+     * console.log('Supported circuits:', circuits);
+     * // ['coinbase_attestation', 'coinbase_country_attestation']
+     * ```
+     */
+    getSupportedCircuits(): CircuitType[];
+    /**
+     * @internal
+     * Validates a proof request for completeness and correctness.
+     *
+     * Checks that the proof request contains all required fields and that the
+     * circuit-specific inputs are valid. Useful for catching configuration errors
+     * before generating QR codes or sending requests to users.
+     *
+     * @param request - ProofRequest object to validate
+     *
+     * @returns Validation result with valid boolean and optional error message
+     *
+     * @example
+     * ```typescript
+     * const request = sdk.createCoinbaseKycRequest({ scope: 'myapp.com' });
+     * const validation = sdk.validateRequest(request);
+     *
+     * if (!validation.valid) {
+     *   console.error('Invalid request:', validation.error);
+     * }
+     * ```
+     */
+    private validateRequest;
+    /**
+     * @internal
+     * Checks if a URL is a ZKProofport deep link.
+     *
+     * Validates whether the given URL uses the ZKProofport deep link scheme
+     * (zkproofport:// by default) and has the correct format for a proof request.
+     *
+     * @param url - URL string to check
+     *
+     * @returns True if the URL is a valid ZKProofport deep link
+     *
+     * @example
+     * ```typescript
+     * const url = 'zkproofport://proof?requestId=abc123&circuit=coinbase_attestation';
+     * if (sdk.isProofportDeepLink(url)) {
+     *   const request = sdk.parseDeepLink(url);
+     *   console.log('Parsed request:', request);
+     * }
+     * ```
+     */
+    private isProofportDeepLink;
+    /**
+     * @internal
+     * Parses a proof request from a deep link URL.
+     *
+     * Extracts and decodes the proof request data from a zkproofport:// deep link URL.
+     * Useful for handling deep link navigation in web applications or validating
+     * deep link URLs before displaying QR codes.
+     *
+     * @param url - ZKProofport deep link URL string
+     *
+     * @returns ProofRequest object with all request details, or null if invalid
+     *
+     * @example
+     * ```typescript
+     * const deepLink = 'zkproofport://proof?requestId=abc123&circuit=coinbase_attestation&...';
+     * const request = sdk.parseDeepLink(deepLink);
+     *
+     * if (request) {
+     *   console.log('Request ID:', request.requestId);
+     *   console.log('Circuit:', request.circuit);
+     * }
+     * ```
+     */
+    private parseDeepLink;
+    /**
+     * Creates a new ProofportSDK instance with environment preset or custom config.
+     * Defaults to `'production'` if no argument is provided.
+     *
+     * **Recommended usage** — use the default production relay:
+     * ```typescript
+     * const sdk = ProofportSDK.create();
+     * ```
+     *
+     * Environment presets:
+     * - `'production'` — relay.zkproofport.app (default)
+     * - `'staging'` — stg-relay.zkproofport.app
+     * - `'local'` — localhost:4001
+     *
+     * @param envOrConfig - Environment name or custom SDK configuration
+     *
+     * @returns New ProofportSDK instance
+     *
+     * @example
+     * ```typescript
+     * // Environment preset (recommended)
+     * const sdk = ProofportSDK.create(); // production (default)
+     * const sdk = ProofportSDK.create('staging');
+     *
+     * // Custom config
+     * const sdk = ProofportSDK.create({
+     *   relayUrl: 'https://my-custom-relay.example.com',
+     * });
+     * ```
+     */
+    static create(envOrConfig?: SDKEnvironment | ProofportConfig): ProofportSDK;
+    /**
+     * Detects if the code is running on a mobile device.
+     *
+     * Uses user agent detection to determine if the current environment is a mobile
+     * browser. This helps the SDK automatically choose between direct deep link
+     * navigation (mobile) and QR code display (desktop).
+     *
+     * @returns True if running on a mobile device (iOS, Android, etc.)
+     *
+     * @example
+     * ```typescript
+     * if (ProofportSDK.isMobile()) {
+     *   // Open deep link directly
+     *   sdk.openProofRequest(request);
+     * } else {
+     *   // Show QR code
+     *   const qr = await sdk.generateQRCode(request);
+     *   displayQRCode(qr);
+     * }
+     * ```
+     */
+    static isMobile(): boolean;
+    /**
+     * Authenticates with ZKProofport using client credentials via the relay server.
+     *
+     * Exchanges a client_id and api_key pair for a short-lived JWT token
+     * that can be used to authenticate relay requests.
+     *
+     * @param credentials - Client ID and API key
+     * @param relayUrl - Relay server URL (e.g., 'https://relay.zkproofport.app')
+     * @returns Promise resolving to AuthToken with JWT token and metadata
+     * @throws Error if authentication fails
+     *
+     * @example
+     * ```typescript
+     * const auth = await ProofportSDK.authenticate(
+     *   { clientId: 'your-client-id', apiKey: 'your-api-key' },
+     *   'https://relay.zkproofport.app'
+     * );
+     * console.log('Token:', auth.token);
+     * console.log('Expires in:', auth.expiresIn, 'seconds');
+     * ```
+     */
+    static authenticate(credentials: AuthCredentials, relayUrl: string): Promise<AuthToken>;
+    /**
+     * Checks if an auth token is still valid (not expired).
+     *
+     * @param auth - AuthToken to check
+     * @returns True if the token has not expired
+     *
+     * @example
+     * ```typescript
+     * if (!ProofportSDK.isTokenValid(auth)) {
+     *   auth = await ProofportSDK.authenticate(credentials, relayUrl);
+     * }
+     * ```
+     */
+    static isTokenValid(auth: AuthToken): boolean;
+    /**
+     * Authenticates with ZKProofport and stores the token for relay requests.
+     *
+     * Instance method that authenticates via the relay server and stores
+     * the JWT token internally, so subsequent relay requests are automatically authenticated.
+     *
+     * @param credentials - Client ID and API key
+     * @returns Promise resolving to AuthToken
+     * @throws Error if authentication fails or relayUrl is not configured
+     *
+     * @example
+     * ```typescript
+     * const sdk = ProofportSDK.create('production');
+     *
+     * await sdk.login({ clientId: 'your-id', apiKey: 'your-key' });
+     * // SDK is now authenticated for relay requests
+     * ```
+     */
+    login(credentials: AuthCredentials): Promise<AuthToken>;
+    /**
+     * Logs out by clearing the stored authentication token.
+     */
+    logout(): void;
+    /**
+     * Returns whether the SDK instance is currently authenticated with a valid token.
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Returns the current auth token, or null if not authenticated.
+     */
+    getAuthToken(): AuthToken | null;
+    /**
+     * Creates a proof request through the relay server.
+     *
+     * This is the recommended way to create proof requests. The relay server:
+     * - Issues a server-side requestId (validated by the mobile app)
+     * - Tracks request status in Redis
+     * - Handles credit deduction and tier enforcement
+     * - Builds the deep link with relay callback URL
+     *
+     * @param circuit - Circuit type identifier
+     * @param inputs - Circuit-specific inputs
+     * @param options - Request options (message, dappName, dappIcon, nonce)
+     * @returns Promise resolving to RelayProofRequest with requestId, deepLink, pollUrl
+     * @throws Error if not authenticated or relay request fails
+     *
+     * @example
+     * ```typescript
+     * const sdk = ProofportSDK.create();
+     * await sdk.login({ clientId: 'id', apiKey: 'key' });
+     *
+     * const relay = await sdk.createRelayRequest('coinbase_attestation', {
+     *   scope: 'myapp.com'
+     * }, { dappName: 'My DApp' });
+     *
+     * // Generate QR code from relay deep link
+     * const qr = await sdk.generateQRCode(relay.deepLink);
+     *
+     * // Wait for proof (WebSocket primary, polling fallback)
+     * const result = await sdk.waitForProof(relay.requestId);
+     * ```
+     */
+    createRelayRequest(circuit: CircuitType, inputs: CircuitInputs, options?: {
+        message?: string;
+        dappName?: string;
+        dappIcon?: string;
+        nonce?: string;
+    }): Promise<RelayProofRequest>;
+    /**
+     * Polls the relay for proof result status.
+     *
+     * @param requestId - The relay-issued request ID
+     * @returns Promise resolving to RelayProofResult
+     * @throws Error if relay URL not configured or request not found
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.pollResult(relay.requestId);
+     * if (result.status === 'completed') {
+     *   console.log('Proof:', result.proof);
+     *   console.log('Public inputs:', result.publicInputs);
+     * }
+     * ```
+     */
+    pollResult(requestId: string): Promise<RelayProofResult>;
+    /**
+     * Polls the relay until proof is completed or failed, with configurable interval and timeout.
+     *
+     * @param requestId - The relay-issued request ID
+     * @param options - Polling options
+     * @param options.intervalMs - Polling interval in milliseconds (default: 2000)
+     * @param options.timeoutMs - Maximum polling time in milliseconds (default: 300000 = 5 min)
+     * @param options.onStatusChange - Callback when status changes
+     * @returns Promise resolving to final RelayProofResult
+     * @throws Error if timeout or relay error
+     */
+    waitForResult(requestId: string, options?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+        onStatusChange?: (result: RelayProofResult) => void;
+    }): Promise<RelayProofResult>;
+    /**
+     * Subscribes to real-time proof status updates via Socket.IO.
+     *
+     * This is the recommended way to receive proof results. Uses WebSocket
+     * connection for instant delivery instead of polling.
+     *
+     * Requires `socket.io-client` package: `npm install socket.io-client`
+     *
+     * @param requestId - The relay-issued request ID to subscribe to
+     * @param callbacks - Event callbacks for status changes and results
+     * @param callbacks.onStatus - Called on status updates (pending, generating)
+     * @param callbacks.onResult - Called when proof is completed or failed
+     * @param callbacks.onError - Called on errors
+     * @returns Unsubscribe function to clean up the connection
+     * @throws Error if not authenticated, relayUrl not set, or socket.io-client not installed
+     *
+     * @example
+     * ```typescript
+     * const relay = await sdk.createRelayRequest('coinbase_attestation', { scope: 'myapp.com' });
+     * const qr = await sdk.generateQRCode(relay.deepLink);
+     *
+     * const unsubscribe = await sdk.subscribe(relay.requestId, {
+     *   onResult: (result) => {
+     *     if (result.status === 'completed') {
+     *       console.log('Proof received!', result.proof);
+     *     }
+     *   },
+     *   onError: (error) => console.error('Error:', error),
+     * });
+     *
+     * // Later: clean up
+     * unsubscribe();
+     * ```
+     */
+    subscribe(requestId: string, callbacks: {
+        onStatus?: (data: {
+            requestId: string;
+            status: string;
+            deepLink?: string;
+        }) => void;
+        onResult?: (result: RelayProofResult) => void;
+        onError?: (error: {
+            error: string;
+            code?: number;
+            requestId?: string;
+        }) => void;
+    }): Promise<() => void>;
+    /**
+     * Waits for a proof result using Socket.IO (primary) with polling fallback.
+     *
+     * Tries Socket.IO first for real-time delivery. If socket.io-client is not
+     * installed or connection fails, automatically falls back to HTTP polling.
+     *
+     * @param requestId - The relay-issued request ID
+     * @param options - Configuration options
+     * @param options.timeoutMs - Maximum wait time in ms (default: 300000 = 5 min)
+     * @param options.onStatusChange - Callback for status updates
+     * @returns Promise resolving to final RelayProofResult
+     */
+    waitForProof(requestId: string, options?: {
+        timeoutMs?: number;
+        onStatusChange?: (result: RelayProofResult | {
+            requestId: string;
+            status: string;
+            deepLink?: string;
+        }) => void;
+    }): Promise<RelayProofResult>;
+    /**
+     * Disconnects the Socket.IO connection if active.
+     */
+    disconnect(): void;
+    /**
+     * Extracts the nullifier from proof public inputs.
+     *
+     * The nullifier is a bytes32 value derived from the user's address and scope,
+     * used to prevent duplicate proof submissions. Each user+scope combination
+     * produces a unique nullifier.
+     *
+     * @param publicInputs - Array of public input hex strings from proof response
+     * @param circuit - Circuit type to determine field positions
+     * @returns Nullifier as hex string (0x...), or null if inputs are insufficient
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.waitForProof(relay.requestId);
+     * if (result.status === 'completed') {
+     *   const nullifier = sdk.extractNullifier(result.publicInputs, result.circuit);
+     *   console.log('Nullifier:', nullifier);
+     * }
+     * ```
+     */
+    extractNullifier(publicInputs: string[], circuit: CircuitType): string | null;
+    /**
+     * Extracts the scope from proof public inputs.
+     *
+     * The scope is an application-specific identifier (e.g., domain name) encoded
+     * as bytes32 in the proof's public inputs.
+     *
+     * @param publicInputs - Array of public input hex strings from proof response
+     * @param circuit - Circuit type to determine field positions
+     * @returns Scope as hex string (0x...), or null if inputs are insufficient
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.waitForProof(relay.requestId);
+     * if (result.status === 'completed') {
+     *   const scope = sdk.extractScope(result.publicInputs, result.circuit);
+     *   console.log('Scope:', scope);
+     * }
+     * ```
+     */
+    extractScope(publicInputs: string[], circuit: CircuitType): string | null;
+    /**
+     * Checks if a nullifier is already registered on-chain.
+     *
+     * Queries the ZKProofportNullifierRegistry contract to determine if the
+     * nullifier has been used before. Used to prevent duplicate proof submissions.
+     *
+     * Requires `nullifierRegistry` in SDK config.
+     *
+     * @param nullifier - Nullifier hex string from extractNullifier()
+     * @param provider - Optional ethers provider (defaults to public RPC for configured chain)
+     * @returns True if nullifier is already registered
+     * @throws Error if nullifierRegistry is not configured
+     *
+     * @example
+     * ```typescript
+     * const sdk = ProofportSDK.create({
+     *   relayUrl: 'https://relay.zkproofport.app',
+     *   nullifierRegistry: { address: '0x...', chainId: 8453 }
+     * });
+     *
+     * const nullifier = sdk.extractNullifier(publicInputs, circuit);
+     * const isDuplicate = await sdk.checkNullifier(nullifier);
+     * ```
+     */
+    checkNullifier(nullifier: string, provider?: any): Promise<boolean>;
+    /**
+     * Gets detailed information about a registered nullifier from on-chain registry.
+     *
+     * Retrieves the registration timestamp, scope, and circuit ID for a nullifier.
+     * Returns null if the nullifier is not registered.
+     *
+     * Requires `nullifierRegistry` in SDK config.
+     *
+     * @param nullifier - Nullifier hex string from extractNullifier()
+     * @param provider - Optional ethers provider (defaults to public RPC for configured chain)
+     * @returns Nullifier info or null if not registered
+     * @throws Error if nullifierRegistry is not configured
+     *
+     * @example
+     * ```typescript
+     * const info = await sdk.getNullifierDetails(nullifier);
+     * if (info) {
+     *   console.log('Registered at:', new Date(info.registeredAt * 1000));
+     *   console.log('Circuit:', info.circuitId);
+     * }
+     * ```
+     */
+    getNullifierDetails(nullifier: string, provider?: any): Promise<{
+        registeredAt: number;
+        scope: string;
+        circuitId: string;
+    } | null>;
+}
+export default ProofportSDK;