@mudrichenkoevgeny/shared-foundation

TypeScript & Zod contracts, API routes, error codes, permission models, runtime enums, and branded types generated directly from the shared-foundation Kotlin Multiplatform (KMP) repository.

Provides a single source of truth (SSOT) between Kotlin Backend/KMP services and TypeScript/React web applications.

Installation

# pnpm
pnpm add @mudrichenkoevgeny/shared-foundation zod

# npm
npm install @mudrichenkoevgeny/shared-foundation zod

# yarn
yarn add @mudrichenkoevgeny/shared-foundation zod

Features

• Zod Schemas: Auto-generated z.ZodType validation schemas for all Request payloads and Response DTOs (loginByEmailRequestSchema, apiErrorResponseSchema, userDetailsPayloadSchema).
• Runtime Enums: TS types & runtime JS objects for all enums and string unions (UserAuthProvider, UserRole, UserAccountStatus, AccountLockoutType, ClientType, SortOrder, UserSortValues, etc.).
• Route Constants: Strongly typed API endpoint routes (ManagementSecuritySettingsRoutes, OpenLoginRoutes, SelfManagementUserRoutes).
• Error & Permission Codes: Literal string definitions for all application error codes (SecurityErrorCodes, CommonErrorCodes) and permission strings (SecurityPermissionCode, UserPermissionCode).
• Branded Types & Helpers: Type-safe domain identifiers (UserId, PermissionCode, UserSessionId, UserIdentifierId, AuditEventId, ClientDeviceId) with converter helpers (toUserIdOrThrow, toPermissionCodeOrNull).
• Domain Models & Mappers: Fully typed TS domain models (UserSession, UserDetails, ClientDeviceInfo) and their runtime mappers from/to API payloads (toUserSession, toUserSessionPayload).
• Composite Parsers: Helper classes for runtime parsing of polymorphic values (CompositeAuditActionTypeParser, CompositeAuditMetadataKeyParser, CompositeAuditResourceTypeParser).

Quick Usage Example

import { 
  ManagementSecuritySettingsRoutes, 
  SecurityErrorCodes, 
  apiErrorResponseSchema, 
  toUserIdOrThrow 
} from '@mudrichenkoevgeny/shared-foundation';

// 1. Using Route Constants
const url = ManagementSecuritySettingsRoutes.GET_MANAGEMENT_SECURITY_SETTINGS;

// 2. Branded Types
const userId = toUserIdOrThrow('123e4567-e89b-12d3-a456-426614174000');

// 3. Validating API Responses with Zod
async function fetchUserSettings() {
  const response = await fetch(url);
  const json = await response.json();

  if (!response.ok) {
    const error = apiErrorResponseSchema.parse(json);
    if (error.code === SecurityErrorCodes.TOTP_NOT_ENABLED) {
      console.error('TOTP configuration required');
    }
    return;
  }
}

Source Code & Repository

The source code for this library and generator is maintained in the main GitHub repository: GitHub Repository: mudrichenkoevgeny/shared-foundation

License

Apache License 2.0. See LICENSE for details.