Bridge Reference

npm install @alien_org/bridge

 
send('app:ready', {});
send('app:close', {});
send('clipboard:write', { text: 'Hello!' });
send('host.back.button:toggle', { visible: false });
send('link:open', { url: 'https://example.com' });
send('haptic:impact', { style: 'medium' });

 
const response = await request(
  'payment:request',
  { recipient, amount, token, network, invoice },
  'payment:response',
  { timeout: 30000 },
);

 
const handler = (payload) => {
  console.log('Back button clicked');
};
 
on('host.back.button:clicked', handler);
 
// Later: unsubscribe
off('host.back.button:clicked', handler);

const unsubscribe = on('host.back.button:clicked', handler);
// Later:
unsubscribe();

 
emit('some:event', { data: 'value' });

 
if (isBridgeAvailable()) {
  // Running in Alien app
} else {
  // Browser dev mode
}

 
import { isAvailable } from '@alien_org/bridge';
 
if (isAvailable('payment:request', { version: contractVersion })) {
  // Safe to call
}

 
const params = getLaunchParams();

 
try {
  const params = retrieveLaunchParams();
} catch (error) {
  if (error instanceof LaunchParamsError) {
    console.log('Not running in Alien app');
  }
}

 
const params = parseLaunchParams(jsonString);

 
if (process.env.NODE_ENV === 'development') {
  mockLaunchParamsForDev({
    authToken: 'dev-token',
    platform: 'ios',
    contractVersion: '1.0.0',
    displayMode: 'standard',
  });
}

 
clearMockLaunchParams();

 
const disable = enableLinkInterceptor({ openMode: 'external' });
 
// Later:
disable();

type SafeResult<T> = { ok: true; data: T } | { ok: false; error: Error };

 
const result = send.ifAvailable(
  'haptic:impact',
  { style: 'medium' },
  { version: contractVersion },
);
 
if (!result.ok) {
  console.warn('Could not send:', result.error.message);
}

 
const result = await request.ifAvailable(
  'payment:request',
  { recipient, amount, token, network, invoice },
  'payment:response',
  { version: contractVersion },
);
 
if (result.ok) {
  console.log('Payment:', result.data.status);
} else {
  console.warn('Failed:', result.error.message);
}

import { createMockBridge } from '@alien_org/bridge/mock';
 
const mock = createMockBridge({
  launchParams: {
    authToken: 'test-token',
    contractVersion: '1.0.0',
    platform: 'ios',
  },
  handlers: {
    'payment:request': (payload) => ({
      status: 'paid',
      txHash: 'mock-tx-123',
      reqId: payload.reqId,
    }),
  },
  delay: 100, // simulate async delay in ms
});
 
// Emit events to the miniapp
mock.emitEvent('host.back.button:clicked', {});
 
// Inspect method calls
const calls = mock.getCalls();
 
// Cleanup
mock.cleanup();

{
  recipient: string;      // Wallet address
  amount: string;         // Amount in token's smallest unit
  token: string;          // 'USDC', 'ALIEN', or token identifier
  network: string;        // 'solana' or 'alien'
  invoice: string;        // Your order/invoice ID
  item?: {                // Optional display info
    title: string;
    iconUrl: string;
    quantity: number;
  };
  test?: PaymentTestScenario;  // Test mode scenario
}

{
  url: string;
  openMode?: 'external' | 'internal';
}

send('link:open', { url: 'https://example.com' });
send('link:open', { url: 'solana:...' });
send('link:open', { url: 'mailto:hi@example.com' });
send('link:open', {
  url: 'https://alien.app/miniapp/other-app',
  openMode: 'internal',
});

{
  style: 'light' | 'medium' | 'heavy' | 'soft' | 'rigid';
}

{
  type: 'success' | 'warning' | 'error';
}

{}

{
  transaction: string;  // Base64-encoded serialized transaction
}

{
  message: string;  // Base58-encoded message bytes
}

{
  transaction: string;  // Base64-encoded
  chain?: SolanaChain;  // 'solana:mainnet' etc.
  options?: {
    skipPreflight?: boolean;
    preflightCommitment?: SolanaCommitment;
    commitment?: SolanaCommitment;
    minContextSlot?: number;
    maxRetries?: number;
  };
}

{
  reqId: string;
  status: 'paid' | 'cancelled' | 'failed';
  txHash?: string;
  errorCode?: PaymentErrorCode;
}

{
  reqId: string;
  text: string | null;
  errorCode?: 'permission_denied' | 'unavailable';
}

{
  reqId: string;
  publicKey?: string;        // Base58-encoded
  errorCode?: WalletSolanaErrorCode;
  errorMessage?: string;     // Human-readable error
}

{
  reqId: string;
  signedTransaction?: string; // Base64-encoded
  errorCode?: WalletSolanaErrorCode;
  errorMessage?: string;
}

{
  reqId: string;
  signature?: string;    // Base58-encoded
  publicKey?: string;    // Base58-encoded
  errorCode?: WalletSolanaErrorCode;
  errorMessage?: string;
}

{
  reqId: string;
  signature?: string;    // Base58-encoded
  errorCode?: WalletSolanaErrorCode;
  errorMessage?: string;
}

 
import {
  BridgeError,
  BridgeTimeoutError,
  BridgeUnavailableError,
  BridgeWindowUnavailableError,
  BridgeMethodUnsupportedError,
} from '@alien_org/bridge';
 
try {
  const result = await request(
    'payment:request',
    params,
    'payment:response',
  );
} catch (error) {
  if (error instanceof BridgeTimeoutError) {
    // error.method, error.timeout
  } else if (error instanceof BridgeMethodUnsupportedError) {
    // error.method, error.contractVersion, error.minVersion
  } else if (error instanceof BridgeUnavailableError) {
    // Not running in Alien app
  } else if (error instanceof BridgeWindowUnavailableError) {
    // Window not available (SSR)
  }
}