ShieldAI/plans/FRE-4524-spamshield-routes.md

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:

{
  phoneNumber: string;      // E.164 format
  message: string;
  userId: string;
  tier: 'BASIC' | 'PLUS' | 'PREMIUM';
}

Response:

{
  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:

{
  phoneNumber: string;      // E.164 format
  callMetadata: {
    duration?: number;
    timeOfDay?: string;
    frequency?: number;
  };
  userId: string;
  tier: 'BASIC' | 'PLUS' | 'PREMIUM';
}

Response:

{
  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:

{
  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.