@revturbine/sdk 0.2.13

package/dist/types/web-sdk/customer-side.d.ts

@@ -0,0 +1,1367 @@
+import { DomainProviderRegistry } from './providers/registry';
+import type { AnyDomainProvider } from './providers/types';
+import type { RevTurbineStorage } from './storage';
+import type { ServerEvaluationPayload as GeneratedServerEvaluationPayload, EntitlementStatus as SchemaEntitlementStatus, ExportedConfig, ExportedConfigSegmentsItem, ContentUiPath, UserContext, UserTrialStatus, TriggerEventType } from '@revt-eng/schema';
+import type { JsonValue, JsonObject, PredicateEvaluationResult } from '@revt-eng/core';
+import { ImpressionHistory } from '@revt-eng/core';
+import { PlacementTypeRegistry } from './placements/registry';
+import { type RecommendationStrategy } from './placements/recommendation';
+import { type LocalPlacementDataset } from './placements/local-resolver';
+export type { JsonValue, JsonObject } from '@revt-eng/core';
+/** Extensible metadata bag attached to placements, events, and interactions. */
+export type SdkMetadata = Record<string, JsonValue>;
+/** User-provided traits or custom context (inherently untyped from customer code). */
+export type SdkTraits = Record<string, JsonValue>;
+/** Properties attached to analytics events. */
+export type SdkEventProperties = Record<string, JsonValue>;
+export interface RevTurbineSdkProvider {
+    getPlacement?: (config: RevTurbinePlacementRequestConfig) => Promise<PlacementOutput | null>;
+    checkEntitlement?: (handle: string, context?: RevTurbineEntitlementContext) => Promise<EntitlementResult>;
+    persistPlacementTypes?: (types: RevTurbinePlacementTypeEntity[]) => Promise<void>;
+    identify?: (userId: string, contextOrTraits?: UserContextInput | SdkTraits) => void;
+}
+export type RevTurbineProviderFactory = (options: RevTurbineInitOptions) => RevTurbineSdkProvider;
+export type RevTurbineProviderFailureSlotBehavior = 'placeholder' | 'invisible';
+interface RevTurbineProviderOptionAugmentations {
+    provider?: RevTurbineSdkProvider | RevTurbineProviderFactory;
+    providerFallbacks?: Array<RevTurbineSdkProvider | RevTurbineProviderFactory>;
+}
+export type RevTurbineInitWithProviderOptions = RevTurbineInitOptions & RevTurbineProviderOptionAugmentations;
+/**
+ * Minimal initialization options for local-only mode.
+ *
+ * When `localRuntime.exportedConfig` is provided, core transport options can be
+ * omitted and the SDK will inject safe local defaults.
+ */
+export type RevTurbineLocalOnlyMinimalInitOptions = Omit<RevTurbineInitOptions, 'tenantId' | 'apiKey' | 'endpoint' | 'mode' | 'runtimeMode' | 'localRuntime'> & {
+    tenantId?: string;
+    apiKey?: string;
+    endpoint?: string;
+    mode?: RevTurbineSdkMode;
+    runtimeMode?: 'local_only';
+    localRuntime: RevTurbineLocalRuntimeOptions & {
+        exportedConfig: ExportedConfig;
+    };
+};
+/**
+ * Public SDK initialization input.
+ *
+ * Accepts either full options for any runtime mode, or local-only minimal
+ * options when `localRuntime.exportedConfig` is provided.
+ */
+export type RevTurbineInitInputOptions = RevTurbineInitWithProviderOptions | (RevTurbineLocalOnlyMinimalInitOptions & RevTurbineProviderOptionAugmentations);
+/**
+ * SDK integration mode.
+ * - `snippet` — lightweight script tag embed
+ * - `react` — React component integration
+ * - `iframe` — sandboxed iframe embed
+ */
+export type RevTurbineSdkMode = 'snippet' | 'react' | 'iframe';
+/**
+ * Canonical surface type for placement rendering.
+ * Re-exported from `@revt-eng/core` — single source of truth.
+ */
+export type { RevTurbineSurfaceType } from '@revt-eng/core';
+import type { RevTurbineSurfaceType } from '@revt-eng/core';
+/**
+ * Convenience input type for identify / setUserContext calls.
+ * Omits the persistence envelope fields (`tenant_id`, `user_id`,
+ * `created_at`, `updated_at`) which the SDK populates automatically.
+ *
+ * @example
+ * ```ts
+ * sdk.identify('user_123', {
+ *   account_id: 'acct_456',
+ *   email: 'jane@acme.com',
+ *   plan: { id: 'pro', name: 'Professional' },
+ *   entitlements: { data_export: true },
+ *   custom: { role: 'editor' },
+ * });
+ * ```
+ */
+export type UserContextInput = Omit<UserContext, 'id' | 'tenant_id' | 'user_id' | 'created_at' | 'updated_at'>;
+/**
+ * A placement output returned by the decision engine.
+ * Re-exported from `@revt-eng/core`.
+ */
+export type { PlacementOutput } from '@revt-eng/core';
+import type { PlacementOutput } from '@revt-eng/core';
+/**
+ * Canonical entitlement check status.
+ * Re-exported from `@revt-eng/schema`.
+ */
+export type EntitlementStatus = SchemaEntitlementStatus;
+/**
+ * Result from an entitlement check.
+ * Re-exported from `@revt-eng/core`.
+ */
+export type { EntitlementResult } from '@revt-eng/core';
+import type { EntitlementResult } from '@revt-eng/core';
+export type { RevTurbineEntitlementContext } from '@revt-eng/core';
+import type { RevTurbineEntitlementContext } from '@revt-eng/core';
+export interface RevTurbinePlacementRequestConfig {
+    /** Slot identifier used for slot-based decisions. */
+    slotId?: string;
+    /** Surface type declared by the slot integration point. */
+    surfaceType?: RevTurbineSurfaceType;
+    /** Entitlement handle used for entitlement-based decisions. */
+    entitlementHandle?: string;
+    /** Optional plan context when rendering plan-specific placements. */
+    planHandle?: string;
+    /** Optional placement handle for chaining from a prior CTA path. */
+    placementHandle?: string;
+    /**
+     * When true, restrict candidate resolution to Fixed-category placements
+     * only for this call. Use when a slot is reserved for PM-wired content
+     * (e.g., a header upgrade button that should never show an RT-initiated
+     * nudge). RT-initiated placements (Usage/Trial/Conversion/Retention) are
+     * filtered out even if they would otherwise match the slot.
+     *
+     * Defaults to `false`. See placement-prioritization-logic spec §1 and
+     * placement-studio-ui.md Appendix C.2 "Restricting a slot to Fixed".
+     */
+    fixedOnly?: boolean;
+}
+/** Tenant-scoped placement type metadata persisted by SDK integrations. */
+export interface RevTurbinePlacementTypeEntity {
+    id: string;
+    label: string;
+    description: string;
+    surfaceType: RevTurbineSurfaceType;
+    priority?: number;
+}
+/**
+ * Current trial status for the identified user.
+ *
+ * Re-exported from the schema's {@link UserTrialStatus} — uses the
+ * canonical snake_case field names (`in_trial`, `trial_type`, etc.)
+ * to match the wire format and avoid brittle remapping.
+ */
+export type RevTurbineTrialContext = UserTrialStatus;
+/**
+ * Arbitrary key/value metadata persisted with an impression record.
+ *
+ * Free-form by design — consumers attach whatever context is useful
+ * for downstream analytics (CTA type, variant id, surface slot id,
+ * experiment arm, etc.). The shape is intentionally untyped because
+ * it's a passthrough into the scaffold's ImpressionRecord.metadata
+ * field, which is the same type (`Record<string, unknown>`) on the
+ * persistence side. Defining the alias here gives the SDK type-
+ * safety scan one place to suppress instead of three identical
+ * parameter sites.
+ */
+export type RevTurbineImpressionMetadata = Record<string, unknown>;
+/** Map of entitlement handle → current usage count. */
+export type UsageBalances = Record<string, number>;
+/**
+ * Outcome of {@link RevTurbineCustomerSdk.gate} — the advertised `gate(action, fn)`
+ * verb. When the action was permitted, `ran` is `true` and `result` holds the
+ * callback's return value; otherwise `ran` is `false`, the callback did not run,
+ * and the caller should surface the `entitlement` (e.g. render an `<RTSlot>` paywall).
+ */
+export type RevTurbineGateResult<T> = {
+    ran: true;
+    result: T;
+    entitlement: EntitlementResult;
+} | {
+    ran: false;
+    entitlement: EntitlementResult;
+};
+/**
+ * Input to {@link RevTurbineCustomerSdk.update} — the advertised `update({ usage })`
+ * verb. Patches customer-reported usage balances; for identity or full user-context
+ * changes use {@link RevTurbineCustomerSdk.identify} / {@link RevTurbineCustomerSdk.setUserContext}.
+ */
+export interface RevTurbineUpdateInput {
+    /** Usage balances to merge into the current snapshot (absolute values). */
+    usage?: UsageBalances;
+}
+/** Usage snapshot entry for a usage unit. */
+export interface RevTurbineUsageSnapshotEntry {
+    /** Current consumed amount for the usage unit. */
+    current: number;
+    /** Configured limit for the usage unit when available. */
+    limit?: number;
+}
+/** Map of usage unit -> usage snapshot. */
+export type RevTurbineUsageSnapshot = Record<string, RevTurbineUsageSnapshotEntry>;
+/** Snapshot of policy-related SDK runtime settings and loaded config metadata. */
+export interface RevTurbinePolicySnapshot {
+    contextPolicy: Required<RevTurbineContextPolicy>;
+    placementBehavior: RevTurbinePlacementBehaviorFlags;
+    runtimeMode: RevTurbineRuntimeMode;
+    exportedConfigVersion?: string;
+}
+export type RevTurbinePersonalizationTokens = Record<string, string | number>;
+/**
+ * Snapshot of the active targeting context used by placement eligibility.
+ */
+export interface RevTurbineTargeting extends UserTargetingContext {
+    /** Segment definitions configured in the active ExportedConfig. */
+    configuredSegments: ExportedConfigSegmentsItem[];
+    /** Predicate fields discovered from configured segments (targeting dimensions). */
+    configuredTraitFields: string[];
+}
+/**
+ * Payload shape accepted by {@link RevTurbineCustomerSdk.hydrate}.
+ *
+ * This is a re-export of the generated `ServerEvaluationPayload` from the
+ * schema, which is the contract between the server-side SDK's `evaluate()`
+ * output and the client-side SDK's hydration input.
+ */
+export type ServerEvaluationHydrationPayload = GeneratedServerEvaluationPayload;
+/**
+ * SDK-local user context state.
+ *
+ * Extends the canonical {@link UserContextInput} with a local `id` field
+ * for user identification. The full persistence-ready {@link UserContext}
+ * (with `tenant_id`, `user_id`, timestamps) is built by the SDK via
+ * {@link RevTurbineCustomerSdk.getUserContext getUserContext()}.
+ *
+ * `custom` is widened to `Record<string, unknown>` at the SDK boundary
+ * for customer convenience; values are narrowed to `TraitValue` when
+ * persisted via the API.
+ */
+export interface RevTurbineUserContext extends Omit<UserContextInput, 'custom' | 'entitlements' | 'usage' | 'personalization' | 'derived_computed_at' | 'context_hash'> {
+    /** Authenticated user identifier. When undefined, the SDK uses an anonymous ID. */
+    id?: string;
+    /**
+     * Server-computed derived-entitlement cache stamp (plan 74). Optional at the
+     * SDK input boundary — local mode does not compute it; the control plane
+     * populates and round-trips it, defaulting to `null` when absent.
+     */
+    derived_computed_at?: UserContextInput['derived_computed_at'];
+    /**
+     * Server-computed user-context hash (plan 74). Optional at the SDK input
+     * boundary for the same reason as `derived_computed_at`.
+     */
+    context_hash?: UserContextInput['context_hash'];
+    /** Customer-defined fields for segmentation and personalization. */
+    custom?: SdkTraits;
+    /** Feature entitlements granted by plan + entitlement rules. */
+    entitlements?: Record<string, boolean>;
+    /** Usage entries derived from credits / usage_limit entitlements, keyed by handle. */
+    usage?: UserContextInput['usage'];
+    /**
+     * Transient personalization token map.
+     *
+     * Holds SDK-derived tokens (plan_name, usage_current, etc.) merged with
+     * app-provided tokens.  Not persisted — rebuilt on each SDK session.
+     * Widened to accept `unknown` at the SDK boundary; narrowed to
+     * `string | number` when serialized.
+     */
+    personalization?: SdkTraits;
+}
+/** Page-level context automatically inferred or manually set. */
+export interface RevTurbinePageContext {
+    /** Fully qualified page URL. */
+    url?: string;
+    /** Document title. */
+    title?: string;
+    /** HTTP referrer. */
+    referrer?: string;
+    /** Semantic tags for page classification (e.g. `['pricing', 'upgrade']`). */
+    tags?: string[];
+}
+/**
+ * Controls automatic context inference behavior.
+ * All flags default to `true` when omitted.
+ */
+export interface RevTurbineContextPolicy {
+    /** Infer anonymous user context from browser APIs. */
+    inferUser?: boolean;
+    /** Infer page context (URL, title, referrer) from `window.location`. */
+    inferPage?: boolean;
+    /** Automatically track SPA route changes via History API patching. */
+    routerAutoTrack?: boolean;
+}
+/**
+ * Feature flags for placement pipeline behavior that may alter decision semantics.
+ *
+ * All flags default to `false` to preserve backward compatibility.
+ */
+export interface RevTurbinePlacementBehaviorFlags {
+    /** Enable client-side payload cap enforcement (max-per-period + cooldown precedence). */
+    enableClientCapsEnforcement: boolean;
+    /** Enable automatic gated placement rendering helpers on entitlement denial. */
+    enableAutoGatedPlacement: boolean;
+    /** Enable automatic trial lifecycle trigger derivation in local-only mode. */
+    enableTrialAutoTriggers: boolean;
+}
+/** Resolver function for a UI path action type. */
+export type RevTurbineUiPathResolver = (uiPath: JsonObject) => void | Promise<void>;
+/** Map of `action_type` -> resolver implementation supplied by the customer app. */
+export type RevTurbineUiPathResolverMap = Record<string, NonNullable<RevTurbineUiPathResolver>>;
+/** Extracts `action_type` string literals from a UI path array type. */
+export type RevTurbineUiPathActionTypes<TUiPaths extends readonly unknown[]> = Extract<{
+    [Index in keyof TUiPaths]: TUiPaths[Index] extends {
+        action_type: infer ActionType;
+    } ? ActionType : never;
+}[number], string>;
+/** Resolver map that requires handlers for every `action_type` present in `TUiPaths`. */
+export type RevTurbineRequiredUiPathResolvers<TUiPaths extends readonly unknown[]> = {
+    [ActionType in RevTurbineUiPathActionTypes<TUiPaths>]: RevTurbineUiPathResolver;
+};
+/**
+ * Compile-time helper for authoring complete UI-path resolver maps.
+ *
+ * When `uiPaths` is provided as a `const` array, TypeScript enforces that
+ * `resolvers` contains every `action_type` key.
+ */
+export declare function defineUiPathResolvers<const TUiPaths extends readonly unknown[]>(uiPaths: TUiPaths, resolvers: RevTurbineRequiredUiPathResolvers<TUiPaths> & RevTurbineUiPathResolverMap): RevTurbineUiPathResolverMap;
+export interface RevTurbineUiPathResolverValidationIssue {
+    uiPathId?: string;
+    name?: string;
+    actionType: string;
+    reason: 'missing_resolver' | 'missing_action_type';
+}
+export interface RevTurbineUiPathResolverValidationReport {
+    valid: boolean;
+    totalUiPaths: number;
+    resolvedUiPaths: number;
+    issues: RevTurbineUiPathResolverValidationIssue[];
+}
+export interface RevTurbineUiPathResolverValidationOptions {
+    /** Optional explicit UI path definitions to validate. Defaults to exportedConfig.content_ui_paths. */
+    uiPaths?: ContentUiPath[];
+    /** Additional action resolver map to validate against for this invocation. */
+    resolvers?: RevTurbineUiPathResolverMap;
+    /** Include CTA handler provider resolvers from domain providers. Default true. */
+    includeProviderHandlers?: boolean;
+    /** Throw when missing resolver coverage is detected. Default false. */
+    throwOnMissing?: boolean;
+}
+/**
+ * Provider abstraction for ExportedConfig access inside the SDK.
+ *
+ * Local mode typically uses a static provider backed by `localRuntime.exportedConfig`.
+ * Other modes can provide custom or REST-backed resolvers via `refresh()`.
+ */
+export interface RevTurbineConfigProvider {
+    /** Return the latest available ExportedConfig snapshot. */
+    getExportedConfig(): ExportedConfig | undefined;
+    /** Optionally refresh the snapshot (for example, from a REST API). */
+    refresh?(): Promise<ExportedConfig | undefined>;
+}
+/**
+ * Options for initializing the RevTurbine SDK.
+ *
+ * @example
+ * ```ts
+ * import { initRevTurbine } from '@revt-eng/sdk';
+ *
+ * const sdk = initRevTurbine({
+ *   tenantId: 'tenant_abc',
+ *   apiKey: 'rt_live_xxx',
+ *   endpoint: 'https://api.revturbine.io',
+ *   mode: 'react',
+ * });
+ * ```
+ */
+export interface RevTurbineInitOptions {
+    /** Your RevTurbine tenant identifier. */
+    tenantId: string;
+    /** API key for authentication. */
+    apiKey: string;
+    /**
+     * Public ingest key for SDK clickstream ingestion (`POST /api/track`).
+     *
+     * Mint one in your RevTurbine tenant under **Settings → Ingest keys**.
+     * This is a tenant-scoped, embeddable `public` token distinct from
+     * {@link apiKey}: it authorizes *only* event ingestion (the
+     * `ingest:write` scope) and carries no role authority, so it is safe
+     * to ship in client bundles. When omitted, the SDK falls back to
+     * {@link apiKey} for the ingest request — but `/api/track` accepts
+     * **only** a `public` token, so a non-public `apiKey` fallback will be
+     * rejected. Set this for any integration that emits events.
+     */
+    ingestPublicKey?: string;
+    /**
+     * Environment identifier stamped on every ingested clickstream event
+     * (`TrackEvent.environment_id`, e.g. `'prod'` / `'staging'`). Lets a
+     * tenant separate analytics by deployment environment. Defaults to
+     * `'default'` when omitted.
+     */
+    environmentId?: string;
+    /** Base URL of the RevTurbine API Edge. */
+    endpoint: string;
+    /** SDK integration mode. */
+    mode: RevTurbineSdkMode;
+    /**
+     * SDK deployment/runtime mode:
+     * - `revturbine_server` (default): standard RevTurbine-hosted endpoints.
+     * - `custom_endpoints`: customer-provided endpoint replacements.
+     * - `local_only`: no server calls, runtime data initialized locally.
+     */
+    runtimeMode?: RevTurbineRuntimeMode;
+    /** Optional endpoint overrides used in `custom_endpoints` mode. */
+    endpointOverrides?: Partial<RevTurbineEndpointOverrides>;
+    /** Optional provider for ExportedConfig-backed data (plans, segments, rules, ui paths). */
+    configProvider?: RevTurbineConfigProvider;
+    /** Local-only runtime configuration used in `local_only` mode. */
+    localRuntime?: RevTurbineLocalRuntimeOptions;
+    /**
+     * Slot behavior after provider-chain failure disables the SDK.
+     * - `invisible` (default): slots return hidden decisions.
+     * - `placeholder`: slots return visible placeholder content.
+     */
+    providerFailureSlotBehavior?: RevTurbineProviderFailureSlotBehavior;
+    /** Typed domain providers (plan, entitlements, segments, content, rules, traits). */
+    domainProviders?: AnyDomainProvider[];
+    /** Optional UI path resolver map used by `validateUiPathResolvers()`. */
+    uiPathResolvers?: RevTurbineUiPathResolverMap;
+    user?: RevTurbineUserContext;
+    page?: RevTurbinePageContext;
+    contextPolicy?: RevTurbineContextPolicy;
+    /**
+     * Opt-in flags for placement decision behavior changes.
+     *
+     * Defaults are conservative (`false`) so existing integrations do not change behavior
+     * until explicitly enabled.
+     */
+    placementBehavior?: Partial<RevTurbinePlacementBehaviorFlags>;
+    extension?: {
+        enabled?: boolean;
+    };
+    /**
+     * Persistent storage provider (survives page reloads).
+     * Browser default: `localStorage`. Server default: in-memory.
+     * Override with a Redis/cookie/DB-backed implementation for SSR persistence.
+     */
+    persistentStorage?: RevTurbineStorage;
+    /**
+     * Session-scoped storage provider (cleared when the tab/session ends).
+     * Browser default: `sessionStorage`. Server default: in-memory.
+     */
+    sessionStorage?: RevTurbineStorage;
+}
+/** Base init options shared by all runtime mode helper builders. */
+export type RevTurbineInitBaseOptions = Omit<RevTurbineInitOptions, 'runtimeMode' | 'endpointOverrides' | 'localRuntime'>;
+export type RevTurbineRuntimeMode = 'revturbine_server' | 'custom_endpoints' | 'local_only';
+/**
+ * Per-operation endpoint path/URL overrides for `custom_endpoints` mode.
+ * Each key maps to a fully-qualified URL or an `endpoint`-relative path.
+ */
+export interface RevTurbineEndpointOverrides {
+    decideContext: string;
+    bootstrapContext: string;
+    decide: string;
+    getPlacement: string;
+    checkEntitlement: string;
+    userContext: string;
+    trialStatus: string;
+    ingestEvents: string;
+    touchpointTransition: string;
+    legacyInteractions: string;
+    placementTypes: string;
+    surfaceSlots: string;
+}
+export interface RevTurbineLocalRuntimeData {
+    placementDecisionsByPlacementId?: Record<string, RevTurbinePlacementDecision>;
+    placementsByLookupKey?: Record<string, PlacementOutput | null>;
+    entitlementByHandle?: Record<string, EntitlementResult>;
+    userContextByUserId?: Record<string, UserTargetingContext>;
+    trialStatus?: RevTurbineTrialContext;
+}
+export interface RevTurbineLocalRuntimeResolvers {
+    getPlacementDecision?: (input: RevTurbinePlacementDecisionInput, placement?: RevTurbinePlacementRecord, context?: JsonObject) => RevTurbinePlacementDecision | Promise<RevTurbinePlacementDecision>;
+    getPlacement?: (config: RevTurbinePlacementRequestConfig) => PlacementOutput | null | Promise<PlacementOutput | null>;
+    checkEntitlement?: (handle: string, context?: RevTurbineEntitlementContext) => EntitlementResult | Promise<EntitlementResult>;
+    fetchUserContext?: (userId: string) => UserTargetingContext | Promise<UserTargetingContext>;
+    getTrialStatus?: () => RevTurbineTrialContext | Promise<RevTurbineTrialContext>;
+    /** Optional ExportedConfig resolver for provider-backed config access in any mode. */
+    resolveExportedConfig?: () => ExportedConfig | Promise<ExportedConfig>;
+}
+export interface RevTurbineLocalRuntimeOptions {
+    /**
+     * Full ExportedConfig snapshot loaded at initialization for local-only execution.
+     * Contains plans, entitlements, entitlement rules, segments, ui paths,
+     * surface templates, trial, and theme. Providers and resolvers can read
+     * this to hydrate domain state without a server.
+     */
+    exportedConfig?: ExportedConfig;
+    /** Optional static placements dataset used by the SDK's built-in local resolver. */
+    placements?: LocalPlacementDataset;
+    /**
+     * Arbitrary configuration/context/content passed at initialization for local-only execution.
+     * This is persisted under localStorage and used as runtime source-of-truth.
+     */
+    initialData?: RevTurbineLocalRuntimeData;
+    /** Optional resolver callbacks for advanced local decisioning behavior. */
+    resolvers?: RevTurbineLocalRuntimeResolvers;
+    /** Optional explicit storage key for persisted local-only runtime state. */
+    storageKey?: string;
+    /**
+     * Reactive context callback. When provided, the SDK calls this before every
+     * local decision request and passes the result as the third argument to
+     * `resolvers.getPlacementDecision`.
+     *
+     * This allows local resolvers to react to user context changes (plan state,
+     * trial day, usage counters) without rebuilding the provider.
+     */
+    getContext?: () => JsonObject | Promise<JsonObject>;
+}
+type RevTurbineBaseInitWithoutRuntimeSpecifics = Omit<RevTurbineInitOptions, 'runtimeMode' | 'localRuntime' | 'uiPathResolvers'>;
+/**
+ * Strict initialization mode for compile-time safety:
+ * when using `local_only` runtime with `localRuntime.exportedConfig`,
+ * `uiPathResolvers` is required.
+ */
+export type RevTurbineInitOptionsStrict = (RevTurbineBaseInitWithoutRuntimeSpecifics & {
+    runtimeMode: 'local_only';
+    localRuntime: RevTurbineLocalRuntimeOptions & {
+        exportedConfig: ExportedConfig;
+    };
+    uiPathResolvers: RevTurbineUiPathResolverMap;
+}) | (RevTurbineBaseInitWithoutRuntimeSpecifics & {
+    runtimeMode: 'local_only';
+    localRuntime: RevTurbineLocalRuntimeOptions & {
+        exportedConfig?: undefined;
+    };
+    uiPathResolvers?: RevTurbineUiPathResolverMap;
+}) | (RevTurbineBaseInitWithoutRuntimeSpecifics & {
+    runtimeMode?: Exclude<RevTurbineRuntimeMode, 'local_only'>;
+    localRuntime?: RevTurbineLocalRuntimeOptions;
+    uiPathResolvers?: RevTurbineUiPathResolverMap;
+});
+/**
+ * Build a server-backed SDK config (default runtime mode).
+ */
+export declare function createServerRuntimeConfig(options: RevTurbineInitBaseOptions): RevTurbineInitOptions;
+/**
+ * Build a custom-endpoint SDK config.
+ */
+export declare function createCustomEndpointRuntimeConfig(options: RevTurbineInitBaseOptions & {
+    endpointOverrides: Partial<RevTurbineEndpointOverrides>;
+}): RevTurbineInitOptions;
+/**
+ * Build a local-only SDK config.
+ */
+export declare function createLocalRuntimeConfig<const TUiPaths extends readonly unknown[]>(options: RevTurbineInitBaseOptions & {
+    localRuntime: RevTurbineLocalRuntimeOptions & {
+        exportedConfig: Omit<ExportedConfig, 'content_ui_paths'> & {
+            content_ui_paths: TUiPaths;
+        };
+    };
+    uiPathResolvers: RevTurbineRequiredUiPathResolvers<TUiPaths> & RevTurbineUiPathResolverMap;
+}): RevTurbineInitOptions;
+export declare function createLocalRuntimeConfig(options: RevTurbineInitBaseOptions & {
+    localRuntime: RevTurbineLocalRuntimeOptions;
+    uiPathResolvers?: RevTurbineUiPathResolverMap;
+}): RevTurbineInitOptions;
+/**
+ * Build a strict local-only SDK config.
+ *
+ * Unlike {@link createLocalRuntimeConfig}, this helper always requires
+ * `exportedConfig.content_ui_paths` and complete `uiPathResolvers` coverage at
+ * compile time for action types present in that exported config.
+ */
+export declare function createStrictLocalRuntimeConfig<const TUiPaths extends readonly unknown[]>(options: RevTurbineInitBaseOptions & {
+    localRuntime: RevTurbineLocalRuntimeOptions & {
+        exportedConfig: Omit<ExportedConfig, 'content_ui_paths'> & {
+            content_ui_paths: TUiPaths;
+        };
+    };
+    uiPathResolvers: RevTurbineRequiredUiPathResolvers<TUiPaths> & RevTurbineUiPathResolverMap;
+}): RevTurbineInitOptions;
+/** Optional context for slot-based placement requests. */
+export interface RevTurbineSlotPlacementRequestOptions {
+    entitlementHandle?: string;
+    planHandle?: string;
+    placementHandle?: string;
+}
+/** Optional context for entitlement-based placement requests. */
+export interface RevTurbineEntitlementPlacementRequestOptions {
+    slotId?: string;
+    surfaceType?: RevTurbineSurfaceType;
+    planHandle?: string;
+    placementHandle?: string;
+}
+/** Optional context for chained placement requests. */
+export interface RevTurbineChainedPlacementRequestOptions {
+    slotId?: string;
+    surfaceType?: RevTurbineSurfaceType;
+    entitlementHandle?: string;
+    planHandle?: string;
+}
+/**
+ * Create a typed placement request for slot + surface lookups.
+ */
+export declare function createSlotPlacementRequest(slotId: string, surfaceType: RevTurbineSurfaceType, options?: RevTurbineSlotPlacementRequestOptions): RevTurbinePlacementRequestConfig;
+/**
+ * Create a typed placement request for entitlement-gated lookups.
+ */
+export declare function createEntitlementPlacementRequest(entitlementHandle: string, options?: RevTurbineEntitlementPlacementRequestOptions): RevTurbinePlacementRequestConfig;
+/**
+ * Create a typed placement request for chained/CTA follow-up lookups.
+ */
+export declare function createChainedPlacementRequest(placementHandle: string, options?: RevTurbineChainedPlacementRequestOptions): RevTurbinePlacementRequestConfig;
+/**
+ * Configuration for registering a placement slot.
+ * The combination of name + route + scope key produces a deterministic placement ID.
+ *
+ * @deprecated Use `RevTurbineSurfaceSlotConfig`.
+ */
+export interface RevTurbinePlacementConfig {
+    /** Human-readable placement name (e.g. `'pricing_banner'`). */
+    name: string;
+    /** Optional scope key to differentiate placements on the same route. */
+    placementScopeKey?: string;
+    /** Arbitrary metadata attached to the placement for analytics. */
+    metadata?: SdkMetadata;
+}
+/**
+ * Canonical configuration for a renderable surface slot.
+ *
+ * `id` must be unique within the customer app integration.
+ */
+export interface RevTurbineSurfaceSlotConfig {
+    /** Required unique identifier for the surface slot. */
+    id: string;
+    /** Optional human-readable label used for analytics and debugging. */
+    name?: string;
+    /**
+     * Surface template IDs that this slot accepts.
+     *
+     * When provided, only placements whose surface template matches one of
+     * these IDs are eligible to render in this slot. This acts as a filter
+     * at decision time — both the local resolver and the remote
+     * decide-context endpoint use this constraint.
+     */
+    surfaceTemplateIds?: string[];
+    /** Arbitrary metadata attached to the slot for analytics and traceability. */
+    metadata?: SdkMetadata;
+}
+export type { RevTurbinePlacementRecord } from '@revt-eng/core';
+import type { RevTurbinePlacementRecord } from '@revt-eng/core';
+export interface RevTurbinePlacementContent {
+    placementId: string;
+    requestId: string;
+    decisionSource: 'remote' | 'fallback';
+    content: RevTurbineDecisionContent;
+}
+/**
+ * Simplified content fields carried on placement decisions.
+ * Re-exported from `@revt-eng/core`.
+ */
+export type { RevTurbineDecisionContent } from '@revt-eng/core';
+import type { RevTurbineDecisionContent } from '@revt-eng/core';
+export type { RevTurbineContextMode } from '@revt-eng/core';
+import type { RevTurbineContextMode } from '@revt-eng/core';
+export type { RevTurbineMeterUsageOverride } from '@revt-eng/core';
+export type { RevTurbinePlacementDecisionOverrides } from '@revt-eng/core';
+import type { RevTurbinePlacementDecisionOverrides } from '@revt-eng/core';
+/**
+ * Input for requesting a placement decision.
+ * Re-exported from `@revt-eng/core`.
+ */
+export type { RevTurbinePlacementDecisionInput } from '@revt-eng/core';
+import type { RevTurbinePlacementDecisionInput } from '@revt-eng/core';
+export interface RevTurbineBootstrapDecisionInput {
+    userId: string;
+    contextMode?: RevTurbineContextMode;
+    overrides?: RevTurbinePlacementDecisionOverrides;
+    traits?: Record<string, string | number | boolean>;
+    ttlMs?: number;
+    placementIds: string[];
+}
+/**
+ * A placement decision returned by the decision engine.
+ * Re-exported from `@revt-eng/core`.
+ */
+export type { RevTurbinePlacementDecision } from '@revt-eng/core';
+import type { RevTurbinePlacementDecision } from '@revt-eng/core';
+/** Predicate-level evaluation detail for segment matching diagnostics. */
+export type RevTurbineSegmentPredicateEvaluation = PredicateEvaluationResult;
+/** Segment-level evaluation detail for placement diagnostics. */
+export interface RevTurbineSegmentEvaluation {
+    segmentId: string;
+    segmentName?: string;
+    matched: boolean;
+    predicates: RevTurbineSegmentPredicateEvaluation[];
+}
+/** Entitlement-rule evaluation detail for placement diagnostics. */
+export interface RevTurbineEntitlementRuleEvaluation {
+    ruleId: string;
+    entitlementId?: string;
+    entitlementHandle?: string;
+    kind?: string;
+    /** Human-readable plan scopes resolved from `planIds` (e.g. `starter`, `professional`). */
+    planScopes: string[];
+    planIds: string[];
+    /**
+     * Segment IDs the rule is scoped to. Empty array means "matches all users".
+     * Evaluated with intra-dimension OR + cross-dimension AND per spec §2.5
+     * (plan #39 REQ-8).
+     */
+    segmentIds?: string[];
+    matchesPlan: boolean;
+    matchesSegment: boolean;
+    matched: boolean;
+    outcome: EntitlementStatus | 'unknown';
+    /** Human-readable description of what this rule grants (e.g. "grants access", "sets limit to 5,000 calls / month"). */
+    outcomeDescription?: string;
+    reason?: string;
+}
+/** Placement rule signals extracted from the selected placement output. */
+export interface RevTurbinePlacementRuleEvaluation {
+    ruleId?: string;
+    decisionId?: string;
+    category?: string;
+    suppressionReason?: string;
+    reasonCodes: string[];
+    capPolicies: Array<{
+        count: number;
+        period: 'session' | 'day' | 'week' | 'month' | 'lifetime';
+        cooldownMs?: number;
+    }>;
+}
+/** Placement payload eligibility detail for explainability UI. */
+export interface RevTurbinePlacementPayloadEvaluation {
+    payloadId: string;
+    placementId: string;
+    placementName: string;
+    status: 'draft' | 'active' | 'disabled';
+    planIds: string[];
+    planScopes: string[];
+    segmentChips: string[];
+    surfaceTemplateIds: string[];
+    matchesPlan: boolean;
+    matchesSegment: boolean;
+    eligible: boolean;
+    selected: boolean;
+}
+/** Structured explanation object for placement decision visualization. */
+export interface RevTurbinePlacementDecisionExplanation {
+    generatedAt: string;
+    input: RevTurbinePlacementDecisionInput;
+    decision: RevTurbinePlacementDecision;
+    targeting: RevTurbineTargeting;
+    policy: RevTurbinePolicySnapshot;
+    entitlements: Record<string, EntitlementResult>;
+    segments: RevTurbineSegmentEvaluation[];
+    entitlementRules: RevTurbineEntitlementRuleEvaluation[];
+    eligiblePayloads: RevTurbinePlacementPayloadEvaluation[];
+    placementRules: RevTurbinePlacementRuleEvaluation;
+}
+/**
+ * Types of user interactions with a placement treatment.
+ * Re-exported from `@revt-eng/core`.
+ */
+export type { RevTurbineTreatmentInteractionType } from '@revt-eng/core';
+import type { RevTurbineTreatmentInteractionType } from '@revt-eng/core';
+export type { RevTurbineTreatmentInteractionInput } from '@revt-eng/core';
+import type { RevTurbineTreatmentInteractionInput } from '@revt-eng/core';
+/**
+ * Optional fields for constructing typed interaction payloads.
+ */
+export interface RevTurbineTreatmentInteractionOptions {
+    treatmentId?: string;
+    interactionAt?: string;
+    metadata?: SdkMetadata;
+}
+/**
+ * Create a typed treatment interaction payload.
+ */
+export declare function createTreatmentInteraction(userId: string, placementId: string, interactionType: RevTurbineTreatmentInteractionType, options?: RevTurbineTreatmentInteractionOptions): RevTurbineTreatmentInteractionInput;
+export interface RevTurbineEventOptions {
+    immediate?: boolean;
+}
+/**
+ * User targeting context for payload eligibility.
+ * Re-exported from `@revt-eng/core`.
+ */
+export type { UserTargetingContext } from '@revt-eng/core';
+import type { UserTargetingContext } from '@revt-eng/core';
+/** A named semantic event with structured payload. */
+export interface RevTurbineSemanticEvent {
+    /** Event type name (e.g. `'checkout_started'`). */
+    eventType: string;
+    /** Structured event payload. */
+    payload: SdkEventProperties;
+    /** Delivery options. */
+    options?: RevTurbineEventOptions;
+}
+/**
+ * Canonical trigger event names recognised by the SDK and decision engine.
+ *
+ * These correspond to the placement categories defined in the product requirements
+ * (trial lifecycle, usage/limits, feature gating, retention, expansion).
+ */
+export type RevTurbineTriggerEvent = TriggerEventType;
+/** Payload for trial-related trigger events. */
+export interface TrialTriggerPayload {
+    days_remaining?: number;
+}
+/** Payload for usage/limit trigger events. */
+export interface UsageTriggerPayload {
+    /** The entitlement handle this usage event refers to. */
+    entitlement_handle?: string;
+    /** Current usage count for the entitlement. */
+    current_usage?: number;
+    /** Usage limit configured for the entitlement on the active plan. */
+    usage_limit?: number;
+    usage_percent?: number;
+    threshold?: number;
+    balance?: number;
+    allocation?: number;
+    seats_used?: number;
+    seats_allowed?: number;
+}
+/** Payload for feature-gate trigger events. */
+export interface FeatureGateTriggerPayload {
+    feature: string;
+}
+/** Payload for payment-related trigger events. */
+export interface PaymentTriggerPayload {
+    retry_count?: number;
+    renewal_date?: string;
+}
+/** Union of all typed trigger payloads. */
+export type RevTurbineTriggerPayload = TrialTriggerPayload | UsageTriggerPayload | FeatureGateTriggerPayload | PaymentTriggerPayload | SdkEventProperties;
+/**
+ * Create a typed semantic event payload.
+ */
+export declare function createSemanticEvent(eventType: string, payload: SdkEventProperties, options?: RevTurbineEventOptions): RevTurbineSemanticEvent;
+export type { RevTurbineEventEnvelope } from '@revt-eng/core';
+/**
+ * The core RevTurbine customer-facing SDK.
+ *
+ * Provides methods for:
+ * - **Identity** — `identify()`, `resetIdentity()`
+ * - **Placements** — `registerPlacement()`, `getPlacementDecision()`, `getPlacement()`
+ * - **Entitlements** — `checkEntitlement()`, `updateUsage()`
+ * - **Trials** — `getTrialStatus()`
+ * - **Events** — `capture()`, `trackEvent()`, `emitSemantic()`
+ * - **Interactions** — `trackTreatmentInteraction()`, `dismiss()`, `convert()`
+ * - **Context** — `setUserContext()`, `setPageContext()`, `refreshPageContext()`
+ *
+ * @example
+ * ```ts
+ * const sdk = initRevTurbine({
+ *   tenantId: 'tenant_abc',
+ *   apiKey: 'rt_live_xxx',
+ *   endpoint: 'https://api.revturbine.io',
+ *   mode: 'react',
+ * });
+ *
+ * sdk.identify('user_123', { plan: 'pro' });
+ * const decision = await sdk.getPlacementDecision({ placementId, userId: 'user_123' });
+ * ```
+ */
+export declare class RevTurbineCustomerSdk {
+    private readonly tenantId;
+    private readonly apiKey;
+    private readonly ingestPublicKey?;
+    private readonly environmentId;
+    private readonly endpoint;
+    private readonly runtimeMode;
+    private readonly endpointOverrides;
+    private readonly localRuntime?;
+    private readonly localStorageKey;
+    private readonly mode;
+    private readonly policy;
+    private readonly extensionEnabled;
+    private readonly placementBehavior;
+    private readonly providerFailureSlotBehavior;
+    private readonly uiPathResolvers;
+    private readonly persistentStore;
+    private readonly sessionStore;
+    private readonly anonymousId;
+    private readonly sessionId;
+    private readonly decisionCache;
+    private readonly interactionState;
+    private readonly interactionQueue;
+    private readonly defaultDecisionTtlMs;
+    private readonly defaultDismissCooldownMs;
+    private readonly defaultRemindLaterMs;
+    private readonly defaultUsageWarningPercent;
+    private readonly defaultTrialExpiringDays;
+    private readonly events;
+    private readonly placements;
+    private readonly syncedSurfaceSlotIds;
+    private userContext;
+    private pageContext;
+    private usageBalances;
+    private localDecisionsByPlacementId;
+    private localPlacementsByLookupKey;
+    private localEntitlementsByHandle;
+    private localUserContextsByUserId;
+    private localTrialStatus;
+    private readonly presentationCapsByKey;
+    private readonly usageLimitByEntitlement;
+    private readonly usageTokenPrefixByEntitlement;
+    private readonly segmentIdsByPredicateField;
+    private readonly configuredSegmentsById;
+    private readonly dirtySegmentIds;
+    private readonly segmentMembershipBySegmentId;
+    private segmentMembershipUserId?;
+    private lastTrialTriggerStage;
+    private readonly configProvider?;
+    private readonly defaultLocalPlacementDecisionResolver?;
+    private sdkDisabledByProviderFailure;
+    private sdkDisabledReason?;
+    readonly providerRegistry: DomainProviderRegistry;
+    readonly placementTypeRegistry: PlacementTypeRegistry;
+    readonly impressionHistory: ImpressionHistory;
+    constructor(options: RevTurbineInitOptions);
+    private isLocalOnlyMode;
+    private resolveConfigProvider;
+    private refreshExportedConfigSnapshot;
+    private getConfiguredExportedConfig;
+    private rebuildSegmentPredicateFieldIndex;
+    private buildDefaultLocalPlacementDecisionResolver;
+    /**
+     * Build a minimal provider context from the SDK's user state when no
+     * explicit domain providers are registered.  This allows the local
+     * placement resolver to access plan and usage data for token
+     * interpolation (e.g. `{{usage_remaining}}`).
+     */
+    private synthesizeProviderContext;
+    private markAllSegmentsDirty;
+    private markSegmentsDirtyForFields;
+    private toSegmentEvaluationTraits;
+    private buildTargetingState;
+    private markSegmentsDirtyFromContextChange;
+    /** Resolve current pathname from page context or window.location (server-safe). */
+    private currentPathname;
+    disableForProviderFailure(reason: string): void;
+    private isDisabledByProviderFailure;
+    private disabledDecisionForPlacement;
+    private disabledPlacementOutputForConfig;
+    private endpointFor;
+    private localPlacementLookupKey;
+    private localLookupMatchesConfig;
+    private localOutputMatchesConfig;
+    private applyCategoryConflictSuppression;
+    private resolveLocalPlacementFromCandidates;
+    private localPlacementForConfig;
+    private hydrateLocalRuntimeState;
+    private persistLocalRuntimeState;
+    private decisionCacheStorageKey;
+    private interactionStateStorageKey;
+    private presentationCapsStorageKey;
+    private hydrateDecisionCache;
+    private persistDecisionCache;
+    private hydrateInteractionState;
+    private persistInteractionState;
+    private hydratePresentationCaps;
+    private persistPresentationCaps;
+    /**
+     * The set of identifiers (lowercased plan id + unique_handle) that name the
+     * user's CURRENT plan, so an `entitlement_rule` whose plan target carries
+     * either form is matched. The app may set `plan.id` to the handle (`"free"`)
+     * or the config id (`"plan_free"`); both resolve to the same plan here.
+     */
+    private activePlanIdentifiers;
+    /** Whether a rule's plan targets include the active plan (no plan target = applies to all plans). */
+    private ruleTargetsActivePlan;
+    private hydrateUsageLimitRulesFromExportedConfig;
+    private recalculateDerivedUsageTraits;
+    /**
+     * Resolves `{{recommended_plan_handle}}` and `{{recommended_plan_name}}`
+     * tokens against the user's current commercial plan (per Appendix C.3
+     * and targeting-studio-ui.md §4.1 — the base plan, NOT the trial-grant
+     * overlay). Falls back to empty strings when the user has no current
+     * plan, the plan is at the top of the hierarchy, or the exported config
+     * has no plans.
+     *
+     * Q-3 (plan #46) audit: `userContext.plan.id` is the commercial plan;
+     * `effectivePlanHandle` (resolved separately in `deriveLocalEntitlement`
+     * for reverse-trial grants) is the trial overlay. The spec example
+     * "Free user on Pro reverse trial → recommends Pro" works because Free
+     * is the base; next-tier-up from Free is Pro.
+     */
+    private deriveRecommendedPlanTokens;
+    /**
+     * Return the SDK-resolved personalization token map.
+     *
+     * Reads from the transient `personalization` map on the user context,
+     * which holds both SDK-derived tokens (plan_name, usage_current, etc.)
+     * and app-provided tokens set via `setPersonalization()` or `identify()`.
+     *
+     * Pass the placement's payload (its `recommendation_strategy` /
+     * `recommendation_plan_override` fields) to resolve the
+     * `{{recommended_plan_handle}}` / `{{recommended_plan_name}}` tokens for
+     * that specific placement (plan #47, Appendix C.3). Without a payload the
+     * map carries the user-level `next_tier_up` default; with one, the
+     * placement's authored strategy (e.g. a `custom` forced plan) overlays
+     * those two tokens. All other tokens are unaffected.
+     *
+     * @param payload Optional placement payload carrying the per-placement
+     *   recommendation strategy. Omit for the user-level default.
+     */
+    getPersonalizationTokens(payload?: {
+        recommendation_strategy?: RecommendationStrategy | null;
+        recommendation_plan_override?: string | null;
+    }): RevTurbinePersonalizationTokens;
+    /**
+     * Return the SDK-resolved entitlement snapshot for the active user.
+     *
+     * The returned object is keyed by entitlement handle and reflects the
+     * latest results from local/runtime checks tracked by the SDK.
+     */
+    getEntitlements(): Record<string, EntitlementResult>;
+    /**
+     * Return the SDK-resolved usage snapshot for the active user.
+     *
+     * Keys are usage units (derived from configured usage token prefixes when available),
+     * and values include current usage plus optional limit when known.
+     */
+    getUsage(): RevTurbineUsageSnapshot;
+    /**
+     * Return current SDK policy snapshot.
+     */
+    getPolicy(): RevTurbinePolicySnapshot;
+    private deriveLocalEntitlementFromConfiguredRules;
+    /**
+     * Inline adapter — given a UserTrialStatus + the tenant's
+     * reverse_trial_rules from ExportedConfig, derive the inputs that
+     * close plan 43 TASK-2. Returns undefined fields when the user
+     * isn't on an active reverse trial, when no rule matches, or when
+     * the rule has no entitlements_during_trial[].
+     *
+     * Why inline (not calling scaffold's deriveReverseTrialGrants):
+     * the scaffold helper takes a `TrialInstance` (DB-side state) and
+     * matches by `rule_id`. The SDK only holds `UserTrialStatus` (the
+     * transient runtime shape) and doesn't see the rule_id. We match
+     * by `fallback_plan_id === plan_handle` instead — that's the
+     * single configured rule the user can be on per spec §2.4.2.
+     */
+    private resolveReverseTrialGrants;
+    /**
+     * Return the SDK-resolved targeting snapshot for the active user.
+     *
+     * Includes user id, segment ids, traits, plan, and merged usage so demo
+     * surfaces can display the same context used by placement eligibility.
+     */
+    getTargeting(): RevTurbineTargeting;
+    /**
+     * Explain why a placement decision was selected.
+     *
+     * Returns a structured diagnostic payload that includes:
+     * - Segment membership evaluation with predicate-level pass/fail details
+     * - Entitlement-rule matching outcomes for current targeting context
+     * - Placement decision metadata (`rule_id`, reason codes, suppression)
+     *
+     * Useful for debuggers, QA tooling, and customer-facing explainability UIs.
+     */
+    explainPlacementDecision(input: RevTurbinePlacementDecisionInput): Promise<RevTurbinePlacementDecisionExplanation>;
+    private usageThresholdForEntitlement;
+    private evaluateUsageThresholdCrossings;
+    private deriveTrialTriggerStage;
+    private evaluateTrialLifecycleTriggers;
+    private resolveAnonymousId;
+    private installBridge;
+    private installRouteTracking;
+    private mergeUserContext;
+    private mergePageContext;
+    private collectPageContextIssues;
+    private collectPayloadIssues;
+    private buildValidationWarningEvent;
+    private toEventEnvelope;
+    private sendEvents;
+    private dispatchToEventConsumers;
+    capture(eventName: string, properties: SdkEventProperties, options?: RevTurbineEventOptions): Promise<void>;
+    emitSemantic(eventType: string, payload: SdkEventProperties, options?: RevTurbineEventOptions): Promise<void>;
+    /**
+     * Optimized routine to evaluate segment membership and usage thresholds.
+     * Should be called on every user context or usage update.
+     *
+     * @param update - Partial user context or usage update payload
+     * @param isUsageUpdate - If true, also check usage thresholds
+     */
+    private evaluateUserSegmentsAndUsage;
+    setUserContext(userContext: RevTurbineUserContext): void;
+    setPageContext(pageContext: RevTurbinePageContext): void;
+    refreshPageContext(): void;
+    /**
+     * Hydrate the SDK with a server-evaluated payload.
+     *
+     * Call this on the client after receiving a `ServerEvaluationPayload`
+     * from the server-side SDK. Pre-populates the decision cache,
+     * entitlements, trial status, and user context so the client SDK
+     * avoids redundant API calls.
+     *
+     * @example
+     * ```ts
+     * // In your React component / page hydration:
+     * const sdk = initRevTurbine({ tenantId, apiKey, endpoint, mode: 'react' });
+     * sdk.hydrate(serverPayload);
+     * ```
+     */
+    hydrate(payload: ServerEvaluationHydrationPayload): void;
+    generatePlacementId(input: {
+        placementName: string;
+        placementScopeKey?: string;
+        normalizedPageRoute?: string;
+    }): Promise<string>;
+    /**
+     * @deprecated Use `registerSurfaceSlot`.
+     */
+    registerPlacement(config: RevTurbinePlacementConfig): Promise<string>;
+    private upsertSurfaceSlot;
+    registerSurfaceSlot(config: RevTurbineSurfaceSlotConfig): Promise<string>;
+    persistPlacementTypes(types: RevTurbinePlacementTypeEntity[]): Promise<void>;
+    private stableStringify;
+    private decisionCacheKey;
+    private interactionStateKey;
+    private readDecisionCache;
+    private writeDecisionCache;
+    private suppressionForState;
+    private placementCapKey;
+    private extractPlacementCapPolicies;
+    private applyPlacementCapsIfNeeded;
+    /**
+     * Plan 43 TASK-14 — gate a getPlacementDecision result on `cap.v1` policies.
+     *
+     * On the first decision pass (`tick: true`), the cap state is ticked when
+     * the cap allows firing — so a placement with
+     * `max_per_period: { count: 1, period: 'lifetime' }` is consumed once.
+     * On a cache-hit re-evaluation (`tick: false`), the cap state is only
+     * read, so subsequent identical inputs observe the consumed budget and
+     * the decision flips to `visible: false` with a `cap_exceeded` reason.
+     * Without this re-evaluation, the decision cache would return the
+     * stale `visible: true` from before the tick. When
+     * `enableClientCapsEnforcement` is false, this helper is a no-op.
+     */
+    private gateDecisionByCaps;
+    private normalizeDecisionFromResponse;
+    getPlacementDecision(input: RevTurbinePlacementDecisionInput): Promise<RevTurbinePlacementDecision>;
+    preloadPlacementDecisions(inputs: RevTurbinePlacementDecisionInput[]): Promise<void>;
+    bootstrapPlacementDecisions(inputs: RevTurbinePlacementDecisionInput[]): Promise<void>;
+    private updateInteractionState;
+    private flushInteractionQueue;
+    trackTreatmentInteraction(input: RevTurbineTreatmentInteractionInput): Promise<void>;
+    getPlacementContent(placementId: string, request?: JsonObject): Promise<RevTurbinePlacementContent>;
+    private normalizePlacementOutput;
+    private normalizeEntitlementResult;
+    private validateTrialStatusShape;
+    getPlacement(config: RevTurbinePlacementRequestConfig): Promise<PlacementOutput | null>;
+    checkEntitlement(handle: string, context?: RevTurbineEntitlementContext): Promise<EntitlementResult>;
+    updateUsage(balances: UsageBalances): void;
+    /**
+     * Build the full persistence-ready {@link UserContext} from the current
+     * SDK state. Includes `tenant_id` and `user_id` required for API storage.
+     */
+    getUserContext(): UserContext;
+    /**
+     * Fetch the resolved user context from the decision API.
+     * Returns the user's matched segments, traits, plan, and usage — used
+     * to determine which placement payloads are eligible for display.
+     */
+    fetchUserContext(userId: string): Promise<UserTargetingContext>;
+    /**
+     * Record that a placement was rendered to the user. Plan 43 TASK-9.
+     *
+     * Writes an `impressed` record to the SDK's `ImpressionHistory`,
+     * which persists to `localStorage` via `StorageImpressionStore`
+     * (or in-memory storage in non-browser environments). The
+     * impression contributes to:
+     *
+     *   - **Frequency caps (`cap.v1`)** — once-per-period limits
+     *     count this impression against the user's quota for the
+     *     placement.
+     *   - **Trial milestone supersession analytics** — for trial_progress
+     *     ladders, the supersession diagnostic uses delivery state
+     *     to distinguish "replaced an undelivered placement" (counts
+     *     in `superseded_placement_ids`) from "lower threshold was
+     *     already shown" (NOT counted — spec §3.5 "supersession only
+     *     applies to undelivered placements").
+     *   - **Generic milestone supersession (`content.milestone_order`)**
+     *     — the order-based variant in `applyContentMilestoneSupersession`.
+     *
+     * Call this from consumer code when the placement is actually
+     * shown to the user (e.g., from a React component's `useEffect`
+     * on mount, or after the rendering call returns). The SDK does
+     * NOT auto-record impressions — surfaces are rendered by consumer
+     * code, so only the consumer knows when a placement was actually
+     * presented (vs. fetched but not displayed).
+     *
+     * Safe to call multiple times for the same placement — duplicates
+     * append additional impression records (used by frequency caps to
+     * count delivery events).
+     *
+     * @param placementId - The placement's stable rule_id (e.g.
+     *   `'pl_trial_progress_70'`). Match `decision.output.rule_id`
+     *   from `getPlacementDecision`.
+     * @param payloadId - Optional payload variant id, for
+     *   variant-level analytics.
+     * @param surfaceTemplateId - Optional surface template id, for
+     *   per-surface cap accounting.
+     * @param metadata - Optional metadata persisted with the record.
+     *
+     * @example
+     * ```ts
+     * const decision = await sdk.getPlacementDecision({ placementId: 'slot_trial_modal' });
+     * if (decision.visible && decision.output?.rule_id) {
+     *   renderBanner(decision.output);
+     *   await sdk.recordImpression(decision.output.rule_id, decision.output.output_id);
+     * }
+     * ```
+     */
+    recordImpression(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: RevTurbineImpressionMetadata): Promise<void>;
+    /**
+     * Record a placement dismissal — the user explicitly closed it.
+     * The placement is permanently retired for this user; subsequent
+     * `getPlacementDecision` calls return `visible: false`.
+     *
+     * @param placementId - The placement's stable rule_id.
+     * @param payloadId - Optional payload variant id.
+     * @param surfaceTemplateId - Optional surface template id.
+     * @param metadata - Optional metadata persisted with the record.
+     */
+    recordDismissal(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: RevTurbineImpressionMetadata): Promise<void>;
+    /**
+     * Record a placement click-through — the user engaged with the CTA.
+     * The placement is permanently retired for this user.
+     *
+     * @param placementId - The placement's stable rule_id.
+     * @param payloadId - Optional payload variant id.
+     * @param surfaceTemplateId - Optional surface template id.
+     * @param metadata - Optional metadata persisted with the record.
+     */
+    recordClickThru(placementId: string, payloadId?: string, surfaceTemplateId?: string, metadata?: RevTurbineImpressionMetadata): Promise<void>;
+    getTrialStatus(): Promise<RevTurbineTrialContext>;
+    /**
+     * Returns the ExportedConfig snapshot loaded at initialization, if any.
+     * Available only in `local_only` mode when `exportedConfig` was provided.
+     */
+    getExportedConfig(): ExportedConfig | undefined;
+    /**
+     * Validate that each configured UI path action has a resolver implementation.
+     *
+    * By default this validates `localRuntime.exportedConfig.content_ui_paths` (when present)
+     * against:
+     * - `uiPathResolvers` passed at SDK init
+     * - optional `resolvers` passed to this method
+     * - CTA handlers from domain providers (`domain: 'cta'`), unless disabled
+     */
+    validateUiPathResolvers(options?: RevTurbineUiPathResolverValidationOptions): Promise<RevTurbineUiPathResolverValidationReport>;
+    private assertUiPathResolverCoverageOrThrow;
+    dismiss(outputId: string): Promise<void>;
+    snooze(outputId: string, seconds?: number): Promise<void>;
+    convert(outputId: string): Promise<void>;
+    /**
+     * Emit a canonical trigger event recognised by the decision engine.
+     *
+     * Convenience wrapper over {@link emitSemantic} that constrains the event
+     * name to {@link RevTurbineTriggerEvent} and attaches standard context
+     * (user_id, plan, timestamp) automatically.
+     *
+     * @example
+     * ```ts
+     * await sdk.emitTrigger('usage_limit_approaching', { usage_percent: 85, threshold: 80 });
+     * await sdk.emitTrigger('trial_expiring', { days_remaining: 2 });
+     * await sdk.emitTrigger('feature_gated', { feature: 'advanced_automation' });
+     * ```
+     */
+    emitTrigger(trigger: RevTurbineTriggerEvent, payload?: RevTurbineTriggerPayload, options?: RevTurbineEventOptions): Promise<void>;
+    trackEvent(name: string, data?: SdkEventProperties): Promise<void>;
+    identify(userId: string, contextOrTraits?: UserContextInput | SdkTraits): void;
+    resetIdentity(): void;
+    /**
+     * Hard-reset the user context to a blank slate — removes EVERY user-context
+     * value (`id`, `plan`, `email`, `account_id`, `custom`, `usage`,
+     * `entitlements`, `personalization`) plus usage balances, and clears the
+     * decision cache, interaction state, and impression history.
+     *
+     * Unlike {@link resetIdentity} (a sign-out that re-infers anonymous context
+     * when the `inferUser` policy is on), this performs **no** inference, so the
+     * resulting context is guaranteed empty. Mostly for demo / fixture flows that
+     * reset cleanly between scenarios.
+     *
+     * @example
+     * // Between demo personas:
+     * rt.resetUserContext();
+     * rt.identify('demo_pro', { plan: { id: 'pro', name: 'Pro' } });
+     */
+    resetUserContext(): void;
+    /**
+     * Shared teardown for {@link resetIdentity} / {@link resetUserContext}:
+     * blanks the user context and usage balances, recomputes derived traits, and
+     * clears the decision cache, interaction state, and impression history.
+     * `reinfer` controls whether anonymous context is re-inferred (sign-out) or
+     * the context is left fully empty (hard reset).
+     */
+    private clearAllUserState;
+    /**
+     * Check whether the user can do something — the advertised alias of
+     * {@link checkEntitlement}. Returns the rich {@link EntitlementResult}
+     * (`allowed`, `status`, `reason`, limits, `enforcement`). For billing-critical
+     * entitlements, confirm `enforcement === 'server_required'` on your backend.
+     *
+     * @example
+     * const access = await rt.can('generate_image');
+     * if (!access.allowed) showUpgrade();
+     */
+    can(handle: string, context?: RevTurbineEntitlementContext): Promise<EntitlementResult>;
+    /**
+     * Gate an action behind an entitlement — the advertised `gate(action, fn)` verb.
+     * Checks the entitlement for `action`; if allowed, runs `fn` and returns its
+     * result; otherwise does NOT run `fn` and returns the entitlement so the caller
+     * can surface a paywall (e.g. render an `<RTSlot>`). See {@link RevTurbineGateResult}.
+     *
+     * @example
+     * const gated = await rt.gate('export_pdf', () => exportPdf());
+     * if (!gated.ran) openPaywall(gated.entitlement);
+     */
+    gate<T>(action: string, fn: () => T | Promise<T>, context?: RevTurbineEntitlementContext): Promise<RevTurbineGateResult<T>>;
+    /**
+     * Track an event — the advertised alias of {@link trackEvent}. Powers
+     * analytics, frequency caps, attribution, and experiments.
+     *
+     * @example
+     * rt.track('ai_generation_completed', { credits: 3 });
+     */
+    track(name: string, data?: SdkEventProperties): Promise<void>;
+    /**
+     * Patch customer-reported usage — the advertised `update({ usage })` verb,
+     * delegating to {@link updateUsage}. For identity or full user-context changes
+     * use {@link identify} / {@link setUserContext}.
+     *
+     * @example
+     * rt.update({ usage: { generations: 25 } });
+     */
+    update(patch: RevTurbineUpdateInput): void;
+    /**
+     * Clear the current user — the advertised alias of {@link resetIdentity}
+     * (e.g. on sign-out).
+     */
+    reset(): void;
+    onRouteChange(change: {
+        path: string;
+        title?: string;
+        tags?: string[];
+    }): void;
+}
+/**
+ * Initialize the RevTurbine SDK.
+ *
+ * This is the primary entry point for browser integration.
+ * Also available as `window.RevTurbine.init()` for non-module environments.
+ *
+ * @param options - SDK initialization options
+ * @returns A configured SDK instance
+ *
+ * @example
+ * ```ts
+ * import { initRevTurbine } from '@revt-eng/sdk';
+ *
+ * const sdk = initRevTurbine({
+ *   tenantId: 'tenant_abc',
+ *   apiKey: 'rt_live_xxx',
+ *   endpoint: 'https://api.revturbine.io',
+ *   mode: 'snippet',
+ * });
+ * ```
+ */
+export declare function initRevTurbine(options: RevTurbineInitInputOptions): RevTurbineCustomerSdk;
+declare global {
+    interface Window {
+        RevTurbine?: {
+            init: typeof initRevTurbine;
+        };
+    }
+}
+//# sourceMappingURL=customer-side.d.ts.map