@golemio/energetics 1.12.1 → 1.12.2-dev.2727447026

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,55 @@ paths:
                             schema:
                                 $ref: "#/components/schemas/EnergeticsBuildingFull"
 
+    /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 +505,205 @@ components:
                                 type: string
 
     schemas:
+        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
+                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 devices and prices
+                            properties:
+                                invoice:
+                                    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.1",
+    "version": "1.12.2-dev.2727447026",
     "description": "Golemio Energetics Module",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",