JavaScript/TypeScript SDK

Installation

npm install openai
# or
yarn add openai
# or
pnpm add openai

Minimum: Node.js 18+ (for native fetch). The OpenAI SDK works with Mavera’s Responses API via baseURL override.

Install Troubleshooting

Wrong package

Install the official openai package. Avoid openai-api, openai-node, or similar. Verify with npm list openai.

ESM vs CommonJS

The SDK supports both. Use "type": "module" in package.json for ESM, or require("openai") for CommonJS. For TypeScript, ensure moduleResolution is compatible.

TypeScript type errors for persona_id

The OpenAI types don’t include persona_id. Add it directly to the request object; use // @ts-expect-error above the line, or extend the types if needed.

Node version

Node 18+ required. Check with node -v. For older Node, consider upgrading or using the REST API directly.

Migrating from OpenAI

If you’re switching from OpenAI to Mavera, change only these:

baseURL — baseURL: "https://app.mavera.io/api/v1"
apiKey — Use your Mavera key (starts with mvra_live_)
model — Use mavera-1
persona_id — Add persona_id: "..." to every responses.create() call (JavaScript accepts it directly; no extra_body)

Streaming, tools, and structured outputs work with minor adjustments. See Migrate OpenAI to Mavera.

Configuration

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "mvra_live_your_key_here",
  baseURL: "https://app.mavera.io/api/v1",
});

Store your API key in an environment variable: MAVERA_API_KEY

const client = new OpenAI({
  apiKey: process.env.MAVERA_API_KEY,
  baseURL: "https://app.mavera.io/api/v1",
});

Responses API

Basic Usage

const response = await client.responses.create({
  model: "mavera-1",
  input: "What are the latest trends in AI?",
  instructions: "You are a helpful assistant.",
  // @ts-ignore - Mavera custom field
  persona_id: "YOUR_PERSONA_ID",
});

console.log(response.output[0].content[0].text);
console.log("Credits used:", response.usage.credits_used);

Streaming

const stream = client.responses.stream({
  model: "mavera-1",
  input: "Write a short story",
  // @ts-ignore - Mavera custom field
  persona_id: "YOUR_PERSONA_ID",
});

for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}

With Analysis Mode

const response = await client.responses.create({
  model: "mavera-1",
  input: "How do millennials feel about remote work?",
  // @ts-ignore - Mavera custom field
  persona_id: "YOUR_PERSONA_ID",
  analysis_mode: true,
  reasoning_effort: "high",
});

const analysis = response.analysis;
console.log(`Confidence: ${analysis.confidence}/10`);

REST API Endpoints

For non-Chat endpoints, use fetch:

const headers = {
  Authorization: "Bearer mvra_live_your_key_here",
  "Content-Type": "application/json",
};
const baseURL = "https://app.mavera.io/api/v1";

// List personas
const personasRes = await fetch(`${baseURL}/personas`, { headers });
const { data: personas } = await personasRes.json();

// Mave Agent
const maveRes = await fetch(`${baseURL}/mave/chat`, {
  method: "POST",
  headers,
  body: JSON.stringify({ message: "Analyze the EV market" }),
});
const maveResult = await maveRes.json();

// Create Focus Group
const fgRes = await fetch(`${baseURL}/focus-groups`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Product Feedback",
    sample_size: 50,
    persona_ids: ["persona_1", "persona_2"],
    questions: [...],
  }),
});

TypeScript Support

The SDK includes full TypeScript types:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MAVERA_API_KEY,
  baseURL: "https://app.mavera.io/api/v1",
});

const response = await client.responses.create({
  model: "mavera-1",
  input: "Hello",
  // @ts-ignore - Mavera custom field
  persona_id: "YOUR_PERSONA_ID",
});

Error Handling

import OpenAI from "openai";

try {
  const response = await client.responses.create({...});
} catch (error) {
  if (error instanceof OpenAI.AuthenticationError) {
    console.error("Invalid API key");
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("Rate limited - implement backoff");
  } else if (error instanceof OpenAI.APIError) {
    if (error.status === 402) {
      console.error("Insufficient credits");
    } else {
      console.error("API error:", error.message);
    }
  }
}

Edge Runtime / Vercel

Works in Edge Runtime environments:

// app/api/chat/route.ts
import OpenAI from "openai";

export const runtime = "edge";

const client = new OpenAI({
  apiKey: process.env.MAVERA_API_KEY,
  baseURL: "https://app.mavera.io/api/v1",
});

export async function POST(req: Request) {
  const { message } = await req.json();

  const response = await client.responses.create({
    model: "mavera-1",
    input: message,
    // @ts-ignore - Mavera custom field
    persona_id: process.env.PERSONA_ID,
  });

  return Response.json(response);
}

React / Next.js Example

"use client";

import { useState } from "react";

export function Chat() {
  const [message, setMessage] = useState("");
  const [response, setResponse] = useState("");

  const handleSubmit = async () => {
    const res = await fetch("/api/chat", {
      method: "POST",
      body: JSON.stringify({ message }),
    });
    const data = await res.json();
    setResponse(data.output[0].content[0].text);
  };

  return (
    <div>
      <input value={message} onChange={(e) => setMessage(e.target.value)} />
      <button onClick={handleSubmit}>Send</button>
      <p>{response}</p>
    </div>
  );
}

Full Example Script (Node.js)

A runnable script: list personas, send a chat, print the response.

// mavera_chat.mjs — run with: node mavera_chat.mjs "Your question here"
import OpenAI from "openai";

const apiKey = process.env.MAVERA_API_KEY;
if (!apiKey) {
  console.error("Set MAVERA_API_KEY environment variable");
  process.exit(1);
}

const client = new OpenAI({
  apiKey,
  baseURL: "https://app.mavera.io/api/v1",
});

async function main() {
  const question = process.argv[2] || "What matters most to you when choosing a product?";

  const personasRes = await fetch("https://app.mavera.io/api/v1/personas", {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const { data: personas } = await personasRes.json();
  const personaId = personas?.[0]?.id;
  if (!personaId) {
    console.error("No personas found");
    process.exit(1);
  }
  console.log(`Using persona: ${personas[0].name}\n`);

  const response = await client.responses.create({
    model: "mavera-1",
    input: question,
    // @ts-ignore - Mavera custom field
    persona_id: personaId,
  });

  console.log(response.output[0].content[0].text);
  console.log(`\nCredits used: ${response.usage.credits_used}`);
}

main().catch(console.error);

Run: MAVERA_API_KEY=mvra_live_xxx node mavera_chat.mjs "How do you feel about subscription pricing?"

Quickstart: Chat

First chat in 5 minutes

Migrate OpenAI → Mavera

Switching from OpenAI

Streaming Chat in React

React component for streaming

API Reference

Responses API spec

Getting Started

Core Concepts

Features

SDKs & Libraries

JavaScript/TypeScript SDK

Installation

Install Troubleshooting

Migrating from OpenAI

Configuration

Responses API

Basic Usage

Streaming

With Analysis Mode

REST API Endpoints

TypeScript Support

Error Handling

Edge Runtime / Vercel

React / Next.js Example

Full Example Script (Node.js)

Quickstart: Chat

Migrate OpenAI → Mavera

Streaming Chat in React

API Reference

​Installation

​Install Troubleshooting

​Migrating from OpenAI

​Configuration

​Responses API

​Basic Usage

​Streaming

​With Analysis Mode

​REST API Endpoints

​TypeScript Support

​Error Handling

​Edge Runtime / Vercel

​React / Next.js Example

​Full Example Script (Node.js)

Quickstart: Chat

Migrate OpenAI → Mavera

Streaming Chat in React

API Reference

Installation

Install Troubleshooting

Migrating from OpenAI

Configuration

Responses API

Basic Usage

Streaming

With Analysis Mode

REST API Endpoints

TypeScript Support

Error Handling

Edge Runtime / Vercel

React / Next.js Example

Full Example Script (Node.js)