@sapiom/core

@sapiom/core

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

Core SDK for Sapiom API providing HTTP client adapters, transaction management, and automatic payment handling.

Features

• ✅ Lightweight core - Minimal footprint with focused functionality
• ✅ HTTP client agnostic - Works with Axios, Fetch, Node HTTP
• ✅ Automatic payment handling - Handles 402 Payment Required flows
• ✅ Pre-emptive authorization - Protect endpoints before access
• ✅ TypeScript native - Full type safety
• ✅ Tree-shakeable - Only bundle what you use
• ✅ Node.js 18+ - Uses native fetch

Installation

npm install @sapiom/core
# or
pnpm add @sapiom/core
# or
yarn add @sapiom/core

Quick Start

Direct API Client

import { SapiomClient } from '@sapiom/core';

const client = new SapiomClient({
  apiKey: process.env.SAPIOM_API_KEY,
  baseURL: 'https://api.sapiom.ai' // optional
});

// Create a transaction
const transaction = await client.transactions.create({
  service: 'api',
  action: 'call',
  resource: 'completion',
  qualifiers: {
    model: 'gpt-4',
    tokens: 1000
  }
});

// Check transaction status
console.log(client.transactions.isAuthorized(transaction)); // boolean

Axios Integration

For Axios integration, install the separate package:

npm install @sapiom/axios axios

import axios from 'axios';
import { withSapiom } from '@sapiom/axios';

const client = withSapiom(axios.create({
  baseURL: 'https://api.example.com'
}), {
  apiKey: process.env.SAPIOM_API_KEY
});

// Automatically handles 402 payment flows
const response = await client.get('/premium-endpoint');

See @sapiom/axios for complete documentation.

Fetch Integration

For Fetch API integration, install the separate package:

npm install @sapiom/fetch

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

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

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

See @sapiom/fetch for complete documentation.

Node.js HTTP/HTTPS

For Node.js HTTP/HTTPS integration, install the separate package:

npm install @sapiom/node-http

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

See @sapiom/node-http for complete documentation.

API Reference

SapiomClient

Constructor

new SapiomClient(config: SapiomClientConfig)

Config options:

• apiKey: string - Required: Your Sapiom API key
• baseURL?: string - Optional: API base URL (default: https://api.sapiom.ai)
• timeout?: number - Optional: Request timeout in ms (default: 30000)
• headers?: Record<string, string> - Optional: Additional headers

Methods

transactions.create()

await client.transactions.create({
  service: string;
  action: string;
  resource: string;
  qualifiers?: Record<string, any>;
  paymentData?: PaymentData;
  metadata?: Record<string, any>;
})

transactions.get()

await client.transactions.get(transactionId: string)

Helper Methods

client.transactions.isAuthorized(transaction): boolean
client.transactions.isCompleted(transaction): boolean
client.transactions.requiresPayment(transaction): boolean
client.transactions.getPaymentDetails(transaction): PaymentDetails | null

HTTP Integrations

Configuration Options

All HTTP integrations accept a config object:

{
  sapiom: {
    apiKey: string;
    baseURL?: string;
    timeout?: number;
  },
  authorization?: {
    enabled?: boolean;
    authorizedEndpoints?: Array<{
      pathPattern: RegExp;
      service: string;
    }>;
    onAuthorizationPending?: (txId: string, endpoint: string) => void;
  },
  payment?: {
    enabled?: boolean;
    onPaymentRequired?: (txId: string, payment: PaymentDetails) => void;
  }
}

Environment Variables

All integrations automatically read from environment:

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

Error Handling

try {
  const transaction = await client.transactions.create({...});
} catch (error) {
  if (error.response?.status === 401) {
    console.error('Authentication failed');
  } else if (error.response?.status === 402) {
    console.error('Payment required');
  } else if (error.response?.status === 403) {
    console.error('Access denied');
  }
}

Advanced Usage

Custom HTTP Adapter

import type { HttpClientAdapter, HttpRequest, HttpResponse } from '@sapiom/core';

class MyCustomAdapter implements HttpClientAdapter {
  async request(config: HttpRequest): Promise<HttpResponse> {
    // Your custom HTTP logic
  }
}

Payment Error Detection

import { isPaymentRequiredError, extractX402Response } from '@sapiom/core';

if (isPaymentRequiredError(error)) {
  const x402Response = extractX402Response(error);
  console.log('Payment required:', x402Response);
}

TypeScript Types

import type {
  SapiomClientConfig,
  TransactionResponse,
  HttpClientAdapter,
  HttpRequest,
  HttpResponse,
  X402Response,
  X402PaymentRequirement,
} from '@sapiom/core';

License

MIT © Sapiom

Links

• Documentation
• GitHub
• NPM
• Issues