# -- types

This document describes the TypeScript interfaces and types used in the authentication system.

## Base Types

```typescript
// Authentication token structure
type Token = {
  accessToken: string; // JWT access token for API authentication
  refreshToken: string; // Token for refreshing access tokens
  expireAt: number; // Unix timestamp of token expiration
};

// Basic user identification
type UserId = string;
type AccountId = string;
type Email = string;
```

## Request Types

### Login Request

```typescript
interface LoginRequest {
  email: string; // User email address (required)
  password: string; // User password (required)
  withUserData?: boolean; // Include user profile data (default: true)
  withAccountData?: boolean; // Include account details (default: true)
}
```

### Password Reset Requests

```typescript
interface SendResetPasswordEmailRequest {
  email: string; // Email address to send reset link
}

interface ResetPasswordRequest {
  newPassword: string; // New password to set
  resetPasswordToken: string; // Token from reset email link
}
```

## Response Types

### Authentication Responses

```typescript
// Base authentication response from SDK
interface AuthenticationResponseDto {
  token: Token;
  user: AuthenticatedUserDto;
}

interface AuthenticatedUserDto {
  id: string; // User unique identifier
}

// Extended login response with additional data
interface LoginResponseData extends AuthenticationResponseDto {
  userData?: {
    user: CustomerUser;
    account: CustomerAccountNameDto;
    accounts: CustomerAccountNameDto[];
  };
  accountData?: GetCustomerAccountResponse;
}

interface LoginResponse extends AuthenticationResponseDto {
  success: boolean;
  data: LoginResponseData;
}
```

### Password Reset Responses

```typescript
interface SendResetPasswordEmailResponse {
  success: boolean;
  message: string; // Status message for user display
}

interface ResetPasswordResponse {
  success: boolean;
  message: string; // Status message for user display
}
```

### Token Refresh Response

```typescript
interface RefreshTokenResponse {
  success: boolean;
  token?: string; // New access token
  refreshToken?: string; // New refresh token
  expireAt?: number; // New expiration timestamp
  message?: string; // Error message if failed
}
```

## Entity Types

### User Types

```typescript
// Complete user information from SDK
interface CustomerUser {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  phoneNumber?: string;
  preferences?: UserPreferences;
  lastLoginAt?: string;
  createdAt: string;
  updatedAt: string;
}

interface UserPreferences {
  language?: string;
  currency?: string;
  notifications?: NotificationSettings;
}

interface NotificationSettings {
  email: boolean;
  push: boolean;
  sms: boolean;
}
```

### Account Types

```typescript
// Basic account information
interface CustomerAccountNameDto {
  id: string;
  name: string;
  externalId: string;
}

// Complete account information from SDK
interface GetCustomerAccountResponse {
  id: string;
  name: string;
  externalId: string;
  description?: string;
  settings: AccountSettings;
  permissions: Permission[];
  addresses: Address[];
  createdAt: string;
  updatedAt: string;
}

interface AccountSettings {
  defaultCurrency: string;
  timezone: string;
  businessHours: BusinessHours;
}

interface Permission {
  id: string;
  name: string;
  scope: string;
}
```

## Composable Types

### API Functions

```typescript
interface AuthApi {
  getAuthenticatedUser: (useStore?: boolean) => Promise<any | null>;
  login: (
    params: LoginRequest,
    useStore?: boolean
  ) => Promise<boolean | undefined>;
  logout: () => Promise<void>;
  sendResetPasswordEmail: (
    email: string
  ) => Promise<SendResetPasswordEmailResponse>;
  resetPassword: (
    newPassword: string,
    resetPasswordToken: string
  ) => Promise<ResetPasswordResponse>;
  getStores: () => Promise<any[] | null>;
}
```

### Helper Functions

```typescript
interface AuthHelpers {
  setTokenCookies: (token: Token) => void;
  setAccountCookies: (customerAccountId: string) => void;
  setStoreCookies: (storeId: string) => void;
  setStoreViewCookies: (storeViewId: string) => void;
  setCurrencyCookies: (currency: string) => void;
  clearTokenCookies: () => void;
  ensureAuthenticated: () => Promise<string>;
}
```

### Getter Functions

```typescript
interface AuthGetters {
  // Currently returns empty ref - future expansion point
  // May include computed properties for authentication state
}
```

### Complete Composable Type

```typescript
interface UseDjustAuth extends AuthApi, AuthHelpers, AuthGetters {}
```

## Store Types

### User Store State

```typescript
interface UserStoreState {
  isAuthenticated: boolean;
  user: CustomerUser | null;
  account: GetCustomerAccountResponse | CustomerAccountNameDto | null;
  accounts: CustomerAccountNameDto[] | null;
  shippingAddresses: GetCustomerAccountAddressesResponse;
  billingAddresses: GetCustomerAccountAddressesResponse;
  currency: string | null;
}
```

### Store Actions

```typescript
interface UserStoreActions {
  loginAuthenticatedUser: (authenticatedUser: {
    user: CustomerUser;
    accounts: CustomerAccountNameDto[];
    account: CustomerAccountNameDto;
    currency: string;
  }) => void;

  setAccount: (account: GetCustomerAccountResponse) => void;

  login: (authenticatedUser: {
    user: CustomerUser;
    accounts: CustomerAccountNameDto[];
    account: GetCustomerAccountResponse | CustomerAccountNameDto;
    currency?: string;
  }) => void;

  logout: () => void;

  setShippingAddresses: (
    addresses: GetCustomerAccountAddressesResponse
  ) => void;
  setBillingAddresses: (addresses: GetCustomerAccountAddressesResponse) => void;
}
```

## Error Types

### Authentication Errors

```typescript
interface AuthError extends Error {
  statusCode?: number;
  data?: {
    message: string;
    code?: string;
    details?: any;
  };
}

// Specific error scenarios
interface ValidationError extends AuthError {
  field: string;
  constraint: string;
}

interface SecurityError extends AuthError {
  reason: "ACCOUNT_LOCKED" | "SUSPICIOUS_ACTIVITY" | "TOKEN_INVALID";
  lockoutDuration?: number;
}
```

## Utility Types

### Cookie Configuration

```typescript
interface CookieConfig {
  maxAge?: number;
  path?: string;
  domain?: string;
  secure?: boolean;
  httpOnly?: boolean;
  sameSite?: "strict" | "lax" | "none";
}
```

### Authentication Context

```typescript
interface AuthContext {
  isAuthenticated: boolean;
  user: CustomerUser | null;
  currentAccount: GetCustomerAccountResponse | null;
  availableAccounts: CustomerAccountNameDto[];
  permissions: Permission[];
  tokenExpiration: number | null;
}
```

## SDK Integration Types

### From djust-front-sdk

```typescript
// Re-exported from SDK
export type {
  AuthenticationResponseDto,
  AuthentificationLoginRequestDto,
} from "@djust-b2b/djust-front-sdk/lib/interfaces/models/auth";

export type { CustomerUser } from "@djust-b2b/djust-front-sdk/lib/interfaces/models/customer-user";

export type {
  GetCustomerAccountResponse,
  GetCustomerAccountAddressesResponse,
} from "@djust-b2b/djust-front-sdk";
```

## Type Guards

### Authentication Type Guards

```typescript
// Helper functions to validate types at runtime
function isValidToken(token: any): token is Token {
  return (
    token &&
    typeof token.accessToken === "string" &&
    typeof token.refreshToken === "string" &&
    typeof token.expireAt === "number"
  );
}

function isAuthenticatedUser(user: any): user is CustomerUser {
  return user && typeof user.id === "string" && typeof user.email === "string";
}

function isLoginResponse(response: any): response is LoginResponse {
  return (
    response &&
    typeof response.success === "boolean" &&
    response.data &&
    isValidToken(response.data.token)
  );
}
```