📦 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 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 |