dodopayments 2.9.0 → 2.9.1

data/lib/dodopayments/resources/entitlements/files.rb

@@ -4,14 +4,11 @@ module Dodopayments
   module Resources
     class Entitlements
       class Files
-        # Companion to `post_entitlement_file`. Deletes the file from the Entitlements
-        # Engine (force=true) and atomically removes the `file_id` from the entitlement's
-        # `integration_config.digital_file_ids` JSONB array. EE delete happens first; if
-        # it fails we surface the error and leave local state untouched.
+        # Detach a previously-attached file from a `digital_files` entitlement.
         #
         # @overload delete(file_id, id:, request_options: {})
         #
-        # @param file_id [String] Digital file Id from EE
+        # @param file_id [String] Identifier of the attached file
         #
         # @param id [String] Entitlement Id
         #
@@ -34,11 +31,7 @@ module Dodopayments
           )
         end
 
-        # Streams a multipart/form-data body to the Entitlements Engine
-        # (`POST /api/digital-files/dodo/files/upload`) and appends the returned `file_id`
-        # to the entitlement's `integration_config.digital_file_ids` using a JSONB array
-        # append. Compensates EE-side on local DB write failure (best-effort delete of the
-        # just-uploaded file).
+        # Attach a file to a `digital_files` entitlement. Per-file size cap: 500 MiB.
         #
         # @overload upload(id, request_options: {})
         #

data/lib/dodopayments/resources/entitlements/grants.rb

@@ -36,10 +36,8 @@ module Dodopayments
           )
         end
 
-        # Revokes a single entitlement grant for the caller's business. For LicenseKey
-        # integrations, also disables the backing license key. Idempotent: re-revoking an
-        # already-revoked grant returns 200 with current state. The revocation reason is
-        # always set to "manual" for API-initiated revocations.
+        # Revoke a single grant. Idempotent: re-revoking an already-revoked grant returns
+        # the grant in its current state.
         #
         # @overload revoke(grant_id, id:, request_options: {})
         #

data/lib/dodopayments/resources/entitlements.rb

@@ -21,7 +21,7 @@ module Dodopayments
       #
       # @param description [String, nil] Optional description
       #
-      # @param metadata [Hash{Symbol=>String}, nil] Optional user-facing metadata
+      # @param metadata [Hash{Symbol=>String}] Additional metadata for the entitlement
       #
       # @param request_options [Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -70,7 +70,7 @@ module Dodopayments
       #
       # @param description [String, nil]
       #
-      # @param integration_config [Dodopayments::Models::IntegrationConfig::GitHubConfig, Dodopayments::Models::IntegrationConfig::DiscordConfig, Dodopayments::Models::IntegrationConfig::TelegramConfig, Dodopayments::Models::IntegrationConfig::FigmaConfig, Dodopayments::Models::IntegrationConfig::FramerConfig, Dodopayments::Models::IntegrationConfig::NotionConfig, Dodopayments::Models::IntegrationConfig::DigitalFilesConfig, Dodopayments::Models::IntegrationConfig::LicenseKeyConfig, nil] Platform-specific configuration for an entitlement.
+      # @param integration_config [Dodopayments::Models::IntegrationConfig::GitHubConfig, Dodopayments::Models::IntegrationConfig::DiscordConfig, Dodopayments::Models::IntegrationConfig::TelegramConfig, Dodopayments::Models::IntegrationConfig::FigmaConfig, Dodopayments::Models::IntegrationConfig::FramerConfig, Dodopayments::Models::IntegrationConfig::NotionConfig, Dodopayments::Models::IntegrationConfig::DigitalFilesConfig, Dodopayments::Models::IntegrationConfig::LicenseKeyConfig, nil] Integration-specific configuration supplied when creating or updating
       #
       # @param metadata [Hash{Symbol=>String}, nil]
       #

data/lib/dodopayments/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dodopayments
-  VERSION = "2.9.0"
+  VERSION = "2.9.1"
 end

data/rbi/dodopayments/models/digital_product_delivery.rbi

@@ -11,19 +11,21 @@ module Dodopayments
           )
         end
 
+      # One entry per attached file.
       sig { returns(T::Array[Dodopayments::DigitalProductDeliveryFile]) }
       attr_accessor :files
 
+      # Optional external URL, passed through from the entitlement configuration.
       sig { returns(T.nilable(String)) }
       attr_accessor :external_url
 
+      # Optional human-readable delivery instructions, passed through from the
+      # entitlement configuration.
       sig { returns(T.nilable(String)) }
       attr_accessor :instructions
 
-      # Digital-product-delivery payload for a grant. Populated for grants whose
-      # entitlement has `integration_type = 'digital_files'`. `files` carries presigned
-      # download URLs; the source (EE service or legacy in-process S3 presigning) is
-      # opaque to the caller.
+      # Digital-product-delivery payload, present on grants for `digital_files`
+      # entitlements. Each file carries a short-lived presigned download URL.
       sig do
         params(
           files: T::Array[Dodopayments::DigitalProductDeliveryFile::OrHash],
@@ -31,7 +33,15 @@ module Dodopayments
           instructions: T.nilable(String)
         ).returns(T.attached_class)
       end
-      def self.new(files:, external_url: nil, instructions: nil)
+      def self.new(
+        # One entry per attached file.
+        files:,
+        # Optional external URL, passed through from the entitlement configuration.
+        external_url: nil,
+        # Optional human-readable delivery instructions, passed through from the
+        # entitlement configuration.
+        instructions: nil
+      )
       end
 
       sig do

data/rbi/dodopayments/models/digital_product_delivery_file.rbi

@@ -11,6 +11,7 @@ module Dodopayments
           )
         end
 
+      # Short-lived presigned URL for downloading the file.
       sig { returns(String) }
       attr_accessor :download_url
 
@@ -18,18 +19,23 @@ module Dodopayments
       sig { returns(Integer) }
       attr_accessor :expires_in
 
+      # Identifier of the attached file.
       sig { returns(String) }
       attr_accessor :file_id
 
+      # Original filename of the attached file.
       sig { returns(String) }
       attr_accessor :filename
 
+      # Optional content-type declared at upload.
       sig { returns(T.nilable(String)) }
       attr_accessor :content_type
 
+      # Optional size of the file in bytes.
       sig { returns(T.nilable(Integer)) }
       attr_accessor :file_size
 
+      # One file in a digital-product delivery payload.
       sig do
         params(
           download_url: String,
@@ -41,12 +47,17 @@ module Dodopayments
         ).returns(T.attached_class)
       end
       def self.new(
+        # Short-lived presigned URL for downloading the file.
         download_url:,
         # Seconds until `download_url` expires.
         expires_in:,
+        # Identifier of the attached file.
         file_id:,
+        # Original filename of the attached file.
         filename:,
+        # Optional content-type declared at upload.
         content_type: nil,
+        # Optional size of the file in bytes.
         file_size: nil
       )
       end

data/rbi/dodopayments/models/entitlement.rbi

@@ -8,43 +8,50 @@ module Dodopayments
           T.any(Dodopayments::Entitlement, Dodopayments::Internal::AnyHash)
         end
 
+      # Unique identifier of the entitlement.
       sig { returns(String) }
       attr_accessor :id
 
+      # Identifier of the business that owns this entitlement.
       sig { returns(String) }
       attr_accessor :business_id
 
+      # Timestamp when the entitlement was created.
       sig { returns(Time) }
       attr_accessor :created_at
 
-      # Public-facing variant of [`IntegrationConfig`]. Mirrors every variant shape on
-      # the wire EXCEPT `DigitalFiles`, which is replaced with a hydrated
-      # `digital_files` object (resolved download URLs etc.). The persisted JSONB stays
-      # ID-only via [`IntegrationConfig`]; this enum is response-only.
+      # Integration-specific configuration. For `digital_files` entitlements this
+      # includes presigned download URLs for each attached file.
       sig { returns(Dodopayments::IntegrationConfigResponse::Variants) }
       attr_accessor :integration_config
 
+      # Platform integration this entitlement uses.
       sig { returns(Dodopayments::EntitlementIntegrationType::TaggedSymbol) }
       attr_accessor :integration_type
 
+      # Always `true` for entitlements returned by the public API; soft-deleted
+      # entitlements are not returned.
       sig { returns(T::Boolean) }
       attr_accessor :is_active
 
+      # Arbitrary key-value metadata supplied at creation or via PATCH.
+      sig { returns(T::Hash[Symbol, String]) }
+      attr_accessor :metadata
+
+      # Display name supplied at creation.
       sig { returns(String) }
       attr_accessor :name
 
+      # Timestamp when the entitlement was last modified.
       sig { returns(Time) }
       attr_accessor :updated_at
 
+      # Optional description supplied at creation.
       sig { returns(T.nilable(String)) }
       attr_accessor :description
 
-      sig { returns(T.nilable(T.anything)) }
-      attr_reader :metadata
-
-      sig { params(metadata: T.anything).void }
-      attr_writer :metadata
-
+      # Detailed view of a single entitlement: identity, integration type,
+      # integration-specific configuration, and metadata.
       sig do
         params(
           id: String,
@@ -63,27 +70,35 @@ module Dodopayments
             ),
           integration_type: Dodopayments::EntitlementIntegrationType::OrSymbol,
           is_active: T::Boolean,
+          metadata: T::Hash[Symbol, String],
           name: String,
           updated_at: Time,
-          description: T.nilable(String),
-          metadata: T.anything
+          description: T.nilable(String)
         ).returns(T.attached_class)
       end
       def self.new(
+        # Unique identifier of the entitlement.
         id:,
+        # Identifier of the business that owns this entitlement.
         business_id:,
+        # Timestamp when the entitlement was created.
         created_at:,
-        # Public-facing variant of [`IntegrationConfig`]. Mirrors every variant shape on
-        # the wire EXCEPT `DigitalFiles`, which is replaced with a hydrated
-        # `digital_files` object (resolved download URLs etc.). The persisted JSONB stays
-        # ID-only via [`IntegrationConfig`]; this enum is response-only.
+        # Integration-specific configuration. For `digital_files` entitlements this
+        # includes presigned download URLs for each attached file.
         integration_config:,
+        # Platform integration this entitlement uses.
         integration_type:,
+        # Always `true` for entitlements returned by the public API; soft-deleted
+        # entitlements are not returned.
         is_active:,
+        # Arbitrary key-value metadata supplied at creation or via PATCH.
+        metadata:,
+        # Display name supplied at creation.
         name:,
+        # Timestamp when the entitlement was last modified.
         updated_at:,
-        description: nil,
-        metadata: nil
+        # Optional description supplied at creation.
+        description: nil
       )
       end
 
@@ -98,10 +113,10 @@ module Dodopayments
             integration_type:
               Dodopayments::EntitlementIntegrationType::TaggedSymbol,
             is_active: T::Boolean,
+            metadata: T::Hash[Symbol, String],
             name: String,
             updated_at: Time,
-            description: T.nilable(String),
-            metadata: T.anything
+            description: T.nilable(String)
           }
         )
       end

data/rbi/dodopayments/models/entitlement_create_params.rbi

@@ -43,9 +43,12 @@ module Dodopayments
       sig { returns(T.nilable(String)) }
       attr_accessor :description
 
-      # Optional user-facing metadata
+      # Additional metadata for the entitlement
       sig { returns(T.nilable(T::Hash[Symbol, String])) }
-      attr_accessor :metadata
+      attr_reader :metadata
+
+      sig { params(metadata: T::Hash[Symbol, String]).void }
+      attr_writer :metadata
 
       sig do
         params(
@@ -63,7 +66,7 @@ module Dodopayments
           integration_type: Dodopayments::EntitlementIntegrationType::OrSymbol,
           name: String,
           description: T.nilable(String),
-          metadata: T.nilable(T::Hash[Symbol, String]),
+          metadata: T::Hash[Symbol, String],
           request_options: Dodopayments::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
@@ -76,7 +79,7 @@ module Dodopayments
         name:,
         # Optional description
         description: nil,
-        # Optional user-facing metadata
+        # Additional metadata for the entitlement
         metadata: nil,
         request_options: {}
       )
@@ -100,7 +103,7 @@ module Dodopayments
               Dodopayments::EntitlementIntegrationType::OrSymbol,
             name: String,
             description: T.nilable(String),
-            metadata: T.nilable(T::Hash[Symbol, String]),
+            metadata: T::Hash[Symbol, String],
             request_options: Dodopayments::RequestOptions
           }
         )

data/rbi/dodopayments/models/entitlement_grant_created_webhook_event.rbi

@@ -15,6 +15,8 @@ module Dodopayments
       sig { returns(String) }
       attr_accessor :business_id
 
+      # Detailed view of a single entitlement grant: who it's for, its lifecycle state,
+      # and any integration-specific delivery payload.
       sig { returns(Dodopayments::Entitlements::EntitlementGrant) }
       attr_reader :data
 
@@ -47,6 +49,8 @@ module Dodopayments
       def self.new(
         # The business identifier
         business_id:,
+        # Detailed view of a single entitlement grant: who it's for, its lifecycle state,
+        # and any integration-specific delivery payload.
         data:,
         # The timestamp of when the event occurred
         timestamp:,

data/rbi/dodopayments/models/entitlement_grant_delivered_webhook_event.rbi

@@ -15,6 +15,8 @@ module Dodopayments
       sig { returns(String) }
       attr_accessor :business_id
 
+      # Detailed view of a single entitlement grant: who it's for, its lifecycle state,
+      # and any integration-specific delivery payload.
       sig { returns(Dodopayments::Entitlements::EntitlementGrant) }
       attr_reader :data
 
@@ -47,6 +49,8 @@ module Dodopayments
       def self.new(
         # The business identifier
         business_id:,
+        # Detailed view of a single entitlement grant: who it's for, its lifecycle state,
+        # and any integration-specific delivery payload.
         data:,
         # The timestamp of when the event occurred
         timestamp:,

data/rbi/dodopayments/models/entitlement_grant_failed_webhook_event.rbi

@@ -15,6 +15,8 @@ module Dodopayments
       sig { returns(String) }
       attr_accessor :business_id
 
+      # Detailed view of a single entitlement grant: who it's for, its lifecycle state,
+      # and any integration-specific delivery payload.
       sig { returns(Dodopayments::Entitlements::EntitlementGrant) }
       attr_reader :data
 
@@ -46,6 +48,8 @@ module Dodopayments
       def self.new(
         # The business identifier
         business_id:,
+        # Detailed view of a single entitlement grant: who it's for, its lifecycle state,
+        # and any integration-specific delivery payload.
         data:,
         # The timestamp of when the event occurred
         timestamp:,

data/rbi/dodopayments/models/entitlement_grant_revoked_webhook_event.rbi

@@ -15,6 +15,8 @@ module Dodopayments
       sig { returns(String) }
       attr_accessor :business_id
 
+      # Detailed view of a single entitlement grant: who it's for, its lifecycle state,
+      # and any integration-specific delivery payload.
       sig { returns(Dodopayments::Entitlements::EntitlementGrant) }
       attr_reader :data
 
@@ -47,6 +49,8 @@ module Dodopayments
       def self.new(
         # The business identifier
         business_id:,
+        # Detailed view of a single entitlement grant: who it's for, its lifecycle state,
+        # and any integration-specific delivery payload.
         data:,
         # The timestamp of when the event occurred
         timestamp:,

data/rbi/dodopayments/models/entitlement_update_params.rbi

@@ -20,8 +20,8 @@ module Dodopayments
       sig { returns(T.nilable(String)) }
       attr_accessor :description
 
-      # 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`.
       sig do
         returns(
           T.nilable(
@@ -71,8 +71,8 @@ module Dodopayments
       def self.new(
         id:,
         description: nil,
-        # 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`.
         integration_config: nil,
         metadata: nil,
         name: nil,

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