@kitiumai/types

Shared TypeScript domain types and runtime validators for the KitiumAI ecosystem.

What is this package?

@kitiumai/types is the shared contract layer for KitiumAI apps and services:

• Domain models for product areas (auth, user, org, billing, etc.)
• API contract types (requests/responses, errors, pagination, webhooks)
• Runtime validation via Zod schemas (@kitiumai/types/validators) and prebuilt validators (VALIDATORS)
• Granular subpath exports for faster builds and better tree-shaking

Why do we need this package?

• Prevents “type drift” across services by keeping DTOs and entities in one place
• Improves safety by pairing TypeScript types with runtime validation (Zod)
• Makes refactors cheaper by centralizing contracts and versioning (/v1, /experimental)

Competitor comparison

| Approach | Strengths | Gaps this package covers | |---|---|---| | Ad-hoc shared types/ folder per repo | Simple to start | No versioning, easy to drift, often no runtime validation | | OpenAPI/GraphQL codegen types | Great for API edges | Usually doesn’t cover internal domain models; runtime parsing is still needed | | ORM-generated types (e.g. Prisma) | Accurate DB shapes | Not a full API/contract layer; doesn’t model workflows and external inputs | | Schema-only packages (Zod/TypeBox only) | Runtime-first | Harder to maintain a consistent, discoverable “domain surface” across many modules |

USP

• Contract-first, modular public surface (subpath exports)
• Runtime validation included, not bolted on (VALIDATORS, Zod schemas)
• Versioned and experimental entrypoints for controlled evolution
• ESM-first with CJS compatibility and sideEffects: false

Public API (entrypoints)

The package publishes the following entrypoints (from package.json#exports):

| Import path | What it contains | |---|---| | @kitiumai/types | Convenience re-exports for most domains + VALIDATORS | | @kitiumai/types/auth | Authentication and identity types | | @kitiumai/types/auth/access | Access control types | | @kitiumai/types/auth/rbac | RBAC types | | @kitiumai/types/auth/sso | SSO types | | @kitiumai/types/auth/twofa | 2FA types | | @kitiumai/types/user | User domain types | | @kitiumai/types/organization | Organization domain types | | @kitiumai/types/product | Product and feature types | | @kitiumai/types/billing | Billing and subscription types | | @kitiumai/types/billing/pricing | Pricing types | | @kitiumai/types/api | API request/response contract types | | @kitiumai/types/api/contracts | Shared API contract helpers/types | | @kitiumai/types/api/errors | API error types and status codes | | @kitiumai/types/errors | Error models and utilities | | @kitiumai/types/services | Service-facing contract types | | @kitiumai/types/services/email | Email service types | | @kitiumai/types/services/file | File service types | | @kitiumai/types/services/search | Search service types | | @kitiumai/types/services/database | Database service types | | @kitiumai/types/utils | Shared utility types | | @kitiumai/types/primitives | Branded primitives + small runtime helpers | | @kitiumai/types/entities | Entity shapes (type namespace) | | @kitiumai/types/validators | Zod schemas + validator helpers + registries | | @kitiumai/types/security | Security and compliance types | | @kitiumai/types/frameworks/react | React integration types | | @kitiumai/types/realtime | Real-time (WebSocket/SSE) types | | @kitiumai/types/graphql | GraphQL integration types | | @kitiumai/types/testing | Testing utilities/types | | @kitiumai/types/openapi | OpenAPI integration types | | @kitiumai/types/enterprise | Enterprise and compliance types | | @kitiumai/types/ecosystem | Third-party ecosystem types | | @kitiumai/types/v1 | Versioned alias of the primary surface | | @kitiumai/types/experimental | Opt-in preview exports |

Examples

Use domain types (types-only)

import type { User } from '@kitiumai/types/user';
import type { Organization } from '@kitiumai/types/organization';

export type Session = { user: User; organization: Organization };

Runtime validation (prebuilt)

import { VALIDATORS } from '@kitiumai/types';

const result = VALIDATORS.loginCredentials.parse({ email: '[email protected]', password: 'secret' });
if (!result.success) throw result.error;

Use Zod schemas directly

import { UserRegistrationSchema } from '@kitiumai/types/validators';

const input = UserRegistrationSchema.parse({
  email: '[email protected]',
  firstName: 'A',
  lastName: 'B',
  password: 'secret',
  confirmPassword: 'secret',
  acceptTerms: true,
  acceptPrivacy: true,
});

Branded primitives

import { brand } from '@kitiumai/types/primitives';

const userId = brand('usr_123', 'id:user');