Node.js SDK Overview

The Orchesty Node.js SDK enables you to build custom applications, connectors, and batch processing nodes using TypeScript or JavaScript. It provides a comprehensive framework for API integration, OAuth2 authentication, data transformation, and workflow orchestration.

What Can You Build? #

Applications #

Applications handle authentication and provide configuration for API integrations:

ABasicApplication - For API keys, tokens, and basic auth
AOAuth2Application - For OAuth2 authentication flows

Connectors #

Connectors perform specific actions in your integration workflows:

AConnector - Base class for custom connectors
ACommonNode - Common functionality for nodes
ABatchNode - Batch processing capabilities

Core Concepts #

Data Transfer Objects #

Learn how data flows through your integrations:

ProcessDto - Main data object for connectors
RequestDto - HTTP request configuration
BatchProcessDto - Batch operation data

Configuration & Forms #

Create user-friendly configuration interfaces:

FormStack - Collection of configuration forms
Form - Individual form configuration
Field - Form fields with validation
FieldType - Available field types
CoreFormsEnum - Standard form identifiers

Application Management #

Manage user credentials and application state:

ApplicationInstall - User credential storage
DIContainer - Dependency injection container

Quick Start #

1. Install the SDK #

npm install @orchesty/nodejs-sdk

2. Create a Basic Application #

import { ABasicApplication } from '@orchesty/nodejs-sdk';
import { FormStack, Form, Field, FieldType, CoreFormsEnum } from '@orchesty/nodejs-sdk';

export default class MyAPIApplication extends ABasicApplication {
    public getName(): string {
        return 'my-api';
    }

    public getPublicName(): string {
        return 'My API';
    }

    public getDescription(): string {
        return 'Integration with My API service';
    }

    public getFormStack(): FormStack {
        const apiKeyField = new Field(FieldType.PASSWORD, 'api_key', 'API Key');
        const form = new Form(CoreFormsEnum.AUTHORIZATION_FORM, 'Authorization');
        form.addField(apiKeyField);
        
        const formStack = new FormStack();
        formStack.addForm(form);
        return formStack;
    }

    public getRequestDto(dto, applicationInstall, method, url, data): RequestDto {
        const settings = applicationInstall.getSettings();
        const apiKey = settings[CoreFormsEnum.AUTHORIZATION_FORM]['api_key'];
        
        const requestDto = new RequestDto(url, method, dto, data);
        requestDto.setHeaders({
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
        });
        
        return requestDto;
    }
}

3. Create a Connector #

import AConnector from '@orchesty/nodejs-sdk';
import { ProcessDto, RequestDto, HttpMethods } from '@orchesty/nodejs-sdk';

export default class FetchDataConnector extends AConnector {
    public getName(): string {
        return 'fetch-data';
    }

    public async processAction(dto: ProcessDto): Promise<ProcessDto> {
        // Get application credentials
        const appInstall = await this.getApplicationInstallFromProcess(dto);
        
        // Make API request using your application
        const requestDto = await this.getApplication().getRequestDto(
            dto,
            appInstall,
            HttpMethods.GET,
            'https://api.example.com/data'
        );
        
        const responseDto = await this.getSender().send(requestDto);
        
        // Set output data
        dto.setJsonData(JSON.parse(responseDto.getBody()));
        
        return dto;
    }
}

4. Register Your Components #

import DIContainer from '@orchesty/nodejs-sdk';

const container = new DIContainer();

// Register application
const myApp = new MyAPIApplication();
container.setApplication(myApp);

// Register connector
const connector = new FetchDataConnector();
container.setConnector(connector);

Documentation Structure #

For Application Developers #

Start with ABasicApplication or AOAuth2Application
Learn about FormStack and Field for configuration
Understand ApplicationInstall for credential management

For Connector Developers #

Begin with AConnector basics
Master ProcessDto for data handling
Learn RequestDto for API calls

For Batch Processing #

Explore ABatchNode for batch operations
Work with BatchProcessDto for batch data

Common Patterns #

Pattern: API Integration #

Create an application class extending ABasicApplication or AOAuth2Application
Define configuration forms with FormStack
Implement getRequestDto() to add authentication
Create connectors extending AConnector for specific actions

Pattern: Data Transformation #

Create a connector extending AConnector
Read input with dto.getJsonData()
Transform the data
Set output with dto.setJsonData()

Pattern: Error Handling #

Wrap API calls in try/catch
Use dto.setStopProcess() for errors
Return the DTO with error status

SDK Resources #

GitHub Repository: orchesty-nodejs-sdk
NPM Package: @orchesty/nodejs-sdk
TypeScript: Full TypeScript support with type definitions

Getting Help #

Review the class documentation linked above
Check the SDK tutorials
Explore example connectors in the Orchesty Store