myAi/Apis/cv-matcher-api/Controllers/JobSearchController.cs

using Api.Services.Contracts;
using CvMatcher.Models.Requests;
using CvMatcher.Models.Responses;
using Microsoft.AspNetCore.Mvc;
using Shared.Models.Responses;
using Swashbuckle.AspNetCore.Annotations;

namespace Api.Controllers;

/// <summary>
/// Internal endpoints for managing one-click job-search tokens and sessions.
/// Routes are prefixed with <c>api/cv/job-search</c>. Protected by the internal API key middleware — not reachable from the public internet.
/// </summary>
[ApiController]
[Route("api/cv/job-search")]
public sealed class JobSearchController : ControllerBase
{
    private readonly IJobTokenService _tokenService;
    private readonly ILogger<JobSearchController> _logger;

    public JobSearchController(IJobTokenService tokenService, ILogger<JobSearchController> logger)
    {
        _tokenService = tokenService;
        _logger = logger;
    }

    /// <summary>
    /// Creates a one-time job-search token linked to a CV document and email address.
    /// Called by <c>api</c> immediately after a successful CV match when an email is provided.
    /// The token is embedded in the job-search link sent to the user's email.
    /// </summary>
    /// <param name="request">The CV document ID and the recipient email address.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>
    /// 200 OK with a <see cref="CreateJobSearchTokenResponse"/> containing the generated token ID;
    /// 400 Bad Request if <c>CvDocumentId</c> or <c>Email</c> is missing;
    /// 500 Internal Server Error if token creation fails.
    /// </returns>
    [HttpPost("token")]
    [SwaggerOperation(Summary = "Create job search token", Description = "Creates a one-time token that lets the user start a background job search by clicking the link in their match email.")]
    [SwaggerResponse(StatusCodes.Status200OK, "Token created successfully", typeof(CreateJobSearchTokenResponse))]
    [SwaggerResponse(StatusCodes.Status400BadRequest, "CvDocumentId or Email missing", typeof(ErrorResponse))]
    [SwaggerResponse(StatusCodes.Status500InternalServerError, "Token creation failed", typeof(ErrorResponse))]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status400BadRequest)]
    [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status500InternalServerError)]
    public async Task<ActionResult<CreateJobSearchTokenResponse>> CreateToken(
        [FromBody] CreateJobSearchTokenRequest request,
        CancellationToken ct)
    {
        try
        {
            if (string.IsNullOrWhiteSpace(request.CvDocumentId) || string.IsNullOrWhiteSpace(request.Email))
                return BadRequest(new ErrorResponse { Error = "CvDocumentId and Email are required.", Code = "invalid_request" });

            var tokenId = await _tokenService.CreateTokenAsync(request.CvDocumentId, request.Email, request.Language, ct);
            return Ok(new CreateJobSearchTokenResponse { TokenId = tokenId });
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to create job search token.");
            return StatusCode(StatusCodes.Status500InternalServerError, new ErrorResponse { Error = "Failed to create token.", Code = "token_create_failed" });
        }
    }

    /// <summary>
    /// Validates the one-time token, marks it as used, and enqueues a <c>JobSearchSession</c> with status <c>Pending</c>.
    /// Called by <c>api</c> when the user clicks the job-search link in their match email.
    /// The <c>cv-search-job</c> worker picks up the pending session and runs the search.
    /// </summary>
    /// <param name="tokenId">The UUID token extracted from the email link.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>
    /// 200 OK with a <see cref="StartJobSearchResponse"/> whose <c>Status</c> is one of
    /// <c>Started</c>, <c>AlreadyUsed</c>, or <c>Expired</c>;
    /// 500 Internal Server Error if the session cannot be created.
    /// </returns>
    [HttpPost("token/{tokenId}/start")]
    [SwaggerOperation(Summary = "Start job search", Description = "Validates the one-time token and creates a Pending job search session for the cv-search-job worker to process.")]
    [SwaggerResponse(StatusCodes.Status200OK, "Search status returned (Started, AlreadyUsed, or Expired)", typeof(StartJobSearchResponse))]
    [SwaggerResponse(StatusCodes.Status500InternalServerError, "Session creation failed", typeof(ErrorResponse))]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ErrorResponse), StatusCodes.Status500InternalServerError)]
    public async Task<ActionResult<StartJobSearchResponse>> Start(string tokenId, CancellationToken ct)
    {
        try
        {
            var status = await _tokenService.TriggerStartAsync(tokenId, ct);
            return Ok(new StartJobSearchResponse { Status = status });
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to start job search for token {TokenId}.", tokenId);
            return StatusCode(StatusCodes.Status500InternalServerError, new ErrorResponse { Error = "Failed to start search.", Code = "start_failed" });
        }
    }
}