@voltom/contracts 1.0.0

package/README.md

@@ -0,0 +1,486 @@
+# @voltom/contracts
+
+Universal contract language for voltom products — primitive types, response shapes, error codes, and the `defineContract()` engine.
+
+## Getting Started
+
+### Prerequisites
+
+- **Node.js** 20+ ([download](https://nodejs.org))
+- **npm** 10+ (included with Node.js)
+- **Git** (for cloning and versioning)
+
+### Installation & Setup
+
+```bash
+# 1. Navigate to the project
+cd /Users/jzegarram/product-factory/@voltom-contracts
+
+# 2. Install dependencies
+npm install
+
+# 3. Verify everything works
+npm run test
+
+# 4. Start developing
+npm run dev
+```
+
+### Development Workflow
+
+#### Watch Mode (Recommended for development)
+
+```bash
+npm run dev
+```
+
+This runs TypeScript compiler in watch mode. Any changes to `src/` files trigger a rebuild automatically.
+
+#### Run Tests
+
+```bash
+# Run tests once
+npm run test
+
+# Run tests in watch mode (re-run on file changes)
+npm run test:watch
+```
+
+#### Type Checking
+
+```bash
+# Check TypeScript without emitting
+npm run type-check
+```
+
+Run this before committing to catch type errors early.
+
+#### Build for Production
+
+```bash
+# Create dist/ with CJS, ESM, and .d.ts
+npm run build
+```
+
+Output:
+- `dist/index.js` — CommonJS (Node.js)
+- `dist/index.mjs` — ES Modules (browsers, modern tools)
+- `dist/index.d.ts` — TypeScript declarations
+
+### Project Structure
+
+```
+src/
+├── primitives.ts         ← t.* type builders (add new types here)
+├── responses.ts          ← Response envelopes (SingleResponse, etc.)
+├── errors.ts             ← ErrorCode + HTTP status map
+├── contract.ts           ← defineContract() engine
+├── helpers.ts            ← Production patterns (auditFields, etc.)
+├── index.ts              ← Public API exports
+└── types/
+    ├── contract.types.ts
+    └── pagination.types.ts
+__tests__/
+└── primitives.test.ts    ← Test examples
+```
+
+### Common Development Tasks
+
+#### Add a New Primitive Type
+
+1. **Define in `src/primitives.ts`**:
+   ```typescript
+   export const t = {
+     // ... existing types ...
+     myNewType: (opts?: { /* options */ }) => {
+       // Use Zod under the hood
+       return z.string().custom(/* validation */)
+     }
+   }
+   ```
+
+2. **Add tests to `src/__tests__/primitives.test.ts`**:
+   ```typescript
+   describe('t.myNewType()', () => {
+     it('validates correct input', () => {
+       const schema = t.myNewType()
+       expect(schema.parse('valid-input')).toBe('valid-input')
+     })
+     
+     it('rejects invalid input', () => {
+       const schema = t.myNewType()
+       expect(() => schema.parse('invalid')).toThrow()
+     })
+   })
+   ```
+
+3. **Verify tests pass**:
+   ```bash
+   npm run test
+   ```
+
+4. **Update `src/index.ts` if needed** (usually auto-exported from primitives)
+
+5. **Create a changeset**:
+   ```bash
+   npx changeset
+   # Select: patch (bug fix), minor (new type), or major (breaking change)
+   ```
+
+#### Add a New Error Code
+
+1. **Update `src/errors.ts`**:
+   ```typescript
+   export type ErrorCode =
+     | 'EXISTING_ERROR'
+     | 'MY_NEW_ERROR'  // ← Add here
+   
+   export const ERROR_STATUS_MAP: Record<ErrorCode, number> = {
+     EXISTING_ERROR: 400,
+     MY_NEW_ERROR: 409,  // ← Add HTTP status
+   }
+   
+   export const ERROR_MESSAGES: Record<ErrorCode, string> = {
+     EXISTING_ERROR: 'Error message',
+     MY_NEW_ERROR: 'My error message', // ← Add default message
+   }
+   ```
+
+2. **Test it**:
+   ```bash
+   npm run type-check
+   npm run test
+   ```
+
+3. **Create a changeset** (⚠️ This is a breaking change):
+   ```bash
+   npx changeset
+   # Select: major (breaking change — all products must update)
+   ```
+
+#### Update Response Shapes
+
+**⚠️ WARNING:** Response shapes are locked. Changes require major version bump and coordination with all products.
+
+Do NOT change existing fields. If you need a new response type:
+
+1. **Create new envelope in `src/responses.ts`**
+2. **Export from `src/index.ts`**
+3. **Document in README**
+4. **Changeset as major version**
+5. **Notify all products**
+
+---
+
+## Before You Commit
+
+Run this checklist:
+
+```bash
+# 1. Format & lint (if you add linting rules)
+npm run lint
+
+# 2. Type check
+npm run type-check
+
+# 3. Run all tests
+npm run test
+
+# 4. Build
+npm run build
+
+# 5. Verify bundle size
+ls -lh dist/
+```
+
+If all pass, you're ready to commit.
+
+---
+
+## Publishing to npm
+
+### Step-by-Step
+
+```bash
+# 1. Make your changes
+# (edit src/primitives.ts, src/errors.ts, etc.)
+
+# 2. Write tests for new types
+# (edit src/__tests__/primitives.test.ts)
+
+# 3. Verify everything locally
+npm run test
+npm run type-check
+npm run build
+
+# 4. Create a changeset
+npx changeset
+# Follow the prompts:
+# - Select type: patch | minor | major
+# - Write summary of changes
+# - Describe why in more detail
+
+# 5. Commit your changes
+git add .
+git commit -m "feat: add new type or error code"
+
+# 6. Push to GitHub
+git push origin your-branch
+
+# 7. Create PR, get reviewed, merge to main
+# (CI automatically publishes on merge)
+```
+
+### CI/CD (Automatic on Merge)
+
+When you merge to `main`, GitHub Actions automatically:
+
+1. ✅ Runs all tests
+2. ✅ Builds the package
+3. ✅ Bumps version (`package.json`, `CHANGELOG.md`)
+4. ✅ Publishes to GitHub Packages
+
+You don't need to do anything else.
+
+---
+
+## Troubleshooting
+
+### Tests Failing
+
+```bash
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+npm run test
+```
+
+### Type Errors
+
+```bash
+# Run type checker for detailed errors
+npm run type-check
+
+# Fix TypeScript errors in the code
+# (usually in src/ files)
+
+# Re-run type-check
+npm run type-check
+```
+
+### Build Failing
+
+```bash
+# Check tsup config
+cat tsup.config.ts
+
+# Try rebuilding with clean slate
+npm run build
+
+# Check dist/ was created
+ls dist/
+```
+
+### Changeset Issues
+
+```bash
+# If you haven't created a changeset
+npx changeset
+
+# If changeset is malformed, fix it
+# (changesets are in .changeset/*.md files)
+
+# Verify changeset is valid
+cat .changeset/*.md
+```
+
+---
+
+## File Reference
+
+| File | Purpose | When to edit |
+|------|---------|--------------|
+| `src/primitives.ts` | Type builders | Adding new `t.*` types |
+| `src/responses.ts` | Response envelopes | (Locked — don't edit) |
+| `src/errors.ts` | Error codes | Adding new ErrorCode |
+| `src/helpers.ts` | Production patterns | Adding new helpers |
+| `src/index.ts` | Public API | Exporting new code |
+| `src/__tests__/primitives.test.ts` | Tests | Every new type needs tests |
+| `package.json` | Dependencies, scripts | Adding dev dependencies |
+| `tsconfig.json` | TypeScript config | Changing TS behavior |
+
+---
+
+## Next Steps
+
+1. **Read [CLAUDE.md](CLAUDE.md)** for detailed rules and patterns
+2. **Read [PRODUCTION-GUIDE.md](PRODUCTION-GUIDE.md)** for production best practices
+3. **Review [QUICK-REFERENCE.md](QUICK-REFERENCE.md)** for quick lookups
+4. **Start developing** — pick a task and follow the workflow above
+
+---
+
+## Quick Start
+
+```typescript
+import { defineContract, t } from '@voltom/contracts'
+import type { SingleResponse, PaginatedResponse, ApiError } from '@voltom/contracts'
+
+// Define a contract
+export const usersContract = defineContract({
+  resource: 'users',
+  basePath: '/api/v1/users',
+  entity: {
+    id: t.uuid(),
+    email: t.email(),
+    name: t.string({ min: 1, max: 255 }),
+    createdAt: t.datetime(),
+  },
+  endpoints: {
+    list: { method: 'GET', path: '/', response: 'paginated' },
+    show: { method: 'GET', path: '/:id', response: 'single' },
+    create: { method: 'POST', path: '/', body: 'CreateUser' },
+    delete: { method: 'DELETE', path: '/:id', response: 'deleted' },
+  },
+  bodies: {
+    CreateUser: {
+      email: t.email(),
+      name: t.string({ min: 1, max: 255 }),
+    },
+  },
+})
+```
+
+## What's Included
+
+### 1. Primitive Type Builders (`t.*`)
+
+```typescript
+t.uuid()                    // UUID string
+t.string({ min, max })      // string with constraints
+t.email()                   // email format
+t.number()                  // number
+t.int()                     // integer
+t.boolean()                 // boolean
+t.datetime()                // ISO 8601 datetime
+t.date()                    // ISO 8601 date
+t.enum(['a', 'b'])         // enum
+t.optional(schema)          // optional<T>
+t.nullable(schema)          // nullable<T>
+t.array(schema)             // T[]
+```
+
+### 2. Response Shapes (Canonical)
+
+```typescript
+SingleResponse<T>      // { data: T, timestamp: string }
+PaginatedResponse<T>   // { data: T[], meta: PaginationMeta, timestamp: string }
+DeletedResponse        // { deleted: true, id: string, timestamp: string }
+ApiError               // { error: { code: ErrorCode, message: string }, timestamp: string }
+```
+
+### 3. Error Codes
+
+```typescript
+type ErrorCode =
+  | 'VALIDATION_ERROR'  // 400 — invalid input
+  | 'UNAUTHORIZED'      // 401 — no session
+  | 'FORBIDDEN'         // 403 — not allowed
+  | 'NOT_FOUND'         // 404 — missing resource
+  | 'CONFLICT'          // 409 — duplicate or bad state
+  | 'UNPROCESSABLE'     // 422 — business logic rejected
+  | 'INTERNAL_ERROR'    // 500 — server error
+
+// Map to HTTP status
+import { ERROR_STATUS_MAP } from '@voltom/contracts'
+const status = ERROR_STATUS_MAP['VALIDATION_ERROR'] // 400
+```
+
+### 4. `defineContract()` Engine
+
+Type-safe contract definition for every resource in your product:
+
+```typescript
+interface ContractConfig {
+  resource: string                                    // e.g., 'users'
+  basePath: string                                    // e.g., '/api/v1/users'
+  entity: Record<string, z.ZodTypeAny>               // the shape
+  endpoints?: Record<string, EndpointDef>            // GET, POST, etc.
+  bodies?: Record<string, Record<string, z.ZodTypeAny>>  // request bodies
+  filters?: Record<string, z.ZodTypeAny>             // query filters
+  actions?: Record<string, ActionDef>                // custom actions
+  permissions?: Record<string, string>               // access control hints
+}
+```
+
+## Installation
+
+```bash
+npm install @voltom/contracts zod
+```
+
+## Usage in Different Contexts
+
+### In Product Contracts (`{product}-contracts`)
+
+```typescript
+import { defineContract, t } from '@voltom/contracts'
+
+export const teamsContract = defineContract({
+  // ... your contract definition
+})
+```
+
+### In Backend (NestJS)
+
+```typescript
+import type { SingleResponse, ApiError, ErrorCode } from '@voltom/contracts'
+import { ERROR_STATUS_MAP } from '@voltom/contracts'
+
+// Use in controllers, services, interceptors
+```
+
+### In Frontend (React/Next.js)
+
+```typescript
+import type { PaginatedResponse, ApiError } from '@voltom/contracts'
+
+// Use in API calls, type inference
+```
+
+## Versioning
+
+- **patch**: bug fixes (1.0.x)
+- **minor**: new types, additive changes (1.x.0)
+- **major**: breaking changes — requires coordination (x.0.0)
+
+## Development
+
+```bash
+npm install              # Install dependencies
+npm run dev              # Watch mode
+npm run build            # Build (CJS + ESM + .d.ts)
+npm run type-check       # TypeScript check
+npm run test             # Run tests
+npm run test:watch       # Watch mode for tests
+```
+
+## Publishing
+
+1. Make changes
+2. `npx changeset` — create changeset
+3. PR → review → merge to main
+4. CI publishes automatically to GitHub Packages
+5. Version bumped, CHANGELOG updated
+
+## See Also
+
+- [Platform Overview](../docs/00-PLATFORM-OVERVIEW.md)
+- [Project Identity](../docs/PROJECT-IDENTITY.md)
+- [Full Contract Documentation](../docs/01-CONTRACTS-BASE.md)
+
+---
+
+**Organization:** voltom  
+**Status:** Active  
+**License:** MIT