busroot-sdk 0.0.7-alpha → 0.0.7-alpha.0

package/README.md

@@ -0,0 +1,278 @@
+# Busroot SDK
+
+Official TypeScript/JavaScript SDK for the [Busroot](https://www.output.industries) manufacturing performance platform.
+
+## About Busroot
+
+Busroot is a cloud-based manufacturing performance platform that gives factories real-time visibility of how their machines and processes are performing. It connects to shop-floor equipment and automatically blends machine data with operational context such as production schedules, SKUs, and energy use to reveal the true causes of downtime, under-performance, and waste.
+
+Manufacturers use Busroot to:
+- Improve equipment utilisation and increase output
+- Reduce energy consumption and operational costs
+- Detect and track downtime automatically
+- Calculate OEE (Overall Equipment Effectiveness)
+- Analyse cycle times and benchmark performance
+- Track production quality and scrap rates
+- Monitor energy efficiency across operations
+
+Developed by [Output Industries Ltd](https://www.output.industries), Busroot replaces spreadsheets and guesswork with clear insights that help teams make better decisions, act faster, and unlock more value from the assets they already have.
+
+## Documentation
+
+For complete platform documentation, API references, and guides, visit:
+- **Platform Documentation**: [https://docs.output.industries/](https://docs.output.industries/)
+- **Company Website**: [https://www.output.industries/](https://www.output.industries/)
+- **API Reference**: [https://docs.output.industries/integration/http-api-reference](https://docs.output.industries/integration/http-api-reference)
+
+## Installation
+
+Install the SDK using your preferred package manager:
+
+```bash
+# Using npm
+npm install busroot-sdk
+
+# Using pnpm
+pnpm add busroot-sdk
+
+# Using yarn
+yarn add busroot-sdk
+```
+
+## Quick Start
+
+### 1. Get Your API Credentials
+
+You'll need:
+- **Account ID**: Your Busroot account identifier
+- **API Key**: Generated from your Busroot account settings
+
+Contact your Busroot administrator or visit the [Busroot platform](https://app.busroot.com) to obtain these credentials.
+
+### 2. Initialize the Client
+
+```typescript
+import { BusrootClient } from 'busroot-sdk';
+
+const client = new BusrootClient({
+  accountId: 'account_your-account-id',
+  apiKey: 'your-api-key-here',
+  apiEndpoint: 'https://api.busroot.com',
+  mqttHost: 'mqtt.busroot.com',
+  enableMqtt: true,  // Optional: Enable real-time updates via MQTT
+  enableDebug: false // Optional: Enable debug logging
+});
+```
+
+### 3. Fetch Manufacturing Data
+
+#### Get Account Information
+
+```typescript
+const account = await client.getAccount();
+console.log(`Account: ${account.domain}`);
+console.log(`Plants: ${account.plants.length}`);
+```
+
+#### Get All Stations
+
+```typescript
+const stations = await client.getStations();
+stations.forEach(station => {
+  console.log(`${station.name}: ${station.state.label}`);
+});
+```
+
+#### Get Station Performance Data
+
+```typescript
+const performance = await client.getStationWindows({
+  stationCodes: ['STATION_01'],
+  from: '2024-01-01T00:00:00Z',
+  to: '2024-01-01T23:59:59Z',
+  interval: '1h' // Aggregate data hourly
+});
+
+performance.forEach(data => {
+  console.log(`Production: ${data.productionGoodCount} units`);
+  console.log(`Downtime: ${data.downtimeMs}ms`);
+  console.log(`Energy: ${data.electricalKwh}kWh`);
+});
+```
+
+#### Get Production Schedules
+
+```typescript
+const schedules = await client.getSchedules();
+schedules.forEach(schedule => {
+  console.log(`${schedule.skuName}: ${schedule.quantityGood}/${schedule.plannedQuantity}`);
+});
+```
+
+#### Real-time Updates with MQTT
+
+```typescript
+// Subscribe to real-time station metric updates
+client.on('StationMetricNew', (metric) => {
+  console.log(`New metric for ${metric.stationCode}`);
+  console.log(`Production: ${metric.productionGoodCount}`);
+  console.log(`Status: ${metric.isAlive ? 'Connected' : 'Disconnected'}`);
+});
+
+// Subscribe to production events
+client.on('ProductionNew', (production) => {
+  console.log(`Production recorded: ${production.quantityGood} units`);
+});
+
+// Clean up when done
+process.on('SIGINT', () => {
+  client.destroy();
+  process.exit();
+});
+```
+
+## Key Features
+
+### 📊 Comprehensive Type Definitions
+
+The SDK provides full TypeScript type definitions for all Busroot data structures:
+
+```typescript
+import type {
+  StationViewModel,
+  ScheduleViewModel,
+  OeeViewModel,
+  StationWindowSchema,
+  SkuViewModel
+} from 'busroot-sdk';
+```
+
+All types include detailed JSDoc comments explaining manufacturing concepts and field meanings.
+
+### ⚡ Real-time Data Streaming
+
+Enable MQTT support to receive live updates from your shop floor:
+- Station performance metrics
+- Production counts
+- Downtime events
+- Schedule changes
+- Machine status updates
+
+### 🔍 Flexible Querying
+
+Query historical data with flexible filters:
+- Date ranges
+- Station selection
+- Time interval aggregation
+- Production schedules
+- Downtime analysis
+
+### ✅ Runtime Validation
+
+All API responses are validated using [Zod](https://github.com/colinhacks/zod) schemas, ensuring type safety at runtime.
+
+## API Methods
+
+### Account & Configuration
+- `getAccount()` - Fetch account information and configuration
+- `getPlants()` - List all manufacturing plants
+- `getStationGroups()` - List station groups
+
+### Stations & Equipment
+- `getStations()` - List all stations
+- `getStation(code)` - Get specific station details
+- `getStationWindows(params)` - Query time-series performance data
+
+### Production & Scheduling
+- `getSchedules(params)` - Fetch production schedules
+- `getProduction(params)` - Query production records
+- `getSkus()` - List all SKUs (products/parts)
+
+### Performance Analysis
+- `getOee(params)` - Calculate Overall Equipment Effectiveness
+- `getDowntime(params)` - Query downtime events
+
+### Real-time Events
+- `on(eventType, listener)` - Subscribe to real-time events
+- `off(eventType, listener)` - Unsubscribe from events
+- `destroy()` - Clean up connections
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides comprehensive type definitions. All data structures include detailed documentation:
+
+```typescript
+import type { StationWindowSchema } from 'busroot-sdk';
+
+// StationWindowSchema includes fields like:
+// - productionGoodCount: Number of good quality units produced
+// - downtimeMs: Milliseconds of downtime
+// - electricalKwh: Energy consumed
+// - oeeAvailability: OEE Availability percentage
+// And many more manufacturing-specific metrics
+```
+
+## React Integration
+
+The SDK includes React hooks for easy integration with React applications:
+
+```typescript
+import { useBusroot } from 'busroot-sdk';
+
+function StationDashboard() {
+  const { stations, loading, error } = useBusroot();
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      {stations.map(station => (
+        <div key={station.code}>
+          <h3>{station.name}</h3>
+          <p>Status: {station.state.label}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Development
+
+### Building from Source
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the SDK
+pnpm run build
+
+# Run tests
+pnpm test
+
+# Run linter
+pnpm run lint
+```
+
+## Manufacturing Concepts
+
+Busroot uses industry-standard manufacturing terminology:
+
+- **Station**: A piece of equipment or work area on the shop floor
+- **Schedule**: A production plan assigning SKUs to stations with target quantities
+- **SKU**: Stock Keeping Unit (a product or part being manufactured)
+- **OEE**: Overall Equipment Effectiveness (Availability × Performance × Quality)
+- **Downtime**: Periods when equipment is not productive during scheduled production time
+- **Station Window**: Time-bucketed performance metrics (e.g., per minute, per shift)
+- **Utilisation**: Percentage of scheduled time that equipment was productive
+- **Cycle Time**: Time to produce one unit
+
+See the [documentation](https://docs.output.industries/) for detailed explanations of all manufacturing metrics.
+
+## Support
+
+- **Documentation**: [https://docs.output.industries/](https://docs.output.industries/)
+- **GitHub Issues**: Report bugs and request features
+- **Email**: Contact support through the Output Industries website

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busroot-sdk",
-  "version": "0.0.7-alpha",
+  "version": "0.0.7-alpha.0",
   "description": "An SDK for accessing Busroot from output.industries",
   "homepage": "https://www.output.industries",
   "main": "./build/index.js",
@@ -12,7 +12,8 @@
     "build": "pnpm run lint && tsc --build --clean && tsc --build",
     "lint": "eslint 'src/**/*.ts'",
     "lint-fix": "eslint 'src/**/*.ts' --fix",
-    "test": "jest"  },
+    "test": "jest"
+  },
   "files": [
     "build"
   ],