Migrate the TypeScript SDK from 0.3 to 0.4

Version 0.4.0 of @polygonlabs/oms-wallet changes how the active wallet and session are read, replaces the expiry callback with a session change callback, and renames several parameters and types. This page covers the changes most applications need. The full migration guide lists every change. If you use the wagmi connector, upgrade @polygonlabs/oms-wallet-wagmi-connector to the same version. Both packages are released together. The connector now follows the session: it disconnects when the session ends or a non-Ethereum wallet becomes active. Version 0.4.0 stores sessions in a new format, per project and environment, and does not restore sessions saved by 0.3. Each user signs in once after the upgrade. The 0.3 records are left in storage unread.

Read the active wallet

omsWallet.wallet.walletAddress was removed. Read omsWallet.wallet.activeWallet, a WalletAccount or undefined when signed out. Narrowing on type gives an Ethereum wallet a viem Address.

import { WalletType } from '@polygonlabs/oms-wallet'

// 0.3
const address = omsWallet.wallet.walletAddress

// 0.4
const activeWallet = omsWallet.wallet.activeWallet
if (activeWallet?.type === WalletType.Ethereum) {
  const address = activeWallet.address
}

Auth results and WalletActivationResult no longer have walletAddress. Use result.wallet.address.

Check `session` for `undefined`

omsWallet.wallet.session is now OMSWalletSession | undefined (renamed from OMSWalletSessionState). In 0.3 it was an object whose fields were undefined when signed out. session is defined exactly when activeWallet is, and its expiresAt and auth are always set.

// 0.3
const email = omsWallet.wallet.session.auth?.email

// 0.4
const email = omsWallet.wallet.session?.auth.email

Both values are frozen. Copy them before changing them.

Replace `onSessionExpired` with `onSessionChange`

onSessionChange reports every change of the active wallet or session, with a reason: signedIn, walletChanged, expiryUpdated, signedOut, or expired. An expired change carries the ended session as expiredSession.

// 0.3
omsWallet.wallet.onSessionExpired(({ session }) => showSignIn(session.auth))

// 0.4
omsWallet.wallet.onSessionChange((event) => {
  if (event.reason === 'expired') showSignIn(event.expiredSession.session.auth)
})

Listeners run shortly after the change, not during the call that made it. With the default browser storage, changes made in other tabs of the same origin are reported too. See Sessions and access.

Renamed parameters and types

0.3	0.4
`createWallet({ type })`	`createWallet({ walletType })`
`importEncryptedWallet({ type, keyMaterial })`	`importEncryptedWallet({ walletType, keyMaterial })`
`isValid…Signature({ walletId, … })`	`isValid…Signature({ walletAddress, … })`, or omit `walletAddress` for the active wallet
`feeOption.token.logoURL`, `tokenID`	`feeOption.token.logoUrl`, `tokenId`
`OMSWalletClient`, `OMSWalletIndexerClient`	`WalletClient`, `IndexerClient`
`OMSWalletSessionState`	`OMSWalletSession`
`OMSWalletSessionExpiredListener`	`OMSWalletSessionChangeListener`
`AuthMode.OTP`, `AuthMode.IDToken`	Removed. `AuthMode` lists only the OIDC redirect modes.

TypeScript reports each of these. In untyped JavaScript, createWallet({ type }) silently creates an Ethereum wallet, so search for these calls. upstreamError.code is now a string: compare with '7313', not 7313. TypeScript flags comparisons and switch cases against numbers, but untyped JavaScript, values typed any, and logs that record the code now see a string. WalletType gained Tron. Exhaustive switch statements over WalletType or WalletAccount need a tron case.

Behavior changes

These need no code change to compile, but can change what your application sees:

Session expiry extends with use. session.expiresAt is the current expiry, not a fixed end time. An idle session ends about 10 days after its last use, and never after the requested lifetime. The default lifetime is now 180 days instead of one week; pass sessionLifetimeSeconds for a hard limit. Listen for expiryUpdated instead of treating expiresAt as final.
The expiry is checked when it passes. When expiresAt passes, a session past its requested lifetime ends at once. Otherwise the SDK asks the wallet API, once the page is shown, and reports expired only if the session ended.
Signed requests time out after 30 seconds with OMS_REQUEST_FAILED (retryable: true), counting the time spent waiting behind other signed requests, which are now sent one at a time. A transaction that times out after it was sent still fails with OMS_TRANSACTION_EXECUTION_UNCONFIRMED: check its status before sending it again.
Refused transactions fail as request errors. A transaction the wallet API refuses before submitting it, for example because simulation shows it would revert, fails with OMS_REQUEST_FAILED (or OMS_SESSION_EXPIRED when the session has ended) instead of OMS_TRANSACTION_EXECUTION_UNCONFIRMED. It was never submitted, so there is nothing to check.
callContract takes a bare method name. Pass 'transfer', not 'transfer(address,uint256)'. A full signature now throws OMS_VALIDATION_ERROR before any request.
Sign-in claims a claimable wallet. With automatic selection, a user with no wallet of the requested type but a claimable one gets that wallet instead of a new one.
Instances of one project share one wallet. Creating OMSWallet again for the same project and environment, with the same storage, returns the same wallet, so signing out or switching wallets applies to both. Passing one storage object with a different credentialSigner or redirectAuthStorage throws OMSWalletValidationError, so outside a browser, instances that share a storage must also share a credentialSigner.

​Users sign in once after upgrading

​Read the active wallet

​Check session for undefined

​Replace onSessionExpired with onSessionChange

​Renamed parameters and types

​Behavior changes

Users sign in once after upgrading

Read the active wallet

Check `session` for `undefined`

Replace `onSessionExpired` with `onSessionChange`

Renamed parameters and types

Behavior changes