@chipi-stack/starknet-connector 0.2.0 → 0.4.0

package/README.md

@@ -1,15 +1,19 @@
 # @chipi-stack/starknet-connector
 
-**"Connect with Chipi"** — a [starknet-react](https://starknet-react.com) /
+**"Connect with Chipi"**, a [starknet-react](https://starknet-react.com) /
 [get-starknet](https://github.com/starknet-io/get-starknet) connector that lets
 any Starknet dApp connect to a **Chipi hosted smart-account wallet** (passkey,
-gasless via paymaster). No browser extension, no WalletConnect, no whitelisting
-— add the package to your own dApp and it just works.
+gasless via paymaster). No browser extension, no WalletConnect, no whitelisting,
+just add the package to your own dApp and it works.
 
 ```bash
 npm install @chipi-stack/starknet-connector
 ```
 
+Ships both ESM and CommonJS. Versions before 0.3.0 were ESM-only and failed
+under any CommonJS resolver (plain Node, `tsx`, `ts-node`, Jest) with
+`ERR_PACKAGE_PATH_NOT_EXPORTED`. Bundlers were never affected.
+
 ## Use it
 
 Add one connector to your `StarknetConfig`:
@@ -36,7 +40,7 @@ export function App({ children }) {
 
 That's it. Your existing `useConnect` / `useAccount` flow now offers "Connect
 with Chipi", and `account.signMessage(...)` / `account.execute(...)` route to the
-user's Chipi wallet — **gasless**, signed with their passkey.
+user's Chipi wallet, **gasless**, signed with their passkey.
 
 ## How it works
 
@@ -50,11 +54,11 @@ account.execute(calls)
    └─ wallet_addInvokeTransaction ─► user approves ─► sponsored tx ─► tx hash
 ```
 
-- The connector is **transport only** — it opens the hosted wallet in a popup and
+- The connector is **transport only**: it opens the hosted wallet in a popup and
   forwards get-starknet `wallet_*` RPC calls over `postMessage`. It holds no
   keys and signs nothing itself.
 - The hosted wallet renders a **decoded approval** for every sign/execute (it
-  shows the actual intent — token, amount, spender — and hard-blocks typed data
+  shows the actual intent, token, amount, spender, and hard-blocks typed data
   it can't read), then runs the real passkey + paymaster path.
 - `account()` wraps the channel in a `starknet.js` `WalletAccount`, so the dApp
   uses a standard `AccountInterface`.
@@ -68,38 +72,78 @@ chipi({
   name: "Connect with Chipi", // display name
   icon: "data:image/svg+xml;base64,...", // display icon
   register: true, // self-register on window (default)
+  transport: {
+    openTimeoutMs: 180_000, // ready handshake; on timeout the popup is closed
+    requestTimeoutMs: 120_000, // per request; 0 disables
+  },
 });
 ```
 
-`chipi(options)` is a thin wrapper — `new ChipiConnector(options)` still works
+`chipi(options)` is a thin wrapper: `new ChipiConnector(options)` still works
 identically if you prefer instantiating the class directly.
 
+## Events and errors
+
+- The connector forwards the wallet's `accountsChanged` / `networkChanged` as
+  starknet-react `change` events (`{ account, chainId }`); an empty account list
+  emits `disconnect`.
+- `connect({ chainIdHint })` rejects with `code: "UNSUPPORTED_CHAIN"` for any
+  chain other than mainnet (`SN_MAIN`), before opening a popup.
+- A request that gets no answer within `requestTimeoutMs` rejects with
+  `code: "REQUEST_TIMEOUT"`.
+- If the user closes the wallet window, later requests reject with
+  `code: "POPUP_CLOSED"` instead of reopening it (browsers block popups outside
+  a click). Call `connect()` again from a click.
+- `disconnect()` closes the popup and removes `window.starknet_chipi`; the next
+  `connect()` registers it again.
+
 ## Compatibility
 
 - `@starknet-react/core` **>= 3** (peer) · tested against `5.x`
-- `starknet` **>= 8.1.2** (peer) — `WalletAccount.connect` is identical across 8/9
+- `starknet` **>= 8.1.2** (peer); `WalletAccount.connect` is identical across 8/9
 - **Starknet mainnet** (v1). The wallet is mainnet-only.
 
 ## Discovery
 
 Instantiating the connector also **self-registers** the wallet on `window`
-(`window.starknet_chipi` + a `starknet:announceWallet` event — the get-starknet /
+(`window.starknet_chipi` + a `starknet:announceWallet` event, the get-starknet /
 Starknet-Wallet-Standard discovery path), so dApps that _scan_ for wallets find
-"Connect with Chipi" even if they don't import this package — no whitelisting,
+"Connect with Chipi" even if they don't import this package, no whitelisting,
 no coordination with us required. Pass `register: false` to opt out (e.g. to
 avoid a duplicate entry in a picker that already lists the connector
 explicitly). It's a no-op during SSR. You can also call
 `registerChipiWallet(swo)` directly.
 
+### Wallet Standard (get-starknet v5+ discovery)
+
+For dApps that discover wallets through the Wallet Standard
+(`@starknet-io/get-starknet-discovery`, `@starknet-start/react`), register Chipi
+as a `WalletWithStarknetFeatures` (`starknet:walletApi`, `standard:connect`,
+`standard:disconnect`, `standard:events`) backed by the same popup:
+
+```ts
+import { registerChipiStandardWallet } from "@chipi-stack/starknet-connector";
+
+const unregister = registerChipiStandardWallet({
+  walletUrl: "https://wallet.chipipay.com", // default
+});
+// later: unregister();
+```
+
+It dispatches `wallet-standard:register-wallet` and answers
+`wallet-standard:app-ready`, with no extra dependency. Accounts are on
+`starknet:0x534e5f4d41494e` (mainnet). `connect({ silent: true })` never opens a
+popup. Use `createChipiStandardWallet(options)` to build the wallet object
+without registering it.
+
 ## Notes / limits (v1)
 
 - **Popup-based** (external dApps). The in-app-browser ("parent") mode is in the
-  transport but not exposed yet — the hosted wallet side handles it in a later
+  transport but not exposed yet; the hosted wallet side handles it in a later
   release.
-- Mainnet only — pass a mainnet `provider`.
+- Mainnet only, pass a mainnet `provider`.
 - One approval at a time; a dApp that fires two prompts truly simultaneously has
   its second request rejected (most dApps serialize).
 
 MIT · [docs.chipipay.com](https://docs.chipipay.com) ·
-[example](https://github.com/chipi-pay/build-with-chipi/tree/feat/connect-with-chipi-tutorial/tutorials/03-connect-with-chipi)
-(pending merge — [PR #22](https://github.com/chipi-pay/build-with-chipi/pull/22))
+[example](https://github.com/chipi-pay/build-with-chipi/tree/main/tutorials/03-connect-with-chipi)