dodopayments 2.29.0 → 2.30.0

package/src/resources/entitlements/entitlements.ts

@@ -0,0 +1,384 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as SubscriptionsAPI from '../subscriptions';
+import * as FilesAPI from './files';
+import { FileDeleteParams, FileUploadResponse, Files } from './files';
+import * as GrantsAPI from './grants';
+import {
+  EntitlementGrant,
+  EntitlementGrantsDefaultPageNumberPagination,
+  GrantListParams,
+  GrantRevokeParams,
+  Grants,
+  LicenseKeyGrant,
+} from './grants';
+import { APIPromise } from '../../core/api-promise';
+import {
+  DefaultPageNumberPagination,
+  type DefaultPageNumberPaginationParams,
+  PagePromise,
+} from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Entitlements extends APIResource {
+  files: FilesAPI.Files = new FilesAPI.Files(this._client);
+  grants: GrantsAPI.Grants = new GrantsAPI.Grants(this._client);
+
+  /**
+   * POST /entitlements
+   */
+  create(body: EntitlementCreateParams, options?: RequestOptions): APIPromise<Entitlement> {
+    return this._client.post('/entitlements', { body, ...options });
+  }
+
+  /**
+   * GET /entitlements/{id}
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<Entitlement> {
+    return this._client.get(path`/entitlements/${id}`, options);
+  }
+
+  /**
+   * PATCH /entitlements/{id}
+   */
+  update(id: string, body: EntitlementUpdateParams, options?: RequestOptions): APIPromise<Entitlement> {
+    return this._client.patch(path`/entitlements/${id}`, { body, ...options });
+  }
+
+  /**
+   * GET /entitlements
+   */
+  list(
+    query: EntitlementListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<EntitlementsDefaultPageNumberPagination, Entitlement> {
+    return this._client.getAPIList('/entitlements', DefaultPageNumberPagination<Entitlement>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * DELETE /entitlements/{id} (soft-delete)
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/entitlements/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export type EntitlementsDefaultPageNumberPagination = DefaultPageNumberPagination<Entitlement>;
+
+export interface Entitlement {
+  id: string;
+
+  business_id: string;
+
+  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_config: IntegrationConfigResponse;
+
+  integration_type: EntitlementIntegrationType;
+
+  is_active: boolean;
+
+  name: string;
+
+  updated_at: string;
+
+  description?: string | null;
+
+  metadata?: unknown;
+}
+
+export type EntitlementIntegrationType =
+  | 'discord'
+  | 'telegram'
+  | 'github'
+  | 'figma'
+  | 'framer'
+  | 'notion'
+  | 'digital_files'
+  | 'license_key';
+
+/**
+ * Platform-specific configuration for an entitlement. Each variant uses unique
+ * field names so `#[serde(untagged)]` can disambiguate correctly.
+ */
+export type IntegrationConfig =
+  | IntegrationConfig.GitHubConfig
+  | IntegrationConfig.DiscordConfig
+  | IntegrationConfig.TelegramConfig
+  | IntegrationConfig.FigmaConfig
+  | IntegrationConfig.FramerConfig
+  | IntegrationConfig.NotionConfig
+  | IntegrationConfig.DigitalFilesConfig
+  | IntegrationConfig.LicenseKeyConfig;
+
+export namespace IntegrationConfig {
+  export interface GitHubConfig {
+    /**
+     * One of: pull, push, admin, maintain, triage
+     */
+    permission: string;
+
+    target_id: string;
+  }
+
+  export interface DiscordConfig {
+    guild_id: string;
+
+    role_id?: string | null;
+  }
+
+  export interface TelegramConfig {
+    chat_id: string;
+  }
+
+  export interface FigmaConfig {
+    figma_file_id: string;
+  }
+
+  export interface FramerConfig {
+    framer_template_id: string;
+  }
+
+  export interface NotionConfig {
+    notion_template_id: string;
+  }
+
+  export interface DigitalFilesConfig {
+    digital_file_ids: Array<string>;
+
+    external_url?: string | null;
+
+    instructions?: string | null;
+
+    /**
+     * Three-way patchable field (mirrors the credit_entitlements pattern):
+     *
+     * - omitted → preserve persisted (`None`)
+     * - `null` → clear (`Some(None)`)
+     * - `[...]` → replace (`Some(Some(...))`)
+     *
+     * On Create / storage we collapse "clear" and empty-array to `None` so the
+     * persisted JSONB never carries a `null` legacy_file_ids key.
+     */
+    legacy_file_ids?: Array<string> | null;
+  }
+
+  export interface LicenseKeyConfig {
+    activation_message?: string | null;
+
+    activations_limit?: number | null;
+
+    duration_count?: number | null;
+
+    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.
+ */
+export type IntegrationConfigResponse =
+  | IntegrationConfigResponse.GitHubConfig
+  | IntegrationConfigResponse.DiscordConfig
+  | IntegrationConfigResponse.TelegramConfig
+  | IntegrationConfigResponse.FigmaConfig
+  | IntegrationConfigResponse.FramerConfig
+  | IntegrationConfigResponse.NotionConfig
+  | IntegrationConfigResponse.DigitalFilesConfig
+  | IntegrationConfigResponse.LicenseKeyConfig;
+
+export namespace IntegrationConfigResponse {
+  export interface GitHubConfig {
+    permission: string;
+
+    target_id: string;
+  }
+
+  export interface DiscordConfig {
+    guild_id: string;
+
+    role_id?: string | null;
+  }
+
+  export interface TelegramConfig {
+    chat_id: string;
+  }
+
+  export interface FigmaConfig {
+    figma_file_id: string;
+  }
+
+  export interface FramerConfig {
+    framer_template_id: string;
+  }
+
+  export interface NotionConfig {
+    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`).
+     */
+    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`).
+     */
+    export interface DigitalFiles {
+      files: Array<DigitalFiles.File>;
+
+      external_url?: string | null;
+
+      instructions?: string | null;
+    }
+
+    export namespace DigitalFiles {
+      export interface File {
+        download_url: string;
+
+        /**
+         * Seconds until `download_url` expires.
+         */
+        expires_in: number;
+
+        file_id: string;
+
+        filename: string;
+
+        /**
+         * `"legacy"` for files in `product_files`, `"ee"` for files managed by the
+         * Entitlements Engine.
+         */
+        source: string;
+
+        content_type?: string | null;
+
+        file_size?: number | null;
+      }
+    }
+  }
+
+  export interface LicenseKeyConfig {
+    activation_message?: string | null;
+
+    activations_limit?: number | null;
+
+    duration_count?: number | null;
+
+    duration_interval?: SubscriptionsAPI.TimeInterval | null;
+  }
+}
+
+export interface EntitlementCreateParams {
+  /**
+   * Platform-specific configuration (validated per integration_type)
+   */
+  integration_config: IntegrationConfig;
+
+  /**
+   * Which platform integration this entitlement uses
+   */
+  integration_type: EntitlementIntegrationType;
+
+  /**
+   * Display name for this entitlement
+   */
+  name: string;
+
+  /**
+   * Optional description
+   */
+  description?: string | null;
+
+  /**
+   * Optional user-facing metadata
+   */
+  metadata?: { [key: string]: string } | null;
+}
+
+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_config?: IntegrationConfig | null;
+
+  metadata?: { [key: string]: string } | null;
+
+  name?: string | null;
+}
+
+export interface EntitlementListParams extends DefaultPageNumberPaginationParams {
+  /**
+   * Filter by integration type
+   */
+  integration_type?:
+    | 'discord'
+    | 'telegram'
+    | 'github'
+    | 'figma'
+    | 'framer'
+    | 'notion'
+    | 'digital_files'
+    | 'license_key';
+}
+
+Entitlements.Files = Files;
+Entitlements.Grants = Grants;
+
+export declare namespace Entitlements {
+  export {
+    type Entitlement as Entitlement,
+    type EntitlementIntegrationType as EntitlementIntegrationType,
+    type IntegrationConfig as IntegrationConfig,
+    type IntegrationConfigResponse as IntegrationConfigResponse,
+    type EntitlementsDefaultPageNumberPagination as EntitlementsDefaultPageNumberPagination,
+    type EntitlementCreateParams as EntitlementCreateParams,
+    type EntitlementUpdateParams as EntitlementUpdateParams,
+    type EntitlementListParams as EntitlementListParams,
+  };
+
+  export {
+    Files as Files,
+    type FileUploadResponse as FileUploadResponse,
+    type FileDeleteParams as FileDeleteParams,
+  };
+
+  export {
+    Grants as Grants,
+    type EntitlementGrant as EntitlementGrant,
+    type LicenseKeyGrant as LicenseKeyGrant,
+    type EntitlementGrantsDefaultPageNumberPagination as EntitlementGrantsDefaultPageNumberPagination,
+    type GrantListParams as GrantListParams,
+    type GrantRevokeParams as GrantRevokeParams,
+  };
+}

package/src/resources/entitlements/files.ts

@@ -0,0 +1,53 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+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.
+   */
+  delete(fileID: string, params: FileDeleteParams, options?: RequestOptions): APIPromise<void> {
+    const { id } = params;
+    return this._client.delete(path`/entitlements/${id}/files/${fileID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * 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).
+   */
+  upload(id: string, options?: RequestOptions): APIPromise<FileUploadResponse> {
+    return this._client.post(path`/entitlements/${id}/files`, options);
+  }
+}
+
+export interface FileUploadResponse {
+  /**
+   * EE-issued digital file id; appended to
+   * `entitlements.integration_config.digital_file_ids`.
+   */
+  file_id: string;
+}
+
+export interface FileDeleteParams {
+  /**
+   * Entitlement Id
+   */
+  id: string;
+}
+
+export declare namespace Files {
+  export { type FileUploadResponse as FileUploadResponse, type FileDeleteParams as FileDeleteParams };
+}

package/src/resources/entitlements/grants.ts

@@ -0,0 +1,136 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as ProductsAPI from '../products/products';
+import { APIPromise } from '../../core/api-promise';
+import {
+  DefaultPageNumberPagination,
+  type DefaultPageNumberPaginationParams,
+  PagePromise,
+} from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Grants extends APIResource {
+  /**
+   * GET /entitlements/{id}/grants (public API)
+   */
+  list(
+    id: string,
+    query: GrantListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<EntitlementGrantsDefaultPageNumberPagination, EntitlementGrant> {
+    return this._client.getAPIList(
+      path`/entitlements/${id}/grants`,
+      DefaultPageNumberPagination<EntitlementGrant>,
+      { query, ...options },
+    );
+  }
+
+  /**
+   * 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(grantID: string, params: GrantRevokeParams, options?: RequestOptions): APIPromise<EntitlementGrant> {
+    const { id } = params;
+    return this._client.delete(path`/entitlements/${id}/grants/${grantID}`, options);
+  }
+}
+
+export type EntitlementGrantsDefaultPageNumberPagination = DefaultPageNumberPagination<EntitlementGrant>;
+
+export interface EntitlementGrant {
+  id: string;
+
+  business_id: string;
+
+  created_at: string;
+
+  customer_id: string;
+
+  entitlement_id: string;
+
+  external_id: string;
+
+  status: 'Pending' | 'Delivered' | 'Failed' | 'Revoked';
+
+  updated_at: string;
+
+  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?: ProductsAPI.DigitalProductDelivery | null;
+
+  error_code?: string | null;
+
+  error_message?: string | null;
+
+  /**
+   * Present only when the entitlement integration_type is `license_key`.
+   */
+  license_key?: LicenseKeyGrant | null;
+
+  metadata?: unknown;
+
+  oauth_expires_at?: string | null;
+
+  oauth_url?: string | null;
+
+  payment_id?: string | null;
+
+  revocation_reason?: string | null;
+
+  revoked_at?: string | null;
+
+  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.
+ */
+export interface LicenseKeyGrant {
+  activations_used: number;
+
+  key: string;
+
+  activations_limit?: number | null;
+
+  expires_at?: string | null;
+}
+
+export interface GrantListParams extends DefaultPageNumberPaginationParams {
+  /**
+   * Filter by customer ID
+   */
+  customer_id?: string;
+
+  /**
+   * Filter by grant status
+   */
+  status?: 'Pending' | 'Delivered' | 'Failed' | 'Revoked';
+}
+
+export interface GrantRevokeParams {
+  /**
+   * Entitlement ID
+   */
+  id: string;
+}
+
+export declare namespace Grants {
+  export {
+    type EntitlementGrant as EntitlementGrant,
+    type LicenseKeyGrant as LicenseKeyGrant,
+    type EntitlementGrantsDefaultPageNumberPagination as EntitlementGrantsDefaultPageNumberPagination,
+    type GrantListParams as GrantListParams,
+    type GrantRevokeParams as GrantRevokeParams,
+  };
+}

package/src/resources/entitlements/index.ts

@@ -0,0 +1,22 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Entitlements,
+  type Entitlement,
+  type EntitlementIntegrationType,
+  type IntegrationConfig,
+  type IntegrationConfigResponse,
+  type EntitlementCreateParams,
+  type EntitlementUpdateParams,
+  type EntitlementListParams,
+  type EntitlementsDefaultPageNumberPagination,
+} from './entitlements';
+export { Files, type FileUploadResponse, type FileDeleteParams } from './files';
+export {
+  Grants,
+  type EntitlementGrant,
+  type LicenseKeyGrant,
+  type GrantListParams,
+  type GrantRevokeParams,
+  type EntitlementGrantsDefaultPageNumberPagination,
+} from './grants';

package/src/resources/entitlements.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './entitlements/index';

package/src/resources/index.ts

@@ -54,6 +54,7 @@ export {
   type Customer,
   type CustomerPortalSession,
   type CustomerListCreditEntitlementsResponse,
+  type CustomerListEntitlementsResponse,
   type CustomerRetrievePaymentMethodsResponse,
   type CustomerCreateParams,
   type CustomerUpdateParams,
@@ -80,6 +81,17 @@ export {
   type DisputeListParams,
   type DisputeListResponsesDefaultPageNumberPagination,
 } from './disputes';
+export {
+  Entitlements,
+  type Entitlement,
+  type EntitlementIntegrationType,
+  type IntegrationConfig,
+  type IntegrationConfigResponse,
+  type EntitlementCreateParams,
+  type EntitlementUpdateParams,
+  type EntitlementListParams,
+  type EntitlementsDefaultPageNumberPagination,
+} from './entitlements/entitlements';
 export { Invoices } from './invoices/invoices';
 export {
   LicenseKeyInstances,
@@ -156,6 +168,7 @@ export {
   Products,
   type AddMeterToPrice,
   type AttachCreditEntitlement,
+  type AttachProductEntitlement,
   type CbbProrationBehavior,
   type CreditEntitlementMappingResponse,
   type DigitalProductDelivery,
@@ -163,6 +176,7 @@ export {
   type LicenseKeyDuration,
   type Price,
   type Product,
+  type ProductEntitlementSummary,
   type ProductListResponse,
   type ProductUpdateFilesResponse,
   type ProductCreateParams,
@@ -182,10 +196,12 @@ export {
   Subscriptions,
   type AddonCartResponseItem,
   type AttachAddon,
+  type CancellationFeedback,
   type CreditEntitlementCartResponse,
   type MeterCartResponseItem,
   type MeterCreditEntitlementCartResponse,
   type OnDemandSubscription,
+  type ScheduledPlanChange,
   type Subscription,
   type SubscriptionStatus,
   type TimeInterval,
@@ -230,6 +246,7 @@ export {
   type CreditExpiredWebhookEvent,
   type CreditManualAdjustmentWebhookEvent,
   type CreditOverageChargedWebhookEvent,
+  type CreditOverageResetWebhookEvent,
   type CreditRolledOverWebhookEvent,
   type CreditRolloverForfeitedWebhookEvent,
   type DisputeAcceptedWebhookEvent,
@@ -241,6 +258,10 @@ export {
   type DisputeWonWebhookEvent,
   type DunningRecoveredWebhookEvent,
   type DunningStartedWebhookEvent,
+  type EntitlementGrantCreatedWebhookEvent,
+  type EntitlementGrantDeliveredWebhookEvent,
+  type EntitlementGrantFailedWebhookEvent,
+  type EntitlementGrantRevokedWebhookEvent,
   type LicenseKeyCreatedWebhookEvent,
   type PaymentCancelledWebhookEvent,
   type PaymentFailedWebhookEvent,

package/src/resources/license-key-instances.ts

@@ -79,6 +79,11 @@ export interface LicenseKeyInstanceUpdateParams {
 }
 
 export interface LicenseKeyInstanceListParams extends DefaultPageNumberPaginationParams {
+  /**
+   * Filter instances by entitlement grant ID
+   */
+  grant_id?: string | null;
+
   /**
    * Filter by license key ID
    */