voiceml 0.7.1.1

data/lib/voiceml/resources/incoming_phone_numbers.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../models/incoming_phone_numbers'
+
+module VoiceML
+  # Operations on `/IncomingPhoneNumbers` — tenant-scoped DID lookup and routing.
+  #
+  # Twilio-compatible: `sid` is the canonical `PN`-prefixed identifier, `phone_number` is the
+  # E.164 form. The standard lookup-by-number pattern (`list(phone_number: '+1...')`
+  # 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
+    }.freeze
+
+    CREATE_FIELDS = {
+      'PhoneNumber'         => :phone_number,
+      'VoiceUrl'            => :voice_url,
+      'VoiceMethod'         => :voice_method,
+      'VoiceFallbackUrl'    => :voice_fallback_url,
+      'VoiceFallbackMethod' => :voice_fallback_method,
+      'FriendlyName'        => :friendly_name
+    }.freeze
+
+    UPDATE_FIELDS = {
+      'VoiceUrl'            => :voice_url,
+      'VoiceMethod'         => :voice_method,
+      'VoiceFallbackUrl'    => :voice_fallback_url,
+      'VoiceFallbackMethod' => :voice_fallback_method,
+      'FriendlyName'        => :friendly_name
+    }.freeze
+
+    LIST_TYPED_FIELDS = {
+      'PhoneNumber'  => :phone_number,
+      'FriendlyName' => :friendly_name,
+      'Beta'         => :beta,
+      'Origin'       => :origin,
+      'Page'         => :page,
+      'PageSize'     => :page_size,
+      'PageToken'    => :page_token
+    }.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).
+    # @return [VoiceML::IncomingPhoneNumberList]
+    def list(phone_number: nil, page: nil, page_size: nil)
+      kwargs = { phone_number: phone_number, page: page, page_size: page_size }
+      IncomingPhoneNumberList.from_hash(
+        @transport.request(:get, path('IncomingPhoneNumbers'),
+                           params: form_params(LIST_FIELDS, kwargs))
+      )
+    end
+
+    # 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 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).
+    # @return [VoiceML::IncomingPhoneNumber]
+    def create(phone_number:, voice_url: nil, voice_method: nil,
+               voice_fallback_url: nil, voice_fallback_method: nil,
+               friendly_name: 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
+      }
+      IncomingPhoneNumber.from_hash(
+        @transport.request(:post, path('IncomingPhoneNumbers'),
+                           form: form_params(CREATE_FIELDS, kwargs))
+      )
+    end
+
+    # Fetch a single DID by its `PN`-prefixed sid.
+    # @return [VoiceML::IncomingPhoneNumber]
+    def get(sid)
+      IncomingPhoneNumber.from_hash(
+        @transport.request(:get, path('IncomingPhoneNumbers', sid))
+      )
+    end
+
+    # Update voice 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:`.
+    # @return [VoiceML::IncomingPhoneNumber]
+    def update(sid, **opts)
+      IncomingPhoneNumber.from_hash(
+        @transport.request(:post, path('IncomingPhoneNumbers', sid),
+                           form: form_params(UPDATE_FIELDS, opts))
+      )
+    end
+
+    # Release a DID from the authenticated tenant. Idempotent — 204 even if already gone.
+    # @return [nil]
+    def delete(sid)
+      @transport.request(:delete, path('IncomingPhoneNumbers', sid))
+      nil
+    end
+
+    # @return [VoiceML::IncomingPhoneNumberList]
+    def list_local(**kwargs)
+      list_typed('Local', kwargs)
+    end
+
+    # @return [VoiceML::IncomingPhoneNumber]
+    def create_local(**kwargs)
+      create_typed('Local', kwargs)
+    end
+
+    # @return [VoiceML::IncomingPhoneNumberList]
+    def list_mobile(**kwargs)
+      list_typed('Mobile', kwargs)
+    end
+
+    # @return [VoiceML::IncomingPhoneNumber]
+    def create_mobile(**kwargs)
+      create_typed('Mobile', kwargs)
+    end
+
+    # @return [VoiceML::IncomingPhoneNumberList]
+    def list_toll_free(**kwargs)
+      list_typed('TollFree', kwargs)
+    end
+
+    # @return [VoiceML::IncomingPhoneNumber]
+    def create_toll_free(**kwargs)
+      create_typed('TollFree', kwargs)
+    end
+
+    private
+
+    def list_typed(kind, kwargs)
+      IncomingPhoneNumberList.from_hash(
+        @transport.request(:get, path('IncomingPhoneNumbers', kind),
+                           params: form_params(LIST_TYPED_FIELDS, kwargs))
+      )
+    end
+
+    def create_typed(kind, kwargs)
+      IncomingPhoneNumber.from_hash(
+        @transport.request(:post, path('IncomingPhoneNumbers', kind),
+                           form: form_params(CREATE_FIELDS, kwargs))
+      )
+    end
+  end
+end

data/lib/voiceml/resources/messages.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../models/messages'
+
+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).
+  #
+  # All methods accept idiomatic snake_case keyword arguments — they're
+  # translated to the PascalCase wire names internally.
+  class MessagesResource < BaseResource
+    CREATE_FIELDS = {
+      'To'                   => :to,
+      'Body'                 => :body,
+      'From'                 => :from,
+      'MessagingServiceSid'  => :messaging_service_sid,
+      'StatusCallback'       => :status_callback
+    }.freeze
+
+    LIST_FIELDS = {
+      'To'         => :to,
+      'From'       => :from,
+      'DateSent'   => :date_sent,
+      'DateSent<'  => :date_sent_lt,
+      'DateSent>'  => :date_sent_gt,
+      'Page'       => :page,
+      'PageSize'   => :page_size,
+      'PageToken'  => :page_token
+    }.freeze
+
+    UPDATE_FIELDS = {
+      'Body'   => :body,
+      'Status' => :status
+    }.freeze
+
+    # Dispatch an outbound SMS. `to:` and `body:` are required; `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))
+      Message.from_hash(data)
+    end
+
+    # Retrieve a previously-sent Message by sid.
+    #
+    # @return [VoiceML::Message]
+    def fetch(sid)
+      Message.from_hash(@transport.request(:get, path('Messages', sid)))
+    end
+
+    # Return a single page of Messages, narrowed by the Twilio-documented filter
+    # set (To, From, DateSent eq/gt/lt) plus pagination.
+    #
+    # @return [VoiceML::MessageList]
+    def list(**kwargs)
+      MessageList.from_hash(
+        @transport.request(:get, path('Messages'), params: form_params(LIST_FIELDS, kwargs))
+      )
+    end
+
+    # Walk every page of /Messages and yield each Message. 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
+      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_num += 1
+      end
+    end
+
+    # Mutate an existing Message — redact `body:` to empty string, or attempt
+    # `status: "canceled"`. Cancellation returns 21610 today because the gateway
+    # is fire-and-forget.
+    #
+    # @return [VoiceML::Message]
+    def update(sid, **kwargs)
+      data = @transport.request(:post, path('Messages', sid),
+                                form: form_params(UPDATE_FIELDS, kwargs))
+      Message.from_hash(data)
+    end
+
+    # Remove a Message resource from the account's store.
+    #
+    # @return [nil]
+    def delete(sid)
+      @transport.request(:delete, path('Messages', sid))
+      nil
+    end
+  end
+end

data/lib/voiceml/resources/notifications.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../models/diagnostics'
+
+module VoiceML
+  # Account-scoped `/Notifications` compat stubs (always empty list; fetch returns 404).
+  class NotificationsResource < BaseResource
+    LIST_FIELDS = {
+      'Page'          => :page,
+      'PageSize'      => :page_size,
+      'PageToken'     => :page_token,
+      'Log'           => :log,
+      'MessageDate'   => :message_date,
+      'MessageDate<'  => :message_date_lt,
+      'MessageDate>'  => :message_date_gt
+    }.freeze
+
+    # @return [VoiceML::NotificationsList]
+    def list(**kwargs)
+      NotificationsList.from_hash(
+        @transport.request(:get, path('Notifications'),
+                           params: form_params(LIST_FIELDS, kwargs))
+      )
+    end
+
+    # @return [Hash]
+    def get(notification_sid)
+      @transport.request(:get, path('Notifications', notification_sid))
+    end
+  end
+end

data/lib/voiceml/resources/queues.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../models/queues'
+
+module VoiceML
+  # Operations on `/Queues` and their members.
+  class QueuesResource < BaseResource
+    QUEUE_FIELDS = {
+      'FriendlyName' => :friendly_name,
+      'MaxSize'      => :max_size
+    }.freeze
+
+    DEQUEUE_FIELDS = {
+      'Url'    => :url,
+      'Method' => :method
+    }.freeze
+
+    LIST_PAGE_FIELDS = {
+      'Page'      => :page,
+      'PageSize'  => :page_size,
+      'PageToken' => :page_token
+    }.freeze
+
+    LIST_MEMBERS_FIELDS = {
+      'Page'      => :page,
+      'PageSize'  => :page_size,
+      'PageToken' => :page_token
+    }.freeze
+
+    # @return [VoiceML::Queue]
+    def create(**kwargs)
+      Queue.from_hash(
+        @transport.request(:post, path('Queues'), form: form_params(QUEUE_FIELDS, kwargs))
+      )
+    end
+
+    # @return [VoiceML::QueueList]
+    def list(**kwargs)
+      QueueList.from_hash(
+        @transport.request(:get, path('Queues'), params: form_params(LIST_PAGE_FIELDS, kwargs))
+      )
+    end
+
+    # @yield [VoiceML::Queue]
+    # @return [Enumerator<VoiceML::Queue>] when no block given
+    def each(**kwargs, &block)
+      return enum_for(:each, **kwargs) unless block
+
+      page_num = kwargs.delete(:page) || 0
+      loop do
+        chunk = list(**kwargs, page: page_num)
+        chunk.queues.each(&block)
+        break if chunk.next_page_uri.nil? || chunk.next_page_uri.empty? || chunk.queues.empty?
+        page_num += 1
+      end
+    end
+
+    # @return [VoiceML::Queue]
+    def get(queue_sid)
+      Queue.from_hash(@transport.request(:get, path('Queues', queue_sid)))
+    end
+
+    # @return [VoiceML::Queue]
+    def update(queue_sid, **kwargs)
+      Queue.from_hash(
+        @transport.request(:post, path('Queues', queue_sid),
+                           form: form_params(QUEUE_FIELDS, kwargs))
+      )
+    end
+
+    # @return [nil]
+    def delete(queue_sid)
+      @transport.request(:delete, path('Queues', queue_sid))
+      nil
+    end
+
+    # --- Members ---
+
+    # @return [VoiceML::QueueMemberList]
+    def list_members(queue_sid, **kwargs)
+      QueueMemberList.from_hash(
+        @transport.request(:get, path('Queues', queue_sid, 'Members'),
+                           params: form_params(LIST_MEMBERS_FIELDS, kwargs))
+      )
+    end
+
+    # @return [VoiceML::QueueMember]
+    def peek_front(queue_sid)
+      QueueMember.from_hash(
+        @transport.request(:get, path('Queues', queue_sid, 'Members', 'Front'))
+      )
+    end
+
+    # Dequeue the front-of-queue member to a TwiML URL.
+    # @return [VoiceML::QueueMember]
+    def dequeue_front(queue_sid, **kwargs)
+      QueueMember.from_hash(
+        @transport.request(:post, path('Queues', queue_sid, 'Members', 'Front'),
+                           form: form_params(DEQUEUE_FIELDS, kwargs))
+      )
+    end
+
+    # @return [VoiceML::QueueMember]
+    def get_member(queue_sid, call_sid)
+      QueueMember.from_hash(
+        @transport.request(:get, path('Queues', queue_sid, 'Members', call_sid))
+      )
+    end
+
+    # Dequeue a specific member by CallSid.
+    # @return [VoiceML::QueueMember]
+    def dequeue_member(queue_sid, call_sid, **kwargs)
+      QueueMember.from_hash(
+        @transport.request(:post, path('Queues', queue_sid, 'Members', call_sid),
+                           form: form_params(DEQUEUE_FIELDS, kwargs))
+      )
+    end
+  end
+end

data/lib/voiceml/resources/recordings.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../models/recordings'
+
+module VoiceML
+  # Account-scoped `/Recordings` operations.
+  #
+  # Per-call recording start/stop/list lives on {VoiceML::CallsResource} — this resource
+  # handles the account-wide list, single-recording fetch (both metadata and audio),
+  # and delete.
+  class RecordingsResource < BaseResource
+    LIST_FIELDS = {
+      'DateCreated'   => :date_created,
+      'DateCreated<'  => :date_created_lt,
+      'DateCreated>'  => :date_created_gt,
+      'CallSid'       => :call_sid,
+      'ConferenceSid' => :conference_sid,
+      'IncludeSoftDeleted' => :include_soft_deleted,
+      'Page'          => :page,
+      'PageSize'      => :page_size,
+      'PageToken'     => :page_token
+    }.freeze
+
+    GET_FIELDS = {
+      'IncludeSoftDeleted' => :include_soft_deleted
+    }.freeze
+
+    # @return [VoiceML::RecordingList]
+    def list(**kwargs)
+      RecordingList.from_hash(
+        @transport.request(:get, path('Recordings'), params: form_params(LIST_FIELDS, kwargs))
+      )
+    end
+
+    # @yield [VoiceML::Recording]
+    # @return [Enumerator<VoiceML::Recording>] when no block given
+    def each(**kwargs, &block)
+      return enum_for(:each, **kwargs) unless block
+
+      page_num = kwargs.delete(:page) || 0
+      loop do
+        chunk = list(**kwargs, page: page_num)
+        chunk.recordings.each(&block)
+        break if chunk.next_page_uri.nil? || chunk.next_page_uri.empty? || chunk.recordings.empty?
+        page_num += 1
+      end
+    end
+
+    # Fetch the metadata JSON for a recording.
+    # @return [VoiceML::Recording]
+    def get(recording_sid, **kwargs)
+      params = form_params(GET_FIELDS, kwargs)
+      Recording.from_hash(
+        @transport.request(:get, path('Recordings', recording_sid), params: params.empty? ? nil : params)
+      )
+    end
+
+    # Fetch the WAV audio for a recording.
+    #
+    # Three server delivery shapes are flattened into one result by following any 302
+    # redirect to S3:
+    # - `200 OK` — local file present.
+    # - `302 Found` — archived to S3; the SDK follows the presigned URL.
+    # - `410 Gone` — local file gone AND no S3 key. Raises `VoiceML::GoneError`.
+    #
+    # @return [VoiceML::RecordingAudio]
+    def get_audio(recording_sid)
+      status, content, headers = @transport.fetch_bytes(
+        "#{path('Recordings', recording_sid, suffix: '')}.wav"
+      )
+      content_type = headers['content-type']
+      content_type = content_type.first if content_type.is_a?(Array)
+      x_amz_id = headers['x-amz-id-2']
+      RecordingAudio.new(
+        sid: recording_sid,
+        content: content,
+        content_type: content_type || 'application/octet-stream',
+        via_redirect: status == 200 && !x_amz_id.nil?
+      )
+    end
+
+    # @return [nil]
+    def delete(recording_sid)
+      @transport.request(:delete, path('Recordings', recording_sid))
+      nil
+    end
+  end
+end