Node.js, Bun, and Deno

@fireweaveai/server-sdk is the Fireweave server SDK for JavaScript runtimes. It evaluates control points and registers targets — the two v1 capabilities. The wire protocol still uses the parameter name flagKey. Install this package. @fireweaveai/sdk is frozen at 2.1.0 and is not the install target. See Migrate to v1.

Supported runtimes

From package.json#engines and the SDK runtime docs:

Runtime	Minimum	Notes
Node.js	`>=20.20`	Reference runtime
Bun	`1.2`	Same package
Deno	`2.0`	Import via `npm:@fireweaveai/server-sdk`

The package is ESM and has zero runtime dependencies.

Install

npm install @fireweaveai/server-sdk

Bun:

bun add @fireweaveai/server-sdk

Deno needs no install step:

import { initFireweave } from 'npm:@fireweaveai/server-sdk';

Published latest is 2.3.0.

Initialize

initFireweave is the single entry point. mode is required and never inferred. Init throws FireweaveError (kind Configuration) when mode is missing, remote credentials are blank, apiUrl fails the host allowlist, or local mode is combined with credentials.

import { initFireweave } from '@fireweaveai/server-sdk';

const fireweave = await initFireweave({
  mode: 'local',
  local: { controlPoints: { 'new-checkout': true } },
});

const enabled = await fireweave.controlPoints.getBooleanValue('new-checkout', false, {
  targetingKey: 'user_42',
});

await fireweave.shutdown();

Production:

const fireweave = await initFireweave({
  mode: 'remote',
  apiUrl: process.env.FW_API_URL,
  apiKey: process.env.FW_PROJECT_API_KEY,
});

The SDK reads no environment variables. Your app may read FW_API_URL / FW_PROJECT_API_KEY and pass them in. Lower-level construction for a custom adapter:

import { FireweaveClient, FireweaveRemoteAdapter, FireweaveRuntime } from '@fireweaveai/server-sdk';

const runtime = new FireweaveRuntime(new FireweaveRemoteAdapter({ apiUrl, apiKey }));
const fireweave = new FireweaveClient(runtime);
await fireweave.initialize();

Configuration and authentication

Remote mode speaks POST /v1/flags/evaluate and POST /v1/targets/register. Auth is Authorization: Bearer <key>.

Option	Mode	Description
`apiUrl`	`remote`	fw-server base URL (required)
`apiKey`	`remote`	Fireweave project key (`project-api-key_…`) (required)
`allowedHosts`	`remote`	SSRF allowlist override; default is Fireweave hosts plus loopback
`local.controlPoints`	`local`	Seeded boolean map. A present key resolves `STATIC`; an absent key misses to your default with reason `DEFAULT`
`local.log`	`local`	Sink for the `[fireweave:local]` registerTarget trace. Defaults to `console.info`

https is required off-loopback; http is loopback-only. Pass allowedHosts: ['*'] to opt out of host pinning. A self-hosted fw-server must list its own host. See Configuration and auth.

Targets

registerTarget lives on the client.

const registered = await fireweave.registerTarget('user_42', {
  kind: 'user',
  properties: { plan: 'pro', region: 'eu-west' },
});
console.log(registered.ok, registered.error?.kind);

RegisterTargetOptions: kind?: 'user' | 'device', properties?, environment?, signal?. Returns { ok, error? } and never throws. In local mode the adapter records the target in-process, traces [fireweave:local], and returns { ok: true }. InMemoryAdapter does not implement registration. See Targeting and targets.

Control points

client.controlPoints is the native API. client.flags is the same object (deprecated alias, silent at runtime, not scheduled for removal in 2.x). Do not use flags in new code. Types (ExpectedFlagType): 'boolean' | 'string' | 'number' | 'object'. 'number' is a single IEEE-754 double.

const on = await fireweave.controlPoints.getBooleanValue('new-checkout', false, {
  targetingKey: 'user_42',
});

const decision = await fireweave.controlPoints.getBooleanDetails('new-checkout', false, {
  targetingKey: 'user_42',
});
console.log(decision.reason, decision.variant);

const general = await fireweave.controlPoints.evaluate('new-checkout', 'boolean', false, {
  targetingKey: 'user_42',
});

Nine methods: getBooleanValue, getStringValue, getNumberValue, getObjectValue, getBooleanDetails, getStringDetails, getNumberDetails, getObjectDetails, evaluate. *Value returns Decision.value. *Details returns the whole Decision. Evaluation never throws. The per-call parameter is flagKey. That name is fixed by the wire protocol. See Control points.

Adapters

Adapter	Use
`FireweaveRemoteAdapter`	Production. `initFireweave({ mode: 'remote', … })` builds it.
`FireweaveLocalAdapter`	Dev boolean map. `initFireweave({ mode: 'local', … })` builds it.
`InMemoryAdapter`	Tests and conformance fixtures. `{ flags, fault?, initError?, initGate? }`.

See Adapters and Testing.

Errors

Single class FireweaveError with 15 kinds: NotReady, FlagNotFound, TypeMismatch, InvalidContext, Authentication, Authorization, RateLimited, Timeout, Network, BackendUnavailable, MalformedResponse, UnsupportedCapability, Configuration, AlreadyClosed, Internal. Evaluation never throws. Helpers: isFireweaveError, ERROR_TAXONOMY, redactSecrets. See Errors.

Testing

Prefer local mode for a first offline run. Use InMemoryAdapter when you need typed fixtures. The repo test-server stub implements POST /v1/flags/evaluate and GET /health. It does not implement POST /v1/targets/register. See Testing.

Shutdown

await fireweave.shutdown();

Default timeout: 10 seconds. After shutdown, later evaluations degrade with AlreadyClosed. See Initialize, ready, shutdown.

Not in this SDK

@fireweaveai/sdk as the install target (frozen at 2.1.0)
FireweaveProvider, makeFireweaveLocalProvider, and any OpenFeature peer
releases, exposures, signals, capabilities, guardrails
Environment-variable auto-read (FW_API_URL, FW_PROJECT_API_KEY, FW_DEPRECATION_WARNINGS)
In-process local evaluation from polled definitions

Quickstart

Offline evaluate in every language.

Compatibility

Seven-language surface and the 65×7 aggregate.

Migrate to v1

Package rename and the retired provider / extension surface.

Get Started

SDKs

Concepts

Production

CLI

Terraform

Testing

Troubleshooting

Migration

Reference

Node.js, Bun, and Deno

Supported runtimes

Install

Initialize

Configuration and authentication

Targets

Control points

Adapters

Errors

Testing

Shutdown

Not in this SDK

Next

Quickstart

Compatibility

Migrate to v1

​Supported runtimes

​Install

​Initialize

​Configuration and authentication

​Targets

​Control points

​Adapters

​Errors

​Testing

​Shutdown

​Not in this SDK

​Next

Quickstart

Compatibility

Migrate to v1

Supported runtimes

Install

Initialize

Configuration and authentication

Targets

Control points

Adapters

Errors

Testing

Shutdown

Not in this SDK

Next