@kerne/react 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -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.js';
-export { d as defaultLocalization } from './i18n-Di5qlnL1.js';
+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.js';
+export { d as defaultLocalization } from './i18n-CXEhPK58.js';
 
 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 };

package/dist/index.js

@@ -13,13 +13,15 @@ import {
   useClient,
   useEntitlements,
   useInvitation,
+  usePlanSwitch,
   usePlans,
   usePortal,
+  useReportUsage,
   useSubscription,
   useUsage,
   useUser,
   useWaitlist
-} from "./chunk-NFJ2S5VJ.js";
+} from "./chunk-IHNWY4ML.js";
 
 // src/components.tsx
 import React from "react";
@@ -173,8 +175,10 @@ export {
   useEntitlements,
   useInvitation,
   useKerneError,
+  usePlanSwitch,
   usePlans,
   usePortal,
+  useReportUsage,
   useSubscription,
   useUsage,
   useUser,