metronome-sdk 3.4.0 → 3.6.0

data/lib/metronome_sdk/resources/v1/contracts/products.rb

@@ -15,7 +15,7 @@ module MetronomeSDK
           # an ERP system. Give the product a meaningful name as they will appear on
           # customer invoices.
           #
-          # @overload create(name:, type:, billable_metric_id: nil, composite_product_ids: nil, composite_tags: nil, custom_fields: nil, exclude_free_usage: nil, is_refundable: nil, netsuite_internal_item_id: nil, netsuite_overage_item_id: nil, presentation_group_key: nil, pricing_group_key: nil, quantity_conversion: nil, quantity_rounding: nil, tags: nil, request_options: {})
+          # @overload create(name:, type:, billable_metric_id: nil, composite_product_ids: nil, composite_tags: nil, custom_fields: nil, exclude_free_usage: nil, is_refundable: nil, netsuite_internal_item_id: nil, netsuite_overage_item_id: nil, presentation_group_key: nil, pricing_group_key: nil, quantity_conversion: nil, quantity_rounding: nil, sql_breakdown_granularity: nil, tags: nil, request_options: {})
           #
           # @param name [String] displayed on invoices
           #
@@ -45,6 +45,8 @@ module MetronomeSDK
           #
           # @param quantity_rounding [MetronomeSDK::Models::V1::Contracts::QuantityRounding, nil] Optional. Only valid for USAGE products. If provided, the quantity will be round
           #
+          # @param sql_breakdown_granularity [Symbol, MetronomeSDK::Models::V1::Contracts::ProductCreateParams::SqlBreakdownGranularity] Defines the breakdown behavior when calculating usage from SQL Billable Metrics.
+          #
           # @param tags [Array<String>]
           #
           # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
@@ -99,7 +101,7 @@ module MetronomeSDK
           # - Product type cannot be changed after creation. For incorrect product types,
           #   create a new product and archive the original instead.
           #
-          # @overload update(product_id:, starting_at:, billable_metric_id: nil, composite_product_ids: nil, composite_tags: nil, exclude_free_usage: nil, is_refundable: nil, name: nil, netsuite_internal_item_id: nil, netsuite_overage_item_id: nil, presentation_group_key: nil, pricing_group_key: nil, quantity_conversion: nil, quantity_rounding: nil, tags: nil, request_options: {})
+          # @overload update(product_id:, starting_at:, billable_metric_id: nil, composite_product_ids: nil, composite_tags: nil, exclude_free_usage: nil, is_refundable: nil, name: nil, netsuite_internal_item_id: nil, netsuite_overage_item_id: nil, presentation_group_key: nil, pricing_group_key: nil, quantity_conversion: nil, quantity_rounding: nil, sql_breakdown_granularity: nil, tags: nil, request_options: {})
           #
           # @param product_id [String] ID of the product to update
           #
@@ -129,6 +131,8 @@ module MetronomeSDK
           #
           # @param quantity_rounding [MetronomeSDK::Models::V1::Contracts::QuantityRounding, nil] Optional. Only valid for USAGE products. If provided, the quantity will be round
           #
+          # @param sql_breakdown_granularity [Symbol, MetronomeSDK::Models::V1::Contracts::ProductUpdateParams::SqlBreakdownGranularity] Defines the breakdown behavior when calculating usage from SQL Billable Metrics.
+          #
           # @param tags [Array<String>] If not provided, defaults to product's current tags
           #
           # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]

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

@@ -22,8 +22,8 @@ module MetronomeSDK
         #
         # Contracts define a customer's products, pricing, discounts, access duration, and
         # billing configuration. Contracts serve as the central billing agreement for both
-        # PLG and Enterprise customers, you can automatically customers access to your
-        # products and services directly from your product or CRM.
+        # PLG and Enterprise customers. You can automatically grant customers access to
+        # your products and services directly from your product or CRM.
         #
         # ### Use this endpoint to:
         #
@@ -525,6 +525,10 @@ module MetronomeSDK
         #
         # ### Usage guidelines:
         #
+        # - **Balance ledger details**: Use the
+        #   [listBalances](https://docs.metronome.com/api-reference/credits-and-commits/list-balances)
+        #   endpoint instead to understand detailed ledger drawdowns for each individual
+        #   balance
         # - **Draft invoice handling**: Use `invoice_inclusion_mode` to control whether
         #   pending draft invoice deductions are included (`FINALIZED_AND_DRAFT`, the
         #   default) or excluded (`FINALIZED`) from the balance calculation
@@ -590,6 +594,9 @@ module MetronomeSDK
         #
         # ### Usage guidelines:
         #
+        # - Use the
+        #   [getNetBalance](https://docs.metronome.com/api-reference/credits-and-commits/get-the-net-balance-of-a-customer)
+        #   endpoint to retrieve a single combined current balance
         # - Date filtering: Use `effective_before` to include only balances with access
         #   before a specific date (exclusive)
         # - Set `include_balance=true` for calculated balance amounts on each commit or
@@ -643,6 +650,73 @@ module MetronomeSDK
           )
         end
 
+        # Some parameter documentations has been truncated, see
+        # {MetronomeSDK::Models::V1::ContractListSeatBalancesParams} for more details.
+        #
+        # Retrieve detailed balance for seat-based credits and commits from the contract's
+        # subscriptions, broken down by individual seats.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Display per-seat balance information in customer dashboards
+        # - Filter balance data by subscription or specific seats
+        #
+        # ### Key response fields:
+        #
+        # An array of seat balance objects containing:
+        #
+        # - Seat id
+        # - Balance: current total balance across all commits and credits
+        #
+        # ### Usage guidelines:
+        #
+        # - Date filtering: use `covering_date` OR `starting_at`/`ending_before` to filter
+        #   balance data by time range
+        # - Set `include_credits_and_commits=true` for detailed commits and credits
+        #   breakdown per seat
+        # - Set `include_ledgers=true` for detailed transaction history per commit/credit
+        #   per seat
+        #
+        # @overload list_seat_balances(contract_id:, customer_id:, covering_date: nil, cursor: nil, effective_before: nil, include_credits_and_commits: nil, include_ledgers: nil, limit: nil, seat_ids: nil, starting_at: nil, subscription_ids: nil, request_options: {})
+        #
+        # @param contract_id [String] The contract ID to retrieve seat balances for
+        #
+        # @param customer_id [String] The customer ID to retrieve seat balances for
+        #
+        # @param covering_date [Time] Include only commits or credits with access that cover this specific date (canno
+        #
+        # @param cursor [String] Page token from a previous response to retrieve the next page
+        #
+        # @param effective_before [Time] Include only commits or credits with access effective on or before this date (ca
+        #
+        # @param include_credits_and_commits [Boolean] Include credits and commits in the response
+        #
+        # @param include_ledgers [Boolean] Include ledger entries for each commit and commit. `include_credits_and_commits`
+        #
+        # @param limit [Integer] Maximum number of seats to return. Range: 1-100. Default: 25.
+        #
+        # @param seat_ids [Array<String>] Optional filter to only include specific seats.
+        #
+        # @param starting_at [Time] Include only commits or credits with access effective on or after this date (can
+        #
+        # @param subscription_ids [Array<String>] Optional filter to only include seats from specific subscriptions. If subscripti
+        #
+        # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [MetronomeSDK::Models::V1::ContractListSeatBalancesResponse]
+        #
+        # @see MetronomeSDK::Models::V1::ContractListSeatBalancesParams
+        def list_seat_balances(params)
+          parsed, options = MetronomeSDK::V1::ContractListSeatBalancesParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "v1/contracts/seatBalances/list",
+            body: parsed,
+            model: MetronomeSDK::Models::V1::ContractListSeatBalancesResponse,
+            options: options
+          )
+        end
+
         # Some parameter documentations has been truncated, see
         # {MetronomeSDK::Models::V1::ContractRetrieveRateScheduleParams} for more details.
         #

data/lib/metronome_sdk/resources/v1/customers/invoices.rb

@@ -136,10 +136,12 @@ module MetronomeSDK
           # - Voided invoices are included in results by default unless filtered out by
           #   status
           #
-          # @overload list(customer_id:, credit_type_id: nil, ending_before: nil, limit: nil, next_page: nil, skip_zero_qty_line_items: nil, sort: nil, starting_on: nil, status: nil, request_options: {})
+          # @overload list(customer_id:, contract_id: nil, credit_type_id: nil, ending_before: nil, limit: nil, next_page: nil, skip_zero_qty_line_items: nil, sort: nil, starting_on: nil, status: nil, type: nil, request_options: {})
           #
           # @param customer_id [String] Path param
           #
+          # @param contract_id [String] Query param: Only return invoices for the specified contract
+          #
           # @param credit_type_id [String] Query param: Only return invoices for the specified credit type
           #
           # @param ending_before [Time] Query param: RFC 3339 timestamp (exclusive). Invoices will only be returned for
@@ -156,6 +158,8 @@ module MetronomeSDK
           #
           # @param status [String] Query param: Invoice status, e.g. DRAFT, FINALIZED, or VOID
           #
+          # @param type [Symbol, MetronomeSDK::Models::V1::Customers::InvoiceListParams::Type] Query param: Filter invoices by type. Defaults to returning all invoice types.
+          #
           # @param request_options [MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
           #
           # @return [MetronomeSDK::Internal::CursorPage<MetronomeSDK::Models::V1::Customers::Invoice>]

data/lib/metronome_sdk/resources/v1/packages.rb

@@ -58,14 +58,12 @@ module MetronomeSDK
         #   provisioning with a package. Edited contracts will still be associated with
         #   the package used during provisioning.
         #
-        # @overload create(name:, aliases: nil, billing_anchor_date: nil, billing_provider: nil, commits: nil, contract_name: nil, credits: nil, delivery_method: nil, duration: nil, multiplier_override_prioritization: nil, net_payment_terms_days: nil, overrides: nil, prepaid_balance_threshold_configuration: nil, rate_card_alias: nil, rate_card_id: nil, recurring_commits: nil, recurring_credits: nil, scheduled_charges: nil, scheduled_charges_on_usage_invoices: nil, spend_threshold_configuration: nil, subscriptions: nil, uniqueness_key: nil, usage_statement_schedule: nil, request_options: {})
+        # @overload create(name:, aliases: nil, billing_provider: nil, commits: nil, contract_name: nil, credits: nil, delivery_method: nil, duration: nil, multiplier_override_prioritization: nil, net_payment_terms_days: nil, overrides: nil, prepaid_balance_threshold_configuration: nil, rate_card_alias: nil, rate_card_id: nil, recurring_commits: nil, recurring_credits: nil, scheduled_charges: nil, scheduled_charges_on_usage_invoices: nil, spend_threshold_configuration: nil, subscriptions: nil, uniqueness_key: nil, usage_statement_schedule: nil, request_options: {})
         #
         # @param name [String]
         #
         # @param aliases [Array<MetronomeSDK::Models::V1::PackageCreateParams::Alias>] Reference this alias when creating a contract. If the same alias is assigned to
         #
-        # @param billing_anchor_date [Symbol, MetronomeSDK::Models::V1::PackageCreateParams::BillingAnchorDate]
-        #
         # @param billing_provider [Symbol, MetronomeSDK::Models::V1::PackageCreateParams::BillingProvider]
         #
         # @param commits [Array<MetronomeSDK::Models::V1::PackageCreateParams::Commit>]

data/lib/metronome_sdk/version.rb

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

data/lib/metronome_sdk.rb

@@ -56,9 +56,9 @@ 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/update_base_threshold_commit"
 require_relative "metronome_sdk/models/balance_filter"
 require_relative "metronome_sdk/models/base_usage_filter"
 require_relative "metronome_sdk/models/commit"
@@ -121,6 +121,8 @@ require_relative "metronome_sdk/models/v1/contract_list_balances_params"
 require_relative "metronome_sdk/models/v1/contract_list_balances_response"
 require_relative "metronome_sdk/models/v1/contract_list_params"
 require_relative "metronome_sdk/models/v1/contract_list_response"
+require_relative "metronome_sdk/models/v1/contract_list_seat_balances_params"
+require_relative "metronome_sdk/models/v1/contract_list_seat_balances_response"
 require_relative "metronome_sdk/models/v1/contract_retrieve_params"
 require_relative "metronome_sdk/models/v1/contract_retrieve_rate_schedule_params"
 require_relative "metronome_sdk/models/v1/contract_retrieve_rate_schedule_response"

data/rbi/metronome_sdk/internal/util.rbi

@@ -148,12 +148,20 @@ module MetronomeSDK
         end
       end
 
+      # https://www.rfc-editor.org/rfc/rfc3986.html#section-3.3
+      RFC_3986_NOT_PCHARS = T.let(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/, Regexp)
+
       class << self
         # @api private
         sig { params(uri: URI::Generic).returns(String) }
         def uri_origin(uri)
         end
 
+        # @api private
+        sig { params(path: T.any(String, Integer)).returns(String) }
+        def encode_path(path)
+        end
+
         # @api private
         sig { params(path: T.any(String, T::Array[String])).returns(String) }
         def interpolate_path(path)

data/rbi/metronome_sdk/models/base_threshold_commit.rbi

@@ -30,10 +30,21 @@ module MetronomeSDK
       sig { params(name: String).void }
       attr_writer :name
 
+      # The priority of the commit, used to determine drawdown order. Lower priority
+      # commits are consumed first. Defaults to 100 if not specified.
+      sig { returns(T.nilable(Float)) }
+      attr_reader :priority
+
+      sig { params(priority: Float).void }
+      attr_writer :priority
+
       sig do
-        params(product_id: String, description: String, name: String).returns(
-          T.attached_class
-        )
+        params(
+          product_id: String,
+          description: String,
+          name: String,
+          priority: Float
+        ).returns(T.attached_class)
       end
       def self.new(
         # The commit product that will be used to generate the line item for commit
@@ -42,13 +53,21 @@ module MetronomeSDK
         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
+        name: nil,
+        # The priority of the commit, used to determine drawdown order. Lower priority
+        # commits are consumed first. Defaults to 100 if not specified.
+        priority: nil
       )
       end
 
       sig do
         override.returns(
-          { product_id: String, description: String, name: String }
+          {
+            product_id: String,
+            description: String,
+            name: String,
+            priority: Float
+          }
         )
       end
       def to_hash