dodopayments 1.51.1 → 1.52.5

data/rbi/dodopayments/resources/usage_events.rbi

@@ -0,0 +1,175 @@
+# typed: strong
+
+module Dodopayments
+  module Resources
+    class UsageEvents
+      # Fetch detailed information about a single event using its unique event ID. This
+      # endpoint is useful for:
+      #
+      # - Debugging specific event ingestion issues
+      # - Retrieving event details for customer support
+      # - Validating that events were processed correctly
+      # - Getting the complete metadata for an event
+      #
+      # ## Event ID Format:
+      #
+      # The event ID should be the same value that was provided during event ingestion
+      # via the `/events/ingest` endpoint. Event IDs are case-sensitive and must match
+      # exactly.
+      #
+      # ## Response Details:
+      #
+      # The response includes all event data including:
+      #
+      # - Complete metadata key-value pairs
+      # - Original timestamp (preserved from ingestion)
+      # - Customer and business association
+      # - Event name and processing information
+      #
+      # ## Example Usage:
+      #
+      # ```text
+      # GET /events/api_call_12345
+      # ```
+      sig do
+        params(
+          event_id: String,
+          request_options: Dodopayments::RequestOptions::OrHash
+        ).returns(Dodopayments::Event)
+      end
+      def retrieve(
+        # Unique event identifier (case-sensitive, must match the ID used during
+        # ingestion)
+        event_id,
+        request_options: {}
+      )
+      end
+
+      # Fetch events from your account with powerful filtering capabilities. This
+      # endpoint is ideal for:
+      #
+      # - Debugging event ingestion issues
+      # - Analyzing customer usage patterns
+      # - Building custom analytics dashboards
+      # - Auditing billing-related events
+      #
+      # ## Filtering Options:
+      #
+      # - **Customer filtering**: Filter by specific customer ID
+      # - **Event name filtering**: Filter by event type/name
+      # - **Meter-based filtering**: Use a meter ID to apply the meter's event name and
+      #   filter criteria automatically
+      # - **Time range filtering**: Filter events within a specific date range
+      # - **Pagination**: Navigate through large result sets
+      #
+      # ## Meter Integration:
+      #
+      # When using `meter_id`, the endpoint automatically applies:
+      #
+      # - The meter's configured `event_name` filter
+      # - The meter's custom filter criteria (if any)
+      # - If you also provide `event_name`, it must match the meter's event name
+      #
+      # ## Example Queries:
+      #
+      # - Get all events for a customer: `?customer_id=cus_abc123`
+      # - Get API request events: `?event_name=api_request`
+      # - Get events from last 24 hours:
+      #   `?start=2024-01-14T10:30:00Z&end=2024-01-15T10:30:00Z`
+      # - Get events with meter filtering: `?meter_id=mtr_xyz789`
+      # - Paginate results: `?page_size=50&page_number=2`
+      sig do
+        params(
+          customer_id: String,
+          end_: Time,
+          event_name: String,
+          meter_id: String,
+          page_number: Integer,
+          page_size: Integer,
+          start: Time,
+          request_options: Dodopayments::RequestOptions::OrHash
+        ).returns(
+          Dodopayments::Internal::DefaultPageNumberPagination[
+            Dodopayments::Event
+          ]
+        )
+      end
+      def list(
+        # Filter events by customer ID
+        customer_id: nil,
+        # Filter events created before this timestamp
+        end_: nil,
+        # Filter events by event name. If both event_name and meter_id are provided, they
+        # must match the meter's configured event_name
+        event_name: nil,
+        # Filter events by meter ID. When provided, only events that match the meter's
+        # event_name and filter criteria will be returned
+        meter_id: nil,
+        # Page number (0-based, default: 0)
+        page_number: nil,
+        # Number of events to return per page (default: 10)
+        page_size: nil,
+        # Filter events created after this timestamp
+        start: nil,
+        request_options: {}
+      )
+      end
+
+      # This endpoint allows you to ingest custom events that can be used for:
+      #
+      # - Usage-based billing and metering
+      # - Analytics and reporting
+      # - Customer behavior tracking
+      #
+      # ## Important Notes:
+      #
+      # - **Duplicate Prevention**:
+      #   - Duplicate `event_id` values within the same request are rejected (entire
+      #     request fails)
+      #   - Subsequent requests with existing `event_id` values are ignored (idempotent
+      #     behavior)
+      # - **Rate Limiting**: Maximum 1000 events per request
+      # - **Time Validation**: Events with timestamps older than 1 hour or more than 5
+      #   minutes in the future will be rejected
+      # - **Metadata Limits**: Maximum 50 key-value pairs per event, keys max 100 chars,
+      #   values max 500 chars
+      #
+      # ## Example Usage:
+      #
+      # ```json
+      # {
+      #   "events": [
+      #     {
+      #       "event_id": "api_call_12345",
+      #       "customer_id": "cus_abc123",
+      #       "event_name": "api_request",
+      #       "timestamp": "2024-01-15T10:30:00Z",
+      #       "metadata": {
+      #         "endpoint": "/api/v1/users",
+      #         "method": "GET",
+      #         "tokens_used": "150"
+      #       }
+      #     }
+      #   ]
+      # }
+      # ```
+      sig do
+        params(
+          events: T::Array[Dodopayments::EventInput::OrHash],
+          request_options: Dodopayments::RequestOptions::OrHash
+        ).returns(Dodopayments::Models::UsageEventIngestResponse)
+      end
+      def ingest(
+        # List of events to be pushed
+        events:,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Dodopayments::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/sig/dodopayments/client.rbs

@@ -51,6 +51,10 @@ module Dodopayments
 
     attr_reader webhooks: Dodopayments::Resources::Webhooks
 
+    attr_reader usage_events: Dodopayments::Resources::UsageEvents
+
+    attr_reader meters: Dodopayments::Resources::Meters
+
     private def auth_headers: -> ::Hash[String, String]
 
     def initialize: (

data/sig/dodopayments/models/add_meter_to_price.rbs

@@ -0,0 +1,45 @@
+module Dodopayments
+  module Models
+    type add_meter_to_price =
+      {
+        meter_id: String,
+        price_per_unit: String,
+        description: String?,
+        free_threshold: Integer?,
+        measurement_unit: String?,
+        name: String?
+      }
+
+    class AddMeterToPrice < Dodopayments::Internal::Type::BaseModel
+      attr_accessor meter_id: String
+
+      attr_accessor price_per_unit: String
+
+      attr_accessor description: String?
+
+      attr_accessor free_threshold: Integer?
+
+      attr_accessor measurement_unit: String?
+
+      attr_accessor name: String?
+
+      def initialize: (
+        meter_id: String,
+        price_per_unit: String,
+        ?description: String?,
+        ?free_threshold: Integer?,
+        ?measurement_unit: String?,
+        ?name: String?
+      ) -> void
+
+      def to_hash: -> {
+        meter_id: String,
+        price_per_unit: String,
+        description: String?,
+        free_threshold: Integer?,
+        measurement_unit: String?,
+        name: String?
+      }
+    end
+  end
+end

data/sig/dodopayments/models/event.rbs

@@ -0,0 +1,53 @@
+module Dodopayments
+  module Models
+    type event =
+      {
+        business_id: String,
+        customer_id: String,
+        event_id: String,
+        event_name: String,
+        timestamp: Time,
+        metadata: ::Hash[Symbol, Dodopayments::Models::Event::metadata]?
+      }
+
+    class Event < Dodopayments::Internal::Type::BaseModel
+      attr_accessor business_id: String
+
+      attr_accessor customer_id: String
+
+      attr_accessor event_id: String
+
+      attr_accessor event_name: String
+
+      attr_accessor timestamp: Time
+
+      attr_accessor metadata: ::Hash[Symbol, Dodopayments::Models::Event::metadata]?
+
+      def initialize: (
+        business_id: String,
+        customer_id: String,
+        event_id: String,
+        event_name: String,
+        timestamp: Time,
+        ?metadata: ::Hash[Symbol, Dodopayments::Models::Event::metadata]?
+      ) -> void
+
+      def to_hash: -> {
+        business_id: String,
+        customer_id: String,
+        event_id: String,
+        event_name: String,
+        timestamp: Time,
+        metadata: ::Hash[Symbol, Dodopayments::Models::Event::metadata]?
+      }
+
+      type metadata = String | Float | bool
+
+      module Metadata
+        extend Dodopayments::Internal::Type::Union
+
+        def self?.variants: -> ::Array[Dodopayments::Models::Event::metadata]
+      end
+    end
+  end
+end

data/sig/dodopayments/models/event_input.rbs

@@ -0,0 +1,48 @@
+module Dodopayments
+  module Models
+    type event_input =
+      {
+        customer_id: String,
+        event_id: String,
+        event_name: String,
+        metadata: ::Hash[Symbol, Dodopayments::Models::EventInput::metadata]?,
+        timestamp: Time?
+      }
+
+    class EventInput < Dodopayments::Internal::Type::BaseModel
+      attr_accessor customer_id: String
+
+      attr_accessor event_id: String
+
+      attr_accessor event_name: String
+
+      attr_accessor metadata: ::Hash[Symbol, Dodopayments::Models::EventInput::metadata]?
+
+      attr_accessor timestamp: Time?
+
+      def initialize: (
+        customer_id: String,
+        event_id: String,
+        event_name: String,
+        ?metadata: ::Hash[Symbol, Dodopayments::Models::EventInput::metadata]?,
+        ?timestamp: Time?
+      ) -> void
+
+      def to_hash: -> {
+        customer_id: String,
+        event_id: String,
+        event_name: String,
+        metadata: ::Hash[Symbol, Dodopayments::Models::EventInput::metadata]?,
+        timestamp: Time?
+      }
+
+      type metadata = String | Float | bool
+
+      module Metadata
+        extend Dodopayments::Internal::Type::Union
+
+        def self?.variants: -> ::Array[Dodopayments::Models::EventInput::metadata]
+      end
+    end
+  end
+end

data/sig/dodopayments/models/invoices/payment_retrieve_refund_params.rbs

@@ -0,0 +1,17 @@
+module Dodopayments
+  module Models
+    module Invoices
+      type payment_retrieve_refund_params =
+        {  } & Dodopayments::Internal::Type::request_parameters
+
+      class PaymentRetrieveRefundParams < Dodopayments::Internal::Type::BaseModel
+        extend Dodopayments::Internal::Type::RequestParameters::Converter
+        include Dodopayments::Internal::Type::RequestParameters
+
+        def initialize: (?request_options: Dodopayments::request_opts) -> void
+
+        def to_hash: -> { request_options: Dodopayments::RequestOptions }
+      end
+    end
+  end
+end

data/sig/dodopayments/models/meter.rbs

@@ -0,0 +1,65 @@
+module Dodopayments
+  module Models
+    type meter =
+      {
+        id: String,
+        aggregation: Dodopayments::MeterAggregation,
+        business_id: String,
+        created_at: Time,
+        event_name: String,
+        measurement_unit: String,
+        name: String,
+        updated_at: Time,
+        description: String?,
+        filter: Dodopayments::MeterFilter?
+      }
+
+    class Meter < Dodopayments::Internal::Type::BaseModel
+      attr_accessor id: String
+
+      attr_accessor aggregation: Dodopayments::MeterAggregation
+
+      attr_accessor business_id: String
+
+      attr_accessor created_at: Time
+
+      attr_accessor event_name: String
+
+      attr_accessor measurement_unit: String
+
+      attr_accessor name: String
+
+      attr_accessor updated_at: Time
+
+      attr_accessor description: String?
+
+      attr_accessor filter: Dodopayments::MeterFilter?
+
+      def initialize: (
+        id: String,
+        aggregation: Dodopayments::MeterAggregation,
+        business_id: String,
+        created_at: Time,
+        event_name: String,
+        measurement_unit: String,
+        name: String,
+        updated_at: Time,
+        ?description: String?,
+        ?filter: Dodopayments::MeterFilter?
+      ) -> void
+
+      def to_hash: -> {
+        id: String,
+        aggregation: Dodopayments::MeterAggregation,
+        business_id: String,
+        created_at: Time,
+        event_name: String,
+        measurement_unit: String,
+        name: String,
+        updated_at: Time,
+        description: String?,
+        filter: Dodopayments::MeterFilter?
+      }
+    end
+  end
+end

data/sig/dodopayments/models/meter_aggregation.rbs

@@ -0,0 +1,35 @@
+module Dodopayments
+  module Models
+    type meter_aggregation =
+      { type: Dodopayments::Models::MeterAggregation::type_, key: String? }
+
+    class MeterAggregation < Dodopayments::Internal::Type::BaseModel
+      attr_accessor type: Dodopayments::Models::MeterAggregation::type_
+
+      attr_accessor key: String?
+
+      def initialize: (
+        type: Dodopayments::Models::MeterAggregation::type_,
+        ?key: String?
+      ) -> void
+
+      def to_hash: -> {
+        type: Dodopayments::Models::MeterAggregation::type_,
+        key: String?
+      }
+
+      type type_ = :count | :sum | :max | :last
+
+      module Type
+        extend Dodopayments::Internal::Type::Enum
+
+        COUNT: :count
+        SUM: :sum
+        MAX: :max
+        LAST: :last
+
+        def self?.values: -> ::Array[Dodopayments::Models::MeterAggregation::type_]
+      end
+    end
+  end
+end

data/sig/dodopayments/models/meter_archive_params.rbs

@@ -0,0 +1,15 @@
+module Dodopayments
+  module Models
+    type meter_archive_params =
+      {  } & Dodopayments::Internal::Type::request_parameters
+
+    class MeterArchiveParams < Dodopayments::Internal::Type::BaseModel
+      extend Dodopayments::Internal::Type::RequestParameters::Converter
+      include Dodopayments::Internal::Type::RequestParameters
+
+      def initialize: (?request_options: Dodopayments::request_opts) -> void
+
+      def to_hash: -> { request_options: Dodopayments::RequestOptions }
+    end
+  end
+end

data/sig/dodopayments/models/meter_create_params.rbs

@@ -0,0 +1,51 @@
+module Dodopayments
+  module Models
+    type meter_create_params =
+      {
+        aggregation: Dodopayments::MeterAggregation,
+        event_name: String,
+        measurement_unit: String,
+        name: String,
+        description: String?,
+        filter: Dodopayments::MeterFilter?
+      }
+      & Dodopayments::Internal::Type::request_parameters
+
+    class MeterCreateParams < Dodopayments::Internal::Type::BaseModel
+      extend Dodopayments::Internal::Type::RequestParameters::Converter
+      include Dodopayments::Internal::Type::RequestParameters
+
+      attr_accessor aggregation: Dodopayments::MeterAggregation
+
+      attr_accessor event_name: String
+
+      attr_accessor measurement_unit: String
+
+      attr_accessor name: String
+
+      attr_accessor description: String?
+
+      attr_accessor filter: Dodopayments::MeterFilter?
+
+      def initialize: (
+        aggregation: Dodopayments::MeterAggregation,
+        event_name: String,
+        measurement_unit: String,
+        name: String,
+        ?description: String?,
+        ?filter: Dodopayments::MeterFilter?,
+        ?request_options: Dodopayments::request_opts
+      ) -> void
+
+      def to_hash: -> {
+        aggregation: Dodopayments::MeterAggregation,
+        event_name: String,
+        measurement_unit: String,
+        name: String,
+        description: String?,
+        filter: Dodopayments::MeterFilter?,
+        request_options: Dodopayments::RequestOptions
+      }
+    end
+  end
+end