node-red-contrib-eskomsepush 0.0.17 → 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run *)",
+      "Bash(npx jest *)"
+    ]
+  }
+}

package/jest.config.js

@@ -0,0 +1,9 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/src/__tests__/**/*.test.ts'],
+  collectCoverageFrom: ['src/lib/**/*.ts'],
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', { tsconfig: 'tsconfig.test.json' }]
+  }
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "node-red-contrib-eskomsepush",
-  "version": "0.0.17",
+  "version": "0.1.0",
   "description": "Node-RED interface for the Eskomsepush API",
-  "main": "index.js",
   "scripts": {
-    "test": "standard --fix"
+    "build": "tsc && cp src/nodes/eskomsepush.html dist/nodes/ && cp -r src/nodes/icons dist/nodes/",
+    "prepare": "npm run build",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "clean": "rm -rf dist"
   },
   "keywords": [
     "node-red",
@@ -19,7 +22,7 @@
   "license": "MIT",
   "node-red": {
     "nodes": {
-      "eskomsepush": "./src/nodes/eskomsepush.js"
+      "eskomsepush": "./dist/nodes/eskomsepush.js"
     },
     "version": ">=3.0.2"
   },
@@ -28,12 +31,16 @@
     "url": "https://github.com/dirkjanfaber/node-red-contrib-eskomsepush"
   },
   "dependencies": {
-    "axios": "^1.3.5"
+    "axios": "^1.17.0"
   },
   "devDependencies": {
-    "standard": "^17.0.0"
+    "@types/jest": "^29.5.14",
+    "@types/node": "^25.9.3",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.11",
+    "typescript": "^6.0.3"
   },
   "engines": {
-    "node": ">=14.17.4"
+    "node": ">=18.0.0"
   }
 }

package/src/__tests__/api.test.ts

@@ -0,0 +1,103 @@
+import axios from 'axios'
+import { fetchAllowance, fetchArea, fetchStatus, migrateAreaId, searchAreas } from '../lib/api'
+
+jest.mock('axios')
+const mockedAxios = axios as jest.Mocked<typeof axios>
+
+const V3_BASE = 'https://developer.sepush.co.za/business/3.0'
+const TOKEN = 'TEST-TOKEN-1234'
+
+beforeEach(() => jest.clearAllMocks())
+
+describe('migrateAreaId', () => {
+  it('strips the location suffix from a v2-style ID', () => {
+    expect(migrateAreaId('eskde-10-fourways')).toEqual({ id: 'eskde-10', migrated: true })
+  })
+
+  it('leaves a v3-style ID unchanged', () => {
+    expect(migrateAreaId('eskde-10')).toEqual({ id: 'eskde-10', migrated: false })
+  })
+
+  it('handles long location suffixes', () => {
+    expect(migrateAreaId('eskmo-15-ballitokwadukuzakwazulunatal')).toEqual({
+      id: 'eskmo-15',
+      migrated: true
+    })
+  })
+})
+
+describe('fetchAllowance', () => {
+  it('calls the v3 api_allowance endpoint', async () => {
+    const payload = { allowance: { count: 10, limit: 50, type: 'free' } }
+    mockedAxios.get.mockResolvedValueOnce({ data: payload })
+
+    const result = await fetchAllowance(TOKEN)
+
+    expect(mockedAxios.get).toHaveBeenCalledWith(
+      `${V3_BASE}/api_allowance`,
+      expect.objectContaining({ headers: { token: TOKEN } })
+    )
+    expect(result).toEqual(payload)
+  })
+})
+
+describe('fetchStatus', () => {
+  it('calls the v3 status endpoint', async () => {
+    const payload = { status: { eskom: { stage: '2', name: 'National', next_stages: [], stage_updated: '' } } }
+    mockedAxios.get.mockResolvedValueOnce({ data: payload })
+
+    const result = await fetchStatus(TOKEN)
+
+    expect(mockedAxios.get).toHaveBeenCalledWith(
+      `${V3_BASE}/status`,
+      expect.objectContaining({ headers: { token: TOKEN } })
+    )
+    expect(result).toEqual(payload)
+  })
+})
+
+describe('fetchArea', () => {
+  it('calls the v3 area endpoint with the given area ID', async () => {
+    const payload = { events: [], info: { name: 'Test', region: 'Test' }, schedule: { days: [], source: '' } }
+    mockedAxios.get.mockResolvedValueOnce({ data: payload })
+
+    await fetchArea(TOKEN, 'eskde-10')
+
+    expect(mockedAxios.get).toHaveBeenCalledWith(
+      `${V3_BASE}/area`,
+      expect.objectContaining({
+        headers: { token: TOKEN },
+        params: { id: 'eskde-10' }
+      })
+    )
+  })
+
+  it('appends test=current when testMode is true', async () => {
+    mockedAxios.get.mockResolvedValueOnce({ data: {} })
+
+    await fetchArea(TOKEN, 'eskde-10', true)
+
+    expect(mockedAxios.get).toHaveBeenCalledWith(
+      `${V3_BASE}/area`,
+      expect.objectContaining({ params: { id: 'eskde-10', test: 'current' } })
+    )
+  })
+})
+
+describe('searchAreas', () => {
+  it('calls the v3 areas_search endpoint with text param', async () => {
+    const payload = { areas: [{ id: 'eskde-10', name: 'Fourways 2', region: 'Eskom Direct' }] }
+    mockedAxios.get.mockResolvedValueOnce({ data: payload })
+
+    const result = await searchAreas(TOKEN, 'fourways')
+
+    expect(mockedAxios.get).toHaveBeenCalledWith(
+      `${V3_BASE}/areas_search`,
+      expect.objectContaining({
+        headers: { token: TOKEN },
+        params: { text: 'fourways' }
+      })
+    )
+    expect(result).toEqual(payload)
+  })
+})

package/src/__tests__/loadshedding.test.ts

@@ -0,0 +1,262 @@
+import { calculateCalc, calculateSleepTime, getMinutesToAPIReset } from '../lib/loadshedding'
+import type { AreaInfo, StatusInfo } from '../lib/types'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeArea(
+  stageSlots: string[][],
+  tomorrowSlots: string[][] = stageSlots,
+  events: AreaInfo['events'] = []
+): AreaInfo {
+  return {
+    events,
+    info: { name: 'Test Area', region: 'Test Region' },
+    schedule: {
+      days: [
+        { date: '2024-01-15', name: 'Monday',  stages: stageSlots    },
+        { date: '2024-01-16', name: 'Tuesday', stages: tomorrowSlots }
+      ],
+      source: 'test'
+    }
+  }
+}
+
+function makeStatus(stage: string, key = 'eskom'): StatusInfo {
+  return { status: { [key]: { stage, name: 'National', next_stages: [], stage_updated: '' } } }
+}
+
+/** Local Date at a specific clock time on 2024-01-15 */
+function at(h: number, m = 0): Date {
+  return new Date(2024, 0, 15, h, m, 0)
+}
+
+// ---------------------------------------------------------------------------
+// getMinutesToAPIReset
+// ---------------------------------------------------------------------------
+
+describe('getMinutesToAPIReset', () => {
+  it('returns 60 minutes when it is 01:00', () => {
+    expect(getMinutesToAPIReset(at(1))).toBe(60)
+  })
+
+  it('returns 23 * 60 minutes when it is 03:00 (reset already passed today)', () => {
+    expect(getMinutesToAPIReset(at(3))).toBe(23 * 60)
+  })
+
+  it('returns 0 minutes at exactly 02:00', () => {
+    expect(getMinutesToAPIReset(at(2))).toBe(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// calculateSleepTime
+// ---------------------------------------------------------------------------
+
+describe('calculateSleepTime', () => {
+  it('returns 60 when all allowance is consumed', () => {
+    expect(calculateSleepTime(50, 50, 0, 120)).toBe(60)
+  })
+
+  it('returns 60 when remaining is negative due to buffer', () => {
+    expect(calculateSleepTime(50, 48, 5, 120)).toBe(60)
+  })
+
+  it('enforces a minimum of 10 minutes', () => {
+    // remaining=50, minutesToReset=1 → round(1/ceil(50/2)) = round(1/25) = 0 → min 10
+    expect(calculateSleepTime(50, 0, 0, 1)).toBe(10)
+  })
+
+  it('distributes remaining calls evenly over minutesToReset', () => {
+    // remaining=20, minutesToReset=120 → round(120/ceil(20/2)) = round(120/10) = 12
+    expect(calculateSleepTime(50, 30, 0, 120)).toBe(12)
+  })
+
+  it('applies buffer when calculating remaining calls', () => {
+    // remaining=15 (50-30-5), minutesToReset=120 → round(120/ceil(15/2)) = round(120/8) = 15
+    expect(calculateSleepTime(50, 30, 5, 120)).toBe(15)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// calculateCalc
+// ---------------------------------------------------------------------------
+
+describe('calculateCalc', () => {
+  const SLEEPTIME = 60
+
+  describe('stage 0 (no loadshedding)', () => {
+    it('returns inactive with no next period', () => {
+      const area = makeArea([[], []])
+      const status = makeStatus('0')
+      const result = calculateCalc(area, status, 'eskom', SLEEPTIME, at(13))
+
+      expect(result.active).toBe(false)
+      expect(result.next).toBeUndefined()
+    })
+  })
+
+  describe('schedule-based loadshedding', () => {
+    // Stage 2 slots on 2024-01-15: 04:00–06:30 and 12:00–14:30
+    // Stage 1 slots are in index 0, stage 2 in index 1
+    const stageSlots = [
+      ['20:00-22:30'],                  // stage 1
+      ['04:00-06:30', '12:00-14:30']    // stage 2
+    ]
+    const tomorrowSlots = [
+      ['00:00-02:30'],
+      ['00:00-02:30', '08:00-10:30']
+    ]
+
+    it('detects an active schedule slot', () => {
+      const area = makeArea(stageSlots, tomorrowSlots)
+      const result = calculateCalc(area, makeStatus('2'), 'eskom', SLEEPTIME, at(13))
+
+      expect(result.active).toBe(true)
+      expect(result.type).toBe('schedule')
+      expect(result.stage).toBe('2')
+      expect(result.duration).toBe(2.5 * 3600)
+      expect(result.islong).toBe(false)
+    })
+
+    it('finds the next slot later today when not active', () => {
+      const area = makeArea(stageSlots, tomorrowSlots)
+      const result = calculateCalc(area, makeStatus('2'), 'eskom', SLEEPTIME, at(8))
+
+      expect(result.active).toBe(false)
+      expect(result.next?.type).toBe('schedule')
+      expect(result.next?.duration).toBe(2.5 * 3600)
+      expect(result.next?.islong).toBe(false)
+      // secondstostatechange should be positive (time until 12:00)
+      expect(result.secondstostatechange).toBeGreaterThan(0)
+    })
+
+    it('falls back to the first slot tomorrow when today has no more slots', () => {
+      const area = makeArea(stageSlots, tomorrowSlots)
+      const result = calculateCalc(area, makeStatus('2'), 'eskom', SLEEPTIME, at(23))
+
+      expect(result.active).toBe(false)
+      expect(result.next?.type).toBe('schedule')
+      // The next start should be on 2024-01-16 (tomorrow)
+      expect(new Date(result.next!.start).getDate()).toBe(16)
+    })
+
+    it('marks islong true for a 4-hour-plus slot', () => {
+      const longSlots = [
+        ['12:00-16:00']   // stage 1, exactly 4 h
+      ]
+      const area = makeArea(longSlots)
+      const result = calculateCalc(area, makeStatus('1'), 'eskom', SLEEPTIME, at(10))
+
+      expect(result.next?.islong).toBe(true)
+    })
+
+    it('handles midnight-crossing slots', () => {
+      const midnightSlots = [
+        ['22:00-00:30']   // stage 1, crosses midnight
+      ]
+      const area = makeArea(midnightSlots, midnightSlots)
+      const result = calculateCalc(area, makeStatus('1'), 'eskom', SLEEPTIME, at(23))
+
+      expect(result.active).toBe(true)
+      expect(result.type).toBe('schedule')
+    })
+
+    it('sets secondstostatechange to time until shedding ends when active', () => {
+      const area = makeArea(stageSlots, tomorrowSlots)
+      const result = calculateCalc(area, makeStatus('2'), 'eskom', SLEEPTIME, at(13))
+
+      // 14:30 − 13:00 = 90 minutes = 5400 seconds
+      expect(result.secondstostatechange).toBeCloseTo(5400, -1)
+    })
+
+    it('marks isHigherStage true when the next event has a higher stage than current', () => {
+      // We need the schedule loop to NOT overwrite calc.next, so we use an area
+      // whose stages array has only 1 element — stage 2 (index 1) is out of bounds → break.
+      const eventStartMs = Date.UTC(2024, 0, 15, 20, 0)
+      const eventEndMs   = Date.UTC(2024, 0, 15, 22, 30)
+      const events: AreaInfo['events'] = [{
+        start: new Date(eventStartMs).toISOString(),
+        end:   new Date(eventEndMs).toISOString(),
+        note:  'Stage 4 Loadshedding'
+      }]
+      const area = makeArea([['20:00-22:30']], [['00:00-02:30']], events)
+      const result = calculateCalc(area, makeStatus('2'), 'eskom', SLEEPTIME, at(10))
+
+      expect(result.next?.type).toBe('event')
+      expect(result.next?.stage).toBe('4')
+      expect(result.next?.isHigherStage).toBe(true)
+    })
+  })
+
+  describe('event-based loadshedding', () => {
+    // Events use ISO timestamps with timezone offset — Date.parse handles them in UTC
+    const eventStartMs = Date.UTC(2024, 0, 15, 10, 0)   // 10:00 UTC
+    const eventEndMs   = Date.UTC(2024, 0, 15, 12, 30)  // 12:30 UTC
+    const events: AreaInfo['events'] = [{
+      start: new Date(eventStartMs).toISOString(),
+      end:   new Date(eventEndMs).toISOString(),
+      note:  'Stage 2 Loadshedding'
+    }]
+
+    it('detects an active event', () => {
+      const area = makeArea([[]], [[]], events)
+      const nowUTC = new Date(Date.UTC(2024, 0, 15, 11, 0)) // 11:00 UTC, inside event
+
+      const result = calculateCalc(area, makeStatus('0'), 'eskom', SLEEPTIME, nowUTC)
+
+      expect(result.active).toBe(true)
+      expect(result.type).toBe('event')
+      expect(result.stage).toBe('2') // stage overridden from event note
+    })
+
+    it('finds an upcoming event when not yet started', () => {
+      const area = makeArea([[]], [[]], events)
+      const nowUTC = new Date(Date.UTC(2024, 0, 15, 8, 0)) // 08:00 UTC, before event
+
+      const result = calculateCalc(area, makeStatus('0'), 'eskom', SLEEPTIME, nowUTC)
+
+      expect(result.active).toBe(false)
+      expect(result.next?.type).toBe('event')
+      expect(result.next?.duration).toBe(2.5 * 3600)
+    })
+
+    it('ignores a past event', () => {
+      const area = makeArea([[]], [[]], events)
+      const nowUTC = new Date(Date.UTC(2024, 0, 15, 13, 0)) // 13:00 UTC, after event
+
+      const result = calculateCalc(area, makeStatus('0'), 'eskom', SLEEPTIME, nowUTC)
+
+      expect(result.active).toBe(false)
+      expect(result.next).toBeUndefined()
+    })
+
+    it('does not crash when event note has no stage pattern', () => {
+      const bareEvents: AreaInfo['events'] = [{
+        start: new Date(eventStartMs).toISOString(),
+        end:   new Date(eventEndMs).toISOString(),
+        note:  'Unplanned outage'
+      }]
+      const area = makeArea([[]], [[]], bareEvents)
+      const nowUTC = new Date(Date.UTC(2024, 0, 15, 11, 0))
+
+      expect(() => calculateCalc(area, makeStatus('1'), 'eskom', SLEEPTIME, nowUTC)).not.toThrow()
+    })
+  })
+
+  describe('statusselect', () => {
+    it('reads the stage from the correct statusselect key', () => {
+      const statusInfo: StatusInfo = {
+        status: {
+          eskom:    { stage: '1', name: 'National', next_stages: [], stage_updated: '' },
+          capetown: { stage: '3', name: 'Cape Town', next_stages: [], stage_updated: '' }
+        }
+      }
+      const area = makeArea([['20:00-22:30'], [], ['12:00-14:30', '20:00-22:30']])
+      const result = calculateCalc(area, statusInfo, 'capetown', SLEEPTIME, at(8))
+
+      expect(result.stage).toBe('3')
+    })
+  })
+})

package/src/lib/api.ts

@@ -0,0 +1,45 @@
+import axios from 'axios'
+import type { AllowanceInfo, AreaInfo, AreasSearchResult, StatusInfo } from './types'
+
+const API_BASE = 'https://developer.sepush.co.za/business/3.0'
+
+/** Detects a v2-style area ID (e.g. eskde-10-fourways) and returns the v3 equivalent (eskde-10). */
+export function migrateAreaId(areaId: string): { id: string; migrated: boolean } {
+  const parts = areaId.split('-')
+  if (parts.length > 2) {
+    return { id: parts.slice(0, 2).join('-'), migrated: true }
+  }
+  return { id: areaId, migrated: false }
+}
+
+export async function fetchAllowance(token: string): Promise<AllowanceInfo> {
+  const { data } = await axios.get<AllowanceInfo>(`${API_BASE}/api_allowance`, {
+    headers: { token }
+  })
+  return data
+}
+
+export async function fetchStatus(token: string): Promise<StatusInfo> {
+  const { data } = await axios.get<StatusInfo>(`${API_BASE}/status`, {
+    headers: { token }
+  })
+  return data
+}
+
+export async function fetchArea(token: string, areaId: string, testMode = false): Promise<AreaInfo> {
+  const params: Record<string, string> = { id: areaId }
+  if (testMode) params.test = 'current'
+  const { data } = await axios.get<AreaInfo>(`${API_BASE}/area`, {
+    headers: { token },
+    params
+  })
+  return data
+}
+
+export async function searchAreas(token: string, query: string): Promise<AreasSearchResult> {
+  const { data } = await axios.get<AreasSearchResult>(`${API_BASE}/areas_search`, {
+    headers: { token },
+    params: { text: query }
+  })
+  return data
+}

package/src/lib/loadshedding.ts

@@ -0,0 +1,131 @@
+import type { AreaInfo, CalcResult, StatusInfo } from './types'
+
+export function getMinutesToAPIReset(now: Date = new Date()): number {
+  const resetTime = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 2, 0, 0)
+  if (now > resetTime) {
+    resetTime.setDate(resetTime.getDate() + 1)
+  }
+  return Math.floor((resetTime.getTime() - now.getTime()) / 60_000)
+}
+
+export function calculateSleepTime(
+  limit: number,
+  count: number,
+  buffer: number,
+  minutesToReset: number
+): number {
+  const remaining = limit - buffer - count
+  if (remaining <= 0) return 60
+  const sleeptime = Math.round(minutesToReset / Math.ceil(remaining / 2))
+  return Math.max(sleeptime, 10)
+}
+
+function parseScheduleTime(date: string, time: string): number {
+  const [year, month, day] = date.split('-').map(Number)
+  const [hour, minute] = time.split(':').map(Number)
+  return new Date(year, month - 1, day, hour, minute).getTime()
+}
+
+export function calculateCalc(
+  areaInfo: AreaInfo,
+  statusInfo: StatusInfo,
+  statusselect: string,
+  sleeptime: number,
+  now: Date = new Date()
+): CalcResult {
+  const statusStage = statusInfo.status[statusselect]?.stage ?? '0'
+  const calc: CalcResult = {
+    sleeptime,
+    stage: statusStage,
+    active: false
+  }
+
+  // Check events first — an active event can override the effective stage
+  if (areaInfo.events.length > 0) {
+    const firstEvent = areaInfo.events[0]
+    const eventStart = Date.parse(firstEvent.start)
+    const eventEnd = Date.parse(firstEvent.end)
+
+    if (now.getTime() >= eventStart && now.getTime() < eventEnd) {
+      calc.type = 'event'
+      calc.active = true
+      const stageMatch = firstEvent.note.match(/Stage (\d+)/i)
+      if (stageMatch) calc.stage = stageMatch[1]
+      calc.start = eventStart
+      calc.end = eventEnd
+    } else if (now.getTime() < eventStart) {
+      const stageMatch = firstEvent.note.match(/Stage (\d+)/i)
+      calc.next = {
+        type: 'event',
+        start: eventStart,
+        end: eventEnd,
+        duration: 0,   // computed in post-loop block
+        islong: false, // computed in post-loop block
+        stage: stageMatch ? stageMatch[1] : statusStage
+      }
+    }
+  }
+
+  // Check scheduled downtime — uses local time (schedule times have no timezone info)
+  const effectiveStageNum = parseInt(String(calc.stage), 10)
+  let breakLoop = false
+
+  for (const day of areaInfo.schedule.days) {
+    const stageIndex = effectiveStageNum - 1
+
+    if (stageIndex < 0 || stageIndex >= day.stages.length) {
+      break // Stage 0 or out of range → no scheduled loadshedding
+    }
+
+    const slots = day.stages[stageIndex]
+    if (!Array.isArray(slots)) break
+
+    for (const slot of slots) {
+      const [startStr, endStr] = slot.split('-')
+      let schedStart = parseScheduleTime(day.date, startStr)
+      let schedEnd = parseScheduleTime(day.date, endStr)
+
+      // Handle slots that cross midnight (e.g. "22:00-00:30")
+      if (schedEnd < schedStart) {
+        schedEnd += 24 * 60 * 60 * 1000
+      }
+
+      if (now.getTime() < schedEnd) {
+        breakLoop = true
+        if (now.getTime() >= schedStart) {
+          calc.active = true
+          calc.type = 'schedule'
+          calc.start = schedStart
+          calc.end = schedEnd
+        } else {
+          calc.next = {
+            type: 'schedule',
+            start: schedStart,
+            end: schedEnd,
+            duration: 0,   // computed below
+            islong: false, // computed below
+            stage: calc.stage
+          }
+        }
+        break
+      }
+    }
+    if (breakLoop) break
+  }
+
+  // Compute derived fields — next block runs first so active block can overwrite secondstostatechange
+  if (calc.next) {
+    calc.next.duration = (calc.next.end - calc.next.start) / 1000
+    calc.next.islong = calc.next.duration >= 4 * 3600
+    calc.secondstostatechange = Math.floor((calc.next.start - now.getTime()) / 1000)
+    calc.next.isHigherStage = Number(calc.next.stage) > Number(calc.stage)
+  }
+
+  if (calc.active && calc.start !== undefined && calc.end !== undefined) {
+    calc.duration = (calc.end - calc.start) / 1000
+    calc.islong = calc.duration >= 4 * 3600
+    calc.secondstostatechange = Math.floor((calc.end - now.getTime()) / 1000)
+  }
+
+  return calc
+}

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.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"]
+}

package/src/nodes/eskomsepush.js

@@ -1,368 +0,0 @@
-module.exports = function (RED) {
-  'use strict'
-
-  const axios = require('axios')
-  const EskomSePushInfo = {
-    api: {
-      lastUpdate: null,
-      info: {}
-    },
-    status: {
-      lastUpdate: null,
-      info: {}
-    },
-    area: {
-      lastUpdate: null,
-      info: {}
-    },
-    calc: {}
-  }
-
-  function getMinutesToAPIReset () {
-    const now = new Date()
-    const targetTime = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 2, 0, 0)
-    if (now > targetTime) {
-      targetTime.setDate(targetTime.getDate() + 1)
-    }
-    const timeDiff = targetTime - now
-    const minutesLeft = Math.floor(timeDiff / (1000 * 60))
-
-    return minutesLeft
-  }
-
-  function checkAllowance (node) {
-    const options = {}
-    const headers = { token: node.config.licensekey }
-
-    if (node.config.verbose === true) {
-      node.warn('Running function checkAllowance')
-    }
-    axios.get('https://developer.sepush.co.za/business/2.0/api_allowance',
-      { params: options, headers }).then(function (response) {
-      EskomSePushInfo.api.info = response.data
-      if (EskomSePushInfo.api.lastUpdate === null) {
-        EskomSePushInfo.api.lastUpdate = new Date()
-        updateSheddingStatus(node)
-      }
-      EskomSePushInfo.api.lastUpdate = new Date()
-    })
-      .catch(error => {
-        node.warn({ error: error.message })
-      })
-  }
-
-  function checkStage (node) {
-    const options = {}
-    const headers = { token: node.config.licensekey }
-
-    if (node.config.verbose === true) {
-      let warnstring = 'Running function checkStage'
-      if (EskomSePushInfo.status.lastUpdate === null) {
-        warnstring += ' - initial run'
-      } else {
-        warnstring += ' after ' + ((new Date() - EskomSePushInfo.status.lastUpdate) / 60000).toFixed(0) + ' minutes'
-      }
-      node.warn(warnstring)
-    }
-    axios.get('https://developer.sepush.co.za/business/2.0/status',
-      { params: options, headers }).then(function (response) {
-      EskomSePushInfo.status.info = response.data
-      EskomSePushInfo.status.lastUpdate = new Date()
-      // Call updateSheddingStatus again now we have new data
-      updateSheddingStatus(node)
-    })
-      .catch(error => {
-        node.warn({ error: error.message })
-      })
-  }
-
-  function checkArea (node) {
-    const options = { id: node.config.area }
-    const headers = { token: node.config.licensekey }
-    const url = 'https://developer.sepush.co.za/business/2.0/area'
-
-    if (node.config.verbose === true) {
-      let warnstring = 'Running function checkArea'
-      if (EskomSePushInfo.area.lastUpdate === null) {
-        warnstring += ' - initial run'
-      } else {
-        warnstring += ' after ' + ((new Date() - EskomSePushInfo.area.lastUpdate) / 60000).toFixed(0) + ' minutes'
-      }
-      node.warn(warnstring)
-    }
-    if (node.config.test) {
-      options.test = 'current'
-    }
-    axios.get(url,
-      { params: options, headers }).then(function (response) {
-      EskomSePushInfo.area.info = response.data
-      EskomSePushInfo.area.lastUpdate = new Date()
-      // Call updateSheddingStatus again now we have new data
-      updateSheddingStatus(node)
-    })
-      .catch(error => {
-        node.warn({ error: error.message })
-      })
-  }
-
-  function updateSheddingStatus (node, msg) {
-    const now = new Date()
-
-    // Check allowance every ten minutes
-    if ((msg && msg.payload === 'allowance') || EskomSePushInfo.api.lastUpdate === null || (now.getTime() - EskomSePushInfo.api.lastUpdate.getTime()) > 600000) {
-      checkAllowance(node)
-    }
-
-    // If we don't have API info, we just return
-    if (Object.entries(EskomSePushInfo.api.info).length === 0) {
-      node.warn('No API info (yet), refusing to continue')
-      return
-    }
-
-    // The same is true if we have no API calls left
-    if (EskomSePushInfo.api.info.allowance.count >= EskomSePushInfo.api.info.allowance.limit) {
-      node.warn('No API calls left, not checking status/schedule')
-      return
-    }
-
-    // Fetching actual information takes 2 calls, so calculate how long until the next API count
-    // reset and divide the calls over the day. Wait at least 60 minutes between calls
-    // reduce limit by api_allowance_buffer to cater for units consumed by other API calls
-    if (node.config.verbose === true) {
-      node.warn('Minutes to API Reset: ' + getMinutesToAPIReset())
-    }
-    const allowanceRemaining = EskomSePushInfo.api.info.allowance.limit - node.config.api_allowance_buffer - EskomSePushInfo.api.info.allowance.count
-
-    if (allowanceRemaining > 0) {
-      EskomSePushInfo.calc.sleeptime = Math.round(getMinutesToAPIReset() / Math.ceil(allowanceRemaining / 2))
-      if (node.config.verbose === true) {
-        node.warn('API allowance limit: ' + EskomSePushInfo.api.info.allowance.limit)
-        node.warn('API allowance count: ' + EskomSePushInfo.api.info.allowance.count)
-        node.warn('Calculated sleeptime: ' + EskomSePushInfo.calc.sleeptime)
-      }
-      if (EskomSePushInfo.calc.sleeptime < 10) {
-        EskomSePushInfo.calc.sleeptime = 10
-        if (node.config.verbose === true) {
-          node.warn('Calculated sleeptime was less than 10. Set it to 10: ' + EskomSePushInfo.calc.sleeptime)
-        }
-      }
-    } else {
-      EskomSePushInfo.calc.sleeptime = 60
-      if (node.config.verbose === true) {
-        node.warn('Set sleeptime to 60 since allowance count is low: ' + EskomSePushInfo.calc.sleeptime)
-      }
-    }
-
-    if ((msg && msg.payload === 'stage') || EskomSePushInfo.status.lastUpdate === null || (now.getTime() - EskomSePushInfo.status.lastUpdate) > (EskomSePushInfo.calc.sleeptime * 60000)) {
-      checkStage(node)
-    }
-
-    if ((msg && msg.payload === 'area') || EskomSePushInfo.area.lastUpdate === null || (now.getTime() - EskomSePushInfo.area.lastUpdate) > (EskomSePushInfo.calc.sleeptime * 60000)) {
-      checkArea(node)
-    }
-
-    // Now we have all info to continue. Just making sure that all update values are non null.
-    if (EskomSePushInfo.api.lastUpdate === null ||
-        EskomSePushInfo.status.lastUpdate === null ||
-        EskomSePushInfo.area.lastUpdate === null) {
-      (node.config.verbose === true) && node.warn('Not enough info to continue.')
-      return
-    }
-
-    // Determine the current stage
-    EskomSePushInfo.calc.stage = EskomSePushInfo.status.info.status[node.config.statusselect].stage
-
-    if (node.config.verbose === true) {
-      node.warn('API call status: ' + EskomSePushInfo.api.info.allowance.count + '/' + EskomSePushInfo.api.info.allowance.limit)
-      node.warn(EskomSePushInfo)
-    }
-
-    // Default to false, overrule of loadshedding is active
-    EskomSePushInfo.calc.active = false
-
-    // Are there any events going on?
-    if (Object.entries(EskomSePushInfo.area.info.events).length > 0) {
-      const EventStart = Date.parse(EskomSePushInfo.area.info.events[0].start)
-      const EventEnd = Date.parse(EskomSePushInfo.area.info.events[0].end)
-      if (now >= EventStart && now < EventEnd) {
-        EskomSePushInfo.calc.type = 'event'
-        EskomSePushInfo.calc.active = true
-        if (EskomSePushInfo.area.info.events[0].note.match(/Stage (\d+)/i)) {
-          EskomSePushInfo.calc.stage = EskomSePushInfo.area.info.events[0].note.match(/Stage (\d+)/i)[1]
-        }
-        EskomSePushInfo.calc.start = EventStart
-        EskomSePushInfo.calc.end = EventEnd
-      } else {
-        EskomSePushInfo.calc.next = {
-          type: 'event',
-          start: EventStart,
-          end: EventEnd,
-          stage: EskomSePushInfo.area.info.events[0].note.match(/Stage (\d+)/i)[1]
-        }
-      }
-    }
-
-    // Scheduled downtime has the thing that the time is in locatime
-    // So not just like events, where they are in UTC with an offset
-    let BreakLoop = false
-    for (const dates of EskomSePushInfo.area.info.schedule.days) {
-      const stageIndex = EskomSePushInfo.calc.stage - 1
-      if (stageIndex >= 0 && stageIndex < dates.stages.length) {
-        if (Array.isArray(dates.stages[stageIndex])) {
-          for (const schedule of dates.stages[stageIndex]) {
-            const ScheduleStart = Date.parse(dates.date + ' ' + schedule.split('-')[0])
-            let ScheduleEnd = Date.parse(dates.date + ' ' + schedule.split('-')[1])
-            if (ScheduleEnd < ScheduleStart) {
-              ScheduleEnd += (24 * 60 * 60 * 1000)
-            }
-            if (now < ScheduleEnd) {
-              BreakLoop = true
-              // This schedule is either active or will be next
-              if (now >= ScheduleStart) {
-                EskomSePushInfo.calc.active = true
-                EskomSePushInfo.calc.type = 'schedule'
-                EskomSePushInfo.calc.start = ScheduleStart
-                EskomSePushInfo.calc.end = ScheduleEnd
-              } else {
-                EskomSePushInfo.calc.next = {
-                  type: 'schedule',
-                  start: ScheduleStart,
-                  end: ScheduleEnd,
-                  stage: EskomSePushInfo.calc.stage
-                }
-              }
-            }
-            if (BreakLoop) { break }
-          }
-        } else {
-          console.warn('Not an array:', dates.stages[stageIndex]) // Warning if not an array
-        }
-      } else {
-        console.warn('Invalid stage index:', stageIndex) // Warning if stage index is out of bounds
-      }
-      if (BreakLoop) { break }
-    }
-
-    if (EskomSePushInfo.calc.next) {
-      EskomSePushInfo.calc.next.duration = (EskomSePushInfo.calc.next.end - EskomSePushInfo.calc.next.start) / 1000
-      EskomSePushInfo.calc.next.islong = EskomSePushInfo.calc.next.duration >= (4 * 3600)
-      EskomSePushInfo.calc.secondstostatechange = parseInt((EskomSePushInfo.calc.next.start - now) / 1000)
-      EskomSePushInfo.calc.next.isHigherStage = EskomSePushInfo.calc.next.stage > EskomSePushInfo.calc.stage
-    }
-
-    if (EskomSePushInfo.calc.active) {
-      EskomSePushInfo.calc.duration = (EskomSePushInfo.calc.end - EskomSePushInfo.calc.start) / 1000
-      EskomSePushInfo.calc.islong = EskomSePushInfo.calc.duration >= (4 * 3600)
-      EskomSePushInfo.calc.secondstostatechange = parseInt((EskomSePushInfo.calc.end - now) / 1000)
-    }
-
-    if (node.config.verbose === true) {
-      node.warn(EskomSePushInfo.calc)
-    }
-
-    // Send output
-    node.send([{
-      payload: EskomSePushInfo.calc.active,
-      stage: EskomSePushInfo.calc.stage,
-      statusselect: node.config.statusselect,
-      api: {
-        count: EskomSePushInfo.api.info.allowance.count,
-        limit: EskomSePushInfo.api.info.allowance.limit
-      },
-      calc: EskomSePushInfo.calc
-    }, {
-      stage: EskomSePushInfo.status,
-      schedule: EskomSePushInfo.area
-    }])
-
-    // And update the status
-    let fill = 'green'
-    let shape = 'ring'
-    let statusText = 'Stage ' + EskomSePushInfo.calc.stage + ': '
-
-    if (EskomSePushInfo.calc.active) {
-      fill = 'yellow'
-      if (EskomSePushInfo.calc.type === 'event') {
-        shape = 'dot'
-      }
-      if (EskomSePushInfo.calc.start) {
-        statusText += new Date(EskomSePushInfo.calc.start).toLocaleTimeString([], { timeStyle: 'short' })
-        statusText += ' - ' + new Date(EskomSePushInfo.calc.end).toLocaleTimeString([], { timeStyle: 'short' })
-      }
-    } else {
-      if (new Date(EskomSePushInfo.calc.next.start).getUTCDay() !== now.getUTCDate()) {
-        statusText += new Date(EskomSePushInfo.calc.next.start).toLocaleString([], { weekday: 'short' }) + ' '
-      }
-      statusText += new Date(EskomSePushInfo.calc.next.start).toLocaleTimeString([], { timeStyle: 'short' })
-      statusText += ' - ' + new Date(EskomSePushInfo.calc.next.end).toLocaleTimeString([], { timeStyle: 'short' })
-    }
-
-    statusText += ' (API: ' + EskomSePushInfo.api.info.allowance.count + '/' + EskomSePushInfo.api.info.allowance.limit + ')'
-    node.status({
-      fill, shape, text: statusText
-    })
-  }
-
-  function EskomSePush (config) {
-    RED.nodes.createNode(this, config)
-
-    const node = this
-    node.config = config
-
-    updateSheddingStatus(node)
-    const intervalId = setInterval(function () {
-      updateSheddingStatus(node)
-    }, 60000)
-
-    node.on('input', function (msg) {
-      updateSheddingStatus(node, msg)
-    })
-
-    node.on('close', function () {
-      clearInterval(intervalId)
-    })
-  }
-
-  RED.nodes.registerType('eskomsepush', EskomSePush)
-
-  RED.httpNode.get('/eskomsepush/search', (req, res) => {
-    if (!req.query || !req.query.token || !req.query.search) {
-      res.setHeader('Content-Type', 'application/json')
-      return res.send('invalid')
-    }
-    const headers = {
-      token: req.query.token
-    }
-    const options = {
-      text: req.query.search
-    }
-
-    res.setHeader('Content-Type', 'application/json')
-    axios.get('https://developer.sepush.co.za/business/2.0/areas_search',
-      { params: options, headers }).then(function (response) {
-      return res.send(response.data)
-    })
-      .catch(error => {
-        return res.send({ error: error.message })
-      })
-  })
-  RED.httpNode.get('/eskomsepush/api', (req, res) => {
-    if (!req.query.token) {
-      res.setHeader('Content-Type', 'application/json')
-      return res.send('invalid')
-    }
-    const headers = {
-      token: req.query.token
-    }
-    const options = {}
-
-    res.setHeader('Content-Type', 'application/json')
-    axios.get('https://developer.sepush.co.za/business/2.0/api_allowance',
-      { params: options, headers }).then(function (response) {
-      return res.send(response.data)
-    })
-      .catch(error => {
-        return res.send({ error: error.message })
-      })
-  })
-}