Event Reference

OxGasAuth and OxGasClient are typed event emitters. Subscribe to lifecycle events to drive UI updates, log analytics, or react to errors without wrapping every SDK call in try/catch.

on()

Subscribe to an event.

client.on('stateChange', (state) => {
  console.log('New state:', state);
});

on() returns nothing. To unsubscribe, keep a reference to the handler and call off() (below) — or use removeAllListeners() during teardown.

once()

Subscribe and auto-unsubscribe after the first fire.

client.once('connected', (wallet) => {
  console.log('First login this session:', wallet.address);
});

off()

Remove a specific listener.

function handleDisconnect() {
  console.log('Disconnected');
}

client.on('disconnected', handleDisconnect);
// later…
client.off('disconnected', handleDisconnect);

removeAllListeners()

Remove every listener for an event, or for all events.

client.removeAllListeners('error');  // just 'error'
client.removeAllListeners();          // everything

Call removeAllListeners() on unmount in React/Vue/Svelte components — destroy() does this for you, but if you keep the SDK instance alive across mount cycles you’ll want to manage listeners explicitly.

Available events

stateChange

Fired whenever the authentication state transitions.

| Payload | "disconnected" | "connecting" | "connected" |

client.on('stateChange', (state) => {
  if (state === 'connecting') showSpinner();
  if (state === 'connected') hideSpinner();
});

The event does not fire for no-op transitions (e.g. calling logout() when already disconnected).

connected

Fired once login completes successfully.

| Payload | WalletInfo — { address: 0x…, email: string } |

client.on('connected', (wallet) => {
  console.log('Welcome,', wallet.email);
  console.log('Address:', wallet.address);
});

disconnected

Fired when the user logs out, the session is destroyed, or an auth error forces a disconnect.

| Payload | (none) |

client.on('disconnected', () => {
  // Clear cached user data
});

signatureComplete

Fired when a signMessage or signTransaction request returns successfully.

| Payload | { type: 'message' \| 'transaction', result: SignMessageResult \| SignTxResult } |

client.on('signatureComplete', ({ type, result }) => {
  if (type === 'message') {
    console.log('Signed message:', result.signature);
  } else {
    console.log('Signed tx:', result.txHash);
  }
});

The result shape depends on type:

// type === 'message'
interface SignMessageResult { signature: `0x${string}` }

// type === 'transaction'
interface SignTxResult {
  rawTx:  `0x${string}`;
  txHash: `0x${string}`;
  from:   `0x${string}`;
}

error

Fired when a widget-level error occurs that isn’t caught by a specific promise — for example, the widget unexpectedly closes while idle, or KMS returns an unexpected failure during a background refresh.

| Payload | Error (typically WidgetError or another OxGasError subclass) |

client.on('error', (err) => {
  console.error('Background error:', err.message);
});

Note: errors from await client.login() (or any awaited method) still throw normally — the error event is for background failures only, so you don’t lose visibility on things that happen outside an active call.

A typical React subscription pattern

useEffect(() => {
  const onState = (s: AuthState) => setState(s);
  const onConnected = (w: WalletInfo) => setWallet(w);

  client.on('stateChange', onState);
  client.on('connected', onConnected);

  return () => {
    client.off('stateChange', onState);
    client.off('connected', onConnected);
  };
}, []);

Keep handler refs stable across renders (defined inside useEffect or wrapped in useCallback) — otherwise the cleanup function tries to unsubscribe a different function reference and the original handler leaks.