@cicero-zcash/react 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,484 @@
+import React from 'react';
+
+type ZcashAddressType = 'unified' | 'sapling' | 'transparent' | 'unknown';
+type ZcashNetwork = 'mainnet' | 'testnet';
+type PaymentStatus = 'idle' | 'pending' | 'detected' | 'confirmed' | 'expired' | 'failed';
+type CiceroTheme = 'supabase' | 'emerald' | 'dark' | 'light';
+interface PaymentDetails {
+    recipient: string;
+    amount: number | string;
+    memo?: string;
+    message?: string;
+    network?: ZcashNetwork;
+    invoiceId?: string;
+}
+interface Zip321PaymentRequest {
+    address: string;
+    amount?: string;
+    memo?: string;
+    message?: string;
+    rawUri: string;
+}
+interface CiceroPayProps {
+    /** Zcash recipient address (Unified, Sapling, or Transparent) */
+    recipient: string;
+    /** Amount in ZEC */
+    amount: number | string;
+    /** Optional encrypted memo (up to 512 bytes, supported on shielded addresses) */
+    memo?: string;
+    /** Optional human-readable message */
+    message?: string;
+    /** Button label text */
+    label?: string;
+    /** Zcash network (defaults to 'mainnet') */
+    network?: ZcashNetwork;
+    /** Visual theme */
+    theme?: CiceroTheme;
+    /** Button variant */
+    variant?: 'primary' | 'outline' | 'dark';
+    /** Button size */
+    size?: 'sm' | 'md' | 'lg';
+    /** Whether to show estimated USD value alongside ZEC */
+    showUsd?: boolean;
+    /** Custom modal title */
+    modalTitle?: string;
+    /** Custom modal subtitle */
+    modalSubtitle?: string;
+    /** Invoice expiration time in seconds (defaults to 900 = 15 mins) */
+    expiresInSeconds?: number;
+    /** Optional custom lightwalletd or indexer URL */
+    customRpcUrl?: string;
+    /** Optional unique invoice or order reference */
+    invoiceId?: string;
+    /** Callback fired when transaction confirmation is detected */
+    onSuccess?: (tx: {
+        txId: string;
+        amount: number;
+        memo?: string;
+    }) => void;
+    /** Callback fired on payment error */
+    onError?: (error: Error) => void;
+    /** Callback fired whenever the payment status transitions */
+    onStatusChange?: (status: PaymentStatus) => void;
+    /** Custom CSS classes for the trigger button */
+    className?: string;
+    /** Disable the button */
+    disabled?: boolean;
+}
+
+type WalletCategory = 'extension' | 'mobile' | 'desktop' | 'read-only' | 'developer';
+interface WalletSession$1 {
+    address?: string;
+    viewingKey?: string;
+    network?: ZcashNetwork;
+    connected: boolean;
+    walletId: string;
+    balance?: number;
+}
+interface SendPaymentParams {
+    recipient: string;
+    amount: number | string;
+    memo?: string;
+    message?: string;
+}
+interface SendPaymentResult {
+    txId: string;
+    submitted: boolean;
+    rawUri?: string;
+}
+interface ZcashWallet {
+    id: string;
+    name: string;
+    icon: string;
+    description: string;
+    category: WalletCategory;
+    downloadUrl?: string;
+    isAvailable: () => boolean;
+    connect: (options?: {
+        network?: ZcashNetwork;
+    }) => Promise<WalletSession$1>;
+    disconnect?: () => Promise<void>;
+    getBalance?: (options?: {
+        address?: string;
+        network?: ZcashNetwork;
+    }) => Promise<number | null>;
+    sendPayment?: (params: SendPaymentParams) => Promise<SendPaymentResult>;
+}
+
+declare const zucchiniWallet: ZcashWallet;
+
+declare const zashiWallet: ZcashWallet;
+
+declare const ywallet: ZcashWallet;
+
+declare const viewingKeyWallet: ZcashWallet;
+
+declare const burnerWallet: ZcashWallet;
+
+/**
+ * Returns the default suite of supported Zcash wallets.
+ * Zucchini will be marked as available if the browser extension is detected.
+ */
+declare function getDefaultWallets(): ZcashWallet[];
+
+interface AccountState {
+    address: string | null;
+    viewingKey: string | null;
+    isConnected: boolean;
+    isConnecting: boolean;
+    status: 'disconnected' | 'connecting' | 'connected' | 'error';
+    wallet: ZcashWallet | null;
+    error: string | null;
+}
+interface BalanceState {
+    zec: number;
+    usd: string | null;
+    isLoading: boolean;
+}
+interface CiceroContextType {
+    account: AccountState;
+    address: string | null;
+    isConnected: boolean;
+    isConnecting: boolean;
+    wallet: ZcashWallet | null;
+    network: ZcashNetwork;
+    switchNetwork: (net: ZcashNetwork) => void;
+    balance: BalanceState;
+    refetchBalance: () => Promise<void>;
+    connect: (walletId: string, customAddressOrKey?: string) => Promise<void>;
+    disconnect: () => Promise<void>;
+    sendPayment: (params: SendPaymentParams) => Promise<SendPaymentResult>;
+    isConnectModalOpen: boolean;
+    openConnectModal: () => void;
+    closeConnectModal: () => void;
+    isAccountModalOpen: boolean;
+    openAccountModal: () => void;
+    closeAccountModal: () => void;
+    wallets: ZcashWallet[];
+    appName?: string;
+    appLogo?: string;
+}
+interface CiceroProviderProps {
+    children: React.ReactNode;
+    initialNetwork?: ZcashNetwork;
+    wallets?: ZcashWallet[];
+    appName?: string;
+    appLogo?: string;
+    autoConnect?: boolean;
+}
+declare const CiceroProvider: React.FC<CiceroProviderProps>;
+declare function useCicero(): CiceroContextType;
+declare const useAccount: () => {
+    address: string | null;
+    isConnected: boolean;
+    isConnecting: boolean;
+    wallet: ZcashWallet | null;
+    disconnect: () => Promise<void>;
+    viewingKey: string | null;
+    status: "disconnected" | "connecting" | "connected" | "error";
+    error: string | null;
+};
+declare const useBalance: () => {
+    refetch: () => Promise<void>;
+    zec: number;
+    usd: string | null;
+    isLoading: boolean;
+};
+declare const useConnectModal: () => {
+    isOpen: boolean;
+    openConnectModal: () => void;
+    closeConnectModal: () => void;
+};
+declare const useAccountModal: () => {
+    isOpen: boolean;
+    openAccountModal: () => void;
+    closeAccountModal: () => void;
+};
+
+interface CiceroConnectButtonProps {
+    label?: string;
+    variant?: 'primary' | 'outline' | 'dark';
+    size?: 'sm' | 'md' | 'lg';
+    showBalance?: boolean;
+    showNetwork?: boolean;
+    className?: string;
+}
+declare const CiceroConnectButton: React.FC<CiceroConnectButtonProps>;
+
+interface CiceroConnectModalProps {
+    isOpen?: boolean;
+    onClose?: () => void;
+}
+declare const CiceroConnectModal: React.FC<CiceroConnectModalProps>;
+
+interface CiceroAccountModalProps {
+    isOpen?: boolean;
+    onClose?: () => void;
+}
+declare const CiceroAccountModal: React.FC<CiceroAccountModalProps>;
+
+declare const CiceroPayButton: React.FC<CiceroPayProps>;
+
+interface CiceroModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    recipient: string;
+    amount: number | string;
+    memo?: string;
+    message?: string;
+    network?: ZcashNetwork;
+    status: PaymentStatus;
+    txId: string | null;
+    secondsRemaining: number;
+    zip321Uri: string;
+    addressType: string;
+    isShielded: boolean;
+    memoValidation: {
+        valid: boolean;
+        warning?: string;
+        byteLength: number;
+    };
+    onSimulateDetection?: () => void;
+    onResetPayment?: () => void;
+    title?: string;
+    subtitle?: string;
+    showUsd?: boolean;
+    /** Zucchini Wallet integration */
+    zucchiniAvailable?: boolean;
+    zucchiniPaying?: boolean;
+    onPayWithZucchini?: () => void;
+}
+declare const CiceroModal: React.FC<CiceroModalProps>;
+
+interface CiceroQRCodeProps {
+    value: string;
+    size?: number;
+    className?: string;
+    level?: 'L' | 'M' | 'Q' | 'H';
+    includeMargin?: boolean;
+}
+declare const CiceroQRCode: React.FC<CiceroQRCodeProps>;
+
+declare const CiceroInvoice: React.FC<CiceroPayProps>;
+
+interface UseCiceroPaymentOptions {
+    recipient: string;
+    amount: number | string;
+    memo?: string;
+    message?: string;
+    network?: ZcashNetwork;
+    expiresInSeconds?: number;
+    invoiceId?: string;
+    customRpcUrl?: string;
+    onSuccess?: (tx: {
+        txId: string;
+        amount: number;
+        memo?: string;
+    }) => void;
+    onError?: (error: Error) => void;
+    onStatusChange?: (status: PaymentStatus) => void;
+}
+declare function useCiceroPayment({ recipient, amount, memo, message, network, expiresInSeconds, // 15 mins
+invoiceId, customRpcUrl, onSuccess, onError, onStatusChange, }: UseCiceroPaymentOptions): {
+    status: PaymentStatus;
+    txId: string | null;
+    secondsRemaining: number;
+    isModalOpen: boolean;
+    openModal: () => void;
+    closeModal: () => void;
+    resetPayment: () => void;
+    zip321Uri: string;
+    deepLinks: {
+        generic: string;
+        zashi: string;
+        ywallet: string;
+    };
+    addressType: ZcashAddressType;
+    isShielded: boolean;
+    memoValidation: {
+        valid: boolean;
+        warning?: string;
+        byteLength: number;
+    };
+    simulateDetection: () => void;
+    invoiceId: string | undefined;
+    network: ZcashNetwork;
+    customRpcUrl: string | undefined;
+    zucchiniAvailable: boolean;
+    zucchiniPaying: boolean;
+    payWithZucchini: () => Promise<void>;
+};
+
+declare function useZcashPrice(enabled?: boolean): {
+    convertZecToUsd: (zecAmount: number | string) => string | null;
+    usdPrice: number | null;
+    loading: boolean;
+    error: string | null;
+    lastUpdated: number | null;
+};
+
+type WalletConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+type WalletPaymentStatus = 'idle' | 'requesting' | 'submitted' | 'error';
+interface WalletSession {
+    address?: string;
+    connected: boolean;
+    balance?: number;
+}
+interface WalletPaymentResult {
+    txId: string;
+    submitted: boolean;
+}
+/**
+ * Adapter for the Zucchini Wallet browser extension.
+ *
+ * Zucchini injects a provider onto window.zucchini (or window.zcash) and implements
+ * the typed @zucchinifi/dapp-sdk Zcash contract.
+ */
+declare class ZucchiniWalletAdapter {
+    private client;
+    private provider;
+    private _connected;
+    private _address;
+    private _lastAccounts;
+    /**
+     * Checks whether the Zucchini Wallet extension is installed and its
+     * provider is available in the current browser environment.
+     */
+    static isAvailable(): boolean;
+    /**
+     * Subscribes to wallet readiness. Fires callback immediately if already available,
+     * or listens for injection events / polls briefly for late extension initialization.
+     */
+    static onReady(callback: () => void): () => void;
+    /**
+     * Discovers and initializes the Zucchini Client using @zucchinifi/dapp-sdk/zcash
+     * with graceful fallback to raw window.zucchini / window.zcash globals.
+     */
+    private getClient;
+    /**
+     * Requests connection with view_addresses and send_transaction permissions.
+     * Resolves the user's active Shielded Unified Address.
+     */
+    connect(): Promise<WalletSession>;
+    /**
+     * Helper to normalize raw balance formats (e.g. number, string, zatoshis, or pool totals).
+     */
+    private parseBalancePayload;
+    /**
+     * Reads real-time balance from Zucchini provider.
+     */
+    getBalance(options?: {
+        address?: string;
+        network?: string;
+    }): Promise<number | null>;
+    /**
+     * Sends payment via standard ZIP-321 URI requestPayment or transaction fallback.
+     */
+    requestPayment(params: {
+        recipient: string;
+        amount: number | string;
+        memo?: string;
+    }): Promise<WalletPaymentResult>;
+    /**
+     * Subscribes to accountsChanged events.
+     */
+    onAccountsChanged(listener: (accounts: any) => void): () => void;
+    /**
+     * Subscribes to disconnect events.
+     */
+    onDisconnect(listener: () => void): () => void;
+    /**
+     * Disconnects the current session.
+     */
+    disconnect(): Promise<void>;
+    get isConnected(): boolean;
+    get address(): string | null;
+}
+
+interface UseZucchiniWalletOptions {
+    /** Auto-connect on mount when extension is detected */
+    autoConnect?: boolean;
+}
+declare function useZucchiniWallet(options?: UseZucchiniWalletOptions): {
+    /** Whether the Zucchini extension is installed in this browser */
+    isAvailable: boolean;
+    /** Current wallet connection lifecycle state */
+    connectionStatus: WalletConnectionStatus;
+    /** Current payment request lifecycle state */
+    paymentStatus: WalletPaymentStatus;
+    /** Active session info (address, etc.) */
+    session: WalletSession | null;
+    /** Last error message (if any) */
+    error: string | null;
+    /** Prompt the user to connect their Zucchini Wallet */
+    connect: () => Promise<WalletSession>;
+    /** Send a ZIP-321 payment request for user review & approval */
+    requestPayment: (params: {
+        recipient: string;
+        amount: number | string;
+        memo?: string;
+    }) => Promise<WalletPaymentResult>;
+    /** Disconnect the current session */
+    disconnect: () => Promise<void>;
+};
+
+/**
+ * Detects the type of a Zcash address.
+ */
+declare function getAddressType(address: string): ZcashAddressType;
+/**
+ * Checks whether an address supports zero-knowledge shielded encryption (Unified or Sapling).
+ */
+declare function isShieldedAddress(address: string): boolean;
+/**
+ * Truncates a long address for display purposes.
+ * e.g., u1abcdef...987654
+ */
+declare function truncateAddress(address: string, start?: number, end?: number): string;
+/**
+ * Validates whether the address supports encrypted memos.
+ * Memos in Zcash are strictly for shielded receivers (Sapling & Orchard).
+ * Transparent addresses do not support on-chain encrypted memos.
+ */
+declare function validateMemoSupport(address: string, memo?: string): {
+    valid: boolean;
+    warning?: string;
+    byteLength: number;
+};
+
+/**
+ * Encodes a string to Base64URL without padding per RFC 4648 §5 / ZIP-321 specification.
+ */
+declare function encodeBase64Url(str: string): string;
+/**
+ * Decodes a Base64URL string without padding per ZIP-321 specification.
+ */
+declare function decodeBase64Url(base64url: string): string;
+interface BuildZip321Params {
+    address: string;
+    amount?: number | string;
+    memo?: string;
+    message?: string;
+}
+/**
+ * Generates an RFC-compliant ZIP-321 Payment Request URI.
+ * Example output:
+ * zcash:u1xyz...?amount=0.05&memo=T3JkZXIgIzEwNDI&message=Payment%20for%20order
+ */
+declare function generateZip321Uri({ address, amount, memo, message, }: BuildZip321Params): string;
+/**
+ * Parses a ZIP-321 URI back into its component parts.
+ */
+declare function parseZip321Uri(rawUri: string): Zip321PaymentRequest;
+/**
+ * Generates deep link URLs for major mobile Zcash wallets:
+ * - Zashi (Electric Coin Co.)
+ * - Ywallet
+ */
+declare function getWalletDeepLinks(zip321Uri: string): {
+    generic: string;
+    zashi: string;
+    ywallet: string;
+};
+
+export { type AccountState, type BalanceState, type BuildZip321Params, CiceroAccountModal, type CiceroAccountModalProps, CiceroConnectButton, type CiceroConnectButtonProps, CiceroConnectModal, type CiceroConnectModalProps, type CiceroContextType, CiceroInvoice, CiceroModal, CiceroPayButton, type CiceroPayProps, CiceroProvider, type CiceroProviderProps, CiceroQRCode, type CiceroTheme, type PaymentDetails, type PaymentStatus, type SendPaymentParams, type SendPaymentResult, type UseCiceroPaymentOptions, type UseZucchiniWalletOptions, type WalletCategory, type WalletSession$1 as WalletSession, type ZcashAddressType, type ZcashNetwork, type ZcashWallet, type Zip321PaymentRequest, ZucchiniWalletAdapter, burnerWallet, decodeBase64Url, encodeBase64Url, generateZip321Uri, getAddressType, getDefaultWallets, getWalletDeepLinks, isShieldedAddress, parseZip321Uri, truncateAddress, useAccount, useAccountModal, useBalance, useCicero, useCiceroPayment, useConnectModal, useZcashPrice, useZucchiniWallet, validateMemoSupport, viewingKeyWallet, ywallet, zashiWallet, zucchiniWallet };