voiceml 0.9.2 → 0.9.3

data/lib/voiceml/resources/diagnostics.rb

@@ -1,64 +1,49 @@
 # frozen_string_literal: true
 
-require 'json'
-require 'net/http'
-require 'uri'
-
 require_relative '../models/diagnostics'
 
 module VoiceML
   # Diagnostic surfaces — `/health` and the OpenAPI doc endpoints.
   #
   # These don't sit under `/2010-04-01/Accounts/{AccountSid}/...`; they're mounted at the
-  # server root and don't require auth (the spec marks them `security: []`).
+  # server root and require no credentials (the spec marks them `security: []`), so every
+  # call routes through the normal transport — the configured HTTP client, timeout, proxy
+  # and User-Agent apply — with auth omitted.
   class DiagnosticsResource
     def initialize(transport)
       @transport = transport
     end
 
     # Hit `GET /health`. 200 = all hard checks pass; 503 raises `VoiceML::ServerError`
-    # with the failure list on `error.body`.
+    # with the failure list on `error.body`. `warnings`/`failures` are optional in the
+    # response body.
     #
     # @return [VoiceML::HealthStatus]
     def health
-      HealthStatus.from_hash(unauth_request('/health'))
+      HealthStatus.from_hash(@transport.request(:get, '/health', auth: false))
     end
 
     # Fetch the OpenAPI spec as parsed JSON.
     #
     # @return [Hash]
     def openapi_json
-      unauth_request('/openapi.json')
+      @transport.request(:get, '/openapi.json', auth: false)
     end
 
-    private
-
-    def unauth_request(path)
-      uri = URI.parse("#{@transport.base_url}#{path}")
-      req = Net::HTTP::Get.new(uri)
-      req['Accept']     = 'application/json'
-      req['User-Agent'] = @transport.user_agent
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl     = uri.scheme == 'https'
-      http.open_timeout = 10
-      http.read_timeout = 10
-      response = http.start { |h| h.request(req) }
-
-      status = response.code.to_i
-      unless status >= 200 && status < 300
-        body = begin
-          response.body && !response.body.empty? ? JSON.parse(response.body) : response.body
-        rescue JSON::ParserError
-          response.body
-        end
-        message = body.is_a?(Hash) && body['message'].is_a?(String) ? body['message'] : "HTTP #{status}"
-        more_info = body.is_a?(Hash) && body['more_info'].is_a?(String) ? body['more_info'] : nil
-        raise VoiceML.error_from_response(status, message, body: body, more_info: more_info)
-      end
-
-      return nil if response.body.nil? || response.body.empty?
+    # Fetch the OpenAPI spec as raw YAML (`/openapi.yaml`).
+    #
+    # @return [String]
+    def openapi_yaml
+      _status, body, _headers = @transport.request_raw(:get, '/openapi.yaml', auth: false)
+      body
+    end
 
-      JSON.parse(response.body)
+    # Fetch the OpenAPI spec as raw YAML (`/openapi.yml`).
+    #
+    # @return [String]
+    def openapi_yml
+      _status, body, _headers = @transport.request_raw(:get, '/openapi.yml', auth: false)
+      body
     end
   end
 end

data/lib/voiceml/resources/exports.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../models/exports'
+
+module VoiceML
+  # Operations on `/Exports` — the account's daily usage archives.
+  class ExportsResource < BaseResource
+    # List the account's available archives, newest first.
+    #
+    # @return [VoiceML::ExportList]
+    def list
+      ExportList.from_hash(@transport.request(:get, path('Exports')))
+    end
+
+    # Download one day's archive. Like recording audio, the server may answer
+    # with the bytes directly or with a 302 to a presigned object; redirects
+    # are followed with credentials stripped and https -> http downgrades
+    # refused.
+    #
+    # @param date [String] archive day, `YYYY-MM-DD`.
+    # @return [VoiceML::ExportDownload]
+    def download(date)
+      status, content, headers = @transport.fetch_bytes(path('Exports', date, suffix: ''))
+      content_type = headers['content-type']
+      content_type = content_type.first if content_type.is_a?(Array)
+      x_amz_id = headers['x-amz-id-2']
+      ExportDownload.new(
+        date: date,
+        content: content,
+        content_type: content_type || 'application/octet-stream',
+        via_redirect: status == 200 && !x_amz_id.nil?
+      )
+    end
+  end
+end

data/lib/voiceml/resources/incoming_phone_numbers.rb

@@ -11,10 +11,13 @@ module VoiceML
   # returning a 0-or-1-row envelope, then `get(sid)`) is supported.
   class IncomingPhoneNumbersResource < BaseResource
     LIST_FIELDS = {
-      'PhoneNumber' => :phone_number,
-      'Page'        => :page,
-      'PageSize'    => :page_size,
-      'PageToken'   => :page_token
+      'PhoneNumber'  => :phone_number,
+      'FriendlyName' => :friendly_name,
+      'Beta'         => :beta,
+      'Origin'       => :origin,
+      'Page'         => :page,
+      'PageSize'     => :page_size,
+      'PageToken'    => :page_token
     }.freeze
 
     CREATE_FIELDS = {
@@ -23,7 +26,11 @@ module VoiceML
       'VoiceMethod'         => :voice_method,
       'VoiceFallbackUrl'    => :voice_fallback_url,
       'VoiceFallbackMethod' => :voice_fallback_method,
-      'FriendlyName'        => :friendly_name
+      'SmsUrl'              => :sms_url,
+      'SmsMethod'           => :sms_method,
+      'SmsFallbackUrl'      => :sms_fallback_url,
+      'SmsFallbackMethod'   => :sms_fallback_method,
+      'SmsApplicationSid'   => :sms_application_sid
     }.freeze
 
     UPDATE_FIELDS = {
@@ -31,28 +38,36 @@ module VoiceML
       'VoiceMethod'         => :voice_method,
       'VoiceFallbackUrl'    => :voice_fallback_url,
       'VoiceFallbackMethod' => :voice_fallback_method,
-      'FriendlyName'        => :friendly_name
+      'SmsUrl'              => :sms_url,
+      'SmsMethod'           => :sms_method,
+      'SmsFallbackUrl'      => :sms_fallback_url,
+      'SmsFallbackMethod'   => :sms_fallback_method,
+      'SmsApplicationSid'   => :sms_application_sid
     }.freeze
 
-    LIST_TYPED_FIELDS = {
-      'PhoneNumber'  => :phone_number,
-      'FriendlyName' => :friendly_name,
-      'Beta'         => :beta,
-      'Origin'       => :origin,
-      'Page'         => :page,
-      'PageSize'     => :page_size,
-      'PageToken'    => :page_token
+    # The typed Local/Mobile/TollFree creates take a reduced body: only
+    # `PhoneNumber`, `VoiceUrl` and `VoiceMethod`.
+    CREATE_TYPED_FIELDS = {
+      'PhoneNumber' => :phone_number,
+      'VoiceUrl'    => :voice_url,
+      'VoiceMethod' => :voice_method
     }.freeze
 
     # List DIDs assigned to the authenticated tenant.
     #
     # @param phone_number [String, nil] exact-match E.164 filter. Returns a 0-or-1-row
     #   envelope when set — the standard twilio-ruby lookup pattern.
-    # @param page         [Integer, nil] 0-indexed page number.
-    # @param page_size    [Integer, nil] page size (server-bounded).
+    # @param friendly_name [String, nil] filter by display label.
+    # @param beta [Boolean, nil] filter new (beta) numbers.
+    # @param origin [String, nil] filter by number origin (`twilio`, `hosted`).
+    # @param page [Integer, nil] 0-indexed page number.
+    # @param page_size [Integer, nil] page size (server-bounded).
+    # @param page_token [String, nil] continuation token from a previous page.
     # @return [VoiceML::IncomingPhoneNumberList]
-    def list(phone_number: nil, page: nil, page_size: nil)
-      kwargs = { phone_number: phone_number, page: page, page_size: page_size }
+    def list(phone_number: nil, friendly_name: nil, beta: nil, origin: nil,
+             page: nil, page_size: nil, page_token: nil)
+      kwargs = { phone_number: phone_number, friendly_name: friendly_name, beta: beta,
+                 origin: origin, page: page, page_size: page_size, page_token: page_token }
       IncomingPhoneNumberList.from_hash(
         @transport.request(:get, path('IncomingPhoneNumbers'),
                            params: form_params(LIST_FIELDS, kwargs))
@@ -62,22 +77,29 @@ module VoiceML
     # Assign a DID to the authenticated tenant. Idempotent re-POSTing the same
     # `phone_number:` rebinds the voice routing (matches Twilio update semantics).
     #
-    # @param phone_number          [String] required. E.164 — leading `+`, 7-15 digits.
-    # @param voice_url             [String, nil] inbound-voice handler URL.
-    # @param voice_method          [String, nil] HTTP method for `voice_url` (`GET`/`POST`).
-    # @param voice_fallback_url    [String, nil] fallback handler URL.
+    # @param phone_number [String] required. E.164 — leading `+`, 7-15 digits.
+    # @param voice_url [String, nil] inbound-voice handler URL.
+    # @param voice_method [String, nil] HTTP method for `voice_url` (`GET`/`POST`).
+    # @param voice_fallback_url [String, nil] fallback handler URL.
     # @param voice_fallback_method [String, nil] HTTP method for `voice_fallback_url`.
-    # @param friendly_name         [String, nil] display label (server may ignore in v0.5.x).
+    # @param sms_url [String, nil] inbound-SMS webhook URL.
+    # @param sms_method [String, nil] HTTP method for `sms_url`.
+    # @param sms_fallback_url [String, nil] inbound-SMS fallback URL.
+    # @param sms_fallback_method [String, nil] HTTP method for `sms_fallback_url`.
+    # @param sms_application_sid [String, nil] `AP`-prefixed Application that
+    #   handles inbound SMS (`^AP[0-9a-fA-F]{32}$`).
     # @return [VoiceML::IncomingPhoneNumber]
     def create(phone_number:, voice_url: nil, voice_method: nil,
                voice_fallback_url: nil, voice_fallback_method: nil,
-               friendly_name: nil)
+               sms_url: nil, sms_method: nil, sms_fallback_url: nil,
+               sms_fallback_method: nil, sms_application_sid: nil)
       kwargs = {
         phone_number: phone_number,
         voice_url: voice_url, voice_method: voice_method,
-        voice_fallback_url: voice_fallback_url,
-        voice_fallback_method: voice_fallback_method,
-        friendly_name: friendly_name
+        voice_fallback_url: voice_fallback_url, voice_fallback_method: voice_fallback_method,
+        sms_url: sms_url, sms_method: sms_method,
+        sms_fallback_url: sms_fallback_url, sms_fallback_method: sms_fallback_method,
+        sms_application_sid: sms_application_sid
       }
       IncomingPhoneNumber.from_hash(
         @transport.request(:post, path('IncomingPhoneNumbers'),
@@ -93,11 +115,10 @@ module VoiceML
       )
     end
 
-    # Update voice routing on an assigned DID. Only set fields are touched.
+    # Update voice/SMS routing on an assigned DID. Only set fields are touched.
     #
     # @param sid [String] the `PN`-prefixed identifier.
-    # @param opts [Hash] any of `voice_url:`, `voice_method:`, `voice_fallback_url:`,
-    #   `voice_fallback_method:`, `friendly_name:`.
+    # @param opts [Hash] any of the `create` kwargs except `phone_number:`.
     # @return [VoiceML::IncomingPhoneNumber]
     def update(sid, **opts)
       IncomingPhoneNumber.from_hash(
@@ -148,14 +169,14 @@ module VoiceML
     def list_typed(kind, kwargs)
       IncomingPhoneNumberList.from_hash(
         @transport.request(:get, path('IncomingPhoneNumbers', kind),
-                           params: form_params(LIST_TYPED_FIELDS, kwargs))
+                           params: form_params(LIST_FIELDS, kwargs))
       )
     end
 
     def create_typed(kind, kwargs)
       IncomingPhoneNumber.from_hash(
         @transport.request(:post, path('IncomingPhoneNumbers', kind),
-                           form: form_params(CREATE_FIELDS, kwargs))
+                           form: form_params(CREATE_TYPED_FIELDS, kwargs))
       )
     end
   end

data/lib/voiceml/resources/messages.rb

@@ -2,21 +2,25 @@
 
 require_relative 'base'
 require_relative '../models/messages'
+require_relative '../models/media'
 
 module VoiceML
-  # Operations on `/Messages` — VoiceTel's Twilio-compatible SMS surface,
-  # backed by the SDK 2.2 gateway. Outbound-only today (no MMS, no inbound
-  # webhook delivery).
+  # Operations on `/Messages` — VoiceTel's Twilio-compatible SMS/MMS surface,
+  # backed by the SDK 2.2 gateway.
   #
   # All methods accept idiomatic snake_case keyword arguments — they're
-  # translated to the PascalCase wire names internally.
+  # translated to the PascalCase wire names internally. Unknown kwargs raise
+  # `ArgumentError`.
   class MessagesResource < BaseResource
     CREATE_FIELDS = {
       'To'                   => :to,
       'Body'                 => :body,
+      'MediaUrl'             => :media_url,
       'From'                 => :from,
       'MessagingServiceSid'  => :messaging_service_sid,
-      'StatusCallback'       => :status_callback
+      'ValidityPeriod'       => :validity_period,
+      'StatusCallback'       => :status_callback,
+      'StatusCallbackMethod' => :status_callback_method
     }.freeze
 
     LIST_FIELDS = {
@@ -35,12 +39,31 @@ module VoiceML
       'Status' => :status
     }.freeze
 
-    # Dispatch an outbound SMS. `to:` and `body:` are required; `from:` falls
-    # back to the tenant's configured default sender when omitted.
+    FEEDBACK_FIELDS = {
+      'Outcome' => :outcome
+    }.freeze
+
+    LIST_MEDIA_FIELDS = {
+      'DateCreated'  => :date_created,
+      'DateCreated<' => :date_created_lt,
+      'DateCreated>' => :date_created_gt,
+      'Page'         => :page,
+      'PageSize'     => :page_size,
+      'PageToken'    => :page_token
+    }.freeze
+
+    # Dispatch an outbound SMS or MMS. `to:` is required, plus at least one of
+    # `body:` (SMS text) or `media_url:` (MMS media; pass a string or an array —
+    # repeated keys are sent on the wire). `from:` falls back to the tenant's
+    # configured default sender when omitted.
     #
     # @return [VoiceML::Message]
     def create(**kwargs)
-      data = @transport.request(:post, path('Messages'), form: form_params(CREATE_FIELDS, kwargs))
+      form = form_params(CREATE_FIELDS, kwargs)
+      raise ArgumentError, 'to: is required' if form['To'].nil?
+      raise ArgumentError, 'either body: or media_url: is required' if form['Body'].nil? && form['MediaUrl'].nil?
+
+      data = @transport.request(:post, path('Messages'), form: form)
       Message.from_hash(data)
     end
 
@@ -61,21 +84,22 @@ module VoiceML
       )
     end
 
-    # Walk every page of /Messages and yield each Message. Returns an Enumerator
-    # when called without a block.
+    # Walk every page of /Messages and yield each Message, following the
+    # envelope's `next_page_uri` verbatim (the server requires its `PageToken`
+    # on page 2+). Returns an Enumerator when called without a block.
     #
     # @yield [VoiceML::Message]
     # @return [Enumerator<VoiceML::Message>] when no block given
     def each(**kwargs, &block)
       return enum_for(:each, **kwargs) unless block
 
-      page_num = kwargs.delete(:page) || 0
+      page = list(**kwargs)
       loop do
-        chunk = list(**kwargs, page: page_num)
-        chunk.messages.each(&block)
-        break if chunk.next_page_uri.nil? || chunk.next_page_uri.empty? || chunk.messages.empty?
+        page.messages.each(&block)
+        nxt = next_page(page)
+        break if nxt.nil?
 
-        page_num += 1
+        page = nxt
       end
     end
 
@@ -90,6 +114,19 @@ module VoiceML
       Message.from_hash(data)
     end
 
+    # Submit delivery feedback for a Message
+    # (`POST /Messages/{Sid}/Feedback.json`). `outcome:` is `"confirmed"` or
+    # `"unconfirmed"`; any other value echoes back as `unconfirmed` and the
+    # feedback is not persisted.
+    #
+    # @return [VoiceML::MessageFeedback]
+    def create_feedback(sid, outcome:)
+      MessageFeedback.from_hash(
+        @transport.request(:post, path('Messages', sid, 'Feedback'),
+                           form: form_params(FEEDBACK_FIELDS, { outcome: outcome }))
+      )
+    end
+
     # Remove a Message resource from the account's store.
     #
     # @return [nil]
@@ -97,5 +134,32 @@ module VoiceML
       @transport.request(:delete, path('Messages', sid))
       nil
     end
+
+    # --- Media (`/Messages/{MessageSid}/Media`) ---
+
+    # List the media items of a message.
+    #
+    # @return [VoiceML::MediaList]
+    def list_media(message_sid, **kwargs)
+      MediaList.from_hash(
+        @transport.request(:get, path('Messages', message_sid, 'Media'),
+                           params: form_params(LIST_MEDIA_FIELDS, kwargs))
+      )
+    end
+
+    # Fetch one media item's metadata.
+    #
+    # @return [VoiceML::Media]
+    def get_media(message_sid, sid)
+      Media.from_hash(@transport.request(:get, path('Messages', message_sid, 'Media', sid)))
+    end
+
+    # Delete a media item.
+    #
+    # @return [nil]
+    def delete_media(message_sid, sid)
+      @transport.request(:delete, path('Messages', message_sid, 'Media', sid))
+      nil
+    end
   end
 end

data/lib/voiceml/resources/messaging_v1.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'base'
 require_relative '../models/messaging_v1'
 
 module VoiceML
@@ -20,6 +21,9 @@ module VoiceML
   # `create` / `list` / `fetch` / `delete` reuse the shared path; `update`
   # (`POST /v1/Services/{sid}`) is unique to Messaging Service.
   class MessagingV1ServicesResource
+    include V1Pages
+    include FieldMapping
+
     SERVICE_FIELDS = {
       'FriendlyName' => :friendly_name,
       'InboundRequestUrl' => :inbound_request_url,
@@ -46,7 +50,7 @@ module VoiceML
     def create(friendly_name:, **kwargs)
       kwargs[:friendly_name] = friendly_name
       MessagingService.from_hash(
-        @transport.request(:post, '/v1/Services', form: build_form(kwargs))
+        @transport.request(:post, '/v1/Services', form: form_params(SERVICE_FIELDS, kwargs))
       )
     end
 
@@ -57,31 +61,61 @@ module VoiceML
     end
 
     def fetch(sid)
-      MessagingService.from_hash(@transport.request(:get, "/v1/Services/#{sid}"))
+      MessagingService.from_hash(@transport.request(:get, "/v1/Services/#{encode_path_segment(sid)}"))
     end
 
     def update(sid, **kwargs)
       MessagingService.from_hash(
-        @transport.request(:post, "/v1/Services/#{sid}", form: build_form(kwargs))
+        @transport.request(:post, "/v1/Services/#{encode_path_segment(sid)}",
+                           form: form_params(SERVICE_FIELDS, kwargs))
       )
     end
 
     def delete(sid)
-      @transport.request(:delete, "/v1/Services/#{sid}")
+      @transport.request(:delete, "/v1/Services/#{encode_path_segment(sid)}")
       nil
     end
 
-    private
+    # --- Sender-pool phone numbers (`/v1/Services/{ChatServiceSid}/PhoneNumbers`) ---
+
+    # List the phone numbers in a Messaging Service's sender pool. Note the
+    # spec declares only `Page`/`PageSize` here — no `PageToken`.
+    #
+    # @return [VoiceML::MessagingServicePhoneNumberList]
+    def list_phone_numbers(chat_service_sid, page: nil, page_size: nil)
+      params = {}
+      params['Page'] = page unless page.nil?
+      params['PageSize'] = page_size unless page_size.nil?
+      MessagingServicePhoneNumberList.new(
+        @transport.request(:get, "/v1/Services/#{encode_path_segment(chat_service_sid)}/PhoneNumbers",
+                           params: params)
+      )
+    end
+
+    # Add a phone number (by its `PN` sid) to a Messaging Service's sender
+    # pool. HTTP 409 means the number is already in the pool.
+    #
+    # @return [VoiceML::MessagingServicePhoneNumber]
+    def create_phone_number(chat_service_sid, phone_number_sid:)
+      MessagingServicePhoneNumber.from_hash(
+        @transport.request(:post, "/v1/Services/#{encode_path_segment(chat_service_sid)}/PhoneNumbers",
+                           form: { 'PhoneNumberSid' => phone_number_sid })
+      )
+    end
 
-    def build_form(kwargs)
-      out = {}
-      SERVICE_FIELDS.each do |wire, k|
-        value = kwargs[k]
-        next if value.nil?
+    # @return [VoiceML::MessagingServicePhoneNumber]
+    def fetch_phone_number(chat_service_sid, sid)
+      MessagingServicePhoneNumber.from_hash(
+        @transport.request(:get, "/v1/Services/#{encode_path_segment(chat_service_sid)}/PhoneNumbers/#{encode_path_segment(sid)}")
+      )
+    end
 
-        out[wire] = value
-      end
-      out
+    # Remove a phone number from a Messaging Service's sender pool.
+    #
+    # @return [nil]
+    def delete_phone_number(chat_service_sid, sid)
+      @transport.request(:delete, "/v1/Services/#{encode_path_segment(chat_service_sid)}/PhoneNumbers/#{encode_path_segment(sid)}")
+      nil
     end
   end
 end

data/lib/voiceml/resources/monitor_v1.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+require_relative '../models/monitor_v1'
+
+module VoiceML
+  # `client.monitor_alerts` — Monitor v1 Alerts (`/v1/Alerts`), on the
+  # default host: failure events for calls and messaging delivery.
+  #
+  # The server serves a single page (`meta.next_page_url` is always `null`);
+  # `next_page` follows the envelope verbatim regardless and returns `nil`
+  # when there is no continuation.
+  class MonitorAlertsResource
+    include V1Pages
+    include FieldMapping
+
+    LIST_FIELDS = {
+      'LogLevel'  => :log_level,
+      'StartDate' => :start_date,
+      'EndDate'   => :end_date,
+      'PageSize'  => :page_size
+    }.freeze
+
+    def initialize(transport)
+      @transport = transport
+    end
+
+    # Return one page of alerts, narrowed by severity (`log_level:` `"error"`
+    # or `"warning"`) and generation window (`start_date:` / `end_date:`,
+    # `YYYY-MM-DD` or a full ISO-8601 timestamp). `page_size:` limits this
+    # collection (default 50, capped at 1000 server-side).
+    #
+    # @return [VoiceML::MonitorAlertList]
+    def list(**kwargs)
+      MonitorAlertList.new(
+        @transport.request(:get, '/v1/Alerts', params: form_params(LIST_FIELDS, kwargs))
+      )
+    end
+
+    # Walk every page of `/v1/Alerts` and yield each alert, following the
+    # envelope's `meta.next_page_url` verbatim. Returns an Enumerator when
+    # called without a block; stopping early makes no further requests.
+    #
+    # @yield [VoiceML::MonitorAlert]
+    # @return [Enumerator<VoiceML::MonitorAlert>] when no block given
+    def each(**kwargs, &block)
+      return enum_for(:each, **kwargs) unless block
+
+      page = list(**kwargs)
+      loop do
+        page.alerts.each(&block)
+        nxt = next_page(page)
+        break if nxt.nil?
+
+        page = nxt
+      end
+    end
+
+    # Fetch one alert by sid, with the stored request/response detail when
+    # the underlying event carries any.
+    #
+    # @return [VoiceML::MonitorAlert]
+    def fetch(sid)
+      MonitorAlert.from_hash(@transport.request(:get, "/v1/Alerts/#{encode_path_segment(sid)}"))
+    end
+  end
+end

data/lib/voiceml/resources/notifications.rb

@@ -26,7 +26,7 @@ module VoiceML
 
     # @return [Hash]
     def get(notification_sid)
-      @transport.request(:get, path('Notifications', notification_sid))
+      Notification.from_hash(@transport.request(:get, path('Notifications', notification_sid)))
     end
   end
 end

data/lib/voiceml/resources/outgoing_caller_ids.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../models/outgoing_caller_ids'
+
+module VoiceML
+  # Operations on `/OutgoingCallerIds` — verified caller-id numbers.
+  class OutgoingCallerIdsResource < BaseResource
+    LIST_FIELDS = {
+      'PhoneNumber'  => :phone_number,
+      'FriendlyName' => :friendly_name,
+      'Page'         => :page,
+      'PageSize'     => :page_size,
+      'PageToken'    => :page_token
+    }.freeze
+
+    CREATE_FIELDS = {
+      'PhoneNumber'  => :phone_number,
+      'FriendlyName' => :friendly_name
+    }.freeze
+
+    UPDATE_FIELDS = {
+      'FriendlyName' => :friendly_name
+    }.freeze
+
+    # List verified outgoing caller ids.
+    #
+    # @return [VoiceML::OutgoingCallerIdList]
+    def list(**kwargs)
+      OutgoingCallerIdList.from_hash(
+        @transport.request(:get, path('OutgoingCallerIds'),
+                           params: form_params(LIST_FIELDS, kwargs))
+      )
+    end
+
+    # Start verification of a new outgoing caller id. The server places a
+    # validation call; the returned `VoiceML::ValidationRequest` carries the
+    # `validation_code` the user must enter on that call.
+    #
+    # @param phone_number [String] required. E.164.
+    # @param friendly_name [String, nil] display label.
+    # @return [VoiceML::ValidationRequest]
+    def create(phone_number:, friendly_name: nil)
+      ValidationRequest.from_hash(
+        @transport.request(:post, path('OutgoingCallerIds'),
+                           form: form_params(CREATE_FIELDS,
+                                             { phone_number: phone_number,
+                                               friendly_name: friendly_name }))
+      )
+    end
+
+    # Fetch a verified caller id by its `PN`-prefixed sid.
+    #
+    # @return [VoiceML::OutgoingCallerId]
+    def fetch(sid)
+      OutgoingCallerId.from_hash(@transport.request(:get, path('OutgoingCallerIds', sid)))
+    end
+
+    # Update a caller id's friendly name.
+    #
+    # @return [VoiceML::OutgoingCallerId]
+    def update(sid, friendly_name: nil)
+      OutgoingCallerId.from_hash(
+        @transport.request(:post, path('OutgoingCallerIds', sid),
+                           form: form_params(UPDATE_FIELDS, { friendly_name: friendly_name }))
+      )
+    end
+
+    # Remove a caller id.
+    #
+    # @return [nil]
+    def delete(sid)
+      @transport.request(:delete, path('OutgoingCallerIds', sid))
+      nil
+    end
+  end
+end