@elevasis/ui 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -44,8 +44,10 @@ declare function getPreset(name: PresetName | (string & {})): ThemePreset;
  */
 interface ApiClientContextValue {
     getAccessToken: () => Promise<string | undefined>;
+    /** @deprecated Read via getOrganizationId() instead. Kept for downstream context consumers during migration. */
     organizationId: string | null;
     isOrganizationReady: boolean;
+    getOrganizationId: () => string | null;
     onError?: (endpoint: string, error: Error, details?: ApiErrorDetails) => void;
 }
 interface ApiErrorDetails {
@@ -56,11 +58,70 @@ interface ApiErrorDetails {
 interface ApiClientProviderProps {
     children: React.ReactNode;
     getAccessToken: () => Promise<string | undefined>;
-    organizationId: string | null;
+    /**
+     * Static org ID. Used when org ID is stable at render time.
+     * Cannot reflect org switches without re-rendering the provider.
+     * Prefer getOrganizationId for dynamic org context.
+     * @deprecated Pass getOrganizationId instead for dynamic org resolution.
+     */
+    organizationId?: string | null;
+    /**
+     * Callback invoked on every request to read the current org ID.
+     * Takes precedence over organizationId when provided.
+     * Allows org switching without re-rendering the provider tree.
+     */
+    getOrganizationId?: () => string | null;
     isOrganizationReady: boolean;
     onError?: (endpoint: string, error: Error, details?: ApiErrorDetails) => void;
 }
 
+/**
+ * Pluggable notification adapter interface.
+ *
+ * Implement this to connect any notification library (Mantine, react-toastify, etc.)
+ * to the Elevasis UI hooks.
+ */
+interface NotificationAdapter {
+    success(title: string, message: string): void;
+    error(title: string, message: string): void;
+    info(title: string, message: string): void;
+    warning(title: string, message: string): void;
+    /** Formats and displays an API error using structured error-utils helpers. */
+    apiError(error: unknown): void;
+}
+/**
+ * Provides a notification adapter to all descendant components.
+ *
+ * Pass a `MantineNotificationAdapter` for Command Center, or any custom
+ * adapter for other consumers (template, tests, etc.).
+ *
+ * When omitted, hooks fall back to the console adapter automatically.
+ *
+ * @example
+ * ```tsx
+ * import { NotificationProvider } from '@repo/ui/provider'
+ * import { mantineNotificationAdapter } from '@repo/ui/provider'
+ *
+ * <NotificationProvider adapter={mantineNotificationAdapter}>
+ *   <App />
+ * </NotificationProvider>
+ * ```
+ */
+declare function NotificationProvider({ adapter, children }: {
+    adapter: NotificationAdapter;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Returns the active notification adapter.
+ *
+ * Falls back to the console adapter when used outside a NotificationProvider,
+ * so hooks remain functional in template environments without Mantine.
+ *
+ * Named `useNotificationAdapter` to avoid collision with the data-fetching
+ * `useNotifications` hook exported from `hooks/monitoring`.
+ */
+declare function useNotificationAdapter(): NotificationAdapter;
+
 /** Flat + per-scheme override pattern. Flat values apply to both; `light`/`dark` win over flat. */
 type WithSchemes<T> = T & {
     light?: T;
@@ -144,6 +205,8 @@ interface OAuthConfig {
     tokenStorage?: 'session';
     /** Pre-select organization in WorkOS flow. */
     organizationId?: string;
+    /** Auth provider for the authorize request. Defaults to 'authkit' (hosted login UI). */
+    provider?: 'authkit' | 'GoogleOAuth' | 'MicrosoftOAuth' | 'GitHubOAuth' | 'AppleOAuth';
 }
 /** Deferred -- will throw at runtime. */
 interface ApiKeyConfig {
@@ -160,16 +223,18 @@ interface ElevasisCoreProviderProps {
      */
     theme?: ElevasisCoreThemeConfig;
     /**
-     * Override organization ID resolution.
-     * Command-center passes Zustand-managed org ID here.
-     * SDK consumers typically omit this (auto-resolved from JWT/API key).
+     * @deprecated Organization ID is now resolved automatically via OrganizationProvider.
+     * This prop is accepted for backwards compatibility during migration but is no longer
+     * used when the full provider stack is active (apiUrl provided).
      */
     organizationId?: string | null;
     /** Custom QueryClient. If omitted, a default is created internally. */
     queryClient?: QueryClient;
     /**
      * API base URL (e.g., 'https://api.elevasis.com' or 'http://localhost:5170').
-     * When provided, ElevasisCoreProvider composes ApiClientProvider + ElevasisServiceProvider internally.
+     * When provided, ElevasisCoreProvider composes the full provider stack:
+     * ApiClientProvider + ElevasisServiceProvider + ProfileProvider +
+     * OrganizationProvider + NotificationProvider + InitializationProvider.
      * When omitted, no service context is provided (theme-only mode).
      */
     apiUrl?: string;
@@ -179,11 +244,25 @@ interface ElevasisCoreProviderProps {
      */
     onError?: (endpoint: string, error: Error, details?: ApiErrorDetails) => void;
     /**
-     * Override organization readiness check.
-     * Defaults to `!!organizationId` if not provided.
-     * Command-center passes `!!currentMembership` for its stricter readiness requirement.
+     * @deprecated Organization readiness is now managed internally by OrganizationProvider.
+     * Accepted for backwards compatibility but ignored when apiUrl is provided.
      */
     isOrganizationReady?: boolean;
+    /**
+     * Notification adapter for displaying success/error/info messages.
+     * When provided, wraps the subtree in a NotificationProvider with this adapter.
+     * When omitted, the console fallback adapter is used automatically.
+     *
+     * ElevasisUIProvider (Mantine variant) passes mantineNotificationAdapter here automatically.
+     * Headless/SDK consumers can pass a custom adapter or omit for console output.
+     */
+    notifications?: NotificationAdapter;
+    /**
+     * Whether to inject CSS variables, `data-elevasis-scheme` attribute, and font links.
+     * Set to `false` when the consumer has its own complete design system and only
+     * needs auth + API from this provider. Defaults to `true`.
+     */
+    injectStyles?: boolean;
     children: ReactNode;
 }
 interface ElevasisProviderProps {
@@ -196,16 +275,15 @@ interface ElevasisProviderProps {
      */
     theme?: ElevasisThemeConfig;
     /**
-     * Override organization ID resolution.
-     * Command-center passes Zustand-managed org ID here.
-     * SDK consumers typically omit this (auto-resolved from JWT/API key).
+     * @deprecated Organization ID is now resolved automatically via OrganizationProvider.
+     * Accepted for backwards compatibility during migration but no longer used internally.
      */
     organizationId?: string | null;
     /** Custom QueryClient. If omitted, a default is created internally. */
     queryClient?: QueryClient;
     /**
      * API base URL (e.g., 'https://api.elevasis.com' or 'http://localhost:5170').
-     * When provided, ElevasisProvider composes ApiClientProvider + ElevasisServiceProvider internally.
+     * When provided, ElevasisUIProvider composes the full provider stack via ElevasisCoreProvider.
      * When omitted, no service context is provided (theme-only mode).
      */
     apiUrl?: string;
@@ -215,9 +293,8 @@ interface ElevasisProviderProps {
      */
     onError?: (endpoint: string, error: Error, details?: ApiErrorDetails) => void;
     /**
-     * Override organization readiness check.
-     * Defaults to `!!organizationId` if not provided.
-     * Command-center passes `!!currentMembership` for its stricter readiness requirement.
+     * @deprecated Organization readiness is now managed internally by OrganizationProvider.
+     * Accepted for backwards compatibility but ignored when apiUrl is provided.
      */
     isOrganizationReady?: boolean;
     children: ReactNode;
@@ -5758,18 +5835,19 @@ declare function TanStackRouterBridge({ children }: {
 /**
  * UI provider for Elevasis-powered applications. Includes Mantine theme integration.
  *
- * Composes: MantineThemeProvider + QueryClientProvider + auth provider +
- * auth bridge. When apiUrl is provided, also composes
- * ApiClientProvider + ElevasisServiceProvider.
+ * A thin Mantine shell around ElevasisCoreProvider. Handles:
+ * - MantineProvider with theme resolution (presets, token overrides, color scheme)
+ * - Google Font injection for preset fonts
+ * - CSS variables resolver
+ * - Mantine notification adapter (wired into NotificationProvider automatically)
  *
- * Supports authkit and oauth modes. apiKey mode will throw until implemented.
+ * All auth, API, profile, organization, and initialization composition is
+ * delegated to ElevasisCoreProvider.
  *
  * @example Command-center (dogfooding)
  * ```tsx
  * <ElevasisUIProvider
  *   auth={{ mode: 'authkit', clientId: '...', redirectUri: '/auth-redirect' }}
- *   organizationId={currentWorkOSOrganizationId}
- *   isOrganizationReady={!!currentMembership}
  *   apiUrl={import.meta.env.VITE_API_SERVER}
  *   onError={handleApiError}
  *   queryClient={queryClient}
@@ -5795,32 +5873,47 @@ declare function TanStackRouterBridge({ children }: {
  * </ElevasisUIProvider>
  * ```
  */
-declare function ElevasisUIProvider({ auth, theme, organizationId, queryClient, apiUrl, onError, isOrganizationReady, children }: ElevasisProviderProps): react_jsx_runtime.JSX.Element;
+declare function ElevasisUIProvider({ theme, children, ...coreProps }: ElevasisProviderProps): react_jsx_runtime.JSX.Element;
 /** @deprecated Use ElevasisUIProvider instead. Alias kept for backwards compatibility. */
 declare const ElevasisProvider: typeof ElevasisUIProvider;
 
 /**
  * Headless root provider for Elevasis-powered applications.
  *
- * Same capabilities as ElevasisUIProvider but without any Mantine dependency.
- * Injects CSS variables via a `<style>` tag and sets `data-elevasis-scheme`
- * on the `<html>` element.
+ * Pure auth + API provider with no style side-effects. Does not inject CSS
+ * variables, set `data-elevasis-scheme`, or load fonts. Consumers that need
+ * Elevasis theming should use `ElevasisProvider` (Mantine) instead.
+ *
+ * When `apiUrl` is provided, composes the full provider stack:
+ *   QueryClientProvider -> AuthProvider -> ApiClientProvider ->
+ *   ElevasisServiceProvider -> ProfileProvider -> OrganizationProvider ->
+ *   NotificationProvider -> InitializationProvider
  *
- * Composes: QueryClientProvider + auth provider + auth bridge.
- * When apiUrl is provided, also composes ApiClientProvider + ElevasisServiceProvider.
+ * The `notifications` prop wires a custom adapter (e.g. mantineNotificationAdapter)
+ * into the NotificationProvider. When omitted, the console fallback is used.
  *
  * @example Headless SDK consumer
  * ```tsx
  * <ElevasisCoreProvider
  *   auth={{ mode: 'authkit', clientId: '...', redirectUri: '/' }}
- *   theme={{ colorScheme: 'dark', preset: 'default' }}
  *   apiUrl="https://api.elevasis.com"
  * >
  *   <Dashboard />
  * </ElevasisCoreProvider>
  * ```
+ *
+ * @example With custom notification adapter
+ * ```tsx
+ * <ElevasisCoreProvider
+ *   auth={{ mode: 'authkit', clientId: '...', redirectUri: '/' }}
+ *   apiUrl="https://api.elevasis.com"
+ *   notifications={myNotificationAdapter}
+ * >
+ *   <Dashboard />
+ * </ElevasisCoreProvider>
+ * ```
  */
-declare function ElevasisCoreProvider({ auth, theme, organizationId, queryClient, apiUrl, onError, isOrganizationReady, children }: ElevasisCoreProviderProps): react_jsx_runtime.JSX.Element;
+declare function ElevasisCoreProvider({ auth, queryClient, apiUrl, onError, notifications, children }: ElevasisCoreProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Hook to access the ElevasisServiceProvider context.
@@ -5851,6 +5944,20 @@ declare function useElevasisServices(): ElevasisServiceContextValue;
  */
 declare function ElevasisServiceProvider({ apiRequest, organizationId, isReady, children }: ElevasisServiceProviderProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Mantine-backed notification adapter.
+ *
+ * Wraps `@mantine/notifications` with the same defaults as `notify.tsx`
+ * (`autoClose: 5000`, `position: 'top-right'`). The `apiError()` method
+ * replicates `showApiErrorNotification` behavior including retryAfter-based
+ * autoClose.
+ *
+ * Use this adapter in Command Center (Mantine-powered) consumers.
+ * Template consumers should omit the NotificationProvider and rely on the
+ * console fallback, or supply their own adapter.
+ */
+declare const mantineNotificationAdapter: NotificationAdapter;
+
 declare function useCommandQueue({ status, limit, offset, humanCheckpoint, timeRange, priorityMin, priorityMax, }?: {
     status?: TaskStatus;
     limit?: number;
@@ -6724,7 +6831,7 @@ declare function useGetExecutionHistory(scheduleId: string | undefined, options?
     executions: {
         id: string;
         createdAt: string;
-        status: "running" | "completed" | "failed" | "cancelled";
+        status: "completed" | "failed" | "running" | "cancelled";
         step: number | null;
         itemLabel: string | null;
         duration: number | null;
@@ -6988,6 +7095,196 @@ declare function useStableAccessToken(): () => Promise<string>;
  */
 declare function useSessionCheck(): void;
 
+/**
+ * Type for the useOrganizations hook return value
+ */
+interface UseOrganizationsReturn$1 {
+    currentWorkOSOrganizationId: string | null;
+    currentMembership: MembershipWithDetails | null;
+    setCurrentWorkOSOrganizationId: (id: string | null) => void;
+    setCurrentMembership: (membership: MembershipWithDetails | null) => void;
+    setOrganizationsInitializing: (initializing: boolean) => void;
+    setOrganizationsLoading: (loading: boolean) => void;
+    setOrganizationsError: (error: string | null) => void;
+    organizations: {
+        isInitializing: boolean;
+        isOrgRefreshing: boolean;
+        error: string | null;
+    };
+}
+/**
+ * Type for the useApiClient hook return value
+ */
+interface UseApiClientReturn {
+    apiRequest: <T = unknown>(path: string, options?: RequestInit) => Promise<T>;
+}
+/**
+ * Return type for useOrgInitialization hook
+ */
+interface UseOrgInitializationReturn {
+    memberships: MembershipWithDetails[];
+    isInitializing: boolean;
+    isLoading: boolean;
+    isInitialized: boolean;
+    error: string | null;
+    currentOrganization: MembershipWithDetails['organization'] | null;
+    retry: () => Promise<void>;
+}
+/**
+ * Factory function to create a useOrgInitialization hook for your app.
+ *
+ * Usage in app:
+ * ```typescript
+ * import { createUseOrgInitialization } from '@repo/ui/organization'
+ * import { useOrganizations } from './hooks/useOrganizations'
+ * import { useApiClient } from './api/hooks/useApiClient'
+ *
+ * export const useOrgInitialization = createUseOrgInitialization(
+ *   useOrganizations,
+ *   useApiClient
+ * )
+ * ```
+ *
+ * This pattern allows the shared package to provide the hook logic
+ * while each app provides its own hook instances.
+ */
+declare function createUseOrgInitialization(useOrganizations: () => UseOrganizationsReturn$1, useApiClient: () => UseApiClientReturn): () => UseOrgInitializationReturn;
+
+interface InitializationError {
+    layer: 'auth' | 'profile' | 'organization';
+    message: string;
+    originalError?: Error;
+}
+interface AppInitializationState {
+    userReady: boolean;
+    organizationReady: boolean;
+    allReady: boolean;
+    isInitializing: boolean;
+    error: InitializationError | null;
+    retry: () => void;
+    profile: SupabaseUserProfile | null;
+}
+/**
+ * Factory function to create a useAppInitialization hook for your app.
+ *
+ * Usage in app:
+ * ```typescript
+ * import { createUseAppInitialization } from '@repo/ui/initialization'
+ * import { useOrgInitialization } from './organization/hooks/useOrgInitialization'
+ *
+ * export const useAppInitialization = createUseAppInitialization(useOrgInitialization)
+ * ```
+ *
+ * This pattern allows the shared package to provide the hook logic
+ * while each app provides its own hook instances.
+ */
+declare function createUseAppInitialization(useOrgInitialization: () => UseOrgInitializationReturn): () => AppInitializationState;
+
+interface ProtectedRouteProps {
+    children: ReactNode;
+    /**
+     * Path to redirect to when user is unauthenticated.
+     * @default '/login'
+     */
+    redirectTo?: string;
+    /**
+     * Rendered while initialization is in progress.
+     * When not provided, nothing is rendered during initialization.
+     */
+    fallback?: ReactNode;
+    /**
+     * Rendered when initialization fails with a non-organization error.
+     * Receives the error and a retry callback.
+     * When not provided, the error is silently swallowed (children not rendered).
+     */
+    errorFallback?: (error: InitializationError, retry: () => void) => ReactNode;
+    /**
+     * When true (default), waits for both user AND organization to be ready
+     * before rendering children. When false, only waits for user readiness.
+     * @default true
+     */
+    waitForOrganization?: boolean;
+}
+/**
+ * Headless route guard for authenticated pages.
+ *
+ * Reads initialization state from the nearest InitializationProvider.
+ * Redirects unauthenticated users to `redirectTo` (default: '/login')
+ * with a `returnTo` search param preserving the current location.
+ *
+ * Organization-layer errors are allowed through — routes like /invitations
+ * must be accessible even when the user has no org membership.
+ *
+ * @example
+ * // With custom fallback (your Mantine loader):
+ * <ProtectedRoute fallback={<AppShellLoader />}>
+ *   <DashboardPage />
+ * </ProtectedRoute>
+ *
+ * @example
+ * // Wait only for user, not org (e.g. /invitations route):
+ * <ProtectedRoute waitForOrganization={false}>
+ *   <InvitationsPage />
+ * </ProtectedRoute>
+ */
+declare function ProtectedRoute({ children, redirectTo, fallback, errorFallback, waitForOrganization }: ProtectedRouteProps): react_jsx_runtime.JSX.Element | null;
+
+interface AdminGuardProps {
+    children: ReactNode;
+    /**
+     * Path to redirect non-admin users to.
+     * @default '/'
+     */
+    redirectTo?: string;
+    /**
+     * Rendered while user readiness is being determined.
+     * When not provided, nothing is rendered during initialization.
+     */
+    fallback?: ReactNode;
+}
+/**
+ * Headless route guard for platform admin pages.
+ *
+ * Reads `profile.is_platform_admin` from the nearest InitializationProvider.
+ * Non-admin users are redirected to `redirectTo` (default: '/').
+ *
+ * Must be nested inside a ProtectedRoute (or equivalent) so that
+ * `userReady` is guaranteed to be true when this guard runs.
+ *
+ * @example
+ * <ProtectedRoute>
+ *   <AdminGuard fallback={<AppShellLoader />}>
+ *     <AdminDashboard />
+ *   </AdminGuard>
+ * </ProtectedRoute>
+ */
+declare function AdminGuard({ children, redirectTo, fallback }: AdminGuardProps): react_jsx_runtime.JSX.Element | null;
+
+interface ProfileContextValue {
+    profile: SupabaseUserProfile | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Consumes the nearest ProfileProvider.
+ *
+ * @throws {Error} If called outside of a ProfileProvider tree.
+ */
+declare function useProfile(): ProfileContextValue;
+/**
+ * Provides shared profile state to its subtree via React Context.
+ *
+ * Wraps useUserProfile so that all consumers share one profile fetch
+ * instead of each triggering an independent sync call.
+ *
+ * Must be rendered inside the auth and service provider layers so that
+ * the underlying hook can access useAuthContext and useElevasisServices.
+ */
+declare function ProfileProvider({ children }: {
+    children: ReactNode;
+}): react.FunctionComponentElement<react.ProviderProps<ProfileContextValue | null>>;
+
 interface UseUserProfileOptions {
     /**
      * Optional error handler for profile sync failures
@@ -7045,6 +7342,63 @@ declare class UserProfileService {
     }>): Promise<SupabaseUserProfile | null>;
 }
 
+/**
+ * The value exposed by OrganizationProvider to all consumers.
+ */
+interface OrganizationContextValue {
+    /** WorkOS organization ID of the currently selected organization. */
+    currentWorkOSOrganizationId: string | null;
+    /** Supabase (UUID) organization ID of the currently selected organization. */
+    currentSupabaseOrganizationId: string | null;
+    /** Full membership record for the currently selected organization. */
+    currentMembership: MembershipWithDetails | null;
+    /** All memberships for the authenticated user. */
+    memberships: MembershipWithDetails[];
+    /** True while the initial membership list is being fetched. */
+    isInitializing: boolean;
+    /** True while a subsequent org switch / refresh is in flight. */
+    isOrgRefreshing: boolean;
+    /** Error message if the membership fetch or org switch failed. */
+    error: string | null;
+    /**
+     * Switch the active organization.
+     *
+     * Persists the selection to `last_visited_org` on the user profile and
+     * invalidates all org-scoped TanStack Query cache entries.
+     *
+     * @param workosOrgId - WorkOS organization ID to switch to.
+     */
+    switchOrganization: (workosOrgId: string) => void;
+    /**
+     * Re-fetch memberships and retry org selection after an error.
+     */
+    retry: () => Promise<void>;
+}
+/**
+ * Consumes the nearest OrganizationProvider.
+ *
+ * @throws {Error} If called outside of an OrganizationProvider tree.
+ */
+declare function useOrganization(): OrganizationContextValue;
+
+/**
+ * Provides organization state to its subtree via React Context.
+ *
+ * Must be rendered inside:
+ * - ElevasisServiceProvider (needs apiRequest)
+ * - ProfileProvider (needs useProfile for last_visited_org preference)
+ * - A TanStack QueryClientProvider (needs useQueryClient for cache invalidation)
+ *
+ * Behaviors:
+ * - Fetches all memberships for the authenticated user via GET /memberships/my-memberships
+ * - Selects the active org by priority: saved preference > WorkOS org ID > first membership
+ * - Persists org switches to PATCH /users/me { last_visited_org }
+ * - Clears all state when the user signs out (user becomes null)
+ */
+declare function OrganizationProvider({ children }: {
+    children: ReactNode;
+}): react.FunctionComponentElement<react.ProviderProps<OrganizationContextValue | null>>;
+
 interface OrganizationsState {
     currentWorkOSOrganizationId: string | null;
     currentSupabaseOrganizationId: string | null;
@@ -7127,61 +7481,6 @@ declare function createUseOrganizations<TStore extends OrganizationsSlice>(useSt
     error: string | null;
 };
 
-/**
- * Type for the useOrganizations hook return value
- */
-interface UseOrganizationsReturn$1 {
-    currentWorkOSOrganizationId: string | null;
-    currentMembership: MembershipWithDetails | null;
-    setCurrentWorkOSOrganizationId: (id: string | null) => void;
-    setCurrentMembership: (membership: MembershipWithDetails | null) => void;
-    setOrganizationsInitializing: (initializing: boolean) => void;
-    setOrganizationsLoading: (loading: boolean) => void;
-    setOrganizationsError: (error: string | null) => void;
-    organizations: {
-        isInitializing: boolean;
-        isOrgRefreshing: boolean;
-        error: string | null;
-    };
-}
-/**
- * Type for the useApiClient hook return value
- */
-interface UseApiClientReturn {
-    apiRequest: <T = unknown>(path: string, options?: RequestInit) => Promise<T>;
-}
-/**
- * Return type for useOrgInitialization hook
- */
-interface UseOrgInitializationReturn {
-    memberships: MembershipWithDetails[];
-    isInitializing: boolean;
-    isLoading: boolean;
-    isInitialized: boolean;
-    error: string | null;
-    currentOrganization: MembershipWithDetails['organization'] | null;
-    retry: () => Promise<void>;
-}
-/**
- * Factory function to create a useOrgInitialization hook for your app.
- *
- * Usage in app:
- * ```typescript
- * import { createUseOrgInitialization } from '@repo/ui/organization'
- * import { useOrganizations } from './hooks/useOrganizations'
- * import { useApiClient } from './api/hooks/useApiClient'
- *
- * export const useOrgInitialization = createUseOrgInitialization(
- *   useOrganizations,
- *   useApiClient
- * )
- * ```
- *
- * This pattern allows the shared package to provide the hook logic
- * while each app provides its own hook instances.
- */
-declare function createUseOrgInitialization(useOrganizations: () => UseOrganizationsReturn$1, useApiClient: () => UseApiClientReturn): () => UseOrgInitializationReturn;
-
 type Organization = NonNullable<MembershipWithDetails['organization']>;
 interface OrganizationSwitcherProps {
     currentOrganization: Organization | undefined;
@@ -7221,28 +7520,52 @@ declare function useApiClientContext(): ApiClientContextValue;
  * }
  * ```
  */
-declare function ApiClientProvider({ children, getAccessToken, organizationId, isOrganizationReady, onError }: ApiClientProviderProps): react_jsx_runtime.JSX.Element;
+declare function ApiClientProvider({ children, getAccessToken, organizationId, getOrganizationId: getOrganizationIdProp, isOrganizationReady, onError }: ApiClientProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
- * Return type of useOrganizations hook (subset needed by useApiClient)
+ * Return type of useOrganizations hook (subset needed by the factory)
  */
 interface UseOrganizationsReturn {
     isInitializing: boolean;
     isOrgRefreshing: boolean;
 }
 /**
- * Factory function to create a useApiClient hook for your app.
- *
- * This pattern allows the shared package to provide the hook logic
- * while each app provides its own useOrganizations hook and API URL.
+ * Hook that returns apiRequest and deferredApiRequest bound to the current
+ * ApiClientContext. apiUrl is the only parameter because org ID is resolved
+ * at call time via getOrganizationId() from context.
  *
- * Usage in app:
+ * Usage:
  * ```typescript
- * import { createUseApiClient } from '@repo/ui/api'
- * import { useOrganizations } from './organization/hooks/useOrganizations'
+ * import { useApiClient } from '@repo/ui/api'
  *
  * const API_URL = import.meta.env.VITE_API_SERVER || 'http://localhost:5170'
+ *
+ * function useMyClient() {
+ *   return useApiClient(API_URL)
+ * }
+ * ```
+ */
+declare function useApiClient(apiUrl: string): {
+    apiRequest: <T>(endpoint: string, options?: RequestInit) => Promise<T>;
+    deferredApiRequest: <T>(endpoint: string, options?: RequestInit) => Promise<T>;
+    isOrganizationReady: boolean;
+    isInitializing: boolean;
+};
+/**
+ * Factory function to create a useApiClient hook for your app.
+ *
+ * @deprecated Use the plain `useApiClient(apiUrl)` hook instead.
+ * The factory pattern is no longer needed because org ID is resolved at
+ * call time via getOrganizationId() from ApiClientContext.
+ *
+ * Migration:
+ * ```typescript
+ * // Before
  * export const useApiClient = createUseApiClient(useOrganizations, API_URL)
+ *
+ * // After
+ * import { useApiClient } from '@repo/ui/api'
+ * // call useApiClient(API_URL) directly in your hook/component
  * ```
  */
 declare function createUseApiClient(useOrganizations: () => UseOrganizationsReturn, apiUrl: string): () => {
@@ -7252,35 +7575,50 @@ declare function createUseApiClient(useOrganizations: () => UseOrganizationsRetu
     isInitializing: boolean;
 };
 
-interface InitializationError {
-    layer: 'auth' | 'profile' | 'organization';
-    message: string;
-    originalError?: Error;
-}
-interface AppInitializationState {
-    userReady: boolean;
-    organizationReady: boolean;
-    allReady: boolean;
-    isInitializing: boolean;
-    error: InitializationError | null;
-    retry: () => void;
-    profile: SupabaseUserProfile | null;
-}
+declare const InitializationContext: react.Context<AppInitializationState | null>;
 /**
- * Factory function to create a useAppInitialization hook for your app.
+ * Consumes the nearest InitializationProvider.
  *
- * Usage in app:
- * ```typescript
- * import { createUseAppInitialization } from '@repo/ui/initialization'
- * import { useOrgInitialization } from './organization/hooks/useOrgInitialization'
+ * @throws {Error} If called outside of an InitializationProvider tree.
+ */
+declare function useInitialization(): AppInitializationState;
+/**
+ * Aggregates auth, profile, and organization state into a single initialization context.
  *
- * export const useAppInitialization = createUseAppInitialization(useOrgInitialization)
- * ```
+ * Must be rendered inside:
+ * - An AuthProvider (needs useAuthContext)
+ * - A ProfileProvider (needs useProfile)
+ * - An OrganizationProvider (needs useOrganization)
  *
- * This pattern allows the shared package to provide the hook logic
- * while each app provides its own hook instances.
+ * Initialization Layers (Sequential):
+ * 1. WorkOS Auth (useAuthContext)
+ * 2. User Profile Sync (useProfile)
+ * 3. Organization Context (useOrganization)
+ *
+ * @example
+ * // Org-scoped pages with data queries (most common)
+ * const { organizationReady } = useInitialization()
+ * const { data, isLoading } = useResources()
+ * if (!organizationReady || isLoading) return <SubshellLoader />
+ *
+ * @example
+ * // Pages accessible without org (invitations, pending)
+ * const { userReady, error } = useInitialization()
+ * if (!userReady) return <SubshellLoader />
+ * if (error?.layer === 'organization') {
+ *   return <PendingInvitationPage message={error.message} />
+ * }
+ *
+ * @example
+ * // Pages with error handling
+ * const { organizationReady, error, retry } = useInitialization()
+ * if (error?.layer === 'organization') return <NoOrgError error={error} />
+ * if (error) return <ErrorCard error={error} onRetry={retry} />
+ * if (!organizationReady) return <SubshellLoader />
  */
-declare function createUseAppInitialization(useOrgInitialization: () => UseOrgInitializationReturn): () => AppInitializationState;
+declare function InitializationProvider({ children }: {
+    children: ReactNode;
+}): react.FunctionComponentElement<react.ProviderProps<AppInitializationState | null>>;
 
-export { AGENT_CONSTANTS, APIClientError, APIErrorAlert, ActionModal, AgentDefinitionDisplay, AgentExecutionTimeline, AgentExecutionVisualizer, AgentIterationEdge, AgentIterationNode, ApiClientProvider, AuthProvider, BaseEdge, BaseNode, CONTAINER_CONSTANTS, ChatHeader, ChatInputArea, ChatInterface, ChatSidebar, CollapsibleJsonSection, CollapsibleSection, ConfigCard, ConfirmationInputModal, ConfirmationModal, ContextViewer, ContractDisplay, CustomModal, CustomSelector, DetailCardSkeleton, ElevasisCoreProvider, ElevasisProvider, ElevasisServiceProvider, ElevasisUIProvider, EmptyState, EmptyVisualizer, ExecutionLogsTable, ExecutionStats, ExecutionStatusBadge, FormFieldRenderer, GRAPH_CONSTANTS, GlowingHandle, GraphBackground, GraphContainer, GraphFitViewButton, GraphFitViewHandler, GraphLegend, JsonViewer, ListSkeleton, MessageBubble, NavigationButton, NewKnowledgeMapEdge, NewKnowledgeMapGraph, NewKnowledgeMapNode, NotificationBell, NotificationItem, NotificationList, NotificationPanel, OperationsService, OrganizationSwitcher, PageNotFound, PageTitleCaption, ResourceCard, ResourceDefinitionSection, ResourceHealthChart, RouterProvider, SHARED_VIZ_CONSTANTS, STATUS_COLORS, StatCard, StatCardSkeleton, StatsCardSkeleton, StyledMarkdown, TIMELINE_CONSTANTS, TabCountBadge, TanStackRouterBridge, TaskCard, TimeRangeSelector, TimelineAxis, TimelineBar, TimelineContainer, TimelineRow, ToolsListDisplay, TrendIndicator, UnifiedWorkflowEdge, UnifiedWorkflowGraph, UnifiedWorkflowNode, UserProfileService, VisualizerContainer, WORKFLOW_CONSTANTS, WorkOSAuthBridge, WorkflowDefinitionDisplay, WorkflowExecutionTimeline, calculateBarPosition, calculateGraphHeight, catalogItemToResourceDefinition, createCssVariablesResolver, createOrganizationsSlice, createUseApiClient, createUseAppInitialization, createUseOrgInitialization, createUseOrganizations, executionsKeys, formatDate, formatDuration, formatErrorMessage, generateShades, getEdgeColor, getEdgeOpacity, getErrorInfo, getErrorTitle, getGraphBackgroundStyles, getHealthColor, getIcon, getPreset, getResourceColor, getResourceIcon, getResourceStatusColor, getStatusColors, getStatusIcon, iconMap, isAPIClientError, mantineThemeOverride, observabilityKeys, scheduleKeys, shouldAnimateEdge, showApiErrorNotification, showErrorNotification, showInfoNotification, showSuccessNotification, showWarningNotification, useActivities, useActivityTrend, useAgentIterationData, useApiClientContext, useAuthContext, useBulkDeleteExecutions, useBusinessImpact, useCancelExecution, useCancelSchedule, useCommandQueue, useCommandQueueTotals, useConnectionHighlight, useCostBreakdown, useCostByModel, useCostSummary, useCostTrends, useCreateSchedule, useDashboardMetrics, useDeleteExecution, useDeleteSchedule, useDeleteTask, useDirectedChainHighlighting, useElevasisServices, useErrorAnalysis, useErrorDetail, useErrorDetails, useErrorDistribution, useErrorTrends, useExecuteAsync, useExecution, useExecutionHealth, useExecutionLogs, useExecutionPath, useExecutions, useFitViewTrigger, useGetExecutionHistory, useGetSchedule, useGraphBackgroundStyles, useGraphHighlighting, useGraphTheme, useListSchedules, useMarkAllAsRead, useMarkAsRead, useMergedExecution, useNewKnowledgeMapLayout, useNodeSelection, useNotificationCount, useNotifications, useOAuthContext, usePatchTask, usePauseSchedule, useReactFlowAgent, useSessionCheck as useRefocusSessionCheck, useResolveAllErrors, useResolveError, useResolveErrorsByExecution, useResourceDefinition, useResources, useResumeSchedule, useRetryExecution, useRouterContext, useSessionCheck, useStableAccessToken, useSubmitAction, useTimelineData, useTopFailingResources, useUnifiedWorkflowLayout, useUnresolveError, useUpdateAnchor, useUpdateSchedule, useUserProfile, useWorkflowStepsLayout, validateEmail };
-export type { ActivityTrendResponse, AgentIterationEdgeData, AgentIterationNodeData, AgentStatus, ApiClientContextValue, ApiClientProviderProps, ApiErrorDetails, ApiKeyConfig, AppInitializationState, AuthAdapter, AuthConfig, AuthKitConfig, BulkDeleteExecutionsParams, BulkDeleteExecutionsResult, BusinessImpactMetrics, CancelExecutionParams, CancelExecutionResult, ContextViewerProps, CostBreakdownItem, CreateScheduleInput, CreateSessionResponse, DeleteExecutionParams, DirectedChainHighlightingOptions, DirectedChainHighlightingResult, EdgeColorOptions, EdgeOpacityOptions, ElevasisCoreProviderProps, ElevasisCoreThemeConfig, ElevasisProviderProps, ElevasisServiceContextValue, ElevasisServiceProviderProps, ElevasisThemeConfig, ElevasisTokenOverrides, ErrorDistributionItem, ErrorDistributionParams, ErrorFilters, ErrorTrendsParams, ExecuteAsyncParams, ExecuteAsyncResult, ExecutionErrorDetails, ExecutionHistoryItem, ExecutionHistoryResponse, ExecutionLogEntry, ExecutionLogsPageResponse, ExecutionLogsTableProps, ExecutionPathState, ExecutionStatus$1 as ExecutionStatus, FailingResource, FitViewButtonVariant, GlowIntensity, GraphFitViewHandlerProps, GraphHeightOptions, GraphHighlightingResult, GraphMode, GraphThemeColors, InitializationError, JsonViewerProps, KnowledgeMapEdgeData, KnowledgeMapNodeData, LinkProps, ListActivitiesResponse, ListSchedulesFilters, ListSchedulesResponse, NavigationButtonProps, NodeColorType, OAuthConfig, OAuthContextValue, OrganizationsActions, OrganizationsSlice, OrganizationsState, PresetName, ResourcesResponse, RetryExecutionParams, RouterAdapter, SerializedKnowledgeMap, SerializedKnowledgeNode, SessionListItem, StatCardProps, StatusColorScheme, StatusIconColors, StepExecutionData, StyledMarkdownProps, SubmitActionRequest, SubmitActionResponse, TablerIcon, TaskSchedule, ThemePreset, TimelineBarProps, TimelineContainerProps, TimelineRowProps, TopFailingResourcesParams, TrendIndicatorProps, UnifiedWorkflowEdgeData, UnifiedWorkflowNodeData, UpdateScheduleInput, UseActivitiesParams, UseActivityTrendParams, UseApiClientReturn, UseExecutionHealthParams, UseExecutionLogsParams, UseOrgInitializationReturn, UseOrganizationsReturn$1 as UseOrganizationsReturn, UseUserProfileReturn, WithSchemes, WorkflowEdgeType, WorkflowStepEdgeData, WorkflowStepNodeData, WorkflowStepsLayoutInput };
+export { AGENT_CONSTANTS, APIClientError, APIErrorAlert, ActionModal, AdminGuard, AgentDefinitionDisplay, AgentExecutionTimeline, AgentExecutionVisualizer, AgentIterationEdge, AgentIterationNode, ApiClientProvider, AuthProvider, BaseEdge, BaseNode, CONTAINER_CONSTANTS, ChatHeader, ChatInputArea, ChatInterface, ChatSidebar, CollapsibleJsonSection, CollapsibleSection, ConfigCard, ConfirmationInputModal, ConfirmationModal, ContextViewer, ContractDisplay, CustomModal, CustomSelector, DetailCardSkeleton, ElevasisCoreProvider, ElevasisProvider, ElevasisServiceProvider, ElevasisUIProvider, EmptyState, EmptyVisualizer, ExecutionLogsTable, ExecutionStats, ExecutionStatusBadge, FormFieldRenderer, GRAPH_CONSTANTS, GlowingHandle, GraphBackground, GraphContainer, GraphFitViewButton, GraphFitViewHandler, GraphLegend, InitializationContext, InitializationProvider, JsonViewer, ListSkeleton, MessageBubble, NavigationButton, NewKnowledgeMapEdge, NewKnowledgeMapGraph, NewKnowledgeMapNode, NotificationBell, NotificationItem, NotificationList, NotificationPanel, NotificationProvider, OperationsService, OrganizationProvider, OrganizationSwitcher, PageNotFound, PageTitleCaption, ProfileProvider, ProtectedRoute, ResourceCard, ResourceDefinitionSection, ResourceHealthChart, RouterProvider, SHARED_VIZ_CONSTANTS, STATUS_COLORS, StatCard, StatCardSkeleton, StatsCardSkeleton, StyledMarkdown, TIMELINE_CONSTANTS, TabCountBadge, TanStackRouterBridge, TaskCard, TimeRangeSelector, TimelineAxis, TimelineBar, TimelineContainer, TimelineRow, ToolsListDisplay, TrendIndicator, UnifiedWorkflowEdge, UnifiedWorkflowGraph, UnifiedWorkflowNode, UserProfileService, VisualizerContainer, WORKFLOW_CONSTANTS, WorkOSAuthBridge, WorkflowDefinitionDisplay, WorkflowExecutionTimeline, calculateBarPosition, calculateGraphHeight, catalogItemToResourceDefinition, createCssVariablesResolver, createOrganizationsSlice, createUseApiClient, createUseAppInitialization, createUseOrgInitialization, createUseOrganizations, executionsKeys, formatDate, formatDuration, formatErrorMessage, generateShades, getEdgeColor, getEdgeOpacity, getErrorInfo, getErrorTitle, getGraphBackgroundStyles, getHealthColor, getIcon, getPreset, getResourceColor, getResourceIcon, getResourceStatusColor, getStatusColors, getStatusIcon, iconMap, isAPIClientError, mantineNotificationAdapter, mantineThemeOverride, observabilityKeys, scheduleKeys, shouldAnimateEdge, showApiErrorNotification, showErrorNotification, showInfoNotification, showSuccessNotification, showWarningNotification, useActivities, useActivityTrend, useAgentIterationData, useApiClient, useApiClientContext, useAuthContext, useBulkDeleteExecutions, useBusinessImpact, useCancelExecution, useCancelSchedule, useCommandQueue, useCommandQueueTotals, useConnectionHighlight, useCostBreakdown, useCostByModel, useCostSummary, useCostTrends, useCreateSchedule, useDashboardMetrics, useDeleteExecution, useDeleteSchedule, useDeleteTask, useDirectedChainHighlighting, useElevasisServices, useErrorAnalysis, useErrorDetail, useErrorDetails, useErrorDistribution, useErrorTrends, useExecuteAsync, useExecution, useExecutionHealth, useExecutionLogs, useExecutionPath, useExecutions, useFitViewTrigger, useGetExecutionHistory, useGetSchedule, useGraphBackgroundStyles, useGraphHighlighting, useGraphTheme, useInitialization, useListSchedules, useMarkAllAsRead, useMarkAsRead, useMergedExecution, useNewKnowledgeMapLayout, useNodeSelection, useNotificationAdapter, useNotificationCount, useNotifications, useOAuthContext, useOrganization, usePatchTask, usePauseSchedule, useProfile, useReactFlowAgent, useSessionCheck as useRefocusSessionCheck, useResolveAllErrors, useResolveError, useResolveErrorsByExecution, useResourceDefinition, useResources, useResumeSchedule, useRetryExecution, useRouterContext, useSessionCheck, useStableAccessToken, useSubmitAction, useTimelineData, useTopFailingResources, useUnifiedWorkflowLayout, useUnresolveError, useUpdateAnchor, useUpdateSchedule, useUserProfile, useWorkflowStepsLayout, validateEmail };
+export type { ActivityTrendResponse, AdminGuardProps, AgentIterationEdgeData, AgentIterationNodeData, AgentStatus, ApiClientContextValue, ApiClientProviderProps, ApiErrorDetails, ApiKeyConfig, AppInitializationState, AuthAdapter, AuthConfig, AuthKitConfig, BulkDeleteExecutionsParams, BulkDeleteExecutionsResult, BusinessImpactMetrics, CancelExecutionParams, CancelExecutionResult, ContextViewerProps, CostBreakdownItem, CreateScheduleInput, CreateSessionResponse, DeleteExecutionParams, DirectedChainHighlightingOptions, DirectedChainHighlightingResult, EdgeColorOptions, EdgeOpacityOptions, ElevasisCoreProviderProps, ElevasisCoreThemeConfig, ElevasisProviderProps, ElevasisServiceContextValue, ElevasisServiceProviderProps, ElevasisThemeConfig, ElevasisTokenOverrides, ErrorDistributionItem, ErrorDistributionParams, ErrorFilters, ErrorTrendsParams, ExecuteAsyncParams, ExecuteAsyncResult, ExecutionErrorDetails, ExecutionHistoryItem, ExecutionHistoryResponse, ExecutionLogEntry, ExecutionLogsPageResponse, ExecutionLogsTableProps, ExecutionPathState, ExecutionStatus$1 as ExecutionStatus, FailingResource, FitViewButtonVariant, GlowIntensity, GraphFitViewHandlerProps, GraphHeightOptions, GraphHighlightingResult, GraphMode, GraphThemeColors, InitializationError, JsonViewerProps, KnowledgeMapEdgeData, KnowledgeMapNodeData, LinkProps, ListActivitiesResponse, ListSchedulesFilters, ListSchedulesResponse, NavigationButtonProps, NodeColorType, NotificationAdapter, OAuthConfig, OAuthContextValue, OrganizationContextValue, OrganizationsActions, OrganizationsSlice, OrganizationsState, PresetName, ProfileContextValue, ProtectedRouteProps, ResourcesResponse, RetryExecutionParams, RouterAdapter, SerializedKnowledgeMap, SerializedKnowledgeNode, SessionListItem, StatCardProps, StatusColorScheme, StatusIconColors, StepExecutionData, StyledMarkdownProps, SubmitActionRequest, SubmitActionResponse, TablerIcon, TaskSchedule, ThemePreset, TimelineBarProps, TimelineContainerProps, TimelineRowProps, TopFailingResourcesParams, TrendIndicatorProps, UnifiedWorkflowEdgeData, UnifiedWorkflowNodeData, UpdateScheduleInput, UseActivitiesParams, UseActivityTrendParams, UseApiClientReturn, UseExecutionHealthParams, UseExecutionLogsParams, UseOrgInitializationReturn, UseOrganizationsReturn$1 as UseOrganizationsReturn, UseUserProfileReturn, WithSchemes, WorkflowEdgeType, WorkflowStepEdgeData, WorkflowStepNodeData, WorkflowStepsLayoutInput };