skuse-ui 0.1.0

package/dist/test-spec.json

@@ -0,0 +1,779 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Skuse Test API",
+    "summary": "A test spec covering OAS 3.1 features",
+    "version": "1.0.0",
+    "description": "Local test spec to validate Skuse features — schema.examples, global security, tag descriptions, models, etc."
+  },
+  "security": [{ "bearerAuth": [] }],
+  "tags": [
+    {
+      "name": "books",
+      "description": "Operations about books in the library",
+      "externalDocs": {
+        "description": "Books documentation",
+        "url": "https://example.com/docs/books"
+      }
+    },
+    {
+      "name": "authors",
+      "description": "Author management endpoints"
+    },
+    {
+      "name": "media",
+      "description": "Polymorphic media items — tests discriminator rendering"
+    },
+    {
+      "name": "oas31",
+      "description": "OAS 3.1 edge cases — prefixItems, if/then/else, additionalProperties:false, titled variants, canExpand on non-property schemas"
+    }
+  ],
+  "servers": [
+    { "url": "https://api.example.com/v1", "description": "Production" },
+    { "url": "https://staging.example.com/v1", "description": "Staging" }
+  ],
+  "paths": {
+    "/books": {
+      "get": {
+        "tags": ["books"],
+        "operationId": "getBooks",
+        "summary": "List all books",
+        "description": "Returns a paginated list of books. Supports filtering by author and genre.",
+        "parameters": [
+          {
+            "name": "page",
+            "in": "query",
+            "schema": { "type": "integer", "default": 1 },
+            "description": "Page number"
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": { "type": "integer", "default": 20 },
+            "description": "Items per page"
+          },
+          {
+            "name": "author",
+            "in": "query",
+            "schema": { "type": "string" },
+            "description": "Filter by author name",
+            "deprecated": true
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A list of books",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BookList"
+                }
+              }
+            },
+            "links": {
+              "GetBookById": {
+                "operationId": "getBook",
+                "parameters": { "id": "$response.body#/data/0/id" },
+                "description": "Use the id of the first book to fetch its details"
+              },
+              "ListAuthors": {
+                "operationId": "getAuthors",
+                "description": "Browse authors of the returned books"
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "tags": ["books"],
+        "operationId": "createBook",
+        "summary": "Create a book",
+        "security": [{ "bearerAuth": [] }],
+        "callbacks": {
+          "onBookIndexed": {
+            "{$request.body#/callbackUrl}": {
+              "post": {
+                "summary": "Book indexed notification",
+                "description": "Sent when the newly created book has been indexed and is searchable.",
+                "requestBody": {
+                  "required": true,
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "object",
+                        "properties": {
+                          "bookId": { "type": "integer", "description": "ID of the indexed book" },
+                          "indexedAt": { "type": "string", "format": "date-time" }
+                        }
+                      }
+                    }
+                  }
+                },
+                "responses": {
+                  "200": { "description": "Callback received" }
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BookInput"
+              },
+              "examples": {
+                "fiction": {
+                  "summary": "Fiction book",
+                  "value": { "title": "Dune", "author": "Frank Herbert", "genre": "fiction", "year": 1965 }
+                },
+                "nonfiction": {
+                  "summary": "Non-fiction book",
+                  "value": { "title": "Sapiens", "author": "Yuval Noah Harari", "genre": "history", "year": 2011 }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Book created",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Book" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/books/{id}": {
+      "summary": "Operations on a specific book",
+      "description": "All endpoints under this path operate on a single book identified by its numeric `id`.",
+      "get": {
+        "tags": ["books"],
+        "operationId": "getBook",
+        "summary": "Get a book",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "integer" },
+            "description": "Book ID"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A single book. The schema.examples array (OAS 3.1) is used here to test the multi-example selector.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "id": { "type": "integer" },
+                    "title": { "type": "string" },
+                    "author": { "type": "string" },
+                    "genre": { "type": "string", "enum": ["fiction", "nonfiction", "history", "science"] },
+                    "year": { "type": "integer" },
+                    "available": { "type": "boolean" }
+                  },
+                  "examples": [
+                    { "id": 1, "title": "Dune", "author": "Frank Herbert", "genre": "fiction", "year": 1965, "available": true },
+                    { "id": 2, "title": "Sapiens", "author": "Yuval Noah Harari", "genre": "history", "year": 2011, "available": false },
+                    { "id": 3, "title": "A Brief History of Time", "author": "Stephen Hawking", "genre": "science", "year": 1988, "available": true }
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Book not found"
+          }
+        }
+      },
+      "delete": {
+        "tags": ["books"],
+        "operationId": "deleteBook",
+        "summary": "Delete a book",
+        "description": "Permanently deletes a book. This action cannot be undone.",
+        "security": [],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "integer" }
+          }
+        ],
+        "responses": {
+          "204": { "description": "Deleted successfully" },
+          "403": { "description": "Forbidden" }
+        }
+      }
+    },
+    "/authors": {
+      "get": {
+        "tags": ["authors"],
+        "operationId": "getAuthors",
+        "summary": "List authors",
+        "responses": {
+          "200": {
+            "description": "List of authors",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/AuthorList" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/authors/{id}": {
+      "get": {
+        "tags": ["authors"],
+        "operationId": "getAuthor",
+        "summary": "Get an author",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "integer" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Author details",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Author" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/books/{id}/cover": {
+      "put": {
+        "tags": ["books"],
+        "operationId": "uploadBookCover",
+        "summary": "Upload a book cover image",
+        "description": "Tests `contentMediaType` and `contentEncoding` rendering (OAS 3.1).",
+        "parameters": [
+          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["filename", "data"],
+                "properties": {
+                  "filename": { "type": "string", "description": "Original filename" },
+                  "data": {
+                    "type": "string",
+                    "contentMediaType": "image/png",
+                    "contentEncoding": "base64",
+                    "description": "Base64-encoded PNG image"
+                  },
+                  "thumbnail": {
+                    "type": "string",
+                    "contentMediaType": "image/jpeg",
+                    "contentEncoding": "base64",
+                    "description": "Optional base64-encoded JPEG thumbnail"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": { "description": "Cover uploaded" }
+        }
+      }
+    },
+    "/validate": {
+      "post": {
+        "tags": ["media"],
+        "operationId": "validateId",
+        "summary": "Validate a strict identifier",
+        "description": "Tests `not` schema rendering — the request body uses `StrictId` which contains `not` constraints.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/StrictId" }
+            }
+          }
+        },
+        "responses": {
+          "200": { "description": "Valid" },
+          "422": { "description": "Validation error" }
+        }
+      }
+    },
+    "/geo/track": {
+      "get": {
+        "tags": ["oas31"],
+        "operationId": "getGeoTrack",
+        "summary": "Get a GPS track",
+        "description": "Returns an array of `GeoPoint` tuples. Tests **prefixItems** rendering — each point is a `[latitude, longitude, elevation]` tuple. The extra `items: false` means no additional positional items are allowed beyond the three defined.",
+        "responses": {
+          "200": {
+            "description": "Array of GPS points",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": { "$ref": "#/components/schemas/GeoPoint" }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/events": {
+      "post": {
+        "tags": ["oas31"],
+        "operationId": "createEvent",
+        "summary": "Create an event",
+        "description": "Tests **if/then/else** conditional schemas. If `type` is `online`, the `url` field becomes required. Otherwise, `location` is required instead.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/EventPayload" }
+            }
+          }
+        },
+        "responses": {
+          "201": { "description": "Event created" }
+        }
+      }
+    },
+    "/config": {
+      "get": {
+        "tags": ["oas31"],
+        "operationId": "getConfig",
+        "summary": "Get user configuration",
+        "description": "Tests **additionalProperties: false** — the response schema is a closed object. No properties beyond `theme` and `language` are permitted.",
+        "responses": {
+          "200": {
+            "description": "User configuration",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/StrictConfig" }
+              }
+            }
+          }
+        }
+      },
+      "put": {
+        "tags": ["oas31"],
+        "operationId": "updateConfig",
+        "summary": "Update user configuration",
+        "description": "Same closed schema on the request body.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/StrictConfig" }
+            }
+          }
+        },
+        "responses": {
+          "200": { "description": "Configuration updated" }
+        }
+      }
+    },
+    "/metrics": {
+      "post": {
+        "tags": ["oas31"],
+        "operationId": "pushMetrics",
+        "summary": "Push a metric bag",
+        "description": "Tests **patternProperties** + **additionalProperties as object** together. `MetricBag` has one fixed field (`timestamp`), any key matching `^metric_` must be a number, and all other extra keys must be strings. The childCount badge should reflect all three categories.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/MetricBag" }
+            }
+          }
+        },
+        "responses": {
+          "204": { "description": "Metrics recorded" }
+        }
+      }
+    },
+    "/shapes": {
+      "post": {
+        "tags": ["oas31"],
+        "operationId": "createShape",
+        "summary": "Create a shape",
+        "description": "Tests **title in oneOf variants** and **required-first sort inside renderCompositeOption**. Each variant has a `title` (`Circle`, `Rectangle`) and a mix of required / optional properties — required ones should appear first in the expanded view.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/Shape" }
+            }
+          }
+        },
+        "responses": {
+          "201": { "description": "Shape created" }
+        }
+      }
+    },
+    "/payloads": {
+      "post": {
+        "tags": ["oas31"],
+        "operationId": "sendPayload",
+        "summary": "Send a flexible payload",
+        "description": "Tests **canExpand on a variant with no direct properties**. The `Freeform` variant has only `additionalProperties: {type: string}` and no `properties` object — it must still be expandable and show the `[key: string]` row.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/FlexPayload" }
+            }
+          }
+        },
+        "responses": {
+          "200": { "description": "Payload accepted" }
+        }
+      }
+    },
+    "/media": {
+      "post": {
+        "tags": ["media"],
+        "operationId": "createMedia",
+        "summary": "Add a media item",
+        "description": "Creates a media item. The `mediaType` field acts as a discriminator to determine which schema variant to use.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/Media" }
+            }
+          }
+        },
+        "responses": {
+          "201": { "description": "Media item created" }
+        }
+      },
+      "get": {
+        "tags": ["media"],
+        "operationId": "listMedia",
+        "summary": "List media items",
+        "responses": {
+          "200": {
+            "description": "A list of media items",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": { "$ref": "#/components/schemas/Media" }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "webhooks": {
+    "newBook": {
+      "post": {
+        "operationId": "webhookNewBook",
+        "summary": "New book created",
+        "description": "Fired whenever a new book is added to the library. Your endpoint should respond with a 2xx status to acknowledge receipt.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/Book" }
+            }
+          }
+        },
+        "responses": {
+          "200": { "description": "Webhook acknowledged" }
+        }
+      }
+    },
+    "bookDeleted": {
+      "post": {
+        "operationId": "webhookBookDeleted",
+        "summary": "Book deleted",
+        "description": "Fired when a book is permanently removed from the system.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "id": { "type": "integer" },
+                  "deletedAt": { "type": "string", "format": "date-time" }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": { "description": "Acknowledged" }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
+      }
+    },
+    "schemas": {
+      "Book": {
+        "type": "object",
+        "title": "Book",
+        "description": "Represents a book in the library system",
+        "required": ["id", "title", "author"],
+        "properties": {
+          "id": { "type": "integer", "description": "Unique identifier" },
+          "title": { "type": "string", "description": "Book title" },
+          "author": { "type": "string", "description": "Author name" },
+          "genre": {
+            "type": "string",
+            "title": "BookGenre",
+            "enum": ["fiction", "nonfiction", "history", "science"],
+            "description": "Book genre"
+          },
+          "year": { "type": "integer", "description": "Publication year" },
+          "available": { "type": "boolean", "description": "Whether the book is available for borrowing" }
+        }
+      },
+      "BookInput": {
+        "type": "object",
+        "description": "Payload for creating or updating a book",
+        "required": ["title", "author"],
+        "properties": {
+          "title": { "type": "string" },
+          "author": { "type": "string" },
+          "genre": { "type": "string", "enum": ["fiction", "nonfiction", "history", "science"] },
+          "year": { "type": "integer" }
+        }
+      },
+      "BookList": {
+        "type": "object",
+        "properties": {
+          "data": {
+            "type": "array",
+            "items": { "$ref": "#/components/schemas/Book" }
+          },
+          "total": { "type": "integer" },
+          "page": { "type": "integer" },
+          "limit": { "type": "integer" }
+        }
+      },
+      "Author": {
+        "type": "object",
+        "description": "An author in the library system",
+        "required": ["id", "name"],
+        "properties": {
+          "id": { "type": "integer" },
+          "name": { "type": "string" },
+          "bio": { "type": "string" },
+          "birthYear": { "type": "integer" },
+          "nationality": { "type": "string" }
+        }
+      },
+      "AuthorList": {
+        "type": "object",
+        "properties": {
+          "data": {
+            "type": "array",
+            "items": { "$ref": "#/components/schemas/Author" }
+          },
+          "total": { "type": "integer" }
+        }
+      },
+      "Media": {
+        "description": "A polymorphic media item. Use `mediaType` to select the correct variant.",
+        "oneOf": [
+          { "$ref": "#/components/schemas/AudioBook" },
+          { "$ref": "#/components/schemas/EBook" },
+          { "$ref": "#/components/schemas/PrintBook" }
+        ],
+        "discriminator": {
+          "propertyName": "mediaType",
+          "mapping": {
+            "audio": "#/components/schemas/AudioBook",
+            "ebook": "#/components/schemas/EBook",
+            "print": "#/components/schemas/PrintBook"
+          }
+        }
+      },
+      "AudioBook": {
+        "type": "object",
+        "description": "An audio book with a narrator and duration",
+        "required": ["mediaType", "title", "narrator", "durationMinutes"],
+        "properties": {
+          "mediaType": { "type": "string", "enum": ["audio"] },
+          "title": { "type": "string" },
+          "narrator": { "type": "string", "description": "Name of the narrator" },
+          "durationMinutes": { "type": "integer", "description": "Total duration in minutes" }
+        }
+      },
+      "EBook": {
+        "type": "object",
+        "description": "A digital e-book",
+        "required": ["mediaType", "title", "format"],
+        "properties": {
+          "mediaType": { "type": "string", "enum": ["ebook"] },
+          "title": { "type": "string" },
+          "format": { "type": "string", "enum": ["epub", "pdf", "mobi"], "description": "File format" },
+          "fileSizeKb": { "type": "integer", "description": "File size in kilobytes" }
+        }
+      },
+      "NonEmptyString": {
+        "type": "string",
+        "description": "A string that must not be empty or null",
+        "not": { "type": "string", "maxLength": 0 }
+      },
+      "StrictId": {
+        "type": "object",
+        "title": "StrictIdentifier",
+        "description": "An identifier that must not be a negative number",
+        "properties": {
+          "id": {
+            "type": "integer",
+            "not": { "minimum": -1, "maximum": -1 }
+          },
+          "label": { "$ref": "#/components/schemas/NonEmptyString" }
+        }
+      },
+      "GeoPoint": {
+        "type": "array",
+        "title": "GeoPoint",
+        "description": "A GPS coordinate tuple `[latitude, longitude, elevation]`. Uses **prefixItems** — each position has its own type and description. `items: false` forbids extra positions beyond the three defined.",
+        "prefixItems": [
+          { "type": "number", "description": "Latitude in decimal degrees", "minimum": -90, "maximum": 90 },
+          { "type": "number", "description": "Longitude in decimal degrees", "minimum": -180, "maximum": 180 },
+          { "type": "number", "description": "Elevation in metres above sea level" }
+        ],
+        "items": false,
+        "minItems": 3,
+        "maxItems": 3
+      },
+      "EventPayload": {
+        "type": "object",
+        "title": "EventPayload",
+        "description": "An event. Uses **if/then/else** — `url` is required for online events, `location` is required for in-person events.",
+        "required": ["type", "name"],
+        "properties": {
+          "type": { "type": "string", "enum": ["online", "in-person"], "description": "Event delivery mode" },
+          "name": { "type": "string", "description": "Event name" },
+          "url": { "type": "string", "format": "uri", "description": "Stream URL (online events only)" },
+          "location": { "type": "string", "description": "Physical location (in-person events only)" }
+        },
+        "if": {
+          "properties": { "type": { "const": "online" } }
+        },
+        "then": {
+          "required": ["url"],
+          "properties": { "url": { "type": "string", "format": "uri" } }
+        },
+        "else": {
+          "required": ["location"],
+          "properties": { "location": { "type": "string" } }
+        }
+      },
+      "StrictConfig": {
+        "type": "object",
+        "title": "StrictConfig",
+        "description": "User configuration object. **additionalProperties: false** — no fields beyond `theme` and `language` are accepted.",
+        "additionalProperties": false,
+        "required": ["theme"],
+        "properties": {
+          "theme": { "type": "string", "enum": ["light", "dark", "system"], "description": "UI colour scheme" },
+          "language": { "type": "string", "description": "BCP-47 language tag, e.g. `en-US`" }
+        }
+      },
+      "MetricBag": {
+        "type": "object",
+        "title": "MetricBag",
+        "description": "A named bag of metrics. Tests **patternProperties** + **additionalProperties as object**. Keys starting with `metric_` must be numbers; all other extra keys must be strings. The collapsed childCount badge should reflect all three entry types.",
+        "properties": {
+          "timestamp": { "type": "string", "format": "date-time", "description": "Collection timestamp" }
+        },
+        "patternProperties": {
+          "^metric_": { "type": "number", "description": "A numeric metric value" }
+        },
+        "additionalProperties": { "type": "string", "description": "Arbitrary string metadata" }
+      },
+      "Shape": {
+        "description": "A 2-D shape. Tests **title on oneOf variants** and **required-first sort** — required fields (`radius` / `width`+`height`) should appear before optional ones (`color`, `opacity`) in the expanded view.",
+        "oneOf": [
+          {
+            "title": "Circle",
+            "type": "object",
+            "required": ["radius"],
+            "properties": {
+              "color": { "type": "string", "description": "Fill colour" },
+              "opacity": { "type": "number", "minimum": 0, "maximum": 1, "description": "Opacity 0–1" },
+              "radius": { "type": "number", "description": "Radius in pixels" }
+            }
+          },
+          {
+            "title": "Rectangle",
+            "type": "object",
+            "required": ["width", "height"],
+            "properties": {
+              "color": { "type": "string", "description": "Fill colour" },
+              "width": { "type": "number", "description": "Width in pixels" },
+              "height": { "type": "number", "description": "Height in pixels" }
+            }
+          }
+        ]
+      },
+      "FlexPayload": {
+        "description": "Tests **canExpand on a variant without direct properties**. `Freeform` has only `additionalProperties` (no `properties` key) — it must still be expandable and display a `[key: string]: string` row.",
+        "oneOf": [
+          {
+            "title": "Fixed",
+            "type": "object",
+            "description": "A payload with well-known keys",
+            "required": ["key", "value"],
+            "properties": {
+              "key": { "type": "string" },
+              "value": { "type": "string" }
+            }
+          },
+          {
+            "title": "Freeform",
+            "type": "object",
+            "description": "Any string key-value pairs — no fixed properties",
+            "additionalProperties": { "type": "string" }
+          }
+        ]
+      },
+      "PrintBook": {
+        "type": "object",
+        "description": "A physical print book",
+        "required": ["mediaType", "title", "isbn"],
+        "properties": {
+          "mediaType": { "type": "string", "enum": ["print"] },
+          "title": { "type": "string" },
+          "isbn": { "type": "string", "description": "ISBN-13 identifier" },
+          "pageCount": { "type": "integer" }
+        }
+      }
+    }
+  }
+}