@revturbine/sdk 0.2.22 → 0.2.24

package/dist/types/web-sdk/placements/AccessGateSurfaceSlot.d.ts

@@ -16,21 +16,36 @@ export type AccessGateSurfaceSlotProps = {
     id: string;
     /** Optional human-readable slot label used for analytics/debugging. */
     name?: string;
+    /**
+     * Shorthand entitlement gate — `can="brand_kit"` is equivalent to
+     * `check={{ entitlement: 'brand_kit' }}`, mirroring the `useCan('brand_kit')`
+     * hook. Merged with `check` when both are supplied. Provide `can` or `check`.
+     */
+    can?: string;
     /**
      * One or more access checks to evaluate before granting access.
      *
      * - `{ entitlement: 'brand_kit' }` — check an entitlement handle.
      * - `{ usage: 'core_credits', threshold: 80 }` — check a usage percentage threshold.
      *
-     * When an array is passed, access is denied if **any** check fails.
+     * When an array is passed, access is denied if **any** check fails. Optional
+     * when `can` is provided.
      */
-    check: AccessGateCheck | AccessGateCheck[];
+    check?: AccessGateCheck | AccessGateCheck[];
     /**
      * Placement to display when access is denied.
      * The slot fetches the gated placement from the decision engine.
      * If no placement matches, `deniedFallback` is shown.
      */
     deniedFallback?: React.ReactNode;
+    /**
+     * Rendered instead of `children` when the entitlement is `limited` — access is
+     * still granted, the usage/credit balance is just running low. Use it for a soft
+     * "running low" state (e.g. the feature plus a warning). When omitted, `limited`
+     * renders `children` normally, since a `limited` user is still entitled; pass
+     * `null` to render nothing.
+     */
+    limitedFallback?: React.ReactNode;
     /** Content to render when access is granted. */
     children: React.ReactNode;
     /**
@@ -52,23 +67,31 @@ export type AccessGateSurfaceSlotProps = {
     style?: React.CSSProperties;
 };
 /**
- * Access-gate surface slot — renders children when entitled, or a gated
- * placement when access is denied.
+ * Merge the `can` shorthand and the `check` prop into the effective check list:
+ * `can="x"` becomes `{ entitlement: 'x' }`, and `check` is appended as-is.
+ * Exported for unit testing.
+ */
+export declare function resolveGateChecks(can: string | undefined, check: AccessGateCheck | AccessGateCheck[] | undefined): AccessGateCheck[];
+/**
+ * Access-gate surface slot — renders children when entitled (allowed *or*
+ * `limited`), or a gated placement when access is `denied`.
  *
- * Checks entitlements and/or usage thresholds. On failure, displays the
- * configured gated placement (or `deniedFallback` if no placement matches).
- * On success, renders `children` unmodified.
+ * Checks entitlements and/or usage thresholds. On denial, displays the configured
+ * gated placement (or `deniedFallback` if no placement matches). On success,
+ * renders `children` — or `limitedFallback` when the entitlement is `limited`.
  *
  * @example
  * ```tsx
- * <AccessGateSurfaceSlot
- *   id="export-gate"
- *   check={{ entitlement: 'mp4_download' }}
- *   deniedFallback={<span>Upgrade to export</span>}
- * >
+ * // `can` shorthand — mirrors useCan('mp4_download')
+ * <AccessGateSurfaceSlot id="export-gate" can="mp4_download" deniedFallback={<span>Upgrade to export</span>}>
  *   <ExportButton />
  * </AccessGateSurfaceSlot>
  *
+ * // soft-warn while still granting access when the balance runs low
+ * <AccessGateSurfaceSlot id="credits-gate" can="core_credits" limitedFallback={<LowBalanceNotice />}>
+ *   <RecordButton />
+ * </AccessGateSurfaceSlot>
+ *
  * <AccessGateSurfaceSlot
  *   id="usage-gate"
  *   check={[
@@ -81,7 +104,7 @@ export type AccessGateSurfaceSlotProps = {
  * </AccessGateSurfaceSlot>
  * ```
  */
-export declare function AccessGateSurfaceSlot({ id, name, check, children, deniedFallback, surfaceTemplateIds, metadata, onDenied, ...options }: AccessGateSurfaceSlotProps): React.JSX.Element | null;
+export declare function AccessGateSurfaceSlot({ id, name, can, check, children, deniedFallback, limitedFallback, surfaceTemplateIds, metadata, onDenied, ...options }: AccessGateSurfaceSlotProps): React.JSX.Element | null;
 export declare namespace AccessGateSurfaceSlot {
     var displayName: string;
 }

package/dist/types/web-sdk/placements/AccessGateSurfaceSlot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AccessGateSurfaceSlot.d.ts","sourceRoot":"","sources":["../../../../placements/AccessGateSurfaceSlot.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAkB,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EACV,qBAAqB,EACrB,4BAA4B,EAC5B,oCAAoC,EAEpC,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAEtE,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAItC,MAAM,MAAM,eAAe,GACvB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,4BAA4B,CAAA;CAAE,GAC/D;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,MAAM,MAAM,0BAA0B,GAAG;IACvC,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;;OAOG;IACH,KAAK,EAAE,eAAe,GAAG,eAAe,EAAE,CAAC;IAE3C;;;;OAIG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAEjC,gDAAgD;IAChD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAE1B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,SAAS,CAAC,EAAE,oCAAoC,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACnD,eAAe,CAAC,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC/C,sDAAsD;IACtD,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,EAAE,EACF,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,cAAqB,EACrB,kBAAkB,EAClB,QAAQ,EACR,QAAQ,EACR,GAAG,OAAO,EACX,EAAE,0BAA0B,4BAyE5B;yBAnFe,qBAAqB"}
+{"version":3,"file":"AccessGateSurfaceSlot.d.ts","sourceRoot":"","sources":["../../../../placements/AccessGateSurfaceSlot.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAkB,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EACV,qBAAqB,EACrB,4BAA4B,EAC5B,oCAAoC,EAEpC,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAEtE,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAItC,MAAM,MAAM,eAAe,GACvB;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,4BAA4B,CAAA;CAAE,GAC/D;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,MAAM,MAAM,0BAA0B,GAAG;IACvC,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,eAAe,GAAG,eAAe,EAAE,CAAC;IAE5C;;;;OAIG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAEjC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAElC,gDAAgD;IAChD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAE1B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,SAAS,CAAC,EAAE,oCAAoC,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACnD,eAAe,CAAC,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC/C,sDAAsD;IACtD,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;CAC7B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,KAAK,EAAE,eAAe,GAAG,eAAe,EAAE,GAAG,SAAS,GACrD,eAAe,EAAE,CAKnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,EAAE,EACF,IAAI,EACJ,GAAG,EACH,KAAK,EACL,QAAQ,EACR,cAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,QAAQ,EACR,QAAQ,EACR,GAAG,OAAO,EACX,EAAE,0BAA0B,4BA+E5B;yBA3Fe,qBAAqB"}

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

@@ -1,22 +1,47 @@
 import { type UseEntitlementOptions, type UseEntitlementResult } from './useEntitlement';
 /**
- * Verb-parity alias of {@link useEntitlement} — the reactive counterpart to the
- * imperative `rt.can(handle)`. Takes the entitlement handle positionally (matching
+ * Result of {@link useCan} — the entitlement check reduced to the shape a `can`
+ * question actually needs.
+ */
+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
+     * `limited` users who are still entitled).
+     */
+    can: boolean;
+    /**
+     * `true` when access is granted but the balance is approaching its limit (the
+     * "running low" state). Surface a soft warning while still allowing the action.
+     */
+    limited: boolean;
+    /**
+     * The full entitlement result (`status`, `reason`, `current_tier`, `placement`,
+     * …), or `null` until the check resolves — the escape hatch for details beyond
+     * `can` / `limited`.
+     */
+    result: UseEntitlementResult['result'];
+}
+/**
+ * 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 the identical reactive result (`allowed` / `denied` / `limited` /
- * `result` / `recheck` / …).
+ * returns a curated `{ can, limited, result }`.
  *
- * Use this when you want the hook name to read like the `can` verb; it is a thin
- * wrapper with no behavioral difference from `useEntitlement({ handle })`.
+ * For the full reactive surface (`allowed` / `denied` / `isLoading` / `error` /
+ * `gatedPlacement` / `recheck`), use {@link useEntitlement} directly.
  *
  * @example
  * ```tsx
- * function BrandKitSection() {
- *   const { allowed, denied, result } = useCan('brand_kit');
- *   if (denied) return <UpgradePrompt reason={result?.reason} />;
- *   return <BrandKitEditor />;
+ * function BatchExport() {
+ *   const { can, limited } = useCan('batch_export');
+ *   if (!can) return <UpgradePrompt />;
+ *   return <BatchExportButton warnLowBalance={limited} />;
  * }
  * ```
  */
-export declare function useCan(handle: string, options?: Omit<UseEntitlementOptions, 'handle'>): UseEntitlementResult;
+export declare function useCan(handle: string, options?: Omit<UseEntitlementOptions, 'handle'>): UseCanResult;
 //# sourceMappingURL=useCan.d.ts.map

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;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,GAC9C,oBAAoB,CAEtB"}
+{"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revturbine/sdk",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "description": "RevTurbine customer-facing SDK — placement decisioning, entitlement checks, and usage tracking.",
   "type": "module",
   "exports": {