Orbit Flag Client

A simple TypeScript/JavaScript SDK for evaluating feature flags from your Orbit Flag service, similar to LaunchDarkly's client SDK.

Installation

npm install @orbit-flag/client

Usage

Basic Setup

import { OrbitFlagClient } from "@orbit-flag/client";

const client = new OrbitFlagClient({
  teamId: "your-team-id-here",
  context: {
    userId: "user-123",
    environment: "production",
    version: "1.2.0",
  },
});

Evaluating Boolean Feature Flags

The client evaluates boolean feature flags with fallback values:

// Evaluate a feature flag (returns boolean)
const isNewFeatureEnabled = await client.evaluate("new-feature", false);

// Fallback defaults to false if not specified
const isBetaEnabled = await client.evaluate("beta-features");

// Use in conditional logic
if (await client.evaluate("maintenance-mode", false)) {
  console.log("Application is in maintenance mode");
}

Error Handling

The client automatically falls back to your provided default values if:

• The API request fails
• The flag doesn't exist
• Network timeouts occur
• Any other errors happen

// This will return false if anything goes wrong
const featureEnabled = await client.evaluate("risky-feature", false);

if (featureEnabled) {
  // Safe to use the new feature
}

Caching

The client automatically caches flag values to reduce API calls:

// First call hits the API
const value1 = await client.evaluate("cached-flag", false);

// Second call uses cached value (within TTL)
const value2 = await client.evaluate("cached-flag", false);

// Clear cache manually if needed
client.clearCache();

Checking Flag Existence

const exists = await client.flagExists("some-flag");
if (exists) {
  const value = await client.evaluate("some-flag", false);
}

API Format

The client sends requests to your /api/evaluate endpoint in this format:

{
  "teamId": "your-team-id",
  "flagKey": "flag-name",
  "context": {
    "userId": "user-123",
    "environment": "production",
    "version": "1.2.0"
  }
}

Note: The context field is only included if you provide it in the client configuration.

Configuration Options

interface ClientConfig {
  teamId: string; // Required: Your team ID
  context?: Record<string, any>; // Optional: Context object sent with each evaluation
  baseUrl?: string; // Optional: API base URL (default: http://localhost:3000)
  timeout?: number; // Optional: Request timeout in ms (default: 5000)
  enableCaching?: boolean; // Optional: Enable flag caching (default: true)
  cacheTTL?: number; // Optional: Cache TTL in ms (default: 300000)
}

Browser and Node.js Support

The client works in both browser and Node.js environments:

• Browser: Uses native fetch API
• Node.js 18+: Uses built-in fetch
• Node.js < 18: Automatically imports node-fetch (install separately)

TypeScript Support

Full TypeScript support with proper typing for all flag variations and configurations.

License

MIT