Auto-commit 2026-05-02 09:37

plans/FRE-4524-spamshield-routes.md

@@ -0,0 +1,134 @@
+# FRE-4524 - Create spamshield.routes.ts with spam classification endpoints
+
+## Parent Issue
+FRE-4507 - Implement Redis rate limiting middleware
+
+## Goal ID
+2c5a8678-b505-4e9c-8ec4-c41faa9626ff
+
+## Description
+Create a new `spamshield.routes.ts` file that exposes spam classification API endpoints with rate limit middleware integration.
+
+### Required Endpoints
+
+#### POST /api/v1/spam/classify/sms
+Classify an SMS message as spam or not spam.
+
+**Request Body:**
+```typescript
+{
+  phoneNumber: string;      // E.164 format
+  message: string;
+  userId: string;
+  tier: 'BASIC' | 'PLUS' | 'PREMIUM';
+}
+```
+
+**Response:**
+```typescript
+{
+  isSpam: boolean;
+  score: number;
+  features: string[];
+  rateLimit: {
+    remaining: number;
+    resetAt: Date;
+    limit: number;
+  };
+}
+```
+
+**Rate Limit:** Applied via spam-rate-limit.middleware.ts
+
+#### POST /api/v1/spam/classify/call
+Classify a call based on metadata and context.
+
+**Request Body:**
+```typescript
+{
+  phoneNumber: string;      // E.164 format
+  callMetadata: {
+    duration?: number;
+    timeOfDay?: string;
+    frequency?: number;
+  };
+  userId: string;
+  tier: 'BASIC' | 'PLUS' | 'PREMIUM';
+}
+```
+
+**Response:**
+```typescript
+{
+  decision: 'BLOCK' | 'FLAG' | 'ALLOW';
+  confidence: number;
+  reasons: string[];
+  rateLimit: {
+    remaining: number;
+    resetAt: Date;
+    limit: number;
+  };
+}
+```
+
+**Rate Limit:** Applied via spam-rate-limit.middleware.ts
+
+#### GET /api/v1/spam/rate-limit/status
+Get current rate limit status for a user.
+
+**Query Parameters:**
+- `userId`: string (required)
+- `tier`: 'BASIC' | 'PLUS' | 'PREMIUM' (required)
+
+**Response:**
+```typescript
+{
+  userId: string;
+  tier: string;
+  currentLimits: {
+    perMinute: {
+      used: number;
+      limit: number;
+      remaining: number;
+      resetAt: Date;
+    };
+    perDay: {
+      used: number;
+      limit: number;
+      remaining: number;
+      resetAt: Date;
+    };
+  };
+}
+```
+
+## Acceptance Criteria
+- [ ] Create `services/spamshield/src/routes/spamshield.routes.ts`
+- [ ] Implement POST /api/v1/spam/classify/sms endpoint
+- [ ] Implement POST /api/v1/spam/classify/call endpoint
+- [ ] Implement GET /api/v1/spam/rate-limit/status endpoint
+- [ ] Integrate spam-rate-limit.middleware.ts for classification endpoints
+- [ ] Return rate limit metadata in responses
+- [ ] Handle 429 responses when limits exceeded
+- [ ] Proper TypeScript typing for request/response objects
+- [ ] Export route registrar function
+
+## File to Create
+`services/spamshield/src/routes/spamshield.routes.ts`
+
+## Dependencies
+- FRE-4522 (spamshield.config.ts with rate limit structure)
+- FRE-4523 (spam-rate-limit.middleware.ts)
+- `@shieldai/types` (for type definitions)
+
+## Priority
+MEDIUM (Depends on middleware implementation)
+
+## Status
+todo
+
+## Assigned To
+d20f6f1c-1f24-4405-a122-2f93e0d6c94a (Founding Engineer)
+
+## Notes
+Routes should follow the existing pattern in `packages/api/src/routes/` for consistency. The spamshield service routes will be registered in the API gateway.