@useparagon/ocs-core

@useparagon/ocs-core

Core engine for the Open Connector Specification. Loads connector YAML as lightweight config and executes actions, triggers, and pipelines directly — no code generation required.

Note: This package is a library. For the CLI (ocs build, ocs run, etc.), see the ocs repo.

Architecture

OCS connectors are defined entirely in YAML. The OCS core engine treats YAML definitions as lightweight config (similar to a state machine) and executes them directly at runtime:

YAML files → load as JSON config → runtime engine executes

There is no code generation step for standard connectors. The runtime engine has processors for each resource type (actions, triggers, pipelines) that understand the YAML config format and execute it against provider APIs.

This is analogous to a workflow engine — configs are small, storable (Postgres, Redis, etc.), and the engine interprets them at runtime. Only connectors that need custom logic beyond what YAML can express use the optional codegen escape hatch.

Table of contents

• Installation
• Package exports
• Quick start
• CLI API
  • Validate
  • Run action
  • Run trigger
  • Run pipeline
  • List resources
  • Auth
  • Utilities
• Escape hatch: codegen build
• SDK API
• Runtime API
• Development
• Key features
• Related repositories

Installation

npm install @useparagon/ocs-core

Package exports

Import path	Purpose
@useparagon/ocs-core	Types, loader, validator, codegen, SDK base classes, connector builder
@useparagon/ocs-core/runtime	HTTP client, auth handlers, pagination, rate-limit, retry, YAML handlers, testing harness
@useparagon/ocs-core/cli	Programmatic APIs for validate, run, list, auth (used by the ocs CLI)

Quick start

The primary workflow is validate → run directly from YAML:

import {
  validateConnector,
  runAction,
  formatRunActionResult,
} from '@useparagon/ocs-core/cli';

// 1. Validate the connector YAML (schema + semantic rules)
const validation = validateConnector({ dir: '/path/to/connector' });
if (!validation.success) {
  console.error('Validation failed:', validation.schemaErrors, validation.semanticErrors);
  process.exit(1);
}

// 2. Run an action directly from the YAML config
const result = await runAction({
  dir: '/path/to/connector',
  action: 'get-profile',
  input: '{"profileId": "abc123"}',
  stored: '{"apiKey": "pk_your_key"}',
});

console.log(formatRunActionResult(result, true));

No build step. No generated code. The YAML is loaded as config and the runtime engine executes it.

CLI API

All functions below are exported from @useparagon/ocs-core/cli.

Validate

Validate connector YAML (schema + semantic rules) without generating any code.

import { validateConnector, formatValidateResult } from '@useparagon/ocs-core/cli';

const result = validateConnector({ dir: '/path/to/connector', verbose: true });

console.log(formatValidateResult(result));
// result.success, result.connectorId, result.schemaErrors, result.semanticErrors
// result.resourceCounts — { actions, triggers, pipelines, entities }

Types: ValidateOptions, ValidateResult

Run action

Execute a single action directly from connector YAML.

import { runAction, formatRunActionResult } from '@useparagon/ocs-core/cli';

const result = await runAction({
  dir: '/path/to/connector',
  action: 'get-profile',
  input: '{"profileId": "abc123"}',
  stored: '{"apiKey": "pk_your_key"}',
  timeout: 30000,
  verbose: true,
});

console.log(formatRunActionResult(result, true));
// result.success, result.data, result.error, result.statusCode, result.duration

Types: RunActionOptions, RunActionResult

Run trigger

Start a trigger handler. Polling triggers run once; webhook triggers register and wait.

import { runTrigger } from '@useparagon/ocs-core/cli';

const result = await runTrigger({
  dir: '/path/to/connector',
  trigger: 'contact-created',
  stored: '{"apiKey": "pk_your_key"}',
});

Types: RunTriggerOptions, RunTriggerResult

Run pipeline

Execute a data sync pipeline. Pages through data sources and collects records.

import { runPipeline, formatRunPipelineResult } from '@useparagon/ocs-core/cli';

const result = await runPipeline({
  dir: '/path/to/connector',
  pipeline: 'sync-contacts',
  maxPages: 5,
  verbose: true,
});

console.log(formatRunPipelineResult(result, true));
// result.success, result.items, result.totalPages, result.lastCursor

Types: RunPipelineOptions, RunPipelineResult

List resources

List available actions, triggers, and pipelines from connector YAML.

import { listResources, formatListResult } from '@useparagon/ocs-core/cli';

const options = { dir: '/path/to/connector', kind: 'all' as const, format: 'table' as const };
const result = listResources(options);

console.log(formatListResult(result, options));
// result.connectorName, result.actions, result.triggers, result.pipelines

Types: ListOptions, ListResult

Auth

OAuth2 login flow for connector authentication.

import { authLogin } from '@useparagon/ocs-core/cli';

const result = await authLogin({
  dir: '/path/to/connector',
  tunnel: false,
  port: 9876,
  stored: '{"clientId": "...", "clientSecret": "..."}',
  verbose: true,
});
// result.credentials, result.credentialsFile

Types: AuthLoginOptions, AuthLoginResult

Utilities

import {
  resolveConnectorDir,    // Resolve connector root directory
  discoverProjectRoot,    // Walk up to find connector.yaml
  loadCredentials,        // Load creds from JSON, .env, or OCS_CREDENTIALS env var
  formatCliError,         // Format errors for user-facing output
  isCacheFresh,           // Check if a build cache is still valid
  resolveConnectorId,     // Extract connectorId from YAML
} from '@useparagon/ocs-core/cli';

Escape hatch: codegen build

For connectors that need custom TypeScript handlers beyond what the YAML runtime engine supports, there is an optional codegen build pipeline:

import { runBuild, formatBuildResult } from '@useparagon/ocs-core/cli';

const result = await runBuild({
  dir: '/path/to/connector',
  skipValidation: false,
  skipTypeErrors: false,
  verbose: true,
});

console.log(formatBuildResult(result));

This generates TypeScript SDK classes from YAML, compiles them, and produces build artifacts. Most connectors should not need this — the YAML runtime engine handles standard action/trigger/pipeline execution directly.

Types: BuildOptions, BuildResult

SDK API

The main entry point (@useparagon/ocs-core) exports types, loader, validator, codegen, and SDK base classes:

import {
  // Load YAML → ConnectorDefinition (lightweight config object)
  buildConnector,
  buildFromResolved,
  buildConnectorFromYamlStrings,

  // Loader
  parseOCSYaml,
  loadOCSFile,
  resolveConnectorDirectory,

  // Validator
  validateSchema,
  validateSemantic,
  validateDocument,

  // Codegen (escape hatch)
  generateSDK,

  // SDK base classes (for custom TypeScript handlers)
  ActionBase,
  ConnectorBase,
  TriggerBase,
  PipelineBase,
} from '@useparagon/ocs-core';

Runtime API

The runtime entry point (@useparagon/ocs-core/runtime) provides the YAML execution engine and supporting infrastructure:

import {
  // YAML runtime engine — executes connector config directly
  createYamlHandlers,
  YamlActionHandler,
  YamlTriggerHandler,
  YamlPipelineHandler,

  // Connector runner
  ConnectorRunner,

  // HTTP, auth, pagination, rate-limit
  createConnectorHttpClient,
  resolveAuth,

  // Testing harness
  ConnectorTestHarness,
  MockHttpClient,
} from '@useparagon/ocs-core/runtime';

Development

git clone https://github.com/useparagon/ocs-core.git
cd ocs-core
npm install
npm run build

Scripts:

Script	Description
npm run build	Build the package (tsup -> dist/)
npm run dev -- <cmd>	Run in dev mode via tsx (no build needed)
npm run typecheck	Type-check without emitting
npm run test	Run tests (Jest with ESM support)
npm run lint	Lint with ESLint
npm run format	Format with Prettier

Project structure:

src/
├── cli-api.ts    # Barrel export for @useparagon/ocs-core/cli
├── cli/          # CLI function implementations (validate, list, build)
├── codegen/      # YAML → TypeScript SDK generator (escape hatch)
├── connector/    # ConnectorDefinition builder (YAML → config object)
├── loader/       # YAML parser and connector directory resolver
├── validator/    # Schema (Ajv) + semantic validation rules
├── sdk/          # Base classes for custom TypeScript handlers
├── _runtime/     # YAML execution engine, HTTP client, auth, pagination, rate-limit
├── types/        # OCS resource type definitions
├── interfaces/   # Pure contracts (no runtime)
├── errors/       # Error hierarchy (OCSError, HttpRequestError, etc.)
└── utils/        # Shared utilities

Key features

Feature	Description
YAML-first	Connectors defined entirely in YAML — treated as lightweight config
No codegen	YAML configs executed directly by the runtime engine (like a workflow engine)
Validation	Two-layer validation: JSON Schema (structural) + semantic cross-resource rules
Pagination	Built-in support for offset, cursor, and link-header pagination strategies
Rate limiting	Named rate-limit buckets with proactive throttling and exponential backoff
Idempotency	Automatic idempotency key injection for safe retries on POST/PATCH
Filtering	CONDITIONAL input parameters translated to provider-native query syntax
Expressions	JSONata-based expression evaluation for complex field mappings
Plugins	Extensible plugin system for custom processing steps

Related repositories

Package	Repo	Purpose
@useparagon/ocs	ocs	YAML spec definition, ocs CLI for validation, running, publishing, and deployment
@useparagon/ocs-core	this repo	Core library — loader, validator, YAML runtime engine, SDK
@useparagon/ocs-registry	ocs-registry	Connector registry API, OCI artifact storage, connector-base Docker image

License

MIT