/**
 * API: who watches a ticket, and watching / unwatching it (GitHub #277).
 *
 *   GET  ?ticket_id=N            the watchers, whether I watch, whether I may add others
 *   POST {action: 'watch',   ticket_id, analyst_id?}   analyst_id omitted = me
 *   POST {action: 'unwatch', ticket_id, analyst_id?}
 *   POST {action: 'watch_many', ticket_ids: [..]}      the right-click menu on a selection - me only
 */

if (!isset($_SESSION['analyst_id'])) {
    echo json_encode(['success' => false, 'error' => 'Not authenticated']);
    exit;
}
requireModuleAccessJson('tickets');

$conn = connectToDatabase();
$me = (int)$_SESSION['analyst_id'];
$canWrite = analystCanWriteModule($conn, $me, 'tickets');

try {
    if (($_SERVER['REQUEST_METHOD'] ?? 'GET') === 'GET') {
        $ticketId = (int)($_GET['ticket_id'] ?? 0);
        if (!TicketWatchers::canSee($conn, $me, $ticketId)) {
            throw new ServiceError('not_found', 'not_found', 'Ticket not found.');
        }
        $list = TicketWatchers::list($conn, $ticketId);
        echo json_encode([
            'success'   => true,
            'ready'     => TicketWatchers::ready($conn),
            'watchers'  => $list,
            'watching'  => in_array($me, array_column($list, 'analyst_id'), true),
            'can_add'   => $canWrite,
        ]);
        exit;
    }

    csrfRequireWriteMethod();

    if ($action === 'watch_many') {
        // Me on each selected ticket I can see; one that is not mine to see is skipped, not an error.
        $done = 0; $already = 0; $skipped = 0;
        foreach (array_slice(array_unique(array_map('intval', (array)($in['ticket_ids'] ?? []))), 0, 500) as $id) {
            try {
                $r = TicketWatchers::add($conn, $ctx, $id, $me, $canWrite);
                $r['added'] ? $done++ : $already++;
            } catch (ServiceError $e) {
                if ($e->kind === 'validation' && $e->errorCode === 'not_ready') throw $e;
                $skipped++;
            }
        }
        echo json_encode(['success' => true, 'added' => $done, 'already' => $already, 'skipped' => $skipped]);
        exit;
    }

    $ticketId = (int)($in['ticket_id'] ?? 0);
    $who = isset($in['analyst_id']) && (int)$in['analyst_id'] > 0 ? (int)$in['analyst_id'] : $me;
    if ($action === 'watch') {
        $r = TicketWatchers::add($conn, $ctx, $ticketId, $who, $canWrite);
    } elseif ($action === 'unwatch') {
        $r = TicketWatchers::remove($conn, $ctx, $ticketId, $who, $canWrite);
    } else {
        throw new ServiceError('validation', 'invalid_field', 'Unknown action.');
    }
    $list = TicketWatchers::list($conn, $ticketId);
    echo json_encode(['success' => true] + $r + [
        'watchers' => $list,
        'watching' => in_array($me, array_column($list, 'analyst_id'), true),
    ]);
} catch (ServiceError $e) {
    http_response_code($e->kind === 'not_found' ? 404 : ($e->kind === 'forbidden' ? 403 : 400));
    echo json_encode(['success' => false, 'error' => $e->getMessage(), 'code' => $e->errorCode]);
}

        <?php /* GH #277: Watch / Stop watching - the label is set when the menu opens
                 (populateContextWatchItem in assets/js/ticket-watchers.js). */ ?>
        <button class="ticket-context-menu-item" type="button" id="ctxWatchItem" data-mode="watch" onclick="watchFromContext()">
            <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"/><circle cx="12" cy="12" r="3"/></svg>
            <span><?php echo htmlspecialchars(t('tickets.watch.watch')); ?></span>
        </button>

    ['GET',    '#^/tickets/(\d+)/watchers$#',              ['ticket_watchers', 'read'],       'apiTicketWatchersList'],
    ['POST',   '#^/tickets/(\d+)/watchers$#',              ['ticket_watchers', 'create'],     'apiTicketWatchersAdd'],
    ['DELETE', '#^/tickets/(\d+)/watchers/(\d+)$#',        ['ticket_watchers', 'delete'],     'apiTicketWatchersRemove'],

// api/v1/lib/permissions.php
        // GH #277. Watchers are told about a ticket as if it were theirs, through their own settings.
        'ticket_watchers' => [
            'label'   => 'Ticket watchers',
            'actions' => [
                'read'   => 'List who is watching a ticket',
                'create' => 'Add an analyst (the key\'s own, or another who can see the ticket) as a watcher',
                'delete' => 'Take an analyst off a ticket\'s watchers',
            ],
        ],

// api/v1/lib/modules.php - API_V1_RESOURCE_MODULES
    'ticket_watchers' => ['tickets'],   // GH #277

/** One watcher as the API returns it. */
function apiTicketWatcherShape(array $w): array {
    return [
        'analyst'    => ['id' => $w['analyst_id'], 'name' => $w['name']],
        'added_by'   => $w['added_by'] !== null ? ['id' => $w['added_by'], 'name' => $w['added_by_name']] : null,
        'added_at'   => apiIsoDate($w['added_at']),
    ];
}

/** GET /tickets/{id}/watchers */
function apiTicketWatchersList(PDO $conn, array $apiKey, array $params, array $body): void {
    apiLoadTicket($conn, $apiKey, (int)$params[0]);
    require_once __DIR__ . '/../../../includes/services/ticket_watchers.php';
    apiRespond(array_map('apiTicketWatcherShape', TicketWatchers::list($conn, (int)$params[0])));
}

/**
 * POST /tickets/{id}/watchers - { "analyst_id": 7 }; omitted = the key's own analyst.
 * 201 when added, 200 when they already watched. The analyst must be able to see the ticket.
 */
function apiTicketWatchersAdd(PDO $conn, array $apiKey, array $params, array $body): void {
    apiLoadTicket($conn, $apiKey, (int)$params[0]);
    require_once __DIR__ . '/../../../includes/services/ticket_watchers.php';
    $who = isset($body['analyst_id']) ? (int)$body['analyst_id'] : (int)$apiKey['analyst_id'];
    try {
        // The key's ticket_watchers.create permission is the write access here.
        $r = TicketWatchers::add($conn, ActorContext::fromApiKey($apiKey), (int)$params[0], $who, true);
    } catch (ServiceError $e) { apiFailFromService($e); }
    $mine = array_values(array_filter(TicketWatchers::list($conn, (int)$params[0]), fn($w) => $w['analyst_id'] === $who));
    apiRespond($mine ? apiTicketWatcherShape($mine[0]) : null, $r['added'] ? 201 : 200);
}

/** DELETE /tickets/{id}/watchers/{analyst_id} - 404 when they were not watching. */
function apiTicketWatchersRemove(PDO $conn, array $apiKey, array $params, array $body): void {
    apiLoadTicket($conn, $apiKey, (int)$params[0]);
    require_once __DIR__ . '/../../../includes/services/ticket_watchers.php';
    try {
        $r = TicketWatchers::remove($conn, ActorContext::fromApiKey($apiKey), (int)$params[0], (int)$params[1], true);
    } catch (ServiceError $e) { apiFailFromService($e); }
    if (!$r['removed']) apiError(404, 'not_found', 'That analyst is not watching this ticket.');
    apiRespond(['ticket_id' => (int)$params[0], 'analyst_id' => (int)$params[1], 'removed' => true]);
}

$fire = function (string $event, int $actor) use ($ticketId, $conn) {
    $_SESSION = ['analyst_id' => $actor, 'analyst_name' => 'ZZ actor'];
    $t = $conn->query("SELECT id, subject, assigned_analyst_id, owner_id FROM tickets WHERE id = $ticketId")->fetch(PDO::FETCH_ASSOC);
    $t['id'] = (int)$t['id']; $t['assigned_analyst_id'] = (int)$t['assigned_analyst_id'];
    notificationsHandleEvent($event, ['ticket' => $t, 'analyst_id' => $t['assigned_analyst_id']]);
};

    echo "\nA watcher who is deactivated\n";
    require_once 'includes/services/analysts.php';
    require_once 'includes/analyst_lifecycle.php';
    TicketWatchers::add($conn, $wCtx, $ticketId, $watcher, false);
    $watching = fn(int $id) => (int)$conn->query("SELECT COUNT(*) FROM ticket_watchers WHERE ticket_id = $ticketId AND analyst_id = $id")->fetchColumn();
    $listed = fn(int $id) => in_array($id, array_column(TicketWatchers::list($conn, $ticketId), 'analyst_id'), true);
    $setInactive(null);
    check('never saved = stop', TicketWatchers::inactivePolicy($conn) === 'stop');
    AnalystsService::update($conn, $oCtx, $watcher, ['is_active' => false]);
    check('stop: the watch is kept', $watching($watcher) === 1);
    check('...but not shown on the ticket', !$listed($watcher));