@vivettoai/sdk

Official TypeScript/JavaScript client for the Vivetto AI gateway.

OpenAI-compatible: Vivetto extends the official openai client (peer dependency). After swapping the constructor, existing chat, images, embeddings, moderations, audio, and OpenAI responses call sites keep working. Chat/completions go through the Vivetto gateway (with automatic provider failover). Other OpenAI APIs use your OPENAI_API_KEY fallback when the gateway does not proxy them.

Important: openai must be installed in your app (>=4). The SDK declares it as a peerDependency so TypeScript resolves a single OpenAI type (avoids private _options assignability errors).

Install

npm install @vivettoai/sdk
# or: pnpm add @vivettoai/sdk / yarn add @vivettoai/sdk

Requires Node 18+ and openai >= 4 (installed automatically).

Quick start

VIVETTO_API_KEY=viv_...
VIVETTO_GATEWAY_BASE_URL=https://vivetto-gateway-ulp3nlh52a-uc.a.run.app
OPENAI_API_KEY=sk-...   # failover + images/embeddings/etc.

import { Vivetto } from "@vivettoai/sdk";

const client = new Vivetto({
  apiKey: process.env.VIVETTO_API_KEY!,
  baseUrl: process.env.VIVETTO_GATEWAY_BASE_URL,
  fallback: {
    openaiApiKey: process.env.OPENAI_API_KEY,
  },
});

const completion = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello from Vivetto" }],
});
console.log(completion.choices[0]?.message?.content);

Mint a key in the Vivetto dashboard (Settings → SDK & CLI), or run:

npx @vivettoai/wizard wizard --skip-agent

Deploying? Add VIVETTO_API_KEY and VIVETTO_GATEWAY_BASE_URL to your hosting platform's environment (Vercel, Cloud Run, etc.). The wizard only writes them to your local .env. If they are missing in production, requests bypass the gateway and go straight to your provider keys (see below), so nothing breaks, but you lose gateway routing and observability.

Provider failover

Requests never hard-fail just because the gateway is unavailable, as long as at least one provider key is configured (OPENAI_API_KEY, ANTHROPIC_API_KEY, or GEMINI_API_KEY, or the equivalent fallback options). The SDK sends the request to the original provider when:

• VIVETTO_API_KEY is not set (the gateway is skipped entirely),
• the gateway URL is wrong or unreachable (network errors, HTTP 404/405 from something that is not a Vivetto gateway),
• the gateway is down or timing out (any 5xx, or 408).

Claude models fall back to Anthropic and Gemini models to Google; everything else falls back to OpenAI. Fallback responses include vivetto_fallback: true. Policy blocks from the gateway (HTTP 403) are never bypassed.

Publishing (maintainers)

From the monorepo root, use pnpm only so workspace:^ is rewritten:

pnpm --filter @vivettoai/sdk check-pack
pnpm --filter @vivettoai/sdk publish --access public --no-git-checks

See ../wizard/PUBLISH.md.