@revturbine/sdk 0.2.68 → 0.2.69

package/dist/types/web-sdk/react/useCan.d.ts

@@ -7,9 +7,13 @@ export 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;
@@ -18,6 +22,14 @@ export 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
@@ -29,16 +41,21 @@ export 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} />;
  * }
  * ```

package/dist/types/web-sdk/react/useCan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCan.d.ts","sourceRoot":"","sources":["../../../../react/useCan.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAEzG;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,GAAG,EAAE,OAAO,CAAC;IACb;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,MAAM,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,GAC9C,YAAY,CAGd"}
+{"version":3,"file":"useCan.d.ts","sourceRoot":"","sources":["../../../../react/useCan.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAEzG;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;OAWG;IACH,GAAG,EAAE,OAAO,CAAC;IACb;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,MAAM,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,GAC9C,YAAY,CASd"}

package/dist/types/web-sdk/react/useEntitlement.d.ts

@@ -40,6 +40,12 @@ export 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() {

package/dist/types/web-sdk/react/useEntitlement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useEntitlement.d.ts","sourceRoot":"","sources":["../../../../react/useEntitlement.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,4BAA4B,EAC5B,gCAAgC,EACjC,MAAM,kBAAkB,CAAC;AAM1B,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,OAAO,CAAC,EAAE,4BAA4B,CAAC;IACvC,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,IAAI,CAAC,gCAAgC,EAAE,mBAAmB,CAAC,CAAC;CACpF;AAED,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;IACnB,yCAAyC;IACzC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,kEAAkE;IAClE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,MAAM,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,cAAc,EAAE,eAAe,GAAG,IAAI,CAAC;IACvC,oCAAoC;IACpC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EACN,OAAO,EACP,SAAgB,EAChB,QAAgB,EAChB,oBAAoB,GACrB,EAAE,qBAAqB,GAAG,oBAAoB,CAqD9C"}
+{"version":3,"file":"useEntitlement.d.ts","sourceRoot":"","sources":["../../../../react/useEntitlement.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,4BAA4B,EAC5B,gCAAgC,EACjC,MAAM,kBAAkB,CAAC;AAM1B,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,OAAO,CAAC,EAAE,4BAA4B,CAAC;IACvC,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,IAAI,CAAC,gCAAgC,EAAE,mBAAmB,CAAC,CAAC;CACpF;AAED,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;IACnB,yCAAyC;IACzC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,kEAAkE;IAClE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,MAAM,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,cAAc,EAAE,eAAe,GAAG,IAAI,CAAC;IACvC,oCAAoC;IACpC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EACN,OAAO,EACP,SAAgB,EAChB,QAAgB,EAChB,oBAAoB,GACrB,EAAE,qBAAqB,GAAG,oBAAoB,CAqD9C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revturbine/sdk",
-  "version": "0.2.68",
+  "version": "0.2.69",
   "description": "RevTurbine customer-facing SDK — placement decisioning, entitlement checks, and usage tracking.",
   "type": "module",
   "packageManager": "pnpm@11.12.0",