@levered_dev/sdk

TypeScript SDK for Levered — variant optimization with multi-armed and contextual bandits.

Install

npm install @levered_dev/sdk

Basic Usage

import { LeveredClient } from '@levered_dev/sdk';

const client = new LeveredClient({
  apiUrl: 'https://api.levered.dev',
  onExposure: (event) => {
    // Log to your warehouse (BigQuery, Snowflake, Postgres, etc.)
    analytics.track('variant_exposure', event);
  },
  onError: (err) => {
    console.error('Levered SDK error:', err);
  },
});

const result = await client.getVariant({
  anonymousId: 'user-abc-123',
  optimizationId: 'your-optimization-uuid',
  context: { device_type: 'mobile', source: 'email' }, // optional, for CMAB
});

if (result) {
  // Use result.variant — e.g. { headline: "Save 20%", cta_text: "Get Started" }
  renderPage(result.variant);
} else {
  // Fallback — API unavailable or model not trained yet
  renderPage({ headline: 'Welcome', cta_text: 'Sign Up' });
}

React

import { LeveredProvider, useVariant } from '@levered_dev/sdk/react';

function App() {
  return (
    <LeveredProvider
      apiUrl="https://api.levered.dev"
      anonymousId={getSessionId()}
      onExposure={(event) => analytics.track('exposure', event)}
    >
      <HeroSection />
    </LeveredProvider>
  );
}

function HeroSection() {
  const { variant, isLoading } = useVariant({
    optimizationId: 'your-optimization-uuid',
    fallback: { headline: 'Welcome', cta_text: 'Sign Up' },
    context: { device_type: 'mobile' },
  });

  return (
    <section>
      <h1>{variant.headline}</h1>
      <button>{variant.cta_text}</button>
    </section>
  );
}

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiUrl | string | — | Base URL of the Levered API (required) | | onExposure | (event) => void | — | Called when a user is exposed to a variant | | onError | (error) => void | — | Called when a request fails after all retries | | timeoutMs | number | 2000 | Request timeout in ms | | maxRetries | number | 2 | Retry attempts with exponential backoff (200ms, 400ms) | | cacheTtlMs | number | 60000 | In-memory cache TTL in ms. Set to 0 to disable |

How It Works

1. getVariant() calls POST /api/v2/optimizations/:id/serve with the anonymous ID and optional context.
2. The API returns the best variant(s) ranked by expected reward from the bandit model.
3. The SDK fires onExposure so you can log the exposure to your warehouse.
4. Responses are cached in-memory (1 min default) to avoid redundant requests.
5. On network failure, retries up to maxRetries times with exponential backoff, then returns null.

Exposure Logging

You are responsible for logging exposures to your data warehouse. The onExposure callback receives:

{
  anonymousId: string;       // The user/session ID you provided
  optimizationId: string;    // UUID of the optimization
  variant: Record<string, string | number | boolean>;  // The assigned variant
  context: Record<string, unknown>;  // Context sent with the request
  timestamp: string;         // ISO-8601 timestamp
}

Log this to your BigQuery/Snowflake/Postgres exposures table. Levered reads from your warehouse to train models — it does not store your behavioral data.