@balmli/homey-utility-prices

Utility helpers for Homey apps that need Nordic electricity spot prices and related analytics. It wraps Nord Pool's Data Portal API, handles caching on Homey devices, and exposes tooling for comparing prices, heating schedules, and aggregations.

• Fetch day-ahead spot prices (yesterday/today/tomorrow) and daily averages from Nord Pool.
• Normalise data into NordpoolPrice records with timestamps, slot duration metadata, price levels, and optional financial support adjustments.
• Cache prices in Homey device store via PricesFetchClient and orchestrate fetch/update intervals with PriceFetcher.
• Analyse prices with PriceApi / PriceComparer helpers (e.g., find lowest hours, compute averages, decide heating strategy).
• Provide heating schedule calculations with public-holiday awareness.

Installation

npm install @balmli/homey-utility-prices

The package is published as CommonJS with bundled type declarations in dist/.

Usage

Fetch day-ahead spot prices

import moment from 'moment-timezone';
import {NordpoolApi, Currency} from '@balmli/homey-utility-prices';

const api = new NordpoolApi({logger: console});
const today = moment().tz('Europe/Oslo').startOf('day');

const prices = await api.fetchPrices(today, {
  priceArea: 'Bergen',
  currency: Currency.NOK,
});

console.log(prices[0].startsAt.format(), prices[0].price);

Cache prices on a Homey device

import moment from 'moment-timezone';
import {PriceFetcher, PricesFetchClient, PriceFetcherMethod} from '@balmli/homey-utility-prices';

const priceFetcher = new PriceFetcher({
  logger: console,
  pricesFetchClient: new PricesFetchClient({logger: console}),
  device: homeyDevice,
});

priceFetcher.setNordpoolOptions({priceArea: 'Oslo', currency: 'NOK'});
priceFetcher.setFetchMethod(PriceFetcherMethod.nordpool);
priceFetcher.setFetchTime(30); // optional: seconds past the hour to fetch (default: 3)
priceFetcher.start();

// Fetches prices hourly (e.g., at 10:00:30, 11:00:30, etc.)
priceFetcher.on('prices', prices => {
  console.log(`Received ${prices.length} price periods`);
});

// Emits current price every 15 minutes (00:03, 15:03, 30:03, 45:03)
priceFetcher.on('priceChanged', currentPrice => {
  console.log(`Current price: ${currentPrice.price}`);
});

Price comparisons

PriceApi and PriceComparer expose helpers to identify lowest/highest periods, compare against averages, and feed Homey automation flows. See the tests in tests/ for worked examples.

Development

• Build: npm run build
• Test: npm test
• TypeScript sources live in lib/; compiled artifacts are written to dist/.

Slot duration handling

As of the Nord Pool policy change on 1 October 2025, the Day Ahead API switches to 15-minute intervals. The library now stores slot metadata (durationMinutes, endsAt) across fetch, cache, and comparer helpers so Homey apps continue to work seamlessly with both hourly archives and quarter-hour futures.

Fetch and Update Schedule

• Price fetching: Runs once per hour at the configured offset (default: 3 seconds past the hour). Example: 10:00:03, 11:00:03, 12:00:03.
• Price updates: The priceChanged event fires every 15 minutes at 00:03, 15:03, 30:03, 45:03 to support quarter-hour slots.
• No configuration needed - the library automatically handles the appropriate intervals.

Review specs/ and QUARTER_HOUR_USAGE.md for detailed design notes and migration guidance.