docs: add AuthResponse struct definition and document MagicLinkSender type

[github-actions]

Two small documentation gaps surfaced during a post-push documentation audit:

Changes

1. Add handler.AuthResponse struct definition

AuthResponse is an exported type that is the primary response body for Signup, Login, RefreshToken, VerifyMagicLink, and FinishAuthentication. Previously it was only described in prose ("containing token, refresh_token...") without a Go struct block. UserDTO was already shown as a Go struct definition in the same section — AuthResponse deserves the same treatment so that:

• Frontend/client developers can see the exact JSON field names (token, refresh_token, user) and know that refresh_token is omitted (not null) when Sessions is not configured.
• Contributors writing custom handlers or tests can use the exported type directly without looking at source.

2. Document handler.MagicLinkSender type and nil Sender behaviour

The MagicLinkHandler.Sender field has an exported named type (handler.MagicLinkSender) that wasn't mentioned by name in the docs. Also, the existing error-response table already documented the 503 behaviour for a nil Sender, but there was no prose near the struct example that drew attention to this "must be set" requirement — unlike EmailVerificationHandler.SendEmail which is explicitly noted as a no-op when nil. The new sentence:

• Names the exported MagicLinkSender type for discoverability.
• Reinforces that a nil Sender is not a "test-mode no-op" (it's an error) and that the token is already stored at that point (aligning with the error table note).

Verification

Both changes are documentation only (no code changes). Accuracy was verified against:

• handler/auth.go — AuthResponse struct definition (lines 67–73)
• handler/magiclink.go — MagicLinkSender type (line 19), nil-Sender 503 path (lines 73–76)

Warning

⚠️ Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by Update Docs · ● 2.8M · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/update-docs.md@96b9d4c39aa22359c0b38265927eadb31dcf4e2a

Greptile Summary

This documentation-only PR adds a Go struct block for AuthResponse in the auth Response types section and documents the MagicLinkSender type along with the nil-Sender 503 behaviour. Both changes have been verified against the source (handler/auth.go lines 67–71, handler/magiclink.go lines 19 and 73–76) and are accurate.

Confidence Score: 5/5

Documentation-only change with no code modifications; safe to merge.

All changes are prose and code-block additions to README.md that accurately reflect the live source. No P0 or P1 findings; the nil-Sender orphaned-token concern was already captured in a previous review thread and is now addressed in the docs.

No files require special attention.

Important Files Changed

Filename	Overview
README.md	Adds AuthResponse struct block and MagicLinkSender documentation; both are accurate against the source code in handler/auth.go and handler/magiclink.go

Sequence Diagram

sequenceDiagram
    participant Client
    participant RequestMagicLink
    participant MagicLinkStore
    participant MagicLinkSender

    Client->>RequestMagicLink: POST /auth/magic-link/request {email}
    RequestMagicLink->>MagicLinkStore: CreateMagicLink(email, tokenHash, expiresAt)
    MagicLinkStore-->>RequestMagicLink: ok
    alt Sender is nil
        RequestMagicLink-->>Client: 503 Service Unavailable (token persisted, unconsumed)
    else Sender configured
        RequestMagicLink->>MagicLinkSender: func(ctx, email, token) error
        MagicLinkSender-->>RequestMagicLink: nil or error (swallowed)
        RequestMagicLink-->>Client: 200 message response
    end

    Client->>RequestMagicLink: GET /auth/magic-link/verify with query param
    RequestMagicLink-->>Client: 200 AuthResponse {token, refresh_token?, user}

Loading

_{Reviews (2): Last reviewed commit: "docs: warn that nil Sender accumulates u..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Closes documentation gaps in the handler package README by adding concrete Go type definitions and clarifying the expected configuration for magic-link delivery, improving discoverability and accuracy for client authors and contributors.

Changes:

• Added a Go AuthResponse struct definition (including JSON field names and omitempty behavior for refresh_token).
• Documented the exported handler.MagicLinkSender type and clarified that a nil Sender causes RequestMagicLink to fail with 503 after persisting the token.

Show a summary per file

File	Description
README.md	Adds AuthResponse struct block and documents MagicLinkSender/nil-Sender behavior in MagicLinkHandler docs.

Copilot's findings

Tip

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

• Files reviewed: 1/1 changed files
• Comments generated: 0