Core TypeScript types, interfaces, and enums for the Flaggr SDK and evaluation system

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

Extended evaluation result with metadata:

interface EvaluationResult<T extends FlagValue = FlagValue> {
  value: T
  variant?: string
  reason: EvaluationReason
  flagKey: string
  errorCode?: string
}

Targeting Types

TargetingRule

interface TargetingRule {
  id: string
  conditions: Condition[]
  conditionOperator?: 'and' | 'or'     // Default: 'and'
  groups?: ConditionGroup[]             // Nested condition groups
  groupOperator?: 'and' | 'or'
  rolloutPercentage?: number            // 0-100
  variant?: string                       // Named variant to select
  value?: FlagValue                      // Literal value to return
}

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 (0-100)
}

SDK Types

FlaggrConfig

Configuration for createFlaggr():

interface FlaggrConfig {
  apiUrl?: string               // Default: 'https://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)
  enableStreaming?: boolean     // SSE real-time updates
  defaults?: Record<string, FlagValue>  // Offline defaults
}

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
  onDestroy?(): void
}

FlagChangeEvent

interface FlagChangeEvent {
  flagKey: string
  oldValue?: FlagValue
  newValue: FlagValue
  timestamp: number
}

ConnectionState

type ConnectionState = 'CONNECTING' | 'CONNECTED' | 'DISCONNECTED' | '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
  token: string
  tokenType?: 'opaque' | 'jwt'
  permissions: {
    read: boolean
    write: boolean
    delete: boolean
  }
  scopes?: string[]         // JWT tokens only
  expiresAt?: string
  lastUsedAt?: string
  createdBy?: string
  createdAt: 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 (Enum)

enum EvaluationReason {
  STATIC = 1,
  DEFAULT = 2,
  TARGETING_MATCH = 3,
  SPLIT = 4,
  CACHED = 5,
  FLAG_NOT_FOUND = 6,
  ERROR = 7,
  DISABLED = 8,
}