@kerne/react 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -3,25 +3,38 @@ 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';
+import { User, AuthResponse, ActivationContext, AuthConfig, EntitlementCheck, SubscriptionWithPlan, 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';
 
 interface KerneReactConfig extends Omit<KerneConfig, 'secretKey'> {
     storage?: Storage;
     storageKey?: string;
     onAuthChange?: (user: User | null) => void;
+    /**
+     * A cross-origin handoff arrived but could not be exchanged for a session -
+     * an expired one-time code, or an origin this tenant does not allow.
+     *
+     * Worth handling: the SDK cannot render UI, so without this the user
+     * completes a magic link, lands on your app, and is simply not signed in
+     * with nothing on screen explaining why. Typically a toast plus a link back
+     * to sign in.
+     */
+    onHandoffError?: (error: unknown) => void;
     /** Auto-refresh session before expiry (default: true) */
     autoRefresh?: boolean;
     /** Refresh buffer in seconds before expiry (default: 60) */
     refreshBuffer?: number;
 }
 
-type Listener$1 = () => void;
+type Listener = () => void;
 declare class KerneClient {
     private kerne;
     private storage;
     private storageKey;
     private onAuthChange?;
+    private onHandoffError?;
     private autoRefresh;
     private refreshBuffer;
     private refreshTimer;
@@ -31,16 +44,43 @@ declare class KerneClient {
     private _refreshToken;
     private _expiresAt;
     private _isLoading;
+    private _authConfigPromise;
     readonly baseUrl: string;
     readonly appId: string;
     constructor(config: KerneReactConfig);
-    subscribe(listener: Listener$1): () => void;
+    subscribe(listener: Listener): () => void;
     private notify;
     get user(): User | null;
     get token(): string | null;
     get isAuthenticated(): boolean;
     get isLoading(): boolean;
     private loadSession;
+    private getHandoffCodeFromUrl;
+    /**
+     * Strips only `kerne_handoff` from the URL, leaving the rest of the
+     * path/query (e.g. a `return_to` the host app added) untouched - and
+     * without adding a history entry, so back-navigation doesn't resurrect it.
+     */
+    private stripHandoffParamFromUrl;
+    /**
+     * Same shape as `refreshOnLoad`: a bootstrap-only path invoked once from
+     * `loadSession()` when a `kerne_handoff` code is present in the URL,
+     * entirely invisible to the host app - no code on their end required.
+     *
+     * Works no matter which page the browser lands on: `redirectUrl` is a hard
+     * navigation (`window.location.href`), so the destination reloads the SDK
+     * fresh and `loadSession()` reads the code straight off that page's own
+     * URL - there is no dependency on a specific "callback route", as long as
+     * `KerneProvider` wraps whatever the host renders there (normally true when
+     * it is mounted once at the app root).
+     *
+     * One retry on a transient failure (network blip, 5xx) - worth it because
+     * the code was never reached by the server in that case, so it is still
+     * unspent. A 4xx (invalid/expired/already-consumed) is not retried: the
+     * code is gone, retrying only delays the "logged out" outcome.
+     */
+    private exchangeHandoffOnLoad;
+    private refreshOnLoad;
     /**
      * `AuthResponse.user` is the minimal `{id, email, role}` claim set the
      * token endpoint returns, not the full profile (`User`) - so this always
@@ -76,10 +116,45 @@ declare class KerneClient {
         currentPassword: string;
         newPassword: string;
     }): Promise<void>;
+    /** Soft-deletes (deactivates) the caller's own account, then clears the local session. */
+    requestAccountDeletion(): Promise<void>;
     /** Forgot-password flow (logged out) - sends the reset email. */
-    requestPasswordReset(email: string): Promise<void>;
+    requestPasswordReset(email: string, callbackUrl?: string): Promise<void>;
     /** Confirms a password reset with the token from the email. */
     confirmPasswordReset(token: string, password: string): Promise<void>;
+    /**
+     * Sends a magic-link email (logged out). Anti-enumeration: always resolves,
+     * regardless of whether the email is registered.
+     */
+    startPasswordless(email: string, callbackUrl?: string, invitation?: {
+        invitationToken?: string;
+        invitationCode?: string;
+    }): Promise<void>;
+    /** Completes a magic-link login using the `token` query param from the emailed link. */
+    loginWithMagicLink(token: string): Promise<AuthResponse>;
+    /** Read-only: which UI to render for an activation token, without consuming it. */
+    getActivationContext(token: string): Promise<ActivationContext>;
+    /** Completes activation (sets a password or confirms magic-link mode), then logs the user in. */
+    completeActivation(token: string, password?: string): Promise<AuthResponse>;
+    /**
+     * Mints a handoff code for the current session and redirects the browser
+     * to `url` with it attached (`?kerne_handoff=...`) - never the real
+     * token/refresh_token, which would otherwise leak into server logs,
+     * browser history, and third-party `Referer` headers on the landing page.
+     */
+    redirectWithSession(url: string): Promise<void>;
+    /**
+     * The tenant's public auth config - which sign-in methods to render, whether
+     * registration is open, whether to show Kerne branding.
+     *
+     * Deduped on the in-flight promise rather than the resolved value: the
+     * prebuilt forms all read this on mount, and two of them mounted together
+     * (a login screen with a register link prefetching) would otherwise fire two
+     * identical requests before either resolved. Cached for the client's
+     * lifetime - this config changes on the order of "the owner edited their
+     * settings", not per render.
+     */
+    getAuthConfig(): Promise<AuthConfig>;
     /**
      * Errors are not swallowed here (unlike the old implementation, which
      * caught everything and returned `false`) - a 401/500 must not be
@@ -115,7 +190,7 @@ declare class KerneClient {
     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>;
+    sendVerificationEmail(verificationType?: 'code' | 'link', callbackUrl?: string): Promise<void>;
     verifyEmailWithCode(code: string): Promise<{
         success: boolean;
         needsTokenRefresh: boolean;
@@ -133,8 +208,16 @@ declare class KerneClient {
 declare const KerneContext: React.Context<KerneClient | null>;
 interface KerneProviderProps extends KerneReactConfig {
     children: React.ReactNode;
+    /**
+     * Overrides for the prebuilt components' copy, including the error-code
+     * messages. Set once here rather than per component - the strings are shared,
+     * and a per-component prop would mean re-passing the same dictionary to every
+     * screen. Merged group-by-group over the English defaults, so a partial
+     * override keeps everything it does not mention.
+     */
+    localization?: DeepPartial<KerneLocalization>;
 }
-declare function KerneProvider({ children, ...config }: KerneProviderProps): react_jsx_runtime.JSX.Element;
+declare function KerneProvider({ children, localization, ...config }: KerneProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Access the Kerne client instance
@@ -149,7 +232,7 @@ declare function useClient(): KerneClient;
  * ```
  */
 declare function useAuth(): {
-    user: User | null;
+    user: _kerne_types.User | null;
     token: string | null;
     isAuthenticated: boolean;
     isLoading: boolean;
@@ -165,20 +248,26 @@ declare function useAuth(): {
         invitationCode?: string;
     }) => Promise<_kerne_types.AuthResponse>;
     logout: () => void;
-    refreshUser: () => Promise<User | null>;
+    refreshUser: () => Promise<_kerne_types.User | null>;
     refreshToken: () => Promise<_kerne_types.AuthResponse | null>;
     updateProfile: (params: {
         first_name?: string;
         last_name?: string;
         avatar?: string;
-    }) => Promise<User>;
+    }) => Promise<_kerne_types.User>;
     updatePassword: (params: {
         currentPassword: string;
         newPassword: string;
     }) => Promise<void>;
-    requestPasswordReset: (email: string) => Promise<void>;
+    requestAccountDeletion: () => Promise<void>;
+    requestPasswordReset: (email: string, callbackUrl?: string) => Promise<void>;
     confirmPasswordReset: (token: string, password: string) => Promise<void>;
-    sendVerificationEmail: (verificationType?: "code" | "link") => Promise<void>;
+    startPasswordless: (email: string, callbackUrl?: string, invitation?: {
+        invitationToken?: string;
+        invitationCode?: string;
+    }) => Promise<void>;
+    loginWithMagicLink: (token: string) => Promise<_kerne_types.AuthResponse>;
+    sendVerificationEmail: (verificationType?: "code" | "link", callbackUrl?: string) => Promise<void>;
     verifyEmailWithCode: (code: string) => Promise<{
         success: boolean;
         needsTokenRefresh: boolean;
@@ -192,6 +281,9 @@ declare function useAuth(): {
         needsVerification: boolean;
         email: string;
     }>;
+    getActivationContext: (token: string) => Promise<_kerne_types.ActivationContext>;
+    completeActivation: (token: string, password?: string) => Promise<_kerne_types.AuthResponse>;
+    redirectWithSession: (url: string) => Promise<void>;
 };
 /**
  * Checkout hook - starts a Stripe/Polar checkout session for a plan price.
@@ -226,30 +318,33 @@ declare function usePortal(): {
     openPortal: (returnUrl?: string) => Promise<void>;
 };
 /**
- * Hook for a plain allowed/denied entitlement check.
+ * Whether the current scope has access to one feature - the single entry
+ * point for a live, per-feature decision. Deliberately not named after what
+ * it checks TODAY: this gates entitlements for now, but the same shape is
+ * meant to answer for a future access-rule engine (custom RBAC, feature
+ * flags) without a rename - "access" is the word that survives that.
+ * `details` (not `entitlement`) follows the same logic on the return value.
  *
- * @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.
+ * Not `useCheck` either - too close to `useCheckout` to skim safely, and
+ * unrelated to it in every other way. Not folded into `useEntitlements()`
+ * (the cached list, for display): the two hit different endpoints with
+ * different consistency guarantees, and merging them would make the network
+ * behavior branch silently on whether a key was passed.
+ *
+ * Replaces the former `useAllows`/`useCheck` pair, which were two names for
+ * one request: `client.allows()` is literally `check().allowed`, hitting the
+ * same endpoint and discarding the rest.
  *
  * @example
  * ```tsx
- * const { check, isLoading } = useCheck('api_calls');
- * // check?.remaining, check?.limit, check?.overage_behavior
+ * const { allowed } = useAccess('advanced_analytics');
+ * const { details } = useAccess('api_calls');
+ * // details?.remaining, details?.limit, details?.overage_behavior
  * ```
  */
-declare function useCheck(featureKey: string, requested?: number): {
-    check: EntitlementCheck | null;
+declare function useAccess(featureKey: string, requested?: number): {
+    details: EntitlementCheck | null;
+    allowed: boolean;
     isLoading: boolean;
     error: Error | null;
 };
@@ -263,8 +358,8 @@ declare function useCheck(featureKey: string, requested?: number): {
  */
 declare function useSubscription(productSlug?: string): {
     isActive: boolean;
-    planSlug: any;
-    subscription: any | null;
+    planSlug: string | undefined;
+    subscription: SubscriptionWithPlan | null;
     isLoading: boolean;
     error: Error | null;
 };
@@ -282,11 +377,27 @@ declare function usePlans(productIdOrSlug?: string): {
     isLoading: boolean;
     error: Error | null;
 };
+/**
+ * The tenant's public auth config - which sign-in methods are enabled, whether
+ * registration is open, whether to show Kerne branding. Drives what the
+ * prebuilt forms render, so a tenant that turns magic link on gets the button
+ * without shipping any code.
+ *
+ * @example
+ * ```tsx
+ * const { config, isLoading } = useAuthConfig();
+ * ```
+ */
+declare function useAuthConfig(): {
+    config: AuthConfig | null;
+    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).
+ * screen. Use `useAccess` instead for a single feature - this response
+ * never carries `allowed` (see docs: the list is cached, a stale verdict
+ * would be unsafe).
  *
  * @example
  * ```tsx
@@ -353,13 +464,13 @@ declare function useInvitation(params: {
  * ```
  */
 declare function useUser(): {
-    user: User | null;
+    user: _kerne_types.User | null;
     isLoading: boolean;
     update: (params: {
         first_name?: string;
         last_name?: string;
         avatar?: string;
-    }) => Promise<User>;
+    }) => Promise<_kerne_types.User>;
     fullName: string | null;
     initials: string | null;
     email: string | null;
@@ -431,8 +542,16 @@ interface SubscriptionGuardProps {
 declare function HasSubscription({ children, fallback }: SubscriptionGuardProps): ReactNode;
 interface EntitlementGuardProps {
     children: ReactNode;
-    /** Capability key to check */
-    key: string;
+    /**
+     * Capability key to check.
+     *
+     * NOT named `key`: React reserves that prop for reconciliation and strips it
+     * before the component sees it, so the previous `key="..."` signature could
+     * only ever read `undefined` - the check then failed and the guard rendered
+     * its fallback forever. Same name as `useAccess(featureKey)` and
+     * `UpgradePrompt`, so the whole entitlement surface reads alike.
+     */
+    featureKey: string;
     /** Minimum value required (for limit features) */
     minimum?: number;
     /** Fallback content when entitlement is not met */
@@ -445,18 +564,18 @@ interface EntitlementGuardProps {
  *
  * @example
  * ```tsx
- * <Allows key="advanced_analytics" fallback={<UpgradePrompt feature="analytics" />}>
+ * <Allows featureKey="advanced_analytics" fallback={<UpgradePrompt featureKey="advanced_analytics" />}>
  *   <AnalyticsDashboard />
  * </Allows>
  * ```
  */
-declare function Allows({ children, key, minimum, fallback, }: EntitlementGuardProps): ReactNode;
+declare function Allows({ children, featureKey, minimum, fallback, }: EntitlementGuardProps): ReactNode;
 interface ProtectedProps {
     children: ReactNode;
     /** Require authentication */
     auth?: boolean;
-    /** Require specific capability key */
-    key?: string;
+    /** Require a specific capability. Not `key` - React reserves that prop name. */
+    featureKey?: string;
     /** Fallback for unauthenticated */
     authFallback?: ReactNode;
     /** Fallback for missing feature */
@@ -467,12 +586,12 @@ interface ProtectedProps {
  *
  * @example
  * ```tsx
- * <Protected auth key="advanced_analytics" authFallback={<Login />} billingFallback={<Upgrade />}>
+ * <Protected auth featureKey="advanced_analytics" authFallback={<Login />} billingFallback={<Upgrade />}>
  *   <ProFeature />
  * </Protected>
  * ```
  */
-declare function Protected({ children, auth, key, authFallback, billingFallback, }: ProtectedProps): ReactNode;
+declare function Protected({ children, auth, featureKey, authFallback, billingFallback, }: ProtectedProps): ReactNode;
 
 /**
  * Kerne Error Boundary
@@ -533,35 +652,4 @@ declare function useKerneError(): {
     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 { 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 };
+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 };