nexus-sdk-hooks-events

name	nexus-sdk-hooks-events
description	Configure Nexus SDK intent/allowance/swap intent hooks and event streaming. Use when integrating approval flows, intent previews, or real-time progress events (NEXUS_EVENTS).

Hooks and Events

Set up hooks once after SDK init

• Call sdk.setOnIntentHook(callback).
• Call sdk.setOnAllowanceHook(callback).
• Call sdk.setOnSwapIntentHook(callback).
• If a hook is not set, the SDK auto-approves and continues.
• If a hook is set, always call allow(...) or deny() or the flow will stall.
• Optionally auto-deny after a timeout to avoid hanging UX.

Handle intent hook (bridge / bridgeAndTransfer / bridgeAndExecute)

Signature

sdk.setOnIntentHook((data) => {
  // data: OnIntentHookData
});

OnIntentHookData

• allow(): void — continue the flow
• deny(): void — reject the flow
• intent: ReadableIntent — readable intent info for UI
• refresh(selectedSources?: number[]): Promise<ReadableIntent> — refresh the intent

How to use

• Store data in a ref so UI can call allow()/deny() later.
• Call refresh() on an interval (e.g., every 15s) if you show intent details.
• If the user closes the modal or cancels, call deny() and clear the ref.

Handle allowance hook (approval control)

Signature

sdk.setOnAllowanceHook((data) => {
  // data: OnAllowanceHookData
});

OnAllowanceHookData

• allow(decisions): void
  • decisions must match the number of sources
  • each entry can be 'min', 'max', bigint, or numeric string
• deny(): void
• sources: AllowanceHookSources
  • includes chain/token info and current vs required allowance

How to use

• Present each source to the user (chain + token + required allowance).
• Build the decisions array in the same order as sources.
• Call allow(decisions) to continue, or deny() to cancel.
• Ensure decisions.length === sources.length or the SDK will reject with INVALID_VALUES_ALLOWANCE_HOOK.

Handle swap intent hook (swap flows)

Signature

sdk.setOnSwapIntentHook((data) => {
  // data: OnSwapIntentHookData
});

OnSwapIntentHookData

• allow(): void
• deny(): void
• intent: SwapIntent
• refresh(): Promise<SwapIntent>

How to use

• Store data and show a UI summary.
• Call allow() to proceed or deny() to cancel.

Stream events for progress UI

Attach listeners

• All main operations accept { onEvent } in options.

Event names and payloads

• NEXUS_EVENTS.STEPS_LIST → BridgeStepType[]
• NEXUS_EVENTS.STEP_COMPLETE → BridgeStepType
• NEXUS_EVENTS.SWAP_STEP_COMPLETE → SwapStepType

Typical usage

• Use STEPS_LIST to seed step trackers.
• Use STEP_COMPLETE and SWAP_STEP_COMPLETE to update progress and explorer links.

Handle errors and cancellation

• If an operation throws, clear intent/allowance refs to avoid stale state.
• On user cancel, call deny() for the active hook and reset UI state.
• If a hook is set but no allow()/deny() is called, the intent remains pending.

Expand error-handling patterns

Normalize errors

• The SDK throws NexusError for known failures.
• Import from SDK:
  • import { NexusError, ERROR_CODES } from '@avail-project/nexus-core'

Map common error codes to UX responses

• USER_DENIED_INTENT / USER_DENIED_ALLOWANCE / USER_DENIED_INTENT_SIGNATURE:
  • Treat as user cancel; show a neutral message and reset UI.
• INVALID_VALUES_ALLOWANCE_HOOK:
  • Fix decisions length/type and resubmit.
• SDK_NOT_INITIALIZED / WALLET_NOT_CONNECTED / CONNECT_ACCOUNT_FAILED:
  • Prompt user to reconnect; re-run sdk.initialize(...).
• INVALID_INPUT / INVALID_ADDRESS_LENGTH:
  • Validate inputs; block submission until fixed.
• INSUFFICIENT_BALANCE / NO_BALANCE_FOR_ADDRESS:
  • Prompt user to reduce amount or fund source chain.
• TOKEN_NOT_SUPPORTED / CHAIN_NOT_FOUND:
  • Block submission and update selectors.
• QUOTE_FAILED / SWAP_FAILED / RATES_CHANGED_BEYOND_TOLERANCE / SLIPPAGE_EXCEEDED_ALLOWANCE:
  • Re-run quote or suggest a smaller amount.
• RFF_FEE_EXPIRED:
  • Re-simulate and re-submit the transaction.
• TRANSACTION_TIMEOUT / LIQUIDITY_TIMEOUT:
  • Show “pending” state and allow retry or check intent history.
• TRANSACTION_REVERTED:
  • Display failure with explorer link if available.
• COSMOS_ERROR / INTERNAL_ERROR:
  • Show a generic error and log err.data?.details for support.

Use a helper pattern

import { NexusError, ERROR_CODES } from '@avail-project/nexus-core';

export function getReadableNexusError(err: unknown): string {
  if (err instanceof NexusError) {
    switch (err.code) {
      case ERROR_CODES.USER_DENIED_INTENT:
      case ERROR_CODES.USER_DENIED_ALLOWANCE:
      case ERROR_CODES.USER_DENIED_INTENT_SIGNATURE:
        return 'Transaction cancelled by user';
      case ERROR_CODES.INSUFFICIENT_BALANCE:
        return 'Insufficient balance';
      case ERROR_CODES.SLIPPAGE_EXCEEDED_ALLOWANCE:
      case ERROR_CODES.RATES_CHANGED_BEYOND_TOLERANCE:
        return 'Price changed too much. Please try again.';
      case ERROR_CODES.TRANSACTION_TIMEOUT:
        return 'Transaction timed out. Please retry.';
      default:
        return err.message;
    }
  }
  if (err instanceof Error) return err.message;
  return 'Unknown error';
}

Clean up on error

• Clear intent/allowance refs and reset progress state:
  • intentRef.current = null; allowanceRef.current = null; swapIntentRef.current = null;
  • reset step UI and pending flags