@cloudpdf/contract 3.0.0-next.1 → 3.0.0-next.11

package/dist/openapi.js

@@ -1,12 +1,12 @@
 // src/openapi.ts
-import { zodToJsonSchema } from "zod-to-json-schema";
+import { EngineErrorPayloadSchema as EngineErrorPayloadSchema2, PdfActionWireComponents } from "@embedpdf/engine-core/wire";
 import { z as z2 } from "zod";
-import { EngineErrorPayloadSchema as EngineErrorPayloadSchema2 } from "@embedpdf/engine-core/wire";
+import { ignoreOverride, zodToJsonSchema } from "zod-to-json-schema";
 
 // src/index.ts
-import { z } from "zod";
 import {
   AnnotationListPageSnapshotSchema,
+  AnnotationListSnapshotAllPagesSchema,
   DocumentHeadSchema,
   DocumentManifestSchema,
   DocumentMetadataSchema,
@@ -16,26 +16,50 @@ 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_-]+$/;
+var originPattern = /^https?:\/\/(\*\.)?[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*(:\d{1,5})?$/;
+var originPatternArray = z.array(
+  z.string().max(262).regex(
+    originPattern,
+    "must be a web origin like https://example.com (optionally one leading *. wildcard label, optional port, no path)"
+  )
+).min(1).max(32);
+var shareTokenPattern = /^shr_[A-Za-z0-9_-]{24}$/;
 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`,
+  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`,
-  documentUploadDirect: (tenantId, docId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents/${encodeURIComponent(docId)}/upload-direct`,
+  documentUploadProxy: (tenantId, docId) => `/v1/tenants/${encodeURIComponent(tenantId)}/documents/${encodeURIComponent(docId)}/upload-proxy`,
   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`,
+  shares: (tenantId) => `/v1/tenants/${encodeURIComponent(tenantId)}/shares`,
+  share: (tenantId, shareId) => `/v1/tenants/${encodeURIComponent(tenantId)}/shares/${encodeURIComponent(shareId)}`,
+  tenantUsage: (tenantId) => `/v1/tenants/${encodeURIComponent(tenantId)}/usage`,
+  tenantSuspend: (tenantId) => `/v1/tenants/${encodeURIComponent(tenantId)}/suspend`,
+  tenantResume: (tenantId) => `/v1/tenants/${encodeURIComponent(tenantId)}/resume`,
+  /**
+   * The public share-session exchange. Deliberately outside any tenant
+   * subtree: the caller holds only a share token and does not know the
+   * tenant — the grant row resolves it server-side.
+   */
+  shareSessions: "/v1/share-sessions",
   /** 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({
   id: z.string(),
@@ -60,7 +84,8 @@ var AdminDocumentInitRequestSchema = z.object({
   idempotencyKey: z.string().optional(),
   dedupMode: DedupModeSchema.optional(),
   docId: z.string().regex(docIdPattern).optional(),
-  uploadTtlSec: z.number().finite().min(60).max(3600).optional()
+  uploadTtlSec: z.number().finite().min(60).max(3600).optional(),
+  uploadPreference: UploadPreferenceSchema.optional()
 });
 var AdminPresignedUploadSchema = z.object({
   url: z.string(),
@@ -75,7 +100,7 @@ var AdminInitUploadSchema = z.discriminatedUnion("kind", [
     key: z.string()
   }),
   z.object({
-    kind: z.literal("direct"),
+    kind: z.literal("proxy"),
     url: z.string(),
     key: z.string()
   })
@@ -102,6 +127,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
 });
@@ -121,7 +219,7 @@ var AdminDocumentListResponseSchema = z.object({
    */
   nextCursor: z.string().nullable().optional()
 });
-var AdminUploadDirectResponseSchema = z.object({
+var AdminUploadProxyResponseSchema = z.object({
   sha256: z.string().regex(sha256Hex)
 });
 var AdminErrorPayloadSchema = z.object({
@@ -168,6 +266,13 @@ var AdminTenantRecordSchema = z.object({
   name: z.string(),
   /** True when the namespace materialized on first use rather than via explicit create. */
   autoProvisioned: z.boolean(),
+  /**
+   * `suspended` tenants fail closed: every tenant JWT, doc JWT, and
+   * share exchange is refused until resume. The API token is exempt —
+   * the operator must be able to inspect, resume, or delete a
+   * suspended tenant. Optional because older servers omit it.
+   */
+  status: z.enum(["active", "suspended"]).optional(),
   createdAt: z.number()
 });
 var AdminTenantCreateRequestSchema = z.object({
@@ -197,7 +302,8 @@ var adminTenantScopes = [
   "docs.read",
   "docs.delete",
   "tokens.issue-doc",
-  "tokens.revoke"
+  "tokens.revoke",
+  "shares.manage"
 ];
 var AdminTokenIssueDocRequestSchema = z.object({
   kind: z.literal("doc"),
@@ -215,6 +321,14 @@ var AdminTokenIssueDocRequestSchema = z.object({
   displayName: z.string().max(256).optional(),
   groupId: z.string().max(256).optional(),
   groups: z.array(z.string().max(256)).max(64).optional(),
+  /**
+   * Origin lock: web origins (scheme + host, optional port; one leading
+   * `*.` wildcard label allowed) the minted token may be presented
+   * from. Enforced on every engine request that carries a browser
+   * `Origin` header — hotlink prevention, not DRM: non-browser callers
+   * are governed by the token itself.
+   */
+  origins: originPatternArray.optional(),
   /** Token lifetime in seconds. */
   expiresIn: z.number().int().min(60).max(60 * 60 * 24 * 90)
 });
@@ -235,9 +349,110 @@ var AdminTokenIssueResponseSchema = z.object({
   /** Unix seconds. */
   expiresAt: z.number()
 });
+var ShareGrantRecordSchema = z.object({
+  /** Grant id; doubles as the public share token (`shr_…`). */
+  id: z.string(),
+  tenantId: z.string(),
+  docId: z.string(),
+  layerName: z.string(),
+  /** Doc capabilities the exchanged session carries. */
+  scope: z.array(z.string()),
+  /** Origin allowlist; null means any origin. */
+  origins: z.array(z.string()).nullable(),
+  /** True when a passphrase is required at exchange. The passphrase itself is never returned. */
+  passwordProtected: z.boolean(),
+  /** Lifetime of each exchanged session token, in seconds. */
+  sessionTtlSeconds: z.number(),
+  /** Paused grants refuse exchange (404) but keep their configuration. */
+  disabled: z.boolean(),
+  /** Unix epoch ms after which exchange returns 410; null = no expiry. */
+  expiresAt: z.number().nullable(),
+  /** Total successful exchanges — a dashboard convenience, not the usage meter. */
+  exchangeCount: z.number(),
+  lastExchangedAt: z.number().nullable(),
+  createdBy: z.string(),
+  createdAt: z.number(),
+  updatedAt: z.number()
+});
+var ShareGrantCreateRequestSchema = z.object({
+  docId: z.string().regex(docIdPattern),
+  layerName: z.string().min(1).max(256).optional(),
+  /**
+   * Doc capability scopes the exchanged session will carry. Validated
+   * server-side against the engine's scope vocabulary, same as
+   * `tokens.issue`.
+   */
+  scope: z.array(z.string().min(1).max(128)).min(1).max(64),
+  /** Origin allowlist; omit to allow any origin. */
+  origins: originPatternArray.optional(),
+  /** Optional passphrase gate, checked at exchange. Stored as a hash; never returned. */
+  password: z.string().min(1).max(1024).optional(),
+  /** Lifetime of exchanged session tokens. Default 600. */
+  sessionTtlSeconds: z.number().int().min(60).max(60 * 60).optional(),
+  /** Unix epoch ms after which the grant stops exchanging; omit for no expiry. */
+  expiresAt: z.number().int().positive().optional()
+});
+var ShareGrantUpdateRequestSchema = z.object({
+  scope: z.array(z.string().min(1).max(128)).min(1).max(64).optional(),
+  origins: originPatternArray.nullable().optional(),
+  password: z.string().min(1).max(1024).nullable().optional(),
+  sessionTtlSeconds: z.number().int().min(60).max(60 * 60).optional(),
+  disabled: z.boolean().optional(),
+  expiresAt: z.number().int().positive().nullable().optional()
+});
+var ShareGrantResponseSchema = z.object({
+  share: ShareGrantRecordSchema
+});
+var ShareGrantListQuerySchema = 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(),
+  /** Filter to one document's grants. */
+  docId: z.string().regex(docIdPattern).optional()
+});
+var ShareGrantListResponseSchema = z.object({
+  shares: z.array(ShareGrantRecordSchema),
+  /** Opaque cursor for the next page; `null` on the last page. */
+  nextCursor: z.string().nullable().optional()
+});
+var AdminTenantShareParamsSchema = z.object({
+  tenantId: z.string().regex(tenantIdPattern),
+  shareId: z.string().regex(shareTokenPattern)
+});
+var ShareExchangeRequestSchema = z.object({
+  shareToken: z.string().regex(shareTokenPattern),
+  /** Required when the grant is passphrase-protected (422 otherwise). */
+  password: z.string().min(1).max(1024).optional()
+});
+var ShareSessionResponseSchema = z.object({
+  /** A doc-scoped session JWT carrying the grant's capabilities and origin lock. */
+  token: z.string(),
+  docId: z.string(),
+  layerName: z.string(),
+  /** Unix seconds when the session token expires; exchange again for a fresh one. */
+  expiresAt: z.number()
+});
+var TenantUsageQuerySchema = z.object({
+  /** UTC month to report, `YYYY-MM`. Defaults to the current month. */
+  period: z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/).optional()
+});
+var TenantUsageResponseSchema = z.object({
+  tenantId: z.string(),
+  periodStart: z.string(),
+  periodEnd: z.string(),
+  metrics: z.object({
+    "pdf.views": z.number(),
+    "pdf.uploads": z.number(),
+    "storage.bytes": z.number()
+  })
+});
+var TenantSuspendRequestSchema = z.object({
+  /** Optional operator reason, written to the security-events trail. */
+  reason: z.string().max(1024).optional()
+});
 var adminOperations = {
   "tenants.create": {
     operationId: "tenants.create",
+    title: "Create tenant",
     summary: "Create a tenant, or confirm it already exists \u2014 ensure-style, idempotent.",
     method: "POST",
     path: adminWirePaths.tenants,
@@ -251,6 +466,7 @@ var adminOperations = {
   },
   "tenants.list": {
     operationId: "tenants.list",
+    title: "List tenants",
     summary: "List tenants, newest first, cursor-paginated.",
     method: "GET",
     path: adminWirePaths.tenants,
@@ -264,6 +480,7 @@ var adminOperations = {
   },
   "tenants.get": {
     operationId: "tenants.get",
+    title: "Get tenant",
     summary: "Fetch one tenant record.",
     method: "GET",
     path: "/v1/tenants/:tenantId",
@@ -277,6 +494,7 @@ var adminOperations = {
   },
   "tenants.delete": {
     operationId: "tenants.delete",
+    title: "Delete tenant",
     summary: "Delete a tenant and everything under it.",
     method: "DELETE",
     path: "/v1/tenants/:tenantId",
@@ -291,6 +509,7 @@ var adminOperations = {
   },
   "documents.init": {
     operationId: "documents.init",
+    title: "Initialize upload",
     summary: "Begin an upload: create (or resume/dedupe) a pending document and issue upload access.",
     method: "POST",
     path: "/v1/tenants/:tenantId/documents/init",
@@ -305,6 +524,7 @@ var adminOperations = {
   },
   "documents.commit": {
     operationId: "documents.commit",
+    title: "Commit upload",
     summary: "Finish an upload: verify the SHA-256 and promote the document to ready.",
     method: "POST",
     path: "/v1/tenants/:tenantId/documents/:id/commit",
@@ -318,24 +538,47 @@ var adminOperations = {
       404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
     }
   },
-  "documents.uploadDirect": {
-    operationId: "documents.uploadDirect",
-    summary: "Upload the PDF bytes through the origin instead of a presigned URL.",
+  "documents.uploadProxy": {
+    operationId: "documents.uploadProxy",
+    title: "Upload document through the origin",
+    summary: "Upload a bounded PDF through the API when the initialized transfer kind is proxy.",
     method: "POST",
-    path: "/v1/tenants/:tenantId/documents/:id/upload-direct",
+    path: "/v1/tenants/:tenantId/documents/:id/upload-proxy",
     credentials: ["api-token", "tenant-jwt"],
     scope: ["docs.create"],
     params: AdminTenantDocParamsSchema,
     body: {
-      contentType: ["application/pdf", "application/octet-stream", "multipart/form-data"]
+      contentType: "multipart/form-data"
     },
     responses: {
-      200: { contentType: "application/json", schema: AdminUploadDirectResponseSchema },
-      400: { contentType: "application/json", schema: AdminErrorPayloadSchema }
-    }
+      200: { contentType: "application/json", schema: AdminUploadProxyResponseSchema },
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      409: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    },
+    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",
     summary: "List documents in the tenant, newest first, cursor-paginated.",
     method: "GET",
     path: "/v1/tenants/:tenantId/documents",
@@ -350,6 +593,7 @@ var adminOperations = {
   },
   "documents.get": {
     operationId: "documents.get",
+    title: "Get document",
     summary: "Fetch one document record.",
     method: "GET",
     path: "/v1/tenants/:tenantId/documents/:id",
@@ -364,6 +608,7 @@ var adminOperations = {
   },
   "documents.download": {
     operationId: "documents.download",
+    title: "Download document",
     summary: "Download the stored base PDF bytes.",
     method: "GET",
     path: "/v1/tenants/:tenantId/documents/:id/download",
@@ -378,6 +623,7 @@ var adminOperations = {
   },
   "documents.delete": {
     operationId: "documents.delete",
+    title: "Delete document",
     summary: "Delete a document and its stored artifacts.",
     method: "DELETE",
     path: "/v1/tenants/:tenantId/documents/:id",
@@ -392,6 +638,7 @@ var adminOperations = {
   },
   "documents.thumbnail": {
     operationId: "documents.thumbnail",
+    title: "Get thumbnail",
     summary: "Fetch the warmed dashboard-tile render for a document.",
     method: "GET",
     path: "/v1/tenants/:tenantId/documents/:id/thumbnail",
@@ -405,6 +652,7 @@ var adminOperations = {
   },
   "deployment.licenseStatus": {
     operationId: "deployment.licenseStatus",
+    title: "License status",
     summary: "License decision plus usage-reporting and meter snapshots for this deployment.",
     method: "GET",
     path: adminWirePaths.deploymentLicenseStatus,
@@ -416,6 +664,7 @@ var adminOperations = {
   },
   "tokens.issue": {
     operationId: "tokens.issue",
+    title: "Issue token",
     summary: "Mint a delegated JWT: a doc token, or (API token only) a tenant token.",
     method: "POST",
     path: "/v1/tenants/:tenantId/tokens",
@@ -433,6 +682,7 @@ var adminOperations = {
   },
   "tokens.revoke": {
     operationId: "tokens.revoke",
+    title: "Revoke token",
     summary: "Revoke a token by jti; live sessions drop on their next heartbeat.",
     method: "POST",
     path: "/v1/tenants/:tenantId/tokens/:jti/revoke",
@@ -449,6 +699,153 @@ var adminOperations = {
       400: { contentType: "application/json", schema: AdminErrorPayloadSchema }
     },
     notes: "Mounted only when the deployment enables token revocation."
+  },
+  "tenants.usage": {
+    operationId: "tenants.usage",
+    title: "Tenant usage",
+    summary: "Per-tenant usage facts (views, uploads, stored bytes) for one UTC month.",
+    method: "GET",
+    path: "/v1/tenants/:tenantId/usage",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["docs.read"],
+    params: AdminTenantParamsSchema,
+    query: TenantUsageQuerySchema,
+    responses: {
+      200: { contentType: "application/json", schema: TenantUsageResponseSchema },
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    },
+    notes: "Facts only \u2014 no limits or billing state. Views count share exchanges plus authorized /v1/access grants, deduplicated across the two."
+  },
+  "tenants.suspend": {
+    operationId: "tenants.suspend",
+    title: "Suspend tenant",
+    summary: "Fail the tenant closed: refuse every tenant JWT, doc JWT, and share exchange.",
+    method: "POST",
+    path: "/v1/tenants/:tenantId/suspend",
+    credentials: ["api-token"],
+    scope: [],
+    params: AdminTenantParamsSchema,
+    body: {
+      contentType: "application/json",
+      schema: TenantSuspendRequestSchema,
+      required: false
+    },
+    responses: {
+      204: {},
+      404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    },
+    notes: "Instantly reversible with resume. The API token is exempt, so a suspended tenant can still be inspected, exported, resumed, or deleted."
+  },
+  "tenants.resume": {
+    operationId: "tenants.resume",
+    title: "Resume tenant",
+    summary: "Lift a suspension; credentials for the tenant verify again.",
+    method: "POST",
+    path: "/v1/tenants/:tenantId/resume",
+    credentials: ["api-token"],
+    scope: [],
+    params: AdminTenantParamsSchema,
+    responses: {
+      204: {},
+      404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "shares.create": {
+    operationId: "shares.create",
+    title: "Create share",
+    summary: "Create a standing share grant for one document \u2014 the no-backend embed credential.",
+    method: "POST",
+    path: "/v1/tenants/:tenantId/shares",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["shares.manage"],
+    params: AdminTenantParamsSchema,
+    body: { contentType: "application/json", schema: ShareGrantCreateRequestSchema },
+    responses: {
+      200: { contentType: "application/json", schema: ShareGrantResponseSchema },
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      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."
+  },
+  "shares.list": {
+    operationId: "shares.list",
+    title: "List shares",
+    summary: "List share grants in the tenant, newest first, cursor-paginated.",
+    method: "GET",
+    path: "/v1/tenants/:tenantId/shares",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["shares.manage"],
+    params: AdminTenantParamsSchema,
+    query: ShareGrantListQuerySchema,
+    responses: {
+      200: { contentType: "application/json", schema: ShareGrantListResponseSchema },
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "shares.get": {
+    operationId: "shares.get",
+    title: "Get share",
+    summary: "Fetch one share grant.",
+    method: "GET",
+    path: "/v1/tenants/:tenantId/shares/:shareId",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["shares.manage"],
+    params: AdminTenantShareParamsSchema,
+    responses: {
+      200: { contentType: "application/json", schema: ShareGrantResponseSchema },
+      404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "shares.update": {
+    operationId: "shares.update",
+    title: "Update share",
+    summary: "Edit a grant in place \u2014 every embedded copy of the token follows the row.",
+    method: "PATCH",
+    path: "/v1/tenants/:tenantId/shares/:shareId",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["shares.manage"],
+    params: AdminTenantShareParamsSchema,
+    body: { contentType: "application/json", schema: ShareGrantUpdateRequestSchema },
+    responses: {
+      200: { contentType: "application/json", schema: ShareGrantResponseSchema },
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "shares.delete": {
+    operationId: "shares.delete",
+    title: "Revoke share",
+    summary: "Delete a grant; exchange stops immediately, live sessions lapse at their exp.",
+    method: "DELETE",
+    path: "/v1/tenants/:tenantId/shares/:shareId",
+    credentials: ["api-token", "tenant-jwt"],
+    scope: ["shares.manage"],
+    params: AdminTenantShareParamsSchema,
+    responses: {
+      204: {},
+      404: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    }
+  },
+  "shares.exchange": {
+    operationId: "shares.exchange",
+    title: "Exchange share token",
+    summary: "Trade a public share token for a short-lived document session JWT.",
+    method: "POST",
+    path: adminWirePaths.shareSessions,
+    credentials: [],
+    scope: [],
+    body: { contentType: "application/json", schema: ShareExchangeRequestSchema },
+    responses: {
+      200: { contentType: "application/json", schema: ShareSessionResponseSchema },
+      400: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      403: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      404: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      410: { contentType: "application/json", schema: AdminErrorPayloadSchema },
+      422: { contentType: "application/json", schema: AdminErrorPayloadSchema }
+    },
+    notes: "Unauthenticated, but requires a browser Origin header, checked against the grant allowlist. Unknown, revoked, and disabled tokens are indistinguishable (404). Passphrase-protected grants return 422 SharePasswordRequired until `password` is supplied. Mounted only when the deployment can sign (HS256 mode)."
   }
 };
 var DocIdParamsSchema = z.object({
@@ -477,6 +874,7 @@ var MutationResponseSchema = z.object({ meta: MutationMetaSchema }).passthrough(
 var docOperations = {
   "doc.head": {
     operationId: "doc.head",
+    title: "Open document",
     summary: "Open a document and return its head (versions, page count, security).",
     method: "GET",
     path: wireTemplates.docHead,
@@ -492,6 +890,7 @@ var docOperations = {
   },
   "doc.manifest": {
     operationId: "doc.manifest",
+    title: "Get manifest",
     summary: "Full layer manifest at the layer's current version.",
     method: "GET",
     path: wireTemplates.layerManifest,
@@ -507,6 +906,7 @@ var docOperations = {
   },
   "doc.metadata.get": {
     operationId: "doc.metadata.get",
+    title: "Get metadata",
     summary: "Document metadata (PDF info dictionary view) for a layer.",
     method: "GET",
     path: wireTemplates.layerMetadata,
@@ -522,6 +922,7 @@ var docOperations = {
   },
   "doc.render": {
     operationId: "doc.render",
+    title: "Render page",
     summary: "Render one page as an image at the current layer version.",
     method: "GET",
     path: wireTemplates.layerRenderPage,
@@ -538,6 +939,7 @@ var docOperations = {
   },
   "doc.text": {
     operationId: "doc.text",
+    title: "Extract page text",
     summary: "Extracted text content for one page.",
     method: "GET",
     path: wireTemplates.layerTextPage,
@@ -553,6 +955,7 @@ var docOperations = {
   },
   "doc.annotations.list": {
     operationId: "doc.annotations.list",
+    title: "List annotations",
     summary: "One page's annotations at the current layer version.",
     method: "GET",
     path: wireTemplates.layerAnnotationItems,
@@ -566,8 +969,27 @@ var docOperations = {
       404: { contentType: "application/json", schema: EngineErrorPayloadSchema }
     }
   },
+  "doc.annotations.listAll": {
+    operationId: "doc.annotations.listAll",
+    title: "List all annotations",
+    summary: "All pages' annotations as one coherent snapshot at the current layer version.",
+    method: "GET",
+    path: wireTemplates.layerAnnotationItemsAll,
+    credentials: docCredentials,
+    scope: [],
+    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.",
+    responses: {
+      200: { contentType: "application/json", schema: AnnotationListSnapshotAllPagesSchema },
+      404: { contentType: "application/json", schema: EngineErrorPayloadSchema },
+      409: { contentType: "application/json", schema: EngineErrorPayloadSchema }
+    }
+  },
   "doc.annotations.create": {
     operationId: "doc.annotations.create",
+    title: "Create annotation",
     summary: "Create an annotation on a page.",
     method: "POST",
     path: wireTemplates.layerAnnotationItems,
@@ -586,6 +1008,7 @@ var docOperations = {
   },
   "doc.annotations.update": {
     operationId: "doc.annotations.update",
+    title: "Update annotation",
     summary: "Update one annotation by key.",
     method: "PATCH",
     path: wireTemplates.layerAnnotationItem,
@@ -603,6 +1026,7 @@ var docOperations = {
   },
   "doc.annotations.delete": {
     operationId: "doc.annotations.delete",
+    title: "Delete annotation",
     summary: "Delete one annotation by key.",
     method: "DELETE",
     path: wireTemplates.layerAnnotationItem,
@@ -618,6 +1042,7 @@ var docOperations = {
   },
   "doc.forms.get": {
     operationId: "doc.forms.get",
+    title: "Get form snapshot",
     summary: "Reconciled form snapshot: fields, widgets, values.",
     method: "GET",
     path: wireTemplates.layerForm,
@@ -633,6 +1058,7 @@ var docOperations = {
   },
   "doc.forms.setValue": {
     operationId: "doc.forms.setValue",
+    title: "Set form value",
     summary: "Set one form field's value.",
     method: "POST",
     path: wireTemplates.layerFormFieldValue,
@@ -650,6 +1076,7 @@ var docOperations = {
   },
   "doc.forms.reset": {
     operationId: "doc.forms.reset",
+    title: "Reset form field",
     summary: "Reset one form field to its default value.",
     method: "POST",
     path: wireTemplates.layerFormFieldReset,
@@ -665,6 +1092,7 @@ var docOperations = {
   },
   "doc.forms.exportData": {
     operationId: "doc.forms.exportData",
+    title: "Export form data",
     summary: "Export form data as FDF or XFDF.",
     method: "GET",
     path: wireTemplates.layerFormData,
@@ -681,6 +1109,7 @@ var docOperations = {
   },
   "doc.forms.importData": {
     operationId: "doc.forms.importData",
+    title: "Import form data",
     summary: "Import form data (FDF/XFDF), filling matching fields.",
     method: "POST",
     path: wireTemplates.layerFormData,
@@ -698,6 +1127,7 @@ var docOperations = {
   },
   "doc.pages.move": {
     operationId: "doc.pages.move",
+    title: "Move pages",
     summary: "Reorder pages.",
     method: "POST",
     path: wireTemplates.layerPagesMove,
@@ -715,6 +1145,7 @@ var docOperations = {
   },
   "doc.pages.rotate": {
     operationId: "doc.pages.rotate",
+    title: "Rotate pages",
     summary: "Set absolute rotation on pages.",
     method: "POST",
     path: wireTemplates.layerPagesRotate,
@@ -732,6 +1163,7 @@ var docOperations = {
   },
   "doc.pages.delete": {
     operationId: "doc.pages.delete",
+    title: "Delete pages",
     summary: "Delete pages.",
     method: "POST",
     path: wireTemplates.layerPagesDelete,
@@ -749,6 +1181,7 @@ var docOperations = {
   },
   "doc.pages.flatten": {
     operationId: "doc.pages.flatten",
+    title: "Flatten pages",
     summary: "Flatten annotations and form fields into page content.",
     method: "POST",
     path: wireTemplates.layerPagesFlatten,
@@ -764,8 +1197,68 @@ 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],
+    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",
+    summary: "Export the listed pages, in order, as a standalone PDF.",
+    method: "POST",
+    path: wireTemplates.layerPagesExtract,
+    credentials: docCredentials,
+    scope: [],
+    docCapabilities: ["doc.download"],
+    requestHeaders: [documentPasswordHeader],
+    params: DocLayerParamsSchema,
+    body: { contentType: "application/json", schema: looseJson },
+    responses: {
+      200: { contentType: "application/pdf" },
+      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.'
+  },
   "doc.redactions.apply": {
     operationId: "doc.redactions.apply",
+    title: "Apply redactions",
     summary: "Apply pending redactions, permanently removing content.",
     method: "POST",
     path: wireTemplates.layerRedactionsApply,
@@ -783,6 +1276,7 @@ var docOperations = {
   },
   "doc.download": {
     operationId: "doc.download",
+    title: "Download PDF",
     summary: "Download the layer's current PDF (base plus layer edits).",
     method: "GET",
     path: wireTemplates.layerDownload,
@@ -798,6 +1292,19 @@ var docOperations = {
   }
 };
 var allOperations = { ...adminOperations, ...docOperations };
+var docsGroups = {
+  deployment: { title: "Deployment" },
+  tenants: { title: "Tenants" },
+  documents: { title: "Tenant documents" },
+  tokens: { title: "Tokens" },
+  shares: { title: "Shares" },
+  doc: { title: "Document operations", slug: "document-operations" },
+  "doc.annotations": { title: "Annotations" },
+  "doc.forms": { title: "Forms" },
+  "doc.metadata": { title: "Metadata" },
+  "doc.pages": { title: "Pages" },
+  "doc.redactions": { title: "Redactions" }
+};
 
 // src/openapi.ts
 var STATUS_TEXT = {
@@ -808,6 +1315,7 @@ var STATUS_TEXT = {
   403: "Forbidden",
   404: "Not found",
   409: "Conflict",
+  410: "Gone",
   422: "Unprocessable"
 };
 var SECURITY_SCHEME = {
@@ -817,12 +1325,23 @@ 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_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 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);
+  }
   for (const op of Object.values(allOperations)) {
+    assertDocsGroupsCover(op);
     const openApiPath = toOpenApiPath(op.path);
     const method = op.method.toLowerCase();
     const entry = paths[openApiPath] ??= {};
@@ -837,23 +1356,29 @@ function buildAdminOpenApiDocument(opts) {
       license: { name: "Apache-2.0", identifier: "Apache-2.0" }
     },
     paths: sortKeys(paths),
+    // Docs navigation manifest: section titles and URL slugs for the API
+    // reference, in sidebar order (see `docsGroups` in the registry).
+    "x-docs-groups": docsGroups,
     components: {
       securitySchemes: {
         apiToken: {
           type: "http",
           scheme: "bearer",
+          "x-docs-title": "API token",
           description: "The deployment's static root credential (CLOUDPDF_API_AUTH_TOKENS), valid on every surface."
         },
         tenantToken: {
           type: "http",
           scheme: "bearer",
           bearerFormat: "JWT",
+          "x-docs-title": "Tenant token",
           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",
+          "x-docs-title": "Document token",
           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)."
         }
       },
@@ -861,6 +1386,15 @@ function buildAdminOpenApiDocument(opts) {
     }
   };
 }
+function assertDocsGroupsCover(op) {
+  const { groups } = sdkOperationName(op.operationId);
+  for (let depth = 1; depth <= groups.length; depth += 1) {
+    const key = groups.slice(0, depth).join(".");
+    if (!(key in docsGroups)) {
+      throw new Error(`Operation ${op.operationId} has no docsGroups entry for "${key}"`);
+    }
+  }
+}
 function operationObject(op, schemas) {
   const parameters = [...pathParameters(op), ...queryParameters(op), ...headerParameters(op)];
   const sdkName = sdkOperationName(op.operationId);
@@ -868,6 +1402,7 @@ function operationObject(op, schemas) {
     operationId: op.operationId,
     "x-fern-sdk-group-name": sdkName.groups,
     "x-fern-sdk-method-name": sdkName.method,
+    "x-docs-title": op.title,
     summary: op.summary,
     ...op.notes ? { description: op.notes } : {},
     security: op.credentials.map((credential) => ({ [SECURITY_SCHEME[credential]]: [] })),
@@ -879,12 +1414,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) {
@@ -978,11 +1555,50 @@ function registerSchema(schemas, name, schema) {
   const referenced = zodToJsonSchema(schema, {
     target: "openApi3",
     $refStrategy: "root",
-    basePath: ["#", ...componentPath]
+    basePath: ["#", ...componentPath],
+    override: (definition) => {
+      const sharedName = SHARED_COMPONENT_BY_DEFINITION.get(definition);
+      if (!sharedName || sharedName === name) return ignoreOverride;
+      return { $ref: `#/components/schemas/${sharedName}` };
+    }
   });
-  schemas[name] = breakAncestorReferences(referenced, componentPath);
+  const canonical = collapseSharedReferenceAliases(referenced, referenced, componentPath);
+  schemas[name] = breakAncestorReferences(canonical, componentPath);
   return { $ref: `#/components/schemas/${name}` };
 }
+function collapseSharedReferenceAliases(value, component, componentPath) {
+  if (Array.isArray(value)) {
+    return value.map((child) => collapseSharedReferenceAliases(child, component, componentPath));
+  }
+  if (!value || typeof value !== "object") return value;
+  const record = value;
+  if (Object.keys(record).length === 1 && typeof record.$ref === "string") {
+    const target = resolveComponentReference(component, record.$ref, componentPath);
+    if (target && typeof target === "object" && !Array.isArray(target)) {
+      const targetRecord = target;
+      if (Object.keys(targetRecord).length === 1 && typeof targetRecord.$ref === "string" && SHARED_COMPONENT_REFS.has(targetRecord.$ref)) {
+        return { $ref: targetRecord.$ref };
+      }
+    }
+  }
+  return Object.fromEntries(
+    Object.entries(record).map(([key, child]) => [
+      key,
+      collapseSharedReferenceAliases(child, component, componentPath)
+    ])
+  );
+}
+function resolveComponentReference(component, reference, componentPath) {
+  if (!reference.startsWith("#/")) return void 0;
+  const target = reference.slice(2).split("/").map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~"));
+  if (target.length < componentPath.length || !componentPath.every((segment, index) => target[index] === segment)) {
+    return void 0;
+  }
+  return target.slice(componentPath.length).reduce((current, segment) => {
+    if (!current || typeof current !== "object") return void 0;
+    return current[segment];
+  }, component);
+}
 function breakAncestorReferences(value, path) {
   if (Array.isArray(value)) {
     return value.map((child, index) => breakAncestorReferences(child, [...path, String(index)]));
@@ -1024,6 +1640,7 @@ function sortKeys(obj) {
   return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
 }
 export {
-  buildAdminOpenApiDocument
+  buildAdminOpenApiDocument,
+  sdkOperationName
 };
 //# sourceMappingURL=openapi.js.map