node-red-contrib-eskomsepush 0.0.18 → 0.1.1

package/src/lib/types.ts

@@ -0,0 +1,109 @@
+export interface AllowanceInfo {
+  allowance: {
+    count: number
+    limit: number
+    type: string
+  }
+}
+
+export interface StatusEntry {
+  name: string
+  next_stages: Array<{ stage: string; stage_start_timestamp: string }>
+  stage: string
+  stage_updated: string
+}
+
+export interface StatusInfo {
+  status: Record<string, StatusEntry>
+}
+
+export interface AreaEvent {
+  end: string
+  note: string
+  start: string
+}
+
+export interface ScheduleDay {
+  date: string
+  name: string
+  stages: string[][]
+}
+
+export interface AreaInfo {
+  events: AreaEvent[]
+  info: {
+    name: string
+    region: string
+  }
+  schedule: {
+    days: ScheduleDay[]
+    source: string
+  }
+}
+
+export interface AreasSearchResult {
+  areas: Array<{
+    id: string
+    name: string
+    region: string
+  }>
+}
+
+export interface NextPeriod {
+  type: 'schedule' | 'event'
+  start: number
+  end: number
+  duration: number
+  islong: boolean
+  stage: string | number
+  isHigherStage?: boolean
+}
+
+export interface CalcResult {
+  sleeptime: number
+  stage: string | number
+  active: boolean
+  type?: 'schedule' | 'event'
+  start?: number
+  end?: number
+  duration?: number
+  islong?: boolean
+  secondstostatechange?: number
+  next?: NextPeriod
+}
+
+export interface NodeConfig {
+  name?: string
+  licensekey: string
+  area: string
+  statusselect: string
+  test?: boolean
+  verbose?: boolean
+  api_allowance_buffer: number
+}
+
+export interface NodeRedNode {
+  config: NodeConfig
+  status(opts: { fill?: string; shape?: string; text?: string }): void
+  warn(msg: unknown): void
+  send(msgs: (object | null)[]): void
+  on(event: 'close' | 'input', listener: (...args: unknown[]) => void): void
+}
+
+export interface NodeRed {
+  nodes: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    createNode(node: any, config: NodeConfig): void
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    registerType(type: string, constructor: any): void
+  }
+  httpNode: {
+    get(
+      path: string,
+      handler: (
+        req: { query: Record<string, string> },
+        res: { setHeader(name: string, value: string): void; send(data: unknown): unknown }
+      ) => void
+    ): void
+  }
+}

package/src/nodes/eskomsepush.html

@@ -144,7 +144,7 @@
 </script>
 
 <script type="text/html" data-help-name="eskomsepush">
-    <h3 id=""eskomsepushapi>EskomSePush API</h3>
+    <h3 id="eskomsepushapi">EskomSePush API</h3>
 
     <p>A node for retrieving info from the EskomSePush API.</p>
 
@@ -152,23 +152,24 @@
 in South Africa as easy as possible.</p>
 <p>First you need to configure the node by entering the license key and entering
 the correct area.</p>
-<p>Once deployed, the node will fetch the data from EskomSePush every hour. As
-every fetch from the API takes 2 calls, the 50 free queries per day on a
-free account should suffice. Every ten minutes the API status is checked to
-see how many queries you have left.</p>
+<p>Once deployed, the node fetches data from EskomSePush at a dynamic interval
+calculated from your remaining daily API allowance — never more often than needed.
+Every fetch of status and schedule takes 2 API calls. Every ten minutes the
+allowance is checked to see how many queries you have left.</p>
 <p>Internally the node checks every minute if a schedule is currently active or not. It
     will also output a message on the first deployment.</p>
 
 <h3 id="configuration">Configuration</h3>
 
 <p>First you will need a <em>licence key</em>. You can get one from <a href="https://eskomsepush.gumroad.com/l/api">here</a>, by subsribing to the Free model. Note that this is for personal use only.</p>
-<p>Next you need to insert the correct area. Once a valid license is filled out, the API can be used for searching the correct area id. Do note that this will cost some of the daily queries. If you don&#39;t want that and you already know the id of the area, fill out the area id manually.</p>
+<p>Next you need to insert the correct area id. Once a valid license is filled out, the search form below can help find it — note that each search costs API quota. If you already know the id, fill it out manually.</p>
+<p>Use the short form of the area id: <code>eskmo-15</code>, not <code>eskmo-15-ballitokwadukuzakwazulunatal</code>. If you have an old-style id with a location suffix, the node will still work but will log a warning asking you to update it.</p>
 <p>Then you need to fill out which status to follow. This can be either <em>National</em> (eskom) or <em>Capetown</em>.</p>
 <p>The <i>API allowance buffer</i> allows you to reserve some daily unused API calls (so you can use your API key for other integrations too). If you don't use that, set this to _0_ (zero).</p>
 <p>If the <em>test</em> checkbox has been selected, test data for the area will be fetched instead of the actual schedule. This is useful when debugging.</p>
 <p>The <em>verbose</em> checkbox will give some additional <tt>node.warn()</tt> messages, appearing in the debug tab. This is also useful when debugging.</p>
 
-<h3 id=""inputs">Inputs</h3>
+<h3 id="inputs">Inputs</h3>
 
 <p>
     The input side is not needed in most cases. The node will output its status every ten minutes and won't update the information it gets from the API more 
@@ -253,7 +254,7 @@ a matching <em>schedule</em>.
 
 <h1 id="documentation">Documentation</h1>
 
-<p>The GitHub site for the node can be found <a href="https://github.com/dirkjanfaber/node-red-contrib-eskomsepush">here</a>, while the documentation for the API can be found <a href="https://documenter.getpostman.com/view/1296288/UzQuNk3E">here</a>.
+<p>The GitHub site for the node can be found <a href="https://github.com/dirkjanfaber/node-red-contrib-eskomsepush">here</a>, while the documentation for the API can be found <a href="https://developer.sepush.co.za/business/3.0/">here</a>.
 For issues and/or suggestions for improving the node, please use the <a href="https://github.com/dirkjanfaber/node-red-contrib-eskomsepush/issues">issue tracker</a>.</p>
 </script>
 

package/src/nodes/eskomsepush.ts

@@ -0,0 +1,203 @@
+import { fetchAllowance, fetchArea, fetchStatus, migrateAreaId, searchAreas } from '../lib/api'
+import { calculateCalc, calculateSleepTime, getMinutesToAPIReset } from '../lib/loadshedding'
+import type {
+  AllowanceInfo,
+  AreaInfo,
+  CalcResult,
+  NodeConfig,
+  NodeRed,
+  NodeRedNode,
+  StatusInfo
+} from '../lib/types'
+
+module.exports = function (RED: NodeRed) {
+  'use strict'
+
+  function EskomSePush(this: NodeRedNode, config: NodeConfig) {
+    RED.nodes.createNode(this, config)
+    this.config = config
+
+    const node = this
+
+    // Per-instance state — avoids shared-state bugs when multiple nodes exist in the same flow
+    const info = {
+      api:    { lastUpdate: null as Date | null, info: {} as Partial<AllowanceInfo> },
+      status: { lastUpdate: null as Date | null, info: {} as Partial<StatusInfo>    },
+      area:   { lastUpdate: null as Date | null, info: {} as Partial<AreaInfo>      },
+      calc:   {} as Partial<CalcResult>
+    }
+
+    async function updateSheddingStatus(msg?: { payload?: unknown }) {
+      const now = new Date()
+
+      // Refresh allowance every 10 minutes or on demand
+      if (msg?.payload === 'allowance' ||
+          info.api.lastUpdate === null ||
+          (now.getTime() - info.api.lastUpdate.getTime()) > 600_000) {
+        try {
+          if (node.config.verbose) node.warn('Running fetchAllowance')
+          info.api.info = await fetchAllowance(node.config.licensekey)
+          info.api.lastUpdate = now
+        } catch (err) {
+          node.warn({ error: (err as Error).message })
+        }
+      }
+
+      if (Object.keys(info.api.info).length === 0) {
+        node.warn('No API info (yet), refusing to continue')
+        return
+      }
+
+      const allowance = (info.api.info as AllowanceInfo).allowance
+      if (allowance.count >= allowance.limit) {
+        node.warn('No API calls left, not checking status/schedule')
+        node.status({ fill: 'red', shape: 'ring', text: 'API quota reached' })
+        return
+      }
+
+      const minutesToReset = getMinutesToAPIReset(now)
+      info.calc.sleeptime = calculateSleepTime(
+        allowance.limit,
+        allowance.count,
+        node.config.api_allowance_buffer,
+        minutesToReset
+      )
+      if (node.config.verbose) node.warn('Calculated sleeptime: ' + info.calc.sleeptime)
+
+      const sleepMs = info.calc.sleeptime * 60_000
+
+      const { id: resolvedAreaId, migrated } = migrateAreaId(node.config.area)
+      if (migrated) {
+        node.warn(
+          `Area ID "${node.config.area}" is a v2-style ID. ` +
+          `Using "${resolvedAreaId}" for the v3 API. ` +
+          `Please update the area ID in the node configuration.`
+        )
+      }
+
+      // Refresh stage on demand or when sleeptime has elapsed
+      if (msg?.payload === 'stage' ||
+          info.status.lastUpdate === null ||
+          (now.getTime() - info.status.lastUpdate.getTime()) > sleepMs) {
+        try {
+          if (node.config.verbose) {
+            node.warn(
+              info.status.lastUpdate === null
+                ? 'Running fetchStatus - initial run'
+                : `Running fetchStatus after ${((now.getTime() - info.status.lastUpdate.getTime()) / 60_000).toFixed(0)} minutes`
+            )
+          }
+          node.status({ fill: 'yellow', shape: 'ring', text: 'Fetching status' })
+          info.status.info = await fetchStatus(node.config.licensekey)
+          info.status.lastUpdate = now
+        } catch (err) {
+          node.warn({ error: (err as Error).message })
+        }
+      }
+
+      // Refresh area schedule on demand or when sleeptime has elapsed
+      if (msg?.payload === 'area' ||
+          info.area.lastUpdate === null ||
+          (now.getTime() - info.area.lastUpdate.getTime()) > sleepMs) {
+        try {
+          if (node.config.verbose) {
+            node.warn(
+              info.area.lastUpdate === null
+                ? 'Running fetchArea - initial run'
+                : `Running fetchArea after ${((now.getTime() - info.area.lastUpdate.getTime()) / 60_000).toFixed(0)} minutes`
+            )
+          }
+          node.status({ fill: 'yellow', shape: 'ring', text: 'Fetching schedule' })
+          info.area.info = await fetchArea(node.config.licensekey, resolvedAreaId, node.config.test)
+          info.area.lastUpdate = now
+        } catch (err) {
+          node.warn({ error: (err as Error).message })
+        }
+      }
+
+      if (!info.api.lastUpdate || !info.status.lastUpdate || !info.area.lastUpdate) {
+        if (node.config.verbose) node.warn('Not enough info to continue')
+        return
+      }
+
+      const calc = calculateCalc(
+        info.area.info as AreaInfo,
+        info.status.info as StatusInfo,
+        node.config.statusselect,
+        info.calc.sleeptime,
+        now
+      )
+      info.calc = calc
+
+      if (node.config.verbose) node.warn(calc)
+
+      node.send([
+        {
+          payload: calc.active,
+          stage: calc.stage,
+          statusselect: node.config.statusselect,
+          api: { count: allowance.count, limit: allowance.limit },
+          calc
+        },
+        {
+          stage: info.status,
+          schedule: info.area
+        }
+      ])
+
+      const fill = calc.active ? 'yellow' : 'green'
+      const shape = calc.active && calc.type === 'event' ? 'dot' : 'ring'
+      let statusText = `Stage ${calc.stage}: `
+
+      if (calc.active && calc.start !== undefined && calc.end !== undefined) {
+        statusText += new Date(calc.start).toLocaleTimeString([], { timeStyle: 'short' })
+        statusText += ' - ' + new Date(calc.end).toLocaleTimeString([], { timeStyle: 'short' })
+      } else if (calc.next) {
+        const nextDate = new Date(calc.next.start)
+        // Fix: original code compared getUTCDay() (0–6) with getUTCDate() (1–31), always unequal
+        if (nextDate.toDateString() !== now.toDateString()) {
+          statusText += nextDate.toLocaleString([], { weekday: 'short' }) + ' '
+        }
+        statusText += nextDate.toLocaleTimeString([], { timeStyle: 'short' })
+        statusText += ' - ' + new Date(calc.next.end).toLocaleTimeString([], { timeStyle: 'short' })
+      }
+
+      statusText += ` (API: ${allowance.count}/${allowance.limit})`
+      node.status({ fill, shape, text: statusText })
+    }
+
+    updateSheddingStatus()
+    const intervalId = setInterval(() => updateSheddingStatus(), 60_000)
+
+    node.on('input', (msg) => updateSheddingStatus(msg as { payload?: unknown }))
+    node.on('close', () => clearInterval(intervalId))
+  }
+
+  RED.nodes.registerType('eskomsepush', EskomSePush)
+
+  RED.httpNode.get('/eskomsepush/search', async (req, res) => {
+    res.setHeader('Content-Type', 'application/json')
+    if (!req.query?.token || !req.query?.search) {
+      return res.send(JSON.stringify({ error: 'invalid' }))
+    }
+    try {
+      const data = await searchAreas(req.query.token, req.query.search)
+      return res.send(data)
+    } catch (err) {
+      return res.send({ error: (err as Error).message })
+    }
+  })
+
+  RED.httpNode.get('/eskomsepush/api', async (req, res) => {
+    res.setHeader('Content-Type', 'application/json')
+    if (!req.query?.token) {
+      return res.send(JSON.stringify({ error: 'invalid' }))
+    }
+    try {
+      const data = await fetchAllowance(req.query.token)
+      return res.send(data)
+    } catch (err) {
+      return res.send({ error: (err as Error).message })
+    }
+  })
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/**/__tests__/**"]
+}

package/tsconfig.test.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["node", "jest"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}