helius-wallet-kit 0.1.0

package/dist/core/index.d.cts

@@ -0,0 +1,170 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { Connection } from '@solana/web3.js';
+
+interface HeliusWalletConfig {
+    apiKey?: string;
+    /**
+     * Helius project id. Required — stamped as the Turnkey sub-org name on every
+     * end-user wallet so signatures can be attributed to your project for usage
+     * billing (resolved server-side via getSubOrgIds by name).
+     */
+    projectId: string;
+    planTier?: HeliusPlan;
+    rpcProxyPath?: string;
+    /**
+     * Base URL for the Helius WaaS control-plane API (the `/waas/config`
+     * bootstrap). Defaults to Helius production; override for local/staging.
+     */
+    apiBaseUrl?: string;
+    /**
+     * Per-cluster Helius Secure RPC URL (key-less, safe in the browser). When set
+     * for the active cluster, the wallet's Solana connection, priority-fee lookups,
+     * and transaction sends go directly to it — no route handler needed. Sends use
+     * standard RPC (not Helius Sender), so they forgo Sender's optimized landing;
+     * use proxy mode for best mainnet landing. Falls back to the same-origin
+     * `rpcProxyPath` proxy when unset. Pass a stable reference (memoize it) to
+     * avoid unnecessary re-renders.
+     */
+    secureRpcUrl?: Partial<Record<Cluster, string>>;
+    cluster?: Cluster;
+    authMethods?: {
+        passkey?: boolean;
+        email?: boolean;
+        sms?: boolean;
+        wallet?: boolean;
+        google?: boolean;
+        apple?: boolean;
+        discord?: boolean;
+        x?: boolean;
+    };
+    theme?: {
+        darkMode?: boolean;
+        primaryColor?: string;
+        borderRadius?: string;
+        logoLight?: string;
+        logoDark?: string;
+    };
+    onError?: (error: Error) => void;
+}
+type Cluster = "devnet" | "mainnet-beta";
+type HeliusPlan = "basic" | "developer" | "business" | "professional";
+declare function isWaasEligible(plan: HeliusPlan): boolean;
+type AuthStatus = "loading" | "unauthenticated" | "authenticated";
+type PriorityLevel = "Min" | "Low" | "Medium" | "High" | "VeryHigh" | "UnsafeMax";
+/**
+ * All six priority-fee levels (in micro-lamports per compute unit) returned by
+ * Helius's `getPriorityFeeEstimate` when called with
+ * `includeAllPriorityFeeLevels: true`. The lowercase keys match the upstream
+ * RPC response shape — intentionally distinct from the PascalCase
+ * `PriorityLevel` union which is what the RPC accepts as input.
+ */
+interface PriorityFeeLevels {
+    min: number;
+    low: number;
+    medium: number;
+    high: number;
+    veryHigh: number;
+    unsafeMax: number;
+}
+/**
+ * One row of Helius Enhanced Transactions API response. Fields beyond the
+ * common set are passed through verbatim via the index signature — Helius's
+ * parsed-tx schema is evolving, and consumers rendering UI off specific fields
+ * should cast at their call site rather than wait for us to widen this type.
+ */
+interface EnhancedTransaction {
+    signature: string;
+    slot: number;
+    timestamp: number;
+    type: string;
+    source: string;
+    fee: number;
+    feePayer: string;
+    description?: string;
+    nativeTransfers?: Array<{
+        fromUserAccount: string;
+        toUserAccount: string;
+        amount: number;
+    }>;
+    tokenTransfers?: Array<{
+        fromUserAccount: string;
+        toUserAccount: string;
+        mint: string;
+        tokenAmount: number;
+    }>;
+    [key: string]: unknown;
+}
+interface HeliusWallet {
+    address: string | null;
+    status: AuthStatus;
+    user: {
+        userId: string;
+        username: string;
+        email?: string;
+        /**
+         * Turnkey sub-organization id for this end-user. Each authenticated user
+         * gets their own sub-org, fully isolated. Useful for server-side audit
+         * trails and admin observability. Always defined when status is
+         * "authenticated".
+         */
+        subOrgId: string;
+        /**
+         * Turnkey wallet id (the wallet container holding this user's accounts).
+         * May be undefined for a brief window post-signup before the wallet
+         * provisioning completes.
+         */
+        walletId: string | null;
+    } | null;
+    login: () => Promise<void>;
+    logout: () => Promise<void>;
+    signTransaction: (transaction: Uint8Array | Buffer) => Promise<Buffer>;
+    signAndSendTransaction: (transaction: Uint8Array | Buffer) => Promise<string>;
+    signMessage: (message: string) => Promise<string>;
+    exportWallet: () => Promise<void>;
+    /**
+     * Fetch parsed transaction history for the connected wallet via Helius
+     * Enhanced Transactions API. Returns empty array if no wallet is connected.
+     */
+    getTransactions: (options?: {
+        limit?: number;
+    }) => Promise<EnhancedTransaction[]>;
+    /**
+     * Estimate priority fee in micro-lamports for a transaction touching the
+     * given writable accounts. `priorityLevel` defaults to "Medium". Uses
+     * Helius's `getPriorityFeeEstimate` RPC method.
+     */
+    getPriorityFee: (accountKeys: string[], priorityLevel?: PriorityLevel) => Promise<number>;
+    /**
+     * Like `getPriorityFee`, but returns every level Helius reports
+     * (min/low/medium/high/veryHigh/unsafeMax). Use when rendering a fee
+     * picker; otherwise prefer `getPriorityFee` for the single-value case.
+     */
+    getPriorityFeeLevels: (accountKeys: string[]) => Promise<PriorityFeeLevels>;
+    connection: Connection;
+    rpcUrl: string;
+    cluster: Cluster;
+    setCluster: (cluster: Cluster) => void;
+    apiKey: string | null;
+    projectId: string | null;
+    planTier: HeliusPlan | null;
+}
+
+declare const HeliusWalletContext: React.Context<{
+    rpcProxyPath: string;
+    secureRpcUrl?: Partial<Record<Cluster, string>>;
+    cluster: Cluster;
+    setCluster: (cluster: Cluster) => void;
+    apiKey: string | null;
+    projectId: string | null;
+    planTier: HeliusPlan | null;
+    waasEligible: boolean;
+}>;
+declare function HeliusWalletProvider({ config, children, }: {
+    config: HeliusWalletConfig;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+declare function useHeliusWallet(): HeliusWallet;
+
+export { type AuthStatus, type Cluster, type EnhancedTransaction, type HeliusPlan, type HeliusWallet, type HeliusWalletConfig, HeliusWalletContext, HeliusWalletProvider, type PriorityFeeLevels, type PriorityLevel, isWaasEligible, useHeliusWallet };

package/dist/core/index.d.ts

@@ -0,0 +1,170 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { Connection } from '@solana/web3.js';
+
+interface HeliusWalletConfig {
+    apiKey?: string;
+    /**
+     * Helius project id. Required — stamped as the Turnkey sub-org name on every
+     * end-user wallet so signatures can be attributed to your project for usage
+     * billing (resolved server-side via getSubOrgIds by name).
+     */
+    projectId: string;
+    planTier?: HeliusPlan;
+    rpcProxyPath?: string;
+    /**
+     * Base URL for the Helius WaaS control-plane API (the `/waas/config`
+     * bootstrap). Defaults to Helius production; override for local/staging.
+     */
+    apiBaseUrl?: string;
+    /**
+     * Per-cluster Helius Secure RPC URL (key-less, safe in the browser). When set
+     * for the active cluster, the wallet's Solana connection, priority-fee lookups,
+     * and transaction sends go directly to it — no route handler needed. Sends use
+     * standard RPC (not Helius Sender), so they forgo Sender's optimized landing;
+     * use proxy mode for best mainnet landing. Falls back to the same-origin
+     * `rpcProxyPath` proxy when unset. Pass a stable reference (memoize it) to
+     * avoid unnecessary re-renders.
+     */
+    secureRpcUrl?: Partial<Record<Cluster, string>>;
+    cluster?: Cluster;
+    authMethods?: {
+        passkey?: boolean;
+        email?: boolean;
+        sms?: boolean;
+        wallet?: boolean;
+        google?: boolean;
+        apple?: boolean;
+        discord?: boolean;
+        x?: boolean;
+    };
+    theme?: {
+        darkMode?: boolean;
+        primaryColor?: string;
+        borderRadius?: string;
+        logoLight?: string;
+        logoDark?: string;
+    };
+    onError?: (error: Error) => void;
+}
+type Cluster = "devnet" | "mainnet-beta";
+type HeliusPlan = "basic" | "developer" | "business" | "professional";
+declare function isWaasEligible(plan: HeliusPlan): boolean;
+type AuthStatus = "loading" | "unauthenticated" | "authenticated";
+type PriorityLevel = "Min" | "Low" | "Medium" | "High" | "VeryHigh" | "UnsafeMax";
+/**
+ * All six priority-fee levels (in micro-lamports per compute unit) returned by
+ * Helius's `getPriorityFeeEstimate` when called with
+ * `includeAllPriorityFeeLevels: true`. The lowercase keys match the upstream
+ * RPC response shape — intentionally distinct from the PascalCase
+ * `PriorityLevel` union which is what the RPC accepts as input.
+ */
+interface PriorityFeeLevels {
+    min: number;
+    low: number;
+    medium: number;
+    high: number;
+    veryHigh: number;
+    unsafeMax: number;
+}
+/**
+ * One row of Helius Enhanced Transactions API response. Fields beyond the
+ * common set are passed through verbatim via the index signature — Helius's
+ * parsed-tx schema is evolving, and consumers rendering UI off specific fields
+ * should cast at their call site rather than wait for us to widen this type.
+ */
+interface EnhancedTransaction {
+    signature: string;
+    slot: number;
+    timestamp: number;
+    type: string;
+    source: string;
+    fee: number;
+    feePayer: string;
+    description?: string;
+    nativeTransfers?: Array<{
+        fromUserAccount: string;
+        toUserAccount: string;
+        amount: number;
+    }>;
+    tokenTransfers?: Array<{
+        fromUserAccount: string;
+        toUserAccount: string;
+        mint: string;
+        tokenAmount: number;
+    }>;
+    [key: string]: unknown;
+}
+interface HeliusWallet {
+    address: string | null;
+    status: AuthStatus;
+    user: {
+        userId: string;
+        username: string;
+        email?: string;
+        /**
+         * Turnkey sub-organization id for this end-user. Each authenticated user
+         * gets their own sub-org, fully isolated. Useful for server-side audit
+         * trails and admin observability. Always defined when status is
+         * "authenticated".
+         */
+        subOrgId: string;
+        /**
+         * Turnkey wallet id (the wallet container holding this user's accounts).
+         * May be undefined for a brief window post-signup before the wallet
+         * provisioning completes.
+         */
+        walletId: string | null;
+    } | null;
+    login: () => Promise<void>;
+    logout: () => Promise<void>;
+    signTransaction: (transaction: Uint8Array | Buffer) => Promise<Buffer>;
+    signAndSendTransaction: (transaction: Uint8Array | Buffer) => Promise<string>;
+    signMessage: (message: string) => Promise<string>;
+    exportWallet: () => Promise<void>;
+    /**
+     * Fetch parsed transaction history for the connected wallet via Helius
+     * Enhanced Transactions API. Returns empty array if no wallet is connected.
+     */
+    getTransactions: (options?: {
+        limit?: number;
+    }) => Promise<EnhancedTransaction[]>;
+    /**
+     * Estimate priority fee in micro-lamports for a transaction touching the
+     * given writable accounts. `priorityLevel` defaults to "Medium". Uses
+     * Helius's `getPriorityFeeEstimate` RPC method.
+     */
+    getPriorityFee: (accountKeys: string[], priorityLevel?: PriorityLevel) => Promise<number>;
+    /**
+     * Like `getPriorityFee`, but returns every level Helius reports
+     * (min/low/medium/high/veryHigh/unsafeMax). Use when rendering a fee
+     * picker; otherwise prefer `getPriorityFee` for the single-value case.
+     */
+    getPriorityFeeLevels: (accountKeys: string[]) => Promise<PriorityFeeLevels>;
+    connection: Connection;
+    rpcUrl: string;
+    cluster: Cluster;
+    setCluster: (cluster: Cluster) => void;
+    apiKey: string | null;
+    projectId: string | null;
+    planTier: HeliusPlan | null;
+}
+
+declare const HeliusWalletContext: React.Context<{
+    rpcProxyPath: string;
+    secureRpcUrl?: Partial<Record<Cluster, string>>;
+    cluster: Cluster;
+    setCluster: (cluster: Cluster) => void;
+    apiKey: string | null;
+    projectId: string | null;
+    planTier: HeliusPlan | null;
+    waasEligible: boolean;
+}>;
+declare function HeliusWalletProvider({ config, children, }: {
+    config: HeliusWalletConfig;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+declare function useHeliusWallet(): HeliusWallet;
+
+export { type AuthStatus, type Cluster, type EnhancedTransaction, type HeliusPlan, type HeliusWallet, type HeliusWalletConfig, HeliusWalletContext, HeliusWalletProvider, type PriorityFeeLevels, type PriorityLevel, isWaasEligible, useHeliusWallet };