feat(sdk,core): add envvars.bulkDelete() and document the endpoint

Adds `envvars.bulkDelete(projectRef, slug, { keys, onlyWrittenBy?,
onlyShadowingParent? })`, resolving projectRef and slug from the task
context like the neighbouring envvars functions, plus the matching
`bulkDeleteEnvVars` API client method and param type. Documents the
endpoint in the management API reference and caps each key at 256
characters in the request schema.

Author: matt-aitken

.changeset/envvar-bulk-delete.md

@@ -1,5 +1,14 @@
 ---
+"@trigger.dev/sdk": patch
 "@trigger.dev/core": patch
 ---
 
-Add a bulk delete endpoint for environment variables, `POST /api/v1/projects/:projectRef/envvars/:slug/bulk-delete`, which removes up to 1000 variables from one environment in a single call and can be limited to values last written by a given source or to branch values that shadow a value on the parent environment.
+Delete many environment variables in one call with `envvars.bulkDelete()`, backed by the new `POST /api/v1/projects/:projectRef/envvars/:slug/bulk-delete` endpoint. You can limit the delete to values last written by a given source, or to branch values that shadow a value on the parent environment, and the response lists the keys that were deleted and the keys that were skipped.
+
+```ts
+import { envvars } from "@trigger.dev/sdk";
+
+const result = await envvars.bulkDelete("proj_yubjwjsfkxnylobaqvqz", "dev", {
+  keys: ["SLACK_API_KEY", "STRIPE_SECRET_KEY"],
+});
+```

docs/docs.json

@@ -410,7 +410,8 @@
               "management/envvars/create",
               "management/envvars/retrieve",
               "management/envvars/update",
-              "management/envvars/delete"
+              "management/envvars/delete",
+              "management/envvars/bulk-delete"
             ]
           },
           {

docs/management/envvars/bulk-delete.mdx

@@ -0,0 +1,4 @@
+---
+title: "Bulk delete env vars"
+openapi: "v3-openapi POST /api/v1/projects/{projectRef}/envvars/{env}/bulk-delete"
+---

docs/v3-openapi.yaml

@@ -2185,6 +2185,124 @@ paths:
               override: false
             });
 
+  "/api/v1/projects/{projectRef}/envvars/{env}/bulk-delete":
+    parameters:
+      - $ref: "#/components/parameters/projectRef"
+      - $ref: "#/components/parameters/env"
+    post:
+      operationId: bulk_delete_project_envvars_v1
+      summary: Bulk delete environment variables
+      description: Delete up to 1000 environment variables from a specific project and environment in one request. Keys that have no value in the environment, or that the filters exclude, are returned as skipped.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                keys:
+                  type: array
+                  description: The names of the variables to delete from this environment.
+                  minItems: 1
+                  maxItems: 1000
+                  items:
+                    type: string
+                    minLength: 1
+                    maxLength: 256
+                onlyWrittenBy:
+                  description: Only delete values that were last written by this source.
+                  oneOf:
+                    - type: object
+                      properties:
+                        type:
+                          type: string
+                          enum: ["user"]
+                        userId:
+                          type: string
+                      required: ["type", "userId"]
+                    - type: object
+                      properties:
+                        type:
+                          type: string
+                          enum: ["integration"]
+                        integration:
+                          type: string
+                      required: ["type", "integration"]
+                onlyShadowingParent:
+                  type: boolean
+                  description: On a preview branch, only delete values whose key also has a value on the parent environment, so the branch falls back to the shared value.
+                  default: false
+              required: ["keys"]
+      responses:
+        "200":
+          description: The request completed. Each requested key appears in either `deleted` or `skipped`.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  deleted:
+                    type: array
+                    description: Keys whose value was removed from the environment.
+                    items:
+                      type: string
+                  skipped:
+                    type: array
+                    description: Keys that were left untouched, because the environment had no value for them or a filter excluded them.
+                    items:
+                      type: string
+                required: ["deleted", "skipped"]
+        "400":
+          description: Invalid request parameters or body
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        "401":
+          description: Unauthorized request
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        "404":
+          description: Resource not found
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+      tags:
+        - envvars
+      security:
+        - secretKey: []
+        - personalAccessToken: []
+      x-codeSamples:
+        - lang: typescript
+          label: Outside of a task
+          source: |-
+            import { envvars } from "@trigger.dev/sdk";
+
+            const result = await envvars.bulkDelete("proj_yubjwjsfkxnylobaqvqz", "dev", {
+              keys: ["SLACK_API_KEY", "STRIPE_SECRET_KEY"],
+            });
+
+            console.log(result.deleted, result.skipped);
+        - lang: typescript
+          label: Inside a task
+          source: |-
+            import { envvars, task } from "@trigger.dev/sdk";
+
+            export const myTask = task({
+              id: "my-task",
+              run: async () => {
+                // projectRef and env are automatically inferred from the task context
+                const result = await envvars.bulkDelete({
+                  keys: ["SLACK_API_KEY", "STRIPE_SECRET_KEY"],
+                });
+
+                console.log(result.deleted, result.skipped);
+              }
+            })
+
   "/api/v1/projects/{projectRef}/envvars/{env}/{name}":
     parameters:
       - $ref: "#/components/parameters/projectRef"

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

@@ -53,6 +53,7 @@ import {
   CreateUploadPayloadUrlResponseBody,
   SessionTranscriptResponseBody,
   CreateWaitpointTokenResponseBody,
+  BulkDeleteEnvironmentVariablesResponseBody,
   CreatedSessionResponseBody,
   DeletedScheduleObject,
   EndAndContinueSessionResponseBody,
@@ -129,6 +130,7 @@ import {
   STREAM_START_HEADER,
 } from "./runStream.js";
 import type {
+  BulkDeleteEnvironmentVariablesParams,
   CreateBulkActionOptions,
   CreateEnvironmentVariableParams,
   ImportEnvironmentVariablesParams,
@@ -154,6 +156,7 @@ export type CreateBatchApiResponse = Prettify<
 >;
 
 export type {
+  BulkDeleteEnvironmentVariablesParams,
   CreateBulkActionOptions,
   CreateEnvironmentVariableParams,
   ImportEnvironmentVariablesParams,
@@ -1187,6 +1190,24 @@ export class ApiClient {
     );
   }
 
+  bulkDeleteEnvVars(
+    projectRef: string,
+    slug: string,
+    body: BulkDeleteEnvironmentVariablesParams,
+    requestOptions?: ZodFetchOptions
+  ) {
+    return zodfetch(
+      BulkDeleteEnvironmentVariablesResponseBody,
+      `${this.baseUrl}/api/v1/projects/${projectRef}/envvars/${slug}/bulk-delete`,
+      {
+        method: "POST",
+        headers: this.#getHeaders(false),
+        body: JSON.stringify(body),
+      },
+      mergeRequestOptions(this.defaultRequestOptions, requestOptions)
+    );
+  }
+
   updateRunMetadata(
     runId: string,
     body: UpdateMetadataRequestBody,

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

@@ -1,4 +1,5 @@
 import type {
+  EnvironmentVariableSource,
   MachinePresetName,
   QueueTypeName,
   RunStatus,
@@ -29,6 +30,15 @@ export interface UpdateEnvironmentVariableParams {
   value: string;
 }
 
+export type BulkDeleteEnvironmentVariablesParams = {
+  /** The variables to delete from the environment, up to 1000 per call. */
+  keys: string[];
+  /** Only delete values that were last written by this source. */
+  onlyWrittenBy?: EnvironmentVariableSource;
+  /** Only delete values on a branch whose key also has a value on the parent environment. */
+  onlyShadowingParent?: boolean;
+};
+
 export interface ListRunsQueryParams extends CursorPageParams {
   status?: Array<RunStatus> | RunStatus;
   taskIdentifier?: Array<string> | string;

packages/core/src/v3/schemas/api.ts

@@ -1623,7 +1623,7 @@ export type ImportEnvironmentVariablesRequestBody = z.infer<
 >;
 
 export const BulkDeleteEnvironmentVariablesRequestBody = z.object({
-  keys: z.array(z.string()).min(1).max(1000),
+  keys: z.array(z.string().min(1).max(256)).min(1).max(1000),
   /** Only remove values last written by this source. */
   onlyWrittenBy: EnvironmentVariableSource.optional(),
   /** Only remove values whose key also has a value on the parent environment. */

packages/trigger-sdk/src/v3/envvars.ts

@@ -1,6 +1,8 @@
 import type {
   ApiPromise,
   ApiRequestOptions,
+  BulkDeleteEnvironmentVariablesParams,
+  BulkDeleteEnvironmentVariablesResponseBody,
   CreateEnvironmentVariableParams,
   EnvironmentVariableResponseBody,
   EnvironmentVariableWithSecret,
@@ -15,7 +17,11 @@ import {
 } from "@trigger.dev/core/v3";
 import { tracer } from "./tracer.js";
 
-export type { CreateEnvironmentVariableParams, ImportEnvironmentVariablesParams };
+export type {
+  BulkDeleteEnvironmentVariablesParams,
+  CreateEnvironmentVariableParams,
+  ImportEnvironmentVariablesParams,
+};
 
 export function upload(
   projectRef: string,
@@ -278,6 +284,72 @@ export function del(
   return apiClient.deleteEnvVar($projectRef, $slug, $name, $requestOptions);
 }
 
+export function bulkDelete(
+  projectRef: string,
+  slug: string,
+  params: BulkDeleteEnvironmentVariablesParams,
+  requestOptions?: ApiRequestOptions
+): ApiPromise<BulkDeleteEnvironmentVariablesResponseBody>;
+export function bulkDelete(
+  params: BulkDeleteEnvironmentVariablesParams,
+  requestOptions?: ApiRequestOptions
+): ApiPromise<BulkDeleteEnvironmentVariablesResponseBody>;
+export function bulkDelete(
+  projectRefOrParams: string | BulkDeleteEnvironmentVariablesParams,
+  slugOrRequestOptions?: string | ApiRequestOptions,
+  params?: BulkDeleteEnvironmentVariablesParams,
+  requestOptions?: ApiRequestOptions
+): ApiPromise<BulkDeleteEnvironmentVariablesResponseBody> {
+  let $projectRef: string;
+  let $params: BulkDeleteEnvironmentVariablesParams;
+  let $slug: string;
+  const $requestOptions = overloadRequestOptions(
+    "bulkDelete",
+    slugOrRequestOptions,
+    requestOptions
+  );
+
+  if (taskContext.ctx) {
+    if (typeof projectRefOrParams === "string") {
+      $projectRef = projectRefOrParams;
+      $slug =
+        typeof slugOrRequestOptions === "string"
+          ? slugOrRequestOptions
+          : taskContext.ctx.environment.slug;
+
+      if (!params) {
+        throw new Error("params is required");
+      }
+
+      $params = params;
+    } else {
+      $params = projectRefOrParams;
+      $projectRef = taskContext.ctx.project.ref;
+      $slug = taskContext.ctx.environment.slug;
+    }
+  } else {
+    if (typeof projectRefOrParams !== "string") {
+      throw new Error("projectRef is required");
+    }
+
+    if (!slugOrRequestOptions || typeof slugOrRequestOptions !== "string") {
+      throw new Error("slug is required");
+    }
+
+    if (!params) {
+      throw new Error("params is required");
+    }
+
+    $projectRef = projectRefOrParams;
+    $slug = slugOrRequestOptions;
+    $params = params;
+  }
+
+  const apiClient = apiClientManager.clientOrThrow();
+
+  return apiClient.bulkDeleteEnvVars($projectRef, $slug, $params, $requestOptions);
+}
+
 export function update(
   projectRef: string,
   slug: string,

packages/trigger-sdk/src/v3/index.ts

@@ -65,7 +65,10 @@ export {
 } from "./deployments.js";
 export * as envvars from "./envvars.js";
 export * as queues from "./queues.js";
-export type { ImportEnvironmentVariablesParams } from "./envvars.js";
+export type {
+  BulkDeleteEnvironmentVariablesParams,
+  ImportEnvironmentVariablesParams,
+} from "./envvars.js";
 
 export { configure, auth } from "./auth.js";
 export { TriggerClient, type TriggerClientConfig } from "./triggerClient.js";