@unicitylabs/sphere-sdk 0.6.4 → 0.6.6

package/dist/impl/browser/connect/index.d.ts

@@ -73,6 +73,27 @@ interface PublicIdentity {
     readonly nametag?: string;
 }
 
+/**
+ * Sphere Connect Permission System
+ * Defines scopes, maps methods/intents to required permissions.
+ */
+declare const PERMISSION_SCOPES: {
+    readonly IDENTITY_READ: "identity:read";
+    readonly BALANCE_READ: "balance:read";
+    readonly TOKENS_READ: "tokens:read";
+    readonly HISTORY_READ: "history:read";
+    readonly L1_READ: "l1:read";
+    readonly EVENTS_SUBSCRIBE: "events:subscribe";
+    readonly RESOLVE_PEER: "resolve:peer";
+    readonly TRANSFER_REQUEST: "transfer:request";
+    readonly L1_TRANSFER: "l1:transfer";
+    readonly DM_REQUEST: "dm:request";
+    readonly DM_READ: "dm:read";
+    readonly PAYMENT_REQUEST: "payment:request";
+    readonly SIGN_REQUEST: "sign:request";
+};
+type PermissionScope = (typeof PERMISSION_SCOPES)[keyof typeof PERMISSION_SCOPES];
+
 /**
  * Sphere Connect Types
  * Session, configuration, and callback types.
@@ -86,6 +107,81 @@ interface ConnectTransport {
     /** Clean up transport resources */
     destroy(): void;
 }
+interface ConnectClientConfig {
+    /** Transport layer for communication */
+    transport: ConnectTransport;
+    /** dApp metadata sent during handshake */
+    dapp: DAppMetadata;
+    /** Permissions to request. Defaults to all. */
+    permissions?: PermissionScope[];
+    /** Timeout for query requests in ms. Default: 30000. */
+    timeout?: number;
+    /** Timeout for intent requests in ms (user interaction). Default: 120000. */
+    intentTimeout?: number;
+    /** Existing session ID to resume. If the host still has an active session
+     *  with this ID, the connection is restored without re-showing the approval UI. */
+    resumeSessionId?: string;
+    /** If true, the connection will silently fail if the origin is not already approved by the wallet.
+     *  No approval UI will be shown. Used for auto-connect on page load. */
+    silent?: boolean;
+}
+interface ConnectResult {
+    readonly sessionId: string;
+    readonly permissions: PermissionScope[];
+    readonly identity: PublicIdentity;
+}
+type ConnectEventHandler = (data: unknown) => void;
+
+/**
+ * ConnectClient — dApp side of Sphere Connect.
+ *
+ * Lightweight client that communicates with a wallet's ConnectHost
+ * through a ConnectTransport. Provides query and intent methods
+ * that mirror the Sphere SDK API.
+ *
+ * Zero dependencies on the Sphere SDK core.
+ */
+
+declare class ConnectClient {
+    private readonly transport;
+    private readonly dapp;
+    private readonly requestedPermissions;
+    private readonly timeout;
+    private readonly intentTimeout;
+    private readonly resumeSessionId;
+    private readonly silent;
+    private sessionId;
+    private grantedPermissions;
+    private identity;
+    private connected;
+    private pendingRequests;
+    private eventHandlers;
+    private unsubscribeTransport;
+    private handshakeResolver;
+    constructor(config: ConnectClientConfig);
+    /** Connect to the wallet. Returns session info and public identity. */
+    connect(): Promise<ConnectResult>;
+    /** Disconnect from the wallet */
+    disconnect(): Promise<void>;
+    /** Whether currently connected */
+    get isConnected(): boolean;
+    /** Granted permission scopes */
+    get permissions(): readonly PermissionScope[];
+    /** Current session ID */
+    get session(): string | null;
+    /** Public identity received during handshake */
+    get walletIdentity(): PublicIdentity | null;
+    /** Send a query request and return the result */
+    query<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    /** Send an intent request. The wallet will open its UI for user confirmation. */
+    intent<T = unknown>(action: string, params: Record<string, unknown>): Promise<T>;
+    /** Subscribe to a wallet event. Returns unsubscribe function. */
+    on(event: string, handler: ConnectEventHandler): () => void;
+    private handleMessage;
+    private handleHandshakeResponse;
+    private handlePendingResponse;
+    private cleanup;
+}
 
 /**
  * PostMessageTransport — Browser transport for Sphere Connect.
@@ -186,4 +282,88 @@ declare const ExtensionTransport: {
     forHost(chromeApi: ChromeMessagingApi): ConnectTransport;
 };
 
-export { type ChromeMessagingApi, EXT_MSG_TO_CLIENT, EXT_MSG_TO_HOST, type ExtensionConnectEnvelope, ExtensionTransport, type PostMessageClientOptions, type PostMessageHostOptions, PostMessageTransport, isExtensionConnectEnvelope };
+/**
+ * autoConnect — Universal dApp connection to Sphere wallet.
+ *
+ * Auto-detects the best available transport and connects:
+ *   P1: iframe   → PostMessageTransport to parent window
+ *   P2: extension → ExtensionTransport via chrome extension
+ *   P3: standalone → PostMessageTransport to popup window
+ *
+ * Usage:
+ *   import { autoConnect } from '@unicitylabs/sphere-sdk/connect/browser';
+ *
+ *   const client = await autoConnect({
+ *     dapp: { name: 'My App', url: location.origin },
+ *     walletUrl: 'https://sphere.unicity.network',
+ *   });
+ *
+ *   // Use the client — same API regardless of transport:
+ *   const balance = await client.query('sphere_getBalance');
+ *   await client.intent('send', { recipient: '@bob', amount: '1000', coinId: 'UCT' });
+ *   client.on('transfer:incoming', (data) => console.log(data));
+ */
+
+/** Returns true when the page is running inside an iframe. */
+declare function isInIframe(): boolean;
+/** Returns true when the Sphere browser extension is installed and active. */
+declare function hasExtension(): boolean;
+/** Detected transport type. */
+type DetectedTransport = 'iframe' | 'extension' | 'popup';
+/** Detect which transport to use based on the current environment. */
+declare function detectTransport(): DetectedTransport;
+interface AutoConnectConfig {
+    /** dApp metadata sent during handshake. */
+    dapp: DAppMetadata;
+    /**
+     * Wallet URL for popup fallback (P3).
+     * The URL will be opened with `/connect?origin=<current origin>` appended.
+     * Required if the extension is not installed and the page is not in an iframe.
+     */
+    walletUrl?: string;
+    /** Permissions to request. Defaults to all. */
+    permissions?: PermissionScope[];
+    /**
+     * If true, silently fail if the wallet has not previously approved this origin.
+     * No UI will be shown. Useful for auto-connect on page load.
+     * Default: false.
+     */
+    silent?: boolean;
+    /** Existing session ID to resume (for popup mode). */
+    resumeSessionId?: string;
+    /** Timeout for query requests in ms. Default: 30000. */
+    timeout?: number;
+    /** Timeout for intent requests in ms. Default: 120000. */
+    intentTimeout?: number;
+    /**
+     * Popup window features (width, height, etc.).
+     * Default: 'width=420,height=720,scrollbars=yes,resizable=yes'
+     */
+    popupFeatures?: string;
+    /**
+     * Force a specific transport instead of auto-detecting.
+     * Useful for testing or explicit control.
+     */
+    forceTransport?: DetectedTransport;
+}
+interface AutoConnectResult {
+    /** Connected client — use for queries, intents, and events. */
+    client: ConnectClient;
+    /** Connection result with session info and identity. */
+    connection: ConnectResult;
+    /** Which transport was selected. */
+    transport: DetectedTransport;
+    /**
+     * Disconnect and clean up all resources.
+     * For popup mode, also closes the popup window.
+     */
+    disconnect: () => Promise<void>;
+}
+/**
+ * Auto-detect the best transport and connect to the Sphere wallet.
+ *
+ * @throws Error if connection fails or is rejected by the wallet.
+ */
+declare function autoConnect(config: AutoConnectConfig): Promise<AutoConnectResult>;
+
+export { type AutoConnectConfig, type AutoConnectResult, type ChromeMessagingApi, type DetectedTransport, EXT_MSG_TO_CLIENT, EXT_MSG_TO_HOST, type ExtensionConnectEnvelope, ExtensionTransport, type PostMessageClientOptions, type PostMessageHostOptions, PostMessageTransport, autoConnect, detectTransport, hasExtension, isExtensionConnectEnvelope, isInIframe };