# 📦 USHI Core Shared Package

Auto-generated documentation of all modules in `src/`. Includes file-level summaries, exports, and structure.

---

## 🆕 Recent Highlights

- ✅ Standardized `ApiErrorCode` enum with extended HTTP error coverage
- ✅ Introduced structured `ApiErrorContext` for detailed debugging
- ✅ Consistent response builders: `ok()`, `created()`, `deleted()`, `internalError()`, etc.
- ✅ `204 No Content` response included
- ✅ Strongly typed and extensible error/success helpers

---



## 🗂️ File Structure

```
📁 api
  📁 errors
    📄 errors.ts
    📄 index.ts
  📄 headers.ts
  📄 index.ts
  📁 responses
    📄 ErrorResponse.ts
    📄 LoginResponse.ts
    📄 SuccessResponse.ts
    📄 apiResponse.ts
    📄 index.ts
  📄 routes.ts
📁 core
  📁 dtos
    📁 base
      📄 BaseDto.ts
      📄 index.ts
    📁 demographics
      📄 DemographicsProfileDto.ts
      📄 index.ts
    📁 identity
      📄 IdentityProfileDto.ts
      📄 index.ts
    📄 index.ts
    📁 lms
      📄 LMSPersonProfileDto.ts
      📄 index.ts
    📁 region
      📄 RegionDto.ts
      📄 index.ts
    📁 role
      📄 RoleAssignmentDto.ts
      📄 RoleDto.ts
      📄 RoleRegistry.ts
      📄 index.ts
    📁 social
      📄 SocialProfileDto.ts
      📄 index.ts
    📁 trial
      📄 TrialParticipantProfileDto.ts
      📄 index.ts
    📁 user
      📄 PersonDto.ts
      📄 PersonProfileDto.ts
      📄 index.ts
    📁 wallet
      📄 WalletProfileDto.ts
      📄 index.ts
  📁 enums
    📄 PersonEnums.ts
    📄 index.ts
  📄 index.ts
📁 env
  📄 browser.ts
  📄 common.ts
  📄 node.ts
📄 index.ts
📁 types
  📄 base.ts
  📄 demographicsProfile.ts
  📄 identityProfile.ts
  📄 index.ts
  📄 lambda.ts
  📄 lmsPersonProfile.ts
  📄 role.ts
  📄 roleAssignment.ts
  📄 socialProfile.ts
  📄 trialParticipantProfile.ts
  📄 user.ts
  📄 userProfile.ts
  📄 walletProfile.ts
📁 utils
  📄 Token.ts
  📄 index.ts
  📄 logger.ts
  📄 roles.ts
  📁 validation
    📄 CheckRules.ts
    📄 index.ts
    📁 schemas
      📄 index.ts
      📄 loginSchema.ts
    📄 zodUtils.ts
```

---

## `.`

| File | Description | Exports |
|------|-------------|---------|
| `index.ts` | — | — |

## `api`

| File | Description | Exports |
|------|-------------|---------|
| `headers.ts` | — | defaultHeaders, enum |
| `index.ts` | — | — |
| `routes.ts` | Flatten nested route object to get a union of all route paths as strings. | ApiRoutes |

## `api/errors`

| File | Description | Exports |
|------|-------------|---------|
| `errors.ts` | — | — |
| `index.ts` | — | — |

## `api/responses`

| File | Description | Exports |
|------|-------------|---------|
| `ErrorResponse.ts` | //  * Returns an error 4xx/5xx API Gateway response. //  * @param message - Error message to return //  * @param statusCode - Optional error code (defaults to 500) // | error, error |
| `LoginResponse.ts` | — | — |
| `SuccessResponse.ts` | Returns a successful 2xx API Gateway response. @template T - Payload type @param body - The response payload (typed) @param statusCode - HTTP status code (defaults to 200) @returns APIGatewayProxyResultV2 with JSON-encoded payload | success |
| `apiResponse.ts` | A serializable object to be returned in an API Gateway response. | buildResponse |
| `index.ts` | — | — |

## `core`

| File | Description | Exports |
|------|-------------|---------|
| `index.ts` | — | — |

## `core/dtos`

| File | Description | Exports |
|------|-------------|---------|
| `index.ts` | — | — |

## `core/dtos/base`

| File | Description | Exports |
|------|-------------|---------|
| `BaseDto.ts` | BaseDto<T>  Abstract base class for all Data Transfer Objects (DTOs) in the USHI platform. Provides common properties and a consistent serialization structure.  @template T - Raw input type extending IBaseDtoInput | — |
| `index.ts` | — | — |

## `core/dtos/demographics`

| File | Description | Exports |
|------|-------------|---------|
| `DemographicsProfileDto.ts` | DemographicsProfileDto  DTO for user identity and demographics used in trials, personalization, and segmentation. | — |
| `index.ts` | — | — |

## `core/dtos/identity`

| File | Description | Exports |
|------|-------------|---------|
| `IdentityProfileDto.ts` | IdentityProfileDto  DTO for structured legal identity associated with a user. Useful for secure trials, identity verification, or eConsent. | — |
| `index.ts` | — | — |

## `core/dtos/lms`

| File | Description | Exports |
|------|-------------|---------|
| `LMSPersonProfileDto.ts` | LMSPersonProfileDto  DTO for user learning profile in the USHI LMS system. | — |
| `index.ts` | — | — |

## `core/dtos/region`

| File | Description | Exports |
|------|-------------|---------|
| `RegionDto.ts` | IRegionDto - Raw input structure for Region | — |
| `index.ts` | — | — |

## `core/dtos/role`

| File | Description | Exports |
|------|-------------|---------|
| `RoleAssignmentDto.ts` | RoleAssignmentDto  DTO class for managing user roles within scoped domains and contexts. Supports auditing, expiration, and status tracking. | — |
| `RoleDto.ts` | RoleDto  Data Transfer Object for Role entities in the USHI platform. Encapsulates role identity (e.g., 'admin', 'student') and domain scope (e.g., LMS, Trial), providing consistent serialization and access to role data. | — |
| `RoleRegistry.ts` | RoleRegistry  Maps each RoleDomain to the valid PersonRole[] values allowed in that domain. This is used for validation, UI dropdowns, and system-wide role management. | RoleRegistry |
| `index.ts` | — | — |

## `core/dtos/social`

| File | Description | Exports |
|------|-------------|---------|
| `SocialProfileDto.ts` | SocialProfileDto  DTO for representing a user's social presence in the USHI community platform. | — |
| `index.ts` | — | — |

## `core/dtos/trial`

| File | Description | Exports |
|------|-------------|---------|
| `TrialParticipantProfileDto.ts` | TrialParticipantProfileDto  DTO for representing a user's enrollment and status within a clinical trial. | — |
| `index.ts` | — | — |

## `core/dtos/user`

| File | Description | Exports |
|------|-------------|---------|
| `PersonDto.ts` | PersonDto  DTO for the global Person entity in the USHI platform. This is the root user object shared across all systems (LMS, Trials, Social). Includes identity linkage via Cognito ID and optional phone number for verification. | — |
| `PersonProfileDto.ts` | PersonProfileDto  Aggregated DTO class that builds a full PersonProfile from raw nested inputs. | — |
| `index.ts` | — | — |

## `core/dtos/wallet`

| File | Description | Exports |
|------|-------------|---------|
| `WalletProfileDto.ts` | WalletProfileDto  DTO for storing blockchain-linked user identity. | — |
| `index.ts` | — | — |

## `core/enums`

| File | Description | Exports |
|------|-------------|---------|
| `PersonEnums.ts` | RoleDomain  Logical domain scopes used in role-based access control across the USHI platform. Enables contextual permission separation (e.g., global vs LMS vs trial-specific). | — |
| `index.ts` | — | — |

## `env`

| File | Description | Exports |
|------|-------------|---------|
| `browser.ts` | — | — |
| `common.ts` | — | — |
| `node.ts` | — | — |

## `types`

| File | Description | Exports |
|------|-------------|---------|
| `base.ts` | Raw input type for DTO constructors | — |
| `demographicsProfile.ts` | IDemographicsProfileDto - Raw input for user identity & demographics | — |
| `identityProfile.ts` | IIdentityProfileDto - Raw input for identity profile | — |
| `index.ts` | — | — |
| `lambda.ts` | Extracted request context fields for logs or analytics | — |
| `lmsPersonProfile.ts` | ILMSPersonProfileDto - Raw input for LMS user profile | — |
| `role.ts` | IRoleDto  Represents the raw input structure for a Role entity, typically used when creating or updating roles in the system. | — |
| `roleAssignment.ts` | Status of a role assignment | — |
| `socialProfile.ts` | ISocialProfileDto - Raw input for social profile creation/update | — |
| `trialParticipantProfile.ts` | ITrialParticipantProfileDto - Raw input for trial profile | — |
| `user.ts` | IPersonDto - Raw input shape for global Person entity | — |
| `userProfile.ts` | PersonProfile - Unified cross-domain representation of a user in the USHI platform. Used for aggregation, display, and platform-wide access decisions. | — |
| `walletProfile.ts` | IWalletProfileDto - Raw input for wallet info | — |

## `utils`

| File | Description | Exports |
|------|-------------|---------|
| `Token.ts` | — | — |
| `index.ts` | — | — |
| `logger.ts` | — | logger |
| `roles.ts` | getActiveAssignmentsForPerson  Filters role assignments to include only those that: - belong to the specified user - are currently active - have not expired  @param userId - The user ID to filter by @param assignments - All role assignments in the system @param now - Optional override for current time (defaults to Date.now()) @returns Array of active, non-expired role assignments | isAdmin, isTrialRole, getActiveAssignmentsForPerson, isRoleStillValid, validateRoleAssignments |

## `utils/validation`

| File | Description | Exports |
|------|-------------|---------|
| `CheckRules.ts` | @deprecated Use Zod schema + validateBody() instead. | — |
| `index.ts` | — | — |
| `zodUtils.ts` | — | validateBody |

## `utils/validation/schemas`

| File | Description | Exports |
|------|-------------|---------|
| `index.ts` | — | — |
| `loginSchema.ts` | — | loginSchema |