voiceml 0.7.1.1

data/lib/voiceml/resources/base.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module VoiceML
+  # @api private
+  # Mixin holding a `Transport` reference and helpers for AccountSid-scoped pathing.
+  class BaseResource
+    def initialize(transport)
+      @transport = transport
+    end
+
+    private
+
+    # Build a URL under `/2010-04-01/Accounts/{AccountSid}/...`. Caller passes path segments
+    # (e.g. `"Calls"`, sid, `"Recordings"`). Empty segments are skipped; nothing is
+    # URL-encoded — sids and slugs never need escaping.
+    #
+    # As of v0.5.0 every REST endpoint resolves under its `.json` form (Twilio drop-in
+    # compatibility). Pass `suffix: ''` to opt out — used by `.wav` audio fetches and any
+    # caller that needs to append a different extension.
+    def path(*parts, suffix: '.json')
+      tail = parts.compact.reject { |p| p.to_s.empty? }.join('/')
+      "/2010-04-01/Accounts/#{@transport.account_sid}/#{tail}#{suffix}"
+    end
+
+    # Translate snake_case Ruby kwargs to the form/query field names the server expects.
+    # `nil` values are dropped; booleans become "true"/"false" inside Transport.
+    def form_params(map, kwargs)
+      out = {}
+      map.each do |wire_name, ruby_key|
+        value = kwargs[ruby_key]
+        next if value.nil?
+
+        out[wire_name] = value
+      end
+      out
+    end
+  end
+end

data/lib/voiceml/resources/calls.rb

@@ -0,0 +1,414 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../models/calls'
+require_relative '../models/recordings'
+require_relative '../models/streams'
+require_relative '../models/siprec'
+require_relative '../models/transcriptions'
+require_relative '../models/diagnostics'
+require_relative '../models/payments'
+
+module VoiceML
+  # Operations on `/Calls` and call-scoped sub-resources (Recordings, Streams, Siprec,
+  # Transcriptions, Notifications, Events, UserDefinedMessages).
+  #
+  # All methods accept idiomatic snake_case keyword arguments — they're translated to
+  # Twilio's PascalCase wire names internally.
+  class CallsResource < BaseResource
+    # Create-call form-field map (snake_case kwarg -> Twilio wire name).
+    CREATE_FIELDS = {
+      'To'                                    => :to,
+      'From'                                  => :from,
+      'Url'                                   => :url,
+      'Method'                                => :method,
+      'Twiml'                                 => :twiml,
+      'ApplicationSid'                        => :application_sid,
+      'FallbackUrl'                           => :fallback_url,
+      'FallbackMethod'                        => :fallback_method,
+      'StatusCallback'                        => :status_callback,
+      'StatusCallbackMethod'                  => :status_callback_method,
+      'StatusCallbackEvent'                   => :status_callback_event,
+      'MachineDetection'                      => :machine_detection,
+      'MachineDetectionTimeout'               => :machine_detection_timeout,
+      'MachineDetectionSpeechThreshold'       => :machine_detection_speech_threshold,
+      'MachineDetectionSpeechEndThreshold'    => :machine_detection_speech_end_threshold,
+      'MachineDetectionSilenceTimeout'        => :machine_detection_silence_timeout,
+      'AsyncAmdStatusCallback'                => :async_amd_status_callback,
+      'AsyncAmdStatusCallbackMethod'          => :async_amd_status_callback_method,
+      'Record'                                => :record,
+      'RecordingStatusCallback'               => :recording_status_callback,
+      'RecordingStatusCallbackMethod'         => :recording_status_callback_method,
+      'RecordingStatusCallbackEvent'          => :recording_status_callback_event,
+      'RecordingChannels'                     => :recording_channels,
+      'RecordingTrack'                        => :recording_track,
+      'Trim'                                  => :trim,
+      'Timeout'                               => :timeout,
+      'SendDigits'                            => :send_digits,
+      'CallerId'                              => :caller_id,
+      'CallReason'                            => :call_reason,
+      'SipAuthUsername'                       => :sip_auth_username,
+      'SipAuthPassword'                       => :sip_auth_password,
+      'Byoc'                                  => :byoc,
+      'AsyncAmd'                              => :async_amd,
+      'CallToken'                             => :call_token
+    }.freeze
+
+    UPDATE_FIELDS = {
+      'Status'                => :status,
+      'Twiml'                 => :twiml,
+      'Url'                   => :url,
+      'Method'                => :method,
+      'FallbackUrl'           => :fallback_url,
+      'FallbackMethod'        => :fallback_method,
+      'StatusCallback'        => :status_callback,
+      'StatusCallbackMethod'  => :status_callback_method,
+      'StatusCallbackEvent'   => :status_callback_event
+    }.freeze
+
+    LIST_FIELDS = {
+      'To'             => :to,
+      'From'           => :from,
+      'Status'         => :status,
+      'ParentCallSid'  => :parent_call_sid,
+      'StartTime'      => :start_time,
+      'StartTime<'     => :start_time_lt,
+      'StartTime>'     => :start_time_gt,
+      # Note: spec defines `StartTime>=` and `StartTime<=` as the literal query names.
+      'StartTime>='    => :start_time_gte,
+      'StartTime<='    => :start_time_lte,
+      'EndTime'        => :end_time,
+      'EndTime<'       => :end_time_lt,
+      'EndTime>'       => :end_time_gt,
+      'Page'           => :page,
+      'PageSize'       => :page_size,
+      'PageToken'      => :page_token
+    }.freeze
+
+    LIST_RECORDINGS_FIELDS = {
+      'DateCreated'   => :date_created,
+      'DateCreated<'  => :date_created_lt,
+      'DateCreated>'  => :date_created_gt,
+      'Page'          => :page,
+      'PageSize'      => :page_size,
+      'PageToken'     => :page_token
+    }.freeze
+
+    LIST_STUB_PAGE_FIELDS = {
+      'Page'      => :page,
+      'PageSize'  => :page_size,
+      'PageToken' => :page_token
+    }.freeze
+
+    LIST_NOTIFICATIONS_FIELDS = {
+      'Page'          => :page,
+      'PageSize'      => :page_size,
+      'PageToken'     => :page_token,
+      'Log'           => :log,
+      'MessageDate'   => :message_date,
+      'MessageDate<'  => :message_date_lt,
+      'MessageDate>'  => :message_date_gt
+    }.freeze
+
+    START_RECORDING_FIELDS = {
+      'RecordingMaxDuration'           => :recording_max_duration,
+      'RecordingChannels'              => :recording_channels,
+      'PlayBeep'                       => :play_beep,
+      'RecordingStatusCallback'        => :recording_status_callback,
+      'RecordingStatusCallbackMethod'  => :recording_status_callback_method,
+      'RecordingStatusCallbackEvent'   => :recording_status_callback_event
+    }.freeze
+
+    START_STREAM_FIELDS = {
+      'Url'                  => :url,
+      'Track'                => :track,
+      'Name'                 => :name,
+      'StatusCallback'       => :status_callback,
+      'StatusCallbackMethod' => :status_callback_method
+    }.freeze
+
+    START_SIPREC_FIELDS = {
+      'Name'                 => :name,
+      'ConnectorName'        => :connector_name,
+      'Track'                => :track,
+      'StatusCallback'       => :status_callback,
+      'StatusCallbackMethod' => :status_callback_method
+    }.freeze
+
+    START_TRANSCRIPTION_FIELDS = {
+      'Name'                 => :name,
+      'Track'                => :track,
+      'LanguageCode'         => :language_code,
+      'TranscriptionEngine'  => :transcription_engine,
+      'ProfanityFilter'      => :profanity_filter,
+      'PartialResults'       => :partial_results,
+      'Hints'                => :hints,
+      'StatusCallback'       => :status_callback,
+      'StatusCallbackMethod' => :status_callback_method,
+      'StatusCallbackEvents' => :status_callback_events
+    }.freeze
+
+    START_PAYMENT_FIELDS = {
+      'IdempotencyKey'         => :idempotency_key,
+      'StatusCallback'         => :status_callback,
+      'BankAccountType'        => :bank_account_type,
+      'ChargeAmount'           => :charge_amount,
+      'Currency'               => :currency,
+      'Description'            => :description,
+      'Input'                  => :input,
+      'MinPostalCodeLength'    => :min_postal_code_length,
+      'Parameter'              => :parameter,
+      'PaymentConnector'       => :payment_connector,
+      'PaymentMethod'          => :payment_method,
+      'PostalCode'             => :postal_code,
+      'SecurityCode'           => :security_code,
+      'Timeout'                => :timeout,
+      'TokenType'              => :token_type,
+      'ValidCardTypes'         => :valid_card_types,
+      'RequireMatchingInputs'  => :require_matching_inputs,
+      'Confirmation'           => :confirmation
+    }.freeze
+
+    UPDATE_PAYMENT_FIELDS = {
+      'IdempotencyKey' => :idempotency_key,
+      'StatusCallback' => :status_callback,
+      'Capture'        => :capture,
+      'Status'         => :status
+    }.freeze
+
+    # @return [VoiceML::CallList]
+    def list(**kwargs)
+      data = @transport.request(:get, path('Calls'), params: form_params(LIST_FIELDS, kwargs))
+      CallList.from_hash(data)
+    end
+
+    # Walk every page of /Calls and yield each Call. Returns an Enumerator when
+    # called without a block.
+    #
+    # @yield [VoiceML::Call]
+    # @return [Enumerator<VoiceML::Call>] 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.calls.each(&block)
+        break if chunk.next_page_uri.nil? || chunk.next_page_uri.empty? || chunk.calls.empty?
+        page_num += 1
+      end
+    end
+
+    # Create a new outbound call.
+    #
+    # Pass at most one of `url:` / `twiml:` / `application_sid:` (Twiml wins if multiple are set
+    # — Twilio's documented precedence).
+    #
+    # @return [VoiceML::Call]
+    def create(**kwargs)
+      data = @transport.request(:post, path('Calls'), form: form_params(CREATE_FIELDS, kwargs))
+      Call.from_hash(data)
+    end
+
+    # @return [VoiceML::Call]
+    def get(call_sid)
+      data = @transport.request(:get, path('Calls', call_sid))
+      Call.from_hash(data)
+    end
+
+    # @return [VoiceML::Call]
+    def update(call_sid, **kwargs)
+      data = @transport.request(:post, path('Calls', call_sid),
+                                form: form_params(UPDATE_FIELDS, kwargs))
+      Call.from_hash(data)
+    end
+
+    # @return [nil]
+    def delete(call_sid)
+      @transport.request(:delete, path('Calls', call_sid))
+      nil
+    end
+
+    # --- Call-scoped Recordings ---
+
+    # @return [VoiceML::RecordingList]
+    def list_recordings(call_sid, **kwargs)
+      RecordingList.from_hash(
+        @transport.request(:get, path('Calls', call_sid, 'Recordings'),
+                           params: form_params(LIST_RECORDINGS_FIELDS, kwargs))
+      )
+    end
+
+    # @return [VoiceML::Recording]
+    def start_recording(call_sid, **kwargs)
+      data = @transport.request(:post, path('Calls', call_sid, 'Recordings'),
+                                form: form_params(START_RECORDING_FIELDS, kwargs))
+      Recording.from_hash(data)
+    end
+
+    # @return [VoiceML::Recording]
+    def get_recording(call_sid, recording_sid)
+      Recording.from_hash(
+        @transport.request(:get, path('Calls', call_sid, 'Recordings', recording_sid))
+      )
+    end
+
+    # @param status [String] one of "in-progress", "paused", "stopped".
+    # @return [VoiceML::Recording]
+    def update_recording(call_sid, recording_sid, status:)
+      data = @transport.request(:post, path('Calls', call_sid, 'Recordings', recording_sid),
+                                form: { 'Status' => status })
+      Recording.from_hash(data)
+    end
+
+    # @return [nil]
+    def delete_recording(call_sid, recording_sid)
+      @transport.request(:delete, path('Calls', call_sid, 'Recordings', recording_sid))
+      nil
+    end
+
+    # --- Streams ---
+
+    # @return [VoiceML::StreamList]
+    def list_streams(call_sid)
+      StreamList.from_hash(@transport.request(:get, path('Calls', call_sid, 'Streams')))
+    end
+
+    # @return [VoiceML::Stream]
+    def start_stream(call_sid, **kwargs)
+      data = @transport.request(:post, path('Calls', call_sid, 'Streams'),
+                                form: form_params(START_STREAM_FIELDS, kwargs))
+      Stream.from_hash(data)
+    end
+
+    # @return [VoiceML::Stream]
+    def get_stream(call_sid, stream_sid)
+      Stream.from_hash(@transport.request(:get, path('Calls', call_sid, 'Streams', stream_sid)))
+    end
+
+    # @return [VoiceML::Stream]
+    def stop_stream(call_sid, stream_sid)
+      data = @transport.request(:post, path('Calls', call_sid, 'Streams', stream_sid),
+                                form: { 'Status' => 'stopped' })
+      Stream.from_hash(data)
+    end
+
+    # --- SIPREC ---
+
+    # @return [VoiceML::SiprecList]
+    def list_siprec(call_sid)
+      SiprecList.from_hash(@transport.request(:get, path('Calls', call_sid, 'Siprec')))
+    end
+
+    # @return [VoiceML::SiprecSession]
+    def start_siprec(call_sid, **kwargs)
+      data = @transport.request(:post, path('Calls', call_sid, 'Siprec'),
+                                form: form_params(START_SIPREC_FIELDS, kwargs))
+      SiprecSession.from_hash(data)
+    end
+
+    # @return [VoiceML::SiprecSession]
+    def get_siprec(call_sid, siprec_sid)
+      SiprecSession.from_hash(
+        @transport.request(:get, path('Calls', call_sid, 'Siprec', siprec_sid))
+      )
+    end
+
+    # @return [VoiceML::SiprecSession]
+    def stop_siprec(call_sid, siprec_sid)
+      data = @transport.request(:post, path('Calls', call_sid, 'Siprec', siprec_sid),
+                                form: { 'Status' => 'stopped' })
+      SiprecSession.from_hash(data)
+    end
+
+    # --- Transcriptions ---
+
+    # @return [VoiceML::TranscriptionList]
+    def list_transcriptions(call_sid)
+      TranscriptionList.from_hash(
+        @transport.request(:get, path('Calls', call_sid, 'Transcriptions'))
+      )
+    end
+
+    # @return [VoiceML::CallTranscription]
+    def start_transcription(call_sid, **kwargs)
+      data = @transport.request(:post, path('Calls', call_sid, 'Transcriptions'),
+                                form: form_params(START_TRANSCRIPTION_FIELDS, kwargs))
+      CallTranscription.from_hash(data)
+    end
+
+    # @return [VoiceML::CallTranscription]
+    def get_transcription(call_sid, transcription_sid)
+      CallTranscription.from_hash(
+        @transport.request(:get, path('Calls', call_sid, 'Transcriptions', transcription_sid))
+      )
+    end
+
+    # @return [VoiceML::CallTranscription]
+    def stop_transcription(call_sid, transcription_sid)
+      data = @transport.request(:post,
+                                path('Calls', call_sid, 'Transcriptions', transcription_sid),
+                                form: { 'Status' => 'stopped' })
+      CallTranscription.from_hash(data)
+    end
+
+    # --- Notifications / Events (compat stubs) ---
+
+    # @return [VoiceML::NotificationsList]
+    def list_notifications(call_sid, **kwargs)
+      NotificationsList.from_hash(
+        @transport.request(:get, path('Calls', call_sid, 'Notifications'),
+                           params: form_params(LIST_NOTIFICATIONS_FIELDS, kwargs))
+      )
+    end
+
+    # @return [Hash]
+    def get_notification(call_sid, notification_sid)
+      @transport.request(:get, path('Calls', call_sid, 'Notifications', notification_sid))
+    end
+
+    # @return [VoiceML::EventsList]
+    def list_events(call_sid, **kwargs)
+      EventsList.from_hash(
+        @transport.request(:get, path('Calls', call_sid, 'Events'),
+                           params: form_params(LIST_STUB_PAGE_FIELDS, kwargs))
+      )
+    end
+
+    # `POST /Calls/{sid}/UserDefinedMessages` — always raises `NotImplementedAPIError`.
+    # Mounted on the server only as a 501 stub. The SDK forwards the call so callers get a
+    # clean exception rather than discovering at runtime that the endpoint doesn't exist.
+    def send_user_defined_message(call_sid, payload = nil)
+      @transport.request(:post, path('Calls', call_sid, 'UserDefinedMessages'),
+                         form: payload)
+    end
+
+    # --- Payments (the REST companion to the `<Pay>` TwiML verb) ---
+
+    # Begin a `<Pay>` session on the live call. Returns the freshly-minted
+    # CallPayment. Returns 403 when the tenant is not `pay_enabled` or has no
+    # `stripe_secret_key` configured.
+    #
+    # `idempotency_key:` is accepted and persisted for diagnostic visibility but
+    # replay-dedup is NOT enforced today.
+    #
+    # @return [VoiceML::CallPayment]
+    def start_payment(call_sid, **kwargs)
+      data = @transport.request(:post, path('Calls', call_sid, 'Payments'),
+                                form: form_params(START_PAYMENT_FIELDS, kwargs))
+      CallPayment.from_hash(data)
+    end
+
+    # Advance or terminate an existing Pay session. `status: "complete"`
+    # captures the collected fields; `status: "cancel"` aborts the session.
+    # `capture: ...` tells the runtime which input the user is about to type
+    # next.
+    #
+    # @return [VoiceML::CallPayment]
+    def update_payment(call_sid, payment_sid, **kwargs)
+      data = @transport.request(:post, path('Calls', call_sid, 'Payments', payment_sid),
+                                form: form_params(UPDATE_PAYMENT_FIELDS, kwargs))
+      CallPayment.from_hash(data)
+    end
+  end
+end

data/lib/voiceml/resources/conferences.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../models/conferences'
+require_relative '../models/recordings'
+
+module VoiceML
+  # Operations on `/Conferences` and their participants/recordings.
+  class ConferencesResource < BaseResource
+    UPDATE_PARTICIPANT_FIELDS = {
+      'Muted' => :muted,
+      'Hold'  => :hold
+    }.freeze
+
+    LIST_FIELDS = {
+      'FriendlyName' => :friendly_name,
+      'Status'       => :status,
+      'DateCreated'  => :date_created,
+      'DateCreated<' => :date_created_lt,
+      'DateCreated>' => :date_created_gt,
+      'DateUpdated'  => :date_updated,
+      'DateUpdated<' => :date_updated_lt,
+      'DateUpdated>' => :date_updated_gt,
+      'Page'         => :page,
+      'PageSize'     => :page_size,
+      'PageToken'    => :page_token
+    }.freeze
+
+    CREATE_PARTICIPANT_FIELDS = {
+      'From'                   => :from,
+      'To'                     => :to,
+      'Label'                  => :label,
+      'Muted'                  => :muted,
+      'StartConferenceOnEnter' => :start_conference_on_enter,
+      'EndConferenceOnExit'    => :end_conference_on_exit,
+      'Timeout'                => :timeout,
+      'StatusCallback'         => :status_callback,
+      'StatusCallbackMethod'   => :status_callback_method,
+      'StatusCallbackEvent'    => :status_callback_event
+    }.freeze
+
+    UPDATE_RECORDING_FIELDS = {
+      'Status' => :status
+    }.freeze
+
+    LIST_PARTICIPANTS_FIELDS = {
+      'Muted'    => :muted,
+      'Hold'     => :hold,
+      'Coaching' => :coaching,
+      'Page'     => :page,
+      'PageSize' => :page_size,
+      'PageToken' => :page_token
+    }.freeze
+
+    LIST_CALL_RECORDINGS_FIELDS = {
+      'DateCreated'   => :date_created,
+      'DateCreated<'  => :date_created_lt,
+      'DateCreated>'  => :date_created_gt,
+      'Page'          => :page,
+      'PageSize'      => :page_size,
+      'PageToken'     => :page_token
+    }.freeze
+
+    # @return [VoiceML::ConferenceList]
+    def list(**kwargs)
+      ConferenceList.from_hash(
+        @transport.request(:get, path('Conferences'), params: form_params(LIST_FIELDS, kwargs))
+      )
+    end
+
+    # @yield [VoiceML::Conference]
+    # @return [Enumerator<VoiceML::Conference>] 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.conferences.each(&block)
+        break if chunk.next_page_uri.nil? || chunk.next_page_uri.empty? || chunk.conferences.empty?
+        page_num += 1
+      end
+    end
+
+    # @return [VoiceML::Conference]
+    def get(conference_sid)
+      Conference.from_hash(@transport.request(:get, path('Conferences', conference_sid)))
+    end
+
+    # End a live conference. v1 supports only `status: "completed"`.
+    # @return [VoiceML::Conference]
+    def end_conference(conference_sid, status: 'completed')
+      data = @transport.request(:post, path('Conferences', conference_sid),
+                                form: { 'Status' => status })
+      Conference.from_hash(data)
+    end
+
+    # --- Participants ---
+
+    # @return [VoiceML::ParticipantList]
+    def list_participants(conference_sid, **kwargs)
+      ParticipantList.from_hash(
+        @transport.request(:get, path('Conferences', conference_sid, 'Participants'),
+                           params: form_params(LIST_PARTICIPANTS_FIELDS, kwargs))
+      )
+    end
+
+    # @return [VoiceML::Participant]
+    def get_participant(conference_sid, call_sid)
+      Participant.from_hash(
+        @transport.request(:get, path('Conferences', conference_sid, 'Participants', call_sid))
+      )
+    end
+
+    # Mute/unmute or hold/unhold a participant. At least one of `muted:` / `hold:` must be set.
+    # @return [VoiceML::Participant]
+    def update_participant(conference_sid, call_sid, **kwargs)
+      data = @transport.request(
+        :post,
+        path('Conferences', conference_sid, 'Participants', call_sid),
+        form: form_params(UPDATE_PARTICIPANT_FIELDS, kwargs)
+      )
+      Participant.from_hash(data)
+    end
+
+    # @return [nil]
+    def kick_participant(conference_sid, call_sid)
+      @transport.request(:delete,
+                         path('Conferences', conference_sid, 'Participants', call_sid))
+      nil
+    end
+
+    # Dial a leg into a conference.
+    # @return [VoiceML::Participant]
+    def create_participant(conference_sid, from:, to:, **kwargs)
+      kwargs = kwargs.merge(from: from, to: to)
+      data = @transport.request(
+        :post,
+        path('Conferences', conference_sid, 'Participants'),
+        form: form_params(CREATE_PARTICIPANT_FIELDS, kwargs)
+      )
+      Participant.from_hash(data)
+    end
+
+    # --- Recordings ---
+
+    # @return [VoiceML::RecordingList]
+    def list_recordings(conference_sid, **kwargs)
+      RecordingList.from_hash(
+        @transport.request(:get, path('Conferences', conference_sid, 'Recordings'),
+                           params: form_params(LIST_CALL_RECORDINGS_FIELDS, kwargs))
+      )
+    end
+
+    # @return [VoiceML::Recording]
+    def get_recording(conference_sid, recording_sid)
+      Recording.from_hash(
+        @transport.request(:get, path('Conferences', conference_sid, 'Recordings', recording_sid))
+      )
+    end
+
+    # @return [VoiceML::Recording]
+    def update_recording(conference_sid, recording_sid, **kwargs)
+      data = @transport.request(
+        :post,
+        path('Conferences', conference_sid, 'Recordings', recording_sid),
+        form: form_params(UPDATE_RECORDING_FIELDS, kwargs)
+      )
+      Recording.from_hash(data)
+    end
+
+    # @return [nil]
+    def delete_recording(conference_sid, recording_sid)
+      @transport.request(:delete, path('Conferences', conference_sid, 'Recordings', recording_sid))
+      nil
+    end
+  end
+end

data/lib/voiceml/resources/diagnostics.rb

@@ -0,0 +1,64 @@
+# 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: []`).
+  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`.
+    #
+    # @return [VoiceML::HealthStatus]
+    def health
+      HealthStatus.from_hash(unauth_request('/health'))
+    end
+
+    # Fetch the OpenAPI spec as parsed JSON.
+    #
+    # @return [Hash]
+    def openapi_json
+      unauth_request('/openapi.json')
+    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?
+
+      JSON.parse(response.body)
+    end
+  end
+end