feat: add Vonage Messages API adapter

[bhardwajparth51]

What does this PR do?

Adds a new SMS adapter for the Vonage Messages API (v1). This adapter is preferred over the legacy SMS API as it is more cost-effective and built on Vonage's modern messaging infrastructure.

Key details of the implementation:

• Uses Basic authentication (Base64 encoded API Key and Secret) for the Messages API, matching Vonage's requirements for this endpoint.
• Strictly validates responses against the 202 Accepted status code, which is the exclusive success response for the Messages API.
• Implements a shared VonageMessagesBase trait containing the common API logic, allowing future channel adapters (like WhatsApp or Viber) to easily reuse it.

Test Plan

1. Static Analysis: Verified type safety and syntax using vendor/bin/phpstan analyse --level=6 src tests.
2. Integration Test: Added tests/Messaging/Adapter/SMS/VonageMessagesTest.php, adhering to the repository's convention of environment-gated integration testing using the assertResponse() request-catcher.
3. Operational Verification: Validated the request Authorization header generation, JSON payload composition, and fallbacks to guarantee the adapter correctly structures API requests.

Related PRs and Issues

Closes #82

Have you read the Contributing Guidelines on issues?

Yes.

[greptile-apps]

Greptile Summary

This PR adds a new VonageMessages SMS adapter targeting the Vonage Messages API v1 with Basic auth, JSON payloads, and a 202-only success check. Both previously flagged concerns — the missing VONAGE_TO guard in tests and the null from producing an invalid JSON body — have been addressed: the test now skips cleanly when any of the three env vars are absent, and process() returns an early error result when $from is empty before the API call is made.

Confidence Score: 5/5

Safe to merge — all previously identified P1 issues have been resolved and no new defects were found.

Both critical issues (null from serialized as JSON null, missing VONAGE_TO skip guard) from prior review rounds are now handled correctly. The implementation is consistent with other SMS adapters in the repo, uses the correct Vonage Messages API endpoint and auth scheme, and the error-extraction logic covers detail, title, and raw-string error shapes.

No files require special attention.

Important Files Changed

Filename	Overview
src/Utopia/Messaging/Adapter/SMS/VonageMessages.php	New SMS adapter for Vonage Messages API v1 with Basic auth, JSON body, and explicit guard for empty from; logic is correct and consistent with other adapters in the repo.
tests/Messaging/Adapter/SMS/VonageMessagesTest.php	Integration tests guard all three env vars (VONAGE_API_KEY, VONAGE_API_SECRET, VONAGE_TO) and handle optional VONAGE_FROM correctly in both test cases.

_{Reviews (8): Last reviewed commit: "fix: address review feedback and harden ..." | Re-trigger Greptile}

[bhardwajparth51]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Walkthrough

Adds a new SMS adapter Utopia\Messaging\Adapter\SMS\VonageMessages that sends SMS via the Vonage Messages API (v1). The adapter accepts apiKey, apiSecret, and optional default from, limits requests to one message per call, normalizes destination numbers, and treats HTTP 202 as delivered; other responses are reported as failures with error extraction. A shared trait Utopia\Messaging\Adapter\VonageMessagesBase supplies the API endpoint and request/authorization header helpers. Two PHPUnit tests exercise send behavior with and without a fallback from.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and clearly summarizes the main change: adding a new Vonage Messages API adapter for SMS messaging.
Linked Issues check	✅ Passed	The PR fully addresses all coding requirements from issue #82: creates VonageMessagesBase trait [#82], implements VonageMessages SMS adapter [#82], and includes proper integration tests.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #82 requirements: new VonageMessagesBase trait, VonageMessages SMS adapter, and corresponding integration tests with no extraneous modifications.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description check	✅ Passed	The pull request description clearly explains the motivation, implementation details, and test plan for adding a new Vonage Messages API SMS adapter.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

tests/Messaging/Adapter/SMS/VonageMessagesTest.php (1)

30-34: Inconsistent handling of VONAGE_FROM between constructor and message.

The constructor fallback (line 27) uses 'Vonage' when VONAGE_FROM is unset, but the message's from (line 33) receives false (from getenv() returning false). This creates an inconsistent test scenario where the adapter's from differs from the message's from.

If the intent is to test the adapter's constructor from taking precedence, the message's from could be explicitly set to null or omitted. If the intent is to pass matching values, both should use the same fallback.

♻️ Suggested clarification

         $message = new SMS(
             to: [$to],
             content: 'Test Content',
-            from: \getenv('VONAGE_FROM')
+            from: \getenv('VONAGE_FROM') ?: null
         );

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e6eed56d-cd95-4c22-9ff3-18c201ec0c9c

📥 Commits

Reviewing files that changed from the base of the PR and between fcb4c3c and 6710210.

📒 Files selected for processing (3)

• src/Utopia/Messaging/Adapter/SMS/VonageMessages.php
• src/Utopia/Messaging/Adapter/VonageMessagesBase.php
• tests/Messaging/Adapter/SMS/VonageMessagesTest.php

[bhardwajparth51]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[bhardwajparth51]

@stnguyen90 Ready for review! let me know if it need any additional changes.

[bhardwajparth51]

i think the CI failures are all pre-existing they're coming from expired or missing github secrets for Twilio, Resend, Sendgrid, Mailgun, Fast2SMS, Inforu, Discord, APNS, and FCM. My Vonage tests are correctly skipping since the VONAGE_* secrets aren't configured in CI yet.

[bhardwajparth51]

@ChiragAgg5k can you review it

[bhardwajparth51]

I went ahead and set up a Vonage developer account to run the integration tests locally against the live API. Everything works perfectly!

[ChiragAgg5k]

lets avoid a base class, not sure why we would need one

[greptile-apps]

Tip:

Greploop — Automatically fix all review issues by running /greploops in Claude Code. It iterates: fix, push, re-review, repeat until 5/5 confidence.

Use the Greptile plugin for Claude Code to query reviews, search comments, and manage custom context directly from your terminal.

[ChiragAgg5k]

@bhardwajparth51 lets fix the static analysis. also i propose we can make this a breaking change and mark the older adapter as legacy, perhaps VonageLegacy? since this one is clearly better and recommended to use