@golemio/fypr 1.1.1-dev.2368450356 → 1.1.1-dev.2387575538

package/docs/openapi-output.yaml

@@ -24,19 +24,58 @@ tags:
       description: Data about physical (on-site) information elements of the Legible Prague system.
 
 paths:
-    /v1/fypr/display-cases:
+    /v1/fypr/elements:
         get:
             tags:
                 - FYPR (v1)
-            summary: GET All Display Cases
+            summary: GET FYPR links to elements kinds
+            operationId: listFyprElementsKinds
+            responses:
+                "200":
+                    description: OK
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required:
+                                    - links
+                                properties:
+                                    links:
+                                        type: array
+                                        items:
+                                            type: object
+                                            required:
+                                                - rel
+                                                - href
+                                            properties:
+                                                rel:
+                                                    type: string
+                                                    example: display-cases
+                                                    description: >-
+                                                        Relation name identifying the element kind.
+                                                href:
+                                                    type: string
+                                                    example: /v1/fypr/elements/display-cases
+                                                    description: >-
+                                                        Absolute path to the list endpoint for this element kind.
+
+    /v1/fypr/elements/display-cases:
+        get:
+            tags:
+                - FYPR (v1)
+            summary: GET Display Cases
             operationId: listDisplayCases
             parameters:
-                - $ref: "#/components/parameters/limit"
-                - $ref: "#/components/parameters/offset"
+                - $ref: "#/components/parameters/Limit"
+                - $ref: "#/components/parameters/Offset"
             responses:
                 "200":
                     description: OK
-
+                    headers:
+                        Last-Modified:
+                            $ref: "#/components/headers/LastModified"
+                        Cache-Control:
+                            $ref: "#/components/headers/CacheControlNoCache"
                     content:
                         application/json:
                             schema:
@@ -45,22 +84,26 @@ paths:
                                     $ref: "#/components/schemas/DisplayCase"
                 "400":
                     $ref: "#/components/responses/BadRequestError"
-                "401":
-                    $ref: "#/components/responses/UnauthorizedError"
+                "413":
+                    $ref: "#/components/responses/ContentTooLargeError"
 
-    /v1/fypr/information-panels:
+    /v1/fypr/elements/information-panels:
         get:
             tags:
                 - FYPR (v1)
-            summary: GET All Information Panels
+            summary: GET Information Panels
             operationId: listInformationPanels
             parameters:
-                - $ref: "#/components/parameters/limit"
-                - $ref: "#/components/parameters/offset"
+                - $ref: "#/components/parameters/Limit"
+                - $ref: "#/components/parameters/Offset"
             responses:
                 "200":
                     description: OK
-
+                    headers:
+                        Last-Modified:
+                            $ref: "#/components/headers/LastModified"
+                        Cache-Control:
+                            $ref: "#/components/headers/CacheControlNoCache"
                     content:
                         application/json:
                             schema:
@@ -69,22 +112,26 @@ paths:
                                     $ref: "#/components/schemas/InformationPanel"
                 "400":
                     $ref: "#/components/responses/BadRequestError"
-                "401":
-                    $ref: "#/components/responses/UnauthorizedError"
+                "413":
+                    $ref: "#/components/responses/ContentTooLargeError"
 
-    /v1/fypr/obelisks:
+    /v1/fypr/elements/obelisks:
         get:
             tags:
                 - FYPR (v1)
-            summary: GET All Obelisks
+            summary: GET Obelisks
             operationId: listObelisks
             parameters:
-                - $ref: "#/components/parameters/limit"
-                - $ref: "#/components/parameters/offset"
+                - $ref: "#/components/parameters/Limit"
+                - $ref: "#/components/parameters/Offset"
             responses:
                 "200":
                     description: OK
-
+                    headers:
+                        Last-Modified:
+                            $ref: "#/components/headers/LastModified"
+                        Cache-Control:
+                            $ref: "#/components/headers/CacheControlNoCache"
                     content:
                         application/json:
                             schema:
@@ -93,22 +140,26 @@ paths:
                                     $ref: "#/components/schemas/Obelisk"
                 "400":
                     $ref: "#/components/responses/BadRequestError"
-                "401":
-                    $ref: "#/components/responses/UnauthorizedError"
+                "413":
+                    $ref: "#/components/responses/ContentTooLargeError"
 
-    /v1/fypr/signposts:
+    /v1/fypr/elements/signposts:
         get:
             tags:
                 - FYPR (v1)
-            summary: GET All Signposts
+            summary: GET Signposts
             operationId: listSignposts
             parameters:
-                - $ref: "#/components/parameters/limit"
-                - $ref: "#/components/parameters/offset"
+                - $ref: "#/components/parameters/Limit"
+                - $ref: "#/components/parameters/Offset"
             responses:
                 "200":
                     description: OK
-
+                    headers:
+                        Last-Modified:
+                            $ref: "#/components/headers/LastModified"
+                        Cache-Control:
+                            $ref: "#/components/headers/CacheControlNoCache"
                     content:
                         application/json:
                             schema:
@@ -117,22 +168,26 @@ paths:
                                     $ref: "#/components/schemas/Signpost"
                 "400":
                     $ref: "#/components/responses/BadRequestError"
-                "401":
-                    $ref: "#/components/responses/UnauthorizedError"
+                "413":
+                    $ref: "#/components/responses/ContentTooLargeError"
 
-    /v1/fypr/totems:
+    /v1/fypr/elements/totems:
         get:
             tags:
                 - FYPR (v1)
-            summary: GET All Totems
+            summary: GET Totems
             operationId: listTotems
             parameters:
-                - $ref: "#/components/parameters/limit"
-                - $ref: "#/components/parameters/offset"
+                - $ref: "#/components/parameters/Limit"
+                - $ref: "#/components/parameters/Offset"
             responses:
                 "200":
                     description: OK
-
+                    headers:
+                        Last-Modified:
+                            $ref: "#/components/headers/LastModified"
+                        Cache-Control:
+                            $ref: "#/components/headers/CacheControlNoCache"
                     content:
                         application/json:
                             schema:
@@ -141,31 +196,337 @@ paths:
                                     $ref: "#/components/schemas/Totem"
                 "400":
                     $ref: "#/components/responses/BadRequestError"
-                "401":
-                    $ref: "#/components/responses/UnauthorizedError"
+                "413":
+                    $ref: "#/components/responses/ContentTooLargeError"
+
+    /v1/fypr/elements/{kind}/{id}:
+        get:
+            tags:
+                - FYPR (v1)
+            summary: GET FYPR element by kind and id
+            operationId: getFyprElementDetail
+            parameters:
+                - $ref: "#/components/parameters/Kind"
+                - name: id
+                  in: path
+                  required: true
+                  schema:
+                      $ref: "#/components/schemas/ElementId"
+                  description: >-
+                      UUID of the element to retrieve.
+            responses:
+                "200":
+                    description: OK
+                    headers:
+                        Last-Modified:
+                            $ref: "#/components/headers/LastModified"
+                        Cache-Control:
+                            $ref: "#/components/headers/CacheControlNoCache"
+                    content:
+                        application/json:
+                            schema:
+                                oneOf:
+                                    - $ref: "#/components/schemas/DisplayCase"
+                                    - $ref: "#/components/schemas/InformationPanel"
+                                    - $ref: "#/components/schemas/Obelisk"
+                                    - $ref: "#/components/schemas/Signpost"
+                                    - $ref: "#/components/schemas/Totem"
+                "400":
+                    $ref: "#/components/responses/BadRequestError"
+                "404":
+                    $ref: "#/components/responses/NotFoundError"
 
 components:
     parameters:
-        limit:
+        Limit:
             name: limit
             in: query
             required: false
-            example: 10
             schema:
                 type: integer
+                minimum: 1
+                maximum: 10000
+                default: 100
             description: >-
                 Limits number of retrieved items.
 
-        offset:
+        Offset:
             name: offset
             in: query
             required: false
             example: 0
             schema:
                 type: integer
-            description: Offset for pagination. The default value is 0.
+                minimum: 0
+                default: 0
+            description: >-
+                Offset for pagination. The default value is 0.
+
+        Kind:
+            name: kind
+            in: path
+            required: true
+            schema:
+                type: string
+                enum:
+                    - display-cases
+                    - information-panels
+                    - obelisks
+                    - signposts
+                    - totems
+            description: >-
+                Kind of the FYPR element.
+
+    headers:
+        LastModified:
+            description: Timestamp of the latest resource update.
+            schema:
+                type: string
+                example: "2024-08-12T12:40:30.000Z"
+        CacheControlNoCache:
+            description: Cache control directive for caching proxies
+            schema:
+                type: string
+                example: max-age=300, stale-while-revalidate=60
+
+    responses:
+        ContentTooLargeError:
+            description: Content too large - limit query parameter exceeds maximum (10000)
+            content:
+                application/json:
+                    schema:
+                        type: object
+                        properties:
+                            error_message:
+                                type: string
+                                example: "Pagination limit error"
+                                nullable: false
+                            error_status:
+                                type: integer
+                                example: 413
+                                nullable: false
+                            error_info:
+                                type: string
+                                example: "{...}"
+                                nullable: true
+                        required:
+                            - error_message
+                            - error_status
+
+        NotFoundError:
+            description: Not found - the requested resource does not exist
+            content:
+                application/json:
+                    schema:
+                        type: object
+                        properties:
+                            error_message:
+                                type: string
+                                example: "Not found"
+                                nullable: false
+                            error_status:
+                                type: integer
+                                example: 404
+                                nullable: false
+                            error_info:
+                                type: string
+                                example: "{...}"
+                                nullable: true
+                        required:
+                            - error_message
+                            - error_status
+
+        BadRequestError:
+            description: Bad request - invalid query parameters
+            content:
+                application/json:
+                    schema:
+                        type: object
+                        properties:
+                            error_message:
+                                type: string
+                                example: "Bad request"
+                                nullable: false
+                            error_status:
+                                type: integer
+                                example: 400
+                                nullable: false
+                            error_info:
+                                type: string
+                                example: "{...}"
+                                nullable: true
+                        required:
+                            - error_message
+                            - error_status
 
     schemas:
+        ElementId:
+            type: string
+            format: uuid
+            example: "1b75c16b-d5a3-40ca-8560-5a7dc011655d"
+            description: >-
+                Unique identifier for an element. UUID v4, server-generated.
+
+        ElementReadOnly:
+            type: object
+            description: >-
+                Server-set fields that clients can only read. All properties carry
+                readOnly: true. Composed via allOf into each typed element schema.
+            properties:
+                id:
+                    allOf:
+                        - $ref: "#/components/schemas/ElementId"
+                    readOnly: true
+                    description: >-
+                        Server-generated UUID primary key. Immutable after creation.
+                source_created_at:
+                    type: string
+                    format: date-time
+                    readOnly: true
+                    example: "2024-01-15T08:30:00.000Z"
+                    description: >-
+                        Timestamp when the record was first created in the upstream CMS
+                        (Strapi). ISO 8601 UTC. Server-set, not writable by clients.
+                source_updated_at:
+                    type: string
+                    format: date-time
+                    readOnly: true
+                    example: "2024-08-12T12:40:30.000Z"
+                    description: >-
+                        Timestamp of the most recent update in the upstream CMS (Strapi).
+                        ISO 8601 UTC. Server-set, not writable by clients.
+                source_published_at:
+                    type: string
+                    format: date-time
+                    readOnly: true
+                    example: "2024-08-12T13:00:00.000Z"
+                    description: >-
+                        Timestamp when the record was published in the upstream CMS
+                        (Strapi). ISO 8601 UTC. Server-set, not writable by clients.
+
+        ElementBase:
+            type: object
+            description: >-
+                Writable base fields shared by all FYPR element types. No id or timestamps.
+                Composed via allOf by each typed element schema.
+            required:
+                - document_id
+                - kind
+            properties:
+                document_id:
+                    type: string
+                    nullable: false
+                    example: "abc123def456"
+                    description: >-
+                        Unique document identifier sourced from the upstream CMS (Strapi).
+                        Used as the stable external reference for deduplication.
+                uid:
+                    type: string
+                    format: uuid
+                    nullable: true
+                    example: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+                    description: >-
+                        Optional external UUID assigned to the physical element by the
+                        field operations team. May be null for elements not yet assigned.
+                kind:
+                    type: string
+                    nullable: false
+                    enum:
+                        - totem
+                        - information_panel
+                        - display_case
+                        - obelisk
+                        - signpost
+                    example: "totem"
+                    description: >-
+                        Discriminator field identifying the element type. Determines which
+                        typed schema applies (Totem, InformationPanel, DisplayCase, Obelisk,
+                        Signpost).
+                name:
+                    type: string
+                    nullable: true
+                    example: "Totem Palackeho namesti"
+                    description: Human-readable name of the element. May be null.
+                state:
+                    type: string
+                    nullable: true
+                    example: "REALIZED"
+                    description: >-
+                        Lifecycle state of the element (e.g. PLANNED, IN_PROGRESS,
+                        REALIZED). Sourced from CMS. May be null.
+                owner:
+                    type: string
+                    nullable: true
+                    example: "ROPID"
+                    description: >-
+                        Organization or entity that owns the element. May be null.
+                manager:
+                    type: string
+                    nullable: true
+                    example: "THMP"
+                    description: >-
+                        Organization or entity that manages the element. May be null.
+                city_district:
+                    type: string
+                    nullable: true
+                    example: "Praha 6"
+                    description: >-
+                        Prague city district where the element is physically located.
+                        May be null.
+                lat:
+                    type: number
+                    format: double
+                    nullable: true
+                    example: 50.0755
+                    description: >-
+                        WGS-84 latitude coordinate of the element's installation site.
+                        May be null if coordinates are not yet surveyed.
+                lon:
+                    type: number
+                    format: double
+                    nullable: true
+                    example: 14.4378
+                    description: >-
+                        WGS-84 longitude coordinate of the element's installation site.
+                        May be null if coordinates are not yet surveyed.
+                map_link:
+                    type: string
+                    nullable: true
+                    example: "https://mapy.cz/s/example"
+                    description: >-
+                        URL to an external map view showing the element location.
+                        May be null.
+                planned_year_of_realization:
+                    type: string
+                    nullable: true
+                    example: "2025"
+                    description: >-
+                        Year in which the element is planned to be realized or installed.
+                        Stored as string to accommodate partial or estimated values.
+                        May be null.
+                note:
+                    type: string
+                    nullable: true
+                    example: "Installed near bus stop exit B."
+                    description: >-
+                        Free-text operational note attached to the element by field staff.
+                        May be null.
+                handover:
+                    type: boolean
+                    nullable: true
+                    example: true
+                    description: >-
+                        Indicates whether the element has been handed over to the
+                        maintenance team. May be null if handover status is unknown.
+                handover_date:
+                    type: string
+                    format: date
+                    nullable: true
+                    example: "2024-08-12"
+                    description: >-
+                        Date on which the element was formally handed over to the
+                        maintenance team. ISO 8601 date. May be null.
+
         DisplayCase:
             description: >-
                 Fully composed DisplayCase schema for list responses. Combines DisplayCaseBase
@@ -327,167 +688,6 @@ components:
                               Scheduled cleaning frequency for the display case (e.g. daily,
                               weekly, monthly). May be null if no cleaning schedule is set.
 
-        ElementBase:
-            type: object
-            description: >-
-                Writable base fields shared by all FYPR element types. No id or timestamps.
-                Composed via allOf by each typed element schema.
-            required:
-                - document_id
-                - kind
-            properties:
-                document_id:
-                    type: string
-                    nullable: false
-                    example: "abc123def456"
-                    description: >-
-                        Unique document identifier sourced from the upstream CMS (Strapi).
-                        Used as the stable external reference for deduplication.
-                uid:
-                    type: string
-                    format: uuid
-                    nullable: true
-                    example: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
-                    description: >-
-                        Optional external UUID assigned to the physical element by the
-                        field operations team. May be null for elements not yet assigned.
-                kind:
-                    type: string
-                    nullable: false
-                    enum:
-                        - totem
-                        - information_panel
-                        - display_case
-                        - obelisk
-                        - signpost
-                    example: "totem"
-                    description: >-
-                        Discriminator field identifying the element type. Determines which
-                        typed schema applies (Totem, InformationPanel, DisplayCase, Obelisk,
-                        Signpost).
-                name:
-                    type: string
-                    nullable: true
-                    example: "Totem Palackeho namesti"
-                    description: Human-readable name of the element. May be null.
-                state:
-                    type: string
-                    nullable: true
-                    example: "REALIZED"
-                    description: >-
-                        Lifecycle state of the element (e.g. PLANNED, IN_PROGRESS,
-                        REALIZED). Sourced from CMS. May be null.
-                owner:
-                    type: string
-                    nullable: true
-                    example: "ROPID"
-                    description: >-
-                        Organization or entity that owns the element. May be null.
-                city_district:
-                    type: string
-                    nullable: true
-                    example: "Praha 6"
-                    description: >-
-                        Prague city district where the element is physically located.
-                        May be null.
-                lat:
-                    type: number
-                    format: double
-                    nullable: true
-                    example: 50.0755
-                    description: >-
-                        WGS-84 latitude coordinate of the element's installation site.
-                        May be null if coordinates are not yet surveyed.
-                lon:
-                    type: number
-                    format: double
-                    nullable: true
-                    example: 14.4378
-                    description: >-
-                        WGS-84 longitude coordinate of the element's installation site.
-                        May be null if coordinates are not yet surveyed.
-                map_link:
-                    type: string
-                    nullable: true
-                    example: "https://mapy.cz/s/example"
-                    description: >-
-                        URL to an external map view showing the element location.
-                        May be null.
-                planned_year_of_realization:
-                    type: string
-                    nullable: true
-                    example: "2025"
-                    description: >-
-                        Year in which the element is planned to be realized or installed.
-                        Stored as string to accommodate partial or estimated values.
-                        May be null.
-                note:
-                    type: string
-                    nullable: true
-                    example: "Installed near bus stop exit B."
-                    description: >-
-                        Free-text operational note attached to the element by field staff.
-                        May be null.
-                handover:
-                    type: boolean
-                    nullable: true
-                    example: true
-                    description: >-
-                        Indicates whether the element has been handed over to the
-                        maintenance team. May be null if handover status is unknown.
-                handover_date:
-                    type: string
-                    format: date
-                    nullable: true
-                    example: "2024-08-12"
-                    description: >-
-                        Date on which the element was formally handed over to the
-                        maintenance team. ISO 8601 date. May be null.
-
-        ElementId:
-            type: string
-            format: uuid
-            example: "1b75c16b-d5a3-40ca-8560-5a7dc011655d"
-            description: >-
-                Unique identifier for an element. UUID v4, server-generated.
-
-        ElementReadOnly:
-            type: object
-            description: >-
-                Server-set fields that clients can only read. All properties carry
-                readOnly: true. Composed via allOf into each typed element schema.
-            properties:
-                id:
-                    allOf:
-                        - $ref: "#/components/schemas/ElementId"
-                    readOnly: true
-                    description: >-
-                        Server-generated UUID primary key. Immutable after creation.
-                source_created_at:
-                    type: string
-                    format: date-time
-                    readOnly: true
-                    example: "2024-01-15T08:30:00.000Z"
-                    description: >-
-                        Timestamp when the record was first created in the upstream CMS
-                        (Strapi). ISO 8601 UTC. Server-set, not writable by clients.
-                source_updated_at:
-                    type: string
-                    format: date-time
-                    readOnly: true
-                    example: "2024-08-12T12:40:30.000Z"
-                    description: >-
-                        Timestamp of the most recent update in the upstream CMS (Strapi).
-                        ISO 8601 UTC. Server-set, not writable by clients.
-                source_published_at:
-                    type: string
-                    format: date-time
-                    readOnly: true
-                    example: "2024-08-12T13:00:00.000Z"
-                    description: >-
-                        Timestamp when the record was published in the upstream CMS
-                        (Strapi). ISO 8601 UTC. Server-set, not writable by clients.
-
         InformationPanel:
             description: >-
                 Fully composed information panel schema. Combines InformationPanelBase (writable
@@ -1041,6 +1241,41 @@ components:
                           example: "SN-2024-00042"
                           description: >-
                               Manufacturer's serial number of the panel unit. May be null.
+                      producer:
+                          type: string
+                          nullable: true
+                          description: >-
+                              Name of the panel manufacturer. May be null.
+                      producer_contact_person:
+                          type: string
+                          nullable: true
+                          description: >-
+                              Contact person at the panel manufacturer. May be null.
+                      panel_technology:
+                          type: string
+                          nullable: true
+                          description: >-
+                              Display technology of the panel (e.g. LCD, e-paper). May be null.
+                      panel_model:
+                          type: string
+                          nullable: true
+                          description: >-
+                              Model designation of the panel unit. May be null.
+                      owner_contact:
+                          type: string
+                          nullable: true
+                          description: >-
+                              Contact information for the element owner. May be null.
+                      connectivity_internet:
+                          type: string
+                          nullable: true
+                          description: >-
+                              Internet connectivity type or provider for the panel. May be null.
+                      phone_number:
+                          type: string
+                          nullable: true
+                          description: >-
+                              Phone number associated with the panel's SIM or connectivity. May be null.
 
         Obelisk:
             description: >-
@@ -1696,13 +1931,13 @@ components:
                           description: >-
                               Construction or mounting type of the totem
                               (e.g. STANDALONE, POLE_MOUNTED, WALL_MOUNTED). May be null.
-                      price_without_vat:
+                      production_price_without_vat:
                           type: number
                           format: double
                           nullable: true
                           example: 320000.00
                           description: >-
-                              Total purchase price of this totem unit, excluding VAT
+                              Total production price of this totem unit, excluding VAT
                               (Czech crowns). May be null.
                       serial_number:
                           type: string
@@ -1711,50 +1946,3 @@ components:
                           description: >-
                               Manufacturer's serial number of this totem unit.
                               May be null.
-
-    responses:
-        BadRequestError:
-            description: Bad request - invalid query parameters
-            content:
-                application/json:
-                    schema:
-                        type: object
-                        properties:
-                            error_message:
-                                type: string
-                                example: "Bad request"
-                                nullable: false
-                            error_status:
-                                type: integer
-                                example: 400
-                                nullable: false
-                            error_info:
-                                type: string
-                                example: "{...}"
-                                nullable: true
-                        required:
-                            - error_message
-                            - error_status
-
-        UnauthorizedError:
-            description: API key is missing or invalid
-            headers:
-                WWW_Authenticate:
-                    schema:
-                        type: string
-            content:
-                application/json:
-                    schema:
-                        type: object
-                        properties:
-                            error_message:
-                                type: string
-                                example: "Unauthorized. Failed to authenticate user."
-                                nullable: false
-                            error_status:
-                                type: integer
-                                example: 401
-                                nullable: false
-                        required:
-                            - error_message
-                            - error_status