Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

46.2 KB
Raw Blame
<?php

declare(strict_types=1);

namespace OpenWA\Tests;

use OpenWA\Client;
use OpenWA\Exceptions\OpenWANotFoundException;
use PHPUnit\Framework\TestCase;

class ResourcesTest extends TestCase
{
    // ── Sessions ──────────────────────────────────────────────────────

    public function testSessionLifecyclePaths(): void
    {
        $backend = new MockBackend();
        // Queue responses in CALL order: list, get, create, start, stop, logout, forceKill, delete.
        $backend->on(200, []);
        $backend->on(200, ['id' => 's1', 'name' => 'n', 'status' => 'ready']);
        $backend->on(201, ['id' => 's1', 'name' => 'n', 'status' => 'created']);
        $backend->on(200, ['id' => 's1', 'status' => 'initializing']);
        $backend->on(200, ['id' => 's1', 'status' => 'disconnected']);
        $backend->on(200, ['id' => 's1', 'status' => 'disconnected']);
        $backend->on(200, ['id' => 's1', 'status' => 'disconnected']);
        $backend->on(204);
        $client = $backend->makeClient();
        $client->sessions->list();
        $this->assertSame('/api/sessions', $backend->calls()[0]['path']);
        $client->sessions->get('s1');
        $this->assertRequest($backend, 'GET', '/api/sessions/s1');
        $client->sessions->create(['name' => 'n']);
        $this->assertSame(['name' => 'n'], $backend->lastCall()['body']);
        $client->sessions->start('s1');
        $this->assertStringContainsString('/sessions/s1/start', $backend->lastCall()['path']);
        $client->sessions->stop('s1');
        $this->assertRequest($backend, 'POST', '/api/sessions/s1/stop');
        $client->sessions->logout('s1');
        $this->assertStringContainsString('/sessions/s1/logout', $backend->lastCall()['path']);
        $client->sessions->forceKill('s1');
        $this->assertStringContainsString('/sessions/s1/force-kill', $backend->lastCall()['path']);
        $client->sessions->delete('s1');
        $this->assertSame('DELETE', $backend->lastCall()['method']);
    }

    public function testSessionListSendsName(): void
    {
        $backend = new MockBackend();
        $backend->on(200, []);
        $client = $backend->makeClient();
        $client->sessions->list(['name' => 'my-bot']);
        $this->assertStringContainsString('name=my-bot', $backend->lastCall()['url']);
    }

    public function testQrPairingStats(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['qrCode' => 'data:image/png;base64,xxx', 'status' => 'qr_ready']);
        $backend->on(200, ['pairingCode' => 'ABCD1234', 'status' => 'qr_ready']);
        $backend->on(200, ['total' => 1, 'active' => 1, 'ready' => 1, 'disconnected' => 0, 'byStatus' => ['ready' => 1]]);
        $client = $backend->makeClient();
        $client->sessions->getQrCode('s1');
        $this->assertStringContainsString('/sessions/s1/qr', $backend->calls()[0]['url']);
        $client->sessions->requestPairingCode('s1', ['phoneNumber' => '628123456789']);
        $this->assertSame(['phoneNumber' => '628123456789'], $backend->lastCall()['body']);
        $client->sessions->stats();
        $this->assertStringContainsString('/sessions/stats/overview', $backend->lastCall()['url']);
    }

    public function testSetOnlinePresence(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->sessions->setOnlinePresence('s1', ['available' => false]);
        // The account's own presence: no chat id in the path and no /subscribe suffix.
        $this->assertSame('PUT', $backend->lastCall()['method']);
        $this->assertStringEndsWith('/sessions/s1/presence', $backend->lastCall()['url']);
        $this->assertSame(['available' => false], $backend->lastCall()['body']);
    }

    // ── Groups ────────────────────────────────────────────────────────

    public function testGroupListGetCreate(): void
    {
        $backend = new MockBackend();
        $backend->on(200, []);
        $backend->on(200, ['id' => '[email protected]', 'subject' => 'G', 'participants' => []]);
        $backend->on(201, ['id' => '[email protected]', 'subject' => 'G', 'participants' => []]);
        $client = $backend->makeClient();
        $client->groups->list('s');
        $this->assertRequest($backend, 'GET', '/api/sessions/s/groups');
        $client->groups->get('s', '[email protected]');
        $this->assertStringContainsString('/groups/[email protected]', $backend->calls()[1]['url']);
        $client->groups->create('s', ['name' => 'G', 'participants' => ['[email protected]']]);
        $this->assertSame(['name' => 'G', 'participants' => ['[email protected]']], $backend->lastCall()['body']);
    }

    public function testGroupParticipantOps(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['success' => true]);
        $backend->on(200, ['success' => true]);
        $backend->on(200, ['success' => true]);
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->groups->addParticipants('s', 'g', ['[email protected]', '[email protected]']);
        $this->assertSame(['participants' => ['[email protected]', '[email protected]']], $backend->calls()[0]['body']);
        $this->assertSame('POST', $backend->calls()[0]['method']);
        $client->groups->removeParticipants('s', 'g', ['[email protected]']);
        $this->assertSame('DELETE', $backend->calls()[1]['method']);
        $client->groups->promoteParticipants('s', 'g', ['[email protected]']);
        $this->assertStringContainsString('/promote', $backend->calls()[2]['url']);
        $client->groups->demoteParticipants('s', 'g', ['[email protected]']);
        $this->assertStringContainsString('/demote', $backend->calls()[3]['url']);
    }

    public function testGroupSubjectDescriptionInvite(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['success' => true]);
        $backend->on(200, ['success' => true]);
        $backend->on(200, ['success' => true]);
        $backend->on(200, ['inviteCode' => 'c', 'inviteLink' => 'l']);
        $backend->on(200, ['inviteCode' => 'c2', 'inviteLink' => 'l2']);
        $client = $backend->makeClient();
        $client->groups->setSubject('s', 'g', 'New');
        $this->assertSame(['subject' => 'New'], $backend->calls()[0]['body']);
        $this->assertSame('PUT', $backend->calls()[0]['method']);
        $client->groups->setDescription('s', 'g', 'desc');
        $this->assertSame(['description' => 'desc'], $backend->calls()[1]['body']);
        $client->groups->leave('s', 'g');
        $this->assertRequest($backend, 'POST', '/api/sessions/s/groups/g/leave');
        $client->groups->inviteCode('s', 'g');
        $this->assertRequest($backend, 'GET', '/api/sessions/s/groups/g/invite-code');
        $client->groups->revokeInviteCode('s', 'g');
        $this->assertStringContainsString('/revoke', $backend->calls()[4]['url']);
    }

    public function testGroupSetMemberLabel(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->groups->setMemberLabel('s', '[email protected]', 'Site A');
        $this->assertRequest($backend, 'PUT', '/api/sessions/s/groups/[email protected]/member-label');
        $this->assertSame(['label' => 'Site A'], $backend->lastCall()['body']);
    }

    public function testGroupJoinAndSettings(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['success' => true, 'groupId' => '[email protected]']);
        $backend->on(200, ['announce' => true, 'locked' => false]);
        $backend->on(200, ['success' => true, 'message' => 'Group settings updated']);
        $client = $backend->makeClient();
        $joined = $client->groups->joinGroup('s', 'AbCdEf123');
        $this->assertSame('POST', $backend->calls()[0]['method']);
        $this->assertSame('/api/sessions/s/groups/join', $backend->calls()[0]['path']);
        $this->assertSame(['inviteCode' => 'AbCdEf123'], $backend->calls()[0]['body']);
        $this->assertSame('[email protected]', $joined['groupId']);
        $settings = $client->groups->getGroupSettings('s', '[email protected]');
        $this->assertSame('/api/sessions/s/groups/[email protected]/settings', $backend->calls()[1]['path']);
        $this->assertTrue($settings['announce']);
        $client->groups->updateGroupSettings('s', '[email protected]', ['announce' => true, 'ephemeralSeconds' => 604800]);
        $this->assertSame('PUT', $backend->calls()[2]['method']);
        $this->assertSame(['announce' => true, 'ephemeralSeconds' => 604800], $backend->calls()[2]['body']);
    }

    // ── Contacts ──────────────────────────────────────────────────────

    public function testContactPaths(): void
    {
        $backend = new MockBackend();
        $backend->on(200, []);
        $backend->on(200, ['id' => '[email protected]']);
        $backend->on(200, ['number' => '628123', 'exists' => true, 'whatsappId' => '[email protected]']);
        $backend->on(200, ['url' => 'http://p']);
        $backend->on(200, ['contactId' => 'x@lid', 'phone' => '628123']);
        $client = $backend->makeClient();
        $client->contacts->list('s', ['limit' => 10]);
        $this->assertStringContainsString('limit=10', $backend->calls()[0]['url']);
        $client->contacts->get('s', '[email protected]');
        $this->assertRequest($backend, 'GET', '/api/sessions/s/contacts/[email protected]');
        $client->contacts->check('s', '628123');
        $this->assertStringContainsString('/check/628123', $backend->calls()[2]['url']);
        $client->contacts->profilePicture('s', '[email protected]');
        $this->assertRequest($backend, 'GET', '/api/sessions/s/contacts/[email protected]/profile-picture');
        $client->contacts->phone('s', 'x@lid');
        $this->assertRequest($backend, 'GET', '/api/sessions/s/contacts/x@lid/phone');
    }

    public function testBlockUnblock(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['success' => true]);
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->contacts->block('s', '[email protected]');
        $this->assertSame('POST', $backend->calls()[0]['method']);
        $client->contacts->unblock('s', '[email protected]');
        $this->assertSame('DELETE', $backend->calls()[1]['method']);
    }

    public function testListBlockedGetsSessionWideRoute(): void
    {
        $backend = (new MockBackend())->on(200, ['[email protected]', '[email protected]']);
        $client = $backend->makeClient();
        $res = $client->contacts->listBlocked('s');
        $call = $backend->lastCall();
        $this->assertSame('GET', $call['method']);
        // Session-wide: no contact id in the path, and not the /contacts list route.
        $this->assertSame('/api/sessions/s/contacts/blocked', $call['path']);
        $this->assertNull($call['body']);
        $this->assertSame(['[email protected]', '[email protected]'], $res);
    }

    public function testProfilePicturesBatchResolvesIdsQuery(): void
    {
        $backend = (new MockBackend())->on(200, ['pictures' => ['[email protected]' => 'http://p/a', '[email protected]' => null]]);
        $client = $backend->makeClient();
        $res = $client->contacts->profilePictures('s', ['[email protected]', '[email protected]']);
        $call = $backend->lastCall();
        $this->assertSame('GET', $call['method']);
        $this->assertSame('/api/sessions/s/contacts/profile-pictures', $call['path']);
        $this->assertSame('ids=a%40c.us%2Cb%40c.us', $call['query']);
        $this->assertSame(['[email protected]' => 'http://p/a', '[email protected]' => null], $res['pictures']);
    }

    // ── Webhooks ──────────────────────────────────────────────────────

    public function testWebhookCrudTest(): void
    {
        $wh = ['id' => 'w1', 'sessionId' => 's', 'url' => 'u', 'events' => ['*'], 'active' => true, 'createdAt' => '', 'updatedAt' => ''];
        $backend = new MockBackend();
        $backend->on(200, [$wh]);
        $backend->on(200, $wh);
        $backend->on(201, $wh);
        $backend->on(200, array_merge($wh, ['active' => false]));
        $backend->on(204);
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->webhooks->list('s');
        $this->assertRequest($backend, 'GET', '/api/sessions/s/webhooks');
        $client->webhooks->get('s', 'w1');
        $this->assertRequest($backend, 'GET', '/api/sessions/s/webhooks/w1');
        $client->webhooks->create('s', ['url' => 'u', 'events' => ['*']]);
        $this->assertSame(['url' => 'u', 'events' => ['*']], $backend->calls()[2]['body']);
        $client->webhooks->update('s', 'w1', ['active' => false]);
        $this->assertSame('PUT', $backend->calls()[3]['method']);
        $client->webhooks->delete('s', 'w1');
        $this->assertRequest($backend, 'DELETE', '/api/sessions/s/webhooks/w1');
        $client->webhooks->test('s', 'w1');
        $this->assertStringContainsString('/webhooks/w1/test', $backend->calls()[5]['url']);
    }

    public function testEmptyMapFieldsEncodeAsJsonObjectNotJsonList(): void
    {
        // headers (webhook create/update) and vars (send-template) are map-typed on the wire; an
        // empty PHP array would serialize as a JSON list [] and the gateway's object validation
        // rejects it. The SDK must cast the empty map so it encodes as {}.
        $backend = (new MockBackend())->on(201, ['id' => 'w1']);
        $client = $backend->makeClient();

        $client->webhooks->create('s', ['url' => 'u', 'events' => ['*'], 'headers' => []]);
        $this->assertSame('{"url":"u","events":["*"],"headers":{}}', $backend->rawBody(0));

        $backend->on(200, ['id' => 'w1']);
        $client->webhooks->update('s', 'w1', ['active' => true, 'headers' => []]);
        $this->assertSame('{"active":true,"headers":{}}', $backend->rawBody(1));

        $backend->on(200, ['id' => 'm1']);
        $client->messages->sendTemplate('s', ['chatId' => 'c', 'templateName' => 't', 'vars' => []]);
        $this->assertSame('{"chatId":"c","templateName":"t","vars":{}}', $backend->rawBody(2));

        $backend->on(201, ['id' => 's1']);
        $client->sessions->create(['name' => 'n', 'config' => []]);
        $this->assertSame('{"name":"n","config":{}}', $backend->rawBody(3));
    }

    /** @dataProvider objectMaps */
    public function testMapFieldsStayObjectsForEveryArrayKeyShape(array $map): void
    {
        $backend = new MockBackend();
        foreach (range(1, 5) as $ignored) {
            $backend->on(200, []);
        }
        $client = $backend->makeClient();
        $template = ['chatId' => 'c', 'templateName' => 't', 'vars' => $map];
        $bulk = ['messages' => [['chatId' => 'c', 'type' => 'text', 'content' => ['text' => '{{0}}'], 'variables' => $map]], 'options' => []];
        $webhook = ['url' => 'https://receiver.example/hook', 'events' => ['message.received'], 'headers' => $map];
        $session = ['name' => 'fixture-session', 'config' => $map];
        $original = serialize([$template, $bulk, $webhook, $session]);

        $client->messages->sendTemplate('s', $template, 'template-key');
        $client->messages->sendBulk('s', $bulk);
        $client->webhooks->create('s', $webhook);
        $client->webhooks->update('s', 'w', ['headers' => $map]);
        $client->sessions->create($session);

        $bodies = array_map(fn ($index) => json_decode($backend->rawBody($index), false, 512, JSON_THROW_ON_ERROR), range(0, 4));
        foreach ([$bodies[0]->vars, $bodies[1]->messages[0]->variables, $bodies[2]->headers, $bodies[3]->headers, $bodies[4]->config] as $value) {
            $this->assertInstanceOf(\stdClass::class, $value);
            $this->assertSame($map, (array) $value);
        }
        $this->assertInstanceOf(\stdClass::class, $bodies[1]->options);
        $this->assertSame([], (array) $bodies[1]->options);
        $this->assertIsArray($bodies[1]->messages);
        $this->assertSame($original, serialize([$template, $bulk, $webhook, $session]));
        $this->assertSame('template-key', $backend->callAt(0)['headers']['idempotency-key']);
        $this->assertArrayNotHasKey('idempotency-key', $backend->callAt(1)['headers']);
    }

    public static function objectMaps(): array
    {
        return [
            'numeric zero' => [[0 => 'one']],
            'contiguous numeric keys' => [[0 => 'one', 1 => 'two']],
            'sparse numeric keys' => [[1 => 'one']],
            'named keys' => [['custom' => 'value']],
            'empty map' => [[]],
        ];
    }

    /** @dataProvider referencedMaps */
    public function testMapNormalizationPreservesCallerReferences(string $kind): void
    {
        $map = $kind === 'bulk-options' ? ['delayBetweenMessages' => 3000] : ['custom' => 'Alice'];
        $item = ['chatId' => 'c', 'type' => 'text', 'content' => ['text' => '{{custom}}'], 'variables' => $map];
        $items = [$item];
        $body = match ($kind) {
            'template' => ['chatId' => 'c', 'templateName' => 't', 'vars' => &$map],
            'bulk-variable' => ['messages' => [['chatId' => 'c', 'type' => 'text', 'content' => ['text' => '{{custom}}'], 'variables' => &$map]]],
            'bulk-item' => ['messages' => [&$item]],
            'bulk-messages' => ['messages' => &$items],
            'bulk-options' => ['messages' => [$item], 'options' => &$map],
            'webhook-create', 'webhook-update' => ['headers' => &$map],
            'session' => ['name' => 'fixture-session', 'config' => &$map],
        };
        $before = serialize([$body, $map, $item, $items]);
        $backend = (new MockBackend())->on(200, []);
        $client = $backend->makeClient();

        match ($kind) {
            'template' => $client->messages->sendTemplate('s', $body),
            'bulk-variable', 'bulk-item', 'bulk-messages', 'bulk-options' => $client->messages->sendBulk('s', $body),
            'webhook-create' => $client->webhooks->create('s', $body),
            'webhook-update' => $client->webhooks->update('s', 'w', $body),
            'session' => $client->sessions->create($body),
        };

        $this->assertSame($before, serialize([$body, $map, $item, $items]));
        $sent = json_decode($backend->rawBody(0), false, 512, JSON_THROW_ON_ERROR);
        $value = match ($kind) {
            'template' => $sent->vars,
            'bulk-variable', 'bulk-item', 'bulk-messages' => $sent->messages[0]->variables,
            'bulk-options' => $sent->options,
            'webhook-create', 'webhook-update' => $sent->headers,
            'session' => $sent->config,
        };
        $this->assertInstanceOf(\stdClass::class, $value);
        $this->assertSame($map, (array) $value);
    }

    public static function referencedMaps(): array
    {
        return [
            'template variables' => ['template'],
            'bulk variables' => ['bulk-variable'],
            'bulk item' => ['bulk-item'],
            'bulk messages' => ['bulk-messages'],
            'bulk options' => ['bulk-options'],
            'webhook create' => ['webhook-create'],
            'webhook update' => ['webhook-update'],
            'session config' => ['session'],
        ];
    }

    public function testMapNormalizationPreservesNullOmissionAndProtocolLists(): void
    {
        $backend = new MockBackend();
        foreach (range(1, 5) as $ignored) {
            $backend->on(200, []);
        }
        $client = $backend->makeClient();
        $client->messages->sendTemplate('s', ['chatId' => 'c', 'templateName' => 't', 'vars' => null]);
        $client->messages->sendTemplate('s', ['chatId' => 'c', 'templateName' => 't']);
        $client->messages->sendPoll('s', ['chatId' => 'c', 'name' => 'Q', 'options' => ['A', 'B'], 'mentions' => []]);
        $client->webhooks->create('s', ['url' => 'https://receiver.example/hook', 'events' => ['message.received'], 'headers' => null, 'filters' => ['conditions' => []]]);
        $client->request('POST', '/api/anything', [], ['first', 'second']);

        $bodies = array_map(fn ($index) => json_decode($backend->rawBody($index), false, 512, JSON_THROW_ON_ERROR), range(0, 4));
        $this->assertTrue(property_exists($bodies[0], 'vars'));
        $this->assertNull($bodies[0]->vars);
        $this->assertFalse(property_exists($bodies[1], 'vars'));
        $this->assertSame(['A', 'B'], $bodies[2]->options);
        $this->assertSame([], $bodies[2]->mentions);
        $this->assertNull($bodies[3]->headers);
        $this->assertSame(['message.received'], $bodies[3]->events);
        $this->assertSame([], $bodies[3]->filters->conditions);
        $this->assertSame(['first', 'second'], $bodies[4]);
    }

    public function testBulkItemsEncodeEmptyVariablesAsJsonObject(): void
    {
        $backend = (new MockBackend())->on(200, ['id' => 'b1']);
        $client = $backend->makeClient();

        $client->messages->sendBulk('s', ['messages' => [
            ['chatId' => 'c1', 'type' => 'template', 'templateName' => 't', 'variables' => []],
            ['chatId' => 'c2', 'type' => 'template', 'templateName' => 't', 'variables' => ['x' => 'y']],
        ]]);
        $this->assertSame(
            '{"messages":[{"chatId":"c1","type":"template","templateName":"t","variables":{}},{"chatId":"c2","type":"template","templateName":"t","variables":{"x":"y"}}]}',
            $backend->rawBody(0)
        );
    }

    public function testWebhookCreateForwardsPolymorphicFilterValuesVerbatim(): void
    {
        $backend = (new MockBackend())->on(201, ['id' => 'w1']);
        $client = $backend->makeClient();
        // The filter value is polymorphic on the wire: string (text fields),
        // string list (id/enum fields), bool (boolean fields) + caseSensitive.
        $filters = [
            'conditions' => [
                ['field' => 'sender', 'operator' => 'is', 'value' => ['[email protected]']],
                ['field' => 'body', 'operator' => 'contains', 'value' => 'invoice', 'caseSensitive' => true],
                ['field' => 'isGroup', 'operator' => 'is', 'value' => false],
            ],
        ];
        $client->webhooks->create('s', ['url' => 'u', 'events' => ['message.received'], 'filters' => $filters]);
        $this->assertSame(
            ['url' => 'u', 'events' => ['message.received'], 'filters' => $filters],
            $backend->lastCall()['body']
        );
    }

    // ── Chats & Health ────────────────────────────────────────────────

    public function testChatsPreserveOptionalLastMessageType(): void
    {
        $backend = new MockBackend();
        $backend->on(200, [['id' => '[email protected]', 'lastMessageType' => 'image'], ['id' => '[email protected]']]);
        $chats = $backend->makeClient()->chats->list('s');
        $this->assertSame('image', $chats[0]['lastMessageType']);
        $this->assertArrayNotHasKey('lastMessageType', $chats[1]);
    }

    public function testChats(): void
    {
        $backend = new MockBackend();
        $backend->on(200, []);
        $backend->on(200, ['success' => true]);
        $backend->on(200, ['success' => true]);
        $backend->on(200, ['success' => true]);
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->chats->list('s');
        $this->assertRequest($backend, 'GET', '/api/sessions/s/chats');
        $client->chats->markRead('s', ['chatId' => '[email protected]']);
        $this->assertStringContainsString('/chats/read', $backend->calls()[1]['url']);
        $client->chats->markUnread('s', ['chatId' => '[email protected]']);
        $this->assertRequest($backend, 'POST', '/api/sessions/s/chats/unread');
        $client->chats->delete('s', ['chatId' => '[email protected]']);
        $this->assertRequest($backend, 'POST', '/api/sessions/s/chats/delete');
        $client->chats->sendState('s', ['chatId' => '[email protected]', 'state' => 'typing']);
        $this->assertStringContainsString('/chats/typing', $backend->calls()[4]['url']);
    }

    public function testChatsClearMessages(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->chats->clearMessages('s', '[email protected]');
        $this->assertSame('DELETE', $backend->lastCall()['method']);
        $this->assertSame('/api/sessions/s/chats/[email protected]/messages', $backend->lastCall()['path']);
    }

    public function testGroupsPicture(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['url' => 'https://x/p.jpg']);
        $backend->on(200, ['success' => true]);
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->groups->getPicture('s', '[email protected]');
        $this->assertSame('/api/sessions/s/groups/[email protected]/picture', $backend->lastCall()['path']);
        $client->groups->setPicture('s', '[email protected]', ['url' => 'https://x/new.jpg']);
        $this->assertSame('PUT', $backend->lastCall()['method']);
        $client->groups->deletePicture('s', '[email protected]');
        $this->assertSame('DELETE', $backend->lastCall()['method']);
    }

    public function testContactsAddressbook(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['success' => true]);
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->contacts->upsert('s', '[email protected]', ['firstName' => 'Ada']);
        $this->assertSame('PUT', $backend->lastCall()['method']);
        $this->assertSame('/api/sessions/s/contacts/[email protected]', $backend->lastCall()['path']);
        $client->contacts->delete('s', '[email protected]');
        $this->assertSame('DELETE', $backend->lastCall()['method']);
    }

    public function testChatsArchive(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->chats->archive('s', ['chatId' => '[email protected]', 'archive' => true]);
        $this->assertSame('/api/sessions/s/chats/archive', $backend->lastCall()['path']);
        $this->assertSame('POST', $backend->lastCall()['method']);
    }

    public function testChatsPinPostsTheFlag(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->chats->pin('s', ['chatId' => '[email protected]', 'pin' => true]);
        $this->assertSame('/api/sessions/s/chats/pin', $backend->lastCall()['path']);
        $this->assertSame('POST', $backend->lastCall()['method']);
        $this->assertSame(['chatId' => '[email protected]', 'pin' => true], $backend->lastCall()['body']);
    }

    public function testChatsPinReportsRefusalRatherThanThrowing(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['success' => false]);
        $client = $backend->makeClient();
        $this->assertSame(['success' => false], $client->chats->pin('s', ['chatId' => '[email protected]', 'pin' => true]));
    }

    public function testChatsMuteSendsEpochMillisecondsUnchanged(): void
    {
        // The value must arrive as the exact millisecond number given. A client that divided by 1000
        // would still get a 200 back; the wrong unit is only visible on the wire.
        $backend = new MockBackend();
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->chats->mute('s', ['chatId' => '[email protected]', 'muteUntil' => 1893456000000]);
        $this->assertSame('/api/sessions/s/chats/mute', $backend->lastCall()['path']);
        $this->assertSame(['chatId' => '[email protected]', 'muteUntil' => 1893456000000], $backend->lastCall()['body']);
    }

    public function testChatsMuteSendsExplicitNullToUnmute(): void
    {
        // null is the unmute signal and is NOT the same as omitting the key, which the route rejects.
        $backend = new MockBackend();
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->chats->mute('s', ['chatId' => '[email protected]', 'muteUntil' => null]);
        $this->assertArrayHasKey('muteUntil', $backend->lastCall()['body']);
        $this->assertNull($backend->lastCall()['body']['muteUntil']);
    }

    // ── Status (Stories) ──────────────────────────────────────────────

    public function testStatusSendForwardsRecipientsAndNestedMedia(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['statusId' => 's1', 'timestamp' => '2025-01-01T00:00:00.000Z', 'expiresAt' => '2025-01-02T00:00:00.000Z']);
        $backend->on(200, ['statusId' => 's2', 'timestamp' => '2025-01-01T00:00:00.000Z', 'expiresAt' => '2025-01-02T00:00:00.000Z']);
        $backend->on(200, ['statusId' => 's3', 'timestamp' => '2025-01-01T00:00:00.000Z', 'expiresAt' => '2025-01-02T00:00:00.000Z']);
        $backend->on(200, ['statusId' => 's4', 'timestamp' => '2025-01-01T00:00:00.000Z', 'expiresAt' => '2025-01-02T00:00:00.000Z']);
        $client = $backend->makeClient();
        // `recipients` is forwarded verbatim (required on Baileys, ignored by whatsapp-web.js); media posts
        // use a nested {image|video|audio:{...}} body.
        $client->status->sendText('s', ['text' => 'hi', 'recipients' => ['[email protected]']]);
        $this->assertSame(['text' => 'hi', 'recipients' => ['[email protected]']], $backend->lastCall()['body']);
        $client->status->sendImage('s', ['image' => ['url' => 'http://img'], 'recipients' => ['[email protected]'], 'caption' => 'c']);
        $this->assertSame(['image' => ['url' => 'http://img'], 'recipients' => ['[email protected]'], 'caption' => 'c'], $backend->lastCall()['body']);
        $client->status->sendVideo('s', ['video' => ['url' => 'http://vid'], 'recipients' => ['[email protected]']]);
        $this->assertSame(['video' => ['url' => 'http://vid'], 'recipients' => ['[email protected]']], $backend->lastCall()['body']);
        // A voice status wraps its media under `audio` and carries no caption.
        $client->status->sendVoice('s', ['audio' => ['base64' => 'T2dnUw=='], 'recipients' => ['[email protected]']]);
        $this->assertSame('/api/sessions/s/status/send-voice', $backend->lastCall()['path']);
        $this->assertSame(['audio' => ['base64' => 'T2dnUw=='], 'recipients' => ['[email protected]']], $backend->lastCall()['body']);
    }

    public function testVotePollPostsOptionTexts(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->messages->votePoll('s', ['chatId' => 'c1', 'pollMessageId' => 'p1', 'options' => ['Pizza']]);
        $this->assertSame('/api/sessions/s/messages/vote-poll', $backend->lastCall()['path']);
        $this->assertSame('POST', $backend->lastCall()['method']);
    }

    public function testStarPostsTheBooleanThrough(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->messages->star('s', ['chatId' => 'c1', 'messageId' => 'm1', 'star' => false]);
        $this->assertSame('/api/sessions/s/messages/star', $backend->lastCall()['path']);
        $this->assertSame('POST', $backend->lastCall()['method']);
    }

    public function testPinAndUnpinPostToTheirRoutes(): void
    {
        $backend = new MockBackend();
        // Queue responses in CALL order: pin, unpin.
        $backend->on(200, ['success' => true]);
        $backend->on(200, ['success' => true]);
        $client = $backend->makeClient();
        $client->messages->pin('s', ['chatId' => 'c1', 'messageId' => 'm1', 'durationSeconds' => 604800]);
        $this->assertSame('/api/sessions/s/messages/pin', $backend->lastCall()['path']);
        $this->assertSame('POST', $backend->lastCall()['method']);
        $client->messages->unpin('s', ['chatId' => 'c1', 'messageId' => 'm1']);
        $this->assertSame('/api/sessions/s/messages/unpin', $backend->lastCall()['path']);
    }

    public function testMessageMediaReturnsArchivedBytes(): void
    {
        $backend = (new MockBackend())->onRaw(200, 'PNG_BYTES', ['Content-Type' => 'image/png']);
        $client = $backend->makeClient();
        $media = $client->messages->media('s', 'c1', 'm1');
        $call = $backend->lastCall();
        $this->assertSame('GET', $call['method']);
        $this->assertSame('/api/sessions/s/messages/c1/m1/media', $call['path']);
        $this->assertSame('PNG_BYTES', $media['data']);
        $this->assertSame('image/png', $media['contentType']);
    }

    public function testStatusMediaReturnsStoredBytes(): void
    {
        $backend = (new MockBackend())->onRaw(200, 'PNG_BYTES', ['Content-Type' => 'image/png']);
        $client = $backend->makeClient();
        $media = $client->status->media('s', 'w1');
        $call = $backend->lastCall();
        $this->assertSame('GET', $call['method']);
        $this->assertSame('/api/sessions/s/status/w1/media', $call['path']);
        $this->assertSame('PNG_BYTES', $media['data']);
        $this->assertSame('image/png', $media['contentType']);
    }

    public function testStatusMedia404MapsToNotFoundException(): void
    {
        $backend = (new MockBackend())->on(404, [
            'statusCode' => 404,
            'message' => 'Status media not found or expired',
            'error' => 'Not Found',
        ]);
        $this->expectException(OpenWANotFoundException::class);
        $backend->makeClient()->status->media('s', 'w1');
    }

    public function testHealthAndAuth(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['status' => 'ok', 'version' => '0.7.2']);
        $backend->on(200, ['status' => 'ok']);
        $backend->on(200, ['status' => 'ok', 'details' => []]);
        $backend->on(200, ['valid' => true, 'role' => 'admin']);
        $client = $backend->makeClient();
        $client->health->check();
        $this->assertSame('/api/health', $backend->calls()[0]['path']);
        $client->health->live();
        $this->assertRequest($backend, 'GET', '/api/health/live');
        $client->health->ready();
        $this->assertRequest($backend, 'GET', '/api/health/ready');
        $client->auth();
        $this->assertSame('POST', $backend->calls()[3]['method']);
        $this->assertStringContainsString('/auth/validate', $backend->calls()[3]['url']);
    }

    public function testGroupMembershipRequests(): void
    {
        $backend = new MockBackend();
        $backend->on(200, [['participantId' => '[email protected]', 'method' => 'invite_link']]);
        $backend->on(200, ['success' => true, 'message' => 'ok', 'results' => []]);
        $backend->on(200, ['success' => true, 'message' => 'ok', 'results' => []]);
        $client = $backend->makeClient();

        $pending = $client->groups->getMembershipRequests('s', '[email protected]');
        $this->assertSame('GET', $backend->lastCall()['method']);
        $this->assertStringEndsWith('/groups/[email protected]/membership-requests', $backend->lastCall()['url']);
        $this->assertSame('[email protected]', $pending[0]['participantId']);

        $client->groups->approveMembershipRequests('s', '[email protected]', ['[email protected]']);
        $this->assertStringEndsWith('/membership-requests/approve', $backend->lastCall()['url']);
        $this->assertSame(['participants' => ['[email protected]']], $backend->lastCall()['body']);

        // Omitting the list means "every pending request": an empty body, not a null participants key.
        $client->groups->rejectMembershipRequests('s', '[email protected]');
        $this->assertStringEndsWith('/membership-requests/reject', $backend->lastCall()['url']);
        $this->assertSame([], $backend->lastCall()['body']);
        // On the wire that is an empty object, as in the other SDKs, not an empty array.
        $this->assertSame('{}', $backend->rawBody(2));
    }

    public function testCreateCallLink(): void
    {
        $backend = new MockBackend();
        $backend->on(200, ['link' => 'https://call.whatsapp.com/video/AbC']);
        $client = $backend->makeClient();
        $res = $client->calls->createLink('s', ['type' => 'video', 'startTime' => 1800000000000]);
        $this->assertSame('POST', $backend->lastCall()['method']);
        $this->assertStringEndsWith('/sessions/s/calls/link', $backend->lastCall()['url']);
        $this->assertSame(['type' => 'video', 'startTime' => 1800000000000], $backend->lastCall()['body']);
        $this->assertStringContainsString('call.whatsapp.com', $res['link']);
    }

    public function testRedriveDeliveryFailuresPostsTheFilterOrAnEmptyObject(): void
    {
        $result = ['redriven' => 1, 'delivered' => 1, 'enqueued' => 0, 'failed' => 0, 'skipped' => 0, 'remaining' => 0];
        $backend = new MockBackend();
        $backend->on(200, $result);
        $backend->on(200, $result);
        $client = $backend->makeClient();

        $this->assertSame($result, $client->webhooks->redriveDeliveryFailures(['sessionId' => 's', 'limit' => 10]));
        $this->assertRequest($backend, 'POST', '/api/webhooks/delivery-failures/redrive');
        $this->assertSame('{"sessionId":"s","limit":10}', $backend->rawBody(0));

        // An empty filter must go out as a JSON object: `[]` is not a valid body for the DTO.
        $client->webhooks->redriveDeliveryFailures();
        $this->assertSame('{}', $backend->rawBody(1));
    }

    public function testRedriveDeliveryFailuresKeepsAnExplicitEmptyIdsList(): void
    {
        // The gateway reads ids: [] as "replay nothing" and an omitted ids as "replay up to 100 rows".
        $backend = new MockBackend();
        $backend->on(200, ['redriven' => 0, 'delivered' => 0, 'enqueued' => 0, 'failed' => 0, 'skipped' => 0, 'remaining' => 3]);

        $backend->makeClient()->webhooks->redriveDeliveryFailures(['ids' => []]);

        $this->assertSame('{"ids":[]}', $backend->rawBody(0));
    }

    public function testSendMethodsForwardIdempotencyKeysWithoutChangingJson(): void
    {
        $cases = [
            ['sendText', 'send-text', ['chatId' => '[email protected]', 'text' => 'hello', 'quotedMessageId' => 'q']],
            ['sendImage', 'send-image', ['chatId' => '[email protected]', 'url' => 'https://media/image', 'caption' => 'image']],
            ['sendVideo', 'send-video', ['chatId' => '[email protected]', 'url' => 'https://media/video']],
            ['sendAudio', 'send-audio', ['chatId' => '[email protected]', 'url' => 'https://media/audio', 'ptt' => true]],
            ['sendDocument', 'send-document', ['chatId' => '[email protected]', 'url' => 'https://media/doc', 'filename' => 'doc.pdf']],
            ['sendSticker', 'send-sticker', ['chatId' => '[email protected]', 'url' => 'https://media/sticker']],
            ['sendLocation', 'send-location', ['chatId' => '[email protected]', 'latitude' => -6.2, 'longitude' => 106.8]],
            ['sendContact', 'send-contact', ['chatId' => '[email protected]', 'contactName' => 'A', 'contactNumber' => '628']],
            ['sendTemplate', 'send-template', ['chatId' => '[email protected]', 'templateId' => 't', 'vars' => []]],
            ['sendPoll', 'send-poll', ['chatId' => '[email protected]', 'name' => 'Q', 'options' => ['A', 'B']]],
            ['reply', 'reply', ['chatId' => '[email protected]', 'quotedMessageId' => 'q', 'text' => 'reply']],
            ['forward', 'forward', ['fromChatId' => '[email protected]', 'toChatId' => '[email protected]', 'messageId' => 'm']],
        ];
        foreach ([null, '!', '~', 'a', str_repeat('a', 255)] as $key) {
            $backend = new MockBackend();
            $client = $backend->makeClient();
            foreach ($cases as $index => [$method, $segment, $body]) {
                $backend->on(200, ['messageId' => 'm', 'timestamp' => 1]);
                if ($key === null) {
                    $client->messages->{$method}('s', $body);
                } else {
                    $client->messages->{$method}('s', $body, $key);
                }
                $call = $backend->lastCall();
                $this->assertSame('POST', $call['method'], $method);
                $this->assertSame('/api/sessions/s/messages/' . $segment, $call['path'], $method);
                // The key travels in its header only: in the URL it would reach proxy and access logs.
                $this->assertSame('', $call['query'], $method);
                $this->assertSame($body, $call['body'], $method);
                $expected = $body;
                if ($method === 'sendTemplate') {
                    $expected['vars'] = new \stdClass();
                }
                $this->assertSame(json_encode($expected), $backend->rawBody($index), $method);
                if ($key === null) {
                    $this->assertArrayNotHasKey('idempotency-key', $call['headers'], $method);
                } else {
                    $this->assertSame($key, $call['headers']['idempotency-key'], $method);
                }
            }
        }
    }

    public function testSendKeysStayLocalToEachRequest(): void
    {
        $backend = new MockBackend();
        $client = $backend->makeClient();
        $body = ['chatId' => '[email protected]', 'text' => 'hello'];
        foreach (['first-key', 'second-key', null] as $key) {
            $backend->on(200, ['messageId' => 'm', 'timestamp' => 1]);
            if ($key === null) {
                $client->messages->sendText('s', $body);
                $this->assertArrayNotHasKey('idempotency-key', $backend->lastCall()['headers']);
            } else {
                $client->messages->sendText('s', $body, $key);
                $this->assertSame($key, $backend->lastCall()['headers']['idempotency-key']);
            }
            $this->assertSame('', $backend->lastCall()['query']);
            $this->assertSame($body, $backend->lastCall()['body']);
        }
    }

    public function testSendKeyOverridesDefaultHeaderWithoutChangingDefaults(): void
    {
        $backend = new MockBackend();
        $defaults = ['iDeMpOtEnCy-KeY' => 'default-key', 'X-Trace' => 'trace'];
        $client = new Client([
            'baseUrl' => 'http://localhost:2785',
            'apiKey' => 'owa_k1_test',
            'httpClient' => $backend->httpClient(),
            'defaultHeaders' => $defaults,
        ]);
        $body = ['chatId' => '[email protected]', 'text' => 'hello'];
        $backend->on(200, ['messageId' => 'm', 'timestamp' => 1]);
        $client->messages->sendText('s', $body, 'request-key');
        $this->assertSame('request-key', $backend->lastCall()['headers']['idempotency-key']);
        $this->assertSame('trace', $backend->lastCall()['headers']['x-trace']);
        $backend->on(200, ['messageId' => 'm', 'timestamp' => 1]);
        $client->messages->sendText('s', $body);
        $this->assertSame('default-key', $backend->lastCall()['headers']['idempotency-key']);
        $this->assertSame(['iDeMpOtEnCy-KeY' => 'default-key', 'X-Trace' => 'trace'], $defaults);
    }

    public function testInvalidSendKeysAreRefusedBeforeTransport(): void
    {
        $backend = new MockBackend();
        $client = $backend->makeClient();
        foreach (['', ' ', 'contains space', "key\n", "\xC3\xA9", "a\x7Fb", str_repeat('a', 256)] as $key) {
            try {
                $client->messages->sendText('s', ['chatId' => '[email protected]', 'text' => 'hello'], $key);
                $this->fail('Expected invalid key to be refused');
            } catch (\InvalidArgumentException $error) {
                $this->assertStringContainsString('1-255 visible ASCII', $error->getMessage());
                $this->assertSame([], $backend->calls());
            }
        }
    }

    /**
     * Eleven routes no other test calls. Each row is written from the contract (openapi.json: verb, path,
     * query and request-body keys), not read off the client, so a changed verb or a renamed body key fails here.
     *
     * @dataProvider untestedRoutes
     */
    public function testVerbPathQueryAndBodyOfARouteNoOtherTestCalls(
        callable $call,
        string $method,
        string $path,
        array $query,
        ?array $body
    ): void {
        $backend = (new MockBackend())->on(200, []);
        $call($backend->makeClient());

        $this->assertCount(1, $backend->calls());
        $this->assertRequest($backend, $method, $path);
        parse_str($backend->lastCall()['query'], $sent);
        $this->assertSame($query, $sent);
        $this->assertSame($body === null ? '' : json_encode($body), $backend->rawBody(0));
    }

    public static function untestedRoutes(): array
    {
        $config = ['autoRejectCalls' => true, 'maxReconnectAttempts' => null, 'reconnectBaseDelay' => 2000];
        return [
            'sessions->getConfig' => [fn (Client $c) => $c->sessions->getConfig('s1'), 'GET', '/api/sessions/s1/config', [], null],
            'sessions->updateConfig' => [fn (Client $c) => $c->sessions->updateConfig('s1', $config), 'PATCH', '/api/sessions/s1/config', [], $config],
            'sessions->getProxy' => [fn (Client $c) => $c->sessions->getProxy('s1'), 'GET', '/api/sessions/s1/proxy', [], null],
            'sessions->updateProxy' => [fn (Client $c) => $c->sessions->updateProxy('s1', ['proxyUrl' => null]), 'PATCH', '/api/sessions/s1/proxy', [], ['proxyUrl' => null]],
            'webhooks->listAll' => [fn (Client $c) => $c->webhooks->listAll(['limit' => 5, 'offset' => 10]), 'GET', '/api/webhooks', ['limit' => '5', 'offset' => '10'], null],
            'webhooks->deliveryFailures' => [
                fn (Client $c) => $c->webhooks->deliveryFailures(['sessionId' => 's1', 'limit' => 5, 'offset' => 10]),
                'GET',
                '/api/webhooks/delivery-failures',
                ['sessionId' => 's1', 'limit' => '5', 'offset' => '10'],
                null,
            ],
            'chats->subscribePresence' => [
                fn (Client $c) => $c->chats->subscribePresence('s1', ['chatId' => '[email protected]']),
                'POST',
                '/api/sessions/s1/presence/subscribe',
                [],
                ['chatId' => '[email protected]'],
            ],
            'chats->getPresence' => [fn (Client $c) => $c->chats->getPresence('s1', '[email protected]'), 'GET', '/api/sessions/s1/presence/[email protected]', [], null],
            'status->fromContact' => [fn (Client $c) => $c->status->fromContact('s1', '[email protected]'), 'GET', '/api/sessions/s1/status/[email protected]', [], null],
            'labels->chats' => [fn (Client $c) => $c->labels->chats('s1', 'l1'), 'GET', '/api/sessions/s1/labels/l1/chats', [], null],
            'groups->joinInfo' => [fn (Client $c) => $c->groups->joinInfo('s1', 'INVITE'), 'GET', '/api/sessions/s1/groups/join-info', ['code' => 'INVITE'], null],
        ];
    }

    private function assertRequest(MockBackend $backend, string $method, string $path): void
    {
        $this->assertSame($method, $backend->lastCall()['method']);
        $this->assertSame($path, $backend->lastCall()['path']);
    }
}