@crombolo/contracts 0.10.0 → 0.12.1

package/generated/delivery-api.d.ts

@@ -0,0 +1,415 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+
+export interface paths {
+  "/umbraco/delivery/api/v2/content": {
+    get: operations["GetContent2.0"];
+  };
+  "/umbraco/delivery/api/v2/content/item/{id}": {
+    get: operations["GetContentItemById2.0"];
+  };
+  "/umbraco/delivery/api/v2/content/item/{path}": {
+    get: operations["GetContentItemByPath2.0"];
+  };
+  "/umbraco/delivery/api/v2/content/items": {
+    get: operations["GetContentItems2.0"];
+  };
+  "/umbraco/delivery/api/v2/media": {
+    get: operations["GetMedia2.0"];
+  };
+  "/umbraco/delivery/api/v2/media/item/{id}": {
+    get: operations["GetMediaItemById2.0"];
+  };
+  "/umbraco/delivery/api/v2/media/item/{path}": {
+    get: operations["GetMediaItemByPath2.0"];
+  };
+  "/umbraco/delivery/api/v2/media/items": {
+    get: operations["GetMediaItems2.0"];
+  };
+}
+
+export type webhooks = Record<string, never>;
+
+export interface components {
+  schemas: {
+    IApiContentResponseModel: {
+      contentType: null | string;
+      name?: null | string;
+      /** Format: date-time */
+      createDate: string;
+      /** Format: date-time */
+      updateDate: string;
+      route: components["schemas"]["IApiContentRouteModel"];
+      /** Format: uuid */
+      id: string;
+      properties: null | Record<string, never>;
+      cultures: null | {
+        [key: string]: components["schemas"]["IApiContentRouteModel"];
+      };
+    };
+    IApiContentRouteModel: {
+      path: null | string;
+      queryString?: null | string;
+      startItem: components["schemas"]["IApiContentStartItemModel"];
+    };
+    IApiContentStartItemModel: {
+      /** Format: uuid */
+      id: string;
+      path: null | string;
+    };
+    IApiMediaWithCropsResponseModel: {
+      path: null | string;
+      /** Format: date-time */
+      createDate: string;
+      /** Format: date-time */
+      updateDate: string;
+      focalPoint?: components["schemas"]["ImageFocalPointModel"];
+      crops?: null | components["schemas"]["ImageCropModel"][];
+      /** Format: uuid */
+      id: string;
+      name: null | string;
+      mediaType: null | string;
+      url: null | string;
+      extension?: null | string;
+      /** Format: int32 */
+      width?: null | number;
+      /** Format: int32 */
+      height?: null | number;
+      /** Format: int32 */
+      bytes?: null | number;
+      properties: null | Record<string, never>;
+    };
+    ImageCropCoordinatesModel: {
+      /** Format: double */
+      x1: number;
+      /** Format: double */
+      y1: number;
+      /** Format: double */
+      x2: number;
+      /** Format: double */
+      y2: number;
+    };
+    ImageCropModel: {
+      alias: null | string;
+      /** Format: int32 */
+      width: number;
+      /** Format: int32 */
+      height: number;
+      coordinates: components["schemas"]["ImageCropCoordinatesModel"];
+    };
+    ImageFocalPointModel: {
+      /** Format: double */
+      left: number;
+      /** Format: double */
+      top: number;
+    };
+    PagedIApiContentResponseModel: {
+      /** Format: int64 */
+      total: number;
+      items: components["schemas"]["IApiContentResponseModel"][];
+    };
+    PagedIApiMediaWithCropsResponseModel: {
+      /** Format: int64 */
+      total: number;
+      items: components["schemas"]["IApiMediaWithCropsResponseModel"][];
+    };
+    ProblemDetails: {
+      type?: null | string;
+      title?: null | string;
+      /** Format: int32 */
+      status?: null | number;
+      detail?: null | string;
+      instance?: null | string;
+    };
+  };
+  responses: never;
+  parameters: never;
+  requestBodies: never;
+  headers: never;
+  pathItems: never;
+}
+
+export type $defs = Record<string, never>;
+
+export type external = Record<string, never>;
+
+export interface operations {
+
+  "GetContent2.0": {
+    parameters: {
+      query?: {
+        /** @description Specifies the content items to fetch. Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#query-parameters) for more details on this. */
+        fetch?: string;
+        /** @description Defines how to filter the fetched content items. Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#query-parameters) for more details on this. */
+        filter?: string[];
+        /** @description Defines how to sort the found content items. Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#query-parameters) for more details on this. */
+        sort?: string[];
+        /** @description Specifies the number of found content items to skip. Use this to control pagination of the response. */
+        skip?: number;
+        /** @description Specifies the number of found content items to take. Use this to control pagination of the response. */
+        take?: number;
+        /** @description Defines the properties that should be expanded in the response. Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#query-parameters) for more details on this. */
+        expand?: string;
+        /** @description Explicitly defines which properties should be included in the response (by default all properties are included). Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#query-parameters) for more details on this. */
+        fields?: string;
+      };
+      header?: {
+        /** @description Defines the language to return. Use this when querying language variant content items. */
+        "Accept-Language"?: string;
+        /** @description Defines the segment to return. Use this when querying segment variant content items. */
+        "Accept-Segment"?: string;
+        /** @description Whether to request draft content. */
+        Preview?: boolean;
+        /** @description URL segment or GUID of a root content item. */
+        "Start-Item"?: string;
+      };
+    };
+    responses: {
+      /** @description OK */
+      200: {
+        content: {
+          "application/json": components["schemas"]["PagedIApiContentResponseModel"];
+        };
+      };
+      /** @description Bad Request */
+      400: {
+        content: {
+          "application/json": components["schemas"]["ProblemDetails"];
+        };
+      };
+      /** @description Not Found */
+      404: {
+        content: never;
+      };
+    };
+  };
+  "GetContentItemById2.0": {
+    parameters: {
+      query?: {
+        /** @description Defines the properties that should be expanded in the response. Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#query-parameters) for more details on this. */
+        expand?: string;
+        /** @description Explicitly defines which properties should be included in the response (by default all properties are included). Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#query-parameters) for more details on this. */
+        fields?: string;
+      };
+      header?: {
+        /** @description Defines the language to return. Use this when querying language variant content items. */
+        "Accept-Language"?: string;
+        /** @description Defines the segment to return. Use this when querying segment variant content items. */
+        "Accept-Segment"?: string;
+        /** @description Whether to request draft content. */
+        Preview?: boolean;
+        /** @description URL segment or GUID of a root content item. */
+        "Start-Item"?: string;
+      };
+      path: {
+        id: string;
+      };
+    };
+    responses: {
+      /** @description OK */
+      200: {
+        content: {
+          "application/json": components["schemas"]["IApiContentResponseModel"];
+        };
+      };
+      /** @description Unauthorized */
+      401: {
+        content: never;
+      };
+      /** @description Forbidden */
+      403: {
+        content: never;
+      };
+      /** @description Not Found */
+      404: {
+        content: never;
+      };
+    };
+  };
+  "GetContentItemByPath2.0": {
+    parameters: {
+      query?: {
+        /** @description Defines the properties that should be expanded in the response. Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#query-parameters) for more details on this. */
+        expand?: string;
+        /** @description Explicitly defines which properties should be included in the response (by default all properties are included). Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#query-parameters) for more details on this. */
+        fields?: string;
+      };
+      header?: {
+        /** @description Defines the language to return. Use this when querying language variant content items. */
+        "Accept-Language"?: string;
+        /** @description Defines the segment to return. Use this when querying segment variant content items. */
+        "Accept-Segment"?: string;
+        /** @description Whether to request draft content. */
+        Preview?: boolean;
+        /** @description URL segment or GUID of a root content item. */
+        "Start-Item"?: string;
+      };
+      path: {
+        path: string;
+      };
+    };
+    responses: {
+      /** @description OK */
+      200: {
+        content: {
+          "application/json": components["schemas"]["IApiContentResponseModel"];
+        };
+      };
+      /** @description Unauthorized */
+      401: {
+        content: never;
+      };
+      /** @description Forbidden */
+      403: {
+        content: never;
+      };
+      /** @description Not Found */
+      404: {
+        content: never;
+      };
+    };
+  };
+  "GetContentItems2.0": {
+    parameters: {
+      query?: {
+        id?: string[];
+        /** @description Defines the properties that should be expanded in the response. Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#query-parameters) for more details on this. */
+        expand?: string;
+        /** @description Explicitly defines which properties should be included in the response (by default all properties are included). Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api#query-parameters) for more details on this. */
+        fields?: string;
+      };
+      header?: {
+        /** @description Defines the language to return. Use this when querying language variant content items. */
+        "Accept-Language"?: string;
+        /** @description Defines the segment to return. Use this when querying segment variant content items. */
+        "Accept-Segment"?: string;
+        /** @description Whether to request draft content. */
+        Preview?: boolean;
+        /** @description URL segment or GUID of a root content item. */
+        "Start-Item"?: string;
+      };
+    };
+    responses: {
+      /** @description OK */
+      200: {
+        content: {
+          "application/json": components["schemas"]["IApiContentResponseModel"][];
+        };
+      };
+      /** @description Unauthorized */
+      401: {
+        content: never;
+      };
+      /** @description Forbidden */
+      403: {
+        content: never;
+      };
+    };
+  };
+  "GetMedia2.0": {
+    parameters: {
+      query?: {
+        /** @description Specifies the media items to fetch. Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api/media-delivery-api#query-parameters) for more details on this. */
+        fetch?: string;
+        /** @description Defines how to filter the fetched media items. Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api/media-delivery-api#query-parameters) for more details on this. */
+        filter?: string[];
+        /** @description Defines how to sort the found media items. Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api/media-delivery-api#query-parameters) for more details on this. */
+        sort?: string[];
+        /** @description Specifies the number of found media items to skip. Use this to control pagination of the response. */
+        skip?: number;
+        /** @description Specifies the number of found media items to take. Use this to control pagination of the response. */
+        take?: number;
+        /** @description Defines the properties that should be expanded in the response. Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api/media-delivery-api#query-parameters) for more details on this. */
+        expand?: string;
+        /** @description Explicitly defines which properties should be included in the response (by default all properties are included). Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api/media-delivery-api#query-parameters) for more details on this. */
+        fields?: string;
+      };
+    };
+    responses: {
+      /** @description OK */
+      200: {
+        content: {
+          "application/json": components["schemas"]["PagedIApiMediaWithCropsResponseModel"];
+        };
+      };
+      /** @description Bad Request */
+      400: {
+        content: {
+          "application/json": components["schemas"]["ProblemDetails"];
+        };
+      };
+    };
+  };
+  "GetMediaItemById2.0": {
+    parameters: {
+      query?: {
+        /** @description Defines the properties that should be expanded in the response. Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api/media-delivery-api#query-parameters) for more details on this. */
+        expand?: string;
+        /** @description Explicitly defines which properties should be included in the response (by default all properties are included). Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api/media-delivery-api#query-parameters) for more details on this. */
+        fields?: string;
+      };
+      path: {
+        id: string;
+      };
+    };
+    responses: {
+      /** @description OK */
+      200: {
+        content: {
+          "application/json": components["schemas"]["IApiMediaWithCropsResponseModel"];
+        };
+      };
+      /** @description Not Found */
+      404: {
+        content: never;
+      };
+    };
+  };
+  "GetMediaItemByPath2.0": {
+    parameters: {
+      query?: {
+        /** @description Defines the properties that should be expanded in the response. Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api/media-delivery-api#query-parameters) for more details on this. */
+        expand?: string;
+        /** @description Explicitly defines which properties should be included in the response (by default all properties are included). Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api/media-delivery-api#query-parameters) for more details on this. */
+        fields?: string;
+      };
+      path: {
+        path: string;
+      };
+    };
+    responses: {
+      /** @description OK */
+      200: {
+        content: {
+          "application/json": components["schemas"]["IApiMediaWithCropsResponseModel"];
+        };
+      };
+      /** @description Not Found */
+      404: {
+        content: never;
+      };
+    };
+  };
+  "GetMediaItems2.0": {
+    parameters: {
+      query?: {
+        id?: string[];
+        /** @description Defines the properties that should be expanded in the response. Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api/media-delivery-api#query-parameters) for more details on this. */
+        expand?: string;
+        /** @description Explicitly defines which properties should be included in the response (by default all properties are included). Refer to [the documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api/media-delivery-api#query-parameters) for more details on this. */
+        fields?: string;
+      };
+    };
+    responses: {
+      /** @description OK */
+      200: {
+        content: {
+          "application/json": components["schemas"]["IApiMediaWithCropsResponseModel"][];
+        };
+      };
+    };
+  };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@crombolo/contracts",
-  "version": "0.10.0",
-  "description": "The Umbraco Management API OpenAPI document and the TypeScript types generated from it.",
+  "version": "0.12.1",
+  "description": "The Umbraco Management and Delivery API OpenAPI documents and the TypeScript types generated from them.",
   "license": "MIT",
   "author": "Crombolo",
   "homepage": "https://github.com/kineco-au/crombolo-cms#readme",
@@ -19,11 +19,13 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./OpenApi.json": "./OpenApi.json"
+    "./OpenApi.json": "./OpenApi.json",
+    "./DeliveryApi.json": "./DeliveryApi.json"
   },
   "files": [
     "src",
     "OpenApi.json",
+    "DeliveryApi.json",
     "generated",
     "NOTICE"
   ],

package/src/spec.ts

@@ -4,6 +4,9 @@ import { join } from 'node:path'
 
 export const SPEC_PATH = join(import.meta.dir, '../OpenApi.json')
 
+/** Umbraco's Delivery API at release-18.2.0: its generic contract (story 050). */
+export const DELIVERY_SPEC_PATH = join(import.meta.dir, '../DeliveryApi.json')
+
 export const HTTP_METHODS = ['get', 'post', 'put', 'delete', 'patch'] as const
 export type HttpMethod = (typeof HTTP_METHODS)[number]
 
@@ -43,6 +46,14 @@ export function loadSpec(): OpenApiSpec {
   return cached
 }
 
+let deliveryCached: OpenApiSpec | undefined
+
+export function loadDeliverySpec(): OpenApiSpec {
+  if (!deliveryCached)
+    deliveryCached = JSON.parse(readFileSync(DELIVERY_SPEC_PATH, 'utf8')) as OpenApiSpec
+  return deliveryCached
+}
+
 export async function loadSpecAsync(): Promise<OpenApiSpec> {
   if (!cached) cached = (await Bun.file(SPEC_PATH).json()) as OpenApiSpec
   return cached

package/src/types.ts

@@ -35,3 +35,20 @@ export type RequestOf<K extends OperationId> = operations[K] extends {
 export type ParamsOf<K extends OperationId> = operations[K] extends { parameters: infer P }
   ? P
   : never
+
+import type {
+  components as DeliveryComponents,
+  operations as DeliveryOperationTable,
+} from '../generated/delivery-api.d.ts'
+
+/** The Delivery API's schemas: `DeliverySchemas['IApiContentResponseModel']`. */
+export type DeliverySchemas = DeliveryComponents['schemas']
+export type DeliveryOperations = DeliveryOperationTable
+export type DeliveryOperationId = keyof DeliveryOperationTable
+
+/** The 200 JSON body of a Delivery API operation. */
+export type DeliveryResponseOf<K extends DeliveryOperationId> = DeliveryOperationTable[K] extends {
+  responses: { 200: infer Ok }
+}
+  ? JsonContent<Ok>
+  : never