@interswitch/apex-bridge

Bridge protocol types and utilities for APEX mini-app platform

This package provides the core TypeScript types, validation utilities, and permission system for the APEX JS-Native bridge protocol.

Installation

npm install @interswitch/apex-bridge
# or
yarn add @interswitch/apex-bridge

Usage

Message Types

import {
  BridgeRequest,
  BridgeResponse,
  BridgeEvent,
  createRequest,
  createSuccessResponse,
  createErrorResponse,
} from '@interswitch/apex-bridge';

// Create a request
const request = createRequest('device', 'vibrate', { duration: 100 });
// {
//   version: '1.0.0',
//   callbackId: 'cb_1234567890_abc',
//   namespace: 'device',
//   method: 'vibrate',
//   params: { duration: 100 },
//   timestamp: 1234567890
// }

// Create a success response
const response = createSuccessResponse(request.callbackId, { vibrated: true });

// Create an error response
const error = createErrorResponse(request.callbackId, 'PERMISSION_DENIED');

Namespace Types

import { Device, Storage, Payment } from '@interswitch/apex-bridge';

// Typed parameters
const vibrateParams: Device.VibrateParams = {
  duration: 100,
  pattern: 'light',
};

// Typed responses
const deviceInfo: Device.GetInfoResponse = {
  platform: 'ios',
  osVersion: '16.4',
  model: 'iPhone 14 Pro',
  // ...
};

Validation

import {
  validateVibrateParams,
  validateStorageSetParams,
  validatePaymentRequestParams,
} from '@interswitch/apex-bridge';

const result = validatePaymentRequestParams({
  amount: 5000,
  currency: 'NGN',
  description: 'Test payment',
});

if (!result.valid) {
  console.error(result.error?.message);
}

Permissions

import {
  checkPermission,
  getRequiredPermission,
  isUrlAllowed,
} from '@interswitch/apex-bridge';

// Check what permission a method needs
const permission = getRequiredPermission('location', 'get');
// 'location'

// Check if a URL is allowed
const allowed = isUrlAllowed(
  'https://api.example.com/data',
  'request',
  { request: ['api.example.com'] }
);
// true

API Reference

Message Functions

| Function | Description | |----------|-------------| | createRequest(namespace, method, params) | Create a bridge request | | createSuccessResponse(callbackId, data) | Create a success response | | createErrorResponse(callbackId, code, details?) | Create an error response | | createEvent(namespace, event, data) | Create an event message | | generateCallbackId() | Generate a unique callback ID |

Type Guards

| Function | Description | |----------|-------------| | isBridgeResponse(message) | Check if message is a response | | isBridgeEvent(message) | Check if message is an event |

Validators

| Function | Description | |----------|-------------| | validateString(value, field, options?) | Validate string with length limits | | validateNumber(value, field, options?) | Validate number with min/max | | validateBoolean(value, field) | Validate boolean | | validateEnum(value, field, allowed) | Validate against allowed values | | validateUrl(value, field) | Validate URL format | | validateRequired(obj, fields) | Check required fields exist |

Permission Functions

| Function | Description | |----------|-------------| | checkPermission(namespace, method, checker) | Check if call is allowed | | getRequiredPermission(namespace, method) | Get required permission | | requiresExplicitConsent(permission) | Check if needs user prompt | | requiresBiometric(permission) | Check if needs biometric | | isUrlAllowed(url, type, domains) | Check URL against allowlist |

Namespaces

All bridge API types are organized by namespace:

• Device - Device info, vibration, screen
• Storage - Key-value storage
• Network - HTTP requests
• UI - Toast, modal, navigation bar
• Location - GPS, geolocation
• Media - Camera, images, video
• Auth - Biometrics, user info
• Payment - Payment requests, wallet
• Clipboard - Copy/paste

Error Codes

| Code | Description | |------|-------------| | PERMISSION_DENIED | Missing required permission | | INVALID_PARAMS | Parameter validation failed | | NOT_SUPPORTED | Feature not available | | TIMEOUT | Operation timed out | | NETWORK_ERROR | Network request failed | | USER_CANCELLED | User cancelled operation | | SYSTEM_ERROR | Internal error | | RATE_LIMITED | Too many requests | | PAYMENT_FAILED | Payment processing failed | | PAYMENT_CANCELLED | User cancelled payment |

License

MIT