doct-ui-auth-kit 1.0.0

package/dist/core/auth-api-adapter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * API adapter interface for the SSO auth SDK.
+ * Consumers implement this to connect the SDK to their central auth service.
+ * The SDK never performs HTTP calls directly.
+ */
+import type { AuthenticateWithProviderParams, CompleteProfileParams, SendOtpResponse, SSOSession, VerifyOtpResponse } from './auth-types';
+/** Parameters for sending OTP to phone or email. */
+export interface SendOtpParams {
+    type: 'phone' | 'email';
+    value: string;
+}
+/** Parameters for verifying OTP. */
+export interface VerifyOtpParams {
+    type: 'phone' | 'email';
+    value: string;
+    otp: string;
+}
+/**
+ * Adapter implemented by the consumer to talk to the central auth service.
+ * All methods return promises; the SDK handles loading/error state.
+ */
+export interface AuthApiAdapter {
+    /** Send OTP to the given phone or email. */
+    sendOtp(params: SendOtpParams): Promise<SendOtpResponse>;
+    /**
+     * Verify OTP. Returns session if existing user, or isNewUser flag for profile completion.
+     * May return conflict error when identifier is linked to another account.
+     */
+    verifyOtp(params: VerifyOtpParams): Promise<VerifyOtpResponse>;
+    /** Complete profile for new users; returns SSO session. */
+    completeProfile(params: CompleteProfileParams): Promise<SSOSession>;
+    /** Authenticate with a third-party provider (Google/Apple) credential. */
+    authenticateWithProvider(params: AuthenticateWithProviderParams): Promise<VerifyOtpResponse>;
+    /** Validate an existing SSO session token; called on SDK mount. Returns null if invalid/expired. */
+    validateSession(token: string): Promise<SSOSession | null>;
+    /** Optional: refresh an expired SSO session using refresh token. */
+    refreshSession?(refreshToken: string): Promise<SSOSession | null>;
+}

package/dist/core/auth-context.d.ts

@@ -0,0 +1,67 @@
+import type { SSOSession } from './auth-types';
+import type { AuthFlowState } from './use-auth-flow';
+/** Provider config slice exposed to flow for Google/Apple wiring. */
+export interface AuthFlowProviderConfig {
+    google?: {
+        clientId: string;
+        enableOneTap?: boolean;
+    };
+    apple?: {
+        clientId: string;
+        redirectUri: string;
+    };
+}
+/** Async actions that perform I/O and dispatch to the flow reducer. */
+export interface AuthFlowActions {
+    selectMethod: (method: 'phone' | 'email' | 'google' | 'apple') => void;
+    /** From REPEAT_LOGIN: continue with last used method. */
+    continueWithLastMethod: () => void;
+    submitIdentifier: (data: {
+        phone?: string;
+        email?: string;
+    }) => void;
+    /** Foreign (non-IN) phone flow: collect fullName + email, send OTP to email. */
+    submitForeignEmail: (data: {
+        fullName: string;
+        email: string;
+    }) => void;
+    verifyOtp: (otp: string) => void;
+    resendOtp: () => void;
+    completeProfile: (data: {
+        fullName: string;
+        phone?: string;
+        email?: string;
+    }) => void;
+    providerCallback: (params: {
+        provider: 'google' | 'apple';
+        credential: string;
+    }) => void;
+    goBack: () => void;
+    reset: () => void;
+    signOut: () => void;
+}
+export interface AuthFlowContextValue {
+    state: AuthFlowState;
+    actions: AuthFlowActions;
+    /** Session when step is AUTHENTICATED. */
+    session: SSOSession | null;
+    /** True while step is CHECKING_SESSION. */
+    isLoading: boolean;
+    /** Provider config for Google/Apple (One Tap, Sign-In button). */
+    providerConfig: AuthFlowProviderConfig | undefined;
+}
+export declare const AuthFlowContext: import("react").Context<AuthFlowContextValue | null>;
+/**
+ * Hook to access auth flow state and actions. Must be used within SSOAuthProvider.
+ */
+export declare function useAuthFlow(): AuthFlowContextValue;
+/**
+ * Hook to access SSO session state only. Must be used within SSOAuthProvider.
+ */
+export declare function useAuthSession(): {
+    session: SSOSession | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    signOut: () => void;
+    authMethod: import("./auth-types").AuthMethod | null;
+};

package/dist/core/auth-flow.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Full auth flow orchestrator. Renders the correct page per flow state.
+ * Use inside SSOAuthProvider + AuthLayout.Main.
+ */
+export declare function AuthFlow(): import("react/jsx-runtime").JSX.Element | null;

package/dist/core/auth-provider.d.ts

@@ -0,0 +1,39 @@
+import type { AuthApiAdapter } from './auth-api-adapter';
+import type { AuthError, SSOSession } from './auth-types';
+import type { TokenStorageStrategy } from './sso-session';
+export interface SSOAuthConfig {
+    /** Consumer-provided adapter to their central auth service. */
+    apiAdapter: AuthApiAdapter;
+    /** Auth method configs (Google client ID, Apple client ID, etc.). */
+    providers?: {
+        google?: {
+            clientId: string;
+            enableOneTap?: boolean;
+        };
+        apple?: {
+            clientId: string;
+            redirectUri: string;
+        };
+    };
+    /** Called when SSO session is established (any method). */
+    onAuthSuccess: (session: SSOSession) => void;
+    /** Called on auth errors. */
+    onAuthError?: (error: AuthError) => void;
+    /** Optional: called when user signs out. */
+    onSignOut?: () => void;
+    /** SSO token persistence strategy. Defaults to localStorage. */
+    tokenStorage?: TokenStorageStrategy;
+    /** Branding customization (logo, slider images). */
+    branding?: {
+        logo?: React.ReactNode;
+        sliderImages?: string[];
+    };
+}
+export interface SSOAuthProviderProps {
+    config: SSOAuthConfig;
+    children: React.ReactNode;
+}
+/**
+ * SSO Auth provider: runs session check on mount, holds flow state, and provides async actions.
+ */
+export declare function SSOAuthProvider({ config, children }: SSOAuthProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/core/auth-types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * SSO auth domain types: session, flow steps, adapter contracts, and error codes.
+ * Used by the flow engine, provider, and adapter implementations.
+ */
+/** Auth methods available in the SSO system. */
+export type AuthMethod = 'phone' | 'email' | 'google' | 'apple';
+/** User payload in the SSO session. */
+export interface SSOUser {
+    id: string;
+    name: string;
+    email?: string;
+    phone?: string;
+    avatar?: string;
+    isNewUser: boolean;
+}
+/** The SSO session — same structure regardless of auth method used. */
+export interface SSOSession {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+    user: SSOUser;
+    authMethod: AuthMethod;
+}
+/** Flow states for the state machine. */
+export type AuthStep = 'CHECKING_SESSION' | 'REPEAT_LOGIN' | 'METHOD_SELECT' | 'PHONE_ENTRY' | 'EMAIL_ENTRY' | 'FOREIGN_EMAIL_COLLECT' | 'OTP_VERIFICATION' | 'PROFILE_COMPLETION' | 'PROVIDER_PENDING' | 'CONFLICT' | 'AUTHENTICATED';
+/** Error codes from the central auth service. */
+export type AuthErrorCode = 'IDENTIFIER_CONFLICT' | 'OTP_EXPIRED' | 'OTP_INVALID' | 'OTP_RATE_LIMIT' | 'SESSION_EXPIRED' | 'PROVIDER_AUTH_FAILED' | 'NETWORK_ERROR' | 'UNKNOWN';
+/** Auth error with code and optional message / linked identifier. */
+export interface AuthError {
+    code: AuthErrorCode;
+    message?: string;
+    /** Masked linked identifier when conflict (e.g. "+91 98XXXX0X0X"). */
+    linkedIdentifier?: string;
+}
+/** Response from sendOtp. */
+export interface SendOtpResponse {
+    success: boolean;
+    /** Masked value for display (e.g. "+91 9825910X0X" or "j***@gmail.com"). */
+    maskedValue?: string;
+    error?: AuthError;
+}
+/** Result of verifyOtp or authenticateWithProvider: existing user gets session, new user gets profile step. */
+export interface VerifyOtpResponse {
+    /** Present when user exists and is authenticated. */
+    session?: SSOSession;
+    /** True when user is new and must complete profile. */
+    isNewUser: boolean;
+    /** When isNewUser and conflict (e.g. email already linked), masked linked identifier. */
+    conflict?: AuthError;
+}
+/** Input for completeProfile (new users). */
+export interface CompleteProfileParams {
+    fullName: string;
+    email?: string;
+    phone?: string;
+}
+/** Input for authenticateWithProvider (Google/Apple credential). */
+export interface AuthenticateWithProviderParams {
+    provider: 'google' | 'apple';
+    /** Id token or equivalent from the provider. */
+    credential: string;
+}
+/** Repeat-login device history (method + masked identifier). */
+export interface RepeatLoginInfo {
+    method: AuthMethod;
+    maskedIdentifier: string;
+    timestamp: number;
+}

package/dist/core/device-detection.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Device-based repeat login detection.
+ * Stores last-used method and masked identifier in localStorage (device-local UX only).
+ */
+import type { AuthMethod } from './auth-types';
+export interface StoredRepeatLogin {
+    method: AuthMethod;
+    maskedIdentifier: string;
+    timestamp: number;
+}
+/**
+ * Reads repeat-login info from localStorage if present.
+ * Safe to call in browser; returns null in SSR or when not found.
+ */
+export declare function getRepeatLoginInfo(): StoredRepeatLogin | null;
+/**
+ * Saves repeat-login info to localStorage after successful auth.
+ */
+export declare function setRepeatLoginInfo(info: StoredRepeatLogin): void;
+/**
+ * Clears repeat-login info (e.g. on sign out).
+ */
+export declare function clearRepeatLoginInfo(): void;

package/dist/core/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * SSO Auth SDK core: types, adapter, provider, flow, session, device detection.
+ */
+export * from './auth-api-adapter';
+export * from './auth-context';
+export * from './auth-flow';
+export * from './auth-provider';
+export * from './auth-types';
+export * from './device-detection';
+export * from './sso-session';
+export * from './use-auth-flow';

package/dist/core/sso-session.d.ts

@@ -0,0 +1,35 @@
+/**
+ * SSO session management: token persistence strategies and useAuthSession hook.
+ * Token storage is consumer-configurable for cross-app SSO (e.g. shared cookie domain).
+ */
+import type { AuthMethod, SSOSession } from './auth-types';
+/** How/where the SSO token is stored for cross-app access. */
+export interface TokenStorageStrategy {
+    get(): string | null;
+    set(token: string, expiresAt: number): void;
+    remove(): void;
+}
+/**
+ * Token storage using localStorage (single-origin).
+ * Suitable for dev or when all Docthub apps share the same origin.
+ */
+export declare function localStorageTokenStorage(): TokenStorageStrategy;
+/**
+ * Token storage using a cookie on the given domain (e.g. '.docthub.com').
+ * Allows subdomains to share the SSO session. Not httpOnly (set from client).
+ */
+export declare function cookieTokenStorage(domain: string): TokenStorageStrategy;
+/**
+ * Return type of useAuthSession. Session and loading come from AuthFlowContext.
+ */
+export interface UseAuthSessionReturn {
+    session: SSOSession | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    signOut: () => void;
+    authMethod: AuthMethod | null;
+}
+/**
+ * useAuthSession hook is implemented in auth-context (uses AuthFlowContext).
+ * Re-exported from core index for consumer convenience.
+ */

package/dist/core/use-auth-flow.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Auth flow state machine: reducer and state type.
+ * Side effects (API calls, token persistence) are performed by the provider; this module is pure.
+ */
+import type { AuthError, AuthStep, SSOSession } from './auth-types';
+/** Identifier type for OTP / profile steps. */
+export type IdentifierType = 'phone' | 'email';
+/** Full state for the auth flow. */
+export interface AuthFlowState {
+    step: AuthStep;
+    /** Previous step for goBack. */
+    lastStep: AuthStep;
+    /** Current identifier value (phone or email) when in OTP or profile. */
+    identifierValue: string;
+    /** Type of identifier (phone vs email). */
+    identifierType: IdentifierType;
+    /** Masked value for display (e.g. "+91 9825910X0X"). */
+    maskedRecipient: string;
+    /** For PROFILE_COMPLETION: which field to collect (phone or email). */
+    signupMode: IdentifierType;
+    /** For REPEAT_LOGIN: last used method label. */
+    lastMethod: string;
+    /** Set when step is AUTHENTICATED. */
+    session: SSOSession | null;
+    /** Set when step is CONFLICT. */
+    conflictError: AuthError | null;
+    /** For FOREIGN_EMAIL_COLLECT: the non-IN phone we already have. */
+    foreignPhoneValue: string;
+    /** When set, foreign flow: use in completeProfile after OTP for new user. */
+    pendingFullName: string;
+    pendingEmail: string;
+}
+export declare const INITIAL_STEP: AuthStep;
+export declare function getInitialAuthFlowState(): AuthFlowState;
+/** Pure reducer actions. */
+export type AuthFlowAction = {
+    type: 'SET_SESSION';
+    session: SSOSession;
+} | {
+    type: 'SET_STEP_REPEAT_LOGIN';
+    lastMethod: string;
+    maskedIdentifier: string;
+} | {
+    type: 'SET_STEP_METHOD_SELECT';
+} | {
+    type: 'SET_STEP_PHONE_ENTRY';
+} | {
+    type: 'SET_STEP_EMAIL_ENTRY';
+} | {
+    type: 'SET_STEP_FOREIGN_EMAIL_COLLECT';
+    phoneValue: string;
+    maskedPhone?: string;
+} | {
+    type: 'SET_STEP_OTP_VERIFICATION';
+    identifierType: IdentifierType;
+    value: string;
+    maskedValue: string;
+    /** Optional: from foreign flow for completeProfile after OTP. */
+    pendingFullName?: string;
+    pendingEmail?: string;
+} | {
+    type: 'SET_STEP_PROFILE_COMPLETION';
+    signupMode: IdentifierType;
+} | {
+    type: 'SET_STEP_PROVIDER_PENDING';
+} | {
+    type: 'SET_STEP_CONFLICT';
+    error: AuthError;
+} | {
+    type: 'SET_STEP_AUTHENTICATED';
+    session: SSOSession;
+} | {
+    type: 'GO_BACK';
+} | {
+    type: 'RESET';
+} | {
+    type: 'SIGN_OUT';
+};
+export declare function authFlowReducer(state: AuthFlowState, action: AuthFlowAction): AuthFlowState;

package/dist/docthub.svg

@@ -0,0 +1,5 @@
+<svg width="46" height="46" viewBox="0 0 46 46" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="46" height="46" rx="23" fill="#18A3A6"/>
+<path d="M14.5039 15.972H17.8004C20.0002 15.8457 22.1711 16.5207 23.9114 17.872C24.6514 18.5147 25.2359 19.317 25.6208 20.2183C26.0057 21.1196 26.181 22.0965 26.1336 23.0754C26.1866 24.0779 26.0229 25.0799 25.6536 26.0134C25.2843 26.9468 24.7181 27.7896 23.9936 28.4844C22.3607 29.8691 20.2583 30.5737 18.1208 30.4526H14.5091L14.5039 15.972ZM17.1812 27.955H18.1173C19.5394 28.0467 20.9445 27.6055 22.0589 26.7174C22.5331 26.2712 22.9035 25.7262 23.1437 25.1211C23.384 24.5159 23.4885 23.8653 23.4495 23.2153C23.4881 22.5569 23.3759 21.8983 23.1215 21.2898C22.8671 20.6812 22.477 20.1388 21.9812 19.7038C20.7803 18.8089 19.3002 18.3702 17.8056 18.4662H17.1846L17.1812 27.955Z" fill="white"/>
+<path d="M29.8948 15.9609H25.2891V18.006H29.8809V22.598H31.8777V15.9609H29.8948Z" fill="white"/>
+</svg>

package/dist/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export { type EmailFormValues, type LoginEntryFormValues, type LoginEntryMode, type PhoneFormValues, type UseLoginEntryFormOptions, type UseLoginEntryFormReturn, useLoginEntryForm, } from './use-login-entry-form';
+export { DEFAULT_OTP_TITLES, OTP_LENGTH, type OtpFormValues, type OtpVerificationMode, RESEND_COOLDOWN_SECONDS, type UseOtpVerificationOptions, type UseOtpVerificationReturn, useOtpVerification, } from './use-otp-verification';
+export { type SignupEmailFormValues, type SignupEntryMode, type SignupFormValues, type SignupPhoneFormValues, type UseSignupFormOptions, type UseSignupFormReturn, useSignupForm, } from './use-signup-form';

package/dist/hooks/use-login-entry-form.d.ts

@@ -0,0 +1,32 @@
+import type { UseFormReturn } from 'react-hook-form';
+import { z } from 'zod';
+/** Login mode: phone number or email */
+export type LoginEntryMode = 'phone' | 'email';
+declare const phoneFormSchema: z.ZodObject<{
+    phone: z.ZodString;
+}, z.core.$strip>;
+declare const emailFormSchema: z.ZodObject<{
+    email: z.ZodString;
+}, z.core.$strip>;
+export type PhoneFormValues = z.infer<typeof phoneFormSchema>;
+export type EmailFormValues = z.infer<typeof emailFormSchema>;
+export type LoginEntryFormValues = PhoneFormValues | EmailFormValues;
+export interface UseLoginEntryFormOptions {
+    mode: LoginEntryMode;
+    /** Called with valid form data on submit. Omit or pass undefined when not needed. */
+    onSubmit?: ((data: {
+        phone?: string;
+        email?: string;
+    }) => void) | undefined;
+}
+export interface UseLoginEntryFormReturn {
+    methods: UseFormReturn<LoginEntryFormValues>;
+    handleSubmit: (data: LoginEntryFormValues) => void;
+    isPhone: boolean;
+}
+/**
+ * Form state and validation for the login entry screen (phone or email).
+ * Use with LoginEntry component or build a custom UI with the returned methods.
+ */
+export declare function useLoginEntryForm({ mode, onSubmit, }: UseLoginEntryFormOptions): UseLoginEntryFormReturn;
+export {};

package/dist/hooks/use-otp-verification.d.ts

@@ -0,0 +1,29 @@
+import type { UseFormReturn } from 'react-hook-form';
+import { z } from 'zod';
+/** OTP verification mode: mobile (phone) or email */
+export type OtpVerificationMode = 'phone' | 'email';
+export declare const OTP_LENGTH = 6;
+export declare const RESEND_COOLDOWN_SECONDS = 120;
+declare const otpFormSchema: z.ZodObject<{
+    otp: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type OtpFormValues = z.infer<typeof otpFormSchema>;
+export declare const DEFAULT_OTP_TITLES: Record<OtpVerificationMode, string>;
+export interface UseOtpVerificationOptions {
+    onSubmit?: ((otp: string) => void) | undefined;
+    onResendCode?: (() => void) | undefined;
+}
+export interface UseOtpVerificationReturn {
+    methods: UseFormReturn<OtpFormValues>;
+    handleSubmit: (data: OtpFormValues) => void;
+    handleResend: () => void;
+    resendSecondsLeft: number;
+    canResend: boolean;
+    timerText: string;
+}
+/**
+ * Form state, resend countdown, and validation for OTP verification.
+ * Use with OtpVerification component or build a custom OTP UI.
+ */
+export declare function useOtpVerification({ onSubmit, onResendCode, }?: UseOtpVerificationOptions): UseOtpVerificationReturn;
+export {};

package/dist/hooks/use-signup-form.d.ts

@@ -0,0 +1,37 @@
+import type { UseFormReturn } from 'react-hook-form';
+import { z } from 'zod';
+/** Signup mode: phone number or email as the second field (after full name) */
+export type SignupEntryMode = 'phone' | 'email';
+declare const signupPhoneFormSchema: z.ZodObject<{
+    fullName: z.ZodString;
+    phone: z.ZodString;
+}, z.core.$strip>;
+declare const signupEmailFormSchema: z.ZodObject<{
+    fullName: z.ZodString;
+    email: z.ZodString;
+}, z.core.$strip>;
+export type SignupPhoneFormValues = z.infer<typeof signupPhoneFormSchema>;
+export type SignupEmailFormValues = z.infer<typeof signupEmailFormSchema>;
+export type SignupFormValues = SignupPhoneFormValues | SignupEmailFormValues;
+export interface UseSignupFormOptions {
+    /** Mode: phone number or email as second field */
+    mode: SignupEntryMode;
+    /** Called with valid form data on submit. Omit or pass undefined when not needed. */
+    onSubmit?: ((data: {
+        fullName: string;
+        phone?: string;
+        email?: string;
+    }) => void) | undefined;
+}
+export interface UseSignupFormReturn {
+    methods: UseFormReturn<SignupFormValues>;
+    handleSubmit: (data: SignupFormValues) => void;
+    /** True when mode is 'phone', false when mode is 'email'. Use to switch between phone/email input. */
+    isPhone: boolean;
+}
+/**
+ * Form state and validation for the signup screen (full name + phone or email).
+ * Use with SignupPage component or build a custom signup form.
+ */
+export declare function useSignupForm({ mode, onSubmit, }: UseSignupFormOptions): UseSignupFormReturn;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Auth SDK UI Kit – library entry point.
+ * Consumers can import components, layouts, hooks, core (SSO provider, flow, session), and auth methods.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   SSOAuthProvider,
+ *   AuthFlow,
+ *   useAuthFlow,
+ *   useAuthSession,
+ *   MainLayout,
+ *   AuthLayout,
+ *   LoginEntry,
+ *   OtpVerification,
+ *   useGoogleOneTap,
+ * } from 'doct-ui-auth-kit';
+ * ```
+ */
+export * from './adapters';
+export * from './auth-methods';
+export * from './components/layout';
+export * from './core';
+export * from './hooks';
+export * from './pages';
+export * from './types';