npm package: @qt-test/apex-bridge
Description: Bridge protocol types and utilities for APEX mini-app platform
Author: Interswitch
Latest version: 0.1.0

# @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

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

## Usage

### Message Types

```typescript
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

```typescript
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

```typescript
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

```typescript
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