Add useWalletLink hook

[VishwajeetTulse]

Summary

Adds useWalletLink, the headless half of the library, and tightens the
transports typing on createWalletLinkConfig.

useWalletLink

Wraps wagmi's useConnectors / useAccount / useConnect / useDisconnect
into a single hook, so a dapp gets the EIP-6963-discovered wallets,
connect/disconnect, and the current account from one import.

Returns wallets, connect / connectAsync, disconnect / disconnectAsync,
the account (address, chain, chainId, connector, status, and the
isConnected / isConnecting / isReconnecting / isDisconnected flags),
plus pendingWallet, error, and reset.

Two details worth a reviewer's eye:

• pendingWallet reports the specific wallet mid-connect, so the UI can show
  a pending state on the button the user actually clicked. It's gated on
  isPending because react-query's variables outlive the mutation and would
  otherwise keep naming a wallet after the attempt settled.
• No 'use client' directive, deliberately. tsup silently strips it, and
  making it survive would be wrong anyway: the bundle is a single file, so the
  directive would be hoisted over createWalletLinkConfig and make it a
  client-only export, breaking cookieToInitialState(config, ...), which has to
  run in a Server Component and is exactly what the SSR cookie storage exists to
  serve. The hook is client-only regardless; the calling component supplies the
  boundary. See "Follow-ups" below.

Fix: transports must cover every chain

transports was Record<number, Transport>, which is looser than the
Record<chains[number]['id'], Transport> wagmi itself enforces. A map missing a
chain compiled clean and then threw
TypeError: rest.transports[chainId] is not a function from inside wagmi, the
first time anything touched that chain, far from the cause.

Keying it to chains restores the compile-time check, and a const type
parameter narrows the chain ids to literals so the error names the missing chain:

Property '1' is missing in type '{ 11155111: HttpTransport; }'
  but required in type 'Record<1 | 11155111, Transport>'

Omitting transports still generates a complete set of http() defaults.

Testing

typecheck, lint, format:check, and build all pass. Verified by probe that
a partial transports map is now rejected at compile time while a complete map
and an omitted one both compile; smoke-tested the built CJS bundle for its
exports and for no regression in the config.

Summary by CodeRabbit

• New Features
  • Added a headless wallet connection hook with wallet discovery, connection and disconnection actions, account and network details, status indicators, pending-wallet tracking, and error handling.
  • Exposed the wallet hook and its related types through the public package entrypoint.
  • Improved configuration typing so transport settings are matched to the configured chains.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: ASSERTIVE

Plan: Pro

Run ID: bf3a7b2b-f268-49a4-be0c-b22589a11bd5

📥 Commits

Reviewing files that changed from the base of the PR and between 9a339a9 and 25a8fa2.

📒 Files selected for processing (3)

• src/config.ts
• src/index.ts
• src/useWalletLink.ts

---

Walkthrough

This change adds chain-aware transport typing to wallet configuration and introduces a public headless useWalletLink hook backed by wagmi. The package entrypoint now exports the hook and its connection-related types.

Changes

WalletLink API

Layer / File(s)	Summary
Chain-aware configuration typing src/config.ts	CreateWalletLinkConfigParameters and createWalletLinkConfig preserve the chain tuple and derive transport keys from chain IDs.
Headless wallet connection hook and exports src/useWalletLink.ts, src/index.ts	Adds wagmi-backed wallet discovery, connection and disconnection actions, account state, lifecycle status, pending wallet tracking, errors, reset behavior, and public barrel exports.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant useWalletLink
  participant wagmiHooks
  participant Connector
  Client->>useWalletLink: invoke hook
  useWalletLink->>wagmiHooks: read connectors and account state
  wagmiHooks-->>useWalletLink: wallets and connection state
  Client->>useWalletLink: call connect(parameters)
  useWalletLink->>wagmiHooks: invoke connect with connector and chainId
  wagmiHooks->>Connector: connect wallet
  Connector-->>wagmiHooks: return accounts and chainId
  wagmiHooks-->>useWalletLink: update connection state
  useWalletLink-->>Client: return result and state

Loading

Possibly related PRs

• StabilityNexus/WalletLink#1: Adds the initial configuration and type scaffolding refined by this change.

Suggested labels: Typescript Lang

Poem

A rabbit hops where wallets gleam,
Chains line up in a typed-up stream.
Wagmi knocks; connectors sing,
Accounts bloom on swiftest wing.
“Connect!” I cheer—and nudge the spring.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: adding the useWalletLink hook.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/use-walletlink-hook

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install timed out. The project may have too many dependencies for the sandbox.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}