dodopayments 2.30.0 → 2.31.0

package/src/resources/entitlements/entitlements.ts

@@ -74,32 +74,62 @@ export class Entitlements extends APIResource {
 
 export type EntitlementsDefaultPageNumberPagination = DefaultPageNumberPagination<Entitlement>;
 
+/**
+ * Detailed view of a single entitlement: identity, integration type,
+ * integration-specific configuration, and metadata.
+ */
 export interface Entitlement {
+  /**
+   * Unique identifier of the entitlement.
+   */
   id: string;
 
+  /**
+   * Identifier of the business that owns this entitlement.
+   */
   business_id: string;
 
+  /**
+   * Timestamp when the entitlement was created.
+   */
   created_at: string;
 
   /**
-   * 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: IntegrationConfigResponse;
 
+  /**
+   * Platform integration this entitlement uses.
+   */
   integration_type: EntitlementIntegrationType;
 
+  /**
+   * Always `true` for entitlements returned by the public API; soft-deleted
+   * entitlements are not returned.
+   */
   is_active: boolean;
 
+  /**
+   * Arbitrary key-value metadata supplied at creation or via PATCH.
+   */
+  metadata: { [key: string]: string };
+
+  /**
+   * Display name supplied at creation.
+   */
   name: string;
 
+  /**
+   * Timestamp when the entitlement was last modified.
+   */
   updated_at: string;
 
+  /**
+   * Optional description supplied at creation.
+   */
   description?: string | null;
-
-  metadata?: unknown;
 }
 
 export type EntitlementIntegrationType =
@@ -113,8 +143,8 @@ export type EntitlementIntegrationType =
   | 'license_key';
 
 /**
- * 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`.
  */
 export type IntegrationConfig =
   | IntegrationConfig.GitHubConfig
@@ -129,71 +159,119 @@ export type IntegrationConfig =
 export namespace IntegrationConfig {
   export interface GitHubConfig {
     /**
-     * One of: pull, push, admin, maintain, triage
+     * Permission to grant on the repository.
      */
-    permission: string;
+    permission: 'pull' | 'push' | 'admin' | 'maintain' | 'triage';
 
+    /**
+     * Repository or organisation slug to grant access to.
+     */
     target_id: string;
   }
 
   export interface DiscordConfig {
+    /**
+     * Discord guild (server) ID.
+     */
     guild_id: string;
 
+    /**
+     * Optional Discord role to assign within the guild.
+     */
     role_id?: string | null;
   }
 
   export interface TelegramConfig {
+    /**
+     * Telegram chat ID. For groups this is typically a negative integer.
+     */
     chat_id: string;
   }
 
   export interface FigmaConfig {
+    /**
+     * Figma file identifier to grant access to.
+     */
     figma_file_id: string;
   }
 
   export interface FramerConfig {
+    /**
+     * Framer template identifier to grant access to.
+     */
     framer_template_id: string;
   }
 
   export interface NotionConfig {
+    /**
+     * Notion template identifier to grant access to.
+     */
     notion_template_id: string;
   }
 
   export interface DigitalFilesConfig {
+    /**
+     * 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: Array<string>;
 
+    /**
+     * Optional external URL shown to the customer alongside the files.
+     */
     external_url?: string | null;
 
+    /**
+     * Optional human-readable delivery instructions shown to the customer alongside
+     * the files.
+     */
     instructions?: string | null;
 
     /**
-     * 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?: Array<string> | null;
   }
 
   export interface LicenseKeyConfig {
+    /**
+     * Optional message displayed when a customer activates the license key (≤ 2500
+     * characters).
+     */
     activation_message?: string | null;
 
+    /**
+     * Maximum activations allowed per issued license key. Omit for unlimited.
+     */
     activations_limit?: number | null;
 
+    /**
+     * 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?: number | null;
 
+    /**
+     * Unit of `duration_count`.
+     */
     duration_interval?: SubscriptionsAPI.TimeInterval | null;
   }
 }
 
 /**
- * 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 on an entitlement read response.
+ *
+ * For `digital_files` entitlements the response includes presigned download URLs
+ * for each attached file; other integrations match the shape supplied at creation.
  */
 export type IntegrationConfigResponse =
   | IntegrationConfigResponse.GitHubConfig
@@ -207,60 +285,96 @@ export type IntegrationConfigResponse =
 
 export namespace IntegrationConfigResponse {
   export interface GitHubConfig {
-    permission: string;
+    /**
+     * Permission to grant on the repository.
+     */
+    permission: 'pull' | 'push' | 'admin' | 'maintain' | 'triage';
 
+    /**
+     * Repository or organisation slug to grant access to.
+     */
     target_id: string;
   }
 
   export interface DiscordConfig {
+    /**
+     * Discord guild (server) ID.
+     */
     guild_id: string;
 
+    /**
+     * Optional Discord role to assign within the guild.
+     */
     role_id?: string | null;
   }
 
   export interface TelegramConfig {
+    /**
+     * Telegram chat ID. For groups this is typically a negative integer.
+     */
     chat_id: string;
   }
 
   export interface FigmaConfig {
+    /**
+     * Figma file identifier to grant access to.
+     */
     figma_file_id: string;
   }
 
   export interface FramerConfig {
+    /**
+     * Framer template identifier to grant access to.
+     */
     framer_template_id: string;
   }
 
   export interface NotionConfig {
+    /**
+     * Notion template identifier to grant access to.
+     */
     notion_template_id: string;
   }
 
   export interface DigitalFilesConfig {
     /**
-     * Populated digital-files payload for entitlement read surfaces. Mirrors
-     * `DigitalProductDelivery` but is sourced from an entitlement's
-     * `integration_config` (not a grant) and tags each file with its origin (`legacy`
-     * vs `ee`).
+     * Populated digital-files payload with each file's metadata and a short-lived
+     * presigned download URL.
      */
     digital_files: DigitalFilesConfig.DigitalFiles;
   }
 
   export namespace DigitalFilesConfig {
     /**
-     * Populated digital-files payload for entitlement read surfaces. Mirrors
-     * `DigitalProductDelivery` but is sourced from an entitlement's
-     * `integration_config` (not a grant) and tags each file with its origin (`legacy`
-     * vs `ee`).
+     * Populated digital-files payload with each file's metadata and a short-lived
+     * presigned download URL.
      */
     export interface DigitalFiles {
+      /**
+       * One entry per attached file.
+       */
       files: Array<DigitalFiles.File>;
 
+      /**
+       * Optional external URL, passed through from the entitlement configuration.
+       */
       external_url?: string | null;
 
+      /**
+       * Optional human-readable delivery instructions, passed through from the
+       * entitlement configuration.
+       */
       instructions?: string | null;
     }
 
     export namespace DigitalFiles {
+      /**
+       * One file in a resolved digital-files payload.
+       */
       export interface File {
+        /**
+         * Short-lived presigned URL for downloading the file.
+         */
         download_url: string;
 
         /**
@@ -268,30 +382,51 @@ export namespace IntegrationConfigResponse {
          */
         expires_in: number;
 
+        /**
+         * Identifier of the attached file.
+         */
         file_id: string;
 
+        /**
+         * Original filename of the attached file.
+         */
         filename: string;
 
         /**
-         * `"legacy"` for files in `product_files`, `"ee"` for files managed by the
-         * Entitlements Engine.
+         * Optional content-type declared at upload.
          */
-        source: string;
-
         content_type?: string | null;
 
+        /**
+         * Optional size of the file in bytes.
+         */
         file_size?: number | null;
       }
     }
   }
 
   export interface LicenseKeyConfig {
+    /**
+     * Optional message displayed when a customer activates the license key (≤ 2500
+     * characters).
+     */
     activation_message?: string | null;
 
+    /**
+     * Maximum activations allowed per issued license key. Omit for unlimited.
+     */
     activations_limit?: number | null;
 
+    /**
+     * 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?: number | null;
 
+    /**
+     * Unit of `duration_count`.
+     */
     duration_interval?: SubscriptionsAPI.TimeInterval | null;
   }
 }
@@ -318,17 +453,17 @@ export interface EntitlementCreateParams {
   description?: string | null;
 
   /**
-   * Optional user-facing metadata
+   * Additional metadata for the entitlement
    */
-  metadata?: { [key: string]: string } | null;
+  metadata?: { [key: string]: string };
 }
 
 export interface EntitlementUpdateParams {
   description?: string | null;
 
   /**
-   * 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?: IntegrationConfig | null;
 

package/src/resources/entitlements/files.ts

@@ -8,10 +8,7 @@ import { path } from '../../internal/utils/path';
 
 export class Files extends APIResource {
   /**
-   * 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.
    */
   delete(fileID: string, params: FileDeleteParams, options?: RequestOptions): APIPromise<void> {
     const { id } = params;
@@ -22,11 +19,7 @@ export class Files extends APIResource {
   }
 
   /**
-   * 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.
    */
   upload(id: string, options?: RequestOptions): APIPromise<FileUploadResponse> {
     return this._client.post(path`/entitlements/${id}/files`, options);
@@ -35,8 +28,8 @@ export class Files extends APIResource {
 
 export interface FileUploadResponse {
   /**
-   * 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: string;
 }

package/src/resources/entitlements/grants.ts

@@ -28,10 +28,8 @@ export class Grants extends APIResource {
   }
 
   /**
-   * 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.
    */
   revoke(grantID: string, params: GrantRevokeParams, options?: RequestOptions): APIPromise<EntitlementGrant> {
     const { id } = params;
@@ -41,68 +39,134 @@ export class Grants extends APIResource {
 
 export type EntitlementGrantsDefaultPageNumberPagination = DefaultPageNumberPagination<EntitlementGrant>;
 
+/**
+ * Detailed view of a single entitlement grant: who it's for, its lifecycle state,
+ * and any integration-specific delivery payload.
+ */
 export interface EntitlementGrant {
+  /**
+   * Unique identifier of the grant.
+   */
   id: string;
 
+  /**
+   * Identifier of the business that owns the grant.
+   */
   business_id: string;
 
+  /**
+   * Timestamp when the grant was created.
+   */
   created_at: string;
 
+  /**
+   * Identifier of the customer the grant was issued to.
+   */
   customer_id: string;
 
+  /**
+   * Identifier of the entitlement this grant was issued from.
+   */
   entitlement_id: string;
 
-  external_id: string;
+  /**
+   * Arbitrary key-value metadata recorded on the grant.
+   */
+  metadata: { [key: string]: string };
 
+  /**
+   * Lifecycle status of the grant.
+   */
   status: 'Pending' | 'Delivered' | 'Failed' | 'Revoked';
 
+  /**
+   * Timestamp when the grant was last modified.
+   */
   updated_at: string;
 
+  /**
+   * Timestamp when the grant transitioned to `delivered`, when applicable.
+   */
   delivered_at?: string | null;
 
   /**
-   * 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?: ProductsAPI.DigitalProductDelivery | null;
 
+  /**
+   * Machine-readable code reported when delivery failed, when applicable.
+   */
   error_code?: string | null;
 
+  /**
+   * Human-readable message reported when delivery failed, when applicable.
+   */
   error_message?: string | null;
 
   /**
-   * Present only when the entitlement integration_type is `license_key`.
+   * License-key delivery payload, present when the entitlement integration is
+   * `license_key`.
    */
   license_key?: LicenseKeyGrant | null;
 
-  metadata?: unknown;
-
+  /**
+   * Timestamp when `oauth_url` stops being valid, when applicable.
+   */
   oauth_expires_at?: string | null;
 
+  /**
+   * 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?: string | null;
 
+  /**
+   * Identifier of the payment that triggered this grant, when applicable.
+   */
   payment_id?: string | null;
 
+  /**
+   * Reason recorded when the grant was revoked, when applicable.
+   */
   revocation_reason?: string | null;
 
+  /**
+   * Timestamp when the grant transitioned to `revoked`, when applicable.
+   */
   revoked_at?: string | null;
 
+  /**
+   * Identifier of the subscription that triggered this grant, when applicable.
+   */
   subscription_id?: string | null;
 }
 
 /**
- * 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.
  */
 export interface LicenseKeyGrant {
+  /**
+   * Number of activations consumed so far.
+   */
   activations_used: number;
 
+  /**
+   * Issued license key.
+   */
   key: string;
 
+  /**
+   * Maximum activations allowed by the entitlement, when set.
+   */
   activations_limit?: number | null;
 
+  /**
+   * When the license key expires, when applicable.
+   */
   expires_at?: string | null;
 }
 

package/src/resources/products/products.ts

@@ -333,20 +333,34 @@ export interface CreditEntitlementMappingResponse {
 }
 
 /**
- * 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.
  */
 export interface DigitalProductDelivery {
+  /**
+   * One entry per attached file.
+   */
   files: Array<DigitalProductDeliveryFile>;
 
+  /**
+   * Optional external URL, passed through from the entitlement configuration.
+   */
   external_url?: string | null;
 
+  /**
+   * Optional human-readable delivery instructions, passed through from the
+   * entitlement configuration.
+   */
   instructions?: string | null;
 }
 
+/**
+ * One file in a digital-product delivery payload.
+ */
 export interface DigitalProductDeliveryFile {
+  /**
+   * Short-lived presigned URL for downloading the file.
+   */
   download_url: string;
 
   /**
@@ -354,12 +368,24 @@ export interface DigitalProductDeliveryFile {
    */
   expires_in: number;
 
+  /**
+   * Identifier of the attached file.
+   */
   file_id: string;
 
+  /**
+   * Original filename of the attached file.
+   */
   filename: string;
 
+  /**
+   * Optional content-type declared at upload.
+   */
   content_type?: string | null;
 
+  /**
+   * Optional size of the file in bytes.
+   */
   file_size?: number | null;
 }
 
@@ -614,10 +640,8 @@ export interface Product {
   description?: string | null;
 
   /**
-   * 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.
    */
   digital_product_delivery?: DigitalProductDelivery | null;
 
@@ -664,10 +688,10 @@ export interface ProductEntitlementSummary {
   id: string;
 
   /**
-   * 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 on an entitlement read response.
+   *
+   * For `digital_files` entitlements the response includes presigned download URLs
+   * for each attached file; other integrations match the shape supplied at creation.
    */
   integration_config: EntitlementsAPI.IntegrationConfigResponse;
 

package/src/resources/webhook-events.ts

@@ -175,6 +175,10 @@ export namespace WebhookPayload {
     payment_id?: string | null;
   }
 
+  /**
+   * Detailed view of a single entitlement grant: who it's for, its lifecycle state,
+   * and any integration-specific delivery payload.
+   */
   export interface EntitlementGrant extends GrantsAPI.EntitlementGrant {
     payload_type: 'EntitlementGrant';
   }