TypeScript Types

`CanaryGate`

The main SDK class.


class CanaryGate {
  constructor(apiKey: string, options?: CanaryGateOptions)
  init(): Promise<void>
  getFlag(key: string): FlagData | undefined
  getFlags(): FlagData[]
  isStale(): boolean
  getLastSyncAt(): string | null
  disconnect(): void
}

`CanaryGateOptions`


type CanaryGateOptions = {
  /** Environment slug. Defaults to the project default environment. */
  environment?: string
  /** Browser polling interval in ms. Default: 30000, clamped to a 3000ms minimum (0 disables). Throws if set on the server entry. */
  pollIntervalMs?: number
  /** Initial stream reconnect delay in ms. Default: 5000. Server-only; throws if set on the browser entry. */
  reconnectDelay?: number
  /** Maximum stream reconnect delay in ms. Default: 30000. Server-only. */
  maxReconnectDelay?: number
  /** Time in ms without a server heartbeat before reconnecting the stream. Default: 65000. Server-only. */
  heartbeatTimeoutMs?: number
  /** Called whenever the evaluated flag set changes (polling refresh or SSE event), with the updated flags. Never called on initial load. */
  onUpdate?: (flags: FlagData[]) => void
}

The API base URL is not an option — it is resolved from the CANARYGATE_BASE_URL (or NEXT_PUBLIC_CANARYGATE_BASE_URL in browsers) environment variable, defaulting to https://api.canarygate.dev. Set the variable when self-hosting or during local development.

`FlagData`

Union type representing any flag.


type FlagData = BooleanFlagData | RolloutFlagData

`BooleanFlagData`


type BooleanFlagData = {
  key: string
  type: 'boolean'
  enabled: boolean
}

`RolloutFlagData`


type RolloutFlagData = {
  key: string
  type: 'rollout'
  enabled: boolean
  percent: number
}

Narrowing by type

Use type for safe narrowing:


const flag = canary.getFlag('new-dashboard')
 
if (flag?.type === 'rollout') {
  // TypeScript knows flag is RolloutFlagData here
  console.log(flag.percent)
}

Full exports


import {
  CanaryGate,
  type CanaryGateOptions,
  type FlagData,
  type BooleanFlagData,
  type RolloutFlagData
} from '@canarygate/sdk/client'
 
// Both entry points export the same types:
import { type FlagData as ServerFlagData } from '@canarygate/sdk/server'