@famgia/omnify-react-sso 2.2.0 → 2.2.2

package/dist/index.d.cts

@@ -1,17 +1,18 @@
 export { DateString, DateTimeString, Locale, LocaleMap, ValidationRule } from '@omnify-base/schemas/common';
 export { defaultLocale, fallbackLocale, getMessage, getMessages, supportedLocales, validationMessages } from '@omnify-base/schemas/i18n';
-export { BranchCreate, BranchUpdate, PermissionCreate, PermissionUpdate, RoleCreate, RolePermission, RolePermissionCreate, RolePermissionUpdate, RoleUpdate, Team, TeamCreate, TeamPermission, TeamPermissionCreate, TeamPermissionUpdate, TeamUpdate, User, UserCreate, UserUpdate, branchCreateSchema, branchSchemas, branchUpdateSchema, permissionCreateSchema, permissionSchemas, permissionUpdateSchema, roleCreateSchema, rolePermissionCreateSchema, rolePermissionSchemas, rolePermissionUpdateSchema, roleSchemas, roleUpdateSchema, teamCreateSchema, teamPermissionCreateSchema, teamPermissionSchemas, teamPermissionUpdateSchema, teamSchemas, teamUpdateSchema, userCreateSchema, userSchemas, userUpdateSchema } from './schemas/index.cjs';
+export { BranchCache, BranchCacheCreate, BranchCacheUpdate, OrganizationCache, OrganizationCacheCreate, OrganizationCacheUpdate, PermissionCreate, PermissionUpdate, RoleCreate, RolePermission, RolePermissionCreate, RolePermissionUpdate, RoleUpdate, TeamCache, TeamCacheCreate, TeamCacheUpdate, TeamPermission, TeamPermissionCreate, TeamPermissionUpdate, UserCache, UserCacheCreate, UserCacheUpdate, branchCacheCreateSchema, branchCacheSchemas, branchCacheUpdateSchema, organizationCacheCreateSchema, organizationCacheSchemas, organizationCacheUpdateSchema, permissionCreateSchema, permissionSchemas, permissionUpdateSchema, roleCreateSchema, rolePermissionCreateSchema, rolePermissionSchemas, rolePermissionUpdateSchema, roleSchemas, roleUpdateSchema, teamCacheCreateSchema, teamCacheSchemas, teamCacheUpdateSchema, teamPermissionCreateSchema, teamPermissionSchemas, teamPermissionUpdateSchema, userCacheCreateSchema, userCacheSchemas, userCacheUpdateSchema } from './schemas/index.cjs';
 import * as react from 'react';
-import { b as SsoContextValue, c as SsoProviderProps, S as SsoUser$2, a as SsoOrganization, d as SsoConfig, e as SsoCallbackProps, O as OrganizationSwitcherProps, P as ProtectedRouteProps } from './types-BCBSfJJr.cjs';
-export { f as SsoCallbackResponse } from './types-BCBSfJJr.cjs';
+import { b as SsoContextValue, c as SsoProviderProps, B as BranchContextValue, d as BranchProviderProps, S as SsoUser$2, a as SsoOrganization, e as SsoConfig, f as SsoCallbackProps, O as OrganizationSwitcherProps, P as ProtectedRouteProps, g as OrgBranchSelectorModalProps, h as BranchGateProps, i as BranchGateSelection } from './types-CJmA2a9r.cjs';
+export { l as OrgBranchSelection, k as SsoBranch, j as SsoCallbackResponse } from './types-CJmA2a9r.cjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-export { branchI18n, getBranchFieldLabel, getBranchFieldPlaceholder, getBranchLabel } from '@omnify-base/schemas/Branch';
+export { branchCacheI18n, getBranchCacheFieldLabel, getBranchCacheFieldPlaceholder, getBranchCacheLabel } from '@omnify-base/schemas/BranchCache';
+export { getOrganizationCacheFieldLabel, getOrganizationCacheFieldPlaceholder, getOrganizationCacheLabel, organizationCacheI18n } from '@omnify-base/schemas/OrganizationCache';
 export { getPermissionFieldLabel, getPermissionFieldPlaceholder, getPermissionLabel, permissionI18n } from '@omnify-base/schemas/Permission';
 export { getRoleFieldLabel, getRoleFieldPlaceholder, getRoleLabel, roleI18n } from '@omnify-base/schemas/Role';
 export { getRolePermissionFieldLabel, getRolePermissionFieldPlaceholder, getRolePermissionLabel, rolePermissionI18n } from '@omnify-base/schemas/RolePermission';
-export { getTeamFieldLabel, getTeamFieldPlaceholder, getTeamLabel, teamI18n } from '@omnify-base/schemas/Team';
+export { getTeamCacheFieldLabel, getTeamCacheFieldPlaceholder, getTeamCacheLabel, teamCacheI18n } from '@omnify-base/schemas/TeamCache';
 export { getTeamPermissionFieldLabel, getTeamPermissionFieldPlaceholder, getTeamPermissionLabel, teamPermissionI18n } from '@omnify-base/schemas/TeamPermission';
-export { getUserFieldLabel, getUserFieldPlaceholder, getUserLabel, userI18n } from '@omnify-base/schemas/User';
+export { getUserCacheFieldLabel, getUserCacheFieldPlaceholder, getUserCacheLabel, userCacheI18n } from '@omnify-base/schemas/UserCache';
 import 'zod';
 
 /**
@@ -24,6 +25,38 @@ declare const SsoContext: react.Context<SsoContextValue | null>;
  */
 declare function SsoProvider({ children, config, onAuthChange }: SsoProviderProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Branch Context
+ *
+ * Provides branch state management across the application.
+ * Must be used within a BranchProvider.
+ */
+declare const BranchContext: react.Context<BranchContextValue | null>;
+
+/**
+ * BranchProvider component
+ *
+ * Provides branch state management for the application.
+ * Automatically fetches branches when organization changes.
+ *
+ * @example
+ * ```tsx
+ * // In your app
+ * <SsoProvider config={ssoConfig}>
+ *   <BranchProvider>
+ *     <App />
+ *   </BranchProvider>
+ * </SsoProvider>
+ *
+ * // In a component
+ * function MyComponent() {
+ *   const { branches, currentBranch, switchBranch } = useBranch();
+ *   // ...
+ * }
+ * ```
+ */
+declare function BranchProvider({ children, storage, storageKey, onBranchChange, }: BranchProviderProps): react_jsx_runtime.JSX.Element;
+
 /**
  * Hook for authentication actions and state
  */
@@ -163,6 +196,49 @@ interface UseSsoReturn {
  */
 declare function useSso(): UseSsoReturn;
 
+/**
+ * Hook return type for branch management
+ */
+type UseBranchReturn = BranchContextValue;
+/**
+ * Hook for branch management
+ *
+ * Provides access to branch state and operations.
+ * Must be used within a BranchProvider.
+ *
+ * @example
+ * ```tsx
+ * function BranchInfo() {
+ *   const {
+ *     branches,
+ *     currentBranch,
+ *     hasMultipleBranches,
+ *     switchBranch
+ *   } = useBranch();
+ *
+ *   // Auto-selection logic is handled by the provider
+ *   // - If only 1 branch: auto-selected
+ *   // - If multiple: use saved preference or primary branch
+ *
+ *   return (
+ *     <div>
+ *       <p>Current: {currentBranch?.name}</p>
+ *       {hasMultipleBranches && (
+ *         <select onChange={(e) => switchBranch(Number(e.target.value))}>
+ *           {branches.map((branch) => (
+ *             <option key={branch.id} value={branch.id}>
+ *               {branch.name}
+ *             </option>
+ *           ))}
+ *         </select>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useBranch(): UseBranchReturn;
+
 /**
  * SSO Callback component
  *
@@ -241,6 +317,168 @@ declare function OrganizationSwitcher({ className, renderTrigger, renderOption,
  */
 declare function ProtectedRoute({ children, fallback, loginFallback, requiredRole, requiredPermission, onAccessDenied, }: ProtectedRouteProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Organization and Branch Selector Modal
+ *
+ * A modal component for selecting organization and branch.
+ * - If user has only one organization, it's auto-selected
+ * - If user has only one branch, it's auto-selected
+ * - Shows selection UI only when there are multiple options
+ *
+ * @example
+ * ```tsx
+ * function CreateProjectButton() {
+ *   const [modalOpen, setModalOpen] = useState(false);
+ *
+ *   const handleConfirm = (orgId: number, branchId: number) => {
+ *     // Create project with selected org and branch
+ *     createProject({ organization_id: orgId, branch_id: branchId });
+ *     setModalOpen(false);
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <Button onClick={() => setModalOpen(true)}>
+ *         Create Project
+ *       </Button>
+ *       <OrgBranchSelectorModal
+ *         open={modalOpen}
+ *         onClose={() => setModalOpen(false)}
+ *         onConfirm={handleConfirm}
+ *       />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function OrgBranchSelectorModal({ open, onClose, onConfirm, title, requireBranch, loadingComponent, }: OrgBranchSelectorModalProps): react_jsx_runtime.JSX.Element;
+
+type StoredSelection = {
+    orgId: string;
+    orgSlug: string;
+    orgName: string;
+    branchId: string;
+    branchName: string;
+    branchCode: string;
+};
+/**
+ * BranchGate - Ensures user has selected an org/branch before accessing the app.
+ *
+ * Different from OrgBranchSelectorModal:
+ * - OrgBranchSelectorModal: Modal for one-time selection (e.g., creating a project)
+ * - BranchGate: Gate that blocks app access until selection is made, persists globally
+ *
+ * Auto-selection behavior:
+ * - If user has only 1 org and 1 branch: auto-selects and allows access
+ * - If user has multiple options: shows selection modal first
+ * - Stores selection in localStorage for persistence
+ *
+ * @example
+ * ```tsx
+ * // In your app layout
+ * function DashboardLayout({ children }) {
+ *   return (
+ *     <BranchGate
+ *       onSelectionChange={(selection) => {
+ *         // Set API headers globally
+ *         api.defaults.headers['X-Branch-Id'] = selection.branchId;
+ *         api.defaults.headers['X-Org-Id'] = selection.orgId;
+ *       }}
+ *     >
+ *       {children}
+ *     </BranchGate>
+ *   );
+ * }
+ * ```
+ */
+declare function BranchGate({ children, onSelectionChange, storageKey, loadingComponent, title, description, }: BranchGateProps): react_jsx_runtime.JSX.Element;
+declare function useBranchGate(storageKey?: string): {
+    selection: StoredSelection | null;
+    selectedOrg: {
+        id: string;
+        slug: string;
+        name: string;
+    } | null;
+    selectedBranch: {
+        id: string;
+        name: string;
+        code: string;
+    } | null;
+    clearSelection: () => void;
+};
+
+/**
+ * Branch header utilities for API clients
+ *
+ * These utilities help set branch context headers on axios instances.
+ * Works with BranchGate's onSelectionChange callback.
+ *
+ * @example
+ * ```typescript
+ * import { createBranchHeaderSetter } from '@famgia/omnify-react-sso';
+ * import api from './api'; // your axios instance
+ *
+ * // Create setter for your axios instance
+ * const setBranchHeaders = createBranchHeaderSetter(api);
+ *
+ * // Use in BranchGate
+ * <BranchGate onSelectionChange={setBranchHeaders}>
+ *   <App />
+ * </BranchGate>
+ * ```
+ */
+
+/**
+ * Headers set by branch selection
+ */
+declare const BRANCH_HEADERS: {
+    readonly BRANCH_ID: "X-Branch-Id";
+    readonly ORG_ID: "X-Org-Id";
+    readonly BRANCH_NAME: "X-Branch-Name";
+    readonly BRANCH_CODE: "X-Branch-Code";
+};
+/**
+ * Minimal axios-like interface for header management
+ */
+interface AxiosLike {
+    defaults: {
+        headers: {
+            common: Record<string, string | undefined>;
+        };
+    };
+}
+/**
+ * Create a branch header setter function for an axios instance
+ *
+ * @param axiosInstance - Your axios instance
+ * @returns A function to pass to BranchGate's onSelectionChange
+ *
+ * @example
+ * ```typescript
+ * const setBranchHeaders = createBranchHeaderSetter(api);
+ *
+ * <BranchGate onSelectionChange={setBranchHeaders}>
+ *   <App />
+ * </BranchGate>
+ * ```
+ */
+declare function createBranchHeaderSetter(axiosInstance: AxiosLike): (selection: BranchGateSelection | null) => void;
+/**
+ * Set branch headers directly on an axios instance
+ *
+ * @example
+ * ```typescript
+ * import api from './api';
+ * import { setBranchHeaders } from '@famgia/omnify-react-sso';
+ *
+ * // In BranchGate onSelectionChange
+ * <BranchGate onSelectionChange={(s) => setBranchHeaders(api, s)}>
+ *   <App />
+ * </BranchGate>
+ * ```
+ */
+declare function setBranchHeaders(axiosInstance: AxiosLike, selection: BranchGateSelection | null): void;
+
 /**
  * Base service configuration
  */
@@ -1211,4 +1449,4 @@ declare const ssoQueryKeys: {
     };
 };
 
-export { type ApiToken$1 as ApiToken, type AssignRoleInput, type AssignRoleResponse, type AuthCallbackInput, type AuthCallbackResponse, type AuthService, type SsoUser$1 as AuthUser, type AuthUserResponse, type Branch, type BranchService, type BranchesResponse, type CleanupOrphanedInput$1 as CleanupOrphanedInput, type CreatePermissionInput$1 as CreatePermissionInput, type CreateRoleInput$1 as CreateRoleInput, type Organization$1 as Organization, OrganizationSwitcher, OrganizationSwitcherProps, type OrphanedTeam$1 as OrphanedTeam, type Permission$1 as Permission, type PermissionListParams, type PermissionMatrix$1 as PermissionMatrix, type PermissionService, ProtectedRoute, ProtectedRouteProps, type RemoveRoleResponse, type Role$1 as Role, type RoleAssignment, type RoleScope, type RoleService, type RoleWithPermissions$1 as RoleWithPermissions, type ServiceConfig, type Permission$1 as ServicePermission, type Role$1 as ServiceRole, SsoCallback, SsoCallbackProps, SsoConfig, SsoContext, SsoContextValue, SsoOrganization, SsoProvider, SsoProviderProps, type SsoService, type SsoServiceConfig, type SsoUser$1 as SsoServiceUser, SsoUser$2 as SsoUser, type SyncPermissionsInput$1 as SyncPermissionsInput, type SyncPermissionsResponse, type SyncRolesInput, type SyncRolesResponse, type SyncTeamPermissionsInput, type TeamPermissionDetail$1 as TeamPermissionDetail, type TeamService, type TeamWithPermissions$1 as TeamWithPermissions, type TokenService, type UpdatePermissionInput$1 as UpdatePermissionInput, type UpdateRoleInput$1 as UpdateRoleInput, type UseAuthReturn, type UseOrganizationReturn, type UseSsoReturn, type UserRoleService, createAuthService, createBranchService, createPermissionService, createRoleService, createSsoService, createTeamService, createTokenService, createUserRoleService, getEffectivePermissions, getScopeLabel, ssoQueryKeys, useAuth, useOrganization, useSso };
+export { type ApiToken$1 as ApiToken, type AssignRoleInput, type AssignRoleResponse, type AuthCallbackInput, type AuthCallbackResponse, type AuthService, type SsoUser$1 as AuthUser, type AuthUserResponse, BRANCH_HEADERS, type Branch, BranchContext, BranchContextValue, BranchGate, BranchGateProps, BranchGateSelection, BranchProvider, BranchProviderProps, type BranchService, type BranchesResponse, type CleanupOrphanedInput$1 as CleanupOrphanedInput, type CreatePermissionInput$1 as CreatePermissionInput, type CreateRoleInput$1 as CreateRoleInput, OrgBranchSelectorModal, OrgBranchSelectorModalProps, type Organization$1 as Organization, OrganizationSwitcher, OrganizationSwitcherProps, type OrphanedTeam$1 as OrphanedTeam, type Permission$1 as Permission, type PermissionListParams, type PermissionMatrix$1 as PermissionMatrix, type PermissionService, ProtectedRoute, ProtectedRouteProps, type RemoveRoleResponse, type Role$1 as Role, type RoleAssignment, type RoleScope, type RoleService, type RoleWithPermissions$1 as RoleWithPermissions, type ServiceConfig, type Permission$1 as ServicePermission, type Role$1 as ServiceRole, SsoCallback, SsoCallbackProps, SsoConfig, SsoContext, SsoContextValue, SsoOrganization, SsoProvider, SsoProviderProps, type SsoService, type SsoServiceConfig, type SsoUser$1 as SsoServiceUser, SsoUser$2 as SsoUser, type SyncPermissionsInput$1 as SyncPermissionsInput, type SyncPermissionsResponse, type SyncRolesInput, type SyncRolesResponse, type SyncTeamPermissionsInput, type TeamPermissionDetail$1 as TeamPermissionDetail, type TeamService, type TeamWithPermissions$1 as TeamWithPermissions, type TokenService, type UpdatePermissionInput$1 as UpdatePermissionInput, type UpdateRoleInput$1 as UpdateRoleInput, type UseAuthReturn, type UseBranchReturn, type UseOrganizationReturn, type UseSsoReturn, type UserRoleService, createAuthService, createBranchHeaderSetter, createBranchService, createPermissionService, createRoleService, createSsoService, createTeamService, createTokenService, createUserRoleService, getEffectivePermissions, getScopeLabel, setBranchHeaders, ssoQueryKeys, useAuth, useBranch, useBranchGate, useOrganization, useSso };

package/dist/index.d.ts

@@ -1,17 +1,18 @@
 export { DateString, DateTimeString, Locale, LocaleMap, ValidationRule } from '@omnify-base/schemas/common';
 export { defaultLocale, fallbackLocale, getMessage, getMessages, supportedLocales, validationMessages } from '@omnify-base/schemas/i18n';
-export { BranchCreate, BranchUpdate, PermissionCreate, PermissionUpdate, RoleCreate, RolePermission, RolePermissionCreate, RolePermissionUpdate, RoleUpdate, Team, TeamCreate, TeamPermission, TeamPermissionCreate, TeamPermissionUpdate, TeamUpdate, User, UserCreate, UserUpdate, branchCreateSchema, branchSchemas, branchUpdateSchema, permissionCreateSchema, permissionSchemas, permissionUpdateSchema, roleCreateSchema, rolePermissionCreateSchema, rolePermissionSchemas, rolePermissionUpdateSchema, roleSchemas, roleUpdateSchema, teamCreateSchema, teamPermissionCreateSchema, teamPermissionSchemas, teamPermissionUpdateSchema, teamSchemas, teamUpdateSchema, userCreateSchema, userSchemas, userUpdateSchema } from './schemas/index.js';
+export { BranchCache, BranchCacheCreate, BranchCacheUpdate, OrganizationCache, OrganizationCacheCreate, OrganizationCacheUpdate, PermissionCreate, PermissionUpdate, RoleCreate, RolePermission, RolePermissionCreate, RolePermissionUpdate, RoleUpdate, TeamCache, TeamCacheCreate, TeamCacheUpdate, TeamPermission, TeamPermissionCreate, TeamPermissionUpdate, UserCache, UserCacheCreate, UserCacheUpdate, branchCacheCreateSchema, branchCacheSchemas, branchCacheUpdateSchema, organizationCacheCreateSchema, organizationCacheSchemas, organizationCacheUpdateSchema, permissionCreateSchema, permissionSchemas, permissionUpdateSchema, roleCreateSchema, rolePermissionCreateSchema, rolePermissionSchemas, rolePermissionUpdateSchema, roleSchemas, roleUpdateSchema, teamCacheCreateSchema, teamCacheSchemas, teamCacheUpdateSchema, teamPermissionCreateSchema, teamPermissionSchemas, teamPermissionUpdateSchema, userCacheCreateSchema, userCacheSchemas, userCacheUpdateSchema } from './schemas/index.js';
 import * as react from 'react';
-import { b as SsoContextValue, c as SsoProviderProps, S as SsoUser$2, a as SsoOrganization, d as SsoConfig, e as SsoCallbackProps, O as OrganizationSwitcherProps, P as ProtectedRouteProps } from './types-BCBSfJJr.js';
-export { f as SsoCallbackResponse } from './types-BCBSfJJr.js';
+import { b as SsoContextValue, c as SsoProviderProps, B as BranchContextValue, d as BranchProviderProps, S as SsoUser$2, a as SsoOrganization, e as SsoConfig, f as SsoCallbackProps, O as OrganizationSwitcherProps, P as ProtectedRouteProps, g as OrgBranchSelectorModalProps, h as BranchGateProps, i as BranchGateSelection } from './types-CJmA2a9r.js';
+export { l as OrgBranchSelection, k as SsoBranch, j as SsoCallbackResponse } from './types-CJmA2a9r.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-export { branchI18n, getBranchFieldLabel, getBranchFieldPlaceholder, getBranchLabel } from '@omnify-base/schemas/Branch';
+export { branchCacheI18n, getBranchCacheFieldLabel, getBranchCacheFieldPlaceholder, getBranchCacheLabel } from '@omnify-base/schemas/BranchCache';
+export { getOrganizationCacheFieldLabel, getOrganizationCacheFieldPlaceholder, getOrganizationCacheLabel, organizationCacheI18n } from '@omnify-base/schemas/OrganizationCache';
 export { getPermissionFieldLabel, getPermissionFieldPlaceholder, getPermissionLabel, permissionI18n } from '@omnify-base/schemas/Permission';
 export { getRoleFieldLabel, getRoleFieldPlaceholder, getRoleLabel, roleI18n } from '@omnify-base/schemas/Role';
 export { getRolePermissionFieldLabel, getRolePermissionFieldPlaceholder, getRolePermissionLabel, rolePermissionI18n } from '@omnify-base/schemas/RolePermission';
-export { getTeamFieldLabel, getTeamFieldPlaceholder, getTeamLabel, teamI18n } from '@omnify-base/schemas/Team';
+export { getTeamCacheFieldLabel, getTeamCacheFieldPlaceholder, getTeamCacheLabel, teamCacheI18n } from '@omnify-base/schemas/TeamCache';
 export { getTeamPermissionFieldLabel, getTeamPermissionFieldPlaceholder, getTeamPermissionLabel, teamPermissionI18n } from '@omnify-base/schemas/TeamPermission';
-export { getUserFieldLabel, getUserFieldPlaceholder, getUserLabel, userI18n } from '@omnify-base/schemas/User';
+export { getUserCacheFieldLabel, getUserCacheFieldPlaceholder, getUserCacheLabel, userCacheI18n } from '@omnify-base/schemas/UserCache';
 import 'zod';
 
 /**
@@ -24,6 +25,38 @@ declare const SsoContext: react.Context<SsoContextValue | null>;
  */
 declare function SsoProvider({ children, config, onAuthChange }: SsoProviderProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Branch Context
+ *
+ * Provides branch state management across the application.
+ * Must be used within a BranchProvider.
+ */
+declare const BranchContext: react.Context<BranchContextValue | null>;
+
+/**
+ * BranchProvider component
+ *
+ * Provides branch state management for the application.
+ * Automatically fetches branches when organization changes.
+ *
+ * @example
+ * ```tsx
+ * // In your app
+ * <SsoProvider config={ssoConfig}>
+ *   <BranchProvider>
+ *     <App />
+ *   </BranchProvider>
+ * </SsoProvider>
+ *
+ * // In a component
+ * function MyComponent() {
+ *   const { branches, currentBranch, switchBranch } = useBranch();
+ *   // ...
+ * }
+ * ```
+ */
+declare function BranchProvider({ children, storage, storageKey, onBranchChange, }: BranchProviderProps): react_jsx_runtime.JSX.Element;
+
 /**
  * Hook for authentication actions and state
  */
@@ -163,6 +196,49 @@ interface UseSsoReturn {
  */
 declare function useSso(): UseSsoReturn;
 
+/**
+ * Hook return type for branch management
+ */
+type UseBranchReturn = BranchContextValue;
+/**
+ * Hook for branch management
+ *
+ * Provides access to branch state and operations.
+ * Must be used within a BranchProvider.
+ *
+ * @example
+ * ```tsx
+ * function BranchInfo() {
+ *   const {
+ *     branches,
+ *     currentBranch,
+ *     hasMultipleBranches,
+ *     switchBranch
+ *   } = useBranch();
+ *
+ *   // Auto-selection logic is handled by the provider
+ *   // - If only 1 branch: auto-selected
+ *   // - If multiple: use saved preference or primary branch
+ *
+ *   return (
+ *     <div>
+ *       <p>Current: {currentBranch?.name}</p>
+ *       {hasMultipleBranches && (
+ *         <select onChange={(e) => switchBranch(Number(e.target.value))}>
+ *           {branches.map((branch) => (
+ *             <option key={branch.id} value={branch.id}>
+ *               {branch.name}
+ *             </option>
+ *           ))}
+ *         </select>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useBranch(): UseBranchReturn;
+
 /**
  * SSO Callback component
  *
@@ -241,6 +317,168 @@ declare function OrganizationSwitcher({ className, renderTrigger, renderOption,
  */
 declare function ProtectedRoute({ children, fallback, loginFallback, requiredRole, requiredPermission, onAccessDenied, }: ProtectedRouteProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Organization and Branch Selector Modal
+ *
+ * A modal component for selecting organization and branch.
+ * - If user has only one organization, it's auto-selected
+ * - If user has only one branch, it's auto-selected
+ * - Shows selection UI only when there are multiple options
+ *
+ * @example
+ * ```tsx
+ * function CreateProjectButton() {
+ *   const [modalOpen, setModalOpen] = useState(false);
+ *
+ *   const handleConfirm = (orgId: number, branchId: number) => {
+ *     // Create project with selected org and branch
+ *     createProject({ organization_id: orgId, branch_id: branchId });
+ *     setModalOpen(false);
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <Button onClick={() => setModalOpen(true)}>
+ *         Create Project
+ *       </Button>
+ *       <OrgBranchSelectorModal
+ *         open={modalOpen}
+ *         onClose={() => setModalOpen(false)}
+ *         onConfirm={handleConfirm}
+ *       />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function OrgBranchSelectorModal({ open, onClose, onConfirm, title, requireBranch, loadingComponent, }: OrgBranchSelectorModalProps): react_jsx_runtime.JSX.Element;
+
+type StoredSelection = {
+    orgId: string;
+    orgSlug: string;
+    orgName: string;
+    branchId: string;
+    branchName: string;
+    branchCode: string;
+};
+/**
+ * BranchGate - Ensures user has selected an org/branch before accessing the app.
+ *
+ * Different from OrgBranchSelectorModal:
+ * - OrgBranchSelectorModal: Modal for one-time selection (e.g., creating a project)
+ * - BranchGate: Gate that blocks app access until selection is made, persists globally
+ *
+ * Auto-selection behavior:
+ * - If user has only 1 org and 1 branch: auto-selects and allows access
+ * - If user has multiple options: shows selection modal first
+ * - Stores selection in localStorage for persistence
+ *
+ * @example
+ * ```tsx
+ * // In your app layout
+ * function DashboardLayout({ children }) {
+ *   return (
+ *     <BranchGate
+ *       onSelectionChange={(selection) => {
+ *         // Set API headers globally
+ *         api.defaults.headers['X-Branch-Id'] = selection.branchId;
+ *         api.defaults.headers['X-Org-Id'] = selection.orgId;
+ *       }}
+ *     >
+ *       {children}
+ *     </BranchGate>
+ *   );
+ * }
+ * ```
+ */
+declare function BranchGate({ children, onSelectionChange, storageKey, loadingComponent, title, description, }: BranchGateProps): react_jsx_runtime.JSX.Element;
+declare function useBranchGate(storageKey?: string): {
+    selection: StoredSelection | null;
+    selectedOrg: {
+        id: string;
+        slug: string;
+        name: string;
+    } | null;
+    selectedBranch: {
+        id: string;
+        name: string;
+        code: string;
+    } | null;
+    clearSelection: () => void;
+};
+
+/**
+ * Branch header utilities for API clients
+ *
+ * These utilities help set branch context headers on axios instances.
+ * Works with BranchGate's onSelectionChange callback.
+ *
+ * @example
+ * ```typescript
+ * import { createBranchHeaderSetter } from '@famgia/omnify-react-sso';
+ * import api from './api'; // your axios instance
+ *
+ * // Create setter for your axios instance
+ * const setBranchHeaders = createBranchHeaderSetter(api);
+ *
+ * // Use in BranchGate
+ * <BranchGate onSelectionChange={setBranchHeaders}>
+ *   <App />
+ * </BranchGate>
+ * ```
+ */
+
+/**
+ * Headers set by branch selection
+ */
+declare const BRANCH_HEADERS: {
+    readonly BRANCH_ID: "X-Branch-Id";
+    readonly ORG_ID: "X-Org-Id";
+    readonly BRANCH_NAME: "X-Branch-Name";
+    readonly BRANCH_CODE: "X-Branch-Code";
+};
+/**
+ * Minimal axios-like interface for header management
+ */
+interface AxiosLike {
+    defaults: {
+        headers: {
+            common: Record<string, string | undefined>;
+        };
+    };
+}
+/**
+ * Create a branch header setter function for an axios instance
+ *
+ * @param axiosInstance - Your axios instance
+ * @returns A function to pass to BranchGate's onSelectionChange
+ *
+ * @example
+ * ```typescript
+ * const setBranchHeaders = createBranchHeaderSetter(api);
+ *
+ * <BranchGate onSelectionChange={setBranchHeaders}>
+ *   <App />
+ * </BranchGate>
+ * ```
+ */
+declare function createBranchHeaderSetter(axiosInstance: AxiosLike): (selection: BranchGateSelection | null) => void;
+/**
+ * Set branch headers directly on an axios instance
+ *
+ * @example
+ * ```typescript
+ * import api from './api';
+ * import { setBranchHeaders } from '@famgia/omnify-react-sso';
+ *
+ * // In BranchGate onSelectionChange
+ * <BranchGate onSelectionChange={(s) => setBranchHeaders(api, s)}>
+ *   <App />
+ * </BranchGate>
+ * ```
+ */
+declare function setBranchHeaders(axiosInstance: AxiosLike, selection: BranchGateSelection | null): void;
+
 /**
  * Base service configuration
  */
@@ -1211,4 +1449,4 @@ declare const ssoQueryKeys: {
     };
 };
 
-export { type ApiToken$1 as ApiToken, type AssignRoleInput, type AssignRoleResponse, type AuthCallbackInput, type AuthCallbackResponse, type AuthService, type SsoUser$1 as AuthUser, type AuthUserResponse, type Branch, type BranchService, type BranchesResponse, type CleanupOrphanedInput$1 as CleanupOrphanedInput, type CreatePermissionInput$1 as CreatePermissionInput, type CreateRoleInput$1 as CreateRoleInput, type Organization$1 as Organization, OrganizationSwitcher, OrganizationSwitcherProps, type OrphanedTeam$1 as OrphanedTeam, type Permission$1 as Permission, type PermissionListParams, type PermissionMatrix$1 as PermissionMatrix, type PermissionService, ProtectedRoute, ProtectedRouteProps, type RemoveRoleResponse, type Role$1 as Role, type RoleAssignment, type RoleScope, type RoleService, type RoleWithPermissions$1 as RoleWithPermissions, type ServiceConfig, type Permission$1 as ServicePermission, type Role$1 as ServiceRole, SsoCallback, SsoCallbackProps, SsoConfig, SsoContext, SsoContextValue, SsoOrganization, SsoProvider, SsoProviderProps, type SsoService, type SsoServiceConfig, type SsoUser$1 as SsoServiceUser, SsoUser$2 as SsoUser, type SyncPermissionsInput$1 as SyncPermissionsInput, type SyncPermissionsResponse, type SyncRolesInput, type SyncRolesResponse, type SyncTeamPermissionsInput, type TeamPermissionDetail$1 as TeamPermissionDetail, type TeamService, type TeamWithPermissions$1 as TeamWithPermissions, type TokenService, type UpdatePermissionInput$1 as UpdatePermissionInput, type UpdateRoleInput$1 as UpdateRoleInput, type UseAuthReturn, type UseOrganizationReturn, type UseSsoReturn, type UserRoleService, createAuthService, createBranchService, createPermissionService, createRoleService, createSsoService, createTeamService, createTokenService, createUserRoleService, getEffectivePermissions, getScopeLabel, ssoQueryKeys, useAuth, useOrganization, useSso };
+export { type ApiToken$1 as ApiToken, type AssignRoleInput, type AssignRoleResponse, type AuthCallbackInput, type AuthCallbackResponse, type AuthService, type SsoUser$1 as AuthUser, type AuthUserResponse, BRANCH_HEADERS, type Branch, BranchContext, BranchContextValue, BranchGate, BranchGateProps, BranchGateSelection, BranchProvider, BranchProviderProps, type BranchService, type BranchesResponse, type CleanupOrphanedInput$1 as CleanupOrphanedInput, type CreatePermissionInput$1 as CreatePermissionInput, type CreateRoleInput$1 as CreateRoleInput, OrgBranchSelectorModal, OrgBranchSelectorModalProps, type Organization$1 as Organization, OrganizationSwitcher, OrganizationSwitcherProps, type OrphanedTeam$1 as OrphanedTeam, type Permission$1 as Permission, type PermissionListParams, type PermissionMatrix$1 as PermissionMatrix, type PermissionService, ProtectedRoute, ProtectedRouteProps, type RemoveRoleResponse, type Role$1 as Role, type RoleAssignment, type RoleScope, type RoleService, type RoleWithPermissions$1 as RoleWithPermissions, type ServiceConfig, type Permission$1 as ServicePermission, type Role$1 as ServiceRole, SsoCallback, SsoCallbackProps, SsoConfig, SsoContext, SsoContextValue, SsoOrganization, SsoProvider, SsoProviderProps, type SsoService, type SsoServiceConfig, type SsoUser$1 as SsoServiceUser, SsoUser$2 as SsoUser, type SyncPermissionsInput$1 as SyncPermissionsInput, type SyncPermissionsResponse, type SyncRolesInput, type SyncRolesResponse, type SyncTeamPermissionsInput, type TeamPermissionDetail$1 as TeamPermissionDetail, type TeamService, type TeamWithPermissions$1 as TeamWithPermissions, type TokenService, type UpdatePermissionInput$1 as UpdatePermissionInput, type UpdateRoleInput$1 as UpdateRoleInput, type UseAuthReturn, type UseBranchReturn, type UseOrganizationReturn, type UseSsoReturn, type UserRoleService, createAuthService, createBranchHeaderSetter, createBranchService, createPermissionService, createRoleService, createSsoService, createTeamService, createTokenService, createUserRoleService, getEffectivePermissions, getScopeLabel, setBranchHeaders, ssoQueryKeys, useAuth, useBranch, useBranchGate, useOrganization, useSso };