@crombolo/contracts 0.14.1 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/contracts",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "The Umbraco Management and Delivery API OpenAPI documents and the TypeScript types generated from them.",
   "license": "MIT",
   "author": "Crombolo",

package/src/index.ts

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

package/src/overrides.ts

@@ -0,0 +1,40 @@
+/**
+ * Where crombolo's Management API differs from Umbraco's contract on purpose.
+ * `OpenApi.json` stays exactly Umbraco's, so a re-copy from a new release is a
+ * clean diff; each difference is listed here with its reason, and applied when
+ * the contract is loaded and when it is served.
+ */
+export interface ContractOverride {
+  /** The schema under `components.schemas` it changes. */
+  schema: string
+  story: string
+  reason: string
+  apply(schema: Record<string, unknown>): void
+}
+
+export const CONTRACT_OVERRIDES: readonly ContractOverride[] = [
+  {
+    schema: 'CreateMemberRequestModel',
+    story: '035',
+    reason:
+      'A member who will only ever sign in through an identity provider is created with no password, as external sign-in creates one.',
+    apply(schema) {
+      schema.required = ((schema.required as string[] | undefined) ?? []).filter(
+        (field) => field !== 'password',
+      )
+    },
+  },
+]
+
+/** The contract with every override applied, leaving the one given untouched. */
+export function applyOverrides<T extends { components: { schemas: Record<string, unknown> } }>(
+  spec: T,
+): T {
+  const copy = structuredClone(spec)
+  for (const override of CONTRACT_OVERRIDES) {
+    const schema = copy.components.schemas[override.schema] as Record<string, unknown> | undefined
+    if (!schema) throw new Error(`The contract has no schema ${override.schema} to override`)
+    override.apply(schema)
+  }
+  return copy
+}

package/src/spec.ts

@@ -1,6 +1,7 @@
 /** Loads and indexes the vendored Umbraco Management API OpenAPI contract. */
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { applyOverrides } from './overrides.ts'
 
 export const SPEC_PATH = join(import.meta.dir, '../OpenApi.json')
 
@@ -40,12 +41,25 @@ export interface OpenApiSpec {
 }
 
 let cached: OpenApiSpec | undefined
+let served: string | undefined
 
+/** Umbraco's contract exactly as vendored, before crombolo's deliberate differences. */
+export function loadUmbracoSpec(): OpenApiSpec {
+  return JSON.parse(readFileSync(SPEC_PATH, 'utf8')) as OpenApiSpec
+}
+
+/** The contract crombolo answers to: Umbraco's, with `CONTRACT_OVERRIDES` applied. */
 export function loadSpec(): OpenApiSpec {
-  if (!cached) cached = JSON.parse(readFileSync(SPEC_PATH, 'utf8')) as OpenApiSpec
+  if (!cached) cached = applyOverrides(loadUmbracoSpec())
   return cached
 }
 
+/** The contract as `GET …/openapi.json` serves it. */
+export function servedContract(): string {
+  if (!served) served = JSON.stringify(loadSpec())
+  return served
+}
+
 let deliveryCached: OpenApiSpec | undefined
 
 export function loadDeliverySpec(): OpenApiSpec {
@@ -55,7 +69,7 @@ export function loadDeliverySpec(): OpenApiSpec {
 }
 
 export async function loadSpecAsync(): Promise<OpenApiSpec> {
-  if (!cached) cached = (await Bun.file(SPEC_PATH).json()) as OpenApiSpec
+  if (!cached) cached = applyOverrides((await Bun.file(SPEC_PATH).json()) as OpenApiSpec)
   return cached
 }