feat: revamp retry classification and switch to @mondaydotcomorg/api …

.gitignore

@@ -50,3 +50,4 @@ docker-compose.override.yml
 .cypress/
 playwright-report/
 test-output/
+.claude/*

package.json

@@ -44,10 +44,10 @@
     "@aws-sdk/client-s3": "^3.879.0",
     "@aws-sdk/client-sqs": "^3.864.0",
     "@aws-sdk/lib-storage": "^3.879.0",
+    "@mondaydotcomorg/api": "^14.0.0",
     "aws-sdk": "^2.1692.0",
     "axios": "^1.11.0",
     "http-status-codes": "^2.3.0",
-    "monday-sdk-js": "^0.5.6",
     "sqs-consumer": "^12.0.0",
     "uuid": "^11.1.0"
   },

src/constants/monday-error-codes.ts

@@ -0,0 +1,33 @@
+import { StatusCodes } from "http-status-codes";
+
+export enum MondayErrorCodes {
+  COMPLEXITY_BUDGET_EXHAUSTED = "COMPLEXITY_BUDGET_EXHAUSTED",
+  MAX_CONCURRENCY_EXCEEDED = "MAX_CONCURRENCY_EXCEEDED",
+}
+
+export const TERMINAL_MONDAY_ERROR_CODES: ReadonlySet<string> = new Set([
+  "ColumnValueException",
+  "CorrectedValueException",
+  "CreateBoardException",
+  "InvalidArgumentException",
+  "InvalidBoardIdException",
+  "InvalidColumnIdException",
+  "InvalidUserIdException",
+  "InvalidVersionException",
+  "ItemNameTooLongException",
+  "ItemsLimitationException",
+  "missingRequiredPermissions",
+  "ResourceNotFoundException",
+  "JsonParseException",
+  "Unauthorized",
+  "UserUnauthorizedException",
+  "USER_ACCESS_DENIED",
+  "DeleteLastGroupException",
+  "RecordInvalidException",
+  "INVALID_QUERY",
+]);
+
+export const RETRYABLE_HTTP_STATUS_CODES: ReadonlySet<number> = new Set([
+  StatusCodes.LOCKED,
+  StatusCodes.TOO_MANY_REQUESTS,
+]);

src/index.ts

@@ -59,7 +59,7 @@ export type {
   MondayApiResponse,
 } from "./types/monday-types";
 
-export { MondayErrorCodes } from "./types/monday-types";
+export { MondayErrorCodes } from "./constants/monday-error-codes";
 
 export type {
   ApiProcessorConfig,

src/producers/sqs/sqs-producer.ts

@@ -7,11 +7,12 @@ import {
 } from "../../types/queue-types";
 import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";
 
-// SQS SendMessage allows DelaySeconds in the range [0, 900].
 const SQS_MIN_DELAY_SECONDS = 0;
 const SQS_MAX_DELAY_SECONDS = 900;
 
-function clampDelaySeconds(delay: number | undefined): number | undefined {
+export function clampDelaySeconds(
+  delay: number | undefined,
+): number | undefined {
   if (delay !== undefined) {
     return Math.min(
       Math.max(delay, SQS_MIN_DELAY_SECONDS),

src/queue-processors/api-request/api-request-queue-processor.ts

@@ -10,7 +10,8 @@ import { JobError } from "../../errors/job-error";
 import {
   buildErrorContext,
   calculateBackoffDelay,
-  hasRetryableError,
+  getRetryAfterSeconds,
+  isRetryableMondayError,
 } from "../../utils/retry-utils";
 
 export class ApiRequestQueueProcessor extends BaseQueueProcessor<
@@ -33,24 +34,16 @@ export class ApiRequestQueueProcessor extends BaseQueueProcessor<
   }
 
   private getRetryAfterValue(error: MondayError, attempts: number): number {
-    const mondayErrors = error.mondayErrors || [];
-    const mondayErrorExtension = mondayErrors.find(hasRetryableError);
-    if (
-      mondayErrorExtension &&
-      mondayErrorExtension.extensions &&
-      mondayErrorExtension.extensions.retry_in_seconds
-    ) {
-      return mondayErrorExtension.extensions.retry_in_seconds;
-    }
-    return calculateBackoffDelay(attempts);
+    return (
+      getRetryAfterSeconds(error.mondayErrors) ??
+      calculateBackoffDelay(attempts)
+    );
   }
 
   private shouldRetryApiCall(error: unknown): boolean {
     if (error instanceof MondayError) {
       const mondayErrors = error.mondayErrors || [];
-      return mondayErrors.some((error) => {
-        return hasRetryableError(error);
-      });
+      return mondayErrors.some(isRetryableMondayError);
     }
     // unknown error, assume retryable
     return true;

src/tasks/call-monday-api-task/monday-client-call-monday-api-task.ts

@@ -1,15 +1,21 @@
+import { ApiClient, ClientError } from "@mondaydotcomorg/api";
 import { BaseCallMondayApiTask } from "./base-call-monday-api-task";
 import { CallEndpointResult } from "../../types/task-types";
 import { StatusCodes } from "http-status-codes";
-import initMondayClient, { MondayServerSdk } from "monday-sdk-js";
 import { MondayError } from "../../errors/monday-error";
 
+export interface MondayClientCallMondayApiTaskOptions {
+  apiVersion?: string;
+}
+
 export class MondayClientCallMondayApiTask extends BaseCallMondayApiTask {
-  private readonly mondayClient: MondayServerSdk;
-  constructor() {
+  private readonly apiVersion?: string;
+
+  constructor(options: MondayClientCallMondayApiTaskOptions = {}) {
     super();
-    this.mondayClient = initMondayClient() as unknown as MondayServerSdk;
+    this.apiVersion = options.apiVersion;
   }
+
   async executeMondayRequest(
     token: string,
     query: string,
@@ -19,30 +25,35 @@ export class MondayClientCallMondayApiTask extends BaseCallMondayApiTask {
       if (!token) {
         throw new Error("API key is required");
       }
-      const response = await this.mondayClient.api(query, { variables, token });
-
-      if (response.errors && response.errors.length > 0) {
-        throw new MondayError("Monday.com API returned application errors", {
-          response,
-          mondayErrors: response.errors,
-          partialData: response.data,
-        });
-      }
-
+      const client = new ApiClient({ token, apiVersion: this.apiVersion });
+      const data = await client.request(query, variables);
       return {
         success: true,
         status: StatusCodes.OK,
-        data: response,
+        data,
       };
     } catch (error) {
+      const mondayError = normalizeClientError(error);
       return {
         success: false,
         status:
-          error instanceof MondayError
+          mondayError instanceof MondayError
             ? StatusCodes.OK
             : StatusCodes.INTERNAL_SERVER_ERROR,
-        error: error,
+        error: mondayError,
       };
     }
   }
 }
+
+export function normalizeClientError(error: unknown): unknown {
+  if (!(error instanceof ClientError)) {
+    return error;
+  }
+  const { response } = error;
+  return new MondayError("Monday.com API returned application errors", {
+    response,
+    mondayErrors: response?.errors,
+    partialData: response?.data,
+  });
+}

src/types/monday-types.ts

@@ -9,28 +9,24 @@ export interface MondayQueueRequestMessage extends BasicMondayRequestMessage {
 }
 
 export interface MondayErrorExtensions {
-  code: string;
+  code?: string;
+  error_code?: string;
   complexity?: number;
   complexity_budget_left?: number;
   complexity_budget_limit?: number;
   retry_in_seconds?: number;
-  status_code: number;
+  status_code?: number;
+  [key: string]: unknown;
 }
 
 export interface MondayApiError {
   message: string;
-  locations?: Array<{ line: number; column: number }>;
-  path?: string[];
+  locations?: ReadonlyArray<{ line: number; column: number }>;
+  path?: ReadonlyArray<string | number>;
   extensions?: MondayErrorExtensions;
-  [key: string]: unknown;
 }
 
 export interface MondayApiResponse {
   data?: unknown;
   errors?: Array<MondayApiError>;
 }
-
-export enum MondayErrorCodes {
-  COMPLEXITY_BUDGET_EXHAUSTED = "COMPLEXITY_BUDGET_EXHAUSTED",
-  MAX_CONCURRENCY_EXCEEDED = "MAX_CONCURRENCY_EXCEEDED",
-}