skills/plugins/library-navigator/skills/api-stack/api-middleware/sp-api-middleware/SKILL.md

name, description

name	description
sp-api-middleware	Shared contracts for the Suaveplan API middleware tier. Exports ApiMiddlewareError base class and API_MIDDLEWARE_CODES registry (RATE_LIMITED, UNAUTHENTICATED, FORBIDDEN, PAYLOAD_TOO_LARGE, AUDIT_SINK_FAILED) with default HTTP status mapping. Concrete middleware factories live in their own packages (api-middleware-rate-limit, rbac, cors, audit, body-limit, rules).

@suaveplan/api-middleware

Purpose

Shared contracts for the Suaveplan API middleware tier. Exports the stable ApiMiddlewareError base class and API_MIDDLEWARE_CODES registry used across all api-middleware-* packages.

This is a contract-only package — concrete middleware factories (rateLimitMiddleware, rbacMiddleware, corsMiddleware, auditMiddleware, bodyLimitMiddleware, rulesMiddleware) live in their own named packages. The redesigned pipeline order is tenant → auth → rate-limit → rbac → audit → handler; this package supplies the shared error vocabulary and status mappings that every middleware in that pipeline references.

Architecture

Component	Source	Role
API_MIDDLEWARE_CODES	src/error-codes/error-codes.ts	5-code API_MW.* registry
ApiMiddlewareError	src/error-codes/error-codes.ts	Typed error class with HTTP status
DEFAULT_STATUS_BY_CODE	src/error-codes/error-codes.ts	Default HTTP status map (429, 401, 403, 413, 500)

File Structure

src/
  index.ts              # Exports API_MIDDLEWARE_CODES, ApiMiddlewareError, DEFAULT_STATUS_BY_CODE
  error-codes/
    error-codes.ts      # Registry + error class + status map
    error-codes.md

Entry Points

Import	Exports
@suaveplan/api-middleware	API_MIDDLEWARE_CODES, ApiMiddlewareError, ApiMiddlewareCode, ApiMiddlewareErrorOptions, DEFAULT_STATUS_BY_CODE

Patterns

Throw a middleware error

import {
    API_MIDDLEWARE_CODES,
    ApiMiddlewareError,
} from "@suaveplan/api-middleware";

throw new ApiMiddlewareError(
    API_MIDDLEWARE_CODES.RATE_LIMITED,
    "too many requests"
);
// status defaults to 429 via DEFAULT_STATUS_BY_CODE

Branch on code

import { API_MIDDLEWARE_CODES } from "@suaveplan/api-middleware";

if (err.code === API_MIDDLEWARE_CODES.UNAUTHENTICATED) {
    // 401
} else if (err.code === API_MIDDLEWARE_CODES.FORBIDDEN) {
    // 403
}

Constraints

• Contract-only — no middleware factories here; they live in named child packages.
• Stable namespace — API_MW.* codes never collide with plugin-level namespaces like AUDIT_PLUGIN.* or CORS_PLUGIN.*.
• Default status mapping — every code maps to a default HTTP status consumed by @suaveplan/api-core problem+json serialiser.
• AUDIT_SINK_FAILED never thrown to client — surfaced only on the audit sink-failure counter so a broken sink can never break a request.
• Dependencies: @suaveplan/error, @suaveplan/types, tslib.

Error Codes

Code	Default Status	Usage
API_MW.RATE_LIMITED	429	Thrown by rate-limit middleware
API_MW.UNAUTHENTICATED	401	Thrown by RBAC middleware
API_MW.FORBIDDEN	403	Thrown by RBAC middleware
API_MW.PAYLOAD_TOO_LARGE	413	Thrown by body-limit middleware
API_MW.AUDIT_SINK_FAILED	500	Counted only, never thrown to client

Checklist

• Read src/error-codes/error-codes.ts before adding new codes
• Preserve contract-only boundary — never add middleware factories to this package
• Update DEFAULT_STATUS_BY_CODE when adding a new code