npm package: @kitiumai/types
Description: Enterprise-ready TypeScript types and interfaces for Kitium AI Product SaaS
Author: Kitium AI
Latest version: 3.0.0

# @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)

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

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

### Runtime validation (prebuilt)

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

const result = VALIDATORS.loginCredentials.parse({ email: 'a@b.com', password: 'secret' });
if (!result.success) throw result.error;
```

### Use Zod schemas directly

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

const input = UserRegistrationSchema.parse({
  email: 'a@b.com',
  firstName: 'A',
  lastName: 'B',
  password: 'secret',
  confirmPassword: 'secret',
  acceptTerms: true,
  acceptPrivacy: true,
});
```

### Branded primitives

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

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