npm package: @nexstem/registry-stack
Description: Node.js SDK for SW Registry Stack - Operator Registry, Pipeline Registry, and Executor
Author: SW Registry Stack Team
Latest version: 1.0.5
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# SW Registry Stack Node.js SDK

[![npm version](https://badge.fury.io/js/%40nexstem%2Fregistry-stack.svg)](https://badge.fury.io/js/%40nexstem%2Fregistry-stack)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/@nexstem/registry-stack)](https://nodejs.org/)

A comprehensive Node.js SDK for the SW Registry Stack, providing TypeScript/JavaScript interfaces for Operator Registry, Pipeline Registry, and Executor operations.

## Installation

```bash
npm install @nexstem/registry-stack
```

## Quick Start

### Executor Operations

```typescript
import { Executor } from '@nexstem/registry-stack';

// Initialize the executor
const executor = new Executor({
  basePath: '/tmp/executor',
  bridgeLibPath: '/path/to/libexecutor_bridge.dylib',
  debug: true
});

await executor.initialize();

// Create a pipeline
const result = await executor.create({
  config: {
    jsonFile: '/path/to/pipeline.json',
    background: true
  },
  deviceId: 'my-device-001',
  enableLogging: true,
  onUnifiedLog: (entry) => {
    console.log('Log:', entry.message, 'from', entry.source);
  }
});

if (result.status === 'success') {
  console.log('Pipeline created:', result.data.pipeline_id);
  
  // Start the pipeline
  await executor.start(result.data.run_id);
  
  // Stop the pipeline
  await executor.stop(result.data.run_id);
  
  // Destroy the pipeline
  await executor.destroy(result.data.run_id);
}
```

### Unified Logging

The SDK provides structured logging with rich context:

```typescript
interface UnifiedLogEntry {
  // Core identification
  node_id: string;
  pipeline_id: string;
  run_id: string;
  device_id: string;
  
  // Log metadata
  level: number;        // 0=DEBUG, 1=INFO, 2=WARNING, 3=ERROR, 4=CRITICAL
  source: number;       // 0=NODE, 1=EXECUTOR, 2=PIPELINE, 3=SDK, 4=SYSTEM
  message: string;
  
  // Timing information
  timestamp: number;
  elapsed_ms: number;
  
  // Context information
  function_name: string;
  file_name: string;
  line_number: number;
  
  // Additional data
  data: any;
  metadata: Record<string, any>;
  
  // SDK specific fields
  sdk_component?: string;
  sdk_operation?: string;
}
```

### Log Sources

- **NODE (0)**: C++ pipeline nodes
- **EXECUTOR (1)**: Executor core operations
- **PIPELINE (2)**: Pipeline management
- **SDK (3)**: Node.js SDK operations
- **SYSTEM (4)**: System components

### Log Levels

- **DEBUG (0)**: Detailed debugging information
- **INFO (1)**: General information
- **WARNING (2)**: Warning messages
- **ERROR (3)**: Error conditions
- **CRITICAL (4)**: Critical failures

## API Reference

### Executor

#### `new Executor(options)`

Create a new Executor instance.

**Options:**
- `basePath: string` - Base directory for executor operations
- `bridgeLibPath: string` - Path to the native bridge library
- `debug?: boolean` - Enable debug logging

#### `executor.initialize()`

Initialize the executor and load the native bridge.

#### `executor.create(options)`

Create a new pipeline.

**Options:**
- `config: { jsonFile?: string, jsonData?: string, background?: boolean }`
- `deviceId?: string`
- `enableLogging?: boolean`
- `onUnifiedLog?: (entry: UnifiedLogEntry) => void`

**Returns:** `Promise<PipelineCreateResponse>`

#### `executor.start(runId)`

Start a pipeline execution.

#### `executor.stop(runId)`

Stop a pipeline execution.

#### `executor.destroy(runId)`

Destroy a pipeline and clean up resources.

## Requirements

- Node.js >= 16.0.0
- Native bridge library (libexecutor_bridge.dylib/libexecutor_bridge.so)