@smartapi/sdk

The official, production-ready JavaScript SDK for the SmartAPI Gateway.

Easily route requests to multiple AI providers (OpenAI, Gemini, Claude, etc.) through a single, unified, and secure gateway. No direct calls to AI providers are required—SmartAPI handles everything securely.

📦 Installation

npm install @smartapi/sdk
# or
yarn add @smartapi/sdk
# or
pnpm add @smartapi/sdk

🚀 Quick Start

Initialize the SDK and send your first message.

Important: Never expose your API key in a frontend environment. Always run the SDK on a secure Node.js backend.

import { SmartAPI } from "@smartapi/sdk";

const client = new SmartAPI({
  apiKey: process.env.SMARTAPI_KEY // e.g., "sap_live_xxxxxxxxx"
});

async function main() {
  const response = await client.chat({
    provider: "gemini",
    model: "gemini-2.5-pro",
    message: "Hello, world!"
  });

  console.log(response);
}

main();

⚙️ Configuration

The SmartAPI constructor accepts an object with the following properties:

| Property | Type | Default | Description | |---|---|---|---| | apiKey | string | Required | Your SmartAPI Gateway Key. | | baseURL | string | https://api.smartapi.com | Override the gateway base URL. | | timeout | number | 60000 | Request timeout in milliseconds. | | maxRetries | number | 2 | Number of times to retry on network failures or rate limits (exponential backoff). | | headers | Object | {} | Custom headers appended to every request. | | endpoints | Object | { chat: '/api/v1/chat', ... } | Override default API routes. | | interceptors | Object | {} | Hooks for onRequest and onResponse. |

Using Interceptors

const client = new SmartAPI({
  apiKey: "sap_live_123",
  interceptors: {
    onRequest: (request) => {
      console.log(`Starting Request to ${request.url}`);
      return request;
    },
    onResponse: (response) => {
      console.log(`Received Response Status: ${response.status}`);
      return response;
    }
  }
});

📚 Core Methods

client.chat(options)

Send a message to an AI provider through the SmartAPI Gateway.

const response = await client.chat({
  provider: "openai",     // "openai", "gemini", "anthropic", etc.
  model: "gpt-4o",        // Specific model ID
  message: "Explain APIs",// Your prompt string or array
  temperature: 0.7,       // Optional
  maxTokens: 500          // Optional
});

client.models.list()

Retrieve all models currently supported by the gateway.

const models = await client.models.list();

client.providers.list()

Retrieve all providers currently connected to your gateway.

const providers = await client.providers.list();

client.usage.get()

Retrieve current budget and token usage.

const usage = await client.usage.get();

🛡️ Error Handling

The SDK exposes granular, professional error classes to help you gracefully handle failures.

import { 
  SmartAPI, 
  RateLimitError, 
  AuthenticationError, 
  TimeoutError 
} from "@smartapi/sdk";

try {
  await client.chat({ provider: "gemini", model: "invalid", message: "Hi" });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log("Too many requests!");
  } else if (error instanceof AuthenticationError) {
    console.log("Invalid API Key.");
  } else if (error instanceof TimeoutError) {
    console.log("Gateway took too long to respond.");
  } else {
    console.log("General Error:", error.message);
  }
}

🔐 Security Best Practices

1. Server-Side Only: Keep your SMARTAPI_KEY safe. Never expose it in browser applications. Use an API route (e.g., Next.js /api, Express) to bridge your frontend and the SDK.
2. Key Rotation: If a key leaks, immediately regenerate it in the SmartAPI Dashboard.

📄 License

MIT © 2026 SmartAPI