@mr.dj2u/knowledge 0.1.0

package/dist/content/patterns/api/error-handling.md

@@ -0,0 +1,311 @@
+# Error Handling in API Services
+
+## Description
+
+Structured error handling in API services uses custom error classes with status codes, error details, and proper HTTP response formatting. This ensures consistent error responses across all API endpoints with full context for debugging and client-side error handling.
+
+## When to Use
+
+**Use custom error handling** for:
+- ✅ API endpoints that need consistent error responses
+- ✅ Services that interact with external APIs or databases
+- ✅ Situations where you need to distinguish error types and statuses
+- ✅ Client-side error handling with structured error objects
+
+## Code Example
+
+### Custom Error Class Definition
+
+```typescript
+// File: src/services/quantum-key-management.ts
+export class QuantumApiError extends Error {
+  status: number;
+  details?: unknown;
+
+  constructor(message: string, status: number, details?: unknown) {
+    super(message);
+    this.name = 'QuantumApiError';
+    this.status = status;
+    this.details = details;
+    
+    // Maintain proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, QuantumApiError.prototype);
+  }
+}
+
+// Usage in services
+async function fetchQuantumProfile(
+  bearerClient: QuantumApiClient,
+  profileId: string
+): Promise<IbmProfileRecord> {
+  try {
+    const response = await bearerClient.getProfile(profileId);
+    return response;
+  } catch (err) {
+    if (err instanceof SdkQuantumApiError) {
+      throw new QuantumApiError(
+        `Failed to fetch profile: ${err.message}`,
+        err.statusCode || 500,
+        { originalError: err }
+      );
+    }
+    throw new QuantumApiError(
+      'Unknown error fetching profile',
+      500,
+      { originalError: err }
+    );
+  }
+}
+```
+
+**From:** DJsPortfolio/src/services/quantum-key-management.ts (lines 1-60)
+
+### SDK Client Error Mapping
+
+```typescript
+// File: src/lib/quantum-sdk-executor.ts
+import { QuantumApiError as SdkQuantumApiError } from '@mr.dj2u/quantum-api';
+
+export type QuantumSdkEndpointExecutionResult = {
+  status: number;
+  statusText: string;
+  data: unknown;
+};
+
+async function executeQuantumEndpoint(
+  input: QuantumSdkEndpointExecutionInput
+): Promise<QuantumSdkEndpointExecutionResult> {
+  try {
+    // Select appropriate client based on auth method
+    const client = input.bearerToken
+      ? createQuantumBearerClient(input.baseUrl, input.bearerToken)
+      : createQuantumPublicClient(input.baseUrl);
+
+    // Execute request
+    const response = await client.request({
+      method: input.method,
+      path: input.path,
+      body: input.body,
+    });
+
+    return {
+      status: response.status,
+      statusText: response.statusText,
+      data: response.data,
+    };
+  } catch (err) {
+    if (err instanceof SdkQuantumApiError) {
+      return {
+        status: err.statusCode || 500,
+        statusText: 'Error',
+        data: {
+          error: err.message,
+          details: err.details,
+        },
+      };
+    }
+    
+    return {
+      status: 500,
+      statusText: 'Internal Server Error',
+      data: {
+        error: 'Unexpected error executing endpoint',
+      },
+    };
+  }
+}
+```
+
+**From:** DJsPortfolio/src/lib/quantum-sdk-executor.ts (lines 1-50)
+
+### Error Response Format
+
+```typescript
+// Standard error response structure
+type ErrorResponse = {
+  error: string;           // Human-readable error message
+  status: number;          // HTTP status code
+  details?: unknown;       // Additional error context
+  timestamp?: string;      // When error occurred
+};
+
+// Return from API route
+export async function POST(request: ExpoRequest) {
+  try {
+    const data = await request.json();
+    const result = await processQuantumRequest(data);
+    return new ExpoResponse(JSON.stringify(result), { status: 200 });
+  } catch (err) {
+    const errorResponse: ErrorResponse = {
+      error: err instanceof Error ? err.message : 'Unknown error',
+      status: err instanceof QuantumApiError ? err.status : 500,
+      details: err instanceof QuantumApiError ? err.details : undefined,
+      timestamp: new Date().toISOString(),
+    };
+
+    return new ExpoResponse(
+      JSON.stringify(errorResponse),
+      {
+        status: errorResponse.status,
+        headers: { 'Content-Type': 'application/json' },
+      }
+    );
+  }
+}
+```
+
+## Configuration
+
+### Environment-Specific Error Handling
+
+```typescript
+// config/error-handling.ts
+export const errorConfig = {
+  development: {
+    exposeStackTraces: true,
+    logErrors: true,
+    verboseMessages: true,
+  },
+  production: {
+    exposeStackTraces: false,
+    logErrors: true,
+    verboseMessages: false,
+  },
+};
+
+export function shouldExposeErrorDetails(): boolean {
+  return errorConfig[process.env.NODE_ENV || 'development'].exposeStackTraces;
+}
+```
+
+### Error Logging
+
+```typescript
+// middleware/error-logger.ts
+export function logError(err: Error, context?: Record<string, any>) {
+  const timestamp = new Date().toISOString();
+  const errorData = {
+    timestamp,
+    message: err.message,
+    name: err.name,
+    stack: err.stack,
+    context,
+  };
+
+  console.error(JSON.stringify(errorData));
+  
+  // Could also send to external logging service
+  // sendToSentry(errorData);
+}
+```
+
+## Best Practices
+
+### ✅ DO
+
+1. **Create typed error classes** for different error scenarios
+   ```typescript
+   class ValidationError extends Error {
+     constructor(public field: string, message: string) {
+       super(message);
+       this.name = 'ValidationError';
+     }
+   }
+   
+   class AuthenticationError extends Error {
+     constructor(message: string) {
+       super(message);
+       this.name = 'AuthenticationError';
+     }
+   }
+   ```
+
+2. **Include status codes** with all errors
+   ```typescript
+   throw new ValidationError('email', 'Invalid email format');
+   // Map to 400 status in handler
+   ```
+
+3. **Log errors with context** for debugging
+   ```typescript
+   try {
+     await fetchData();
+   } catch (err) {
+     logError(err, {
+       userId: user.id,
+       action: 'fetch-profile',
+       timestamp: Date.now(),
+     });
+   }
+   ```
+
+4. **Distinguish error types** in client responses
+   ```typescript
+   const statusMap = {
+     ValidationError: 400,
+     AuthenticationError: 401,
+     NotFoundError: 404,
+     ServerError: 500,
+   };
+   ```
+
+### ❌ DON'T
+
+1. **Don't expose internal error details** in production
+   ```typescript
+   // ❌ BAD - leaks implementation details
+   return JSON.stringify({ error: err.stack });
+   
+   // ✅ GOOD - generic message, log details server-side
+   return JSON.stringify({ error: 'Internal server error' });
+   ```
+
+2. **Don't ignore error types** from third-party libraries
+   ```typescript
+   // ❌ BAD - loses error context
+   catch (err) {
+     throw new Error('Failed');
+   }
+   
+   // ✅ GOOD - map SDK errors to application errors
+   catch (err) {
+     if (err instanceof SdkError) {
+       throw new ApiError(err.message, err.statusCode);
+     }
+   }
+   ```
+
+3. **Don't return different error formats** across endpoints
+   ```typescript
+   // ❌ INCONSISTENT
+   Endpoint 1: { message: "Error" }
+   Endpoint 2: { error: "Error" }
+   Endpoint 3: { err: "Error" }
+   
+   // ✅ CONSISTENT
+   All endpoints: { error, status, details, timestamp }
+   ```
+
+4. **Don't forget to set proper HTTP status codes**
+   ```typescript
+   // ❌ BAD - always returns 200
+   return new ExpoResponse(JSON.stringify(error), { status: 200 });
+   
+   // ✅ GOOD - correct status codes
+   return new ExpoResponse(
+     JSON.stringify(error),
+     { status: error.status || 500 }
+   );
+   ```
+
+## Related Patterns
+
+- [API Routes](./api-routes.md) — Route endpoint structure
+- [CORS Configuration](./cors-configuration.md) — Origin validation
+- [Health Endpoints](./health-endpoints.md) — Health check patterns
+
+---
+
+*Pattern extracted from production repositories: DJsPortfolio, PokePages*
+*Files: DJsPortfolio/src\services\quantum-key-management.ts*
+*Lines 1-60 showing custom QuantumApiError class and error handling patterns*

package/dist/content/patterns/database/drizzle-schema.md

@@ -0,0 +1,280 @@
+# Drizzle ORM Schema Design
+
+## Description
+
+Drizzle ORM schemas define type-safe database tables with full TypeScript inference from database types to application types. Schemas use domain-specific files with shared relations.ts for foreign keys and relationships, enabling compile-time type safety and automatic type generation.
+
+## When to Use
+
+**Use Drizzle schemas** for:
+- ✅ Any PostgreSQL table definition in React Native/Node.js applications
+- ✅ Projects requiring full TypeScript type inference (no separate type definitions)
+- ✅ Applications with complex relationships and joins
+- ✅ Teams valuing compile-time safety over runtime convenience
+
+## Code Example
+
+### Basic Schema with Type Inference
+
+```typescript
+// File: packages/db/src/schema/quantum-api/quantum-execution-jobs/schema.ts
+import { pgTable, uuid, text, jsonb, integer, timestamp, unique, check } from 'drizzle-orm/pg-core';
+
+export const quantumExecutionJobs = pgTable('quantum_execution_jobs', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  provider: text('provider').notNull(), // 'ibm' | 'aws' | etc.
+  remoteJobId: text('remote_job_id').notNull(),
+  status: text('status').notNull().default('queued'), // queued | running | succeeded | failed | cancelled
+  requestPayload: jsonb('request_payload').notNull(), // Full request object
+  resultPayload: jsonb('result_payload'), // Result when status === succeeded
+  errorPayload: jsonb('error_payload'), // Error object when status === failed
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+  completedAt: timestamp('completed_at'),
+}, (table) => ({
+  // Composite unique constraint
+  uniqueRemoteJob: unique().on(table.provider, table.remoteJobId),
+  
+  // Check constraints for valid status values
+  statusCheck: check(
+    'status_check',
+    sql`status IN ('queued', 'running', 'succeeded', 'failed', 'cancelled')`
+  ),
+  
+  // Ensure completedAt is set when status is terminal
+  completedAtCheck: check(
+    'completed_at_check',
+    sql`(status IN ('succeeded', 'failed', 'cancelled') AND completed_at IS NOT NULL) 
+        OR (status NOT IN ('succeeded', 'failed', 'cancelled') AND completed_at IS NULL)`
+  ),
+}));
+
+// Infer types from schema
+export type QuantumExecutionJob = typeof quantumExecutionJobs.$inferSelect;
+export type NewQuantumExecutionJob = typeof quantumExecutionJobs.$inferInsert;
+```
+
+**From:** DJsPortfolio/packages/db/src/schema/quantum-api/quantum-execution-jobs/schema.ts (lines 1-69)
+
+### Schema with Foreign Keys
+
+```typescript
+// File: src/db/eventClaimsSchema.ts (PokePages pattern)
+import { pgTable, uuid, text, timestamp, integer, foreignKey } from 'drizzle-orm/pg-core';
+import { profiles } from './profilesSchema';
+import { events } from './eventsSchema';
+
+export const eventClaims = pgTable(
+  'event_claims',
+  {
+    id: uuid('id').defaultRandom().primaryKey(),
+    userId: uuid('user_id').notNull(),
+    eventId: uuid('event_id').notNull(),
+    claimedAt: timestamp('claimed_at').defaultNow().notNull(),
+    proofData: text('proof_data'), // Optional proof/screenshot
+  },
+  (table) => ({
+    userFk: foreignKey({
+      columns: [table.userId],
+      foreignColumns: [profiles.id],
+      name: 'event_claims_user_fk',
+    }).onDelete('cascade'),
+    
+    eventFk: foreignKey({
+      columns: [table.eventId],
+      foreignColumns: [events.id],
+      name: 'event_claims_event_fk',
+    }).onDelete('cascade'),
+    
+    // Unique constraint: user can only claim event once
+    uniqueUserEvent: unique().on(table.userId, table.eventId),
+  })
+);
+
+export type EventClaim = typeof eventClaims.$inferSelect;
+export type NewEventClaim = typeof eventClaims.$inferInsert;
+```
+
+**From:** PokePages/src/db/eventClaimsSchema.ts pattern
+
+### Indexed Schema for Performance
+
+```typescript
+// File: src/db/postsSchema.ts
+import { pgTable, uuid, text, timestamp, integer, index } from 'drizzle-orm/pg-core';
+
+export const posts = pgTable(
+  'posts',
+  {
+    id: uuid('id').defaultRandom().primaryKey(),
+    userId: uuid('user_id').notNull(),
+    title: text('title').notNull(),
+    content: text('content').notNull(),
+    likes: integer('likes').default(0),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+    updatedAt: timestamp('updated_at').defaultNow().notNull(),
+    deletedAt: timestamp('deleted_at'), // Soft delete
+  },
+  (table) => ({
+    // Single column indexes for common queries
+    userIdIdx: index('posts_user_id_idx').on(table.userId),
+    createdAtIdx: index('posts_created_at_idx').on(table.createdAt),
+    
+    // Composite index for common query pattern
+    userCreatedIdx: index('posts_user_created_idx')
+      .on(table.userId, table.createdAt),
+    
+    // Index for soft deletes
+    activePostsIdx: index('posts_active_idx')
+      .on(table.userId, table.deletedAt),
+  })
+);
+```
+
+## Configuration
+
+### Database Connection Setup
+
+```typescript
+// File: src/db/index.ts
+import { drizzle } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+import * as schemas from './schemas';
+
+const connectionString = process.env.DATABASE_URL!;
+
+// Optimized connection pool for Supabase PgBouncer
+export const client = postgres(connectionString, {
+  prepare: false,        // Required for PgBouncer
+  ssl: 'require',
+  max: 3,               // Small pool size
+  idle_timeout: 20,     // Close idle connections
+  connect_timeout: 30,  // Connection timeout
+  max_lifetime: 1800,   // Recycle after 30 minutes
+});
+
+export const db = drizzle(client, {
+  schema: schemas,
+});
+```
+
+### TypeScript Configuration
+
+```typescript
+// File: tsconfig.json
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "drizzle-orm/compiler",
+        "options": {
+          "casing": "snake_case"
+        }
+      }
+    ]
+  }
+}
+```
+
+## Best Practices
+
+### ✅ DO
+
+1. **Infer types from schema** — don't maintain separate type definitions
+   ```typescript
+   // ✅ GOOD - single source of truth
+   export type Post = typeof posts.$inferSelect;
+   export type NewPost = typeof posts.$inferInsert;
+   
+   // ❌ BAD - duplicate type definitions
+   interface Post {
+     id: string;
+     title: string;
+     // ... manually maintaining type sync
+   }
+   ```
+
+2. **Use domain-specific schema files**
+   ```
+   src/db/
+   ├── profilesSchema.ts
+   ├── postsSchema.ts
+   ├── commentsSchema.ts
+   ├── relations.ts      ← all relationships defined here
+   └── index.ts
+   ```
+
+3. **Define relationships in shared relations.ts**
+   ```typescript
+   // File: src/db/relations.ts
+   import { relations } from 'drizzle-orm';
+   import { profiles, posts, comments } from './schemas';
+   
+   export const profilesRelations = relations(profiles, ({ many }) => ({
+     posts: many(posts),
+   }));
+   ```
+
+4. **Use JSONB for flexible data** instead of many normalized tables
+   ```typescript
+   requestPayload: jsonb('request_payload').notNull(),
+   resultPayload: jsonb('result_payload'),
+   ```
+
+5. **Add check constraints** for data integrity
+   ```typescript
+   check(
+     'status_check',
+     sql`status IN ('pending', 'completed', 'failed')`
+   )
+   ```
+
+### ❌ DON'T
+
+1. **Don't create overly normalized schemas** when embedding is more performant
+   ```typescript
+   // ❌ AVOID - creates N+1 queries
+   users table → user_profiles table → user_settings table
+   
+   // ✅ BETTER - use JSONB for related data
+   users: { profile: jsonb, settings: jsonb }
+   ```
+
+2. **Don't forget indexes** on frequently queried columns
+   ```typescript
+   // ❌ BAD - no index on userId
+   posts table with userId but no index
+   
+   // ✅ GOOD - indexed for fast lookups
+   userIdIdx: index().on(table.userId)
+   ```
+
+3. **Don't use mutable defaults** (like functions) for timestamps
+   ```typescript
+   // ❌ BAD - function called once at migration time
+   createdAt: timestamp('created_at').default(fn)
+   
+   // ✅ GOOD - database handles default for each row
+   createdAt: timestamp('created_at').defaultNow()
+   ```
+
+4. **Don't create tables without soft delete** if you might need historical data
+   ```typescript
+   // ✅ GOOD - reversible deletion
+   deletedAt: timestamp('deleted_at')
+   
+   // Query active records
+   where(isNull(posts.deletedAt))
+   ```
+
+## Related Patterns
+
+- [Database Migrations](./migrations.md) — Managing schema changes
+- [Relationships](./relations.md) — Foreign keys and joins
+- [Query Organization](./query-organization.md) — Data access layer
+
+---
+
+*Pattern extracted from production repositories: DJsPortfolio, PokePages, core-monorepo*
+*Files: DJsPortfolio/packages\db\src\schema\quantum-api\quantum-execution-jobs\schema.ts*
+*Lines 1-69 with full JSONB payload handling and check constraints*