=== API CONTRACT GUARDIAN PLAN ===

Original request: Create a safe API contract plan and Cursor prompt for modifying GET /api/dashboard/metrics.

Interpreted API goal: Add a new dashboard metric to an existing endpoint while preserving the current API contract and frontend dashboard behavior.

API type: REST API

Scope: Single existing endpoint

Known endpoint details: GET /api/dashboard/metrics

Assumptions:

• The frontend dashboard consumes this endpoint.
• The endpoint requires authentication.
• The current response includes existing dashboard metrics that must remain stable.
• The endpoint may have existing tests or frontend API client types.

Missing context:

• Current response shape
• New metric name and type
• Authentication/authorization details
• Existing frontend consumer files
• Existing tests
• Error response format
• Whether generated API types exist

Consumer map: Known consumer:

• frontend dashboard

Consumers to search for:

• dashboard components
• API client functions
• generated types
• hooks or data-fetching utilities
• tests
• documentation examples
• analytics or reporting modules

Current contract map: To be confirmed by inspection:

• method: GET
• path: /api/dashboard/metrics
• authentication: likely required
• query parameters: unknown
• success response: existing metrics object
• error format: unknown
• status codes: likely 200, 401, 403, 500
• caching behavior: unknown
• frontend expectations: existing metric fields and loading/error behavior

Breaking-change risk review:

1. Removing or renaming existing metric fields — High Mitigation: preserve all existing fields and add the new metric as an additional optional field if possible.

2. Changing metric types — High Mitigation: keep numeric, string, date, and currency formats unchanged.

3. Changing status codes — Medium to high Mitigation: preserve existing status semantics.

4. Changing error response shape — Medium Mitigation: preserve current error contract and frontend error handling.

5. Changing authentication behavior — High Mitigation: do not modify auth middleware unless explicitly required.

6. Returning sensitive business data — Medium Mitigation: confirm the new metric is safe for the authenticated user role.

Contract preservation rules:

• Do not remove existing response fields.
• Do not rename existing response fields.
• Do not change existing field types.
• Do not change current status codes unless a documented bug requires it.
• Do not change error response shape.
• Do not change authentication or authorization behavior.
• Add the new metric in a backward-compatible way.
• Update frontend types only to include the new field, not to invalidate old fields.
• Add or update contract tests.

Request validation plan: If the endpoint has query parameters, preserve existing validation. Do not add required query parameters for the new metric unless versioning or migration is planned.

Response schema plan: Add the new metric as a clearly named field in the existing metrics response. Define:

• field name
• field type
• nullable behavior
• unit of measurement
• date range behavior if relevant
• default value for empty data
• whether it should be visible to all authenticated roles

Error contract plan: Preserve existing error format. Confirm behavior for:

• unauthenticated request
• unauthorized role
• invalid query parameter if applicable
• server/database failure
• empty metric data

Contract test plan:

1. Existing response fields remain present.
2. Existing response field types remain unchanged.
3. New metric appears with documented type.
4. Empty data returns a safe default or documented null behavior.
5. Unauthenticated request returns existing auth error format.
6. Unauthorized role returns existing permission error format if applicable.
7. Frontend dashboard still renders with old and new metric data.
8. Error state still renders correctly.
9. No sensitive fields are included.

Documentation plan: Update endpoint documentation with:

• new metric field
• field type
• meaning
• example response
• empty-state behavior
• auth requirements
• error examples if currently documented

Versioning or migration plan: No new version is needed if the change only adds a backward-compatible optional field. If the new metric requires changing existing fields, create a versioned response or temporary compatibility layer.

AI coding agent prompt: Modify GET /api/dashboard/metrics safely to add one new dashboard metric without breaking existing frontend consumers.

Before editing:

1. Inspect the endpoint implementation.
2. Search for all consumers of /api/dashboard/metrics, including dashboard components, API client functions, hooks, generated types, tests, and documentation.
3. Map the current response shape, status codes, error format, authentication behavior, and authorization behavior.
4. Identify the existing dashboard rendering assumptions.
5. Add or update contract tests before changing behavior when possible.

Requirements:

• Preserve all existing response fields.
• Preserve existing field names and types.
• Preserve existing status code behavior.
• Preserve existing error response shape.
• Preserve authentication and authorization behavior.
• Add the new metric in a backward-compatible way.
• Do not expose sensitive data.
• Update frontend types or API client definitions only as needed.
• Update documentation with the new metric.

Out of scope:

• renaming existing fields
• removing existing fields
• changing database schema unless explicitly required and reviewed
• changing authentication logic
• changing dashboard layout broadly
• broad endpoint refactor
• unrelated API cleanup

Testing:

• Add or update contract tests for the endpoint response shape.
• Verify existing dashboard tests still pass.
• Add a test confirming the new metric appears.
• Add tests or manual checks for empty data, unauthorized access, and error responses.
• Run relevant tests if available.

Return:

• current contract summary
• consumers found
• breaking-change risks identified
• files changed
• tests added or run
• documentation updated
• verification steps
• remaining risks

Verification checklist:

• Existing dashboard still renders.
• Existing metric fields are unchanged.
• New metric appears correctly.
• Auth behavior is unchanged.
• Error behavior is unchanged.
• Contract tests pass.
• No sensitive data is exposed.
• Documentation includes the new metric.

Risks and safety notes: Because the frontend already depends on this endpoint, response shape changes must be treated as high-risk. The safest path is to add the new metric as a backward-compatible field and protect the endpoint with contract tests.