Server-Side Integration

The SDK supports server-side entitlement checks and placement decisions using the local runtime mode — all logic runs against an Playbook snapshot with no network calls required.

When to Use Server-Side

Use case	Client SDK	Server SDK
Render placements in React	✅	—
Gate API endpoints	—	✅
Enforce usage limits before processing	—	✅
SSR placement decisions	✅ (local mode)	✅
Track server-side events	—	🔜 Coming soon

Local Runtime (Available Now)

The local runtime evaluates entitlements and placements entirely from an Playbook JSON snapshot. No API server connection required.

Installation

pnpm add @revturbine/sdk

Entitlement Checks

import { initRevTurbine, RuntimeMode } from '@revturbine/sdk/headless';
import playbook from './playbook.json';

const sdk = await initRevTurbine({
  runtimeMode: RuntimeMode.LocalOnly,
  localRuntime: { playbook },
  user: {
    id: 'user_123',
    plan_handle: 'starter',
    entitlements: { data_export: false },
  },
});

// Check an entitlement
const result = await sdk.can('data_export');

if (!result.allowed) {
  // deny access — user needs to upgrade
  console.log('Upgrade required:', result.status);
}

Placement Decisions (SSR)

Resolve placements server-side for SSR or email templates:

import { initRevTurbine, RuntimeMode } from '@revturbine/sdk/headless';
import playbook from './playbook.json';

const sdk = await initRevTurbine({
  runtimeMode: RuntimeMode.LocalOnly,
  localRuntime: { playbook },
  user: {
    id: req.user.id,
    plan_handle: req.user.planHandle,
  },
});

// Report current usage (balances live under `usage`; a bare handle is not
// a usage report)
sdk.update({ usage: { api_calls: req.user.apiCallCount } });

// Resolve a specific slot's placement
const banner = await sdk.getPlacement({ slotId: 'dashboard_banner' });

if (banner) {
  // Render banner.content into your template
}

SSR with React (Local Mode)

For frameworks like Next.js, resolve placements with the local runtime and hydrate client-side:

'use client';

import { RevTurbineProvider, Slot, RuntimeMode } from '@revturbine/sdk';
import playbook from './playbook.json';
import { useMemo } from 'react';

export default function Dashboard({ user }) {
  const options = useMemo(() => ({
    runtimeMode: RuntimeMode.LocalOnly,
    localRuntime: { playbook },
    user: {
      id: user.id,
      plan_handle: user.planHandle,
      entitlements: user.entitlements,
    },
  }), [user]);

  return (
    <RevTurbineProvider options={options}>
      <Slot
        id="dashboard_banner"
        surfaceTemplateIds={["banner_placement"]}
      />
      {/* rest of your dashboard */}
    </RevTurbineProvider>
  );
}

RevTurbineServer Provider

Python server SDK

A Python server SDK is also available, with byte-identical decisioning parity to the Node SDK:

Language	Package	Status
Node.js	`@revturbine/sdk/headless` (local runtime)	✅ Available
Python	`revturbine` (PyPI)	✅ Available

See the Python SDK guide for setup and usage.

Next Steps

Entitlements Guide — entitlement types and checking patterns
Runtime Modes — choosing the right runtime mode
Headless API — imperative SDK usage without React