dodopayments 2.9.0 → 2.10.0

data/lib/dodopayments/models/entitlement_update_params.rb

@@ -18,8 +18,8 @@ module Dodopayments
       optional :description, String, nil?: true
 
       # @!attribute integration_config
-      #   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`.
       #
       #   @return [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]
       optional :integration_config, union: -> { Dodopayments::IntegrationConfig }, nil?: true
@@ -42,7 +42,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/models/entitlements/entitlement_grant.rb

@@ -6,152 +6,170 @@ module Dodopayments
       # @see Dodopayments::Resources::Entitlements::Grants#list
       class EntitlementGrant < Dodopayments::Internal::Type::BaseModel
         # @!attribute id
+        #   Unique identifier of the grant.
         #
         #   @return [String]
         required :id, String
 
         # @!attribute business_id
+        #   Identifier of the business that owns the grant.
         #
         #   @return [String]
         required :business_id, String
 
         # @!attribute created_at
+        #   Timestamp when the grant was created.
         #
         #   @return [Time]
         required :created_at, Time
 
         # @!attribute customer_id
+        #   Identifier of the customer the grant was issued to.
         #
         #   @return [String]
         required :customer_id, String
 
         # @!attribute entitlement_id
+        #   Identifier of the entitlement this grant was issued from.
         #
         #   @return [String]
         required :entitlement_id, String
 
-        # @!attribute external_id
+        # @!attribute metadata
+        #   Arbitrary key-value metadata recorded on the grant.
         #
-        #   @return [String]
-        required :external_id, String
+        #   @return [Hash{Symbol=>String}]
+        required :metadata, Dodopayments::Internal::Type::HashOf[String]
 
         # @!attribute status
+        #   Lifecycle status of the grant.
         #
         #   @return [Symbol, Dodopayments::Models::Entitlements::EntitlementGrant::Status]
         required :status, enum: -> { Dodopayments::Entitlements::EntitlementGrant::Status }
 
         # @!attribute updated_at
+        #   Timestamp when the grant was last modified.
         #
         #   @return [Time]
         required :updated_at, Time
 
         # @!attribute delivered_at
+        #   Timestamp when the grant transitioned to `delivered`, when applicable.
         #
         #   @return [Time, nil]
         optional :delivered_at, Time, nil?: true
 
         # @!attribute digital_product_delivery
-        #   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`.
         #
         #   @return [Dodopayments::Models::DigitalProductDelivery, nil]
         optional :digital_product_delivery, -> { Dodopayments::DigitalProductDelivery }, nil?: true
 
         # @!attribute error_code
+        #   Machine-readable code reported when delivery failed, when applicable.
         #
         #   @return [String, nil]
         optional :error_code, String, nil?: true
 
         # @!attribute error_message
+        #   Human-readable message reported when delivery failed, when applicable.
         #
         #   @return [String, nil]
         optional :error_message, String, nil?: true
 
         # @!attribute license_key
-        #   Present only when the entitlement integration_type is `license_key`.
+        #   License-key delivery payload, present when the entitlement integration is
+        #   `license_key`.
         #
         #   @return [Dodopayments::Models::Entitlements::LicenseKeyGrant, nil]
         optional :license_key, -> { Dodopayments::Entitlements::LicenseKeyGrant }, nil?: true
 
-        # @!attribute metadata
-        #
-        #   @return [Object, nil]
-        optional :metadata, Dodopayments::Internal::Type::Unknown
-
         # @!attribute oauth_expires_at
+        #   Timestamp when `oauth_url` stops being valid, when applicable.
         #
         #   @return [Time, nil]
         optional :oauth_expires_at, Time, nil?: true
 
         # @!attribute oauth_url
+        #   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.
         #
         #   @return [String, nil]
         optional :oauth_url, String, nil?: true
 
         # @!attribute payment_id
+        #   Identifier of the payment that triggered this grant, when applicable.
         #
         #   @return [String, nil]
         optional :payment_id, String, nil?: true
 
         # @!attribute revocation_reason
+        #   Reason recorded when the grant was revoked, when applicable.
         #
         #   @return [String, nil]
         optional :revocation_reason, String, nil?: true
 
         # @!attribute revoked_at
+        #   Timestamp when the grant transitioned to `revoked`, when applicable.
         #
         #   @return [Time, nil]
         optional :revoked_at, Time, nil?: true
 
         # @!attribute subscription_id
+        #   Identifier of the subscription that triggered this grant, when applicable.
         #
         #   @return [String, nil]
         optional :subscription_id, String, nil?: true
 
-        # @!method initialize(id:, business_id:, created_at:, customer_id:, entitlement_id:, external_id:, status:, updated_at:, delivered_at: nil, digital_product_delivery: nil, error_code: nil, error_message: nil, license_key: nil, metadata: nil, oauth_expires_at: nil, oauth_url: nil, payment_id: nil, revocation_reason: nil, revoked_at: nil, subscription_id: nil)
+        # @!method initialize(id:, business_id:, created_at:, customer_id:, entitlement_id:, metadata:, status:, updated_at:, delivered_at: nil, digital_product_delivery: nil, error_code: nil, error_message: nil, license_key: nil, oauth_expires_at: nil, oauth_url: nil, payment_id: nil, revocation_reason: nil, revoked_at: nil, subscription_id: nil)
         #   Some parameter documentations has been truncated, see
         #   {Dodopayments::Models::Entitlements::EntitlementGrant} for more details.
         #
-        #   @param id [String]
+        #   Detailed view of a single entitlement grant: who it's for, its lifecycle state,
+        #   and any integration-specific delivery payload.
         #
-        #   @param business_id [String]
+        #   @param id [String] Unique identifier of the grant.
         #
-        #   @param created_at [Time]
+        #   @param business_id [String] Identifier of the business that owns the grant.
         #
-        #   @param customer_id [String]
+        #   @param created_at [Time] Timestamp when the grant was created.
         #
-        #   @param entitlement_id [String]
+        #   @param customer_id [String] Identifier of the customer the grant was issued to.
         #
-        #   @param external_id [String]
+        #   @param entitlement_id [String] Identifier of the entitlement this grant was issued from.
         #
-        #   @param status [Symbol, Dodopayments::Models::Entitlements::EntitlementGrant::Status]
+        #   @param metadata [Hash{Symbol=>String}] Arbitrary key-value metadata recorded on the grant.
         #
-        #   @param updated_at [Time]
+        #   @param status [Symbol, Dodopayments::Models::Entitlements::EntitlementGrant::Status] Lifecycle status of the grant.
         #
-        #   @param delivered_at [Time, nil]
+        #   @param updated_at [Time] Timestamp when the grant was last modified.
         #
-        #   @param digital_product_delivery [Dodopayments::Models::DigitalProductDelivery, nil] Present only when the entitlement integration_type is `digital_files`.
+        #   @param delivered_at [Time, nil] Timestamp when the grant transitioned to `delivered`, when applicable.
         #
-        #   @param error_code [String, nil]
+        #   @param digital_product_delivery [Dodopayments::Models::DigitalProductDelivery, nil] Digital-product-delivery payload, present when the entitlement
         #
-        #   @param error_message [String, nil]
+        #   @param error_code [String, nil] Machine-readable code reported when delivery failed, when applicable.
         #
-        #   @param license_key [Dodopayments::Models::Entitlements::LicenseKeyGrant, nil] Present only when the entitlement integration_type is `license_key`.
+        #   @param error_message [String, nil] Human-readable message reported when delivery failed, when applicable.
         #
-        #   @param metadata [Object]
+        #   @param license_key [Dodopayments::Models::Entitlements::LicenseKeyGrant, nil] License-key delivery payload, present when the entitlement integration
         #
-        #   @param oauth_expires_at [Time, nil]
+        #   @param oauth_expires_at [Time, nil] Timestamp when `oauth_url` stops being valid, when applicable.
         #
-        #   @param oauth_url [String, nil]
+        #   @param oauth_url [String, nil] Customer-facing OAuth URL for OAuth-style integrations. Populated
         #
-        #   @param payment_id [String, nil]
+        #   @param payment_id [String, nil] Identifier of the payment that triggered this grant, when applicable.
         #
-        #   @param revocation_reason [String, nil]
+        #   @param revocation_reason [String, nil] Reason recorded when the grant was revoked, when applicable.
         #
-        #   @param revoked_at [Time, nil]
+        #   @param revoked_at [Time, nil] Timestamp when the grant transitioned to `revoked`, when applicable.
         #
-        #   @param subscription_id [String, nil]
+        #   @param subscription_id [String, nil] Identifier of the subscription that triggered this grant, when applicable.
 
+        # Lifecycle status of the grant.
+        #
         # @see Dodopayments::Models::Entitlements::EntitlementGrant#status
         module Status
           extend Dodopayments::Internal::Type::Enum

data/lib/dodopayments/models/entitlements/file_upload_response.rb

@@ -6,8 +6,8 @@ module Dodopayments
       # @see Dodopayments::Resources::Entitlements::Files#upload
       class FileUploadResponse < Dodopayments::Internal::Type::BaseModel
         # @!attribute file_id
-        #   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.
         #
         #   @return [String]
         required :file_id, String
@@ -16,7 +16,7 @@ module Dodopayments
         #   Some parameter documentations has been truncated, see
         #   {Dodopayments::Models::Entitlements::FileUploadResponse} for more details.
         #
-        #   @param file_id [String] EE-issued digital file id; appended to
+        #   @param file_id [String] Identifier of the attached file. Pass it to
       end
     end
   end

data/lib/dodopayments/models/entitlements/license_key_grant.rb

@@ -5,35 +5,40 @@ module Dodopayments
     module Entitlements
       class LicenseKeyGrant < Dodopayments::Internal::Type::BaseModel
         # @!attribute activations_used
+        #   Number of activations consumed so far.
         #
         #   @return [Integer]
         required :activations_used, Integer
 
         # @!attribute key
+        #   Issued license key.
         #
         #   @return [String]
         required :key, String
 
         # @!attribute activations_limit
+        #   Maximum activations allowed by the entitlement, when set.
         #
         #   @return [Integer, nil]
         optional :activations_limit, Integer, nil?: true
 
         # @!attribute expires_at
+        #   When the license key expires, when applicable.
         #
         #   @return [Time, nil]
         optional :expires_at, Time, nil?: true
 
         # @!method initialize(activations_used:, key:, activations_limit: nil, expires_at: nil)
-        #   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.
-        #
-        #   @param activations_used [Integer]
-        #   @param key [String]
-        #   @param activations_limit [Integer, nil]
-        #   @param expires_at [Time, nil]
+        #   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.
+        #
+        #   @param activations_used [Integer] Number of activations consumed so far.
+        #
+        #   @param key [String] Issued license key.
+        #
+        #   @param activations_limit [Integer, nil] Maximum activations allowed by the entitlement, when set.
+        #
+        #   @param expires_at [Time, nil] When the license key expires, when applicable.
       end
     end
   end

data/lib/dodopayments/models/integration_config.rb

@@ -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
 
@@ -25,103 +25,133 @@ module Dodopayments
 
       class GitHubConfig < Dodopayments::Internal::Type::BaseModel
         # @!attribute permission
-        #   One of: pull, push, admin, maintain, triage
+        #   Permission to grant on the repository.
         #
-        #   @return [String]
-        required :permission, String
+        #   @return [Symbol, Dodopayments::Models::IntegrationConfig::GitHubConfig::Permission]
+        required :permission, enum: -> { Dodopayments::IntegrationConfig::GitHubConfig::Permission }
 
         # @!attribute target_id
+        #   Repository or organisation slug to grant access to.
         #
         #   @return [String]
         required :target_id, String
 
         # @!method initialize(permission:, target_id:)
-        #   @param permission [String] One of: pull, push, admin, maintain, triage
+        #   @param permission [Symbol, Dodopayments::Models::IntegrationConfig::GitHubConfig::Permission] Permission to grant on the repository.
+        #
+        #   @param target_id [String] Repository or organisation slug to grant access to.
+
+        # Permission to grant on the repository.
         #
-        #   @param target_id [String]
+        # @see Dodopayments::Models::IntegrationConfig::GitHubConfig#permission
+        module Permission
+          extend Dodopayments::Internal::Type::Enum
+
+          PULL = :pull
+          PUSH = :push
+          ADMIN = :admin
+          MAINTAIN = :maintain
+          TRIAGE = :triage
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
       end
 
       class DiscordConfig < Dodopayments::Internal::Type::BaseModel
         # @!attribute guild_id
+        #   Discord guild (server) ID.
         #
         #   @return [String]
         required :guild_id, String
 
         # @!attribute role_id
+        #   Optional Discord role to assign within the guild.
         #
         #   @return [String, nil]
         optional :role_id, String, nil?: true
 
         # @!method initialize(guild_id:, role_id: nil)
-        #   @param guild_id [String]
-        #   @param role_id [String, nil]
+        #   @param guild_id [String] Discord guild (server) ID.
+        #
+        #   @param role_id [String, nil] Optional Discord role to assign within the guild.
       end
 
       class TelegramConfig < Dodopayments::Internal::Type::BaseModel
         # @!attribute chat_id
+        #   Telegram chat ID. For groups this is typically a negative integer.
         #
         #   @return [String]
         required :chat_id, String
 
         # @!method initialize(chat_id:)
-        #   @param chat_id [String]
+        #   @param chat_id [String] Telegram chat ID. For groups this is typically a negative integer.
       end
 
       class FigmaConfig < Dodopayments::Internal::Type::BaseModel
         # @!attribute figma_file_id
+        #   Figma file identifier to grant access to.
         #
         #   @return [String]
         required :figma_file_id, String
 
         # @!method initialize(figma_file_id:)
-        #   @param figma_file_id [String]
+        #   @param figma_file_id [String] Figma file identifier to grant access to.
       end
 
       class FramerConfig < Dodopayments::Internal::Type::BaseModel
         # @!attribute framer_template_id
+        #   Framer template identifier to grant access to.
         #
         #   @return [String]
         required :framer_template_id, String
 
         # @!method initialize(framer_template_id:)
-        #   @param framer_template_id [String]
+        #   @param framer_template_id [String] Framer template identifier to grant access to.
       end
 
       class NotionConfig < Dodopayments::Internal::Type::BaseModel
         # @!attribute notion_template_id
+        #   Notion template identifier to grant access to.
         #
         #   @return [String]
         required :notion_template_id, String
 
         # @!method initialize(notion_template_id:)
-        #   @param notion_template_id [String]
+        #   @param notion_template_id [String] Notion template identifier to grant access to.
       end
 
       class DigitalFilesConfig < Dodopayments::Internal::Type::BaseModel
         # @!attribute digital_file_ids
+        #   Files attached to this entitlement. Add files via
+        #   `POST /entitlements/{id}/files` and remove them via
+        #   `DELETE /entitlements/{id}/files/{file_id}`.
         #
         #   @return [Array<String>]
         required :digital_file_ids, Dodopayments::Internal::Type::ArrayOf[String]
 
         # @!attribute external_url
+        #   Optional external URL shown to the customer alongside the files.
         #
         #   @return [String, nil]
         optional :external_url, String, nil?: true
 
         # @!attribute instructions
+        #   Optional human-readable delivery instructions shown to the customer alongside
+        #   the files.
         #
         #   @return [String, nil]
         optional :instructions, String, nil?: true
 
         # @!attribute legacy_file_ids
-        #   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.
         #
         #   @return [Array<String>, nil]
         optional :legacy_file_ids, Dodopayments::Internal::Type::ArrayOf[String], nil?: true
@@ -130,41 +160,54 @@ module Dodopayments
         #   Some parameter documentations has been truncated, see
         #   {Dodopayments::Models::IntegrationConfig::DigitalFilesConfig} for more details.
         #
-        #   @param digital_file_ids [Array<String>]
+        #   @param digital_file_ids [Array<String>] Files attached to this entitlement. Add files via
         #
-        #   @param external_url [String, nil]
+        #   @param external_url [String, nil] Optional external URL shown to the customer alongside the files.
         #
-        #   @param instructions [String, nil]
+        #   @param instructions [String, nil] Optional human-readable delivery instructions shown to the customer
         #
-        #   @param legacy_file_ids [Array<String>, nil] Three-way patchable field (mirrors the credit_entitlements pattern):
+        #   @param legacy_file_ids [Array<String>, nil] Three-way patchable list of legacy file identifiers:
       end
 
       class LicenseKeyConfig < Dodopayments::Internal::Type::BaseModel
         # @!attribute activation_message
+        #   Optional message displayed when a customer activates the license key (≤ 2500
+        #   characters).
         #
         #   @return [String, nil]
         optional :activation_message, String, nil?: true
 
         # @!attribute activations_limit
+        #   Maximum activations allowed per issued license key. Omit for unlimited.
         #
         #   @return [Integer, nil]
         optional :activations_limit, Integer, nil?: true
 
         # @!attribute duration_count
+        #   Validity duration of issued license keys. Provide both `duration_count` and
+        #   `duration_interval` together for a fixed duration; omit both for non-expiring
+        #   keys.
         #
         #   @return [Integer, nil]
         optional :duration_count, Integer, nil?: true
 
         # @!attribute duration_interval
+        #   Unit of `duration_count`.
         #
         #   @return [Symbol, Dodopayments::Models::TimeInterval, nil]
         optional :duration_interval, enum: -> { Dodopayments::TimeInterval }, nil?: true
 
         # @!method initialize(activation_message: nil, activations_limit: nil, duration_count: nil, duration_interval: nil)
-        #   @param activation_message [String, nil]
-        #   @param activations_limit [Integer, nil]
-        #   @param duration_count [Integer, nil]
-        #   @param duration_interval [Symbol, Dodopayments::Models::TimeInterval, nil]
+        #   Some parameter documentations has been truncated, see
+        #   {Dodopayments::Models::IntegrationConfig::LicenseKeyConfig} for more details.
+        #
+        #   @param activation_message [String, nil] Optional message displayed when a customer activates the license
+        #
+        #   @param activations_limit [Integer, nil] Maximum activations allowed per issued license key. Omit for unlimited.
+        #
+        #   @param duration_count [Integer, nil] Validity duration of issued license keys. Provide both
+        #
+        #   @param duration_interval [Symbol, Dodopayments::Models::TimeInterval, nil] Unit of `duration_count`.
       end
 
       # @!method self.variants