autoworkflow 3.1.4 → 3.5.0

package/.claude/skills/trpc.md

@@ -0,0 +1,426 @@
+# tRPC Skill
+
+## Project Setup
+\`\`\`typescript
+// server/trpc.ts
+import { initTRPC, TRPCError } from '@trpc/server';
+import { type Context } from './context';
+import superjson from 'superjson';
+import { ZodError } from 'zod';
+
+const t = initTRPC.context<Context>().create({
+  transformer: superjson,
+  errorFormatter({ shape, error }) {
+    return {
+      ...shape,
+      data: {
+        ...shape.data,
+        zodError:
+          error.cause instanceof ZodError ? error.cause.flatten() : null,
+      },
+    };
+  },
+});
+
+export const router = t.router;
+export const publicProcedure = t.procedure;
+export const middleware = t.middleware;
+export const mergeRouters = t.mergeRouters;
+\`\`\`
+
+## Context
+\`\`\`typescript
+// server/context.ts
+import { type inferAsyncReturnType } from '@trpc/server';
+import { type CreateNextContextOptions } from '@trpc/server/adapters/next';
+import { getServerSession } from 'next-auth';
+import { prisma } from './db';
+import { authOptions } from './auth';
+
+export async function createContext(opts: CreateNextContextOptions) {
+  const session = await getServerSession(opts.req, opts.res, authOptions);
+
+  return {
+    prisma,
+    session,
+    user: session?.user,
+  };
+}
+
+export type Context = inferAsyncReturnType<typeof createContext>;
+\`\`\`
+
+## Middleware
+\`\`\`typescript
+// server/middleware.ts
+import { TRPCError } from '@trpc/server';
+import { middleware, publicProcedure } from './trpc';
+
+// Logging middleware
+const loggerMiddleware = middleware(async ({ path, type, next }) => {
+  const start = Date.now();
+  const result = await next();
+  const duration = Date.now() - start;
+  console.log(\`[\${type}] \${path} - \${duration}ms\`);
+  return result;
+});
+
+// Auth middleware
+const isAuthed = middleware(async ({ ctx, next }) => {
+  if (!ctx.session || !ctx.user) {
+    throw new TRPCError({
+      code: 'UNAUTHORIZED',
+      message: 'Not authenticated',
+    });
+  }
+  return next({
+    ctx: {
+      ...ctx,
+      user: ctx.user, // user is now non-nullable
+    },
+  });
+});
+
+// Role middleware
+const hasRole = (role: string) =>
+  middleware(async ({ ctx, next }) => {
+    if (ctx.user?.role !== role) {
+      throw new TRPCError({
+        code: 'FORBIDDEN',
+        message: 'Insufficient permissions',
+      });
+    }
+    return next();
+  });
+
+// Procedures with middleware
+export const protectedProcedure = publicProcedure
+  .use(loggerMiddleware)
+  .use(isAuthed);
+
+export const adminProcedure = protectedProcedure.use(hasRole('admin'));
+\`\`\`
+
+## Router Definition
+\`\`\`typescript
+// server/routers/user.ts
+import { z } from 'zod';
+import { router, publicProcedure, protectedProcedure } from '../trpc';
+import { TRPCError } from '@trpc/server';
+
+export const userRouter = router({
+  // Public query
+  getById: publicProcedure
+    .input(z.object({ id: z.string().uuid() }))
+    .query(async ({ ctx, input }) => {
+      const user = await ctx.prisma.user.findUnique({
+        where: { id: input.id },
+        select: {
+          id: true,
+          name: true,
+          image: true,
+          // Don't expose email publicly
+        },
+      });
+
+      if (!user) {
+        throw new TRPCError({
+          code: 'NOT_FOUND',
+          message: 'User not found',
+        });
+      }
+
+      return user;
+    }),
+
+  // Protected query
+  me: protectedProcedure.query(async ({ ctx }) => {
+    return ctx.prisma.user.findUnique({
+      where: { id: ctx.user.id },
+      include: { profile: true },
+    });
+  }),
+
+  // Mutation with input validation
+  updateProfile: protectedProcedure
+    .input(
+      z.object({
+        name: z.string().min(2).max(100).optional(),
+        bio: z.string().max(500).optional(),
+        website: z.string().url().optional().or(z.literal('')),
+      })
+    )
+    .mutation(async ({ ctx, input }) => {
+      return ctx.prisma.user.update({
+        where: { id: ctx.user.id },
+        data: input,
+      });
+    }),
+
+  // List with pagination
+  list: publicProcedure
+    .input(
+      z.object({
+        limit: z.number().min(1).max(100).default(10),
+        cursor: z.string().uuid().optional(),
+      })
+    )
+    .query(async ({ ctx, input }) => {
+      const { limit, cursor } = input;
+
+      const users = await ctx.prisma.user.findMany({
+        take: limit + 1,
+        ...(cursor && {
+          cursor: { id: cursor },
+          skip: 1,
+        }),
+        orderBy: { createdAt: 'desc' },
+      });
+
+      let nextCursor: string | undefined;
+      if (users.length > limit) {
+        const nextItem = users.pop();
+        nextCursor = nextItem?.id;
+      }
+
+      return { users, nextCursor };
+    }),
+});
+
+// server/routers/post.ts
+export const postRouter = router({
+  create: protectedProcedure
+    .input(
+      z.object({
+        title: z.string().min(1).max(200),
+        content: z.string().min(1),
+        published: z.boolean().default(false),
+      })
+    )
+    .mutation(async ({ ctx, input }) => {
+      return ctx.prisma.post.create({
+        data: {
+          ...input,
+          authorId: ctx.user.id,
+        },
+      });
+    }),
+
+  delete: protectedProcedure
+    .input(z.object({ id: z.string().uuid() }))
+    .mutation(async ({ ctx, input }) => {
+      const post = await ctx.prisma.post.findUnique({
+        where: { id: input.id },
+      });
+
+      if (!post) {
+        throw new TRPCError({ code: 'NOT_FOUND' });
+      }
+
+      if (post.authorId !== ctx.user.id) {
+        throw new TRPCError({ code: 'FORBIDDEN' });
+      }
+
+      return ctx.prisma.post.delete({ where: { id: input.id } });
+    }),
+});
+\`\`\`
+
+## App Router
+\`\`\`typescript
+// server/routers/_app.ts
+import { router } from '../trpc';
+import { userRouter } from './user';
+import { postRouter } from './post';
+
+export const appRouter = router({
+  user: userRouter,
+  post: postRouter,
+});
+
+export type AppRouter = typeof appRouter;
+\`\`\`
+
+## Next.js API Handler
+\`\`\`typescript
+// app/api/trpc/[trpc]/route.ts (App Router)
+import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
+import { appRouter } from '@/server/routers/_app';
+import { createContext } from '@/server/context';
+
+const handler = (req: Request) =>
+  fetchRequestHandler({
+    endpoint: '/api/trpc',
+    req,
+    router: appRouter,
+    createContext: () => createContext({ req }),
+  });
+
+export { handler as GET, handler as POST };
+\`\`\`
+
+## Client Setup
+\`\`\`typescript
+// utils/trpc.ts
+import { createTRPCReact } from '@trpc/react-query';
+import { type AppRouter } from '@/server/routers/_app';
+
+export const trpc = createTRPCReact<AppRouter>();
+
+// app/providers.tsx
+'use client';
+
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { httpBatchLink } from '@trpc/client';
+import { useState } from 'react';
+import { trpc } from '@/utils/trpc';
+import superjson from 'superjson';
+
+export function TRPCProvider({ children }: { children: React.ReactNode }) {
+  const [queryClient] = useState(() => new QueryClient());
+  const [trpcClient] = useState(() =>
+    trpc.createClient({
+      links: [
+        httpBatchLink({
+          url: '/api/trpc',
+          transformer: superjson,
+        }),
+      ],
+    })
+  );
+
+  return (
+    <trpc.Provider client={trpcClient} queryClient={queryClient}>
+      <QueryClientProvider client={queryClient}>
+        {children}
+      </QueryClientProvider>
+    </trpc.Provider>
+  );
+}
+\`\`\`
+
+## Client Usage
+\`\`\`typescript
+// components/UserProfile.tsx
+'use client';
+
+import { trpc } from '@/utils/trpc';
+
+export function UserProfile({ userId }: { userId: string }) {
+  // Query
+  const { data: user, isLoading, error } = trpc.user.getById.useQuery(
+    { id: userId },
+    { enabled: !!userId }
+  );
+
+  // Mutation
+  const utils = trpc.useUtils();
+  const updateProfile = trpc.user.updateProfile.useMutation({
+    onSuccess: () => {
+      // Invalidate and refetch
+      utils.user.me.invalidate();
+    },
+    onError: (error) => {
+      console.error('Update failed:', error.message);
+    },
+  });
+
+  const handleUpdate = (data: { name: string }) => {
+    updateProfile.mutate(data);
+  };
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return <div>{user?.name}</div>;
+}
+
+// Infinite query
+export function PostList() {
+  const {
+    data,
+    fetchNextPage,
+    hasNextPage,
+    isFetchingNextPage,
+  } = trpc.post.list.useInfiniteQuery(
+    { limit: 10 },
+    {
+      getNextPageParam: (lastPage) => lastPage.nextCursor,
+    }
+  );
+
+  return (
+    <div>
+      {data?.pages.map((page) =>
+        page.posts.map((post) => <PostCard key={post.id} post={post} />)
+      )}
+      {hasNextPage && (
+        <button
+          onClick={() => fetchNextPage()}
+          disabled={isFetchingNextPage}
+        >
+          {isFetchingNextPage ? 'Loading...' : 'Load More'}
+        </button>
+      )}
+    </div>
+  );
+}
+\`\`\`
+
+## Server-Side Calls (RSC)
+\`\`\`typescript
+// Server component usage
+import { createCaller } from '@/server/routers/_app';
+import { createContext } from '@/server/context';
+
+export default async function Page() {
+  const ctx = await createContext();
+  const caller = createCaller(ctx);
+
+  const user = await caller.user.me();
+
+  return <div>{user.name}</div>;
+}
+\`\`\`
+
+## Error Handling
+\`\`\`typescript
+// Custom error with data
+throw new TRPCError({
+  code: 'BAD_REQUEST',
+  message: 'Validation failed',
+  cause: new Error('Original error'),
+});
+
+// Error codes
+type TRPCErrorCode =
+  | 'PARSE_ERROR'
+  | 'BAD_REQUEST'
+  | 'UNAUTHORIZED'
+  | 'FORBIDDEN'
+  | 'NOT_FOUND'
+  | 'METHOD_NOT_SUPPORTED'
+  | 'TIMEOUT'
+  | 'CONFLICT'
+  | 'PRECONDITION_FAILED'
+  | 'PAYLOAD_TOO_LARGE'
+  | 'TOO_MANY_REQUESTS'
+  | 'CLIENT_CLOSED_REQUEST'
+  | 'INTERNAL_SERVER_ERROR';
+\`\`\`
+
+## ❌ DON'T
+- Skip input validation with Zod
+- Expose sensitive data in public procedures
+- Forget to handle errors in mutations
+- Use any types for inputs/outputs
+- Skip middleware for auth checks
+
+## ✅ DO
+- Use superjson for Date/Map/Set support
+- Create reusable middleware
+- Use proper error codes
+- Invalidate queries after mutations
+- Use infinite queries for pagination
+- Type your context properly
+- Use procedure builders for common patterns