cloudflare 7.2.0 → 7.3.0

package/src/resources/email-security/investigate/bulk/messages.ts

@@ -21,7 +21,7 @@ export class BaseMessages extends APIResource {
    * ```ts
    * // Automatically fetches more pages as needed.
    * for await (const messageListResponse of client.emailSecurity.investigate.bulk.messages.list(
-   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   'f174e90a-fafe-4643-bbbc-4a0ed4fc8415',
    *   { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
    * )) {
    *   // ...
@@ -58,7 +58,10 @@ export interface MessageListResponse {
 
   retry_count: number;
 
-  status: 'PENDING' | 'DISCOVERING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'SKIPPED';
+  /**
+   * Status of a message within a bulk action job.
+   */
+  status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'SKIPPED';
 
   alert_id?: string | null;
 
@@ -80,6 +83,9 @@ export namespace MessageListResponse {
   export interface Move {
     client_recipient: string;
 
+    /**
+     * The mailbox folder to move messages to.
+     */
     destination:
       | 'Inbox'
       | 'JunkEmail'
@@ -172,6 +178,9 @@ export namespace MessageListResponse {
 
     envelope_to?: Array<string> | null;
 
+    /**
+     * The verdict Email Security assigns to a message.
+     */
     final_disposition?:
       | 'MALICIOUS'
       | 'MALICIOUS-BEC'
@@ -335,6 +344,9 @@ export namespace MessageListResponse {
 
       detail?: string | null;
 
+      /**
+       * The verdict Email Security assigns to a message.
+       */
       detection?:
         | 'MALICIOUS'
         | 'MALICIOUS-BEC'
@@ -380,9 +392,9 @@ export interface MessageListParams extends V4PagePaginationArrayParams {
   account_id: string;
 
   /**
-   * Query param
+   * Query param: Filter the job's messages by their processing status.
    */
-  status?: 'PENDING' | 'DISCOVERING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'SKIPPED';
+  status?: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'SKIPPED';
 }
 
 export declare namespace Messages {

package/src/resources/email-security/investigate/detections.ts

@@ -14,7 +14,7 @@ export class BaseDetections extends APIResource {
 
   /**
    * Returns detection details such as threat categories and sender information for
-   * non-benign messages.
+   * messages with a detection.
    *
    * @example
    * ```ts
@@ -58,6 +58,9 @@ export interface DetectionGetResponse {
 
   validation: DetectionGetResponse.Validation;
 
+  /**
+   * The verdict Email Security assigns to a message.
+   */
   final_disposition?:
     | 'MALICIOUS'
     | 'MALICIOUS-BEC'

package/src/resources/email-security/investigate/investigate.ts

@@ -67,7 +67,7 @@ export class BaseInvestigate extends APIResource {
   ] as const);
 
   /**
-   * Returns information for each email that matches the search parameter(s).
+   * Returns information for each email that matches the provided search parameters.
    *
    * @example
    * ```ts
@@ -192,6 +192,9 @@ export interface InvestigateListResponse {
 
   envelope_to?: Array<string> | null;
 
+  /**
+   * The verdict Email Security assigns to a message.
+   */
   final_disposition?:
     | 'MALICIOUS'
     | 'MALICIOUS-BEC'
@@ -355,6 +358,9 @@ export namespace InvestigateListResponse {
 
     detail?: string | null;
 
+    /**
+     * The verdict Email Security assigns to a message.
+     */
     detection?:
       | 'MALICIOUS'
       | 'MALICIOUS-BEC'
@@ -452,6 +458,9 @@ export interface InvestigateGetResponse {
 
   envelope_to?: Array<string> | null;
 
+  /**
+   * The verdict Email Security assigns to a message.
+   */
   final_disposition?:
     | 'MALICIOUS'
     | 'MALICIOUS-BEC'
@@ -615,6 +624,9 @@ export namespace InvestigateGetResponse {
 
     detail?: string | null;
 
+    /**
+     * The verdict Email Security assigns to a message.
+     */
     detection?:
       | 'MALICIOUS'
       | 'MALICIOUS-BEC'
@@ -659,12 +671,12 @@ export interface InvestigateListParams extends V4PagePaginationArrayParams {
   account_id: string;
 
   /**
-   * Query param
+   * Query param: Filter by alert ID.
    */
   alert_id?: string;
 
   /**
-   * Query param
+   * Query param: Pagination cursor from the previous response's `result_info`.
    */
   cursor?: string;
 
@@ -687,7 +699,8 @@ export interface InvestigateListParams extends V4PagePaginationArrayParams {
   detections_only?: boolean;
 
   /**
-   * Query param: Sender domains to filter by.
+   * Query param: Filter by a domain found in the email — sender domain, recipient
+   * domain, or a domain in a link.
    */
   domain?: string;
 
@@ -707,27 +720,29 @@ export interface InvestigateListParams extends V4PagePaginationArrayParams {
   message_action?: 'PREVIEW' | 'QUARANTINE_RELEASED' | 'MOVED';
 
   /**
-   * Query param
+   * Query param: Filter by the RFC 5322 Message-ID header.
    */
   message_id?: string;
 
   /**
-   * Query param
+   * Query param: Metric to aggregate the results by.
    */
   metric?: string;
 
   /**
-   * Query param: Space-delimited search term. Case-insensitive.
+   * Query param: Space-delimited term matched case-insensitively against message
+   * metadata — sender, recipient, subject, attachment names and hashes, and message
+   * ID.
    */
   query?: string;
 
   /**
-   * Query param
+   * Query param: Filter by recipient. Matches an email address or a domain.
    */
   recipient?: string;
 
   /**
-   * Query param
+   * Query param: Filter by sender. Matches an email address or a domain.
    */
   sender?: string;
 
@@ -744,7 +759,8 @@ export interface InvestigateListParams extends V4PagePaginationArrayParams {
   start?: string;
 
   /**
-   * Query param
+   * Query param: Search for messages containing individual keywords in any order
+   * within the subject.
    */
   subject?: string;
 }

package/src/resources/email-security/investigate/move.ts

@@ -45,9 +45,10 @@ export class BaseMove extends APIResource {
   }
 
   /**
-   * Moves multiple messages to a specified mailbox folder (Inbox, JunkEmail,
+   * Moves one or more messages to a specified mailbox folder (Inbox, JunkEmail,
    * DeletedItems, RecoverableItemsDeletions, or RecoverableItemsPurges). Requires
-   * active integration.
+   * active integration. Operates on an explicit list of messages; to move all
+   * messages matching a search, create a bulk action job instead.
    *
    * @example
    * ```ts
@@ -56,6 +57,7 @@ export class BaseMove extends APIResource {
    *   {
    *     account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    *     destination: 'Inbox',
+   *     ids: ['4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678'],
    *   },
    * )) {
    *   // ...
@@ -181,7 +183,7 @@ export interface MoveCreateParams {
   account_id: string;
 
   /**
-   * Body param
+   * Body param: The mailbox folder to move messages to.
    */
   destination:
     | 'Inbox'
@@ -214,7 +216,7 @@ export interface MoveBulkParams {
   account_id: string;
 
   /**
-   * Body param
+   * Body param: The mailbox folder to move messages to.
    */
   destination:
     | 'Inbox'
@@ -223,6 +225,11 @@ export interface MoveBulkParams {
     | 'RecoverableItemsDeletions'
     | 'RecoverableItemsPurges';
 
+  /**
+   * Body param: List of message IDs to move.
+   */
+  ids: Array<string>;
+
   /**
    * @deprecated This field is nonfunctional.
    */
@@ -239,11 +246,6 @@ export interface MoveBulkParams {
     | 'NONE'
     | null;
 
-  /**
-   * Body param: List of message IDs to move.
-   */
-  ids?: Array<string>;
-
   /**
    * @deprecated Use `ids` instead.
    */

package/src/resources/email-security/investigate/preview.ts

@@ -13,16 +13,18 @@ export class BasePreview extends APIResource {
   ] as const);
 
   /**
-   * Generates a preview image for a message that was not flagged as a detection.
-   * Useful for investigating benign messages. Returns a base64-encoded PNG
-   * screenshot of the email body.
+   * Generates a preview image for a message that was not flagged as a detection. The
+   * message is rendered from the copy in the recipient's mailbox, so this requires
+   * an active integration and only works while the message is still in the
+   * recipient's inbox. Returns a base64-encoded PNG screenshot of the email body.
+   * For messages with a detection, use the detection preview endpoint instead.
    *
    * @example
    * ```ts
    * const preview =
    *   await client.emailSecurity.investigate.preview.create({
    *     account_id: '023e105f4ecef8ad9ca31a8372d0c353',
-   *     postfix_id: '4Njp3P0STMz2c02Q',
+   *     id: '4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678',
    *   });
    * ```
    */
@@ -37,8 +39,9 @@ export class BasePreview extends APIResource {
   }
 
   /**
-   * Returns a preview of the message body as a base64 encoded PNG image for
-   * non-benign messages.
+   * Returns a preview of the message body as a base64-encoded PNG image for any
+   * message with a detection. For messages without a detection, use the
+   * non-detection preview endpoint instead.
    *
    * @example
    * ```ts
@@ -86,9 +89,9 @@ export interface PreviewCreateParams {
   account_id: string;
 
   /**
-   * Body param: The identifier of the message.
+   * Body param: Unique identifier for a message retrieved from investigation.
    */
-  postfix_id: string;
+  id: string;
 }
 
 export interface PreviewGetParams {

package/src/resources/email-security/investigate/raw.ts

@@ -13,7 +13,7 @@ export class BaseRaw extends APIResource {
   ] as const);
 
   /**
-   * Returns the raw eml of any non-benign message.
+   * Returns the raw EML content of any message with a detection.
    *
    * @example
    * ```ts

package/src/resources/email-security/investigate/reclassify.ts

@@ -15,19 +15,10 @@ export class BaseReclassify extends APIResource {
   /**
    * Submits a request to reclassify an email's disposition. Use for reporting false
    * positives or false negatives. Optionally provide the raw EML content for
-   * reanalysis. The reclassification is processed asynchronously.
+   * reanalysis. The reclassification is processed asynchronously. Deprecated; use
+   * the create submissions endpoint instead.
    *
-   * @example
-   * ```ts
-   * const reclassify =
-   *   await client.emailSecurity.investigate.reclassify.create(
-   *     '4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678',
-   *     {
-   *       account_id: '023e105f4ecef8ad9ca31a8372d0c353',
-   *       expected_disposition: 'NONE',
-   *     },
-   *   );
-   * ```
+   * @deprecated
    */
   create(
     investigateID: string,
@@ -54,7 +45,7 @@ export interface ReclassifyCreateParams {
   account_id: string;
 
   /**
-   * Body param
+   * Body param: The disposition the message should have.
    */
   expected_disposition: 'NONE' | 'BULK' | 'MALICIOUS' | 'SPAM' | 'SPOOF' | 'SUSPICIOUS';
 
@@ -64,7 +55,8 @@ export interface ReclassifyCreateParams {
   eml_content?: string;
 
   /**
-   * Body param
+   * Body param: Submission ID of the original user submission, when reclassifying an
+   * escalated user report.
    */
   escalated_submission_id?: string;
 }

package/src/resources/email-security/investigate/release.ts

@@ -14,8 +14,9 @@ export class BaseRelease extends APIResource {
 
   /**
    * Delivers one or more quarantined messages to their intended recipients, for
-   * cases where a message was incorrectly quarantined. The response includes
-   * delivery status for each recipient.
+   * cases where a message was incorrectly quarantined. Operates on an explicit list
+   * of messages; to release all messages matching a search, create a bulk action job
+   * instead. The response includes delivery status for each recipient.
    *
    * @example
    * ```ts
@@ -23,7 +24,7 @@ export class BaseRelease extends APIResource {
    * for await (const releaseBulkResponse of client.emailSecurity.investigate.release.bulk(
    *   {
    *     account_id: '023e105f4ecef8ad9ca31a8372d0c353',
-   *     body: ['4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678'],
+   *     ids: ['4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678'],
    *   },
    * )) {
    *   // ...
@@ -34,11 +35,11 @@ export class BaseRelease extends APIResource {
     params: ReleaseBulkParams,
     options?: RequestOptions,
   ): PagePromise<ReleaseBulkResponsesSinglePage, ReleaseBulkResponse> {
-    const { account_id, body } = params;
+    const { account_id, ...body } = params;
     return this._client.getAPIList(
       path`/accounts/${account_id}/email-security/investigate/release`,
       SinglePage<ReleaseBulkResponse>,
-      { body: body, method: 'post', ...options },
+      { body, method: 'post', ...options },
     );
   }
 }
@@ -71,9 +72,9 @@ export interface ReleaseBulkParams {
   account_id: string;
 
   /**
-   * Body param
+   * Body param: Investigate IDs of the messages to release.
    */
-  body: Array<string>;
+  ids: Array<string>;
 }
 
 export declare namespace Release {

package/src/resources/email-security/phishguard/index.ts

@@ -6,5 +6,5 @@ export {
   BaseReports,
   type ReportListResponse,
   type ReportListParams,
-  type ReportListResponsesSinglePage,
+  type ReportListResponsesV4PagePaginationArray,
 } from './reports';

package/src/resources/email-security/phishguard/phishguard.ts

@@ -6,7 +6,7 @@ import {
   BaseReports,
   ReportListParams,
   ReportListResponse,
-  ReportListResponsesSinglePage,
+  ReportListResponsesV4PagePaginationArray,
   Reports,
 } from './reports';
 
@@ -28,7 +28,7 @@ export declare namespace Phishguard {
     Reports as Reports,
     BaseReports as BaseReports,
     type ReportListResponse as ReportListResponse,
-    type ReportListResponsesSinglePage as ReportListResponsesSinglePage,
+    type ReportListResponsesV4PagePaginationArray as ReportListResponsesV4PagePaginationArray,
     type ReportListParams as ReportListParams,
   };
 }

package/src/resources/email-security/phishguard/reports.ts

@@ -1,7 +1,11 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../../core/resource';
-import { PagePromise, SinglePage } from '../../../core/pagination';
+import {
+  PagePromise,
+  V4PagePaginationArray,
+  type V4PagePaginationArrayParams,
+} from '../../../core/pagination';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
@@ -30,24 +34,27 @@ export class BaseReports extends APIResource {
   list(
     params: ReportListParams,
     options?: RequestOptions,
-  ): PagePromise<ReportListResponsesSinglePage, ReportListResponse> {
+  ): PagePromise<ReportListResponsesV4PagePaginationArray, ReportListResponse> {
     const { account_id, ...query } = params;
     return this._client.getAPIList(
       path`/accounts/${account_id}/email-security/phishguard/reports`,
-      SinglePage<ReportListResponse>,
+      V4PagePaginationArray<ReportListResponse>,
       { query, ...options },
     );
   }
 }
 export class Reports extends BaseReports {}
 
-export type ReportListResponsesSinglePage = SinglePage<ReportListResponse>;
+export type ReportListResponsesV4PagePaginationArray = V4PagePaginationArray<ReportListResponse>;
 
 export interface ReportListResponse {
   id: number;
 
   content: string;
 
+  /**
+   * The verdict Email Security assigns to a message.
+   */
   disposition:
     | 'MALICIOUS'
     | 'MALICIOUS-BEC'
@@ -101,7 +108,7 @@ export namespace ReportListResponse {
   }
 }
 
-export interface ReportListParams {
+export interface ReportListParams extends V4PagePaginationArrayParams {
   /**
    * Path param: Account identifier tag.
    */
@@ -131,7 +138,7 @@ export interface ReportListParams {
 export declare namespace Reports {
   export {
     type ReportListResponse as ReportListResponse,
-    type ReportListResponsesSinglePage as ReportListResponsesSinglePage,
+    type ReportListResponsesV4PagePaginationArray as ReportListResponsesV4PagePaginationArray,
     type ReportListParams as ReportListParams,
   };
 }

package/src/resources/email-security/settings/allow-policies.ts

@@ -102,9 +102,10 @@ export class BaseAllowPolicies extends APIResource {
   }
 
   /**
-   * Executes multiple operations atomically. All four operation arrays (deletes,
-   * patches, puts, posts) are required and executed in order. Send empty arrays for
-   * unused operations.
+   * Executes multiple allow policy operations atomically: delete, partially update,
+   * replace, and create allow policies in a single request. All four operation
+   * arrays (deletes, patches, puts, posts) are required and executed in order. Send
+   * empty arrays for unused operations.
    *
    * @example
    * ```ts
@@ -935,22 +936,12 @@ export interface AllowPolicyListParams extends V4PagePaginationArrayParams {
   order?: 'pattern' | 'created_at';
 
   /**
-   * Query param
+   * Query param: Filter by exact pattern value.
    */
   pattern?: string;
 
   /**
-   * Query param: Type of pattern matching.
-   *
-   * - EMAIL: matches a full email address (e.g. `user@example.com`)
-   * - DOMAIN: matches a domain name (e.g. `example.com`)
-   * - IP: matches a plain IPv4 or IPv6 address (e.g. `1.2.3.4` or
-   *   `2606:4700:4700::1111`) or CIDR block (e.g. `1.2.3.0/24` or
-   *   `2606:4700:4700::/48`). The API rejects private or unique-local, loopback,
-   *   link-local, unspecified, and IPv4 broadcast addresses, including their
-   *   IPv4-mapped IPv6 equivalents.
-   * - UNKNOWN: deprecated; you cannot use this when creating or updating policies,
-   *   but it may appear on existing entries.
+   * Query param: Filter by pattern type.
    */
   pattern_type?: 'EMAIL' | 'DOMAIN' | 'IP' | 'UNKNOWN';
 
@@ -980,22 +971,24 @@ export interface AllowPolicyBatchParams {
   account_id: string;
 
   /**
-   * Body param
+   * Body param: IDs of the allow policies to delete.
    */
   deletes: Array<AllowPolicyBatchParams.Delete>;
 
   /**
-   * Body param
+   * Body param: Partial updates to apply — each entry carries the policy's ID and
+   * only the fields to change.
    */
   patches: Array<AllowPolicyBatchParams.Patch>;
 
   /**
-   * Body param
+   * Body param: Allow policies to create.
    */
   posts: Array<AllowPolicyBatchParams.Post>;
 
   /**
-   * Body param
+   * Body param: Full replacements to apply — each entry carries the policy's ID and
+   * every field of its new value.
    */
   puts: Array<AllowPolicyBatchParams.Put>;
 }