metronome-sdk 0.3.0 → 1.0.0

data/lib/metronome_sdk/resources/v2/contracts.rb

@@ -7,8 +7,23 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V2::ContractRetrieveParams} for more details.
         #
-        # Get a specific contract. New clients should use this endpoint rather than the v1
-        # endpoint.
+        # Gets the details for a specific contract, including contract term, rate card
+        # information, credits and commits, and more.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Check the duration of a customer's current contract
+        # - Get details on contract terms, including access schedule amounts for
+        #   commitments and credits
+        # - Understand the state of a contract at a past time. As you can evolve the terms
+        #   of a contract over time through editing, use the `as_of_date` parameter to
+        #   view the full contract configuration as of that point in time.
+        #
+        # ### Usage guidelines:
+        #
+        # - Optionally, use the `include_balance` and `include_ledger` fields to include
+        #   balances and ledgers in the credit and commit responses. Using these fields
+        #   will cause the query to be slower.
         #
         # @overload retrieve(contract_id:, customer_id:, as_of_date: nil, include_balance: nil, include_ledgers: nil, request_options: {})
         #
@@ -41,8 +56,21 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V2::ContractListParams} for more details.
         #
-        # List all contracts for a customer in chronological order. New clients should use
-        # this endpoint rather than the v1 endpoint.
+        # For a given customer, lists all of their contracts in chronological order.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Check if a customer is provisioned with any contract, and at which tier
+        # - Check the duration and terms of a customer's current contract
+        # - Power a page in your end customer experience that shows the customer's history
+        #   of tiers (e.g. this customer started out on the Pro Plan, then downgraded to
+        #   the Starter plan).
+        #
+        # ### Usage guidelines:
+        #
+        # Use the `starting_at`, `covering_date`, and `include_archived` parameters to
+        # filter the list of returned contracts. For example, to list only currently
+        # active contracts, pass `covering_date` equal to the current time.
         #
         # @overload list(customer_id:, covering_date: nil, include_archived: nil, include_balance: nil, include_ledgers: nil, starting_at: nil, request_options: {})
         #
@@ -77,9 +105,30 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V2::ContractEditParams} for more details.
         #
-        # Edit a contract. Contract editing must be enabled to use this endpoint.
+        # The ability to edit a contract helps you react quickly to the needs of your
+        # customers and your business.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Encode mid-term commitment and discount changes
+        # - Fix configuration mistakes and easily roll back packaging changes
+        #
+        # ### Key response fields:
+        #
+        # - The `id` of the edit
+        # - Complete edit details. For example, if you edited the contract to add new
+        #   overrides and credits, you will receive the IDs of those overrides and credits
+        #   in the response.
+        #
+        # ### Usage guidelines:
+        #
+        # - When you edit a contract, any draft invoices update immediately to reflect
+        #   that edit. Finalized invoices remain unchanged - you must void and regenerate
+        #   them in the UI or API to reflect the edit.
+        # - Contract editing must be enabled to use this endpoint. Reach out to your
+        #   Metronome representative to learn more.
         #
-        # @overload edit(contract_id:, customer_id:, add_commits: nil, add_credits: nil, add_discounts: nil, add_overrides: nil, add_prepaid_balance_threshold_configuration: nil, add_professional_services: nil, add_recurring_commits: nil, add_recurring_credits: nil, add_reseller_royalties: nil, add_scheduled_charges: nil, add_spend_threshold_configuration: nil, add_subscriptions: nil, allow_contract_ending_before_finalized_invoice: nil, archive_commits: nil, archive_credits: nil, archive_scheduled_charges: nil, remove_overrides: nil, update_commits: nil, update_contract_end_date: nil, update_contract_name: nil, update_credits: nil, update_prepaid_balance_threshold_configuration: nil, update_recurring_commits: nil, update_recurring_credits: nil, update_scheduled_charges: nil, update_spend_threshold_configuration: nil, update_subscriptions: nil, request_options: {})
+        # @overload edit(contract_id:, customer_id:, add_commits: nil, add_credits: nil, add_discounts: nil, add_overrides: nil, add_prepaid_balance_threshold_configuration: nil, add_professional_services: nil, add_recurring_commits: nil, add_recurring_credits: nil, add_reseller_royalties: nil, add_scheduled_charges: nil, add_spend_threshold_configuration: nil, add_subscriptions: nil, allow_contract_ending_before_finalized_invoice: nil, archive_commits: nil, archive_credits: nil, archive_scheduled_charges: nil, remove_overrides: nil, uniqueness_key: nil, update_commits: nil, update_contract_end_date: nil, update_contract_name: nil, update_credits: nil, update_prepaid_balance_threshold_configuration: nil, update_recurring_commits: nil, update_recurring_credits: nil, update_scheduled_charges: nil, update_spend_threshold_configuration: nil, update_subscriptions: nil, request_options: {})
         #
         # @param contract_id [String] ID of the contract being edited
         #
@@ -93,7 +142,7 @@ module MetronomeSDK
         #
         # @param add_overrides [Array<MetronomeSDK::Models::V2::ContractEditParams::AddOverride>]
         #
-        # @param add_prepaid_balance_threshold_configuration [MetronomeSDK::Models::V2::ContractEditParams::AddPrepaidBalanceThresholdConfiguration]
+        # @param add_prepaid_balance_threshold_configuration [MetronomeSDK::Models::PrepaidBalanceThresholdConfigurationV2]
         #
         # @param add_professional_services [Array<MetronomeSDK::Models::V2::ContractEditParams::AddProfessionalService>] This field's availability is dependent on your client's configuration.
         #
@@ -105,7 +154,7 @@ module MetronomeSDK
         #
         # @param add_scheduled_charges [Array<MetronomeSDK::Models::V2::ContractEditParams::AddScheduledCharge>]
         #
-        # @param add_spend_threshold_configuration [MetronomeSDK::Models::V2::ContractEditParams::AddSpendThresholdConfiguration]
+        # @param add_spend_threshold_configuration [MetronomeSDK::Models::SpendThresholdConfigurationV2]
         #
         # @param add_subscriptions [Array<MetronomeSDK::Models::V2::ContractEditParams::AddSubscription>] Optional list of [subscriptions](https://docs.metronome.com/manage-product-acces
         #
@@ -119,6 +168,8 @@ module MetronomeSDK
         #
         # @param remove_overrides [Array<MetronomeSDK::Models::V2::ContractEditParams::RemoveOverride>] IDs of overrides to remove
         #
+        # @param uniqueness_key [String] Optional uniqueness key to prevent duplicate contract edits.
+        #
         # @param update_commits [Array<MetronomeSDK::Models::V2::ContractEditParams::UpdateCommit>]
         #
         # @param update_contract_end_date [Time, nil] RFC 3339 timestamp indicating when the contract will end (exclusive).
@@ -158,10 +209,24 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V2::ContractEditCommitParams} for more details.
         #
-        # Edit a customer or contract commit. Contract commits can only be edited using
-        # this endpoint if contract editing is enabled.
+        # Edit specific details for a contract-level or customer-level commit. Use this
+        # endpoint to modify individual commit access schedules, invoice schedules,
+        # applicable products, invoicing contracts, or other fields.
+        #
+        # ### Usage guidelines:
         #
-        # @overload edit_commit(commit_id:, customer_id:, access_schedule: nil, applicable_product_ids: nil, applicable_product_tags: nil, invoice_contract_id: nil, invoice_schedule: nil, priority: nil, product_id: nil, specifiers: nil, request_options: {})
+        # - As with all edits in Metronome, draft invoices will reflect the edit
+        #   immediately, while finalized invoices are untouched unless voided and
+        #   regenerated.
+        # - If a commit's invoice schedule item is associated with a finalized invoice,
+        #   you cannot remove or update the invoice schedule item.
+        # - If a commit's invoice schedule item is associated with a voided invoice, you
+        #   cannot remove the invoice schedule item.
+        # - You cannot remove an commit access schedule segment that was applied to a
+        #   finalized invoice. You can void the invoice beforehand and then remove the
+        #   access schedule segment.
+        #
+        # @overload edit_commit(commit_id:, customer_id:, access_schedule: nil, applicable_product_ids: nil, applicable_product_tags: nil, invoice_contract_id: nil, invoice_schedule: nil, priority: nil, product_id: nil, rate_type: nil, specifiers: nil, request_options: {})
         #
         # @param commit_id [String] ID of the commit to edit
         #
@@ -181,7 +246,9 @@ module MetronomeSDK
         #
         # @param product_id [String]
         #
-        # @param specifiers [Array<MetronomeSDK::Models::V2::ContractEditCommitParams::Specifier>, nil] List of filters that determine what kind of customer usage draws down a commit o
+        # @param rate_type [Symbol, MetronomeSDK::Models::V2::ContractEditCommitParams::RateType] If provided, updates the commit to use the specified rate type for current and f
+        #
+        # @param specifiers [Array<MetronomeSDK::Models::CommitSpecifierInput>, nil] List of filters that determine what kind of customer usage draws down a commit o
         #
         # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -202,10 +269,24 @@ module MetronomeSDK
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V2::ContractEditCreditParams} for more details.
         #
-        # Edit a customer or contract credit. Contract credits can only be edited using
-        # this endpoint if contract editing is enabled.
+        # Edit details for a contract-level or customer-level credit.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Extend the duration or the amount of an existing free credit like a trial
+        # - Modify individual credit access schedules, applicable products, priority, or
+        #   other fields.
+        #
+        # ### Usage guidelines:
         #
-        # @overload edit_credit(credit_id:, customer_id:, access_schedule: nil, applicable_product_ids: nil, applicable_product_tags: nil, priority: nil, product_id: nil, specifiers: nil, request_options: {})
+        # - As with all edits in Metronome, draft invoices will reflect the edit
+        #   immediately, while finalized invoices are untouched unless voided and
+        #   regenerated.
+        # - You cannot remove an access schedule segment that was applied to a finalized
+        #   invoice. You can void the invoice beforehand and then remove the access
+        #   schedule segment.
+        #
+        # @overload edit_credit(credit_id:, customer_id:, access_schedule: nil, applicable_product_ids: nil, applicable_product_tags: nil, priority: nil, product_id: nil, rate_type: nil, specifiers: nil, request_options: {})
         #
         # @param credit_id [String] ID of the credit to edit
         #
@@ -221,7 +302,9 @@ module MetronomeSDK
         #
         # @param product_id [String]
         #
-        # @param specifiers [Array<MetronomeSDK::Models::V2::ContractEditCreditParams::Specifier>, nil] List of filters that determine what kind of customer usage draws down a commit o
+        # @param rate_type [Symbol, MetronomeSDK::Models::V2::ContractEditCreditParams::RateType] If provided, updates the credit to use the specified rate type for current and f
+        #
+        # @param specifiers [Array<MetronomeSDK::Models::CommitSpecifierInput>, nil] List of filters that determine what kind of customer usage draws down a commit o
         #
         # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -239,8 +322,21 @@ module MetronomeSDK
           )
         end
 
-        # Get the edit history of a specific contract. Contract editing must be enabled to
-        # use this endpoint.
+        # List all the edits made to a contract over time. In Metronome, you can edit a
+        # contract at any point after it's created to fix mistakes or reflect changes in
+        # terms. Metronome stores a full history of all edits that were ever made to a
+        # contract, whether through the UI, `editContract` endpoint, or other endpoints
+        # like `updateContractEndDate`.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Understand what changes were made to a contract, when, and by who
+        #
+        # ### Key response fields:
+        #
+        # - An array of every edit ever made to the contract
+        # - Details on each individual edit - for example showing that in one edit, a user
+        #   added two discounts and incremented a subscription quantity.
         #
         # @overload get_edit_history(contract_id:, customer_id:, request_options: {})
         #

data/lib/metronome_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MetronomeSDK
-  VERSION = "0.3.0"
+  VERSION = "1.0.0"
 end

data/lib/metronome_sdk.rb

@@ -50,23 +50,44 @@ require_relative "metronome_sdk/errors"
 require_relative "metronome_sdk/internal/transport/base_client"
 require_relative "metronome_sdk/internal/transport/pooled_net_requester"
 require_relative "metronome_sdk/client"
+require_relative "metronome_sdk/internal/body_cursor_page"
 require_relative "metronome_sdk/internal/cursor_page"
+require_relative "metronome_sdk/internal/cursor_page_without_limit"
+require_relative "metronome_sdk/models/base_threshold_commit"
+require_relative "metronome_sdk/models/update_base_threshold_commit"
 require_relative "metronome_sdk/models/id"
 require_relative "metronome_sdk/models/v1/customers/invoice"
 require_relative "metronome_sdk/models/base_usage_filter"
 require_relative "metronome_sdk/models/commit"
+require_relative "metronome_sdk/models/commit_hierarchy_configuration"
+require_relative "metronome_sdk/models/commit_rate"
+require_relative "metronome_sdk/models/commit_specifier"
+require_relative "metronome_sdk/models/commit_specifier_input"
+require_relative "metronome_sdk/models/contract"
+require_relative "metronome_sdk/models/contract_v2"
 require_relative "metronome_sdk/models/contract_without_amendments"
 require_relative "metronome_sdk/models/credit"
 require_relative "metronome_sdk/models/credit_type_data"
 require_relative "metronome_sdk/models/discount"
 require_relative "metronome_sdk/models/event_type_filter"
+require_relative "metronome_sdk/models/hierarchy_configuration"
 require_relative "metronome_sdk/models/override"
+require_relative "metronome_sdk/models/override_tier"
+require_relative "metronome_sdk/models/overwrite_rate"
+require_relative "metronome_sdk/models/payment_gate_config"
+require_relative "metronome_sdk/models/payment_gate_config_v2"
+require_relative "metronome_sdk/models/prepaid_balance_threshold_configuration"
+require_relative "metronome_sdk/models/prepaid_balance_threshold_configuration_v2"
 require_relative "metronome_sdk/models/property_filter"
 require_relative "metronome_sdk/models/pro_service"
 require_relative "metronome_sdk/models/rate"
+require_relative "metronome_sdk/models/recurring_commit_subscription_config"
 require_relative "metronome_sdk/models/scheduled_charge"
 require_relative "metronome_sdk/models/schedule_duration"
 require_relative "metronome_sdk/models/schedule_point_in_time"
+require_relative "metronome_sdk/models/spend_threshold_configuration"
+require_relative "metronome_sdk/models/spend_threshold_configuration_v2"
+require_relative "metronome_sdk/models/subscription"
 require_relative "metronome_sdk/models/tier"
 require_relative "metronome_sdk/models/v1/alert_archive_params"
 require_relative "metronome_sdk/models/v1/alert_archive_response"
@@ -171,10 +192,11 @@ require_relative "metronome_sdk/models/v1/customer_list_costs_response"
 require_relative "metronome_sdk/models/v1/customer_list_params"
 require_relative "metronome_sdk/models/v1/customer_preview_events_params"
 require_relative "metronome_sdk/models/v1/customer_preview_events_response"
+require_relative "metronome_sdk/models/v1/customer_retrieve_billing_configurations_params"
+require_relative "metronome_sdk/models/v1/customer_retrieve_billing_configurations_response"
 require_relative "metronome_sdk/models/v1/customer_retrieve_params"
 require_relative "metronome_sdk/models/v1/customer_retrieve_response"
 require_relative "metronome_sdk/models/v1/customers/alert_list_params"
-require_relative "metronome_sdk/models/v1/customers/alert_list_response"
 require_relative "metronome_sdk/models/v1/customers/alert_reset_params"
 require_relative "metronome_sdk/models/v1/customers/alert_retrieve_params"
 require_relative "metronome_sdk/models/v1/customers/alert_retrieve_response"
@@ -185,13 +207,11 @@ require_relative "metronome_sdk/models/v1/customers/billing_config_retrieve_resp
 require_relative "metronome_sdk/models/v1/customers/commit_create_params"
 require_relative "metronome_sdk/models/v1/customers/commit_create_response"
 require_relative "metronome_sdk/models/v1/customers/commit_list_params"
-require_relative "metronome_sdk/models/v1/customers/commit_list_response"
 require_relative "metronome_sdk/models/v1/customers/commit_update_end_date_params"
 require_relative "metronome_sdk/models/v1/customers/commit_update_end_date_response"
 require_relative "metronome_sdk/models/v1/customers/credit_create_params"
 require_relative "metronome_sdk/models/v1/customers/credit_create_response"
 require_relative "metronome_sdk/models/v1/customers/credit_list_params"
-require_relative "metronome_sdk/models/v1/customers/credit_list_response"
 require_relative "metronome_sdk/models/v1/customers/credit_update_end_date_params"
 require_relative "metronome_sdk/models/v1/customers/credit_update_end_date_response"
 require_relative "metronome_sdk/models/v1/customers/customer_alert"
@@ -213,6 +233,7 @@ require_relative "metronome_sdk/models/v1/customers/plan_list_params"
 require_relative "metronome_sdk/models/v1/customers/plan_list_price_adjustments_params"
 require_relative "metronome_sdk/models/v1/customers/plan_list_price_adjustments_response"
 require_relative "metronome_sdk/models/v1/customers/plan_list_response"
+require_relative "metronome_sdk/models/v1/customer_set_billing_configurations_params"
 require_relative "metronome_sdk/models/v1/customer_set_ingest_aliases_params"
 require_relative "metronome_sdk/models/v1/customer_set_name_params"
 require_relative "metronome_sdk/models/v1/customer_set_name_response"

data/rbi/metronome_sdk/errors.rbi

@@ -59,10 +59,10 @@ module MetronomeSDK
     end
 
     class APIConnectionError < MetronomeSDK::Errors::APIError
-      sig { void }
+      sig { returns(NilClass) }
       attr_accessor :status
 
-      sig { void }
+      sig { returns(NilClass) }
       attr_accessor :body
 
       # @api private

data/rbi/metronome_sdk/internal/body_cursor_page.rbi

@@ -0,0 +1,22 @@
+# typed: strong
+
+module MetronomeSDK
+  module Internal
+    class BodyCursorPage
+      include MetronomeSDK::Internal::Type::BasePage
+
+      Elem = type_member
+
+      sig { returns(String) }
+      attr_accessor :next_page_
+
+      sig { returns(T.nilable(T::Array[Elem])) }
+      attr_accessor :data
+
+      # @api private
+      sig { returns(String) }
+      def inspect
+      end
+    end
+  end
+end

data/rbi/metronome_sdk/internal/cursor_page_without_limit.rbi

@@ -0,0 +1,22 @@
+# typed: strong
+
+module MetronomeSDK
+  module Internal
+    class CursorPageWithoutLimit
+      include MetronomeSDK::Internal::Type::BasePage
+
+      Elem = type_member
+
+      sig { returns(String) }
+      attr_accessor :next_page_
+
+      sig { returns(T.nilable(T::Array[Elem])) }
+      attr_accessor :data
+
+      # @api private
+      sig { returns(String) }
+      def inspect
+      end
+    end
+  end
+end

data/rbi/metronome_sdk/models/base_threshold_commit.rbi

@@ -0,0 +1,58 @@
+# typed: strong
+
+module MetronomeSDK
+  module Models
+    class BaseThresholdCommit < MetronomeSDK::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            MetronomeSDK::BaseThresholdCommit,
+            MetronomeSDK::Internal::AnyHash
+          )
+        end
+
+      # The commit product that will be used to generate the line item for commit
+      # payment.
+      sig { returns(String) }
+      attr_accessor :product_id
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :description
+
+      sig { params(description: String).void }
+      attr_writer :description
+
+      # Specify the name of the line item for the threshold charge. If left blank, it
+      # will default to the commit product name.
+      sig { returns(T.nilable(String)) }
+      attr_reader :name
+
+      sig { params(name: String).void }
+      attr_writer :name
+
+      sig do
+        params(product_id: String, description: String, name: String).returns(
+          T.attached_class
+        )
+      end
+      def self.new(
+        # The commit product that will be used to generate the line item for commit
+        # payment.
+        product_id:,
+        description: nil,
+        # Specify the name of the line item for the threshold charge. If left blank, it
+        # will default to the commit product name.
+        name: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          { product_id: String, description: String, name: String }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end