@cloudpdf/contract 3.0.0-next.1

package/dist/openapi.js

@@ -0,0 +1,1029 @@
+// 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";
+
+// src/index.ts
+import { z } from "zod";
+import {
+  AnnotationListPageSnapshotSchema,
+  DocumentHeadSchema,
+  DocumentManifestSchema,
+  DocumentMetadataSchema,
+  EngineErrorPayloadSchema,
+  FormSnapshotSchema,
+  MutationMetaSchema,
+  PageTextSnapshotSchema,
+  wireTemplates
+} from "@embedpdf/engine-core/wire";
+var sha256Hex = /^[0-9a-f]{64}$/i;
+var docIdPattern = /^[A-Za-z0-9_-]+$/;
+var tenantIdPattern = /^[A-Za-z0-9_-]+$/;
+var adminWirePaths = {
+  tenants: "/v1/tenants",
+  tenant: (tenantId) => `/v1/tenants/${encodeURIComponent(tenantId)}`,
+  documents: (tenantId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents`,
+  documentsInit: (tenantId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents/init`,
+  document: (tenantId, docId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents/${encodeURIComponent(docId)}`,
+  documentCommit: (tenantId, docId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents/${encodeURIComponent(docId)}/commit`,
+  documentUploadDirect: (tenantId, docId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents/${encodeURIComponent(docId)}/upload-direct`,
+  documentDownload: (tenantId, docId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents/${encodeURIComponent(docId)}/download`,
+  /** The warmed dashboard-tile artifact. Returns 404 while `pending`/`locked`. */
+  documentThumbnail: (tenantId, docId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents/${encodeURIComponent(docId)}/thumbnail`,
+  tokenIssue: (tenantId) => `/v1/tenants/${encodeURIComponent(tenantId)}/tokens`,
+  tokenRevoke: (tenantId, jti) => `/v1/tenants/${encodeURIComponent(tenantId)}/tokens/${encodeURIComponent(jti)}/revoke`,
+  /** Deployment-global singletons: API-token only, no tenant context. */
+  deploymentLicenseStatus: "/v1/deployment/license/status"
+};
+var DedupModeSchema = z.enum(["always-create", "reuse-existing"]);
+var DocumentStateSchema = z.enum(["pending", "ready", "failed", "deleting"]);
+var AdminDocumentRecordSchema = z.object({
+  id: z.string(),
+  tenantId: z.string(),
+  state: DocumentStateSchema,
+  baseSha: z.string().nullable(),
+  storageSizeBytes: z.number().nullable(),
+  metadata: z.record(z.string(), z.unknown()).nullable(),
+  idempotencyKey: z.string().nullable(),
+  failureReason: z.string().nullable(),
+  /** Dashboard tile lifecycle. Optional because older servers omit these fields. */
+  thumbnailState: z.enum(["pending", "ready", "locked", "failed"]).optional(),
+  thumbnailUrl: z.string().nullable().optional(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  createdBy: z.string().nullable()
+});
+var AdminDocumentInitRequestSchema = z.object({
+  contentLength: z.number().finite().min(1),
+  contentSha256: z.string().regex(sha256Hex),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  idempotencyKey: z.string().optional(),
+  dedupMode: DedupModeSchema.optional(),
+  docId: z.string().regex(docIdPattern).optional(),
+  uploadTtlSec: z.number().finite().min(60).max(3600).optional()
+});
+var AdminPresignedUploadSchema = z.object({
+  url: z.string(),
+  headers: z.record(z.string(), z.string()),
+  method: z.literal("PUT"),
+  expiresAt: z.number()
+});
+var AdminInitUploadSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("presigned"),
+    presigned: AdminPresignedUploadSchema,
+    key: z.string()
+  }),
+  z.object({
+    kind: z.literal("direct"),
+    url: z.string(),
+    key: z.string()
+  })
+]);
+var AdminDocumentInitResponseSchema = z.discriminatedUnion("tag", [
+  z.object({
+    tag: z.literal("created"),
+    document: AdminDocumentRecordSchema,
+    upload: AdminInitUploadSchema
+  }),
+  z.object({
+    tag: z.literal("resumed"),
+    document: AdminDocumentRecordSchema,
+    upload: AdminInitUploadSchema
+  }),
+  z.object({
+    tag: z.literal("deduped"),
+    document: AdminDocumentRecordSchema
+  })
+]);
+var AdminDocumentCommitRequestSchema = z.object({
+  sha256: z.string().regex(sha256Hex)
+});
+var AdminDocumentCommitResponseSchema = z.object({
+  document: AdminDocumentRecordSchema
+});
+var AdminDocumentResponseSchema = z.object({
+  document: AdminDocumentRecordSchema
+});
+var ADMIN_DOCUMENT_LIST_DEFAULT_LIMIT = 100;
+var ADMIN_DOCUMENT_LIST_MAX_LIMIT = 200;
+var AdminDocumentListQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(ADMIN_DOCUMENT_LIST_MAX_LIMIT).default(ADMIN_DOCUMENT_LIST_DEFAULT_LIMIT),
+  cursor: z.string().min(1).optional(),
+  state: DocumentStateSchema.optional()
+});
+var AdminDocumentListResponseSchema = z.object({
+  documents: z.array(AdminDocumentRecordSchema),
+  /**
+   * Opaque cursor for the next page; `null` on the last page. Optional
+   * because pre-pagination servers omit it — clients treat absence as
+   * "no continuation available", same convention as the thumbnail fields.
+   */
+  nextCursor: z.string().nullable().optional()
+});
+var AdminUploadDirectResponseSchema = z.object({
+  sha256: z.string().regex(sha256Hex)
+});
+var AdminErrorPayloadSchema = z.object({
+  error: z.object({
+    code: z.string(),
+    message: z.string()
+  })
+});
+var AdminThumbnailUnavailablePayloadSchema = z.object({
+  error: z.object({
+    code: z.string(),
+    message: z.string(),
+    state: z.string()
+  })
+});
+var AdminTenantParamsSchema = z.object({
+  tenantId: z.string().regex(tenantIdPattern)
+});
+var AdminTenantDocParamsSchema = z.object({
+  tenantId: z.string().regex(tenantIdPattern),
+  id: z.string().regex(docIdPattern)
+});
+var AdminTenantJtiParamsSchema = z.object({
+  tenantId: z.string().regex(tenantIdPattern),
+  jti: z.string().min(1).max(256)
+});
+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
+   * once the token would have expired anyway. Defaults server-side to
+   * now + 30 days.
+   */
+  expiresAtSeconds: z.number().int().positive().optional()
+});
+var AdminLicenseStatusResponseSchema = z.object({
+  license: z.unknown(),
+  reporting: z.unknown().nullable(),
+  usage: z.unknown().nullable()
+});
+var AdminTenantRecordSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  /** True when the namespace materialized on first use rather than via explicit create. */
+  autoProvisioned: z.boolean(),
+  createdAt: z.number()
+});
+var AdminTenantCreateRequestSchema = z.object({
+  id: z.string().regex(tenantIdPattern),
+  /** Display name; defaults to the id. */
+  name: z.string().min(1).max(256).optional()
+});
+var AdminTenantCreateResponseSchema = z.object({
+  tenant: AdminTenantRecordSchema,
+  /** False when the tenant already existed — create is ensure-style. */
+  created: z.boolean()
+});
+var AdminTenantResponseSchema = z.object({
+  tenant: AdminTenantRecordSchema
+});
+var AdminTenantListQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(ADMIN_DOCUMENT_LIST_MAX_LIMIT).default(ADMIN_DOCUMENT_LIST_DEFAULT_LIMIT),
+  cursor: z.string().min(1).optional()
+});
+var AdminTenantListResponseSchema = z.object({
+  tenants: z.array(AdminTenantRecordSchema),
+  /** Opaque cursor for the next page; `null` on the last page. */
+  nextCursor: z.string().nullable().optional()
+});
+var adminTenantScopes = [
+  "docs.create",
+  "docs.read",
+  "docs.delete",
+  "tokens.issue-doc",
+  "tokens.revoke"
+];
+var AdminTokenIssueDocRequestSchema = z.object({
+  kind: z.literal("doc"),
+  /** Subject of the minted token — the end user's id in your system. */
+  sub: z.string().min(1).max(256),
+  docId: z.string().regex(docIdPattern),
+  layerName: z.string().min(1).max(256).optional(),
+  /**
+   * Doc capability scopes (`doc.open`, `doc.render`, …, plus the
+   * collab grammar). Validated server-side against the engine's scope
+   * 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(),
+  /** Token lifetime in seconds. */
+  expiresIn: z.number().int().min(60).max(60 * 60 * 24 * 90)
+});
+var AdminTokenIssueTenantRequestSchema = z.object({
+  kind: z.literal("tenant"),
+  sub: z.string().min(1).max(256),
+  scope: z.array(z.union([z.literal("*"), z.enum(adminTenantScopes)])).min(1).max(16),
+  /** Token lifetime in seconds. */
+  expiresIn: z.number().int().min(60).max(60 * 60 * 24 * 90)
+});
+var AdminTokenIssueRequestSchema = z.discriminatedUnion("kind", [
+  AdminTokenIssueDocRequestSchema,
+  AdminTokenIssueTenantRequestSchema
+]);
+var AdminTokenIssueResponseSchema = z.object({
+  token: z.string(),
+  jti: z.string(),
+  /** Unix seconds. */
+  expiresAt: z.number()
+});
+var adminOperations = {
+  "tenants.create": {
+    operationId: "tenants.create",
+    summary: "Create a tenant, or confirm it already exists \u2014 ensure-style, idempotent.",
+    method: "POST",
+    path: adminWirePaths.tenants,
+    credentials: ["api-token"],
+    scope: [],
+    body: { contentType: "application/json", schema: AdminTenantCreateRequestSchema },
+    responses: {
+      200: { contentType: "application/json", schema: AdminTenantCreateResponseSchema },
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "tenants.list": {
+    operationId: "tenants.list",
+    summary: "List tenants, newest first, cursor-paginated.",
+    method: "GET",
+    path: adminWirePaths.tenants,
+    credentials: ["api-token"],
+    scope: [],
+    query: AdminTenantListQuerySchema,
+    responses: {
+      200: { contentType: "application/json", schema: AdminTenantListResponseSchema },
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "tenants.get": {
+    operationId: "tenants.get",
+    summary: "Fetch one tenant record.",
+    method: "GET",
+    path: "/v1/tenants/:tenantId",
+    credentials: ["api-token"],
+    scope: [],
+    params: AdminTenantParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: AdminTenantResponseSchema },
+      404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "tenants.delete": {
+    operationId: "tenants.delete",
+    summary: "Delete a tenant and everything under it.",
+    method: "DELETE",
+    path: "/v1/tenants/:tenantId",
+    credentials: ["api-token"],
+    scope: [],
+    params: AdminTenantParamsSchema,
+    responses: {
+      204: {},
+      404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    },
+    notes: "Destroys the tenant and everything in its namespace \u2014 documents, layers, stored bytes, audit history. Irreversible."
+  },
+  "documents.init": {
+    operationId: "documents.init",
+    summary: "Begin an upload: create (or resume/dedupe) a pending document and issue upload access.",
+    method: "POST",
+    path: "/v1/tenants/:tenantId/documents/init",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["docs.create"],
+    params: AdminTenantParamsSchema,
+    body: { contentType: "application/json", schema: AdminDocumentInitRequestSchema },
+    responses: {
+      200: { contentType: "application/json", schema: AdminDocumentInitResponseSchema },
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "documents.commit": {
+    operationId: "documents.commit",
+    summary: "Finish an upload: verify the SHA-256 and promote the document to ready.",
+    method: "POST",
+    path: "/v1/tenants/:tenantId/documents/:id/commit",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["docs.create"],
+    params: AdminTenantDocParamsSchema,
+    body: { contentType: "application/json", schema: AdminDocumentCommitRequestSchema },
+    responses: {
+      200: { contentType: "application/json", schema: AdminDocumentCommitResponseSchema },
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "documents.uploadDirect": {
+    operationId: "documents.uploadDirect",
+    summary: "Upload the PDF bytes through the origin instead of a presigned URL.",
+    method: "POST",
+    path: "/v1/tenants/:tenantId/documents/:id/upload-direct",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["docs.create"],
+    params: AdminTenantDocParamsSchema,
+    body: {
+      contentType: ["application/pdf", "application/octet-stream", "multipart/form-data"]
+    },
+    responses: {
+      200: { contentType: "application/json", schema: AdminUploadDirectResponseSchema },
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "documents.list": {
+    operationId: "documents.list",
+    summary: "List documents in the tenant, newest first, cursor-paginated.",
+    method: "GET",
+    path: "/v1/tenants/:tenantId/documents",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["docs.read"],
+    params: AdminTenantParamsSchema,
+    query: AdminDocumentListQuerySchema,
+    responses: {
+      200: { contentType: "application/json", schema: AdminDocumentListResponseSchema },
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "documents.get": {
+    operationId: "documents.get",
+    summary: "Fetch one document record.",
+    method: "GET",
+    path: "/v1/tenants/:tenantId/documents/:id",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["docs.read"],
+    params: AdminTenantDocParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: AdminDocumentResponseSchema },
+      403: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "documents.download": {
+    operationId: "documents.download",
+    summary: "Download the stored base PDF bytes.",
+    method: "GET",
+    path: "/v1/tenants/:tenantId/documents/:id/download",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["docs.read"],
+    params: AdminTenantDocParamsSchema,
+    responses: {
+      200: { contentType: "application/pdf" },
+      403: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "documents.delete": {
+    operationId: "documents.delete",
+    summary: "Delete a document and its stored artifacts.",
+    method: "DELETE",
+    path: "/v1/tenants/:tenantId/documents/:id",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["docs.delete"],
+    params: AdminTenantDocParamsSchema,
+    responses: {
+      204: {},
+      403: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "documents.thumbnail": {
+    operationId: "documents.thumbnail",
+    summary: "Fetch the warmed dashboard-tile render for a document.",
+    method: "GET",
+    path: "/v1/tenants/:tenantId/documents/:id/thumbnail",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["docs.read"],
+    params: AdminTenantDocParamsSchema,
+    responses: {
+      200: { contentType: ["image/webp", "image/png"] },
+      404: { contentType: "application/json", schema: AdminThumbnailUnavailablePayloadSchema }
+    }
+  },
+  "deployment.licenseStatus": {
+    operationId: "deployment.licenseStatus",
+    summary: "License decision plus usage-reporting and meter snapshots for this deployment.",
+    method: "GET",
+    path: adminWirePaths.deploymentLicenseStatus,
+    credentials: ["api-token"],
+    scope: [],
+    responses: {
+      200: { contentType: "application/json", schema: AdminLicenseStatusResponseSchema }
+    }
+  },
+  "tokens.issue": {
+    operationId: "tokens.issue",
+    summary: "Mint a delegated JWT: a doc token, or (API token only) a tenant token.",
+    method: "POST",
+    path: "/v1/tenants/:tenantId/tokens",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["tokens.issue-doc"],
+    params: AdminTenantParamsSchema,
+    body: { contentType: "application/json", schema: AdminTokenIssueRequestSchema },
+    responses: {
+      200: { contentType: "application/json", schema: AdminTokenIssueResponseSchema },
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      403: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    },
+    notes: 'kind "tenant" requires the API token \u2014 authority mints only downward. Mounted only when the deployment can sign (HS256 mode); asymmetric deployments mint with their own private key.'
+  },
+  "tokens.revoke": {
+    operationId: "tokens.revoke",
+    summary: "Revoke a token by jti; live sessions drop on their next heartbeat.",
+    method: "POST",
+    path: "/v1/tenants/:tenantId/tokens/:jti/revoke",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["tokens.revoke"],
+    params: AdminTenantJtiParamsSchema,
+    body: {
+      contentType: "application/json",
+      schema: AdminTokenRevokeRequestSchema,
+      required: false
+    },
+    responses: {
+      204: {},
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    },
+    notes: "Mounted only when the deployment enables token revocation."
+  }
+};
+var DocIdParamsSchema = z.object({
+  docId: z.string().regex(docIdPattern)
+});
+var DocLayerParamsSchema = DocIdParamsSchema.extend({
+  layerName: z.string().min(1)
+});
+var DocPageParamsSchema = DocLayerParamsSchema.extend({
+  pon: z.coerce.number().int().min(0)
+});
+var DocAnnotationParamsSchema = DocPageParamsSchema.extend({
+  annotKey: z.string().min(1)
+});
+var DocFieldParamsSchema = DocLayerParamsSchema.extend({
+  fieldKey: z.string().min(1)
+});
+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 looseJson = z.record(z.string(), z.unknown());
+var docCredentials = ["api-token", "doc-jwt"];
+var MutationResponseSchema = z.object({ meta: MutationMetaSchema }).passthrough();
+var docOperations = {
+  "doc.head": {
+    operationId: "doc.head",
+    summary: "Open a document and return its head (versions, page count, security).",
+    method: "GET",
+    path: wireTemplates.docHead,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.open"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocIdParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: DocumentHeadSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.manifest": {
+    operationId: "doc.manifest",
+    summary: "Full layer manifest at the layer's current version.",
+    method: "GET",
+    path: wireTemplates.layerManifest,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.open"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocLayerParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: DocumentManifestSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.metadata.get": {
+    operationId: "doc.metadata.get",
+    summary: "Document metadata (PDF info dictionary view) for a layer.",
+    method: "GET",
+    path: wireTemplates.layerMetadata,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.open"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocLayerParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: DocumentMetadataSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.render": {
+    operationId: "doc.render",
+    summary: "Render one page as an image at the current layer version.",
+    method: "GET",
+    path: wireTemplates.layerRenderPage,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.render"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocPageParamsSchema,
+    notes: "Render parameters (viewport, format) pass as flat dotted query keys, e.g. `?viewport.kind=width&viewport.width=800`; the full grammar is documented with the viewer.",
+    responses: {
+      200: { contentType: "image/webp" },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.text": {
+    operationId: "doc.text",
+    summary: "Extracted text content for one page.",
+    method: "GET",
+    path: wireTemplates.layerTextPage,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.text.copy"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocPageParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: PageTextSnapshotSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.annotations.list": {
+    operationId: "doc.annotations.list",
+    summary: "One page's annotations at the current layer version.",
+    method: "GET",
+    path: wireTemplates.layerAnnotationItems,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.annotate.read"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocPageParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: AnnotationListPageSnapshotSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.annotations.create": {
+    operationId: "doc.annotations.create",
+    summary: "Create an annotation on a page.",
+    method: "POST",
+    path: wireTemplates.layerAnnotationItems,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.annotate.modify"],
+    requestHeaders: [documentPasswordHeader],
+    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 },
+      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.annotations.update": {
+    operationId: "doc.annotations.update",
+    summary: "Update one annotation by key.",
+    method: "PATCH",
+    path: wireTemplates.layerAnnotationItem,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.annotate.modify"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocAnnotationParamsSchema,
+    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.annotations.delete": {
+    operationId: "doc.annotations.delete",
+    summary: "Delete one annotation by key.",
+    method: "DELETE",
+    path: wireTemplates.layerAnnotationItem,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.annotate.modify"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocAnnotationParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: MutationResponseSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.forms.get": {
+    operationId: "doc.forms.get",
+    summary: "Reconciled form snapshot: fields, widgets, values.",
+    method: "GET",
+    path: wireTemplates.layerForm,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.forms.read"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocLayerParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: FormSnapshotSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.forms.setValue": {
+    operationId: "doc.forms.setValue",
+    summary: "Set one form field's value.",
+    method: "POST",
+    path: wireTemplates.layerFormFieldValue,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.forms.fill"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocFieldParamsSchema,
+    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.forms.reset": {
+    operationId: "doc.forms.reset",
+    summary: "Reset one form field to its default value.",
+    method: "POST",
+    path: wireTemplates.layerFormFieldReset,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.forms.fill"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocFieldParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: MutationResponseSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.forms.exportData": {
+    operationId: "doc.forms.exportData",
+    summary: "Export form data as FDF or XFDF.",
+    method: "GET",
+    path: wireTemplates.layerFormData,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.forms.read"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocLayerParamsSchema,
+    query: z.object({ format: z.enum(["fdf", "xfdf"]).optional() }),
+    responses: {
+      200: { contentType: ["application/vnd.adobe.xfdf", "application/vnd.fdf"] },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.forms.importData": {
+    operationId: "doc.forms.importData",
+    summary: "Import form data (FDF/XFDF), filling matching fields.",
+    method: "POST",
+    path: wireTemplates.layerFormData,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.forms.fill"],
+    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.move": {
+    operationId: "doc.pages.move",
+    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",
+    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",
+    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.flatten": {
+    operationId: "doc.pages.flatten",
+    summary: "Flatten annotations and form fields into page content.",
+    method: "POST",
+    path: wireTemplates.layerPagesFlatten,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.pages.modify", "doc.annotate.modify"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocLayerParamsSchema,
+    body: { contentType: "application/json", schema: looseJson, required: false },
+    responses: {
+      200: { contentType: "application/json", schema: MutationResponseSchema },
+      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.redactions.apply": {
+    operationId: "doc.redactions.apply",
+    summary: "Apply pending redactions, permanently removing content.",
+    method: "POST",
+    path: wireTemplates.layerRedactionsApply,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.pages.modify", "doc.annotate.modify", "doc.redact"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocLayerParamsSchema,
+    body: { contentType: "application/json", schema: looseJson, required: false },
+    responses: {
+      200: { contentType: "application/json", schema: MutationResponseSchema },
+      400: { contentType: "application/json", schema: EngineErrorPayloadSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
+  "doc.download": {
+    operationId: "doc.download",
+    summary: "Download the layer's current PDF (base plus layer edits).",
+    method: "GET",
+    path: wireTemplates.layerDownload,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.download"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocLayerParamsSchema,
+    responses: {
+      200: { contentType: "application/pdf" },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  }
+};
+var allOperations = { ...adminOperations, ...docOperations };
+
+// src/openapi.ts
+var STATUS_TEXT = {
+  200: "OK",
+  204: "No content",
+  400: "Bad request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not found",
+  409: "Conflict",
+  422: "Unprocessable"
+};
+var SECURITY_SCHEME = {
+  "api-token": "apiToken",
+  "tenant-jwt": "tenantToken",
+  "doc-jwt": "docToken"
+};
+var ADMIN_ERROR_REF = "#/components/schemas/AdminErrorPayload";
+var ENGINE_ERROR_REF = "#/components/schemas/EngineErrorPayload";
+function buildAdminOpenApiDocument(opts) {
+  const paths = {};
+  const schemas = {};
+  registerSchema(schemas, "AdminErrorPayload", AdminErrorPayloadSchema);
+  registerSchema(schemas, "EngineErrorPayload", EngineErrorPayloadSchema2);
+  for (const op of Object.values(allOperations)) {
+    const openApiPath = toOpenApiPath(op.path);
+    const method = op.method.toLowerCase();
+    const entry = paths[openApiPath] ??= {};
+    entry[method] = operationObject(op, schemas);
+  }
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: "CloudPDF Engine API",
+      version: opts.version,
+      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 \u2014 do not edit by hand.",
+      license: { name: "Apache-2.0", identifier: "Apache-2.0" }
+    },
+    paths: sortKeys(paths),
+    components: {
+      securitySchemes: {
+        apiToken: {
+          type: "http",
+          scheme: "bearer",
+          description: "The deployment's static root credential (CLOUDPDF_API_AUTH_TOKENS), valid on every surface."
+        },
+        tenantToken: {
+          type: "http",
+          scheme: "bearer",
+          bearerFormat: "JWT",
+          description: "Delegated tenant JWT, valid only under its own /v1/tenants/{tenantId}/ subtree \u2014 the path tenant must equal the token's tenant_id. Doc-scoped viewer tokens are rejected on every admin route."
+        },
+        docToken: {
+          type: "http",
+          scheme: "bearer",
+          bearerFormat: "JWT",
+          description: "Doc-scoped JWT, valid only on the /v1/docs/{docId} subtree it names, gated by the capability scopes it carries (each operation's x-required-capability)."
+        }
+      },
+      schemas
+    }
+  };
+}
+function operationObject(op, schemas) {
+  const parameters = [...pathParameters(op), ...queryParameters(op), ...headerParameters(op)];
+  const sdkName = sdkOperationName(op.operationId);
+  const out = {
+    operationId: op.operationId,
+    "x-fern-sdk-group-name": sdkName.groups,
+    "x-fern-sdk-method-name": sdkName.method,
+    summary: op.summary,
+    ...op.notes ? { description: op.notes } : {},
+    security: op.credentials.map((credential) => ({ [SECURITY_SCHEME[credential]]: [] })),
+    "x-required-scope": [...op.scope],
+    ...op.docCapabilities ? { "x-required-capability": [...op.docCapabilities] } : {},
+    ...parameters.length > 0 ? { parameters } : {},
+    ...op.body ? { requestBody: requestBody(op, op.body, schemas) } : {},
+    responses: responses(op, schemas)
+  };
+  return out;
+}
+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}`);
+  }
+  return { groups: parts, method };
+}
+function headerParameters(op) {
+  if (!op.requestHeaders) return [];
+  return op.requestHeaders.map((header) => ({
+    name: header.name,
+    in: "header",
+    required: header.required ?? false,
+    description: header.description,
+    schema: { type: "string" }
+  }));
+}
+function pathParameters(op) {
+  const names = [...op.path.matchAll(/:([A-Za-z0-9_]+)/g)].map((m) => m[1]);
+  const shape = op.params ? objectShape(op.params) : {};
+  return names.map((name) => ({
+    name,
+    in: "path",
+    required: true,
+    schema: shape[name] ? inlineSchemaOf(shape[name]) : { type: "string" }
+  }));
+}
+function queryParameters(op) {
+  if (!op.query) return [];
+  return Object.entries(objectShape(op.query)).map(([name, prop]) => ({
+    name,
+    in: "query",
+    required: !prop.isOptional(),
+    // Optionality is carried by `required` above; strip the ZodOptional
+    // wrapper so the schema describes the value's shape rather than
+    // `T | undefined` (which converts to a meaningless anyOf/not).
+    schema: inlineSchemaOf(unwrapOptional(prop))
+  }));
+}
+function unwrapOptional(schema) {
+  let current = schema;
+  while (current instanceof z2.ZodOptional) current = current.unwrap();
+  return current;
+}
+function requestBody(op, body, schemas) {
+  const schema = body.schema ? registerSchema(schemas, `${sdkTypeName(op.operationId)}Request`, body.schema) : void 0;
+  return {
+    required: body.required ?? true,
+    content: contentObject(body.contentType, schema)
+  };
+}
+function responses(op, schemas) {
+  const out = {};
+  const typedResponses = Object.values(op.responses).filter((response) => response.schema).length;
+  for (const [status, response] of Object.entries(op.responses)) {
+    const schema = response.schema ? registerSchema(
+      schemas,
+      `${sdkTypeName(op.operationId)}${typedResponses > 1 ? status : ""}Response`,
+      response.schema
+    ) : void 0;
+    out[status] = {
+      description: STATUS_TEXT[Number(status)] ?? "Response",
+      ...response.contentType ? { content: contentObject(response.contentType, schema) } : {}
+    };
+  }
+  out["default"] = {
+    description: "Error",
+    content: {
+      "application/json": {
+        schema: { $ref: op.credentials.includes("doc-jwt") ? ENGINE_ERROR_REF : ADMIN_ERROR_REF }
+      }
+    }
+  };
+  return out;
+}
+function contentObject(contentType, schema) {
+  const types = typeof contentType === "string" ? [contentType] : contentType;
+  return Object.fromEntries(types.map((t) => [t, mediaObject(t, schema)]));
+}
+function mediaObject(contentType, schema) {
+  if (schema) return { schema };
+  if (contentType === "multipart/form-data") {
+    return {
+      schema: {
+        type: "object",
+        properties: { file: { type: "string", format: "binary" } },
+        required: ["file"]
+      }
+    };
+  }
+  return { schema: { type: "string", format: "binary" } };
+}
+function registerSchema(schemas, name, schema) {
+  if (schemas[name]) throw new Error(`Duplicate OpenAPI schema name: ${name}`);
+  const componentPath = ["components", "schemas", name];
+  const referenced = zodToJsonSchema(schema, {
+    target: "openApi3",
+    $refStrategy: "root",
+    basePath: ["#", ...componentPath]
+  });
+  schemas[name] = breakAncestorReferences(referenced, componentPath);
+  return { $ref: `#/components/schemas/${name}` };
+}
+function breakAncestorReferences(value, path) {
+  if (Array.isArray(value)) {
+    return value.map((child, index) => breakAncestorReferences(child, [...path, String(index)]));
+  }
+  if (!value || typeof value !== "object") return value;
+  const record = value;
+  if (typeof record.$ref === "string" && record.$ref.startsWith("#/")) {
+    const target = record.$ref.slice(2).split("/").map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~"));
+    if (target.length <= path.length && target.every((segment, index) => path[index] === segment)) {
+      return {};
+    }
+  }
+  return Object.fromEntries(
+    Object.entries(record).map(([key, child]) => [
+      key,
+      breakAncestorReferences(child, [...path, key])
+    ])
+  );
+}
+function inlineSchemaOf(schema) {
+  return zodToJsonSchema(schema, {
+    target: "openApi3",
+    $refStrategy: "none"
+  });
+}
+function sdkTypeName(operationId) {
+  return operationId.split(".").map((part) => `${part[0].toUpperCase()}${part.slice(1)}`).join("");
+}
+function objectShape(schema) {
+  if (schema instanceof z2.ZodObject) {
+    return schema.shape;
+  }
+  return {};
+}
+function toOpenApiPath(template) {
+  return template.replace(/:([A-Za-z0-9_]+)/g, "{$1}");
+}
+function sortKeys(obj) {
+  return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
+}
+export {
+  buildAdminOpenApiDocument
+};
+//# sourceMappingURL=openapi.js.map