@simo-online/sdk — SIMOSphere AI TypeScript SDK

Official TypeScript / JavaScript client for the SIMOSphere AI gateway.

• OpenAI-compatible chat.completions (sync + streaming)
• Tenant admin: API keys, usage, credits, files
• Zero runtime dependencies — uses native fetch (Node 18.17+ / modern browsers)
• Typed end-to-end against the published OpenAPI 3.1 spec

Install

npm install @simo-online/sdk
# or
pnpm add @simo-online/sdk
# or
yarn add @simo-online/sdk

Quickstart

import { SimoClient } from '@simo-online/sdk';

const simo = new SimoClient({ apiKey: process.env.SIMO_API_KEY! });

// 1. Chat completion (OpenAI-compatible)
const chat = await simo.chat.completions.create({
  model: 'apertus-8b-eu',
  messages: [
    { role: 'system', content: 'Du bist ein hilfreicher Assistent.' },
    { role: 'user', content: 'Was ist Datensouveraenitaet?' },
  ],
});
console.log(chat.choices[0].message.content);

// 2. Streaming
for await (const chunk of simo.chat.completions.createStream({
  model: 'apertus-8b-eu',
  messages: [{ role: 'user', content: 'Schreibe ein Haiku ueber Souveraenitaet.' }],
})) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

// 3. List models
const models = await simo.models.list();
console.log(models.data.map((m) => m.id));

// 4. Manage API keys
const key = await simo.keys.create({ name: 'ci-pipeline', scopes: ['chat:write'] });
console.log('New key (shown once):', key.token);

// 5. Check credit balance
const credit = await simo.credits.balance();
console.log(`Balance: ${credit.balance_eur} EUR`);

// 6. Usage summary
const usage = await simo.usage.summary({ from: '2026-05-01', to: '2026-05-31' });
console.log(`${usage.total_requests} requests · ${usage.total_input_tokens + usage.total_output_tokens} tokens`);

Configuration

| Option | Default | Notes | | ---------------- | ------------------------------------ | ---------------------------------------------- | | apiKey | (required) | Issued via dashboard or simo keys create | | baseUrl | https://api.simosphereai.com | Use sandbox.api.simosphereai.com for testing | | timeoutMs | 60000 | Per-request timeout | | fetch | globalThis.fetch | Pass undici or node-fetch if needed | | defaultHeaders | {} | Merged into every request |

Error handling

import { SimoClient, SimoApiError } from '@simo-online/sdk';

try {
  await simo.chat.completions.create({ model: 'x', messages: [] });
} catch (err) {
  if (err instanceof SimoApiError) {
    console.error(err.status, err.body?.error?.type, err.body?.error?.message);
    console.error('Request ID for support:', err.requestId);
  } else {
    throw err;
  }
}

Idempotency

Pass idempotencyKey on any mutating call to dedupe retries server-side:

await simo.keys.create(
  { name: 'webhook-2026-05-25' },
  { idempotencyKey: 'create-webhook-key-once' },
);

Cancellation

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

await simo.chat.completions.create(
  { model: 'apertus-8b-eu', messages: [{ role: 'user', content: '...' }] },
  { signal: controller.signal },
);

OpenAI SDK migration

- import OpenAI from 'openai';
- const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+ import { SimoClient } from '@simo-online/sdk';
+ const client = new SimoClient({ apiKey: process.env.SIMO_API_KEY });

  const chat = await client.chat.completions.create({
-   model: 'gpt-4o-mini',
+   model: 'apertus-8b-eu',
    messages: [{ role: 'user', content: 'Hello' }],
  });

Versioning & stability

• Follows Semantic Versioning.
• Tracks the gateway's published 2026-05-18 API contract; method names mirror the OpenAI SDK so familiar code ports cleanly.
• SIMOSphere (capital) is a back-compat alias for the 0.0.x preview SDK and will be removed in 0.3.0.

Links

• Gateway docs: https://onboarding.simosphereai.com/llms-full.txt
• OpenAPI spec: https://api.simosphereai.com/openapi.json
• Issue tracker: https://github.com/SIMOSphereOS/simosphere-ai-api-platform/issues

License

Business Source License 1.1 — see LICENSE.

Engineered at SIMO GmbH · Aschaffenburg, Germany.