Getting Started

Quickstart

Get ToggleAI running in your application in under 5 minutes. Install the SDK, initialize, and evaluate your first flag.

1. Install the SDK

typescript
npm install toggleai-sdk
# or
yarn add toggleai-sdk
# or
pnpm add toggleai-sdk

2. Initialize the Client

Create a client instance with your API credentials. The SDK will fetch your configuration payload and begin background polling to keep flags fresh.

typescript
import { ToggleAIClient } from "toggleai-sdk";

const client = new ToggleAIClient({
  clientId: "pk_live_xxxxxxxxxxxxxxxx",
  secret: "sk_live_xxxxxxxxxxxxxxxx",
  pollingInterval: 30000, // refresh every 30s (default)
});

await client.init();

3. Evaluate Feature Flags

Flags are evaluated locally from the cached config payload — zero network latency, sub-millisecond response.

typescript
const context = {
  userId: "user_123",
  attributes: { plan: "premium", country: "US" },
};

// Boolean flag
if (client.getFlag("new-checkout", context)) {
  showNewCheckout();
}

// Typed flag value (string, number, JSON)
const color = client.getFlagValue<string>("buy-btn-color", context, "#000");
const limit = client.getFlagValue<number>("max-items", context, 10);

4. Read Remote Configs

Remote configs are key-value pairs that don't depend on user context. Perfect for app-wide settings.

typescript
const timeout = client.getConfig<number>("api_timeout_ms", 5000);
const theme = client.getConfig<{ primary: string }>("theme_colors", { primary: "#fff" });
const all = client.getAllConfigs();

5. Log Events & Errors

The SDK includes a built-in logger that batches and flushes events to the backend automatically.

typescript
const logger = client.getLogger();

logger.info("User signed in", { userId: "user_123" });
logger.warn("Slow query", { duration: 450 });

try {
  await riskyOperation();
} catch (err) {
  logger.captureError(err as Error, { userId: "user_123" });
}

6. Cleanup

Always close the client when shutting down. This stops polling and flushes any pending log events.

typescript
client.close();
OverviewAuthentication