@plyaz/types

Core TypeScript type definitions for the Plyaz Web3 sports platform. This package serves as the foundation for type safety across all frontend and backend services.

Overview

@plyaz/types provides comprehensive TypeScript interfaces, enums, and type definitions for all entities, API contracts, and data structures used throughout the Plyaz ecosystem. This package ensures type consistency across microservices, frontend applications, and shared packages.

Installation

pnpm add @plyaz/types

Architecture Position

@plyaz/types ← Foundation layer (no dependencies)
    ↓
All other packages depend on types

Core Exports

All types can be imported directly from the main package:

import type {
  // User & Authentication
  UserRole,
} from '@plyaz/types';

Type Categories

Core Entities

• User Management: Authentication, profiles, roles, preferences
• Athlete System: Performance tracking, tokenization, campaigns
• Stakeholder Network: Scouts, agents, clubs, fans relationships
• Digital Assets: NFTs, tokens, collectibles, marketplace items

System Types

• API Layer: Request/response schemas, pagination, filtering
• Blockchain: Transaction types, wallet connections, smart contracts
• Events: Event bus messages, notifications, real-time updates
• Configuration: Environment settings, feature flags, constants

Validation Schemas

• Input Validation: Zod-compatible type definitions
• Business Rules: Constraint types for domain logic
• Security: Permission sets, access control types

Usage Examples

Basic Entity Usage

import type { Athlete, PerformanceMetrics, SportCategory } from '@plyaz/types';

const athlete: Athlete = {
  id: 'athlete_123',
  profile: {
    name: 'John Doe',
    sport: SportCategory.FOOTBALL,
    position: 'Forward'
  },
  tokenAddress: '0x...',
  currentRanking: 45
};

const performance: PerformanceMetrics = {
  athleteId: athlete.id,
  period: '2024-Q1',
  goals: 12,
  assists: 8,
  rating: 8.5
};

API Response Typing

import type { ApiResponse, PaginatedResponse, Athlete } from '@plyaz/types';

// Single resource response
type AthleteResponse = ApiResponse<Athlete>;

// Paginated collection response
type AthletesListResponse = PaginatedResponse<Athlete>;

const athletesList: AthletesListResponse = {
  data: [athlete1, athlete2],
  pagination: {
    page: 1,
    limit: 20,
    total: 150,
    hasNext: true
  },
  meta: {
    timestamp: new Date().toISOString(),
    requestId: 'req_123'
  }
};

Event System Typing

import type { EventPayload } from '@plyaz/types';

// Type-safe event handling
const athleteTokenMinted: EventPayload<'ATHLETE_TOKEN_MINTED'> = {
  type: 'ATHLETE_TOKEN_MINTED',
  payload: {
    athleteId: 'athlete_123',
    tokenAddress: '0x...',
    initialSupply: 1000000,
    timestamp: Date.now()
  },
  metadata: {
    source: 'blockchain-service',
    version: '1.0.0'
  }
};

Type Safety Guidelines

• Package
• Documentation

Validation Integration

Types are designed to work seamlessly with validation libraries:

import { z } from 'zod';
import type { User } from '@plyaz/types';

// Zod schema matching TypeScript type
const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(['ATHLETE', 'SCOUT', 'AGENT', 'CLUB', 'FAN']),
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime()
}) satisfies z.ZodType<User>;

Version Management

Semantic Versioning

• Major: Breaking changes to existing types
• Minor: New types or optional properties
• Patch: Documentation updates, fixes

Migration Strategy

• Deprecation notices for 2 versions before removal
• Migration guides for breaking changes
• Backward compatibility helpers when possible

Development

Available Scripts

# Build the package
pnpm build

# Linting
pnpm lint              # Check for lint errors
pnpm lint:fix          # Fix auto-fixable lint errors

# Code formatting
pnpm format            # Format all files
pnpm format:check      # Check formatting without changes

# Type checking
pnpm type:check        # Verify TypeScript types

# Testing
pnpm test              # Run tests with Vitest
pnpm coverage          # Generate test coverage report

# Publishing
pnpm publish           # Publish to npm
pnpm release:publish   # Publish with release process
pnpm publish:ci        # CI-friendly publish (no git checks)
pnpm release           # Create new version with standard-version

Local Development Setup

# Install dependencies
pnpm install

# Run type checking and tests
pnpm type:check && pnpm test

# Build and verify
pnpm build

Contributing Guidelines

1. All types must be exported from appropriate index files
2. Add comprehensive JSDoc documentation
3. Include unit tests for complex type utilities
4. Update CHANGELOG.md for all changes
5. Follow the established naming conventions

Dependencies

This package has zero runtime dependencies to maintain its position as the foundation layer. Only development dependencies are allowed:

• typescript - Type definitions and compilation
• tsd - Type testing utilities (dev only)

Support

For questions about type definitions or to request new types:

1. Check existing documentation and examples
2. Search closed issues for similar requests
3. Create a new issue with the types label
4. Tag the CTO for review