dodopayments 2.51.0 → 2.53.0

package/src/resources/moderation.ts

@@ -0,0 +1,388 @@
+// 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 { RequestOptions } from '../internal/request-options';
+
+export class Moderation extends APIResource {
+  /**
+   * Screens text, an image, or both, and returns a verdict: `allow`, `flag` or
+   * `deny`. The API is fail-closed: do not generate when you get no verdict.
+   *
+   * **Pricing.** Dodo Payments charges $0.30 per 1000 billable screens and debits
+   * the fee from your balance. A billable screen is a live-mode screen that returns
+   * a verdict. Errors and test-mode screens are free.
+   *
+   * **429.** Honour `Retry-After` and retry. A 429 is a throughput limit, not a
+   * verdict.
+   *
+   * **Test mode** returns mock verdicts and never calls the model. The default
+   * verdict is `allow`. Put one of these strings in `text` to select another
+   * outcome: `dodo_mock_flag` (`flag`), `dodo_mock_deny` (`deny`),
+   * `dodo_mock_overloaded` (429) or `dodo_mock_not_ready` (503).
+   */
+  screen(body: ModerationScreenParams, options?: RequestOptions): APIPromise<ModerationScreenResponse> {
+    return this._client.post('/moderation/screen', { body, ...options });
+  }
+
+  /**
+   * Shows how many billable screens you made and how close you are to your next
+   * charge.
+   *
+   * **Billing.** A billable screen is a live-mode screen that returns a verdict.
+   * Dodo Payments charges $0.30 for each full block of 1000 billable screens and
+   * debits the fee from your balance. Each full block is charged within one hour.
+   * Screens that do not fill a block stay unbilled until they do. Errors and
+   * test-mode screens are free and are not counted.
+   */
+  retrieveUsage(options?: RequestOptions): APIPromise<ModerationRetrieveUsageResponse> {
+    return this._client.get('/moderation/usage', options);
+  }
+}
+
+/**
+ * A moderation category.
+ */
+export type ModerationCategory =
+  | 'violent_crimes'
+  | 'sex_related_crimes'
+  | 'child_sexual_exploitation'
+  | 'suicide_and_self_harm'
+  | 'indiscriminate_weapons'
+  | 'intellectual_property'
+  | 'defamation'
+  | 'non_violent_crimes'
+  | 'hate'
+  | 'privacy'
+  | 'specialized_advice'
+  | 'sexual_content'
+  | 'non_consensual_intimate_imagery'
+  | 'minor_coded_language'
+  | 'real_person_likeness'
+  | 'living_artist_style'
+  | 'prompt_injection';
+
+/**
+ * How each score in `categories` was measured.
+ */
+export interface ModerationCategoryProvenance {
+  /**
+   * Child sexual exploitation.
+   */
+  child_sexual_exploitation: ModerationProvenance;
+
+  /**
+   * False depiction that is likely to injure the reputation of a real person.
+   */
+  defamation: ModerationProvenance;
+
+  /**
+   * Demeaning people because of a protected characteristic.
+   */
+  hate: ModerationProvenance;
+
+  /**
+   * Chemical, biological, radiological, nuclear or explosive weapons.
+   */
+  indiscriminate_weapons: ModerationProvenance;
+
+  /**
+   * Copyright or trademark infringement.
+   */
+  intellectual_property: ModerationProvenance;
+
+  /**
+   * Imitation of the signature style of a specific living artist.
+   */
+  living_artist_style: ModerationProvenance;
+
+  /**
+   * Age-coded language that suggests the subject is a minor.
+   */
+  minor_coded_language: ModerationProvenance;
+
+  /**
+   * Non-consensual intimate imagery: undressing, nudifying or sexualising a real
+   * person.
+   */
+  non_consensual_intimate_imagery: ModerationProvenance;
+
+  /**
+   * Non-violent crimes.
+   */
+  non_violent_crimes: ModerationProvenance;
+
+  /**
+   * Sensitive private information about a person.
+   */
+  privacy: ModerationProvenance;
+
+  /**
+   * An attempt to override or manipulate the instructions of the system.
+   */
+  prompt_injection: ModerationProvenance;
+
+  /**
+   * The likeness of a real, identifiable, named person.
+   */
+  real_person_likeness: ModerationProvenance;
+
+  /**
+   * Sex-related crimes.
+   */
+  sex_related_crimes: ModerationProvenance;
+
+  /**
+   * Sexually explicit or pornographic content.
+   */
+  sexual_content: ModerationProvenance;
+
+  /**
+   * Unqualified financial, medical, legal or electoral advice.
+   */
+  specialized_advice: ModerationProvenance;
+
+  /**
+   * Suicide and self-harm.
+   */
+  suicide_and_self_harm: ModerationProvenance;
+
+  /**
+   * Violent crimes.
+   */
+  violent_crimes: ModerationProvenance;
+}
+
+/**
+ * The probability, from 0 to 1, that the screen falls in each category.
+ */
+export interface ModerationCategoryScores {
+  /**
+   * Child sexual exploitation.
+   */
+  child_sexual_exploitation: number;
+
+  /**
+   * False depiction that is likely to injure the reputation of a real person.
+   */
+  defamation: number;
+
+  /**
+   * Demeaning people because of a protected characteristic.
+   */
+  hate: number;
+
+  /**
+   * Chemical, biological, radiological, nuclear or explosive weapons.
+   */
+  indiscriminate_weapons: number;
+
+  /**
+   * Copyright or trademark infringement.
+   */
+  intellectual_property: number;
+
+  /**
+   * Imitation of the signature style of a specific living artist.
+   */
+  living_artist_style: number;
+
+  /**
+   * Age-coded language that suggests the subject is a minor.
+   */
+  minor_coded_language: number;
+
+  /**
+   * Non-consensual intimate imagery: undressing, nudifying or sexualising a real
+   * person.
+   */
+  non_consensual_intimate_imagery: number;
+
+  /**
+   * Non-violent crimes.
+   */
+  non_violent_crimes: number;
+
+  /**
+   * Sensitive private information about a person.
+   */
+  privacy: number;
+
+  /**
+   * An attempt to override or manipulate the instructions of the system.
+   */
+  prompt_injection: number;
+
+  /**
+   * The likeness of a real, identifiable, named person.
+   */
+  real_person_likeness: number;
+
+  /**
+   * Sex-related crimes.
+   */
+  sex_related_crimes: number;
+
+  /**
+   * Sexually explicit or pornographic content.
+   */
+  sexual_content: number;
+
+  /**
+   * Unqualified financial, medical, legal or electoral advice.
+   */
+  specialized_advice: number;
+
+  /**
+   * Suicide and self-harm.
+   */
+  suicide_and_self_harm: number;
+
+  /**
+   * Violent crimes.
+   */
+  violent_crimes: number;
+}
+
+/**
+ * The verdict. `allow` means the content passed. `deny` means block the content.
+ * `flag` means apply your own judgement. It is not a soft deny.
+ */
+export type ModerationDecision = 'allow' | 'flag' | 'deny';
+
+/**
+ * How a score was measured. `targeted` means a check for that one category
+ * measured it. `broad` means the general check that covers all categories measured
+ * it.
+ */
+export type ModerationProvenance = 'targeted' | 'broad';
+
+/**
+ * Your moderation usage.
+ */
+export interface ModerationRetrieveUsageResponse {
+  /**
+   * Your billable screens per UTC day for the last 30 days, charged or not. A day
+   * with no screens is not in the list.
+   */
+  daily: Array<ModerationRetrieveUsageResponse.Daily>;
+
+  /**
+   * Billable screens still needed to fill the next block of 1000. A full block is
+   * charged within one hour, so this value is 1000 when your unbilled screens fill
+   * whole blocks.
+   */
+  screens_to_next_block: number;
+
+  /**
+   * Billable screens that Dodo Payments has not charged for yet.
+   */
+  unbilled_screens: number;
+}
+
+export namespace ModerationRetrieveUsageResponse {
+  export interface Daily {
+    /**
+     * The UTC day.
+     */
+    date: string;
+
+    /**
+     * Billable screens on that day.
+     */
+    screens: number;
+  }
+}
+
+/**
+ * The verdict of one screen.
+ */
+export interface ModerationScreenResponse {
+  /**
+   * The probability, from 0 to 1, that the screen falls in each category.
+   */
+  categories: ModerationCategoryScores;
+
+  /**
+   * True when real-person likeness and sexual content together crossed their
+   * combined threshold, the pattern of a sexual deepfake.
+   */
+  compound_triggered: boolean;
+
+  /**
+   * The verdict. `allow` means the content passed. `deny` means block the content.
+   * `flag` means apply your own judgement. It is not a soft deny.
+   */
+  decision: ModerationDecision;
+
+  /**
+   * The time the screen took, in milliseconds.
+   */
+  latency_ms: number;
+
+  /**
+   * True when the text was also screened in a normalized form, with obfuscation such
+   * as invisible or look-alike characters removed.
+   */
+  normalized_applied: boolean;
+
+  /**
+   * Human-readable reasons for the decision. The wording can change, so do not parse
+   * it.
+   */
+  notes: Array<string>;
+
+  /**
+   * The number of yes/no questions the model answered for this screen.
+   */
+  passes: number;
+
+  /**
+   * How each score in `categories` was measured.
+   */
+  provenance: ModerationCategoryProvenance;
+
+  /**
+   * The `request_id` you sent, or null.
+   */
+  request_id: string | null;
+
+  /**
+   * The categories whose score crossed the threshold of the category. It can be
+   * empty on a `flag` from the general check. `notes` then gives the reason.
+   */
+  triggered: Array<ModerationCategory>;
+}
+
+export interface ModerationScreenParams {
+  /**
+   * The image to screen, as base64, with or without a `data:image/...;base64,`
+   * prefix. The formats are JPEG, PNG, WebP, GIF and BMP. The limit is 6991530
+   * base64 characters, and the decoded image must be at most 5 MiB.
+   */
+  image?: string | null;
+
+  /**
+   * Your identifier for this screen, up to 128 characters, with no control
+   * characters. The response returns it in `request_id`.
+   */
+  request_id?: string | null;
+
+  /**
+   * The text to screen, up to 8000 characters.
+   */
+  text?: string | null;
+}
+
+export declare namespace Moderation {
+  export {
+    type ModerationCategory as ModerationCategory,
+    type ModerationCategoryProvenance as ModerationCategoryProvenance,
+    type ModerationCategoryScores as ModerationCategoryScores,
+    type ModerationDecision as ModerationDecision,
+    type ModerationProvenance as ModerationProvenance,
+    type ModerationRetrieveUsageResponse as ModerationRetrieveUsageResponse,
+    type ModerationScreenResponse as ModerationScreenResponse,
+    type ModerationScreenParams as ModerationScreenParams,
+  };
+}

package/src/resources/payments.ts

@@ -329,6 +329,13 @@ export interface Payment {
    */
   disputes: Array<DisputesAPI.Dispute>;
 
+  /**
+   * True when one payment starts more than one subscription. Read this field to find
+   * the payment type. Do not read the length of `subscription_ids`. Do not read
+   * `subscription_id` for null.
+   */
+  is_multi_subscription: boolean;
+
   /**
    * Whether this payment was created solely to update a subscription's payment
    * method (a zero-/setup-amount charge). `false` for normal charges.
@@ -377,6 +384,13 @@ export interface Payment {
    */
   settlement_currency: MiscAPI.Currency;
 
+  /**
+   * Every subscription that this payment starts or charges, in a stable order. It is
+   * empty for a one-time payment. It holds the value of `subscription_id` when the
+   * payment names one subscription.
+   */
+  subscription_ids: Array<string>;
+
   /**
    * Total amount charged to the customer including tax, in the currency's smallest
    * unit (e.g. cents for USD, yen for JPY, fils for KWD — see the currency's decimal
@@ -496,7 +510,9 @@ export interface Payment {
   status?: IntentStatus | null;
 
   /**
-   * Identifier of the subscription if payment is part of a subscription
+   * Identifier of the subscription if payment is part of a subscription. A
+   * multi-subscription payment leaves this null, because no single subscription owns
+   * the payment. Read `subscription_ids` for those.
    */
   subscription_id?: string | null;
 
@@ -675,6 +691,18 @@ export interface RefundListItem {
    */
   currency?: MiscAPI.Currency | null;
 
+  /**
+   * The reference number that the card network or the bank gives to the refund. The
+   * customer can give this number to their bank to trace the refund. It is null
+   * until the payment processor sends it.
+   */
+  network_reference?: string | null;
+
+  /**
+   * The kind of `network_reference`: ARN, STAN or RRN.
+   */
+  network_reference_type?: RefundsAPI.RefundNetworkReferenceType | null;
+
   /**
    * The reason provided for the refund, if any. Optional.
    */
@@ -748,6 +776,13 @@ export interface PaymentListResponse {
 
   has_license_key: boolean;
 
+  /**
+   * True when one payment starts more than one subscription. Read this field to find
+   * the payment type. Do not read the length of `subscription_ids`. Do not read
+   * `subscription_id` for null.
+   */
+  is_multi_subscription: boolean;
+
   /**
    * Arbitrary key-value metadata. Values can be string, integer, number, or boolean.
    */
@@ -761,6 +796,13 @@ export interface PaymentListResponse {
    */
   payment_provider: 'stripe' | 'adyen' | 'dodo';
 
+  /**
+   * Every subscription that this payment starts or charges, in a stable order. It is
+   * empty for a one-time payment. It holds the value of `subscription_id` when the
+   * payment names one subscription.
+   */
+  subscription_ids: Array<string>;
+
   total_amount: number;
 
   /**

package/src/resources/payouts/breakup/breakup.ts

@@ -38,11 +38,27 @@ export type BreakupRetrieveResponse = Array<BreakupRetrieveResponse.BreakupRetri
 export namespace BreakupRetrieveResponse {
   /**
    * Payout breakup aggregated by event type, with amounts in the payout's currency.
+   *
+   * The rows sum to the payout amount. The last row can be `unattributed`, which is
+   * not a ledger event type. It holds the payout amount less the entries that fund
+   * it, and it takes either sign:
+   *
+   * - Positive: the entries come to less than the payout, so the payout drew on the
+   *   balance an earlier cycle left over. A cycle of refunds and disputes produces a
+   *   large positive value.
+   * - Negative: the entries come to more than the payout, and the remainder funds a
+   *   later payout. This is the common case, for two reasons. The walk that claims
+   *   the entries stops at the first one that reaches its target, so it passes the
+   *   target by part of an entry. The target is also the gross debit, which holds
+   *   the payout fee, and the fee is not a line here.
+   *
+   * The row is absent when the two are equal.
    */
   export interface BreakupRetrieveResponseItem {
     /**
      * The type of balance ledger event (e.g., "payment", "refund", "dispute",
-     * "payment_fees").
+     * "payment_fees"), or `unattributed` for the payout amount the entries do not
+     * account for.
      */
     event_type: string;
 

package/src/resources/payouts/breakup/details.ts

@@ -13,10 +13,10 @@ import { path } from '../../../internal/utils/path';
 
 export class Details extends APIResource {
   /**
-   * Returns paginated individual balance ledger entries for a payout, with each
-   * entry's amount pro-rated into the payout's currency. Supports pagination via
-   * `page_size` (default 10, max 100) and `page_number` (default 0) query
-   * parameters.
+   * Returns paginated individual balance ledger entries for a payout. Each entry is
+   * converted into the payout's currency at the rate the payout settled at. Supports
+   * pagination via `page_size` (default 10, max 100) and `page_number` (default 0)
+   * query parameters.
    *
    * @example
    * ```ts
@@ -64,8 +64,8 @@ export class Details extends APIResource {
 export type DetailListResponsesDefaultPageNumberPagination = DefaultPageNumberPagination<DetailListResponse>;
 
 /**
- * Individual balance ledger entry for a payout, with amounts pro-rated into the
- * payout's currency.
+ * Individual balance ledger entry for a payout, converted into the payout's
+ * currency.
  */
 export interface DetailListResponse {
   /**
@@ -97,8 +97,9 @@ export interface DetailListResponse {
 
   /**
    * Amount in the payout's currency, in that currency's smallest unit (cents for
-   * USD, yen for JPY, fils for KWD). Uses cumulative rounding to ensure sum matches
-   * payout total exactly.
+   * USD, yen for JPY, fils for KWD). The entry is converted at the rate the payout
+   * settled at. These amounts sum to the value of the entries, which can be less
+   * than the payout: the grouped breakup reports the difference as `unattributed`.
    */
   payout_currency_amount: number;
 

package/src/resources/refunds.ts

@@ -114,12 +114,34 @@ export interface Refund {
    */
   currency?: MiscAPI.Currency | null;
 
+  /**
+   * The reference number that the card network or the bank gives to the refund. The
+   * customer can give this number to their bank to trace the refund. It is null
+   * until the payment processor sends it.
+   */
+  network_reference?: string | null;
+
+  /**
+   * The kind of `network_reference`: ARN, STAN or RRN.
+   */
+  network_reference_type?: RefundNetworkReferenceType | null;
+
   /**
    * The reason provided for the refund, if any. Optional.
    */
   reason?: string | null;
 }
 
+/**
+ * The kind of reference number that the card network or the bank gives to a
+ * refund.
+ */
+export type RefundNetworkReferenceType =
+  | 'acquirer_reference_number'
+  | 'system_trace_audit_number'
+  | 'retrieval_reference_number'
+  | 'other';
+
 export type RefundStatus = 'succeeded' | 'failed' | 'pending' | 'review';
 
 export interface RefundListParams extends DefaultPageNumberPaginationParams {
@@ -193,6 +215,7 @@ export namespace RefundCreateParams {
 export declare namespace Refunds {
   export {
     type Refund as Refund,
+    type RefundNetworkReferenceType as RefundNetworkReferenceType,
     type RefundStatus as RefundStatus,
     type RefundListParams as RefundListParams,
     type RefundCreateParams as RefundCreateParams,

package/src/resources/subscriptions.ts

@@ -634,6 +634,12 @@ export interface Subscription {
    */
   cancelled_at?: string | null;
 
+  /**
+   * The caller that cancelled the subscription or scheduled its cancel. `null` when
+   * no caller is known, for example when the system cancelled the subscription.
+   */
+  cancelled_by?: SubscriptionCancelledBy | null;
+
   /**
    * Customer's responses to custom fields collected during checkout
    */
@@ -694,6 +700,28 @@ export interface Subscription {
   trial_amount?: number | null;
 }
 
+/**
+ * The caller that cancelled a subscription or scheduled its cancel.
+ */
+export interface SubscriptionCancelledBy {
+  /**
+   * The kind of caller.
+   */
+  actor_type: 'customer' | 'merchant_user' | 'api_key' | 'dodo_team';
+
+  /**
+   * Email of the customer or of the dashboard user. `null` for an API key or the
+   * Dodo Payments team.
+   */
+  email?: string | null;
+
+  /**
+   * Name of the customer or of the dashboard user. `null` for an API key or the Dodo
+   * Payments team.
+   */
+  name?: string | null;
+}
+
 export type SubscriptionStatus =
   | 'pending'
   | 'active'
@@ -1014,6 +1042,12 @@ export interface SubscriptionListResponse {
    */
   cancelled_at?: string | null;
 
+  /**
+   * The caller that cancelled the subscription or scheduled its cancel. `null` when
+   * no caller is known, for example when the system cancelled the subscription.
+   */
+  cancelled_by?: SubscriptionCancelledBy | null;
+
   /**
    * Business / legal name associated with the tax id (B2B). When set this is used on
    * the invoice in place of the customer's personal name.
@@ -1225,14 +1259,22 @@ export namespace SubscriptionPreviewChangePlanResponse {
       currency: MiscAPI.Currency;
 
       /**
-       * Net credit movement in the smallest currency unit (e.g. cents). **Negative** –
-       * credits were deducted from the customer's balance to offset the charge (typical
-       * on upgrades). **Positive** – credits were added to the customer's balance,
-       * either from a downgrade proration refund or from topping-up the wallet to meet a
-       * gateway minimum-charge threshold. **Zero** – no credit movement occurred.
+       * Net credit movement in the smallest unit of `customer_credits_currency` (e.g.
+       * cents). Read `customer_credits_currency` for the currency. It can differ from
+       * `currency`. **Negative** – credits were deducted from the customer's balance to
+       * offset the charge (typical on upgrades). **Positive** – credits were added to
+       * the customer's balance, either from a downgrade proration refund or from
+       * topping-up the wallet to meet a gateway minimum-charge threshold. **Zero** – no
+       * credit movement occurred.
        */
       customer_credits: number;
 
+      /**
+       * This field gives the currency of `customer_credits`. The credit wallet uses the
+       * subscription currency.
+       */
+      customer_credits_currency: MiscAPI.Currency;
+
       settlement_amount: number;
 
       settlement_currency: MiscAPI.Currency;
@@ -1989,6 +2031,7 @@ export declare namespace Subscriptions {
     type OnDemandSubscription as OnDemandSubscription,
     type ScheduledPlanChange as ScheduledPlanChange,
     type Subscription as Subscription,
+    type SubscriptionCancelledBy as SubscriptionCancelledBy,
     type SubscriptionStatus as SubscriptionStatus,
     type TimeInterval as TimeInterval,
     type UpdateSubscriptionPlanReq as UpdateSubscriptionPlanReq,

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '2.51.0'; // x-release-please-version
+export const VERSION = '2.53.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "2.51.0";
+export declare const VERSION = "2.53.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "2.51.0";
+export declare const VERSION = "2.53.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '2.51.0'; // x-release-please-version
+exports.VERSION = '2.53.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '2.51.0'; // x-release-please-version
+export const VERSION = '2.53.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map