metronome-sdk 0.2.0 → 1.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 alert to monitor customer spending, balances, and billing metrics
+        # in real-time. Metronome's alert system provides industry-leading speed with
+        # immediate evaluation capabilities, enabling you to proactively manage customer
+        # accounts and prevent revenue leakage.
+        #
+        # This endpoint creates configurable alerts that continuously monitor various
+        # billing thresholds including spend limits, credit balances, commitment
+        # utilization, and invoice totals. Alerts can be configured globally for all
+        # customers or targeted to specific customer accounts. Custom fields can be used
+        # on certain alert types to further target alerts to groups of customers.
+        #
+        # ### 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 alert configuration with its unique ID and current status
+        # - The customer's evaluation status (ok, in_alarm, or evaluating)
+        # - Alert 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 alert must have a unique `uniqueness_key` within
+        #   your organization. Use `release_uniqueness_key` : `true` when archiving to
+        #   reuse keys
+        # - Alert type requirements: Different alert types require specific fields (e.g.,
+        #   `billable_metric_id` for usage alerts, `credit_type_id` for credit-based
+        #   alerts)
+        # - Webhook delivery: Alerts trigger webhook notifications for real-time
+        #   integration with your systems. Configure webhook endpoints before creating
+        #   alerts
+        # - Performance at scale: Metronome's event-driven architecture processes alert
+        #   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:
@@ -74,7 +118,33 @@ module MetronomeSDK
         )
         end
 
-        # Archive an existing alert
+        # Permanently disable an alert and remove it from active monitoring across all
+        # customers. Archived alerts stop evaluating immediately and can optionally
+        # release their uniqueness key for reuse in future alert configurations.
+        #
+        # ### Use this endpoint to:
+        #
+        # - Decommission alerts that are no longer needed
+        # - Clean up test or deprecated alert configurations
+        # - Free up uniqueness keys for reuse with new alerts
+        # - Stop alert evaluations without losing historical configuration data
+        # - Disable outdated monitoring rules during pricing model transitions
+        #
+        # ### Key response fields:
+        #
+        # - data: Object containing the archived alert's ID
+        # - Alert evaluation stops immediately for all affected customers
+        # - Historical alert data and configurations remain accessible for audit purposes
+        #
+        # ### Usage guidelines:
+        #
+        # - Irreversible for evaluation: Archived alerts cannot be re-enabled; create a
+        #   new alert to resume monitoring
+        # - Uniqueness key handling: Set `release_uniqueness_key` : `true` to reuse the
+        #   key in future alerts
+        # - Immediate effect: Alert evaluation stops instantly across all customers
+        # - Historical preservation: Archive operation maintains alert history and
+        #   configuration for compliance and auditing
         sig do
           params(
             id: String,

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,
@@ -14,6 +18,7 @@ module MetronomeSDK
               billable_metric_id: String,
               composite_product_ids: T::Array[String],
               composite_tags: T::Array[String],
+              custom_fields: T::Hash[Symbol, String],
               exclude_free_usage: T::Boolean,
               is_refundable: T::Boolean,
               netsuite_internal_item_id: String,
@@ -44,6 +49,8 @@ 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
             exclude_free_usage: nil,
@@ -81,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,
@@ -93,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,
@@ -180,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,
@@ -206,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,

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

@@ -24,7 +24,39 @@ module MetronomeSDK
           end
           attr_reader :named_schedules
 
-          # Create a new rate card
+          # In Metronome, the rate card is the central location for your pricing. Rate cards
+          # were built with new product launches and pricing changes in mind - you can
+          # update your products and pricing in one place, and that change will be
+          # automatically propagated across your customer cohorts. Most clients need only
+          # maintain one or a few rate cards within Metronome.
+          #
+          # ### Use this endpoint to:
+          #
+          # - Create a rate card with a name and description
+          # - Define the rate card's single underlying fiat currency, and any number of
+          #   conversion rates between that fiat currency and custom pricing units. You can
+          #   then add products and associated rates in the fiat currency or custom pricing
+          #   unit for which you have defined a conversion rate.
+          # - Set aliases for the rate card. Aliases are human-readable names that you can
+          #   use in the place of the id of the rate card when provisioning a customer's
+          #   contract. By using an alias, you can easily create a contract and provision a
+          #   customer by choosing the paygo rate card, without storing the rate card id in
+          #   your internal systems. This is helpful when launching a new rate card for
+          #   paygo customers, you can update the alias for paygo to be scheduled to be
+          #   assigned to the new rate card without updating your code.
+          #
+          # ### Key response fields:
+          #
+          # - The ID of the rate card you just created
+          #
+          # ### Usage guidelines:
+          #
+          # - After creating a rate card, you can now use the addRate or addRates endpoints
+          #   to add products and their prices to it
+          # - A rate card alias can only be used by one rate card at a time. If you create a
+          #   contract with a rate card alias that is already in use by another rate card,
+          #   the original rate card's alias schedule will be updated. The alias will
+          #   reference the rate card to which it was most recently assigned.
           sig do
             params(
               name: String,
@@ -53,6 +85,7 @@ module MetronomeSDK
             aliases: nil,
             # Required when using custom pricing units in rates.
             credit_type_conversions: nil,
+            # Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
             custom_fields: nil,
             description: nil,
             # The Metronome ID of the credit type to associate with the rate card, defaults to
@@ -62,8 +95,9 @@ module MetronomeSDK
           )
           end
 
-          # Get a specific rate card NOTE: Use `/contract-pricing/rate-cards/getRates` to
-          # retrieve rate card rates.
+          # Return details for a specific rate card including name, description, and
+          # aliases. This endpoint does not return rates - use the dedicated getRates or
+          # getRateSchedule endpoints to understand the rates on a rate card.
           sig do
             params(
               id: String,
@@ -75,7 +109,58 @@ module MetronomeSDK
           def retrieve(id:, request_options: {})
           end
 
-          # Update a rate card
+          # Update the metadata properties of an existing rate card, including its name,
+          # description, and aliases. This endpoint is designed for managing rate card
+          # identity and reference aliases rather than modifying pricing rates.
+          #
+          # Modifies the descriptive properties and alias configuration of a rate card
+          # without affecting the underlying pricing rates or schedules. This allows you to
+          # update how a rate card is identified and referenced throughout your system.
+          #
+          # ### Use this endpoint to:
+          #
+          # - Rate card renaming: Update display names or descriptions for organizational
+          #   clarity
+          # - Alias management: Add, modify, or schedule alias transitions for seamless rate
+          #   card migrations
+          # - Documentation updates: Keep rate card descriptions current with business
+          #   context
+          # - Self-serve provisioning setup: Configure aliases to enable code-free rate card
+          #   transitions
+          #
+          # #### Active contract impact:
+          #
+          # - Alias changes: Already-created contracts continue using their originally
+          #   assigned rate cards.
+          # - Other changes made using this endpoint will only impact the Metronome UI.
+          #
+          # #### Grandfathering existing PLG customer pricing:
+          #
+          # - Rate card aliases support scheduled transitions, enabling seamless rate card
+          #   migrations for new customers, allowing existing customers to be grandfathered
+          #   into their existing prices without code. Note that there are multiple
+          #   mechanisms to support grandfathering in Metronome.
+          #
+          # #### How scheduled aliases work for PLG grandfathering:
+          #
+          # Initial setup:
+          #
+          # - Add alias to current rate card: Assign a stable alias (e.g.,
+          #   "standard-pricing") to your active rate card
+          # - Reference alias during contract creation: Configure your self-serve workflow
+          #   to create contracts using `rate_card_alias` instead of direct `rate_card_id`
+          # - Automatic resolution: New contracts referencing the alias automatically
+          #   resolve to the rate card associated with the alias at the point in time of
+          #   provisioning
+          #
+          # #### Grandfathering process:
+          #
+          # - Create new rate card: Build your new rate card with updated pricing structure
+          # - Schedule alias transition: Add the same alias to the new rate card with a
+          #   `starting_at` timestamp
+          # - Automatic cutover: Starting at the scheduled time, new contracts created in
+          #   your PLG workflow using that alias will automatically reference the new rate
+          #   card
           sig do
             params(
               rate_card_id: String,
@@ -104,8 +189,9 @@ module MetronomeSDK
           )
           end
 
-          # List rate cards NOTE: Use `/contract-pricing/rate-cards/getRates` to retrieve
-          # rate card rates.
+          # List all rate cards. Returns rate card IDs, names, descriptions, aliases, and
+          # other details. To view the rates associated with a given rate card, use the
+          # getRates or getRateSchedule endpoints.
           sig do
             params(
               limit: Integer,
@@ -129,7 +215,11 @@ module MetronomeSDK
           )
           end
 
-          # Archive a rate card
+          # Permanently disable a rate card by archiving it, preventing use in new contracts
+          # while preserving existing contract pricing. Use this when retiring old pricing
+          # models, consolidating rate cards, or removing outdated pricing structures.
+          # Returns the archived rate card ID and stops the rate card from appearing in
+          # contract creation workflows.
           sig do
             params(
               id: String,
@@ -141,8 +231,18 @@ module MetronomeSDK
           def archive(id:, request_options: {})
           end
 
-          # Get all rates for a rate card from starting_at (either in perpetuity or until
-          # ending_before, if provided)
+          # A rate card defines the prices that you charge for your products. Rate cards
+          # support scheduled changes over time, to allow you to easily roll out pricing
+          # changes and new product launches across your customer base. Use this endpoint to
+          # understand the rate schedule `starting_at` a given date, optionally filtering
+          # the list of rates returned based on product id or pricing group values. For
+          # example, you may want to display a schedule of upcoming price changes 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(
               rate_card_id: String,