Node.js HTTP

The @sapiom/node-http package creates a Sapiom-enabled HTTP client using Node.js native http and https modules.

---

Installation

npm

npm install @sapiom/node-http

pnpm

pnpm add @sapiom/node-http

yarn

yarn add @sapiom/node-http

Note

Server-Side Only: Uses Node.js native http and https modules

---

Basic Setup

Create a Sapiom-enabled HTTP client:

import { createClient } from '@sapiom/node-http';

const client = createClient({
  apiKey: process.env.SAPIOM_API_KEY
});

const response = await client.request({
  method: 'GET',
  url: 'https://api.example.com/data',
  headers: {}
});

---

Configuration

All configuration options for createClient:

import { createClient } from '@sapiom/node-http';

const client = createClient({
  // Optional - Automatically uses process.env.SAPIOM_API_KEY if not provided
  apiKey: process.env.MY_CUSTOM_SAPIOM_KEY,

  // 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
});

Configuration Options

apiKey string required

Your Sapiom API key. Can also be set via SAPIOM_API_KEY environment variable

enabled boolean default: true

Enable Sapiom handling. When disabled, requests pass through without Sapiom processing

failureMode 'open' | 'closed' default: 'open'

Control behavior when Sapiom operations fail:

• 'open': Allow requests to proceed (prioritizes availability)
• 'closed': Block requests (prioritizes security)

agentName string

Agent identifier for tracking and attribution

agentId string | number

Agent UUID or numeric ID

serviceName string

Service name for transactions

traceId string

Internal trace UUID for request correlation

traceExternalId string

External trace identifier for integration with external systems

---

Per-Request Overrides

Override configuration for individual requests using the __sapiom property:

// Disable Sapiom for a specific request
await client.request({
  method: 'GET',
  url: 'https://api.example.com/public',
  headers: {},
  __sapiom: { enabled: false }
});

// Override metadata for a specific request
await client.request({
  method: 'POST',
  url: 'https://api.example.com/resource',
  headers: { 'Content-Type': 'application/json' },
  body: { data: 'test' },
  __sapiom: {
    serviceName: 'different-service',
    actionName: 'custom-action',
    traceExternalId: 'ext-789'
  }
});

---

Payment Handling

The client automatically handles 402 Payment Required responses:

import { createClient } from '@sapiom/node-http';

const client = createClient({
  apiKey: process.env.SAPIOM_API_KEY
});

try {
  // Automatically handles 402 payment flows
  const response = await client.request({
    method: 'GET',
    url: 'https://api.example.com/premium-endpoint',
    headers: {}
  });
  console.log(response.data);
} catch (error) {
  // Payment errors will be handled by Sapiom
  console.error('Request failed:', error);
}

---

Environment Variables

Automatically reads from environment:

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

---

Next Steps

Axios Axios client integration

Fetch API Native fetch integration