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

package/dist/openapi.js

@@ -1,10 +1,9 @@
 // src/openapi.ts
-import { zodToJsonSchema } from "zod-to-json-schema";
-import { z as z2 } from "zod";
 import { EngineErrorPayloadSchema as EngineErrorPayloadSchema2 } from "@embedpdf/engine-core/wire";
+import { z as z2 } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
 
 // src/index.ts
-import { z } from "zod";
 import {
   AnnotationListPageSnapshotSchema,
   DocumentHeadSchema,
@@ -16,6 +15,7 @@ import {
   PageTextSnapshotSchema,
   wireTemplates
 } from "@embedpdf/engine-core/wire";
+import { z } from "zod";
 var sha256Hex = /^[0-9a-f]{64}$/i;
 var docIdPattern = /^[A-Za-z0-9_-]+$/;
 var tenantIdPattern = /^[A-Za-z0-9_-]+$/;
@@ -32,6 +32,7 @@ var adminWirePaths = {
   tenant: (tenantId) => `/v1/tenants/${encodeURIComponent(tenantId)}`,
   documents: (tenantId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents`,
   documentsInit: (tenantId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents/init`,
+  documentsImport: (tenantId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents/import`,
   document: (tenantId, docId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents/${encodeURIComponent(docId)}`,
   documentCommit: (tenantId, docId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents/${encodeURIComponent(docId)}/commit`,
   documentUploadProxy: (tenantId, docId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents/${encodeURIComponent(docId)}/upload-proxy`,
@@ -54,7 +55,9 @@ var adminWirePaths = {
   /** Deployment-global singletons: API-token only, no tenant context. */
   deploymentLicenseStatus: "/v1/deployment/license/status"
 };
-var DedupModeSchema = z.enum(["always-create", "reuse-existing"]);
+var DedupModeSchema = z.enum(["always-create", "reuse-existing"]).describe(
+  "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."
+);
 var UploadPreferenceSchema = z.enum(["auto", "presigned", "proxy"]);
 var DocumentStateSchema = z.enum(["pending", "ready", "failed", "deleting"]);
 var AdminDocumentRecordSchema = z.object({
@@ -123,6 +126,79 @@ var AdminDocumentCommitRequestSchema = z.object({
 var AdminDocumentCommitResponseSchema = z.object({
   document: AdminDocumentRecordSchema
 });
+var utf8ByteLength = (s) => new TextEncoder().encode(s).length;
+var AdminImportSourceSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("url"),
+    url: z.string().url().max(8192).describe(
+      "The URL to fetch. Must be allowed by the deployment import policy (scheme, network range, size) and must declare a length."
+    )
+  }).describe(
+    "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 \u2014 treat it as a secret. CloudPDF never echoes its query string back in errors, logs, or stored failure reasons."
+  ),
+  z.object({
+    kind: z.literal("connection"),
+    connectionId: z.string().min(1).max(128).describe("The operator-registered storage connection to read from."),
+    key: z.string().min(1).refine((k) => !k.includes("\0"), "key must not contain NUL").refine((k) => utf8ByteLength(k) <= 1024, "key must be at most 1024 UTF-8 bytes").describe(
+      "The object key to read, inside the connection's configured scope. At most 1024 UTF-8 bytes."
+    ),
+    revision: z.string().min(1).max(1024).optional().describe(
+      "Pins a specific version of the object. Provider-interpreted (S3 VersionId, GCS generation, Azure version id); providers without versioning reject it."
+    )
+  }).describe(
+    "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."
+);
+var AdminDocumentImportRequestSchema = z.object({
+  source: AdminImportSourceSchema,
+  /**
+   * Optional integrity pins, enforced when present: `sizeBytes`
+   * 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
+   * hash the server cannot know what content to reuse.
+   */
+  expected: z.object({
+    sizeBytes: z.number().int().min(1).optional().describe("Checked against the source's declared Content-Length before the transfer."),
+    sha256: z.string().regex(sha256Hex).optional().describe(
+      "Checked against the server-observed digest after the transfer. Required when dedupMode is reuse-existing."
+    )
+  }).optional().describe(
+    "Integrity pins, enforced when present. When absent, the server-observed values become authoritative."
+  ),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  idempotencyKey: z.string().optional().describe(
+    "Retrying with the same key resumes the same document rather than importing a second copy \u2014 including after a 502."
+  ),
+  dedupMode: DedupModeSchema.optional(),
+  docId: z.string().regex(docIdPattern).optional(),
+  /**
+   * `sync` (default) holds the response open for the whole transfer.
+   * `async` accepts the request (202, document `pending`), transfers
+   * in the background, and the caller polls the document. Async
+   * requires a `connection` source (URLs are secrets and expire, so
+   * they cannot sit in a durable job); filesystem connections
+   * additionally require `expected.sha256`, since they have no
+   * revisions to pin retries to.
+   */
+  mode: z.enum(["sync", "async"]).optional().describe(
+    "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."
+  )
+});
+var AdminDocumentImportResponseSchema = z.object({
+  /**
+   * `imported` — bytes were pulled, verified, and committed (sync).
+   * `deduped`  — an existing document satisfied the request without a
+   * transfer (content dedup or idempotent replay).
+   * `accepted` — async: the job is queued (HTTP 202); poll the
+   * document until `ready` or `failed`.
+   */
+  tag: z.enum(["imported", "deduped", "accepted"]),
+  document: AdminDocumentRecordSchema
+});
 var AdminDocumentResponseSchema = z.object({
   document: AdminDocumentRecordSchema
 });
@@ -480,6 +556,25 @@ var adminOperations = {
     },
     notes: "This bounded origin-mediated fallback must only be used after documents.init returns upload.kind=proxy. Auto mode prefers a presigned object-store PUT whenever available."
   },
+  "documents.importFrom": {
+    operationId: "documents.importFrom",
+    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.",
+    method: "POST",
+    path: "/v1/tenants/:tenantId/documents/import",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["docs.create"],
+    params: AdminTenantParamsSchema,
+    body: { contentType: "application/json", schema: AdminDocumentImportRequestSchema },
+    responses: {
+      200: { contentType: "application/json", schema: AdminDocumentImportResponseSchema },
+      202: { contentType: "application/json", schema: AdminDocumentImportResponseSchema },
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      403: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      502: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    },
+    notes: "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 \u2014 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)."
+  },
   "documents.list": {
     operationId: "documents.list",
     title: "List documents",
@@ -1231,12 +1326,54 @@ function operationObject(op, schemas) {
   };
   return out;
 }
+var RESERVED_SDK_SEGMENTS = [
+  [
+    "Java",
+    /* @__PURE__ */ new Set([
+      ...["abstract", "assert", "boolean", "break", "byte", "case", "catch", "char", "class"],
+      ...["const", "continue", "default", "do", "double", "else", "enum", "extends", "final"],
+      ...["finally", "float", "for", "goto", "if", "implements", "import", "instanceof", "int"],
+      ...["interface", "long", "native", "new", "package", "private", "protected", "public"],
+      ...["return", "short", "static", "strictfp", "super", "switch", "synchronized", "this"],
+      ...["throw", "throws", "transient", "try", "void", "volatile", "while"],
+      ...["true", "false", "null"]
+    ])
+  ],
+  [
+    "Python",
+    /* @__PURE__ */ new Set([
+      ...["False", "None", "True", "and", "as", "assert", "async", "await", "break", "class"],
+      ...["continue", "def", "del", "elif", "else", "except", "finally", "for", "from"],
+      ...["global", "if", "import", "in", "is", "lambda", "nonlocal", "not", "or", "pass"],
+      ...["raise", "return", "try", "while", "with", "yield"]
+    ])
+  ],
+  [
+    "Ruby",
+    /* @__PURE__ */ new Set([
+      ...["alias", "and", "begin", "break", "case", "class", "def", "do", "else", "elsif"],
+      ...["end", "ensure", "false", "for", "if", "in", "module", "next", "nil", "not", "or"],
+      ...["redo", "rescue", "retry", "return", "self", "super", "then", "true", "undef"],
+      ...["unless", "until", "when", "while", "yield"]
+    ])
+  ]
+];
 function sdkOperationName(operationId) {
   const parts = operationId.split(".");
   const method = parts.pop();
   if (!method || parts.length === 0) {
     throw new Error(`Operation ID must use resource.method form: ${operationId}`);
   }
+  for (const segment of [...parts, method]) {
+    const collisions = RESERVED_SDK_SEGMENTS.filter(([, words]) => words.has(segment)).map(
+      ([language]) => language
+    );
+    if (collisions.length > 0) {
+      throw new Error(
+        `Operation "${operationId}" cannot use "${segment}" as an SDK name segment: it is a reserved word in ${collisions.join(" and ")}, so SDK generators would rename or reject it. Pick a compound name instead (e.g. importFrom rather than import).`
+      );
+    }
+  }
   return { groups: parts, method };
 }
 function headerParameters(op) {
@@ -1376,6 +1513,7 @@ function sortKeys(obj) {
   return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
 }
 export {
-  buildAdminOpenApiDocument
+  buildAdminOpenApiDocument,
+  sdkOperationName
 };
 //# sourceMappingURL=openapi.js.map