Core TypeScript types, interfaces, and enums for the Flaggr SDK and evaluation system
Last updated November 14, 2026
Type Reference
Complete reference for the TypeScript types used across the Flaggr SDK and API.
Core Types
FeatureFlag
The complete flag definition:
interface FeatureFlag {
key: string
name: string
type: FlagType
enabled: boolean
defaultValue: FlagValue
variants?: FlagVariant[]
targeting?: TargetingRule[]
projectId: string
serviceId: string
environment: Environment
isPublic?: boolean
tags?: string[]
description?: string
}FlagType
type FlagType = 'boolean' | 'string' | 'number' | 'object'FlagValue
type FlagValue = boolean | string | number | Record<string, unknown>Environment
type Environment = 'development' | 'staging' | 'production'Evaluation Types
EvaluationContext
Context passed with every flag evaluation:
interface EvaluationContext {
targetingKey?: string
[key: string]: string | number | boolean | undefined
}Always include targetingKey for consistent rollouts and variant assignment.
ResolutionDetails
The result of a flag evaluation:
interface ResolutionDetails<T extends FlagValue = FlagValue> {
value: T
variant?: string
reason?: string
errorCode?: string
errorMessage?: string
flagMetadata?: Record<string, string | number | boolean>
}EvaluationResult
What @flaggr/sdk's evaluate and evaluateSync return:
interface EvaluationResult<T extends FlagValue = FlagValue> {
value: T
reason: 'STATIC' | 'DEFAULT' | 'TARGETING_MATCH' | 'OVERRIDE' | 'VARIANT' | 'SPLIT' | 'DISABLED'
| 'NOT_FOUND' | 'FLAG_NOT_FOUND' | 'EXPERIMENT' | 'PREREQUISITE_FAILED' | 'MUTUAL_EXCLUSION' | 'ERROR'
variant?: string
errorMessage?: string
}reason is a string, not the Connect enum below: the client passes on whatever reason the server sent. FLAG_NOT_FOUND comes from the data plane, and EXPERIMENT, PREREQUISITE_FAILED and MUTUAL_EXCLUSION from the control plane. 0.4.0's type doesn't list those four, although the client returns them. See Evaluation Reasons and Errors.
Targeting Types
TargetingRule
interface TargetingRule {
id: string
conditions: Condition[] // Empty, with no groups: the rule matches everyone (see below)
conditionOperator?: 'and' | 'or' // Default: 'and'
groups?: ConditionGroup[] // Nested condition groups
groupOperator?: 'and' | 'or'
rolloutPercentage?: number // Whole number 0-100; unset serves everyone the rule matches
variant?: string // Variant name reported with the rule's value (doesn't serve that variant's value)
value?: FlagValue // Value to serve (the flag's defaultValue when unset)
}A rule with no conditions and no groups matches everyone on https://flaggr.dev and in @flaggr/sdk 0.5.0 evaluating locally; a data plane from before Flaggr 0.5.0 and local evaluation before @flaggr/sdk 0.5.0 match it to nobody. See Evaluation Order. A condition group without conditions matches nobody.
The flags https://api.flaggr.dev exports and streams carry every field, an unset one as null (or "" for conditionOperator, groupOperator and variant). @flaggr/sdk 0.5.0 evaluating locally reads those as unset: a rule whose rolloutPercentage is null serves everyone it matches, and one whose value is null serves the flag's default value.
Condition
interface Condition {
property: string
operator: ConditionOperator
value: string | number | boolean | Array<string | number>
}ConditionOperator
type ConditionOperator =
| 'equals' | 'not_equals'
| 'in' | 'not_in'
| 'contains' | 'starts_with' | 'ends_with' | 'regex'
| 'greater_than' | 'less_than' | 'gte' | 'lte'
| 'before' | 'after'FlagVariant
interface FlagVariant {
name: string
value: FlagValue
weight?: number // Percentage weight, a whole number 0-100
}SDK Types
FlaggrConfig
Configuration for createFlaggr():
interface FlaggrConfig {
apiUrl?: string // Default: 'https://api.flaggr.dev'
serviceId: string // Your service identifier
apiKey?: string // API token
environment?: string // Target environment
context?: EvaluationContext // Default evaluation context
plugins?: FlaggrPlugin[] // SDK plugins
cacheTtl?: number // Cache TTL in ms (default: 10000)
updateMode?: 'stream' | 'batch' | 'poll' // Update delivery (default: 'poll')
batchIntervalMs?: number // Batch refresh cadence in ms (default: 2000)
enableStreaming?: boolean // Deprecated alias for updateMode: 'stream'
bootstrap?: Record<string, unknown> // Flag configurations to evaluate locally from the start
defaults?: Record<string, FlagValue> // Fallbacks for evaluations that fail or find no flag
remoteConfig?: boolean // Fetch service settings from GET /api/sdk-config (control plane)
exposeFlags?: boolean // Publish resolved values to window.__FLAGGR_FLAGS__ for browser analytics (0.5.0+; default: on in a browser page; data-expose-flags="false" on any script tag turns the default off)
}FlaggrPlugin
Plugin interface for extending SDK behavior:
interface FlaggrPlugin {
name: string
onInit?(client: FlaggrClientInstance): void
onEvaluate?(flagKey: string, context?: EvaluationContext): void
onEvaluateComplete?(flagKey: string, result: EvaluationResult, durationMs: number): void
onEvaluateError?(flagKey: string, error: Error, durationMs: number): void
onFlagChange?(event: FlagChangeEvent): void
onConnectionStateChange?(state: ConnectionState): void
onRequest?(info: RequestInfo): void // { url, durationMs, ok, requestBytes, responseBytes }
onDestroy?(): void
}FlagChangeEvent
interface FlagChangeEvent {
flagKey: string
oldValue?: FlagValue
newValue: FlagValue
}ConnectionState
enum ConnectionState {
DISCONNECTED = 'disconnected',
CONNECTING = 'connecting',
CONNECTED = 'connected',
ERROR = 'error',
}Project & Team Types
Project
interface Project {
id: string
name: string
slug: string
settings?: {
defaultEnvironment?: string
demoEnabled?: boolean
demoServiceId?: string
}
tags?: string[]
}Service
interface Service {
id: string
slug: string
projectId: string
name: string
description?: string
tags?: string[]
}ProjectRole
type ProjectRole = 'owner' | 'admin' | 'member' | 'viewer'ApiToken
interface ApiToken {
id: string
projectId: string
name: string
kind: 'api_token' | 'sdk_key' | 'jwt'
tokenType?: 'opaque' | 'jwt'
permissions: {
read: boolean
write: boolean
delete: boolean
evaluationOnly?: boolean // true on an SDK key
}
scopes?: string[] // JWT tokens and scoped API tokens (tokenType "opaque")
tokenHint?: string
expiresAt?: string
lastUsedAt?: string
lastUsedUserAgent?: string
createdBy?: string
createdByName?: string // list only
createdByEmail?: string // list only
createdAt: string
updatedAt?: string
}Connect Protocol Types
Types used by the Connect-RPC protocol:
Value (Protobuf)
interface Value {
boolValue?: boolean
stringValue?: string
numberValue?: number
jsonValue?: string // JSON-encoded for objects
}EvaluationReason (Connect protocol enum)
The reason field of Connect-RPC and gRPC-Web evaluation responses:
enum EvaluationReason {
STATIC = 1,
DEFAULT = 2,
TARGETING_MATCH = 3,
SPLIT = 4,
CACHED = 5,
FLAG_NOT_FOUND = 6,
ERROR = 7,
DISABLED = 8,
}Related
- Client SDK Usage — SDK initialization and usage
- TypeScript SDK — Standalone SDK package
- Targeting Rules — Targeting rule structure