@chipi-stack/starknet-connector 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,10 +1,372 @@
-export { chipi } from "./factory.js";
-export { ChipiConnector } from "./connector.js";
-export type { ChipiConnectorOptions } from "./connector.js";
-export { ChipiPopupTransport } from "./transport.js";
-export type { ChipiTransportOptions } from "./transport.js";
-export { registerChipiWallet, CHIPI_WINDOW_KEY } from "./register.js";
-export type { ChipiRegistration } from "./register.js";
-export { CHIPI_WC, isChipiWalletMessage, isChipiDappMessage } from "./protocol.js";
-export type { ChipiRpcCall, ChipiReadyMessage, ChipiRpcRequestMessage, ChipiRpcResultMessage, ChipiEventMessage, ChipiWalletMessage, ChipiDappMessage, } from "./protocol.js";
-//# sourceMappingURL=index.d.ts.map
+import { Connector } from '@starknet-react/core';
+import { ProviderInterface, AccountInterface } from 'starknet';
+import { StarknetWindowObject, RpcMessage, RequestFnCall, RpcTypeToMessageMap, RequestFn } from '@starknet-io/types-js';
+
+/**
+ * Wire protocol between the "Connect with Chipi" connector (running in the dApp)
+ * and the Chipi hosted wallet (running at `wallet.chipipay.com` in a popup).
+ *
+ * Both sides import these shapes so the contract stays in lock-step. The
+ * transport is `window.postMessage`: the dApp opens the wallet in a popup,
+ * forwards get-starknet `wallet_*` RPC calls over the channel, and the wallet
+ * answers after the user approves in its own (already-built) approval UI.
+ */
+/** A get-starknet RPC call as sent over the wire: just the discriminant +
+ * optional params (the full typed `RpcMessage` carries result/errors we don't
+ * serialize). */
+interface ChipiRpcCall {
+    type: string;
+    params?: unknown;
+}
+/** Namespace tag on every message so we ignore unrelated postMessages. */
+declare const CHIPI_WC: "chipi-connect/v1";
+/** wallet → dApp: the hosted wallet page finished loading and is listening. */
+interface ChipiReadyMessage {
+    channel: typeof CHIPI_WC;
+    type: "ready";
+}
+/** dApp → wallet: forward a get-starknet `wallet_*` RPC call. */
+interface ChipiRpcRequestMessage {
+    channel: typeof CHIPI_WC;
+    type: "rpc";
+    id: string;
+    /** The dApp origin, so the wallet can show it + enforce Verify checks. */
+    origin: string;
+    call: ChipiRpcCall;
+}
+/** wallet → dApp: the result (or error) for a given request id. */
+type ChipiRpcResultMessage = {
+    channel: typeof CHIPI_WC;
+    type: "rpc-result";
+    id: string;
+    ok: true;
+    result: unknown;
+} | {
+    channel: typeof CHIPI_WC;
+    type: "rpc-result";
+    id: string;
+    ok: false;
+    error: {
+        code: number;
+        message: string;
+    };
+};
+/** wallet → dApp: an account/network change to propagate to the dApp. */
+interface ChipiEventMessage {
+    channel: typeof CHIPI_WC;
+    type: "event";
+    event: "accountsChanged" | "networkChanged";
+    data: unknown;
+}
+type ChipiWalletMessage = ChipiReadyMessage | ChipiRpcResultMessage | ChipiEventMessage;
+type ChipiDappMessage = ChipiRpcRequestMessage;
+declare function isChipiWalletMessage(data: unknown): data is ChipiWalletMessage;
+/** Type guard for a dApp→wallet message (used by the hosted wallet side). */
+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 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 {
+    /** Hosted wallet base URL, e.g. `https://wallet.chipipay.com`. */
+    walletUrl: string;
+    /**
+     * Transport mode:
+     *  - `"popup"` (default): open the hosted wallet in a popup window: the
+     *    universal model, works for any external dApp.
+     *  - `"parent"`: the dApp is embedded in an iframe INSIDE the Chipi wallet
+     *    (in-app browser); talk to `window.parent` instead of opening a popup, so
+     *    approval renders inline in the wallet. Only works when the dApp is
+     *    actually iframed by the Chipi host.
+     *  - `"auto"`: use `"parent"` when running inside an iframe, else `"popup"`.
+     */
+    mode?: "popup" | "parent" | "auto";
+    /** Popup window name. */
+    windowName?: string;
+    /** Popup window features. */
+    windowFeatures?: string;
+    /** 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 {
+    private readonly opts;
+    private readonly walletOrigin;
+    private readonly url;
+    private target;
+    private ownsTarget;
+    private ready;
+    private listening;
+    private readonly pending;
+    private readonly handlers;
+    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;
+    private ensureListener;
+    private onMessage;
+    /** Resolve "auto" → "parent" when iframed, else "popup". */
+    private resolveMode;
+    /** Open (or reuse) the wallet (popup window OR the parent frame) and wait for
+     * 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;
+    /** While requests are in flight, watch for the user closing the popup and
+     * 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.
+     *
+     * 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;
+}
+
+/**
+ * `ChipiConnector`: a starknet-react / get-starknet connector for the Chipi
+ * hosted smart-account wallet. A self-contained connector package any dApp
+ * adds to its `connectors` array (`new ChipiConnector()`) directly: no
+ * whitelisting, no dependency on a third-party wallet kit, and NO browser
+ * extension required. Clicking "Connect with Chipi" opens our hosted wallet
+ * (passkey + gasless paymaster) in a popup; the dApp's `wallet_*` RPC calls are
+ * forwarded over postMessage and answered after the user approves in Chipi's
+ * own (already-built) approval UI.
+ */
+
+type ConnectorIcons = StarknetWindowObject["icon"];
+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;
+    /** Override the connector id / display name / icon if embedding. */
+    id?: string;
+    name?: string;
+    icon?: ConnectorIcons;
+    transport?: ChipiTransportOptions;
+    /**
+     * 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
+     * `false` to opt out (e.g. to avoid a double entry in a picker that already
+     * lists the connector explicitly). No-op during SSR.
+     */
+    register?: boolean;
+}
+declare class ChipiConnector extends Connector {
+    private readonly transport;
+    private readonly _id;
+    private readonly _name;
+    private readonly _icon;
+    private _account;
+    private _swo;
+    private _registration;
+    private readonly _autoRegister;
+    constructor(options?: ChipiConnectorOptions);
+    /**
+     * Announce this wallet to scanning dApps (`window.starknet_chipi` +
+     * `starknet:announceWallet`). Called automatically from the constructor
+     * unless `register: false`. Idempotent and SSR-safe.
+     */
+    register(): void;
+    /** Undo {@link register}: remove the window object + announce listener. */
+    unregister(): void;
+    get id(): string;
+    get name(): string;
+    get icon(): ConnectorIcons;
+    /** Hosted wallet: always available (no extension to detect). */
+    available(): boolean;
+    /** No silent reconnect in v1: the user re-approves the popup each session. */
+    ready(): Promise<boolean>;
+    /** Lazily build the postMessage-backed get-starknet window object. */
+    private swo;
+    /**
+     * 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>;
+    request<T extends RpcMessage["type"]>(call: RequestFnCall<T>): Promise<RpcTypeToMessageMap[T]["result"]>;
+}
+
+/**
+ * Plain-function form of {@link ChipiConnector}, for parity with
+ * `@starknet-react/core`'s built-in factories (`ready()`, `braavos()`):
+ *
+ *   const connectors = [chipi(), ready(), braavos()];
+ *
+ * Equivalent to `new ChipiConnector(options)`: use whichever reads better
+ * in your `connectors` array.
+ */
+declare function chipi(options?: ChipiConnectorOptions): ChipiConnector;
+
+/** Window key get-starknet discovers by scanning for `starknet*` properties. */
+declare const CHIPI_WINDOW_KEY = "starknet_chipi";
+interface ChipiRegistration {
+    /** Remove `window.starknet_chipi` + the announce listener. */
+    dispose: () => void;
+}
+/**
+ * Make a Chipi `StarknetWindowObject` discoverable to any get-starknet /
+ * starknet-react / starknetkit dApp on the page: WITHOUT an upstream PR and
+ * WITHOUT whitelisting. This self-registration covers the apps that scan for
+ * wallets rather than importing our connector explicitly.
+ *
+ * Discovery is announced two ways for maximum reach:
+ *  1. **window scan**: set `window.starknet_chipi`. get-starknet v4's
+ *     `getAvailableWallets()` finds every `window` key starting with `starknet`.
+ *  2. **event announce**: dispatch `starknet:announceWallet` now and again on
+ *     the dApp's `starknet:requestWallets` (the EIP-6963-style, timing-robust
+ *     Starknet Wallet Standard discovery path).
+ *
+ * SSR-safe (no-ops when there's no `window`) and idempotent per (target, wallet).
+ */
+declare function registerChipiWallet(wallet: StarknetWindowObject, target?: (Window & typeof globalThis) | undefined): ChipiRegistration;
+
+/**
+ * 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 };