feat: implement issues #598-601 refactoring

.gitignore

@@ -3,6 +3,7 @@ node_modules/
 
 # Environment
 .env*
+!.env.example
 
 # OS
 .DS_Store
@@ -18,22 +19,46 @@ Thumbs.db
 dist/
 build/
 out/
-
-# Next.js
 .next/
 .vercel
 
 # Debug
 *.log
 npm-debug.log*
+lighthouse/
 
 # Keys
 *.pem
 
+# AI
 .claude
+.kilocode/
+
+# Reports
 .lhci_reports/
 bundle-reports/
 trend-data.json
+
+# Generated code
 packages/*/dist/
 frontend/src/generated/
-packages/contracts/src/generated/
+packages/contracts/src/generated/
+
+# Test snapshots and artifacts
+**/__snapshots__/
+**/*.snap
+coverage/
+
+# Rust
+contracts/target/
+contracts/*.wasm
+
+# Docker
+docker-compose.override.yml
+
+# Turbo
+.turbo/
+
+# Misc
+test-write.txt
+AGENTS.md

backend/prisma/schema.prisma

@@ -1,5 +1,12 @@
-// Prisma schema — Issue #207
-// Full type-safe schema with soft deletes, indexes, and relations.
+// Prisma schema — Issue #598
+// Full type-safe schema with soft deletes, indexes, relations, and base model patterns.
+//
+// Base model pattern (applied to all auditable entities):
+//   id            String    @id @default(uuid())
+//   tenantId      String    @map("tenant_id")
+//   createdAt     DateTime  @default(now()) @map("created_at")
+//   updatedAt     DateTime  @updatedAt @map("updated_at")
+//   deletedAt     DateTime? @map("deleted_at")
 
 generator client {
   provider = "prisma-client-js"

backend/src/middleware/errorHandler.ts

@@ -1,30 +1,35 @@
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
 import { ERROR_CODE_REGISTRY, resolveErrorCode } from '@agenticpay/error-codes';
+import { PaymentError, AuthError, ProjectError, DisputeError, ValidationError, NotFoundError } from '../types/errors';
 
 type AsyncRouteHandler = (req: Request, res: Response, next: NextFunction) => Promise<unknown>;
 
 export class AppError extends Error {
   statusCode: number;
   code: string;
   details?: unknown;
+  metadata?: Record<string, unknown>;
 
-  constructor(statusCode: number, message: string, code = 'INTERNAL_SERVER_ERROR', details?: unknown) {
+  constructor(statusCode: number, message: string, code = 'INTERNAL_SERVER_ERROR', details?: unknown, metadata?: Record<string, unknown>) {
     super(message);
     this.name = 'AppError';
     this.statusCode = statusCode;
     this.code = code;
     this.details = details;
+    this.metadata = metadata;
   }
 }
 
+export { PaymentError, AuthError, ProjectError, DisputeError, ValidationError, NotFoundError };
+
 export function asyncHandler(handler: AsyncRouteHandler): RequestHandler {
   return (req, res, next) => {
     Promise.resolve(handler(req, res, next)).catch(next);
   };
 }
 
 export function notFoundHandler(req: Request, _res: Response, next: NextFunction) {
-  next(new AppError(404, `Route not found: ${req.method} ${req.originalUrl}`, 'NOT_FOUND'));
+  next(new NotFoundError(`Route not found: ${req.method} ${req.originalUrl}`));
 }
 
 export function errorHandler(err: unknown, req: Request, res: Response, _next: NextFunction) {
@@ -42,7 +47,16 @@ export function errorHandler(err: unknown, req: Request, res: Response, _next: N
         : 'Unexpected error';
 
   const logMethod = registered.httpStatus >= 500 ? console.error : console.warn;
-  logMethod(`[${code}] ${message}`, err);
+  const logContext = {
+    code,
+    message,
+    statusCode: registered.httpStatus || statusCode,
+    ...(isAppError && err.metadata ? { metadata: err.metadata } : {}),
+    ...(req.requestId ? { requestId: req.requestId } : {}),
+    ...(req.user?.id ? { userId: req.user.id } : {}),
+    ...(!isProduction && !isAppError && err instanceof Error && err.stack ? { stack: err.stack } : {}),
+  };
+  logMethod(`[${code}] ${message}`, logContext);
 
   if (registered.deprecated && registered.sunsetAt) {
     res.setHeader('Sunset', registered.sunsetAt);

backend/src/types/errors.ts

@@ -0,0 +1,71 @@
+export class PaymentError extends Error {
+  constructor(
+    message: string,
+    public code: string = 'PAYMENT_ERROR',
+    public statusCode: number = 400,
+    public metadata?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'PaymentError';
+  }
+}
+
+export class AuthError extends Error {
+  constructor(
+    message: string,
+    public code: string = 'AUTH_ERROR',
+    public statusCode: number = 401,
+    public metadata?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'AuthError';
+  }
+}
+
+export class ProjectError extends Error {
+  constructor(
+    message: string,
+    public code: string = 'PROJECT_ERROR',
+    public statusCode: number = 400,
+    public metadata?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'ProjectError';
+  }
+}
+
+export class DisputeError extends Error {
+  constructor(
+    message: string,
+    public code: string = 'DISPUTE_ERROR',
+    public statusCode: number = 400,
+    public metadata?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'DisputeError';
+  }
+}
+
+export class NotFoundError extends Error {
+  constructor(
+    message: string,
+    public code: string = 'NOT_FOUND',
+    public statusCode: number = 404,
+    public metadata?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'NotFoundError';
+  }
+}
+
+export class ValidationError extends Error {
+  constructor(
+    message: string,
+    public code: string = 'VALIDATION_ERROR',
+    public statusCode: number = 422,
+    public metadata?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}