@transai/connector-runner-hp-indigo 0.2.0

package/README.md

@@ -0,0 +1,638 @@
+# HP Indigo Connector Runner
+
+A connector runner library for receiving job status messages from HP Indigo digital printing presses via JMF (Job Messaging Format) or webhook.
+
+**Note:** This is a connector-runner library that runs within the `connector-orchestrator` process, not a standalone application.
+
+## Quick Start
+
+### Basic Configuration (Recommended)
+
+```json
+{
+  "callbackHost": "connector.example.com",
+  "port": 3050,
+  "webhookPath": "/hp-indigo/job-status",
+  "jmf": {
+    "enabled": true,
+    "printerUrl": "http://<printer-ip>:8080/prodflow/jmf/HP-DFE-V12-1"
+  }
+}
+```
+
+### What Happens
+1. Connector starts on port 3050
+2. Subscribes to HP Indigo via JMF
+3. HP Indigo sends job notifications automatically
+4. Data stored in `<datasourceIdentifier>_job-status` collection
+
+---
+
+## Features
+
+✅ **Dual Mode Operation**
+- JMF Subscription (automatic, standards-based)
+- Passive Webhook (fallback, manual configuration)
+
+✅ **Self-Healing**
+- Automatic subscription health checks every 5 minutes
+- Auto-recovery if HP Indigo restarts or subscription fails
+- Startup cleanup of stale subscriptions
+
+✅ **Production-Ready**
+- Graceful shutdown with proper JMF unsubscribe
+- 5-second timeout protection
+- Handles crashes, SIGTERM, SIGINT via ConnectorSDK
+
+✅ **Flexible Parsing**
+- Supports both XML and JSON message formats
+- Multiple field naming conventions (JobID/jobId/id)
+- Preserves all additional fields
+
+---
+
+## Operation Modes
+
+### Mode 1: JMF Subscription (Recommended)
+
+**When to use:** HP Indigo supports JMF protocol (DFE V12 and later)
+
+**Benefits:**
+- Automatic registration - no manual printer configuration
+- Standards-based (CIP4 JMF)
+- Health monitoring with auto-heal
+- Proper lifecycle management
+
+**Configuration:**
+```typescript
+{
+  callbackHost: 'connector.example.com', // Must be reachable by HP Indigo
+  port: 3050,
+  webhookPath: '/hp-indigo/job-status',
+  jmf: {
+    enabled: true,
+    printerUrl: 'http://<printer-ip>:8080/prodflow/jmf/HP-DFE-V12-1',
+    channelId: 'hp-indigo-channel-1' // Optional
+  }
+}
+```
+
+### Mode 2: Passive Webhook (Fallback)
+
+**When to use:** HP Indigo doesn't support JMF, or as fallback
+
+**Configuration:**
+```typescript
+{
+  port: 3050,
+  webhookPath: '/hp-indigo/job-status'
+  // No JMF configuration
+}
+```
+
+**Setup:** Manually configure HP Indigo to POST to:
+```
+http://<your-server-ip>:3050/hp-indigo/job-status
+```
+
+---
+
+## Configuration Reference
+
+### ConnectorConfig
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `callbackHost` | string | Conditional | - | Externally reachable IP or hostname for webhook callback URL (required when jmf.enabled) |
+| `port` | number | No | 3050 | Port for webhook server |
+| `webhookPath` | string | No | `/hp-indigo/job-status` | Path for webhook endpoint |
+| `jmf.enabled` | boolean | No | false | Enable JMF subscription mode |
+| `jmf.printerUrl` | string | Conditional | - | HP Indigo JMF endpoint (required if jmf.enabled) |
+| `jmf.channelId` | string | No | `channel-<timestamp>` | Custom channel ID for subscription |
+
+### Example: Full Configuration
+
+```json
+{
+  "connector": {
+    "identifier": "hp-indigo-prod",
+    "type": "hp-indigo",
+    "config": {
+      "callbackHost": "connector.example.com",
+      "port": 3050,
+      "webhookPath": "/hp-indigo/job-status",
+      "jmf": {
+        "enabled": true,
+        "printerUrl": "http://<printer-ip>:8080/prodflow/jmf/HP-DFE-V12-1",
+        "channelId": "hp-indigo-channel-1"
+      }
+    }
+  }
+}
+```
+
+---
+
+## JMF Subscription Details
+
+### Lifecycle
+
+```
+┌─────────────────────────────────────────┐
+│ STARTUP                                  │
+├─────────────────────────────────────────┤
+│ 1. Start webhook server (port 3050)     │
+│ 2. Clean up stale subscriptions         │
+│ 3. Send JMF Subscribe to HP Indigo      │
+│ 4. Start health monitoring (every 5min) │
+└─────────────────────────────────────────┘
+
+┌─────────────────────────────────────────┐
+│ OPERATION                                │
+├─────────────────────────────────────────┤
+│ • Receive job notifications              │
+│ • Store in hp_indigo_job_status         │
+│ • Track last notification time           │
+│ • Health check every 5 minutes:          │
+│   - Send JMF QueueStatus query           │
+│   - Re-subscribe if unhealthy            │
+└─────────────────────────────────────────┘
+
+┌─────────────────────────────────────────┐
+│ SHUTDOWN                                 │
+├─────────────────────────────────────────┤
+│ 1. Send JMF Unsubscribe (5s timeout)    │
+│ 2. Stop health monitoring                │
+│ 3. Close webhook server                  │
+└─────────────────────────────────────────┘
+```
+
+### Subscribe Message
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<JMF xmlns="http://www.CIP4.org/JDFSchema_1_1"
+     SenderID="TransAI-HP-Indigo-Connector"
+     TimeStamp="2026-04-02T10:00:00Z"
+     Version="1.4">
+  <Query ID="query-123" Type="SubscriptionFilter">
+    <SubscriptionFilter ChannelID="hp-indigo-channel-1" 
+                       URL="http://<connector-host>:3050/hp-indigo/job-status">
+      <MessageFilter MessageType="Signal">
+        <SignalFilter SignalType="Status"/>
+      </MessageFilter>
+    </SubscriptionFilter>
+  </Query>
+</JMF>
+```
+
+### Unsubscribe Message
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<JMF xmlns="http://www.CIP4.org/JDFSchema_1_1"
+     SenderID="TransAI-HP-Indigo-Connector"
+     TimeStamp="2026-04-02T10:00:00Z"
+     Version="1.4">
+  <Command ID="cmd-123" Type="StopPersistentChannel">
+    <StopPersistentChannel ChannelID="hp-indigo-channel-1"/>
+  </Command>
+</JMF>
+```
+
+### Health Check Message
+
+```xml
+<JMF xmlns="http://www.CIP4.org/JDFSchema_1_1">
+  <Query Type="QueueStatus">
+    <QueueFilter ChannelID="hp-indigo-channel-1"/>
+  </Query>
+</JMF>
+```
+
+---
+
+## Health Monitoring & Auto-Heal
+
+The connector automatically monitors subscription health and recovers from failures.
+
+### How It Works
+
+**Every 5 minutes:**
+1. Send JMF QueueStatus query to HP Indigo
+2. Check if subscription channel is active
+3. If unhealthy → auto-heal (re-subscribe)
+4. Fallback: check notification timestamps if JMF unavailable
+
+**Benefits:**
+- ✅ Instant failure detection (via JMF)
+- ✅ Works even for idle printers
+- ✅ Recovers from HP Indigo restarts
+- ✅ Handles network interruptions
+- ✅ No manual intervention needed
+
+### Scenarios Handled
+
+| Scenario | Detection | Recovery |
+|----------|-----------|----------|
+| HP Indigo restarts | JMF QueueStatus fails | Auto-resubscribe |
+| Network interruption | JMF query fails + no data | Auto-resubscribe |
+| HP Indigo timeout | JMF indicates inactive | Auto-resubscribe |
+| Idle printer | JMF shows active | No action (healthy) |
+
+---
+
+## Message Format
+
+### Incoming Messages
+
+The connector accepts both XML and JSON:
+
+**XML Example:**
+```xml
+<JobStatus>
+  <JobID>12345</JobID>
+  <JobName>Print Job Example</JobName>
+  <Status>Completed</Status>
+  <State>Finished</State>
+  <Printer>HP Indigo 12000</Printer>
+  <Owner>user@example.com</Owner>
+  <Pages>100</Pages>
+  <Sheets>25</Sheets>
+  <Copies>4</Copies>
+</JobStatus>
+```
+
+**JSON Example:**
+```json
+{
+  "jobId": "12345",
+  "jobName": "Print Job Example",
+  "status": "Completed",
+  "state": "Finished",
+  "printer": "HP Indigo 12000",
+  "owner": "user@example.com",
+  "pages": 100,
+  "sheets": 25,
+  "copies": 4
+}
+```
+
+### Stored Data
+
+Messages are stored in `${datasourceIdentifier}_job-status` collection (e.g., `hp-indigo-prod_job-status`) with these fields:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `jobId` | string | Yes | Unique job identifier (key field) |
+| `jobName` | string | Yes | Job name |
+| `jobStatus` | string | Yes | Current status |
+| `jobState` | string | Yes | Current state |
+| `timestamp` | string | Yes | ISO timestamp (auto-generated) |
+| `printer` | string | No | Printer name/ID |
+| `owner` | string | No | Job owner |
+| `pages` | number | No | Number of pages |
+| `sheets` | number | No | Number of sheets |
+| `copies` | number | No | Number of copies |
+
+Additional fields from the source are automatically preserved.
+
+---
+
+## Network Setup
+
+### Example Network
+
+- HP Indigo: `<printer-ip>:8080`
+- Your Connector: `<connector-host>:3050`
+
+### Requirements
+
+✅ Port 3050 open on connector server (firewall)
+✅ Connector can reach HP Indigo JMF endpoint
+✅ HP Indigo can reach connector webhook (for notifications)
+
+### Testing Connectivity
+
+**Test HP Indigo is reachable:**
+```bash
+curl http://xxx.xxx.xxx.xx:8080/prodflow/jmf/HP-DFE-V12-1
+```
+
+**Test connector health endpoint:**
+```bash
+curl http://<connector-host>:3050/health
+# Should return: {"status":"ok"}
+```
+
+---
+
+## Logging
+
+### Normal Operation
+
+```
+[HP Indigo] Webhook server started on 0.0.0.0:3050
+[HP Indigo] Listening for job status updates on /hp-indigo/job-status
+[HP Indigo] Cleaning up any stale JMF subscriptions before starting...
+[HP Indigo] No stale subscription found (expected on first start)
+[HP Indigo JMF] Subscribing to printer at http://xxx.xxx.xxx.xx:8080/prodflow/jmf/HP-DFE-V12-1
+[HP Indigo JMF] Successfully subscribed with channel ID: hp-indigo-channel-1
+[HP Indigo] JMF subscription established successfully
+[HP Indigo] Starting subscription health monitoring
+```
+
+### Health Check (Every 5 minutes)
+
+```
+[HP Indigo] Health check: Subscription active (verified via JMF)
+```
+
+### Auto-Heal
+
+```
+[HP Indigo] JMF health check indicates subscription is not active - attempting to re-subscribe...
+[HP Indigo] Subscription re-established successfully (auto-heal)
+```
+
+### Shutdown
+
+```
+[HP Indigo] Initiating JMF unsubscribe...
+[HP Indigo JMF] Unsubscribing channel hp-indigo-channel-1
+[HP Indigo JMF] Successfully unsubscribed channel hp-indigo-channel-1
+[HP Indigo] JMF subscription terminated successfully
+```
+
+---
+
+## Troubleshooting
+
+### Issue: Cannot connect to HP Indigo JMF endpoint
+
+**Test:**
+```bash
+curl http://xxx.xxx.xxx.xx:8080/prodflow/jmf/HP-DFE-V12-1
+```
+
+**Solutions:**
+- Check network connectivity: `ping xxx.xxx.xxx.xx`
+- Verify HP Indigo service is running
+- Check firewall on HP Indigo server
+- Verify JMF endpoint URL is correct
+
+### Issue: HP Indigo cannot reach webhook
+
+**Test from HP Indigo server:**
+```bash
+curl http://<connector-host>:3050/health
+```
+
+**Solutions:**
+- Check connector is running
+- Check firewall on connector server (port 3050)
+- Verify network connectivity
+
+### Issue: JMF subscription fails
+
+**Check logs for:** `Failed to establish JMF subscription`
+
+**Solutions:**
+- Connector automatically falls back to passive webhook mode
+- Manually configure HP Indigo to POST to your webhook URL
+- Contact HP support for JMF documentation
+
+### Issue: Not receiving notifications
+
+**Check:**
+1. Is HP Indigo processing jobs?
+2. Check connector-orchestrator logs for this connector's webhooks (set level to `verbose`)
+3. Verify subscription is active: look for health check logs in orchestrator
+4. Check auto-heal logs - may be re-subscribing
+5. Verify connector is enabled in orchestrator configuration
+
+**Enable debug logging in orchestrator:**
+```json
+{
+  "logging": {
+    "level": "debug"
+  }
+}
+```
+
+---
+
+## Deployment
+
+This connector-runner is deployed via the **connector-orchestrator**, not as a standalone application.
+
+### How to Deploy
+
+1. **Build the library:**
+   ```bash
+   npm exec nx build connector-runner-hp-indigo
+   ```
+
+2. **Add connector configuration** to connector-orchestrator:
+   ```json
+   {
+     "identifier": "hp-indigo-prod",
+     "connectorType": "hp-indigo",
+     "tenantIdentifier": "your-tenant",
+     "name": "HP Indigo Production",
+     "enabled": true,
+      "config": {
+        "port": 3050,
+        "webhookPath": "/hp-indigo/job-status",
+        "jmf": {
+          "enabled": true,
+          "printerUrl": "http://<printer-ip>:8080/prodflow/jmf/HP-DFE-V12-1",
+          "channelId": "hp-indigo-channel-1"
+        }
+      }
+   }
+   ```
+
+3. **Configure network access** on the host running connector-orchestrator:
+   - Allow incoming TCP on port 3050 (for HP Indigo notifications)
+   - Allow outgoing connections to HP Indigo JMF endpoint
+
+4. **Start/restart connector-orchestrator**
+   - Orchestrator will load and run this connector-runner
+   - Monitor orchestrator logs for HP Indigo connector startup
+
+### Network Requirements
+
+- **Port 3050** must be accessible on the orchestrator host (from HP Indigo network)
+- Runs **within orchestrator process** (no separate deployment)
+- Uses **orchestrator's logging infrastructure**
+- Works wherever orchestrator runs (cloud/on-prem/VM/bare metal)
+
+---
+
+## Advanced Features
+
+### Startup Cleanup
+
+Prevents duplicate subscriptions by unsubscribing stale channels on startup:
+
+```typescript
+// On startup, before subscribing:
+1. Attempt to unsubscribe (cleanup old subscription)
+2. Subscribe with fresh subscription
+3. Start health monitoring
+```
+
+This handles crashes where previous instance didn't cleanly unsubscribe.
+
+### Health Monitoring
+
+**Primary Check (JMF-based):**
+- Sends JMF `QueueStatus` query every 5 minutes
+- Verifies subscription channel is active
+- Instant detection, works for idle printers
+
+**Fallback Check (Data-based):**
+- If JMF query fails, checks notification timestamps
+- Triggers re-subscribe if no data for 15+ minutes
+- Graceful degradation if JMF unsupported
+
+### Graceful Shutdown
+
+ConnectorSDK handles all signals (SIGTERM, SIGINT, uncaughtException). On shutdown:
+
+```typescript
+1. Stop() called by SDK
+2. JMF unsubscribe sent (max 5 seconds)
+3. Stop health monitoring
+4. Close webhook server
+5. Exit cleanly
+```
+
+Unsubscribe has 5-second timeout to prevent hanging.
+
+---
+
+## Message Capture
+
+All fields are captured and preserved:
+
+**Standard Fields** (typed):
+- jobId, jobName, jobStatus, jobState
+- timestamp (auto-generated)
+- printer, owner, pages, sheets, copies
+
+**Additional Fields** (dynamic):
+- All other fields from the source message are preserved
+- Supports both PascalCase and camelCase
+- Handles XML attributes and nested elements
+
+---
+
+## Endpoints
+
+| Path | Method | Description |
+|------|--------|-------------|
+| `/hp-indigo/job-status` | POST | Receives job status notifications |
+| `/health` | GET | Health check (returns `{"status":"ok"}`) |
+
+---
+
+## Development
+
+### Build Library
+```bash
+npm exec nx build connector-runner-hp-indigo
+```
+
+### Run Tests
+```bash
+npm exec nx test connector-runner-hp-indigo
+```
+
+### Lint Code
+```bash
+npm exec nx lint connector-runner-hp-indigo
+```
+
+### Testing in Connector-Orchestrator
+
+To test this connector-runner:
+1. Build the library: `npm exec nx build connector-runner-hp-indigo`
+2. Configure connector in connector-orchestrator
+3. Start connector-orchestrator
+4. Monitor logs for HP Indigo connector startup and subscription
+
+---
+
+## Architecture
+
+```
+┌─────────────────┐
+│  HP Indigo DFE  │
+│  xxx.xxx.xxx.xx │
+└────────┬────────┘
+         │ JMF Subscribe/Health Check
+         ↓
+┌─────────────────┐
+│  JMF Client     │  - Subscription management
+│                 │  - Health monitoring
+└────────┬────────┘  - Auto-heal
+         │
+         │ Callbacks
+         ↓
+┌─────────────────┐
+│ Webhook Server  │  - HTTP server (Express)
+│  Port 3050      │  - XML/JSON parsing
+└────────┬────────┘  - Data storage
+         │
+         ↓ Notifications
+┌─────────────────┐
+│  HP Indigo      │  ← Job status updates
+│  Printer        │
+└─────────────────┘
+```
+
+---
+
+## Files
+
+- `lib/connector-runner-hp-indigo.ts` - Main connector class implementing ConnectorRuntimeSDK
+- `jmf-client.ts` - JMF protocol client (subscribe/unsubscribe/health)
+- `webhook-server.ts` - Express HTTP webhook server
+- `types.ts` - TypeScript interfaces and configuration types
+- `index.ts` - Public API exports
+
+---
+
+## Standards & References
+
+- **JMF**: CIP4 Job Messaging Format for print industry
+- **CIP4**: International Cooperation for Integration of Processes
+- **HP Indigo**: Digital printing press messaging
+
+### Links
+
+- [CIP4 JMF Specification](https://www.cip4.org/)
+- [JMF Documentation](https://confluence.cip4.org/display/PUB/JMF)
+- [HP Indigo Forum](https://accept-forum.enfocus.com/viewtopic.php?t=761)
+
+---
+
+## Guarantees
+
+✅ **JMF unsubscribe will be called** on every shutdown (via ConnectorSDK)
+✅ **Maximum 5-second delay** during shutdown (won't hang)
+✅ **Health checks every 5 minutes** using JMF protocol
+✅ **Auto-recovery** from subscription failures
+✅ **Startup cleanup** prevents duplicate subscriptions
+✅ **Crash-resilient** - recovers gracefully on restart
+✅ **Graceful fallback** to passive mode if JMF unavailable
+✅ **Production-tested** - follows xod-core conventions
+
+---
+
+## License
+
+Part of the xod-core platform.
+