@sheepit-ai/sdk-js

Browser-side SDK for the Sheepit release-intelligence platform. Ship flags, run experiments, and track events with a tiny (~8KB gzipped) client.

React apps: use @sheepit-ai/react — it wraps this SDK with hooks and a provider.

Note: GoaTech* named exports (GoaTech, IGoaTech, GoaTechConfig) are deprecated aliases for Sheepit, ISheepit, SheepitConfig and will be removed in 2.0.0. Update imports at your convenience — both names work in 1.x.

Install

npm install @sheepit-ai/sdk-js
# or
pnpm add @sheepit-ai/sdk-js
# or
yarn add @sheepit-ai/sdk-js

Quickstart

import { Sheepit } from "@sheepit-ai/sdk-js";

const gt = Sheepit.create({
  apiKey: "lp_pub_xxx_abc123...", // publishable key — safe in browsers
  apiUrl: "https://api.goatech.ai", // optional, defaults to prod
});

// Track an event
gt.track("course_viewed", { course_id: "abc-123" });

// Evaluate a flag
const showBeta = gt.flag("show_beta_ui", false);

// Get an experiment variant (server-bucketed, sticky per device)
const { variant, payload } = gt.experiment("checkout_redesign");

// Identify a user after login
gt.identify("user_abc123", { email: "[email protected]" });

// On logout
gt.reset();

Keys

Use the publishable key (lp_pub_*) in browsers. It can only post events and fetch config — no admin access. Secret keys (lp_sec_*) are rejected at initialization if used in a browser context.

API

Sheepit.create(config)

Create an SDK instance. Required: apiKey. Other options:

• apiUrl — defaults to https://api.goatech.ai
• debug — enables verbose logging + local flag overrides
• flushInterval — ms between event flushes (default 5000)
• flushSize — batch size (default 20)
• autoCaptureErrors — capture window.onerror + unhandledrejection as $error events (default true; pass false to disable or an object to configure)
• autoCaptureHttpErrors — wrap fetch to emit $http_error on non-2xx responses (default false)
• appVersion — attached to every event for Release attribution

gt.track(eventName, properties?)

Queue an event for batch upload. Returns immediately; events flush on a timer, on visibilitychange, and on pagehide.

gt.identify(userId, traits?)

Associate the current device with a user. Subsequent events carry user_id + traits. Do not put PII in traits unless you've disclosed it.

gt.reset()

Clear user identity and cached experiment assignments. Call on logout.

gt.flag<T>(flagKey, defaultValue?)

Return the server-evaluated flag value, or defaultValue if not set. Fires a $flag_exposure event once per session per flag.

gt.experiment(experimentKey)

Return the assigned variant for an experiment. Result is { variant: string; payload?: Record<string, unknown> }. Assignments are computed server-side and remain sticky per device.

gt.flush()

Force-flush queued events. Returns a promise that resolves when the batch is sent.

gt.destroy()

Tear down the instance (stops timers, clears state). Useful in tests.

Offline

Events queue locally (IndexedDB or localStorage) when the network is down and retry with exponential backoff. Cap is ~1000 events to prevent unbounded memory growth — oldest dropped first.

Type-safe flags via @sheepit-ai/cli

Install the CLI and run sheepit codegen to generate type-safe flag constants from your project's Flag definitions. See the CLI README.

License

MIT © GoaTech AI LLC