dodopayments 2.9.0 → 2.10.0

data/rbi/dodopayments/models/entitlements/entitlement_grant.rbi

@@ -14,24 +14,31 @@ module Dodopayments
             )
           end
 
+        # Unique identifier of the grant.
         sig { returns(String) }
         attr_accessor :id
 
+        # Identifier of the business that owns the grant.
         sig { returns(String) }
         attr_accessor :business_id
 
+        # Timestamp when the grant was created.
         sig { returns(Time) }
         attr_accessor :created_at
 
+        # Identifier of the customer the grant was issued to.
         sig { returns(String) }
         attr_accessor :customer_id
 
+        # Identifier of the entitlement this grant was issued from.
         sig { returns(String) }
         attr_accessor :entitlement_id
 
-        sig { returns(String) }
-        attr_accessor :external_id
+        # Arbitrary key-value metadata recorded on the grant.
+        sig { returns(T::Hash[Symbol, String]) }
+        attr_accessor :metadata
 
+        # Lifecycle status of the grant.
         sig do
           returns(
             Dodopayments::Entitlements::EntitlementGrant::Status::TaggedSymbol
@@ -39,14 +46,16 @@ module Dodopayments
         end
         attr_accessor :status
 
+        # Timestamp when the grant was last modified.
         sig { returns(Time) }
         attr_accessor :updated_at
 
+        # Timestamp when the grant transitioned to `delivered`, when applicable.
         sig { returns(T.nilable(Time)) }
         attr_accessor :delivered_at
 
-        # Present only when the entitlement integration_type is `digital_files`. Populated
-        # eagerly on every list and single-record endpoint.
+        # Digital-product-delivery payload, present when the entitlement integration is
+        # `digital_files`.
         sig { returns(T.nilable(Dodopayments::DigitalProductDelivery)) }
         attr_reader :digital_product_delivery
 
@@ -58,13 +67,16 @@ module Dodopayments
         end
         attr_writer :digital_product_delivery
 
+        # Machine-readable code reported when delivery failed, when applicable.
         sig { returns(T.nilable(String)) }
         attr_accessor :error_code
 
+        # Human-readable message reported when delivery failed, when applicable.
         sig { returns(T.nilable(String)) }
         attr_accessor :error_message
 
-        # Present only when the entitlement integration_type is `license_key`.
+        # License-key delivery payload, present when the entitlement integration is
+        # `license_key`.
         sig { returns(T.nilable(Dodopayments::Entitlements::LicenseKeyGrant)) }
         attr_reader :license_key
 
@@ -76,30 +88,34 @@ module Dodopayments
         end
         attr_writer :license_key
 
-        sig { returns(T.nilable(T.anything)) }
-        attr_reader :metadata
-
-        sig { params(metadata: T.anything).void }
-        attr_writer :metadata
-
+        # Timestamp when `oauth_url` stops being valid, when applicable.
         sig { returns(T.nilable(Time)) }
         attr_accessor :oauth_expires_at
 
+        # Customer-facing OAuth URL for OAuth-style integrations. Populated during the
+        # customer-portal accept flow; `null` until the customer completes that step, and
+        # on grants for non-OAuth integrations.
         sig { returns(T.nilable(String)) }
         attr_accessor :oauth_url
 
+        # Identifier of the payment that triggered this grant, when applicable.
         sig { returns(T.nilable(String)) }
         attr_accessor :payment_id
 
+        # Reason recorded when the grant was revoked, when applicable.
         sig { returns(T.nilable(String)) }
         attr_accessor :revocation_reason
 
+        # Timestamp when the grant transitioned to `revoked`, when applicable.
         sig { returns(T.nilable(Time)) }
         attr_accessor :revoked_at
 
+        # Identifier of the subscription that triggered this grant, when applicable.
         sig { returns(T.nilable(String)) }
         attr_accessor :subscription_id
 
+        # Detailed view of a single entitlement grant: who it's for, its lifecycle state,
+        # and any integration-specific delivery payload.
         sig do
           params(
             id: String,
@@ -107,7 +123,7 @@ module Dodopayments
             created_at: Time,
             customer_id: String,
             entitlement_id: String,
-            external_id: String,
+            metadata: T::Hash[Symbol, String],
             status:
               Dodopayments::Entitlements::EntitlementGrant::Status::OrSymbol,
             updated_at: Time,
@@ -118,7 +134,6 @@ module Dodopayments
             error_message: T.nilable(String),
             license_key:
               T.nilable(Dodopayments::Entitlements::LicenseKeyGrant::OrHash),
-            metadata: T.anything,
             oauth_expires_at: T.nilable(Time),
             oauth_url: T.nilable(String),
             payment_id: T.nilable(String),
@@ -128,28 +143,47 @@ module Dodopayments
           ).returns(T.attached_class)
         end
         def self.new(
+          # Unique identifier of the grant.
           id:,
+          # Identifier of the business that owns the grant.
           business_id:,
+          # Timestamp when the grant was created.
           created_at:,
+          # Identifier of the customer the grant was issued to.
           customer_id:,
+          # Identifier of the entitlement this grant was issued from.
           entitlement_id:,
-          external_id:,
+          # Arbitrary key-value metadata recorded on the grant.
+          metadata:,
+          # Lifecycle status of the grant.
           status:,
+          # Timestamp when the grant was last modified.
           updated_at:,
+          # Timestamp when the grant transitioned to `delivered`, when applicable.
           delivered_at: nil,
-          # Present only when the entitlement integration_type is `digital_files`. Populated
-          # eagerly on every list and single-record endpoint.
+          # Digital-product-delivery payload, present when the entitlement integration is
+          # `digital_files`.
           digital_product_delivery: nil,
+          # Machine-readable code reported when delivery failed, when applicable.
           error_code: nil,
+          # Human-readable message reported when delivery failed, when applicable.
           error_message: nil,
-          # Present only when the entitlement integration_type is `license_key`.
+          # License-key delivery payload, present when the entitlement integration is
+          # `license_key`.
           license_key: nil,
-          metadata: nil,
+          # Timestamp when `oauth_url` stops being valid, when applicable.
           oauth_expires_at: nil,
+          # Customer-facing OAuth URL for OAuth-style integrations. Populated during the
+          # customer-portal accept flow; `null` until the customer completes that step, and
+          # on grants for non-OAuth integrations.
           oauth_url: nil,
+          # Identifier of the payment that triggered this grant, when applicable.
           payment_id: nil,
+          # Reason recorded when the grant was revoked, when applicable.
           revocation_reason: nil,
+          # Timestamp when the grant transitioned to `revoked`, when applicable.
           revoked_at: nil,
+          # Identifier of the subscription that triggered this grant, when applicable.
           subscription_id: nil
         )
         end
@@ -162,7 +196,7 @@ module Dodopayments
               created_at: Time,
               customer_id: String,
               entitlement_id: String,
-              external_id: String,
+              metadata: T::Hash[Symbol, String],
               status:
                 Dodopayments::Entitlements::EntitlementGrant::Status::TaggedSymbol,
               updated_at: Time,
@@ -173,7 +207,6 @@ module Dodopayments
               error_message: T.nilable(String),
               license_key:
                 T.nilable(Dodopayments::Entitlements::LicenseKeyGrant),
-              metadata: T.anything,
               oauth_expires_at: T.nilable(Time),
               oauth_url: T.nilable(String),
               payment_id: T.nilable(String),
@@ -186,6 +219,7 @@ module Dodopayments
         def to_hash
         end
 
+        # Lifecycle status of the grant.
         module Status
           extend Dodopayments::Internal::Type::Enum
 

data/rbi/dodopayments/models/entitlements/file_upload_response.rbi

@@ -12,15 +12,15 @@ module Dodopayments
             )
           end
 
-        # EE-issued digital file id; appended to
-        # `entitlements.integration_config.digital_file_ids`.
+        # Identifier of the attached file. Pass it to
+        # `DELETE /entitlements/{id}/files/{file_id}` to detach the file later.
         sig { returns(String) }
         attr_accessor :file_id
 
         sig { params(file_id: String).returns(T.attached_class) }
         def self.new(
-          # EE-issued digital file id; appended to
-          # `entitlements.integration_config.digital_file_ids`.
+          # Identifier of the attached file. Pass it to
+          # `DELETE /entitlements/{id}/files/{file_id}` to detach the file later.
           file_id:
         )
         end

data/rbi/dodopayments/models/entitlements/license_key_grant.rbi

@@ -12,22 +12,24 @@ module Dodopayments
             )
           end
 
+        # Number of activations consumed so far.
         sig { returns(Integer) }
         attr_accessor :activations_used
 
+        # Issued license key.
         sig { returns(String) }
         attr_accessor :key
 
+        # Maximum activations allowed by the entitlement, when set.
         sig { returns(T.nilable(Integer)) }
         attr_accessor :activations_limit
 
+        # When the license key expires, when applicable.
         sig { returns(T.nilable(Time)) }
         attr_accessor :expires_at
 
-        # Nested representation of license-key grant fields. Present only when the grant's
-        # entitlement has `integration_type = 'license_key'` and a row exists in
-        # `license_keys`. The grant's top-level `status` is the source of truth for the
-        # grant's lifecycle — no per-license-key status is exposed here.
+        # License-key delivery payload, present on grants for `license_key` entitlements.
+        # The grant's top-level `status` is the source of truth for the grant's lifecycle.
         sig do
           params(
             activations_used: Integer,
@@ -37,9 +39,13 @@ module Dodopayments
           ).returns(T.attached_class)
         end
         def self.new(
+          # Number of activations consumed so far.
           activations_used:,
+          # Issued license key.
           key:,
+          # Maximum activations allowed by the entitlement, when set.
           activations_limit: nil,
+          # When the license key expires, when applicable.
           expires_at: nil
         )
         end

data/rbi/dodopayments/models/integration_config.rbi

@@ -2,8 +2,8 @@
 
 module Dodopayments
   module Models
-    # Platform-specific configuration for an entitlement. Each variant uses unique
-    # field names so `#[serde(untagged)]` can disambiguate correctly.
+    # Integration-specific configuration supplied when creating or updating an
+    # entitlement. The shape required matches the entitlement's `integration_type`.
     module IntegrationConfig
       extend Dodopayments::Internal::Type::Union
 
@@ -30,28 +30,94 @@ module Dodopayments
             )
           end
 
-        # One of: pull, push, admin, maintain, triage
-        sig { returns(String) }
+        # Permission to grant on the repository.
+        sig do
+          returns(
+            Dodopayments::IntegrationConfig::GitHubConfig::Permission::OrSymbol
+          )
+        end
         attr_accessor :permission
 
+        # Repository or organisation slug to grant access to.
         sig { returns(String) }
         attr_accessor :target_id
 
         sig do
-          params(permission: String, target_id: String).returns(
-            T.attached_class
-          )
+          params(
+            permission:
+              Dodopayments::IntegrationConfig::GitHubConfig::Permission::OrSymbol,
+            target_id: String
+          ).returns(T.attached_class)
         end
         def self.new(
-          # One of: pull, push, admin, maintain, triage
+          # Permission to grant on the repository.
           permission:,
+          # Repository or organisation slug to grant access to.
           target_id:
         )
         end
 
-        sig { override.returns({ permission: String, target_id: String }) }
+        sig do
+          override.returns(
+            {
+              permission:
+                Dodopayments::IntegrationConfig::GitHubConfig::Permission::OrSymbol,
+              target_id: String
+            }
+          )
+        end
         def to_hash
         end
+
+        # Permission to grant on the repository.
+        module Permission
+          extend Dodopayments::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(
+                Symbol,
+                Dodopayments::IntegrationConfig::GitHubConfig::Permission
+              )
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          PULL =
+            T.let(
+              :pull,
+              Dodopayments::IntegrationConfig::GitHubConfig::Permission::TaggedSymbol
+            )
+          PUSH =
+            T.let(
+              :push,
+              Dodopayments::IntegrationConfig::GitHubConfig::Permission::TaggedSymbol
+            )
+          ADMIN =
+            T.let(
+              :admin,
+              Dodopayments::IntegrationConfig::GitHubConfig::Permission::TaggedSymbol
+            )
+          MAINTAIN =
+            T.let(
+              :maintain,
+              Dodopayments::IntegrationConfig::GitHubConfig::Permission::TaggedSymbol
+            )
+          TRIAGE =
+            T.let(
+              :triage,
+              Dodopayments::IntegrationConfig::GitHubConfig::Permission::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Dodopayments::IntegrationConfig::GitHubConfig::Permission::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
       end
 
       class DiscordConfig < Dodopayments::Internal::Type::BaseModel
@@ -63,9 +129,11 @@ module Dodopayments
             )
           end
 
+        # Discord guild (server) ID.
         sig { returns(String) }
         attr_accessor :guild_id
 
+        # Optional Discord role to assign within the guild.
         sig { returns(T.nilable(String)) }
         attr_accessor :role_id
 
@@ -74,7 +142,12 @@ module Dodopayments
             T.attached_class
           )
         end
-        def self.new(guild_id:, role_id: nil)
+        def self.new(
+          # Discord guild (server) ID.
+          guild_id:,
+          # Optional Discord role to assign within the guild.
+          role_id: nil
+        )
         end
 
         sig do
@@ -93,11 +166,15 @@ module Dodopayments
             )
           end
 
+        # Telegram chat ID. For groups this is typically a negative integer.
         sig { returns(String) }
         attr_accessor :chat_id
 
         sig { params(chat_id: String).returns(T.attached_class) }
-        def self.new(chat_id:)
+        def self.new(
+          # Telegram chat ID. For groups this is typically a negative integer.
+          chat_id:
+        )
         end
 
         sig { override.returns({ chat_id: String }) }
@@ -114,11 +191,15 @@ module Dodopayments
             )
           end
 
+        # Figma file identifier to grant access to.
         sig { returns(String) }
         attr_accessor :figma_file_id
 
         sig { params(figma_file_id: String).returns(T.attached_class) }
-        def self.new(figma_file_id:)
+        def self.new(
+          # Figma file identifier to grant access to.
+          figma_file_id:
+        )
         end
 
         sig { override.returns({ figma_file_id: String }) }
@@ -135,11 +216,15 @@ module Dodopayments
             )
           end
 
+        # Framer template identifier to grant access to.
         sig { returns(String) }
         attr_accessor :framer_template_id
 
         sig { params(framer_template_id: String).returns(T.attached_class) }
-        def self.new(framer_template_id:)
+        def self.new(
+          # Framer template identifier to grant access to.
+          framer_template_id:
+        )
         end
 
         sig { override.returns({ framer_template_id: String }) }
@@ -156,11 +241,15 @@ module Dodopayments
             )
           end
 
+        # Notion template identifier to grant access to.
         sig { returns(String) }
         attr_accessor :notion_template_id
 
         sig { params(notion_template_id: String).returns(T.attached_class) }
-        def self.new(notion_template_id:)
+        def self.new(
+          # Notion template identifier to grant access to.
+          notion_template_id:
+        )
         end
 
         sig { override.returns({ notion_template_id: String }) }
@@ -177,23 +266,29 @@ module Dodopayments
             )
           end
 
+        # Files attached to this entitlement. Add files via
+        # `POST /entitlements/{id}/files` and remove them via
+        # `DELETE /entitlements/{id}/files/{file_id}`.
         sig { returns(T::Array[String]) }
         attr_accessor :digital_file_ids
 
+        # Optional external URL shown to the customer alongside the files.
         sig { returns(T.nilable(String)) }
         attr_accessor :external_url
 
+        # Optional human-readable delivery instructions shown to the customer alongside
+        # the files.
         sig { returns(T.nilable(String)) }
         attr_accessor :instructions
 
-        # Three-way patchable field (mirrors the credit_entitlements pattern):
+        # Three-way patchable list of legacy file identifiers:
         #
-        # - omitted → preserve persisted (`None`)
-        # - `null` → clear (`Some(None)`)
-        # - `[...]` → replace (`Some(Some(...))`)
+        # - omitted → preserve the current value
+        # - `null` → clear
+        # - `[...]` → replace
         #
-        # On Create / storage we collapse "clear" and empty-array to `None` so the
-        # persisted JSONB never carries a `null` legacy_file_ids key.
+        # On create, an omitted field, an explicit `null`, or an empty array all result in
+        # no legacy files attached.
         sig { returns(T.nilable(T::Array[String])) }
         attr_accessor :legacy_file_ids
 
@@ -206,17 +301,23 @@ module Dodopayments
           ).returns(T.attached_class)
         end
         def self.new(
+          # Files attached to this entitlement. Add files via
+          # `POST /entitlements/{id}/files` and remove them via
+          # `DELETE /entitlements/{id}/files/{file_id}`.
           digital_file_ids:,
+          # Optional external URL shown to the customer alongside the files.
           external_url: nil,
+          # Optional human-readable delivery instructions shown to the customer alongside
+          # the files.
           instructions: nil,
-          # Three-way patchable field (mirrors the credit_entitlements pattern):
+          # Three-way patchable list of legacy file identifiers:
           #
-          # - omitted → preserve persisted (`None`)
-          # - `null` → clear (`Some(None)`)
-          # - `[...]` → replace (`Some(Some(...))`)
+          # - omitted → preserve the current value
+          # - `null` → clear
+          # - `[...]` → replace
           #
-          # On Create / storage we collapse "clear" and empty-array to `None` so the
-          # persisted JSONB never carries a `null` legacy_file_ids key.
+          # On create, an omitted field, an explicit `null`, or an empty array all result in
+          # no legacy files attached.
           legacy_file_ids: nil
         )
         end
@@ -244,15 +345,22 @@ module Dodopayments
             )
           end
 
+        # Optional message displayed when a customer activates the license key (≤ 2500
+        # characters).
         sig { returns(T.nilable(String)) }
         attr_accessor :activation_message
 
+        # Maximum activations allowed per issued license key. Omit for unlimited.
         sig { returns(T.nilable(Integer)) }
         attr_accessor :activations_limit
 
+        # Validity duration of issued license keys. Provide both `duration_count` and
+        # `duration_interval` together for a fixed duration; omit both for non-expiring
+        # keys.
         sig { returns(T.nilable(Integer)) }
         attr_accessor :duration_count
 
+        # Unit of `duration_count`.
         sig { returns(T.nilable(Dodopayments::TimeInterval::OrSymbol)) }
         attr_accessor :duration_interval
 
@@ -265,9 +373,16 @@ module Dodopayments
           ).returns(T.attached_class)
         end
         def self.new(
+          # Optional message displayed when a customer activates the license key (≤ 2500
+          # characters).
           activation_message: nil,
+          # Maximum activations allowed per issued license key. Omit for unlimited.
           activations_limit: nil,
+          # Validity duration of issued license keys. Provide both `duration_count` and
+          # `duration_interval` together for a fixed duration; omit both for non-expiring
+          # keys.
           duration_count: nil,
+          # Unit of `duration_count`.
           duration_interval: nil
         )
         end