Clean up and changes around common fields for Phone number messages and pricing for the same

Author: nishadmusthafa

protobufs/livekit_phone_number.proto

@@ -6,6 +6,14 @@ option go_package = "github.com/livekit/protocol/livekit";
 
 import "google/protobuf/empty.proto";
 
+// Phone number status enumeration
+enum PhoneNumberStatus {
+  PHONE_NUMBER_STATUS_UNSPECIFIED = 0;  // Default value
+  PHONE_NUMBER_STATUS_ACTIVE = 1;       // Number is active and ready for use
+  PHONE_NUMBER_STATUS_PENDING = 2;      // Number is being provisioned
+  PHONE_NUMBER_STATUS_RELEASED = 3;     // Number has been released
+}
+
 // Public Phone Number Service - External API for phone number management
 service PhoneNumberService {
   // List available phone numbers in inventory
@@ -29,70 +37,85 @@ service PhoneNumberService {
 message ListPhoneNumberInventoryRequest {
   string country_code = 1;        // Optional: Filter by country code (e.g., "US", "CA")
   string area_code = 2;           // Optional: Filter by area code (e.g., "415")
-  string pattern = 3;             // Optional: Filter by pattern (e.g., "***-***-1234")
-  int32 limit = 4;                // Optional: Maximum number of results (default: 50)
-  int32 offset = 5;               // Optional: Number of results to skip (default: 0)
+  int32 limit = 3;                // Optional: Maximum number of results (default: 50)
+  string page_token = 4;          // Optional: Token for pagination (empty for first page)
 }
 
 // ListPhoneNumberInventoryResponse - Response containing available phone numbers
 message ListPhoneNumberInventoryResponse {
   repeated PhoneNumberInventoryItem items = 1;  // List of available phone numbers
-  int32 total_count = 2;                        // Total number of available numbers
-  int32 limit = 3;                              // Limit used in the request
-  int32 offset = 4;                             // Offset used in the request
+  string next_page_token = 2;                   // Token for next page (empty if no more pages)
 }
 
-// PurchasePhoneNumberRequest - Request to purchase a phone number
+// PurchasePhoneNumberRequest - Request to purchase phone numbers
 message PurchasePhoneNumberRequest {
-  string phone_number = 1;        // Phone number to purchase (e.g., "+1234567890")
+  repeated string phone_numbers = 1;  // Phone numbers to purchase (e.g., ["+1234567890", "+1234567891"])
 }
 
-// PurchasePhoneNumberResponse - Response containing the purchased phone number
+// PurchasePhoneNumberResponse - Response containing the purchased phone numbers
 message PurchasePhoneNumberResponse {
-  PurchasedPhoneNumber phone_number = 1;  // Details of the purchased phone number
+  repeated PurchasedPhoneNumber phone_numbers = 1;  // Details of the purchased phone numbers
 }
 
 // ListPurchasedPhoneNumbersRequest - Request to list purchased phone numbers
 message ListPurchasedPhoneNumbersRequest {
   int32 limit = 1;                // Optional: Maximum number of results (default: 50)
-  int32 offset = 2;               // Optional: Number of results to skip (default: 0)
+  string page_token = 2;          // Optional: Token for pagination (empty for first page)
 }
 
 // ListPurchasedPhoneNumbersResponse - Response containing purchased phone numbers
 message ListPurchasedPhoneNumbersResponse {
   repeated PurchasedPhoneNumber items = 1;  // List of purchased phone numbers
-  int32 total_count = 2;                   // Total number of purchased numbers
-  int32 limit = 3;                         // Limit used in the request
-  int32 offset = 4;                        // Offset used in the request
+  string next_page_token = 2;               // Token for next page (empty if no more pages)
+  int32 total_count = 3;                    // Total number of purchased phone numbers
 }
 
 // ReleasePhoneNumberRequest - Request to release a purchased phone number
 message ReleasePhoneNumberRequest {
   string phone_number = 1;        // Phone number to release (e.g., "+1234567890")
 }
 
+// GlobalPhoneNumber represents a phone number with standardized format
+message GlobalPhoneNumber {
+  string id = 1;                  // unique identifier
+  string e164_format = 2;         // e.g., "+14155552671"
+  string country_code = 3;        // e.g., "US"
+  string area_code = 4;           // e.g., "415"
+  string number_type  = 5;        // e.g., local, toll-free, national, mobile
+  string locality = 6;            // City/locality (e.g., "San Francisco")
+  string region = 7;              // State/region (e.g., "CA")
+  int64 spam_score = 8;           // can be used later for fraud detection
+  int64 created_at = 9;           // timestamp when created
+  int64 updated_at = 10;          // timestamp when updated
+}
+
+// PhoneNumberCost represents the pricing structure for a phone number
+message PhoneNumberCost {
+  string currency = 1;                    // Currency code (e.g., "USD", "EUR")
+
+  // Monthly rental cost
+  double monthly_rental = 2;              // Monthly rental cost (e.g., 10.00)
+
+  // Voice calling costs
+  double voice_cost = 3;                  // Voice cost per unit (e.g., 2.00)
+  string voice_billing_unit = 4;          // Voice billing unit (e.g., "minute", "second", "call")
+
+  // SMS costs
+  double sms_cost = 5;                    // SMS cost per unit (e.g., 0.50)
+  string sms_billing_unit = 6;            // SMS billing unit (e.g., "message", "character")
+}
+
 // PhoneNumberInventoryItem - Represents an available phone number for purchase
 message PhoneNumberInventoryItem {
-  string phone_number = 1;        // Phone number in E.164 format (e.g., "+14155552671")
-  string country_code = 2;        // Country code (e.g., "US")
-  string area_code = 3;           // Area code (e.g., "415")
-  string locality = 4;            // City/locality (e.g., "San Francisco")
-  string region = 5;              // State/region (e.g., "CA")
-  string capabilities = 6;        // Comma-separated capabilities (e.g., "voice,sms")
-  int64 monthly_cost_cents = 7;   // Monthly cost in cents
-  bool available = 8;             // Whether the number is currently available
-  string carrier_name = 9;        // Name of the carrier providing this number
+  GlobalPhoneNumber phone_number = 1;  // Common phone number fields
+  repeated string capabilities = 2;    // Comma-separated capabilities (e.g., "voice,sms")
+  PhoneNumberCost cost = 3;           // Cost structure for this phone number
 }
 
 // PurchasedPhoneNumber - Represents a phone number owned by a LiveKit project
 message PurchasedPhoneNumber {
-  string id = 1;                  // Unique identifier for the phone number
-  string phone_number = 2;        // Phone number in E.164 format (e.g., "+14155552671")
-  string country_code = 3;        // Country code (e.g., "US")
-  string area_code = 4;           // Area code (e.g., "415")
-  string national_number = 5;     // National number without country code (e.g., "4155552671")
-  bool is_mobile = 6;             // Whether this is a mobile number
-  string status = 7;              // Current status ("active", "pending", "released")
-  int64 assigned_at = 8;          // Timestamp when the number was assigned
-  int64 released_at = 9;          // Timestamp when the number was released (if applicable)
-} 
+  GlobalPhoneNumber phone_number = 1;  // Common phone number fields
+  PhoneNumberStatus status = 2;        // Current status of the phone number
+  int64 assigned_at = 3;               // Timestamp when the number was assigned
+  int64 released_at = 4;               // Timestamp when the number was released (if applicable)
+}