RevTurbineServer

The RevTurbine server-side client. Holds the server key; mints client sessions (RevTurbineServer.createClientSession), writes server-only user state (RevTurbineServer.assignSeatType) and reads the user’s server-resolved built-in dimensions (RevTurbineServer.getBuiltinDimensions).

Accessors

clientSessions

Get Signature

get clientSessions(): object

Client-session minting namespace (plan 157). Ergonomic form of createClientSession:

Example

const { client_token, expires_at } = await server.clientSessions.create({
  subject: session.user.id,
});
// return client_token to the frontend

Returns

object

create

create: (input) => Promise<ClientSessionResult>

Parameters

input

CreateClientSessionInput

Returns

Promise<ClientSessionResult>

Methods

assignSeatType()

assignSeatType(userId, seatTypeHandle, options?): Promise<{ }>

Assign a user’s seat type, or clear it with null (plan 279 TASK-16a).

Calls POST /api/sdk/user-contexts (upsertServerUserContext) with exactly { user_id, seat_type_handle }, authenticated by the server key this client holds. The tenant is taken from that key — it is never a parameter, and no tenant header is sent.

Server-written only (D-36). A user’s seat-type assignment is written only by the tenant’s backend through this server-key call (or by RevTurbine enrichment). It is never set from the browser: the client SDK’s identify() / update() do not accept seat_type_handle, and the endpoint refuses every credential except a server key.

Pass options.builtinDimensions (and options.override) to set built-in dimension values in the same write — see setBuiltinDimensions for their semantics (BL-0382).

Parameters

userId

string

The tenant’s own identifier for the user (non-empty).

seatTypeHandle

string | null

One of the tenant’s current seat-type handles, or null to clear the user’s assignment.

options?

AssignSeatTypeOptions = {}

Optional built-in dimension values to write with the seat.

Returns

Promise<{ }>

The resulting state, including the stored seat_type_handle, the customer-set builtin_dimensions, the pinned overrides and updated_at.

Throws

if the control plane refuses the write — reason is unknown_seat_type for a 422 on the handle, unknown_dimension_value for a 422 on a dimension value, and forbidden for a 403 (the key is not a server key). The error never carries the key.

Example

await server.assignSeatType('user_123', 'admin');
await server.assignSeatType('user_123', null); // clear the assignment

createClientSession()

createClientSession(input): Promise<ClientSessionResult>

Mint a short-lived, opaque per-user client-session token (plan 157; the server key is the minting authority, plan 256).

The customer backend — which holds the server key (passed as RevTurbineServerOptions.apiKey) — calls this to obtain a browser-safe rt_client_ token scoped to one end-user subject, then returns the token to its frontend. The frontend authenticates GET /api/sdk/client-context with it to read the user’s client-safe context.

This is a server-only capability: the browser SDK never mints tokens (it only consumes them). The tenant is derived server-side from the server key, never from this call.

Parameters

input

CreateClientSessionInput

Returns

Promise<ClientSessionResult>

Throws

if the control plane rejects the mint. The error carries only the HTTP status + request id — never the key.

getBuiltinDimensions()

getBuiltinDimensions(userId): Promise<{ }>

Read the control plane’s server-resolved built-in segment dimensions for one user (BL-0366).

Calls GET /api/sdk/user-contexts/{userId}/builtin-dimensions (getServerUserBuiltinDimensions), authenticated by the server key this client holds. The tenant is taken from that key — it is never a parameter, and no tenant header is sent. The result’s builtin_dimensions carries the values the browser SDK would receive through the client context (Subscription State, Trial Type, Activity State, Seat Type, Buyer Role, Billing Health, Email Type); region / device_type are request-derived and never present. An unknown user resolves to each dimension’s default.

Feed it to local evaluation as the server overlay: pass result.builtin_dimensions as createStaticProviders({ …, userContext, serverBuiltinDimensions }), which overlays it per key on userContext.builtin_dimensions — the server value wins (plan 279 PD-3). The Python and Rust server SDKs accept the same object through server_builtin_dimensions.

Parameters

userId

string

The tenant’s own identifier for the user (non-empty) — the same key assignSeatType and createClientSession use.

Returns

Promise<{ }>

{ tenant_id, user_id, builtin_dimensions, resolved_at }.

Throws

if the control plane refuses the read — reason is forbidden for a 403 (the key is not a server key). The error never carries the key.

Example

const { builtin_dimensions } = await server.getBuiltinDimensions('user_123');
const providers = createStaticProviders({
  config: playbook,
  userContext: { id: 'user_123' },
  serverBuiltinDimensions: builtin_dimensions,
});

setBuiltinDimensions()

setBuiltinDimensions(userId, dimensions, options?): Promise<{ }>

Set a user’s built-in segment dimension values from your backend (BL-0382, rulings D-46 / D-47).

Calls POST /api/sdk/user-contexts (upsertServerUserContext) with { user_id, builtin_dimensions, override }, authenticated by the server key this client holds. The tenant is taken from that key — never a parameter. The write is an UPSERT per dimension: dimensions you do not name are left alone, and null clears a dimension (its value and its pin). The seat assignment is untouched (use assignSeatType).

Settable dimensions: subscription_state, trial_type, billing_health, activity_level, buyer_role, email_type, region, device_type — each takes a value from its closed vocabulary (the types enforce it). seat_type is not settable here; it is assignSeatType.

The control plane applies the value before delivery, so both the browser SDK’s client context and getBuiltinDimensions return it:

override: false (default): delivered until a newer RevTurbine enrichment change supersedes it (last writer wins, enrichment included); writing a pinned dimension without the flag unpins it.
override: true: pinned — enrichment never replaces it until you write the dimension again without the flag, or clear it.

Parameters

userId

string

The tenant’s own identifier for the user (non-empty) — the same key assignSeatType and createClientSession use.

dimensions

Dimension → value (or null to clear). Must name at least one dimension.

options?

SetBuiltinDimensionsOptions = {}

{ override } — see above.

Returns

Promise<{ }>

The resulting state: seat_type_handle, every customer-set builtin_dimensions value now stored, the pinned overrides, and updated_at.

Throws

if the control plane refuses the write — reason is unknown_dimension_value for a 422 and forbidden for a 403 (the key is not a server key). The error never carries the key.

Example

// Your billing system knows better than RevTurbine's Stripe view: pin it.
await server.setBuiltinDimensions('user_123', { subscription_state: 'paid' }, { override: true });
// Hand the dimension back to RevTurbine enrichment.
await server.setBuiltinDimensions('user_123', { subscription_state: null });