@cloudpdf/contract 3.0.0-next.14 → 3.0.0-next.16

package/dist/openapi.js

@@ -1,31 +1,64 @@
 // src/openapi.ts
-import { EngineErrorPayloadSchema as EngineErrorPayloadSchema2, PdfActionWireComponents } from "@embedpdf/engine-core/wire";
+import {
+  AnnotationWireComponents,
+  AttachmentWireComponents,
+  ChangeWireComponents,
+  DocumentWireComponents,
+  EngineErrorPayloadSchema as EngineErrorPayloadSchema2,
+  FormWireComponents,
+  OutlineWireComponents,
+  PdfActionWireComponents
+} from "@embedpdf/engine-core/wire";
 import { z as z2 } from "zod";
 import { ignoreOverride, zodToJsonSchema } from "zod-to-json-schema";
 
 // src/index.ts
 import {
+  ChangeRequestSchema,
+  ChangeResponseSchema,
   PageScaleInputSchema,
   PageScaleResultSchema,
-  PageMeasurementViewportSchema
+  PageMeasurementViewportListSchema
 } from "@embedpdf/engine-core/wire";
 import {
-  AnnotationListPageSnapshotSchema,
-  AnnotationListSnapshotAllPagesSchema,
+  AnnotationCreateResultSchema,
+  AnnotationDeleteResultSchema,
+  AnnotationFlattenResultSchema,
+  AnnotationListSchema,
+  AnnotationReorderBodySchema,
+  AnnotationReorderResultSchema,
+  AnnotationUpdateResultSchema,
   DocumentHeadSchema,
   DocumentManifestSchema,
+  CustomMetadataSchema,
   DocumentMetadataSchema,
+  DocumentOutlineSchema,
   EngineErrorPayloadSchema,
+  FormResetBodySchema,
+  FormWidgetDeleteResultSchema,
+  FormWidgetUpdateBodySchema,
+  FormWidgetUpdateResultSchema,
+  FormWidgetsReorderBodySchema,
+  FormWidgetsReorderResultSchema,
+  FormCalculationsReorderBodySchema,
+  FormCalculationsReorderResultSchema,
+  FormResetResultSchema,
+  FormSetValueResultSchema,
   FormSnapshotSchema,
-  MutationMetaSchema,
+  IdentitySchema,
+  PageFlattenResultSchema,
+  PageNameResultSchema,
+  RedactionApplyResultSchema,
+  RedactionApplyScopeSchema,
   PageTextSnapshotSchema,
   ChangeAnalysisSchema,
   DocumentVersionsSchema,
-  SignatureAbortResultSchema,
+  SignatureCancelResultSchema,
   SignatureCompleteBodySchema,
   SignatureCompleteResultSchema,
   SignaturePreparedWireSchema,
   SignatureSnapshotSchema,
+  AttachmentListSchema,
   wireTemplates
 } from "@embedpdf/engine-core/wire";
 import { z } from "zod";
@@ -162,7 +195,7 @@ var AdminImportSourceSchema = z.discriminatedUnion("kind", [
     "The operator pre-registered the authority: the request names a connection and a key inside it. Which provider backs the connection (S3, GCS, Azure Blob, filesystem, ...) is deployment configuration, never wire surface."
   )
 ]).describe(
-  "Where CloudPDF pulls the bytes from. The two shapes differ in WHO supplies the authority to read, not in which storage vendor holds the file."
+  "Where CloudPDF pulls the bytes from. The two shapes differ in who supplies the authority to read, not in which storage vendor holds the file."
 );
 var AdminDocumentImportRequestSchema = z.object({
   source: AdminImportSourceSchema,
@@ -171,7 +204,7 @@ var AdminDocumentImportRequestSchema = z.object({
    * against the source's declared Content-Length before the transfer,
    * `sha256` against the server-observed digest after it. When absent
    * the server-observed values become authoritative.
-   * `dedupMode=reuse-existing` REQUIRES `sha256` — without a declared
+   * `dedupMode=reuse-existing` requires `sha256` — without a declared
    * hash the server cannot know what content to reuse.
    */
   expected: z.object({
@@ -262,7 +295,7 @@ var AdminTokenRevokeRequestSchema = z.object({
   /** Optional human reason, written to the audit row. */
   reason: z.string().max(1024).optional(),
   /**
-   * The token's `exp` (unix seconds), used to GC the revocation row
+   * The token's `exp` (unix seconds); the revocation row is garbage-collected
    * once the token would have expired anyway. Defaults server-side to
    * now + 30 days.
    */
@@ -329,10 +362,12 @@ var AdminTokenIssueDocRequestSchema = z.object({
    * vocabulary — an unknown string rejects the whole request.
    */
   scope: z.array(z.string().min(1).max(128)).min(1).max(64),
-  userId: z.string().max(256).optional(),
-  displayName: z.string().max(256).optional(),
-  groupId: z.string().max(256).optional(),
-  groups: z.array(z.string().max(256)).max(64).optional(),
+  /**
+   * Who the token acts for: the same `Identity` the local engine takes at
+   * open time. `displayName` becomes the author of the annotations the token
+   * creates, `userId` and `groupId` their owner and group.
+   */
+  identity: IdentitySchema.optional(),
   /**
    * Origin lock: web origins (scheme + host, optional port; one leading
    * `*.` wildcard label allowed) the minted token may be presented
@@ -779,7 +814,7 @@ var adminOperations = {
       403: { contentType: "application/json", schema: AdminErrorPayloadSchema },
       404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
     },
-    notes: "The returned share id IS the public share token. Mounted only when the deployment can sign (HS256 mode) \u2014 exchange mints session JWTs, so grants exist only where minting does."
+    notes: "The returned share id is the public share token. Mounted only when the deployment can sign (HS256 mode) \u2014 exchange mints session JWTs, so grants exist only where minting does."
   },
   "shares.list": {
     operationId: "shares.list",
@@ -867,22 +902,35 @@ var DocLayerParamsSchema = DocIdParamsSchema.extend({
   layerName: z.string().min(1)
 });
 var DocPageParamsSchema = DocLayerParamsSchema.extend({
-  pon: z.coerce.number().int().min(0)
+  pageKey: z.string().min(1).regex(/^obj:[1-9][0-9]*$/).describe(
+    "The page's address, `obj:N`: the page's indirect object number, the durable identity every `PageLayout.ref` carries. Mirrors `annotKey` and `fieldKey`."
+  )
 });
 var DocAnnotationParamsSchema = DocPageParamsSchema.extend({
-  annotKey: z.string().min(1)
+  annotKey: z.string().min(1).regex(/^(obj:[1-9][0-9]*|base:(0|[1-9][0-9]*))$/).describe(
+    "The annotation's address on the page: `obj:N`, its indirect object number, or `base:N` for an annotation the uploaded file stored inline (without an object number of its own), the position it was born at in the page's /Annots. The name the annotation's `ref` carries for life."
+  )
 });
 var DocFieldParamsSchema = DocLayerParamsSchema.extend({
   fieldKey: z.string().min(1)
 });
+var DocAttachmentParamsSchema = DocLayerParamsSchema.extend({
+  fileKey: z.string().min(1).describe(
+    "The embedded file's name-tree key (its `ref.key`), token-text encoded, as `fieldKey` is."
+  )
+});
 var documentPasswordHeader = {
   name: "X-Document-Password",
   required: false,
   description: "Base64-encoded password for an encrypted document. Valid only with the API token (403 anywhere else). An encrypted document answers 422 DocPasswordRequired when the header is absent. Viewer doc JWTs use the SDK password-session flow instead."
 };
+var idempotencyKeyHeader = {
+  name: "Idempotency-Key",
+  required: false,
+  description: "Names the change: 1 to 255 printable ASCII characters. A retry under the same key on the same layer answers with what the first request committed, and changes nothing."
+};
 var looseJson = z.record(z.string(), z.unknown());
 var docCredentials = ["api-token", "doc-jwt"];
-var MutationResponseSchema = z.object({ meta: MutationMetaSchema }).passthrough();
 var DocSigningParamsSchema = DocLayerParamsSchema.extend({
   signingId: z.string().min(1)
 });
@@ -958,6 +1006,74 @@ var docOperations = {
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
   },
+  "doc.metadata.custom.get": {
+    operationId: "doc.metadata.custom.get",
+    title: "Get custom keys",
+    summary: "The Info dictionary's own keys for a layer: every key but the standard fields, as { key: value }.",
+    method: "GET",
+    path: wireTemplates.layerCustomMetadata,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.open"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocLayerParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: CustomMetadataSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.outline.get": {
+    operationId: "doc.outline.get",
+    title: "Get outline",
+    summary: "The document's outline (its bookmarks) for a layer: every item, depth first, with its parent, its target in page space, its look and whether it opens. Edit it with the outline ops of a change.",
+    method: "GET",
+    path: wireTemplates.layerOutline,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.open"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocLayerParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: DocumentOutlineSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.attachments.list": {
+    operationId: "doc.attachments.list",
+    title: "List attachments",
+    summary: "The files embedded in the document (its /EmbeddedFiles) for a layer, in key order: each with its name, type, description, size, checksum and dates, never its bytes. Add and remove them with the attachment ops of a change.",
+    method: "GET",
+    path: wireTemplates.layerAttachments,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.open"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocLayerParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: AttachmentListSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    },
+    notes: "A file-attachment annotation's file is listed with the annotation; read its bytes with `doc.annotations.readFile`."
+  },
+  "doc.attachments.download": {
+    operationId: "doc.attachments.download",
+    title: "Download an attachment",
+    summary: "One embedded file's bytes, decoded. Its name and type are what the listing says; `Content-Type` is its type, or `application/octet-stream` when it has none.",
+    method: "GET",
+    path: wireTemplates.layerAttachmentFile,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.download"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocAttachmentParamsSchema,
+    responses: {
+      200: { contentType: "application/octet-stream" },
+      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema },
+      413: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    },
+    notes: "A file that decodes past the server's limit is refused (PayloadTooLarge)."
+  },
   "doc.signatures.list": {
     operationId: "doc.signatures.list",
     title: "List signatures",
@@ -1012,7 +1128,7 @@ var docOperations = {
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       409: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     },
-    notes: "The multipart envelope: a JSON `body` part (field, subFilter, digest, contentsSize, signer, certify, lock, appearance) and an optional `resource:<key>` PDF part the body's `appearance.resource` names. A certification (`certify.permission`) additionally requires `doc.sign.certify`. The layer is read-only until the signing completes, is aborted, or expires (15 minutes). A layer behind the document head cannot sign (StaleBase)."
+    notes: "Multipart: a JSON `body` part (field, subFilter, digest, contentsSize, signer, certify, lock), naming the appearance PDF it may carry as `resources: { appearance: '<key>' }`, and that PDF as the part `resource:<key>`. A certification (`certify.permission`) additionally requires `doc.sign.certify`. The layer is read-only until the signing completes, is cancelled, or expires (15 minutes). A layer behind the document head cannot sign (StaleBase)."
   },
   "doc.signatures.complete": {
     operationId: "doc.signatures.complete",
@@ -1034,19 +1150,19 @@ var docOperations = {
     },
     notes: "`cms` is the detached CMS over the prepared digest, base64. `expectedVersion` must be what prepare returned. Idempotent by signing id: the same CMS again answers `already-completed`. Every layer of the document then sits over the new version; refetch the manifest after a completion."
   },
-  "doc.signatures.abort": {
-    operationId: "doc.signatures.abort",
-    title: "Abort a signature",
+  "doc.signatures.cancel": {
+    operationId: "doc.signatures.cancel",
+    title: "Cancel a signature",
     summary: "Discard a pending signing candidate.",
     method: "DELETE",
-    path: wireTemplates.layerSignatureAbort,
+    path: wireTemplates.layerSignatureCancel,
     credentials: docCredentials,
     scope: [],
     docCapabilities: ["doc.sign"],
     requestHeaders: [documentPasswordHeader],
     params: DocSigningParamsSchema,
     responses: {
-      200: { contentType: "application/json", schema: SignatureAbortResultSchema },
+      200: { contentType: "application/json", schema: SignatureCancelResultSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
   },
@@ -1213,7 +1329,7 @@ var docOperations = {
     requestHeaders: [documentPasswordHeader],
     params: DocPageParamsSchema,
     responses: {
-      200: { contentType: "application/json", schema: AnnotationListPageSnapshotSchema },
+      200: { contentType: "application/json", schema: AnnotationListSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
   },
@@ -1228,13 +1344,45 @@ var docOperations = {
     docCapabilities: ["doc.annotate.read"],
     requestHeaders: [documentPasswordHeader],
     params: DocLayerParamsSchema,
-    notes: "Returns one entry per page plus the audit-log cursor for reconciling subsequent document events. Page order is unspecified; join by `pageState.pageObjectNumber` when display order matters.",
+    notes: "Returns one entry per page plus the audit-log cursor for reconciling subsequent document events. Page order is unspecified; join by `page` (a `PageRef`) when display order matters.",
     responses: {
-      200: { contentType: "application/json", schema: AnnotationListSnapshotAllPagesSchema },
+      200: { contentType: "application/json", schema: AnnotationListSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       409: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
   },
+  "doc.changes": {
+    operationId: "doc.changes",
+    title: "Apply changes",
+    summary: "Apply user actions to a layer, each a change whose ops apply in order, all or none, or the undo of an earlier change.",
+    method: "POST",
+    path: wireTemplates.layerChanges,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: [
+      "doc.annotate.modify",
+      "doc.attachments.modify",
+      "doc.forms.fill",
+      "doc.forms.modify",
+      "doc.metadata.modify",
+      "doc.outline.modify",
+      "doc.pages.assemble"
+    ],
+    requestHeaders: [documentPasswordHeader],
+    params: DocLayerParamsSchema,
+    body: {
+      contentType: ["application/json", "multipart/form-data"],
+      schema: ChangeRequestSchema
+    },
+    notes: "Each change stands on its own and names itself by `opId`: a refused change rolls back alone, and the answer lists every change in order, applied with its result or refused with its error. Asked again under its `opId`, a change gets the same answer, refusals included; a different change under an answered `opId` is refused (IdempotencyKeyReused). `{ opId, undoOf }` undoes an earlier change of the caller, here or in an earlier request; an undo leaves alone what was changed since, and the undo of an undo redoes. A redaction, a flatten, a form repair or a completed signature ends undo for the changes before it (UndoUnavailable). Each op is checked against its own capability: annotation ops need `doc.annotate.modify`, form values `doc.forms.fill`, form structure `doc.forms.modify`, metadata `doc.metadata.modify`, outline `doc.outline.modify`, pages `doc.pages.assemble`, embedded files `doc.attachments.modify`. Bytes (a stamp's drawing, an attached file, a signature's artwork, a PDF whose pages come in) travel as multipart: a JSON `body` part, each op naming its files by role as `resources: { <role>: '<key>' }`, and each file as the part `resource:<key>`. At most 64 changes per request and 512 ops per change.",
+    responses: {
+      200: { contentType: "application/json", schema: ChangeResponseSchema },
+      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema },
+      409: { contentType: "application/json", schema: EngineErrorPayloadSchema },
+      413: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
   "doc.annotations.create": {
     operationId: "doc.annotations.create",
     title: "Create annotation",
@@ -1244,12 +1392,12 @@ var docOperations = {
     credentials: docCredentials,
     scope: [],
     docCapabilities: ["doc.annotate.modify"],
-    requestHeaders: [documentPasswordHeader],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
     params: DocPageParamsSchema,
     body: { contentType: "application/json", schema: looseJson },
     notes: "Doc JWTs may instead carry collab scopes (annotations:create:self, \u2026) that refine per-annotation authorship rules; the API token is exempt from both.",
     responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
+      200: { contentType: "application/json", schema: AnnotationCreateResultSchema },
       400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
@@ -1263,11 +1411,11 @@ var docOperations = {
     credentials: docCredentials,
     scope: [],
     docCapabilities: ["doc.annotate.modify"],
-    requestHeaders: [documentPasswordHeader],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
     params: DocAnnotationParamsSchema,
     body: { contentType: "application/json", schema: looseJson },
     responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
+      200: { contentType: "application/json", schema: AnnotationUpdateResultSchema },
       400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
@@ -1281,27 +1429,45 @@ var docOperations = {
     credentials: docCredentials,
     scope: [],
     docCapabilities: ["doc.annotate.modify"],
-    requestHeaders: [documentPasswordHeader],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
     params: DocAnnotationParamsSchema,
     responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
+      200: { contentType: "application/json", schema: AnnotationDeleteResultSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.annotations.reorder": {
+    operationId: "doc.annotations.reorder",
+    title: "Reorder annotations",
+    summary: "Change the stacking order of one page's annotations: they go together, in the order given, next to a neighbour annotation (`{ before }`, `{ after }`) or to the bottom (`'start'`) or top (`'end'`). Widgets paint above every annotation and have their own order (`doc.forms.reorderWidgets`): a widget is refused. Returns the page's new order.",
+    method: "POST",
+    path: wireTemplates.layerAnnotationItemsReorder,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.annotate.modify"],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
+    params: DocPageParamsSchema,
+    body: { contentType: "application/json", schema: AnnotationReorderBodySchema },
+    responses: {
+      200: { contentType: "application/json", schema: AnnotationReorderResultSchema },
+      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
   },
   "doc.annotations.flatten": {
     operationId: "doc.annotations.flatten",
     title: "Flatten annotations",
-    summary: "Flatten a chosen set of one page's annotations into its content \u2014 pages.flatten for a selection. Painted annotations are removed; ineligible ones report skipped.",
+    summary: "Flatten a chosen set of one page's annotations into its content \u2014 pages.flatten for a selection. Painted annotations are removed; ineligible ones report unchanged.",
     method: "POST",
     path: wireTemplates.layerAnnotationItemsFlatten,
     credentials: docCredentials,
     scope: [],
     docCapabilities: ["doc.pages.modify", "doc.annotate.modify"],
-    requestHeaders: [documentPasswordHeader],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
     params: DocPageParamsSchema,
     body: { contentType: "application/json", schema: looseJson },
     responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
+      200: { contentType: "application/json", schema: AnnotationFlattenResultSchema },
       400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
@@ -1324,10 +1490,46 @@ var docOperations = {
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
   },
-  "doc.forms.get": {
-    operationId: "doc.forms.get",
-    title: "Get form snapshot",
-    summary: "Reconciled form snapshot: fields, widgets, values.",
+  "doc.annotations.readAppearance": {
+    operationId: "doc.annotations.readAppearance",
+    title: "Read an annotation appearance",
+    summary: "A stamp's drawing as a one-page PDF, before the fit, rotation and opacity its data describes: with the data, the bytes to create the same stamp again. A read; the source is untouched.",
+    method: "GET",
+    path: wireTemplates.layerAnnotationItemAppearanceResource,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.download"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocAnnotationParamsSchema,
+    responses: {
+      200: { contentType: "application/pdf" },
+      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.annotations.readFile": {
+    operationId: "doc.annotations.readFile",
+    title: "Read an attached file",
+    summary: "A file-attachment annotation's file, decoded: its `file` resource. Its name and type are what the annotation's `file` says. A read; the source is untouched.",
+    method: "GET",
+    path: wireTemplates.layerAnnotationItemFileResource,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.download"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocAnnotationParamsSchema,
+    responses: {
+      200: { contentType: "application/octet-stream" },
+      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema },
+      413: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    },
+    notes: "A file that decodes past the server's limit is refused (PayloadTooLarge)."
+  },
+  "doc.forms.list": {
+    operationId: "doc.forms.list",
+    title: "List form fields",
+    summary: "The form: every field with its value, every widget's row (its place, look and state), and the calculation order. A form field's widgets come with the form, never with the annotations.",
     method: "GET",
     path: wireTemplates.layerForm,
     credentials: docCredentials,
@@ -1349,62 +1551,100 @@ var docOperations = {
     credentials: docCredentials,
     scope: [],
     docCapabilities: ["doc.forms.fill"],
-    requestHeaders: [documentPasswordHeader],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
     params: DocFieldParamsSchema,
     body: { contentType: "application/json", schema: looseJson },
     responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
+      200: { contentType: "application/json", schema: FormSetValueResultSchema },
       400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
   },
-  "doc.forms.reset": {
-    operationId: "doc.forms.reset",
-    title: "Reset form field",
-    summary: "Reset one form field to its default value.",
+  "doc.forms.updateWidget": {
+    operationId: "doc.forms.updateWidget",
+    title: "Update form widget",
+    summary: "Change a widget's place and look: what an annotation update takes, for a form field's widget. A widget is the form's, so the annotation routes refuse one.",
+    method: "PATCH",
+    path: wireTemplates.layerFormWidget,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.forms.modify"],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
+    params: DocAnnotationParamsSchema,
+    body: { contentType: "application/json", schema: FormWidgetUpdateBodySchema },
+    responses: {
+      200: { contentType: "application/json", schema: FormWidgetUpdateResultSchema },
+      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.forms.deleteWidget": {
+    operationId: "doc.forms.deleteWidget",
+    title: "Delete form widget",
+    summary: "Delete a widget: it leaves its page, and its field when it has one. The field survives, unplaced when this was its last widget. A widget that is its field's own dictionary is refused: delete the field. A widget is the form's, so the annotation routes refuse one.",
+    method: "DELETE",
+    path: wireTemplates.layerFormWidget,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.forms.modify"],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
+    params: DocAnnotationParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: FormWidgetDeleteResultSchema },
+      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.forms.reorderWidgets": {
+    operationId: "doc.forms.reorderWidgets",
+    title: "Reorder form widgets",
+    summary: "Change the stacking order of one page's widgets: they go together, in the order given, next to a neighbour widget or to the bottom (`'start'`) or top (`'end'`) of the page's widgets, which paint above every annotation. Where the page's `/Tabs` follows it, this is also the tab order. Returns the page's new widget order.",
     method: "POST",
-    path: wireTemplates.layerFormFieldReset,
+    path: wireTemplates.layerFormWidgetsReorder,
     credentials: docCredentials,
     scope: [],
-    docCapabilities: ["doc.forms.fill"],
-    requestHeaders: [documentPasswordHeader],
-    params: DocFieldParamsSchema,
+    docCapabilities: ["doc.forms.modify"],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
+    params: DocPageParamsSchema,
+    body: { contentType: "application/json", schema: FormWidgetsReorderBodySchema },
     responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
+      200: { contentType: "application/json", schema: FormWidgetsReorderResultSchema },
+      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
   },
-  "doc.forms.exportData": {
-    operationId: "doc.forms.exportData",
-    title: "Export form data",
-    summary: "Export form data as FDF or XFDF.",
-    method: "GET",
-    path: wireTemplates.layerFormData,
+  "doc.forms.reorderCalculations": {
+    operationId: "doc.forms.reorderCalculations",
+    title: "Reorder form calculations",
+    summary: "Change the form's calculation order, the order its fields' calculate scripts run in: the fields go together, in the order given, next to a neighbour field or to the start (`'start'`) or end (`'end'`). Every field named must have a calculate script, which puts it in the order. Returns the whole new order.",
+    method: "POST",
+    path: wireTemplates.layerFormCalculationsReorder,
     credentials: docCredentials,
     scope: [],
-    docCapabilities: ["doc.forms.read"],
-    requestHeaders: [documentPasswordHeader],
+    docCapabilities: ["doc.forms.modify"],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
     params: DocLayerParamsSchema,
-    query: z.object({ format: z.enum(["fdf", "xfdf"]).optional() }),
+    body: { contentType: "application/json", schema: FormCalculationsReorderBodySchema },
     responses: {
-      200: { contentType: ["application/vnd.adobe.xfdf", "application/vnd.fdf"] },
+      200: { contentType: "application/json", schema: FormCalculationsReorderResultSchema },
+      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
   },
-  "doc.forms.importData": {
-    operationId: "doc.forms.importData",
-    title: "Import form data",
-    summary: "Import form data (FDF/XFDF), filling matching fields.",
+  "doc.forms.reset": {
+    operationId: "doc.forms.reset",
+    title: "Reset form",
+    summary: "Reset the fields named in `refs` to their default values, or the whole form without it. Returns the fields that changed.",
     method: "POST",
-    path: wireTemplates.layerFormData,
+    path: wireTemplates.layerFormReset,
     credentials: docCredentials,
     scope: [],
     docCapabilities: ["doc.forms.fill"],
-    requestHeaders: [documentPasswordHeader],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
     params: DocLayerParamsSchema,
-    body: { contentType: "application/json", schema: looseJson },
+    body: { contentType: "application/json", schema: FormResetBodySchema },
     responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
+      200: { contentType: "application/json", schema: FormResetResultSchema },
       400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
@@ -1421,7 +1661,7 @@ var docOperations = {
     requestHeaders: [documentPasswordHeader],
     params: DocPageParamsSchema,
     responses: {
-      200: { contentType: "application/json", schema: z.array(PageMeasurementViewportSchema) },
+      200: { contentType: "application/json", schema: PageMeasurementViewportListSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
   },
@@ -1434,7 +1674,7 @@ var docOperations = {
     credentials: docCredentials,
     scope: [],
     docCapabilities: ["doc.annotate.modify"],
-    requestHeaders: [documentPasswordHeader],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
     params: DocPageParamsSchema,
     body: { contentType: "application/json", schema: PageScaleInputSchema },
     responses: {
@@ -1443,60 +1683,6 @@ var docOperations = {
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
   },
-  "doc.pages.move": {
-    operationId: "doc.pages.move",
-    title: "Move pages",
-    summary: "Reorder pages.",
-    method: "POST",
-    path: wireTemplates.layerPagesMove,
-    credentials: docCredentials,
-    scope: [],
-    docCapabilities: ["doc.pages.assemble"],
-    requestHeaders: [documentPasswordHeader],
-    params: DocLayerParamsSchema,
-    body: { contentType: "application/json", schema: looseJson },
-    responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
-      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
-      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
-    }
-  },
-  "doc.pages.rotate": {
-    operationId: "doc.pages.rotate",
-    title: "Rotate pages",
-    summary: "Set absolute rotation on pages.",
-    method: "POST",
-    path: wireTemplates.layerPagesRotate,
-    credentials: docCredentials,
-    scope: [],
-    docCapabilities: ["doc.pages.assemble"],
-    requestHeaders: [documentPasswordHeader],
-    params: DocLayerParamsSchema,
-    body: { contentType: "application/json", schema: looseJson },
-    responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
-      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
-      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
-    }
-  },
-  "doc.pages.delete": {
-    operationId: "doc.pages.delete",
-    title: "Delete pages",
-    summary: "Delete pages.",
-    method: "POST",
-    path: wireTemplates.layerPagesDelete,
-    credentials: docCredentials,
-    scope: [],
-    docCapabilities: ["doc.pages.assemble"],
-    requestHeaders: [documentPasswordHeader],
-    params: DocLayerParamsSchema,
-    body: { contentType: "application/json", schema: looseJson },
-    responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
-      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
-      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
-    }
-  },
   "doc.pages.setName": {
     operationId: "doc.pages.setName",
     title: "Set page name",
@@ -1506,11 +1692,11 @@ var docOperations = {
     credentials: docCredentials,
     scope: [],
     docCapabilities: ["doc.pages.assemble"],
-    requestHeaders: [documentPasswordHeader],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
     params: DocLayerParamsSchema,
     body: { contentType: "application/json", schema: looseJson },
     responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
+      200: { contentType: "application/json", schema: PageNameResultSchema },
       400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
@@ -1524,11 +1710,11 @@ var docOperations = {
     credentials: docCredentials,
     scope: [],
     docCapabilities: ["doc.pages.assemble"],
-    requestHeaders: [documentPasswordHeader],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
     params: DocLayerParamsSchema,
     body: { contentType: "application/json", schema: looseJson },
     responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
+      200: { contentType: "application/json", schema: PageNameResultSchema },
       400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
@@ -1542,55 +1728,15 @@ var docOperations = {
     credentials: docCredentials,
     scope: [],
     docCapabilities: ["doc.pages.modify", "doc.annotate.modify"],
-    requestHeaders: [documentPasswordHeader],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
     params: DocLayerParamsSchema,
     body: { contentType: "application/json", schema: looseJson, required: false },
     responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
+      200: { contentType: "application/json", schema: PageFlattenResultSchema },
       400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
   },
-  "doc.pages.insert": {
-    operationId: "doc.pages.insert",
-    title: "Insert pages from a PDF",
-    summary: "Copy every page of an uploaded PDF into the document at an index.",
-    method: "POST",
-    path: wireTemplates.layerPagesInsert,
-    credentials: docCredentials,
-    scope: [],
-    docCapabilities: ["doc.pages.assemble"],
-    requestHeaders: [documentPasswordHeader],
-    params: DocLayerParamsSchema,
-    body: {
-      contentType: "multipart/form-data"
-    },
-    responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
-      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
-      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
-    },
-    notes: 'Multipart mutation envelope: a `body` field holding `{"destIndex"?: number}` (omitted \u2192 append) plus a `resource:source` file part carrying the standalone PDF whose pages are copied in. The inserted copies get fresh page object numbers, returned in insertion order.'
-  },
-  "doc.pages.insertBlank": {
-    operationId: "doc.pages.insertBlank",
-    title: "Insert blank pages",
-    summary: "Create blank pages of an explicit size at an index.",
-    method: "POST",
-    path: wireTemplates.layerPagesInsertBlank,
-    credentials: docCredentials,
-    scope: [],
-    docCapabilities: ["doc.pages.assemble"],
-    requestHeaders: [documentPasswordHeader],
-    params: DocLayerParamsSchema,
-    body: { contentType: "application/json", schema: looseJson },
-    responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
-      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
-      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
-    },
-    notes: 'Body is `{"size": {"width", "height"}, "count"?, "destIndex"?}` \u2014 size in PDF points, count in [1, 100], destIndex omitted \u2192 append.'
-  },
   "doc.pages.extract": {
     operationId: "doc.pages.extract",
     title: "Extract pages",
@@ -1608,7 +1754,7 @@ var docOperations = {
       400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     },
-    notes: 'A read, not a mutation: the source document is untouched and no event is published. Body is `{"pageObjectNumbers": number[]}`; the response body is the new PDF.'
+    notes: 'A read, not a mutation: the source document is untouched and no event is published. Body is `{"pages": PageRef[], "flatten"?: {"usage"?: "display" | "print"}, "includeAnnotations"?: boolean, "includeFormFields"?: boolean}`; the response body is the new PDF. With `flatten` the copy is the pages as they draw for `usage` (`"print"`: a print copy): the annotations and form fields painted in, nothing interactive left, layers in their state for the usage. A flattened copy takes `doc.download` or `doc.download.flattened`, and paints only what the caller may read; `includeAnnotations` and `includeFormFields` choose what it paints, and are refused without `flatten`.'
   },
   "doc.redactions.apply": {
     operationId: "doc.redactions.apply",
@@ -1619,11 +1765,11 @@ var docOperations = {
     credentials: docCredentials,
     scope: [],
     docCapabilities: ["doc.pages.modify", "doc.annotate.modify", "doc.redact"],
-    requestHeaders: [documentPasswordHeader],
+    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
     params: DocLayerParamsSchema,
-    body: { contentType: "application/json", schema: looseJson, required: false },
+    body: { contentType: "application/json", schema: RedactionApplyScopeSchema },
     responses: {
-      200: { contentType: "application/json", schema: MutationResponseSchema },
+      200: { contentType: "application/json", schema: RedactionApplyResultSchema },
       400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
@@ -1654,8 +1800,11 @@ var docsGroups = {
   shares: { title: "Shares" },
   doc: { title: "Document operations", slug: "document-operations" },
   "doc.annotations": { title: "Annotations" },
+  "doc.attachments": { title: "Attachments" },
   "doc.forms": { title: "Forms" },
   "doc.metadata": { title: "Metadata" },
+  "doc.metadata.custom": { title: "Custom keys" },
+  "doc.outline": { title: "Outline" },
   "doc.pages": { title: "Pages" },
   "doc.redactions": { title: "Redactions" },
   "doc.signatures": { title: "Digital signatures" },
@@ -1681,18 +1830,35 @@ var SECURITY_SCHEME = {
 };
 var ADMIN_ERROR_REF = "#/components/schemas/AdminErrorPayload";
 var ENGINE_ERROR_REF = "#/components/schemas/EngineErrorPayload";
-var SHARED_COMPONENT_SCHEMAS = PdfActionWireComponents;
+var SHARED_COMPONENT_SCHEMAS = sharedComponents([
+  { AdminErrorPayload: AdminErrorPayloadSchema, EngineErrorPayload: EngineErrorPayloadSchema2 },
+  DocumentWireComponents,
+  PdfActionWireComponents,
+  AnnotationWireComponents,
+  FormWireComponents,
+  OutlineWireComponents,
+  AttachmentWireComponents,
+  ChangeWireComponents
+]);
 var SHARED_COMPONENT_BY_DEFINITION = new Map(
   Object.entries(SHARED_COMPONENT_SCHEMAS).map(([name, schema]) => [schema._def, name])
 );
 var SHARED_COMPONENT_REFS = new Set(
   Object.keys(SHARED_COMPONENT_SCHEMAS).map((name) => `#/components/schemas/${name}`)
 );
+function sharedComponents(registries) {
+  const components = {};
+  for (const registry of registries) {
+    for (const [name, schema] of Object.entries(registry)) {
+      if (components[name]) throw new Error(`Duplicate shared component name: ${name}`);
+      components[name] = schema;
+    }
+  }
+  return components;
+}
 function buildAdminOpenApiDocument(opts) {
   const paths = {};
   const schemas = {};
-  registerSchema(schemas, "AdminErrorPayload", AdminErrorPayloadSchema);
-  registerSchema(schemas, "EngineErrorPayload", EngineErrorPayloadSchema2);
   for (const [name, schema] of Object.entries(SHARED_COMPONENT_SCHEMAS)) {
     registerSchema(schemas, name, schema);
   }