v2c-any 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tiago Santos
+
+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,230 @@
+![v2a - V2C any](docs/assets/images/v2ca.png)
+
+# v2c-any (v2ca)
+
+> **Turn `{ device: any }` into V2C Dynamic Power Control**
+
+**v2c-any** (binary: `v2ca`) is a universal adapter that allows **any device** — physical meters, MQTT topics, simulators, or proxies — to integrate with **V2C wallboxes** for **Dynamic Power Control**.
+
+If it can expose power data, **v2c-any** can make it speak *V2C*.
+
+## Why v2c-any?
+
+V2C wallboxes support Dynamic Power Control via specific meters or MQTT inputs.  
+In real installations, however, power data often comes from **heterogeneous sources**:
+
+- Different brands of energy meters  
+- Existing MQTT infrastructures  
+- Home Assistant sensors  
+- Custom hardware or software systems  
+- Simulated or virtual meters for testing  
+
+**v2c-any** bridges that gap.
+
+It adapts **any input** into the protocol and format expected by a V2C wallbox — without changing your existing setup.
+
+## The idea
+
+```ts
+{ device: any } → V2C
+```
+
+Or in practical terms:
+
+```
+[Any Meter | MQTT | API | Simulator]
+            │
+            ▼
+         v2c-any
+            │
+            ▼
+       V2C Wallbox
+```
+
+## Key features
+
+- 🔌 **Universal adapter** – works with *any* power data source  
+- 📡 **MQTT support** – publish once, charge dynamically  
+- ⚡ **Dynamic Power Control** – grid, solar, or hybrid scenarios  
+- 🧪 **Simulation mode** – emulate supported meters for testing  
+- 🔁 **Proxy mode** – forward and transform existing devices  
+- 🧩 **Extensible architecture** – add new adapters easily  
+- 🟦 **TypeScript-first** – predictable, typed, maintainable  
+
+## Quick Start
+
+### Installation
+
+```bash
+# Install globally via npm
+npm install -g v2c-any
+
+# Or run directly with npx
+npx v2c-any
+```
+
+### Configuration
+
+`v2ca` uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) to load configuration. Create a configuration file in one of these formats:
+
+- `.v2carc` (JSON or YAML)
+- `.v2carc.json`
+- `.v2carc.yaml` or `.v2carc.yml`
+- `v2ca.config.js` (CommonJS or ESM)
+- `package.json` with a `"v2ca"` key
+
+**Example configuration** (`.v2carc.yaml`):
+
+```yaml
+provider: mqtt
+properties:
+  url: mqtt://localhost:1883
+  device: shelly-pro-em
+  meters:
+    grid:
+      mode: pull
+      feed:
+        type: adapter
+        properties:
+          interval: 5000
+          ip: 192.168.1.100
+    solar:
+      mode: pull
+      feed:
+        type: mock
+        properties:
+          interval: 5000
+          value:
+            power: 2500
+```
+
+### Running
+
+```bash
+# Run with auto-detected configuration
+v2ca
+
+# Run from source (development)
+npm run dev
+
+# Run with Docker
+docker run -v $(pwd)/.v2carc.yaml:/app/.v2carc.yaml v2c-any
+```
+
+## Operating Modes
+
+`v2c-any` supports two primary operating modes depending on how your V2C wallbox is configured:
+
+### REST Mode (Shelly EM1 Emulator)
+
+Emulates a **Shelly Pro EM** energy meter by exposing a REST API that V2C wallboxes can poll.
+
+**Use this when:**
+- Your V2C wallbox is configured to poll a Shelly meter
+- You want to act as a drop-in replacement for physical hardware
+- You prefer a pull-based (polling) approach
+
+**Configuration example:**
+
+```yaml
+provider: rest
+properties:
+  port: 3000
+  device: shelly-pro-em
+  meters:
+    grid:
+      feed:
+        type: adapter
+        properties:
+          ip: 192.168.1.100
+    solar:
+      feed:
+        type: mock
+        properties:
+          value:          
+            id: 1
+            voltage: 230.2
+            current: 3.785
+            act_power: 852.7
+            aprt_power: 873.1
+            pf: 0.98
+            freq: 50
+            calibration: factory
+```
+
+**How it works:**
+1. `v2ca` starts a Fastify HTTP server
+2. Exposes endpoints matching Shelly Pro EM API format
+3. V2C wallbox polls these endpoints (e.g., `/rpc/EM1.GetStatus?id=0`)
+4. Returns real-time power data from your configured sources
+
+### MQTT Mode (Direct Publisher)
+
+Publishes power data directly to MQTT topics that V2C wallboxes subscribe to.
+
+**Use this when:**
+- Your V2C wallbox is configured for MQTT integration
+- You have an existing MQTT broker
+- You want push-based (event-driven) updates
+- You need lower latency or more frequent updates
+
+**Configuration example:**
+
+```yaml
+provider: mqtt
+properties:
+  url: mqtt://broker.local:1883
+  device: shelly-pro-em
+  meters:
+    grid:
+      mode: pull       # v2ca polls your device
+      feed:
+        type: adapter
+        properties:
+          interval: 2000   # Every 2 seconds
+          ip: 192.168.1.100
+    solar:
+      mode: push       # v2ca subscribes to MQTT topic
+      feed:
+        type: bridge
+        properties:
+          url: mqtt://solar-meter.local:1883
+          topic: solar/power
+```
+
+**How it works:**
+1. `v2ca` connects to your MQTT broker
+2. Publishes to V2C-expected topics (e.g., `trydan_v2c_sun_power`)
+3. Supports both **pull** (polling devices) and **push** (subscribing to topics)
+4. V2C wallbox subscribes and receives real-time updates
+
+### Mode Comparison
+
+| Feature         | REST Mode                  | MQTT Mode                   |
+|-----------------|----------------------------|-----------------------------|
+| **Protocol**    | HTTP/REST                  | MQTT                        |
+| **Direction**   | Pull (V2C polls v2ca)      | Push (v2ca publishes)       |
+| **Latency**     | Higher (polling interval)  | Lower (event-driven)        |
+| **Setup**       | Simpler (no broker needed) | Requires MQTT broker        |
+| **Use Case**    | Shelly meter replacement   | MQTT-native setups          |
+| **Scalability** | Limited by polling         | Better for multiple devices |
+
+## What v2c-any is *not*
+
+- ❌ Not a replacement for your existing meters  
+- ❌ Not tied to a single vendor or ecosystem  
+- ❌ Not limited to one communication protocol  
+
+It’s an **adapter**, not a lock-in.
+
+## Name origin
+
+`v2c-any` comes from the TypeScript `any` type:
+
+> “I don’t care what you are — I can work with you.”
+
+Exactly the philosophy behind this project.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

package/dist/adapter/adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/application-context.js

@@ -0,0 +1,31 @@
+import { Registry } from './registry/registry.js';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { globSync } from 'glob';
+import { logger } from './utils/logger.js';
+/**
+ * Registry of device provider factories keyed by device identifier.
+ * Each factory produces an `EM1Status` provider for a specific device.
+ */
+export const devicesProviderRegistry = new Registry();
+/**
+ * Registry of device adapters keyed by device identifier.
+ * Each adapter transforms raw device messages into `EnergyInformation`.
+ */
+export const devicesAdapterRegistry = new Registry();
+/**
+ * Dynamically loads all device modules discovered under devices.
+ * Imports each module to allow self-registration into application registries.
+ *
+ * @returns A promise that resolves when all device modules are loaded
+ */
+export async function loadDeviceModules() {
+    logger.info('Loading device modules...');
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    // Support both .ts (dev/tsx) and .js (built) files
+    const devicePaths = globSync('device/**/index.{ts,js}', { cwd: __dirname });
+    logger.info({ count: devicePaths.length }, 'Found device modules.');
+    for (const path of devicePaths) {
+        await import(`./${path}`);
+    }
+}

package/dist/configuration/configuration-loader.js

@@ -0,0 +1,48 @@
+import { cosmiconfig } from 'cosmiconfig';
+import { logger } from '../utils/logger.js';
+/**
+ * Loads and merges v2ca configuration from various sources (.v2carc, v2ca.config.js, package.json).
+ * Uses cosmiconfig for auto-discovery and merges user config with defaults.
+ */
+export class ConfigurationLoader {
+    /**
+     * Creates a new configuration loader.
+     * @param configurationValidator - Validator to ensure configuration integrity
+     */
+    constructor(configurationValidator) {
+        this.configurationValidator = configurationValidator;
+        // Initialize cosmiconfig explorer once for reuse across multiple loads
+        this.explorer = cosmiconfig('v2ca');
+    }
+    /**
+     * Loads and validates the v2ca configuration.
+     * @returns A promise that resolves to the fully merged and validated configuration
+     * @throws {Error} If configuration loading or validation fails
+     */
+    async load() {
+        try {
+            logger.info('Searching for configuration...');
+            // Search for config in standard locations
+            const result = await this.explorer.search();
+            let config;
+            if (result?.config) {
+                // Configuration found - merge, validate, and use it
+                const configSource = result.filepath ? result.filepath : 'package.json';
+                logger.info({ source: configSource }, 'Configuration loaded');
+                config = this.configurationValidator.validate(result.config);
+            }
+            else {
+                // No configuration found - use defaults
+                logger.info('No configuration found');
+                throw new Error('No configuration found');
+            }
+            logger.info('Configuration loaded successfully');
+            return config;
+        }
+        catch (error) {
+            // Wrap any errors with context for better debugging
+            // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+            throw new Error(`Failed to load configuration: ${error}`);
+        }
+    }
+}

package/dist/configuration/configuration-validator.js

@@ -0,0 +1,24 @@
+import { configurationSchema, } from '../schema/configuration.js';
+/**
+ * Validates v2ca configuration against Zod schema for type safety and correctness.
+ * Ensures all configuration values conform to expected types and constraints,
+ * providing detailed error messages for any validation failures.
+ */
+export class ConfigurationValidator {
+    /**
+     * Validates configuration against the schema and returns the validated result.
+     * @param config - Configuration object to validate
+     * @returns Validated and typed configuration object
+     * @throws {Error} If validation fails, with detailed error information
+     */
+    validate(config) {
+        const result = configurationSchema.safeParse(config);
+        if (!result.success) {
+            const errors = result.error.issues
+                .map((e) => `${e.path.join('.')}:${e.message}`)
+                .join(', ');
+            throw new Error(`Configuration validation failed: ${errors}`);
+        }
+        return result.data;
+    }
+}

package/dist/device/shelly-pro-em/em1-status-provider.js

@@ -0,0 +1,49 @@
+import { request } from 'undici';
+import { logger } from '../../utils/logger.js';
+import { energyTypeToId } from '../../utils/mappers.js';
+/**
+ * Provider that fetches EM1 status data from a Shelly Pro EM device via HTTP.
+ * Retrieves real-time energy monitoring data by querying the device's RPC API endpoint.
+ */
+export class EM1StatusProvider {
+    /**
+     * Creates a new EM1 status provider.
+     * @param host - The IP address or hostname of the Shelly Pro EM device
+     * @param energyType - The type of energy data to retrieve (e.g., active, reactive)
+     */
+    constructor(host, energyType) {
+        this.host = host;
+        this.energyType = energyType;
+    }
+    /**
+     * Fetches the current EM1 status from the device.
+     * @returns A promise that resolves to the EM1 status object containing energy metrics
+     * @throws {Error} If the HTTP request fails or returns invalid data
+     */
+    async get() {
+        logger.debug({ host: this.host, energyType: this.energyType }, 'Fetching EM1Status');
+        const id = energyTypeToId(this.energyType);
+        const res = await request(`http://${this.host}/rpc/EM1.GetStatus?id=${id}`, { method: 'GET' });
+        return (await res.body.json());
+    }
+}
+/**
+ * Factory for creating EM1StatusProvider instances.
+ * Implements the factory pattern to instantiate providers with the appropriate configuration.
+ */
+class EM1StatusProviderFactory {
+    /**
+     * Creates a new EM1StatusProvider instance with the specified configuration.
+     * @param options - Configuration options including target IP and energy type
+     * @returns A configured EM1StatusProvider instance
+     */
+    create(options) {
+        logger.debug({ ip: options.properties.ip, energyType: options.energyType }, 'Creating EM1StatusProvider');
+        return new EM1StatusProvider(options.properties.ip, options.energyType);
+    }
+}
+/**
+ * Singleton factory instance for creating `EM1StatusProvider` objects.
+ * Provides a ready-to-use factory to build providers with supplied options.
+ */
+export const em1StatusProviderFactory = new EM1StatusProviderFactory();

package/dist/device/shelly-pro-em/energy-information-em1-status-adapter.js

@@ -0,0 +1,24 @@
+/**
+ * Adapter that transforms EM1Status data into EnergyInformation format.
+ * Extracts active power metrics from Shelly Pro EM device status and converts them
+ * to a standardized energy information structure.
+ */
+class EnergyInformationEM1StatusAdapter {
+    /**
+     * Adapts EM1 status data to energy information.
+     * Extracts the active power value if available, otherwise returns undefined.
+     * @param input - The EM1Status object containing device status data
+     * @returns A promise that resolves to EnergyInformation with power data, or undefined if power data is unavailable
+     */
+    adapt(input) {
+        if (input.act_power !== undefined) {
+            return Promise.resolve({ power: input.act_power });
+        }
+        return Promise.resolve(undefined);
+    }
+}
+/**
+ * Singleton adapter instance for converting `EM1Status` to `EnergyInformation`.
+ * Use this ready-to-use instance where an adapter object is required.
+ */
+export const energyInformationEM1StatusAdapter = new EnergyInformationEM1StatusAdapter();

package/dist/device/shelly-pro-em/index.js

@@ -0,0 +1,8 @@
+import { devicesAdapterRegistry, devicesProviderRegistry, } from '../../application-context.js';
+import { logger } from '../../utils/logger.js';
+import { energyInformationEM1StatusAdapter } from './energy-information-em1-status-adapter.js';
+import { em1StatusProviderFactory } from './em1-status-provider.js';
+const DEVICE_NAME = 'shelly-pro-em';
+devicesProviderRegistry.register(DEVICE_NAME, em1StatusProviderFactory);
+devicesAdapterRegistry.register(DEVICE_NAME, energyInformationEM1StatusAdapter);
+logger.info('Shelly Pro EM registered');

package/dist/factory/em1-status-provider-factory.js

@@ -0,0 +1,48 @@
+import { FixedValueProviderFactory } from '../provider/fixed-value-provider.js';
+/**
+ * Factory for creating EM1Status providers with flexible data source strategies.
+ * Supports multiple feed types: adapter-based providers, mock values, or disabled providers.
+ */
+export class EM1StatusProviderFactory {
+    /**
+     * Creates a new EM1Status provider factory.
+     * @param devicesProvider - Registry containing provider factories for different devices
+     */
+    constructor(devicesProvider) {
+        this.devicesProvider = devicesProvider;
+    }
+    /**
+     * Creates the appropriate provider factory based on the feed configuration type.
+     * @param options - Configuration options specifying the feed type and properties
+     * @returns A provider factory matching the requested feed type
+     * @throws {Error} If an adapter feed is requested but the device is not registered
+     */
+    createProviderFactory(options) {
+        switch (options.configuration.feed.type) {
+            case 'adapter': {
+                const provider = this.devicesProvider.get(options.device);
+                if (!provider) {
+                    throw new Error(`No provider registered for device: ${options.device}`);
+                }
+                return provider;
+            }
+            case 'mock':
+                return new FixedValueProviderFactory({
+                    value: options.configuration.feed.properties?.value,
+                });
+            case 'off':
+                return new FixedValueProviderFactory({ value: undefined });
+        }
+    }
+    /**
+     * Creates an EM1Status provider with the specified configuration.
+     * @param options - Configuration options including energy type, device, and feed type
+     * @returns A provider that supplies EM1Status or undefined
+     */
+    create(options) {
+        return this.createProviderFactory(options).create({
+            energyType: options.energyType,
+            ...options.configuration.feed,
+        });
+    }
+}

package/dist/factory/executable-service-factory.js

@@ -0,0 +1 @@
+export {};

package/dist/factory/mqtt-feed-executable-service-factory.js

@@ -0,0 +1,68 @@
+/**
+ * Converts numeric callback properties to accept EnergyInformation objects.
+ * Extracts the power value from EnergyInformation and passes it to the underlying callback.
+ *
+ * @param callbackProperties - The callback properties expecting numeric power values
+ * @returns Converted callback properties that accept EnergyInformation
+ */
+function convertCallbackProperties(callbackProperties) {
+    return {
+        callback: async (data) => {
+            if (data?.power !== undefined) {
+                await callbackProperties.callback(data.power);
+            }
+        },
+    };
+}
+/**
+ * Factory for creating MQTT feed executable services with flexible communication modes.
+ * Supports both pull (periodic polling) and push (event-driven) MQTT feed strategies.
+ * Automatically routes to the appropriate service factory based on configuration.
+ */
+export class MqttFeedExecutableServiceFactory {
+    /**
+     * Creates a new MQTT feed executable service factory.
+     * @param pullExecutableServiceFactory - Factory for pull-mode services
+     * @param pushExecutableServiceFactory - Factory for push-mode services
+     */
+    constructor(pullExecutableServiceFactory, pushExecutableServiceFactory) {
+        this.pullExecutableServiceFactory = pullExecutableServiceFactory;
+        this.pushExecutableServiceFactory = pushExecutableServiceFactory;
+    }
+    /**
+     * Creates an executable service using the appropriate mode-specific factory.
+     * Routes to pull or push factory based on the configuration mode.
+     *
+     * @param options - Configuration options including energy type, device, mode, and callbacks
+     * @returns An ExecutableService configured for the specified MQTT feed mode
+     */
+    create(options) {
+        let callbackProperties;
+        switch (options.energyType) {
+            case 'solar': {
+                callbackProperties = convertCallbackProperties(options.callbacks.sun);
+                break;
+            }
+            case 'grid': {
+                callbackProperties = convertCallbackProperties(options.callbacks.grid);
+                break;
+            }
+        }
+        switch (options.configuration.mode) {
+            case 'pull':
+                return this.pullExecutableServiceFactory.create({
+                    energyType: options.energyType,
+                    device: options.device,
+                    configuration: options.configuration.feed,
+                    callbackProperties,
+                });
+            case 'push':
+                return this.pushExecutableServiceFactory.create({
+                    energyType: options.energyType,
+                    device: options.device,
+                    configuration: options.configuration.feed,
+                    callbackProperties,
+                });
+        }
+    }
+}

package/dist/factory/mqtt-pull-executable-service-factory.js

@@ -0,0 +1,73 @@
+import { AdapterProviderFactory } from '../provider/adapter-provider.js';
+import { FixedValueProviderFactory } from '../provider/fixed-value-provider.js';
+import { PullPushService } from '../service/pull-push-service.js';
+import { noOpExecutableService } from '../service/no-op-executable-service.js';
+/**
+ * Factory for creating MQTT pull-mode (polling) executable services.
+ * Supports multiple data source strategies: device adapters, mock values, or disabled sources.
+ * Periodically polls energy data and invokes a callback with the results.
+ */
+export class MqttPullExecutableServiceFactory {
+    /**
+     * Creates a new MQTT pull executable service factory.
+     * @param devicesProviderRegistry - Registry of device providers for adapter-based sources
+     * @param devicesAdapterRegistry - Registry of device adapters for transforming provider output
+     */
+    constructor(devicesProviderRegistry, devicesAdapterRegistry) {
+        this.devicesProviderRegistry = devicesProviderRegistry;
+        this.devicesAdapterRegistry = devicesAdapterRegistry;
+    }
+    /**
+     * Creates the appropriate provider factory based on the feed configuration type.
+     * Combines provider and adapter for adapter-based sources, or returns mock/off providers.
+     *
+     * @param options - Configuration options specifying the feed type and device
+     * @returns A provider factory matching the requested feed type
+     * @throws {Error} If an adapter feed is requested but the device provider or adapter is not registered
+     */
+    createProviderFactory(options) {
+        switch (options.configuration.type) {
+            case 'adapter': {
+                const provider = this.devicesProviderRegistry.get(options.device);
+                if (!provider) {
+                    throw new Error(`No provider registered for device: ${options.device}`);
+                }
+                const adapter = this.devicesAdapterRegistry.get(options.device);
+                if (!adapter) {
+                    throw new Error(`No adapter registered for device: ${options.device}`);
+                }
+                return {
+                    providerFactory: new AdapterProviderFactory(provider, adapter),
+                    interval: options.configuration.properties.interval,
+                };
+            }
+            case 'mock':
+                return {
+                    providerFactory: new FixedValueProviderFactory({
+                        value: options.configuration.properties.value,
+                    }),
+                    interval: options.configuration.properties.interval,
+                };
+            case 'off':
+                return null;
+        }
+    }
+    /**
+     * Creates an executable service that periodically polls energy data.
+     * @param options - Configuration options including device, interval, and callback
+     * @returns A PullPushService configured to poll at the specified interval
+     */
+    create(options) {
+        const energyProviderFactory = this.createProviderFactory(options);
+        if (!energyProviderFactory) {
+            return noOpExecutableService;
+        }
+        const { providerFactory, interval } = energyProviderFactory;
+        const energyProvider = providerFactory.create({
+            energyType: options.energyType,
+            ...options.configuration,
+        });
+        const service = new PullPushService(energyProvider, interval, options.callbackProperties);
+        return service;
+    }
+}

package/dist/factory/mqtt-push-executable-service-factory.js

@@ -0,0 +1,36 @@
+import { noOpExecutableService } from '../service/no-op-executable-service.js';
+import { MqttBridgeService } from '../service/mqtt-bridge-service.js';
+/**
+ * Factory for creating MQTT push-mode (event-driven) executable services.
+ * Supports MQTT bridge (subscribing to device topics) or disabled sources.
+ * Returns a ready-to-run `ExecutableService` instance.
+ */
+export class MqttPushExecutableServiceFactory {
+    /**
+     * Creates a new MQTT push executable service factory.
+     * @param devicesAdapter - Registry of device adapters to transform incoming messages
+     */
+    constructor(devicesAdapter) {
+        this.devicesAdapter = devicesAdapter;
+    }
+    /**
+     * Creates an executable service using the appropriate push strategy.
+     * Returns a bridge service when configured, or a no-op service if disabled.
+     * @param options - Configuration including device, energy type, push config, and callback
+     * @returns An `ExecutableService` configured for the specified MQTT push mode
+     * @throws {Error} If `bridge` is selected but no adapter is registered for the device
+     */
+    create(options) {
+        switch (options.configuration.type) {
+            case 'bridge': {
+                const adapter = this.devicesAdapter.get(options.device);
+                if (!adapter) {
+                    throw new Error(`No adapter registered for device: ${options.device}`);
+                }
+                return new MqttBridgeService(options.configuration.properties, options.callbackProperties, adapter);
+            }
+            case 'off':
+                return noOpExecutableService;
+        }
+    }
+}