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

This PR adds a new VonageMessages adapter targeting Vonage's modern Messages API (v1) with Basic auth and a 202 success check, and renames the existing Vonage adapter to VonageLegacy. The new adapter is well-structured, correctly guards against a missing from field, and the integration test includes proper environment-gated skipping.

• The hard rename of Vonage → VonageLegacy (with the original file deleted) is a breaking API change: existing consumers will get a fatal "class not found" error. A backward compatibility alias or major version bump is needed.

Confidence Score: 4/5

Safe to merge once the backward-compatibility concern for the Vonage → VonageLegacy rename is addressed.

The new VonageMessages adapter implementation is correct and well-tested. The single remaining P1 concern is the hard class rename without a compatibility shim, which would silently break existing library consumers on upgrade.

src/Utopia/Messaging/Adapter/SMS/VonageLegacy.php — the deleted Vonage.php file leaves no backward-compatibility path for existing consumers.

Important Files Changed

Filename	Overview
src/Utopia/Messaging/Adapter/SMS/VonageLegacy.php	Class renamed from Vonage to VonageLegacy — logic unchanged, but the rename is a breaking API change with no backward compatibility alias for existing library consumers.
src/Utopia/Messaging/Adapter/SMS/VonageMessages.php	New Vonage Messages API adapter; correctly uses Basic auth, JSON body, 202 success check, and guards against a null/empty from field before making the API call.
tests/Messaging/Adapter/SMS/VonageMessagesTest.php	New integration test with proper environment-gated skipping for all three env vars (VONAGE_API_KEY, VONAGE_API_SECRET, VONAGE_TO); covers both adapter-level and message-level from paths.
tests/Messaging/Adapter/SMS/VonageLegacyTest.php	Renamed from VonageTest; pre-existing permanently-skipped test updated to reference VonageLegacy — no logic change.

_{Reviews (9): 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