amaran-light-cli 1.0.2

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 S. Zachariah Sprackett <zac@sprackett.com>
+Copyright (c) 2025 Mahyar McDonald <github@hmmfn.com>
+
+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,374 @@
+# Amaran Light CLI
+
+A command line tool for controlling Aputure Amaran lights via WebSocket connection to the Amaran Desktop application.  Not an offical Amaran command line tool.
+
+Also has a circadian lighting command called `auto-cct` that will set the CCT & intensity according to the time of day it is currently at your location, and a service that will run the command every minute to automate it.
+
+Written with AI mostly, including this documentation.  Thanks to [Zac for his core websocket gist that enabled this](https://gist.github.com/zsprackett/29334b9be1e2bd90c1737bd0ba0eaf5c).
+
+## Installation
+
+1. Clone this repository or download the files
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+3. Build the project:
+   ```bash
+   npm run build
+   ```
+4. Optionally, install globally:
+   ```bash
+   npm install -g .
+   ```
+
+## Prerequisites
+
+- Aputure Amaran Desktop application must be running
+- WebSocket server should be accessible (default: ws://localhost:60124)
+
+## Configuration
+
+Configure the WebSocket URL and other settings:
+
+```bash
+# Set WebSocket URL
+amaran-cli config -u ws://localhost:60124
+
+# Set client ID
+amaran-cli config -c my-cli-client
+
+# Enable debug mode
+amaran-cli config -d
+
+# Set default location for auto-cct (overrides geoip)
+amaran-cli config --lat 40.7128 --lon -74.0060
+
+# Show current configuration
+amaran-cli config --show
+```
+
+Configuration is stored in `~/.amaran-cli.json`.
+
+## Discovery
+
+The CLI can automatically discover the WebSocket endpoint from a running Amaran Desktop application:
+
+```bash
+# Discover and save WebSocket URL
+amaran-cli discover
+
+# Discover with debug output
+amaran-cli discover -d
+```
+
+This command uses `lsof` to find the WebSocket port that the Amaran Desktop application is listening on, then saves it to your configuration file for future use.
+
+## Usage
+
+### List all available lights
+```bash
+amaran-cli list
+# or
+amaran-cli ls
+```
+
+### Control lights
+```bash
+# Turn light on
+amaran-cli on "Light Name"
+amaran-cli on node_id_123
+
+# Turn on ALL lights
+amaran-cli on
+
+# Turn light off  
+amaran-cli off "Light Name"
+
+# Turn off ALL lights
+amaran-cli off
+
+# Toggle light on/off
+amaran-cli toggle "Light Name"
+
+# Toggle ALL lights
+amaran-cli toggle
+```
+
+### Set light properties
+```bash
+# Set intensity (0-100%)
+amaran-cli intensity 75 "Light Name"
+
+# Set intensity for ALL lights
+amaran-cli intensity 75
+
+# Set color temperature (2000-6500K)
+amaran-cli cct 5600 "Light Name"
+
+# Set CCT for ALL lights
+amaran-cli cct 5600
+
+# Set color temperature with intensity
+amaran-cli cct 3200 "Light Name" -i 80
+
+# Set CCT with intensity for ALL lights
+amaran-cli cct 3200 -i 80
+
+# Set HSI color
+amaran-cli hsi 240 100 75 "Light Name"  # Blue at full saturation, 75% intensity
+
+# Set HSI for ALL lights
+amaran-cli hsi 240 100 75
+
+# Set color by name or hex
+amaran-cli color red "Light Name"
+amaran-cli color "#ff0000" "Light Name"
+amaran-cli color blue "Light Name" -i 50
+
+# Set color for ALL lights
+amaran-cli color red
+amaran-cli color "#ff0000"
+amaran-cli color blue -i 50
+```
+
+**Note:** For all commands that support device names, you can omit the device name or use `all` to apply the command to all lights. Commands are throttled with 250ms delay between each device to prevent overwhelming the server.
+
+### Auto CCT (Circadian Lighting)
+```bash
+# Set CCT for all lights based on current time and location (auto-detected via geoip)
+amaran-cli auto-cct
+
+# Override IP address for geolocation lookup
+amaran-cli auto-cct --ip 8.8.8.8
+
+# Manual latitude and longitude
+amaran-cli auto-cct --lat 40.7128 --lon -74.0060
+
+# Manual time (ISO 8601 format)
+amaran-cli auto-cct --time 2025-10-26T14:30:00
+
+# Combine manual location and time
+amaran-cli auto-cct --lat 40.7128 --lon -74.0060 --time 2025-10-26T06:00:00
+
+# Use with debug mode to see calculated values
+amaran-cli auto-cct -d
+```
+
+The `auto-cct` command automatically adjusts color temperature based on sunrise/sunset times for your location. By default, it maps the circadian curve to:
+- **Before sunrise / After sunset**: 2000K at 5% intensity (warm, dim night lighting)
+- **Solar noon**: 6500K at 100% intensity (cool, bright daylight)
+- **Between sunrise and sunset**: Smooth bell curve transition from 2000K/5% → 6500K/100% → 2000K/5%
+
+This mimics natural daylight changes throughout the day for more comfortable, circadian-friendly lighting. Both color temperature and brightness follow the same curve, providing natural dimming at dawn/dusk.
+
+**Location Priority:**
+1. Command-line `--lat` and `--lon` arguments (highest priority)
+2. Config file defaults (set with `amaran-cli config --lat <lat> --lon <lon>`)
+3. GeoIP lookup based on public IP address (fallback)
+
+**Bounds (optional):**
+You can constrain the auto-cct curve to your preferred ranges via config:
+
+```bash
+# CCT bounds in Kelvin (defaults 2000–6500)
+amaran-cli config --cct-min 2500 --cct-max 6000
+
+# Intensity bounds in percent (defaults 5–100)
+amaran-cli config --intensity-min 10 --intensity-max 80
+
+# Show the saved configuration
+amaran-cli config --show
+```
+If a bound is not set, the default is used. When both min and max are set, min must be <= max.
+
+### Running Auto-CCT as a Circadian Lighting Service
+
+You can set up auto-cct to run automatically every minute as a circadian lighting background service. The service works with both global and local installations:
+
+```bash
+# For global installation (recommended for production use)
+npm install -g .
+
+# Install and start the circadian lighting service (runs every 60 seconds by default)
+amaran-cli circadian-service install
+
+# Install with custom interval (minimum 10 seconds)
+amaran-cli circadian-service install --interval 120
+
+# Check service status
+amaran-cli circadian-service status
+
+# View logs
+amaran-cli circadian-service logs
+
+# Follow logs in real-time
+amaran-cli circadian-service logs -f
+
+# View error logs
+amaran-cli circadian-service logs -e
+
+# Stop the service temporarily
+amaran-cli circadian-service stop
+
+# Start the service
+amaran-cli circadian-service start
+
+# Uninstall the service completely
+amaran-cli circadian-service uninstall
+```
+
+**Backward Compatibility:**
+The `service` command is still available as an alias to `circadian-service`:
+```bash
+# These commands work the same way
+amaran-cli service install
+amaran-cli circadian-service install
+```
+
+**Installation Detection:**
+- The service automatically detects if amaran-cli is installed globally (via `npm install -g`) or running from a local development build
+- Global installations run the executable directly for better performance
+- Local development builds use Node.js to run the built JavaScript files
+
+The service uses macOS launchd and will automatically start on login. Logs are stored in `~/Library/Logs/amaran-circadian-service.log`.
+
+**Alternative: Using Cron**
+
+If you prefer using cron instead of launchd, the included script handles both global and local installations:
+
+```bash
+# Make the script executable
+chmod +x scripts/run-auto-cct.sh
+
+# Add to crontab (runs every minute)
+crontab -e
+# Add this line:
+# * * * * * /absolute/path/to/amaran-cli/scripts/run-auto-cct.sh
+
+# View logs
+tail -f ~/.amaran-circadian-service.log
+```
+
+**Manual launchd Setup:**
+
+For advanced users who want to create the service manually:
+
+```bash
+chmod +x scripts/create-launchd-service.sh
+./scripts/create-launchd-service.sh
+```
+
+### Preview Auto-CCT Schedule
+
+View how color temperature and intensity will change throughout the day:
+
+```bash
+# Preview schedule for today at your current location
+amaran-cli schedule
+
+# Preview with manual location
+amaran-cli schedule --lat 40.7128 --lon -74.0060
+
+# Preview for a specific date
+amaran-cli schedule --date 2025-12-21
+
+# Change time interval (default: 30 minutes)
+amaran-cli schedule --interval 15
+
+# Combine options
+amaran-cli schedule --lat 51.5074 --lon -0.1278 --date 2025-06-21 --interval 60
+```
+
+The schedule shows CCT and intensity values from 30 minutes before sunrise to 30 minutes after sunset, with special highlighting for:
+- **Sunrise** (yellow)
+- **Solar Noon** (green, bold)
+- **Sunset** (magenta)
+
+This helps you visualize and plan your automated lighting schedule before implementing it.
+
+Note: The schedule respects any configured bounds set via `amaran-cli config --cct-min/--cct-max` and `--intensity-min/--intensity-max`. If no bounds are set, it uses the default curve from `calculateCCT`.
+
+### Get light status
+```bash
+amaran-cli status "Light Name"
+```
+
+### Global options
+All commands support these options:
+- `-u, --url <url>`: Override WebSocket URL
+- `-c, --client-id <id>`: Override client ID  
+- `-d, --debug`: Enable debug mode
+
+Example:
+```bash
+amaran-cli list -u ws://192.168.1.100:60124 -d
+```
+
+## Examples
+
+```bash
+# Configure for remote Amaran Desktop
+amaran-cli config -u ws://192.168.1.100:60124
+
+# List all lights
+amaran-cli list
+
+# Turn on all lights
+amaran-cli on
+
+# Turn on the main key light
+amaran-cli on "Key Light"
+
+# Set all lights to 5600K at 80% intensity
+amaran-cli cct 5600 -i 80
+
+# Set key light to 5600K at 80% intensity
+amaran-cli cct 5600 "Key Light" -i 80
+
+# Set all lights to warm white at 60%
+amaran-cli cct 3200 -i 60
+
+# Set background light to blue at 40%
+amaran-cli color blue "Background" -i 40
+
+# Set all lights to 50% intensity
+amaran-cli intensity 50
+
+# Check status of key light
+amaran-cli status "Key Light"
+
+# Turn off all lights
+amaran-cli off
+```
+
+## Development
+
+```bash
+# Run in development mode
+npm run dev
+
+# Build the project
+npm run build
+
+# Clean build artifacts
+npm run clean
+```
+
+## Device Identification
+
+Devices can be identified by:
+- **Device name**: Case-insensitive partial matching (e.g., "key" matches "Key Light")
+- **Node ID**: Exact match of the device's node_id
+
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Credits
+
+- Original WebSocket control implementation by S. Zachariah Sprackett
+- CLI, auto-CCT, and additional features by Mahyar McDonald
+- Built for use with Aputure Amaran lights and the Amaran Desktop application. This is not an official Amaran app and is not built by them. This was built as a quick hobby utility.
+

package/dist/__tests__/autoCct.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=autoCct.test.d.ts.map

package/dist/__tests__/autoCct.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoCct.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/autoCct.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/autoCct.test.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const commander_1 = require("commander");
+const commands_1 = __importDefault(require("../commands"));
+globals_1.jest.mock('../geoipUtil', () => ({
+    getLocationFromIP: globals_1.jest.fn(() => ({ ll: [37.7749, -122.4194] })),
+}));
+globals_1.jest.mock('../cctUtil', () => ({
+    calculateCCT: globals_1.jest.fn(() => ({ cct: 5600, intensity: 500 })),
+}));
+describe('auto-cct command', () => {
+    const originalFetch = global.fetch;
+    const mockFetch = globals_1.jest.fn();
+    beforeAll(() => {
+        mockFetch.mockImplementation(async () => ({
+            json: async () => ({ ip: '1.2.3.4' }),
+        }));
+        global.fetch = mockFetch;
+    });
+    afterEach(() => {
+        mockFetch.mockClear();
+    });
+    afterAll(() => {
+        global.fetch = originalFetch;
+    });
+    test('skips sleeping lights when running auto-cct', async () => {
+        const setCCT = globals_1.jest.fn();
+        const disconnect = globals_1.jest.fn(async () => Promise.resolve());
+        const sleepState = {
+            '400J5-F2C008': false,
+            '400J5-F2C009': true,
+        };
+        const controllerStub = {
+            getDevices: globals_1.jest.fn(() => [
+                { node_id: '400J5-F2C008', device_name: 'On Light' },
+                { node_id: '400J5-F2C009', device_name: 'Off Light' },
+            ]),
+            getLightSleepStatus: globals_1.jest.fn((nodeId, cb) => {
+                setImmediate(() => cb(true, 'ok', { sleep: sleepState[nodeId] }));
+            }),
+            setCCT,
+            disconnect,
+        };
+        const deps = {
+            createController: async () => controllerStub,
+            findDevice: (_controller, _deviceQuery) => null,
+            asyncCommand: (fn) => (...args) => fn(...args),
+            loadConfig: () => ({}),
+            saveWsUrl: undefined,
+        };
+        const program = new commander_1.Command();
+        program.exitOverride();
+        (0, commands_1.default)(program, deps);
+        await program.parseAsync(['node', 'test', 'auto-cct']);
+        expect(setCCT).toHaveBeenCalledTimes(1);
+        // auto-cct should pass through calculateCCT result
+        expect(setCCT).toHaveBeenCalledWith('400J5-F2C008', 5600, 500);
+        expect(disconnect).toHaveBeenCalledTimes(1);
+    });
+});
+//# sourceMappingURL=autoCct.test.js.map

package/dist/__tests__/autoCct.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoCct.test.js","sourceRoot":"","sources":["../../src/__tests__/autoCct.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/cctUtil.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cctUtil.test.d.ts.map

package/dist/__tests__/cctUtil.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cctUtil.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/cctUtil.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/cctUtil.test.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const suncalc_1 = require("suncalc");
+const cctUtil_1 = require("../cctUtil");
+describe('calculateCCT', () => {
+    const NYC_LAT = 40.7128;
+    const NYC_LON = -74.006;
+    describe('NYC circadian lighting tests', () => {
+        let testDate;
+        let sunrise;
+        let sunset;
+        let solarNoon;
+        const MIN_INTENSITY_PCT = 5;
+        const MAX_INTENSITY_PCT = 100;
+        const MIN_CCT = 2000;
+        const MAX_CCT = 6500;
+        const MIN_INTENSITY_API = MIN_INTENSITY_PCT * 10; // API format (50)
+        const MAX_INTENSITY_API = MAX_INTENSITY_PCT * 10; // API format (1000)
+        beforeAll(() => {
+            // Use a fixed date for consistent test results
+            testDate = new Date('2024-06-21T12:00:00Z'); // Summer solstice
+            const times = (0, suncalc_1.getTimes)(testDate, NYC_LAT, NYC_LON);
+            sunrise = times.sunrise;
+            sunset = times.sunset;
+            solarNoon = times.solarNoon;
+        });
+        it('should return minimum CCT and intensity before sunrise', () => {
+            const beforeSunrise = new Date(sunrise.getTime() - 60000); // 1 minute before
+            const result = (0, cctUtil_1.calculateCCT)(NYC_LAT, NYC_LON, beforeSunrise, {
+                intensityMinPct: MIN_INTENSITY_PCT,
+                intensityMaxPct: MAX_INTENSITY_PCT,
+                cctMinK: MIN_CCT,
+                cctMaxK: MAX_CCT,
+            });
+            expect(result.cct).toBe(MIN_CCT);
+            expect(result.intensity).toBe(MIN_INTENSITY_API);
+        });
+        it('should return minimum CCT and intensity at sunrise edge', () => {
+            const atSunrise = new Date(sunrise.getTime());
+            const result = (0, cctUtil_1.calculateCCT)(NYC_LAT, NYC_LON, atSunrise, {
+                intensityMinPct: MIN_INTENSITY_PCT,
+                intensityMaxPct: MAX_INTENSITY_PCT,
+                cctMinK: MIN_CCT,
+                cctMaxK: MAX_CCT,
+            });
+            // At the exact sunrise moment, should be at minimum
+            expect(result.cct).toBe(MIN_CCT);
+            expect(result.intensity).toBe(MIN_INTENSITY_API);
+        });
+        it('should return maximum CCT and intensity at solar noon', () => {
+            const atNoon = new Date(solarNoon.getTime());
+            const result = (0, cctUtil_1.calculateCCT)(NYC_LAT, NYC_LON, atNoon, {
+                intensityMinPct: MIN_INTENSITY_PCT,
+                intensityMaxPct: MAX_INTENSITY_PCT,
+                cctMinK: MIN_CCT,
+                cctMaxK: MAX_CCT,
+            });
+            // At solar noon (middle of the day), should be at maximum
+            expect(result.cct).toBe(MAX_CCT);
+            expect(result.intensity).toBe(MAX_INTENSITY_API);
+        });
+        it('should return minimum CCT and intensity at sunset edge', () => {
+            const atSunset = new Date(sunset.getTime());
+            const result = (0, cctUtil_1.calculateCCT)(NYC_LAT, NYC_LON, atSunset, {
+                intensityMinPct: MIN_INTENSITY_PCT,
+                intensityMaxPct: MAX_INTENSITY_PCT,
+                cctMinK: MIN_CCT,
+                cctMaxK: MAX_CCT,
+            });
+            // At the exact sunset moment, should be at minimum
+            expect(result.cct).toBe(MIN_CCT);
+            expect(result.intensity).toBe(MIN_INTENSITY_API);
+        });
+        it('should return minimum CCT and intensity after sunset', () => {
+            const afterSunset = new Date(sunset.getTime() + 60000); // 1 minute after
+            const result = (0, cctUtil_1.calculateCCT)(NYC_LAT, NYC_LON, afterSunset, {
+                intensityMinPct: MIN_INTENSITY_PCT,
+                intensityMaxPct: MAX_INTENSITY_PCT,
+                cctMinK: MIN_CCT,
+                cctMaxK: MAX_CCT,
+            });
+            expect(result.cct).toBe(MIN_CCT);
+            expect(result.intensity).toBe(MIN_INTENSITY_API);
+        });
+        it('should have smooth progression from sunrise to noon', () => {
+            const quarterWay = new Date(sunrise.getTime() + (solarNoon.getTime() - sunrise.getTime()) / 4);
+            const result = (0, cctUtil_1.calculateCCT)(NYC_LAT, NYC_LON, quarterWay, {
+                intensityMinPct: MIN_INTENSITY_PCT,
+                intensityMaxPct: MAX_INTENSITY_PCT,
+                cctMinK: MIN_CCT,
+                cctMaxK: MAX_CCT,
+            });
+            // Should be between minimum and maximum values
+            expect(result.cct).toBeGreaterThan(MIN_CCT);
+            expect(result.cct).toBeLessThan(MAX_CCT);
+            expect(result.intensity).toBeGreaterThan(MIN_INTENSITY_API);
+            expect(result.intensity).toBeLessThan(MAX_INTENSITY_API);
+        });
+        it('should have smooth progression from noon to sunset', () => {
+            const threeQuartersWay = new Date(solarNoon.getTime() + (sunset.getTime() - solarNoon.getTime()) / 2);
+            const result = (0, cctUtil_1.calculateCCT)(NYC_LAT, NYC_LON, threeQuartersWay, {
+                intensityMinPct: MIN_INTENSITY_PCT,
+                intensityMaxPct: MAX_INTENSITY_PCT,
+                cctMinK: MIN_CCT,
+                cctMaxK: MAX_CCT,
+            });
+            // Should be between minimum and maximum values
+            expect(result.cct).toBeGreaterThan(MIN_CCT);
+            expect(result.cct).toBeLessThan(MAX_CCT);
+            expect(result.intensity).toBeGreaterThan(MIN_INTENSITY_API);
+            expect(result.intensity).toBeLessThan(MAX_INTENSITY_API);
+        });
+    });
+    describe('Edge cases', () => {
+        it('should handle midnight times', () => {
+            const midnight = new Date('2024-06-21T04:00:00Z'); // Midnight in NYC
+            const result = (0, cctUtil_1.calculateCCT)(NYC_LAT, NYC_LON, midnight);
+            expect(result.cct).toBe(2000);
+            expect(result.intensity).toBe(50); // 5% with default
+        });
+        it('should return valid results for different locations', () => {
+            const LONDON_LAT = 51.5074;
+            const LONDON_LON = -0.1278;
+            const testDate = new Date('2024-06-21T12:00:00Z');
+            const result = (0, cctUtil_1.calculateCCT)(LONDON_LAT, LONDON_LON, testDate);
+            expect(result.cct).toBeGreaterThanOrEqual(2000);
+            expect(result.cct).toBeLessThanOrEqual(6500);
+            expect(result.intensity).toBeGreaterThanOrEqual(50); // 5% minimum
+            expect(result.intensity).toBeLessThanOrEqual(1000);
+        });
+        it('should use default date if not provided', () => {
+            const result = (0, cctUtil_1.calculateCCT)(NYC_LAT, NYC_LON);
+            expect(result.cct).toBeGreaterThanOrEqual(2000);
+            expect(result.cct).toBeLessThanOrEqual(6500);
+            expect(result.intensity).toBeGreaterThanOrEqual(50); // 5% minimum
+            expect(result.intensity).toBeLessThanOrEqual(1000);
+        });
+    });
+    describe('Return value format', () => {
+        it('should return rounded integer values', () => {
+            const testDate = new Date('2024-06-21T12:00:00Z');
+            const result = (0, cctUtil_1.calculateCCT)(NYC_LAT, NYC_LON, testDate);
+            expect(Number.isInteger(result.cct)).toBe(true);
+            expect(Number.isInteger(result.intensity)).toBe(true);
+        });
+        it('should have correct properties', () => {
+            const testDate = new Date('2024-06-21T12:00:00Z');
+            const result = (0, cctUtil_1.calculateCCT)(NYC_LAT, NYC_LON, testDate);
+            expect(result).toHaveProperty('cct');
+            expect(result).toHaveProperty('intensity');
+            expect(typeof result.cct).toBe('number');
+            expect(typeof result.intensity).toBe('number');
+        });
+    });
+    describe('Intensity ranges', () => {
+        const NYC_LAT = 40.7128;
+        const NYC_LON = -74.006;
+        it('intensity stays within [50, 1000] across a whole day (hourly samples)', () => {
+            const base = new Date('2024-06-21T00:00:00Z'); // summer solstice
+            for (let hour = 0; hour < 24; hour++) {
+                const sample = new Date(base.getTime() + hour * 60 * 60 * 1000);
+                const { intensity } = (0, cctUtil_1.calculateCCT)(NYC_LAT, NYC_LON, sample);
+                expect(intensity).toBeGreaterThanOrEqual(50); // 5% minimum
+                expect(intensity).toBeLessThanOrEqual(1000);
+            }
+        });
+        it('intensity stays within range across seasons and locations (spot samples)', () => {
+            const cases = [
+                // Dates: solstices and equinoxes
+                '2024-03-20T00:00:00Z', // vernal equinox
+                '2024-06-21T00:00:00Z', // summer solstice
+                '2024-09-22T00:00:00Z', // autumnal equinox
+                '2024-12-21T00:00:00Z', // winter solstice
+            ];
+            const locations = [
+                { name: 'NYC', lat: 40.7128, lon: -74.006 },
+                { name: 'London', lat: 51.5074, lon: -0.1278 },
+                { name: 'Sydney', lat: -33.8688, lon: 151.2093 },
+            ];
+            const offsetsHours = [0, 6, 12, 18]; // midnight, morning, noon, evening (UTC)
+            for (const iso of cases) {
+                const base = new Date(iso);
+                for (const { lat, lon } of locations) {
+                    for (const h of offsetsHours) {
+                        const d = new Date(base.getTime() + h * 60 * 60 * 1000);
+                        const { intensity } = (0, cctUtil_1.calculateCCT)(lat, lon, d);
+                        expect(intensity).toBeGreaterThanOrEqual(50); // 5% minimum
+                        expect(intensity).toBeLessThanOrEqual(1000);
+                    }
+                }
+            }
+        });
+    });
+});
+//# sourceMappingURL=cctUtil.test.js.map