Documentation Index
Fetch the complete documentation index at: https://mintlify.com/soker90/finper/llms.txt
Use this file to discover all available pages before exploring further.
The Supplies module lets you model the utility contracts attached to one or more properties. You can record periodic meter readings or invoices, track consumption costs over time, and — for electricity contracts — project your historical readings against alternative tariff structures to estimate potential savings.
Data model hierarchy
Property
└── Supply (1 : N)
└── SupplyReading (1 : N)
| Entity | Purpose |
|---|
| Property | A home or premises. Parent container for all supplies. |
| Supply | A single utility contract (electricity, water, gas, other) attached to a property. Holds tariff and contracted-power settings for electricity. |
| SupplyReading | A meter reading or invoice for a supply, covering a period between startDate and endDate. Stores total cost and consumption figures. |
Supply types
| Value | Description |
|---|
electricity | Electricity contract. Supports full tariff and power configuration. |
water | Water supply. |
gas | Gas supply. |
other | Any other utility (requires a name field). |
Properties
Properties have no dedicated GET endpoint. They are returned as part of the GET /api/supplies response, which groups supplies by their parent property.
| Method | Route | Description |
|---|
POST | /api/supplies/properties | Create a new property |
PUT | /api/supplies/properties/:id | Update a property |
DELETE | /api/supplies/properties/:id | Delete a property |
| Field | Type | Required | Description |
|---|
name | string | ✅ | Name or address label for the property |
Supplies
| Method | Route | Description |
|---|
GET | /api/supplies | List all supplies, grouped by property |
POST | /api/supplies | Create a new supply contract |
PUT | /api/supplies/:id | Update a supply contract |
DELETE | /api/supplies/:id | Delete a supply contract |
GET | /api/supplies/:id/tariffs-comparison | Compare current tariff against alternatives (electricity only) |
| Field | Type | Required | Description |
|---|
propertyId | string | ✅ | ID of the parent property |
type | electricity | water | gas | other | ✅ | Utility type |
name | string | When type is other | Display name — required when type is other, optional for all other types |
contractedPowerPeak | number | ❌ | Contracted peak power (kW) — electricity only |
contractedPowerOffPeak | number | ❌ | Contracted off-peak power (kW) — electricity only |
currentPricePowerPeak | number | ❌ | Power term price, peak period — electricity only |
currentPricePowerOffPeak | number | ❌ | Power term price, off-peak period — electricity only |
currentPriceEnergyPeak | number | ❌ | Energy price, peak period (€/kWh) — electricity only |
currentPriceEnergyFlat | number | ❌ | Energy price, flat period (€/kWh) — electricity only |
currentPriceEnergyOffPeak | number | ❌ | Energy price, off-peak period (€/kWh) — electricity only |
Supply Readings
| Method | Route | Description |
|---|
GET | /api/supplies/readings/supply/:supplyId | List all readings for a supply |
POST | /api/supplies/readings | Create a new reading |
PUT | /api/supplies/readings/:id | Update a reading |
DELETE | /api/supplies/readings/:id | Delete a reading |
| Field | Type | Required | Description |
|---|
supplyId | string | ✅ | ID of the parent supply |
startDate | number | ✅ | Unix timestamp (ms) — beginning of the billing period |
endDate | number | ✅ | Unix timestamp (ms) — end of the billing period (must be after startDate) |
amount | number | ✅ | Total cost for the period |
consumption | number | ❌ | Total consumption for the period (kWh, m³, etc.) |
consumptionPeak | number | ❌ | Peak-period consumption — electricity only |
consumptionFlat | number | ❌ | Flat-period consumption — electricity only |
consumptionOffPeak | number | ❌ | Off-peak-period consumption — electricity only |
consumption, consumptionPeak, consumptionFlat, and consumptionOffPeak are all optional. For electricity readings you can supply the three time-of-use breakdown fields instead of (or in addition to) the aggregate consumption field.
Tariff comparison
GET /api/supplies/:id/tariffs-comparison is available for electricity supplies only. Before calling this endpoint, ensure the supply has all of the following configured:
contractedPowerPeak and contractedPowerOffPeak — the contracted power settings.- All five
currentPrice* fields — currentPricePowerPeak, currentPricePowerOffPeak, currentPriceEnergyPeak, currentPriceEnergyFlat, and currentPriceEnergyOffPeak.
The endpoint returns a 400 error if the supply is not of type electricity, or if any of the required power or price configuration fields are missing.
The endpoint fetches a list of alternative market tariffs and projects each one against the supply’s existing readings to calculate what you would have paid. The result lets you compare your actual spend against competing offers without manually recalculating.
Tariff definitions are fetched from an external cache (https://soker90.github.io/tarifas-luz/tarifas.json) and cached for 12 hours.
Route ordering
In server.ts, the /api/supplies/properties and /api/supplies/readings routers are mounted before /api/supplies. This ensures that paths like /api/supplies/properties and /api/supplies/readings/supply/:supplyId are matched by their dedicated routers and do not fall through to the generic /:id handler.
Example: Create a property, supply, and reading in sequence
Step 1 — Create the property:
curl -X POST http://localhost:3008/api/supplies/properties \
-H 'token: <your-jwt>' \
-H 'Content-Type: application/json' \
-d '{ "name": "Main Apartment" }'
id returned (e.g. "prop_abc").
Step 2 — Create an electricity supply for that property:
curl -X POST http://localhost:3008/api/supplies \
-H 'token: <your-jwt>' \
-H 'Content-Type: application/json' \
-d '{
"propertyId": "prop_abc",
"type": "electricity",
"contractedPowerPeak": 5.75,
"contractedPowerOffPeak": 5.75,
"currentPricePowerPeak": 0.104,
"currentPricePowerOffPeak": 0.057,
"currentPriceEnergyPeak": 0.18,
"currentPriceEnergyFlat": 0.14,
"currentPriceEnergyOffPeak": 0.09
}'
id returned (e.g. "sup_xyz").
Step 3 — Record a meter reading / invoice:
curl -X POST http://localhost:3008/api/supplies/readings \
-H 'token: <your-jwt>' \
-H 'Content-Type: application/json' \
-d '{
"supplyId": "sup_xyz",
"startDate": 1714521600000,
"endDate": 1717200000000,
"amount": 87.45,
"consumption": 415,
"consumptionPeak": 120,
"consumptionFlat": 85,
"consumptionOffPeak": 210
}'
