// [IN]: @orpc/contract, valibot / 依赖 oRPC 合约及验证器
// [OUT]: <entity>Contract object / 导出 <entity> API 合约定义
// [POS]: API layer - <Entity> contract definition / API 层 - <实体>合约定义
// Protocol: When updating me, sync this header + parent folder's .folder.md
// 协议：更新本文件时，同步更新此头注释及所属文件夹的 .folder.md

import { oc } from '@orpc/contract';
import * as v from 'valibot';

const <entity>Contract = oc
  .prefix('/<entities>')
  .tag('<entity>')
  .router({
    // GET /<entities> - List all
    all: oc
      .route({ method: 'GET', path: '/', summary: 'List all <entities>' })
      .output(v.array(v.object({
        id: v.string(),
        // ... other fields
      }))),

    // GET /<entities>/{id} - Get one
    one: oc
      .route({ method: 'GET', path: '/{id}', summary: 'Get <entity> by ID' })
      .input(v.object({ id: v.pipe(v.string(), v.uuid()) }))
      .output(v.object({
        id: v.string(),
        // ... all fields
      })),

    // POST /<entities> - Create
    create: oc
      .route({ method: 'POST', path: '/', summary: 'Create <entity>' })
      .input(Create<Entity>Schema)
      .output(v.object({})),

    // DELETE /<entities>/{id} - Delete
    delete: oc
      .route({ method: 'DELETE', path: '/{id}', summary: 'Delete <entity>' })
      .input(v.object({ id: v.pipe(v.string(), v.uuid()) }))
      .output(v.object({})),
  });

export default <entity>Contract;

import <entity>Contract from './<entity>';

export const appContract = oc
  .errors({ /* existing errors */ })
  .router({
    // ... existing routes
    <entity>: <entity>Contract,  // 👈 Add new contract
  });

// [IN]: @repo/db, ../orpc / 依赖数据库及 oRPC 过程
// [OUT]: <entity>Router object / 导出 <entity> 路由处理器
// [POS]: API layer - <Entity> CRUD handlers / API 层 - <实体> CRUD 处理器
// Protocol: When updating me, sync this header + parent folder's .folder.md
// 协议：更新本文件时，同步更新此头注释及所属文件夹的 .folder.md

import { desc, eq } from '@repo/db';
import { <entity> } from '@repo/db/schema';
import { protectedProcedure } from '../orpc';

const <entity>Router = {
  all: protectedProcedure.<entity>.all.handler(({ context }) => {
    return context.db.query.<entity>.findMany({
      orderBy: desc(<entity>.createdAt),
    });
  }),

  one: protectedProcedure.<entity>.one.handler(
    async ({ context, input, errors }) => {
      const [result] = await context.db
        .select()
        .from(<entity>)
        .where(eq(<entity>.id, input.id));

      if (!result) {
        throw errors.NOT_FOUND({ message: `<Entity> not found` });
      }
      return result;
    }
  ),

  create: protectedProcedure.<entity>.create.handler(
    async ({ context, input }) => {
      await context.db.insert(<entity>).values({
        ...input,
        createdBy: context.session.user.id,
      });
      return {};
    }
  ),

  delete: protectedProcedure.<entity>.delete.handler(
    async ({ context, input, errors }) => {
      const res = await context.db
        .delete(<entity>)
        .where(eq(<entity>.id, input.id));

      if (res.rowCount === 0) {
        throw errors.NOT_FOUND({ message: `<Entity> not found` });
      }
      return {};
    }
  ),
};

export default <entity>Router;

import <entity>Router from './<entity>';

export const appRouter = {
  // ... existing routers
  <entity>: <entity>Router,  // 👈 Add new router
};

pnpm db:push

// In apps/web
import { apiClient } from '@/clients/apiClient';

// List
const { data } = apiClient.<entity>.all.useQuery();

// Create
const mutation = apiClient.<entity>.create.useMutation();
await mutation.mutateAsync({ /* input */ });