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

package/dist/openapi.js

@@ -1,10 +1,12 @@
 // src/openapi.ts
 import {
   AnnotationWireComponents,
+  AttachmentWireComponents,
   ChangeWireComponents,
   DocumentWireComponents,
   EngineErrorPayloadSchema as EngineErrorPayloadSchema2,
   FormWireComponents,
+  OutlineWireComponents,
   PdfActionWireComponents
 } from "@embedpdf/engine-core/wire";
 import { z as z2 } from "zod";
@@ -30,6 +32,7 @@ import {
   DocumentManifestSchema,
   CustomMetadataSchema,
   DocumentMetadataSchema,
+  DocumentOutlineSchema,
   EngineErrorPayloadSchema,
   FormResetBodySchema,
   FormWidgetDeleteResultSchema,
@@ -43,13 +46,8 @@ import {
   FormSetValueResultSchema,
   FormSnapshotSchema,
   IdentitySchema,
-  PageDeleteResultSchema,
   PageFlattenResultSchema,
-  PageInsertResultSchema,
-  PageReorderInputSchema,
-  PageReorderResultSchema,
   PageNameResultSchema,
-  PageRotateResultSchema,
   RedactionApplyResultSchema,
   RedactionApplyScopeSchema,
   PageTextSnapshotSchema,
@@ -60,6 +58,7 @@ import {
   SignatureCompleteResultSchema,
   SignaturePreparedWireSchema,
   SignatureSnapshotSchema,
+  AttachmentListSchema,
   wireTemplates
 } from "@embedpdf/engine-core/wire";
 import { z } from "zod";
@@ -915,6 +914,11 @@ var DocAnnotationParamsSchema = DocPageParamsSchema.extend({
 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,
@@ -1018,6 +1022,58 @@ var docOperations = {
       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",
@@ -1305,9 +1361,12 @@ var docOperations = {
     scope: [],
     docCapabilities: [
       "doc.annotate.modify",
+      "doc.attachments.modify",
       "doc.forms.fill",
       "doc.forms.modify",
-      "doc.metadata.modify"
+      "doc.metadata.modify",
+      "doc.outline.modify",
+      "doc.pages.assemble"
     ],
     requestHeaders: [documentPasswordHeader],
     params: DocLayerParamsSchema,
@@ -1315,7 +1374,7 @@ var docOperations = {
       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`. Bytes (a stamp's drawing, an attached file, a signature's artwork) 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.",
+    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 },
@@ -1448,6 +1507,25 @@ var docOperations = {
       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",
@@ -1605,60 +1683,6 @@ var docOperations = {
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
   },
-  "doc.pages.reorder": {
-    operationId: "doc.pages.reorder",
-    title: "Reorder pages",
-    summary: "Move pages together, in the order given, next to a neighbour page (`{ before }`, `{ after }`) or to the start or end. Returns the new layout.",
-    method: "POST",
-    path: wireTemplates.layerPagesReorder,
-    credentials: docCredentials,
-    scope: [],
-    docCapabilities: ["doc.pages.assemble"],
-    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
-    params: DocLayerParamsSchema,
-    body: { contentType: "application/json", schema: PageReorderInputSchema },
-    responses: {
-      200: { contentType: "application/json", schema: PageReorderResultSchema },
-      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, idempotencyKeyHeader],
-    params: DocLayerParamsSchema,
-    body: { contentType: "application/json", schema: looseJson },
-    responses: {
-      200: { contentType: "application/json", schema: PageRotateResultSchema },
-      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, idempotencyKeyHeader],
-    params: DocLayerParamsSchema,
-    body: { contentType: "application/json", schema: looseJson },
-    responses: {
-      200: { contentType: "application/json", schema: PageDeleteResultSchema },
-      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
-      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
-    }
-  },
   "doc.pages.setName": {
     operationId: "doc.pages.setName",
     title: "Set page name",
@@ -1713,46 +1737,6 @@ var docOperations = {
       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, idempotencyKeyHeader],
-    params: DocLayerParamsSchema,
-    body: {
-      contentType: "multipart/form-data"
-    },
-    responses: {
-      200: { contentType: "application/json", schema: PageInsertResultSchema },
-      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
-      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
-    },
-    notes: 'Multipart: a JSON `body` part `{"position"?: PagePosition, "resources": {"source": "<key>"}}` (position omitted \u2192 the end), and the standalone PDF whose pages are copied in as the part `resource:<key>`. 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 a position.",
-    method: "POST",
-    path: wireTemplates.layerPagesInsertBlank,
-    credentials: docCredentials,
-    scope: [],
-    docCapabilities: ["doc.pages.assemble"],
-    requestHeaders: [documentPasswordHeader, idempotencyKeyHeader],
-    params: DocLayerParamsSchema,
-    body: { contentType: "application/json", schema: looseJson },
-    responses: {
-      200: { contentType: "application/json", schema: PageInsertResultSchema },
-      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
-      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
-    },
-    notes: 'Body is `{"size": {"width", "height"}, "count"?, "position"?}` \u2014 size in PDF points, count in [1, 100], `position` a `PagePosition` (omitted \u2192 the end).'
-  },
   "doc.pages.extract": {
     operationId: "doc.pages.extract",
     title: "Extract pages",
@@ -1770,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 `{"pages": PageRef[]}`; 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",
@@ -1816,9 +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" },
@@ -1850,6 +1836,8 @@ var SHARED_COMPONENT_SCHEMAS = sharedComponents([
   PdfActionWireComponents,
   AnnotationWireComponents,
   FormWireComponents,
+  OutlineWireComponents,
+  AttachmentWireComponents,
   ChangeWireComponents
 ]);
 var SHARED_COMPONENT_BY_DEFINITION = new Map(