chronograph-npm 0.1.4 → 0.2.0

package/.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: XeroxQ
+patreon: QlusterIT
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

package/.github/workflows/add-to-project.yml

@@ -0,0 +1,19 @@
+name: Add issues/PRs to project
+
+on:
+  issues:
+    types:
+      - opened
+  pull_request:
+    types:
+      - opened
+
+jobs:
+  add-to-project:
+    name: Add issue/PR to project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v2
+        with:
+          project-url: https://github.com/orgs/Qluster-IT/projects/1
+          github-token: ${{ secrets.PAT }}

package/.github/workflows/auto-assign-issues.yml

@@ -0,0 +1,22 @@
+name: Issue/PR assignment
+
+on:
+    issues:
+        types: [opened]
+    pull_request:
+        types: [opened] #edited, synchronize, reopened
+
+jobs:
+    auto-assign:
+        runs-on: ubuntu-latest
+        permissions:
+            issues: write
+            pull-requests: write
+        steps:
+            - name: 'Auto-assign issue/PR'
+              uses: pozil/auto-assign-issue@v4
+              with:
+                  assignees: XeroxQ
+                  numOfAssignee: 1
+                  allowSelfAssign: true
+                  repo-token: ${{ secrets.PAT }}

package/.github/workflows/reopen-project-item.yml

@@ -0,0 +1,82 @@
+name: Project Item Unarchiveren en Status naar Ready
+
+on:
+  issues:
+    types: [reopened]
+  pull_request:
+    types: [reopened]
+
+jobs:
+  unarchive-and-move:
+    runs-on: ubuntu-latest
+    env:
+      # Hier splitsen we de URL op om de CLI-fout te voorkomen
+      PROJECT_OWNER: "Qluster-IT"
+      PROJECT_NUMBER: 1
+      GITHUB_TOKEN: ${{ secrets.PAT }}
+      ISSUE_NODE_ID: ${{ github.event.issue.node_id }}
+
+    steps:
+      - name: Zoek gekoppeld Project en Item via GraphQL
+        id: item_info
+        run: |
+          RESPONSE=$(gh api graphql -f query='
+            query($issueId: ID!) {
+              node(id: $issueId) {
+                ... on Issue {
+                  projectItems(first: 10) {
+                    nodes {
+                      id
+                      isArchived
+                      project {
+                        id
+                        number
+                        owner {
+                          ... on Organization { login }
+                          ... on User { login }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          ' -f issueId="$ISSUE_NODE_ID")
+
+          # Filter de data voor het juiste project
+          ITEM_DATA=$(echo "$RESPONSE" | jq -r --argjson num "${{ env.PROJECT_NUMBER }}" --arg owner "${{ env.PROJECT_OWNER }}" \
+            '.data.node.projectItems.nodes[] | select(.project.number == $num and (.project.owner.login | ascii_downcase) == ($owner | ascii_downcase))')
+
+          ITEM_ID=$(echo "$ITEM_DATA" | jq -r '.id // empty')
+          PROJECT_ID=$(echo "$ITEM_DATA" | jq -r '.project.id // empty')
+          IS_ARCHIVED=$(echo "$ITEM_DATA" | jq -r '.isArchived // false')
+
+          echo "Gevonden Item ID: $ITEM_ID"
+          echo "Gevonden Project ID: $PROJECT_ID"
+          echo "Is gearchiveerd: $IS_ARCHIVED"
+
+          echo "item_id=$ITEM_ID" >> $GITHUB_OUTPUT
+          echo "project_id=$PROJECT_ID" >> $GITHUB_OUTPUT
+          echo "is_archived=$IS_ARCHIVED" >> $GITHUB_OUTPUT
+
+      - name: Unarchive het projectitem
+        if: steps.item_info.outputs.item_id != '' && steps.item_info.outputs.is_archived == 'true'
+        run: |
+          # We sturen nu verplicht projectId én itemId mee, en vragen 'item { id }' op als return
+          gh api graphql -f query='
+            mutation($projectId: ID!, $itemId: ID!) {
+              unarchiveProjectV2Item(input: {projectId: $projectId, itemId: $itemId}) {
+                item { id }
+              }
+            }
+          ' -f projectId="${{ steps.item_info.outputs.project_id }}" -f itemId="${{ steps.item_info.outputs.item_id }}"
+
+      - name: Zet status op Ready
+        if: steps.item_info.outputs.item_id != ''
+        run: |
+          # We gebruiken nu de URL van het issue in plaats van de --id vlag
+          gh project item-edit ${{ env.PROJECT_NUMBER }} \
+            --owner "${{ env.PROJECT_OWNER }}" \
+            --url "https://github.com/${{ env.PROJECT_OWNER }}/${{ github.event.repository.name }}/issues/${{ github.event.issue.number }}" \
+            --field "Status" \
+            --value "Ready"

package/README.md

@@ -1 +1,96 @@
-## NPM Package for the Chronograph App for Athom's Homey.
+# Chronograph for Homey
+
+`chronograph-npm` lets a Homey app access chronographs provided by the [Chronograph app](https://homey.app/a/nl.fellownet.chronograph/). It provides helpers for retrieving chronographs and receiving realtime updates.
+
+## Installation
+
+Install the package in your Homey app project:
+
+```sh
+npm install chronograph-npm
+```
+
+Add Chronograph to the permissions in your app's `app.json`:
+
+```json
+{
+  "permissions": [
+    "homey:app:nl.fellownet.chronograph"
+  ]
+}
+```
+
+## Initialize
+
+Import `CG` and initialize it from your app's `onInit` method:
+
+```js
+const { CG } = require('chronograph-npm');
+
+class MyApp extends Homey.App {
+  async onInit() {
+    this.chronograph = await CG.init({ homey: this.homey });
+  }
+}
+
+module.exports = MyApp;
+```
+
+`CG.init` accepts one option, `homey`, which must be the Homey instance. It returns a `CG` instance and registers a realtime listener. It does not fetch chronographs during initialization; call `CG.getChronographs()` or `CG.getAllChronographs()` when you need that data. When Homey emits `unload` as the consuming app stops, `CG.destroy()` is called automatically to remove the listeners, without replacing your app's lifecycle methods. Cleanup cannot be guaranteed if the process is forcibly terminated.
+
+## Available API
+
+The package exports the `CG` class:
+
+| Method or property | Description |
+| --- | --- |
+| `CG.init({ homey })` | Initializes the integration and returns a `CG` instance. |
+| `CG.getChronographs()` | Returns the current active chronographs as an array. Each snapshot contains `name`, `data`, `duration`, `targetDuration`, and `running`. |
+| `CG.getAllChronographs()` | Returns configured chronograph names grouped by type, such as `timer`, `stopwatch`, and `transition`. |
+| `CG.onChronographUpdate({ chronograph })` | Update hook. Override it to handle realtime updates; the default implementation does nothing. |
+| `CG.destroy()` | Removes the realtime and unload listeners. Called automatically on Homey's `unload` event; can also be called manually. |
+| `instance.ready` / `CG.ready` | Promise that resolves after successful initialization and realtime-listener registration. |
+| `instance.isReady` / `CG.isReady` | Indicates whether the integration has become ready. |
+
+For example, retrieve active chronographs after initialization:
+
+```js
+const chronographs = await CG.getChronographs();
+for (const chronograph of chronographs) {
+  this.log(chronograph.name, chronograph.running, chronograph.duration);
+}
+```
+
+Use `getAllChronographs()` when you need the configured names (including chronographs that are not currently active):
+
+```js
+const configured = await CG.getAllChronographs();
+this.log(configured.timer);
+```
+
+## Realtime updates
+
+Override the update hook before initializing `CG`. The hook is called with `{ chronograph }` for each realtime update. If an update contains a `now` value, the package converts it to a JavaScript `Date`.
+
+```js
+const { CG } = require('chronograph-npm');
+
+class MyApp extends Homey.App {
+  async onInit() {
+    CG.onChronographUpdate = async ({ chronograph }) => {
+      this.log('Chronograph updated:', chronograph.name, chronograph.now);
+    };
+
+    this.chronograph = await CG.init({ homey: this.homey });
+  }
+}
+
+module.exports = MyApp;
+```
+
+## Requirements
+
+- The Chronograph app must be installed on the same Homey.
+- Your app must declare the Chronograph permission in `app.json`.
+- Initialize the package with your app's Homey instance before calling the retrieval methods.
+- Initialization only registers for realtime updates; fetch chronograph data explicitly using the retrieval methods.

package/dist/cg.d.ts

@@ -2,14 +2,53 @@ export class CG {
     static init({ homey }?: {
         homey: any;
     }): Promise<CG>;
+    /**
+     * Removes the realtime and unload listeners. Called automatically when Homey emits unload.
+     */
     static destroy(): void;
     static getAllChronographs(): Promise<any>;
     static getChronographs(): Promise<any>;
     /**
-     * @description Setable member, when set, will be activated on any variable update.
-     * @param {Object} param0.variable
+     * Handles a realtime update from the Chronograph app. Override this method
+     * to receive updated chronograph data.
+     * @param {Object} param0 Update payload.
+     * @param {Object} param0.chronograph Realtime state snapshot, not a Chronograph class instance.
+     * @param {string} [param0.chronograph.id] Generated identifier; omitted from single-event updates.
+     * @param {string} param0.chronograph.name Configured chronograph name.
+     * @param {number} param0.chronograph.duration Elapsed duration in milliseconds, also exposed as elapsed.
+     * @param {number} param0.chronograph.elapsed Elapsed duration in milliseconds.
+     * @param {number|null} param0.chronograph.targetDuration Target duration in milliseconds.
+     * Stopwatches have no target (NaN before serialization, normally null over the API).
+     * @param {number|null} param0.chronograph.remaining Target duration minus elapsed duration, in milliseconds.
+     * Not meaningful for stopwatches; may be NaN or null after serialization.
+     * @param {boolean} param0.chronograph.running Whether the chronograph is running.
+     * @param {boolean} param0.chronograph.removed Whether this update reports removal of the chronograph.
+     * @param {Date} param0.chronograph.now Snapshot timestamp, converted to a Date by this package.
+     * @param {Object} param0.chronograph.data Chronograph metadata, excluding flowValues; may be incomplete during creation.
+     * @param {'Timer'|'Stopwatch'|'Transition'} [param0.chronograph.data.type] Chronograph kind.
+     * @param {number} [param0.chronograph.data.from] Transition starting value.
+     * @param {number} [param0.chronograph.data.to] Transition ending value.
+     * @param {number} [param0.chronograph.data.steps] Transition step count, limited by its duration.
      */
-    static onChronographUpdate({ chronograph }: any): Promise<void>;
+    static onChronographUpdate({ chronograph }: {
+        chronograph: {
+            id?: string;
+            name: string;
+            duration: number;
+            elapsed: number;
+            targetDuration: number | null;
+            remaining: number | null;
+            running: boolean;
+            removed: boolean;
+            now: Date;
+            data: {
+                type?: 'Timer' | 'Stopwatch' | 'Transition';
+                from?: number;
+                to?: number;
+                steps?: number;
+            };
+        };
+    }): Promise<void>;
     constructor({ homey }: {
         homey: any;
     });

package/dist/cg.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cg.d.ts","sourceRoot":"","sources":["../src/cg.js"],"names":[],"mappings":"AAAA;IAGI;;oBAyBC;IA+BD,uBAQC;IAuCD,0CAEC;IAED,uCAEC;IAKD;;;OAGG;IACH,gEAGC;IA/FD;;OAWC;IATG,WAA6B;IAC7B,iBAAoB;IAIpB,WAAyC;IAM7C,2BAaC;IAVW,SAAqC;IAyBjD,uDAcC;IAGD,eAAe;IACf,kBAeC;CAyBJ"}
+{"version":3,"file":"cg.d.ts","sourceRoot":"","sources":["../src/cg.js"],"names":[],"mappings":"AAAA;IAGI;;oBAWC;IA+BD;;OAEG;IACH,uBASC;IAuCD,0CAEC;IAED,uCAEC;IAKD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;QAlB0B,WAAW;YACE,EAAE,GAA9B,MAAM;YACqB,IAAI,EAA/B,MAAM;YACqB,QAAQ,EAAnC,MAAM;YACqB,OAAO,EAAlC,MAAM;YAC0B,cAAc,EAA9C,MAAM,GAAC,IAAI;YAEqB,SAAS,EAAzC,MAAM,GAAC,IAAI;YAEiB,OAAO,EAAnC,OAAO;YACqB,OAAO,EAAnC,OAAO;YACkB,GAAG,EAA5B,IAAI;YACuB,IAAI;gBAC4B,IAAI,GAA/D,OAAO,GAAC,WAAW,GAAC,YAAY;gBACC,IAAI,GAArC,MAAM;gBAC2B,EAAE,GAAnC,MAAM;gBAC2B,KAAK,GAAtC,MAAM;;;sBAKhB;IArHD;;OAWC;IATG,WAA6B;IAC7B,iBAAoB;IAIpB,WAAyC;IAM7C,2BAaC;IAVW,SAAqC;IA6BjD,uDAcC;IAGD,eAAe;IACf,kBAeC;CA2CJ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chronograph-npm",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "The Chronograph App for Athom's Homey",
   "main": "src/cg.js",
   "types": "./dist/cg.d.ts",

package/src/cg.js

@@ -2,24 +2,10 @@ class CG {
 
 
     static async init({ homey } = {}) {
+        if (CG.Current) CG.destroy();
         let cg = new CG({ homey });
 
-        if (!homey.app.__CG_OnUninit) {
-            homey.app.__CG_OnUninit = homey.app.onUninit;
-            homey.app.onUninit = async function (args) {
-
-                try {
-                    if (CG) await CG.destroy();
-                } catch (error) {
-                    console.log(error);
-                }
-                try {
-                    if (args) await CG.homey.__CG_OnUninit(...args); else await CG.homey.__CG_OnUninit();
-                } catch (error) {
-                    let a = error;
-                }
-            };
-        }
+        homey.once('unload', CG.destroy);
         try {
             await cg.init();
         } catch (error) {
@@ -45,7 +31,7 @@ class CG {
             try {
                 this.api = await this.getAppApi(true);
                 this.api.on('realtime', this.realtimeFunction);
-                await this.api.get('/chronographs')
+                //await this.api.get('/chronographs')
                 if (!CG.isReady && CG._defer) CG._defer.resolve();
             } catch (error) {
                 this.homey.error('CG.init', error);
@@ -57,9 +43,13 @@ class CG {
 
 
 
+    /**
+     * Removes the realtime and unload listeners. Called automatically when Homey emits unload.
+     */
     static destroy() {
         try {
             if (!CG.Current) return;
+            CG.Current.homey.removeListener('unload', CG.destroy);
             if (CG.Current.api) {
                 CG.Current.api.off('realtime', CG.Current.realtimeFunction);
             }
@@ -116,8 +106,26 @@ class CG {
 
 
     /**
-     * @description Setable member, when set, will be activated on any variable update.
-     * @param {Object} param0.variable 
+     * Handles a realtime update from the Chronograph app. Override this method
+     * to receive updated chronograph data.
+     * @param {Object} param0 Update payload.
+     * @param {Object} param0.chronograph Realtime state snapshot, not a Chronograph class instance.
+     * @param {string} [param0.chronograph.id] Generated identifier; omitted from single-event updates.
+     * @param {string} param0.chronograph.name Configured chronograph name.
+     * @param {number} param0.chronograph.duration Elapsed duration in milliseconds, also exposed as elapsed.
+     * @param {number} param0.chronograph.elapsed Elapsed duration in milliseconds.
+     * @param {number|null} param0.chronograph.targetDuration Target duration in milliseconds.
+     * Stopwatches have no target (NaN before serialization, normally null over the API).
+     * @param {number|null} param0.chronograph.remaining Target duration minus elapsed duration, in milliseconds.
+     * Not meaningful for stopwatches; may be NaN or null after serialization.
+     * @param {boolean} param0.chronograph.running Whether the chronograph is running.
+     * @param {boolean} param0.chronograph.removed Whether this update reports removal of the chronograph.
+     * @param {Date} param0.chronograph.now Snapshot timestamp, converted to a Date by this package.
+     * @param {Object} param0.chronograph.data Chronograph metadata, excluding flowValues; may be incomplete during creation.
+     * @param {'Timer'|'Stopwatch'|'Transition'} [param0.chronograph.data.type] Chronograph kind.
+     * @param {number} [param0.chronograph.data.from] Transition starting value.
+     * @param {number} [param0.chronograph.data.to] Transition ending value.
+     * @param {number} [param0.chronograph.data.steps] Transition step count, limited by its duration.
      */
     static async onChronographUpdate({ chronograph }) {
         //BL.homey.log('onChronographUpdate: ', chronograph);

package/test/cg.test.js

@@ -0,0 +1,50 @@
+const assert = require('node:assert/strict');
+const { EventEmitter } = require('node:events');
+const { test } = require('node:test');
+const { CG } = require('../src/cg');
+
+function createHomey() {
+    const homey = new EventEmitter();
+    const api = new EventEmitter();
+    homey.api = { getApiApp: () => api };
+    homey.app = { onUninit() {} };
+    homey.error = (...args) => assert.fail(args.join(' '));
+    return { homey, api };
+}
+
+test('unload removes the realtime listener without replacing app lifecycle methods', async (t) => {
+    const { homey, api } = createHomey();
+    const onUninit = homey.app.onUninit;
+    t.after(() => CG.destroy());
+    await CG.init({ homey });
+
+    assert.equal(homey.app.onUninit, onUninit);
+    assert.equal(api.listenerCount('realtime'), 1);
+    assert.equal(homey.listenerCount('unload'), 1);
+
+    homey.emit('unload');
+
+    assert.equal(api.listenerCount('realtime'), 0);
+    assert.equal(homey.listenerCount('unload'), 0);
+});
+
+test('reinitialization and manual cleanup do not leave listeners behind', async (t) => {
+    const first = createHomey();
+    const second = createHomey();
+    t.after(() => CG.destroy());
+    await CG.init({ homey: first.homey });
+    await CG.init({ homey: second.homey });
+
+    assert.equal(first.api.listenerCount('realtime'), 0);
+    assert.equal(first.homey.listenerCount('unload'), 0);
+    assert.equal(second.api.listenerCount('realtime'), 1);
+    assert.equal(second.homey.listenerCount('unload'), 1);
+
+    first.homey.emit('unload');
+    assert.equal(second.api.listenerCount('realtime'), 1);
+
+    CG.destroy();
+    CG.destroy();
+    assert.equal(second.api.listenerCount('realtime'), 0);
+    assert.equal(second.homey.listenerCount('unload'), 0);
+});