Two modes
OSS / BYOK mode vs Vendo mode — what changes and when to use each.
The SDK operates in two modes, selected automatically at startup based on whether VENDO_API_KEY is present in the environment.
Resolution chain for token(slug)
token("openai")
│
├─ VENDO_TOKEN_OPENAI set? → return it (escape hatch, always wins)
│
├─ VENDO_API_KEY set? → fetch from credentials.vendo.run (Vendo mode)
│
├─ OPENAI_API_KEY set? → return it (OSS / BYOK mode)
│
└─ nothing → raise NotConnected("set OPENAI_API_KEY")OSS / BYOK mode
No Vendo account. Set the conventional env var for each integration.
# .env
OPENAI_API_KEY=sk-...
TELEGRAM_BOT_TOKEN=12345:abcdeimport vendo
tok = vendo.token("openai") # returns OPENAI_API_KEY
bot = vendo.token("telegram") # returns TELEGRAM_BOT_TOKEN
vendo.is_vendo_mode() # False# .env
OPENAI_API_KEY=sk-...
TELEGRAM_BOT_TOKEN=12345:abcdeThe Vendo class constructor requires an API key. In OSS mode there is no Vendo key, so use the module-level helpers (getCredential, primaryEnvVar) which read the BYOK catalog without instantiating a client:
import { getCredential, isVendoMode } from "@vendodev/sdk";
const tok = await getCredential("openai"); // returns OPENAI_API_KEY
const bot = await getCredential("telegram"); // returns TELEGRAM_BOT_TOKEN
isVendoMode(); // false (VENDO_API_KEY not set)If you want a single code path that works in both modes — and you're prepared to handle the constructor throwing in OSS — fall back to the helper:
import { Vendo, getCredential } from "@vendodev/sdk";
async function token(slug: string): Promise<string> {
try {
return await new Vendo().token(slug); // Vendo mode if VENDO_API_KEY set
} catch {
return await getCredential(slug); // OSS / BYOK fallback
}
}# Environment
OPENAI_API_KEY=sk-...
TELEGRAM_BOT_TOKEN=12345:abcdeimport Vendo
let vendo = try Vendo(apiKey: "byok") // byok placeholder activates OSS mode
let tok = try await vendo.token("openai") // reads OPENAI_API_KEY
let bot = try await vendo.token("telegram") // reads TELEGRAM_BOT_TOKENVendo mode
Set VENDO_API_KEY once. Everything else is the same call.
VENDO_API_KEY=vendo_sk_...import vendo
tok = vendo.token("openai") # OAuth-refreshed token from Vendo
bal = vendo.billing.balance() # Vendo-only: raises VendoOnlyFeature in OSS mode
url = vendo.connect_url("slack") # Vendo-only: OAuth popup URL
vendo.is_vendo_mode() # TrueVENDO_API_KEY=vendo_sk_...import { Vendo, isVendoMode } from "@vendodev/sdk";
const vendo = new Vendo();
const tok = await vendo.token("openai"); // OAuth-refreshed token
const bal = await vendo.billing.balance(); // Vendo-only
const url = await vendo.connectUrl("slack"); // Vendo-only
isVendoMode(); // trueVENDO_API_KEY=vendo_sk_...import Vendo
let vendo = try Vendo() // reads VENDO_API_KEY from env
let tok = try await vendo.token("openai") // OAuth-refreshed token
let bal = try await vendo.billing.balance() // Vendo-only
let url = try vendo.connectURL(slug: "slack") // Vendo-onlyVendo-only features
These surfaces throw VendoOnlyFeature in OSS mode:
| Surface | Why |
|---|---|
billing.* | Requires Vendo wallet |
events.subscribe() | Requires Vendo SSE stream |
connect_url / connectUrl / connectURL | Requires Vendo OAuth portal |
for_request / forRequest | Multi-tenant scoping needs a Vendo backend |
for_user / forUser | Same reason |
webhooks.verify() works in both modes because HMAC verification is local.
Discover env vars
vendo.integrations.env_vars("slack")
# ["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"]await vendo.integrations.envVars("slack");
// ["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"]let vars = vendo.integrations.envVars(for: "slack")
// ["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"]The BYOK catalog is bundled at SDK release time. New integrations added to Vendo after your SDK version require an upgrade to be discoverable in OSS mode.
When to use which
| Situation | Recommendation |
|---|---|
| Open-source project you want to keep portable | OSS mode — ship a .env.example |
| Production app or internal tool deployed on Vendo | Vendo mode — set VENDO_API_KEY in your deploy env |
| Local dev against Vendo | Vendo mode — use your personal dev API key |
| CI / test suite | OSS mode — mock the env vars; no network calls |