Edge SDK reference

@avsbhq/edge is a feature-flag client built for edge runtimes: Cloudflare Workers, Vercel Edge Functions, Fastly Compute, Netlify Edge, Deno, Bun, and Lambda@Edge. It evaluates flags locally from a cached datafile and queues events for a flush that each adapter runs the way its runtime allows.

Install

npm install @avsbhq/edge

Quick start

Use the adapter for your runtime. It builds the client, binds a context from the request, awaits init(), and flushes events for you:

import { createCloudflareHandler } from '@avsbhq/edge/cloudflare'import type { KVNamespace } from '@avsbhq/edge/cloudflare'interface Env {  AVSB_SDK_KEY: string  AVSB_DATAFILE_CACHE: KVNamespace}export default {  fetch: createCloudflareHandler<Env>({    sdkKey: (env) => env.AVSB_SDK_KEY,    kv: (env) => env.AVSB_DATAFILE_CACHE,    handler: async (request, client) => {      const flag = client.getBoolFlag('new_homepage', false)      return Response.json({ enabled: flag.isEnabled(), url: request.url })    },  }),}

The adapter already bound a context, so a read takes just a key and a default. Pass a context explicitly only when one call needs a different identity.

Reading flags

import type { AvsbEdgeClient, EvalContext, Flag, GetFlagOptions } from '@avsbhq/edge'declare const client: AvsbEdgeClientinterface EdgeReadSurface {  getFlag<T>(flagKey: string, defaultValue: T, context?: EvalContext, options?: GetFlagOptions): Flag<T>  getBoolFlag(flagKey: string, defaultValue: boolean, context?: EvalContext, options?: GetFlagOptions): Flag<boolean>  getStringFlag(flagKey: string, defaultValue: string, context?: EvalContext, options?: GetFlagOptions): Flag<string>  getNumberFlag(flagKey: string, defaultValue: number, context?: EvalContext, options?: GetFlagOptions): Flag<number>  getJsonFlag<T>(flagKey: string, defaultValue: T, context?: EvalContext, options?: GetFlagOptions): Flag<T>  getAllFlags(context?: EvalContext, options?: { fireExposures?: boolean }): Record<string, Flag>}const theme: Flag<string> = client.getStringFlag('homepage_theme', 'default')const forSomeoneElse: Flag<boolean> = client.getBoolFlag('new_checkout', false, {  kind: 'user',  key: 'u_999',  plan: 'pro',})

Every read returns a frozen Flag<T> carrying value, variationKey, source, ruleId, ruleType, reasons, evaluatedAt, durationMicros, isEnabled() and exists(). The SDK installation guide documents that shape field by field; it is identical in every A vs B SDK.

source says where the value came from:

A typed getter checks the value against the type the dashboard declares for that flag. On a mismatch it returns your default with source: 'not_found' and logs both types. It never coerces. getAllFlags() fires no exposures by default, because a bulk read is not a decision served to a visitor.

Tracking events

import type { AvsbEdgeClient } from '@avsbhq/edge'declare const edge: AvsbEdgeClientedge.track('signup_completed') // a countedge.track('purchase', { revenue: 49.99 }) // moneyedge.track('items_added', { value: 3 }) // a quantityedge.track('checkout_completed', { revenue: 99.5, value: 2 }) // both

revenue and value are two separate columns end to end, exactly as in every other A vs B SDK. revenue is money in decimal major units of the project currency; value is the numeric metric value an average-value metric averages (items, seats, seconds). One conversion can carry money, a quantity, or both.

payload.properties is accepted for cross-runtime symmetry but is not stored on tracked events: the metric ingestion body has no properties field, so the SDK warns once rather than shipping something that looks delivered and is gone. Exposure events do carry properties.

Exposures are automatic: reading a flag whose decision came from an experiment queues one.

Flushing

flushEvents(): Promise<void> sends everything the request produced: queued exposures, queued tracked events, and any deferred cache write or heartbeat. Each adapter already calls it the way its runtime allows:

An edge invocation ends with its request, so a batch that cannot be delivered is lost rather than retried later. The failure log says exactly that, naming the endpoint, the status, and how many events went with it. One retry inside the request is on by default, and every attempt sends byte-identical event ids so ingestion deduplicates instead of double-counting.

Lifecycle

import type { AvsbEdgeClient, FlagDatafile } from '@avsbhq/edge'declare const edgeClient: AvsbEdgeClientinterface EdgeLifecycle {  init(): Promise<InitResultShape>  getInitResult(): InitResultShape | null  isReady(): boolean  getDatafile(): FlagDatafile | null  flushEvents(): Promise<void>}interface InitResultShape {  success: boolean  source: 'network' | 'bootstrap' | 'timeout' | 'error'  error?: Error  degraded?: boolean}const result = await edgeClient.init()if (!result.success) {  // Nothing to serve. Every read returns the default you passed.}

init() never rejects and never runs twice: concurrent callers share one attempt.

degraded: true means one thing only: a stale cached datafile is being served after a failed refresh. Flags still evaluate, and a change published since then is not visible yet.

There is nothing to close. An edge client has no timers, no sockets, and no global state.

Client options

import type { EdgeClientOptions } from '@avsbhq/edge'const options: EdgeClientOptions = {  sdkKey: 'sdk_production_ttqm0eaj4vth1krcb2xn',  cacheTtlMs: 300_000, // datafile freshness window, default 5 minutes  timeoutMs: 3000, // per datafile request  heartbeat: true, // report liveness, default true  maxQueueSize: 500,  eventRetryAttempts: 1,  logLevel: 'warn',}

Adapters own sdkKey, storage, waitUntil, context and pageUrl, because all five come from the request and the bindings you gave them. Everything else is passed through the adapter's clientOptions.

Caching is two separate ideas

• Freshness is cacheTtlMs (default 5 minutes). Past it the client revalidates over the network, and if that fails it serves the stale copy with degraded: true.
• Retention is how long an adapter's store keeps an entry at all. Cloudflare KV defaults to 24 hours (kvRetentionSeconds); the Vercel and Bun in-process maps default to 1 hour (memoryRetentionMs).

Keeping them apart is what makes the degraded path reachable: a store that hard-expired at the freshness window would leave nothing to fall back on when the CDN is unreachable.

Logging

The edge default is never silent. A browser console belongs to your end user; a Worker's log stream belongs to you, and there is no build step that flips a production define for a Worker. The default is console at warn, or debug when globalThis.__AVSB_DEV__ is true. Configuration-level messages are deduplicated for the life of the isolate, so a Worker serving ten thousand requests with a bad key logs it once. Set logLevel: 'silent' for no output at all.

The SDK never throws from a read, a track, or a flush.

Runtime adapters

Each adapter extracts an identity from the request in the way its runtime allows, and contextFrom overrides that when you know better. Adapters never invent a visitor id from the IP address.

Using the client directly

If you own the request lifecycle, skip the adapters:

import { AvsbEdgeClient, readVisitorId } from '@avsbhq/edge'export async function handle(req: Request): Promise<Response> {  const client = new AvsbEdgeClient({    sdkKey: process.env.AVSB_SDK_KEY ?? '',    context: { kind: 'user', key: readVisitorId(req.headers) ?? 'anonymous' },    pageUrl: req.url,  })  await client.init()  const flag = client.getBoolFlag('new_checkout', false)  const response = Response.json({ enabled: flag.isEnabled() })  await client.flushEvents()  return response}

Keeping the datafile fresh

Edge isolates are short-lived and cache the datafile per cold start, so a published change lands within cacheTtlMs at the latest. To pick it up sooner, register a flag.published webhook (Settings, then Webhooks) whose receiver fetches the new datafile and writes it into your runtime's store. New isolates then start from the fresh copy.

The webhook payload carries the project and environment that published, not the datafile itself, so the receiver fetches the datafile before writing it. The Cloudflare Workers and Deno Deploy guides show a receiver end to end.

What's next