@revturbine/sdk 0.2.68 → 0.2.69

package/dist/index.d.ts

@@ -22465,6 +22465,12 @@ interface UseEntitlementResult {
  *
  * Returns a reactive entitlement result that can drive access-gate UI.
  *
+ * Until the first check resolves, `allowed` and `denied` are both `false` and
+ * `result` is `null` — the three-state model. Consumers decide from the triple
+ * (`isLoading` / `allowed` / `denied`), never from `denied` alone; the SDK is
+ * fail-closed, so "not yet allowed" is the default. Evaluation is local to the
+ * loaded Playbook — there is no per-check network call.
+ *
  * @example
  * ```tsx
  * function BrandKitSection() {
@@ -22716,9 +22722,13 @@ interface UseCanResult {
     /**
      * `true` when the user may proceed. This is `allowed || limited` (equivalently,
      * not `denied`): a `limited` entitlement still grants access — it just means the
-     * usage/credit balance is running low. Fail-open, matching the SDK: `can` is also
-     * `true` before the check resolves and if the entitlement service is unreachable.
-     * Gate on `!can` to block; never gate on `!allowed` (that would also block
+     * usage/credit balance is running low. Deny-until-ready, matching the SDK's
+     * fail-closed contract: `can` is `false` until the check resolves, and stays
+     * `false` if the check errors. Evaluation is local to the loaded Playbook (no
+     * per-check network call), so the unresolved window is one microtask once
+     * initialization completes; in hosted mode the first load spans the initial
+     * config fetch. Gate paywall UI on `!can && !isLoading` so entitled users never
+     * see an upsell flash; never gate on `!allowed` (that would also block
      * `limited` users who are still entitled).
      */
     can: boolean;
@@ -22727,6 +22737,14 @@ interface UseCanResult {
      * "running low" state). Surface a soft warning while still allowing the action.
      */
     limited: boolean;
+    /**
+     * `true` until the entitlement check first resolves (including while the SDK
+     * initializes), and again while a recheck is in flight. Settles to `false`
+     * once a result — or an error — has landed. Pair with `can`:
+     * `!can && isLoading` is "still deciding"; `!can && !isLoading` is a settled
+     * deny.
+     */
+    isLoading: boolean;
     /**
      * The full entitlement result (`status`, `reason`, `current_tier`, `placement`,
      * …), or `null` until the check resolves — the escape hatch for details beyond
@@ -22738,16 +22756,21 @@ interface UseCanResult {
  * Reactive counterpart to the imperative `rt.can(handle)` — the entitlement check
  * as a `can` question. Takes the entitlement handle positionally (matching
  * `rt.can('handle')`), plus the same options {@link useEntitlement} accepts, and
- * returns a curated `{ can, limited, result }`.
+ * returns a curated `{ can, limited, isLoading, result }`.
+ *
+ * Deny-until-ready: `can` is `false` while the check is unresolved, flipping
+ * within one microtask in local mode once the Playbook is in memory. Use
+ * `isLoading` to distinguish "still deciding" from a settled deny.
  *
- * For the full reactive surface (`allowed` / `denied` / `isLoading` / `error` /
+ * For the full reactive surface (`allowed` / `denied` / `error` /
  * `gatedPlacement` / `recheck`), use {@link useEntitlement} directly.
  *
  * @example
  * ```tsx
  * function BatchExport() {
- *   const { can, limited } = useCan('batch_export');
- *   if (!can) return <UpgradePrompt />;
+ *   const { can, limited, isLoading } = useCan('batch_export');
+ *   if (!can && isLoading) return null;   // still deciding — render nothing yet
+ *   if (!can) return <UpgradePrompt />;   // settled deny
  *   return <BatchExportButton warnLowBalance={limited} />;
  * }
  * ```