Fix auth token response docs

[ncoprod]

Summary

• update REST docs and OpenAPI schema to show access_token / refresh_token at the top level for POST /api/auth/login
• update /api/auth/session docs/schema to describe the returned profile object instead of a nested session
• assert the login route returns top-level token fields and no session object

Fixes #248.

Validation

• pnpm vitest run src/app/api/auth/login/route.test.ts src/app/api/openapi.json/spec.test.ts

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates the auth API’s documented/contracted responses so login returns tokens at the top level and the session endpoint returns a profile object.

Changes:

• Adjust login response shape to expose access_token / refresh_token at the top level (removing nested session in docs/spec).
• Update /api/auth/session docs/spec to describe returning user + profile.
• Update login route test expectations to match the new response shape.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
src/app/docs/api/api-docs-content.tsx	Updates rendered API docs examples for login and session endpoints.
src/app/api/auth/login/route.test.ts	Updates tests to assert tokens are returned at the top level.
public/openapi.json	Updates OpenAPI schemas/descriptions to match the new auth responses.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[greptile-apps]

Greptile Summary

This PR aligns the REST docs, OpenAPI schema, and tests with the actual login route behavior, which already returns access_token and refresh_token at the top level (not nested inside a session object), and the session endpoint which returns a profile object rather than a session object.

• public/openapi.json: Login 200-response schema now declares top-level access_token/refresh_token as required fields and marks them with security guidance; the session endpoint schema replaces session: object with profile: $ref Profile, which resolves to the existing Profile component schema.
• src/app/api/auth/login/route.test.ts: Mock session extended with refresh_token and three new assertions confirm the top-level token shape and absence of a session key.
• src/app/docs/api/api-docs-content.tsx: Human-readable docs updated to match the corrected response shapes for both endpoints.

Confidence Score: 5/5

Documentation-only sync; no runtime logic changed, all three files correctly reflect the existing route implementations.

The login route and session route already returned the documented shapes before this PR. Every change here is a doc/schema/test fix that brings the written contract in line with the running code, verified by new test assertions that pass against the unchanged implementation.

No files require special attention beyond the minor required vs optional-chaining discrepancy noted in public/openapi.json.

Important Files Changed

Filename	Overview
public/openapi.json	Updated login 200-response schema to show top-level access_token/refresh_token and the session endpoint to reference the Profile schema — both match the actual route implementations.
src/app/api/auth/login/route.test.ts	Adds refresh_token to the mock session and asserts body.access_token, body.refresh_token are present and body.session is absent, correctly pinning the documented behavior.
src/app/docs/api/api-docs-content.tsx	Human-readable API docs updated to reflect top-level tokens for login and profile object for session, consistent with the OpenAPI schema and route implementations.

Sequence Diagram

sequenceDiagram
    participant Client
    participant LoginRoute as POST /api/auth/login
    participant Supabase

    Client->>LoginRoute: "{ email, password }"
    LoginRoute->>Supabase: signInWithPassword(email, password)
    Supabase-->>LoginRoute: "{ user, session: { access_token, refresh_token } }"
    LoginRoute-->>Client: "200 { message, user, access_token, refresh_token }"
    Note over LoginRoute,Client: top-level tokens (no session wrapper)

    Client->>+LoginRoute: GET /api/auth/session (Bearer token)
    LoginRoute->>Supabase: getUser()
    Supabase-->>LoginRoute: "{ user }"
    LoginRoute->>Supabase: "profiles.select(*).eq(id, user.id)"
    Supabase-->>LoginRoute: profile
    LoginRoute-->>Client: "200 { user, profile }"
    Note over LoginRoute,Client: profile object (no session wrapper)

Loading

_{Reviews (2): Last reviewed commit: "Fix auth token response docs" | Re-trigger Greptile}

[ncoprod]

Thanks for the review pass.

I addressed the automated notes in the latest push:

• login response schema now marks access_token and refresh_token as required top-level fields
• token fields include clearer bearer/refresh-token descriptions
• /api/auth/session now has a more specific summary/operation id
• the session response references the existing Profile schema

Validation:

pnpm vitest run src/app/api/auth/login/route.test.ts src/app/api/openapi.json/spec.test.ts

Result: 14 tests passed.