Morpheus Node SDK

Official Node.js SDK for interacting with the Morpheus API Gateway at api.mor.org.

Installation

npm install morpheus-node
# or
yarn add morpheus-node
# or
pnpm add morpheus-node

Quick Start

import MorpheusClient from 'morpheus-node';

// Initialize with API key
const client = new MorpheusClient({
  apiKey: 'your-api-key-here'
});

// Or initialize with email/password for authentication
const client = new MorpheusClient({
  baseURL: 'https://api.mor.org' // Optional, this is the default
});

// Login to get access token
const auth = await client.login({
  email: '[email protected]',
  password: 'your-password'
});

// Create a chat completion
const response = await client.createChatCompletion({
  model: 'llama-3.3-70b',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is the capital of France?' }
  ]
});

console.log(response.choices[0].message.content);

Configuration

const client = new MorpheusClient({
  apiKey: 'your-api-key-here',      // Optional if using login
  accessToken: 'your-token',        // Optional, can be set after login
  baseURL: 'https://api.mor.org',   // Optional, this is the default
  timeout: 30000,                   // Optional, request timeout in ms
  maxRetries: 3,                    // Optional, max retry attempts
  retryDelay: 1000,                 // Optional, initial retry delay in ms
  headers: {                        // Optional, custom headers
    'X-Custom-Header': 'value'
  }
});

API Reference

Authentication

Register User

const auth = await client.register({
  email: '[email protected]',
  password: 'secure-password',
  username: 'optional-username'
});

// Access token is automatically stored for future requests
console.log(auth.access_token);

Login

const auth = await client.login({
  email: '[email protected]',
  password: 'your-password'
});

// Access token is automatically stored
console.log(auth.access_token);

Refresh Token

const newAuth = await client.refreshToken({
  refresh_token: auth.refresh_token
});

API Keys Management

// List API keys
const keys = await client.getApiKeys();

// Create new API key
const newKey = await client.createApiKey({
  name: 'My API Key'
});
console.log('New API Key:', newKey.key);

// Delete API key
await client.deleteApiKey(newKey.id);

Private Key Management

// Store private key
await client.storePrivateKey({
  private_key: 'your-private-key'
});

// Check private key status
const status = await client.getPrivateKeyStatus();
console.log('Has private key:', status.has_private_key);

// Delete private key
await client.deletePrivateKey();

Delegation Management

// Create delegation
const delegation = await client.storeDelegation({
  delegatee_address: '0x...',
  expires_at: '2024-12-31T23:59:59Z'
});

// List all delegations
const delegations = await client.getUserDelegations();

// Get active delegation
const active = await client.getActiveDelegation();

// Delete delegation
await client.deleteDelegation(delegation.id);

Chat Completions

Create Chat Completion

const response = await client.createChatCompletion({
  model: 'llama-3.3-70b',
  messages: [
    { role: 'user', content: 'Hello!' }
  ],
  temperature: 0.7,
  max_tokens: 1000
});

console.log(response.choices[0].message.content);

Stream Chat Completion

const stream = client.streamChatCompletion({
  model: 'llama-3.3-70b',
  messages: [
    { role: 'user', content: 'Tell me a story' }
  ]
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0].delta?.content || '');
}

Stream with Event Emitter

const events = client.streamChatCompletionEvents({
  model: 'llama-3.3-70b',
  messages: [
    { role: 'user', content: 'Tell me a story' }
  ]
});

events.on('message', (event) => {
  process.stdout.write(event.data.choices[0].delta?.content || '');
});

events.on('done', () => {
  console.log('\nStream complete!');
});

events.on('error', (event) => {
  console.error('Stream error:', event.error);
});

Models

List Available Models

const models = await client.listModels();
models.forEach(model => {
  console.log(`${model.id}: ${model.owned_by}`);
});

List All Models (Extended)

const allModels = await client.listAllModels();
allModels.models.forEach(model => {
  console.log(`${model.id}: ${model.provider} (max context: ${model.max_context})`);
});

Get Rated Bids

const bids = await client.getRatedBids();
bids.forEach(bid => {
  console.log(`${bid.model} by ${bid.provider}: ${bid.price_per_token} (rating: ${bid.rating})`);
});

Sessions

Approve Spending

await client.approveSpending({
  amount: '1000000000000000000', // 1 token in wei
  token: 'MOR' // Optional
});

Create Bid Session

const session = await client.createBidSession({
  bid_id: 'bid-123',
  duration: 3600 // Optional, in seconds
});

console.log('Session ID:', session.session_id);

Create Model Session

const session = await client.createModelSession({
  model: 'llama-3.3-70b',
  duration: 3600 // Optional
});

Session Management

// Ping session to keep alive
await client.pingSession({
  session_id: session.session_id
});

// Close session
await client.closeSession({
  session_id: session.session_id
});

Automation

Get Automation Settings

const settings = await client.getAutomationSettings();
console.log('Automation enabled:', settings.enabled);

Update Automation Settings

const updated = await client.updateAutomationSettings({
  enabled: true,
  max_spend_per_session: '1000000000000000000',
  max_spend_per_day: '10000000000000000000',
  allowed_models: ['llama-3.3-70b', 'gpt-4'],
  auto_approve_threshold: '100000000000000000'
});

Health Check

const health = await client.healthCheck();
console.log('API Status:', health.status);

// Root endpoint
const root = await client.getRoot();

Error Handling

The SDK provides specific error types for different scenarios:

import {
  MorpheusError,
  MorpheusAuthenticationError,
  MorpheusRateLimitError,
  MorpheusValidationError,
  MorpheusNetworkError,
  isMorpheusError
} from 'morpheus-node';

try {
  const response = await client.createChatCompletion({
    model: 'invalid-model',
    messages: []
  });
} catch (error) {
  if (isMorpheusError(error)) {
    console.error(`Morpheus Error: ${error.message}`);
    console.error(`Status: ${error.status}`);
    console.error(`Code: ${error.code}`);
    
    if (error instanceof MorpheusAuthenticationError) {
      // Handle authentication error - maybe refresh token
    } else if (error instanceof MorpheusRateLimitError) {
      // Handle rate limit
      console.log(`Retry after: ${error.retryAfter} seconds`);
    } else if (error instanceof MorpheusValidationError) {
      // Handle validation error
      console.log(`Invalid param: ${error.param}`);
    }
  }
}

Advanced Usage

Custom Request Options

const response = await client.createChatCompletion(
  {
    model: 'llama-3.3-70b',
    messages: [{ role: 'user', content: 'Hello' }]
  },
  {
    timeout: 60000, // Override timeout for this request
    signal: abortController.signal, // AbortController for cancellation
    headers: {
      'X-Request-ID': 'custom-id'
    }
  }
);

Token Management

// Manually set access token
client.setAccessToken('new-access-token');

// Get current access token
const token = client.getAccessToken();

Retry Configuration

The SDK automatically retries failed requests with exponential backoff:

• Network errors
• Timeout errors
• 429 (Rate Limit) errors
• 502, 503, 504 (Server) errors

You can configure retry behavior:

const client = new MorpheusClient({
  apiKey: 'your-api-key',
  maxRetries: 5,        // Maximum retry attempts
  retryDelay: 2000      // Initial delay between retries (doubles each time)
});

TypeScript Support

This SDK is written in TypeScript and provides full type definitions:

import type {
  ChatMessage,
  ChatCompletionRequest,
  ChatCompletionResponse,
  Model,
  SessionResponse,
  AutomationSettings,
  AuthResponse
} from 'morpheus-node';

Requirements

• Node.js 14.0.0 or higher
• TypeScript 4.5+ (for TypeScript users)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For support, please visit https://mor.org or open an issue on GitHub.