metronome-sdk 0.3.0 → 2.0.0

data/rbi/metronome_sdk/models.rbi

@@ -1,10 +1,25 @@
 # typed: strong
 
 module MetronomeSDK
+  BaseThresholdCommit = MetronomeSDK::Models::BaseThresholdCommit
+
   BaseUsageFilter = MetronomeSDK::Models::BaseUsageFilter
 
   Commit = MetronomeSDK::Models::Commit
 
+  CommitHierarchyConfiguration =
+    MetronomeSDK::Models::CommitHierarchyConfiguration
+
+  CommitRate = MetronomeSDK::Models::CommitRate
+
+  CommitSpecifier = MetronomeSDK::Models::CommitSpecifier
+
+  CommitSpecifierInput = MetronomeSDK::Models::CommitSpecifierInput
+
+  Contract = MetronomeSDK::Models::Contract
+
+  ContractV2 = MetronomeSDK::Models::ContractV2
+
   ContractWithoutAmendments = MetronomeSDK::Models::ContractWithoutAmendments
 
   Credit = MetronomeSDK::Models::Credit
@@ -15,24 +30,53 @@ module MetronomeSDK
 
   EventTypeFilter = MetronomeSDK::Models::EventTypeFilter
 
+  HierarchyConfiguration = MetronomeSDK::Models::HierarchyConfiguration
+
   ID = MetronomeSDK::Models::ID
 
   Override = MetronomeSDK::Models::Override
 
+  OverrideTier = MetronomeSDK::Models::OverrideTier
+
+  OverwriteRate = MetronomeSDK::Models::OverwriteRate
+
+  PaymentGateConfig = MetronomeSDK::Models::PaymentGateConfig
+
+  PaymentGateConfigV2 = MetronomeSDK::Models::PaymentGateConfigV2
+
+  PrepaidBalanceThresholdConfiguration =
+    MetronomeSDK::Models::PrepaidBalanceThresholdConfiguration
+
+  PrepaidBalanceThresholdConfigurationV2 =
+    MetronomeSDK::Models::PrepaidBalanceThresholdConfigurationV2
+
   PropertyFilter = MetronomeSDK::Models::PropertyFilter
 
   ProService = MetronomeSDK::Models::ProService
 
   Rate = MetronomeSDK::Models::Rate
 
+  RecurringCommitSubscriptionConfig =
+    MetronomeSDK::Models::RecurringCommitSubscriptionConfig
+
   ScheduledCharge = MetronomeSDK::Models::ScheduledCharge
 
   ScheduleDuration = MetronomeSDK::Models::ScheduleDuration
 
   SchedulePointInTime = MetronomeSDK::Models::SchedulePointInTime
 
+  SpendThresholdConfiguration =
+    MetronomeSDK::Models::SpendThresholdConfiguration
+
+  SpendThresholdConfigurationV2 =
+    MetronomeSDK::Models::SpendThresholdConfigurationV2
+
+  Subscription = MetronomeSDK::Models::Subscription
+
   Tier = MetronomeSDK::Models::Tier
 
+  UpdateBaseThresholdCommit = MetronomeSDK::Models::UpdateBaseThresholdCommit
+
   V1 = MetronomeSDK::Models::V1
 
   V2 = MetronomeSDK::Models::V2

data/rbi/metronome_sdk/resources/v1/alerts.rbi

@@ -4,7 +4,51 @@ module MetronomeSDK
   module Resources
     class V1
       class Alerts
-        # Create a new alert
+        # Create a new threshold notification to monitor customer spending, balances, and
+        # billing metrics in real-time. Metronome's notification system provides
+        # industry-leading speed with immediate evaluation capabilities, enabling you to
+        # proactively manage customer accounts and prevent revenue leakage.
+        #
+        # This endpoint creates configurable threshold notifications that continuously
+        # monitor various billing thresholds including spend limits, credit balances,
+        # commitment utilization, and invoice totals. Threshold notifications can be
+        # configured globally for all customers or targeted to specific customer accounts.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Proactively monitor customer spending patterns to prevent unexpected overages
+        #   or credit exhaustion
+        # - Automate notifications when customers approach commitment limits or credit
+        #   thresholds
+        # - Enable real-time intervention for accounts at risk of churn or payment issues
+        # - Scale billing operations by automating threshold-based workflows and
+        #   notifications
+        #
+        # ### Key response fields:
+        #
+        # A successful response returns a CustomerAlert object containing:
+        #
+        # - The threshold notification configuration with its unique ID and current status
+        # - The customer's evaluation status (ok, in_alarm, or evaluating)
+        # - Threshold notification metadata including type, threshold values, and update
+        #   timestamps
+        #
+        # ### Usage guidelines:
+        #
+        # - Immediate evaluation: Set `evaluate_on_create` : `true` (default) for instant
+        #   evaluation against existing customers
+        # - Uniqueness constraints: Each threshold notification must have a unique
+        #   `uniqueness_key` within your organization. Use `release_uniqueness_key` :
+        #   `true` when archiving to reuse keys
+        # - Notification type requirements: Different threshold notification types require
+        #   specific fields (e.g., `billable_metric_id` for usage notifications,
+        #   `credit_type_id` for credit-based threshold notifications)
+        # - Webhook delivery: Threshold notifications trigger webhook notifications for
+        #   real-time integration with your systems. Configure webhook endpoints before
+        #   creating threshold notifications
+        # - Performance at scale: Metronome's event-driven architecture processes
+        #   threshold notification evaluations in real-time as usage events stream in,
+        #   unlike competitors who rely on periodic polling or batch evaluation cycles
         sig do
           params(
             alert_type:
@@ -29,42 +73,44 @@ module MetronomeSDK
           ).returns(MetronomeSDK::Models::V1::AlertCreateResponse)
         end
         def create(
-          # Type of the alert
+          # Type of the threshold notification
           alert_type:,
-          # Name of the alert
+          # Name of the threshold notification
           name:,
-          # Threshold value of the alert policy. Depending upon the alert type, this number
-          # may represent a financial amount, the days remaining, or a percentage reached.
+          # Threshold value of the notification policy. Depending upon the notification
+          # type, this number may represent a financial amount, the days remaining, or a
+          # percentage reached.
           threshold:,
-          # For alerts of type `usage_threshold_reached`, specifies which billable metric to
-          # track the usage for.
+          # For threshold notifications of type `usage_threshold_reached`, specifies which
+          # billable metric to track the usage for.
           billable_metric_id: nil,
-          # An array of strings, representing a way to filter the credit grant this alert
-          # applies to, by looking at the credit_grant_type field on the credit grant. This
-          # field is only defined for CreditPercentage and CreditBalance alerts
+          # An array of strings, representing a way to filter the credit grant this
+          # threshold notification applies to, by looking at the credit_grant_type field on
+          # the credit grant. This field is only defined for CreditPercentage and
+          # CreditBalance notifications
           credit_grant_type_filters: nil,
-          # ID of the credit's currency, defaults to USD. If the specific alert type
+          # ID of the credit's currency, defaults to USD. If the specific notification type
           # requires a pricing unit/currency, find the ID in the
           # [Metronome app](https://app.metronome.com/offering/pricing-units).
           credit_type_id: nil,
-          # A list of custom field filters for alert types that support advanced filtering.
-          # Only present for contract invoices.
+          # A list of custom field filters for threshold notification types that support
+          # advanced filtering. Only present for contract invoices.
           custom_field_filters: nil,
-          # If provided, will create this alert for this specific customer. To create an
-          # alert for all customers, do not specify a `customer_id`.
+          # If provided, will create this threshold notification for this specific customer.
+          # To create a notification for all customers, do not specify a `customer_id`.
           customer_id: nil,
-          # If true, the alert will evaluate immediately on customers that already meet the
-          # alert threshold. If false, it will only evaluate on future customers that
-          # trigger the alert threshold. Defaults to true.
+          # If true, the threshold notification will evaluate immediately on customers that
+          # already meet the notification threshold. If false, it will only evaluate on
+          # future customers that trigger the threshold. Defaults to true.
           evaluate_on_create: nil,
-          # Only present for `spend_threshold_reached` alerts. Scope alert to a specific
-          # group key on individual line items.
+          # Only present for `spend_threshold_reached` notifications. Scope notification to
+          # a specific group key on individual line items.
           group_values: nil,
-          # Only supported for invoice_total_reached alerts. A list of invoice types to
-          # evaluate.
+          # Only supported for invoice_total_reached threshold notifications. A list of
+          # invoice types to evaluate.
           invoice_types_filter: nil,
-          # If provided, will create this alert for this specific plan. To create an alert
-          # for all customers, do not specify a `plan_id`.
+          # If provided, will create this threshold notification for this specific plan. To
+          # create a notification for all customers, do not specify a `plan_id`.
           plan_id: nil,
           # Prevents the creation of duplicates. If a request to create a record is made
           # with a previously used uniqueness key, a new record will not be created and the
@@ -74,7 +120,34 @@ module MetronomeSDK
         )
         end
 
-        # Archive an existing alert
+        # Permanently disable a threshold notification and remove it from active
+        # monitoring across all customers. Archived threshold notifications stop
+        # evaluating immediately and can optionally release their uniqueness key for reuse
+        # in future threshold notification configurations.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Decommission threshold notifications that are no longer needed
+        # - Clean up test or deprecated threshold notification configurations
+        # - Free up uniqueness keys for reuse with new threshold notifications
+        # - Stop threshold notification evaluations without losing historical
+        #   configuration data
+        # - Disable outdated monitoring rules during pricing model transitions
+        #
+        # ### Key response fields:
+        #
+        # - data: Object containing the archived threshold notification's ID
+        #
+        # ### Usage guidelines:
+        #
+        # - Irreversible for evaluation: Archived threshold notifications cannot be
+        #   re-enabled; create a new threshold notification to resume monitoring
+        # - Uniqueness key handling: Set `release_uniqueness_key` : `true` to reuse the
+        #   key in future threshold notifications
+        # - Immediate effect: Threshold notification evaluation stops instantly across all
+        #   customers
+        # - Historical preservation: Archive operation maintains threshold notification
+        #   history and configuration for compliance and auditing
         sig do
           params(
             id: String,
@@ -83,9 +156,10 @@ module MetronomeSDK
           ).returns(MetronomeSDK::Models::V1::AlertArchiveResponse)
         end
         def archive(
-          # The Metronome ID of the alert
+          # The Metronome ID of the threshold notification
           id:,
-          # If true, resets the uniqueness key on this alert so it can be re-used
+          # If true, resets the uniqueness key on this threshold notification so it can be
+          # re-used
           release_uniqueness_key: nil,
           request_options: {}
         )

data/rbi/metronome_sdk/resources/v1/audit_logs.rbi

@@ -4,10 +4,45 @@ module MetronomeSDK
   module Resources
     class V1
       class AuditLogs
-        # Retrieves a range of audit logs. If no further audit logs are currently
-        # available, the data array will be empty. As new audit logs are created,
-        # subsequent requests using the same next_page value will be in the returned data
-        # array, ensuring a continuous and uninterrupted reading of audit logs.
+        # Get a comprehensive audit trail of all operations performed in your Metronome
+        # account, whether initiated through the API, web interface, or automated
+        # processes. This endpoint provides detailed logs of who did what and when,
+        # enabling compliance reporting, security monitoring, and operational
+        # troubleshooting across all interaction channels.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Monitor all account activity for security and compliance purposes
+        # - Track configuration changes regardless of source (API, UI, or system)
+        # - Investigate issues by reviewing historical operations
+        #
+        # ### Key response fields:
+        #
+        # An array of AuditLog objects containing:
+        #
+        # - id: Unique identifier for the audit log entry
+        # - timestamp: When the action occurred (RFC 3339 format)
+        # - actor: Information about who performed the action
+        # - request: Details including request ID, IP address, and user agent
+        # - `resource_type`: The type of resource affected (e.g., customer, contract,
+        #   invoice)
+        # - `resource_id`: The specific resource identifier
+        # - `action`: The operation performed
+        # - `next_page`: Cursor for continuous log retrieval
+        #
+        # ### Usage guidelines:
+        #
+        # - Continuous retrieval: The next_page token enables uninterrupted log
+        #   streaming—save it between requests to ensure no logs are missed
+        # - Empty responses: An empty data array means no new logs yet; continue polling
+        #   with the same next_page token
+        # - Date filtering:
+        #   - `starting_on`: Earliest logs to return (inclusive)
+        #   - `ending_before`: Latest logs to return (exclusive)
+        #   - Cannot be used with `next_page`
+        # - Resource filtering: Must specify both `resource_type` and `resource_id`
+        #   together
+        # - Sort order: Default is `date_asc`; use `date_desc` for newest first
         sig do
           params(
             ending_before: Time,

data/rbi/metronome_sdk/resources/v1/billable_metrics.rbi

@@ -4,7 +4,35 @@ module MetronomeSDK
   module Resources
     class V1
       class BillableMetrics
-        # Creates a new Billable Metric.
+        # Create billable metrics programmatically with this endpoint—an essential step in
+        # configuring your pricing and packaging in Metronome.
+        #
+        # A billable metric is a customizable query that filters and aggregates events
+        # from your event stream. These metrics are continuously tracked as usage data
+        # enters Metronome through the ingestion pipeline. The ingestion process
+        # transforms raw usage data into actionable pricing metrics, enabling accurate
+        # metering and billing for your products.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Create individual or multiple billable metrics as part of a setup workflow.
+        # - Automate the entire pricing configuration process, from metric creation to
+        #   customer contract setup.
+        # - Define metrics using either standard filtering/aggregation or a custom SQL
+        #   query.
+        #
+        # ### Key response fields:
+        #
+        # - The ID of the billable metric that was created
+        # - The created billable metric will be available to be used in Products, usage
+        #   endpoints, and alerts.
+        #
+        # ### Usage guidelines:
+        #
+        # - Metrics defined using standard filtering and aggregation are Streaming
+        #   billable metrics, which have been optimized for ultra low latency and high
+        #   throughput workflows.
+        # - Use SQL billable metrics if you require more flexible aggregation options.
         sig do
           params(
             name: String,
@@ -47,7 +75,17 @@ module MetronomeSDK
         )
         end
 
-        # Get a billable metric.
+        # Retrieves the complete configuration for a specific billable metric by its ID.
+        # Use this to review billable metric setup before associating it with products.
+        # Returns the metric's `name`, `event_type_filter`, `property_filters`,
+        # `aggregation_type`, `aggregation_key`, `group_keys`, `custom fields`, and
+        # `SQL query` (if it's a SQL billable metric).
+        #
+        # Important:
+        #
+        # - Archived billable metrics will include an `archived_at` timestamp; they no
+        #   longer process new usage events but remain accessible for historical
+        #   reference.
         sig do
           params(
             billable_metric_id: String,
@@ -57,7 +95,11 @@ module MetronomeSDK
         def retrieve(billable_metric_id:, request_options: {})
         end
 
-        # List all billable metrics.
+        # Retrieves all billable metrics with their complete configurations. Use this for
+        # programmatic discovery and management of billable metrics, such as associating
+        # metrics to products and auditing for orphaned or archived metrics. Important:
+        # Archived metrics are excluded by default; use `include_archived`=`true`
+        # parameter to include them.
         sig do
           params(
             include_archived: T::Boolean,
@@ -81,7 +123,15 @@ module MetronomeSDK
         )
         end
 
-        # Archive an existing billable metric.
+        # Use this endpoint to retire billable metrics that are no longer used. After a
+        # billable metric is archived, that billable metric can no longer be used in any
+        # new Products to define how that product should be metered. If you archive a
+        # billable metric that is already associated with a Product, the Product will
+        # continue to function as usual, metering based on the definition of the archived
+        # billable metric.
+        #
+        # Archived billable metrics will be returned on the `getBillableMetric` and
+        # `listBillableMetrics` endpoints with a populated `archived_at` field.
         sig do
           params(
             id: String,

data/rbi/metronome_sdk/resources/v1/contracts/products.rbi

@@ -5,7 +5,11 @@ module MetronomeSDK
     class V1
       class Contracts
         class Products
-          # Create a new product
+          # Create a new product object. Products in Metronome represent your company's
+          # individual product or service offerings. A Product can be thought of as the
+          # basic unit of a line item on the invoice. This is analogous to SKUs or items in
+          # an ERP system. Give the product a meaningful name as they will appear on
+          # customer invoices.
           sig do
             params(
               name: String,
@@ -45,6 +49,7 @@ module MetronomeSDK
             composite_product_ids: nil,
             # Required for COMPOSITE products
             composite_tags: nil,
+            # Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
             custom_fields: nil,
             # Beta feature only available for composite products. If true, products with $0
             # will not be included when computing composite usage. Defaults to false
@@ -83,7 +88,7 @@ module MetronomeSDK
           )
           end
 
-          # Get a specific product
+          # Retrieve a product by its ID, including all metadata and historical changes.
           sig do
             params(
               id: String,
@@ -95,7 +100,17 @@ module MetronomeSDK
           def retrieve(id:, request_options: {})
           end
 
-          # Update a product
+          # Updates a product's configuration while maintaining billing continuity for
+          # active customers. Use this endpoint to modify product names, metrics, pricing
+          # rules, and composite settings without disrupting ongoing billing cycles. Changes
+          # are scheduled using the starting_at timestamp, which must be on an hour
+          # boundary—set future dates to schedule updates ahead of time, or past dates for
+          # retroactive changes. Returns the updated product ID upon success.
+          #
+          # ### Usage guidance:
+          #
+          # - Product type cannot be changed after creation. For incorrect product types,
+          #   create a new product and archive the original instead.
           sig do
             params(
               product_id: String,
@@ -182,7 +197,9 @@ module MetronomeSDK
           )
           end
 
-          # List products
+          # Get a paginated list of all products in your organization with their complete
+          # configuration, version history, and metadata. By default excludes archived
+          # products unless explicitly requested via the `archive_filter` parameter.
           sig do
             params(
               limit: Integer,
@@ -208,7 +225,10 @@ module MetronomeSDK
           )
           end
 
-          # Archive a product
+          # Archive a product. Any current rate cards associated with this product will
+          # continue to function as normal. However, it will no longer be available as an
+          # option for newly created rates. Once you archive a product, you can still
+          # retrieve it in the UI and API, but you cannot unarchive it.
           sig do
             params(
               product_id: String,

data/rbi/metronome_sdk/resources/v1/contracts/rate_cards/product_orders.rbi

@@ -6,7 +6,10 @@ module MetronomeSDK
       class Contracts
         class RateCards
           class ProductOrders
-            # Updates ordering of specified products
+            # The ordering of products on a rate card determines the order in which the
+            # products will appear on customers' invoices. Use this endpoint to set the order
+            # of specific products on the rate card by moving them relative to their current
+            # location.
             sig do
               params(
                 product_moves:
@@ -27,7 +30,9 @@ module MetronomeSDK
             )
             end
 
-            # Sets the ordering of products within a rate card
+            # The ordering of products on a rate card determines the order in which the
+            # products will appear on customers' invoices. Use this endpoint to set the order
+            # of products on the rate card.
             sig do
               params(
                 product_order: T::Array[String],

data/rbi/metronome_sdk/resources/v1/contracts/rate_cards/rates.rbi

@@ -6,7 +6,15 @@ module MetronomeSDK
       class Contracts
         class RateCards
           class Rates
-            # Get all rates for a rate card at a point in time
+            # Understand the rate schedule at a given timestamp, optionally filtering the list
+            # of rates returned based on properties such as `product_id` and
+            # `pricing_group_values`. For example, you may want to display the current price
+            # for a given product in your product experience - use this endpoint to fetch that
+            # information from its source of truth in Metronome.
+            #
+            # If you want to understand the rates for a specific customer's contract,
+            # inclusive of contract-level overrides, use the `getContractRateSchedule`
+            # endpoint.
             sig do
               params(
                 at: Time,
@@ -52,8 +60,7 @@ module MetronomeSDK
                 starting_at: Time,
                 billing_frequency:
                   MetronomeSDK::V1::Contracts::RateCards::RateAddParams::BillingFrequency::OrSymbol,
-                commit_rate:
-                  MetronomeSDK::V1::Contracts::RateCards::RateAddParams::CommitRate::OrHash,
+                commit_rate: MetronomeSDK::CommitRate::OrHash,
                 credit_type_id: String,
                 custom_rate: T::Hash[Symbol, T.anything],
                 ending_before: Time,