@provex/extension-react 1.0.16 → 1.2.3

package/dist/useZKTLS.d.cts

@@ -0,0 +1,298 @@
+import { Hex } from 'viem';
+import { IntentStruct } from '@provex/utils/intent';
+import { TokenInfo } from '@provex/utils/tokens';
+import { ActionType, PlatformKey, ProviderKey } from '@provex/utils/payment';
+
+/**
+ * @fileoverview React hook and utilities for PeerAuth browser extension integration.
+ *
+ * The PeerAuth extension (formerly ZK-TLS) provides secure proof generation
+ * for off-chain payment verification. This module provides:
+ *
+ * 1. Type definitions for extension API (window.peer)
+ * 2. useZKTLS hook for React components
+ * 3. Utility functions for transaction matching and proof encoding
+ *
+ * @remarks
+ * The extension exposes `window.peer` (or deprecated `window.zktls`) for:
+ * - Requesting connection (OAuth-like flow)
+ * - Authenticating with payment providers
+ * - Generating notarized proofs
+ * - Fetching transaction metadata
+ *
+ * @see {@link ZKTLSContext} for the React context provider
+ */
+
+declare global {
+    interface ZKTLS {
+        requestConnection(): Promise<boolean>;
+        checkConnectionStatus(): Promise<Status>;
+        getVersion(): Promise<string>;
+        authenticate(inputs: AuthenticationInputs): Promise<void>;
+        generateProof(inputs: GenerateProofInputs): Promise<GenerateProofResponse>;
+        fetchProofById(proofId: string): Promise<ProofResponse>;
+        fetchProofs(): Promise<FetchProofsResponse>;
+        openSidebar(route: string): Promise<void>;
+        onMetadataMessage(fn: (data: MetadataMessageResponse) => void): () => void;
+    }
+    interface Window {
+        /** @deprecated Use window.peer instead */
+        zktls: ZKTLS | undefined;
+        /** PeerAuth extension API (replaces window.zktls) */
+        peer: ZKTLS | undefined;
+    }
+}
+/** the status of the PeerAuth extension */
+type Status = 'connected' | 'disconnected' | 'pending';
+/** the individual metadata message sent by the PeerAuth extension */
+interface MetadataMessage {
+    amount: number;
+    /** Currency code (e.g., 'USD', 'EUR') */
+    currency?: string;
+    /**
+     * Date of the transaction.
+     * Can be a string in YYYYMMDD format, a number (YYYYMMDD or timestamp), or Date object.
+     * The actual type depends on the extension implementation.
+     */
+    date: string | number | Date;
+    hidden: boolean;
+    originalIndex: number;
+    paymentId: number;
+    recipient: string;
+}
+/** the response from the PeerAuth extension when a metadata message is received */
+interface MetadataMessageResponse {
+    expiresAt: number;
+    platform: ProviderKey;
+    requestId: string;
+    metadata: MetadataMessage[];
+}
+/** the response from the PeerAuth extension when fetching proofs */
+interface FetchProofsResponse {
+    notaryRequests: NotaryRequest[];
+}
+/** the inputs for the generateProof function */
+type GenerateProofInputsAbstracted = {
+    platform: PlatformKey;
+    provider: ProviderKey;
+    intentHash: Hex;
+    originalIndex: number;
+};
+/** the inputs for the generateProof function */
+type GenerateProofInputs = {
+    platform: ProviderKey;
+    originalIndex: number;
+    proofIndex?: number;
+    intentHash: string;
+};
+/**
+ * inputs for the generate proof function that requires the intent hash
+ * as hex to ensure it can be converted to a bigint string accurately
+ */
+type HexIntentGenerateProofInputs = Exclude<GenerateProofInputs, 'intentHash'> & {
+    intentHash: Hex;
+};
+/** the response from the PeerAuth extension when generating a proof */
+type GenerateProofResponse = {
+    proofId: string;
+    platform: ProviderKey;
+};
+/** the inputs for the authenticate function */
+type AuthenticationInputs = {
+    actionType: ActionType;
+    platform: PlatformKey;
+};
+/** the response from the PeerAuth extension when fetching a proof */
+interface Proof {
+    claimInfo: ClaimInfo;
+    signedClaim: SignedClaim;
+    isAppclipProof: boolean;
+    status: string;
+}
+/** the response from the PeerAuth extension when fetching a proof */
+interface NotarizedProof {
+    claim: {
+        context: string;
+        epoch: number;
+        identifier: Hex;
+        owner: Hex;
+        parameters: string;
+        provider: string;
+        timestampS: number;
+    };
+    signatures: {
+        attestorAddress: Hex;
+        claimSignature: Record<number, number>;
+        resultSignature: Record<number, number>;
+    };
+}
+/** the claim info for a proof */
+interface ClaimInfo {
+    provider: string;
+    parameters: string;
+    context: string;
+}
+/** the complete claim data for a proof */
+interface CompleteClaimData {
+    identifier: Hex;
+    owner: Hex;
+    timestampS: number;
+    epoch: number;
+}
+/** the signed claim for a proof */
+interface SignedClaim {
+    claim: CompleteClaimData;
+    signatures: Hex[];
+}
+/** the reclaim proof for a proof */
+type ReclaimProof = {
+    claimInfo: ClaimInfo;
+    signedClaim: SignedClaim;
+    isAppclipProof: boolean;
+};
+/** the notary request for a proof */
+interface NotaryRequest {
+    metadata: (string | number)[];
+    actionType: ActionType;
+    id: string;
+    status: string;
+    timestamp: number;
+    proof: NotarizedProof;
+}
+/** the response from the PeerAuth extension when fetching a proof */
+interface ProofResponse {
+    notaryRequest: NotaryRequest;
+}
+declare const extensionUrl = "https://chromewebstore.google.com/detail/ijpgccednehjpeclfcllnjjcmiohdjih";
+/** convert a byte array to a hex string */
+declare const byteArrayToHexString: (byteArray: number[]) => Hex;
+/** parse a proof object from the PeerAuth extension */
+declare const parseExtensionProof: (proofObject: NotarizedProof) => ReclaimProof;
+/** the abi encoding for a proof */
+declare const PROOF_ENCODING: {
+    readonly type: "tuple";
+    readonly components: readonly [{
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly type: "string";
+            readonly name: "provider";
+        }, {
+            readonly type: "string";
+            readonly name: "parameters";
+        }, {
+            readonly type: "string";
+            readonly name: "context";
+        }];
+        readonly name: "claimInfo";
+    }, {
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly type: "tuple";
+            readonly components: readonly [{
+                readonly type: "bytes32";
+                readonly name: "identifier";
+            }, {
+                readonly type: "address";
+                readonly name: "owner";
+            }, {
+                readonly type: "uint32";
+                readonly name: "timestampS";
+            }, {
+                readonly type: "uint32";
+                readonly name: "epoch";
+            }];
+            readonly name: "claim";
+        }, {
+            readonly type: "bytes[]";
+            readonly name: "signatures";
+        }];
+        readonly name: "signedClaim";
+    }, {
+        readonly type: "bool";
+        readonly name: "isAppclipProof";
+    }];
+};
+/** encode a single proof as a bytes array */
+declare function encodeProofAsBytes(proof: ReclaimProof): Hex;
+/** encode two proofs to be passed to the underlying sub-provider */
+declare const encodeTwoProofs: (proof1: ReclaimProof, proof2: ReclaimProof) => `0x${string}`;
+/** a high level function to encode a proof for a given provider and sub-provider */
+declare const encodeProof: ({ extensionProofs, subProvider, provider }: {
+    extensionProofs: NotarizedProof[];
+    subProvider: PlatformKey | null;
+    provider: ProviderKey;
+}) => `0x${string}`;
+/**
+ * wrap a proof with a payment method and proof
+ * this allows us to use a single verifier as an entry point for multiple underlying sub-providers
+ */
+declare const encodeProofWithPaymentMethod: ({ proof, paymentMethod }: {
+    proof: Hex;
+    paymentMethod: number;
+}) => Hex;
+/** the progress of a proof series */
+declare enum SeriesProgress {
+    Generating = 0,
+    Polling = 1,
+    Complete = 2
+}
+type ProgressInfo = {
+    progress: SeriesProgress;
+    total: number;
+    step: number | null;
+    id: string | null;
+};
+/** the mutations for the generate proof series function */
+type GenerateProofSeriesMutations = {
+    progress?: ({ progress, step, id }: ProgressInfo) => void;
+    setOwnerName?: (name: string) => void;
+};
+/** React hook to interact with the PeerAuth extension */
+declare const useZKTLS: () => {
+    /** check if the PeerAuth extension is initialized */
+    isInitialized: boolean;
+    /** request a connection to the PeerAuth extension */
+    requestConnection: () => Promise<boolean>;
+    /**
+     * check the connection status of the PeerAuth extension
+     * @returns the connection status
+     */
+    checkConnectionStatus: () => Promise<Status>;
+    /** get the version of the PeerAuth extension */
+    getVersion: () => Promise<string | undefined>;
+    /** authenticate with the PeerAuth extension */
+    authenticate: (inputs: AuthenticationInputs) => Promise<MetadataMessageResponse>;
+    /** generate a proof */
+    generateProof: (inputs: HexIntentGenerateProofInputs) => Promise<GenerateProofResponse>;
+    /** wait for a proof to be generated */
+    waitForProof: (proofId: string, onCurrent?: (notaryRequest: NotaryRequest | null) => void) => Promise<NotaryRequest>;
+    /** generate a proof series */
+    generateProofSeries: (inputs: GenerateProofInputsAbstracted, { progress: progressCallback }?: GenerateProofSeriesMutations) => Promise<NotaryRequest[]>;
+    /** subscribe to metadata messages */
+    onMetadataMessage: (fn: (data: any) => void) => () => void;
+    /** fetch a proof by its id */
+    fetchProofById: (proofId: string) => Promise<NotaryRequest | null>;
+    /** fetch generated proofs */
+    fetchGeneratedProofs: (genProofResponses: GenerateProofResponse[]) => Promise<(NotaryRequest | null)[]>;
+    /** fetch all proofs */
+    fetchProofs: () => Promise<FetchProofsResponse>;
+    /** open the PeerAuth sidebar */
+    openSidebar: (route: string) => Promise<void>;
+};
+/**
+ * Find the metadata message that matches the intent by amount.
+ * Returns the first (most recent) transaction in the metadata array that matches the expected amount.
+ *
+ * Simplified matching: just find transactions with the correct amount.
+ * The user can manually select if multiple matches exist.
+ */
+declare const findMetadataMessage: ({ metadata, intent, token, centIsInt }: {
+    metadata: MetadataMessage[];
+    intent: IntentStruct;
+    token: TokenInfo;
+    /** @deprecated No longer used - kept for API compatibility */
+    recipient?: string;
+    centIsInt?: boolean;
+}) => MetadataMessage | null;
+
+export { type AuthenticationInputs, type ClaimInfo, type CompleteClaimData, type FetchProofsResponse, type GenerateProofInputs, type GenerateProofInputsAbstracted, type GenerateProofResponse, type GenerateProofSeriesMutations, type HexIntentGenerateProofInputs, type MetadataMessage, type MetadataMessageResponse, type NotarizedProof, type NotaryRequest, PROOF_ENCODING, type ProgressInfo, type Proof, type ProofResponse, type ReclaimProof, SeriesProgress, type SignedClaim, type Status, byteArrayToHexString, encodeProof, encodeProofAsBytes, encodeProofWithPaymentMethod, encodeTwoProofs, extensionUrl, findMetadataMessage, parseExtensionProof, useZKTLS };

package/dist/useZKTLS.d.ts

@@ -0,0 +1,298 @@
+import { Hex } from 'viem';
+import { IntentStruct } from '@provex/utils/intent';
+import { TokenInfo } from '@provex/utils/tokens';
+import { ActionType, PlatformKey, ProviderKey } from '@provex/utils/payment';
+
+/**
+ * @fileoverview React hook and utilities for PeerAuth browser extension integration.
+ *
+ * The PeerAuth extension (formerly ZK-TLS) provides secure proof generation
+ * for off-chain payment verification. This module provides:
+ *
+ * 1. Type definitions for extension API (window.peer)
+ * 2. useZKTLS hook for React components
+ * 3. Utility functions for transaction matching and proof encoding
+ *
+ * @remarks
+ * The extension exposes `window.peer` (or deprecated `window.zktls`) for:
+ * - Requesting connection (OAuth-like flow)
+ * - Authenticating with payment providers
+ * - Generating notarized proofs
+ * - Fetching transaction metadata
+ *
+ * @see {@link ZKTLSContext} for the React context provider
+ */
+
+declare global {
+    interface ZKTLS {
+        requestConnection(): Promise<boolean>;
+        checkConnectionStatus(): Promise<Status>;
+        getVersion(): Promise<string>;
+        authenticate(inputs: AuthenticationInputs): Promise<void>;
+        generateProof(inputs: GenerateProofInputs): Promise<GenerateProofResponse>;
+        fetchProofById(proofId: string): Promise<ProofResponse>;
+        fetchProofs(): Promise<FetchProofsResponse>;
+        openSidebar(route: string): Promise<void>;
+        onMetadataMessage(fn: (data: MetadataMessageResponse) => void): () => void;
+    }
+    interface Window {
+        /** @deprecated Use window.peer instead */
+        zktls: ZKTLS | undefined;
+        /** PeerAuth extension API (replaces window.zktls) */
+        peer: ZKTLS | undefined;
+    }
+}
+/** the status of the PeerAuth extension */
+type Status = 'connected' | 'disconnected' | 'pending';
+/** the individual metadata message sent by the PeerAuth extension */
+interface MetadataMessage {
+    amount: number;
+    /** Currency code (e.g., 'USD', 'EUR') */
+    currency?: string;
+    /**
+     * Date of the transaction.
+     * Can be a string in YYYYMMDD format, a number (YYYYMMDD or timestamp), or Date object.
+     * The actual type depends on the extension implementation.
+     */
+    date: string | number | Date;
+    hidden: boolean;
+    originalIndex: number;
+    paymentId: number;
+    recipient: string;
+}
+/** the response from the PeerAuth extension when a metadata message is received */
+interface MetadataMessageResponse {
+    expiresAt: number;
+    platform: ProviderKey;
+    requestId: string;
+    metadata: MetadataMessage[];
+}
+/** the response from the PeerAuth extension when fetching proofs */
+interface FetchProofsResponse {
+    notaryRequests: NotaryRequest[];
+}
+/** the inputs for the generateProof function */
+type GenerateProofInputsAbstracted = {
+    platform: PlatformKey;
+    provider: ProviderKey;
+    intentHash: Hex;
+    originalIndex: number;
+};
+/** the inputs for the generateProof function */
+type GenerateProofInputs = {
+    platform: ProviderKey;
+    originalIndex: number;
+    proofIndex?: number;
+    intentHash: string;
+};
+/**
+ * inputs for the generate proof function that requires the intent hash
+ * as hex to ensure it can be converted to a bigint string accurately
+ */
+type HexIntentGenerateProofInputs = Exclude<GenerateProofInputs, 'intentHash'> & {
+    intentHash: Hex;
+};
+/** the response from the PeerAuth extension when generating a proof */
+type GenerateProofResponse = {
+    proofId: string;
+    platform: ProviderKey;
+};
+/** the inputs for the authenticate function */
+type AuthenticationInputs = {
+    actionType: ActionType;
+    platform: PlatformKey;
+};
+/** the response from the PeerAuth extension when fetching a proof */
+interface Proof {
+    claimInfo: ClaimInfo;
+    signedClaim: SignedClaim;
+    isAppclipProof: boolean;
+    status: string;
+}
+/** the response from the PeerAuth extension when fetching a proof */
+interface NotarizedProof {
+    claim: {
+        context: string;
+        epoch: number;
+        identifier: Hex;
+        owner: Hex;
+        parameters: string;
+        provider: string;
+        timestampS: number;
+    };
+    signatures: {
+        attestorAddress: Hex;
+        claimSignature: Record<number, number>;
+        resultSignature: Record<number, number>;
+    };
+}
+/** the claim info for a proof */
+interface ClaimInfo {
+    provider: string;
+    parameters: string;
+    context: string;
+}
+/** the complete claim data for a proof */
+interface CompleteClaimData {
+    identifier: Hex;
+    owner: Hex;
+    timestampS: number;
+    epoch: number;
+}
+/** the signed claim for a proof */
+interface SignedClaim {
+    claim: CompleteClaimData;
+    signatures: Hex[];
+}
+/** the reclaim proof for a proof */
+type ReclaimProof = {
+    claimInfo: ClaimInfo;
+    signedClaim: SignedClaim;
+    isAppclipProof: boolean;
+};
+/** the notary request for a proof */
+interface NotaryRequest {
+    metadata: (string | number)[];
+    actionType: ActionType;
+    id: string;
+    status: string;
+    timestamp: number;
+    proof: NotarizedProof;
+}
+/** the response from the PeerAuth extension when fetching a proof */
+interface ProofResponse {
+    notaryRequest: NotaryRequest;
+}
+declare const extensionUrl = "https://chromewebstore.google.com/detail/ijpgccednehjpeclfcllnjjcmiohdjih";
+/** convert a byte array to a hex string */
+declare const byteArrayToHexString: (byteArray: number[]) => Hex;
+/** parse a proof object from the PeerAuth extension */
+declare const parseExtensionProof: (proofObject: NotarizedProof) => ReclaimProof;
+/** the abi encoding for a proof */
+declare const PROOF_ENCODING: {
+    readonly type: "tuple";
+    readonly components: readonly [{
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly type: "string";
+            readonly name: "provider";
+        }, {
+            readonly type: "string";
+            readonly name: "parameters";
+        }, {
+            readonly type: "string";
+            readonly name: "context";
+        }];
+        readonly name: "claimInfo";
+    }, {
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly type: "tuple";
+            readonly components: readonly [{
+                readonly type: "bytes32";
+                readonly name: "identifier";
+            }, {
+                readonly type: "address";
+                readonly name: "owner";
+            }, {
+                readonly type: "uint32";
+                readonly name: "timestampS";
+            }, {
+                readonly type: "uint32";
+                readonly name: "epoch";
+            }];
+            readonly name: "claim";
+        }, {
+            readonly type: "bytes[]";
+            readonly name: "signatures";
+        }];
+        readonly name: "signedClaim";
+    }, {
+        readonly type: "bool";
+        readonly name: "isAppclipProof";
+    }];
+};
+/** encode a single proof as a bytes array */
+declare function encodeProofAsBytes(proof: ReclaimProof): Hex;
+/** encode two proofs to be passed to the underlying sub-provider */
+declare const encodeTwoProofs: (proof1: ReclaimProof, proof2: ReclaimProof) => `0x${string}`;
+/** a high level function to encode a proof for a given provider and sub-provider */
+declare const encodeProof: ({ extensionProofs, subProvider, provider }: {
+    extensionProofs: NotarizedProof[];
+    subProvider: PlatformKey | null;
+    provider: ProviderKey;
+}) => `0x${string}`;
+/**
+ * wrap a proof with a payment method and proof
+ * this allows us to use a single verifier as an entry point for multiple underlying sub-providers
+ */
+declare const encodeProofWithPaymentMethod: ({ proof, paymentMethod }: {
+    proof: Hex;
+    paymentMethod: number;
+}) => Hex;
+/** the progress of a proof series */
+declare enum SeriesProgress {
+    Generating = 0,
+    Polling = 1,
+    Complete = 2
+}
+type ProgressInfo = {
+    progress: SeriesProgress;
+    total: number;
+    step: number | null;
+    id: string | null;
+};
+/** the mutations for the generate proof series function */
+type GenerateProofSeriesMutations = {
+    progress?: ({ progress, step, id }: ProgressInfo) => void;
+    setOwnerName?: (name: string) => void;
+};
+/** React hook to interact with the PeerAuth extension */
+declare const useZKTLS: () => {
+    /** check if the PeerAuth extension is initialized */
+    isInitialized: boolean;
+    /** request a connection to the PeerAuth extension */
+    requestConnection: () => Promise<boolean>;
+    /**
+     * check the connection status of the PeerAuth extension
+     * @returns the connection status
+     */
+    checkConnectionStatus: () => Promise<Status>;
+    /** get the version of the PeerAuth extension */
+    getVersion: () => Promise<string | undefined>;
+    /** authenticate with the PeerAuth extension */
+    authenticate: (inputs: AuthenticationInputs) => Promise<MetadataMessageResponse>;
+    /** generate a proof */
+    generateProof: (inputs: HexIntentGenerateProofInputs) => Promise<GenerateProofResponse>;
+    /** wait for a proof to be generated */
+    waitForProof: (proofId: string, onCurrent?: (notaryRequest: NotaryRequest | null) => void) => Promise<NotaryRequest>;
+    /** generate a proof series */
+    generateProofSeries: (inputs: GenerateProofInputsAbstracted, { progress: progressCallback }?: GenerateProofSeriesMutations) => Promise<NotaryRequest[]>;
+    /** subscribe to metadata messages */
+    onMetadataMessage: (fn: (data: any) => void) => () => void;
+    /** fetch a proof by its id */
+    fetchProofById: (proofId: string) => Promise<NotaryRequest | null>;
+    /** fetch generated proofs */
+    fetchGeneratedProofs: (genProofResponses: GenerateProofResponse[]) => Promise<(NotaryRequest | null)[]>;
+    /** fetch all proofs */
+    fetchProofs: () => Promise<FetchProofsResponse>;
+    /** open the PeerAuth sidebar */
+    openSidebar: (route: string) => Promise<void>;
+};
+/**
+ * Find the metadata message that matches the intent by amount.
+ * Returns the first (most recent) transaction in the metadata array that matches the expected amount.
+ *
+ * Simplified matching: just find transactions with the correct amount.
+ * The user can manually select if multiple matches exist.
+ */
+declare const findMetadataMessage: ({ metadata, intent, token, centIsInt }: {
+    metadata: MetadataMessage[];
+    intent: IntentStruct;
+    token: TokenInfo;
+    /** @deprecated No longer used - kept for API compatibility */
+    recipient?: string;
+    centIsInt?: boolean;
+}) => MetadataMessage | null;
+
+export { type AuthenticationInputs, type ClaimInfo, type CompleteClaimData, type FetchProofsResponse, type GenerateProofInputs, type GenerateProofInputsAbstracted, type GenerateProofResponse, type GenerateProofSeriesMutations, type HexIntentGenerateProofInputs, type MetadataMessage, type MetadataMessageResponse, type NotarizedProof, type NotaryRequest, PROOF_ENCODING, type ProgressInfo, type Proof, type ProofResponse, type ReclaimProof, SeriesProgress, type SignedClaim, type Status, byteArrayToHexString, encodeProof, encodeProofAsBytes, encodeProofWithPaymentMethod, encodeTwoProofs, extensionUrl, findMetadataMessage, parseExtensionProof, useZKTLS };

package/dist/useZKTLS.js

@@ -0,0 +1,3 @@
+export { PROOF_ENCODING, SeriesProgress, byteArrayToHexString, encodeProof, encodeProofAsBytes, encodeProofWithPaymentMethod, encodeTwoProofs, extensionUrl, findMetadataMessage, parseExtensionProof, useZKTLS } from './chunk-DVOEKDW7.js';
+//# sourceMappingURL=useZKTLS.js.map
+//# sourceMappingURL=useZKTLS.js.map

package/dist/useZKTLS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"useZKTLS.js"}

package/dist/useZKTLSContext.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+var react = require('react');
+var viem = require('viem');
+require('@provex/utils/time');
+require('@provex/utils/payment');
+require('@provex/utils/conversionRates');
+require('react/jsx-runtime');
+
+// src/ZKTLSContext.tsx
+viem.parseAbiParameter("((string provider, string parameters, string context) claimInfo, ((bytes32 identifier, address owner, uint32 timestampS, uint32 epoch) claim, bytes[] signatures) signedClaim, bool isAppclipProof)");
+var ZKTLSContext = react.createContext(void 0);
+function useZKTLSContext() {
+  const context = react.useContext(ZKTLSContext);
+  if (context === void 0) {
+    throw new Error("useZKTLSContext must be used within a ZKTLSProvider");
+  }
+  return context;
+}
+
+exports.useZKTLSContext = useZKTLSContext;
+//# sourceMappingURL=useZKTLSContext.cjs.map
+//# sourceMappingURL=useZKTLSContext.cjs.map

package/dist/useZKTLSContext.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useZKTLS.ts","../src/ZKTLSContext.tsx"],"names":["parseAbiParameter","createContext","useContext"],"mappings":";;;;;;;;;;AAuN8BA,uBAAkB,qMAAqM;ACtM9O,IAAM,YAAA,GAAeC,oBAA4C,MAAS,CAAA;AAY1E,SAAS,eAAA,GAAkB;AAChC,EAAA,MAAM,OAAA,GAAUC,iBAAW,YAAY,CAAA;AACvC,EAAA,IAAI,YAAY,MAAA,EAAW;AACzB,IAAA,MAAM,IAAI,MAAM,qDAAqD,CAAA;AAAA,EACvE;AACA,EAAA,OAAO,OAAA;AACT","file":"useZKTLSContext.cjs","sourcesContent":["/**\n * @fileoverview React hook and utilities for PeerAuth browser extension integration.\n *\n * The PeerAuth extension (formerly ZK-TLS) provides secure proof generation\n * for off-chain payment verification. This module provides:\n *\n * 1. Type definitions for extension API (window.peer)\n * 2. useZKTLS hook for React components\n * 3. Utility functions for transaction matching and proof encoding\n *\n * @remarks\n * The extension exposes `window.peer` (or deprecated `window.zktls`) for:\n * - Requesting connection (OAuth-like flow)\n * - Authenticating with payment providers\n * - Generating notarized proofs\n * - Fetching transaction metadata\n *\n * @see {@link ZKTLSContext} for the React context provider\n */\n\nimport { useEffect, useMemo, useState } from \"react\"\nimport { encodeAbiParameters, encodePacked, parseAbiParameter, parseUnits, type Hex } from \"viem\"\nimport { sleep } from \"@provex/utils/time\"\nimport type { IntentStruct } from \"@provex/utils/intent\"\nimport type { TokenInfo } from \"@provex/utils/tokens\"\nimport { extensionPlatforms, providers, subProviderConfigs, type ActionType, type PlatformKey, type ProviderKey, type SubProviderKey } from \"@provex/utils/payment\"\nimport { convertTokenInputToCurrency } from \"@provex/utils/conversionRates\"\n\ndeclare global {\n  interface ZKTLS {\n    requestConnection(): Promise<boolean>\n    checkConnectionStatus(): Promise<Status>\n    getVersion(): Promise<string>\n    authenticate(inputs: AuthenticationInputs): Promise<void>\n    generateProof(inputs: GenerateProofInputs): Promise<GenerateProofResponse>\n    fetchProofById(proofId: string): Promise<ProofResponse>\n    fetchProofs(): Promise<FetchProofsResponse>\n    openSidebar(route: string): Promise<void>\n    onMetadataMessage(fn: (data: MetadataMessageResponse) => void): () => void\n  }\n  interface Window {\n    /** @deprecated Use window.peer instead */\n    zktls: ZKTLS | undefined\n    /** PeerAuth extension API (replaces window.zktls) */\n    peer: ZKTLS | undefined\n  }\n}\n\n/** the status of the PeerAuth extension */\nexport type Status = 'connected' | 'disconnected' | 'pending'\n\n/** the individual metadata message sent by the PeerAuth extension */\nexport interface MetadataMessage {\n  amount: number\n  /** Currency code (e.g., 'USD', 'EUR') */\n  currency?: string\n  /**\n   * Date of the transaction.\n   * Can be a string in YYYYMMDD format, a number (YYYYMMDD or timestamp), or Date object.\n   * The actual type depends on the extension implementation.\n   */\n  date: string | number | Date\n  hidden: boolean\n  originalIndex: number\n  paymentId: number\n  recipient: string\n}\n\n/** the response from the PeerAuth extension when a metadata message is received */\nexport interface MetadataMessageResponse {\n  expiresAt: number\n  platform: ProviderKey\n  requestId: string\n  metadata: MetadataMessage[]\n}\n\n/** the response from the PeerAuth extension when fetching proofs */\nexport interface FetchProofsResponse {\n  notaryRequests: NotaryRequest[]\n}\n\n/** the inputs for the generateProof function */\nexport type GenerateProofInputsAbstracted = {\n  platform: PlatformKey\n  provider: ProviderKey\n  intentHash: Hex\n  originalIndex: number\n}\n\n/** the inputs for the generateProof function */\nexport type GenerateProofInputs = {\n  platform: ProviderKey\n  originalIndex: number\n  proofIndex?: number\n  intentHash: string\n}\n\n/**\n * inputs for the generate proof function that requires the intent hash\n * as hex to ensure it can be converted to a bigint string accurately\n */\nexport type HexIntentGenerateProofInputs = Exclude<GenerateProofInputs, 'intentHash'> & { intentHash: Hex }\n\n/** the response from the PeerAuth extension when generating a proof */\nexport type GenerateProofResponse = {\n  proofId: string\n  platform: ProviderKey\n}\n\n/** the inputs for the authenticate function */\nexport type AuthenticationInputs = {\n  actionType: ActionType\n  platform: PlatformKey\n}\n\n/** the response from the PeerAuth extension when fetching a proof */\nexport interface Proof {\n  claimInfo: ClaimInfo\n  signedClaim: SignedClaim\n  isAppclipProof: boolean\n  status: string\n}\n\n/** the response from the PeerAuth extension when fetching a proof */\nexport interface NotarizedProof {\n  claim: {\n    context: string\n    epoch: number\n    identifier: Hex\n    owner: Hex\n    parameters: string\n    provider: string\n    timestampS: number\n  },\n  signatures: {\n    attestorAddress: Hex\n    claimSignature: Record<number, number>\n    resultSignature: Record<number, number>\n  },\n}\n\n/** the claim info for a proof */\nexport interface ClaimInfo {\n  provider: string\n  parameters: string\n  context: string\n}\n\n/** the complete claim data for a proof */\nexport interface CompleteClaimData {\n  identifier: Hex\n  owner: Hex\n  timestampS: number\n  epoch: number\n}\n\n/** the signed claim for a proof */\nexport interface SignedClaim {\n  claim: CompleteClaimData\n  signatures: Hex[]\n}\n\n/** the reclaim proof for a proof */\nexport type ReclaimProof = {\n  claimInfo: ClaimInfo\n  signedClaim: SignedClaim\n  isAppclipProof: boolean\n}\n\n/** the notary request for a proof */\nexport interface NotaryRequest {\n  metadata: (string | number)[]\n  actionType: ActionType\n  id: string\n  status: string\n  timestamp: number\n  proof: NotarizedProof\n}\n\n/** the response from the PeerAuth extension when fetching a proof */\nexport interface ProofResponse {\n  notaryRequest: NotaryRequest\n}\n\nexport const extensionUrl = 'https://chromewebstore.google.com/detail/ijpgccednehjpeclfcllnjjcmiohdjih'\n\n/** convert a byte array to a hex string */\nexport const byteArrayToHexString = (byteArray: number[]): Hex => {\n  return `0x${byteArray\n    .map(byte => byte.toString(16).padStart(2, '0'))\n    .join('')}`\n}\n\n/** parse a proof object from the PeerAuth extension */\nexport const parseExtensionProof = (proofObject: NotarizedProof) => {\n  return {\n    claimInfo: {\n      provider: proofObject.claim.provider,\n      parameters: proofObject.claim.parameters,\n      context: proofObject.claim.context\n    },\n    signedClaim: {\n      claim: {\n        identifier: proofObject.claim.identifier as Hex,\n        owner: proofObject.claim.owner as Hex,\n        timestampS: proofObject.claim.timestampS,\n        epoch: proofObject.claim.epoch\n      },\n      signatures: [byteArrayToHexString(Object.values(proofObject.signatures.claimSignature))]\n    },\n    isAppclipProof: false\n  } as ReclaimProof\n}\n\n/** the abi encoding for a proof */\nexport const PROOF_ENCODING = parseAbiParameter(\"((string provider, string parameters, string context) claimInfo, ((bytes32 identifier, address owner, uint32 timestampS, uint32 epoch) claim, bytes[] signatures) signedClaim, bool isAppclipProof)\")\n\n/** encode a single proof as a bytes array */\nexport function encodeProofAsBytes(proof: ReclaimProof): Hex {\n  return encodeAbiParameters([PROOF_ENCODING], [proof])\n}\n\n/** encode two proofs to be passed to the underlying sub-provider */\nexport const encodeTwoProofs = (proof1: ReclaimProof, proof2: ReclaimProof) => {\n  return encodeAbiParameters([PROOF_ENCODING, PROOF_ENCODING], [proof1, proof2])\n}\n\n/** a high level function to encode a proof for a given provider and sub-provider */\nexport const encodeProof = ({ extensionProofs, subProvider, provider }: {\n  extensionProofs: NotarizedProof[],\n  subProvider: PlatformKey | null,\n  provider: ProviderKey\n}) => {\n  const reclaimProofs = extensionProofs.map((p) => parseExtensionProof(p))\n  if (provider === 'zelle') {\n    // move this to check the blockchain for the payment method\n    const paymentMethod = subProviderConfigs![provider]![subProvider as SubProviderKey]!.paymentMethod\n    const twoEncoded = reclaimProofs.length === 2\n      ? encodeTwoProofs(reclaimProofs[0]!, reclaimProofs[1]!)\n      : encodeProofAsBytes(reclaimProofs[0]!)\n    // select between various possible sub-providers\n    const withPaymentMethod = encodeProofWithPaymentMethod({\n      paymentMethod,\n      proof: twoEncoded,\n    })\n    return withPaymentMethod\n  }\n  const [reclaimProof] = reclaimProofs\n  return encodeProofAsBytes(reclaimProof!)\n}\n\n/**\n * wrap a proof with a payment method and proof\n * this allows us to use a single verifier as an entry point for multiple underlying sub-providers\n */\nexport const encodeProofWithPaymentMethod = ({\n  proof,\n  paymentMethod\n}: {\n  proof: Hex,\n  paymentMethod: number\n}): Hex => {\n  return encodePacked(['uint8', 'bytes'], [paymentMethod, proof])\n}\n\n/** the progress of a proof series */\nexport enum SeriesProgress {\n  Generating,\n  Polling,\n  Complete,\n}\n\nexport type ProgressInfo = {\n  progress: SeriesProgress\n  total: number\n  step: number | null\n  id: string | null\n}\n\n/** the mutations for the generate proof series function */\nexport type GenerateProofSeriesMutations = {\n  progress?: ({ progress, step, id }: ProgressInfo) => void\n  setOwnerName?: (name: string) => void\n}\n\n/** React hook to interact with the PeerAuth extension */\nexport const useZKTLS = () => {\n  const [isInitialized, setIsInitialized] = useState(false)\n  useEffect(() => {\n    const setup = () => {\n      setIsInitialized(true)\n    }\n    const eventName = 'peer#initialized'\n    if (typeof window.peer !== 'undefined') {\n      // api is available\n      setup()\n    } else {\n      window.addEventListener(eventName, setup)\n      return () => {\n        window.removeEventListener(eventName, setup)\n      }\n    }\n  }, [])\n  return useMemo(() => {\n    /** fetch a proof by its id */\n    const fetchProofById = async (proofId: string): Promise<NotaryRequest | null> => {\n      const proof = await window.peer!.fetchProofById(proofId)\n      if (proof && proof.notaryRequest) return proof.notaryRequest\n      const proofs = await window.peer!.fetchProofs()\n      const proofFromList = proofs.notaryRequests.find((p) => p.id === proofId)\n      if (proofFromList) return proofFromList\n      return null\n    }\n    /** wait for a proof to be generated */\n    const waitForProof = async (proofId: string, onCurrent?: (notaryRequest: NotaryRequest | null) => void) => {\n      let notaryRequest: NotaryRequest | null = null\n      do {\n        notaryRequest = await fetchProofById(proofId)\n        onCurrent?.(notaryRequest)\n        await sleep(1_000)\n      } while (!notaryRequest || !notaryRequest.status || notaryRequest.status === 'pending')\n      if (notaryRequest.status === 'failed' || notaryRequest.status === 'expired' || notaryRequest.status === 'cancelled' || notaryRequest.status === 'error') {\n        throw new Error(`Proof generation failed: ${notaryRequest.status}`)\n      }\n      return notaryRequest\n    }\n    /** generate a proof */\n    const generateProof = async (inputs: HexIntentGenerateProofInputs): Promise<GenerateProofResponse> => {\n      return await window.peer!.generateProof({\n        proofIndex: 0,\n        ...inputs,\n        intentHash: BigInt(inputs.intentHash).toString(),\n      })\n    }\n    return {\n      /** check if the PeerAuth extension is initialized */\n      isInitialized,\n      /** request a connection to the PeerAuth extension */\n      requestConnection: async () => {\n        if (!window.peer) return false\n        return window.peer!.requestConnection()\n      },\n      /**\n       * check the connection status of the PeerAuth extension\n       * @returns the connection status\n       */\n      checkConnectionStatus: async () => {\n        return await window.peer!.checkConnectionStatus()\n      },\n      /** get the version of the PeerAuth extension */\n      getVersion: async () => {\n        return await window.peer?.getVersion()\n      },\n      /** authenticate with the PeerAuth extension */\n      authenticate: async (inputs: AuthenticationInputs) => {\n        // Create promise first to avoid race condition where message arrives before resolver is assigned\n        let resolve: (value: MetadataMessageResponse) => void\n        const promise = new Promise<MetadataMessageResponse>((resolver) => {\n          resolve = resolver\n        })\n\n        // Now set up the listener - resolve is guaranteed to be the real resolver\n        const unsub = window.peer!.onMetadataMessage((data) => {\n          if (`transfer_${data.platform}` === inputs.actionType) {\n            resolve(data)\n          }\n        })\n\n        await window.peer!.authenticate(inputs)\n\n        return await promise.then((data) => {\n          unsub()\n          return data\n        })\n      },\n      /** generate a proof */\n      generateProof,\n      /** wait for a proof to be generated */\n      waitForProof,\n      /** generate a proof series */\n      generateProofSeries: async (\n        inputs: GenerateProofInputsAbstracted,\n        { progress: progressCallback }: GenerateProofSeriesMutations = {},\n      ): Promise<NotaryRequest[]> => {\n        const { platform, provider, intentHash, originalIndex } = inputs\n        const args = {\n          platform: provider,\n          originalIndex,\n          intentHash,\n        } as const\n        // Chase requires 2 proofs (account verification + transaction)\n        // Platform is the bank name (e.g., 'chase') from extensionPlatform config\n        const isChase = platform === extensionPlatforms.CHASE\n        const isZelle = provider === providers.ZELLE\n        const expectedTotal = isZelle && isChase ? 2 : 1\n        progressCallback?.({ progress: SeriesProgress.Generating, step: 0, id: null, total: expectedTotal })\n        const genProofA = await generateProof({ ...args, proofIndex: 0 })\n        progressCallback?.({ progress: SeriesProgress.Polling, step: 0, id: genProofA.proofId, total: expectedTotal })\n        const proofA = await waitForProof(genProofA.proofId)\n        if (!isChase || !isZelle) {\n          progressCallback?.({ progress: SeriesProgress.Complete, step: null, id: null, total: expectedTotal })\n          return [proofA]\n        }\n        progressCallback?.({ progress: SeriesProgress.Generating, step: 1, id: null, total: expectedTotal })\n        const genProofB = await generateProof({ ...args, proofIndex: 1 })\n        progressCallback?.({ progress: SeriesProgress.Polling, step: 1, id: genProofB.proofId, total: expectedTotal })\n        const proofB = await waitForProof(genProofB.proofId)\n        progressCallback?.({ progress: SeriesProgress.Complete, step: null, id: null, total: expectedTotal })\n        return [proofA, proofB]\n      },\n      /** subscribe to metadata messages */\n      onMetadataMessage: (fn: (data: any) => void) => {\n        return window.peer!.onMetadataMessage(fn)\n      },\n      /** fetch a proof by its id */\n      fetchProofById,\n      /** fetch generated proofs */\n      fetchGeneratedProofs: async (genProofResponses: GenerateProofResponse[]) => {\n        return await Promise.all(genProofResponses.map((r) => fetchProofById(r.proofId)))\n      },\n      /** fetch all proofs */\n      fetchProofs: async () => {\n        return await window.peer!.fetchProofs()\n      },\n      /** open the PeerAuth sidebar */\n      openSidebar: async (route: string) => {\n        return await window.peer!.openSidebar(route)\n      },\n    }\n  }, [isInitialized])\n}\n\n/**\n * Find the metadata message that matches the intent by amount.\n * Returns the first (most recent) transaction in the metadata array that matches the expected amount.\n *\n * Simplified matching: just find transactions with the correct amount.\n * The user can manually select if multiple matches exist.\n */\nexport const findMetadataMessage = ({ metadata, intent, token, centIsInt = false }: {\n  metadata: MetadataMessage[],\n  intent: IntentStruct,\n  token: TokenInfo,\n  /** @deprecated No longer used - kept for API compatibility */\n  recipient?: string,\n  centIsInt?: boolean,\n}): MetadataMessage | null => {\n  const currencyAmount = convertTokenInputToCurrency({\n    token,\n    amountOutInt: intent.amount,\n    rate: intent.conversionRate,\n  })\n  /**\n   * Normalize an amount from the extension into a bigint in token base units.\n   *\n   * The extension sends amounts in different formats per provider:\n   * - Venmo: `\"- $1.00\"` (formatted dollar string)\n   * - Others: `100` (integer cents) or `1.00` (decimal dollars)\n   *\n   * We detect the format by checking for currency symbols or decimal points\n   * in the raw value. If present, the value is already in dollars and we\n   * skip the centIsInt division.\n   */\n  const normalizeAmount = (amount: number | string): bigint => {\n    const raw = String(amount)\n    const isFormattedDollars = /[^0-9\\-]/.test(raw) && raw.includes('.')\n    const cleaned = raw.replace(/[^0-9.]/g, '')\n    let value = parseUnits(cleaned, token.decimals)\n    if (centIsInt && !isFormattedDollars) {\n      value = value / 100n\n    }\n    return value\n  }\n\n  // Skip auto-match when manual selection is forced (dev/testing)\n  if (typeof window !== 'undefined' && (window as unknown as Record<string, unknown>).__FORCE_MANUAL_TX_SELECT__) {\n    return null\n  }\n\n  // Find the first transaction that matches the amount (first in array = most recent)\n  // Note: We ignore the hidden flag - matching is purely by amount\n  const match = metadata.find((m) => {\n    const converted = normalizeAmount(m.amount)\n    return converted === currencyAmount || converted === (currencyAmount * -1n)\n  })\n\n  if (!match) {\n    return null\n  }\n\n  return match\n}\n","/**\n * @fileoverview React context for PeerAuth extension state.\n *\n * Provides global access to the useZKTLS hook state throughout the\n * component tree, avoiding prop drilling for extension status.\n *\n * @see {@link useZKTLS} for the underlying hook\n */\n\nimport { createContext, useContext, type ReactNode } from 'react'\nimport { useZKTLS } from './useZKTLS'\n\n/**\n * Context type derived from useZKTLS hook return value.\n */\ntype ZKTLSContextType = ReturnType<typeof useZKTLS>\n\nexport const ZKTLSContext = createContext<ZKTLSContextType | undefined>(undefined)\n\ninterface ZKTLSProviderProps {\n  children: ReactNode\n}\n\n/**\n * Hook to consume the ZKTLS context.\n * Must be used within a ZKTLSProvider.\n *\n * @throws Error if used outside of ZKTLSProvider\n */\nexport function useZKTLSContext() {\n  const context = useContext(ZKTLSContext)\n  if (context === undefined) {\n    throw new Error('useZKTLSContext must be used within a ZKTLSProvider')\n  }\n  return context\n}\n\nexport function ZKTLSProvider({ children }: ZKTLSProviderProps) {\n  const zktlsHook = useZKTLS()\n\n  return (\n    <ZKTLSContext.Provider value={zktlsHook}>\n      {children}\n    </ZKTLSContext.Provider>\n  )\n}\n"]}

package/dist/useZKTLSContext.d.cts

@@ -0,0 +1,8 @@
+export { useZKTLSContext } from './ZKTLSContext.cjs';
+import './useZKTLS.cjs';
+import 'viem';
+import '@provex/utils/intent';
+import '@provex/utils/tokens';
+import '@provex/utils/payment';
+import 'react/jsx-runtime';
+import 'react';