@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.com' // 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 { createSapiomClient } from '@sapiom/axios';

const client = createSapiomClient(axios.create({
  baseURL: 'https://api.example.com'
}), {
  sapiom: {
    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 { createSapiomFetch } from '@sapiom/fetch';

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

// Drop-in replacement for native fetch
const response = await fetch('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 { createSapiomClient } from '@sapiom/node-http';

const client = createSapiomClient({
  sapiom: {
    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.list()

await client.transactions.list({
  status?: 'pending' | 'authorized' | 'declined' | 'failed' | 'completed' | 'cancelled';
  service?: string;
  limit?: number;
  offset?: number;
})

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 { HttpClientAdapter } from '@sapiom/core/core';

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

Payment Error Detection

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

const detector = new PaymentErrorDetection();

if (detector.is402Error(error)) {
  const info = detector.extractPaymentInfo(error);
  console.log('Payment required:', info.paymentData);
}

TypeScript Types

import type {
  SapiomClientConfig,
  Transaction,
  PaymentData,
  PaymentDetails,
  HttpClientAdapter,
  RequestConfig,
  Response
} from '@sapiom/core';

License

MIT © Sapiom

Links

• Documentation
• GitHub
• NPM
• Issues