Skip to main content

@helix/shared/types

Shared TypeScript type definitions for the Helix platform.

Overview​

This library provides primitive types, union types, and enums used across all Helix microservices for consistency and type safety.

Installation​

This is an internal library in the Nx monorepo. Import using the TypeScript path alias:

import { ServiceStatus, UserRole, ProductType } from '@helix/shared/types';

Available Types​

Service Types​

import { ServiceMode, Environment, ServiceStatus, ServiceName } from '@helix/shared/types';

const mode: ServiceMode = 'api'; // 'api' | 'worker'
const env: Environment = 'production'; // 'development' | 'staging' | 'production'
const status: ServiceStatus = 'healthy'; // 'healthy' | 'degraded' | 'unhealthy'
const service: ServiceName = 'auth-service'; // All service names

Tenant Types​

import { TenantStatus, ProductType, ProductStatus } from '@helix/shared/types';

const tenantStatus: TenantStatus = 'active'; // 'active' | 'suspended' | 'decommissioned'
const product: ProductType = 'kira'; // 'cleverscreen' | 'kira' | 'vera'
const productStatus: ProductStatus = 'active'; // 'active' | 'suspended' | 'decommissioned'

User Types​

import { UserRole, PermissionScope } from '@helix/shared/types';

// IMPORTANT: Roles are managed by WorkOS RBAC, not stored in databases
const role: UserRole = 'tenant_admin'; // 'tenant_admin' | 'product_admin' | 'user' | 'read_only'

const scopes: PermissionScope[] = [
  'tenant:read',
  'tenant:write',
  'user:read',
  'product:read'
];

API Response Types​

import { ApiResponse, PaginatedResponse } from '@helix/shared/types';

// Success response
const success: ApiResponse<User> = {
  success: true,
  data: { id: '123', email: 'user@example.com' },
  metadata: { processingTime: 45 }
};

// Error response
const error: ApiResponse<User> = {
  success: false,
  error: {
    code: 'NOT_FOUND',
    message: 'User not found',
    details: { userId: '123' }
  }
};

// Paginated response
const paginated: PaginatedResponse<User> = {
  data: [{ id: '1', email: 'user1@example.com' }],
  pagination: {
    total: 100,
    page: 1,
    pageSize: 10,
    totalPages: 10
  }
};

Authentication Types​

import { TokenType, AuthProvider, JWTPayload } from '@helix/shared/types';

const tokenType: TokenType = 'access'; // 'access' | 'refresh'
const provider: AuthProvider = 'workos';

// JWT payload structure (from WorkOS)
const payload: JWTPayload = {
  sub: 'user_01HXYZ123',
  tenantId: 'tenant_abc123',
  role: 'tenant_admin',
  scopes: ['tenant:read', 'tenant:write'],
  iat: 1705580000,
  exp: 1705583600
};

Audit Types​

import { AuditAction, AuditEntityType } from '@helix/shared/types';

const action: AuditAction = 'update'; // 'create' | 'read' | 'update' | 'delete' | 'login' | 'logout' | 'permission_change'
const entityType: AuditEntityType = 'user'; // 'tenant' | 'user' | 'product' | 'file' | 'report' | 'thread' | 'screening'

WorkOS RBAC Integration​

IMPORTANT: User roles and permission scopes are managed by WorkOS RBAC engine:

  • Roles are NOT stored in our databases
  • Roles come from WorkOS JWT tokens
  • Guards validate roles from JWT claims
  • TenantMember records do NOT contain role fields

This design ensures:

  • Single source of truth (WorkOS)
  • No role synchronization issues
  • Faster authorization (no DB queries)
  • Better security (roles in signed tokens)

Usage in Services​

// In a NestJS service
import { 
  UserRole, 
  PermissionScope, 
  ApiResponse,
  ServiceStatus 
} from '@helix/shared/types';

@Injectable()
export class UserService {
  async getUser(userId: string): Promise<ApiResponse<User>> {
    try {
      const user = await this.userRepository.findById(userId);
      
      return {
        success: true,
        data: user,
        metadata: { processingTime: 23 }
      };
    } catch (error) {
      return {
        success: false,
        error: {
          code: 'NOT_FOUND',
          message: 'User not found'
        }
      };
    }
  }
}

Type Guards​

All types are compile-time only. For runtime validation, use type guards:

import { ApiResponse } from '@helix/shared/types';

function isSuccessResponse<T>(response: ApiResponse<T>): response is { success: true; data: T } {
  return response.success === true;
}

const response = await api.getUser('123');

if (isSuccessResponse(response)) {
  console.log(response.data); // TypeScript knows this exists
} else {
  console.error(response.error); // TypeScript knows this exists
}

Development​

# Build the library
nx build shared-types

# Lint the library
nx lint shared-types

# Test the library
nx test shared-types

License​

Proprietary - CleverChain Limited