AgentSkillsCN

shared-api-types

为使用共享的 @eridu/api-types 包中的密钥、Schema 与类型提供指导。在定义 API 合约、确保前后端之间的类型安全，或实现 Zod Schema 时，应优先选用此技能。

SKILL.md
--- frontmatter
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

Use CaseLocationReason
API Responsespackages/api-typesEnsures FE and BE agree on response shape
API Requestspackages/api-typesEnsures inputs are validated consistently
Shared Enumspackages/api-typesConsistency (e.g., ShowStatus, UserRole)
Internal Service Logicapps/erify_api/...Keep implementation details private
DB Modelsprisma/schema.prismaDB layer should be separate from API layer

Directory Structure

Organize by Domain Resource:

code
packages/api-types/src/
├── shows/
│   ├── index.ts      # Exports
│   ├── schemas.ts    # Zod definitions
│   └── types.ts      # Inferred TS types
├── users/
└── pagination/       # Shared utilities

Implementation Pattern

1. Define Zod Schemas (schemas.ts)

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

typescript
import { 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.

typescript
import 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.

typescript
// 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.

typescript
import { 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.