@kitium-ai/types

Enterprise-ready TypeScript types and interfaces for Kitium AI SaaS platform. Provides a single source of truth for all types across your application.

Usage & Tree-Shaking

This package is ESM-first (type: module) and configured with sideEffects: false and granular subpath exports. Import only what you need to keep bundles small and enable optimal tree-shaking.

• Core entry:

  • import { ApiError } from '@kitiumai/types'

• Auth:

  • import { AuthContext } from '@kitiumai/types/auth'
  • import { AccessPolicy } from '@kitiumai/types/auth/access'
  • import { RbacRole } from '@kitiumai/types/auth/rbac'
  • import { SsoProvider } from '@kitiumai/types/auth/sso'
  • import { TwoFaMethod } from '@kitiumai/types/auth/twofa'

• API:

  • import { ApiRequest } from '@kitiumai/types/api'
  • import { Contract } from '@kitiumai/types/api/contracts'
  • import { ApiErrorShape } from '@kitiumai/types/api/errors'

• Domain:

  • import { User } from '@kitiumai/types/user'
  • import { Organization } from '@kitiumai/types/organization'
  • import { Product } from '@kitiumai/types/product'
  • import { BillingPlan } from '@kitiumai/types/billing'
  • import { PricingTier } from '@kitiumai/types/billing/pricing'
  • import { Entities, EntityId } from '@kitiumai/types/entities'

• Services:

  • import { EmailMessage } from '@kitiumai/types/services/email'
  • import { FileObject } from '@kitiumai/types/services/file'
  • import { SearchQuery } from '@kitiumai/types/services/search'
  • import { DatabaseConfig } from '@kitiumai/types/services/database'
  • import { ServiceMap } from '@kitiumai/types/services'

• Utilities:

  • import { PrimitiveId } from '@kitiumai/types/primitives'
  • import { Validators } from '@kitiumai/types/validators'
  • import { pick, mergeDeep } from '@kitiumai/types/utils'

• Versioned and Experimental:

  • import { V1Schema } from '@kitiumai/types/v1'
  • import { ExperimentalFeature } from '@kitiumai/types/experimental'

Type Declarations

Type declarations are emitted to dist/**/*.d.ts for each subpath. The package also sets typesVersions to point to dist/* to ensure editors and build tools resolve the correct types per entry.

Notes

• Dual publishing: both ESM (.js) and CJS (.cjs) builds are provided for compatibility.
• Avoid importing from deep file paths under dist; prefer documented subpath exports shown above.
• When adding new modules under src/, ensure tsup.config.ts includes them as entry points and update package.json exports accordingly.

Overview

This package provides a comprehensive, type-safe type system designed for scalable SaaS applications. It ensures consistency across:

• Domain Models - Core business entities
• API Contracts - Request/response types
• Database Entities - Persistence layer mappings
• Validators - Runtime validation with Zod
• Utilities - Reusable type helpers

Quickstart

Use the stable, versioned entrypoint for production and the experimental surface when you want access to preview contracts:

// Stable contract pinned to the current major surface
import { User, APIResponse, VALIDATORS, Identifier } from '@kitium-ai/types/v1';

const payload: APIResponse<User> = {
  success: true,
  status: 200,
  data: {
    id: Identifier('user_123'),
    email: 'user@example.com',
    firstName: 'Ada',
    lastName: 'Lovelace',
    status: 'active',
    roles: ['member'],
    permissions: [],
    createdAt: new Date().toISOString(),
    updatedAt: new Date().toISOString(),
  },
  timestamp: new Date().toISOString(),
};

// Opt-in preview surface (safe to tree-shake away)
import { stability } from '@kitium-ai/types/experimental';
console.log(`Using ${stability} contracts`);

// Runtime validation with branded primitives
const result = VALIDATORS.userRegistration.safeParse({
  email: 'user@example.com',
  firstName: 'Ada',
  lastName: 'Lovelace',
  password: 'Supers3cret!',
  confirmPassword: 'Supers3cret!',
  acceptTerms: true,
  acceptPrivacy: true,
});

Installation

npm install @kitium-ai/types
yarn add @kitium-ai/types

Dependencies

• zod (^3.22.4) - Runtime validation and type inference

Versioned entrypoints

• @kitium-ai/types/v1 — pinned stable contract for production consumers
• @kitium-ai/types/experimental — opt-in preview surface isolated from the stable API

Logging

Logger utilities now live in @kitiumai/logger to keep this package focused on transport-safe types.

API references

The package ships typed, runtime-safe entrypoints to mirror your platform surface area:

• @kitium-ai/types — full domain and API surface (auth, users, organizations, billing, products, errors, utilities)
• @kitium-ai/types/v1 — stable, versioned alias of the primary surface
• @kitium-ai/types/experimental — opt-in preview exports for early adopters
• @kitium-ai/types/auth, @kitium-ai/types/organization, @kitium-ai/types/product, @kitium-ai/types/billing — focused domain bundles
• @kitium-ai/types/api — request/response contracts, pagination helpers, webhook payloads
• @kitium-ai/types/primitives — branded identifiers (Identifier, IsoDateTimeString, Uuid) and helper utilities
• @kitium-ai/types/errors — error codes, severities, and response contracts
• @kitium-ai/types/utils — cross-cutting helpers (Result, Pagination, collection helpers)
• VALIDATORS namespace — pre-built Zod schemas for runtime validation across auth, billing, product, and webhook flows

Architecture

1. Domain Models (Business Logic)

Core entity types representing your business domain:

import { User, Organization, Product } from '@kitium-ai/types';

const user: User = {
  id: 'user-123',
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe',
  // ... more properties
};

Key entities:

• User - User profile with authentication status
• Organization - Multi-tenant organization
• Team - Teams within organizations
• Product - Product definitions
• Subscription - Billing subscriptions
• Invoice - Invoice records
• Session - User sessions

2. API Types

Request/response contracts for API communication:

import {
  UserRegistrationRequest,
  UpdateUserProfileRequest,
  APIResponse,
  PaginatedResponse,
} from '@kitium-ai/types';

// Request types
const registrationData: UserRegistrationRequest = {
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe',
  password: 'SecurePassword123!',
  confirmPassword: 'SecurePassword123!',
  acceptTerms: true,
  acceptPrivacy: true,
};

// Response wrapper
const response: APIResponse<User> = {
  success: true,
  status: 200,
  data: user,
  timestamp: new Date().toISOString(),
};

// Paginated responses
const paginated: PaginatedResponse<User> = {
  items: [user1, user2],
  pagination: {
    page: 1,
    pageSize: 20,
    totalItems: 100,
    totalPages: 5,
    hasNextPage: true,
    hasPreviousPage: false,
  },
};

Key request/response types:

• CreateOrganizationRequest / UpdateOrganizationRequest
• CreateProductRequest / CreateFeatureRequest
• CreateSubscriptionRequest / UpdateSubscriptionRequest
• ListQueryParams - Standardized list query parameters
• FileUpload - File upload metadata
• WebhookConfig - Webhook configuration
• APIResponse<T> - Standard response wrapper
• PaginatedResponse<T> - Paginated results

3. Validators (Runtime Validation)

Zod-based schemas for runtime validation and type safety:

import { Validators, UserRegistrationSchema } from '@kitium-ai/types';
import { z } from 'zod';

// Option 1: Using pre-instantiated validators
const registrationResult = Validators.userRegistration.safeParse(data);
if (!registrationResult.success) {
  console.error(registrationResult.error.errors);
}

// Option 2: Direct schema validation
try {
  const validatedData = UserRegistrationSchema.parse(data);
  console.log('Valid:', validatedData);
} catch (error) {
  if (error instanceof z.ZodError) {
    error.errors.forEach((err) => {
      console.log(`${err.path}: ${err.message}`);
    });
  }
}

// Option 3: Type inference
type UserRegistrationType = z.infer<typeof UserRegistrationSchema>;

// Option 4: Safe parsing
const result = UserRegistrationSchema.safeParse(data);
if (result.success) {
  const validated = result.data; // Type-safe
}

Available validators:

• Authentication: LoginCredentialsSchema, PasswordResetConfirmSchema, MFAVerificationSchema
• Users: UserRegistrationSchema, UpdateUserProfileSchema
• Organizations: CreateOrganizationSchema, UpdateOrganizationSchema
• Products: CreateProductSchema, CreateFeatureSchema
• Billing: CreateSubscriptionSchema, UpdateSubscriptionSchema, PricingPlanSchema
• API: ListQueryParamsSchema, FileUploadSchema, WebhookConfigSchema
• And many more...

4. Database Entities

Type-safe database entity definitions for your persistence layer:

import type { Entities } from '@kitium-ai/types';

// Access entity types via the Entities namespace
type UserDB = Entities.UserEntity;
type OrganizationDB = Entities.OrganizationEntity;
type SubscriptionDB = Entities.SubscriptionEntity;

// Create database entities
const userEntity: UserDB = {
  id: 'user-123',
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe',
  passwordHash: 'hash...',
  status: 'active',
  roles: ['member'],
  permissions: ['org:read', 'user:read'],
  timezone: 'UTC',
  language: 'en',
  emailVerified: true,
  phoneVerified: false,
  twoFactorEnabled: false,
  createdAt: new Date(),
  updatedAt: new Date(),
  createdBy: 'system',
  version: 1,
};

Entity features:

• BaseEntity - Core fields (id, timestamps, version)
• AuditableEntity - Extends BaseEntity with audit trail
• Specific entities with database-optimized fields
• Repository<T> interface for type-safe data access

Key database entities:

• UserEntity - User with password hash
• OrganizationEntity - Organization data
• TeamEntity - Team management
• ProductEntity - Product definitions
• SubscriptionEntity - Subscription records
• InvoiceEntity - Invoice data
• AuditLogEntity - Audit trail
• And more...

5. Enums for Type Safety

Comprehensive enums for constants:

import {
  AccountStatus,
  UserRole,
  Permission,
  OrganizationPlan,
  SubscriptionStatus,
  PaymentStatus,
  ProductStatus,
  FeatureStatus,
} from '@kitium-ai/types';

const userRole: UserRole = UserRole.MEMBER;
const planType: OrganizationPlan = OrganizationPlan.PROFESSIONAL;
const subscriptionStatus: SubscriptionStatus = SubscriptionStatus.ACTIVE;
const paymentStatus: PaymentStatus = PaymentStatus.COMPLETED;

Usage Examples

Example 1: User Registration

import { UserRegistrationSchema, UserEntity, Validators } from '@kitium-ai/types';

// Frontend: Validate user input
async function handleUserRegistration(formData: unknown) {
  const validation = Validators.userRegistration.safeParse(formData);

  if (!validation.success) {
    // Handle validation errors
    return { error: validation.error.errors };
  }

  // Send validated data to API
  const response = await fetch('/api/auth/register', {
    method: 'POST',
    body: JSON.stringify(validation.data),
  });

  return response.json();
}

// Backend: Create database entity
function createUserEntity(validatedData: UserRegistration): UserEntity {
  return {
    id: generateId(),
    email: validatedData.email,
    firstName: validatedData.firstName,
    lastName: validatedData.lastName,
    passwordHash: hashPassword(validatedData.password),
    status: 'pending_verification',
    roles: ['member'],
    permissions: ['user:read', 'org:read'],
    timezone: validatedData.timezone || 'UTC',
    language: validatedData.language || 'en',
    emailVerified: false,
    phoneVerified: false,
    twoFactorEnabled: false,
    createdAt: new Date(),
    updatedAt: new Date(),
    createdBy: 'system',
    version: 1,
  };
}

Example 2: API Response Handling

import { APIResponse, User, PaginatedResponse } from '@kitium-ai/types';

// Type-safe API response handler
async function fetchUser(id: string): Promise<APIResponse<User>> {
  const response = await fetch(`/api/users/${id}`);
  const data: APIResponse<User> = await response.json();

  if (!data.success) {
    throw new Error(data.error?.message || 'Failed to fetch user');
  }

  return data; // data.data is type User
}

// Type-safe paginated list handler
async function fetchUsers(page: number) {
  const response = await fetch(`/api/users?page=${page}`);
  const data: APIResponse<PaginatedResponse<User>> = await response.json();

  if (!data.success) throw new Error('Failed to fetch users');

  const pagination = data.data!.pagination;
  console.log(`Page ${pagination.page} of ${pagination.totalPages}`);

  return data.data!.items; // Array<User>
}

Example 3: Form Validation

import { UpdateUserProfileSchema, Validators } from '@kitium-ai/types';

function handleProfileUpdate(formData: FormData) {
  const data = Object.fromEntries(formData);

  // Option 1: Direct validation
  try {
    const validated = UpdateUserProfileSchema.parse(data);
    // Use validated data
  } catch (error) {
    // Handle validation errors
  }

  // Option 2: Safe validation with error mapping
  const result = Validators.updateUserProfile.safeParse(data);

  if (result.success) {
    // Send to API
  } else {
    // Display field errors
    const fieldErrors = result.error.flatten();
    return { fieldErrors: fieldErrors.fieldErrors };
  }
}

Example 4: Database Operations

import type { Entities } from '@kitium-ai/types';

// Type-safe repository pattern
class UserRepository implements Repository<UserEntity> {
  async create(user: Omit<UserEntity, keyof BaseEntity>): Promise<UserEntity> {
    const entity: UserEntity = {
      ...user,
      id: generateId(),
      createdAt: new Date(),
      updatedAt: new Date(),
      version: 1,
    };

    // Save to database
    await db.users.insert(entity);
    return entity;
  }

  async findById(id: string): Promise<UserEntity | null> {
    return db.users.findOne({ id });
  }

  async update(
    id: string,
    updates: Partial<Omit<UserEntity, keyof BaseEntity>>
  ): Promise<UserEntity> {
    const user = await this.findById(id);
    if (!user) throw new Error('User not found');

    const updated: UserEntity = {
      ...user,
      ...updates,
      updatedAt: new Date(),
      version: user.version + 1,
    };

    await db.users.update({ id }, updated);
    return updated;
  }
}

Module Structure

@kitium-ai/types
├── auth.ts           # Authentication & authorization types
├── user.ts           # User management types
├── organization.ts   # Organization & team types
├── product.ts        # Product management types
├── billing.ts        # Billing & subscription types
├── api.ts            # API request/response types
├── errors.ts         # Error handling types
├── utils.ts          # Utility types & helpers
├── validators.ts     # Zod validation schemas
├── entities.ts       # Database entity types
└── index.ts          # Main exports

Type Export Patterns

Pattern 1: Import Domain Types

// Import specific types
import { User, Organization, Product } from '@kitium-ai/types';

// Use in application
const user: User = getUser();

Pattern 2: Import API Request Types

import { CreateOrganizationRequest, UpdateUserProfileRequest } from '@kitium-ai/types';

// Strongly typed API calls
async function createOrganization(data: CreateOrganizationRequest) {
  // ...
}

Pattern 3: Use Validators Module

import { Validators, ValidatorSchemas } from '@kitium-ai/types';
import { z } from 'zod';

// Pre-instantiated validators
Validators.userRegistration.safeParse(data);

// Or use schemas directly
type MyType = z.infer<typeof ValidatorSchemas.UserRegistrationSchema>;

Pattern 4: Use Entity Types

import type { Entities } from '@kitium-ai/types';

type UserDB = Entities.UserEntity;
type OrganizationDB = Entities.OrganizationEntity;

// Implement repositories
class UserDB implements Repository<Entities.UserEntity> {
  // ...
}

Security Best Practices

1. Always Validate User Input

// ✅ Good
const validated = UserRegistrationSchema.parse(userInput);

// ❌ Bad - Don't trust user input
const user = userInput as User;

2. Use Enums for Authorization

// ✅ Good - Type-safe permission checking
if (user.permissions.includes(Permission.ORG_ADMIN)) {
  // Allow operation
}

// ❌ Bad - String magic
if (user.permissions.includes('admin')) {
  // Allow operation
}

3. Never Expose Sensitive Fields

// ✅ Good - Exclude sensitive fields
type SafeUser = Omit<User, 'passwordHash' | 'mfaSecret'>;

// ❌ Bad - Expose all fields
const response = { data: user };

4. Validate Before Database Operations

// ✅ Good - Validate request
const validated = CreateUserSchema.parse(request.body);
const user = await userRepository.create(validated);

// ❌ Bad - No validation
const user = await userRepository.create(request.body);

5. Use Immutable Types

// Domain types use 'readonly' to prevent mutations
export interface User {
  readonly id: string;
  readonly email: string;
  readonly roles: readonly UserRole[]; // Read-only array
}

Advanced Usage

Custom Validator Creation

import { createValidator } from '@kitium-ai/types';
import { z } from 'zod';

const CustomSchema = z.object({
  name: z.string().min(1),
  value: z.number().positive(),
});

const customValidator = createValidator(CustomSchema);
const result = customValidator.safeParse(data);

Extending Types

import { User } from '@kitium-ai/types';

// Extend user with application-specific fields
interface AppUser extends User {
  readonly customField: string;
}

// Use in application
const appUser: AppUser = {
  ...baseUser,
  customField: 'value',
};

Type Guards

import { User, Admin } from '@kitium-ai/types';

// Type guard for user role
function isAdmin(user: User): boolean {
  return user.roles.includes(UserRole.ADMIN);
}

// Usage
if (isAdmin(user)) {
  // Perform admin operations
}

Error Handling

Using Error Types

import {
  ErrorCode,
  ApplicationError,
  ValidationException,
  ResourceNotFoundException,
} from '@kitium-ai/types';

// Create typed error
const error: ValidationException = {
  code: ErrorCode.VALIDATION_FAILED,
  statusCode: 422,
  message: 'Validation failed',
  severity: ErrorSeverity.ERROR,
  validationErrors: [
    {
      field: 'email',
      message: 'Invalid email format',
      code: 'INVALID_EMAIL',
    },
  ],
  timestamp: new Date(),
};

// Handle error responses
function handleError(error: ApplicationError) {
  console.error(`[${error.code}] ${error.message}`);

  if (error instanceof ValidationException) {
    // Handle validation errors
  } else if (error instanceof ResourceNotFoundException) {
    // Handle 404 errors
  }
}

Testing

Type Testing with TypeScript

import { User, Organization } from '@kitium-ai/types';

// This will fail at compile time if types don't match
const testType = (user: User, org: Organization) => {
  // TypeScript validates everything
};

Validation Testing

import { UserRegistrationSchema } from '@kitium-ai/types';
import { describe, it, expect } from 'vitest';

describe('UserRegistrationSchema', () => {
  it('should validate correct registration data', () => {
    const data = {
      email: 'test@example.com',
      firstName: 'John',
      lastName: 'Doe',
      password: 'SecurePass123!',
      confirmPassword: 'SecurePass123!',
      acceptTerms: true,
      acceptPrivacy: true,
    };

    expect(() => UserRegistrationSchema.parse(data)).not.toThrow();
  });

  it('should reject invalid emails', () => {
    const data = {
      email: 'invalid-email',
      // ... other fields
    };

    expect(() => UserRegistrationSchema.parse(data)).toThrow();
  });
});

Contributing

When adding new types:

1. Choose the right module - Place types in appropriate module (auth, user, organization, etc.)
2. Add validation schema - Add Zod schema to validators.ts
3. Add database entity - Add entity type to entities.ts if needed
4. Update exports - Ensure types are properly exported from index.ts
5. Add documentation - Include JSDoc comments with examples
6. Run type-check - Verify no TypeScript errors: npm run type-check
7. Build and test - Build package: npm run build

License

MIT - See LICENSE file

Support

For issues and feature requests, please visit: https://github.com/kitium-ai/types

Related Packages

• @kitium-ai/api - API server implementation
• @kitium-ai/web - Web application
• @kitium-ai/sdk - JavaScript SDK

Changelog

1.0.0 (Current)

• Initial release with comprehensive type system
• Zod-based validators for runtime validation
• Database entity types for persistence layer
• Unified single source of truth for all types
• Full TypeScript strict mode support

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[v2.0.1] - 2025-11-30

Added

updated kitiumai packages with patched version

[v2.0.0] - 2025-11-28

Added

• Documentation examples that show how to consume the stable @kitium-ai/types/v1 entrypoint, opt into the experimental surface, and validate payloads with branded primitives.
• API reference section outlining the major subpath exports and the dedicated logger package location.

[1.0.0] - 2025-11-21

Added

Core Type System

• Domain Models - Comprehensive business entity types across all domains:
  • User management (User, UserProfile, UserSettings, NotificationPreferences)
  • Organization & Team management (Organization, Team, OrganizationMember, TeamMember)
  • Product management (Product, Feature, Release, Issue, Milestone, Epic)
  • Billing & Subscriptions (Subscription, Invoice, PaymentMethod, Refund, DiscountCode)
  • Authentication (Session, APIKey, MFAConfig, AuthResponse)

Validation Layer (Zod-based)

• Validation Schemas (src/validators.ts) with 30+ Zod validators:

  • Authentication validators: LoginCredentialsSchema, PasswordResetConfirmSchema, MFAVerificationSchema, APIKeySchema
  • User validators: UserRegistrationSchema, UpdateUserProfileSchema, NotificationPreferencesSchema
  • Organization validators: CreateOrganizationSchema, UpdateOrganizationSchema, OrganizationSchema
  • Product validators: CreateProductSchema, CreateFeatureSchema
  • Billing validators: CreateSubscriptionSchema, UpdateSubscriptionSchema, PricingPlanSchema
  • API validators: ListQueryParamsSchema, FileUploadSchema, WebhookConfigSchema
  • Error validators: ValidationErrorSchema, ErrorResponseSchema

• Validator Helper Functions:

  • createValidator<T>() - Factory function for creating type-safe validators
  • Validators namespace - Pre-instantiated validators for common types
  • Support for .parse(), .safeParse(), and .validate() methods
  • Type inference support: z.infer<typeof SchemaName>

Database Entity Types

• Database Entity Definitions (src/entities.ts):

  • BaseEntity - Core entity interface with id, timestamps, and version
  • AuditableEntity - Extended entity with full audit trail (createdBy, updatedBy, deletedAt, deletedBy)
  • 25+ domain-specific database entities:
    • User entities: UserEntity, UserSettingsEntity, NotificationPreferencesEntity, AuthenticationHistoryEntity, SessionEntity, APIKeyEntity
    • Organization entities: OrganizationEntity, OrganizationSettingsEntity, OrganizationMemberEntity
    • Team entities: TeamEntity, TeamMemberEntity
    • Product entities: ProductEntity, FeatureEntity, ReleaseEntity
    • Billing entities: SubscriptionEntity, PaymentMethodEntity, InvoiceEntity, PaymentTransactionEntity
    • Infrastructure entities: WebhookConfigEntity, WebhookDeliveryEntity, AuditLogEntity, ActivityLogEntity, FileUploadEntity, ErrorLogEntity, EmailTemplateEntity, FeatureFlagEntity, RateLimitConfigEntity

• Generic Repository Pattern:

  • Repository<T> interface for type-safe data access
  • Standard CRUD operations: create, read, update, delete, exists, count
  • EntityMap type for managing entity relationships

API Request/Response Types

• Standard API communication patterns:
  • APIResponse<T> - Standardized response wrapper with success flag
  • PaginatedResponse<T> - Pagination support with metadata
  • ListQueryParams - Standardized query parameters for list endpoints
  • RequestContext - Request context information
  • FileUpload - File upload metadata
  • WebhookPayload & WebhookConfig - Webhook management
  • HealthCheck, RateLimitInfo, CacheControl, CORSConfig - Infrastructure types

Authentication & Authorization

• Comprehensive authentication types:
  • JWTPayload - JWT token structure
  • Session - User session information
  • LoginCredentials - Login request type
  • OAuthRequest & OAuthCallback - OAuth flow types
  • SAMLConfig & OIDCConfig - Enterprise SSO configuration
  • AuthResponse - Authentication response with tokens
  • RefreshTokenRequest, PasswordResetRequest, PasswordResetConfirm - Auth flow types
  • MFAConfig & MFAVerification - Multi-factor authentication

Role-Based Access Control

• UserRole enum with 7 hierarchical roles:

  • SUPER_ADMIN, ADMIN, OWNER, MANAGER, MEMBER, VIEWER, GUEST

• Permission enum with 32 granular permissions:

  • Organization: ORG_CREATE, ORG_READ, ORG_UPDATE, ORG_DELETE, ORG_INVITE, ORG_SETTINGS
  • User: USER_CREATE, USER_READ, USER_UPDATE, USER_DELETE, USER_ROLE_MANAGE
  • Product: PRODUCT_CREATE, PRODUCT_READ, PRODUCT_UPDATE, PRODUCT_DELETE, PRODUCT_PUBLISH
  • Team: TEAM_CREATE, TEAM_READ, TEAM_UPDATE, TEAM_DELETE, TEAM_INVITE
  • Billing: BILLING_READ, BILLING_UPDATE, BILLING_INVOICE
  • Settings: SETTINGS_READ, SETTINGS_UPDATE, SETTINGS_INTEGRATIONS
  • Analytics: ANALYTICS_READ, ANALYTICS_EXPORT
  • Audit: AUDIT_READ, AUDIT_EXPORT

Billing & Subscription Types

• Subscription Management:

  • PricingPlan - Plan definitions with features and pricing
  • Subscription - Subscription records with billing cycle
  • SubscriptionLineItem - Line items for subscriptions
  • PaymentMethod - Multiple payment method types (credit card, bank, PayPal, etc.)
  • Invoice - Invoice generation and tracking
  • PaymentTransaction - Transaction records
  • Refund - Refund management
  • DiscountCode - Coupon and discount codes
  • BillingAddress - Billing address management
  • UsageRecord - Usage-based billing

• Billing Enums:

  • SubscriptionStatus: ACTIVE, TRIAL, PAST_DUE, PAUSED, CANCELED, EXPIRED, PENDING
  • BillingCycle: MONTHLY, QUARTERLY, ANNUALLY, CUSTOM
  • PaymentMethodType: CREDIT_CARD, DEBIT_CARD, BANK_ACCOUNT, DIGITAL_WALLET, PAYPAL, WIRE_TRANSFER, CHECK
  • PaymentStatus: PENDING, PROCESSING, COMPLETED, FAILED, REFUNDED, DISPUTED
  • InvoiceStatus: DRAFT, SENT, VIEWED, PARTIAL_PAID, PAID, OVERDUE, CANCELED, REFUNDED
  • TaxType: VAT, GST, HST, PST, SALES_TAX, USE_TAX

Error Handling

• Error Types:

  • ApplicationError - Base error interface with severity levels
  • Specialized error types:
    • AuthenticationException - Auth-related errors
    • ValidationException - Validation errors with field details
    • ResourceNotFoundException - 404-style errors
    • ConflictException - Conflict/duplicate resource errors
    • QuotaExceededException - Quota limit errors
    • RateLimitException - Rate limiting errors
    • PaymentException - Payment processing errors

• Error Enums:

  • ErrorCode - 40+ error codes for different scenarios
  • ErrorSeverity - Severity levels (INFO, WARNING, ERROR, CRITICAL)

• Error Infrastructure:

  • ValidationError - Field-level validation error details
  • ValidationResult - Validation results with error/warning lists
  • ValidationRule - Field validation rule definitions
  • ValidationSchema - Schema for validation configuration
  • ErrorResponse - Standard error response format
  • ErrorLog - Error logging and tracking
  • ErrorEvent - Error event for tracking services

Utility Types

• Generic Utility Types:

  • Result<T, E> - Success/failure result type
  • Optional<T> - Nullable type alias
  • Readonly<T> / Mutable<T> - Immutability helpers
  • Dictionary<T> - Type-safe map/dictionary
  • Page<T> - Paginated list utility
  • TreeNode<T> - Tree structure type
  • GraphEdge<T> - Graph edge type

• Function Types:

  • AsyncFunction<T, R> - Async function signature
  • Fn<T, R> - Function signature
  • Callback<T> - Generic callback type
  • Predicate<T> - Boolean predicate type
  • Comparator<T> - Comparison function
  • Mapper<T, R> - Mapping function
  • Reducer<T, R> - Reducer function

• Data Structure Types:

  • Coordinate & Coordinate3D - 2D/3D coordinates
  • Size & Rectangle - Dimension types
  • Color - RGB color with alpha
  • Version - Semantic versioning
  • Duration & Interval - Time-related types
  • Money - Currency amount
  • Percentage - Percentage with decimals
  • LocalizedString - Multi-language support

• Pattern Types:

  • EventEmitter<T> - Generic event emitter
  • Observable<T> & Observer<T> - Observer pattern
  • ObserverSubscription - Subscription management (renamed from Subscription)
  • Deferred<T> - Promise-like deferred type
  • Strategy<T> - Strategy pattern interface
  • Cloneable<T> & Comparable<T> - Object capabilities
  • Serializable & Hashable - Object serialization
  • Auditable & Versioned - Audit and versioning support

• Base Entity Mixins:

  • Entity - Basic identity + timestamps
  • AuditableEntity - Full audit trail
  • Identity - Just id
  • Timestamped - Created/updated timestamps
  • Deletable - Soft delete support
  • Taggable - Tag support
  • Metadata - Arbitrary metadata

Product & Feature Management

• Product Lifecycle:

  • Product - Product definition with versioning
  • ProductVersion - Version tracking with release types
  • Feature - Feature definition with priority and tier
  • Epic - Epic for grouping features
  • Release - Release management
  • Issue - Bug/feature issue tracking
  • Milestone - Roadmap milestone

• Product Enums:

  • ProductStatus: DRAFT, IN_DEVELOPMENT, BETA, RELEASED, DEPRECATED, ARCHIVED, DISCONTINUED
  • FeatureStatus: PLANNED, IN_PROGRESS, TESTING, READY, RELEASED, DEPRECATED, ARCHIVED
  • FeatureTier: FREE, STARTER, PROFESSIONAL, ENTERPRISE, ALL
  • ReleaseType: MAJOR, MINOR, PATCH, BETA, ALPHA, RC

• Metrics & Analytics:

  • ProductUsageMetrics - Usage tracking
  • FeatureAdoption - Feature adoption rates
  • FeatureRequest - User feature requests

Dependencies

• Zod (^3.22.4) - Runtime schema validation and type inference

Package Configuration

• Comprehensive package.json with:
  • ESM and CommonJS export support
  • Per-module exports for tree-shaking
  • TypeScript declaration files
  • Pre-build type checking
  • Build and linting scripts

Documentation

• README.md - Comprehensive documentation including:
  • Architecture overview
  • Installation instructions
  • Complete usage examples
  • Security best practices
  • Advanced patterns
  • Type testing examples
  • Contributing guidelines

Changed

• Renamed Subscription to ObserverSubscription in utils.ts to avoid naming conflicts with billing Subscription type

Technical Details

TypeScript Configuration

• Target: ES2020
• Strict mode enabled
• Comprehensive tsconfig with:
  • Declaration maps
  • Source maps
  • Type checking strictness
  • Module resolution

Export Strategy

• Main entry point - All public types
• Namespaced exports:
  • ValidatorSchemas - All Zod schemas
  • Entities - All database entity types
  • Validators - Pre-instantiated validator objects
• Per-module exports - For better tree-shaking

Code Quality

• TypeScript strict mode compliance
• ESLint configuration
• Type safety throughout
• Immutable types using readonly modifiers
• Comprehensive JSDoc documentation

Verified

• ✅ All TypeScript compilation checks pass
• ✅ No unused variables or imports
• ✅ Type-safe exports with zero conflicts
• ✅ Package builds successfully
• ✅ No circular dependencies

[Unreleased]

Planned Features

• Additional validation schemas for emerging domains
• Database migration utilities
• ORM integration examples (TypeORM, Prisma)
• Testing utilities and test types
• GraphQL type definitions
• OpenAPI/Swagger integration
• Performance monitoring types
• Audit trail querying utilities
• Multi-tenancy utilities

Future Improvements

• Add optional peer dependency on @kitium-ai/schemas for schema composition
• Integration examples with popular SaaS frameworks
• Plugin system for custom validators
• Type generation utilities
• Breaking change detection tools