@powerportalspro/react 6.1.0 → 7.0.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ChangeEvent, ReactNode } from 'react';
-import { components, TableMetadata as TableMetadata$1, ViewMetadata, CurrentUserInfo, Transport, AuthClient, PowerPortalsProClient, LoginRequest, LoginResponse, SwitchIdentityResponse, PowerPortalsProError, TableRecord, RetrieveRecordsResponse, GridDataRequest, GridDataResponse, GridFilterBase, ChartAggregation, ColumnSort, ResolvedColumn, TableSecurityPermission, ChartData, OrganizationRequest } from '@powerportalspro/core';
+import { components, TableMetadata as TableMetadata$1, ViewMetadata, CurrentUserInfo, Transport, AuthClient, PowerPortalsProClient, LoginRequest, LoginResponse, SwitchIdentityResponse, ImpersonateResponse, StopImpersonationResponse, ImpersonationSearchResponse, PowerPortalsProError, TableRecord, RetrieveRecordsResponse, GridDataRequest, GridDataResponse, GridFilterBase, ChartAggregation, ColumnSort, ResolvedColumn, TableSecurityPermission, ChartData, OrganizationRequest } from '@powerportalspro/core';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
@@ -343,6 +343,29 @@ interface PowerPortalsProContextValue {
      * alt id is read from the cookie's claims server-side.
      */
     readonly switchIdentity: () => Promise<SwitchIdentityResponse>;
+    /**
+     * Starts impersonating a portal contact, swapping the auth cookie for theirs. Permitted
+     * server-side only for internal users holding the `SystemAdmin` role, and only ever resolves a
+     * contact — so it can never be used to assume another staff identity.
+     *
+     * On `ImpersonateResult.Started` the auth state is refreshed from `/api/auth/me` and now
+     * describes the CONTACT: `user.userId`, `user.roles` and `user.portalUserType` are theirs, with
+     * `user.isImpersonating` and `user.impersonatorName` the only trace of who is behind it. Other
+     * outcomes leave the state untouched so the caller can surface a message.
+     */
+    readonly impersonate: (targetUserId: string) => Promise<ImpersonateResponse>;
+    /**
+     * Ends an impersonation session and restores the internal user. Takes no parameters — the
+     * identity to return to is read from the session's claims server-side. On
+     * `StopImpersonationResult.Stopped` the auth state is refreshed.
+     */
+    readonly stopImpersonation: () => Promise<StopImpersonationResponse>;
+    /**
+     * Searches contacts the current user may impersonate. Returns an empty result — never an
+     * error — when the caller isn't permitted to impersonate or the query is under three
+     * characters, so a picker can render "no matches" without branching on why.
+     */
+    readonly searchImpersonationTargets: (query: string) => Promise<ImpersonationSearchResponse>;
 }
 declare const PowerPortalsProContext: react.Context<PowerPortalsProContextValue | null>;
 
@@ -482,6 +505,27 @@ type UseAuthResult = AuthState & {
      * On `Switched`, the in-memory auth state is refreshed automatically.
      */
     switchIdentity: () => Promise<SwitchIdentityResponse>;
+    /**
+     * Starts impersonating a portal contact. Allowed server-side only for internal users holding
+     * the `SystemAdmin` role, and only ever resolves a contact — never another staff account.
+     *
+     * On `ImpersonateResult.Started` the auth state refreshes and `auth.user` becomes the CONTACT:
+     * their id, their roles, their user type. `auth.user.isImpersonating` and
+     * `auth.user.impersonatorName` are the only fields that say otherwise, which is what makes the
+     * impersonated session an honest rehearsal of what that contact actually sees.
+     */
+    impersonate: (targetUserId: string) => Promise<ImpersonateResponse>;
+    /**
+     * Ends an impersonation session and restores the internal user. Takes no parameters — the
+     * identity to return to comes from the session's own claims, so the client can't pick it.
+     */
+    stopImpersonation: () => Promise<StopImpersonationResponse>;
+    /**
+     * Searches contacts the current user may impersonate — by name, email, or exact user id.
+     * Returns an empty result rather than an error when the caller isn't permitted or the query is
+     * too short, so a picker renders "no matches" without branching on why.
+     */
+    searchImpersonationTargets: (query: string) => Promise<ImpersonationSearchResponse>;
 };
 declare function useAuth(): UseAuthResult;
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ChangeEvent, ReactNode } from 'react';
-import { components, TableMetadata as TableMetadata$1, ViewMetadata, CurrentUserInfo, Transport, AuthClient, PowerPortalsProClient, LoginRequest, LoginResponse, SwitchIdentityResponse, PowerPortalsProError, TableRecord, RetrieveRecordsResponse, GridDataRequest, GridDataResponse, GridFilterBase, ChartAggregation, ColumnSort, ResolvedColumn, TableSecurityPermission, ChartData, OrganizationRequest } from '@powerportalspro/core';
+import { components, TableMetadata as TableMetadata$1, ViewMetadata, CurrentUserInfo, Transport, AuthClient, PowerPortalsProClient, LoginRequest, LoginResponse, SwitchIdentityResponse, ImpersonateResponse, StopImpersonationResponse, ImpersonationSearchResponse, PowerPortalsProError, TableRecord, RetrieveRecordsResponse, GridDataRequest, GridDataResponse, GridFilterBase, ChartAggregation, ColumnSort, ResolvedColumn, TableSecurityPermission, ChartData, OrganizationRequest } from '@powerportalspro/core';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
@@ -343,6 +343,29 @@ interface PowerPortalsProContextValue {
      * alt id is read from the cookie's claims server-side.
      */
     readonly switchIdentity: () => Promise<SwitchIdentityResponse>;
+    /**
+     * Starts impersonating a portal contact, swapping the auth cookie for theirs. Permitted
+     * server-side only for internal users holding the `SystemAdmin` role, and only ever resolves a
+     * contact — so it can never be used to assume another staff identity.
+     *
+     * On `ImpersonateResult.Started` the auth state is refreshed from `/api/auth/me` and now
+     * describes the CONTACT: `user.userId`, `user.roles` and `user.portalUserType` are theirs, with
+     * `user.isImpersonating` and `user.impersonatorName` the only trace of who is behind it. Other
+     * outcomes leave the state untouched so the caller can surface a message.
+     */
+    readonly impersonate: (targetUserId: string) => Promise<ImpersonateResponse>;
+    /**
+     * Ends an impersonation session and restores the internal user. Takes no parameters — the
+     * identity to return to is read from the session's claims server-side. On
+     * `StopImpersonationResult.Stopped` the auth state is refreshed.
+     */
+    readonly stopImpersonation: () => Promise<StopImpersonationResponse>;
+    /**
+     * Searches contacts the current user may impersonate. Returns an empty result — never an
+     * error — when the caller isn't permitted to impersonate or the query is under three
+     * characters, so a picker can render "no matches" without branching on why.
+     */
+    readonly searchImpersonationTargets: (query: string) => Promise<ImpersonationSearchResponse>;
 }
 declare const PowerPortalsProContext: react.Context<PowerPortalsProContextValue | null>;
 
@@ -482,6 +505,27 @@ type UseAuthResult = AuthState & {
      * On `Switched`, the in-memory auth state is refreshed automatically.
      */
     switchIdentity: () => Promise<SwitchIdentityResponse>;
+    /**
+     * Starts impersonating a portal contact. Allowed server-side only for internal users holding
+     * the `SystemAdmin` role, and only ever resolves a contact — never another staff account.
+     *
+     * On `ImpersonateResult.Started` the auth state refreshes and `auth.user` becomes the CONTACT:
+     * their id, their roles, their user type. `auth.user.isImpersonating` and
+     * `auth.user.impersonatorName` are the only fields that say otherwise, which is what makes the
+     * impersonated session an honest rehearsal of what that contact actually sees.
+     */
+    impersonate: (targetUserId: string) => Promise<ImpersonateResponse>;
+    /**
+     * Ends an impersonation session and restores the internal user. Takes no parameters — the
+     * identity to return to comes from the session's own claims, so the client can't pick it.
+     */
+    stopImpersonation: () => Promise<StopImpersonationResponse>;
+    /**
+     * Searches contacts the current user may impersonate — by name, email, or exact user id.
+     * Returns an empty result rather than an error when the caller isn't permitted or the query is
+     * too short, so a picker renders "no matches" without branching on why.
+     */
+    searchImpersonationTargets: (query: string) => Promise<ImpersonationSearchResponse>;
 };
 declare function useAuth(): UseAuthResult;
 

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createContext, useRef, useState, useEffect, useLayoutEffect, useCallback, useContext, useMemo, useSyncExternalStore, useReducer, useId } from 'react';
-import { Transport, AuthClient, PowerPortalsProClient, LoginResult, SwitchIdentityResult } from '@powerportalspro/core';
+import { Transport, AuthClient, PowerPortalsProClient, LoginResult, SwitchIdentityResult, ImpersonateResult, StopImpersonationResult } from '@powerportalspro/core';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
 // src/masking/reformat.ts
@@ -1057,6 +1057,24 @@ function PowerPortalsProProvider({
     }
     return response;
   }, [auth, refreshAuth]);
+  const impersonate = useCallback(async (targetUserId) => {
+    const response = await auth.impersonateAsync(targetUserId);
+    if (response.result === ImpersonateResult.Started) {
+      await refreshAuth();
+    }
+    return response;
+  }, [auth, refreshAuth]);
+  const stopImpersonation = useCallback(async () => {
+    const response = await auth.stopImpersonationAsync();
+    if (response.result === StopImpersonationResult.Stopped || response.result === StopImpersonationResult.ImpersonatorNotFound) {
+      await refreshAuth();
+    }
+    return response;
+  }, [auth, refreshAuth]);
+  const searchImpersonationTargets = useCallback(
+    (query) => auth.searchImpersonationTargetsAsync(query),
+    [auth]
+  );
   useEffect(() => {
     refreshAuth();
   }, [refreshAuth]);
@@ -1073,7 +1091,10 @@ function PowerPortalsProProvider({
       refreshAuth,
       login,
       logout,
-      switchIdentity
+      switchIdentity,
+      impersonate,
+      stopImpersonation,
+      searchImpersonationTargets
     }),
     [
       transportInstance,
@@ -1087,7 +1108,10 @@ function PowerPortalsProProvider({
       refreshAuth,
       login,
       logout,
-      switchIdentity
+      switchIdentity,
+      impersonate,
+      stopImpersonation,
+      searchImpersonationTargets
     ]
   );
   let localizationContent;
@@ -1141,13 +1165,25 @@ function CacheLocaleSync() {
 
 // src/use-auth.ts
 function useAuth() {
-  const { authState, refreshAuth, login, logout, switchIdentity } = usePowerPortalsPro();
+  const {
+    authState,
+    refreshAuth,
+    login,
+    logout,
+    switchIdentity,
+    impersonate,
+    stopImpersonation,
+    searchImpersonationTargets
+  } = usePowerPortalsPro();
   return {
     ...authState,
     refresh: refreshAuth,
     login,
     logout,
-    switchIdentity
+    switchIdentity,
+    impersonate,
+    stopImpersonation,
+    searchImpersonationTargets
   };
 }
 function AuthorizedView({ children, roles, fallback = null }) {