@cloudpdf/contract 3.0.0-next.5 → 3.0.0-next.7

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "CloudPDF Engine API",
-    "version": "3.0.0-next.5",
+    "version": "3.0.0-next.7",
     "description": "The backend-callable surface of the CloudPDF document engine: deployment and tenant administration plus the document operations (reads, annotations, forms, page operations, redaction, download). Interactive viewing goes through the CloudPDF viewer SDKs, whose session protocol is deliberately not part of this API. Generated from the @cloudpdf/contract operation registry — do not edit by hand.",
     "license": {
       "name": "Apache-2.0",
@@ -2835,6 +2835,108 @@
         }
       }
     },
+    "/v1/tenants/{tenantId}/documents/import": {
+      "post": {
+        "operationId": "documents.importFrom",
+        "x-fern-sdk-group-name": ["documents"],
+        "x-fern-sdk-method-name": "importFrom",
+        "x-docs-title": "Import document",
+        "summary": "Server-side pull: fetch a PDF from a caller-supplied URL (e.g. a presigned object-store GET) or an operator-registered storage connection into CloudPDF-owned storage, verify it, and commit it.",
+        "description": "Default mode is synchronous and bounded: the response returns only after the transfer verified and committed (or failed). mode=async (connection sources only) answers 202 immediately and an in-process worker performs the transfer with leased, fenced retries; poll the document until ready/failed. The deployment import policy gates scheme, network range, and size; sources must declare a length. CloudPDF copies and owns the bytes — the source is never referenced in place. A 502 marks a retryable upstream failure: retry with the same idempotencyKey to resume the same document. URL sources are capabilities and never echoed back. Connection sources name operator-registered storage (bucket/prefix scope, allowed credential classes, and tenant bindings are deployment configuration); `revision` is provider-interpreted (S3 VersionId, GCS generation, Azure version id).",
+        "security": [
+          {
+            "apiToken": []
+          },
+          {
+            "tenantToken": []
+          }
+        ],
+        "x-required-scope": ["docs.create"],
+        "parameters": [
+          {
+            "name": "tenantId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9_-]+$"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DocumentsImportFromRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DocumentsImportFrom200Response"
+                }
+              }
+            }
+          },
+          "202": {
+            "description": "Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DocumentsImportFrom202Response"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DocumentsImportFrom400Response"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DocumentsImportFrom403Response"
+                }
+              }
+            }
+          },
+          "502": {
+            "description": "Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DocumentsImportFrom502Response"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AdminErrorPayload"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/tenants/{tenantId}/documents/init": {
       "post": {
         "operationId": "documents.init",
@@ -4005,7 +4107,8 @@
           },
           "dedupMode": {
             "type": "string",
-            "enum": ["always-create", "reuse-existing"]
+            "enum": ["always-create", "reuse-existing"],
+            "description": "always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice."
           },
           "docId": {
             "type": "string",
@@ -4393,6 +4496,322 @@
         "required": ["error"],
         "additionalProperties": false
       },
+      "DocumentsImportFromRequest": {
+        "type": "object",
+        "properties": {
+          "source": {
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "enum": ["url"]
+                  },
+                  "url": {
+                    "type": "string",
+                    "format": "uri",
+                    "maxLength": 8192,
+                    "description": "The URL to fetch. Must be allowed by the deployment import policy (scheme, network range, size) and must declare a length."
+                  }
+                },
+                "required": ["kind", "url"],
+                "additionalProperties": false,
+                "description": "The caller supplies the authority: a presigned S3/GCS/Azure/R2/MinIO GET, or any HTTPS endpoint the deployment import policy allows. The URL is a capability — treat it as a secret. CloudPDF never echoes its query string back in errors, logs, or stored failure reasons."
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "enum": ["connection"]
+                  },
+                  "connectionId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128,
+                    "description": "The operator-registered storage connection to read from."
+                  },
+                  "key": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The object key to read, inside the connection's configured scope. At most 1024 UTF-8 bytes."
+                  },
+                  "revision": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 1024,
+                    "description": "Pins a specific version of the object. Provider-interpreted (S3 VersionId, GCS generation, Azure version id); providers without versioning reject it."
+                  }
+                },
+                "required": ["kind", "connectionId", "key"],
+                "additionalProperties": false,
+                "description": "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."
+              }
+            ],
+            "description": "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."
+          },
+          "expected": {
+            "type": "object",
+            "properties": {
+              "sizeBytes": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Checked against the source's declared Content-Length before the transfer."
+              },
+              "sha256": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{64}$",
+                "description": "Checked against the server-observed digest after the transfer. Required when dedupMode is reuse-existing."
+              }
+            },
+            "additionalProperties": false,
+            "description": "Integrity pins, enforced when present. When absent, the server-observed values become authoritative."
+          },
+          "metadata": {
+            "type": "object",
+            "additionalProperties": {}
+          },
+          "idempotencyKey": {
+            "type": "string",
+            "description": "Retrying with the same key resumes the same document rather than importing a second copy — including after a 502."
+          },
+          "dedupMode": {
+            "type": "string",
+            "enum": ["always-create", "reuse-existing"],
+            "description": "always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice."
+          },
+          "docId": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_-]+$"
+          },
+          "mode": {
+            "type": "string",
+            "enum": ["sync", "async"],
+            "description": "sync (default) holds the response open for the whole transfer. async answers 202 with the document pending and transfers in the background; it requires a connection source, and filesystem connections additionally require expected.sha256."
+          }
+        },
+        "required": ["source"],
+        "additionalProperties": false
+      },
+      "DocumentsImportFrom200Response": {
+        "type": "object",
+        "properties": {
+          "tag": {
+            "type": "string",
+            "enum": ["imported", "deduped", "accepted"]
+          },
+          "document": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "tenantId": {
+                "type": "string"
+              },
+              "state": {
+                "type": "string",
+                "enum": ["pending", "ready", "failed", "deleting"]
+              },
+              "baseSha": {
+                "type": "string",
+                "nullable": true
+              },
+              "storageSizeBytes": {
+                "type": "number",
+                "nullable": true
+              },
+              "metadata": {
+                "type": "object",
+                "additionalProperties": {},
+                "nullable": true
+              },
+              "idempotencyKey": {
+                "type": "string",
+                "nullable": true
+              },
+              "failureReason": {
+                "type": "string",
+                "nullable": true
+              },
+              "thumbnailState": {
+                "type": "string",
+                "enum": ["pending", "ready", "locked", "failed"]
+              },
+              "thumbnailUrl": {
+                "type": "string",
+                "nullable": true
+              },
+              "createdAt": {
+                "type": "number"
+              },
+              "updatedAt": {
+                "type": "number"
+              },
+              "createdBy": {
+                "type": "string",
+                "nullable": true
+              }
+            },
+            "required": [
+              "id",
+              "tenantId",
+              "state",
+              "baseSha",
+              "storageSizeBytes",
+              "metadata",
+              "idempotencyKey",
+              "failureReason",
+              "createdAt",
+              "updatedAt",
+              "createdBy"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "required": ["tag", "document"],
+        "additionalProperties": false
+      },
+      "DocumentsImportFrom202Response": {
+        "type": "object",
+        "properties": {
+          "tag": {
+            "type": "string",
+            "enum": ["imported", "deduped", "accepted"]
+          },
+          "document": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "tenantId": {
+                "type": "string"
+              },
+              "state": {
+                "type": "string",
+                "enum": ["pending", "ready", "failed", "deleting"]
+              },
+              "baseSha": {
+                "type": "string",
+                "nullable": true
+              },
+              "storageSizeBytes": {
+                "type": "number",
+                "nullable": true
+              },
+              "metadata": {
+                "type": "object",
+                "additionalProperties": {},
+                "nullable": true
+              },
+              "idempotencyKey": {
+                "type": "string",
+                "nullable": true
+              },
+              "failureReason": {
+                "type": "string",
+                "nullable": true
+              },
+              "thumbnailState": {
+                "type": "string",
+                "enum": ["pending", "ready", "locked", "failed"]
+              },
+              "thumbnailUrl": {
+                "type": "string",
+                "nullable": true
+              },
+              "createdAt": {
+                "type": "number"
+              },
+              "updatedAt": {
+                "type": "number"
+              },
+              "createdBy": {
+                "type": "string",
+                "nullable": true
+              }
+            },
+            "required": [
+              "id",
+              "tenantId",
+              "state",
+              "baseSha",
+              "storageSizeBytes",
+              "metadata",
+              "idempotencyKey",
+              "failureReason",
+              "createdAt",
+              "updatedAt",
+              "createdBy"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "required": ["tag", "document"],
+        "additionalProperties": false
+      },
+      "DocumentsImportFrom400Response": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "object",
+            "properties": {
+              "code": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              }
+            },
+            "required": ["code", "message"],
+            "additionalProperties": false
+          }
+        },
+        "required": ["error"],
+        "additionalProperties": false
+      },
+      "DocumentsImportFrom403Response": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "object",
+            "properties": {
+              "code": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              }
+            },
+            "required": ["code", "message"],
+            "additionalProperties": false
+          }
+        },
+        "required": ["error"],
+        "additionalProperties": false
+      },
+      "DocumentsImportFrom502Response": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "object",
+            "properties": {
+              "code": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              }
+            },
+            "required": ["code", "message"],
+            "additionalProperties": false
+          }
+        },
+        "required": ["error"],
+        "additionalProperties": false
+      },
       "DocumentsList200Response": {
         "type": "object",
         "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudpdf/contract",
-  "version": "3.0.0-next.5",
+  "version": "3.0.0-next.7",
   "private": false,
   "description": "The CloudPDF engine contract: operation registry, Zod schemas, and OpenAPI emitter for every backend-callable surface — used by @cloudpdf/server and the generated @cloudpdf/sdk, and the source of the committed openapi.json.",
   "type": "module",
@@ -42,7 +42,7 @@
   "dependencies": {
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.24.6",
-    "@embedpdf/engine-core": "3.0.0-next.5"
+    "@embedpdf/engine-core": "3.0.0-next.7"
   },
   "devDependencies": {
     "@types/node": "latest",