@chipi-stack/starknet-connector 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,236 @@
+import { Connector } from '@starknet-react/core';
+import { ProviderInterface, AccountInterface } from 'starknet';
+import { StarknetWindowObject, RpcMessage, RequestFnCall, RpcTypeToMessageMap } 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 closed it, the next request reopens it.
+ */
+
+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). */
+    openTimeoutMs?: number;
+}
+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;
+    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;
+    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. */
+    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;
+};
+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;
+    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;
+    connect(): Promise<ConnectorData>;
+    disconnect(): Promise<void>;
+    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;
+
+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 };

package/dist/index.d.ts

@@ -1,10 +1,236 @@
-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 } 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 closed it, the next request reopens it.
+ */
+
+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). */
+    openTimeoutMs?: number;
+}
+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;
+    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;
+    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. */
+    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;
+};
+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;
+    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;
+    connect(): Promise<ConnectorData>;
+    disconnect(): Promise<void>;
+    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;
+
+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 };