npm package: @sessionsight/flags
Description: Feature flags SDK for SessionSight.
Author: SessionSight
Latest version: 1.0.1

# @sessionsight/flags

Server-side SDK for evaluating feature flags with segment-based targeting in SessionSight.

## Installation

```bash
npm install @sessionsight/flags
```

## Quick Start

```typescript
import FeatureFlags from '@sessionsight/flags';

await FeatureFlags.init({
  secretApiKey: 'sessionsight_sec_your_secret_key',
  propertyId: 'your-property-id',
  environment: 'production',
});

// Boolean flag
const showBeta = FeatureFlags.getBooleanFlag('beta-ui', false);

// String flag
const bannerText = FeatureFlags.getStringFlag('banner-message', 'Welcome!');
```

## API Reference

### `FeatureFlags.init(config, context?)`

Initialize the SDK. Fetches flag configuration and evaluates flags. Returns a Promise that must be awaited before calling other methods.

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `secretApiKey` | `string` | Yes | - | Your secret API key (`sessionsight_sec_...`) |
| `propertyId` | `string` | Yes | - | The property ID to evaluate flags for |
| `environment` | `string` | Yes | - | Environment name (e.g., `production`, `staging`) |
| `apiUrl` | `string` | No | `https://api.sessionsight.com` | Custom API endpoint |

The optional `context` parameter allows passing an evaluation context on init:

| Property | Type | Description |
| --- | --- | --- |
| `userId` | `string` | Your user's ID. Used for percentage rollouts and user targeting. |
| `visitorId` | `string` | SessionSight visitor ID. Enables segment-based targeting via `segment_match` rules. |
| Custom properties | `string \| number \| boolean` | Any additional properties for targeting rules. |

### `FeatureFlags.getBooleanFlag(key, defaultValue)`

Get a boolean flag value. Returns `defaultValue` if the flag doesn't exist, is disabled, or hasn't been initialized.

```typescript
const showFeature = FeatureFlags.getBooleanFlag('new-feature', false);
```

### `FeatureFlags.getStringFlag(key, defaultValue)`

Get a string flag value. Returns `defaultValue` if the flag doesn't exist, is disabled, or hasn't been initialized.

```typescript
const theme = FeatureFlags.getStringFlag('theme', 'light');
```

### `FeatureFlags.refresh(context?)`

Re-evaluate flags with a new context. Use this for per-request targeting with visitor or user attributes.

```typescript
await FeatureFlags.refresh({
  visitorId: 'visitor-uuid',
  userId: 'user-123',
  plan: 'enterprise',
});
const hasAccess = FeatureFlags.getBooleanFlag('advanced-analytics', false);
```

### `FeatureFlags.destroy()`

Tear down the SDK instance. Call this during cleanup if needed.

## Per-Request Targeting

For web applications serving multiple users, call `refresh()` with the current user's context on each request:

```typescript
// Express middleware example
app.use(async (req, res, next) => {
  await FeatureFlags.refresh({
    visitorId: req.cookies.ss_vid,
    userId: req.user?.id,
  });
  next();
});
```

The `visitorId` comes from the `ss_vid` cookie set by the Insights SDK on the frontend. Pass it to enable segment-based targeting rules configured in the SessionSight dashboard.

## Authentication

This SDK uses your **secret API key** (`sessionsight_sec_...`), not the public key. The secret key should only be used in server-side code. Never expose it in client-side JavaScript.

## Build Outputs

| File | Format | Usage |
| --- | --- | --- |
| `dist/index.js` | ESM | `import FeatureFlags from '@sessionsight/flags'` |
| `dist/index.d.ts` | Types | TypeScript type definitions |