Light Engine Charlie - TypeScript Client Example

This example project demonstrates type-safe API interactions with the Light Engine Charlie platform using TypeScript.

Features

✅ Full Type Safety - All API requests and responses are strongly typed
✅ IDE Autocomplete - IntelliSense support for all methods and properties
✅ Compile-Time Validation - Catch errors before runtime
✅ Comprehensive Examples - 11 real-world usage scenarios
✅ Production Ready - Error handling, timeouts, and retries included

Installation

cd examples/typescript-client
npm install

Type Checking

Verify that all types are correct without running the code:

npm run type-check

This will compile TypeScript and check for type errors without emitting any JavaScript files.

Building

Compile TypeScript to JavaScript:

npm run build

Output will be in the dist/ directory.

Running Examples

Development Mode (with ts-node)

npm run dev

Production Mode (compiled JavaScript)

npm run build
npm start

Prerequisites

The Light Engine Charlie backend must be running:

# In the main project directory
python3 -m backend &

The backend should be accessible at http://localhost:8000.

Type Definitions

This example uses the type definitions from src/types/api.ts in the main project:

Core Types

• SensorPayload - Sensor data ingestion format
• LatestReadingsResponse - Latest sensor readings
• DiscoveryDevice - Discovered device metadata
• NetworkTestRequest - Network connectivity test
• DeviceCommandRequest - Device control commands
• AutomationRule - Automation rule definition
• FailsafePowerRequest - Emergency lighting control

Type Guards

• isErrorResponse() - Check if response is an error
• isSuccessResponse() - Check if response is successful

Example Scenarios

The src/examples.ts file demonstrates:

1. Health Check - Verify API availability
2. Sensor Data Ingestion - Type-safe sensor payload
3. Latest Readings - Retrieve current sensor values
4. Device Discovery - Trigger and retrieve device scans
5. Network Testing - Validate connectivity
6. Device Commands - Control devices with type safety
7. Lighting Fixtures - Get fixture metadata
8. Automation Rules - Create and manage rules
9. Rule Management - List and update rules
10. Emergency Failsafe - Immediate power control
11. Type Safety Benefits - Compile-time error prevention

API Client Usage

import { LightEngineClient } from './client';
import type { SensorPayload } from './types';

// Initialize client
const client = new LightEngineClient({
  baseUrl: 'http://localhost:8000',
  timeout: 10000,
  apiKey: 'optional-jwt-token'
});

// Type-safe sensor data ingestion
const payload: SensorPayload = {
  scope: 'VegRoom1',
  ts: new Date().toISOString(),
  sensors: {
    temperature: { value: 75.2, unit: 'F' },
    humidity: { value: 60.5, unit: '%' }
  }
};

await client.ingestSensorData(payload);

// Type-safe device discovery
const devices = await client.getDiscoveredDevices();
console.log(`Found ${devices.count} devices`);

// Type-safe automation rule
const rule: AutomationRule = {
  name: 'Temperature Alert',
  enabled: true,
  conditions: { sensor: 'temperature', operator: 'gt', value: 85 },
  actions: { notification: { type: 'alert' } },
  priority: 10
};

await client.createRule(rule);

Type Safety Benefits

Before (No Types)

// No autocomplete, runtime errors possible
const result = await fetch('/api/env/ingest', {
  body: JSON.stringify({
    scop: 'VegRoom1', // Typo! Will fail at runtime
    sensors: { temp: 75 } // Wrong field name
  })
});

After (With Types)

// TypeScript catches errors at compile time
const payload: SensorPayload = {
  scop: 'VegRoom1', // ❌ Error: Property 'scop' does not exist
  sensors: { temp: { value: 75 } } // ❌ Error: Type is missing 'unit'
};

// Correct version with IDE autocomplete
const payload: SensorPayload = {
  scope: 'VegRoom1', // ✅ Autocomplete suggests 'scope'
  ts: new Date().toISOString(),
  sensors: {
    temperature: { value: 75, unit: 'F' } // ✅ Autocomplete suggests all fields
  }
};

Testing Output

When you run npm run dev, you should see:

🌱 Light Engine Charlie - Type-Safe API Examples

1️⃣ Health Check
   Status: running
   Version: 1.0.0

2️⃣ Ingest Sensor Data (Type-Safe)
   Ingested: "Sensor data ingested"

3️⃣ Get Latest Readings
   Scope: VegRoom1
   Sensors: temperature, humidity, co2
   Observed: 2025-12-06T12:00:00Z

...

✅ All examples completed successfully!

📊 Type Safety Benefits:
   - IDE autocomplete for all API methods
   - Compile-time type checking
   - IntelliSense for request/response objects
   - Catch errors before runtime

Project Structure

typescript-client/
├── src/
│   ├── client.ts       # Main API client class
│   ├── examples.ts     # Usage examples
│   ├── index.ts        # Entry point
│   └── types.ts        # Type re-exports
├── dist/               # Compiled JavaScript (after build)
├── package.json        # Dependencies
├── tsconfig.json       # TypeScript configuration
└── README.md           # This file

Next Steps

• Extend the Client: Add more methods for your specific use cases
• Add Tests: Write unit tests using Jest or Vitest
• Publish as Package: Share as @light-engine/typescript-client on npm
• Generate from OpenAPI: Auto-generate types from openapi.yaml

Contributing

This example is part of the Light Engine Charlie platform enablement initiative. For questions or improvements, see the main project documentation.

License

MIT