Migrating from openai to floopy-sdk

The openai package works against Floopy out of the box — just point baseURL at https://api.floopy.ai/v1. So why migrate?

floopy-sdk wraps the same openai package by composition (your chat/embeddings calls are still the upstream code) and adds:

• typed methods for decisions, experiments, constraints, export, evaluations, routing.explain, and feedback;
• typed Floopy-* headers via the options field instead of stringly-typed defaultHeaders;
• a FloopyError hierarchy with proper subclasses (FloopyAuthError, FloopyPlanError, FloopyRateLimitError, …).

Security updates to openai reach you on pnpm update — no fork drift.

import OpenAI from "openai";
const client = new OpenAI({
  baseURL: "https://api.floopy.ai/v1",
  apiKey: process.env.FLOOPY_API_KEY,
});
import { Floopy } from "floopy-sdk";
const client = new Floopy({
  apiKey: process.env.FLOOPY_API_KEY!,
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "hello" }],
});

client.chat, client.embeddings, and client.models return the upstream openai-node resources, so types and runtime behavior are identical.

If you were using defaultHeaders to toggle Floopy features, switch to typed options:

const client = new OpenAI({
  apiKey: process.env.FLOOPY_API_KEY,
  baseURL: "https://api.floopy.ai/v1",
  defaultHeaders: {
    "Floopy-Cache-Enabled": "true",
    "Floopy-Cache-Bucket-Max-Size": "3",
    "Floopy-Prompt-Id": "cd4249d5-...",
    "floopy-llm-security-enabled": "true",
  },
});
const client = new Floopy({
  apiKey: process.env.FLOOPY_API_KEY!,
  options: {
    cache: { enabled: true, bucketMaxSize: 3 },
    promptId: "cd4249d5-...",
    llmSecurityEnabled: true,
  },
});

The options keys are typechecked, autocompleted, and the SDK does the header serialization. You can still pass raw headers via defaultHeaders for anything not covered.

Anything you used to call with fetch against /v1/decisions, /v1/experiments, /v1/export/decisions, etc., now has a typed method. See the Node SDK reference.

const r = await fetch("https://api.floopy.ai/v1/decisions/" + id, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const decision = await r.json();
const decision = await floopy.decisions.get(id);

If you cannot migrate every call site at once, keep both clients side-by-side:

import OpenAI from "openai";
import { Floopy } from "floopy-sdk";

const legacy = new OpenAI({
  baseURL: "https://api.floopy.ai/v1",
  apiKey: process.env.FLOOPY_API_KEY,
});

const floopy = new Floopy({ apiKey: process.env.FLOOPY_API_KEY! });

Both talk to the same gateway — the only thing you lose with the legacy path is typed access to Floopy-only endpoints.