@girardmedia/bootspring 1.2.0 → 2.0.3

package/skills/patterns/api/errors.md

@@ -1,296 +0,0 @@
-# API Error Handling Patterns
-
-Patterns for consistent API error responses.
-
-## Error Classes
-
-```typescript
-// lib/errors.ts
-export class AppError extends Error {
-  constructor(
-    message: string,
-    public statusCode: number = 500,
-    public code: string = 'INTERNAL_ERROR'
-  ) {
-    super(message)
-    this.name = 'AppError'
-  }
-}
-
-export class NotFoundError extends AppError {
-  constructor(resource: string) {
-    super(`${resource} not found`, 404, 'NOT_FOUND')
-    this.name = 'NotFoundError'
-  }
-}
-
-export class UnauthorizedError extends AppError {
-  constructor(message = 'Unauthorized') {
-    super(message, 401, 'UNAUTHORIZED')
-    this.name = 'UnauthorizedError'
-  }
-}
-
-export class ForbiddenError extends AppError {
-  constructor(message = 'Forbidden') {
-    super(message, 403, 'FORBIDDEN')
-    this.name = 'ForbiddenError'
-  }
-}
-
-export class ValidationError extends AppError {
-  constructor(
-    message: string,
-    public errors: Record<string, string[]> = {}
-  ) {
-    super(message, 400, 'VALIDATION_ERROR')
-    this.name = 'ValidationError'
-  }
-}
-
-export class ConflictError extends AppError {
-  constructor(message: string) {
-    super(message, 409, 'CONFLICT')
-    this.name = 'ConflictError'
-  }
-}
-
-export class RateLimitError extends AppError {
-  constructor(retryAfter: number) {
-    super('Too many requests', 429, 'RATE_LIMIT_EXCEEDED')
-    this.name = 'RateLimitError'
-  }
-}
-```
-
-## Error Response Format
-
-```typescript
-// lib/api-response.ts
-interface ErrorResponse {
-  error: {
-    message: string
-    code: string
-    details?: Record<string, unknown>
-  }
-}
-
-interface SuccessResponse<T> {
-  data: T
-}
-
-export function errorResponse(
-  error: AppError | Error
-): { body: ErrorResponse; status: number } {
-  if (error instanceof AppError) {
-    return {
-      body: {
-        error: {
-          message: error.message,
-          code: error.code,
-          details: error instanceof ValidationError ? { errors: error.errors } : undefined
-        }
-      },
-      status: error.statusCode
-    }
-  }
-
-  // Unknown error - don't expose details
-  console.error('Unhandled error:', error)
-  return {
-    body: {
-      error: {
-        message: 'An unexpected error occurred',
-        code: 'INTERNAL_ERROR'
-      }
-    },
-    status: 500
-  }
-}
-
-export function successResponse<T>(data: T): SuccessResponse<T> {
-  return { data }
-}
-```
-
-## Error Handler Wrapper
-
-```typescript
-// lib/api-handler.ts
-import { NextRequest, NextResponse } from 'next/server'
-import { AppError, errorResponse } from '@/lib/errors'
-import { ZodError } from 'zod'
-
-type Handler = (request: NextRequest) => Promise<Response>
-
-export function withErrorHandler(handler: Handler): Handler {
-  return async (request: NextRequest) => {
-    try {
-      return await handler(request)
-    } catch (error) {
-      // Handle Zod validation errors
-      if (error instanceof ZodError) {
-        const validationError = new ValidationError(
-          'Validation failed',
-          formatZodErrors(error)
-        )
-        const { body, status } = errorResponse(validationError)
-        return NextResponse.json(body, { status })
-      }
-
-      // Handle app errors
-      if (error instanceof AppError) {
-        const { body, status } = errorResponse(error)
-        return NextResponse.json(body, { status })
-      }
-
-      // Handle unknown errors
-      console.error('Unhandled API error:', error)
-      return NextResponse.json(
-        { error: { message: 'Internal server error', code: 'INTERNAL_ERROR' } },
-        { status: 500 }
-      )
-    }
-  }
-}
-
-function formatZodErrors(error: ZodError): Record<string, string[]> {
-  const errors: Record<string, string[]> = {}
-
-  for (const issue of error.issues) {
-    const path = issue.path.join('.')
-    if (!errors[path]) {
-      errors[path] = []
-    }
-    errors[path].push(issue.message)
-  }
-
-  return errors
-}
-```
-
-## Route Handler with Error Handling
-
-```typescript
-// app/api/users/[id]/route.ts
-import { NextRequest, NextResponse } from 'next/server'
-import { withErrorHandler } from '@/lib/api-handler'
-import { NotFoundError, ForbiddenError } from '@/lib/errors'
-import { auth } from '@/auth'
-
-export const GET = withErrorHandler(async (
-  request: NextRequest,
-  { params }: { params: { id: string } }
-) => {
-  const session = await auth()
-
-  if (!session) {
-    throw new UnauthorizedError()
-  }
-
-  const user = await prisma.user.findUnique({
-    where: { id: params.id }
-  })
-
-  if (!user) {
-    throw new NotFoundError('User')
-  }
-
-  if (user.id !== session.user.id && session.user.role !== 'ADMIN') {
-    throw new ForbiddenError('Cannot access other users')
-  }
-
-  return NextResponse.json({ data: user })
-})
-```
-
-## Error Logging
-
-```typescript
-// lib/error-logger.ts
-import { AppError } from './errors'
-
-interface ErrorContext {
-  userId?: string
-  requestId?: string
-  path?: string
-  method?: string
-}
-
-export function logError(error: Error, context: ErrorContext = {}) {
-  const isOperational = error instanceof AppError
-
-  const logData = {
-    message: error.message,
-    stack: error.stack,
-    isOperational,
-    ...context,
-    timestamp: new Date().toISOString()
-  }
-
-  if (isOperational) {
-    console.warn('Operational error:', logData)
-  } else {
-    console.error('System error:', logData)
-    // Send to error tracking service
-    // await sendToSentry(error, context)
-  }
-}
-```
-
-## Client-Side Error Handling
-
-```typescript
-// lib/api-client.ts
-import { AppError } from './errors'
-
-interface ApiError {
-  error: {
-    message: string
-    code: string
-    details?: Record<string, unknown>
-  }
-}
-
-export async function apiRequest<T>(
-  url: string,
-  options?: RequestInit
-): Promise<T> {
-  const response = await fetch(url, {
-    ...options,
-    headers: {
-      'Content-Type': 'application/json',
-      ...options?.headers
-    }
-  })
-
-  const data = await response.json()
-
-  if (!response.ok) {
-    const apiError = data as ApiError
-    throw new AppError(
-      apiError.error.message,
-      response.status,
-      apiError.error.code
-    )
-  }
-
-  return data.data as T
-}
-
-// Usage
-try {
-  const user = await apiRequest<User>('/api/users/123')
-} catch (error) {
-  if (error instanceof AppError && error.code === 'NOT_FOUND') {
-    // Handle not found
-  }
-}
-```
-
-## When to Use
-
-- RESTful APIs
-- Consistent error format
-- Client error handling
-- Error monitoring

package/skills/patterns/api/graphql.md

@@ -1,440 +0,0 @@
-# GraphQL Patterns
-
-Patterns for implementing GraphQL APIs.
-
-## Apollo Server Setup
-
-```typescript
-// app/api/graphql/route.ts
-import { ApolloServer } from '@apollo/server'
-import { startServerAndCreateNextHandler } from '@as-integrations/next'
-import { typeDefs } from '@/graphql/schema'
-import { resolvers } from '@/graphql/resolvers'
-import { createContext } from '@/graphql/context'
-
-const server = new ApolloServer({
-  typeDefs,
-  resolvers
-})
-
-const handler = startServerAndCreateNextHandler(server, {
-  context: createContext
-})
-
-export { handler as GET, handler as POST }
-```
-
-## Schema Definition
-
-```typescript
-// graphql/schema.ts
-import { gql } from 'graphql-tag'
-
-export const typeDefs = gql`
-  type User {
-    id: ID!
-    email: String!
-    name: String
-    posts: [Post!]!
-    createdAt: String!
-  }
-
-  type Post {
-    id: ID!
-    title: String!
-    content: String
-    published: Boolean!
-    author: User!
-    comments: [Comment!]!
-    createdAt: String!
-  }
-
-  type Comment {
-    id: ID!
-    content: String!
-    author: User!
-    post: Post!
-    createdAt: String!
-  }
-
-  type Query {
-    me: User
-    user(id: ID!): User
-    users(limit: Int, offset: Int): [User!]!
-    post(id: ID!): Post
-    posts(published: Boolean, limit: Int, offset: Int): [Post!]!
-  }
-
-  type Mutation {
-    createUser(input: CreateUserInput!): User!
-    updateUser(id: ID!, input: UpdateUserInput!): User!
-    deleteUser(id: ID!): Boolean!
-
-    createPost(input: CreatePostInput!): Post!
-    updatePost(id: ID!, input: UpdatePostInput!): Post!
-    deletePost(id: ID!): Boolean!
-    publishPost(id: ID!): Post!
-
-    createComment(input: CreateCommentInput!): Comment!
-    deleteComment(id: ID!): Boolean!
-  }
-
-  input CreateUserInput {
-    email: String!
-    name: String
-    password: String!
-  }
-
-  input UpdateUserInput {
-    email: String
-    name: String
-  }
-
-  input CreatePostInput {
-    title: String!
-    content: String
-    published: Boolean
-  }
-
-  input UpdatePostInput {
-    title: String
-    content: String
-    published: Boolean
-  }
-
-  input CreateCommentInput {
-    postId: ID!
-    content: String!
-  }
-`
-```
-
-## Resolvers
-
-```typescript
-// graphql/resolvers.ts
-import { prisma } from '@/lib/db'
-import { GraphQLError } from 'graphql'
-import { Context } from './context'
-
-export const resolvers = {
-  Query: {
-    me: async (_: unknown, __: unknown, ctx: Context) => {
-      if (!ctx.user) return null
-      return prisma.user.findUnique({ where: { id: ctx.user.id } })
-    },
-
-    user: async (_: unknown, { id }: { id: string }) => {
-      return prisma.user.findUnique({ where: { id } })
-    },
-
-    users: async (_: unknown, { limit = 20, offset = 0 }: { limit?: number; offset?: number }) => {
-      return prisma.user.findMany({ take: limit, skip: offset })
-    },
-
-    post: async (_: unknown, { id }: { id: string }) => {
-      return prisma.post.findUnique({ where: { id } })
-    },
-
-    posts: async (_: unknown, args: { published?: boolean; limit?: number; offset?: number }) => {
-      return prisma.post.findMany({
-        where: args.published !== undefined ? { published: args.published } : undefined,
-        take: args.limit ?? 20,
-        skip: args.offset ?? 0,
-        orderBy: { createdAt: 'desc' }
-      })
-    }
-  },
-
-  Mutation: {
-    createPost: async (
-      _: unknown,
-      { input }: { input: { title: string; content?: string; published?: boolean } },
-      ctx: Context
-    ) => {
-      if (!ctx.user) {
-        throw new GraphQLError('Not authenticated', {
-          extensions: { code: 'UNAUTHENTICATED' }
-        })
-      }
-
-      return prisma.post.create({
-        data: {
-          ...input,
-          authorId: ctx.user.id
-        }
-      })
-    },
-
-    updatePost: async (
-      _: unknown,
-      { id, input }: { id: string; input: Partial<{ title: string; content: string; published: boolean }> },
-      ctx: Context
-    ) => {
-      const post = await prisma.post.findUnique({ where: { id } })
-
-      if (!post) {
-        throw new GraphQLError('Post not found', {
-          extensions: { code: 'NOT_FOUND' }
-        })
-      }
-
-      if (post.authorId !== ctx.user?.id) {
-        throw new GraphQLError('Not authorized', {
-          extensions: { code: 'FORBIDDEN' }
-        })
-      }
-
-      return prisma.post.update({
-        where: { id },
-        data: input
-      })
-    },
-
-    deletePost: async (_: unknown, { id }: { id: string }, ctx: Context) => {
-      const post = await prisma.post.findUnique({ where: { id } })
-
-      if (!post || post.authorId !== ctx.user?.id) {
-        throw new GraphQLError('Not authorized', {
-          extensions: { code: 'FORBIDDEN' }
-        })
-      }
-
-      await prisma.post.delete({ where: { id } })
-      return true
-    }
-  },
-
-  // Field resolvers for relations
-  User: {
-    posts: (parent: { id: string }) => {
-      return prisma.post.findMany({ where: { authorId: parent.id } })
-    }
-  },
-
-  Post: {
-    author: (parent: { authorId: string }) => {
-      return prisma.user.findUnique({ where: { id: parent.authorId } })
-    },
-    comments: (parent: { id: string }) => {
-      return prisma.comment.findMany({ where: { postId: parent.id } })
-    }
-  },
-
-  Comment: {
-    author: (parent: { userId: string }) => {
-      return prisma.user.findUnique({ where: { id: parent.userId } })
-    },
-    post: (parent: { postId: string }) => {
-      return prisma.post.findUnique({ where: { id: parent.postId } })
-    }
-  }
-}
-```
-
-## Context
-
-```typescript
-// graphql/context.ts
-import { NextRequest } from 'next/server'
-import { auth } from '@/auth'
-
-export interface Context {
-  user: { id: string; email: string } | null
-}
-
-export async function createContext({ req }: { req: NextRequest }): Promise<Context> {
-  const session = await auth()
-
-  return {
-    user: session?.user ? {
-      id: session.user.id!,
-      email: session.user.email!
-    } : null
-  }
-}
-```
-
-## DataLoader for N+1 Prevention
-
-```typescript
-// graphql/loaders.ts
-import DataLoader from 'dataloader'
-import { prisma } from '@/lib/db'
-import { User, Post } from '@prisma/client'
-
-export function createLoaders() {
-  return {
-    userLoader: new DataLoader<string, User | null>(async (ids) => {
-      const users = await prisma.user.findMany({
-        where: { id: { in: [...ids] } }
-      })
-
-      const userMap = new Map(users.map(u => [u.id, u]))
-      return ids.map(id => userMap.get(id) ?? null)
-    }),
-
-    userPostsLoader: new DataLoader<string, Post[]>(async (userIds) => {
-      const posts = await prisma.post.findMany({
-        where: { authorId: { in: [...userIds] } }
-      })
-
-      const postsByUser = new Map<string, Post[]>()
-      posts.forEach(post => {
-        const existing = postsByUser.get(post.authorId) ?? []
-        postsByUser.set(post.authorId, [...existing, post])
-      })
-
-      return userIds.map(id => postsByUser.get(id) ?? [])
-    })
-  }
-}
-
-// Updated context
-export interface Context {
-  user: { id: string; email: string } | null
-  loaders: ReturnType<typeof createLoaders>
-}
-
-// Updated resolvers using loaders
-export const resolvers = {
-  Post: {
-    author: (parent: { authorId: string }, _: unknown, ctx: Context) => {
-      return ctx.loaders.userLoader.load(parent.authorId)
-    }
-  },
-  User: {
-    posts: (parent: { id: string }, _: unknown, ctx: Context) => {
-      return ctx.loaders.userPostsLoader.load(parent.id)
-    }
-  }
-}
-```
-
-## Client-Side Usage
-
-```typescript
-// lib/graphql/client.ts
-import { ApolloClient, InMemoryCache, createHttpLink } from '@apollo/client'
-import { setContext } from '@apollo/client/link/context'
-
-const httpLink = createHttpLink({
-  uri: '/api/graphql'
-})
-
-const authLink = setContext((_, { headers }) => {
-  const token = typeof window !== 'undefined'
-    ? localStorage.getItem('token')
-    : null
-
-  return {
-    headers: {
-      ...headers,
-      authorization: token ? `Bearer ${token}` : ''
-    }
-  }
-})
-
-export const apolloClient = new ApolloClient({
-  link: authLink.concat(httpLink),
-  cache: new InMemoryCache()
-})
-
-// hooks/usePosts.ts
-import { gql, useQuery, useMutation } from '@apollo/client'
-
-const GET_POSTS = gql`
-  query GetPosts($limit: Int, $offset: Int) {
-    posts(limit: $limit, offset: $offset) {
-      id
-      title
-      content
-      published
-      author {
-        id
-        name
-      }
-    }
-  }
-`
-
-const CREATE_POST = gql`
-  mutation CreatePost($input: CreatePostInput!) {
-    createPost(input: $input) {
-      id
-      title
-    }
-  }
-`
-
-export function usePosts(limit = 10) {
-  const { data, loading, error, fetchMore } = useQuery(GET_POSTS, {
-    variables: { limit, offset: 0 }
-  })
-
-  const loadMore = () => {
-    fetchMore({
-      variables: { offset: data?.posts.length ?? 0 }
-    })
-  }
-
-  return { posts: data?.posts ?? [], loading, error, loadMore }
-}
-
-export function useCreatePost() {
-  const [createPost, { loading, error }] = useMutation(CREATE_POST, {
-    refetchQueries: [{ query: GET_POSTS }]
-  })
-
-  return { createPost, loading, error }
-}
-```
-
-## Subscriptions with WebSocket
-
-```typescript
-// graphql/schema.ts (add subscription type)
-const typeDefs = gql`
-  type Subscription {
-    postCreated: Post!
-    commentAdded(postId: ID!): Comment!
-  }
-`
-
-// graphql/resolvers.ts
-import { PubSub } from 'graphql-subscriptions'
-
-const pubsub = new PubSub()
-
-export const resolvers = {
-  Mutation: {
-    createPost: async (_: unknown, { input }: any, ctx: Context) => {
-      const post = await prisma.post.create({
-        data: { ...input, authorId: ctx.user!.id }
-      })
-
-      pubsub.publish('POST_CREATED', { postCreated: post })
-
-      return post
-    }
-  },
-
-  Subscription: {
-    postCreated: {
-      subscribe: () => pubsub.asyncIterableIterator(['POST_CREATED'])
-    },
-    commentAdded: {
-      subscribe: (_: unknown, { postId }: { postId: string }) => {
-        return pubsub.asyncIterableIterator([`COMMENT_ADDED_${postId}`])
-      }
-    }
-  }
-}
-```
-
-## When to Use
-
-- Complex data requirements
-- Multiple clients (web, mobile)
-- Real-time features
-- Flexible API queries