@kerne/react 0.1.3 → 1.0.0

package/dist/index.d.cts

@@ -3,10 +3,10 @@ import React, { ReactNode, Component, ErrorInfo } from 'react';
 import { KerneConfig, JoinWaitlistParams, ValidateTokenResponse, ValidateCodeResponse } from '@kerne/server';
 export { JoinWaitlistParams, ValidateCodeResponse, ValidateTokenResponse, WaitlistEntry } from '@kerne/server';
 import * as _kerne_types from '@kerne/types';
-import { User, AuthResponse, ActivationContext, AuthConfig, EntitlementCheck, SubscriptionWithPlan, PublicPlan, Entitlements, UsageRecord } from '@kerne/types';
+import { User, AuthResponse, ActivationContext, AuthConfig, EntitlementCheck, SubscriptionWithPlan, Subscription, PublicPlan, Entitlements, UsageRecord } from '@kerne/types';
 export { ActivationContext, AuthConfig, AuthResponse, EntitlementCheck, Entitlements, PublicPlan, Subscription, SubscriptionWithPlan, UsageRecord, User } from '@kerne/types';
-import { D as DeepPartial, K as KerneLocalization } from './i18n-BWTT1DWD.cjs';
-export { d as defaultLocalization } from './i18n-BWTT1DWD.cjs';
+import { D as DeepPartial, K as KerneLocalization } from './i18n-Di5qlnL1.cjs';
+export { d as defaultLocalization } from './i18n-Di5qlnL1.cjs';
 
 interface KerneReactConfig extends Omit<KerneConfig, 'secretKey'> {
     storage?: Storage;
@@ -160,7 +160,7 @@ declare class KerneClient {
      * caught everything and returned `false`) - a 401/500 must not be
      * indistinguishable from a real denial, that's exactly what let the
      * `has_access`/`allowed` mismatch below ship unnoticed. Callers that want
-     * a fail-closed boolean regardless of the reason (e.g. `<Allows>`)
+     * a fail-closed boolean regardless of the reason (e.g. `<Access>`)
      * catch around this themselves.
      */
     allows(featureKey: string, requested?: number): Promise<boolean>;
@@ -177,6 +177,12 @@ declare class KerneClient {
     createPortal(returnUrl?: string): Promise<string>;
     openPortal(returnUrl?: string): Promise<void>;
     getSubscription(productSlug?: string): Promise<SubscriptionWithPlan | null>;
+    /** `immediately: true` ends it now; otherwise cancels at period end (API default). */
+    cancelSubscription(subscriptionId: string, immediately?: boolean): Promise<Subscription>;
+    /** Swaps the plan/price, effective immediately - deferring a downgrade isn't supported yet. */
+    changeSubscriptionPlan(subscriptionId: string, planPriceId: string, options?: {
+        prorationBehavior?: 'none' | 'create_prorations';
+    }): Promise<SubscriptionWithPlan>;
     /** Public pricing data - omit `productIdOrSlug` for the tenant's default product. */
     getPlans(productIdOrSlug?: string): Promise<PublicPlan[]>;
     /** Every entitlement for the current user in one call - for a "your plan" screen. */
@@ -317,6 +323,27 @@ declare function usePortal(): {
     createPortal: (returnUrl?: string) => Promise<string>;
     openPortal: (returnUrl?: string) => Promise<void>;
 };
+/**
+ * Cancels or changes the current scope's own subscription - JWT-scoped like every other hook
+ * here, so this can only ever act on the caller's own subscription (see `SubscriptionCard`).
+ *
+ * @example
+ * ```tsx
+ * const { cancelSubscription, isCanceling } = useCancelSubscription();
+ * <button onClick={() => cancelSubscription(subscriptionId)}>Cancel</button>
+ * ```
+ */
+declare function useCancelSubscription(): {
+    cancelSubscription: (subscriptionId: string, immediately?: boolean) => Promise<_kerne_types.Subscription>;
+    isCanceling: boolean;
+};
+/** Changes the current scope's own subscription to a different plan/price, effective immediately. */
+declare function useChangePlan(): {
+    changePlan: (subscriptionId: string, planPriceId: string, options?: {
+        prorationBehavior?: "none" | "create_prorations";
+    }) => Promise<SubscriptionWithPlan>;
+    isChanging: boolean;
+};
 /**
  * Whether the current scope has access to one feature - the single entry
  * point for a live, per-feature decision. Deliberately not named after what
@@ -359,6 +386,7 @@ declare function useAccess(featureKey: string, requested?: number): {
 declare function useSubscription(productSlug?: string): {
     isActive: boolean;
     planSlug: string | undefined;
+    refetch: () => void;
     subscription: SubscriptionWithPlan | null;
     isLoading: boolean;
     error: Error | null;
@@ -552,24 +580,35 @@ interface EntitlementGuardProps {
      * `UpgradePrompt`, so the whole entitlement surface reads alike.
      */
     featureKey: string;
-    /** Minimum value required (for limit features) */
-    minimum?: number;
+    /**
+     * Units the gated action is about to consume - checked before it runs, not
+     * after. A QUOTA feature with 3 remaining still passes a plain `<Access>`
+     * (>0 left), but fails `requested={5}` up front, so a batch action can be
+     * blocked before the user commits to it instead of after a partial
+     * `consume()` fails mid-way. Omit for a plain yes/no gate.
+     */
+    requested?: number;
     /** Fallback content when entitlement is not met */
     fallback?: ReactNode;
 }
 /**
- * Renders children only when the scope is entitled to a capability. Checks the
- * entitlement itself, never a plan name - a plan can be renamed or restructured
- * without breaking every place that gated on its slug.
+ * Renders children only when the subject is entitled to a capability - and,
+ * with `requested`, entitled to that many units of it right now. Checks the
+ * entitlement itself, never a plan name - a plan can be renamed or
+ * restructured without breaking every place that gated on its slug.
  *
  * @example
  * ```tsx
- * <Allows featureKey="advanced_analytics" fallback={<UpgradePrompt featureKey="advanced_analytics" />}>
+ * <Access featureKey="advanced_analytics" fallback={<UpgradePrompt featureKey="advanced_analytics" />}>
  *   <AnalyticsDashboard />
- * </Allows>
+ * </Access>
+ *
+ * <Access featureKey="ai_credits" requested={5} fallback={<UpgradePrompt reason="Not enough credits for batch processing" />}>
+ *   <BatchProcessButton count={5} />
+ * </Access>
  * ```
  */
-declare function Allows({ children, featureKey, minimum, fallback, }: EntitlementGuardProps): ReactNode;
+declare function Access({ children, featureKey, requested, fallback, }: EntitlementGuardProps): ReactNode;
 interface ProtectedProps {
     children: ReactNode;
     /** Require authentication */
@@ -652,4 +691,4 @@ declare function useKerneError(): {
     clearError: () => void;
 };
 
-export { Allows, AuthLoading, Authenticated, HasSubscription, KerneClient, KerneContext, type KerneError, KerneErrorBoundary, KerneLocalization, KerneProvider, type KerneProviderProps, type KerneReactConfig, Protected, Unauthenticated, useAccess, useAuth, useAuthConfig, useCheckout, useClient, useEntitlements, useInvitation, useKerneError, usePlans, usePortal, useSubscription, useUsage, useUser, useWaitlist };
+export { Access, AuthLoading, Authenticated, HasSubscription, KerneClient, KerneContext, type KerneError, KerneErrorBoundary, KerneLocalization, KerneProvider, type KerneProviderProps, type KerneReactConfig, Protected, Unauthenticated, useAccess, useAuth, useAuthConfig, useCancelSubscription, useChangePlan, useCheckout, useClient, useEntitlements, useInvitation, useKerneError, usePlans, usePortal, useSubscription, useUsage, useUser, useWaitlist };

package/dist/index.d.ts

@@ -3,10 +3,10 @@ import React, { ReactNode, Component, ErrorInfo } from 'react';
 import { KerneConfig, JoinWaitlistParams, ValidateTokenResponse, ValidateCodeResponse } from '@kerne/server';
 export { JoinWaitlistParams, ValidateCodeResponse, ValidateTokenResponse, WaitlistEntry } from '@kerne/server';
 import * as _kerne_types from '@kerne/types';
-import { User, AuthResponse, ActivationContext, AuthConfig, EntitlementCheck, SubscriptionWithPlan, PublicPlan, Entitlements, UsageRecord } from '@kerne/types';
+import { User, AuthResponse, ActivationContext, AuthConfig, EntitlementCheck, SubscriptionWithPlan, Subscription, PublicPlan, Entitlements, UsageRecord } from '@kerne/types';
 export { ActivationContext, AuthConfig, AuthResponse, EntitlementCheck, Entitlements, PublicPlan, Subscription, SubscriptionWithPlan, UsageRecord, User } from '@kerne/types';
-import { D as DeepPartial, K as KerneLocalization } from './i18n-BWTT1DWD.js';
-export { d as defaultLocalization } from './i18n-BWTT1DWD.js';
+import { D as DeepPartial, K as KerneLocalization } from './i18n-Di5qlnL1.js';
+export { d as defaultLocalization } from './i18n-Di5qlnL1.js';
 
 interface KerneReactConfig extends Omit<KerneConfig, 'secretKey'> {
     storage?: Storage;
@@ -160,7 +160,7 @@ declare class KerneClient {
      * caught everything and returned `false`) - a 401/500 must not be
      * indistinguishable from a real denial, that's exactly what let the
      * `has_access`/`allowed` mismatch below ship unnoticed. Callers that want
-     * a fail-closed boolean regardless of the reason (e.g. `<Allows>`)
+     * a fail-closed boolean regardless of the reason (e.g. `<Access>`)
      * catch around this themselves.
      */
     allows(featureKey: string, requested?: number): Promise<boolean>;
@@ -177,6 +177,12 @@ declare class KerneClient {
     createPortal(returnUrl?: string): Promise<string>;
     openPortal(returnUrl?: string): Promise<void>;
     getSubscription(productSlug?: string): Promise<SubscriptionWithPlan | null>;
+    /** `immediately: true` ends it now; otherwise cancels at period end (API default). */
+    cancelSubscription(subscriptionId: string, immediately?: boolean): Promise<Subscription>;
+    /** Swaps the plan/price, effective immediately - deferring a downgrade isn't supported yet. */
+    changeSubscriptionPlan(subscriptionId: string, planPriceId: string, options?: {
+        prorationBehavior?: 'none' | 'create_prorations';
+    }): Promise<SubscriptionWithPlan>;
     /** Public pricing data - omit `productIdOrSlug` for the tenant's default product. */
     getPlans(productIdOrSlug?: string): Promise<PublicPlan[]>;
     /** Every entitlement for the current user in one call - for a "your plan" screen. */
@@ -317,6 +323,27 @@ declare function usePortal(): {
     createPortal: (returnUrl?: string) => Promise<string>;
     openPortal: (returnUrl?: string) => Promise<void>;
 };
+/**
+ * Cancels or changes the current scope's own subscription - JWT-scoped like every other hook
+ * here, so this can only ever act on the caller's own subscription (see `SubscriptionCard`).
+ *
+ * @example
+ * ```tsx
+ * const { cancelSubscription, isCanceling } = useCancelSubscription();
+ * <button onClick={() => cancelSubscription(subscriptionId)}>Cancel</button>
+ * ```
+ */
+declare function useCancelSubscription(): {
+    cancelSubscription: (subscriptionId: string, immediately?: boolean) => Promise<_kerne_types.Subscription>;
+    isCanceling: boolean;
+};
+/** Changes the current scope's own subscription to a different plan/price, effective immediately. */
+declare function useChangePlan(): {
+    changePlan: (subscriptionId: string, planPriceId: string, options?: {
+        prorationBehavior?: "none" | "create_prorations";
+    }) => Promise<SubscriptionWithPlan>;
+    isChanging: boolean;
+};
 /**
  * Whether the current scope has access to one feature - the single entry
  * point for a live, per-feature decision. Deliberately not named after what
@@ -359,6 +386,7 @@ declare function useAccess(featureKey: string, requested?: number): {
 declare function useSubscription(productSlug?: string): {
     isActive: boolean;
     planSlug: string | undefined;
+    refetch: () => void;
     subscription: SubscriptionWithPlan | null;
     isLoading: boolean;
     error: Error | null;
@@ -552,24 +580,35 @@ interface EntitlementGuardProps {
      * `UpgradePrompt`, so the whole entitlement surface reads alike.
      */
     featureKey: string;
-    /** Minimum value required (for limit features) */
-    minimum?: number;
+    /**
+     * Units the gated action is about to consume - checked before it runs, not
+     * after. A QUOTA feature with 3 remaining still passes a plain `<Access>`
+     * (>0 left), but fails `requested={5}` up front, so a batch action can be
+     * blocked before the user commits to it instead of after a partial
+     * `consume()` fails mid-way. Omit for a plain yes/no gate.
+     */
+    requested?: number;
     /** Fallback content when entitlement is not met */
     fallback?: ReactNode;
 }
 /**
- * Renders children only when the scope is entitled to a capability. Checks the
- * entitlement itself, never a plan name - a plan can be renamed or restructured
- * without breaking every place that gated on its slug.
+ * Renders children only when the subject is entitled to a capability - and,
+ * with `requested`, entitled to that many units of it right now. Checks the
+ * entitlement itself, never a plan name - a plan can be renamed or
+ * restructured without breaking every place that gated on its slug.
  *
  * @example
  * ```tsx
- * <Allows featureKey="advanced_analytics" fallback={<UpgradePrompt featureKey="advanced_analytics" />}>
+ * <Access featureKey="advanced_analytics" fallback={<UpgradePrompt featureKey="advanced_analytics" />}>
  *   <AnalyticsDashboard />
- * </Allows>
+ * </Access>
+ *
+ * <Access featureKey="ai_credits" requested={5} fallback={<UpgradePrompt reason="Not enough credits for batch processing" />}>
+ *   <BatchProcessButton count={5} />
+ * </Access>
  * ```
  */
-declare function Allows({ children, featureKey, minimum, fallback, }: EntitlementGuardProps): ReactNode;
+declare function Access({ children, featureKey, requested, fallback, }: EntitlementGuardProps): ReactNode;
 interface ProtectedProps {
     children: ReactNode;
     /** Require authentication */
@@ -652,4 +691,4 @@ declare function useKerneError(): {
     clearError: () => void;
 };
 
-export { Allows, AuthLoading, Authenticated, HasSubscription, KerneClient, KerneContext, type KerneError, KerneErrorBoundary, KerneLocalization, KerneProvider, type KerneProviderProps, type KerneReactConfig, Protected, Unauthenticated, useAccess, useAuth, useAuthConfig, useCheckout, useClient, useEntitlements, useInvitation, useKerneError, usePlans, usePortal, useSubscription, useUsage, useUser, useWaitlist };
+export { Access, AuthLoading, Authenticated, HasSubscription, KerneClient, KerneContext, type KerneError, KerneErrorBoundary, KerneLocalization, KerneProvider, type KerneProviderProps, type KerneReactConfig, Protected, Unauthenticated, useAccess, useAuth, useAuthConfig, useCancelSubscription, useChangePlan, useCheckout, useClient, useEntitlements, useInvitation, useKerneError, usePlans, usePortal, useSubscription, useUsage, useUser, useWaitlist };

package/dist/index.js

@@ -7,6 +7,8 @@ import {
   useAccess,
   useAuth,
   useAuthConfig,
+  useCancelSubscription,
+  useChangePlan,
   useCheckout,
   useClient,
   useEntitlements,
@@ -17,7 +19,7 @@ import {
   useUsage,
   useUser,
   useWaitlist
-} from "./chunk-F6NV76OR.js";
+} from "./chunk-NFJ2S5VJ.js";
 
 // src/components.tsx
 import React from "react";
@@ -47,22 +49,14 @@ function HasSubscription({ children, fallback = null }) {
   if (hasSubscription === null) return null;
   return hasSubscription ? children : fallback;
 }
-function Allows({
+function Access({
   children,
   featureKey,
-  minimum,
+  requested,
   fallback = null
 }) {
-  const client = useClient();
-  const [allowed, setAllowed] = React.useState(null);
-  React.useEffect(() => {
-    client.allows(featureKey, minimum).then((result) => {
-      setAllowed(result);
-    }).catch(() => {
-      setAllowed(false);
-    });
-  }, [client, featureKey, minimum]);
-  if (allowed === null) return null;
+  const { allowed, isLoading } = useAccess(featureKey, requested);
+  if (isLoading) return null;
   return allowed ? children : fallback;
 }
 function Protected({
@@ -77,7 +71,7 @@ function Protected({
     return authFallback;
   }
   if (featureKey) {
-    return /* @__PURE__ */ jsx(Allows, { featureKey, fallback: billingFallback, children });
+    return /* @__PURE__ */ jsx(Access, { featureKey, fallback: billingFallback, children });
   }
   return children;
 }
@@ -158,7 +152,7 @@ function useKerneError() {
   };
 }
 export {
-  Allows,
+  Access,
   AuthLoading,
   Authenticated,
   HasSubscription,
@@ -172,6 +166,8 @@ export {
   useAccess,
   useAuth,
   useAuthConfig,
+  useCancelSubscription,
+  useChangePlan,
   useCheckout,
   useClient,
   useEntitlements,