open-index/open-npm huggingface dataset:
npm package: @flagly/sdk
Description: Official JavaScript/Node.js SDK for Flagly feature flags. Lightweight, fast, and easy to use.
Latest version: 0.1.0

# @flagly/sdk

Lightweight JavaScript and Node.js SDK for evaluating Flagly feature flags.

---

## 📦 Installation

Using npm:

```bash
npm install @flagly/sdk
```

Using yarn:

```bash
yarn add @flagly/sdk
```

Using pnpm:

```bash
pnpm add @flagly/sdk
```

---

## 🚀 Quick Start

```ts
import { FlaglyClient } from '@flagly/sdk';

const client = new Flagly({
  apiKey: 'flg_dev_xxxxx',
});

//sdk initialization
await client.init();

// Get single flag
const country = await client.getValue('country', 'IN');

// Get all flags
const flags = await client.getAllFlags();
```

---

## ⚙️ Configuration

```ts
new FlaglyClient({
  apiKey: string;       // Required
  apiHost?: string;     // Optional (default: http://localhost:4000/v1)
});
```

---

## 📚 API Reference

### `getAllFlags()`

Returns all evaluated flags.

```ts
const flags = await client.getAllFlags();
```

---

### `getValue(key, defaultValue)`

Returns a single flag value.

- If flag exists → returns evaluated value
- If flag disabled → returns defaultValue
- If flag missing → returns defaultValue

```ts
const theme = await client.getValue('theme', 'light');
```

---

## 🛡 Error Handling

The SDK throws clear errors in these cases:

- Invalid API key (401)
- Revoked API key (403)
- Invalid apiHost configuration
- Network failures (if no cache available)

Example:

```ts
try {
  await client.getAllFlags();
} catch (error) {
  console.error(error.message);
}
```

---

## ⚡ Features

- Bulk flag evaluation
- In-memory caching (TTL-based)
- Graceful fallback
- TypeScript support
- Lightweight and dependency-minimal

---

## 🧠 How It Works

- SDK fetches all flags from `/v1/evaluate`
- Flags are cached in memory
- Cache refreshes automatically after TTL
- SDK always returns a value (fallback-safe)

---

## 🛠 Requirements

- Node.js 16+

---

## 📄 License

MIT