@hauses/flags-core

Core SDK for feature flags in JavaScript and TypeScript applications.

🌐 Website: flags.hauses.dev

Installation

npm install @hauses/flags-core
# or
yarn add @hauses/flags-core
# or
pnpm add @hauses/flags-core
# or
bun add @hauses/flags-core

Features

• ⚡ Lightweight - Zero dependencies, minimal bundle size
• 🎯 Type-safe - Full TypeScript support
• 🔄 Real-time - Fetch flags dynamically without redeployment
• 👥 Context targeting - Target flags based on user/company context
• 📊 Event tracking - Automatic flag access tracking
• 🚦 Rate limiting - Built-in rate limiting to prevent excessive API calls

Quick Start

import { FlagsClient } from '@hauses/flags-core';

// Initialize the client
const client = new FlagsClient(
  'your_publishable_key',
  {
    user: {
      key: 'user-123',
      email: '[email protected]',
      name: 'John Doe'
    },
    company: {
      key: 'company-456',
      name: 'Acme Inc'
    }
  }
);

// Initialize and fetch flags
await client.initialize();

// Check if a flag is enabled
const isEnabled = client.getFlag('new-feature');

if (isEnabled) {
  console.log('New feature is enabled!');
}

// Get all flags
const allFlags = client.getFlags();
console.log(allFlags);

API Reference

FlagsClient

Main client for interacting with the Flags API.

Constructor

new FlagsClient(publishableKey: string, context?: FlagsContext, options?: HttpClientOptions)

Parameters:

• publishableKey (string) - Your publishable key from flags.hauses.dev
• context (object, optional) - User and company context for targeting
• options (object, optional) - HTTP client configuration

Example:

const client = new FlagsClient(
  'pk_123456789',
  {
    user: { key: 'user-id', email: '[email protected]' }
  },
  {
    baseUrl: 'https://flags.hauses.dev/api',
    credentials: 'include'
  }
);

Methods

initialize(): Promise<void>

Initialize the client and fetch flags from the API.

await client.initialize();

getFlag(key: string): boolean

Get the value of a specific flag. Returns false if the flag doesn't exist.

const isEnabled = client.getFlag('feature-key');

getFlags(): RawFlags

Get all flags as an object.

const flags = client.getFlags();
// { "feature-1": { key: "feature-1", isEnabled: true }, ... }

setContext(context: FlagsContext): void

Update the user/company context.

client.setContext({
  user: {
    key: 'new-user-id',
    email: '[email protected]'
  }
});

isInitialized(): boolean

Check if the client has been initialized.

if (client.isInitialized()) {
  console.log('Client is ready');
}

fetchFlags(): Promise<RawFlags | undefined>

Manually fetch flags from the API (subject to rate limiting).

const flags = await client.fetchFlags();

Context & Targeting

The SDK supports user and company context for advanced targeting:

interface FlagsContext {
  user?: {
    key: string;          // required - unique user identifier
    name?: string;        // optional - user's display name
    email?: string;       // optional - user's email address
  };
  company?: {
    key: string;          // required - unique company identifier
    name?: string;        // optional - company's display name
  };
}

Example with Full Context

const client = new FlagsClient('pk_123', {
  user: {
    key: 'user-123',
    name: 'Jane Smith',
    email: '[email protected]'
  },
  company: {
    key: 'acme-corp',
    name: 'Acme Corporation'
  }
});

Event Tracking

The SDK automatically tracks flag access events for analytics. Events include:

• user_context - When a user context is set
• check_flag_access - When a flag is checked

These events are rate-limited to prevent excessive API calls.

Rate Limiting

The SDK includes built-in rate limiting:

• Flag fetches are limited to prevent excessive API requests
• Event tracking is rate-limited per flag
• Default: 60 requests per minute per action

HTTP Client

HttpClient

Low-level HTTP client for making API requests.

import { HttpClient } from '@hauses/flags-core';

const client = new HttpClient('pk_123', {
  baseUrl: 'https://flags.hauses.dev/api',
  credentials: 'include'
});

// GET request
const response = await client.get({
  path: 'flags',
  params: new URLSearchParams({ key: 'value' })
});

// POST request
const response = await client.post({
  path: 'events',
  body: { event: 'check_flag_access' }
});

TypeScript Types

interface Flag {
  key: string;
  isEnabled: boolean;
}

type RawFlags = Record<string, Flag>;

interface FlagsContext {
  company?: CompanyContext;
  user?: UserContext;
}

interface UserContext {
  key: string;
  name?: string;
  email?: string;
}

interface CompanyContext {
  key: string;
  name?: string;
}

interface HttpClientOptions {
  baseUrl?: string;
  sdkVersion?: string;
  credentials?: RequestCredentials;
}

Advanced Usage

Custom Base URL

const client = new FlagsClient(
  'pk_123',
  {},
  { baseUrl: 'https://custom.domain.com/api' }
);

Without Context

const client = new FlagsClient('pk_123');
await client.initialize();

Updating Context Dynamically

const client = new FlagsClient('pk_123', {
  user: { key: 'user-1' }
});

await client.initialize();

// Later, when user changes
client.setContext({
  user: { key: 'user-2', email: '[email protected]' }
});

// Fetch updated flags
await client.fetchFlags();

Error Handling

The SDK handles errors gracefully:

try {
  await client.initialize();
} catch (error) {
  console.error('Failed to initialize flags client:', error);
  // Client will return false for all flags if initialization fails
}

// Safe to use even if initialization failed
const isEnabled = client.getFlag('feature'); // Returns false

Browser Support

Works in all modern browsers that support:

• ES6+ / ES2015+
• Fetch API
• Promises

Node.js Support

Compatible with Node.js 18+ (requires native fetch support).

License

MIT

Support

• 📧 Email: [email protected]
• 🌐 Website: flags.hauses.dev
• 📖 Documentation: flags.hauses.dev/docs
• 🐛 Issues: GitHub Issues

Part of the Flags SDK monorepo.