feat(breaking): add Vonage Messages API adapter

[bhardwajparth51]

What does this PR do?

Adds a new SMS adapter for the Vonage Messages API (v1) and renames the existing legacy adapter to VonageLegacy.

Breaking Change: The older Vonage adapter has been renamed to VonageLegacy. Users wishing to continue using the legacy SMS API must update their class references.

Key details of the implementation:

• Modern Infrastructure: Adds VonageMessages, which uses the modern Vonage Messages API (v1). This is the recommended approach as it is more cost-effective and versatile.
• Security: Implements Basic authentication (Base64 encoded API Key and Secret) specifically for the Messages API endpoint.
• Strict Validation: Validates responses against the 202 Accepted status code, ensuring robust error handling for successful handoffs.
• Static Analysis: Resolved PHPStan issues regarding missing value types in iterable return types for request headers.
• Code Cleanup: Simplified the adapter architecture by extending SMSAdapter directly, following repository patterns.

Test Plan

1. Static Analysis: Verified type safety and resolved all PHPStan errors: [OK] No errors.
2. Integration Tests:
   • Added tests/Messaging/Adapter/SMS/VonageMessagesTest.php.
   • Renamed and updated tests/Messaging/Adapter/SMS/VonageTest.php to VonageLegacyTest.php.
   • Both test suites were verified for syntax and correct class mapping (environment-gated).
3. Operational Verification: Validated correct structure of the Authorization header and JSON payload composition.

Related PRs and Issues

Closes #82

Have you read the Contributing Guidelines on issues?

Yes.

[greptile-apps]

Greptile Summary

Adds a new VonageMessages adapter targeting the modern Vonage Messages API (v1) with Basic auth and JSON body, and renames the existing Vonage adapter to VonageLegacy. Concerns raised in previous rounds (null from guard, missing VONAGE_TO env-var check) have been addressed; the breaking rename is intentional and documented.

Confidence Score: 5/5

Safe to merge; all prior P0/P1 concerns are resolved and the one remaining finding is a minor style inconsistency.

The null-from guard, VONAGE_TO env check, and breaking-change acknowledgement from previous review rounds are all in place. The only new finding is a P2 style issue (User-Agent header inconsistency with other adapters). No correctness or security issues remain.

src/Utopia/Messaging/Adapter/SMS/VonageMessages.php — minor User-Agent header inconsistency with the rest of the adapter suite.

Important Files Changed

Filename	Overview
src/Utopia/Messaging/Adapter/SMS/VonageMessages.php	New adapter for Vonage Messages API v1 using Basic auth and JSON body; null-from guard and env-var checks from prior review are in place; minor inconsistency with User-Agent header vs other adapters.
src/Utopia/Messaging/Adapter/SMS/VonageLegacy.php	Straightforward rename of Vonage → VonageLegacy with class name and NAME constant updated; no logic changes.
tests/Messaging/Adapter/SMS/VonageMessagesTest.php	New test file with two conditional-skip tests; guards for all three env vars (key, secret, to) are present and correct.
tests/Messaging/Adapter/SMS/VonageLegacyTest.php	Renamed test class with updated import; body remains unconditionally skipped (pre-existing behaviour, not a regression).

_{Reviews (10): Last reviewed commit: "chore: fix static analysis and rename Vo..." | 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
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%.
Title check	✅ Passed	The title 'feat(breaking): add Vonage Messages API adapter' clearly and specifically summarizes the main change—adding a new Vonage Messages API adapter for SMS functionality.
Description check	✅ Passed	The PR description clearly explains the addition of a new SMS adapter for the Vonage Messages API (v1), details the implementation approach, documents the breaking change regarding the renamed legacy adapter, and outlines the test plan and related issue.

_{✏️ 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

[bhardwajparth51]

@ChiragAgg5k i have updated the PR. Could you review when you have bandwidth