SDK API Reference

Detailed API reference for all Truflag client SDKs.

Public client key

In the dashboard, go to Environments and copy the Public key. Pass it asapiKey when configuring any SDK.

Configure options

Configure once at app startup with at least apiKey.

TSTypeScript

await Flags.configure({
  apiKey: process.env.NEXT_PUBLIC_TRUFLAG_CLIENT_KEY!,
  user: { id: "user-123", attributes: { plan: "pro" } },
});

apiKey

Requiredstring

Public environment key copied from the dashboard.

user

OptionalTruflagUser

Initial active user. If omitted, the SDK restores cached user or creates anonymous identity.

Requiredstring

Stable user identifier used for evaluation and bucketing.

attributes

OptionalUserAttributes

Optional targeting attributes for the active user.

streamEnabled

Optionalboolean

default: true

Enable streaming with polling fallback.

cacheTtlMs

Optionalnumber

default: 300000

Cache snapshot freshness window.

pollingIntervalMs

Optionalnumber

default: 60000

Polling interval when stream is unavailable.

requestTimeoutMs

Optionalnumber

default: 6000

Per-request timeout.

telemetryEnabled

Optionalboolean

default: true

Enable exposures and custom telemetry events.

telemetryFlushIntervalMs

Optionalnumber

default: 10000

Telemetry flush interval.

telemetryBatchSize

Optionalnumber

default: 50

Max events per telemetry flush.

logLevel

Optional"debug" | "info" | "warn" | "error" | "silent"

default: "debug"

Minimum SDK log level.

logger

OptionalLogger

Custom logger implementation.

fetchFn

OptionalFetchLike

Custom fetch implementation.

storage

OptionalStorageAdapter

Custom persistence adapter.

Runtime methods

Core identity, refresh, and flag-read APIs.

Flags.login()

Sets active user and refreshes flag state.

TSTypeScript

Flags.login(user: {
  id: string;
  attributes?: Record<string, string | number | boolean | null>;
}): Promise<void>

Returns

Promise resolved after refresh finishes.

Flags.setAttributes()

Merges attributes into current user and refreshes.

TSTypeScript

Flags.setAttributes(
  attributes: Record<string, string | number | boolean | null>
): Promise<void>

Returns

Promise resolved after refresh finishes.

Flags.refresh()

Fetches latest flags for active user.

TSTypeScript

Flags.refresh(): Promise<void>

Returns

Promise resolved after refresh attempt.

Flags.logout()

Switches to anonymous identity and refreshes.

TSTypeScript

Flags.logout(): Promise<void>

Returns

Promise resolved after anonymous refresh.

Flags.getFlag()

Reads current flag value from SDK state.

TSTypeScript

Flags.getFlag<T>(flagKey: string, defaultValue: T): T

Returns

Resolved value, or fallback when state is not ready or key is missing.

Notes

Automatically queues exposure for this read.

Flags.getFlagPayload()

Returns metadata payload for a flag.

TSTypeScript

Flags.getFlagPayload(flagKey: string): Record<string, unknown> | null

Returns

Payload object or null.

Notes

Does not emit exposure by itself.

Flags.getAllFlags()

Returns all loaded flags.

TSTypeScript

Flags.getAllFlags(): Record<string, unknown>

Returns

Object keyed by flag key.

Notes

Queues exposures for returned flags.

Flags.isReady()

Readiness state for runtime reads.

TSTypeScript

Flags.isReady(): boolean

Returns

True when SDK has usable state.

Flags.subscribe()

Subscribes to SDK state changes.

TSTypeScript

Flags.subscribe(callback: () => void): () => void

Returns

Unsubscribe function.

Reactive APIs

Subscribe to state or flag changes in UI flows.

useFlagsReady()

Subscribes to readiness state.

TSTypeScript

useFlagsReady(): boolean

Returns

True when SDK has usable state.

useFlag()

Subscribes to a single flag value.

TSTypeScript

useFlag<T>(flagKey: string, defaultValue: T): T

Returns

Resolved value or fallback.

Notes

Automatically reports exposure when payload signature changes.

useFlagPayload()

Subscribes to flag payload metadata.

TSTypeScript

useFlagPayload(flagKey: string): Record<string, unknown> | null

Returns

Payload object or null.

Telemetry and events

Custom events, exposures, and manual read-reporting APIs.

Flags.track()

Queues a custom telemetry event.

TSTypeScript

Flags.track(
  eventName: string,
  properties?: Record<string, unknown>,
  options?: { immediate?: boolean }
): Promise<void>

Returns

Promise resolved after optional immediate flush.

Notes

Blank event names are ignored.
Flushes immediately once queue reaches telemetryBatchSize.

Flags.expose()

Manually emits exposure for a flag.

TSTypeScript

Flags.expose(
  flagKey: string,
  options?: { immediate?: boolean; properties?: Record<string, unknown> }
): Promise<void>

Returns

Promise resolved after optional immediate flush.

Flags.notifyFlagRead()

Advanced API: reports a flag read without returning value.

TSTypeScript

Flags.notifyFlagRead(flagKey: string): void

Returns

Nothing.

Notes

No-op if SDK is not ready or flag is missing.