blockmine 1.21.0 → 1.22.0

package/.claude/skills/api-engineering/resources/api-versioning.md

@@ -0,0 +1,88 @@
+# API Versioning
+
+Guide to API versioning strategies and best practices.
+
+## Versioning Strategies
+
+### URI Versioning
+```
+GET /v1/users/123
+GET /v2/users/123
+
+Pros: Simple, clear
+Cons: Pollutes URI space
+```
+
+### Header Versioning
+```
+GET /users/123
+Accept: application/vnd.myapi.v1+json
+
+Pros: Clean URIs
+Cons: Less visible, harder to test
+```
+
+### Query Parameter
+```
+GET /users/123?version=1
+GET /users/123?version=2
+
+Pros: Simple
+Cons: Easy to forget, not RESTful
+```
+
+## Semantic Versioning
+
+```
+MAJOR.MINOR.PATCH
+
+v1.0.0 → v1.1.0: New feature (backward-compatible)
+v1.1.0 → v2.0.0: Breaking change
+v2.0.0 → v2.0.1: Bug fix
+```
+
+## Breaking vs Non-Breaking Changes
+
+```
+Breaking Changes (require new version):
+- Removing endpoint
+- Removing field
+- Changing field type
+- Changing response structure
+- Renaming field
+
+Non-Breaking (can be same version):
+- Adding new endpoint
+- Adding new optional field
+- Adding new query parameter
+- Deprecating (but not removing) field
+```
+
+## Deprecation Strategy
+
+```typescript
+// Mark deprecated fields
+type User {
+  id: ID!
+  fullName: String!
+  name: String! @deprecated(reason: "Use fullName instead")
+}
+
+// Add deprecation headers
+res.setHeader('Deprecation', 'Sun, 01 Jan 2025 00:00:00 GMT');
+res.setHeader('Link', '</v2/users>; rel="successor-version"');
+```
+
+## Best Practices
+
+✅ Version from day one (v1)
+✅ Support 2-3 versions simultaneously
+✅ Give 6-12 months deprecation notice
+✅ Document breaking changes clearly
+✅ Use semantic versioning
+✅ Provide migration guides
+
+---
+
+**Related Resources:**
+- rest-api-design.md - API design principles

package/.claude/skills/api-engineering/resources/graphql-patterns.md

@@ -0,0 +1,106 @@
+# GraphQL Patterns
+
+Guide to GraphQL schema design, resolvers, and common patterns.
+
+## Schema Design
+
+```graphql
+type User {
+  id: ID!
+  email: String!
+  name: String!
+  posts: [Post!]!
+}
+
+type Post {
+  id: ID!
+  title: String!
+  content: String!
+  author: User!
+}
+
+type Query {
+  user(id: ID!): User
+  users(limit: Int, offset: Int): [User!]!
+}
+
+type Mutation {
+  createUser(email: String!, name: String!): User!
+  updateUser(id: ID!, name: String): User!
+}
+```
+
+## Resolvers
+
+```typescript
+const resolvers = {
+  Query: {
+    user: async (parent, { id }, context) => {
+      return await context.prisma.user.findUnique({ where: { id } });
+    },
+    users: async (parent, { limit, offset }, context) => {
+      return await context.prisma.user.findMany({
+        take: limit,
+        skip: offset,
+      });
+    },
+  },
+
+  Mutation: {
+    createUser: async (parent, { email, name }, context) => {
+      return await context.prisma.user.create({
+        data: { email, name },
+      });
+    },
+  },
+
+  User: {
+    posts: async (parent, args, context) => {
+      return await context.prisma.post.findMany({
+        where: { authorId: parent.id },
+      });
+    },
+  },
+};
+```
+
+## N+1 Problem & DataLoader
+
+```typescript
+// ❌ N+1 Problem
+// Fetching 100 users causes 100 additional queries for posts
+const users = await prisma.user.findMany();  // 1 query
+for (const user of users) {
+  const posts = await prisma.post.findMany({ where: { authorId: user.id } });  // N queries
+}
+
+// ✅ Solution: DataLoader
+import DataLoader from 'dataloader';
+
+const postLoader = new DataLoader(async (userIds) => {
+  const posts = await prisma.post.findMany({
+    where: { authorId: { in: userIds } },
+  });
+
+  // Group posts by user ID
+  const postsByUser = {};
+  posts.forEach(post => {
+    if (!postsByUser[post.authorId]) postsByUser[post.authorId] = [];
+    postsByUser[post.authorId].push(post);
+  });
+
+  return userIds.map(id => postsByUser[id] || []);
+});
+
+// In resolver
+User: {
+  posts: (parent, args, context) => {
+    return context.postLoader.load(parent.id);  // Batched!
+  },
+}
+```
+
+---
+
+**Related Resources:**
+- rest-api-design.md - REST comparison

package/.claude/skills/api-engineering/resources/rate-limiting.md

@@ -0,0 +1,118 @@
+# Rate Limiting
+
+Guide to implementing rate limiting and throttling for APIs.
+
+## Algorithms
+
+### Token Bucket
+```typescript
+class TokenBucket {
+  constructor(
+    private capacity: number,  // Max tokens
+    private refillRate: number  // Tokens per second
+  ) {}
+
+  async consume(tokens: number = 1): Promise<boolean> {
+    const key = `rate-limit:${userId}`;
+    const current = await redis.get(key) || this.capacity;
+
+    if (current >= tokens) {
+      await redis.decrby(key, tokens);
+      return true;  // Allowed
+    }
+    return false;  // Rate limited
+  }
+}
+
+// Usage: 100 requests per minute
+const limiter = new TokenBucket(100, 100/60);
+```
+
+### Sliding Window
+```typescript
+async function checkRateLimit(userId: string, limit: number, windowMs: number) {
+  const key = `rate-limit:${userId}`;
+  const now = Date.now();
+  const windowStart = now - windowMs;
+
+  // Remove old entries
+  await redis.zremrangebyscore(key, 0, windowStart);
+
+  // Count requests in window
+  const count = await redis.zcard(key);
+
+  if (count < limit) {
+    await redis.zadd(key, now, `${now}-${Math.random()}`);
+    await redis.expire(key, Math.ceil(windowMs / 1000));
+    return true;  // Allowed
+  }
+
+  return false;  // Rate limited
+}
+
+// Usage: 1000 requests per hour
+await checkRateLimit(userId, 1000, 3600000);
+```
+
+## Express Middleware
+
+```typescript
+import rateLimit from 'express-rate-limit';
+import RedisStore from 'rate-limit-redis';
+import Redis from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+const limiter = rateLimit({
+  store: new RedisStore({ client: redis }),
+  windowMs: 15 * 60 * 1000,  // 15 minutes
+  max: 100,  // 100 requests per window
+  message: 'Too many requests, please try again later',
+  standardHeaders: true,
+  legacyHeaders: false,
+});
+
+app.use('/api/', limiter);
+```
+
+## Response Headers
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 85
+X-RateLimit-Reset: 1642348800
+
+HTTP 429 Too Many Requests
+Retry-After: 60
+```
+
+## Per-User vs Per-IP
+
+```typescript
+// Per-user (authenticated)
+const userLimiter = rateLimit({
+  keyGenerator: (req) => req.user?.id || req.ip,
+  max: 1000,  // Higher limit for authenticated users
+});
+
+// Per-IP (unauthenticated)
+const ipLimiter = rateLimit({
+  keyGenerator: (req) => req.ip,
+  max: 100,  // Lower limit for anonymous users
+});
+```
+
+## Best Practices
+
+✅ Use distributed rate limiting (Redis)
+✅ Return clear error messages
+✅ Include rate limit headers
+✅ Different limits for authenticated vs anonymous
+✅ Higher limits for premium users
+✅ Monitor rate limit hits
+
+---
+
+**Related Resources:**
+- rest-api-design.md - API design
+- api-versioning.md - API versions

package/.claude/skills/api-engineering/resources/rest-api-design.md

@@ -0,0 +1,105 @@
+# REST API Design
+
+Guide to designing RESTful APIs following best practices.
+
+## RESTful Principles
+
+```
+Resources (nouns, not verbs):
+✅ GET /users/123
+✅ POST /orders
+❌ GET /getUser/123
+❌ POST /createOrder
+
+HTTP Methods:
+GET    - Retrieve resource
+POST   - Create resource
+PUT    - Update entire resource
+PATCH  - Partial update
+DELETE - Remove resource
+```
+
+## Resource Modeling
+
+```
+Collection: /users
+Resource:   /users/123
+Sub-resource: /users/123/orders
+```
+
+## HTTP Status Codes
+
+```
+200 OK - Successful GET, PUT, PATCH
+201 Created - Successful POST
+204 No Content - Successful DELETE
+400 Bad Request - Invalid input
+401 Unauthorized - Missing/invalid auth
+403 Forbidden - Authenticated but not authorized
+404 Not Found - Resource doesn't exist
+409 Conflict - Resource conflict (e.g., duplicate email)
+422 Unprocessable Entity - Validation errors
+429 Too Many Requests - Rate limit exceeded
+500 Internal Server Error - Server error
+```
+
+## Request/Response Examples
+
+```typescript
+// POST /users (Create)
+Request:
+{
+  "email": "user@example.com",
+  "name": "John Doe"
+}
+
+Response (201 Created):
+{
+  "id": "usr_123",
+  "email": "user@example.com",
+  "name": "John Doe",
+  "created_at": "2024-01-15T10:30:00Z"
+}
+
+// GET /users?page=1&limit=20 (List with pagination)
+Response (200 OK):
+{
+  "data": [...],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 150,
+    "pages": 8
+  }
+}
+
+// PATCH /users/123 (Partial update)
+Request:
+{
+  "name": "Jane Doe"
+}
+
+Response (200 OK):
+{
+  "id": "usr_123",
+  "email": "user@example.com",
+  "name": "Jane Doe",
+  "updated_at": "2024-01-15T11:00:00Z"
+}
+```
+
+## Best Practices
+
+✅ Use nouns for resources
+✅ Plural resource names (/users, not /user)
+✅ Use proper HTTP methods
+✅ Return appropriate status codes
+✅ Implement pagination
+✅ Use filtering (?status=active)
+✅ Consistent error format
+
+---
+
+**Related Resources:**
+- api-versioning.md - API versioning
+- rate-limiting.md - Rate limiting

package/.claude/skills/backend-dev-guidelines/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: backend-dev-guidelines
+description: Comprehensive backend development guide for Node.js/Express/TypeScript microservices. Use when creating routes, controllers, services, repositories, middleware, or working with Express APIs, Prisma database access, Sentry error tracking, Zod validation, unifiedConfig, dependency injection, or async patterns. Covers layered architecture (routes → controllers → services → repositories), BaseController pattern, error handling, performance monitoring, testing strategies, and migration from legacy patterns.
+---
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎯 SKILL ACTIVATED: backend-dev-guidelines
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+# Backend Development Guidelines
+
+## Purpose
+
+Establish consistency and best practices across backend microservices (blog-api, auth-service, notifications-service) using modern Node.js/Express/TypeScript patterns.
+
+## When to Use This Skill
+
+Automatically activates when working on:
+- Creating or modifying routes, endpoints, APIs
+- Building controllers, services, repositories
+- Implementing middleware (auth, validation, error handling)
+- Database operations with Prisma
+- Error tracking with Sentry
+- Input validation with Zod
+- Configuration management
+- Backend testing and refactoring
+
+---
+
+## Quick Start
+
+### New Backend Feature Checklist
+
+- [ ] **Route**: Clean definition, delegate to controller
+- [ ] **Controller**: Extend BaseController
+- [ ] **Service**: Business logic with DI
+- [ ] **Repository**: Database access (if complex)
+- [ ] **Validation**: Zod schema
+- [ ] **Sentry**: Error tracking
+- [ ] **Tests**: Unit + integration tests
+- [ ] **Config**: Use unifiedConfig
+
+### New Microservice Checklist
+
+- [ ] Directory structure (see [architecture-overview.md](architecture-overview.md))
+- [ ] instrument.ts for Sentry
+- [ ] unifiedConfig setup
+- [ ] BaseController class
+- [ ] Middleware stack
+- [ ] Error boundary
+- [ ] Testing framework
+
+---
+
+## Architecture Overview
+
+### Layered Architecture
+
+```
+HTTP Request
+    ↓
+Routes (routing only)
+    ↓
+Controllers (request handling)
+    ↓
+Services (business logic)
+    ↓
+Repositories (data access)
+    ↓
+Database (Prisma)
+```
+
+**Key Principle:** Each layer has ONE responsibility.
+
+See [architecture-overview.md](architecture-overview.md) for complete details.
+
+---
+
+## Directory Structure
+
+```
+service/src/
+├── config/              # UnifiedConfig
+├── controllers/         # Request handlers
+├── services/            # Business logic
+├── repositories/        # Data access
+├── routes/              # Route definitions
+├── middleware/          # Express middleware
+├── types/               # TypeScript types
+├── validators/          # Zod schemas
+├── utils/               # Utilities
+├── tests/               # Tests
+├── instrument.ts        # Sentry (FIRST IMPORT)
+├── app.ts               # Express setup
+└── server.ts            # HTTP server
+```
+
+**Naming Conventions:**
+- Controllers: `PascalCase` - `UserController.ts`
+- Services: `camelCase` - `userService.ts`
+- Routes: `camelCase + Routes` - `userRoutes.ts`
+- Repositories: `PascalCase + Repository` - `UserRepository.ts`
+
+---
+
+## Core Principles (7 Key Rules)
+
+### 1. Routes Only Route, Controllers Control
+
+```typescript
+// ❌ NEVER: Business logic in routes
+router.post('/submit', async (req, res) => {
+    // 200 lines of logic
+});
+
+// ✅ ALWAYS: Delegate to controller
+router.post('/submit', (req, res) => controller.submit(req, res));
+```
+
+### 2. All Controllers Extend BaseController
+
+```typescript
+export class UserController extends BaseController {
+    async getUser(req: Request, res: Response): Promise<void> {
+        try {
+            const user = await this.userService.findById(req.params.id);
+            this.handleSuccess(res, user);
+        } catch (error) {
+            this.handleError(error, res, 'getUser');
+        }
+    }
+}
+```
+
+### 3. All Errors to Sentry
+
+```typescript
+try {
+    await operation();
+} catch (error) {
+    Sentry.captureException(error);
+    throw error;
+}
+```
+
+### 4. Use unifiedConfig, NEVER process.env
+
+```typescript
+// ❌ NEVER
+const timeout = process.env.TIMEOUT_MS;
+
+// ✅ ALWAYS
+import { config } from './config/unifiedConfig';
+const timeout = config.timeouts.default;
+```
+
+### 5. Validate All Input with Zod
+
+```typescript
+const schema = z.object({ email: z.string().email() });
+const validated = schema.parse(req.body);
+```
+
+### 6. Use Repository Pattern for Data Access
+
+```typescript
+// Service → Repository → Database
+const users = await userRepository.findActive();
+```
+
+### 7. Comprehensive Testing Required
+
+```typescript
+describe('UserService', () => {
+    it('should create user', async () => {
+        expect(user).toBeDefined();
+    });
+});
+```
+
+---
+
+## Common Imports
+
+```typescript
+// Express
+import express, { Request, Response, NextFunction, Router } from 'express';
+
+// Validation
+import { z } from 'zod';
+
+// Database
+import { PrismaClient } from '@prisma/client';
+import type { Prisma } from '@prisma/client';
+
+// Sentry
+import * as Sentry from '@sentry/node';
+
+// Config
+import { config } from './config/unifiedConfig';
+
+// Middleware
+import { SSOMiddlewareClient } from './middleware/SSOMiddleware';
+import { asyncErrorWrapper } from './middleware/errorBoundary';
+```
+
+---
+
+## Quick Reference
+
+### HTTP Status Codes
+
+| Code | Use Case |
+|------|----------|
+| 200 | Success |
+| 201 | Created |
+| 400 | Bad Request |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not Found |
+| 500 | Server Error |
+
+### Service Templates
+
+**Blog API** (✅ Mature) - Use as template for REST APIs
+**Auth Service** (✅ Mature) - Use as template for authentication patterns
+
+---
+
+## Anti-Patterns to Avoid
+
+❌ Business logic in routes
+❌ Direct process.env usage
+❌ Missing error handling
+❌ No input validation
+❌ Direct Prisma everywhere
+❌ console.log instead of Sentry
+
+---
+
+## Navigation Guide
+
+| Need to... | Read this |
+|------------|-----------|
+| Understand architecture | [architecture-overview.md](architecture-overview.md) |
+| Create routes/controllers | [routing-and-controllers.md](routing-and-controllers.md) |
+| Organize business logic | [services-and-repositories.md](services-and-repositories.md) |
+| Validate input | [validation-patterns.md](validation-patterns.md) |
+| Add error tracking | [sentry-and-monitoring.md](sentry-and-monitoring.md) |
+| Create middleware | [middleware-guide.md](middleware-guide.md) |
+| Database access | [database-patterns.md](database-patterns.md) |
+| Manage config | [configuration.md](configuration.md) |
+| Handle async/errors | [async-and-errors.md](async-and-errors.md) |
+| Write tests | [testing-guide.md](testing-guide.md) |
+| See examples | [complete-examples.md](complete-examples.md) |
+
+---
+
+## Resource Files
+
+### [architecture-overview.md](architecture-overview.md)
+Layered architecture, request lifecycle, separation of concerns
+
+### [routing-and-controllers.md](routing-and-controllers.md)
+Route definitions, BaseController, error handling, examples
+
+### [services-and-repositories.md](services-and-repositories.md)
+Service patterns, DI, repository pattern, caching
+
+### [validation-patterns.md](validation-patterns.md)
+Zod schemas, validation, DTO pattern
+
+### [sentry-and-monitoring.md](sentry-and-monitoring.md)
+Sentry init, error capture, performance monitoring
+
+### [middleware-guide.md](middleware-guide.md)
+Auth, audit, error boundaries, AsyncLocalStorage
+
+### [database-patterns.md](database-patterns.md)
+PrismaService, repositories, transactions, optimization
+
+### [configuration.md](configuration.md)
+UnifiedConfig, environment configs, secrets
+
+### [async-and-errors.md](async-and-errors.md)
+Async patterns, custom errors, asyncErrorWrapper
+
+### [testing-guide.md](testing-guide.md)
+Unit/integration tests, mocking, coverage
+
+### [complete-examples.md](complete-examples.md)
+Full examples, refactoring guide
+
+---
+
+## Related Skills
+
+- **database-verification** - Verify column names and schema consistency
+- **error-tracking** - Sentry integration patterns
+- **skill-developer** - Meta-skill for creating and managing skills
+
+---
+
+**Skill Status**: COMPLETE ✅
+**Line Count**: < 500 ✅
+**Progressive Disclosure**: 11 resource files ✅