@optare/react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,396 @@
+import { ReactNode } from 'react';
+import { OptareBootstrap, OptareBranding, OptareProjectInfo, OptareAuthMethods, Session, User, OptareSocialProvider } from '@optare/client';
+export { DEFAULT_AUTH_METHODS, DEFAULT_OPTARE_ORIGIN, OptareAuthMethods, OptareBootstrap, OptareBranding, OptareConfigError, OptareProjectInfo, OptareSocialProvider, Session, User, resolveOptareConfig } from '@optare/client';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface CreateReactAuthClientOptions {
+    bootstrap: OptareBootstrap;
+    publishableKey: string;
+    /** Custom fetch (tests, RN, older Node). */
+    fetch?: typeof fetch;
+    /** Extra headers on every auth request. */
+    headers?: Record<string, string>;
+}
+/**
+ * Structural type for the bits of the better-auth React client the SDK and its
+ * components actually touch, plus an escape hatch for everything else (the
+ * client is a dynamic RPC proxy, so arbitrary property access is meaningful).
+ *
+ * An explicit annotation is required here: better-auth's fully-inferred client
+ * type is too large for TypeScript to serialise into a `.d.ts` (TS7056/TS2742).
+ */
+interface OptareReactAuthClient {
+    getSession: (...args: any[]) => Promise<any>;
+    useSession: () => {
+        data: any;
+        isPending: boolean;
+        isRefetching: boolean;
+        error: unknown;
+        refetch: (...args: any[]) => Promise<void>;
+    };
+    signIn: {
+        email: (body: {
+            email: string;
+            password: string;
+            callbackURL?: string;
+            rememberMe?: boolean;
+        }) => Promise<{
+            data?: any;
+            error?: {
+                message?: string;
+                code?: string;
+            } | null;
+        }>;
+        magicLink: (body: {
+            email: string;
+            callbackURL?: string;
+        }) => Promise<{
+            data?: any;
+            error?: {
+                message?: string;
+                code?: string;
+            } | null;
+        }>;
+        [key: string]: (...args: any[]) => Promise<any>;
+    };
+    signUp: {
+        email: (body: {
+            email: string;
+            password: string;
+            name: string;
+            callbackURL?: string;
+        }) => Promise<{
+            data?: any;
+            error?: {
+                message?: string;
+                code?: string;
+            } | null;
+        }>;
+    };
+    signOut: (...args: any[]) => Promise<any>;
+    organization: {
+        setActive: (body: {
+            organizationId: string | null;
+        }) => Promise<any>;
+        [key: string]: (...args: any[]) => Promise<any>;
+    };
+    twoFactor: Record<string, (...args: any[]) => Promise<any>>;
+    emailOtp: Record<string, (...args: any[]) => Promise<any>>;
+    [key: string]: any;
+}
+declare function createReactAuthClient(options: CreateReactAuthClientOptions): OptareReactAuthClient;
+
+/**
+ * White-label theming — E2, expanded in E11.
+ *
+ * Every component renders against CSS custom properties. The provider resolves
+ * `branding` (from the publishable key, via `@optare/client`) once and exposes
+ * these variables; a host app can override any of them with plain CSS.
+ *
+ * Only two values come from branding — the primary colour and the corner
+ * radius — and both are regex-gated (`safeColor` / `safeLength`) so a project's
+ * branding string can never inject CSS. Everything else is a fixed neutral
+ * palette tuned for legibility on a white card.
+ */
+declare const DEFAULT_PRIMARY = "#4f46e5";
+declare const DEFAULT_RADIUS = "10px";
+/** Reject anything that isn't a plain colour/length so branding can't inject CSS. */
+declare function safeColor(value: string | null | undefined, fallback: string): string;
+declare function safeLength(value: string | null | undefined, fallback: string): string;
+/**
+ * Pick readable text (`#ffffff` or a near-black) to sit on `hex`, choosing
+ * whichever has the higher WCAG contrast ratio. This is what keeps the primary
+ * button and the avatar legible whatever colour the project picked — the E2
+ * version compared raw luminance and washed out on mid-tones.
+ */
+declare function contrastText(hex: string): string;
+type OptareCssVars = Record<`--optare-${string}`, string>;
+declare function brandingToCssVars(branding: OptareBranding | null): OptareCssVars;
+
+/**
+ * `<OptareProvider>` — E2.
+ *
+ * Give it a publishable key; it resolves the endpoint + branding (once) and
+ * builds the React auth client. Children read the client and branding through
+ * the hooks in this file. Pass `bootstrap` to skip the network entirely (SSR,
+ * tests, or when the host already fetched `GET /api/public/config`).
+ */
+type OptareStatus = "loading" | "ready" | "error";
+interface OptareContextValue {
+    status: OptareStatus;
+    error: Error | null;
+    /** Resolved endpoint + project info + branding. `null` until ready. */
+    bootstrap: OptareBootstrap | null;
+    branding: OptareBranding | null;
+    project: OptareProjectInfo | null;
+    /** Enabled sign-in methods. Falls back to email+password before `ready`. */
+    authMethods: OptareAuthMethods;
+    cssVars: OptareCssVars;
+    /** The better-auth React client. `null` until ready. */
+    auth: OptareReactAuthClient | null;
+    publishableKey: string;
+    /** Re-run config resolution after an error. */
+    retry: () => void;
+}
+interface OptareProviderProps {
+    publishableKey: string;
+    bootstrap?: OptareBootstrap;
+    /** Override the auth API origin (self-hosted / preview). */
+    baseURL?: string;
+    /** Where `GET /api/public/config` lives. Defaults to `baseURL`, then hosted. */
+    configURL?: string;
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+    /** Rendered while branding resolves. Default: children (optimistic). */
+    loadingFallback?: ReactNode;
+    /** Rendered if resolution fails. Default: children, with `status === "error"`. */
+    errorFallback?: ReactNode | ((error: Error, retry: () => void) => ReactNode);
+    children: ReactNode;
+}
+declare function OptareProvider(props: OptareProviderProps): ReactNode;
+declare function useOptare(): OptareContextValue;
+/** The better-auth React client. Throws if the provider isn't ready yet. */
+declare function useOptareAuth(): OptareReactAuthClient;
+declare function useOptareConfig(): {
+    bootstrap: OptareBootstrap | null;
+    project: OptareProjectInfo | null;
+    branding: OptareBranding | null;
+    status: OptareStatus;
+};
+declare function useBranding(): OptareBranding | null;
+/** The instance's enabled sign-in methods (social providers, magic-link, …). */
+declare function useAuthMethods(): OptareAuthMethods;
+
+/**
+ * Session + identity hooks — E2.
+ */
+interface UseSessionResult {
+    data: Session | null;
+    user: User | null;
+    isPending: boolean;
+    isAuthenticated: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+declare function useSession(): UseSessionResult;
+declare function useUser(): User | null;
+interface UseSignOutResult {
+    signOut: () => Promise<void>;
+    isPending: boolean;
+    error: Error | null;
+}
+declare function useSignOut(): UseSignOutResult;
+interface UseActiveOrganizationResult {
+    activeOrganizationId: string | null;
+    setActive: (organizationId: string | null) => Promise<void>;
+    isPending: boolean;
+}
+/**
+ * Thin wrapper over the organization plugin's `setActive`. Reads the active id
+ * off the session (`session.activeOrganizationId`, added in F8).
+ */
+declare function useActiveOrganization(): UseActiveOrganizationResult;
+
+declare function notifySessionChanged(): void;
+
+/**
+ * Client-side form validation — E2.
+ *
+ * Deliberately lenient: the server is the authority. These only exist to give
+ * immediate feedback and stop obviously-doomed round trips. Pure functions so
+ * they're trivially testable without a DOM.
+ */
+declare function isValidEmail(value: string): boolean;
+interface PasswordCheck {
+    ok: boolean;
+    /** 0-4 — for a strength meter. */
+    score: number;
+    message: string | null;
+}
+declare function checkPassword(value: string, min?: number): PasswordCheck;
+interface SignInFields {
+    email: string;
+    password: string;
+}
+declare function validateSignIn(fields: SignInFields): Partial<Record<keyof SignInFields, string>>;
+interface SignUpFields {
+    name: string;
+    email: string;
+    password: string;
+}
+declare function validateSignUp(fields: SignUpFields, passwordMin?: number): Partial<Record<keyof SignUpFields, string>>;
+
+/**
+ * `<SignIn />` — E2, expanded in E11.
+ *
+ * Renders whatever the project's Optare instance has enabled: email + password,
+ * an "email me a link" (magic-link) path, an email one-time-code path, and the
+ * configured social providers. Branding (logo, name, colour, radius) comes from
+ * the publishable key. On success it fires `onSuccess` (or navigates to
+ * `redirectTo`). A `twoFactorRedirect` response surfaces `onTwoFactor` so the
+ * host can route to `<TwoFactorChallenge>`.
+ */
+interface SignInProps {
+    /** Called after a completed sign-in (no 2FA pending). */
+    onSuccess?: () => void;
+    /** `window.location` target after sign-in, if `onSuccess` isn't given. */
+    redirectTo?: string;
+    /**
+     * Where the magic-link / social / email-verification round-trip lands the
+     * user. Defaults to the current page URL — set this only to send them
+     * somewhere else (e.g. a dedicated post-login route).
+     */
+    callbackURL?: string;
+    /** Invoked when the server says a 2FA challenge is required. */
+    onTwoFactor?: () => void;
+    /** Invoked when the user clicks "Forgot password?" — route to `<ForgotPassword>`. */
+    onForgotPassword?: () => void;
+    /** Show the "Email me a link instead" option. Default: follows instance config. */
+    allowMagicLink?: boolean;
+    /** Show the "Email me a code instead" option. Default: follows instance config. */
+    allowEmailOtp?: boolean;
+    /** Show social provider buttons. Default: follows instance config. */
+    allowSocial?: boolean;
+    /** Offer "Sign in with SSO" (work-email → IdP). Default: follows instance config. */
+    allowSso?: boolean;
+    /** Slot under the form — e.g. a link to `<SignUp />`. */
+    footer?: ReactNode;
+    title?: string;
+    subtitle?: string;
+}
+declare function SignIn(props: SignInProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * `<SignUp />` — E2.
+ *
+ * Name + email + password. The organization the new user lands in is decided
+ * server-side from the publishable key (F6 `resolveParentTenant`), so there is
+ * nothing to configure here. If the project requires email verification the
+ * server returns success with no session — `onVerificationRequired` fires.
+ */
+interface SignUpProps {
+    onSuccess?: () => void;
+    redirectTo?: string;
+    callbackURL?: string;
+    /** Fired when signup succeeded but a verification email must be clicked first. */
+    onVerificationRequired?: (email: string) => void;
+    /** Minimum password length hint (server is authoritative). Default: 8. */
+    passwordMinLength?: number;
+    /** Show social provider buttons. Default: follows instance config. */
+    allowSocial?: boolean;
+    footer?: ReactNode;
+    title?: string;
+    subtitle?: string;
+}
+declare function SignUp(props: SignUpProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * `<AccountButton />` — E2.
+ *
+ * Avatar + name trigger with a dropdown (profile slot, sign out). Renders
+ * nothing while the session is loading and a `signInSlot` (or nothing) when
+ * signed out. Themed from the publishable key's branding.
+ */
+interface AccountButtonProps {
+    /** Shown when there is no session. */
+    signInSlot?: ReactNode;
+    /** Extra menu items above "Sign out" (e.g. links to your own pages). */
+    menuItems?: ReactNode;
+    /** Called after sign-out completes. */
+    onSignedOut?: () => void;
+    /** Hide the name label, show only the avatar. */
+    compact?: boolean;
+}
+declare function AccountButton(props: AccountButtonProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * `<SocialButtons />` — E11.
+ *
+ * Renders one button per social provider the instance has enabled
+ * (`authMethods.social`, resolved from the publishable key). Clicking a button
+ * starts the OAuth redirect via better-auth's `signIn.social`. Dependency-free:
+ * the provider marks are inline SVG, so `@optare/react` doesn't pull an icon
+ * library into the customer's bundle.
+ *
+ * Renders nothing when no providers are enabled, so callers can drop it in
+ * unconditionally.
+ */
+interface SocialButtonsProps {
+    /** URL to land on after the provider round-trip. Default: current page. */
+    callbackURL?: string;
+    /** URL to land on if the provider flow errors. */
+    errorCallbackURL?: string;
+    /** Verb in the button label. Default: "Continue with". */
+    label?: string;
+    /** Show a divider above the buttons. Default: true. */
+    divider?: boolean;
+    /** Divider text. Default: "or". */
+    dividerLabel?: string;
+    /** Restrict to a subset / order of the enabled providers. */
+    only?: OptareSocialProvider[];
+}
+declare function SocialButtons(props: SocialButtonsProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * `<ForgotPassword />` — E11.
+ *
+ * Collects an email and asks the server to send a reset link
+ * (`auth.forgetPassword`). The link lands on `redirectTo` with a `?token=…`
+ * that `<ResetPassword>` consumes. Always shows the same confirmation whether
+ * or not the address exists — no account-enumeration signal.
+ */
+interface ForgotPasswordProps {
+    /** Path the reset link should point at (your `<ResetPassword>` route). Default: `/reset-password`. */
+    redirectTo?: string;
+    /** Back-to-sign-in handler. */
+    onBack?: () => void;
+    title?: string;
+    subtitle?: string;
+    footer?: ReactNode;
+}
+declare function ForgotPassword(props: ForgotPasswordProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * `<ResetPassword />` — E11.
+ *
+ * The landing screen for the link `<ForgotPassword>` sends. Reads the reset
+ * `token` from the URL (`?token=…`, better-auth's default) unless one is passed
+ * explicitly, takes a new password, and calls `auth.resetPassword`.
+ */
+interface ResetPasswordProps {
+    /** Reset token. Default: read from `?token=` / `?t=` in the current URL. */
+    token?: string;
+    /** Called after the password is changed. */
+    onSuccess?: () => void;
+    /** `window.location` target after success, if `onSuccess` isn't given. */
+    redirectTo?: string;
+    /** Back-to-sign-in handler, shown when the token is missing/invalid. */
+    onBack?: () => void;
+    /** Minimum length hint (server is authoritative). Default: 12. */
+    passwordMinLength?: number;
+    title?: string;
+    footer?: ReactNode;
+}
+declare function ResetPassword(props: ResetPasswordProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * `<TwoFactorChallenge />` — E11.
+ *
+ * Shown after `<SignIn>` reports `onTwoFactor` (better-auth returned
+ * `twoFactorRedirect`). Verifies a TOTP code from the user's authenticator, or
+ * a one-time backup code. On success the session is live — fires `onSuccess`.
+ */
+interface TwoFactorChallengeProps {
+    onSuccess?: () => void;
+    redirectTo?: string;
+    /** "Use a different account" / cancel handler. */
+    onCancel?: () => void;
+    /** Offer the "use a backup code" switch. Default: true. */
+    allowBackupCode?: boolean;
+    title?: string;
+    subtitle?: string;
+    footer?: ReactNode;
+}
+declare function TwoFactorChallenge(props: TwoFactorChallengeProps): react_jsx_runtime.JSX.Element;
+
+export { AccountButton, type AccountButtonProps, type CreateReactAuthClientOptions, DEFAULT_PRIMARY, DEFAULT_RADIUS, ForgotPassword, type ForgotPasswordProps, type OptareContextValue, type OptareCssVars, OptareProvider, type OptareProviderProps, type OptareReactAuthClient, type OptareStatus, type PasswordCheck, ResetPassword, type ResetPasswordProps, SignIn, type SignInFields, type SignInProps, SignUp, type SignUpFields, type SignUpProps, SocialButtons, type SocialButtonsProps, TwoFactorChallenge, type TwoFactorChallengeProps, type UseActiveOrganizationResult, type UseSessionResult, type UseSignOutResult, brandingToCssVars, checkPassword, contrastText, createReactAuthClient, isValidEmail, notifySessionChanged, safeColor, safeLength, useActiveOrganization, useAuthMethods, useBranding, useOptare, useOptareAuth, useOptareConfig, useSession, useSignOut, useUser, validateSignIn, validateSignUp };