@kerne/react 1.0.0 → 1.2.0

package/dist/{chunk-NFJ2S5VJ.js → chunk-IHNWY4ML.js}

@@ -194,6 +194,11 @@ var defaultLocalization = {
     changePlan: "Change plan",
     current: "Current",
     switchTo: "Switch",
+    switching: "Switching...",
+    switchConfirmTitle: "Switch to {plan}?",
+    switchConfirmBody: "This applies right away, and your next invoice reflects the price difference for the rest of this period.",
+    switchConfirmButton: "Yes, switch",
+    switchConfirmDismiss: "Never mind",
     noPlans: "No other plans are available right now.",
     notOnInterval: "Not available on this interval",
     loadFailed: "Could not load your plan right now.",
@@ -373,6 +378,11 @@ var KerneClient = class {
       baseUrl: this.baseUrl,
       appId: this.appId,
       timeout: config.timeout,
+      // Forwarded so <KerneProvider defaultRedirects={...} headers={...}> is
+      // actually honored - the type inherited them from KerneConfig, but the
+      // client was dropping both silently.
+      headers: config.headers,
+      defaultRedirects: config.defaultRedirects,
       onUnauthorized: () => {
         if (process.env.NODE_ENV === "development") {
           console.warn("[Kerne] 401 received. Auto-logout disabled in dev.");
@@ -690,8 +700,9 @@ var KerneClient = class {
     return response;
   }
   // Cross-Origin Session Handoff
-  // For apps/portal (auth hosted on its own origin): call this at the end of
-  // a successful auth flow (login/magic-link/register/activation) instead of
+  // For a hosted auth origin (auth on its own domain, separate from the
+  // tenant's app): call this at the end of a successful auth flow
+  // (login/magic-link/register/activation) instead of
   // a plain `window.location.href = url` whenever `url` isn't same-origin -
   // the exchange on the other end is picked up automatically by
   // `exchangeHandoffOnLoad()`, no code required on the tenant app's side.
@@ -743,6 +754,24 @@ var KerneClient = class {
   async check(featureKey, requested) {
     return this.kerne.check(featureKey, { requested });
   }
+  /** Atomically check a QUOTA limit and commit the consumption. Reports for the signed-in subject. */
+  async consume(featureKey, params) {
+    return this.kerne.consume(featureKey, params);
+  }
+  /** Report usage without a limit check, for the signed-in subject. See `reportUsageBatch()` for many at once. */
+  async reportUsage(featureKey, params) {
+    return this.kerne.reportUsage(featureKey, { subject: this.requireUserId(), ...params });
+  }
+  /** Several usage events in one request instead of one call each - kills the manual request staggering. */
+  async reportUsageBatch(events) {
+    const subject = this.requireUserId();
+    return this.kerne.reportUsageBatch(events.map((e) => ({ subject, ...e })));
+  }
+  requireUserId() {
+    const id = this.user?.id;
+    if (!id) throw new Error("reportUsage requires a signed-in user; none is loaded yet.");
+    return id;
+  }
   async createCheckout(planPriceId, options) {
     const { url } = await this.kerne.billing.checkout(planPriceId, options);
     return url;
@@ -925,7 +954,7 @@ function useAuth() {
       (token2, password) => client.completeActivation(token2, password),
       [client]
     ),
-    // Cross-origin handoff (apps/portal -> tenant app_url) - see redirectWithSession on KerneClient.
+    // Cross-origin handoff (hosted auth origin -> tenant app_url) - see redirectWithSession on KerneClient.
     redirectWithSession: useCallback2((url) => client.redirectWithSession(url), [client])
   };
 }
@@ -981,6 +1010,63 @@ function useChangePlan() {
   );
   return { changePlan, isChanging };
 }
+function usePlanSwitch(subscription, refetchSubscription, options) {
+  const { openCheckout } = useCheckout();
+  const { changePlan } = useChangePlan();
+  const [pending, setPending] = useState(null);
+  const [switching, setSwitching] = useState(false);
+  const [switchError, setSwitchError] = useState(null);
+  const [checkoutPriceId, setCheckoutPriceId] = useState(null);
+  const [checkoutError, setCheckoutError] = useState(null);
+  const successUrl = options?.successUrl;
+  const cancelUrl = options?.cancelUrl;
+  const selectPlan = useCallback2(
+    async (plan, price) => {
+      if (subscription) {
+        setSwitchError(null);
+        setPending({ plan, price });
+        return;
+      }
+      setCheckoutError(null);
+      setCheckoutPriceId(price.id);
+      try {
+        await openCheckout(price.id, { successUrl, cancelUrl });
+      } catch (e) {
+        setCheckoutError(e);
+        setCheckoutPriceId(null);
+      }
+    },
+    [subscription, openCheckout, successUrl, cancelUrl]
+  );
+  const confirmSwitch = useCallback2(async () => {
+    if (!pending || !subscription) return;
+    setSwitching(true);
+    setSwitchError(null);
+    try {
+      await changePlan(subscription.id, pending.price.id);
+      setPending(null);
+      refetchSubscription();
+    } catch (e) {
+      setSwitchError(e);
+    } finally {
+      setSwitching(false);
+    }
+  }, [pending, subscription, changePlan, refetchSubscription]);
+  const dismissSwitch = useCallback2(() => {
+    setPending(null);
+    setSwitchError(null);
+  }, []);
+  return {
+    pending,
+    switching,
+    switchError,
+    checkoutPriceId,
+    checkoutError,
+    selectPlan,
+    confirmSwitch,
+    dismissSwitch
+  };
+}
 function useAccess(featureKey, requested) {
   const client = useClient();
   const [state, setState] = useState({
@@ -1145,6 +1231,23 @@ function useUsage(featureKey) {
   }, [client, featureKey]);
   return state;
 }
+function useReportUsage() {
+  const client = useClient();
+  return {
+    consume: useCallback2(
+      (featureKey, params) => client.consume(featureKey, params),
+      [client]
+    ),
+    report: useCallback2(
+      (featureKey, params) => client.reportUsage(featureKey, params),
+      [client]
+    ),
+    reportBatch: useCallback2(
+      (events) => client.reportUsageBatch(events),
+      [client]
+    )
+  };
+}
 function useWaitlist() {
   const client = useClient();
   return {
@@ -1210,12 +1313,14 @@ export {
   usePortal,
   useCancelSubscription,
   useChangePlan,
+  usePlanSwitch,
   useAccess,
   useSubscription,
   usePlans,
   useAuthConfig,
   useEntitlements,
   useUsage,
+  useReportUsage,
   useWaitlist,
   useInvitation,
   useUser

package/dist/{chunk-IMZFZ3P5.cjs → chunk-N6VPGJ36.cjs}

@@ -194,6 +194,11 @@ var defaultLocalization = {
     changePlan: "Change plan",
     current: "Current",
     switchTo: "Switch",
+    switching: "Switching...",
+    switchConfirmTitle: "Switch to {plan}?",
+    switchConfirmBody: "This applies right away, and your next invoice reflects the price difference for the rest of this period.",
+    switchConfirmButton: "Yes, switch",
+    switchConfirmDismiss: "Never mind",
     noPlans: "No other plans are available right now.",
     notOnInterval: "Not available on this interval",
     loadFailed: "Could not load your plan right now.",
@@ -373,6 +378,11 @@ var KerneClient = (_class = class {
       baseUrl: this.baseUrl,
       appId: this.appId,
       timeout: config.timeout,
+      // Forwarded so <KerneProvider defaultRedirects={...} headers={...}> is
+      // actually honored - the type inherited them from KerneConfig, but the
+      // client was dropping both silently.
+      headers: config.headers,
+      defaultRedirects: config.defaultRedirects,
       onUnauthorized: () => {
         if (process.env.NODE_ENV === "development") {
           console.warn("[Kerne] 401 received. Auto-logout disabled in dev.");
@@ -690,8 +700,9 @@ var KerneClient = (_class = class {
     return response;
   }
   // Cross-Origin Session Handoff
-  // For apps/portal (auth hosted on its own origin): call this at the end of
-  // a successful auth flow (login/magic-link/register/activation) instead of
+  // For a hosted auth origin (auth on its own domain, separate from the
+  // tenant's app): call this at the end of a successful auth flow
+  // (login/magic-link/register/activation) instead of
   // a plain `window.location.href = url` whenever `url` isn't same-origin -
   // the exchange on the other end is picked up automatically by
   // `exchangeHandoffOnLoad()`, no code required on the tenant app's side.
@@ -743,6 +754,24 @@ var KerneClient = (_class = class {
   async check(featureKey, requested) {
     return this.kerne.check(featureKey, { requested });
   }
+  /** Atomically check a QUOTA limit and commit the consumption. Reports for the signed-in subject. */
+  async consume(featureKey, params) {
+    return this.kerne.consume(featureKey, params);
+  }
+  /** Report usage without a limit check, for the signed-in subject. See `reportUsageBatch()` for many at once. */
+  async reportUsage(featureKey, params) {
+    return this.kerne.reportUsage(featureKey, { subject: this.requireUserId(), ...params });
+  }
+  /** Several usage events in one request instead of one call each - kills the manual request staggering. */
+  async reportUsageBatch(events) {
+    const subject = this.requireUserId();
+    return this.kerne.reportUsageBatch(events.map((e) => ({ subject, ...e })));
+  }
+  requireUserId() {
+    const id = _optionalChain([this, 'access', _21 => _21.user, 'optionalAccess', _22 => _22.id]);
+    if (!id) throw new Error("reportUsage requires a signed-in user; none is loaded yet.");
+    return id;
+  }
   async createCheckout(planPriceId, options) {
     const { url } = await this.kerne.billing.checkout(planPriceId, options);
     return url;
@@ -824,7 +853,7 @@ function KerneProvider({ children, localization, ...config }) {
   }, [config.appId, config.baseUrl]);
   _react.useEffect.call(void 0, () => {
     return () => {
-      _optionalChain([client, 'access', _21 => _21.cancelRefresh, 'optionalCall', _22 => _22()]);
+      _optionalChain([client, 'access', _23 => _23.cancelRefresh, 'optionalCall', _24 => _24()]);
     };
   }, [client]);
   const l10n = _react.useMemo.call(void 0, () => mergeLocalization(localization), [localization]);
@@ -925,7 +954,7 @@ function useAuth() {
       (token2, password) => client.completeActivation(token2, password),
       [client]
     ),
-    // Cross-origin handoff (apps/portal -> tenant app_url) - see redirectWithSession on KerneClient.
+    // Cross-origin handoff (hosted auth origin -> tenant app_url) - see redirectWithSession on KerneClient.
     redirectWithSession: _react.useCallback.call(void 0, (url) => client.redirectWithSession(url), [client])
   };
 }
@@ -981,6 +1010,63 @@ function useChangePlan() {
   );
   return { changePlan, isChanging };
 }
+function usePlanSwitch(subscription, refetchSubscription, options) {
+  const { openCheckout } = useCheckout();
+  const { changePlan } = useChangePlan();
+  const [pending, setPending] = _react.useState.call(void 0, null);
+  const [switching, setSwitching] = _react.useState.call(void 0, false);
+  const [switchError, setSwitchError] = _react.useState.call(void 0, null);
+  const [checkoutPriceId, setCheckoutPriceId] = _react.useState.call(void 0, null);
+  const [checkoutError, setCheckoutError] = _react.useState.call(void 0, null);
+  const successUrl = _optionalChain([options, 'optionalAccess', _25 => _25.successUrl]);
+  const cancelUrl = _optionalChain([options, 'optionalAccess', _26 => _26.cancelUrl]);
+  const selectPlan = _react.useCallback.call(void 0, 
+    async (plan, price) => {
+      if (subscription) {
+        setSwitchError(null);
+        setPending({ plan, price });
+        return;
+      }
+      setCheckoutError(null);
+      setCheckoutPriceId(price.id);
+      try {
+        await openCheckout(price.id, { successUrl, cancelUrl });
+      } catch (e) {
+        setCheckoutError(e);
+        setCheckoutPriceId(null);
+      }
+    },
+    [subscription, openCheckout, successUrl, cancelUrl]
+  );
+  const confirmSwitch = _react.useCallback.call(void 0, async () => {
+    if (!pending || !subscription) return;
+    setSwitching(true);
+    setSwitchError(null);
+    try {
+      await changePlan(subscription.id, pending.price.id);
+      setPending(null);
+      refetchSubscription();
+    } catch (e) {
+      setSwitchError(e);
+    } finally {
+      setSwitching(false);
+    }
+  }, [pending, subscription, changePlan, refetchSubscription]);
+  const dismissSwitch = _react.useCallback.call(void 0, () => {
+    setPending(null);
+    setSwitchError(null);
+  }, []);
+  return {
+    pending,
+    switching,
+    switchError,
+    checkoutPriceId,
+    checkoutError,
+    selectPlan,
+    confirmSwitch,
+    dismissSwitch
+  };
+}
 function useAccess(featureKey, requested) {
   const client = useClient();
   const [state, setState] = _react.useState.call(void 0, {
@@ -1040,8 +1126,8 @@ function useSubscription(productSlug) {
     setState((prev) => ({ ...prev, isLoading: true }));
     fetchOnce({ current: true });
   }, [fetchOnce]);
-  const isActive = _optionalChain([state, 'access', _23 => _23.subscription, 'optionalAccess', _24 => _24.status]) === "ACTIVE" || _optionalChain([state, 'access', _25 => _25.subscription, 'optionalAccess', _26 => _26.status]) === "TRIALING";
-  const planSlug = _optionalChain([state, 'access', _27 => _27.subscription, 'optionalAccess', _28 => _28.plan, 'optionalAccess', _29 => _29.slug]);
+  const isActive = _optionalChain([state, 'access', _27 => _27.subscription, 'optionalAccess', _28 => _28.status]) === "ACTIVE" || _optionalChain([state, 'access', _29 => _29.subscription, 'optionalAccess', _30 => _30.status]) === "TRIALING";
+  const planSlug = _optionalChain([state, 'access', _31 => _31.subscription, 'optionalAccess', _32 => _32.plan, 'optionalAccess', _33 => _33.slug]);
   return {
     ...state,
     isActive,
@@ -1145,6 +1231,23 @@ function useUsage(featureKey) {
   }, [client, featureKey]);
   return state;
 }
+function useReportUsage() {
+  const client = useClient();
+  return {
+    consume: _react.useCallback.call(void 0, 
+      (featureKey, params) => client.consume(featureKey, params),
+      [client]
+    ),
+    report: _react.useCallback.call(void 0, 
+      (featureKey, params) => client.reportUsage(featureKey, params),
+      [client]
+    ),
+    reportBatch: _react.useCallback.call(void 0, 
+      (events) => client.reportUsageBatch(events),
+      [client]
+    )
+  };
+}
 function useWaitlist() {
   const client = useClient();
   return {
@@ -1189,9 +1292,9 @@ function useUser() {
     update: updateProfile,
     // Computed properties
     fullName: user ? `${user.first_name || ""} ${user.last_name || ""}`.trim() : null,
-    initials: user ? `${_optionalChain([user, 'access', _30 => _30.first_name, 'optionalAccess', _31 => _31[0]]) || ""}${_optionalChain([user, 'access', _32 => _32.last_name, 'optionalAccess', _33 => _33[0]]) || ""}`.toUpperCase() : null,
-    email: _optionalChain([user, 'optionalAccess', _34 => _34.email]) || null,
-    emailVerified: _optionalChain([user, 'optionalAccess', _35 => _35.email_verified]) || false
+    initials: user ? `${_optionalChain([user, 'access', _34 => _34.first_name, 'optionalAccess', _35 => _35[0]]) || ""}${_optionalChain([user, 'access', _36 => _36.last_name, 'optionalAccess', _37 => _37[0]]) || ""}`.toUpperCase() : null,
+    email: _optionalChain([user, 'optionalAccess', _38 => _38.email]) || null,
+    emailVerified: _optionalChain([user, 'optionalAccess', _39 => _39.email_verified]) || false
   };
 }
 
@@ -1219,4 +1322,6 @@ function useUser() {
 
 
 
-exports.defaultLocalization = defaultLocalization; exports.useLocalization = useLocalization; exports.fill = fill; exports.fillNode = fillNode; exports.useErrorResolver = useErrorResolver; exports.KerneClient = KerneClient; exports.KerneContext = KerneContext; exports.KerneProvider = KerneProvider; exports.useClient = useClient; exports.useAuth = useAuth; exports.useCheckout = useCheckout; exports.usePortal = usePortal; exports.useCancelSubscription = useCancelSubscription; exports.useChangePlan = useChangePlan; exports.useAccess = useAccess; exports.useSubscription = useSubscription; exports.usePlans = usePlans; exports.useAuthConfig = useAuthConfig; exports.useEntitlements = useEntitlements; exports.useUsage = useUsage; exports.useWaitlist = useWaitlist; exports.useInvitation = useInvitation; exports.useUser = useUser;
+
+
+exports.defaultLocalization = defaultLocalization; exports.useLocalization = useLocalization; exports.fill = fill; exports.fillNode = fillNode; exports.useErrorResolver = useErrorResolver; exports.KerneClient = KerneClient; exports.KerneContext = KerneContext; exports.KerneProvider = KerneProvider; exports.useClient = useClient; exports.useAuth = useAuth; exports.useCheckout = useCheckout; exports.usePortal = usePortal; exports.useCancelSubscription = useCancelSubscription; exports.useChangePlan = useChangePlan; exports.usePlanSwitch = usePlanSwitch; exports.useAccess = useAccess; exports.useSubscription = useSubscription; exports.usePlans = usePlans; exports.useAuthConfig = useAuthConfig; exports.useEntitlements = useEntitlements; exports.useUsage = useUsage; exports.useReportUsage = useReportUsage; exports.useWaitlist = useWaitlist; exports.useInvitation = useInvitation; exports.useUser = useUser;

package/dist/{i18n-Di5qlnL1.d.cts → i18n-CXEhPK58.d.cts}

@@ -195,6 +195,11 @@ interface KerneLocalization {
         changePlan: string;
         current: string;
         switchTo: string;
+        switching: string;
+        switchConfirmTitle: string;
+        switchConfirmBody: string;
+        switchConfirmButton: string;
+        switchConfirmDismiss: string;
         noPlans: string;
         notOnInterval: string;
         loadFailed: string;
@@ -268,7 +273,7 @@ interface KerneLocalization {
         signOut: string;
     };
     /**
-     * Keyed by the API's stable ErrorCode (see packages/core/src/errors).
+     * Keyed by the API's stable ErrorCode.
      * Anything absent falls back to `generic` - never to the raw server message,
      * which is written for an integrator and is always English.
      */

package/dist/{i18n-Di5qlnL1.d.ts → i18n-CXEhPK58.d.ts}

@@ -195,6 +195,11 @@ interface KerneLocalization {
         changePlan: string;
         current: string;
         switchTo: string;
+        switching: string;
+        switchConfirmTitle: string;
+        switchConfirmBody: string;
+        switchConfirmButton: string;
+        switchConfirmDismiss: string;
         noPlans: string;
         notOnInterval: string;
         loadFailed: string;
@@ -268,7 +273,7 @@ interface KerneLocalization {
         signOut: string;
     };
     /**
-     * Keyed by the API's stable ErrorCode (see packages/core/src/errors).
+     * Keyed by the API's stable ErrorCode.
      * Anything absent falls back to `generic` - never to the raw server message,
      * which is written for an integrator and is always English.
      */

package/dist/index.cjs

@@ -19,25 +19,27 @@
 
 
 
-var _chunkIMZFZ3P5cjs = require('./chunk-IMZFZ3P5.cjs');
+
+
+var _chunkN6VPGJ36cjs = require('./chunk-N6VPGJ36.cjs');
 
 // src/components.tsx
 var _react = require('react'); var _react2 = _interopRequireDefault(_react);
 var _jsxruntime = require('react/jsx-runtime');
 function Authenticated({ children, fallback = null }) {
-  const { isAuthenticated } = _chunkIMZFZ3P5cjs.useAuth.call(void 0, );
+  const { isAuthenticated } = _chunkN6VPGJ36cjs.useAuth.call(void 0, );
   return isAuthenticated ? children : fallback;
 }
 function Unauthenticated({ children, fallback = null }) {
-  const { isAuthenticated } = _chunkIMZFZ3P5cjs.useAuth.call(void 0, );
+  const { isAuthenticated } = _chunkN6VPGJ36cjs.useAuth.call(void 0, );
   return !isAuthenticated ? children : fallback;
 }
 function AuthLoading({ children }) {
-  const client = _chunkIMZFZ3P5cjs.useClient.call(void 0, );
+  const client = _chunkN6VPGJ36cjs.useClient.call(void 0, );
   return client.isLoading ? children : null;
 }
 function HasSubscription({ children, fallback = null }) {
-  const client = _chunkIMZFZ3P5cjs.useClient.call(void 0, );
+  const client = _chunkN6VPGJ36cjs.useClient.call(void 0, );
   const [hasSubscription, setHasSubscription] = _react2.default.useState(null);
   _react2.default.useEffect(() => {
     client.getSubscription().then((sub) => {
@@ -55,7 +57,7 @@ function Access({
   requested,
   fallback = null
 }) {
-  const { allowed, isLoading } = _chunkIMZFZ3P5cjs.useAccess.call(void 0, featureKey, requested);
+  const { allowed, isLoading } = _chunkN6VPGJ36cjs.useAccess.call(void 0, featureKey, requested);
   if (isLoading) return null;
   return allowed ? children : fallback;
 }
@@ -66,7 +68,7 @@ function Protected({
   authFallback = null,
   billingFallback = null
 }) {
-  const { isAuthenticated } = _chunkIMZFZ3P5cjs.useAuth.call(void 0, );
+  const { isAuthenticated } = _chunkN6VPGJ36cjs.useAuth.call(void 0, );
   if (auth && !isAuthenticated) {
     return authFallback;
   }
@@ -179,4 +181,6 @@ function useKerneError() {
 
 
 
-exports.Access = Access; exports.AuthLoading = AuthLoading; exports.Authenticated = Authenticated; exports.HasSubscription = HasSubscription; exports.KerneClient = _chunkIMZFZ3P5cjs.KerneClient; exports.KerneContext = _chunkIMZFZ3P5cjs.KerneContext; exports.KerneErrorBoundary = KerneErrorBoundary; exports.KerneProvider = _chunkIMZFZ3P5cjs.KerneProvider; exports.Protected = Protected; exports.Unauthenticated = Unauthenticated; exports.defaultLocalization = _chunkIMZFZ3P5cjs.defaultLocalization; exports.useAccess = _chunkIMZFZ3P5cjs.useAccess; exports.useAuth = _chunkIMZFZ3P5cjs.useAuth; exports.useAuthConfig = _chunkIMZFZ3P5cjs.useAuthConfig; exports.useCancelSubscription = _chunkIMZFZ3P5cjs.useCancelSubscription; exports.useChangePlan = _chunkIMZFZ3P5cjs.useChangePlan; exports.useCheckout = _chunkIMZFZ3P5cjs.useCheckout; exports.useClient = _chunkIMZFZ3P5cjs.useClient; exports.useEntitlements = _chunkIMZFZ3P5cjs.useEntitlements; exports.useInvitation = _chunkIMZFZ3P5cjs.useInvitation; exports.useKerneError = useKerneError; exports.usePlans = _chunkIMZFZ3P5cjs.usePlans; exports.usePortal = _chunkIMZFZ3P5cjs.usePortal; exports.useSubscription = _chunkIMZFZ3P5cjs.useSubscription; exports.useUsage = _chunkIMZFZ3P5cjs.useUsage; exports.useUser = _chunkIMZFZ3P5cjs.useUser; exports.useWaitlist = _chunkIMZFZ3P5cjs.useWaitlist;
+
+
+exports.Access = Access; exports.AuthLoading = AuthLoading; exports.Authenticated = Authenticated; exports.HasSubscription = HasSubscription; exports.KerneClient = _chunkN6VPGJ36cjs.KerneClient; exports.KerneContext = _chunkN6VPGJ36cjs.KerneContext; exports.KerneErrorBoundary = KerneErrorBoundary; exports.KerneProvider = _chunkN6VPGJ36cjs.KerneProvider; exports.Protected = Protected; exports.Unauthenticated = Unauthenticated; exports.defaultLocalization = _chunkN6VPGJ36cjs.defaultLocalization; exports.useAccess = _chunkN6VPGJ36cjs.useAccess; exports.useAuth = _chunkN6VPGJ36cjs.useAuth; exports.useAuthConfig = _chunkN6VPGJ36cjs.useAuthConfig; exports.useCancelSubscription = _chunkN6VPGJ36cjs.useCancelSubscription; exports.useChangePlan = _chunkN6VPGJ36cjs.useChangePlan; exports.useCheckout = _chunkN6VPGJ36cjs.useCheckout; exports.useClient = _chunkN6VPGJ36cjs.useClient; exports.useEntitlements = _chunkN6VPGJ36cjs.useEntitlements; exports.useInvitation = _chunkN6VPGJ36cjs.useInvitation; exports.useKerneError = useKerneError; exports.usePlanSwitch = _chunkN6VPGJ36cjs.usePlanSwitch; exports.usePlans = _chunkN6VPGJ36cjs.usePlans; exports.usePortal = _chunkN6VPGJ36cjs.usePortal; exports.useReportUsage = _chunkN6VPGJ36cjs.useReportUsage; exports.useSubscription = _chunkN6VPGJ36cjs.useSubscription; exports.useUsage = _chunkN6VPGJ36cjs.useUsage; exports.useUser = _chunkN6VPGJ36cjs.useUser; exports.useWaitlist = _chunkN6VPGJ36cjs.useWaitlist;

package/dist/index.d.cts

@@ -1,12 +1,12 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode, Component, ErrorInfo } from 'react';
-import { KerneConfig, JoinWaitlistParams, ValidateTokenResponse, ValidateCodeResponse } from '@kerne/server';
+import { KerneConfig, ConsumeParams, ReportUsageParams, ReportUsageBatchEvent, BatchUsageResult, 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, 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-Di5qlnL1.cjs';
-export { d as defaultLocalization } from './i18n-Di5qlnL1.cjs';
+import { User, AuthResponse, ActivationContext, AuthConfig, EntitlementCheck, UsageRecord, SubscriptionWithPlan, Subscription, PublicPlan, Entitlements, PublicPlanPrice } from '@kerne/types';
+export { ActivationContext, AuthConfig, AuthResponse, BatchUsageResult, EntitlementCheck, Entitlements, PublicPlan, Subscription, SubscriptionWithPlan, UsageRecord, User, ValidationFieldError } from '@kerne/types';
+import { D as DeepPartial, K as KerneLocalization } from './i18n-CXEhPK58.cjs';
+export { d as defaultLocalization } from './i18n-CXEhPK58.cjs';
 
 interface KerneReactConfig extends Omit<KerneConfig, 'secretKey'> {
     storage?: Storage;
@@ -166,6 +166,13 @@ declare class KerneClient {
     allows(featureKey: string, requested?: number): Promise<boolean>;
     /** Full entitlement detail (limit/used/remaining/overage) - use `allows()` for a plain boolean. */
     check(featureKey: string, requested?: number): Promise<EntitlementCheck>;
+    /** Atomically check a QUOTA limit and commit the consumption. Reports for the signed-in subject. */
+    consume(featureKey: string, params?: Omit<ConsumeParams, 'subject'>): Promise<EntitlementCheck>;
+    /** Report usage without a limit check, for the signed-in subject. See `reportUsageBatch()` for many at once. */
+    reportUsage(featureKey: string, params?: Omit<ReportUsageParams, 'subject'>): Promise<UsageRecord>;
+    /** Several usage events in one request instead of one call each - kills the manual request staggering. */
+    reportUsageBatch(events: Array<Omit<ReportUsageBatchEvent, 'subject'>>): Promise<BatchUsageResult[]>;
+    private requireUserId;
     createCheckout(planPriceId: string, options?: {
         successUrl?: string;
         cancelUrl?: string;
@@ -344,6 +351,51 @@ declare function useChangePlan(): {
     }) => Promise<SubscriptionWithPlan>;
     isChanging: boolean;
 };
+interface PlanSwitchTarget {
+    plan: PublicPlan;
+    price: PublicPlanPrice;
+}
+/**
+ * The decision every "pick a plan" surface needs, shared so it is only
+ * decided once: an existing subscriber switching plans has to swap in place
+ * (`changePlanPrice`), never start a fresh checkout - Stripe/Polar don't know
+ * about the subscription already on file, so a new checkout session creates
+ * a SECOND, independent one instead of replacing it. The old one stays live
+ * and billed at the provider while Kerne only ever tracks the new one. A
+ * first-time subscriber has nothing to swap, so that case goes straight to
+ * checkout, same as before.
+ *
+ * The switch is staged rather than applied on `selectPlan` alone - it bills
+ * immediately on confirmation (unlike checkout, which only starts billing
+ * once the provider's own page is completed), so the caller's UI gets a
+ * chance to say so before `confirmSwitch()` commits it.
+ *
+ * @param subscription the subject's current subscription, or null - pass
+ * what `useSubscription()` already returned rather than fetching it again
+ * here, so a page showing the current plan and this hook always agree.
+ * @param refetchSubscription called after a successful switch, typically
+ * that same `useSubscription()` call's own `refetch()`.
+ *
+ * @example
+ * ```tsx
+ * const { subscription, refetch } = useSubscription();
+ * const { pending, switching, selectPlan, confirmSwitch, dismissSwitch } =
+ *   usePlanSwitch(subscription, refetch);
+ * ```
+ */
+declare function usePlanSwitch(subscription: SubscriptionWithPlan | null, refetchSubscription: () => void, options?: {
+    successUrl?: string;
+    cancelUrl?: string;
+}): {
+    pending: PlanSwitchTarget | null;
+    switching: boolean;
+    switchError: unknown;
+    checkoutPriceId: string | null;
+    checkoutError: unknown;
+    selectPlan: (plan: PublicPlan, price: PublicPlanPrice) => Promise<void>;
+    confirmSwitch: () => Promise<void>;
+    dismissSwitch: () => void;
+};
 /**
  * Whether the current scope has access to one feature - the single entry
  * point for a live, per-feature decision. Deliberately not named after what
@@ -450,6 +502,24 @@ declare function useUsage(featureKey?: string): {
     isLoading: boolean;
     error: Error | null;
 };
+/**
+ * Usage write path for the signed-in user: `consume()` gates a QUOTA and commits
+ * in one step, `report()`/`reportBatch()` record usage without a check.
+ * `reportBatch()` sends many events in one request - the fix for hand-rolled
+ * request staggering in a component reporting several rows at once.
+ *
+ * @example
+ * ```tsx
+ * const { consume, reportBatch } = useReportUsage();
+ * await consume('exports', { delta: 1 });
+ * await reportBatch(machines.map((m) => ({ featureKey: 'machine_minutes', delta: m.minutes })));
+ * ```
+ */
+declare function useReportUsage(): {
+    consume: (featureKey: string, params?: Omit<ConsumeParams, "subject">) => Promise<EntitlementCheck>;
+    report: (featureKey: string, params?: Omit<ReportUsageParams, "subject">) => Promise<UsageRecord>;
+    reportBatch: (events: Array<Omit<ReportUsageBatchEvent, "subject">>) => Promise<_kerne_types.BatchUsageResult[]>;
+};
 /**
  * Waitlist signup form - a mutation, not a data fetch, same shape as
  * `useCheckout`/`usePortal`.
@@ -691,4 +761,4 @@ declare function useKerneError(): {
     clearError: () => void;
 };
 
-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 };
+export { Access, AuthLoading, Authenticated, HasSubscription, KerneClient, KerneContext, type KerneError, KerneErrorBoundary, KerneLocalization, KerneProvider, type KerneProviderProps, type KerneReactConfig, type PlanSwitchTarget, Protected, Unauthenticated, useAccess, useAuth, useAuthConfig, useCancelSubscription, useChangePlan, useCheckout, useClient, useEntitlements, useInvitation, useKerneError, usePlanSwitch, usePlans, usePortal, useReportUsage, useSubscription, useUsage, useUser, useWaitlist };