Get started with TypeScript

Zhivex keeps the application contract separate from each model provider. Your code imports portable primitives from @zhivex-ai/sdk and installs only the provider adapters it actually uses.

Before you begin

Use the SDK from a trusted server runtime such as Bun, Node.js, a route handler, an API server, or a background worker. Provider keys and effectful tools must not be shipped to the browser.

You need:

• a server-side TypeScript project;
• Bun or a modern Node.js runtime;
• credentials for at least one provider.

1. Install the SDK

Install the high-level package and one provider adapter:

bun add @zhivex-ai/sdk @zhivex-ai/openai

Add zod when your application defines tools or structured outputs:

bun add zod

Use @zhivex-ai/sdk@next only when deliberately validating a prerelease.

For ordinary application code, keep using the package root. TypeScript 1.7 also publishes narrower entrypoints when the boundary itself is useful:

• @zhivex-ai/sdk/catalog for the release-managed model inventory;
• @zhivex-ai/sdk/beta and @zhivex-ai/sdk/experimental for explicit risk opt-in;
• @zhivex-ai/core/contracts, /runtime, /workflows, /ui, /node, and /testing for adapter, framework, or infrastructure authors.

Existing root imports remain compatible. Do not replace them mechanically; use a focused entrypoint when it makes the runtime or stability boundary clearer.

2. Configure credentials

Keep the provider key in your server environment:

export OPENAI_API_KEY="your-server-side-key"

Do not prefix provider credentials with a public framework namespace such as PUBLIC_ or NEXT_PUBLIC_.

3. Generate text

Create quickstart.ts:

import { generateText } from "@zhivex-ai/sdk";
import { createOpenAI } from "@zhivex-ai/openai";

const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

const result = await generateText({
  model: openai("gpt-4o-mini"),
  system: "Be concise and technical.",
  prompt: "Explain this product architecture in three bullets."
});

console.log(result.text);
console.log(result.finishReason);
console.log(result.usage);

Run it with:

bun run quickstart.ts

The response normalizes the text, finish reason, usage, tool results, messages, and execution steps so the surrounding application does not depend on a provider-specific response shape.

4. Choose the next primitive

Need	Start with
One response	generateText()
Progressive text	streamText()
Validated JSON	generateObject()
Model-selected tools	Agent
Multi-turn product chat	Runner + SessionService
Known sequence of steps	createWorkflow()

Continue with generation and tools, build a stateful experience with agents and sessions, or implement a known process with workflows.

Source reference

The runnable examples and the complete API-oriented guide live in the TypeScript SDK repository.