> ## Documentation Index
> Fetch the complete documentation index at: https://superflag.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Node SDK methods, options, cache state, and failure contract

# Node SDK API reference

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

## `createSuperflag(options)`

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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.