@crombolo/contracts 0.0.0-stage → 0.10.0

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@crombolo/contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.0",
+  "description": "The Umbraco Management API OpenAPI document and the TypeScript types generated from it.",
+  "license": "MIT",
+  "author": "Crombolo",
+  "homepage": "https://github.com/kineco-au/crombolo-cms#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kineco-au/crombolo-cms.git",
+    "directory": "packages/contracts"
+  },
+  "bugs": {
+    "url": "https://github.com/kineco-au/crombolo-cms/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./OpenApi.json": "./OpenApi.json"
+  },
+  "files": [
+    "src",
+    "OpenApi.json",
+    "generated",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './spec.ts'
+export type * from './types.ts'

package/src/spec.ts

@@ -0,0 +1,92 @@
+/** Loads and indexes the vendored Umbraco Management API OpenAPI contract. */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const SPEC_PATH = join(import.meta.dir, '../OpenApi.json')
+
+export const HTTP_METHODS = ['get', 'post', 'put', 'delete', 'patch'] as const
+export type HttpMethod = (typeof HTTP_METHODS)[number]
+
+export interface OperationInfo {
+  operationId: string
+  method: HttpMethod
+  /** Full path as written in the spec, e.g. /umbraco/management/api/v1/document/{id} */
+  path: string
+  /** Version segment parsed out of the path, e.g. "1" or "1.1" */
+  version: string | undefined
+  /** First tag, used to group operations by area. */
+  tag: string | undefined
+  /** Path segment after the version, e.g. "document" */
+  area: string | undefined
+  /**
+   * True when the operation overrides the document's global security with an
+   * empty requirement. Exactly 10 operations do this in Umbraco 18.
+   */
+  anonymous: boolean
+}
+
+export interface OpenApiSpec {
+  openapi: string
+  info: { title: string; version: string }
+  security?: unknown[]
+  paths: Record<
+    string,
+    Record<string, { operationId?: string; tags?: string[]; security?: unknown[] }>
+  >
+  components: { schemas: Record<string, unknown> }
+}
+
+let cached: OpenApiSpec | undefined
+
+export function loadSpec(): OpenApiSpec {
+  if (!cached) cached = JSON.parse(readFileSync(SPEC_PATH, 'utf8')) as OpenApiSpec
+  return cached
+}
+
+export async function loadSpecAsync(): Promise<OpenApiSpec> {
+  if (!cached) cached = (await Bun.file(SPEC_PATH).json()) as OpenApiSpec
+  return cached
+}
+
+const VERSION_RE = /\/api\/v(\d+(?:\.\d+)?)\//
+
+export function parsePath(path: string): { version?: string; area?: string } {
+  const m = VERSION_RE.exec(path)
+  if (!m) return {}
+  const version = m[1]
+  const rest = path.slice(m.index + m[0].length)
+  const area = rest.split('/')[0] || undefined
+  return { version, area }
+}
+
+export function listOperations(spec: OpenApiSpec): OperationInfo[] {
+  const out: OperationInfo[] = []
+  for (const [path, item] of Object.entries(spec.paths)) {
+    const { version, area } = parsePath(path)
+    for (const method of HTTP_METHODS) {
+      const op = item[method]
+      if (!op?.operationId) continue
+      out.push({
+        operationId: op.operationId,
+        method,
+        path,
+        version,
+        tag: op.tags?.[0],
+        area,
+        anonymous: Array.isArray(op.security) && op.security.length === 0,
+      })
+    }
+  }
+  return out
+}
+
+/** Operation ids must be unique — the generated client keys methods on them. */
+export function findDuplicateOperationIds(ops: OperationInfo[]): string[] {
+  const seen = new Set<string>()
+  const dupes = new Set<string>()
+  for (const op of ops) {
+    if (seen.has(op.operationId)) dupes.add(op.operationId)
+    seen.add(op.operationId)
+  }
+  return [...dupes]
+}

package/src/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Typed access to the generated contract types.
+ *
+ * `ResponseOf<'GetServerStatus'>` is the exact 200 body the backoffice expects,
+ * so a handler that drifts from the contract fails to compile. Regenerate with
+ * `bun run generate:types` after re-vendoring OpenApi.json.
+ */
+import type { components, operations } from '../generated/management-api.d.ts'
+
+export type Schemas = components['schemas']
+export type Operations = operations
+export type OperationId = keyof operations
+
+type JsonContent<T> = T extends { content: { 'application/json': infer B } } ? B : never
+
+/** The 200/201 JSON response body for an operation, or never if it has none. */
+export type ResponseOf<K extends OperationId> = operations[K] extends {
+  responses: infer R
+}
+  ? R extends { 200: infer Ok }
+    ? JsonContent<Ok>
+    : R extends { 201: infer Created }
+      ? JsonContent<Created>
+      : never
+  : never
+
+/** The JSON request body for an operation, or never if it takes none. */
+export type RequestOf<K extends OperationId> = operations[K] extends {
+  requestBody?: infer B
+}
+  ? JsonContent<NonNullable<B>>
+  : never
+
+/** Query and path parameters declared for an operation. */
+export type ParamsOf<K extends OperationId> = operations[K] extends { parameters: infer P }
+  ? P
+  : never

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.