@shadow-corp/nearconnect 1.0.0

package/build/connection/state.js

@@ -0,0 +1,431 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionStateMachine = exports.DEFAULT_STATE_MACHINE_CONFIG = void 0;
+exports.createStateMachine = createStateMachine;
+exports.getStatusDescription = getStatusDescription;
+const errors_1 = require("../errors");
+/**
+ * Valid state transitions
+ */
+const VALID_TRANSITIONS = {
+    idle: ["detecting", "connecting"],
+    detecting: ["connecting", "error", "idle"],
+    connecting: ["authenticating", "connected", "error", "idle"],
+    authenticating: ["connected", "error", "idle"],
+    connected: ["signing", "disconnecting", "reconnecting", "error"],
+    signing: ["connected", "error"],
+    reconnecting: ["connected", "error", "idle"],
+    disconnecting: ["idle", "error"],
+    error: ["idle", "connecting", "reconnecting"],
+};
+/**
+ * Default state machine configuration
+ */
+exports.DEFAULT_STATE_MACHINE_CONFIG = {
+    maxHistorySize: 50,
+    persistState: false,
+    storageKey: "near-connect:state",
+    stateExpiration: 24 * 60 * 60 * 1000, // 24 hours
+};
+/**
+ * Connection State Machine
+ *
+ * Manages connection lifecycle with proper state transitions
+ */
+class ConnectionStateMachine {
+    state = { status: "idle" };
+    history = [];
+    config;
+    listeners = {
+        enter: new Map(),
+        exit: new Map(),
+        transition: new Set(),
+    };
+    constructor(config = {}) {
+        this.config = { ...exports.DEFAULT_STATE_MACHINE_CONFIG, ...config };
+        this.restoreState();
+    }
+    /**
+     * Get current state
+     */
+    get current() {
+        return this.state;
+    }
+    /**
+     * Get current status (convenience getter)
+     */
+    get status() {
+        return this.state.status;
+    }
+    /**
+     * Check if currently in a specific status
+     */
+    is(status) {
+        return this.state.status === status;
+    }
+    /**
+     * Check if in any of the given statuses
+     */
+    isAnyOf(...statuses) {
+        return statuses.includes(this.state.status);
+    }
+    /**
+     * Check if a transition is valid
+     */
+    canTransition(to) {
+        return VALID_TRANSITIONS[this.state.status]?.includes(to) ?? false;
+    }
+    /**
+     * Transition to a new state
+     */
+    transition(to, reason) {
+        const from = this.state;
+        // Validate transition
+        if (!this.canTransition(to.status)) {
+            this.config.onInvalidTransition?.(from.status, to.status);
+            throw new errors_1.WalletError({
+                code: errors_1.ErrorCode.UNKNOWN_ERROR,
+                message: `Invalid state transition from ${from.status} to ${to.status}`,
+            });
+        }
+        // Exit callbacks for old state
+        const exitListeners = this.listeners.exit.get(from.status);
+        if (exitListeners) {
+            for (const listener of exitListeners) {
+                try {
+                    listener(from);
+                }
+                catch (e) {
+                    console.error("Error in exit listener:", e);
+                }
+            }
+        }
+        // Update state
+        this.state = to;
+        // Record history
+        this.recordHistory(from, to, reason);
+        // Enter callbacks for new state
+        const enterListeners = this.listeners.enter.get(to.status);
+        if (enterListeners) {
+            for (const listener of enterListeners) {
+                try {
+                    listener(to);
+                }
+                catch (e) {
+                    console.error("Error in enter listener:", e);
+                }
+            }
+        }
+        // Transition callbacks
+        for (const listener of this.listeners.transition) {
+            try {
+                listener(from, to);
+            }
+            catch (e) {
+                console.error("Error in transition listener:", e);
+            }
+        }
+        // Config callback
+        this.config.onStateChange?.(from, to);
+        // Persist state
+        if (this.config.persistState) {
+            this.persistState();
+        }
+    }
+    /**
+     * Convenience methods for common transitions
+     */
+    toDetecting(walletId) {
+        this.transition({ status: "detecting", walletId, startedAt: Date.now() });
+    }
+    toConnecting(walletId) {
+        this.transition({ status: "connecting", walletId, startedAt: Date.now() });
+    }
+    toAuthenticating(walletId) {
+        this.transition({ status: "authenticating", walletId, startedAt: Date.now() });
+    }
+    toConnected(walletId, accounts) {
+        this.transition({ status: "connected", walletId, accounts, connectedAt: Date.now() });
+    }
+    toSigning(walletId, operation) {
+        this.transition({ status: "signing", walletId, operation, startedAt: Date.now() });
+    }
+    toReconnecting(walletId, attempt = 1) {
+        this.transition({ status: "reconnecting", walletId, attempt, startedAt: Date.now() });
+    }
+    toDisconnecting(walletId) {
+        this.transition({ status: "disconnecting", walletId, startedAt: Date.now() });
+    }
+    toError(error, walletId) {
+        this.transition({ status: "error", walletId, error, occurredAt: Date.now() });
+    }
+    toIdle() {
+        this.transition({ status: "idle" });
+    }
+    /**
+     * Reset to idle state (bypasses transition validation)
+     */
+    reset() {
+        const from = this.state;
+        this.state = { status: "idle" };
+        this.recordHistory(from, this.state, "reset");
+        if (this.config.persistState) {
+            this.clearPersistedState();
+        }
+    }
+    /**
+     * Record state transition in history
+     */
+    recordHistory(from, to, reason) {
+        this.history.push({
+            from,
+            to,
+            timestamp: Date.now(),
+            reason,
+        });
+        // Trim history if needed
+        if (this.history.length > this.config.maxHistorySize) {
+            this.history = this.history.slice(-this.config.maxHistorySize);
+        }
+    }
+    /**
+     * Get state history
+     */
+    getHistory() {
+        return [...this.history];
+    }
+    /**
+     * Get last N history entries
+     */
+    getRecentHistory(count = 10) {
+        return this.history.slice(-count);
+    }
+    /**
+     * Clear history
+     */
+    clearHistory() {
+        this.history = [];
+    }
+    /**
+     * Register callback for entering a state
+     */
+    onEnter(status, callback) {
+        if (!this.listeners.enter.has(status)) {
+            this.listeners.enter.set(status, new Set());
+        }
+        this.listeners.enter.get(status).add(callback);
+        return () => {
+            this.listeners.enter.get(status)?.delete(callback);
+        };
+    }
+    /**
+     * Register callback for exiting a state
+     */
+    onExit(status, callback) {
+        if (!this.listeners.exit.has(status)) {
+            this.listeners.exit.set(status, new Set());
+        }
+        this.listeners.exit.get(status).add(callback);
+        return () => {
+            this.listeners.exit.get(status)?.delete(callback);
+        };
+    }
+    /**
+     * Register callback for any transition
+     */
+    onTransition(callback) {
+        this.listeners.transition.add(callback);
+        return () => {
+            this.listeners.transition.delete(callback);
+        };
+    }
+    /**
+     * Get connected wallet ID if in connected state
+     */
+    getConnectedWalletId() {
+        if (this.state.status === "connected") {
+            return this.state.walletId;
+        }
+        return null;
+    }
+    /**
+     * Get connected accounts if in connected state
+     */
+    getConnectedAccounts() {
+        if (this.state.status === "connected") {
+            return this.state.accounts;
+        }
+        return [];
+    }
+    /**
+     * Get error if in error state
+     */
+    getError() {
+        if (this.state.status === "error") {
+            return this.state.error;
+        }
+        return null;
+    }
+    /**
+     * Get time spent in current state
+     */
+    getTimeInCurrentState() {
+        const stateWithTime = this.state;
+        const startTime = stateWithTime.startedAt ?? stateWithTime.connectedAt ?? stateWithTime.occurredAt;
+        if (!startTime)
+            return 0;
+        return Date.now() - startTime;
+    }
+    /**
+     * Check if current state has timed out
+     */
+    hasTimedOut(timeoutMs) {
+        return this.getTimeInCurrentState() > timeoutMs;
+    }
+    /**
+     * Persist state to storage
+     */
+    persistState() {
+        if (typeof localStorage === "undefined")
+            return;
+        try {
+            const data = {
+                state: this.state,
+                timestamp: Date.now(),
+            };
+            localStorage.setItem(this.config.storageKey, JSON.stringify(data));
+        }
+        catch (e) {
+            console.warn("Failed to persist state:", e);
+        }
+    }
+    /**
+     * Restore state from storage
+     */
+    restoreState() {
+        if (!this.config.persistState || typeof localStorage === "undefined")
+            return;
+        try {
+            const raw = localStorage.getItem(this.config.storageKey);
+            if (!raw)
+                return;
+            const data = JSON.parse(raw);
+            // Check expiration
+            if (Date.now() - data.timestamp > this.config.stateExpiration) {
+                this.clearPersistedState();
+                return;
+            }
+            // Only restore "connected" state (others are transient)
+            if (data.state.status === "connected") {
+                this.state = data.state;
+            }
+        }
+        catch (e) {
+            console.warn("Failed to restore state:", e);
+            this.clearPersistedState();
+        }
+    }
+    /**
+     * Clear persisted state
+     */
+    clearPersistedState() {
+        if (typeof localStorage === "undefined")
+            return;
+        try {
+            localStorage.removeItem(this.config.storageKey);
+        }
+        catch (e) {
+            console.warn("Failed to clear persisted state:", e);
+        }
+    }
+    /**
+     * Create a snapshot of current state
+     */
+    snapshot() {
+        return {
+            state: { ...this.state },
+            history: this.getHistory(),
+            timestamp: Date.now(),
+        };
+    }
+    /**
+     * Check if currently processing (not idle or connected)
+     */
+    isProcessing() {
+        return !["idle", "connected"].includes(this.state.status);
+    }
+    /**
+     * Check if in a stable state (idle or connected)
+     */
+    isStable() {
+        return ["idle", "connected"].includes(this.state.status);
+    }
+    /**
+     * Wait for state to become stable
+     */
+    async waitForStable(timeoutMs = 30000) {
+        if (this.isStable()) {
+            return this.state;
+        }
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                unsubscribe();
+                reject(new errors_1.WalletError({
+                    code: errors_1.ErrorCode.CONNECTION_TIMEOUT,
+                    message: "Timed out waiting for stable state",
+                }));
+            }, timeoutMs);
+            const unsubscribe = this.onTransition((_, to) => {
+                if (["idle", "connected", "error"].includes(to.status)) {
+                    clearTimeout(timeoutId);
+                    unsubscribe();
+                    resolve(to);
+                }
+            });
+        });
+    }
+    /**
+     * Cleanup
+     */
+    destroy() {
+        this.listeners.enter.clear();
+        this.listeners.exit.clear();
+        this.listeners.transition.clear();
+        this.history = [];
+    }
+}
+exports.ConnectionStateMachine = ConnectionStateMachine;
+/**
+ * Create a simple state machine instance
+ */
+function createStateMachine(config) {
+    return new ConnectionStateMachine(config);
+}
+/**
+ * Get human-readable status description
+ */
+function getStatusDescription(status) {
+    switch (status) {
+        case "idle":
+            return "Not connected";
+        case "detecting":
+            return "Detecting wallet";
+        case "connecting":
+            return "Connecting to wallet";
+        case "authenticating":
+            return "Waiting for approval";
+        case "connected":
+            return "Connected";
+        case "signing":
+            return "Signing transaction";
+        case "reconnecting":
+            return "Reconnecting";
+        case "disconnecting":
+            return "Disconnecting";
+        case "error":
+            return "Error occurred";
+        default:
+            return "Unknown";
+    }
+}
+//# sourceMappingURL=state.js.map

package/build/connection/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/connection/state.ts"],"names":[],"mappings":"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"}

package/build/errors.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Error codes for wallet connection errors
+ */
+export declare enum ErrorCode {
+    WALLET_NOT_FOUND = "WALLET_NOT_FOUND",
+    EXTENSION_NOT_INSTALLED = "EXTENSION_NOT_INSTALLED",
+    EXTENSION_LOCKED = "EXTENSION_LOCKED",
+    USER_REJECTED = "USER_REJECTED",
+    CONNECTION_TIMEOUT = "CONNECTION_TIMEOUT",
+    NETWORK_MISMATCH = "NETWORK_MISMATCH",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    RPC_ERROR = "RPC_ERROR",
+    SESSION_EXPIRED = "SESSION_EXPIRED",
+    SESSION_INVALID = "SESSION_INVALID",
+    NO_ACTIVE_SESSION = "NO_ACTIVE_SESSION",
+    TRANSACTION_FAILED = "TRANSACTION_FAILED",
+    INSUFFICIENT_FUNDS = "INSUFFICIENT_FUNDS",
+    INVALID_TRANSACTION = "INVALID_TRANSACTION",
+    GAS_EXCEEDED = "GAS_EXCEEDED",
+    SANDBOX_BLOCKED = "SANDBOX_BLOCKED",
+    SANDBOX_TIMEOUT = "SANDBOX_TIMEOUT",
+    EXECUTOR_LOAD_FAILED = "EXECUTOR_LOAD_FAILED",
+    SIGN_MESSAGE_FAILED = "SIGN_MESSAGE_FAILED",
+    SIGN_TRANSACTION_FAILED = "SIGN_TRANSACTION_FAILED",
+    NO_ACCOUNTS = "NO_ACCOUNTS",
+    ACCOUNT_NOT_FOUND = "ACCOUNT_NOT_FOUND",
+    MANIFEST_LOAD_FAILED = "MANIFEST_LOAD_FAILED",
+    INVALID_MANIFEST = "INVALID_MANIFEST",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * Recovery actions that can be suggested to users
+ */
+export type RecoveryAction = "install" | "unlock" | "retry" | "switch_network" | "reconnect" | "clear_session" | "select_different_wallet" | "check_balance" | "contact_support" | "open_app" | "refresh";
+/**
+ * Recovery option with action and metadata
+ */
+export interface RecoveryOption {
+    action: RecoveryAction;
+    label: string;
+    description?: string;
+    url?: string;
+    handler?: () => Promise<void>;
+}
+/**
+ * Base error class for all wallet connection errors
+ */
+export declare class WalletError extends Error {
+    readonly code: ErrorCode;
+    readonly walletId?: string;
+    readonly userMessage: string;
+    readonly recoveryOptions: RecoveryOption[];
+    readonly originalError?: Error;
+    readonly timestamp: number;
+    constructor(options: {
+        code: ErrorCode;
+        message: string;
+        userMessage?: string;
+        walletId?: string;
+        recoveryOptions?: RecoveryOption[];
+        originalError?: Error;
+    });
+    private getDefaultUserMessage;
+    private getDefaultRecoveryOptions;
+    /**
+     * Check if the error is recoverable
+     */
+    get isRecoverable(): boolean;
+    /**
+     * Check if the error was caused by user action
+     */
+    get isUserAction(): boolean;
+    /**
+     * Serialize error for logging/analytics
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Specific error classes for common scenarios
+ */
+export declare class WalletNotFoundError extends WalletError {
+    constructor(walletId: string, installUrl?: string);
+}
+export declare class UserRejectedError extends WalletError {
+    constructor(walletId?: string, action?: string);
+}
+export declare class ConnectionTimeoutError extends WalletError {
+    constructor(walletId?: string, timeoutMs?: number);
+}
+export declare class NetworkMismatchError extends WalletError {
+    readonly expectedNetwork: string;
+    readonly actualNetwork?: string;
+    constructor(expectedNetwork: string, actualNetwork?: string, walletId?: string);
+}
+export declare class TransactionError extends WalletError {
+    readonly transactionHash?: string;
+    constructor(options: {
+        code?: ErrorCode;
+        message: string;
+        walletId?: string;
+        transactionHash?: string;
+        originalError?: Error;
+    });
+}
+export declare class SessionError extends WalletError {
+    constructor(code: ErrorCode.SESSION_EXPIRED | ErrorCode.SESSION_INVALID | ErrorCode.NO_ACTIVE_SESSION, walletId?: string);
+}
+export declare class SandboxError extends WalletError {
+    constructor(code: ErrorCode.SANDBOX_BLOCKED | ErrorCode.SANDBOX_TIMEOUT | ErrorCode.EXECUTOR_LOAD_FAILED, walletId?: string, originalError?: Error);
+}
+export declare class SigningError extends WalletError {
+    readonly action: "message" | "transaction";
+    constructor(options: {
+        action: "message" | "transaction";
+        message: string;
+        walletId?: string;
+        originalError?: Error;
+    });
+}
+export declare class RpcError extends WalletError {
+    readonly endpoint?: string;
+    readonly statusCode?: number;
+    constructor(options: {
+        message: string;
+        endpoint?: string;
+        statusCode?: number;
+        originalError?: Error;
+    });
+}
+export declare class ManifestError extends WalletError {
+    readonly manifestUrl?: string;
+    constructor(options: {
+        code: ErrorCode.MANIFEST_LOAD_FAILED | ErrorCode.INVALID_MANIFEST;
+        message: string;
+        manifestUrl?: string;
+        originalError?: Error;
+    });
+}
+/**
+ * Type guard to check if an error is a WalletError
+ */
+export declare function isWalletError(error: unknown): error is WalletError;
+/**
+ * Type guard to check if error has a specific code
+ */
+export declare function hasErrorCode<C extends ErrorCode>(error: unknown, code: C): error is WalletError & {
+    code: C;
+};
+/**
+ * Serialized error format for storage/transmission
+ */
+export interface SerializedWalletError {
+    name: string;
+    code: ErrorCode;
+    message: string;
+    userMessage: string;
+    walletId?: string;
+    recoveryOptions: RecoveryAction[];
+    timestamp: number;
+    originalMessage?: string;
+}
+/**
+ * Deserialize a WalletError from JSON
+ */
+export declare function deserializeError(data: SerializedWalletError): WalletError;
+/**
+ * Helper to wrap unknown errors with improved pattern detection
+ */
+export declare function wrapError(error: unknown, walletId?: string): WalletError;
+/**
+ * Get a user-friendly message for any error
+ */
+export declare function getUserFriendlyMessage(error: unknown): string;
+/**
+ * Get recovery options for any error
+ */
+export declare function getRecoveryOptions(error: unknown): RecoveryOption[];