@sapiom/node-http

Node.js http/https client with payment handling

Installation

npm install @sapiom/node-http

Functions

createClient

Creates a Sapiom-enabled Node.js HTTP client with automatic authorization and payment handling

This creates a native HTTP client using Node.js’s http/https modules with:

• Pre-emptive authorization (request pre-processing)
• Reactive payment handling (response error handling for 402)

Works directly with Node.js native types, supporting streams, buffers, and all body types.

Signature:

function createClient(config?: SapiomNodeHttpConfig | undefined): HttpClientAdapter & { __sapiomClient: SapiomClient; }

Parameters:

Name	Type	Description
config	SapiomNodeHttpConfig | undefined	-

Returns: HttpClientAdapter & { __sapiomClient: SapiomClient; } - A Sapiom-enabled HttpClientAdapter

Example:

// Simplest usage (reads SAPIOM_API_KEY from environment)
import { createClient } from '@sapiom/node-http';

const client = createClient();

// Auto-handles 402 payment errors and authorization
const response = await client.request({
  method: 'GET',
  url: 'https://api.example.com/premium-endpoint',
  headers: { 'Content-Type': 'application/json' }
});

Example:

// With API key and default metadata
import { createClient } from '@sapiom/node-http';

const client = createClient({
  apiKey: 'sk_...',
  agentName: 'my-agent',
  serviceName: 'my-service'
});

const response = await client.request({
  method: 'POST',
  url: 'https://api.example.com/data',
  headers: { 'Content-Type': 'application/json' },
  body: { key: 'value' }
});

Example:

// With default metadata (applied to all requests)
import { createClient } from '@sapiom/node-http';

const client = createClient({
  apiKey: 'sk_...',
  agentName: 'my-agent',
  serviceName: 'my-service'
});

// Per-request override via __sapiom property
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'
  }
});

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

Classes

AuthorizationDeniedError

Custom error classes

Constructor:

new AuthorizationDeniedError(transactionId: string, endpoint: string, reason: string | undefined)

Parameter	Type	Description
transactionId	string	-
endpoint	string	-
reason	string | undefined	-

AuthorizationTimeoutError

Constructor:

new AuthorizationTimeoutError(transactionId: string, endpoint: string, timeout: number)

Parameter	Type	Description
transactionId	string	-
endpoint	string	-
timeout	number	-

Interfaces

SapiomNodeHttpConfig

Configuration for Sapiom-enabled Node.js HTTP client

Extends: BaseSapiomIntegrationConfig