@sapiom/fetch

⚠️ Beta Status: Currently in v0.x. API may change before v1.0.0. Production-ready and actively maintained.

Fetch API integration for Sapiom SDK providing automatic payment handling (402 errors) and pre-emptive authorization.

Installation

npm install @sapiom/fetch

Note: Requires Node.js 18+ (native fetch).

Quick Start

import { createFetch } from '@sapiom/fetch';

const fetch = createFetch({
  apiKey: process.env.SAPIOM_API_KEY
});

// Drop-in replacement for native fetch
const response = await fetch('https://api.example.com/data');
const data = await response.json();

Features

• ✅ Drop-in replacement for native fetch
• ✅ Automatic 402 payment handling
• ✅ Pre-emptive authorization
• ✅ Full TypeScript support
• ✅ Uses native Fetch API (no additional HTTP client needed)
• ✅ Environment variable configuration

Configuration

import { createFetch } from '@sapiom/fetch';

const fetch = createFetch({
  // Required (or use SAPIOM_API_KEY environment variable)
  apiKey: 'sk_...',

  // Optional - Control
  enabled: true,              // Enable Sapiom handling (default: true)
  failureMode: 'open',        // 'open' | 'closed' (default: 'open')
                              // 'open': Allow requests if Sapiom fails (prioritizes availability)
                              // 'closed': Block requests if Sapiom fails (prioritizes security)

  // Optional - Default metadata (applied to all requests)
  agentName: 'my-agent',      // Agent identifier
  agentId: 'agent-123',       // Agent UUID or numeric ID
  serviceName: 'my-service',  // Service name for transactions
  traceId: 'trace-xyz',       // Internal trace UUID
  traceExternalId: 'ext-456', // External trace identifier
});

Per-Request Overrides

Override configuration for individual requests using the __sapiom property:

// Disable Sapiom for a specific request
const publicRequest = new Request('/api/public');
(publicRequest as any).__sapiom = { enabled: false };
await fetch(publicRequest);

// Override metadata for a specific request
const request = new Request('/api/resource', { method: 'POST' });
(request as any).__sapiom = {
  serviceName: 'different-service',
  actionName: 'custom-action',
  traceExternalId: 'ext-789'
};
await fetch(request);

Environment Variables

Automatically reads from environment:

• SAPIOM_API_KEY (required)
• SAPIOM_BASE_URL or SAPIOM_API_URL (optional)
• SAPIOM_TIMEOUT (optional, in milliseconds)

License

MIT © Sapiom

Links

• Documentation
• GitHub
• NPM