@revturbine/cli 0.19.2 → 0.19.3

package/README.md

@@ -80,7 +80,7 @@ Commands that read a config name the version explicitly — there is no default:
 | `status` | The live Release and the open draft, side by side. |
 | `history` | The Release Version Log, newest first. |
 | `preview` | The open draft's staged changes. |
-| `evaluate` | Run a config version's placement/entitlement decisions locally for a user context. Use `--slot` with optional `--component-type`; deprecated `--surface-type` remains an alias. |
+| `evaluate` | Run a config version's placement/entitlement decisions locally for a user context. Use `--slot` with optional `--component-type`; deprecated `--surface-type` remains an alias. The ctx file carries the whole decision context — `plan_handle`, `traits`, `usage`, `trial` (or `trial_instances` + `now_iso`) — and `--usage` / `--trial-status` / `--now` override those keys, so usage-threshold and trial placements decide here exactly as they do in an app. Output reports `payload_ids`: which authored payload the resolver chose per placement, plus the SDK's `personalization_tokens`. |
 | `generate types` | Generate a TypeScript module of typed Playbook handles from any config version — `Entitlements` (namespaced by type, with the `EntitlementHandle` union for type-safe `can()`/`gate()`/`checkEntitlement()` call sites), plus `Plans`, `Segments`, `SurfaceTemplates`, and `UiPathActionTypes`. Const objects + literal-union types (erasable — no enums). `--out <path>` writes the file; the generated header records the exact command to regenerate it. `--json` for the raw handle map. |
 | `analytics catalog\|templates\|views\|view\|create\|preview\|query` | Work with the hosted Semantic Catalog and canonical analytics-view documents. Create and preview pass the document through unchanged to the same server contract used by the web editor and MCP tools; preview remains subject to the server's query limits. |
 | `ingest-keys create` (alias `mint`) | Mint a tenant-bound public ingest token for browser SDK use. Requires one or more `--origin` values; optional `--ip` restrictions. The full token is returned once. `ingest-keys list` shows ids/previews and `ingest-keys revoke <id>` invalidates one. |

package/dist/cli.js

@@ -14390,28 +14390,181 @@ function formatAuthentication(hasToken, tokenValid) {
   return "authentication: verification unavailable \u2014 credentials present; retry when the instance is reachable";
 }
 
+// src/lib/evaluate-context.ts
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var DEFAULT_USAGE_UNIT = "unit";
+function normalizeUsageEntry(handle, value, errors) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0) {
+      errors.push(`usage.${handle} must be a finite number \u2265 0`);
+      return void 0;
+    }
+    return { entitlement_handle: handle, unit: DEFAULT_USAGE_UNIT, amount: value };
+  }
+  if (!isRecord4(value)) {
+    errors.push(`usage.${handle} must be a number or an object with "amount"`);
+    return void 0;
+  }
+  const amount = value.amount;
+  if (typeof amount !== "number" || !Number.isFinite(amount) || amount < 0) {
+    errors.push(`usage.${handle}.amount must be a finite number \u2265 0`);
+    return void 0;
+  }
+  const entry = {
+    entitlement_handle: typeof value.entitlement_handle === "string" ? value.entitlement_handle : handle,
+    unit: typeof value.unit === "string" && value.unit.length > 0 ? value.unit : DEFAULT_USAGE_UNIT,
+    amount
+  };
+  if (value.limit !== void 0) {
+    if (typeof value.limit !== "number" || !Number.isFinite(value.limit) || value.limit < 0) {
+      errors.push(`usage.${handle}.limit must be a finite number \u2265 0`);
+    } else {
+      entry.limit = value.limit;
+    }
+  }
+  if (value.reset_date !== void 0) {
+    if (typeof value.reset_date !== "string") {
+      errors.push(`usage.${handle}.reset_date must be a string`);
+    } else {
+      entry.reset_date = value.reset_date;
+    }
+  }
+  return entry;
+}
+function normalizeUsage(value, errors) {
+  if (value === void 0 || value === null) return void 0;
+  if (!isRecord4(value)) {
+    errors.push("usage must be an object keyed by entitlement handle");
+    return void 0;
+  }
+  const out = {};
+  for (const [handle, raw] of Object.entries(value)) {
+    const entry = normalizeUsageEntry(handle, raw, errors);
+    if (entry) out[handle] = entry;
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function normalizeTrialStatus(value, errors) {
+  if (value === void 0 || value === null) return void 0;
+  if (!isRecord4(value)) {
+    errors.push("trial status must be an object (the SDK's UserTrialStatus)");
+    return void 0;
+  }
+  if (typeof value.in_trial !== "boolean") {
+    errors.push('trial status must carry a boolean "in_trial"');
+    return void 0;
+  }
+  return value;
+}
+function normalizeTrialInstances(value, errors) {
+  if (value === void 0 || value === null) return void 0;
+  if (!Array.isArray(value) || value.some((item) => !isRecord4(item))) {
+    errors.push("trial_instances must be an array of TrialInstance objects");
+    return void 0;
+  }
+  return value.length > 0 ? value : void 0;
+}
+function normalizeNowIso(value, source, errors) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value !== "string" || Number.isNaN(Date.parse(value))) {
+    errors.push(`${source} must be an ISO-8601 timestamp (e.g. 2026-09-21T00:00:00Z)`);
+    return void 0;
+  }
+  return new Date(value).toISOString();
+}
+function parseJsonFlag(raw, flag, errors) {
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    errors.push(`${flag} must be valid JSON: ${err.message}`);
+    return void 0;
+  }
+}
+function parseDecisionContext(input) {
+  const errors = [];
+  const usageSource = input.usage !== void 0 ? parseJsonFlag(input.usage, "--usage", errors) : input.ctx.usage;
+  const usage = normalizeUsage(usageSource, errors);
+  const trialSource = input.trialStatus !== void 0 ? parseJsonFlag(input.trialStatus, "--trial-status", errors) : input.ctx.trial;
+  const trialStatus = normalizeTrialStatus(trialSource, errors);
+  const trialInstances = normalizeTrialInstances(input.ctx.trial_instances, errors);
+  const nowIso = input.now !== void 0 ? normalizeNowIso(input.now, "--now", errors) : normalizeNowIso(input.ctx.now_iso, "now_iso", errors);
+  if (errors.length > 0) return { ok: false, errors };
+  return {
+    ok: true,
+    context: {
+      ...usage ? { usage } : {},
+      ...trialStatus ? { trialStatus } : {},
+      ...trialInstances ? { trialInstances } : {},
+      ...nowIso ? { nowIso } : {}
+    }
+  };
+}
+
 // src/lib/evaluate-local.ts
 import { initRevTurbine } from "@revturbine/sdk/headless";
 function resolvePlacementComponentType(input) {
   return input.componentType ?? input.surfaceType;
 }
+function payloadIdOf(decision) {
+  if (typeof decision !== "object" || decision === null) return null;
+  const output = decision.output;
+  if (typeof output !== "object" || output === null) return null;
+  const id = output.output_id;
+  return typeof id === "string" ? id : null;
+}
+async function completeUsageLimits(session, usage) {
+  let completed = false;
+  const filled = {};
+  for (const [handle, entry] of Object.entries(usage)) {
+    if (entry.limit !== void 0) {
+      filled[handle] = entry;
+      continue;
+    }
+    const result = await session.checkEntitlement(entry.entitlement_handle);
+    if (typeof result?.limit === "number" && Number.isFinite(result.limit)) {
+      filled[handle] = { ...entry, limit: result.limit };
+      completed = true;
+    } else {
+      filled[handle] = entry;
+    }
+  }
+  if (completed) session.setUserContext({ usage: filled });
+}
 async function evaluateLocal(config, input) {
   const user = { id: input.userId };
   if (input.planHandle) user.plan_handle = input.planHandle;
   if (input.traits && Object.keys(input.traits).length > 0) user.custom = input.traits;
+  if (input.usage) user.usage = input.usage;
   const session = await initRevTurbine({
     user,
-    localRuntime: { playbook: config }
+    localRuntime: {
+      playbook: config,
+      ...input.trialStatus ? { initialData: { trialStatus: input.trialStatus } } : {}
+    }
   });
+  if (input.trialInstances) {
+    await session.sdk.setTrialInstances(
+      input.trialInstances,
+      input.nowIso ? { nowIso: input.nowIso } : void 0
+    );
+  }
+  const trialAsked = Boolean(input.trialInstances || input.trialStatus);
+  const trialStatus = trialAsked ? await session.getTrialStatus() : void 0;
+  if (input.usage) await completeUsageLimits(session, input.usage);
   const entitlements = {};
   for (const handle of input.entitlementHandles ?? []) {
     entitlements[handle] = await session.checkEntitlement(handle);
   }
   const decisions = [];
+  const payloadIds = {};
   for (const placementId of input.placementIds ?? []) {
     const controller = session.placement({ placement: { name: placementId } });
     await controller.load();
-    decisions.push(controller.state.decision);
+    const decision = controller.state.decision;
+    decisions.push(decision);
+    payloadIds[placementId] = payloadIdOf(decision);
   }
   const componentType = input.slot ? resolvePlacementComponentType(input.slot) : void 0;
   const placement = input.slot && (input.slot.slotId || componentType) ? await session.getPlacement({
@@ -14419,7 +14572,14 @@ async function evaluateLocal(config, input) {
     ...componentType ? { componentType } : {},
     ...input.planHandle ? { planHandle: input.planHandle } : {}
   }) : null;
-  return { decisions, entitlements, placement };
+  return {
+    decisions,
+    payloadIds,
+    entitlements,
+    placement,
+    personalizationTokens: session.sdk.getPersonalizationTokens(),
+    ...trialStatus !== void 0 ? { trialStatus } : {}
+  };
 }
 
 // src/lib/ingest-keys.ts
@@ -14665,14 +14825,14 @@ function schemaForConfig(raw) {
 var repairDeprecatedFields2 = repairDeprecatedFields;
 var LEGACY_HEADER_ALIASES = /* @__PURE__ */ new Set(["version", "change_set_id"]);
 var UNKNOWN_FIELD_CODE = "cli/unknown-field";
-function isRecord4(value) {
+function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function unknownTopLevelKeys(raw) {
-  if (!isRecord4(raw)) return [];
+  if (!isRecord5(raw)) return [];
   const { schema } = schemaForConfig(raw);
   const parsed = schema.safeParse(raw);
-  if (!parsed.success || !isRecord4(parsed.data)) return [];
+  if (!parsed.success || !isRecord5(parsed.data)) return [];
   const recognized = new Set(Object.keys(parsed.data));
   return Object.keys(raw).filter((key2) => !recognized.has(key2) && !LEGACY_HEADER_ALIASES.has(key2));
 }
@@ -14916,17 +15076,17 @@ function finalOutputLines(params) {
 
 // src/lib/handles-codegen.ts
 var UNTYPED_GROUP = "untyped";
-function isRecord5(value) {
+function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function nonEmptyString(value) {
   return typeof value === "string" && value.length > 0 ? value : null;
 }
 function extractEntitlementHandles(config) {
-  if (!isRecord5(config) || !Array.isArray(config.entitlements)) return {};
+  if (!isRecord6(config) || !Array.isArray(config.entitlements)) return {};
   const groups = /* @__PURE__ */ new Map();
   for (const entry of config.entitlements) {
-    if (!isRecord5(entry)) continue;
+    if (!isRecord6(entry)) continue;
     const handle = nonEmptyString(entry.unique_handle) ?? nonEmptyString(entry.handle);
     if (!handle) continue;
     const type = nonEmptyString(entry.type) ?? UNTYPED_GROUP;
@@ -14996,36 +15156,36 @@ function collectStrings(values) {
   return [...out].sort();
 }
 function extractPlanHandles(config) {
-  if (!isRecord5(config) || !Array.isArray(config.plans)) return [];
+  if (!isRecord6(config) || !Array.isArray(config.plans)) return [];
   return collectStrings(
     config.plans.map(
-      (p) => isRecord5(p) ? nonEmptyString(p.unique_handle) ?? nonEmptyString(p.handle) ?? p.id : null
+      (p) => isRecord6(p) ? nonEmptyString(p.unique_handle) ?? nonEmptyString(p.handle) ?? p.id : null
     )
   );
 }
 function extractSegmentHandles(config) {
-  if (!isRecord5(config) || !Array.isArray(config.segments)) return [];
+  if (!isRecord6(config) || !Array.isArray(config.segments)) return [];
   return collectStrings(
-    config.segments.map((s) => isRecord5(s) ? nonEmptyString(s.handle) ?? s.id : null)
+    config.segments.map((s) => isRecord6(s) ? nonEmptyString(s.handle) ?? s.id : null)
   );
 }
 function extractSurfaceTemplateIds(config) {
-  if (!isRecord5(config)) return [];
+  if (!isRecord6(config)) return [];
   const ids = [];
   if (Array.isArray(config.surface_templates)) {
     for (const t of config.surface_templates) {
-      if (isRecord5(t)) ids.push(t.id ?? t.template_id);
+      if (isRecord6(t)) ids.push(t.id ?? t.template_id);
     }
   }
   const surfacesOf = (payload) => {
-    if (!isRecord5(payload) || !Array.isArray(payload.surfaces)) return;
+    if (!isRecord6(payload) || !Array.isArray(payload.surfaces)) return;
     for (const surface of payload.surfaces) {
-      if (isRecord5(surface)) ids.push(surface.template_id);
+      if (isRecord6(surface)) ids.push(surface.template_id);
     }
   };
   if (Array.isArray(config.placements)) {
     for (const placement of config.placements) {
-      if (!isRecord5(placement) || !Array.isArray(placement.payloads)) continue;
+      if (!isRecord6(placement) || !Array.isArray(placement.payloads)) continue;
       for (const payload of placement.payloads) surfacesOf(payload);
     }
   }
@@ -15035,9 +15195,9 @@ function extractSurfaceTemplateIds(config) {
   return collectStrings(ids);
 }
 function extractUiPathActionTypes(config) {
-  if (!isRecord5(config) || !Array.isArray(config.content_ui_paths)) return [];
+  if (!isRecord6(config) || !Array.isArray(config.content_ui_paths)) return [];
   return collectStrings(
-    config.content_ui_paths.map((p) => isRecord5(p) ? p.action_type : null)
+    config.content_ui_paths.map((p) => isRecord6(p) ? p.action_type : null)
   );
 }
 function renderFlatFamily(lines, opts) {
@@ -15139,19 +15299,19 @@ function fail(cls, message) {
 }
 
 // src/lib/pin-drift.ts
-function isRecord6(value) {
+function isRecord7(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function pinOf(pkg, name) {
   for (const field of ["devDependencies", "dependencies"]) {
     const deps = pkg[field];
-    if (isRecord6(deps) && typeof deps[name] === "string") return deps[name];
+    if (isRecord7(deps) && typeof deps[name] === "string") return deps[name];
   }
   return void 0;
 }
 var EXACT = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
 function checkPinDrift(pkg) {
-  if (!isRecord6(pkg)) return [];
+  if (!isRecord7(pkg)) return [];
   const warnings = [];
   const cliPin = pinOf(pkg, "@revturbine/cli");
   if (cliPin !== void 0 && !EXACT.test(cliPin)) {
@@ -16223,8 +16383,8 @@ program.command("preview").description("The open draft's Runtime Impact summary
   emit(data, Boolean(opts.json), text);
 });
 program.command("evaluate").description(
-  "Run placement/entitlement decisions for a user context against a config version \u2014 evaluated LOCALLY: the CLI fetches the version's Playbook and runs the SDK engine in-process (plan 192; clean-room, no suppression/cap history). Requires --live, --draft, or --release <id>."
-).option("--live", "Evaluate the live (deployed) configuration").option("--draft", "Evaluate the tenant's open draft").option("--release <id>", "Evaluate a past release (from its frozen snapshot)").option("--entitlement <handle>", "Check one entitlement (the checkEntitlement result)").option("--slot <id>", "Evaluate one surface slot (the getPlacement decision for that slot)").option("--component-type <type>", "Disambiguate a slot that can render more than one component, or resolve by component type alone").option("--surface-type <type>", "Deprecated alias for --component-type").option("--plan-handle <handle>", "Evaluate as if the user were on this plan (overrides the ctx file)").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).requiredOption("--user <file>", "JSON file: { user_id, customer_id?, plan_handle?, traits?, now_iso? }").option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(
+  "Run placement/entitlement decisions for a user context against a config version \u2014 evaluated LOCALLY: the CLI fetches the version's Playbook and runs the SDK engine in-process (plan 192; clean-room, no suppression/cap history). The ctx file carries the full decision context \u2014 plan, traits, usage, trial state and a clock pin \u2014 so usage-threshold and trial placements decide here as they do in an app. Requires --live, --draft, or --release <id>."
+).option("--live", "Evaluate the live (deployed) configuration").option("--draft", "Evaluate the tenant's open draft").option("--release <id>", "Evaluate a past release (from its frozen snapshot)").option("--entitlement <handle>", "Check one entitlement (the checkEntitlement result)").option("--slot <id>", "Evaluate one surface slot (the getPlacement decision for that slot)").option("--component-type <type>", "Disambiguate a slot that can render more than one component, or resolve by component type alone").option("--surface-type <type>", "Deprecated alias for --component-type").option("--plan-handle <handle>", "Evaluate as if the user were on this plan (overrides the ctx file)").option("--usage <json>", `Usage entries keyed by entitlement handle, e.g. '{"api_calls":{"amount":95}}' (overrides the ctx file) \u2014 required to decide usage/credit-threshold placements`).option("--trial-status <json>", `Trial status, e.g. '{"in_trial":true,"trial_limit_type":"time","days_remaining":3}' (overrides the ctx file) \u2014 required to decide trial placements`).option("--now <iso>", "Pin the clock (ISO-8601) for trial derivation from the ctx file's trial_instances (overrides ctx now_iso)").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).requiredOption("--user <file>", "JSON file: { user_id, plan_handle?, traits?, usage?, trial?, trial_instances?, now_iso? }").option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(
   async (opts) => {
     const [sel] = requireSelectors(opts, [], { count: 1, allowed: ["draft", "live", "release"], command: "evaluate" });
     const conn = connect(opts.url, opts.tenantId);
@@ -16242,8 +16402,18 @@ program.command("evaluate").description(
     }
     const userId = typeof ctx.user_id === "string" && ctx.user_id.length > 0 ? ctx.user_id : void 0;
     if (!userId) fail(EXIT.VALIDATION, `user file must carry a non-empty string "user_id" (${opts.user})`);
-    if (typeof ctx.now_iso === "string") {
-      diag("WARNING: now_iso is ignored \u2014 local evaluation uses the real clock.");
+    const parsed = parseDecisionContext({
+      ctx,
+      usage: opts.usage,
+      trialStatus: opts.trialStatus,
+      now: opts.now
+    });
+    if (!parsed.ok) fail(EXIT.VALIDATION, `invalid decision context in ${opts.user}: ${parsed.errors.join("; ")}`);
+    const decisionContext = parsed.context;
+    if (decisionContext.nowIso && !decisionContext.trialInstances) {
+      diag(
+        'NOTE: the pinned clock only moves trial derivation from trial_instances; an explicit "trial" status is already fixed in time.'
+      );
     }
     if (typeof ctx.customer_id === "string") {
       diag(
@@ -16262,6 +16432,7 @@ program.command("evaluate").description(
       userId,
       planHandle,
       traits,
+      ...decisionContext,
       entitlementHandles: opts.entitlement ? [opts.entitlement] : bulk ? asStringArray2(ctx.entitlement_handles) : [],
       placementIds: bulk ? asStringArray2(ctx.placement_ids) : [],
       slot: wantsSlot ? { slotId: opts.slot, componentType } : void 0
@@ -16271,10 +16442,18 @@ program.command("evaluate").description(
         tenant_id: conn.tenantId,
         user_id: userId,
         ...playbookVersionId ? { playbook_version_id: playbookVersionId } : {},
-        evaluated_at: (/* @__PURE__ */ new Date()).toISOString(),
+        // The pinned clock when one was given, so the stamp matches the
+        // instant the decisions were made against.
+        evaluated_at: decisionContext.nowIso ?? (/* @__PURE__ */ new Date()).toISOString(),
         // Provenance: decided in-process by the SDK engine, not by a server.
         evaluation: "local",
-        ...result
+        decisions: result.decisions,
+        // Which authored payload the resolver chose, per requested placement.
+        payload_ids: result.payloadIds,
+        entitlements: result.entitlements,
+        placement: result.placement,
+        personalization_tokens: result.personalizationTokens,
+        ...result.trialStatus !== void 0 ? { trial_status: result.trialStatus } : {}
       },
       true
     );
@@ -16546,10 +16725,23 @@ var COMMAND_EXAMPLES = {
   ].join("\n"),
   evaluate: [
     "",
-    "Example:",
+    "Examples:",
     "  revturbine evaluate --live --user ./ctx.json --entitlement seats",
     "  revturbine evaluate --draft --user ./ctx.json --slot upgrade_banner --component-type banner --plan-handle pro",
-    '    ctx.json: { "user_id": "u1", "plan_handle": "pro", "entitlement_handles": ["seats"] }'
+    `  revturbine evaluate --live --user ./ctx.json --usage '{"api_calls":{"amount":95}}'`,
+    `  revturbine evaluate --live --user ./ctx.json --trial-status '{"in_trial":true,"trial_limit_type":"time","days_remaining":3}'`,
+    "  revturbine evaluate --live --user ./ctx.json --now 2026-09-21T00:00:00Z",
+    "",
+    "ctx.json \u2014 the whole decision context:",
+    '    { "user_id": "u1", "plan_handle": "pro", "traits": { "tier": "smb" },',
+    '      "usage": { "api_calls": { "amount": 95, "limit": 100 } },',
+    '      "trial": { "in_trial": true, "trial_limit_type": "time", "days_remaining": 3 },',
+    '      "trial_instances": [ ... ], "now_iso": "2026-09-21T00:00:00Z",',
+    '      "entitlement_handles": ["seats"], "placement_ids": ["pl_usage_warn"] }',
+    "",
+    `  usage \u2014 omit "limit" and it is taken from the Playbook's entitlement rule.`,
+    "  trial \u2014 an explicit status; trial_instances + now_iso derive one at that clock.",
+    "  Output carries payload_ids: which authored payload won, per placement."
   ].join("\n")
 };
 for (const [name, text] of Object.entries(COMMAND_EXAMPLES)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revturbine/cli",
-  "version": "0.19.2",
+  "version": "0.19.3",
   "description": "revturbine — validate RevTurbine Playbooks and ship them to a RevTurbine instance through the playbook-version lifecycle (draft → Release).",
   "license": "MIT",
   "repository": {
@@ -30,7 +30,7 @@
     "verify": "npm run typecheck && npm run lint && npm run check:schema && npm run test"
   },
   "dependencies": {
-    "@revturbine/sdk": "^0.7.4",
+    "@revturbine/sdk": ">=0.10.9 <1",
     "commander": "^15.0.0",
     "semver": "^7.8.5",
     "zod": "4.4.3"