@chipi-stack/starknet-connector 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Connector } from '@starknet-react/core';
 import { ProviderInterface, AccountInterface } from 'starknet';
-import { StarknetWindowObject, RpcMessage, RequestFnCall, RpcTypeToMessageMap } from '@starknet-io/types-js';
+import { StarknetWindowObject, RpcMessage, RequestFnCall, RpcTypeToMessageMap, RequestFn } from '@starknet-io/types-js';
 
 /**
  * Wire protocol between the "Connect with Chipi" connector (running in the dApp)
@@ -68,7 +68,9 @@ declare function isChipiDappMessage(data: unknown): data is ChipiDappMessage;
  * Client-side (dApp) transport: opens the Chipi hosted wallet in a popup,
  * performs the ready handshake, and forwards get-starknet `wallet_*` RPC calls
  * over `postMessage`, correlating responses by id. The popup is reused across
- * requests; if the user closed it, the next request reopens it.
+ * requests. If the user closes it, later requests reject with `POPUP_CLOSED`
+ * instead of reopening it: `window.open` outside a click is blocked by
+ * browsers, so the dApp must call `connect()` (or `open()`) again from a click.
  */
 
 interface ChipiTransportOptions {
@@ -89,9 +91,19 @@ interface ChipiTransportOptions {
     windowName?: string;
     /** Popup window features. */
     windowFeatures?: string;
-    /** Ready-handshake timeout (ms). */
+    /** Ready-handshake timeout (ms). Defaults to 180_000. On timeout the popup is
+     * closed and the transport resets, so the next `open()` starts clean. */
     openTimeoutMs?: number;
+    /**
+     * Per-request timeout (ms), counted from when the request is posted to the
+     * wallet. Defaults to 120_000. A request that gets no answer in time rejects
+     * with an Error whose `code` (and `name`) is `"REQUEST_TIMEOUT"`. Pass `0` to
+     * disable.
+     */
+    requestTimeoutMs?: number;
 }
+/** Error codes the transport attaches to `Error.code` (besides wallet codes). */
+type ChipiTransportErrorCode = "REQUEST_TIMEOUT" | "POPUP_CLOSED";
 type EventName = "accountsChanged" | "networkChanged";
 type EventHandler = (data: unknown) => void;
 declare class ChipiPopupTransport {
@@ -107,6 +119,9 @@ declare class ChipiPopupTransport {
     private readyDeferred;
     private openPromise;
     private closeWatch;
+    /** True once this transport opened a popup. A later request with no live
+     * popup means the user closed it: reject instead of reopening off-gesture. */
+    private hadPopup;
     constructor(opts: ChipiTransportOptions);
     on(event: EventName, handler: EventHandler): void;
     off(event: EventName, handler: EventHandler): void;
@@ -118,6 +133,8 @@ declare class ChipiPopupTransport {
      * its ready handshake. Concurrent calls share ONE handshake. */
     open(): Promise<void>;
     private doOpen;
+    /** Close the popup (if we own one) and forget the target + ready state. */
+    private resetTarget;
     private awaitReady;
     /** Reject every in-flight request (popup closed / disconnected). */
     private rejectAllPending;
@@ -125,7 +142,19 @@ declare class ChipiPopupTransport {
      * reject them: otherwise the dApp's promise would hang forever. */
     private startCloseWatch;
     private stopCloseWatch;
-    /** Forward a get-starknet RPC call to the wallet, awaiting its response. */
+    /**
+     * Forward a get-starknet RPC call to the wallet, awaiting its response.
+     *
+     * With no wallet window open, passive calls are answered locally and never
+     * open it: `wallet_getPermissions` → `[]`, `wallet_requestAccounts` with
+     * `silent_mode: true` → `[]`, `wallet_requestChainId` → SN_MAIN.
+     *
+     * The first request may open the popup. Once a popup has been opened, a
+     * request made after it was closed rejects with `code: "POPUP_CLOSED"`
+     * instead of calling `window.open` again: requests usually run outside a
+     * click, where browsers block popups. Reopen via `connect()` / `open()`
+     * from a click.
+     */
     request(call: ChipiRpcCall): Promise<unknown>;
     /** Close the popup (if we own one) + reject in-flight requests. */
     close(): void;
@@ -147,6 +176,10 @@ type ConnectorData = {
     account?: string;
     chainId?: bigint;
 };
+/** Mirrors starknet-react's `ConnectArgs` (not exported by every version). */
+type ConnectArgs = {
+    chainIdHint?: bigint;
+};
 interface ChipiConnectorOptions {
     /** Hosted wallet base URL. Defaults to `https://wallet.chipipay.com`. */
     walletUrl?: string;
@@ -154,12 +187,19 @@ interface ChipiConnectorOptions {
     id?: string;
     name?: string;
     icon?: ConnectorIcons;
-    transport?: ChipiTransportOptions;
+    /**
+     * Popup transport tuning: `windowName`, `windowFeatures`, `openTimeoutMs`,
+     * `requestTimeoutMs`. `walletUrl` is optional here (the top-level
+     * `walletUrl` wins) and `mode` is always `"popup"`.
+     */
+    transport?: Omit<ChipiTransportOptions, "walletUrl"> & {
+        walletUrl?: string;
+    };
     /**
      * Self-register the wallet on `window` (set `window.starknet_chipi` + announce
-     * via `starknet:announceWallet`) so dApps that *scan* for wallets, raw
-     * get-starknet / Wallet-Standard consumers that don't import this connector,
-     * also discover "Connect with Chipi". Defaults to `true` in a browser; pass
+     * via `starknet:announceWallet`) so dApps that *scan* `window.starknet*`
+     * (get-starknet v4, get-starknet-discovery's injected scan) and don't import
+     * this connector also discover "Connect with Chipi". Defaults to `true` in a browser; pass
      * `false` to opt out (e.g. to avoid a double entry in a picker that already
      * lists the connector explicitly). No-op during SSR.
      */
@@ -173,6 +213,7 @@ declare class ChipiConnector extends Connector {
     private _account;
     private _swo;
     private _registration;
+    private readonly _autoRegister;
     constructor(options?: ChipiConnectorOptions);
     /**
      * Announce this wallet to scanning dApps (`window.starknet_chipi` +
@@ -191,8 +232,18 @@ declare class ChipiConnector extends Connector {
     ready(): Promise<boolean>;
     /** Lazily build the postMessage-backed get-starknet window object. */
     private swo;
-    connect(): Promise<ConnectorData>;
+    /**
+     * Open the hosted wallet (call from a click: it opens a popup) and request
+     * the account. Chipi is mainnet-only: a `chainIdHint` other than SN_MAIN
+     * rejects before any popup opens.
+     */
+    connect(args?: ConnectArgs): Promise<ConnectorData>;
     disconnect(): Promise<void>;
+    /** Forward the wallet's account/network events as starknet-react events. */
+    private subscribe;
+    private unsubscribe;
+    private onAccountsChanged;
+    private onNetworkChanged;
     private emitEvent;
     account(provider: ProviderInterface): Promise<AccountInterface>;
     chainId(): Promise<bigint>;
@@ -233,4 +284,100 @@ interface ChipiRegistration {
  */
 declare function registerChipiWallet(wallet: StarknetWindowObject, target?: (Window & typeof globalThis) | undefined): ChipiRegistration;
 
-export { CHIPI_WC, CHIPI_WINDOW_KEY, ChipiConnector, type ChipiConnectorOptions, type ChipiDappMessage, type ChipiEventMessage, ChipiPopupTransport, type ChipiReadyMessage, type ChipiRegistration, type ChipiRpcCall, type ChipiRpcRequestMessage, type ChipiRpcResultMessage, type ChipiTransportOptions, type ChipiWalletMessage, chipi, isChipiDappMessage, isChipiWalletMessage, registerChipiWallet };
+/**
+ * Chipi as a Wallet Standard wallet with Starknet features
+ * (`WalletWithStarknetFeatures` from `@starknet-io/get-starknet-wallet-standard`),
+ * so dApps on get-starknet v5+/v6 discovery (`@starknet-io/get-starknet-discovery`,
+ * `@starknet-start/react`, anything that listens for
+ * `wallet-standard:register-wallet`) list "Chipi" without importing this
+ * package's connector.
+ *
+ * Backed by the same popup transport as {@link ChipiConnector}. The types
+ * below mirror the upstream interfaces structurally so this package keeps no
+ * runtime (or type) dependency on `@wallet-standard/*`.
+ */
+
+/** Wallet Standard chain id for Starknet mainnet: `starknet:` + hex of "SN_MAIN"
+ * (same as `WELL_KNOWN_STARKNET_CHAINS[0]` in get-starknet-wallet-standard). */
+declare const CHIPI_STARKNET_MAINNET_CHAIN: "starknet:0x534e5f4d41494e";
+/** `starknet:0x...` chain identifier. */
+type ChipiStarknetChain = `starknet:0x${string}`;
+/** Data-URI icon, as Wallet Standard requires. */
+type ChipiWalletIcon = `data:image/${"svg+xml" | "webp" | "png" | "gif"};base64,${string}`;
+/** Mirrors `@wallet-standard/base` `WalletAccount`. */
+interface ChipiStandardWalletAccount {
+    readonly address: string;
+    readonly publicKey: Uint8Array;
+    readonly chains: readonly ChipiStarknetChain[];
+    readonly features: readonly `${string}:${string}`[];
+}
+/** Mirrors `@wallet-standard/features` `StandardEventsChangeProperties`. */
+interface ChipiStandardChangeProperties {
+    readonly chains?: readonly ChipiStarknetChain[];
+    readonly accounts?: readonly ChipiStandardWalletAccount[];
+}
+/** Mirrors `StarknetFeatures` from `@starknet-io/get-starknet-wallet-standard`.
+ * (A type alias, not an interface, so it satisfies Wallet Standard's
+ * `IdentifierRecord` index signature.) */
+type ChipiStandardWalletFeatures = {
+    readonly "starknet:walletApi": {
+        readonly version: "1.0.0";
+        readonly request: RequestFn;
+        readonly walletVersion: string;
+        readonly id: string;
+    };
+    readonly "standard:connect": {
+        readonly version: "1.0.0";
+        readonly connect: (input?: {
+            readonly silent?: boolean;
+        }) => Promise<{
+            readonly accounts: readonly ChipiStandardWalletAccount[];
+        }>;
+    };
+    readonly "standard:disconnect": {
+        readonly version: "1.0.0";
+        readonly disconnect: () => Promise<void>;
+    };
+    readonly "standard:events": {
+        readonly version: "1.0.0";
+        readonly on: <E extends "change">(event: E, listener: (properties: ChipiStandardChangeProperties) => void) => () => void;
+    };
+};
+/** Structurally a `WalletWithStarknetFeatures`. */
+interface ChipiStandardWallet {
+    readonly version: "1.0.0";
+    readonly name: string;
+    readonly icon: ChipiWalletIcon;
+    readonly chains: readonly ChipiStarknetChain[];
+    readonly accounts: readonly ChipiStandardWalletAccount[];
+    readonly features: ChipiStandardWalletFeatures;
+}
+interface ChipiStandardWalletOptions {
+    /** Hosted wallet base URL. Defaults to `https://wallet.chipipay.com`. */
+    walletUrl?: string;
+    /** Display name. Defaults to `"Chipi"`. */
+    name?: string;
+    /** Data-URI icon. Defaults to the Chipi icon. */
+    icon?: ChipiWalletIcon;
+    /** Popup transport tuning (window name/features, timeouts). */
+    transport?: Omit<ChipiTransportOptions, "walletUrl" | "mode">;
+}
+/**
+ * Build the Chipi Wallet Standard wallet (without registering it). `connect`
+ * opens the popup, so dApps call it from a click; `connect({ silent: true })`
+ * never opens a popup and returns the current accounts (empty if not
+ * connected).
+ */
+declare function createChipiStandardWallet(options?: ChipiStandardWalletOptions): ChipiStandardWallet;
+/**
+ * Register Chipi with every Wallet Standard app on the page: dispatches
+ * `wallet-standard:register-wallet` now and answers later
+ * `wallet-standard:app-ready` events (the `@wallet-standard/wallet`
+ * `registerWallet` protocol, implemented here without the dependency).
+ *
+ * Returns an unregister function that removes the listener and unregisters
+ * from every app that accepted the wallet. SSR-safe: a no-op without `window`.
+ */
+declare function registerChipiStandardWallet(options?: ChipiStandardWalletOptions, target?: (Window & typeof globalThis) | undefined): () => void;
+
+export { CHIPI_STARKNET_MAINNET_CHAIN, CHIPI_WC, CHIPI_WINDOW_KEY, ChipiConnector, type ChipiConnectorOptions, type ChipiDappMessage, type ChipiEventMessage, ChipiPopupTransport, type ChipiReadyMessage, type ChipiRegistration, type ChipiRpcCall, type ChipiRpcRequestMessage, type ChipiRpcResultMessage, type ChipiStandardChangeProperties, type ChipiStandardWallet, type ChipiStandardWalletAccount, type ChipiStandardWalletFeatures, type ChipiStandardWalletOptions, type ChipiStarknetChain, type ChipiTransportErrorCode, type ChipiTransportOptions, type ChipiWalletIcon, type ChipiWalletMessage, chipi, createChipiStandardWallet, isChipiDappMessage, isChipiWalletMessage, registerChipiStandardWallet, registerChipiWallet };