cloudflare 6.0.0 → 6.2.0

package/src/resources/security-center/insights/audit-logs.ts

@@ -0,0 +1,313 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../resource';
+import { isRequestOptions } from '../../../core';
+import * as Core from '../../../core';
+import { CloudflareError } from '../../../error';
+import { CursorPagination, type CursorPaginationParams } from '../../../pagination';
+
+export class AuditLogs extends APIResource {
+  /**
+   * Lists audit log entries for all Security Center insights in the account or zone,
+   * showing changes to insight status and classification.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const auditLogListResponse of client.securityCenter.insights.auditLogs.list(
+   *   { account_id: 'account_id' },
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    params?: AuditLogListParams,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<AuditLogListResponsesCursorPagination, AuditLogListResponse>;
+  list(
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<AuditLogListResponsesCursorPagination, AuditLogListResponse>;
+  list(
+    params: AuditLogListParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<AuditLogListResponsesCursorPagination, AuditLogListResponse> {
+    if (isRequestOptions(params)) {
+      return this.list({}, params);
+    }
+    const { account_id, zone_id, ...query } = params;
+    if (!account_id && !zone_id) {
+      throw new CloudflareError('You must provide either account_id or zone_id.');
+    }
+    if (account_id && zone_id) {
+      throw new CloudflareError('You cannot provide both account_id and zone_id.');
+    }
+    const { accountOrZone, accountOrZoneId } =
+      account_id ?
+        {
+          accountOrZone: 'accounts',
+          accountOrZoneId: account_id,
+        }
+      : {
+          accountOrZone: 'zones',
+          accountOrZoneId: zone_id,
+        };
+    return this._client.getAPIList(
+      `/${accountOrZone}/${accountOrZoneId}/security-center/insights/audit-log`,
+      AuditLogListResponsesCursorPagination,
+      { query, ...options },
+    );
+  }
+
+  /**
+   * Lists audit log entries for a specific Security Center insight, showing changes
+   * to its status and classification over time.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const auditLogListByInsightResponse of client.securityCenter.insights.auditLogs.listByInsight(
+   *   'issue_id',
+   *   { account_id: 'account_id' },
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  listByInsight(
+    issueId: string,
+    params?: AuditLogListByInsightParams,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<AuditLogListByInsightResponsesCursorPagination, AuditLogListByInsightResponse>;
+  listByInsight(
+    issueId: string,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<AuditLogListByInsightResponsesCursorPagination, AuditLogListByInsightResponse>;
+  listByInsight(
+    issueId: string,
+    params: AuditLogListByInsightParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<AuditLogListByInsightResponsesCursorPagination, AuditLogListByInsightResponse> {
+    if (isRequestOptions(params)) {
+      return this.listByInsight(issueId, {}, params);
+    }
+    const { account_id, zone_id, ...query } = params;
+    if (!account_id && !zone_id) {
+      throw new CloudflareError('You must provide either account_id or zone_id.');
+    }
+    if (account_id && zone_id) {
+      throw new CloudflareError('You cannot provide both account_id and zone_id.');
+    }
+    const { accountOrZone, accountOrZoneId } =
+      account_id ?
+        {
+          accountOrZone: 'accounts',
+          accountOrZoneId: account_id,
+        }
+      : {
+          accountOrZone: 'zones',
+          accountOrZoneId: zone_id,
+        };
+    return this._client.getAPIList(
+      `/${accountOrZone}/${accountOrZoneId}/security-center/insights/${issueId}/audit-log`,
+      AuditLogListByInsightResponsesCursorPagination,
+      { query, ...options },
+    );
+  }
+}
+
+export class AuditLogListResponsesCursorPagination extends CursorPagination<AuditLogListResponse> {}
+
+export class AuditLogListByInsightResponsesCursorPagination extends CursorPagination<AuditLogListByInsightResponse> {}
+
+export interface AuditLogListResponse {
+  /**
+   * UUIDv7 identifier for the audit log entry, time-ordered.
+   */
+  id?: string;
+
+  /**
+   * The timestamp when the change occurred.
+   */
+  changed_at?: string;
+
+  /**
+   * The actor that made the change. 'system' for automated changes, or a user
+   * identifier.
+   */
+  changed_by?: string;
+
+  /**
+   * The value of the field after the change. Null if the field was cleared.
+   */
+  current_value?: string | null;
+
+  /**
+   * The field that was changed.
+   */
+  field_changed?: 'status' | 'user_classification';
+
+  /**
+   * The ID of the insight this audit log entry relates to.
+   */
+  issue_id?: string;
+
+  /**
+   * The value of the field before the change. Null if the field was not previously
+   * set.
+   */
+  previous_value?: string | null;
+
+  /**
+   * Optional rationale provided for the change.
+   */
+  rationale?: string | null;
+
+  /**
+   * The zone ID associated with the insight. Only present for zone-level insights.
+   */
+  zone_id?: number;
+}
+
+export interface AuditLogListByInsightResponse {
+  /**
+   * UUIDv7 identifier for the audit log entry, time-ordered.
+   */
+  id?: string;
+
+  /**
+   * The timestamp when the change occurred.
+   */
+  changed_at?: string;
+
+  /**
+   * The actor that made the change. 'system' for automated changes, or a user
+   * identifier.
+   */
+  changed_by?: string;
+
+  /**
+   * The value of the field after the change. Null if the field was cleared.
+   */
+  current_value?: string | null;
+
+  /**
+   * The field that was changed.
+   */
+  field_changed?: 'status' | 'user_classification';
+
+  /**
+   * The ID of the insight this audit log entry relates to.
+   */
+  issue_id?: string;
+
+  /**
+   * The value of the field before the change. Null if the field was not previously
+   * set.
+   */
+  previous_value?: string | null;
+
+  /**
+   * Optional rationale provided for the change.
+   */
+  rationale?: string | null;
+
+  /**
+   * The zone ID associated with the insight. Only present for zone-level insights.
+   */
+  zone_id?: number;
+}
+
+export interface AuditLogListParams extends CursorPaginationParams {
+  /**
+   * Path param: The Account ID to use for this endpoint. Mutually exclusive with the
+   * Zone ID.
+   */
+  account_id?: string;
+
+  /**
+   * Path param: The Zone ID to use for this endpoint. Mutually exclusive with the
+   * Account ID.
+   */
+  zone_id?: string;
+
+  /**
+   * Query param: Filter entries changed before this timestamp (RFC 3339).
+   */
+  before?: string;
+
+  /**
+   * Query param: Filter by the actor that made the change.
+   */
+  changed_by?: string;
+
+  /**
+   * Query param: Filter by the field that was changed.
+   */
+  field_changed?: 'status' | 'user_classification';
+
+  /**
+   * Query param: Sort order for results. Use 'asc' for oldest first or 'desc' for
+   * newest first.
+   */
+  order?: 'asc' | 'desc';
+
+  /**
+   * Query param: Filter entries changed at or after this timestamp (RFC 3339).
+   */
+  since?: string;
+}
+
+export interface AuditLogListByInsightParams extends CursorPaginationParams {
+  /**
+   * Path param: The Account ID to use for this endpoint. Mutually exclusive with the
+   * Zone ID.
+   */
+  account_id?: string;
+
+  /**
+   * Path param: The Zone ID to use for this endpoint. Mutually exclusive with the
+   * Account ID.
+   */
+  zone_id?: string;
+
+  /**
+   * Query param: Filter entries changed before this timestamp (RFC 3339).
+   */
+  before?: string;
+
+  /**
+   * Query param: Filter by the actor that made the change.
+   */
+  changed_by?: string;
+
+  /**
+   * Query param: Filter by the field that was changed.
+   */
+  field_changed?: 'status' | 'user_classification';
+
+  /**
+   * Query param: Sort order for results. Use 'asc' for oldest first or 'desc' for
+   * newest first.
+   */
+  order?: 'asc' | 'desc';
+
+  /**
+   * Query param: Filter entries changed at or after this timestamp (RFC 3339).
+   */
+  since?: string;
+}
+
+AuditLogs.AuditLogListResponsesCursorPagination = AuditLogListResponsesCursorPagination;
+AuditLogs.AuditLogListByInsightResponsesCursorPagination = AuditLogListByInsightResponsesCursorPagination;
+
+export declare namespace AuditLogs {
+  export {
+    type AuditLogListResponse as AuditLogListResponse,
+    type AuditLogListByInsightResponse as AuditLogListByInsightResponse,
+    AuditLogListResponsesCursorPagination as AuditLogListResponsesCursorPagination,
+    AuditLogListByInsightResponsesCursorPagination as AuditLogListByInsightResponsesCursorPagination,
+    type AuditLogListParams as AuditLogListParams,
+    type AuditLogListByInsightParams as AuditLogListByInsightParams,
+  };
+}

package/src/resources/security-center/insights/class.ts

@@ -9,6 +9,14 @@ import { CloudflareError } from '../../../error';
 export class Class extends APIResource {
   /**
    * Retrieves Security Center insight counts aggregated by classification class.
+   *
+   * @example
+   * ```ts
+   * const classes =
+   *   await client.securityCenter.insights.class.get({
+   *     account_id: 'account_id',
+   *   });
+   * ```
    */
   get(params?: ClassGetParams, options?: Core.RequestOptions): Core.APIPromise<ClassGetResponse>;
   get(options?: Core.RequestOptions): Core.APIPromise<ClassGetResponse>;

package/src/resources/security-center/insights/classification.ts

@@ -0,0 +1,127 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../resource';
+import * as Core from '../../../core';
+import { CloudflareError } from '../../../error';
+
+export class Classification extends APIResource {
+  /**
+   * Updates the user classification for a Security Center insight. Valid values are
+   * 'false_positive' or 'accept_risk'. To reset, set classification to null. Cannot
+   * change directly between classification values - must reset to null first.
+   *
+   * @example
+   * ```ts
+   * const classification =
+   *   await client.securityCenter.insights.classification.update(
+   *     'issue_id',
+   *     { account_id: 'account_id' },
+   *   );
+   * ```
+   */
+  update(
+    issueId: string,
+    params: ClassificationUpdateParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<ClassificationUpdateResponse> {
+    const { account_id, zone_id, ...body } = params;
+    if (!account_id && !zone_id) {
+      throw new CloudflareError('You must provide either account_id or zone_id.');
+    }
+    if (account_id && zone_id) {
+      throw new CloudflareError('You cannot provide both account_id and zone_id.');
+    }
+    const { accountOrZone, accountOrZoneId } =
+      account_id ?
+        {
+          accountOrZone: 'accounts',
+          accountOrZoneId: account_id,
+        }
+      : {
+          accountOrZone: 'zones',
+          accountOrZoneId: zone_id,
+        };
+    return this._client.patch(
+      `/${accountOrZone}/${accountOrZoneId}/security-center/insights/${issueId}/classification`,
+      { body, ...options },
+    );
+  }
+}
+
+export interface ClassificationUpdateResponse {
+  errors: Array<ClassificationUpdateResponse.Error>;
+
+  messages: Array<ClassificationUpdateResponse.Message>;
+
+  /**
+   * Whether the API call was successful.
+   */
+  success: true;
+}
+
+export namespace ClassificationUpdateResponse {
+  export interface Error {
+    code: number;
+
+    message: string;
+
+    documentation_url?: string;
+
+    source?: Error.Source;
+  }
+
+  export namespace Error {
+    export interface Source {
+      pointer?: string;
+    }
+  }
+
+  export interface Message {
+    code: number;
+
+    message: string;
+
+    documentation_url?: string;
+
+    source?: Message.Source;
+  }
+
+  export namespace Message {
+    export interface Source {
+      pointer?: string;
+    }
+  }
+}
+
+export interface ClassificationUpdateParams {
+  /**
+   * Path param: The Account ID to use for this endpoint. Mutually exclusive with the
+   * Zone ID.
+   */
+  account_id?: string;
+
+  /**
+   * Path param: The Zone ID to use for this endpoint. Mutually exclusive with the
+   * Account ID.
+   */
+  zone_id?: string;
+
+  /**
+   * Body param: User-defined classification for the insight. Can be
+   * 'false_positive', 'accept_risk', 'other', or null.
+   */
+  classification?: 'false_positive' | 'accept_risk' | 'other' | null;
+
+  /**
+   * Body param: Rationale for the classification change. Required when
+   * classification is 'accept_risk' or 'other'.
+   */
+  rationale?: string;
+}
+
+export declare namespace Classification {
+  export {
+    type ClassificationUpdateResponse as ClassificationUpdateResponse,
+    type ClassificationUpdateParams as ClassificationUpdateParams,
+  };
+}

package/src/resources/security-center/insights/context.ts

@@ -0,0 +1,46 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../resource';
+import * as Core from '../../../core';
+
+export class Context extends APIResource {
+  /**
+   * Returns the full context payload for an insight. This endpoint is used for
+   * insights with large payloads that are not included inline in the list response.
+   *
+   * @example
+   * ```ts
+   * const context =
+   *   await client.securityCenter.insights.context.get(
+   *     'issue_id',
+   *     { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
+   *   );
+   * ```
+   */
+  get(
+    issueId: string,
+    params: ContextGetParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<ContextGetResponse> {
+    const { account_id } = params;
+    return (
+      this._client.get(
+        `/accounts/${account_id}/security-center/insights/${issueId}/context`,
+        options,
+      ) as Core.APIPromise<{ result: ContextGetResponse }>
+    )._thenUnwrap((obj) => obj.result);
+  }
+}
+
+export type ContextGetResponse = { [key: string]: unknown };
+
+export interface ContextGetParams {
+  /**
+   * Identifier.
+   */
+  account_id: string;
+}
+
+export declare namespace Context {
+  export { type ContextGetResponse as ContextGetResponse, type ContextGetParams as ContextGetParams };
+}

package/src/resources/security-center/insights/index.ts

@@ -1,6 +1,21 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export {
+  AuditLogListResponsesCursorPagination,
+  AuditLogListByInsightResponsesCursorPagination,
+  AuditLogs,
+  type AuditLogListResponse,
+  type AuditLogListByInsightResponse,
+  type AuditLogListParams,
+  type AuditLogListByInsightParams,
+} from './audit-logs';
 export { Class, type ClassGetResponse, type ClassGetParams } from './class';
+export {
+  Classification,
+  type ClassificationUpdateResponse,
+  type ClassificationUpdateParams,
+} from './classification';
+export { Context, type ContextGetResponse, type ContextGetParams } from './context';
 export {
   InsightListResponsesV4PagePagination,
   Insights,

package/src/resources/security-center/insights/insights.ts

@@ -4,8 +4,22 @@ import { APIResource } from '../../../resource';
 import { isRequestOptions } from '../../../core';
 import * as Core from '../../../core';
 import * as IssuesAPI from '../../intel/attack-surface-report/issues';
+import * as AuditLogsAPI from './audit-logs';
+import {
+  AuditLogListByInsightParams,
+  AuditLogListByInsightResponse,
+  AuditLogListByInsightResponsesCursorPagination,
+  AuditLogListParams,
+  AuditLogListResponse,
+  AuditLogListResponsesCursorPagination,
+  AuditLogs,
+} from './audit-logs';
 import * as ClassAPI from './class';
 import { Class, ClassGetParams, ClassGetResponse } from './class';
+import * as ClassificationAPI from './classification';
+import { Classification, ClassificationUpdateParams, ClassificationUpdateResponse } from './classification';
+import * as ContextAPI from './context';
+import { Context, ContextGetParams, ContextGetResponse } from './context';
 import * as SeverityAPI from './severity';
 import { Severity, SeverityGetParams, SeverityGetResponse } from './severity';
 import * as TypeAPI from './type';
@@ -17,10 +31,23 @@ export class Insights extends APIResource {
   class: ClassAPI.Class = new ClassAPI.Class(this._client);
   severity: SeverityAPI.Severity = new SeverityAPI.Severity(this._client);
   type: TypeAPI.Type = new TypeAPI.Type(this._client);
+  auditLogs: AuditLogsAPI.AuditLogs = new AuditLogsAPI.AuditLogs(this._client);
+  classification: ClassificationAPI.Classification = new ClassificationAPI.Classification(this._client);
+  context: ContextAPI.Context = new ContextAPI.Context(this._client);
 
   /**
    * Lists all Security Center insights for the account or zone, showing security
    * findings and recommendations.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const insightListResponse of client.securityCenter.insights.list(
+   *   { account_id: 'account_id' },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     params?: InsightListParams,
@@ -63,6 +90,14 @@ export class Insights extends APIResource {
   /**
    * Archives a Security Center insight for an account or zone, removing it from the
    * active insights list while preserving historical data.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.securityCenter.insights.dismiss('issue_id', {
+   *     account_id: 'account_id',
+   *   });
+   * ```
    */
   dismiss(
     issueId: string,
@@ -305,6 +340,11 @@ Insights.InsightListResponsesV4PagePagination = InsightListResponsesV4PagePagina
 Insights.Class = Class;
 Insights.Severity = Severity;
 Insights.Type = Type;
+Insights.AuditLogs = AuditLogs;
+Insights.AuditLogListResponsesCursorPagination = AuditLogListResponsesCursorPagination;
+Insights.AuditLogListByInsightResponsesCursorPagination = AuditLogListByInsightResponsesCursorPagination;
+Insights.Classification = Classification;
+Insights.Context = Context;
 
 export declare namespace Insights {
   export {
@@ -324,4 +364,26 @@ export declare namespace Insights {
   };
 
   export { Type as Type, type TypeGetResponse as TypeGetResponse, type TypeGetParams as TypeGetParams };
+
+  export {
+    AuditLogs as AuditLogs,
+    type AuditLogListResponse as AuditLogListResponse,
+    type AuditLogListByInsightResponse as AuditLogListByInsightResponse,
+    AuditLogListResponsesCursorPagination as AuditLogListResponsesCursorPagination,
+    AuditLogListByInsightResponsesCursorPagination as AuditLogListByInsightResponsesCursorPagination,
+    type AuditLogListParams as AuditLogListParams,
+    type AuditLogListByInsightParams as AuditLogListByInsightParams,
+  };
+
+  export {
+    Classification as Classification,
+    type ClassificationUpdateResponse as ClassificationUpdateResponse,
+    type ClassificationUpdateParams as ClassificationUpdateParams,
+  };
+
+  export {
+    Context as Context,
+    type ContextGetResponse as ContextGetResponse,
+    type ContextGetParams as ContextGetParams,
+  };
 }

package/src/resources/security-center/insights/severity.ts

@@ -10,6 +10,14 @@ export class Severity extends APIResource {
   /**
    * Retrieves Security Center insight counts aggregated by severity level (critical,
    * high, medium, low).
+   *
+   * @example
+   * ```ts
+   * const severities =
+   *   await client.securityCenter.insights.severity.get({
+   *     account_id: 'account_id',
+   *   });
+   * ```
    */
   get(params?: SeverityGetParams, options?: Core.RequestOptions): Core.APIPromise<SeverityGetResponse>;
   get(options?: Core.RequestOptions): Core.APIPromise<SeverityGetResponse>;

package/src/resources/security-center/insights/type.ts

@@ -9,6 +9,13 @@ import { CloudflareError } from '../../../error';
 export class Type extends APIResource {
   /**
    * Retrieves Security Center insight counts aggregated by insight type.
+   *
+   * @example
+   * ```ts
+   * const types = await client.securityCenter.insights.type.get(
+   *   { account_id: 'account_id' },
+   * );
+   * ```
    */
   get(params?: TypeGetParams, options?: Core.RequestOptions): Core.APIPromise<TypeGetResponse>;
   get(options?: Core.RequestOptions): Core.APIPromise<TypeGetResponse>;