Improve the SDK function types and expose a new APIError instead of the APIResult type

Author: ericallam

.changeset/ninety-pets-travel.md

@@ -0,0 +1,6 @@
+---
+"@trigger.dev/sdk": patch
+"@trigger.dev/core": patch
+---
+
+Improve the SDK function types and expose a new APIError instead of the APIResult type

apps/webapp/app/routes/api.v1.schedules.$scheduleId.ts

@@ -6,6 +6,7 @@ import { prisma } from "~/db.server";
 import { ViewSchedulePresenter } from "~/presenters/v3/ViewSchedulePresenter.server";
 import { authenticateApiRequest } from "~/services/apiAuth.server";
 import { UpsertSchedule } from "~/v3/schedules";
+import { ServiceValidationError } from "~/v3/services/baseService.server";
 import { UpsertTaskScheduleService } from "~/v3/services/upsertTaskSchedule.server";
 
 const ParamsSchema = z.object({
@@ -87,6 +88,10 @@ export async function action({ request, params }: ActionFunctionArgs) {
 
         return json(responseObject, { status: 200 });
       } catch (error) {
+        if (error instanceof ServiceValidationError) {
+          return json({ error: error.message }, { status: 422 });
+        }
+
         return json(
           { error: error instanceof Error ? error.message : "Internal Server Error" },
           { status: 500 }

apps/webapp/app/routes/api.v1.schedules.ts

@@ -5,6 +5,7 @@ import { z } from "zod";
 import { ScheduleListPresenter } from "~/presenters/v3/ScheduleListPresenter.server";
 import { authenticateApiRequest } from "~/services/apiAuth.server";
 import { UpsertSchedule } from "~/v3/schedules";
+import { ServiceValidationError } from "~/v3/services/baseService.server";
 import { UpsertTaskScheduleService } from "~/v3/services/upsertTaskSchedule.server";
 
 const SearchParamsSchema = z.object({
@@ -63,6 +64,10 @@ export async function action({ request }: ActionFunctionArgs) {
 
     return json(responseObject, { status: 200 });
   } catch (error) {
+    if (error instanceof ServiceValidationError) {
+      return json({ error: error.message }, { status: 422 });
+    }
+
     return json(
       { error: error instanceof Error ? error.message : "Internal Server Error" },
       { status: 500 }

apps/webapp/app/v3/services/baseService.server.ts

@@ -32,3 +32,10 @@ export abstract class BaseService {
     );
   }
 }
+
+export class ServiceValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ServiceValidationError";
+  }
+}

apps/webapp/app/v3/services/upsertTaskSchedule.server.ts

@@ -4,7 +4,7 @@ import { ZodError } from "zod";
 import { $transaction, PrismaClientOrTransaction } from "~/db.server";
 import { generateFriendlyId } from "../friendlyIdentifiers";
 import { CronPattern, UpsertSchedule } from "../schedules";
-import { BaseService } from "./baseService.server";
+import { BaseService, ServiceValidationError } from "./baseService.server";
 import { RegisterNextTaskScheduleInstanceService } from "./registerNextTaskScheduleInstance.server";
 import cronstrue from "cronstrue";
 import { calculateNextScheduledTimestamp } from "../utils/calculateNextSchedule.server";
@@ -32,10 +32,10 @@ export class UpsertTaskScheduleService extends BaseService {
       CronPattern.parse(schedule.cron);
     } catch (e) {
       if (e instanceof ZodError) {
-        throw new Error(`Invalid cron expression: ${e.issues[0].message}`);
+        throw new ServiceValidationError(`Invalid cron expression: ${e.issues[0].message}`);
       }
 
-      throw new Error(
+      throw new ServiceValidationError(
         `Invalid cron expression: ${e instanceof Error ? e.message : JSON.stringify(e)}`
       );
     }

docs/v3-openapi.json

@@ -40,6 +40,9 @@
           "400": {
             "description": "Invalid request parameters"
           },
+          "422": {
+            "description": "Unprocessable Entity"
+          },
           "401": {
             "description": "Unauthorized"
           }
@@ -216,6 +219,9 @@
           },
           "404": {
             "description": "Resource not found"
+          },
+          "422": {
+            "description": "Unprocessable Entity"
           }
         },
         "tags": [

packages/core/package.json

@@ -76,7 +76,8 @@
     "superjson": "^2.2.1",
     "ulidx": "^2.2.1",
     "zod": "3.22.3",
-    "zod-error": "1.5.0"
+    "zod-error": "1.5.0",
+    "zod-validation-error": "^1.5.0"
   },
   "devDependencies": {
     "@trigger.dev/tsconfig": "workspace:*",

packages/core/src/v3/apiClient/index.ts

@@ -1,5 +1,5 @@
 import { context, propagation } from "@opentelemetry/api";
-import { ZodFetchOptions, zodfetch } from "../../zodfetch";
+import { ZodFetchOptions, zodfetch } from "../zodfetch";
 import {
   BatchTriggerTaskRequestBody,
   BatchTriggerTaskResponse,
@@ -25,7 +25,7 @@ export type TriggerOptions = {
 
 const zodFetchOptions: ZodFetchOptions = {
   retry: {
-    maxAttempts: 5,
+    maxAttempts: 3,
     minTimeoutInMs: 1000,
     maxTimeoutInMs: 30_000,
     factor: 2,

packages/core/src/v3/apiErrors.ts

@@ -0,0 +1,142 @@
+export type APIHeaders = Record<string, string | null | undefined>;
+
+export class APIError extends Error {
+  readonly status: number | undefined;
+  readonly headers: APIHeaders | undefined;
+  readonly error: Object | undefined;
+
+  readonly code: string | null | undefined;
+  readonly param: string | null | undefined;
+  readonly type: string | undefined;
+
+  constructor(
+    status: number | undefined,
+    error: Object | undefined,
+    message: string | undefined,
+    headers: APIHeaders | undefined
+  ) {
+    super(`${APIError.makeMessage(status, error, message)}`);
+    this.status = status;
+    this.headers = headers;
+
+    const data = error as Record<string, any>;
+    this.error = data;
+    this.code = data?.["code"];
+    this.param = data?.["param"];
+    this.type = data?.["type"];
+  }
+
+  private static makeMessage(status: number | undefined, error: any, message: string | undefined) {
+    const msg = error?.message
+      ? typeof error.message === "string"
+        ? error.message
+        : JSON.stringify(error.message)
+      : error
+      ? JSON.stringify(error)
+      : message;
+
+    if (status && msg) {
+      return `${status} ${msg}`;
+    }
+    if (status) {
+      return `${status} status code (no body)`;
+    }
+    if (msg) {
+      return msg;
+    }
+    return "(no status code or body)";
+  }
+
+  static generate(
+    status: number | undefined,
+    errorResponse: Object | undefined,
+    message: string | undefined,
+    headers: APIHeaders | undefined
+  ) {
+    if (!status) {
+      return new APIConnectionError({ cause: castToError(errorResponse) });
+    }
+
+    const error = (errorResponse as Record<string, any>)?.["error"];
+
+    if (status === 400) {
+      return new BadRequestError(status, error, message, headers);
+    }
+
+    if (status === 401) {
+      return new AuthenticationError(status, error, message, headers);
+    }
+
+    if (status === 403) {
+      return new PermissionDeniedError(status, error, message, headers);
+    }
+
+    if (status === 404) {
+      return new NotFoundError(status, error, message, headers);
+    }
+
+    if (status === 409) {
+      return new ConflictError(status, error, message, headers);
+    }
+
+    if (status === 422) {
+      return new UnprocessableEntityError(status, error, message, headers);
+    }
+
+    if (status === 429) {
+      return new RateLimitError(status, error, message, headers);
+    }
+
+    if (status >= 500) {
+      return new InternalServerError(status, error, message, headers);
+    }
+
+    return new APIError(status, error, message, headers);
+  }
+}
+
+export class APIConnectionError extends APIError {
+  override readonly status: undefined = undefined;
+
+  constructor({ message, cause }: { message?: string; cause?: Error | undefined }) {
+    super(undefined, undefined, message || "Connection error.", undefined);
+    // in some environments the 'cause' property is already declared
+    // @ts-ignore
+    if (cause) this.cause = cause;
+  }
+}
+
+export class BadRequestError extends APIError {
+  override readonly status: 400 = 400;
+}
+
+export class AuthenticationError extends APIError {
+  override readonly status: 401 = 401;
+}
+
+export class PermissionDeniedError extends APIError {
+  override readonly status: 403 = 403;
+}
+
+export class NotFoundError extends APIError {
+  override readonly status: 404 = 404;
+}
+
+export class ConflictError extends APIError {
+  override readonly status: 409 = 409;
+}
+
+export class UnprocessableEntityError extends APIError {
+  override readonly status: 422 = 422;
+}
+
+export class RateLimitError extends APIError {
+  override readonly status: 429 = 429;
+}
+
+export class InternalServerError extends APIError {}
+
+function castToError(err: any): Error {
+  if (err instanceof Error) return err;
+  return new Error(err);
+}

packages/core/src/v3/index.ts

@@ -7,6 +7,7 @@ export * from "./zodNamespace";
 export * from "./zodSocket";
 export * from "./zodIpc";
 export * from "./errors";
+export * from "./apiErrors";
 export * from "./runtime-api";
 export * from "./logger-api";
 export * from "./clock-api";

packages/core/src/v3/utils/ioSerialization.ts

@@ -110,27 +110,25 @@ async function exportPacket(packet: IOPacket, pathPrefix: string): Promise<IOPac
 
   const presignedResponse = await apiClientManager.client!.createUploadPayloadUrl(filename);
 
-  if (presignedResponse.ok) {
-    const uploadResponse = await fetch(presignedResponse.data.presignedUrl, {
-      method: "PUT",
-      headers: {
-        "Content-Type": packet.dataType,
-      },
-      body: packet.data,
-    });
-
-    if (!uploadResponse.ok) {
-      throw new Error(
-        `Failed to upload output to ${presignedResponse.data.presignedUrl}: ${uploadResponse.statusText}`
-      );
-    }
-
-    return {
-      data: filename,
-      dataType: "application/store",
-    };
+  const uploadResponse = await fetch(presignedResponse.presignedUrl, {
+    method: "PUT",
+    headers: {
+      "Content-Type": packet.dataType,
+    },
+    body: packet.data,
+  });
+
+  if (!uploadResponse.ok) {
+    throw new Error(
+      `Failed to upload output to ${presignedResponse.presignedUrl}: ${uploadResponse.statusText}`
+    );
   }
 
+  return {
+    data: filename,
+    dataType: "application/store",
+  };
+
   return packet;
 }
 
@@ -172,24 +170,22 @@ async function importPacket(packet: IOPacket, span?: Span): Promise<IOPacket> {
 
   const presignedResponse = await apiClientManager.client.getPayloadUrl(packet.data);
 
-  if (presignedResponse.ok) {
-    const response = await fetch(presignedResponse.data.presignedUrl);
+  const response = await fetch(presignedResponse.presignedUrl);
 
-    if (!response.ok) {
-      throw new Error(
-        `Failed to import packet ${presignedResponse.data.presignedUrl}: ${response.statusText}`
-      );
-    }
+  if (!response.ok) {
+    throw new Error(
+      `Failed to import packet ${presignedResponse.presignedUrl}: ${response.statusText}`
+    );
+  }
 
-    const data = await response.text();
+  const data = await response.text();
 
-    span?.setAttribute("size", Buffer.byteLength(data, "utf8"));
+  span?.setAttribute("size", Buffer.byteLength(data, "utf8"));
 
-    return {
-      data,
-      dataType: response.headers.get("content-type") ?? "application/json",
-    };
-  }
+  return {
+    data,
+    dataType: response.headers.get("content-type") ?? "application/json",
+  };
 
   return packet;
 }