TypeScript Interfaces and Types

Relevant source files

The following files were used as context for generating this wiki page:

• src/types.ts
• src/auth-api.ts
• src/auth-client.ts
• src/auth-store.ts
• src/react/login-form.tsx
• src/react/unauthorized.tsx
• src/auth-guard.ts

The @cellarnode/auth package utilizes a strictly typed architecture to manage OTP-based authentication, token storage, and user authorization across CellarNode dashboards. These types define the contract between the core logic (API clients and stores) and the React UI components, ensuring consistent data handling for identities, API responses, and configuration.

The type system is centered around the AuthUser interface, which defines the structure of an authenticated identity, and several functional interfaces that describe the behavior of the authentication lifecycle, including token management and API interactions.

Sources: package.json:3-4, src/types.ts:1-12

Core Data Models

The system relies on a set of fundamental interfaces to represent users and the inputs required for authentication processes.

User and Identity Types

The AuthUser interface represents the authenticated user state, including their role and organizational context. The UserType is a restricted union type defining valid dashboard roles.

Field	Type	Description
id	string	Unique identifier for the user.
email	string	User's primary email address.
name	string	Full name of the user.
userType	UserType	One of "importer", "producer", or "admin".
orgId	string | null	The organization ID associated with the user.
roles	string[]	Array of strings representing specific permissions or roles.

Sources: src/types.ts:1-12, src/types.ts:89

Authentication Input and Output

These types define the shape of data exchanged during registration and OTP verification.

The diagram shows the relationship between registration inputs and subsequent OTP response structures.
Sources: src/types.ts:14-31

Service Interfaces

The library is organized into three primary service layers, each governed by a specific interface.

AuthStore

AuthStore defines the persistence and background management of the JWT access token. It includes methods for retrieval, manual updates, and ensuring a valid token exists (triggering refreshes if necessary).

• Config: AuthStoreConfig includes baseUrl, refreshPath, and refreshBuffer.
• Methods: getAccessToken(), setAccessToken(), clearAccessToken(), and ensureAccessToken().

Sources: src/types.ts:51-64, src/auth-store.ts:4-60

AuthClient

The AuthClient acts as a specialized wrapper around the fetch API. It automatically injects authorization headers and handles 401 retries by interacting with the AuthStore.

• Methods: fetch<T>(path, options) provides a generic way to make authenticated requests.
• Special Flag: skipAuth within options allows bypassing token injection for public endpoints like /auth/login.

Sources: src/types.ts:66-74, src/auth-client.ts:25-83

AuthApi

AuthApi provides high-level methods for authentication actions. It coordinates between the AuthClient and AuthStore to manage the user's session.

Method	Returns	Description
register	Promise<{userId, message}>	Creates a new user account.
requestOtp	Promise<RequestOtpResponse>	Requests a code for the provided email.
verifyOtp	Promise<VerifyOtpResponse>	Validates code and persists the returned token.
logout	Promise<void>	Ends the session.
getMe	Promise<AuthUser>	Fetches current user profile.

Sources: src/types.ts:76-87, src/auth-api.ts:14-72

Error Handling

The package uses a custom AuthError class and associated response interfaces to handle failed authentication attempts and rate limiting.

This flow illustrates how types are used to transition from a raw API error to specific UI feedback.
Sources: src/types.ts:33-49, src/react/login-form.tsx:114-148

AuthError Structure

AuthError extends the standard Error and adds metadata:

• status: HTTP status code (e.g., 401, 403).
• code: Machine-readable error string (e.g., "OTP_INVALID").
• remainingAttempts: Optional count for OTP attempts.

Sources: src/types.ts:33-49

React Component Props

Interfaces in src/react/ define the configuration and callbacks for the UI.

LoginFormProps

This interface provides comprehensive control over the login experience, including branding, theming, and error handling callbacks.

• userType: Restricts login to a specific role.
• onLoginSuccess: Callback triggered after valid OTP verification.
• onError: Allows external systems (like toast notifications) to capture structured error data.

Sources: src/react/login-form.tsx:32-61

UnauthorizedPageProps

Used for access control UI when a user attempts to access a dashboard they are not authorized for.

• expectedRole: The role required for the page.
• dashboardLinks: An array of DashboardLink objects used to redirect users to their correct portal if they are logged into the wrong one.

Sources: src/react/unauthorized.tsx:6-11, src/types.ts:91-95

Conclusion

The TypeScript interfaces and types in this project establish a robust contract between the frontend React components and the underlying authentication services. By centralizing definitions for users, API responses, and service behaviors, the system ensures that authorization logic remains consistent across different dashboard implementations while providing clear, typed error handling and state management.

Sources: src/types.ts:1-95, src/index.ts:1-25