Node SDK API reference

Current package: @superflag-sh/node@0.2.0.

`createSuperflag(options)`

const flags = createSuperflag({
  apiKey: process.env.SUPERFLAG_API_KEY!,
  endpoint: "https://superflag.sh/api/v1/advanced-config",
  defaultContext: { targetingKey: "server" },
  maxStaleAgeSeconds: 86_400,
  requestTimeoutMs: 3_000,
  maxRetries: 2,
  onDiagnostic(event) {},
})

Option	Required	Description
`apiKey`	Yes	Environment server key beginning with `sdk_`
`endpoint`	No	Advanced-config endpoint; defaults to Superflag production
`allowInsecureHttpForLocalDevelopment`	No	Allow plain HTTP only for an explicit loopback endpoint
`defaultContext`	No	Context used when an individual read omits one
`maxStaleAgeSeconds`	No	Maximum age for last-known-good configuration
`requestTimeoutMs`	No	Per-request timeout
`maxRetries`	No	Bounded transient retries after the first attempt
`fetch`	No	Structural fetch implementation for tests or custom runtimes
`onDiagnostic`	No	Content-free operational diagnostics

endpoint and fetch are credential-bearing Interfaces: every configuration request passes the complete sdk_ bearer credential through them. Use only an HTTPS endpoint and a fetch implementation you control and trust. Never derive either option from a request, tenant, flag value, or other user-controlled input, and never log the request authorization header.

Read methods

await flags.isEnabled(key, context?)
await flags.getString(key, fallback, context?)
await flags.getNumber(key, fallback, context?)
await flags.getJson(key, fallback, context?)
await flags.details(key, fallback, context?)

isEnabled always uses false as its safe fallback. Other typed reads require an explicit fallback. Operational fetch, authorization, schema, and evaluation failures resolve to the fallback; they do not throw.

Lifecycle methods

const state = await flags.refresh()
const snapshot = flags.getState()

Concurrent first reads and refreshes coalesce. The returned state is detached from the internal cache.

State

getState() returns status, optional source app/environment, config version, fetch/expiry/stale timestamps, and the last bounded error. Status is one of idle, ready, stale, or error.

Cache and network behavior

The client:

keeps configuration in memory only;
honors server TTL and opaque ETag revalidation;
serves last-known-good configuration only within maxStaleAgeSeconds;
rejects source identity changes and config-version rollback;
clears cached configuration immediately on 401 or 403;
honors bounded Retry-After behavior on 429; and
never persists keys, contexts, or raw configuration.

Both 200 and 304 advanced-config responses consume one environment config sync. A 304 renews freshness without response bytes.

Core helper versus networked SDK

@superflag-sh/core/node is a pure helper for code that already has a config. @superflag-sh/node owns authenticated synchronization, caching, failure policy, and diagnostics before delegating evaluation to core.

Start here

Node and server SDK

React SDK

React Native and Expo

Core SDK

CLI and agents

Feature decisions

HTTP API

API reference

Node SDK API reference

`createSuperflag(options)`

Read methods

Lifecycle methods

State

Cache and network behavior

Core helper versus networked SDK

​Node SDK API reference

​createSuperflag(options)

​Read methods

​Lifecycle methods

​State

​Cache and network behavior

​Core helper versus networked SDK

Node SDK API reference

`createSuperflag(options)`

Read methods

Lifecycle methods

State

Cache and network behavior

Core helper versus networked SDK