telnyx 5.170.0 → 5.171.0

data/lib/telnyx/resources/enterprises/reputation/numbers.rb

@@ -50,14 +50,18 @@ module Telnyx
           # enterprise. The response includes the latest reputation snapshot per number
           # where one has been collected.
           #
-          # @overload list(enterprise_id, filter_phone_number_contains: nil, filter_phone_number_eq: nil, page_number: nil, page_size: nil, request_options: {})
+          # @overload list(enterprise_id, filter_ownership_status: nil, filter_phone_number_contains: nil, filter_phone_number_eq: nil, filter_source: nil, page_number: nil, page_size: nil, request_options: {})
           #
           # @param enterprise_id [String] The enterprise id. Lowercase UUID.
           #
+          # @param filter_ownership_status [Symbol, Telnyx::Models::Enterprises::Reputation::ReputationOwnershipStatus] Only numbers with this ownership status. `removed` lists the numbers that were r
+          #
           # @param filter_phone_number_contains [String] Partial match on phone number. Must contain at least 5 digits.
           #
           # @param filter_phone_number_eq [String] Exact phone-number match (E.164).
           #
+          # @param filter_source [Symbol, Telnyx::Models::Enterprises::Reputation::ReputationNumberSource] Only numbers with this source.
+          #
           # @param page_number [Integer] 1-based page number. Out-of-range values return an empty page with correct meta.
           #
           # @param page_size [Integer] Items per page. Default 10. Maximum 250; values above are clamped to 250.
@@ -74,8 +78,10 @@ module Telnyx
               method: :get,
               path: ["enterprises/%1$s/reputation/numbers", enterprise_id],
               query: query.transform_keys(
+                filter_ownership_status: "filter[ownership_status]",
                 filter_phone_number_contains: "filter[phone_number][contains]",
                 filter_phone_number_eq: "filter[phone_number][eq]",
+                filter_source: "filter[source]",
                 page_number: "page[number]",
                 page_size: "page[size]"
               ),
@@ -86,8 +92,9 @@ module Telnyx
           end
 
           # Add up to 100 phone numbers to reputation monitoring on this enterprise. Each
-          # must be in E.164 format (`+1NPANXXXXXX` for US/CA) and belong to your Telnyx
-          # phone-number inventory.
+          # must be in E.164 format (`+1NPANXXXXXX` for US/CA). A number in your Telnyx
+          # phone-number inventory is accepted as `source: telnyx`; a number that is not is
+          # treated as hosted with another provider and must meet the requirements below.
           #
           # **Prerequisite**: reputation must already be enabled on this enterprise (see
           # `POST .../reputation`).
@@ -95,6 +102,14 @@ module Telnyx
           # **Pricing:** This is a billable action. See https://telnyx.com/pricing/numbers
           # for current pricing.
           #
+          # A phone number that is not in your Telnyx inventory is treated as a number
+          # hosted with another provider (`source: external`). It must be a US local number,
+          # and the enterprise's ownership proof must be approved first
+          # (`POST /enterprises/{enterprise_id}/reputation/external_verification`);
+          # otherwise the request fails with a 400 whose `detail` contains
+          # `external_verification_required`. Ownership of such numbers is checked every
+          # day.
+          #
           # @overload associate(enterprise_id, phone_numbers:, request_options: {})
           #
           # @param enterprise_id [String] The enterprise id. Lowercase UUID.
@@ -149,6 +164,55 @@ module Telnyx
             )
           end
 
+          # Some parameter documentations has been truncated, see
+          # {Telnyx::Models::Enterprises::Reputation::NumberOwnershipConfirmParams} for more
+          # details.
+          #
+          # Answer an ownership question about a phone number hosted with another provider.
+          #
+          # Send `still_own: true` to confirm you still own a number whose
+          # `ownership_status` is `pending_confirmation` or `flagged`; its status returns to
+          # `verified` and, after a carrier change, the new carrier becomes the one on
+          # record.
+          #
+          # Send `still_own: false` to report that you no longer own the number. It is
+          # removed from Number Reputation immediately, whatever its current status, and the
+          # response shows it with `ownership_status: removed`.
+          #
+          # @overload ownership_confirm(phone_number, enterprise_id:, still_own:, evidence_document_id: nil, request_options: {})
+          #
+          # @param phone_number [String] Path param: Phone number in E.164 format (`+1NPANXXXXXX` for US/CA). The leading
+          #
+          # @param enterprise_id [String] Path param: The enterprise id. Lowercase UUID.
+          #
+          # @param still_own [Boolean] Body param: `true` confirms you still own the number. `false` reports that you n
+          #
+          # @param evidence_document_id [String] Body param: Optional id of an uploaded document supporting the confirmation.
+          #
+          # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Telnyx::Models::Enterprises::Reputation::ReputationPhoneNumberWithReputation]
+          #
+          # @see Telnyx::Models::Enterprises::Reputation::NumberOwnershipConfirmParams
+          def ownership_confirm(phone_number, params)
+            parsed, options = Telnyx::Enterprises::Reputation::NumberOwnershipConfirmParams.dump_request(params)
+            enterprise_id =
+              parsed.delete(:enterprise_id) do
+                raise ArgumentError.new("missing required path argument #{_1}")
+              end
+            @client.request(
+              method: :post,
+              path: [
+                "enterprises/%1$s/reputation/numbers/%2$s/ownership_confirm",
+                enterprise_id,
+                phone_number
+              ],
+              body: parsed,
+              model: Telnyx::Enterprises::Reputation::ReputationPhoneNumberWithReputation,
+              options: options
+            )
+          end
+
           # Some parameter documentations has been truncated, see
           # {Telnyx::Models::Enterprises::Reputation::NumberRefreshParams} for more details.
           #
@@ -182,6 +246,38 @@ module Telnyx
             )
           end
 
+          # Some parameter documentations has been truncated, see
+          # {Telnyx::Models::Enterprises::Reputation::NumberRetrieveOwnershipParams} for
+          # more details.
+          #
+          # Get the ownership status of a phone number, when it was last checked, the
+          # carrier recorded as its baseline, and the history of ownership events.
+          #
+          # @overload retrieve_ownership(phone_number, enterprise_id:, request_options: {})
+          #
+          # @param phone_number [String] Phone number in E.164 format (`+1NPANXXXXXX` for US/CA). The leading `+` MUST be
+          #
+          # @param enterprise_id [String] The enterprise id. Lowercase UUID.
+          #
+          # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Telnyx::Models::Enterprises::Reputation::NumberRetrieveOwnershipResponse]
+          #
+          # @see Telnyx::Models::Enterprises::Reputation::NumberRetrieveOwnershipParams
+          def retrieve_ownership(phone_number, params)
+            parsed, options = Telnyx::Enterprises::Reputation::NumberRetrieveOwnershipParams.dump_request(params)
+            enterprise_id =
+              parsed.delete(:enterprise_id) do
+                raise ArgumentError.new("missing required path argument #{_1}")
+              end
+            @client.request(
+              method: :get,
+              path: ["enterprises/%1$s/reputation/numbers/%2$s/ownership", enterprise_id, phone_number],
+              model: Telnyx::Models::Enterprises::Reputation::NumberRetrieveOwnershipResponse,
+              options: options
+            )
+          end
+
           # @api private
           #
           # @param client [Telnyx::Client]

data/lib/telnyx/resources/enterprises/reputation.rb

@@ -17,6 +17,10 @@ module Telnyx
         # @return [Telnyx::Resources::Enterprises::Reputation::Remediation]
         attr_reader :remediation
 
+        # Phone-number reputation monitoring (spam-score lookup and tracking).
+        # @return [Telnyx::Resources::Enterprises::Reputation::ExternalVerification]
+        attr_reader :external_verification
+
         # Phone Number Reputation tracks how your outbound caller-IDs are perceived (spam
         # risk, engagement, etc.) across the call-screening ecosystem. This endpoint reads
         # the enterprise-level settings: whether the product is enabled, the refresh
@@ -141,6 +145,36 @@ module Telnyx
           )
         end
 
+        # Some parameter documentations has been truncated, see
+        # {Telnyx::Models::Enterprises::ReputationUpdateWebhookParams} for more details.
+        #
+        # Set the HTTPS URL that receives number-ownership events for this enterprise:
+        # `number_reputation.number.flagged`, `number_reputation.number.removed` and
+        # `number_reputation.external_verification.status_changed`. Send
+        # `webhook_url: null` to stop receiving them.
+        #
+        # @overload update_webhook(enterprise_id, webhook_url:, request_options: {})
+        #
+        # @param enterprise_id [String] The enterprise id. Lowercase UUID.
+        #
+        # @param webhook_url [String, nil] HTTPS URL on a publicly routable host. Send `null` to stop receiving number-owne
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::Enterprises::EnterpriseReputationPublicWrapped]
+        #
+        # @see Telnyx::Models::Enterprises::ReputationUpdateWebhookParams
+        def update_webhook(enterprise_id, params)
+          parsed, options = Telnyx::Enterprises::ReputationUpdateWebhookParams.dump_request(params)
+          @client.request(
+            method: :patch,
+            path: ["enterprises/%1$s/reputation/webhook", enterprise_id],
+            body: parsed,
+            model: Telnyx::Enterprises::EnterpriseReputationPublicWrapped,
+            options: options
+          )
+        end
+
         # @api private
         #
         # @param client [Telnyx::Client]
@@ -149,6 +183,8 @@ module Telnyx
           @numbers = Telnyx::Resources::Enterprises::Reputation::Numbers.new(client: client)
           @loa = Telnyx::Resources::Enterprises::Reputation::Loa.new(client: client)
           @remediation = Telnyx::Resources::Enterprises::Reputation::Remediation.new(client: client)
+          @external_verification =
+            Telnyx::Resources::Enterprises::Reputation::ExternalVerification.new(client: client)
         end
       end
     end

data/lib/telnyx/resources/enterprises/verify_email.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Resources
+    class Enterprises
+      # Verify ownership of a DIR's authorizer email. A short code is emailed and
+      # confirmed; the email must be verified before references can be submitted.
+      class VerifyEmail
+        # Email a 6-digit code to the enterprise account's contact email to confirm
+        # ownership of that address.
+        #
+        # A BPO (Business Process Outsourcer) account has no DIR, so it proves ownership
+        # of its own contact email here rather than through a DIR. A BPO account cannot be
+        # approved for use until this contact email is verified.
+        #
+        # The code expires in 15 minutes. Requesting a new code invalidates any previous
+        # one. Resends are rate limited (a short cooldown plus a daily cap). Submit the
+        # code to `POST /enterprises/{enterprise_id}/verify_email/confirm`.
+        #
+        # @overload create(enterprise_id, request_options: {})
+        #
+        # @param enterprise_id [String] The enterprise id. Lowercase UUID.
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::Enterprises::EnterpriseEmailVerificationStatusWrapped]
+        #
+        # @see Telnyx::Models::Enterprises::VerifyEmailCreateParams
+        def create(enterprise_id, params = {})
+          @client.request(
+            method: :post,
+            path: ["enterprises/%1$s/verify_email", enterprise_id],
+            model: Telnyx::Enterprises::EnterpriseEmailVerificationStatusWrapped,
+            options: params[:request_options]
+          )
+        end
+
+        # Submit the 6-digit code that was emailed to the enterprise account's contact
+        # email. On success the contact email is marked verified.
+        #
+        # For security, any failure (wrong, expired, already-used, or too many attempts)
+        # returns the same generic message.
+        #
+        # @overload confirm(enterprise_id, code:, request_options: {})
+        #
+        # @param enterprise_id [String] The enterprise id. Lowercase UUID.
+        #
+        # @param code [String] The 6-digit code sent to the enterprise account's contact email.
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::Enterprises::EnterpriseEmailVerificationStatusWrapped]
+        #
+        # @see Telnyx::Models::Enterprises::VerifyEmailConfirmParams
+        def confirm(enterprise_id, params)
+          parsed, options = Telnyx::Enterprises::VerifyEmailConfirmParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: ["enterprises/%1$s/verify_email/confirm", enterprise_id],
+            body: parsed,
+            model: Telnyx::Enterprises::EnterpriseEmailVerificationStatusWrapped,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Telnyx::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/resources/enterprises.rb

@@ -13,6 +13,11 @@ module Telnyx
       # @return [Telnyx::Resources::Enterprises::Dir]
       attr_reader :dir
 
+      # Verify ownership of a DIR's authorizer email. A short code is emailed and
+      # confirmed; the email must be verified before references can be submitted.
+      # @return [Telnyx::Resources::Enterprises::VerifyEmail]
+      attr_reader :verify_email
+
       # Some parameter documentations has been truncated, see
       # {Telnyx::Models::EnterpriseCreateParams} for more details.
       #
@@ -38,15 +43,15 @@ module Telnyx
       #
       # @param country_code [String] ISO 3166-1 alpha-2 country code. Currently `US` and `CA` are supported.
       #
-      # @param doing_business_as [String]
+      # @param doing_business_as [String] The trade name your business operates under if it is different from your legal n
       #
       # @param fein [String] US Federal Employer Identification Number (`NN-NNNNNNN`) or Canadian equivalent.
       #
-      # @param industry [Symbol, Telnyx::Models::EnterpriseCreateParams::Industry] Industry classification.
+      # @param industry [Symbol, Telnyx::Models::EnterpriseCreateParams::Industry] The industry your business operates in. Choose the closest match from the list;
       #
-      # @param jurisdiction_of_incorporation [String]
+      # @param jurisdiction_of_incorporation [String] The state, province, or country where your business was legally incorporated, fo
       #
-      # @param legal_name [String] Legal name of the enterprise.
+      # @param legal_name [String] Your business's full registered legal name, exactly as it appears on your incorp
       #
       # @param number_of_employees [Symbol, Telnyx::Models::EnterpriseCreateParams::NumberOfEmployees] Approximate headcount range. Used for vetting heuristics; pick the bucket that c
       #
@@ -58,19 +63,19 @@ module Telnyx
       #
       # @param organization_type [Symbol, Telnyx::Models::EnterpriseCreateParams::OrganizationType] Organization category for vetting purposes:
       #
-      # @param website [String]
+      # @param website [String] Your business's public website address, including https://. Leave blank if your
       #
-      # @param corporate_registration_number [String, nil] Optional corporate-registration / company-number identifier.
+      # @param corporate_registration_number [String, nil] The official number your company received when it was legally registered or inco
       #
-      # @param customer_reference [String] Optional free-form string the caller can attach for their own bookkeeping. Telny
+      # @param customer_reference [String] Your own label for this account. Enter any reference that helps you find it in y
       #
-      # @param dun_bradstreet_number [String, nil] Optional D-U-N-S Number.
+      # @param dun_bradstreet_number [String, nil] Your optional 9-digit D-U-N-S Number issued by Dun & Bradstreet, a unique identi
       #
-      # @param primary_business_domain_sic_code [String, nil] Optional SIC code for the primary line of business.
+      # @param primary_business_domain_sic_code [String, nil] The 4-digit Standard Industrial Classification code for your main line of busine
       #
-      # @param professional_license_number [String, nil] Optional professional-license number for regulated industries.
+      # @param professional_license_number [String, nil] If your business operates under a professional license (for example legal, medic
       #
-      # @param role_type [Symbol, Telnyx::Models::EnterpriseCreateParams::RoleType] `enterprise` for an organization registering its own DIRs; `bpo` for a Business
+      # @param role_type [Symbol, Telnyx::Models::EnterpriseCreateParams::RoleType] `enterprise` for an organization registering its own DIRs (the default, and the
       #
       # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -109,12 +114,30 @@ module Telnyx
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {Telnyx::Models::EnterpriseUpdateParams} for more details.
+      #
       # Replace the enterprise's mutable fields. Only mutable fields may be sent.
       # Server-assigned and immutable fields (`id`, `record_type`, `created_at`,
       # `updated_at`, status fields, `organization_type`, `country_code`, `role_type`)
       # cannot be changed: including any of them in the body is rejected with
       # `400 Bad Request` (`Field 'X' is not allowed in this request`).
       #
+      # For an approved BPO enterprise (`role_type` `bpo`), changing any identity field
+      # (legal name, DBA, website, FEIN, industry, number of employees, physical
+      # address, organization contact, D-U-N-S number, legal type, SIC code, corporate
+      # registration number, professional license number, or jurisdiction of
+      # incorporation) resets `bpo_verification_status` to `pending` for re-approval and
+      # sets every DIR authorization for that BPO to `rejected`. After re-approval, link
+      # it again with a newly signed LOA (a new `loa_document_id`); resending the old
+      # one keeps the authorization `rejected`. Re-sending an unchanged value does not
+      # reset anything.
+      #
+      # If Number Reputation is enabled on the enterprise, `legal_name`,
+      # `doing_business_as`, `website`, `fein`, `industry`, `number_of_employees`,
+      # `organization_physical_address`, `organization_contact`, and
+      # `dun_bradstreet_number` cannot be changed: the request is rejected with `400`.
+      #
       # @overload update(enterprise_id, billing_address: nil, billing_contact: nil, corporate_registration_number: nil, customer_reference: nil, doing_business_as: nil, dun_bradstreet_number: nil, fein: nil, industry: nil, jurisdiction_of_incorporation: nil, legal_name: nil, number_of_employees: nil, organization_contact: nil, organization_legal_type: nil, organization_physical_address: nil, primary_business_domain_sic_code: nil, professional_license_number: nil, website: nil, request_options: {})
       #
       # @param enterprise_id [String] The enterprise id. Lowercase UUID.
@@ -123,35 +146,35 @@ module Telnyx
       #
       # @param billing_contact [Telnyx::Models::BillingContact]
       #
-      # @param corporate_registration_number [String, nil]
+      # @param corporate_registration_number [String, nil] The official number your company received when it was legally registered or inco
       #
-      # @param customer_reference [String]
+      # @param customer_reference [String] Your own label for this account. Enter any reference that helps you find it in y
       #
-      # @param doing_business_as [String]
+      # @param doing_business_as [String] The trade name your business operates under if it is different from your legal n
       #
-      # @param dun_bradstreet_number [String, nil]
+      # @param dun_bradstreet_number [String, nil] Your optional 9-digit D-U-N-S Number issued by Dun & Bradstreet, a unique identi
       #
-      # @param fein [String]
+      # @param fein [String] US Federal Employer Identification Number (`NN-NNNNNNN`) or Canadian equivalent.
       #
-      # @param industry [Symbol, Telnyx::Models::EnterpriseUpdateParams::Industry]
+      # @param industry [Symbol, Telnyx::Models::EnterpriseUpdateParams::Industry] The industry your business operates in. Choose the closest match from the list;
       #
-      # @param jurisdiction_of_incorporation [String] Updated state/province/country of incorporation. Optional on update.
+      # @param jurisdiction_of_incorporation [String] The state, province, or country where your business was legally incorporated, fo
       #
-      # @param legal_name [String] Legal name of the enterprise.
+      # @param legal_name [String] Your business's full registered legal name, exactly as it appears on your incorp
       #
-      # @param number_of_employees [String]
+      # @param number_of_employees [String] Approximate headcount range. Used for vetting heuristics; pick the bucket that c
       #
       # @param organization_contact [Telnyx::Models::OrganizationContact]
       #
-      # @param organization_legal_type [String]
+      # @param organization_legal_type [String] Legal-entity form. Pick the form that matches your incorporation documents:
       #
       # @param organization_physical_address [Telnyx::Models::PhysicalAddress]
       #
-      # @param primary_business_domain_sic_code [String, nil]
+      # @param primary_business_domain_sic_code [String, nil] The 4-digit Standard Industrial Classification code for your main line of busine
       #
-      # @param professional_license_number [String, nil]
+      # @param professional_license_number [String, nil] If your business operates under a professional license (for example legal, medic
       #
-      # @param website [String]
+      # @param website [String] Your business's public website address, including https://. Leave blank if your
       #
       # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -175,10 +198,12 @@ module Telnyx
       # Return the enterprises you own, paginated. The default page size is 20; the
       # maximum is 250.
       #
-      # @overload list(filter_legal_name_contains: nil, legal_name: nil, page_number: nil, page_size: nil, request_options: {})
+      # @overload list(filter_legal_name_contains: nil, filter_role_type: nil, legal_name: nil, page_number: nil, page_size: nil, request_options: {})
       #
       # @param filter_legal_name_contains [String] Case-insensitive partial match on legal name.
       #
+      # @param filter_role_type [Symbol, Telnyx::Models::EnterpriseListParams::FilterRoleType] Only return enterprises of this type: `bpo` for call-center (BPO) enterprises, `
+      #
       # @param legal_name [String] Filter by legal name (partial match).
       #
       # @param page_number [Integer] 1-based page number. Out-of-range values return an empty page with correct meta.
@@ -198,6 +223,7 @@ module Telnyx
           path: "enterprises",
           query: query.transform_keys(
             filter_legal_name_contains: "filter[legal_name][contains]",
+            filter_role_type: "filter[role_type]",
             page_number: "page[number]",
             page_size: "page[size]"
           ),
@@ -236,14 +262,15 @@ module Telnyx
         )
       end
 
-      # Branded Calling is a paid product that must be activated on each enterprise.
-      # Activation is idempotent:
+      # Branded Calling must be activated on each enterprise. Activation is idempotent:
       #
-      # - First call: marks the enterprise as activated and begins onboarding it with
-      #   the Branded Calling platform asynchronously. Returns `200` with
+      # - First call: marks the enterprise as activated, effective immediately; you can
+      #   create a DIR right away. The enterprise is registered with the Branded Calling
+      #   platform later, after its first DIR is approved. Returns `200` with
       #   `branded_calling_enabled: true`.
       # - Re-call after success: no-op, returns the same enterprise body.
-      # - Re-call after a prior failure: re-queues onboarding, returns `200`.
+      # - Re-call after a failed registration: re-queues the registration, returns
+      #   `200`.
       #
       # Prerequisite: the calling user must have agreed to the Branded Calling Terms of
       # Service (`POST /terms_of_service/branded_calling/agree`). Without that, this
@@ -251,11 +278,15 @@ module Telnyx
       #
       # Failure modes:
       #
+      # - `400` - the account has no available credit. Add funds and retry.
+      # - `400` - the enterprise is not in the United States. Branded Calling is
+      #   currently available only to US enterprises.
       # - `403` - Branded Calling Terms of Service not accepted.
       # - `404` - enterprise does not exist or does not belong to your account.
       #
-      # **Pricing:** This is a billable action. See https://telnyx.com/pricing/numbers
-      # for current pricing.
+      # **Pricing:** Activation itself is free, but the account must have available
+      # credit. Branded Calling fees are charged per DIR and per branded call. See
+      # https://telnyx.com/pricing/branded-calling for current pricing.
       #
       # @overload branded_calling(enterprise_id, request_options: {})
       #
@@ -282,6 +313,7 @@ module Telnyx
         @client = client
         @reputation = Telnyx::Resources::Enterprises::Reputation.new(client: client)
         @dir = Telnyx::Resources::Enterprises::Dir.new(client: client)
+        @verify_email = Telnyx::Resources::Enterprises::VerifyEmail.new(client: client)
       end
     end
   end

data/lib/telnyx/resources/llm_token_gateway/spend.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Resources
+    class LlmTokenGateway
+      # Manage and report AI Gateway usage.
+      class Spend
+        # Some parameter documentations has been truncated, see
+        # {Telnyx::Models::LlmTokenGateway::SpendRetrieveEventsParams} for more details.
+        #
+        # Return request-level usage history for the authenticated account. Supply both
+        # UTC dates or neither; omitting both returns the previous full UTC day. Dates use
+        # a half-open range [start_date, end_date) of at most 31 days. Cost reflects
+        # budget reference rates, not invoice charges. Unknown spend is excluded and
+        # reported separately. The report snapshot supports at most 10,000 matching
+        # requests, independently of page size. Exceeding this bound returns HTTP 503
+        # without partial results. Narrow the date range or resource filters before
+        # retrying. A failed report must not be interpreted as zero usage. Request tags
+        # can filter either report and metadata:<key> can group the summary.
+        #
+        # @overload retrieve_events(end_date: nil, end_user_id: nil, metadata: nil, page_number: nil, page_size: nil, page_snapshot: nil, start_date: nil, token_group_id: nil, token_key_id: nil, token_user_id: nil, request_options: {})
+        #
+        # @param end_date [Date]
+        #
+        # @param end_user_id [String]
+        #
+        # @param metadata [Hash{Symbol=>String}] Request tag filters as metadata[<key>]=<value>, at most 5, combined with AND. A
+        #
+        # @param page_number [Integer]
+        #
+        # @param page_size [Integer]
+        #
+        # @param page_snapshot [String] Required after page 1; account/filter-bound 15-minute stable snapshot; expired/m
+        #
+        # @param start_date [Date]
+        #
+        # @param token_group_id [String]
+        #
+        # @param token_key_id [String]
+        #
+        # @param token_user_id [String]
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::LlmTokenGateway::SpendRetrieveEventsResponse]
+        #
+        # @see Telnyx::Models::LlmTokenGateway::SpendRetrieveEventsParams
+        def retrieve_events(params = {})
+          parsed, options = Telnyx::LlmTokenGateway::SpendRetrieveEventsParams.dump_request(params)
+          query = Telnyx::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: "llm_token_gateway/spend/events",
+            query: query.transform_keys(
+              page_number: "page[number]",
+              page_size: "page[size]",
+              page_snapshot: "page[snapshot]"
+            ),
+            model: Telnyx::Models::LlmTokenGateway::SpendRetrieveEventsResponse,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Telnyx::Models::LlmTokenGateway::SpendRetrieveSummaryParams} for more details.
+        #
+        # Return request counts, token counts and reference spend grouped by one
+        # attribution dimension. Both UTC dates and group_by are required. Dates use a
+        # half-open range [start_date, end_date) of at most 31 days. Cost reflects budget
+        # reference rates, not invoice charges. Unknown spend is excluded and reported
+        # separately. The report snapshot supports at most 10,000 matching requests,
+        # independently of page size. Exceeding this bound returns HTTP 503 without
+        # partial results. Narrow the date range or resource filters before retrying. A
+        # failed report must not be interpreted as zero usage. Request tags can filter
+        # either report and metadata:<key> can group the summary.
+        #
+        # @overload retrieve_summary(end_date:, group_by:, start_date:, end_user_id: nil, metadata: nil, page_number: nil, page_size: nil, page_snapshot: nil, token_group_id: nil, token_key_id: nil, token_user_id: nil, request_options: {})
+        #
+        # @param end_date [Date]
+        #
+        # @param group_by [Symbol, String, Telnyx::Models::LlmTokenGateway::SpendGroupBy] A scope, or metadata:<key> to group by one request tag's text-form value; reques
+        #
+        # @param start_date [Date]
+        #
+        # @param end_user_id [String]
+        #
+        # @param metadata [Hash{Symbol=>String}] Request tag filters as metadata[<key>]=<value>, at most 5, combined with AND. A
+        #
+        # @param page_number [Integer]
+        #
+        # @param page_size [Integer]
+        #
+        # @param page_snapshot [String] Required after page 1; account/filter-bound 15-minute stable snapshot; expired/m
+        #
+        # @param token_group_id [String]
+        #
+        # @param token_key_id [String]
+        #
+        # @param token_user_id [String]
+        #
+        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Telnyx::Models::LlmTokenGateway::SpendRetrieveSummaryResponse]
+        #
+        # @see Telnyx::Models::LlmTokenGateway::SpendRetrieveSummaryParams
+        def retrieve_summary(params)
+          parsed, options = Telnyx::LlmTokenGateway::SpendRetrieveSummaryParams.dump_request(params)
+          query = Telnyx::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: "llm_token_gateway/spend/summary",
+            query: query.transform_keys(
+              page_number: "page[number]",
+              page_size: "page[size]",
+              page_snapshot: "page[snapshot]"
+            ),
+            model: Telnyx::Models::LlmTokenGateway::SpendRetrieveSummaryResponse,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Telnyx::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end