@kerne/react 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -1,87 +1,567 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import * as _kerne_server from '@kerne/server';
-import { KerneConfig, Kerne } from '@kerne/server';
-import React from 'react';
-import { User, AuthResponse } from '@kerne/types';
+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, EntitlementCheck, SubscriptionWithPlan, PublicPlan, Entitlements, UsageRecord, Subscription } from '@kerne/types';
+export { AuthResponse, EntitlementCheck, Entitlements, PublicPlan, Subscription, SubscriptionWithPlan, UsageRecord, User } from '@kerne/types';
 
 interface KerneReactConfig extends Omit<KerneConfig, 'secretKey'> {
     storage?: Storage;
     storageKey?: string;
     onAuthChange?: (user: User | null) => void;
+    /** Auto-refresh session before expiry (default: true) */
+    autoRefresh?: boolean;
+    /** Refresh buffer in seconds before expiry (default: 60) */
+    refreshBuffer?: number;
 }
+
+type Listener$1 = () => void;
 declare class KerneClient {
     private kerne;
     private storage;
     private storageKey;
     private onAuthChange?;
-    private currentUser;
-    private currentToken;
+    private autoRefresh;
+    private refreshBuffer;
+    private refreshTimer;
+    private listeners;
+    private _user;
+    private _token;
+    private _refreshToken;
+    private _expiresAt;
+    private _isLoading;
+    readonly baseUrl: string;
+    readonly appId: string;
     constructor(config: KerneReactConfig);
-    private loadSession;
-    private saveSession;
-    private clearSession;
+    subscribe(listener: Listener$1): () => void;
+    private notify;
     get user(): User | null;
     get token(): string | null;
     get isAuthenticated(): boolean;
-    get client(): Kerne;
-    get projects(): _kerne_server.ProjectsResource;
+    get isLoading(): boolean;
+    private loadSession;
+    /**
+     * `AuthResponse.user` is the minimal `{id, email, role}` claim set the
+     * token endpoint returns, not the full profile (`User`) - so this always
+     * follows up with `users.me()` rather than assigning it directly (that
+     * used to leave `_user` looking like a `User` while actually missing
+     * `email_verified`/`first_name`/`avatar`/etc).
+     */
+    private saveSession;
+    private clearSession;
+    private scheduleRefresh;
+    private cancelRefresh;
+    private silentRefresh;
     register(params: {
         email: string;
         password: string;
         name?: string;
+        invitationToken?: string;
+        invitationCode?: string;
     }): Promise<AuthResponse>;
     login(params: {
         email: string;
         password: string;
     }): Promise<AuthResponse>;
+    /** Manually trigger a token refresh - normally handled automatically by `autoRefresh`. */
     refreshToken(): Promise<AuthResponse | null>;
     logout(): void;
     refreshUser(): Promise<User | null>;
-    checkEntitlement(featureKey: string, requested?: number): Promise<boolean>;
-    createCheckout(planId: string, options?: {
+    updateProfile(params: {
+        first_name?: string;
+        last_name?: string;
+    }): Promise<User>;
+    updatePassword(params: {
+        currentPassword: string;
+        newPassword: string;
+    }): Promise<void>;
+    /** Forgot-password flow (logged out) - sends the reset email. */
+    requestPasswordReset(email: string): Promise<void>;
+    /** Confirms a password reset with the token from the email. */
+    confirmPasswordReset(token: string, password: string): Promise<void>;
+    /**
+     * Errors are not swallowed here (unlike the old implementation, which
+     * 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>`)
+     * catch around this themselves.
+     */
+    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>;
+    createCheckout(planPriceId: string, options?: {
         successUrl?: string;
         cancelUrl?: string;
     }): Promise<string>;
-    openCheckout(planId: string, options?: {
+    openCheckout(planPriceId: string, options?: {
         successUrl?: string;
         cancelUrl?: string;
     }): Promise<void>;
     createPortal(returnUrl?: string): Promise<string>;
     openPortal(returnUrl?: string): Promise<void>;
+    getSubscription(productSlug?: string): Promise<SubscriptionWithPlan | null>;
+    /** 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. */
+    getEntitlements(): Promise<Entitlements>;
+    /** Usage for the current user - all QUOTA features, or one via `featureKey`. */
+    getUsage(featureKey?: string): Promise<UsageRecord[]>;
+    joinWaitlist(params: JoinWaitlistParams): Promise<{
+        success: boolean;
+    }>;
+    /** Validate an invitation token before showing the registration form. */
+    validateInvitationToken(token: string): Promise<ValidateTokenResponse>;
+    /** Validate an invitation code before showing the registration form. */
+    validateInvitationCode(code: string): Promise<ValidateCodeResponse>;
+    sendVerificationEmail(verificationType?: 'code' | 'link'): Promise<void>;
+    verifyEmailWithCode(code: string): Promise<{
+        success: boolean;
+        needsTokenRefresh: boolean;
+    }>;
+    verifyEmailWithLink(token: string): Promise<{
+        success: boolean;
+        needsTokenRefresh: boolean;
+    }>;
+    getVerificationStatus(): Promise<{
+        emailVerified: boolean;
+        needsVerification: boolean;
+        email: string;
+    }>;
 }
-declare function createKerneClient(config: KerneReactConfig): KerneClient;
+declare const KerneContext: React.Context<KerneClient | null>;
 interface KerneProviderProps extends KerneReactConfig {
     children: React.ReactNode;
 }
 declare function KerneProvider({ children, ...config }: KerneProviderProps): react_jsx_runtime.JSX.Element;
-declare function useKerne(): KerneClient;
+
+/**
+ * Access the Kerne client instance
+ */
+declare function useClient(): KerneClient;
+/**
+ * Authentication hook with optimized re-renders
+ *
+ * @example
+ * ```tsx
+ * const { user, isAuthenticated, login, logout } = useAuth();
+ * ```
+ */
 declare function useAuth(): {
     user: User | null;
+    token: string | null;
     isAuthenticated: boolean;
+    isLoading: boolean;
     login: (params: {
         email: string;
         password: string;
-    }) => Promise<AuthResponse>;
+    }) => Promise<_kerne_types.AuthResponse>;
     register: (params: {
         email: string;
         password: string;
         name?: string;
-    }) => Promise<AuthResponse>;
+        invitationToken?: string;
+        invitationCode?: string;
+    }) => Promise<_kerne_types.AuthResponse>;
     logout: () => void;
     refreshUser: () => Promise<User | null>;
+    refreshToken: () => Promise<_kerne_types.AuthResponse | null>;
+    updateProfile: (params: {
+        first_name?: string;
+        last_name?: string;
+        avatar?: string;
+    }) => Promise<User>;
+    updatePassword: (params: {
+        currentPassword: string;
+        newPassword: string;
+    }) => Promise<void>;
+    requestPasswordReset: (email: string) => Promise<void>;
+    confirmPasswordReset: (token: string, password: string) => Promise<void>;
+    sendVerificationEmail: (verificationType?: "code" | "link") => Promise<void>;
+    verifyEmailWithCode: (code: string) => Promise<{
+        success: boolean;
+        needsTokenRefresh: boolean;
+    }>;
+    verifyEmailWithLink: (token: string) => Promise<{
+        success: boolean;
+        needsTokenRefresh: boolean;
+    }>;
+    getVerificationStatus: () => Promise<{
+        emailVerified: boolean;
+        needsVerification: boolean;
+        email: string;
+    }>;
 };
-declare function useBilling(): {
-    checkEntitlement: (featureKey: string, requested?: number) => Promise<boolean>;
-    createCheckout: (planId: string, options?: {
+/**
+ * Checkout hook - starts a Stripe/Polar checkout session for a plan price.
+ *
+ * @example
+ * ```tsx
+ * const { openCheckout } = useCheckout();
+ * <button onClick={() => openCheckout(planPriceId)}>Upgrade</button>
+ * ```
+ */
+declare function useCheckout(): {
+    createCheckout: (planPriceId: string, options?: {
         successUrl?: string;
         cancelUrl?: string;
     }) => Promise<string>;
-    openCheckout: (planId: string, options?: {
+    openCheckout: (planPriceId: string, options?: {
         successUrl?: string;
         cancelUrl?: string;
     }) => Promise<void>;
+};
+/**
+ * Billing portal hook - lets a user manage their subscription/payment method.
+ *
+ * @example
+ * ```tsx
+ * const { openPortal } = usePortal();
+ * <button onClick={() => openPortal()}>Manage billing</button>
+ * ```
+ */
+declare function usePortal(): {
     createPortal: (returnUrl?: string) => Promise<string>;
     openPortal: (returnUrl?: string) => Promise<void>;
 };
+/**
+ * Hook for a plain allowed/denied entitlement check.
+ *
+ * @example
+ * ```tsx
+ * const { allowed, isLoading } = useAllows('advanced_analytics');
+ * ```
+ */
+declare function useAllows(featureKey: string, requested?: number): {
+    allowed: boolean;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Hook for the full entitlement detail (limit/used/remaining/overage) -
+ * use `useAllows` when a plain boolean is all you need.
+ *
+ * @example
+ * ```tsx
+ * const { check, isLoading } = useCheck('api_calls');
+ * // check?.remaining, check?.limit, check?.overage_behavior
+ * ```
+ */
+declare function useCheck(featureKey: string, requested?: number): {
+    check: EntitlementCheck | null;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Hook for subscription state
+ *
+ * @example
+ * ```tsx
+ * const { subscription, isLoading, isPro } = useSubscription();
+ * ```
+ */
+declare function useSubscription(productSlug?: string): {
+    isActive: boolean;
+    planSlug: any;
+    subscription: any | null;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Public pricing data for a pricing/checkout page - omit `productIdOrSlug`
+ * for the tenant's default product.
+ *
+ * @example
+ * ```tsx
+ * const { plans, isLoading } = usePlans();
+ * ```
+ */
+declare function usePlans(productIdOrSlug?: string): {
+    plans: PublicPlan[];
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Every entitlement for the current user in one call - for a "your plan"
+ * screen. Use `useAllows`/`useCheck` instead for a single feature - this
+ * response never carries `allowed` (see docs: the list is cached, a stale
+ * verdict would be unsafe).
+ *
+ * @example
+ * ```tsx
+ * const { entitlements, isLoading } = useEntitlements();
+ * ```
+ */
+declare function useEntitlements(): {
+    entitlements: Entitlements | null;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Usage for the current user - every QUOTA feature, or one via `featureKey`.
+ *
+ * @example
+ * ```tsx
+ * const { usage, isLoading } = useUsage('api_calls');
+ * ```
+ */
+declare function useUsage(featureKey?: string): {
+    usage: UsageRecord[];
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Waitlist signup form - a mutation, not a data fetch, same shape as
+ * `useCheckout`/`usePortal`.
+ *
+ * @example
+ * ```tsx
+ * const { join } = useWaitlist();
+ * await join({ email });
+ * ```
+ */
+declare function useWaitlist(): {
+    join: (params: JoinWaitlistParams) => Promise<{
+        success: boolean;
+    }>;
+};
+/**
+ * Validates an invitation token/code before showing the registration form -
+ * pass whichever one is present in the URL.
+ *
+ * @example
+ * ```tsx
+ * const { result, isLoading } = useInvitation({ token });
+ * if (!isLoading && !result?.valid) return <InvalidInvite />;
+ * ```
+ */
+declare function useInvitation(params: {
+    token?: string;
+    code?: string;
+}): {
+    result: ValidateTokenResponse | ValidateCodeResponse | null;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Hook for user profile data
+ *
+ * @example
+ * ```tsx
+ * const { user, isLoading, update } = useUser();
+ * ```
+ */
+declare function useUser(): {
+    user: User | null;
+    isLoading: boolean;
+    update: (params: {
+        first_name?: string;
+        last_name?: string;
+        avatar?: string;
+    }) => Promise<User>;
+    fullName: string | null;
+    initials: string | null;
+    email: string | null;
+    emailVerified: boolean;
+};
+
+/**
+ * Guardian Components
+ *
+ * Conditional rendering based on auth/billing state.
+ * Inspired by Clerk's <SignedIn>, <SignedOut> pattern.
+ */
+
+interface AuthGuardProps {
+    children: ReactNode;
+    /** Fallback content when condition is not met */
+    fallback?: ReactNode;
+}
+/**
+ * Renders children only when user is authenticated
+ *
+ * @example
+ * ```tsx
+ * <Authenticated>
+ *   <Dashboard />
+ * </Authenticated>
+ * ```
+ */
+declare function Authenticated({ children, fallback }: AuthGuardProps): ReactNode;
+/**
+ * Renders children only when user is NOT authenticated
+ *
+ * @example
+ * ```tsx
+ * <Unauthenticated>
+ *   <LoginPrompt />
+ * </Unauthenticated>
+ * ```
+ */
+declare function Unauthenticated({ children, fallback }: AuthGuardProps): ReactNode;
+/**
+ * Renders children while auth state is loading
+ *
+ * @example
+ * ```tsx
+ * <AuthLoading>
+ *   <Spinner />
+ * </AuthLoading>
+ * ```
+ */
+declare function AuthLoading({ children }: {
+    children: ReactNode;
+}): ReactNode;
+interface SubscriptionGuardProps {
+    children: ReactNode;
+    /** Fallback content when there's no active subscription */
+    fallback?: ReactNode;
+}
+/**
+ * Renders children only when user has an active subscription
+ *
+ * @example
+ * ```tsx
+ * <HasSubscription fallback={<UpgradePrompt />}>
+ *   <PremiumFeature />
+ * </HasSubscription>
+ * ```
+ */
+declare function HasSubscription({ children, fallback }: SubscriptionGuardProps): ReactNode;
+interface EntitlementGuardProps {
+    children: ReactNode;
+    /** Capability key to check */
+    key: string;
+    /** Minimum value required (for limit features) */
+    minimum?: 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.
+ *
+ * @example
+ * ```tsx
+ * <Allows key="advanced_analytics" fallback={<UpgradePrompt feature="analytics" />}>
+ *   <AnalyticsDashboard />
+ * </Allows>
+ * ```
+ */
+declare function Allows({ children, key, minimum, fallback, }: EntitlementGuardProps): ReactNode;
+interface ProtectedProps {
+    children: ReactNode;
+    /** Require authentication */
+    auth?: boolean;
+    /** Require specific capability key */
+    key?: string;
+    /** Fallback for unauthenticated */
+    authFallback?: ReactNode;
+    /** Fallback for missing feature */
+    billingFallback?: ReactNode;
+}
+/**
+ * Combined guard for auth + entitlement requirements
+ *
+ * @example
+ * ```tsx
+ * <Protected auth key="advanced_analytics" authFallback={<Login />} billingFallback={<Upgrade />}>
+ *   <ProFeature />
+ * </Protected>
+ * ```
+ */
+declare function Protected({ children, auth, key, authFallback, billingFallback, }: ProtectedProps): ReactNode;
+
+/**
+ * Kerne Error Boundary
+ *
+ * Catches auth/billing errors and provides recovery UI
+ */
+
+interface KerneError extends Error {
+    code?: string;
+    statusCode?: number;
+    details?: Record<string, any>;
+}
+interface ErrorBoundaryProps {
+    children: ReactNode;
+    /** Custom fallback UI */
+    fallback?: ReactNode | ((error: KerneError, reset: () => void) => ReactNode);
+    /** Called when error is caught */
+    onError?: (error: KerneError, errorInfo: ErrorInfo) => void;
+    /** Called when user clicks reset */
+    onReset?: () => void;
+}
+interface ErrorBoundaryState {
+    error: KerneError | null;
+    hasError: boolean;
+}
+/**
+ * Error boundary for Kerne SDK errors
+ *
+ * @example
+ * ```tsx
+ * <KerneErrorBoundary
+ *   fallback={(error, reset) => (
+ *     <div>
+ *       <p>Something went wrong: {error.message}</p>
+ *       <button onClick={reset}>Try again</button>
+ *     </div>
+ *   )}
+ *   onError={(error) => console.error('Kerne error:', error)}
+ * >
+ *   <App />
+ * </KerneErrorBoundary>
+ * ```
+ */
+declare class KerneErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+/**
+ * Hook version for functional components that need error state
+ */
+declare function useKerneError(): {
+    error: KerneError | null;
+    hasError: boolean;
+    handleError: (err: Error | KerneError) => void;
+    clearError: () => void;
+};
+
+/**
+ * KerneStore - External store for React 18+ useSyncExternalStore
+ *
+ * Optimized for minimal re-renders:
+ * - Subscribe to specific slices of state
+ * - Only notifies when subscribed values change
+ */
+
+interface KerneState {
+    user: User | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    subscription: Subscription | null;
+    error: Error | null;
+}
+type Listener = () => void;
+type Selector<T> = (state: KerneState) => T;
+declare class KerneStore {
+    private state;
+    private listeners;
+    constructor(initialState?: Partial<KerneState>);
+    getState(): KerneState;
+    getSnapshot(): KerneState;
+    getServerSnapshot(): KerneState;
+    setState(partial: Partial<KerneState>): void;
+    private hasChanged;
+    subscribe(listener: Listener): () => void;
+    private notify;
+    select<T>(selector: Selector<T>): T;
+}
 
-export { KerneClient, KerneProvider, type KerneProviderProps, type KerneReactConfig, createKerneClient, useAuth, useBilling, useKerne };
+export { Allows, AuthLoading, Authenticated, HasSubscription, KerneClient, KerneContext, type KerneError, KerneErrorBoundary, KerneProvider, type KerneProviderProps, type KerneReactConfig, type KerneState, KerneStore, Protected, Unauthenticated, useAllows, useAuth, useCheck, useCheckout, useClient, useEntitlements, useInvitation, useKerneError, usePlans, usePortal, useSubscription, useUsage, useUser, useWaitlist };