@golemio/energetics 1.12.2-dev.2740928370 → 1.12.2-dev.2741327856

package/docs/openapi-output.yaml

@@ -15,7 +15,18 @@ servers:
       description: Main (production) server
 tags:
     - name: ⚡ Energetics (v2)
-      description: 💡 Organizations & measurement devices
+      description: >-
+          💡 Organizations & measurement devices — the original OICT Energetika data domain
+          (`organizations*` and `consumption_energy_*` tables). All endpoints in this group are
+          organization-scoped and require the internal `accessLimit` query parameter, which is set
+          by the permission proxy (never by the client).
+    - name: 🗺️ Energetics DeD (v2)
+      description: >-
+          🏢 DeD — city-wide energy management overview for Prague buildings. A separate data
+          domain from ⚡ Energetics: ENO buildings, consumption points (OM), PRE/PPAS enrichment
+          and Porsenna e-manazer devices. Data is not organization-scoped, so these endpoints do
+          not use the `accessLimit` parameter at all — sending it (or any other unknown query
+          parameter) is rejected with HTTP 400.
 paths:
     /v2/energetics/buildings:
         get:
@@ -73,6 +84,115 @@ paths:
                             schema:
                                 $ref: "#/components/schemas/EnergeticsBuildingFull"
 
+    /v2/energetics/ded/buildings:
+        get:
+            tags:
+                - 🗺️ Energetics DeD (v2)
+            summary: Search buildings by name, address, GID, EAN, EIC or OM identifier
+            description: >-
+                Suggestion endpoint for the DeD map. A single free-text query `q` is matched against the
+                building name, its addresses, the GID and the identifiers of every consumption point mapped
+                to the building.
+
+                Matching runs in two tiers. An exact match on an EAN, EIC, OM identifier or GID is returned
+                on its own — fuzzy candidates are dropped entirely and `matched_exactly` is `true`. Note that
+                one identifier can be mapped to several buildings, so an exact match may still return more
+                than one result; the map should zoom automatically only when exactly one result is returned.
+                Otherwise results are ranked by a weighted full-text and trigram score over the name
+                (highest weight), the main address, the secondary addresses and the identifiers. Queries
+                typed without Czech diacritics match normally.
+
+                Every result carries the building outline as GeoJSON together with its bounding box and
+                centroid, all in WGS84 (EPSG:4326), so the map can zoom to a hit. They are `null` when the
+                building has no usable geometry, signalled by `geometry_source: null`.
+            parameters:
+                - in: query
+                  name: q
+                  required: true
+                  description: Search text — name, address, GID, EAN, EIC or OM identifier.
+                  schema:
+                      type: string
+                      minLength: 1
+                      maxLength: 100
+                      example: "859182400000000001"
+                - in: query
+                  name: limit
+                  required: false
+                  description: Maximum number of suggestions returned.
+                  schema:
+                      type: integer
+                      minimum: 1
+                      maximum: 50
+                      default: 10
+            responses:
+                "200":
+                    description: OK
+                    headers:
+                        Cache-Control:
+                            description: Cache control directive for caching proxies
+                            schema:
+                                type: string
+                                example: public, s-maxage=60, stale-while-revalidate=30
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/EnergeticsDedBuildingSearch"
+                "400":
+                    $ref: "#/components/responses/BadRequestError"
+                "401":
+                    $ref: "#/components/responses/UnauthorizedError"
+                "500":
+                    $ref: "#/components/responses/ServerError"
+
+    /v2/energetics/ded/buildings/{gid}:
+        get:
+            tags:
+                - 🗺️ Energetics DeD (v2)
+            summary: ENO building detail with consumption points (OM) and technical parameters
+            description: >-
+                Returns the ENO building (eno_budova) identified by GID together with its addresses and all
+                consumption points mapped to it. Commodity-specific data is nested under the
+                `electricity`/`gas`/`heat`/`water` keys of each consumption point; only the key matching the
+                `commodity` field is present, the others are omitted entirely.
+
+                Consumption points come from two independent sources: the energobroker mapping (EAN/EIC,
+                enriched with PRE metadata and PPAS invoices) and Porsenna e-manazer devices
+                (`link_source: porsenna`) — heat and water meters, plus any EAN/EIC the mapping lacks.
+                An OM known to both sources is returned once, with the Porsenna data nested as a `porsenna`
+                sub-block (device, sub-meters, yearly consumption) inside its commodity block. Buildings
+                tracked in Porsenna also carry an `energy_management` summary.
+
+                The endpoint returns whatever data exists for the GID: if there is any building record,
+                address, or consumption point, the response is 200 with the missing parts as `null` or
+                empty arrays (e.g. `building: null` when only consumption points or addresses are known).
+                404 is returned only when no source holds any data for the GID.
+            parameters:
+                - in: path
+                  name: gid
+                  required: true
+                  schema:
+                      type: string
+                      example: GID100
+            responses:
+                "200":
+                    description: OK
+                    headers:
+                        Cache-Control:
+                            description: Cache control directive for caching proxies
+                            schema:
+                                type: string
+                                example: public, s-maxage=21600, stale-while-revalidate=60
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/EnergeticsEnoBuildingDetail"
+                "401":
+                    $ref: "#/components/responses/UnauthorizedError"
+                "404":
+                    $ref: "#/components/responses/NotFoundError"
+                "500":
+                    $ref: "#/components/responses/ServerError"
+
     /v2/energetics/devices:
         get:
             tags:
@@ -445,6 +565,439 @@ components:
                                 type: string
 
     schemas:
+        EnergeticsDedBuildingSearch:
+            type: object
+            properties:
+                query:
+                    type: string
+                    example: "859182400000000001"
+                matched_exactly:
+                    type: boolean
+                    description: >-
+                        True when the query resolved to an exact EAN, EIC, OM identifier or GID. In that case
+                        the results contain only exact matches.
+                    example: true
+                results:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/EnergeticsDedBuildingSearchResult"
+            required:
+                - query
+                - matched_exactly
+                - results
+
+        EnergeticsDedBuildingSearchResult:
+            type: object
+            properties:
+                gid:
+                    type: string
+                    example: GID100
+                name:
+                    type: string
+                    nullable: true
+                    example: ZŠ Testovací
+                designation:
+                    type: string
+                    nullable: true
+                    example: ZŠT
+                registration_unit:
+                    allOf:
+                        - $ref: "#/components/schemas/EnergeticsEnoRegistrationUnit"
+                    nullable: true
+                    description: >-
+                        Evidenční jednotka (eno_ciselnik_evidencni_jednotka) resolved through eno_majetek;
+                        null when the building has no majetek record. Its name is part of the search vector.
+                address:
+                    type: string
+                    nullable: true
+                    description: Main address of the building.
+                    example: Testovací 123/4, 100 00 Praha 10
+                addresses:
+                    type: array
+                    description: Every distinct address of the building, the main one first.
+                    items:
+                        type: string
+                    example:
+                        - Testovací 123/4, 100 00 Praha 10
+                        - Testovací 125/6, 100 00 Praha 10
+                matched_by:
+                    type: string
+                    enum: [ean, eic, om, gid, name, address]
+                    example: ean
+                matched_value:
+                    type: string
+                    nullable: true
+                    description: The identifier that matched. Null for non-exact matches.
+                    example: "859182400000000001"
+                score:
+                    type: number
+                    description: Relevance score. Exact matches always score 1000.
+                    example: 1000
+                identifiers:
+                    type: object
+                    properties:
+                        ean:
+                            type: array
+                            items:
+                                type: string
+                        eic:
+                            type: array
+                            items:
+                                type: string
+                        om:
+                            type: array
+                            items:
+                                type: string
+                geometry:
+                    type: object
+                    nullable: true
+                    description: Building outline as GeoJSON geometry in WGS84 (EPSG:4326).
+                    properties:
+                        type:
+                            type: string
+                            example: MultiPolygon
+                        coordinates:
+                            type: array
+                            items: {}
+                bbox:
+                    type: array
+                    nullable: true
+                    description: "[minLon, minLat, maxLon, maxLat] in WGS84, for zooming the map."
+                    items:
+                        type: number
+                    minItems: 4
+                    maxItems: 4
+                    example: [14.4174, 50.0863, 14.4188, 50.0873]
+                centroid:
+                    type: object
+                    nullable: true
+                    properties:
+                        lat:
+                            type: number
+                            example: 50.0868
+                        lon:
+                            type: number
+                            example: 14.4181
+                geometry_source:
+                    type: string
+                    nullable: true
+                    description: Source of the geometry, null when the building has none.
+                    example: eno_geometrie
+                has_building_record:
+                    type: boolean
+                    description: >-
+                        False when the GID is known only through the consumption-point mapping or Porsenna
+                        and has no eno_budova record. Such results are ranked below described buildings.
+                    example: true
+                active_points_count:
+                    type: integer
+                    example: 3
+            # Every property is emitted unconditionally by DedBuildingSearchTransformation - the
+            # nullable ones are present with a null value, never absent.
+            required:
+                - gid
+                - name
+                - designation
+                - registration_unit
+                - address
+                - addresses
+                - matched_by
+                - matched_value
+                - score
+                - identifiers
+                - geometry
+                - bbox
+                - centroid
+                - geometry_source
+                - has_building_record
+                - active_points_count
+
+        EnergeticsEnoRegistrationUnit:
+            type: object
+            description: >-
+                Evidenční jednotka (eno_ciselnik_evidencni_jednotka) resolved through the building's
+                eno_majetek record. The same shape is returned by the search and the detail endpoint.
+            properties:
+                id:
+                    type: number
+                    nullable: true
+                    example: 7001
+                kod:
+                    type: string
+                    nullable: true
+                    example: EJ-7001
+                nazev:
+                    type: string
+                    nullable: true
+                    example: Evidenční jednotka Praha 10
+                typ:
+                    type: string
+                    nullable: true
+                    example: škola
+            required:
+                - id
+                - kod
+                - nazev
+                - typ
+
+        EnergeticsEnoBuildingDetail:
+            type: object
+            properties:
+                gid:
+                    type: string
+                    example: GID100
+                building:
+                    type: object
+                    nullable: true
+                    description: >-
+                        All available eno_budova attributes (Czech identifiers mirror the upstream ENO source).
+                        Null when the GID has no ENO building record and is known only through the
+                        consumption-point mapping.
+                    properties:
+                        zdroj:
+                            type: string
+                            nullable: true
+                        nazev:
+                            type: string
+                            nullable: true
+                        oznaceni:
+                            type: string
+                            nullable: true
+                        druh_vytapeni:
+                            type: string
+                            nullable: true
+                        pripojka_elektro:
+                            type: string
+                            nullable: true
+                        pripojka_voda:
+                            type: string
+                            nullable: true
+                        pripojka_kanalizace:
+                            type: string
+                            nullable: true
+                    additionalProperties: true
+                property:
+                    type: object
+                    nullable: true
+                    description: >-
+                        ENO lookup data (eno_ciselnik_*) resolved through the building's eno_majetek record.
+                        Null when the building has no majetek record.
+                    properties:
+                        registration_unit:
+                            allOf:
+                                - $ref: "#/components/schemas/EnergeticsEnoRegistrationUnit"
+                            nullable: true
+                            description: Evidenční jednotka (eno_ciselnik_evidencni_jednotka).
+                        managers:
+                            type: object
+                            description: Správci (eno_ciselnik_spravce) from the mandate and accounting-unit references.
+                            properties:
+                                mandate:
+                                    type: object
+                                    nullable: true
+                                    description: Správce referenced by eno_majetek.id_maj_spravce_mandatni.
+                                    properties:
+                                        id:
+                                            type: number
+                                            nullable: true
+                                        kod:
+                                            type: string
+                                            nullable: true
+                                        nazev:
+                                            type: string
+                                            nullable: true
+                                        ic:
+                                            type: string
+                                            nullable: true
+                                        dic:
+                                            type: string
+                                            nullable: true
+                                accounting_unit:
+                                    type: object
+                                    nullable: true
+                                    description: Správce referenced by eno_majetek.id_maj_spravce_ucet_jednotka.
+                                    properties:
+                                        id:
+                                            type: number
+                                            nullable: true
+                                        kod:
+                                            type: string
+                                            nullable: true
+                                        nazev:
+                                            type: string
+                                            nullable: true
+                                        ic:
+                                            type: string
+                                            nullable: true
+                                        dic:
+                                            type: string
+                                            nullable: true
+                addresses:
+                    type: array
+                    items:
+                        type: object
+                        properties:
+                            popis:
+                                type: string
+                                nullable: true
+                            hlavni:
+                                type: boolean
+                                nullable: true
+                            poradi:
+                                type: number
+                energy_management:
+                    type: object
+                    nullable: true
+                    description: Porsenna (e-manazer) tracking summary; null when the building is not tracked there
+                    properties:
+                        source:
+                            type: string
+                            example: porsenna_p7
+                        building_name:
+                            type: string
+                            nullable: true
+                        address:
+                            type: string
+                            nullable: true
+                        devices_total:
+                            type: number
+                        devices_active:
+                            type: number
+                consumption_points:
+                    type: array
+                    items:
+                        $ref: "#/components/schemas/EnergeticsEnoConsumptionPoint"
+        EnergeticsEnoPorsennaBlock:
+            type: object
+            description: Porsenna (e-manazer) device detail with sub-meters and yearly consumption aggregates
+            properties:
+                device:
+                    type: object
+                    additionalProperties: true
+                sub_devices:
+                    type: array
+                    items:
+                        type: object
+                        additionalProperties: true
+                yearly_consumption:
+                    type: array
+                    items:
+                        type: object
+                        properties:
+                            period:
+                                type: string
+                                example: "2024"
+                            value:
+                                type: number
+                            unit:
+                                type: string
+                                example: GJ
+                            days_covered:
+                                type: number
+                                nullable: true
+        EnergeticsEnoConsumptionPoint:
+            type: object
+            properties:
+                place_id:
+                    type: string
+                    example: 27ZG100Z0000192O
+                id_type:
+                    type: string
+                    enum: [ean, eic, om]
+                commodity:
+                    type: string
+                    enum: [electricity, gas, heat, water]
+                is_first_gid:
+                    type: boolean
+                is_active:
+                    type: boolean
+                    description: Derived from valid_to (null or in the future means the mapping is active)
+                link_source:
+                    type: string
+                    example: mock
+                valid_from:
+                    type: string
+                    format: date
+                    nullable: true
+                valid_to:
+                    type: string
+                    format: date
+                    nullable: true
+                address:
+                    type: string
+                    nullable: true
+                    description: Consumption point address from the best available source
+                electricity:
+                    type: object
+                    description: Electricity-specific data (present only for commodity = electricity, omitted otherwise)
+                    properties:
+                        metadata:
+                            type: object
+                            nullable: true
+                            description: Latest available month of PRE metadata for the EAN
+                            additionalProperties: true
+                        porsenna:
+                            $ref: "#/components/schemas/EnergeticsEnoPorsennaBlock"
+                gas:
+                    type: object
+                    description: Gas-specific data (present only for commodity = gas, omitted otherwise)
+                    properties:
+                        porsenna:
+                            $ref: "#/components/schemas/EnergeticsEnoPorsennaBlock"
+                        distribution:
+                            type: object
+                            nullable: true
+                            description: Latest non-canceled PPAS distribution invoice with its installation, devices and prices
+                            properties:
+                                invoice:
+                                    type: object
+                                    additionalProperties: true
+                                installation:
+                                    type: object
+                                    additionalProperties: true
+                                devices:
+                                    type: array
+                                    items:
+                                        type: object
+                                        additionalProperties: true
+                                prices:
+                                    type: array
+                                    items:
+                                        type: object
+                                        additionalProperties: true
+                        commercial:
+                            type: object
+                            nullable: true
+                            description: Latest non-canceled PPAS commercial invoice with its installation, devices and prices
+                            properties:
+                                invoice:
+                                    type: object
+                                    additionalProperties: true
+                                installation:
+                                    type: object
+                                    additionalProperties: true
+                                devices:
+                                    type: array
+                                    items:
+                                        type: object
+                                        additionalProperties: true
+                                prices:
+                                    type: array
+                                    items:
+                                        type: object
+                                        additionalProperties: true
+                heat:
+                    type: object
+                    description: Heat-specific data (present only for commodity = heat, omitted otherwise; Porsenna-sourced)
+                    properties:
+                        porsenna:
+                            $ref: "#/components/schemas/EnergeticsEnoPorsennaBlock"
+                water:
+                    type: object
+                    description: Water-specific data (present only for commodity = water, omitted otherwise; Porsenna-sourced)
+                    properties:
+                        porsenna:
+                            $ref: "#/components/schemas/EnergeticsEnoPorsennaBlock"
         EnergeticsBuildingShort:
             type: object
             properties:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@golemio/energetics",
-    "version": "1.12.2-dev.2740928370",
+    "version": "1.12.2-dev.2741327856",
     "description": "Golemio Energetics Module",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",