@pipelex/sdk 0.50.0 → 0.51.0

package/README.md

@@ -167,6 +167,17 @@ for await (const saved of client.iterateMethodExamples(created.method_id)) {
   // every example, oldest first
 }
 
+// Copy a method into a team, or into your personal workspace, with its draft, its form inputs and
+// its examples (web sessions only). A bundle naming storage the destination cannot read answers
+// `refused`, a verdict rather than an error; the key makes a retry copy once.
+const copy = await client.copyMethod(
+  created.method_id,
+  { destination_org_id: "org_team", expected_draft_updated_at: draft.updated_at },
+  { idempotencyKey: crypto.randomUUID() },
+);
+if (copy.outcome === "copied") console.log(copy.method.copied_from); // the original it names
+const copies = await client.listMethodCopies(created.method_id); // where the copies went
+
 // The organization's files, newest first: uploads, test files and the files runs made. Each row's
 // `uri` goes into a run's inputs as any address does. A filtered page can be empty and still carry
 // a nextCursor; iterateFiles follows it.
@@ -273,6 +284,7 @@ These pages ship inside the published package, so a reader who has only installe
 | [`docs/method-trees.md`](./docs/method-trees.md) | A method's tree: the four forms a run, a validation, a save and the crate routes take it in (a directory on disk among them), how it travels inline or by hash and what is uploaded, the files a step reads, the template check's warnings and which step reads which file of the tree, the deployment's limits, the read's listing with its links, `writeMethodTree`, and `MethodFileTransferError` |
 | [`docs/files.md`](./docs/files.md) | An organization's files: `listFiles` and `iterateFiles`, the row, the whole record and its provenance, the query and its repeated filters, paging through filtered pages, one file and its uses, the records of an address, the rename rule, links that name the file, a zip of files and its caps, a run's files, the copy into a method's draft, and an upload recorded as a method's test file with the refusals that come with it |
 | [`docs/method-examples.md`](./docs/method-examples.md) | A method's saved examples: the create, the paged list and its iterator, the edit that raises the input revision, the latest-run write and its `recorded` or `stale` verdict, the build assistant's save and its `kept` or `created` verdict, how an integer past `Number.MAX_SAFE_INTEGER` in the inputs stays exact, and what is refused before sending |
+| [`docs/method-copy.md`](./docs/method-copy.md) | Copying a method into another organization or duplicating it: what a copy holds and the stored files it copies, the `copied` or `refused` verdict, every refusal, the copy's idempotency key, the copies a method lists, and `copied_from` |
 | [`docs/organization-branding.md`](./docs/organization-branding.md) | An organization's logos and colours: `getBranding`, which every member and API key reads, `updateOrganizationBranding`, an admin's write that sets, clears or keeps each key, and how a refused logo or colour names its slot in `errors` so a settings screen shows the sentence under it |
 | [`docs/exact-integers.md`](./docs/exact-integers.md) | Which reads keep an integer past `Number.MAX_SAFE_INTEGER` exact, as a `bigint` (a run's inputs and outputs, an example's inputs), how a request body writes it back with its digits, and `parseExactJson` and `stringifyExactJson` for code showing such data as JSON text |
 | [`docs/crate-routes.md`](./docs/crate-routes.md) | `resolve`, `codegen` and `pipeIo` — the method's tree as the protocol's `files` map, with its dependencies, the normalized crate, the stamped types, and a method's I/O artifacts without a validation — and the offline `runCodegenCheck` that guards a committed tree |

package/dist/cli/script.d.ts

@@ -15,7 +15,7 @@ import type { CommandIO } from "./io.js";
  * update notice and npm 12's run notices off the script's stderr, which carries the command's
  * own lines, while npm's warnings and errors still print.
  */
-export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.50.0";
+export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.51.0";
 export declare const SCRIPT_WRITER = "@pipelex/sdk";
 export declare const SCRIPT_NEEDS = "Node 22.12 or later";
 /** Run `pipelex-sdk script` and return its exit code. */

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import type { MTHDSProtocol, ModelCategory, ModelDeck, RunOptions, StartOptions, VersionInfo } from "mthds/protocol";
 import type { CodegenRequest, CodegenResponse, CrateRouteOptions, DictPipeOutput, FormatResponse, LintResponse, ModelCheckCategory, ModelReferenceVerdict, PipeIORequest, PipeIOResponse, PipelexRunResultStart, PipelexValidateSource, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector } from "./models.js";
 import { type GetRunResultOptions, type RunProgress, type RunRead, type RunResults, type RunResultState, type StartAndWaitForResultOptions, type WaitForResultOptions } from "./runs.js";
-import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, DraftFileFromFileInput, DraftFileFromFileResult, FileArchive, FileArchiveRequest, FileDetail, FileLinkTarget, FileLinksResult, FilePage, FileRecord, FileRecordList, FileRenameInput, FileSummary, GetFileQuery, GetFilesByUriOptions, InvoiceView, Membership, MembershipsResponse, OrganizationBranding, OrganizationBrandingUpdate, ListFilesQuery, ListMethodExamplesQuery, ListMethodsQuery, ListMethodVersionsQuery, ListRunFilesQuery, MethodData, MethodDeletionAccepted, MethodDetail, MethodDraftInput, MethodExample, MethodExampleAssistantSaveInput, MethodExampleAssistantSaveResult, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunResult, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunFilesPage, RunPage, PlanView, ResolvedStorageUrl, SavedMethodFile, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
+import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, DraftFileFromFileInput, DraftFileFromFileResult, FileArchive, FileArchiveRequest, FileDetail, FileLinkTarget, FileLinksResult, FilePage, FileRecord, FileRecordList, FileRenameInput, FileSummary, GetFileQuery, GetFilesByUriOptions, InvoiceView, Membership, MembershipsResponse, OrganizationBranding, OrganizationBrandingUpdate, ListFilesQuery, ListMethodCopiesQuery, ListMethodExamplesQuery, ListMethodsQuery, ListMethodVersionsQuery, ListRunFilesQuery, MethodCopyInput, MethodCopyPage, MethodCopyResult, MethodData, MethodDeletionAccepted, MethodDetail, MethodDraftInput, MethodExample, MethodExampleAssistantSaveInput, MethodExampleAssistantSaveResult, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunResult, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunFilesPage, RunPage, PlanView, ResolvedStorageUrl, SavedMethodFile, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
 import type { MethodTreeForms, MethodTreeLimits } from "./method-trees.js";
 import type { AppInfo } from "./user-agent.js";
 import type { UploadableAsset, UploadFileOptions, UploadRecord } from "./upload.js";
@@ -122,6 +122,34 @@ export interface PipelexStartRequestOptions {
      */
     idempotencyKey?: string | null;
 }
+/**
+ * What a method copy sends beside its body: the request's own header, which no copy argument
+ * reaches, camelCase since it is no wire field of the copy.
+ */
+export interface MethodCopyRequestOptions {
+    /**
+     * The copy's idempotency key, sent as the `Idempotency-Key` header of
+     * `POST /v1/methods/{id}/copy`, and not sent at all when absent or `null`. Generate one per copy
+     * the caller means to make (a `crypto.randomUUID()` is a good key), and keep it, with the
+     * arguments unchanged, across that copy's retries.
+     *
+     * The hosted API stores the copy's answer under the key for 24 hours, scoped to the caller and
+     * the method's organization, so the same copy sent again under the same key is answered with the
+     * stored answer and copies nothing more: a copy whose answer was lost, as on a client timeout,
+     * can be sent again unchanged and makes one copy, not two. A verdict and a `4xx` refusal of the
+     * copy are stored alike, so the same copy under the same key is answered the same again; a `5xx`
+     * and a refusal for its timing (a `408`, `425` or `429`) are not stored, and a copy that failed
+     * with one left nothing visible, so the same key sends it afresh.
+     * The same key with a different body is refused (`409` `conflict`), as is a key whose earlier
+     * request is still being handled (`409` `idempotency_key_in_use`, retryable: send it again
+     * under the same key in a few seconds); a changed copy, such as one with a fresh draft token,
+     * goes under a new key. See `docs/method-copy.md`.
+     *
+     * A key is held to the rule a start's is (`PipelexStartRequestOptions.idempotencyKey`): 1 to
+     * 255 visible ASCII characters, anything else a `RequestArgumentError` before any request.
+     */
+    idempotencyKey?: string | null;
+}
 /**
  * `start()` / `startAndWaitForResult()` options — the same, for the durable path, plus the start
  * request's own `idempotencyKey`.
@@ -231,7 +259,7 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * resolved absolute URL. `mayStartRun` marks a request that may create a run,
      * whose `ApiUnreachableError` then says whether it may have (see `RunCreation`).
      * `idempotencyKey`, already checked by `idempotencyKeyOf`, is sent as the
-     * `Idempotency-Key` header; only `start` passes one.
+     * `Idempotency-Key` header; only `start` and `copyMethod` pass one.
      */
     private requestRaw;
     /**
@@ -1215,6 +1243,71 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * never rewritten as one, which names no tree to serve.
      */
     getMethodVersion(methodId: string, version: number): Promise<MethodVersion>;
+    /**
+     * Copy a method into an organization the caller may change methods in —
+     * `POST /v1/methods/{id}/copy`: the method's own organization for a duplicate, another team, or
+     * the caller's personal workspace.
+     *
+     * The copy is a new, unpublished method of the destination, the caller's, holding the
+     * original's draft tree (the same `draft_digest`), its name unless `name` gives another, its
+     * form inputs and every saved example, each stored file they name copied into the destination,
+     * and `copied_from` naming the original. Published versions and runs are not copied, and the
+     * original stays as it was. The copy takes the draft, never the latest published version; with
+     * `expected_draft_updated_at`, it takes exactly the draft the caller last saw.
+     *
+     * The answer is a `MethodCopyResult` discriminated on `outcome` — branch on it: `copied` with
+     * the copy as `method`, `examples_copied` and `stored_files_copied`; `refused` with the
+     * `reason` `bundle_names_other_storage`, a `message` and every `references` entry (`{ path, uri
+     * }`) a `.mthds` file of the draft holds that the destination cannot read, nothing written.
+     *
+     * The route serves web sessions only: a Pipelex API key belongs to one organization and cannot
+     * speak for another. `options.idempotencyKey` is sent as the `Idempotency-Key` header, so a copy
+     * sent again under the same key is answered with the first one's answer rather than copied
+     * twice (see `MethodCopyRequestOptions`).
+     *
+     * Takes a bare catalog id, as `getMethod` does. Sends `destination_org_id` and, when given,
+     * `name` and `expected_draft_updated_at`, and nothing else: the body is closed, and a `null`
+     * reads as not given. Throws `RequestArgumentError` before any request for a
+     * `destination_org_id` that is not a non-empty string, a `name` or an
+     * `expected_draft_updated_at` given that is not a string, and a malformed idempotency key.
+     * Throws `ApiResponseError` when no verdict was produced, each refusal writing nothing a reader
+     * sees: `403` `forbidden` for a request that is not from a web session; `403`
+     * `role_not_permitted` for a role that may not change methods, in the method's organization or
+     * in the destination; `404` `organization_not_found` for a destination the caller does not
+     * belong to, still being set up or unknown, alike; `404` `not_found` for an unknown method;
+     * `409` `method_being_deleted`; `409` `method_update_conflict` for a draft that moved since
+     * `expected_draft_updated_at`; `409` `conflict`, `runtime`, for a draft whose tree the
+     * organization holds no full record of; `413` `payload_too_large` for an example or a copy too
+     * large for one stored item; `422` `validation_failed` for a body that does not validate, such
+     * as a name holding a lone surrogate; `422` `method_copy_too_large` past one of the copy's
+     * bounds on the stored files it copies, named by `problemDocument.limit` (`MethodCopyLimit`);
+     * and, each retryable, a `502` when the platform could not read the caller's memberships, a
+     * `500` `storage_backend_failed` and a `503` past the copy's deadline. An answer whose
+     * `outcome` is neither arm's, a `copied` one whose `method` is not an object or a `refused` one
+     * whose `references` is not an array, is an answer the SDK cannot read, thrown as an
+     * `ApiResponseError` too.
+     */
+    copyMethod(methodId: string, input: MethodCopyInput, options?: MethodCopyRequestOptions): Promise<MethodCopyResult>;
+    /**
+     * One page of the copies made of a method, in the order of the copies' ids, which says nothing
+     * of when each was made — `GET /v1/methods/{id}/copies`.
+     *
+     * Each row is the `MethodCopyMarker` the original keeps of a copy: the copy's id, the
+     * destination's id, the member who made it and when. The destination is named by its id alone,
+     * never its name, so a surface shows a destination's name only from the reader's own
+     * memberships, and a copy in an organization the reader does not belong to stays a bare id. A
+     * marker stays when its copy is erased, and the copy then reads as not found. Pass the page's
+     * `nextCursor` back as `cursor` to continue; `null` is the last page. A method never copied,
+     * and a copy itself, answer an empty page. The listing is open to every member of the method's
+     * organization, a runner included, as every read of a method is.
+     *
+     * Takes a bare catalog id, as `getMethod` does. Throws `ApiResponseError`: `404` `not_found` for
+     * an unknown method, `409` `method_being_deleted`, `400` `malformed_request` for a cursor the
+     * listing did not issue for this method, `422` for a `limit` outside 1 to 100. A page whose
+     * `items` is not an array or whose `next_cursor` is neither a string nor `null` is an answer the
+     * SDK cannot read, thrown as an `ApiResponseError` too.
+     */
+    listMethodCopies(methodId: string, query?: ListMethodCopiesQuery): Promise<MethodCopyPage>;
     /**
      * Erase a method and everything it produced — `DELETE /v1/methods/{id}`.
      *

package/dist/client.js

@@ -233,6 +233,11 @@ const ARCHIVE_RUN_ID_ARGUMENT = "a run_id naming the run whose files to zip, a n
 const ARCHIVE_NAME_ARGUMENT = "a name for the zip, a string, or none";
 const DRAFT_PATH_ARGUMENT = "the tree path the file takes in the draft, a non-empty string";
 const DRAFT_TOKEN_ARGUMENT = "the draft token the caller last read, the method's `updated_at`, a string, or none";
+/** What each argument of a method copy is, as a refusal of it names it. */
+const COPY_DESTINATION_ARGUMENT = "a destination_org_id, the canonical id of the organization to copy into, a non-empty string";
+const COPY_NAME_ARGUMENT = "a name for the copy, a string, or none";
+const COPY_DRAFT_TOKEN_ARGUMENT = "an expected_draft_updated_at, the draft token the caller last read, the method's " +
+    "`updated_at`, a string, or none";
 /**
  * The refusal of an argument a call cannot take, worded as every such refusal is:
  * `<call>() takes <what>; got <got>.`, with what made it unusable as `cause` when there is one.
@@ -341,6 +346,8 @@ const isString = (value) => typeof value === "string";
 const FILE_ARCHIVE_STATES = ["queued", "building", "ready", "failed"];
 /** What a copy into a draft did in the blob store, the field its answer is discriminated on. */
 const DRAFT_FILE_BLOBS = ["copied", "already_held"];
+/** What a method copy did, the field its answer is discriminated on. */
+const METHOD_COPY_OUTCOMES = ["copied", "refused"];
 /** Whether a run's records are all written, the field a reader of its files branches on. */
 const RUN_FILES_STATES = ["listing", "listed"];
 /** The lists of a page of a run's files, each an array on every page. */
@@ -479,7 +486,7 @@ export class PipelexApiClient {
      * resolved absolute URL. `mayStartRun` marks a request that may create a run,
      * whose `ApiUnreachableError` then says whether it may have (see `RunCreation`).
      * `idempotencyKey`, already checked by `idempotencyKeyOf`, is sent as the
-     * `Idempotency-Key` header; only `start` passes one.
+     * `Idempotency-Key` header; only `start` and `copyMethod` pass one.
      */
     async requestRaw(method, url, options = {}) {
         const hasBody = options.body !== undefined;
@@ -692,6 +699,7 @@ export class PipelexApiClient {
             body,
             timeoutMs: options.timeoutMs ?? POLL_REQUEST_TIMEOUT_MS,
             signal: options.signal,
+            idempotencyKey: options.idempotencyKey,
         });
         if (res.status < 200 || res.status >= 300) {
             this.throwApiResponseError(method, endpoint, res);
@@ -2347,6 +2355,116 @@ export class PipelexApiClient {
         const res = await this.requestProductAnswer("GET", endpoint, undefined);
         return this.readSavedTree("GET", endpoint, withLinks(res), "a published version");
     }
+    /**
+     * Copy a method into an organization the caller may change methods in —
+     * `POST /v1/methods/{id}/copy`: the method's own organization for a duplicate, another team, or
+     * the caller's personal workspace.
+     *
+     * The copy is a new, unpublished method of the destination, the caller's, holding the
+     * original's draft tree (the same `draft_digest`), its name unless `name` gives another, its
+     * form inputs and every saved example, each stored file they name copied into the destination,
+     * and `copied_from` naming the original. Published versions and runs are not copied, and the
+     * original stays as it was. The copy takes the draft, never the latest published version; with
+     * `expected_draft_updated_at`, it takes exactly the draft the caller last saw.
+     *
+     * The answer is a `MethodCopyResult` discriminated on `outcome` — branch on it: `copied` with
+     * the copy as `method`, `examples_copied` and `stored_files_copied`; `refused` with the
+     * `reason` `bundle_names_other_storage`, a `message` and every `references` entry (`{ path, uri
+     * }`) a `.mthds` file of the draft holds that the destination cannot read, nothing written.
+     *
+     * The route serves web sessions only: a Pipelex API key belongs to one organization and cannot
+     * speak for another. `options.idempotencyKey` is sent as the `Idempotency-Key` header, so a copy
+     * sent again under the same key is answered with the first one's answer rather than copied
+     * twice (see `MethodCopyRequestOptions`).
+     *
+     * Takes a bare catalog id, as `getMethod` does. Sends `destination_org_id` and, when given,
+     * `name` and `expected_draft_updated_at`, and nothing else: the body is closed, and a `null`
+     * reads as not given. Throws `RequestArgumentError` before any request for a
+     * `destination_org_id` that is not a non-empty string, a `name` or an
+     * `expected_draft_updated_at` given that is not a string, and a malformed idempotency key.
+     * Throws `ApiResponseError` when no verdict was produced, each refusal writing nothing a reader
+     * sees: `403` `forbidden` for a request that is not from a web session; `403`
+     * `role_not_permitted` for a role that may not change methods, in the method's organization or
+     * in the destination; `404` `organization_not_found` for a destination the caller does not
+     * belong to, still being set up or unknown, alike; `404` `not_found` for an unknown method;
+     * `409` `method_being_deleted`; `409` `method_update_conflict` for a draft that moved since
+     * `expected_draft_updated_at`; `409` `conflict`, `runtime`, for a draft whose tree the
+     * organization holds no full record of; `413` `payload_too_large` for an example or a copy too
+     * large for one stored item; `422` `validation_failed` for a body that does not validate, such
+     * as a name holding a lone surrogate; `422` `method_copy_too_large` past one of the copy's
+     * bounds on the stored files it copies, named by `problemDocument.limit` (`MethodCopyLimit`);
+     * and, each retryable, a `502` when the platform could not read the caller's memberships, a
+     * `500` `storage_backend_failed` and a `503` past the copy's deadline. An answer whose
+     * `outcome` is neither arm's, a `copied` one whose `method` is not an object or a `refused` one
+     * whose `references` is not an array, is an answer the SDK cannot read, thrown as an
+     * `ApiResponseError` too.
+     */
+    async copyMethod(methodId, input, options = {}) {
+        const call = "copyMethod";
+        const endpoint = `${methodPath(methodId, call)}/copy`;
+        const { destination_org_id: destinationOrgId, name, expected_draft_updated_at: token, } = input ?? {};
+        const body = {
+            destination_org_id: requireNonEmptyId(destinationOrgId, call, COPY_DESTINATION_ARGUMENT),
+        };
+        if (name != null) {
+            if (typeof name !== "string") {
+                throw argumentRefusal(call, COPY_NAME_ARGUMENT, describeNumberArgument(name));
+            }
+            body.name = name;
+        }
+        if (token != null) {
+            if (typeof token !== "string") {
+                throw argumentRefusal(call, COPY_DRAFT_TOKEN_ARGUMENT, describeNumberArgument(token));
+            }
+            body.expected_draft_updated_at = token;
+        }
+        const idempotencyKey = idempotencyKeyOf(options, "copy the method");
+        const res = await this.requestProductAnswer("POST", endpoint, body, { idempotencyKey });
+        const answer = this.readObjectAnswer("POST", endpoint, res);
+        let fault;
+        switch (answer.outcome) {
+            case "copied":
+                if (!isPlainObject(answer.method)) {
+                    fault = "a `copied` copy result whose `method` is not an object";
+                }
+                break;
+            case "refused":
+                if (!Array.isArray(answer.references)) {
+                    fault = "a `refused` copy result whose `references` is not an array";
+                }
+                break;
+            default:
+                fault = `a copy result whose \`outcome\` is not ${inWords(METHOD_COPY_OUTCOMES.map((outcome) => `\`${outcome}\``), "or")}`;
+        }
+        if (fault !== undefined) {
+            throw this.unreadableAnswer("POST", `/${API_PREFIX}/${endpoint}`, res, fault);
+        }
+        return answer;
+    }
+    /**
+     * One page of the copies made of a method, in the order of the copies' ids, which says nothing
+     * of when each was made — `GET /v1/methods/{id}/copies`.
+     *
+     * Each row is the `MethodCopyMarker` the original keeps of a copy: the copy's id, the
+     * destination's id, the member who made it and when. The destination is named by its id alone,
+     * never its name, so a surface shows a destination's name only from the reader's own
+     * memberships, and a copy in an organization the reader does not belong to stays a bare id. A
+     * marker stays when its copy is erased, and the copy then reads as not found. Pass the page's
+     * `nextCursor` back as `cursor` to continue; `null` is the last page. A method never copied,
+     * and a copy itself, answer an empty page. The listing is open to every member of the method's
+     * organization, a runner included, as every read of a method is.
+     *
+     * Takes a bare catalog id, as `getMethod` does. Throws `ApiResponseError`: `404` `not_found` for
+     * an unknown method, `409` `method_being_deleted`, `400` `malformed_request` for a cursor the
+     * listing did not issue for this method, `422` for a `limit` outside 1 to 100. A page whose
+     * `items` is not an array or whose `next_cursor` is neither a string nor `null` is an answer the
+     * SDK cannot read, thrown as an `ApiResponseError` too.
+     */
+    async listMethodCopies(methodId, query = {}) {
+        const search = productQuery({ limit: query.limit, cursor: query.cursor });
+        const endpoint = `${methodPath(methodId, "listMethodCopies")}/copies`;
+        return this.requestPage(`${endpoint}${search}`);
+    }
     /**
      * Erase a method and everything it produced — `DELETE /v1/methods/{id}`.
      *
@@ -3802,7 +3920,7 @@ function assertLinkageMethodIdIsBare(options, treeForms) {
 function nonEmptyString(value) {
     return value != null && value.length > 0 ? value : undefined;
 }
-/** The request header the hosted API reads a run start's idempotency key from. */
+/** The request header the hosted API reads a request's idempotency key from. */
 const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
 /**
  * The longest idempotency key a start sends. It is room for any generated key, and keeps the
@@ -3817,21 +3935,22 @@ const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
  */
 const VISIBLE_ASCII = /^[\x21-\x7E]+$/;
 /**
- * The idempotency key a start sends, or `undefined` when the options carry none (absent or
- * `null`). A key that is not a string of 1 to 255 visible ASCII characters is refused with a
- * `RequestArgumentError` rather than dropped, an empty one included, since a start sent without
- * the key its caller gave would lose the protection the caller asked for without a word. The
- * message never quotes the key, which a caller may derive from something private. The Python SDK
- * holds a key to the same rule, in the same words.
+ * The idempotency key a start or a method copy sends, or `undefined` when the options carry none
+ * (absent or `null`). A key that is not a string of 1 to 255 visible ASCII characters is refused
+ * with a `RequestArgumentError` rather than dropped, an empty one included, since a request sent
+ * without the key its caller gave would lose the protection the caller asked for without a word.
+ * `request` says what the request does, as the refusal's last sentence names it ("start the run",
+ * "copy the method"). The message never quotes the key, which a caller may derive from something
+ * private. The Python SDK holds a key to the same rule, in the same words.
  */
-function idempotencyKeyOf(options) {
+function idempotencyKeyOf(options, request = "start the run") {
     const key = options.idempotencyKey;
     if (key == null)
         return undefined;
     const fault = idempotencyKeyFault(key);
     if (fault !== undefined) {
         throw new RequestArgumentError(`The idempotency key must be 1 to ${MAX_IDEMPOTENCY_KEY_LENGTH} visible ASCII characters ` +
-            `(\`!\` to \`~\`), and this one ${fault}. Leave it out to start the run without one.`);
+            `(\`!\` to \`~\`), and this one ${fault}. Leave it out to ${request} without one.`);
     }
     return key;
 }