// packages/libs/contracts/src/specs/users/createUser.ts

import { z } from 'zod';
import { defineCommand } from '../../core/defineCommand';

/**
 * Creates a new user in the system.
 *
 * @domain users
 * @visibility public
 */
export const createUserCommand = defineCommand({
  name: 'createUser',
  description: 'Creates a new user account',
  input: z.object({
    email: z.string().email('Invalid email format'),
    name: z.string().min(1, 'Name is required'),
    role: z.enum(['admin', 'user', 'viewer']).default('user'),
  }),
  output: z.object({
    id: z.string().uuid(),
    email: z.string(),
    name: z.string(),
    role: z.enum(['admin', 'user', 'viewer']),
    createdAt: z.date(),
  }),
  errors: {
    EMAIL_EXISTS: 'A user with this email already exists',
    INVALID_ROLE: 'The specified role is not valid',
  },
});

// Export type helpers
export type CreateUserInput = z.infer<typeof createUserCommand.input>;
export type CreateUserOutput = z.infer<typeof createUserCommand.output>;

// packages/libs/contracts/src/specs/users/index.ts
export * from './createUser';
export * from './getUserById';
// ...

// packages/libs/contracts/src/specs/users/createUser.docblock.ts

import { registerDocBlock } from '@contractspec/lib.docs';

export const createUserDoc = registerDocBlock({
  id: 'spec-create-user',
  title: 'Create User Command',
  body: `
## Overview

Creates a new user account in the system.

## Input

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User's email address |
| name | string | Yes | User's display name |
| role | enum | No | User's role (default: user) |

## Output

Returns the created user object with generated ID and timestamp.

## Errors

- \`EMAIL_EXISTS\`: When email is already registered
- \`INVALID_ROLE\`: When role value is not recognized

## Example

\`\`\`typescript
const user = await execute(createUserCommand, {
  email: 'user@example.com',
  name: 'John Doe',
});
\`\`\`
  `,
  kind: 'reference',
  route: '/docs/specs/users/create-user',
  visibility: 'public',
});

export const <name>Command = defineCommand({
  name: '<name>',
  description: '<description>',
  input: z.object({
    // Define input fields
  }),
  output: z.object({
    // Define output fields
  }),
  errors: {
    // Define error codes
  },
});

export const <name>Query = defineQuery({
  name: '<name>',
  description: '<description>',
  input: z.object({
    // Define input fields
  }),
  output: z.object({
    // Define output fields
  }),
});

export const <name>Event = defineEvent({
  name: '<name>',
  description: '<description>',
  payload: z.object({
    // Define event payload
  }),
});