---

name: shared-api-types description: Provides guidelines for using keys, schemas, and types from the shared @eridu/api-types package. This skill should be used when defining API contracts, ensuring type safety between frontend and backend, or implementing Zod schemas.

Shared API Types & Schemas

This skill outlines the standards for using the @eridu/api-types package. This package is the Single Source of Truth for API contracts between Backend, Frontend, and external services.

When to Use

Directory Structure

Organize by Domain Resource:

Copypackages/api-types/src/
├── shows/
├── users/
│   ├── index.ts      # Exports
│   └── schemas.ts    # Zod definitions and inferred TS types
└── pagination/       # Shared utilities

[!NOTE] While it's possible to split schemas.ts and types.ts, current practice in this monorepo is to consolidate them into schemas.ts for simplicity and easier maintenance.

Implementation Pattern

1. Define Zod Schemas (schemas.ts)

Define schemas that represent the wire format (usually snake_case).

Copyimport { z } from 'zod';

export const userApiResponseSchema = z.object({
  id: z.string(),
  email: z.email(),
  created_at: z.string(),
});

export const createUserDtoSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
});

2. Infer TypeScript Types (types.ts)

ALWAYS infer types from the Zod schemas. Never manually duplicate interfaces.

Copyimport type { z } from 'zod';
import { userApiResponseSchema, createUserDtoSchema } from './schemas.js';

export type UserApiResponse = z.infer<typeof userApiResponseSchema>;
export type CreateUserDto = z.infer<typeof createUserDtoSchema>;

3. Usage in Backend (erify_api)

Import schemas for validation decortors and types for strongly-typed services.

Copy// Controller
import { createUserDtoSchema, CreateUserDto } from '@eridu/api-types/users';

@Post()
// Validate input body with shared schema
@UsePipes(new ZodValidationPipe(createUserDtoSchema))
create(@Body() body: CreateUserDto) { ... }

4. Usage in Frontend (erify_creators)

Import types for API clients and schemas for form validation.

Copyimport { type CreateUserDto, createUserDtoSchema } from '@eridu/api-types/users';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';

// Use shared schema for form validation
const form = useForm<CreateUserDto>({
  resolver: zodResolver(createUserDtoSchema)
});

Checklist

• New API contract? Add to @eridu/api-types first.
• Group by domain folder (src/my-domain/).
• Export schemas (runtime) and types (static).
• Use snake_case for wire formats.
• Infer types using z.infer.