@revturbine/sdk 0.2.85 → 0.2.87

package/dist/types/web-sdk/server/index.d.ts

@@ -1,173 +0,0 @@
-/**
- * @module @revt-eng/web-sdk/server
- *
- * Server-side entitlement and placement decisions for React Server Components
- * (plan 186 TASK-3).
- *
- * A React hook cannot run in a Server Component: every module under `react/`
- * opens with `'use client'`, so importing one from the server graph yields an
- * opaque client reference rather than a callable. This module is the server
- * half — the same decisions, awaited instead of subscribed to.
- *
- * ```tsx
- * // app/page.tsx — a Server Component, no 'use client'
- * const rt = createServerClient({ tenantId, playbook });
- * const { denied } = await getEntitlement(rt, 'brand_kit', { user: { id: userId } });
- * return denied ? <UpgradePrompt /> : <BrandKitEditor />;
- * ```
- *
- * Three properties are deliberate and load-bearing:
- *
- * - **Local by default.** An RSC tree re-renders per request, so a network hop
- *   per decision is a latency tax the client SDK never paid. With a `playbook`
- *   the decision resolves in-process and keeps working when the control plane
- *   is unreachable. Remote is available by explicit configuration.
- * - **Fail closed.** Any evaluation failure resolves denied / not-visible and
- *   never throws into the render tree — a control-plane outage must not turn
- *   into an error boundary, and must never accidentally grant paid access.
- * - **No lifecycle fields.** The returned {@link EntitlementView} carries no
- *   `isLoading` and no `recheck`: the value is awaited, so it is always
- *   decided and there is nothing to re-run mid-render. Synthesizing them would
- *   be a lie the type system then endorses.
- *
- * The credential passed here — a long-lived `server` api-token — must never
- * reach the browser. It is accepted only by {@link createServerClient}, is
- * never placed on a returned value, and never appears in the hydration payload
- * handed to `RevTurbineProvider`.
- *
- * Plan: docs/dev-lifecycle/inprogress/186-server-rendering-sdk-and-api-token-management.md
- */
-import { type ConfigArtifact } from '../config-artifact';
-import type { EntitlementView, PlacementView } from '../views';
-import type { RevTurbineEntitlementContext } from '../customer-side';
-/**
- * The end user a server-side decision is evaluated for.
- *
- * There is no ambient user on the server — a Server Component has no provider
- * to read from — so the caller states it explicitly. Plan 186 TASK-4 adds an
- * optional request-scoped form that supplies this implicitly.
- */
-export interface ServerUser {
-    /** The end-user identifier decisions are evaluated for. */
-    id: string;
-    /** The user's current plan handle, used to resolve entitlement rules. */
-    planHandle?: string;
-    /** Targeting traits for segment evaluation. */
-    traits?: Record<string, string | number | boolean>;
-}
-/** How a {@link RevTurbineServerClient} reaches its decisions. */
-export type ServerTransport = 'local' | 'remote';
-/**
- * Configuration for {@link createServerClient}.
- *
- * Supply a `playbook` for local mode (the default). Supply `endpoint` +
- * `apiToken` for remote mode, which is selected automatically when no playbook
- * is present and can be forced with `transport: 'remote'`.
- */
-export interface ServerClientOptions {
-    /** Tenant the decisions belong to. */
-    tenantId: string;
-    /**
-     * The bundled Playbook. Its presence selects local mode, where decisions
-     * resolve in-process with no network call.
-     */
-    playbook?: ConfigArtifact;
-    /** Target environment for Playbooks that predate environment stamping. */
-    environmentId?: string;
-    /**
-     * A long-lived `server` api-token, for remote mode.
-     *
-     * Server-only. Never return it to the browser, never place it in props, and
-     * never embed it in a hydration payload.
-     */
-    apiToken?: string;
-    /** Control-plane origin, for remote mode. */
-    endpoint?: string;
-    /** Force a transport. Defaults to `'local'` whenever a `playbook` is given. */
-    transport?: ServerTransport;
-}
-/**
- * A server-side decision client.
- *
- * Create one per process (or per request) with {@link createServerClient} and
- * pass it to {@link getEntitlement} / {@link getPlacement}. Holds no per-user
- * state, so it is safe to share across concurrent requests.
- */
-export declare class RevTurbineServerClient {
-    #private;
-    /** Tenant the decisions belong to. */
-    readonly tenantId: string;
-    /** How this client reaches its decisions. */
-    readonly transport: ServerTransport;
-    constructor(options: ServerClientOptions);
-    /**
-     * A runtime bound to one user.
-     *
-     * Built per call rather than once per client: `LocalRuntime` takes its
-     * `userId` at construction and `createStaticProviders` resolves entitlement
-     * rules against a specific `planHandle`, so a shared instance would evaluate
-     * every request against whichever user built it. (This is also why the
-     * existing `LocalEvaluationServer`, whose runtime is constructed once with
-     * `userId: '__server__'`, cannot answer a per-user entitlement question.)
-     * Plan 186 TASK-4 memoizes this per request via React `cache()`.
-     */
-    private runtimeFor;
-    /** @internal Resolve one entitlement, fail-closed. */
-    _entitlement(handle: string, user: ServerUser, context?: RevTurbineEntitlementContext): Promise<EntitlementView>;
-    /** @internal Resolve one placement, fail-closed. */
-    _placement(placementId: string, user: ServerUser): Promise<PlacementView>;
-}
-/**
- * Create a server-side decision client.
- *
- * @param options - Transport and tenant configuration. A `playbook` selects
- * local mode; `endpoint` + `apiToken` select remote.
- *
- * @example
- * ```ts
- * import playbook from '../revturbine.playbook.json';
- * export const rt = createServerClient({ tenantId: 'tn_acme', playbook });
- * ```
- */
-export declare function createServerClient(options: ServerClientOptions): RevTurbineServerClient;
-/**
- * Resolve one entitlement for one user, from a Server Component.
- *
- * Never throws: an evaluation failure resolves denied, so a control-plane
- * outage cannot become an error boundary and cannot accidentally grant access.
- *
- * Gate paid UI on `denied` rather than on `!allowed` — a `limited` result still
- * grants access when the evaluator permits it.
- *
- * @param client - From {@link createServerClient}.
- * @param handle - The entitlement handle, e.g. `'brand_kit'`.
- * @param input - The user to evaluate for, and optional usage context.
- *
- * @example
- * ```tsx
- * const { denied } = await getEntitlement(rt, 'brand_kit', { user: { id: userId } });
- * if (denied) return <UpgradePrompt />;
- * ```
- */
-export declare function getEntitlement(client: RevTurbineServerClient, handle: string, input: {
-    user: ServerUser;
-    context?: RevTurbineEntitlementContext;
-}): Promise<EntitlementView>;
-/**
- * Resolve one placement decision for one user, from a Server Component.
- *
- * Never throws: an evaluation failure resolves not-visible, so a failed
- * decision hides the surface rather than breaking the page.
- *
- * The result carries no interaction callbacks — `dismiss`, `ctaClick` and
- * viewport exposure are inherently client-side. Render the decision on the
- * server and let a client component own the interactions.
- *
- * @param client - From {@link createServerClient}.
- * @param input - The placement to resolve and the user to resolve it for.
- */
-export declare function getPlacement(client: RevTurbineServerClient, input: {
-    placementId: string;
-    user: ServerUser;
-}): Promise<PlacementView>;
-//# sourceMappingURL=index.d.ts.map

package/dist/types/web-sdk/server/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAKH,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACnF,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,KAAK,EAEV,4BAA4B,EAE7B,MAAM,kBAAkB,CAAC;AAE1B;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACpD;AAED,kEAAkE;AAClE,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAqCD;;;;;;GAMG;AACH,qBAAa,sBAAsB;;IACjC,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;gBAYxB,OAAO,EAAE,mBAAmB;IA0BxC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,UAAU;IAelB,sDAAsD;IAChD,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,4BAA4B,GACrC,OAAO,CAAC,eAAe,CAAC;IAY3B,oDAAoD;IAC9C,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;CA0BhF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,sBAAsB,CAEvF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,sBAAsB,EAC9B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,CAAC,EAAE,4BAA4B,CAAA;CAAE,GAClE,OAAO,CAAC,eAAe,CAAC,CAE1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC/C,OAAO,CAAC,aAAa,CAAC,CAExB"}

package/dist/types/web-sdk/views.d.ts

@@ -1,65 +0,0 @@
-/**
- * @module @revt-eng/web-sdk/views
- *
- * The decision shapes a caller reads, independent of *how* the decision was
- * obtained (plan 186 TASK-1).
- *
- * A React hook resolves a decision over time, so its result carries lifecycle
- * fields — `isLoading`, `error`, a re-run callback. A server-rendered caller
- * awaits the decision, so it has none of those: by the time it holds a value,
- * the value is final. What both share is the decision itself, and that shared
- * part lives here.
- *
- * This module deliberately contains **types only and no runtime imports**, and
- * deliberately sits outside `react/`. Every module under `react/` opens with
- * `'use client'`, so a React Server Component importing one receives an opaque
- * client reference rather than a usable value — the server binding could not
- * reuse these shapes if they stayed there.
- *
- * Plan: docs/dev-lifecycle/inprogress/186-server-rendering-sdk-and-api-token-management.md
- */
-import type { EntitlementResult, PlacementOutput, RevTurbinePlacementContent, RevTurbinePlacementDecision } from './customer-side';
-/**
- * A resolved entitlement decision.
- *
- * The three booleans are conveniences over {@link EntitlementView.result} and
- * are mutually exclusive once resolved. Note that `allowed` and `limited` are
- * not opposites: a `limited` result still grants access when the evaluator
- * permits it, so gate paywall UI on `denied`, never on `!allowed`.
- *
- * Callers that need to distinguish "denied" from "not yet decided" want the
- * client-side {@link UseEntitlementResult}, whose `isLoading` carries that
- * distinction. On the server the question does not arise — the value is awaited,
- * so it is always decided.
- */
-export interface EntitlementView {
-    /** The full entitlement result from the evaluator. `null` until resolved. */
-    result: EntitlementResult | null;
-    /** `true` when the entitlement is allowed outright. */
-    allowed: boolean;
-    /** `true` when access is granted but the balance is approaching its limit. */
-    limited: boolean;
-    /** `true` when the entitlement is denied. */
-    denied: boolean;
-    /** The upgrade surface to render on denial, when one was resolved. */
-    gatedPlacement: PlacementOutput | null;
-}
-/**
- * A resolved placement decision.
- *
- * Carries what to render and whether to render it — not how to interact with
- * it. Interaction callbacks (`dismiss`, `ctaClick`, …) and viewport-exposure
- * wiring are inherently client-side and live on
- * {@link UsePlacementResult} instead.
- */
-export interface PlacementView {
-    /** The resolved placement identifier. */
-    placementId: string;
-    /** Whether the placement should be rendered. */
-    visible: boolean;
-    /** The full decision from the engine. `null` until resolved. */
-    decision: RevTurbinePlacementDecision | null;
-    /** Resolved content with personalization tokens expanded. `null` until resolved. */
-    content: RevTurbinePlacementContent['content'] | null;
-}
-//# sourceMappingURL=views.d.ts.map

package/dist/types/web-sdk/views.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../../views.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,0BAA0B,EAC1B,2BAA2B,EAC5B,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,MAAM,EAAE,OAAO,CAAC;IAChB,sEAAsE;IACtE,cAAc,EAAE,eAAe,GAAG,IAAI,CAAC;CACxC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,QAAQ,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAC7C,oFAAoF;IACpF,OAAO,EAAE,0BAA0B,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;CACvD"}