@zucchinifi/dapp-sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,12 @@
 # Zucchini SDK
 
-The Zucchini SDK provides a simple way for DApps to interact with the Zucchini Wallet extension.
+[![npm version](https://badge.fury.io/js/@zucchinifi/dapp-sdk.svg)](https://www.npmjs.com/package/@zucchinifi/dapp-sdk)
+
+The Zucchini SDK provides a simple way for DApps to interact with the Zucchini Wallet extension and Mini-App.
+
+**Zucchini Wallet is now live!**
+- Desktop: [Chrome Web Store](https://chromewebstore.google.com/detail/zucchini/khaifnjdhfaadfhgbilokobnaalmimad)
+- Mobile: Coming soon to the **Base App** as a Farcaster Mini-App.
 
 ## Installation
 
@@ -152,15 +158,27 @@ Fetch supported tokens and get swap quotes.
 const tokens = await zucchini.getTokens();
 
 // Get a swap quote
-const quote = await zucchini.getSwapQuote({
+const quote = await zucchini.swap.getQuote({
     from: 'ZEC',
-    to: 'USDC',
+    to: 'nep141:usd-coin.omft.near', // Using asset ID or symbol
     amount: '100000000', // Amount in base units
     recipient: '0x...', // Destination address
     refundAddress: '0x...' // Refund address (if needed)
 });
 ```
 
+## Explorer
+
+Query transaction history from the Zucchini Explorer.
+
+```typescript
+// Get transactions
+const transactions = await zucchini.explorer.getTransactions({
+    limit: 10,
+    offset: 0
+});
+```
+
 ## Events
 
 Listen for account and chain changes.

package/dist/index.d.mts

@@ -1,4 +1,8 @@
 type Permission = 'view_balance' | 'view_addresses' | 'send_transaction' | 'view_keys';
+interface ZucchiniConfig {
+    apiUrl?: string;
+    dev?: boolean;
+}
 interface RequestArguments {
     method: string;
     params?: any;
@@ -56,24 +60,21 @@ interface DetailedKey {
 }
 interface Token {
     symbol: string;
-    name: string;
-    icon: string;
+    assetId: string;
     decimals: number;
-    assetId?: string;
+    blockchain: string;
+    price?: string;
+    name?: string;
+    icon?: string;
 }
 interface SwapQuote {
-    quote: {
-        amountOutFormatted: string;
-        amountIn: string;
-        amountOut: string;
-        depositAddress?: string;
-        depositMemo?: string;
-        timeEstimate: number;
-    };
-    quoteRequest: {
-        deadline: string;
-    };
+    amountOutFormatted: string;
+    amountIn: string;
+    amountOut: string;
     depositAddress?: string;
+    depositMemo?: string;
+    timeEstimate: number;
+    deadline?: string;
 }
 interface QuoteRequestArgs {
     from: string;
@@ -81,6 +82,35 @@ interface QuoteRequestArgs {
     amount: string;
     recipient?: string;
     refundAddress?: string;
+    dry?: boolean;
+}
+interface DepositSubmitArgs {
+    transactionHash: string;
+    depositAddress: string;
+    memo?: string;
+    userAccount?: string;
+}
+interface SwapStatus {
+    status: 'KNOWN_DEPOSIT_TX' | 'PENDING_DEPOSIT' | 'INCOMPLETE_DEPOSIT' | 'PROCESSING' | 'SUCCESS' | 'REFUNDED' | 'FAILED';
+    depositAddress: string;
+    depositMemo?: string;
+    swaps?: any[];
+}
+interface Withdrawal {
+    id: string;
+    status: string;
+    amount: string;
+    assetId: string;
+    timestamp: string;
+}
+interface ExplorerTransaction {
+    depositAddressAndMemo: string;
+    status: string;
+    originAsset: string;
+    destinationAsset: string;
+    amountIn: string;
+    amountOut: string;
+    timestamp: string;
 }
 declare global {
     interface Window {
@@ -184,6 +214,13 @@ interface Receiver {
 declare function parseUnifiedAddress(unifiedAddress: string): UnifiedAddressResult;
 
 declare class ZucchiniSDK {
+    private _apiUrl;
+    constructor(config?: ZucchiniConfig);
+    /**
+     * Configure the SDK at runtime.
+     */
+    configure(config: ZucchiniConfig): void;
+    get apiUrl(): string;
     /**
      * Check if the Zucchini extension is installed and the provider is injected.
      */
@@ -232,8 +269,22 @@ declare class ZucchiniSDK {
         hasWallet: boolean;
     }>;
     getTokens(): Promise<Token[]>;
-    getSwapQuote(args: QuoteRequestArgs): Promise<SwapQuote>;
+    swap: {
+        getQuote: (args: QuoteRequestArgs) => Promise<SwapQuote>;
+        submitDepositHash: (args: DepositSubmitArgs) => Promise<any>;
+        getStatus: (depositAddress: string, memo?: string) => Promise<SwapStatus>;
+        getWithdrawals: (depositAddress: string, options?: {
+            memo?: string;
+            timestampFrom?: string;
+            page?: number;
+            limit?: number;
+            sortOrder?: "asc" | "desc";
+        }) => Promise<Withdrawal[]>;
+    };
+    explorer: {
+        getTransactions: (params?: Record<string, string | number | boolean | undefined | null>) => Promise<ExplorerTransaction[]>;
+    };
 }
 declare const zucchini: ZucchiniSDK;
 
-export { type Account, type ConnectRequest, type ConnectResponse, type DetailedKey, type Payment, type Permission, type QRCodeOptions, type QuoteRequestArgs, type Receiver, type RequestArguments, type SendTransactionArgs, type SwapQuote, type Token, type UnifiedAddressResult, Zip321Generator, type Zip321Options, Zip321Parser, Zip321ParsingError, type ZucchiniProvider, ZucchiniSDK, createPaymentUri, fromZats, generateQRCode, parsePaymentUri, parseUnifiedAddress, shortenAddress, toZats, zucchini };
+export { type Account, type ConnectRequest, type ConnectResponse, type DepositSubmitArgs, type DetailedKey, type ExplorerTransaction, type Payment, type Permission, type QRCodeOptions, type QuoteRequestArgs, type Receiver, type RequestArguments, type SendTransactionArgs, type SwapQuote, type SwapStatus, type Token, type UnifiedAddressResult, type Withdrawal, Zip321Generator, type Zip321Options, Zip321Parser, Zip321ParsingError, type ZucchiniConfig, type ZucchiniProvider, ZucchiniSDK, createPaymentUri, fromZats, generateQRCode, parsePaymentUri, parseUnifiedAddress, shortenAddress, toZats, zucchini };

package/dist/index.d.ts

@@ -1,10 +1,226 @@
-import { ZucchiniProvider, ConnectResponse, RequestArguments, Permission, SendTransactionArgs, Token, SwapQuote, QuoteRequestArgs } from './types';
-export * from './types';
-export * from './utils';
-export * from './zip321';
-export * from './qrcode';
-export * from './unified_address';
-export declare class ZucchiniSDK {
+type Permission = 'view_balance' | 'view_addresses' | 'send_transaction' | 'view_keys';
+interface ZucchiniConfig {
+    apiUrl?: string;
+    dev?: boolean;
+}
+interface RequestArguments {
+    method: string;
+    params?: any;
+}
+interface SendTransactionArgs {
+    to: string;
+    amount: string;
+    memo?: string;
+}
+interface ConnectRequest {
+    permissions?: Permission[];
+}
+interface ConnectResponse {
+    connected: boolean;
+    accounts: Account[];
+    approvedPermissions: Permission[];
+}
+interface Account {
+    name: string;
+    address: string;
+}
+interface ZucchiniProvider {
+    request(args: RequestArguments): Promise<any>;
+    getBalance(): Promise<{
+        total: string;
+        sapling: string;
+        orchard: string;
+    }>;
+    getAddresses(): Promise<{
+        transparent: string;
+        unified: string;
+    }>;
+    getNetwork(): Promise<{
+        network: 'main' | 'test';
+    }>;
+    getUniversalViewingKey(): Promise<string>;
+    getAllViewingKeys(): Promise<Record<string, DetailedKey>>;
+    getWalletStatus(): Promise<{
+        isLocked: boolean;
+        hasWallet: boolean;
+    }>;
+    on(event: string, callback: (data: any) => void): void;
+    off(event: string, callback: (data: any) => void): void;
+    disconnect(): Promise<void>;
+    isConnected(): Promise<boolean>;
+}
+interface DetailedKey {
+    unified: string;
+    unified_full: string;
+    unified_incoming: string;
+    unified_outgoing?: string;
+    transparent?: string;
+    sapling?: string;
+    orchard?: string;
+}
+interface Token {
+    symbol: string;
+    assetId: string;
+    decimals: number;
+    blockchain: string;
+    price?: string;
+    name?: string;
+    icon?: string;
+}
+interface SwapQuote {
+    amountOutFormatted: string;
+    amountIn: string;
+    amountOut: string;
+    depositAddress?: string;
+    depositMemo?: string;
+    timeEstimate: number;
+    deadline?: string;
+}
+interface QuoteRequestArgs {
+    from: string;
+    to: string;
+    amount: string;
+    recipient?: string;
+    refundAddress?: string;
+    dry?: boolean;
+}
+interface DepositSubmitArgs {
+    transactionHash: string;
+    depositAddress: string;
+    memo?: string;
+    userAccount?: string;
+}
+interface SwapStatus {
+    status: 'KNOWN_DEPOSIT_TX' | 'PENDING_DEPOSIT' | 'INCOMPLETE_DEPOSIT' | 'PROCESSING' | 'SUCCESS' | 'REFUNDED' | 'FAILED';
+    depositAddress: string;
+    depositMemo?: string;
+    swaps?: any[];
+}
+interface Withdrawal {
+    id: string;
+    status: string;
+    amount: string;
+    assetId: string;
+    timestamp: string;
+}
+interface ExplorerTransaction {
+    depositAddressAndMemo: string;
+    status: string;
+    originAsset: string;
+    destinationAsset: string;
+    amountIn: string;
+    amountOut: string;
+    timestamp: string;
+}
+declare global {
+    interface Window {
+        zucchini?: ZucchiniProvider;
+    }
+}
+
+/**
+ * Convert ZEC (decimal string or number) to Zatoshis (bigint).
+ * 1 ZEC = 100,000,000 Zatoshis.
+ * Handles up to 8 decimal places.
+ */
+declare function toZats(amount: string | number): bigint;
+/**
+ * Convert Zatoshis (bigint or string) to ZEC (decimal string).
+ * 1 ZEC = 100,000,000 Zatoshis.
+ */
+declare function fromZats(amount: bigint | string): string;
+/**
+ * Shorten an address for display.
+ * Example: zs1...abcd
+ */
+declare function shortenAddress(address: string, chars?: number): string;
+
+interface Payment {
+    address: string;
+    amount?: bigint;
+    assetId?: string;
+    memo?: string;
+    label?: string;
+    message?: string;
+    otherParams?: Record<string, string>;
+}
+interface Zip321Options {
+    useOrchard?: boolean;
+}
+declare class Zip321ParsingError extends Error {
+    constructor(message: string);
+}
+declare class Zip321Parser {
+    /**
+     * Parses a zcash: URI into a list of Payment objects.
+     * @param uri The zcash URI string.
+     * @param options Parsing options.
+     * @returns An array of Payment objects.
+     * @throws Zip321ParsingError if the URI is invalid.
+     */
+    static parse(uri: string, options?: Zip321Options): Payment[];
+    private static isValidAddress;
+    private static isTransparent;
+    private static isSapling;
+    private static isUnified;
+    private static parseAmount;
+    private static parseAsset;
+    private static isValidBase64Url;
+}
+declare class Zip321Generator {
+    /**
+     * Creates a ZIP 321 compliant URI from a list of payments.
+     * @param payments List of Payment objects.
+     * @param options Generation options.
+     * @returns The formatted zcash: URI.
+     * @throws Error if payments list is empty or invalid.
+     */
+    static create(payments: Payment[], options?: Zip321Options): string;
+    private static formatAmount;
+    private static formatAsset;
+}
+declare function parsePaymentUri(uri: string, options?: Zip321Options): Payment[];
+declare function createPaymentUri(payments: Payment[], options?: Zip321Options): string;
+
+interface QRCodeOptions {
+    width?: number;
+    margin?: number;
+    color?: {
+        dark?: string;
+        light?: string;
+    };
+    logoUrl?: string;
+    logoWidth?: number;
+    logoHeight?: number;
+}
+/**
+ * Generates a QR code Data URL from a string (e.g., a ZIP 321 URI).
+ * @param text The text to encode.
+ * @param options QR code options.
+ * @returns A Promise resolving to a Data URL string (image/png).
+ */
+declare function generateQRCode(text: string, options?: QRCodeOptions): Promise<string>;
+
+interface UnifiedAddressResult {
+    orchard?: string;
+    sapling?: string;
+    transparent?: string;
+    unknown?: Receiver[];
+}
+interface Receiver {
+    typeCode: number;
+    data: Uint8Array;
+}
+declare function parseUnifiedAddress(unifiedAddress: string): UnifiedAddressResult;
+
+declare class ZucchiniSDK {
+    private _apiUrl;
+    constructor(config?: ZucchiniConfig);
+    /**
+     * Configure the SDK at runtime.
+     */
+    configure(config: ZucchiniConfig): void;
+    get apiUrl(): string;
     /**
      * Check if the Zucchini extension is installed and the provider is injected.
      */
@@ -53,6 +269,22 @@ export declare class ZucchiniSDK {
         hasWallet: boolean;
     }>;
     getTokens(): Promise<Token[]>;
-    getSwapQuote(args: QuoteRequestArgs): Promise<SwapQuote>;
+    swap: {
+        getQuote: (args: QuoteRequestArgs) => Promise<SwapQuote>;
+        submitDepositHash: (args: DepositSubmitArgs) => Promise<any>;
+        getStatus: (depositAddress: string, memo?: string) => Promise<SwapStatus>;
+        getWithdrawals: (depositAddress: string, options?: {
+            memo?: string;
+            timestampFrom?: string;
+            page?: number;
+            limit?: number;
+            sortOrder?: "asc" | "desc";
+        }) => Promise<Withdrawal[]>;
+    };
+    explorer: {
+        getTransactions: (params?: Record<string, string | number | boolean | undefined | null>) => Promise<ExplorerTransaction[]>;
+    };
 }
-export declare const zucchini: ZucchiniSDK;
+declare const zucchini: ZucchiniSDK;
+
+export { type Account, type ConnectRequest, type ConnectResponse, type DepositSubmitArgs, type DetailedKey, type ExplorerTransaction, type Payment, type Permission, type QRCodeOptions, type QuoteRequestArgs, type Receiver, type RequestArguments, type SendTransactionArgs, type SwapQuote, type SwapStatus, type Token, type UnifiedAddressResult, type Withdrawal, Zip321Generator, type Zip321Options, Zip321Parser, Zip321ParsingError, type ZucchiniConfig, type ZucchiniProvider, ZucchiniSDK, createPaymentUri, fromZats, generateQRCode, parsePaymentUri, parseUnifiedAddress, shortenAddress, toZats, zucchini };