doct-ui-auth-kit 1.0.18 → 1.0.21

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

@@ -24,6 +24,21 @@ export interface CheckIdentifierResponse {
     exists: boolean;
     userType?: UserType;
 }
+interface LinkOrMergeBaseParams {
+    isLinking: boolean;
+    name: string;
+}
+export type LinkOrMergeAccountParams = (LinkOrMergeBaseParams & {
+    conflictField: 'email';
+    oldEmail?: string;
+    newEmail: string;
+}) | (LinkOrMergeBaseParams & {
+    conflictField: 'phone';
+    oldCountryCode?: string;
+    oldPhone?: string;
+    newCountryCode: string;
+    newPhone: string;
+});
 /**
  * Adapter implemented by the consumer to talk to the central auth service.
  * All methods return promises; the SDK handles loading/error state.
@@ -52,6 +67,13 @@ export interface AuthApiAdapter {
     refreshSession?(refreshToken: string): Promise<SSOSession | null>;
     /** Optional: check identifier existence before OTP routing decisions. */
     checkIdentifier?(params: CheckIdentifierParams): Promise<CheckIdentifierResponse>;
+    /**
+     * Optional: link or merge an account after profile completion reports a
+     * duplicate new email/mobile. Implementations should only send the fields
+     * for `params.conflictField`.
+     */
+    linkOrMergeAccount?(params: LinkOrMergeAccountParams): Promise<SSOSession | void>;
     /** Optional: clear server-side cookie/session on sign out. */
     logout?(): Promise<void>;
 }
+export {};

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

@@ -24,7 +24,7 @@ export interface SSOSession {
 /** User type for layout and OTP routing: Indian (+91) vs Foreign (non +91). */
 export type UserType = 'INDIAN' | 'FOREIGN';
 /** Flow states for the state machine. */
-export type AuthStep = 'CHECKING_SESSION' | 'REPEAT_LOGIN' | 'METHOD_SELECT' | 'PHONE_ENTRY' | 'EMAIL_ENTRY' | 'OTP_VERIFICATION' | 'SIGNUP_DETAILS' | 'PROVIDER_PENDING' | 'AUTHENTICATED';
+export type AuthStep = 'CHECKING_SESSION' | 'REPEAT_LOGIN' | 'METHOD_SELECT' | 'PHONE_ENTRY' | 'EMAIL_ENTRY' | 'OTP_VERIFICATION' | 'SIGNUP_DETAILS' | 'LINK_OR_MERGE' | 'PROVIDER_PENDING' | '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. */

package/dist/types/auth/flow.d.ts

@@ -4,6 +4,20 @@
 import type { AuthStep, SSOSession, UserType } from './auth-types';
 /** Identifier type for OTP / profile steps. */
 export type IdentifierType = 'phone' | 'email';
+export type LinkOrMergeConflictField = IdentifierType;
+export type LinkOrMergeState = {
+    conflictField: 'email';
+    name: string;
+    oldEmail?: string;
+    newEmail: string;
+} | {
+    conflictField: 'phone';
+    name: string;
+    oldCountryCode?: string;
+    oldPhone?: string;
+    newCountryCode: string;
+    newPhone: string;
+};
 /** Full state for the auth flow. */
 export interface AuthFlowState {
     step: AuthStep;
@@ -28,6 +42,8 @@ export interface AuthFlowState {
     /** Foreign flow: signup form data for completeProfile after OTP verify. */
     pendingFullName: string;
     pendingEmail: string;
+    /** Link/merge details collected after duplicate email/mobile profile errors. */
+    linkOrMerge: LinkOrMergeState | null;
 }
 /** Pure reducer actions. */
 export type AuthFlowAction = {
@@ -64,7 +80,9 @@ export type AuthFlowAction = {
     identifierType?: IdentifierType;
     identifierValue?: string;
     maskedRecipient?: string;
-} | {
+} | ({
+    type: 'SET_STEP_LINK_OR_MERGE';
+} & LinkOrMergeState) | {
     type: 'SET_STEP_PROVIDER_PENDING';
 } | {
     type: 'SET_STEP_AUTHENTICATED';
@@ -75,6 +93,16 @@ export type AuthFlowAction = {
     type: 'RESET';
 } | {
     type: 'SIGN_OUT';
+}
+/**
+ * Replace the entire state with a previously-persisted snapshot. Used
+ * by the provider to rehydrate the flow on page refresh so the user
+ * doesn't lose their step. See `flow-state-storage.ts` and the
+ * CHECKING_SESSION fallback in `auth-provider.tsx`.
+ */
+ | {
+    type: 'RESTORE_STATE';
+    state: AuthFlowState;
 };
 /** Provider config slice exposed to flow for Google/Apple wiring. */
 export interface AuthFlowProviderConfig {
@@ -116,6 +144,7 @@ export interface AuthFlowActions {
         provider: 'google' | 'apple';
         credential: string;
     }) => void;
+    verifyLinkOrMerge: () => Promise<void>;
     goBack: () => void;
     reset: () => void;
     signOut: () => void;

package/dist/types/pages/pages.d.ts

@@ -2,7 +2,7 @@
  * Props and public types for auth page components.
  */
 import type { UserType } from '../auth/auth-types';
-import type { IdentifierType } from '../auth/flow';
+import type { IdentifierType, LinkOrMergeState } from '../auth/flow';
 import type { LoginEntryMode } from './login-form';
 import type { UseMainAuthPageHandlersOptions } from './main-login';
 import type { OtpValidateFn, OtpVerificationMode } from './otp-verification';
@@ -85,6 +85,11 @@ export interface SignupPageFullProps extends SignupPageProps {
     layoutType?: 'withSlider' | 'standalone';
     variant?: 'desktop' | 'mobile';
 }
+export interface LinkOrMergePageProps {
+    details: LinkOrMergeState;
+    onBack?: (() => void) | undefined;
+    onVerify: () => Promise<void>;
+}
 /** Props for OtpVerification (inner form without layout). */
 export interface OtpVerificationProps {
     /** Mode: mobile (phone) or email OTP */

package/dist/utils/flow-state-storage.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `sessionStorage` persistence for the auth-flow state machine itself
+ * (step, userType, pendingEmail, etc.). Lets the user refresh on any
+ * step — including non-deep-linkable ones like OTP_VERIFICATION and
+ * SIGNUP_DETAILS — without getting bounced to METHOD_SELECT or
+ * REPEAT_LOGIN by the router-sync deep-link guard.
+ *
+ * Cleared on AUTHENTICATED (the provider's success effect) and
+ * automatically on tab close (sessionStorage default).
+ *
+ * Separate from `form-state-storage.ts` so the two concerns can be
+ * cleared / inspected independently — form values mirror RHF state,
+ * flow state mirrors the reducer.
+ */
+import type { AuthFlowState } from '../types';
+/**
+ * Read a persisted flow state.
+ *
+ * Returns null when storage is missing, the value is unparseable, or
+ * `step` is unrecognised. When the step is valid, the parsed object is
+ * merged on top of `defaultState(step)` — that guarantees every
+ * required field is populated even if the snapshot was hand-edited,
+ * truncated, or written by an older kit version that didn't know
+ * about every field. Without that merge, `RESTORE_STATE` could place
+ * `identifierType: undefined` / `identifierValue: undefined` / etc.
+ * into the reducer and crash downstream pages.
+ */
+export declare function readFlowState(): AuthFlowState | null;
+/** Persist the full flow state. No-op on quota / disabled storage. */
+export declare function writeFlowState(state: AuthFlowState): void;
+/** Wipe the persisted flow state. Called on successful auth. */
+export declare function clearFlowState(): void;

package/dist/utils/index.d.ts

@@ -2,5 +2,6 @@
  * Reusable utilities used in 2+ places across the auth SDK.
  */
 export { buildPhoneRecipient } from './build-phone-recipient';
+export { clearFlowState, readFlowState, writeFlowState, } from './flow-state-storage';
 export { clearAllFormState, clearFormState, readFormState, writeFormState, } from './form-state-storage';
 export { setFormErrorsFromZod } from './set-form-errors-from-zod';

package/package.json

@@ -1,110 +1,110 @@
-{
-  "name": "doct-ui-auth-kit",
-  "version": "1.0.18",
-  "description": "Composable React auth SDK – layouts, login/signup/OTP pages, SSO provider, and auth flow hooks for Docthub",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": ["dist", "README.md"],
-  "keywords": [
-    "react",
-    "auth",
-    "sdk",
-    "docthub",
-    "login",
-    "signup",
-    "sso",
-    "otp"
-  ],
-  "license": "UNLICENSED",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/docthub/doct-ui-auth-kit"
-  },
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build && tsc --build tsconfig.build.json --force && tsc-alias -p tsconfig.build.json",
-    "prepublishOnly": "npm run build",
-    "lint": "biome lint .",
-    "preview": "vite preview",
-    "format": "biome format --write .",
-    "lint:biome": "biome lint .",
-    "check": "biome check .",
-    "check:fix": "biome check --write .",
-    "type-check": "tsc --noEmit",
-    "prepare": "husky",
-    "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./style.css": "./dist/doct-ui-auth-kit.css",
-    "./pages": {
-      "types": "./dist/pages/index.d.ts",
-      "import": "./dist/pages.js"
-    }
-  },
-  "peerDependencies": {
-    "docthub-core-components": "2.99.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "react-hook-form": "^7.50.0",
-    "react-icons": "^5.5.0",
-    "zod": "^4.0.0"
-  },
-  "dependencies": {
-    "clsx": "^2.1.1",
-    "dayjs": "^1.11.19",
-    "docthub-core-components": "2.99.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "react-hook-form": "^7.50.0",
-    "react-icons": "^5.5.0",
-    "react-phone-number-input": "^3.4.14",
-    "react-router-dom": "^7.13.0",
-    "zod": "^4.0.0"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.3.14",
-    "@chromatic-com/storybook": "^5.0.0",
-    "@eslint/js": "^9.39.1",
-    "@storybook/addon-a11y": "^10.2.6",
-    "@storybook/addon-docs": "^10.2.6",
-    "@storybook/addon-onboarding": "^10.2.6",
-    "@storybook/addon-vitest": "^10.2.6",
-    "@storybook/react-vite": "^10.2.6",
-    "@types/node": "^24.10.1",
-    "@types/react": "^19.2.5",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^5.1.1",
-    "@vitest/browser-playwright": "^4.0.18",
-    "@vitest/coverage-v8": "^4.0.18",
-    "autoprefixer": "^10.4.24",
-    "babel-plugin-react-compiler": "^1.0.0",
-    "eslint": "^9.39.1",
-    "eslint-plugin-react-hooks": "^7.0.1",
-    "eslint-plugin-react-refresh": "^0.4.24",
-    "glob": "^13.0.1",
-    "globals": "^16.5.0",
-    "husky": "^9.1.7",
-    "lint-staged": "^16.2.7",
-    "playwright": "^1.58.1",
-    "postcss": "^8.5.6",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "storybook": "^10.2.6",
-    "tailwind-merge": "^3.0.1",
-    "tailwindcss": "^3.4.16",
-    "tailwindcss-animate": "^1.0.7",
-    "tsc-alias": "^1.8.17",
-    "typescript": "~5.6.2",
-    "typescript-eslint": "^8.46.4",
-    "vite": "^7.2.4",
-    "vite-plugin-dts": "^4.5.0",
-    "vitest": "^4.0.18"
-  }
-}
+{
+  "name": "doct-ui-auth-kit",
+  "version": "1.0.21",
+  "description": "Composable React auth SDK – layouts, login/signup/OTP pages, SSO provider, and auth flow hooks for Docthub",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md"],
+  "keywords": [
+    "react",
+    "auth",
+    "sdk",
+    "docthub",
+    "login",
+    "signup",
+    "sso",
+    "otp"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/docthub/doct-ui-auth-kit"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && tsc --build tsconfig.build.json --force && tsc-alias -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "lint": "biome lint .",
+    "preview": "vite preview",
+    "format": "biome format --write .",
+    "lint:biome": "biome lint .",
+    "check": "biome check .",
+    "check:fix": "biome check --write .",
+    "type-check": "tsc --noEmit",
+    "prepare": "husky",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./style.css": "./dist/doct-ui-auth-kit.css",
+    "./pages": {
+      "types": "./dist/pages/index.d.ts",
+      "import": "./dist/pages.js"
+    }
+  },
+  "peerDependencies": {
+    "docthub-core-components": "2.99.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-hook-form": "^7.50.0",
+    "react-icons": "^5.5.0",
+    "zod": "^4.0.0"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "dayjs": "^1.11.19",
+    "docthub-core-components": "2.99.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-hook-form": "^7.50.0",
+    "react-icons": "^5.5.0",
+    "react-phone-number-input": "^3.4.14",
+    "react-router-dom": "^7.13.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@chromatic-com/storybook": "^5.0.0",
+    "@eslint/js": "^9.39.1",
+    "@storybook/addon-a11y": "^10.2.6",
+    "@storybook/addon-docs": "^10.2.6",
+    "@storybook/addon-onboarding": "^10.2.6",
+    "@storybook/addon-vitest": "^10.2.6",
+    "@storybook/react-vite": "^10.2.6",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/coverage-v8": "^4.0.18",
+    "autoprefixer": "^10.4.24",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "glob": "^13.0.1",
+    "globals": "^16.5.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "playwright": "^1.58.1",
+    "postcss": "^8.5.6",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "storybook": "^10.2.6",
+    "tailwind-merge": "^3.0.1",
+    "tailwindcss": "^3.4.16",
+    "tailwindcss-animate": "^1.0.7",
+    "tsc-alias": "^1.8.17",
+    "typescript": "~5.6.2",
+    "typescript-eslint": "^8.46.4",
+    "vite": "^7.2.4",
+    "vite-plugin-dts": "^4.5.0",
+    "vitest": "^4.0.18"
+  }
+}