Installation

Requirements

A FluxGate account and API key (see Getting Started)
Node.js ≥ 18

Install the core SDK

npm install @fluxgate/sdk
# pnpm
pnpm add @fluxgate/sdk

Initialize once — use everywhere

Create a singleton client in lib/fluxgate.ts. Every feature in your app imports this instance — never construct FluxGate at the call-site.

// lib/fluxgate.ts
import { FluxGate } from "@fluxgate/sdk";

export const fg = new FluxGate({
  apiKey: process.env.FLUXGATE_API_KEY!,
  endpoint: "https://fluxgate.app/api/events", // optional override
  timeout: 5000, // optional, default 5 000 ms
  debug: false, // set true in development to log every event
});

Security: Store your API key in an environment secret (.env.local, Vercel env vars, AWS Secrets Manager). Never hard-code it.

Record your first event

recordEvent is the primary method. It accepts a structured payload — never a flat object.

import { fg } from "@/lib/fluxgate";

const startedAt = performance.now();
const response = await myModel.generate(prompt);

await fg.recordEvent({
  usage: {
    model: "gpt-4o",
    provider: "openai",
    inputTokens: response.usage.input_tokens,
    outputTokens: response.usage.output_tokens,
    cachedTokens: response.usage.cached_tokens,
    latencyInMs: performance.now() - startedAt,
    isStreamed: false,
  },
  status: "SUCCESS",
  metadata: {
    feature: "chat-assistant",
    user: currentUser.id, // string ID or full TrackedUser object
    sessionId: session.id,
  },
});

recordEvent is fire-and-forget safe — if the network call fails or times out, it returns null and logs a warning (in debug mode) without throwing.

Provider-specific wrappers (recommended)

For OpenAI, Anthropic, and Google Gemini, use the dedicated wrapper packages. They wrap the provider SDK client and capture telemetry automatically — no manual recordEvent calls needed. See the integration guides for details:

Error and status tracking

Pass a structured status object to record errors alongside the event:

await fg.recordEvent({
  usage: { inputTokens: 120, outputTokens: 0 },
  status: {
    status: "ERROR",
    errorMessage: "Rate limit exceeded — retry after 60 s",
  },
  metadata: { feature: "summarizer" },
});

Verifying the integration

Open your FluxGate dashboard. The Overview card should reflect new usage within a few seconds. If nothing appears:

Confirm FLUXGATE_API_KEY is set in your runtime environment.
Enable debug: true and check the console output for [fluxgate] log lines.
Ensure inputTokens and outputTokens are integers, not strings.