feat: Add BSUID (Business-Scoped User ID) support for WhatsApp usernames

[yHugirat]

Summary

Starting March 31, 2026, WhatsApp webhooks will begin including Business-Scoped User IDs (BSUIDs) and may omit phone numbers for users who enable the new username feature. This PR makes the SDK forward-compatible with these breaking API changes while maintaining full backward compatibility.

See Meta's documentation: Business-scoped user IDs

Changes

Support\Customer

• Made $id (wa_id) and $phone_number (from) nullable — these fields will be omitted when a user enables usernames and the phone number cannot be included
• Added new fields: $user_id (BSUID), $username, $parent_user_id
• Added accessor methods: userId(), username(), parentUserId()
• Added helper methods: identifier() (returns best available ID), hasPhoneNumber(), hasBsuid()

MessageNotificationFactory

• Safely handles missing from and wa_id fields using null coalescing (?? null)
• Extracts new webhook fields: user_id, from_user_id, username, parent_user_id, from_parent_user_id
• Passes all new fields to the Customer constructor

StatusNotification

• Made $customer_id (recipient_id) nullable — will be omitted for BSUID-targeted messages
• Added $recipient_user_id and $parent_recipient_user_id fields
• Added methods: recipientUserId(), parentRecipientUserId(), recipientIdentifier()

StatusNotificationFactory

• Safely handles missing recipient_id using null coalescing
• Extracts recipient_user_id and parent_recipient_user_id from status webhooks

Backward Compatibility

All changes are fully backward-compatible:

• Existing code using customer()->phoneNumber() continues to work (returns phone when available)
• New nullable parameters have default values of null
• No existing method signatures were broken — only return types changed from string to ?string where fields may now be omitted

Timeline

• Feb 16, 2026: Test BSUIDs in App Dashboard test webhooks
• March 31, 2026: BSUIDs in production webhooks, phone numbers may be omitted
• May 2026: API supports sending messages to BSUIDs via new recipient field

Test plan

• Verify existing webhook parsing works with current (phone-only) payloads
• Test with BSUID-only payloads (no from, no wa_id)
• Test with mixed payloads (both phone and BSUID present)
• Verify Customer::identifier() returns phone when available, BSUID as fallback
• Verify StatusNotification handles missing recipient_id