node-red-contrib-senec-cloud-v2 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-07-05
+
+### Fixed
+- **Authentication failed / 404 errors**: Replaced placeholder API endpoints
+  with the real SENEC Cloud App API
+- Implemented OAuth2 Authorization Code + PKCE login flow against the SENEC
+  Keycloak SSO (`sso.senec.com`), emulating the official SENEC app
+- Token refresh now uses the OAuth2 `refresh_token` grant (access tokens
+  are only valid ~5 minutes; refresh tokens ~30 days)
+
+### Changed
+- Data retrieval now uses `app-gateway.prod.senec.dev`:
+  - `GET /v1/senec/anlagen` to discover the system ID
+  - `GET /v2/senec/systems/{id}/dashboard` for energy data
+- DataParser maps the v2 dashboard response (`currently`/`today` with
+  `powerGenerationInW`, `gridDrawInWh`, etc.) to the backward compatible
+  payload structure; today values converted from Wh to kWh
+
+## [Unreleased]
+
+### Added
+- Initial project structure
+- TypeScript configuration
+- Core library components:
+  - AuthenticationManager for SENEC Cloud authentication
+  - SenecAPIClient for data retrieval
+  - DataParser for response parsing
+  - ErrorHandler for error classification and retry logic
+- Comprehensive architecture documentation
+- Feature definitions following AGENTS.md structure
+- Implementation plan and technical requirements
+
+### TODO
+- Implement Node-RED nodes (senec-config, senec-data, senec-image)
+- Research actual SENEC Cloud API endpoints
+- Add unit and integration tests
+- Create example flows
+- Test on CCU RedMatic hardware
+- Complete image generation functionality
+- Publish to npm
+
+## [0.1.0] - TBD
+
+### Added
+- Initial pre-release version
+- Basic SENEC Cloud API integration
+- Configuration and data nodes
+- Backward compatible payload structure
+
+## Future Releases
+
+### [1.0.0] - Target Release
+- Full SENEC Cloud API integration
+- Complete Node-RED node implementation
+- Image generation for TRMNL
+- CCU RedMatic optimization
+- Comprehensive documentation
+- npm package publication
+
+### [1.1.0] - Planned
+- Additional layout templates
+- Custom template support
+- Enhanced error reporting
+- Performance improvements
+
+### [2.0.0] - Future
+- Historical data support
+- Multi-device support
+- Advanced visualization options
+- WebAPI wrapper (optional)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SENEC Node-RED Integration Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,279 @@
+# node-red-contrib-senec-cloud-v2
+
+Node-RED nodes for SENEC Cloud API integration - supports the new SENEC Cloud API (2025+), optimized for CCU RedMatic.
+
+## Features
+
+- ✅ **SENEC Cloud API Integration** - Works with the new SENEC Cloud API (August 2025+)
+- ✅ **Backward Compatible** - Drop-in replacement for existing flows
+- ✅ **CCU RedMatic Optimized** - Low resource usage, tested on CCU hardware
+- ✅ **Automatic Error Recovery** - Exponential backoff retry logic
+- ✅ **Image Generation** - Create PNG images for TRMNL e-ink displays
+- ✅ **Secure** - Credentials encrypted using Node-RED's credential system
+
+## Installation
+
+### Via Node-RED Palette Manager (Recommended)
+
+1. Open Node-RED editor
+2. Click menu (☰) → Manage palette
+3. Go to "Install" tab
+4. Search for `senec-cloud-v2`
+5. Click "Install"
+
+### Via npm
+
+```bash
+cd ~/.node-red
+npm install node-red-contrib-senec-cloud-v2
+node-red-restart
+```
+
+### On CCU RedMatic
+
+1. Open CCU WebUI
+2. Navigate to RedMatic add-on
+3. Open Node-RED editor
+4. Use Palette Manager as described above
+
+## Quick Start
+
+### 1. Add Configuration Node
+
+1. Drag a `senec-data` node into your flow
+2. Double-click to edit
+3. Click the pencil icon next to "SENEC Config"
+4. Enter your SENEC Cloud credentials:
+   - **Username**: Your SENEC Cloud username/email
+   - **Password**: Your SENEC Cloud password
+5. Click "Test Connection" to verify
+6. Click "Add" to save
+
+### 2. Configure Data Node
+
+1. Set poll interval (default: 60 seconds, recommended 120s for CCU)
+2. Enable/disable automatic polling
+3. Deploy your flow
+
+### 3. Use the Data
+
+The node outputs energy data in `msg.payload`:
+
+```javascript
+{
+  steuereinheitState: "online",
+  gridimport: { today: 2.5, now: 150 },      // kWh, W
+  powergenerated: { today: 18.5, now: 3200 }, // kWh, W
+  consumption: { today: 12.3, now: 1800 },    // kWh, W
+  gridexport: { today: 8.2, now: 1400 },      // kWh, W
+  acculevel: { now: 85 }                      // %
+}
+```
+
+## Nodes
+
+### senec-config
+
+Configuration node for SENEC Cloud credentials. Shared across multiple data nodes.
+
+**Configuration**:
+- Username (required)
+- Password (required)
+- Test Connection button
+
+### senec-data
+
+Retrieves energy data from SENEC Cloud.
+
+**Configuration**:
+- SENEC Config: Reference to config node
+- Poll Interval: Seconds between automatic updates (default: 60)
+- Enable Polling: Automatic periodic updates
+
+**Input**: Any message triggers immediate data retrieval (independent of polling)
+
+**Output**: `msg.payload` contains SENEC energy data
+
+**Status Indicators**:
+- 🟢 Connected - Successfully connected and retrieving data
+- 🟡 Retrying - Temporary error, retrying automatically
+- 🔴 Error - Persistent error, check credentials or connection
+
+### senec-image
+
+Generates PNG images from SENEC data for displays.
+
+**Configuration**:
+- Template: trmnl, compact, or detailed
+- Width/Height: Image dimensions
+- Output Format: buffer, base64, or file
+- Color Scheme: monochrome (e-ink) or color
+
+**Input**: `msg.payload` with SENEC data
+
+**Output**: PNG image as Buffer, base64 string, or file path
+
+## Examples
+
+### Basic Monitoring
+
+```
+[senec-data] → [debug]
+```
+
+### TRMNL Display
+
+```
+[inject: every 5 min] → [senec-data] → [senec-image: TRMNL] → [http response]
+```
+
+### CCU Homematic Integration
+
+```
+[senec-data] → [function: extract battery] → [ccu-value: battery variable]
+```
+
+### Automation Example
+
+```javascript
+// In a function node after senec-data
+var battery = msg.payload.acculevel.now;
+var solar = msg.payload.powergenerated.now;
+
+if (battery > 80 && solar > 2000) {
+    // Excess solar available - turn on devices
+    return { payload: true };
+}
+```
+
+## Configuration Tips
+
+### For CCU RedMatic
+
+- Use poll interval of 120 seconds (2 minutes) to reduce resource usage
+- Monitor memory usage in CCU WebUI
+- Disable polling if only triggered retrieval needed
+
+### For Raspberry Pi / Standard Node-RED
+
+- Default 60 second interval works well
+- Can use shorter intervals if needed (minimum 10 seconds)
+
+### For TRMNL Displays
+
+- Use `senec-image` node with TRMNL template
+- Set dimensions to 800x480 (or your display size)
+- Use monochrome color scheme for e-ink
+- Serve via HTTP endpoint for TRMNL to fetch
+
+## Troubleshooting
+
+### Authentication Failed
+
+- Verify credentials in config node
+- Check SENEC Cloud account is active
+- Try logging in to SENEC web portal to confirm credentials
+
+### Connection Timeout
+
+- Check internet connectivity
+- Verify firewall allows HTTPS outbound
+- SENEC Cloud may be temporarily unavailable (automatic retry)
+
+### Rate Limited
+
+- Reduce poll frequency
+- Default backoff will handle this automatically
+- Check for multiple flows polling the same account
+
+### High Memory Usage on CCU
+
+- Increase poll interval to 120-300 seconds
+- Disable polling, use triggered retrieval only
+- Check for other resource-intensive flows
+
+## API Changes
+
+This package supports the **new SENEC Cloud API** (August 2025+). The old API is no longer supported by SENEC.
+
+**Migration from old package**:
+- Payload structure is identical - existing flows work without changes
+- Simply replace old nodes with new ones
+- Update credentials in config node
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/aunovis-fitting/node-red-contrib-senec-cloud-v2.git
+cd node-red-contrib-senec-cloud-v2
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Test
+
+```bash
+npm test
+npm run test:coverage
+```
+
+### Local Testing in Node-RED
+
+```bash
+npm run build
+npm link
+cd ~/.node-red
+npm link node-red-contrib-senec-cloud-v2
+node-red-restart
+```
+
+## Architecture
+
+See [`docs/00-ARCHITECTURE_SUMMARY.md`](docs/00-ARCHITECTURE_SUMMARY.md) for complete architecture documentation.
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/yourusername/node-red-contrib-senec-cloud-v2/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/yourusername/node-red-contrib-senec-cloud-v2/discussions)
+- **Node-RED Forum**: [Node-RED Community](https://discourse.nodered.org/)
+- **HomeMatic Forum**: [HomeMatic-Forum.de](https://homematic-forum.de/) (German)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file
+
+## Acknowledgments
+
+- SENEC for their solar energy storage systems
+- Node-RED community
+- CCU RedMatic project
+- Original senec-cloud package contributors
+
+## Disclaimer
+
+This is an unofficial integration. Not affiliated with or endorsed by SENEC GmbH.
+
+---
+
+**Status**: 🚧 In Development
+
+**Current Version**: 0.1.0 (Pre-release)
+
+**Target Release**: v1.0.0

package/dist/lib/auth-manager.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Authentication Manager
+ *
+ * Handles SENEC Cloud authentication, token management, and refresh logic.
+ *
+ * Since the SENEC API change (August 2025), authentication uses the
+ * SENEC Keycloak SSO with the OAuth2 Authorization Code + PKCE flow,
+ * emulating the official SENEC app:
+ *
+ *   1. GET  /auth  (login page, collects session cookies)
+ *   2. POST username to the login form
+ *   3. POST password to the second-step form
+ *   4. Receive redirect to senec-app-auth://keycloak.prod?code=...
+ *   5. Exchange authorization code for access + refresh tokens
+ *
+ * Access tokens are short-lived (~5 minutes); refresh tokens last ~30 days.
+ * Token refresh uses the standard OAuth2 refresh_token grant.
+ */
+import { SenecCredentials, AuthToken } from '../types/senec';
+export declare class AuthenticationManager {
+    private credentials;
+    private token;
+    private tokenExpiry;
+    private refreshTokenValue;
+    private refreshTokenExpiry;
+    private httpClient;
+    constructor(credentials: SenecCredentials);
+    /**
+     * Authenticate with SENEC Cloud (OAuth2 Authorization Code + PKCE)
+     */
+    authenticate(): Promise<AuthToken>;
+    /**
+     * Refresh the authentication token using the OAuth2 refresh_token grant.
+     * Falls back to a full re-authentication if no valid refresh token exists
+     * or the refresh fails.
+     */
+    refreshToken(): Promise<AuthToken>;
+    /**
+     * Check if the current token is valid
+     */
+    isTokenValid(): boolean;
+    /**
+     * Whether a (probably valid) refresh token is available
+     */
+    canRefresh(): boolean;
+    /**
+     * Get the current token
+     */
+    getToken(): string | null;
+    /**
+     * Clear the stored tokens
+     */
+    clearToken(): void;
+    /**
+     * Store tokens from a Keycloak token endpoint response
+     */
+    private storeTokens;
+    /**
+     * Build a user-friendly error description without leaking credentials
+     */
+    private describeError;
+}
+//# sourceMappingURL=auth-manager.d.ts.map

package/dist/lib/auth-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-manager.d.ts","sourceRoot":"","sources":["../../src/lib/auth-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAsB7D,qBAAa,qBAAqB;IAChC,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,iBAAiB,CAAuB;IAChD,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,UAAU,CAAgB;gBAEtB,WAAW,EAAE,gBAAgB;IAOzC;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC;IAwHxC;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC;IAoCxC;;OAEG;IACH,YAAY,IAAI,OAAO;IAWvB;;OAEG;IACH,UAAU,IAAI,OAAO;IAOrB;;OAEG;IACH,QAAQ,IAAI,MAAM,GAAG,IAAI;IAIzB;;OAEG;IACH,UAAU,IAAI,IAAI;IAOlB;;OAEG;IACH,OAAO,CAAC,WAAW;IAYnB;;OAEG;IACH,OAAO,CAAC,aAAa;CAsBtB"}