From e26923eb1990c023b8022bd9edd8f51dc7839a8d Mon Sep 17 00:00:00 2001
From: Matt Aitken <matt@mattaitken.com>
Date: Tue, 4 Jul 2023 10:31:42 +0100
Subject: [PATCH] backgroundFetch jsdocs

---
 .changeset/popular-cooks-boil.md       |  6 ++++++
 packages/internal/src/schemas/api.ts   |  5 +++++
 packages/internal/src/schemas/fetch.ts | 17 +++++++++++++++++
 packages/trigger-sdk/src/io.ts         | 11 +++++++++++
 4 files changed, 39 insertions(+)
 create mode 100644 .changeset/popular-cooks-boil.md

diff --git a/.changeset/popular-cooks-boil.md b/.changeset/popular-cooks-boil.md
new file mode 100644
index 000000000..97a9c52aa
--- /dev/null
+++ b/.changeset/popular-cooks-boil.md
@@ -0,0 +1,6 @@
+---
+"@trigger.dev/sdk": patch
+"@trigger.dev/internal": patch
+---
+
+backgroundFetch jsdocs
diff --git a/packages/internal/src/schemas/api.ts b/packages/internal/src/schemas/api.ts
index 179d0c5a9..1aa3f24fd 100644
--- a/packages/internal/src/schemas/api.ts
+++ b/packages/internal/src/schemas/api.ts
@@ -447,10 +447,15 @@ export const RedactSchema = z.object({
 });
 
 export const RetryOptionsSchema = z.object({
+  /** The maximum number of times to retry the request. */
   limit: z.number().optional(),
+  /** The exponential factor to use when calculating the next retry time. */
   factor: z.number().optional(),
+  /** The minimum amount of time to wait before retrying the request. */
   minTimeoutInMs: z.number().optional(),
+  /** The maximum amount of time to wait before retrying the request. */
   maxTimeoutInMs: z.number().optional(),
+  /** Whether to randomize the retry time. */
   randomize: z.boolean().optional(),
 });
 
diff --git a/packages/internal/src/schemas/fetch.ts b/packages/internal/src/schemas/fetch.ts
index e8714e3ef..993744410 100644
--- a/packages/internal/src/schemas/fetch.ts
+++ b/packages/internal/src/schemas/fetch.ts
@@ -2,9 +2,13 @@ import { z } from "zod";
 import { RedactStringSchema, RetryOptionsSchema } from "./api";
 
 export const FetchRetryHeadersStrategySchema = z.object({
+  /** The `headers` strategy retries the request using info from the response headers. */
   strategy: z.literal("headers"),
+  /** The header to use to determine the maximum number of times to retry the request. */
   limitHeader: z.string(),
+  /** The header to use to determine the number of remaining retries. */
   remainingHeader: z.string(),
+  /** The header to use to determine the time when the number of remaining retries will be reset. */
   resetHeader: z.string(),
 });
 
@@ -12,10 +16,13 @@ export type FetchRetryHeadersStrategy = z.infer<
   typeof FetchRetryHeadersStrategySchema
 >;
 
+/** The `backoff` strategy retries the request with an exponential backoff. */
 export const FetchRetryBackoffStrategySchema = RetryOptionsSchema.extend({
+  /** The `backoff` strategy retries the request with an exponential backoff. */
   strategy: z.literal("backoff"),
 });
 
+/** The `backoff` strategy retries the request with an exponential backoff. */
 export type FetchRetryBackoffStrategy = z.infer<
   typeof FetchRetryBackoffStrategySchema
 >;
@@ -27,16 +34,26 @@ export const FetchRetryStrategySchema = z.discriminatedUnion("strategy", [
 
 export type FetchRetryStrategy = z.infer<typeof FetchRetryStrategySchema>;
 
+/** The options for a fetch request */
 export const FetchRequestInitSchema = z.object({
+  /** The HTTP method to use for the request. */
   method: z.string().optional(),
+  /** Any headers to send with the request. Note that you can use [redactString](https://trigger.dev/docs/sdk/redactString) to prevent sensitive information from being stored (e.g. in the logs), like API keys and tokens. */
   headers: z.record(z.union([z.string(), RedactStringSchema])).optional(),
+  /** The body of the request. */
   body: z.union([z.string(), z.instanceof(ArrayBuffer)]).optional(),
 });
 
+/** The options for a fetch request */
 export type FetchRequestInit = z.infer<typeof FetchRequestInitSchema>;
 
 export const FetchRetryOptionsSchema = z.record(FetchRetryStrategySchema);
 
+/** An object where the key is a status code pattern and the value is a retrying strategy. Supported patterns are:
+  - Specific status codes: 429
+  - Ranges: 500-599
+  - Wildcards: 2xx, 3xx, 4xx, 5xx 
+  */
 export type FetchRetryOptions = z.infer<typeof FetchRetryOptionsSchema>;
 
 export const FetchOperationSchema = z.object({
diff --git a/packages/trigger-sdk/src/io.ts b/packages/trigger-sdk/src/io.ts
index 430a9fe61..9440c95a8 100644
--- a/packages/trigger-sdk/src/io.ts
+++ b/packages/trigger-sdk/src/io.ts
@@ -149,6 +149,17 @@ export class IO {
     );
   }
 
+  /** `io.backgroundFetch()` fetches data from a URL that can take longer that the serverless timeout. The actual `fetch` request is performed on the Trigger.dev platform, and the response is sent back to you.
+   * @param key Should be a stable and unique key inside the `run()`. See [resumability](https://trigger.dev/docs/documentation/concepts/resumability) for more information.
+   * @param url The URL to fetch from.
+   * @param requestInit The options for the request
+   * @param retry The options for retrying the request if it fails
+   * An object where the key is a status code pattern and the value is a retrying strategy.
+   * Supported patterns are:
+   * - Specific status codes: 429
+   * - Ranges: 500-599
+   * - Wildcards: 2xx, 3xx, 4xx, 5xx
+   */
   async backgroundFetch<TResponseData>(
     key: string | any[],
     url: string,