Add BSUID support - rename UserNumber to UserId

[kzu]

Summary

WhatsApp for Business is rolling out Business-Scoped User IDs (BSUIDs) for privacy. Users who opt for username-based messaging will no longer expose their phone numbers to businesses. This PR adds full SDK support for the new identifier type.

Key Changes

User record

• User(Name, Id, Number?) — Id is always set (phone or BSUID), Number is nullable
• IsBSUID computed property: true when Id matches the BSUID pattern
• Normalization (strip leading +) only applied to Number in the constructor

IMessage / public API

• Breaking rename: UserNumber to UserId throughout the public API
• UserId now returns User.Id (BSUID or phone), not User.Number

Webhook deserialization (Message.jq)

• Reads contacts[].user_id (BSUID) when present; falls back to messages[].from
• Number is set only when a distinct phone number is available

Send path (WhatsAppClientExtensions)

• recipient_type detected dynamically: "individual" for phone numbers, "business_scoped_user_id" for BSUIDs
• Detection uses the canonical BSUID format: {ISO 3166 alpha-2}.{1-128 alphanumeric} (e.g. US.13491208655302741918)
• Prefix must be exactly 2 ASCII letters — cleanly distinguishes BSUIDs from phone numbers (all-digit)
• NormalizeNumber() removed from send methods; only used in User constructor

Storage / Idempotency

• ConversationStorage, Idempotency: partition keys switch from User.Number to User.Id
• Safe migration: conversations are short-lived; idempotency is best-effort

Flows

• FlowDataRequest, FlowDataResponse, FlowToken updated to use UserId

Tests

• BsuidTests.cs added with coverage for:
  • BSUID format detection (valid alpha-2 prefix + alphanumeric suffix)
  • Rejection of numeric-prefixed strings (phone numbers) and malformed ids
  • IsBSUID property on User
  • recipient_type selection based on id shape
• Existing tests updated throughout

BSUID Detection Heuristic

Format: {ISO 3166 alpha-2 country code}.{up to 128 alphanumeric characters} (reference)

Input	Result	Reason
US.13491208655302741918	BSUID	2-letter prefix, alphanumeric suffix
AR.aBc123XyZ	BSUID	Valid alpha-2 + alphanumeric
5491122334455	Phone	All-digit, no dot
54.aBc123XyZ	Phone	Prefix is digits, not alpha-2
USA.abc123	Invalid	3-letter prefix

Webhook Scenarios

Scenario	contacts[].user_id	messages[].from	User.Id	User.Number
Pre-migration	absent	phone	phone	phone
Post-migration, non-privacy	BSUID	phone	BSUID	phone
Post-migration, privacy user	BSUID	BSUID	BSUID	null

Breaking Changes

• IMessage.UserNumber renamed to IMessage.UserId
• All response constructors: userNumber parameter renamed to userId
• IConversationStorage: number parameters renamed to userId
• Conversation record: Number property renamed to UserId

[kzu]

🧪 Details on Ubuntu 24.04.4 LTS

from retest v1.1.0 on .NET 10.0.7 with 💜 by @devlooped