voiceml 0.8.1 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15e4cbe52a1e5c8c9373bc3b9f636c5637915cf7827abd08c87512998f7fafe4
-  data.tar.gz: bc844da7b2b3289c072d7f5b3ef130a90eace33a0fa7f1794235e3bb096b986c
+  metadata.gz: ce6f40c38ff553e748881a1b57f940e977cd24983da928988a7dcc77640cc32d
+  data.tar.gz: d6d26a2ab6ee10d9df572f24c6b667cb87cb03bb68ef40234fb05308db3d3789
 SHA512:
-  metadata.gz: fa0180df722300f7dc736fb67eccd89fd2369c8528d43569eb06e369321d75989a4daee80612c8899354e163ee99fbeda8092bef2e6d561670a94b872fa0b8dc
-  data.tar.gz: a1ca825eac62aa31cb2367340e666a521251055500d0736975ff4a6f5061d9e4e6254d5c4b0e7d643f523cbd03029dc5b4e9840bfd22b7cf07c42775d23ae8fb
+  metadata.gz: 28fe625cbe02ccd47894507e8c28d8eecd06f0caae4aea040f5e21af82980072e39a74aa7cb788fc885f9b24e58239099a87dac639a79b9f3a3c248769e0a652
+  data.tar.gz: 85fd838a671b848768a791d590fbcdefa40c49e89d80b8f2c2c98f475af7035489a727ca3d1ecd7e5988296a5a62f32e3784344fc9fcc11f24beec16d5d9619e

data/README.md

@@ -1,11 +1,11 @@
 # 📞 VoiceML Ruby SDK
 
-The official Ruby client for the [VoiceML REST API](https://voicetel.com/docs/api/v0.7/voiceml/) — Twilio-compatible outbound voice and answering-machine-detection from VoiceTel, with idiomatic snake_case kwargs, structured errors, and a Twilio-compatible wire format.
+The official Ruby client for the [VoiceML REST API](https://voicetel.com/docs/api/v0.9/voiceml/) — Twilio-compatible outbound voice and answering-machine-detection from VoiceTel, with idiomatic snake_case kwargs, structured errors, and a Twilio-compatible wire format.
 
-![Version](https://img.shields.io/badge/version-0.8.1-blue)
+![Version](https://img.shields.io/badge/version-0.9.2-blue)
 ![Ruby](https://img.shields.io/badge/ruby-3.0%2B-red)
 ![License](https://img.shields.io/badge/license-MIT-green)
-![Tests](https://img.shields.io/badge/tests-65%20specs-brightgreen)
+![Tests](https://img.shields.io/badge/tests-188%20examples-brightgreen)
 ![Gem](https://img.shields.io/badge/gem-voiceml-blue)
 
 ## 📚 Table of Contents
@@ -49,10 +49,15 @@ The official Ruby client for the [VoiceML REST API](https://voicetel.com/docs/ap
 - **Notifications** — fetch, list.
 - **SIP** — SIP Trunking: Domains (CRUD), CredentialLists + Credentials (CRUD), IpAccessControlLists + IpAddresses (CRUD), Domain↔ACL/CredentialList mappings (historical, Auth/Calls, Auth/Registrations namespaces).
 - **Routes V2** — Twilio Inbound Processing Region API: `client.routes_v2.sip_domains.fetch(name)` / `update(name, voice_region:, friendly_name:)`.
+- **Messaging Service** — `client.messaging_v1.services` CRUD (`MG...` services), routed automatically at the `messaging.voicetel.com` product host.
+- **Pricing** — read-only `client.pricing.v1` / `client.pricing.v2` for Voice, Messaging, PhoneNumbers, and Trunking country + number lookups.
 - **Diagnostics** — `/health` deep probe, OpenAPI spec.
 
+### 🌐 Per-product hosts
+VoiceML mirrors Twilio's product-per-subdomain model. The whole `conversations_v1` group is routed to `conversations.voicetel.com` and `messaging_v1` to `messaging.voicetel.com`, while everything else stays on the default `voiceml.voicetel.com`. These hosts are derived automatically from `base_url`; a non-`voicetel.com` base (e.g. a self-hosted instance) keeps every product on that single host. Override per product with `messaging_base_url:` / `conversations_base_url:` on the client constructor.
+
 ### 🧪 Tested
-- **81 specs** with mocked HTTP layer (`webmock`) covering every resource and pagination edge cases — spec drift gets caught at parse time.
+- **188 examples** with mocked HTTP layer (`webmock`) covering every resource and pagination edge cases — spec drift gets caught at parse time.
 - Integration smoke spec gated by env vars — safe for CI.
 
 ### 📦 Clean Distribution
@@ -110,7 +115,7 @@ client = VoiceML::Client.new(account_sid: 'AC...', api_key: '...')
 client.diagnostics.health  # uses your AccountSid + key on every call
 ```
 
-> Don't have credentials yet? See **[voicetel.com/docs/api/v0.7/voiceml/](https://voicetel.com/docs/api/v0.7/voiceml/)** for issuance and rotation.
+> Don't have credentials yet? See **[voicetel.com/docs/api/v0.9/voiceml/](https://voicetel.com/docs/api/v0.9/voiceml/)** for issuance and rotation.
 
 ## 🗺️ Resource Reference
 
@@ -124,6 +129,8 @@ client.diagnostics.health  # uses your AccountSid + key on every call
 | `client.messages` | create, fetch, list, update, delete | To/From/DateSent filters; Body redaction; Status=canceled |
 | `client.incoming_phone_numbers` | list, fetch, update | |
 | `client.notifications` | fetch, list | |
+| `client.messaging_v1.services` | create, list, fetch, update, delete | Messaging Service (`MG...`); routed at `messaging.voicetel.com` |
+| `client.pricing.v1` / `.v2` | countries.list / fetch, numbers.fetch | Voice, Messaging, PhoneNumbers, Trunking (read-only, default host) |
 | `client.diagnostics` | `/health`, OpenAPI spec | |
 
 Methods accept idiomatic snake_case keyword arguments — they're translated to Twilio's PascalCase wire field names internally:
@@ -245,7 +252,7 @@ gem build voiceml.gemspec
 
 ## 📖 API Documentation
 
-- **Reference docs:** [voicetel.com/docs/api/v0.7/voiceml/](https://voicetel.com/docs/api/v0.7/voiceml/)
+- **Reference docs:** [voicetel.com/docs/api/v0.9/voiceml/](https://voicetel.com/docs/api/v0.9/voiceml/)
 - **Validator:** [voicetel.com/voiceml/validator/](https://voicetel.com/voiceml/validator/)
 - **SDK catalogue:** [voicetel.com/docs/voiceml-sdks/](https://voicetel.com/docs/voiceml-sdks/)
 - **YARD comments:** every resource method carries `@param` / `@return` docs — `yard doc lib` builds them locally.

data/lib/voiceml/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'transport'
+require_relative 'hosts'
 require_relative 'resources/calls'
 require_relative 'resources/conferences'
 require_relative 'resources/queues'
@@ -12,6 +13,11 @@ require_relative 'resources/diagnostics'
 require_relative 'resources/messages'
 require_relative 'resources/sip'
 require_relative 'resources/routes_v2'
+require_relative 'resources/voice_v1'
+require_relative 'resources/conversations_v1'
+require_relative 'resources/assistants_v1'
+require_relative 'resources/messaging_v1'
+require_relative 'resources/pricing'
 
 module VoiceML
   # Synchronous client for the VoiceML REST API.
@@ -31,7 +37,8 @@ module VoiceML
   class Client
     attr_reader :calls, :conferences, :queues, :applications, :recordings,
                 :incoming_phone_numbers, :notifications, :diagnostics, :messages,
-                :sip, :routes_v2
+                :sip, :routes_v2, :voice_v1, :conversations_v1, :assistants_v1,
+                :messaging_v1, :pricing
 
     # @param account_sid [String] Twilio-format AccountSid (`AC` + 32 hex).
     # @param api_key     [String, nil] per-tenant API key. Pass either `api_key:` or the
@@ -43,11 +50,16 @@ module VoiceML
     # @param max_retries [Integer] retry attempts for 429/5xx and transport errors. Defaults to 2.
     # @param user_agent  [String, nil] override the `User-Agent` header. Defaults to
     #   `"voiceml-ruby/#{VERSION}"`.
+    # @param messaging_base_url     [String, nil] override the host for `messaging_v1`. Defaults to
+    #   the `messaging.*.voicetel.com` subdomain derived from `base_url` (else `base_url` itself).
+    # @param conversations_base_url [String, nil] override the host for `conversations_v1`. Defaults
+    #   to the `conversations.*.voicetel.com` subdomain derived from `base_url` (else `base_url`).
     def initialize(account_sid:, api_key: nil, auth_token: nil,
                    base_url: Transport::DEFAULT_BASE_URL,
                    timeout: Transport::DEFAULT_TIMEOUT,
                    max_retries: Transport::DEFAULT_MAX_RETRIES,
-                   user_agent: nil, http_client: nil)
+                   user_agent: nil, http_client: nil,
+                   messaging_base_url: nil, conversations_base_url: nil)
       if !api_key.nil? && !auth_token.nil?
         raise ArgumentError, 'pass either api_key: or auth_token:, not both'
       end
@@ -64,6 +76,16 @@ module VoiceML
         http_client: http_client
       )
 
+      # VoiceML mirrors Twilio's product-per-subdomain model: the whole Conversations group
+      # rides `conversations.voicetel.com` and Messaging Service rides `messaging.voicetel.com`,
+      # while everything else stays on the default host. See VoiceML::Hosts.
+      _default, messaging_host, conversations_host =
+        Hosts.resolve_product_base_urls(base_url,
+                                        messaging_base_url: messaging_base_url,
+                                        conversations_base_url: conversations_base_url)
+      messaging_transport     = ScopedTransport.new(@transport, messaging_host)
+      conversations_transport = ScopedTransport.new(@transport, conversations_host)
+
       @calls                  = CallsResource.new(@transport)
       @conferences            = ConferencesResource.new(@transport)
       @queues                 = QueuesResource.new(@transport)
@@ -75,6 +97,11 @@ module VoiceML
       @messages               = MessagesResource.new(@transport)
       @sip                    = SipResource.new(@transport)
       @routes_v2              = RoutesV2Resource.new(@transport)
+      @voice_v1               = VoiceV1Resource.new(@transport)
+      @conversations_v1       = ConversationsV1Resource.new(conversations_transport)
+      @assistants_v1          = AssistantsV1Resource.new(@transport)
+      @messaging_v1           = MessagingV1Resource.new(messaging_transport)
+      @pricing                = PricingResource.new(@transport)
     end
 
     def account_sid

data/lib/voiceml/hosts.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+require_relative 'transport'
+
+module VoiceML
+  # Per-product host resolution for the VoiceML API.
+  #
+  # Twilio splits its products across dedicated subdomains (`api.twilio.com`,
+  # `conversations.twilio.com`, `messaging.twilio.com`, ...). VoiceML mirrors that
+  # shape on `voicetel.com`: the Conversations product answers on
+  # `conversations.voicetel.com` and the Messaging Service product on
+  # `messaging.voicetel.com`, while everything else stays on the default
+  # `voiceml.voicetel.com` host. Conversation Service and Messaging Service share
+  # the identical `/v1/Services` path shape, so the *host* is what disambiguates
+  # them on the wire.
+  #
+  # Given the configured `base_url` this module derives the two product hosts by
+  # swapping the leftmost `voiceml` label — but only for recognised
+  # `*.voicetel.com` hosts. For any other base URL (a self-hosted callBroadcast
+  # instance, a test stub, a regional override) the product hosts fall back to the
+  # configured host unchanged, so a single-host deployment keeps working. A caller
+  # who needs Messaging Service against a custom host points `messaging_base_url`
+  # (or `conversations_base_url`) at their own subdomain explicitly.
+  module Hosts
+    module_function
+
+    # Swap the `voiceml` label of a `*.voicetel.com` host for `product`.
+    #
+    # Returns `base_url` unchanged when the host is not a `voiceml.*.voicetel.com`
+    # style host (e.g. a self-hosted instance), so single-host deployments keep
+    # working without special-casing.
+    def derive_product_host(base_url, product)
+      uri = URI.parse(base_url)
+      host = uri.host
+      return base_url if host.nil? || !host.end_with?('.voicetel.com')
+
+      labels = host.split('.')
+      idx = labels.index('voiceml')
+      return base_url if idx.nil?
+
+      labels[idx] = product
+      uri.host = labels.join('.')
+      uri.query = nil
+      uri.fragment = nil
+      uri.to_s
+    end
+
+    # Return `[default, messaging, conversations]` base URLs.
+    #
+    # Explicit overrides win; otherwise each product host is derived from
+    # `base_url` (see module docstring). All three are returned without a
+    # trailing slash.
+    def resolve_product_base_urls(base_url, messaging_base_url: nil, conversations_base_url: nil)
+      default       = Transport.strip_trailing_slashes(base_url)
+      messaging     = Transport.strip_trailing_slashes(messaging_base_url || derive_product_host(default, 'messaging'))
+      conversations = Transport.strip_trailing_slashes(conversations_base_url || derive_product_host(default, 'conversations'))
+      [default, messaging, conversations]
+    end
+  end
+end

data/lib/voiceml/models/accounts.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'common'
+
+module VoiceML
+  # Twilio-compatible Account resource. The voiceml SDK is single-account
+  # (the credential's account is implicit on every call), so this model
+  # exists primarily to decode `GET/POST /Accounts/{Sid}.json` responses
+  # round-trip with the Twilio shape — useful for migration tooling that
+  # echoes the account record back to the caller.
+  class Account
+    ATTRIBUTES = %w[
+      sid friendly_name status type auth_token owner_account_sid
+      date_created date_updated subresource_uris uri
+    ].freeze
+
+    attr_reader(*ATTRIBUTES.map(&:to_sym))
+
+    def initialize(attrs = {})
+      ATTRIBUTES.each do |field|
+        value = attrs.key?(field) ? attrs[field] : attrs[field.to_sym]
+        instance_variable_set("@#{field}", value)
+      end
+    end
+
+    def self.from_hash(hash)
+      return nil if hash.nil?
+
+      new(hash)
+    end
+  end
+
+  # `GET /Accounts/{Sid}/Balance.json` — running balance for the account in
+  # the account's settlement currency. No `sid` field on the wire (the
+  # balance is account-scoped, not its own resource).
+  class Balance
+    ATTRIBUTES = %w[account_sid balance currency].freeze
+
+    attr_reader(*ATTRIBUTES.map(&:to_sym))
+
+    def initialize(attrs = {})
+      ATTRIBUTES.each do |field|
+        value = attrs.key?(field) ? attrs[field] : attrs[field.to_sym]
+        instance_variable_set("@#{field}", value)
+      end
+    end
+
+    def self.from_hash(hash)
+      return nil if hash.nil?
+
+      new(hash)
+    end
+  end
+end

data/lib/voiceml/models/assistants_v1.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require_relative 'common'
+require_relative 'voice_v1' # V1Pageable lives here; Assistants v1 reuses the same `meta` envelope
+
+module VoiceML
+  # Assistants v1 (`/v1/Assistants`, `/v1/Tools`, `/v1/Knowledge`, `/v1/Sessions`,
+  # `/v1/Policies`) — Twilio AI-Assistants surface. Same /v1 conventions as Voice v1
+  # and Conversations v1: Basic-auth account resolution, ISO-8601 dates, `meta`
+  # list envelope (V1Pageable). 7 families for v0.9.1:
+  #   - Assistant (aia_asst_...)
+  #   - Tool (aia_tool_...) + ToolWithPolicies fetch shape
+  #   - Knowledge (aia_know_...) + KnowledgeStatus + KnowledgeChunk
+  #   - Session
+  #   - Message (aia_msg_...) + SendMessageResponse
+  #   - Feedback (aia_fdbk_...)
+  #   - Policy (aia_plcy_...)
+
+  # AssistantsV1Assistant — `aia_asst_...`. Used by list/create/update/delete responses.
+  class AssistantsV1Assistant
+    ATTRIBUTES = %w[
+      account_sid customer_ai id model name owner url personality_prompt
+      date_created date_updated
+    ].freeze
+    attr_reader(*ATTRIBUTES.map(&:to_sym))
+    def initialize(attrs = {})
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
+    end
+    def self.from_hash(h); h.nil? ? nil : new(h); end
+  end
+
+  class AssistantsV1AssistantList
+    include V1Pageable
+    attr_reader :assistants
+    def initialize(hash = {})
+      assign_meta_fields(hash)
+      @assistants = (hash['assistants'] || []).map { |h| AssistantsV1Assistant.from_hash(h) }
+    end
+  end
+
+  # AssistantsV1AssistantWithToolsAndKnowledge — fetch-one shape that includes the
+  # attached tools and knowledge arrays inline.
+  class AssistantsV1AssistantWithToolsAndKnowledge
+    ATTRIBUTES = %w[
+      account_sid customer_ai id model name owner url personality_prompt
+      date_created date_updated tools knowledge
+    ].freeze
+    attr_reader(*ATTRIBUTES.map(&:to_sym))
+    def initialize(attrs = {})
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
+    end
+    def self.from_hash(h); h.nil? ? nil : new(h); end
+  end
+
+  # AssistantsV1Tool — `aia_tool_...`.
+  class AssistantsV1Tool
+    ATTRIBUTES = %w[
+      account_sid description enabled id meta name requires_auth type url
+      date_created date_updated
+    ].freeze
+    attr_reader(*ATTRIBUTES.map(&:to_sym))
+    def initialize(attrs = {})
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
+    end
+    def self.from_hash(h); h.nil? ? nil : new(h); end
+  end
+
+  class AssistantsV1ToolList
+    include V1Pageable
+    attr_reader :tools
+    def initialize(hash = {})
+      assign_meta_fields(hash)
+      @tools = (hash['tools'] || []).map { |h| AssistantsV1Tool.from_hash(h) }
+    end
+  end
+
+  # AssistantsV1ToolWithPolicies — fetch-one shape that includes the policies array inline.
+  class AssistantsV1ToolWithPolicies
+    ATTRIBUTES = %w[
+      account_sid description enabled id meta name requires_auth type url
+      date_created date_updated policies
+    ].freeze
+    attr_reader(*ATTRIBUTES.map(&:to_sym))
+    def initialize(attrs = {})
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
+    end
+    def self.from_hash(h); h.nil? ? nil : new(h); end
+  end
+
+  # AssistantsV1Knowledge — `aia_know_...`.
+  class AssistantsV1Knowledge
+    ATTRIBUTES = %w[
+      account_sid description id knowledge_source_details name status type url
+      embedding_model date_created date_updated
+    ].freeze
+    attr_reader(*ATTRIBUTES.map(&:to_sym))
+    def initialize(attrs = {})
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
+    end
+    def self.from_hash(h); h.nil? ? nil : new(h); end
+  end
+
+  class AssistantsV1KnowledgeList
+    include V1Pageable
+    attr_reader :knowledge
+    def initialize(hash = {})
+      assign_meta_fields(hash)
+      @knowledge = (hash['knowledge'] || []).map { |h| AssistantsV1Knowledge.from_hash(h) }
+    end
+  end
+
+  # AssistantsV1KnowledgeStatus — read-only ingestion status snapshot.
+  class AssistantsV1KnowledgeStatus
+    ATTRIBUTES = %w[account_sid status last_status date_updated].freeze
+    attr_reader(*ATTRIBUTES.map(&:to_sym))
+    def initialize(attrs = {})
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
+    end
+    def self.from_hash(h); h.nil? ? nil : new(h); end
+  end
+
+  # AssistantsV1KnowledgeChunk — single retrieved chunk of indexed Knowledge content.
+  class AssistantsV1KnowledgeChunk
+    ATTRIBUTES = %w[account_sid content metadata date_created date_updated].freeze
+    attr_reader(*ATTRIBUTES.map(&:to_sym))
+    def initialize(attrs = {})
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
+    end
+    def self.from_hash(h); h.nil? ? nil : new(h); end
+  end
+
+  class AssistantsV1KnowledgeChunkList
+    include V1Pageable
+    attr_reader :chunks
+    def initialize(hash = {})
+      assign_meta_fields(hash)
+      @chunks = (hash['chunks'] || []).map { |h| AssistantsV1KnowledgeChunk.from_hash(h) }
+    end
+  end
+
+  # AssistantsV1Session — a chat session between an identity and an Assistant.
+  class AssistantsV1Session
+    ATTRIBUTES = %w[
+      id account_sid assistant_id verified identity date_created date_updated
+    ].freeze
+    attr_reader(*ATTRIBUTES.map(&:to_sym))
+    def initialize(attrs = {})
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
+    end
+    def self.from_hash(h); h.nil? ? nil : new(h); end
+  end
+
+  class AssistantsV1SessionList
+    include V1Pageable
+    attr_reader :sessions
+    def initialize(hash = {})
+      assign_meta_fields(hash)
+      @sessions = (hash['sessions'] || []).map { |h| AssistantsV1Session.from_hash(h) }
+    end
+  end
+
+  # AssistantsV1Message — `aia_msg_...`. One message in an Assistant session.
+  class AssistantsV1Message
+    ATTRIBUTES = %w[
+      id account_sid assistant_id session_id identity role content meta
+      date_created date_updated
+    ].freeze
+    attr_reader(*ATTRIBUTES.map(&:to_sym))
+    def initialize(attrs = {})
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
+    end
+    def self.from_hash(h); h.nil? ? nil : new(h); end
+  end
+
+  class AssistantsV1MessageList
+    include V1Pageable
+    attr_reader :messages
+    def initialize(hash = {})
+      assign_meta_fields(hash)
+      @messages = (hash['messages'] || []).map { |h| AssistantsV1Message.from_hash(h) }
+    end
+  end
+
+  # AssistantsV1SendMessageResponse — POST /v1/Assistants/{id}/Messages return shape.
+  # Distinct from AssistantsV1Message: carries the model's reply body + flag/abort signals.
+  class AssistantsV1SendMessageResponse
+    ATTRIBUTES = %w[status flagged aborted session_id account_sid body error].freeze
+    attr_reader(*ATTRIBUTES.map(&:to_sym))
+    def initialize(attrs = {})
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
+    end
+    def self.from_hash(h); h.nil? ? nil : new(h); end
+  end
+
+  # AssistantsV1Feedback — `aia_fdbk_...`. Numeric score + text feedback on a message.
+  class AssistantsV1Feedback
+    ATTRIBUTES = %w[
+      assistant_id id account_sid user_sid message_id score session_id text
+      date_created date_updated
+    ].freeze
+    attr_reader(*ATTRIBUTES.map(&:to_sym))
+    def initialize(attrs = {})
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
+    end
+    def self.from_hash(h); h.nil? ? nil : new(h); end
+  end
+
+  class AssistantsV1FeedbackList
+    include V1Pageable
+    attr_reader :feedbacks
+    def initialize(hash = {})
+      assign_meta_fields(hash)
+      @feedbacks = (hash['feedbacks'] || []).map { |h| AssistantsV1Feedback.from_hash(h) }
+    end
+  end
+
+  # AssistantsV1Policy — `aia_plcy_...`. Read-only — listed under /v1/Policies (filterable
+  # by ToolId/KnowledgeId) and embedded inline on Tool fetch responses.
+  class AssistantsV1Policy
+    ATTRIBUTES = %w[
+      id name description account_sid user_sid type policy_details
+      date_created date_updated
+    ].freeze
+    attr_reader(*ATTRIBUTES.map(&:to_sym))
+    def initialize(attrs = {})
+      ATTRIBUTES.each { |f| instance_variable_set("@#{f}", attrs.key?(f) ? attrs[f] : attrs[f.to_sym]) }
+    end
+    def self.from_hash(h); h.nil? ? nil : new(h); end
+  end
+
+  class AssistantsV1PolicyList
+    include V1Pageable
+    attr_reader :policies
+    def initialize(hash = {})
+      assign_meta_fields(hash)
+      @policies = (hash['policies'] || []).map { |h| AssistantsV1Policy.from_hash(h) }
+    end
+  end
+end