@p2pdotme/sdk 1.0.0

package/dist/react.d.cts

@@ -0,0 +1,511 @@
+import * as neverthrow from 'neverthrow';
+import { Result, ResultAsync } from 'neverthrow';
+import { Address } from 'viem';
+import { z } from 'zod';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+declare class SdkError<TCode extends string = string> extends Error {
+    readonly code: TCode;
+    readonly cause?: unknown;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, options: {
+        code: TCode;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+
+declare const ZodCurrencySchema: z.ZodEnum<{
+    IDR: "IDR";
+    INR: "INR";
+    BRL: "BRL";
+    ARS: "ARS";
+    MEX: "MEX";
+    VEN: "VEN";
+    EUR: "EUR";
+    NGN: "NGN";
+    USD: "USD";
+}>;
+type CurrencyType = z.infer<typeof ZodCurrencySchema>;
+
+type ZkkycErrorCode = "VALIDATION_ERROR" | "CONTRACT_READ_ERROR" | "ENCODE_ERROR" | "RECLAIM_INIT_FAILED" | "RECLAIM_SESSION_NOT_FOUND" | "RECLAIM_PROOF_GENERATION_FAILED" | "RECLAIM_PROOF_INVALID" | "RECLAIM_POLLING_ABORTED" | "ZK_PASSPORT_INIT_FAILED" | "ZK_PASSPORT_REJECTED" | "ZK_PASSPORT_VERIFICATION_FAILED" | "ZK_PASSPORT_ABORTED" | "PEER_DEPENDENCY_MISSING";
+declare class ZkkycError extends SdkError<ZkkycErrorCode> {
+    constructor(message: string, options: {
+        code: ZkkycErrorCode;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+
+declare const ZodAnonAadharProofParamsSchema: z.ZodObject<{
+    nullifierSeed: z.ZodBigInt;
+    nullifier: z.ZodBigInt;
+    timestamp: z.ZodBigInt;
+    signal: z.ZodBigInt;
+    revealArray: z.ZodTuple<[z.ZodBigInt, z.ZodBigInt, z.ZodBigInt, z.ZodBigInt], null>;
+    packedGroth16Proof: z.ZodTuple<[z.ZodBigInt, z.ZodBigInt, z.ZodBigInt, z.ZodBigInt, z.ZodBigInt, z.ZodBigInt, z.ZodBigInt, z.ZodBigInt], null>;
+}, z.core.$strip>;
+type AnonAadharProofParams = z.infer<typeof ZodAnonAadharProofParamsSchema>;
+declare const ZodSocialVerifyParamsSchema: z.ZodObject<{
+    _socialName: z.ZodString;
+    proofs: z.ZodArray<z.ZodObject<{
+        claimInfo: z.ZodObject<{
+            provider: z.ZodString;
+            parameters: z.ZodString;
+            context: z.ZodString;
+        }, z.core.$strip>;
+        signedClaim: z.ZodObject<{
+            claim: z.ZodObject<{
+                identifier: z.ZodString;
+                owner: z.ZodString & z.ZodType<`0x${string}`, string, z.core.$ZodTypeInternals<`0x${string}`, string>>;
+                timestampS: z.ZodNumber;
+                epoch: z.ZodNumber;
+            }, z.core.$strip>;
+            signatures: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type SocialVerifyParams = z.infer<typeof ZodSocialVerifyParamsSchema>;
+declare const ZodZkPassportRegisterParamsSchema: z.ZodObject<{
+    params: z.ZodObject<{
+        version: z.ZodString;
+        proofVerificationData: z.ZodObject<{
+            vkeyHash: z.ZodString;
+            proof: z.ZodString;
+            publicInputs: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        committedInputs: z.ZodString;
+        serviceConfig: z.ZodObject<{
+            validityPeriodInSeconds: z.ZodNumber;
+            domain: z.ZodString;
+            scope: z.ZodString;
+            devMode: z.ZodBoolean;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    isIDCard: z.ZodBoolean;
+}, z.core.$strip>;
+type ZkPassportRegisterParams = z.infer<typeof ZodZkPassportRegisterParamsSchema>;
+
+interface Zkkyc {
+    prepareSocialVerify(params: SocialVerifyParams): Result<{
+        to: Address;
+        data: `0x${string}`;
+    }, ZkkycError>;
+    prepareSubmitAnonAadharProof(params: AnonAadharProofParams): Result<{
+        to: Address;
+        data: `0x${string}`;
+    }, ZkkycError>;
+    prepareZkPassportRegister(params: ZkPassportRegisterParams): Result<{
+        to: Address;
+        data: `0x${string}`;
+    }, ZkkycError>;
+}
+
+type PayloadErrorCode = "VALIDATION_ERROR" | "CIRCLE_SELECTION_ERROR" | "ENCRYPTION_ERROR" | "DECRYPTION_ERROR";
+declare class PayloadError extends SdkError<PayloadErrorCode> {
+    constructor(message: string, options: {
+        code: PayloadErrorCode;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+
+type OrderRoutingErrorCode = "NO_ELIGIBLE_CIRCLES" | "SUBGRAPH_ERROR" | "SUBGRAPH_NOT_CONFIGURED" | "VALIDATION_ERROR" | "CONTRACT_READ_ERROR";
+declare class OrderRoutingError extends SdkError<OrderRoutingErrorCode> {
+    constructor(message: string, options: {
+        code: OrderRoutingErrorCode;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+
+interface Logger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+
+/**
+ * Minimal viem PublicClient interface — consumers pass their own client.
+ * The SDK only needs `readContract` for on-chain reads.
+ */
+interface PublicClientLike {
+    readContract(args: {
+        address: Address;
+        abi: readonly unknown[];
+        functionName: string;
+        args: readonly unknown[];
+    }): Promise<unknown>;
+}
+
+interface SelectCircleParams {
+    readonly currency: string;
+    readonly user: Address;
+    readonly usdtAmount: bigint;
+    readonly fiatAmount: bigint;
+    readonly orderType: bigint;
+    readonly preferredPCConfigId: bigint;
+}
+
+interface OrderRouter {
+    /**
+     * Full flow: fetch circles from subgraph → epsilon-greedy selection →
+     * on-chain eligibility validation → return circleId.
+     */
+    selectCircle(params: SelectCircleParams): ResultAsync<bigint, OrderRoutingError>;
+}
+
+interface PlaceOrderPayload {
+    readonly pubKey: string;
+    readonly amount: bigint;
+    readonly recipientAddr: `0x${string}`;
+    readonly orderType: number;
+    readonly userUpi: string;
+    readonly userPubKey: string;
+    readonly currency: CurrencyType;
+    readonly preferredPaymentChannelConfigId: bigint;
+    readonly fiatAmountLimit: bigint;
+    readonly circleId: bigint;
+}
+interface SetSellOrderUpiPayload {
+    readonly orderId: number;
+    readonly userEncUpi: string;
+    readonly updatedAmount: bigint;
+}
+
+declare const ZodPlaceOrderParamsSchema: z.ZodObject<{
+    amount: z.ZodBigInt;
+    recipientAddr: z.ZodString & z.ZodType<`0x${string}`, string, z.core.$ZodTypeInternals<`0x${string}`, string>>;
+    orderType: z.ZodNumber;
+    currency: z.ZodEnum<{
+        IDR: "IDR";
+        INR: "INR";
+        BRL: "BRL";
+        ARS: "ARS";
+        MEX: "MEX";
+        VEN: "VEN";
+        EUR: "EUR";
+        NGN: "NGN";
+        USD: "USD";
+    }>;
+    fiatAmount: z.ZodBigInt;
+    user: z.ZodString & z.ZodType<`0x${string}`, string, z.core.$ZodTypeInternals<`0x${string}`, string>>;
+    pubKey: z.ZodOptional<z.ZodString>;
+    preferredPaymentChannelConfigId: z.ZodOptional<z.ZodBigInt>;
+    fiatAmountLimit: z.ZodDefault<z.ZodOptional<z.ZodBigInt>>;
+}, z.core.$strip>;
+type PlaceOrderParams = z.input<typeof ZodPlaceOrderParamsSchema>;
+declare const ZodSetSellOrderUpiParamsSchema: z.ZodObject<{
+    orderId: z.ZodNumber;
+    paymentAddress: z.ZodString;
+    merchantPublicKey: z.ZodString;
+    updatedAmount: z.ZodBigInt;
+}, z.core.$strip>;
+type SetSellOrderUpiParams = z.infer<typeof ZodSetSellOrderUpiParamsSchema>;
+
+interface PayloadGenerator {
+    placeOrder(params: PlaceOrderParams): ResultAsync<PlaceOrderPayload, PayloadError>;
+    setSellOrderUpi(params: SetSellOrderUpiParams): ResultAsync<SetSellOrderUpiPayload, PayloadError>;
+}
+
+type ProfileErrorCode = "VALIDATION_ERROR" | "CONTRACT_READ_ERROR";
+declare class ProfileError extends SdkError<ProfileErrorCode> {
+    constructor(message: string, options: {
+        code: ProfileErrorCode;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+
+declare const ZodUsdcBalanceParamsSchema: z.ZodObject<{
+    address: z.ZodString & z.ZodType<`0x${string}`, string, z.core.$ZodTypeInternals<`0x${string}`, string>>;
+}, z.core.$strip>;
+type UsdcBalanceParams = z.infer<typeof ZodUsdcBalanceParamsSchema>;
+declare const ZodGetBalancesParamsSchema: z.ZodObject<{
+    address: z.ZodString & z.ZodType<`0x${string}`, string, z.core.$ZodTypeInternals<`0x${string}`, string>>;
+    currency: z.ZodEnum<{
+        IDR: "IDR";
+        INR: "INR";
+        BRL: "BRL";
+        ARS: "ARS";
+        MEX: "MEX";
+        VEN: "VEN";
+        EUR: "EUR";
+        NGN: "NGN";
+        USD: "USD";
+    }>;
+}, z.core.$strip>;
+type GetBalancesParams = z.infer<typeof ZodGetBalancesParamsSchema>;
+declare const ZodTxLimitsParamsSchema: z.ZodObject<{
+    address: z.ZodString & z.ZodType<`0x${string}`, string, z.core.$ZodTypeInternals<`0x${string}`, string>>;
+    currency: z.ZodEnum<{
+        IDR: "IDR";
+        INR: "INR";
+        BRL: "BRL";
+        ARS: "ARS";
+        MEX: "MEX";
+        VEN: "VEN";
+        EUR: "EUR";
+        NGN: "NGN";
+        USD: "USD";
+    }>;
+}, z.core.$strip>;
+type TxLimitsParams = z.infer<typeof ZodTxLimitsParamsSchema>;
+declare const ZodPriceConfigParamsSchema: z.ZodObject<{
+    currency: z.ZodEnum<{
+        IDR: "IDR";
+        INR: "INR";
+        BRL: "BRL";
+        ARS: "ARS";
+        MEX: "MEX";
+        VEN: "VEN";
+        EUR: "EUR";
+        NGN: "NGN";
+        USD: "USD";
+    }>;
+}, z.core.$strip>;
+type PriceConfigParams = z.infer<typeof ZodPriceConfigParamsSchema>;
+
+interface TxLimits {
+    readonly buyLimit: number;
+    readonly sellLimit: number;
+}
+interface RpPerUsdtLimit {
+    readonly numerator: bigint;
+    readonly denominator: bigint;
+    /** The USDC multiplier per RP: denominator / numerator. */
+    readonly multiplier: number;
+}
+
+interface Balances {
+    /** USDC balance formatted to a number. */
+    readonly usdc: number;
+    /** Fiat equivalent: usdc * sellPrice. */
+    readonly fiat: number;
+    /** The sell price used for conversion. */
+    readonly sellPrice: number;
+}
+interface PriceConfig {
+    readonly buyPrice: bigint;
+    readonly sellPrice: bigint;
+    readonly buyPriceOffset: bigint;
+    readonly baseSpread: bigint;
+}
+
+interface Profile {
+    /** Reads the USDC balance for a given address (raw bigint, 6 decimals). */
+    getUsdcBalance(params: UsdcBalanceParams): ResultAsync<bigint, ProfileError>;
+    /** Reads buy/sell price config for a given currency (raw bigint, 6 decimals). */
+    getPriceConfig(params: PriceConfigParams): ResultAsync<PriceConfig, ProfileError>;
+    /** Fetches USDC and fiat balance in parallel for a given address and currency. */
+    getBalances(params: GetBalancesParams): ResultAsync<Balances, ProfileError>;
+    /** Reads buy and sell transaction limits for a given address and currency. */
+    getTxLimits(params: TxLimitsParams): ResultAsync<TxLimits, ProfileError>;
+    /** Reads the RP-to-USDC limit ratio for a given currency. */
+    getRpPerUsdtLimitRational(params: PriceConfigParams): ResultAsync<RpPerUsdtLimit, ProfileError>;
+}
+
+type FraudEngineErrorCode = "API_ERROR" | "ENCRYPTION_ERROR" | "SIGNING_ERROR" | "VALIDATION_ERROR" | "NETWORK_ERROR" | "PLACE_ORDER_ERROR";
+declare class FraudEngineError extends SdkError<FraudEngineErrorCode> {
+    constructor(message: string, options: {
+        code: FraudEngineErrorCode;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+
+interface FraudEngineSigner {
+    /**
+     * The subject address tracked by the fraud engine — the wallet that places
+     * on-chain orders and appears in reports, watchlist, and risk scoring.
+     *
+     * - For thirdweb smart wallets (ERC-4337 / account abstraction) this is the
+     *   smart account address.
+     * - For plain EOA wallets this is the same address that produces signatures.
+     */
+    readonly address: string;
+    /**
+     * The address of the key that actually produces the EIP-191 signature.
+     * Defaults to {@link address} when omitted.
+     *
+     * Set this only when the tracked subject is a smart wallet whose admin EOA
+     * is the real signer (smart wallet contracts cannot sign EIP-191 directly).
+     * In that case, {@link address} is the smart wallet and `signerAddress` is
+     * the admin EOA.
+     */
+    readonly signerAddress?: string;
+    signMessage(message: string): Promise<string>;
+}
+interface DeviceDetails {
+    readonly userAgent: string;
+    readonly platform: string;
+    readonly language: string;
+    readonly languages: string[];
+    readonly screenWidth: number;
+    readonly screenHeight: number;
+    readonly devicePixelRatio: number;
+    readonly timezone: string;
+    readonly timezoneOffset: number;
+    readonly cookiesEnabled: boolean;
+    readonly doNotTrack: string | null;
+    readonly online: boolean;
+    readonly connectionType?: string;
+    readonly deviceMemory?: number;
+    readonly hardwareConcurrency?: number;
+    readonly touchSupport: boolean;
+    readonly maxTouchPoints: number;
+    readonly vendor: string;
+    readonly appVersion: string;
+    readonly colorDepth: number;
+    readonly pixelDepth: number;
+    readonly ip?: string;
+    readonly seonSession?: string;
+}
+interface BuyOrderDetails {
+    readonly cryptoAmount: number;
+    readonly fiatAmount: number;
+    readonly currency: string;
+    readonly recipientAddress: string;
+    readonly fee: number;
+    readonly amountAfterFee: number;
+    readonly paymentMethod?: string;
+    readonly estimatedProcessingTime?: string;
+}
+interface UserDetails {
+    readonly currency?: string;
+    readonly country?: string;
+    readonly language?: string;
+    readonly loginMethod?: "email" | "google" | "phone" | "passkey" | "unknown";
+    readonly loginEmail?: string;
+    readonly loginPhone?: string;
+}
+interface FraudCheckResult {
+    readonly approved: boolean;
+    readonly activityLogId: number;
+    readonly message: string;
+    /**
+     * Link an on-chain order ID to this activity log record.
+     * Call after the buy order is placed on-chain (fire-and-forget).
+     * The signer and activityLogId are captured internally — just pass the orderId.
+     */
+    linkOrder(orderId: string): neverthrow.ResultAsync<LinkOrderResult, FraudEngineError>;
+}
+interface LinkOrderResult {
+    readonly success: boolean;
+    readonly message: string;
+}
+interface FingerprintLogResult {
+    readonly success: boolean;
+    readonly message: string;
+}
+type ProcessBuyOrderResult = {
+    readonly status: "placed";
+    readonly orderId: string;
+} | {
+    readonly status: "rejected";
+    readonly message: string;
+};
+interface FraudEngine {
+    init(): Promise<void>;
+    /**
+     * Low-level: run fraud check only. Returns result with `linkOrder()` for manual linking.
+     * For most consumers, prefer `processBuyOrder()` which handles the full flow.
+     */
+    checkBuyOrder(params: {
+        signer: FraudEngineSigner;
+        orderDetails: BuyOrderDetails;
+        userDetails?: UserDetails;
+        orderSource?: string;
+    }): neverthrow.ResultAsync<FraudCheckResult, FraudEngineError>;
+    /**
+     * Full orchestration: fraud check → place order → auto-link.
+     *
+     * - Runs fraud check on all buy orders (backend handles currency-specific logic).
+     *   If rejected, returns `{ status: "rejected" }` without calling `placeOrder`.
+     *   If approved, calls `placeOrder`, auto-links activity log, returns `{ status: "placed", orderId }`.
+     * - Fail-open: if fraud check API errors, still calls `placeOrder` (no linking since no activityLogId).
+     * - Linking is fire-and-forget: if link fails, order is already placed — error is logged, not propagated.
+     */
+    processBuyOrder(params: {
+        signer: FraudEngineSigner;
+        orderDetails: BuyOrderDetails;
+        userDetails?: UserDetails;
+        orderSource?: string;
+        placeOrder: () => Promise<string>;
+    }): neverthrow.ResultAsync<ProcessBuyOrderResult, FraudEngineError>;
+    logFingerprint(params: {
+        signer: FraudEngineSigner;
+    }): neverthrow.ResultAsync<FingerprintLogResult | null, FraudEngineError>;
+    getFingerprint(): Promise<{
+        visitorId: string;
+        confidence: number;
+    } | null>;
+    getDeviceDetails(): Promise<DeviceDetails>;
+    cleanupSeonStorage(): void;
+}
+
+interface FraudEngineSdkConfig {
+    readonly apiUrl: string;
+    readonly encryptionKey: string;
+    readonly seonRegion?: string;
+}
+interface SdkConfig {
+    readonly publicClient: PublicClientLike;
+    readonly subgraphUrl: string;
+    readonly diamondAddress: Address;
+    readonly usdcAddress: Address;
+    readonly reputationManagerAddress?: Address;
+    readonly fraudEngine?: FraudEngineSdkConfig;
+    readonly logger?: Logger;
+}
+interface Sdk {
+    readonly profile: Profile;
+    readonly orderRouter: OrderRouter;
+    readonly payload: PayloadGenerator;
+    readonly zkkyc?: Zkkyc;
+    readonly fraudEngine?: FraudEngine;
+}
+
+/**
+ * Provides Profile, OrderRouter, PayloadGenerator, Zkkyc, and FraudEngine instances to all children.
+ *
+ * Object props (`publicClient`, `logger`) are captured on mount and do **not** trigger
+ * re-instantiation on subsequent renders. To swap them (e.g. switching chains), remount
+ * the provider with a React `key`:
+ *
+ * ```tsx
+ * <SdkProvider key={chainId} publicClient={client} ...>
+ * ```
+ *
+ * Primitive props (`subgraphUrl`, `diamondAddress`, etc.) are compared by value and will
+ * trigger re-instantiation when they actually change.
+ */
+declare function SdkProvider({ children, ...config }: SdkConfig & {
+    readonly children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/** Returns the full SDK object from the nearest SdkProvider. */
+declare function useSdk(): Sdk;
+/** Returns the Profile instance from the nearest SdkProvider. */
+declare function useProfile(): Profile;
+/** Returns the OrderRouter instance from the nearest SdkProvider. */
+declare function useOrderRouter(): OrderRouter;
+/** Returns the PayloadGenerator instance from the nearest SdkProvider. */
+declare function usePayloadGenerator(): PayloadGenerator;
+/** Returns the Zkkyc instance from the nearest SdkProvider. */
+declare function useZkkyc(): Zkkyc;
+/** Returns the FraudEngine instance from the nearest SdkProvider. */
+declare function useFraudEngine(): FraudEngine;
+
+interface UseFingerprintResult {
+    data: {
+        visitorId: string;
+        confidence: number;
+    } | null;
+    error: Error | null;
+    isLoading: boolean;
+}
+declare function useFingerprint(enabled: boolean): UseFingerprintResult;
+
+export { type FraudEngineSdkConfig, type SdkConfig, SdkProvider, useFingerprint, useFraudEngine, useOrderRouter, usePayloadGenerator, useProfile, useSdk, useZkkyc };