SdkSession

A fully-initialized SDK session with convenience methods for creating placement and entitlement controllers, updating user context, and accessing the underlying SDK instance.

This is the recommended entry point for headless (non-React) consumers.

Example

const session = await initRevTurbine({
  tenantId: 'tenant_abc',
  publicKey: 'rtk_…',
  endpoint: 'https://edge.example.com',
  mode: 'snippet',
  user: { id: 'user_123', plan_handle: 'pro' },
});

// Get a placement by slot ID
const banner = session.placement({ surfaceSlot: { id: 'upsell_banner' } });
const decision = await banner.load();

// Check an entitlement with auto-gate
const gate = session.entitlement({ handle: 'brand_kit', autoGate: true });
await gate.check();

// Update user context (works in any runtime mode)
session.identify('user_456', { plan_handle: 'enterprise' });
session.setUserContext({ personalization: { company: 'Acme' } });

Properties

sdk

readonly sdk: RevTurbineCustomerSdk

The underlying SDK instance. Use for advanced/direct operations.

theme

readonly theme: RevTurbineTheme

Resolved theme.

Methods

can()

can(handle, context?): Promise<{ }>

The entitlement check as a can question — alias of checkEntitlement, promoted onto the session facade so session.can('batch_export') works without the session.sdk escape hatch (plan 179 Q-1/Q-3 ruling). Read .allowed for the verdict; an at-cap blocked limit resolves limited + allowed: false.

Parameters

handle

string

context?

RevTurbineEntitlementContext

Returns

Promise<{ }>

checkEntitlement()

checkEntitlement(handle, context?): Promise<{ }>

One-shot entitlement check. For auto-gating or reactive updates, prefer entitlement which returns a full controller.

Parameters

handle

string

context?

RevTurbineEntitlementContext

Returns

Promise<{ }>

entitlement()

entitlement(options): EntitlementGate

Create an EntitlementGate bound to this session’s SDK.

Parameters

options

EntitlementGateOptions

Returns

EntitlementGate

Example

const gate = session.entitlement({ handle: 'brand_kit', autoGate: true });
await gate.check();
if (gate.denied) { showGate(gate.gatedPlacement); }

fetchUserContext()

fetchUserContext(userId): Promise<UserTargetingContext>

Fetch full user context from the server (server runtime mode).

Parameters

userId

string

Returns

Promise<UserTargetingContext>

flushEvents()

flushEvents(): Promise<void>

Flush buffered events immediately. Headless processes are often short-lived (scripts, jobs, edge handlers) — call this before exit so buffered track() events aren’t lost with the process.

Returns

Promise<void>

getPlacement()

getPlacement(config): Promise<{ } | null>

Get a raw placement output by request config (slot, entitlement, plan, or chained). Returns the full PlacementOutput or null.

Parameters

config

RevTurbinePlacementRequestConfig

Returns

Promise<{ } | null>

getPlacementBySlotId()

getPlacementBySlotId(slotId, options?): Promise<RevTurbinePlacementDecision | null>

One-shot: register a surface slot, fetch a decision, and return it.

For repeated use or interaction tracking, prefer placement which returns a full controller.

surfaceTemplateIds limits the slot to those templates. Omitted, the slot accepts the templates the Playbook declares for slotId.

Parameters

slotId

string

options?

Omit<PlacementControllerOptions, "placement" | "surfaceSlot"> & object

Returns

Promise<RevTurbinePlacementDecision | null>

getTrialStatus()

getTrialStatus(): Promise<{ }>

Get the current trial status.

Returns

Promise<{ }>

getUsage()

getUsage(): RevTurbineUsageSnapshot

Get a snapshot of current usage balances.

Returns

RevTurbineUsageSnapshot

getUserContext()

getUserContext(): object

Get the current resolved user context (includes tenant_id, user_id).

Returns

object

identify()

identify(userId, contextOrTraits?): void

Identify a user and optionally set traits/context. Triggers segment re-evaluation and clears decision cache.

Parameters

userId

string

contextOrTraits?

Exact<IdentifyContextInput, IdentifyContextInput>

Returns

void

placement()

placement(options): PlacementController

Create a PlacementController bound to this session’s SDK.

Parameters

options

PlacementControllerOptions

Returns

PlacementController

Example

const banner = session.placement({ surfaceSlot: { id: 'upsell_banner' } });
await banner.load();
if (banner.visible) { renderBanner(banner.content); }

resetIdentity()

resetIdentity(): void

Reset to anonymous user state.

Returns

void

resetUserContext()

resetUserContext(): void

Hard-reset the user context to a blank slate (no anonymous inference) — removes every user-context value plus usage balances and clears the decision cache, interaction state, and impression history. Mostly for demo / fixture flows. See RevTurbineCustomerSdk.resetUserContext.

Returns

void

setUserContext()

setUserContext(context): void

Merge fields into the current user context. Triggers segment re-evaluation.

Parameters

context

RevTurbineUserContext

Returns

void

track()

track(name, data?): Promise<void>

Track an event — the advertised alias of trackEvent, first-class on the session facade so headless code carries the full telemetry surface (plan 179 ruling, Kent 2026-08-13). Powers analytics, frequency caps, attribution, and experiments.

Parameters

name

string

data?

Record<string, JsonValue>

Returns

Promise<void>

trackEvent()

trackEvent(name, data?): Promise<void>

Track a custom event.

Parameters

name

string

data?

Record<string, JsonValue>

Returns

Promise<void>

update()

update(patch): void

Patch the session-scoped user context — the whole-context-minus-id upsert (update({ plan: {...} }), update({ usage: {...} }), …). Alias of the SDK’s update(), promoted onto the session facade so the documented session.update() verb is real (plan 179 Q-1/Q-3 ruling). Unrecognized keys warn (prod-visible, once per session) and drop, exactly as on the SDK — plan 191 Q-5 made the warning prod-visible rather than dev-only, so this comment was stale in the direction that matters.

Parameters

patch

RevTurbineUpdateInput

Returns

void

updateUsage()

updateUsage(balances): void

Update usage balances (e.g. after a meter event).

Parameters

balances

UsageBalances

Returns

void