@automationview/api

Public API for building AutomationView export plugins.

This package provides types, base classes, and utilities for creating export providers that convert Sequence/SFC projects into PLC-compatible formats (PLCopen XML, Structured Text, CSV, etc.), and for registering equipment catalogs (manufacturers, devices, development software).

Installation

npm install @automationview/api

Quick Start

1. Simple function-based provider

Use createSimpleProvider when a full class is overkill:

import { createSimpleProvider } from '@automationview/api';

const provider = createSimpleProvider({
    id: 'csv-export',
    devSoftwareId: 'generic',
    supportedFormats: [{ format: 'csv', label: 'CSV' }],
    export: async (data, options) => {
        const lines = data.sequences.map(g => g.name);
        return {
            success: true,
            outputFiles: [{ path: 'output.csv', content: lines.join('\n') }],
            diagnostics: [],
            durationMs: 0,
            format: options.format,
        };
    },
});

2. Register the provider

Use getAutomationViewAPI() to retrieve the API :

import { getAutomationViewAPI } from '@automationview/api';

export async function activate(context) {
    const api = await getAutomationViewAPI();
    if (!api) return;

    const disposable = api.registerExportProvider(new MyProvider());
    context.subscriptions.push(disposable);
}

Equipment Registration

Equipment registration follows a dependency chain: manufacturer -> equipment -> development software. All three must be registered for the equipment catalog to be complete.

Using EquipmentBuilder (recommended)

The EquipmentBuilder provides a fluent API with a callback pattern for building deeply nested equipment objects:

import {
    createManufacturer,
    createDevSoftware,
    EquipmentBuilder,
} from '@automationview/api';

// 1. Create manufacturer
const siemens = createManufacturer({
    id: 'siemens',
    displayName: 'Siemens',
    country: 'Germany',
    website: 'https://siemens.com',
});

// 2. Build equipment with versions, channels, and parameters
const s71200 = EquipmentBuilder
    .create('s7-1200', 'siemens', 'S7-1200', 'controller', 'profinet')
    .description('Compact controller for small to medium applications')
    .partNumbers(['6ES7214-1AG40-0XB0'])
    .addVersion('V4.5', v => v
        .partNumber('6ES7214-1AG40-0XB0')
        .addChannel('DI0', 'Digital Input 0', 'input', 'BOOL', 0, 1)
        .addChannel('DI1', 'Digital Input 1', 'input', 'BOOL', 0, 1, { bitOffset: 1 })
        .addChannel('DQ0', 'Digital Output 0', 'output', 'BOOL', 2, 1)
        .addParameter('cycle-time', 'CYCLE_TIME', 'Cycle Time', 'INT', 10, { unit: 'ms', min: 1, max: 1000 })
    )
    .build();

// 3. Create development software
const tiaPortal = createDevSoftware({
    id: 'tia-portal-v18',
    displayName: 'TIA Portal V18',
    vendor: 'Siemens',
    plcopenXmlSupport: 'partial',
    supportedEquipmentIds: ['s7-1200'],
});

// 4. Register with the API
const api = avExt.exports;
context.subscriptions.push(
    api.registerManufacturer(siemens),
    api.registerEquipment(s71200),
    api.registerDevSoftware(tiaPortal),
);

Using factory functions

For simpler cases, use individual factory functions:

import {
    createManufacturer,
    createDevSoftware,
    createEquipmentVersion,
    createIOChannel,
    createEquipmentParameter,
} from '@automationview/api';

const channel = createIOChannel({
    id: 'AI0',
    name: 'Analog Input 0',
    direction: 'input',
    dataType: 'INT',
    addressOffset: 0,
    bitSize: 16,
    unit: 'mA',
    range: { min: 0, max: 20 },
});

const param = createEquipmentParameter({
    id: 'filter-time',
    name: 'FILTER_TIME',
    displayName: 'Filter Time',
    dataType: 'INT',
    defaultValue: 50,
    unit: 'ms',
});

const version = createEquipmentVersion({
    version: 'V1.0',
    channels: [channel],
    parameters: [param],
});

API Reference

Export Provider Framework

| Export | Description | |--------|-------------| | AbstractExportProvider | Base class with cancellation, progress, and error handling | | CancellationError | Error thrown to signal cancelled export | | createSimpleProvider(config) | Factory for function-based providers | | DiagnosticBuilder | Fluent builder for ExportDiagnostic objects |

DiagnosticBuilder

import { DiagnosticBuilder } from '@automationview/api';

const err = DiagnosticBuilder.error('MISSING_VAR', 'Variable "x" not declared')
    .source('MyProvider')
    .suggestion('Declare variable "x" before export')
    .build();

const warn = DiagnosticBuilder.warning('LONG_NAME', 'Name exceeds 32 chars').build();
const info = DiagnosticBuilder.info('SKIPPED', 'Empty step skipped').build();

Equipment Builder & Factories

| Export | Description | |--------|-------------| | EquipmentBuilder | Fluent builder for EquipmentInfo with callback-based version nesting | | VersionBuilder | Version builder received via EquipmentBuilder.addVersion callback | | createManufacturer(config) | Factory for ManufacturerInfo objects | | createDevSoftware(config) | Factory for DevSoftwareInfo objects | | createIOChannel(config) | Factory for IOChannel objects | | createEquipmentVersion(config) | Factory for EquipmentVersion objects | | createEquipmentParameter(config) | Factory for EquipmentParameter objects |

Helpers

| Export | Description | |--------|-------------| | getAutomationViewAPI() | Retrieves the AutomationView API. Returns Promise<IAutomationViewAPI \| undefined> |

Type Guards

| Export | Description | |--------|-------------| | isManufacturerInfo(obj) | Checks for ManufacturerInfo shape | | isEquipmentInfo(obj) | Checks for EquipmentInfo shape | | isDevSoftwareInfo(obj) | Checks for DevSoftwareInfo shape | | isExportProviderDescriptor(obj) | Checks for IExportProviderDescriptor shape | | isIOChannel(obj) | Checks for IOChannel shape | | isEquipmentVersion(obj) | Checks for EquipmentVersion shape | | isEquipmentParameter(obj) | Checks for EquipmentParameter shape | | isNamingConvention(obj) | Checks for NamingConvention shape |

Enums

| Export | Values | |--------|--------| | ActionInstruction | ADD, SUB, MUL, DIV, MOVE, SR, RS, TON, TOF, ... | | ActionQualifier | N, S, R, P, L, D, DS, SD, SL | | StepType | INITIAL, STANDARD, MACRO, ENCLOSING |

Re-exported Types

All types needed by export providers are available directly from @automationview/api:

import type {
    // Sequence data model
    SequenceData, StepData, TransitionData, ActionData, ActionOperand,
    // Variables & project
    VariableData, VariableDataType, MachineData, ProjectIOData,
    // Equipment
    ManufacturerInfo, EquipmentInfo, DevSoftwareInfo, NamingConvention,
    EquipmentCategory, CommunicationProtocol, IOChannel, EquipmentVersion,
    EquipmentParameter, EquipmentParameterDataType, ParameterValue,
    // Export
    ExportOptions, ExportResult, ExportDiagnostic, ProjectExportData,
    // API core
    IAutomationViewAPI, IExportProviderDescriptor, APICancellationToken,
    // Config types
    ManufacturerConfig, DevSoftwareConfig, IOChannelConfig,
    EquipmentVersionConfig, EquipmentParameterConfig,
} from '@automationview/api';

Package Structure

src/
├── index.ts                          Barrel exports (grouped by category)
├── equipment/                        Equipment builder & factories
│   ├── EquipmentBuilder.ts              Fluent builder for EquipmentInfo
│   ├── createManufacturer.ts            ManufacturerInfo factory
│   ├── createDevSoftware.ts             DevSoftwareInfo factory
│   ├── createIOChannel.ts               IOChannel factory
│   ├── createEquipmentVersion.ts        EquipmentVersion factory
│   └── createEquipmentParameter.ts      EquipmentParameter factory
├── export/                           Export provider framework
│   ├── AbstractExportProvider.ts        Base class for providers
│   ├── createSimpleProvider.ts          Function-based provider factory
│   └── DiagnosticBuilder.ts             Fluent diagnostic builder
├── validation/                       Runtime validation
│   └── TypeGuards.ts                    Type guard functions
└── vscode/                           VS Code helpers
    └── getAutomationViewAPI.ts          Retrieve the AV extension API

Versioning

@automationview/api follows semver. Plugins must keep their declared dependency in lockstep with the host extension on every minor or major bump (patch releases are drop-in). See docs/API_BUMP_POLICY.md in the automationview-extension repo for the full policy.

License

PRIVATE @RCAutomSolutions