@super-protocol/provider-client

Type-safe client for SuperProtocol Provider API, built on top of openapi-fetch.

Features

- ✅ Type Safety - Automatic type generation from OpenAPI schema
- ✅ Modern API - Uses native fetch API
- ✅ Minimal Size - Only 6kb + openapi-fetch
- ✅ Auto Updates - Types generated on every build
- ✅ Auth Middleware - Automatic token injection in headers

Installation

``bash
npm install @super-protocol/provider-client
`

Quick Start

`typescript
import { createProviderClient } from '@super-protocol/provider-client';

const client = createProviderClient({
baseUrl: process.env.SP_BASE_URL || 'https://cp.dev.superprotocol.com',
accessToken: process.env.SP_ACCESS_TOKEN // Get token through authentication
});

// Get current user information
const { data, error } = await client.GET('/api/auth/me');
if (data) {
console.log('User ID:', data.id);
}
`

Environment Setup

$3

1. Authenticate with SuperProtocol:
- Visit SuperProtocol Console
- Connect your wallet (MetaMask, WalletConnect, etc.)
- Your access token will be generated automatically

2. Alternative: Use the OAuth API:
- Use the /api/auth/token endpoint to get a token programmatically
- See the OAuth documentation for details

3. Set Environment Variable:
`bash
# Option 1: Export in your shell
export SP_ACCESS_TOKEN="your-jwt-token-here"

# Option 2: Create .env file (recommended)
echo "SP_ACCESS_TOKEN=your-jwt-token-here" > .env

# Option 3: Copy from example and edit
cp example.env .env
# Then edit .env with your actual token
`

4. Run the Example:
`bash
# The .env file will be loaded automatically (Node.js 20+)
npm run start:example

# Or run directly with token
SP_ACCESS_TOKEN="your-token" npm run start:example
`

$3

Starting with Node.js 20+, environment variables from .env files are automatically loaded using the --env-file flag. This package is configured to use this feature.

Create a .env file in your project root:

`env


SuperProtocol API Configuration

Get your token from https://console.superprotocol.com after connecting wallet

SP_ACCESS_TOKEN=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...your-full-token-here

Optional: Override default base URL (uncomment to use different environment)

SP_BASE_URL=https://cp.dev.superprotocol.com # Development environment

SP_BASE_URL=https://cp.staging.superprotocol.com # Staging environment

SP_BASE_URL=https://cp.superprotocol.com # Production environment

`

Quick setup options:
`bash


Option 1: Create directly

echo "SP_ACCESS_TOKEN=your-token-here" > .env

Option 2: Copy from example

cp .env.template .env

Then edit .env file with your actual token

`

The start:example script uses --env-file-if-exists=.env flag, which means:
- ✅ If .env file exists, variables are loaded automatically
- ✅ If .env file doesn't exist, no error is thrown
- ✅ Environment variables take precedence over .env file values

For more details, see the Node.js documentation on environment variables.

$3

This package includes a working example that demonstrates all major API endpoints:

`bash


Clone the repository

git clone https://github.com/super-protocol/sp-providers
cd sp-providers/packages/provider-client

Install dependencies

npm install

Set your access token (choose one method):

Method 1: Create .env file (recommended)

echo "SP_ACCESS_TOKEN=your-token-here" > .env

Method 2: Export environment variable

export SP_ACCESS_TOKEN="your-token-here"

Method 3: Copy from example

cp example.env .env

Then edit .env with your actual token

Run the example (automatically loads .env if present)

npm run start:example
`

The example will show you:
- ✅ Current user information
- ✅ User settings and storage configuration
- ✅ Wallet balance and address
- ✅ Available workflows
- ✅ Provider information
- ✅ Example POST request (workflow replenishment)

API Reference

$3

Creates a configured openapi-fetch client with auth middleware.

Parameters:
- baseUrl? - API base URL (default: https://cp.dev.superprotocol.com)
- accessToken? - Authorization token (automatically added to headers)
- headers? - Additional HTTP headers

Returns: Configured openapi-fetch client with typed GET, POST, PUT, DELETE, etc. methods.

Environment Variables:
- SP_ACCESS_TOKEN - Access token for authentication (loaded from .env file automatically with Node.js 20+)
- SP_BASE_URL - Optional base URL override (defaults to https://cp.dev.superprotocol.com)

Example environment configurations:
`bash


Development environment (default)

SP_BASE_URL=https://cp.dev.superprotocol.com

Staging environment

SP_BASE_URL=https://cp.staging.superprotocol.com

Production environment

SP_BASE_URL=https://cp.superprotocol.com
`

Usage Examples

$3

`typescript
import { createProviderClient } from '@super-protocol/provider-client';

// With Node.js 20+ and --env-file flag, .env variables are automatically loaded
const client = createProviderClient({
baseUrl: process.env.SP_BASE_URL || 'https://cp.dev.superprotocol.com',
accessToken: process.env.SP_ACCESS_TOKEN // Loaded from .env file automatically
});

// GET request
const { data: userData, error } = await client.GET('/api/auth/me');

// POST request
const { data: workflow, error: workflowError } = await client.POST('/api/workflows', {
body: {
parentOrderInfo: { / ... / },
parentOrderSlot: { / ... / },
// All fields are typed automatically!
}
});

// PUT request with path parameters
const { data, error } = await client.PUT('/api/offers/{id}', {
params: {
path: { id: 'offer-id' }
},
body: {
name: 'Updated Offer Name'
}
});
`

$3

`typescript
// Query parameters
const { data: offers } = await client.GET('/api/offers', {
params: {
query: {
limit: 10,
offset: 0
}
}
});

// Path parameters
const { data: offer } = await client.GET('/api/offers/{id}', {
params: {
path: { id: 'specific-offer-id' }
}
});

// Combined path and query parameters
const { data: workflows } = await client.GET('/api/workflows/{id}', {
params: {
path: { id: 'workflow-id' },
query: { includeDetails: true }
}
});
`

$3

`typescript
const { data, error, response } = await client.GET('/api/auth/me');

if (error) {
// Typed errors based on endpoint
console.error('Status:', response.status);
console.error('Error:', error);
return;
}

// data is guaranteed to exist if no error
console.log('User:', data.id);
`

$3

`typescript
// Create client with custom headers
const client = createProviderClient({
baseUrl: process.env.SP_BASE_URL || 'https://cp.dev.superprotocol.com',
accessToken: 'your-token',
headers: {
'X-Custom-Header': 'value',
'User-Agent': 'MyApp/1.0'
}
});

// Add additional middleware
client.use({
onRequest({ request }) {
console.log(Making request to ${request.url});
return request;
},
onResponse({ response }) {
console.log(Response status: ${response.status});
return response;
}
});
`

Supported Endpoints

The client supports all SuperProtocol API endpoints with full typing:

$3


- GET /api/auth/me - Current user information
- POST /api/auth/token - Get tokens
- POST /api/auth/refresh-access - Refresh token
- GET /api/auth/logout - Logout

$3

- GET /api/users/nonce/{address} - Get nonce
- POST /api/users - Register user

$3

- GET /api/users/me/wallet - Wallet information
- POST /api/users/me/wallet/withdraw - Withdraw funds

$3

- GET /api/workflows - List workflows
- GET /api/workflows/{id} - Get specific workflow
- POST /api/workflows - Create workflow
- PATCH /api/workflows/{id} - Update workflow
- POST /api/workflows/{orderId}/replenish - Replenish workflow
- POST /api/workflows/{orderId}/cancel - Cancel workflow

$3

- GET /api/providers - Provider information
- POST /api/providers - Create provider
- PATCH /api/providers/{id} - Update provider

$3

- POST /api/offers - Create offer
- GET /api/offers/{id} - Get offer
- PATCH /api/offers/{id} - Update offer
- POST /api/offers/{offerId}/publish - Publish offer
- POST /api/offers/{id}/slots - Add slot

$3

- POST /api/files - Upload file
- POST /api/files/list - List files
- GET /api/files/{id} - Get file
- POST /api/contents - Create content
- GET /api/contents/{id} - Get content

$3

- GET /api/storages - List storages
- GET /api/storages/{id} - Get specific storage
- GET /api/user-settings - User settings
- PATCH /api/user-settings - Update settings

$3

- POST /api/faucet/request-tokens - Request faucet tokens
- GET /health/liveness - Health check
- GET /health/readiness - Readiness check

Type Generation

Types are automatically generated from OpenAPI schema during build:

`bash
npm run generate-types # Manual type generation
npm run build # Includes type generation
``

Type Safety

Thanks to openapi-typescript integration, the client provides:

- ✅ Autocomplete for all available endpoints
- ✅ Type validation for request/response
- ✅ Parameter checking at compile time
- ✅ IntelliSense in VS Code and other IDEs
- ✅ Typed errors for each endpoint

Performance

| Library | Size (min) | Performance |
| -------------------------- | ---------- | -------------------- |
| @super-protocol/provider-client | 6 kB | 300k ops/s (fastest) |
| axios | 32 kB | 225k ops/s (slower) |
| superagent | 55 kB | 50k ops/s (6× slower) |

License

BSL-1.1

---

Built with ❤️ by SuperProtocol team