feat: user should be able to appeal against flag

src/moderation.ts

@@ -1,5 +1,8 @@
 import type {
   APIResponse,
+  AppealOptions,
+  AppealResponse,
+  AppealsSort,
   CustomCheckFlag,
   GetConfigResponse,
   GetUserModerationReportOptions,
@@ -11,6 +14,9 @@ import type {
   ModerationRuleRequest,
   MuteUserResponse,
   Pager,
+  QueryAppealsFilters,
+  QueryAppealsPaginationOptions,
+  QueryAppealsResponse,
   QueryConfigsResponse,
   QueryModerationConfigsFilters,
   QueryModerationConfigsSort,
@@ -186,6 +192,56 @@ export class Moderation {
     );
   }
 
+  /**
+   * Appeal against the moderation decision
+   * @param {string} text
+   * @param {string} entityID
+   * @param {string} entityType
+   * @param {Array<string>} attachments
+   * @param {string} channelCID
+   */
+  async appeal(
+    text: string,
+    entityID: string,
+    entityType: string,
+    attachments: string[],
+    channelCID: string = '',
+    options: AppealOptions = {},
+  ) {
+    return await this.client.post<AppealResponse>(
+      this.client.baseURL + '/api/v2/moderation/appeal',
+      {
+        text,
+        entity_id: entityID,
+        entity_type: entityType,
+        attachments,
+        channel_cid: channelCID,
+        ...options,
+      },
+    );
+  }
+
+  /**
+   * Query appeals
+   * @param {Object} filterConditions Filter conditions for querying appeals
+   * @param {Object} sort Sort conditions for querying appeals
+   * @param {Object} options Pagination options for querying appeals
+   */
+  async queryAppeals(
+    filterConditions: QueryAppealsFilters = {},
+    sort: AppealsSort = [],
+    options: QueryAppealsPaginationOptions = {},
+  ) {
+    return await this.client.post<QueryAppealsResponse>(
+      this.client.baseURL + '/api/v2/moderation/appeals',
+      {
+        filter: filterConditions,
+        sort: normalizeQuerySort(sort),
+        ...options,
+      },
+    );
+  }
+
   /**
    * Upsert moderation config
    * @param {Object} config Moderation config to be upserted

src/types.ts

@@ -3538,6 +3538,20 @@ export type ModerationFlag = {
   moderation_payload_hash?: string;
 };
 
+export type AppealItem = {
+  attachments: string[];
+  created_at: string;
+  updated_at: string;
+  decision_reason: string;
+  entity_id: string;
+  entity_type: string;
+  status: string;
+  text: string;
+  channel_cid: string;
+  user: UserResponse;
+  id: string;
+};
+
 export type ReviewQueueItem = {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   actions_taken: any[];
@@ -3566,6 +3580,7 @@ export type ReviewQueueItem = {
   reviewed_at: string;
   status: string;
   updated_at: string;
+  appeal?: AppealItem;
 };
 
 export type CustomCheckFlag = {
@@ -3598,6 +3613,10 @@ export type SubmitActionOptions = {
     channel_cid?: string;
   };
   user_id?: string;
+  decide_appeal?: {
+    decision_reason: string;
+    status: 'accepted' | 'rejected';
+  };
 };
 
 export type GetUserModerationReportResponse = {
@@ -3740,13 +3759,77 @@ export type ReviewQueueFilters = QueryFilters<
     date_range?: RequireOnlyOne<{
       $eq?: string; // Format: "date1_date2"
     }>;
+  } & {
+    appeal?: boolean;
+  } & {
+    appeal_status?: RequireOnlyOne<{
+      $eq?: 'submitted' | 'accepted' | 'rejected';
+    }>;
   }
 >;
 
 export type ReviewQueueSort =
   | Sort<Pick<ReviewQueueItem, 'id' | 'created_at' | 'updated_at'>>
   | Array<Sort<Pick<ReviewQueueItem, 'id' | 'created_at' | 'updated_at'>>>;
 
+export type AppealsSort =
+  | Sort<Pick<AppealItem, 'created_at' | 'updated_at'>>
+  | Array<Sort<Pick<AppealItem, 'created_at' | 'updated_at'>>>;
+
+export type QueryAppealsFilters = QueryFilters<
+  {
+    entity_type?:
+      | RequireOnlyOne<Pick<QueryFilter<AppealItem['entity_type']>, '$eq' | '$in'>>
+      | PrimitiveFilter<AppealItem['entity_type']>;
+  } & {
+    created_at?:
+      | RequireOnlyOne<
+          Pick<
+            QueryFilter<AppealItem['created_at']>,
+            '$eq' | '$gt' | '$lt' | '$gte' | '$lte'
+          >
+        >
+      | PrimitiveFilter<AppealItem['created_at']>;
+  } & {
+    id?:
+      | RequireOnlyOne<Pick<QueryFilter<AppealItem['id']>, '$eq' | '$in'>>
+      | PrimitiveFilter<AppealItem['id']>;
+  } & {
+    entity_id?:
+      | RequireOnlyOne<Pick<QueryFilter<AppealItem['entity_id']>, '$eq' | '$in'>>
+      | PrimitiveFilter<AppealItem['entity_id']>;
+  } & {
+    status?:
+      | RequireOnlyOne<Pick<QueryFilter<AppealItem['status']>, '$eq' | '$in'>>
+      | PrimitiveFilter<AppealItem['status']>;
+  } & {
+    updated_at?:
+      | RequireOnlyOne<
+          Pick<
+            QueryFilter<AppealItem['updated_at']>,
+            '$eq' | '$gt' | '$lt' | '$gte' | '$lte'
+          >
+        >
+      | PrimitiveFilter<AppealItem['updated_at']>;
+  } & {
+    text?: RequireOnlyOne<{
+      $eq?: string;
+    }>;
+  } & {
+    channel_cid?: RequireOnlyOne<{
+      $eq?: string;
+    }>;
+  } & {
+    decision_reason?: RequireOnlyOne<{
+      $eq?: string;
+    }>;
+  } & {
+    review_queue_item_id?: RequireOnlyOne<{
+      $eq?: string;
+    }>;
+  }
+>;
+
 export type QueryModerationConfigsSort = Array<Sort<'key' | 'created_at' | 'updated_at'>>;
 
 export type ReviewQueuePaginationOptions = Pager;
@@ -3757,6 +3840,14 @@ export type ReviewQueueResponse = {
   prev?: string;
 };
 
+export type QueryAppealsResponse = APIResponse & {
+  items: AppealItem[];
+  next?: string;
+  prev?: string;
+};
+
+export type QueryAppealsPaginationOptions = Pager;
+
 export type ModerationConfig = {
   key: string;
   ai_image_config?: AIImageConfig;
@@ -3788,6 +3879,10 @@ export type UpsertConfigResponse = {
   config: ModerationConfigResponse;
 };
 
+export type AppealResponse = APIResponse & {
+  appeal_id: string;
+};
+
 // Moderation Rule Builder Types
 export type ModerationRule = {
   id: string;
@@ -3959,6 +4054,11 @@ export type ModerationFlagOptions = {
   user_id?: string;
 };
 
+export type AppealOptions = {
+  custom?: Record<string, unknown>;
+  user_id?: string;
+};
+
 export type ModerationMuteOptions = {
   timeout?: number;
   user_id?: string;