npm package: @flagdrop/sdk
Description: FlagDrop backend SDK for Node.js — read feature flags from your cloud storage bucket
Latest version: 0.2.0

# @flagdrop/sdk

Feature flag management where evaluations run entirely inside **your** cloud. No vendor servers. No data leaving your infrastructure.

FlagDrop pushes a lightweight JSON config to a storage bucket in your cloud account. The SDK reads that file and evaluates flags locally — zero network calls to external servers during evaluation.

## Installation

Install the SDK and the cloud storage library for your provider:

```bash
# AWS
npm install @flagdrop/sdk @aws-sdk/client-s3

# GCP
npm install @flagdrop/sdk @google-cloud/storage

# Azure
npm install @flagdrop/sdk @azure/storage-blob
```

Only install the cloud library you need — the SDK lazy-loads providers so unused ones won't cause errors.

## Quick Start

```typescript
import { FlagClient } from '@flagdrop/sdk';

const flags = new FlagClient({
  bucket: 'my-app-flags',
  environment: 'production',
  provider: 'aws',       // 'aws' | 'gcp' | 'azure'
  region: 'us-east-1',
});

await flags.initialize();

// Boolean flag
const enabled = flags.getBool('new-checkout', false);

// String flag with targeting context
const theme = flags.getString('app-theme', 'light', { plan: 'enterprise' });

// Number flag
const maxItems = flags.getNumber('max-items', 10);

// JSON flag
const config = flags.getJSON('feature-config', { limit: 5 });

// Cleanup when shutting down
await flags.close();
```

## Cloud Providers

| Provider | Install | Storage |
|----------|---------|---------|
| **AWS** | `npm install @aws-sdk/client-s3` | Amazon S3 |
| **GCP** | `npm install @google-cloud/storage` | Google Cloud Storage |
| **Azure** | `npm install @azure/storage-blob` | Azure Blob Storage |

Each provider is loaded dynamically at runtime — only the cloud SDK you install is required.

## How It Works

1. **Define flags** in the FlagDrop dashboard
2. **FlagDrop pushes** a JSON config to your cloud storage bucket
3. **The SDK reads** that file locally and evaluates flags at runtime

Flag evaluation happens inside your infrastructure. User context never leaves your cloud.

## Targeting Rules

Pass user context to evaluate targeting rules locally:

```typescript
const ui = flags.getString('checkout-ui', 'standard', {
  plan: 'enterprise',
  country: 'US',
  email: 'admin@acme.com',
});
```

Supported operators: `eq`, `neq`, `in`, `notIn`, `lt`, `gt`, `startsWith`, `endsWith`.

Rules are evaluated in order — first match wins.

## Typed Context & targetingKey

Context values can be strings, numbers, booleans, or string arrays. The special `targetingKey` field provides a stable user identifier used as a fallback for percentage rollouts:

```typescript
const value = client.getBool('my-flag', false, {
  targetingKey: 'user-123',
  plan: 'enterprise',
  age: 25,
  beta: true,
  tags: ['admin', 'beta'],
});
```

- **Numbers** work directly with `lt`/`gt` operators (no string conversion needed)
- **Booleans** are compared via `String()` for `eq`/`neq`
- **String arrays** check overlap with `in`/`notIn` rule values
- **`targetingKey`** is used for rollout bucketing when the rollout attribute is missing from context

## Percentage Rollouts

Deterministic bucketing via MurmurHash3:

```typescript
const enabled = flags.getBool('new-search', false, { userId: 'user-123' });
```

Same user always gets the same result across evaluations and restarts.

## Configuration

```typescript
new FlagClient({
  bucket: 'my-flags',           // Storage bucket name (required)
  environment: 'production',     // Environment name (required)
  provider: 'aws',              // 'aws' | 'gcp' | 'azure' (required)
  region: 'us-east-1',          // Cloud region (required)
  refreshTtlMs: 30000,          // Auto-refresh interval in ms (default: 30000)
  telemetryUrl: '...',           // Optional: FlagDrop telemetry endpoint
});
```

## Links

- [FlagDrop](https://flagdrop.io)
- [Documentation](https://flagdrop.io/docs)
- [Dashboard](https://platform.flagdrop.io)