Skip to main content

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
}
Tip

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,
}