Skip to content
Last updated

PERS SDK - v2.3.26 / Exports / AuthService

Class: AuthService

Platform-agnostic authentication service Handles login, token refresh, and storage operations

Table of contents

Constructors

Methods

Constructors

constructor

• new AuthService(authApi, authProvider?): AuthService

Parameters

NameType
authApiAuthApi
authProvider?TokenStorageProvider

Returns

AuthService

Defined in

core/auth/services/auth-service.ts:66

Methods

loginTenantAdmin

▸ loginTenantAdmin(jwt, options?): Promise<SessionAuthContextResponseDTO>

Login tenant admin with JWT

Parameters

NameTypeDescription
jwtstringAuthentication token (Firebase JWT)
options?TenantAuthOptionsTenant authentication options (tenantId for multi-tenant admins)

Returns

Promise<SessionAuthContextResponseDTO>

Session response with tenant context

Throws

Error with code MULTIPLE_CONTEXT_SELECTION_REQUIRED when tenantId is required but not provided

Defined in

core/auth/services/auth-service.ts:109


loginUser

▸ loginUser(jwt): Promise<SessionAuthContextResponseDTO>

Login user with JWT

Parameters

NameType
jwtstring

Returns

Promise<SessionAuthContextResponseDTO>

Defined in

core/auth/services/auth-service.ts:122


loginBusiness

▸ loginBusiness(jwt, options?): Promise<SessionAuthContextResponseDTO>

Login as business with JWT

Authenticates a user in a business context. The returned JWT contains the user's role within that business.

Parameters

NameTypeDescription
jwtstringAuthentication token (passkey or Firebase JWT)
options?BusinessAuthOptionsBusiness authentication options (businessId for multi-business users)

Returns

Promise<SessionAuthContextResponseDTO>

Session response with business context and role baked into JWT

Throws

MultipleContextSelectionRequiredError when businessId is required but not provided

Example

// Auto-select if single membership
const response = await authService.loginBusiness(jwt);

// Explicit business selection
const response = await authService.loginBusiness(jwt, { businessId: 'biz-123' });
console.log('Business:', response.business?.displayName);

Defined in

core/auth/services/auth-service.ts:153


loginUserWithRawData

▸ loginUserWithRawData(rawLoginData): Promise<SessionAuthContextResponseDTO>

Login user with raw data (no external auth)

Parameters

NameType
rawLoginDataRawUserData

Returns

Promise<SessionAuthContextResponseDTO>

Defined in

core/auth/services/auth-service.ts:166


refreshAccessToken

▸ refreshAccessToken(refreshToken?): Promise<SessionAuthResponseDTO>

Refresh access token with race condition protection

Parameters

NameType
refreshToken?string

Returns

Promise<SessionAuthResponseDTO>

Defined in

core/auth/services/auth-service.ts:179


clearTokens

▸ clearTokens(): Promise<void>

Clear stored tokens and active refresh operations

Returns

Promise<void>

Defined in

core/auth/services/auth-service.ts:225


isFatalAuthError

▸ isFatalAuthError(errorCode): boolean

Check if an error code indicates a fatal auth failure. Fatal errors require immediate logout - the session cannot be recovered.

Parameters

NameType
errorCodeundefined | string

Returns

boolean

Defined in

core/auth/services/auth-service.ts:237


isDefinitiveAuthFailure

▸ isDefinitiveAuthFailure(error): boolean

Comprehensive check if an error represents a DEFINITIVE auth failure. This is the SINGLE SOURCE OF TRUTH for determining if logout is required.

Returns true for:

  • Known fatal error codes (REFRESH_TOKEN_EXPIRED, TOKEN_REVOKED, etc.)
  • Fatal error codes in error messages (wrapped errors)

Returns false for (retryable/recoverable):

  • Network errors
  • Timeouts
  • 5xx server errors
  • TOKEN_EXPIRED (normal refresh trigger)
  • Raw 401/403 without fatal code (should try refresh first)

NOTE: We intentionally DO NOT treat raw 401/403 status as fatal. The HTTP client handles 401 by attempting token refresh first. Only if refresh fails WITH a fatal code do we logout.

Parameters

NameType
errorunknown

Returns

boolean

Defined in

core/auth/services/auth-service.ts:260


handleAuthFailure

▸ handleAuthFailure(): Promise<void>

Handle authentication failure with provider token recovery.

Before logging out, attempts to recover the session using the stored provider token (Firebase JWT, etc.) if it's still valid.

Recovery Flow:

  1. Check if provider token exists and is not expired
  2. Get the auth type (USER, BUSINESS, TENANT) to know which login to use
  3. Attempt re-authentication with provider token
  4. If successful: Session recovered, stay logged in
  5. If failed: Clear tokens and emit AUTH_FAILED

Returns

Promise<void>

Defined in

core/auth/services/auth-service.ts:300


attemptProviderTokenRecovery

▸ attemptProviderTokenRecovery(): Promise<boolean>

Attempt to recover session using stored provider token. Extracts context (tenantId/businessId) from the current refresh token to ensure the recovered session maintains the same context.

This is a PUBLIC method that can be called by TokenRefreshManager when internal refresh fails, to try external (provider token) recovery before giving up.

Returns

Promise<boolean>

true if session was successfully recovered

Defined in

core/auth/services/auth-service.ts:359


hasValidAuth

▸ hasValidAuth(): Promise<boolean>

Check if we have valid authentication tokens

Returns

Promise<boolean>

Defined in

core/auth/services/auth-service.ts:433


getCurrentUser

▸ getCurrentUser(): Promise<UserDTO>

Get current authenticated user

Returns

Promise<UserDTO>

Defined in

core/auth/services/auth-service.ts:446


getCurrentBusiness

▸ getCurrentBusiness(): Promise<BusinessDTO>

Get current business context

Returns

Promise<BusinessDTO>

Defined in

core/auth/services/auth-service.ts:453


getCurrentAdmin

▸ getCurrentAdmin(): Promise<AdminDTO>

Get current admin context

Returns

Promise<AdminDTO>

Defined in

core/auth/services/auth-service.ts:460