docs(core): clarify bulk env var delete skips and the branch-only filter

Says in the API reference, the request schema and the client param type
that a key is also skipped when its value changed while the delete ran,
and that onlyShadowingParent only takes effect when the request
addresses a preview branch. Adds a test for the padded row list path
and matches the docs page title to its siblings.

Author: matt-aitken

apps/webapp/test/environmentVariablesRepository.test.ts

@@ -1078,4 +1078,19 @@ describe("EnvironmentVariablesRepository value deletes", () => {
     expect(await variableKeys()).toEqual([]);
     expect((await secretRows(branch.id)).store).toEqual([]);
   });
+
+  postgresTest("deletes three of four keys through a padded row list", async ({ prisma }) => {
+    const { project, branch, repository, write, ownKeys, secretRows } =
+      await createBranchWithParent(prisma);
+    await write(branch.id, { A: "a", B: "b", C: "c", D: "d" }, vercel);
+
+    expect(
+      await repository.deleteValues(project.id, { environmentId: branch.id, keys: ["A", "B", "C"] })
+    ).toEqual({ deleted: ["A", "B", "C"], skipped: [] });
+    expect(await ownKeys(branch.id)).toEqual(["D"]);
+    expect(await secretRows(branch.id)).toEqual({ store: ["D"], references: ["D"] });
+    expect(await repository.getEnvironmentVariables(project.id, branch.id)).toEqual([
+      { key: "D", value: "d" },
+    ]);
+  });
 });

docs/management/envvars/bulk-delete.mdx

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

docs/v3-openapi.yaml

@@ -2192,7 +2192,7 @@ paths:
     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.
+      description: Delete up to 1000 environment variables from a specific project and environment in one request. Keys that have no value in the environment, that the filters exclude, or whose value changed while the delete ran are returned as skipped.
       requestBody:
         required: true
         content:
@@ -2230,7 +2230,7 @@ paths:
                       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.
+                  description: Only delete values whose key also has a value on the parent environment, so the branch falls back to the shared value. Takes effect only when the request addresses a preview branch, via the `x-trigger-branch` header or the SDK client's `previewBranch` option; on an environment with no parent every key is skipped.
                   default: false
               required: ["keys"]
       responses:
@@ -2248,7 +2248,7 @@ paths:
                       type: string
                   skipped:
                     type: array
-                    description: Keys that were left untouched, because the environment had no value for them or a filter excluded them.
+                    description: Keys that were left untouched, because the environment had no value for them, a filter excluded them, or their value changed while the delete ran. A skip caused by a concurrent change is transient and a retry can delete the key.
                     items:
                       type: string
                 required: ["deleted", "skipped"]

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

@@ -35,7 +35,11 @@ export type BulkDeleteEnvironmentVariablesParams = {
   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. */
+  /**
+   * Only delete values whose key also has a value on the parent environment. Takes effect only
+   * when the request addresses a preview branch (`x-trigger-branch` header or the API client's
+   * `previewBranch` option); on an environment with no parent every key is skipped.
+   */
   onlyShadowingParent?: boolean;
 };
 

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

@@ -1626,7 +1626,11 @@ export const BulkDeleteEnvironmentVariablesRequestBody = z.object({
   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. */
+  /**
+   * Only remove values whose key also has a value on the parent environment. Takes effect only
+   * when the request addresses a preview branch (`x-trigger-branch` header or the API client's
+   * `previewBranch` option); on an environment with no parent every key is skipped.
+   */
   onlyShadowingParent: z.boolean().optional(),
 });
 
@@ -1635,7 +1639,12 @@ export type BulkDeleteEnvironmentVariablesRequestBody = z.infer<
 >;
 
 export const BulkDeleteEnvironmentVariablesResponseBody = z.object({
+  /** Keys whose value was removed from the environment. */
   deleted: z.array(z.string()),
+  /**
+   * Keys left untouched: the environment had no value for them, a filter excluded them, or their
+   * value changed while the delete ran. A skip caused by a concurrent change is transient.
+   */
   skipped: z.array(z.string()),
 });