Introduction

Prismatic’s TypeScript SDK for building custom connectors and code-native integrations

What is Spectral?

Spectral is Prismatic’s open-source TypeScript library for building custom connectors and code-native integrations on the Prismatic embedded iPaaS platform.

With Spectral, you can:

• Build custom connectors (components) with actions, triggers, data sources, and connections that appear natively in the Prismatic integration designer
• Write code-native integrations entirely in TypeScript, deploying them directly to Prismatic without using the low-code designer
• Define OAuth 2.0 connections, on-prem connections, and standard API key connections
• Unit test your connectors and integrations locally before publishing

Quickstart

Build and publish your first custom connector in minutes

Installation

Install Spectral and set up your development environment

Custom Connectors

Learn how to build type-safe connectors with actions, triggers, and connections

Code-Native Integrations

Write complete integrations in TypeScript with full IDE support

Two ways to build with Spectral

Custom Connectors

Custom connectors (components) are reusable building blocks that appear in the Prismatic low-code integration designer. They expose actions, triggers, data sources, and connections that integration builders can use without writing any code.

Use custom connectors when:

• You need to connect to an API not covered by Prismatic’s built-in connectors
• You want to encapsulate reusable business logic as a connector
• Non-developers will build integrations using your connector

import { component, action, input, connection } from "@prismatic-io/spectral";

export default component({
  key: "my-api",
  display: {
    label: "My API",
    description: "Connect to My API",
    iconPath: "icon.png",
  },
  actions: { getUser },
  connections: [myConnection],
});

Code-Native Integrations

Code-native integrations are complete integrations written in TypeScript. Instead of using the visual designer, you define flows, triggers, config pages, and logic entirely in code.

Use code-native integrations when:

• Your team prefers a code-first workflow with version control
• You need complex branching or data transformation logic
• You want full TypeScript type safety throughout your integration

import { integration, flow, trigger, configPage } from "@prismatic-io/spectral";

export default integration({
  name: "My Integration",
  description: "Sync data between systems",
  flows: [syncFlow],
  configPages: [configPage({ ...pageDefinition })],
});

Key features

Full TypeScript Support

Complete type definitions for all APIs. Get autocompletion, type checking, and inline documentation in your IDE.

OAuth 2.0 Connections

Built-in support for OAuth 2.0 authorization code and client credentials flows, including PKCE.

HTTP Client

Built-in Axios-based HTTP client with automatic retry, authorization header injection, and multipart form support.

Testing Utilities

Unit test actions, triggers, data sources, and flows locally with mock contexts and logger assertions.

On-Prem Connections

Support for on-premises connections that route through Prismatic’s on-prem agent.

Polling Triggers

Scheduled polling triggers with state management for detecting new events in APIs that lack webhooks.

Package overview

The @prismatic-io/spectral npm package exports the following top-level APIs:

Export	Purpose
component	Define a custom connector
action	Define an action within a connector
trigger	Define a trigger within a connector
pollingTrigger	Define a polling trigger
dataSource	Define a data source
input	Define an input field
connection	Define a standard connection
oauth2Connection	Define an OAuth 2.0 connection
onPremConnection	Define an on-prem connection
integration	Define a code-native integration
flow	Define a flow within a code-native integration
configPage	Define a config wizard page
configVar	Define a configuration variable
util	Type coercion and utility functions
testing	Unit testing helpers

Learn more

Custom Connectors

Actions, triggers, inputs, connections

Code-Native

Flows, config wizards, endpoint config

Testing

Unit testing your connectors and flows