objectstack/content/docs/references/integration/connector.mdx at e439ab28d42c730bf6426cfb4417fff728dab42f · objectstack-ai/objectstack

title	Connector
description	Connector protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

Connector Protocol - LEVEL 3: Enterprise Connector

Defines the standard connector specification for external system integration.

Connectors enable ObjectStack to sync data with SaaS apps, databases, file storage,

and message queues through a unified protocol.

Positioning in 3-Layer Architecture:

L1: Simple Sync (automation/sync.zod.ts) - Business users - Sync Salesforce to Sheets
L2: ETL Pipeline (automation/etl.zod.ts) - Data engineers - Aggregate 10 sources to warehouse
L3: Enterprise Connector (THIS FILE) - System integrators - Full SAP integration

SCOPE: Most comprehensive integration layer.

Includes authentication, webhooks, rate limiting, field mapping, bidirectional sync,

retry policies, and complete lifecycle management.

This protocol supports multiple authentication strategies, bidirectional sync,

field mapping, webhooks, and comprehensive rate limiting.

Runtime contract — descriptor vs. registered connector (#2612)

This schema serves TWO distinct consumers; do not conflate them:

Runtime registration (plugin-only). The automation engine's connector

registry — what GET /connectors lists and the connector_action flow

node dispatches — is populated exclusively by plugins calling

engine.registerConnector(def, handlers) with a handler per declared

action (ADR-0018 §Addendum). The definition is validated against this

schema at registration.

Declarative connectors: stack entries (catalog descriptors). Stack

metadata validated against this schema is registered as kind 'connector'

for discovery/documentation/marketplace purposes only — it never reaches

the runtime registry, because an action here carries no execution binding

(deliberately: ADR-0023 rejected re-inventing OpenAPI inside this schema).

The automation service warns at boot about declared entries with actions

that lack a same-name runtime registration; mark deliberate catalog-only

entries with enabled: false. Provider-bound declarative instances that

a generic executor (connector-openapi / connector-mcp) materializes at

boot are tracked in #2977 (ADR-0097).

Authentication is now imported from the canonical auth/config.zod.ts.

When to Use This Layer

Use Enterprise Connector when:

Building enterprise-grade connectors (e.g., Salesforce, SAP, Oracle)
Complex OAuth2/SAML authentication required
Bidirectional sync with field mapping and transformations
Webhook management and rate limiting required
Full CRUD operations and data synchronization
Need comprehensive retry strategies and error handling

Examples:

Full Salesforce integration with webhooks
SAP ERP connector with CDC (Change Data Capture)
Microsoft Dynamics 365 connector

When to downgrade:

Simple field sync → Use Simple Sync
Data transformation only → Use ETL Pipeline

See also: [../automation/sync.zod.ts](/docs/references/automation/sync) for Level 1 (simple sync)

See also: [../automation/etl.zod.ts](/docs/references/automation/etl) for Level 2 (data engineering)

When to use Integration Connector vs. Trigger Registry?

Use [integration/connector.zod.ts](/docs/references/integration/connector) when:

Building enterprise-grade connectors (e.g., Salesforce, SAP, Oracle)
Complex OAuth2/SAML authentication required
Bidirectional sync with field mapping and transformations
Webhook management and rate limiting required
Full CRUD operations and data synchronization
Need comprehensive retry strategies and error handling

Use [automation/trigger-registry.zod.ts](/docs/references/automation/trigger-registry) when:

Building simple automation triggers (e.g., "when Slack message received, create task")
No complex authentication needed (simple API keys, basic auth)
Lightweight, single-purpose integrations
Quick setup with minimal configuration

See also: ../../automation/trigger-registry.zod.ts for lightweight automation triggers

**Source:** `packages/spec/src/integration/connector.zod.ts`

TypeScript Usage

import { CircuitBreakerConfig, Connector, ConnectorAction, ConnectorHealth, ConnectorStatus, ConnectorTrigger, ConnectorType, DataSyncConfig, DeclarativeConnectorEntry, ErrorCategory, ErrorMappingConfig, ErrorMappingRule, HealthCheckConfig, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration';
import type { CircuitBreakerConfig, Connector, ConnectorAction, ConnectorHealth, ConnectorStatus, ConnectorTrigger, ConnectorType, DataSyncConfig, DeclarativeConnectorEntry, ErrorCategory, ErrorMappingConfig, ErrorMappingRule, HealthCheckConfig, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration';

// Validate data
const result = CircuitBreakerConfig.parse(data);

CircuitBreakerConfig

Circuit breaker configuration

Properties

Property	Type	Required	Description
enabled	`boolean`	✅	Enable circuit breaker
failureThreshold	`number`	✅	Failures before opening circuit
resetTimeoutMs	`number`	✅	Time in open state before half-open
halfOpenMaxRequests	`number`	✅	Requests allowed in half-open state
monitoringWindow	`number`	✅	Rolling window for failure count in ms
fallbackStrategy	`Enum<'cache' \| 'default_value' \| 'error' \| 'queue'>`	optional	Fallback strategy when circuit is open

Connector

Properties

Property	Type	Required	Description
name	`string`	✅	Unique connector identifier
label	`string`	✅	Display label
type	`Enum<'saas' \| 'database' \| 'file_storage' \| 'message_queue' \| 'api' \| 'custom'>`	✅	Connector type
description	`string`	optional	Connector description
icon	`string`	optional	Icon identifier
authentication	`{ type: 'oauth2'; authorizationUrl: string; tokenUrl: string; clientId: string; … } \| { type: 'api-key'; key: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; password: string } \| { type: 'bearer'; token: string } \| { type: 'none' }`	optional	Authentication configuration (runtime shape with inline secrets). Provider-bound declarative instances use `auth.credentialRef` instead.
provider	`string`	optional	Generic-executor key that materializes this declarative entry at boot (e.g. openapi/mcp/rest). Omit for a catalog-only descriptor. Unknown provider ⇒ hard boot error (ADR-0097).
providerConfig	`Record<string, any>`	optional	Provider-specific config validated by the provider factory at boot (e.g. `{ spec, baseUrl }` for openapi, where spec is an inline document, a package-relative file path like './billing-openapi.json', or an http(s) URL). Requires `provider`.
auth	`{ type: 'none' } \| { type: 'bearer'; credentialRef: string } \| { type: 'api-key'; credentialRef: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; credentialRef: string }`	optional	Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097).
actions	`{ key: string; label: string; description?: string; inputSchema?: Record<string, any>; … }[]`	optional
triggers	`{ key: string; label: string; description?: string; type: Enum<'polling' \| 'webhook'>; … }[]`	optional	Trigger definitions (not yet enforced — never read at registration; see #3197)
syncConfig	`{ strategy?: Enum<'full' \| 'incremental' \| 'upsert' \| 'append_only'>; direction?: Enum<'import' \| 'export' \| 'bidirectional'>; schedule?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; realtimeSync?: boolean; … }`	optional	Data sync configuration
fieldMappings	`{ source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record<string, any> }; defaultValue?: any; … }[]`	optional	Field mapping rules
webhooks	`{ name: string; label?: string; object?: string; triggers?: Enum<'create' \| 'update' \| 'delete'>[]; … }[]`	optional	Webhook configurations (not yet enforced — never read at registration; see #3197)
rateLimitConfig	`{ strategy?: Enum<'fixed_window' \| 'sliding_window' \| 'token_bucket' \| 'leaky_bucket'>; maxRequests: number; windowSeconds: number; burstCapacity?: number; … }`	optional	Rate limiting configuration
retryConfig	`{ strategy?: Enum<'exponential_backoff' \| 'linear_backoff' \| 'fixed_delay' \| 'no_retry'>; maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number; … }`	optional	Retry configuration
connectionTimeoutMs	`number`	optional	Connection timeout in ms
requestTimeoutMs	`number`	optional	Request timeout in ms
status	`Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>`	optional	Connector status
enabled	`boolean`	optional	Enable connector. On declarative stack entries, false marks a deliberate catalog-only descriptor (#2612).
errorMapping	`{ rules: { sourceCode: string \| number; sourceMessage?: string; targetCode: string; targetCategory: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; … }[]; defaultCategory?: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; unmappedBehavior: Enum<'passthrough' \| 'generic_error' \| 'throw'>; logUnmapped?: boolean }`	optional	Error mapping configuration
health	`{ healthCheck?: object; circuitBreaker?: object }`	optional	Health and resilience configuration
metadata	`Record<string, any>`	optional	Custom connector metadata

ConnectorAction

Properties

Property	Type	Required	Description
key	`string`	✅	Action key (machine name)
label	`string`	✅	Human readable label
description	`string`	optional
inputSchema	`Record<string, any>`	optional	Input parameters schema (JSON Schema)
outputSchema	`Record<string, any>`	optional	Output schema (JSON Schema)

ConnectorHealth

Connector health configuration

Properties

Property	Type	Required	Description
healthCheck	`{ enabled: boolean; intervalMs: number; timeoutMs: number; endpoint?: string; … }`	optional	Health check configuration
circuitBreaker	`{ enabled: boolean; failureThreshold: number; resetTimeoutMs: number; halfOpenMaxRequests: number; … }`	optional	Circuit breaker configuration

ConnectorStatus

Connector status

Allowed Values

active
inactive
error
configuring

ConnectorTrigger

Properties

Property	Type	Required	Description
key	`string`	✅	Trigger key
label	`string`	✅	Trigger label
description	`string`	optional
type	`Enum<'polling' \| 'webhook'>`	✅	Trigger type
interval	`number`	optional	Polling interval in seconds

ConnectorType

Connector type

Allowed Values

saas
database
file_storage
message_queue
api
custom

DataSyncConfig

Properties

Property	Type	Required	Description
strategy	`Enum<'full' \| 'incremental' \| 'upsert' \| 'append_only'>`	optional	Synchronization strategy
direction	`Enum<'import' \| 'export' \| 'bidirectional'>`	optional	Sync direction
schedule	`string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }`	optional	Cron expression for scheduled sync — cron`0 /15 * *`
realtimeSync	`boolean`	optional	Enable real-time sync
timestampField	`string`	optional	Field to track last modification time
conflictResolution	`Enum<'source_wins' \| 'target_wins' \| 'latest_wins' \| 'manual'>`	optional	Conflict resolution strategy
batchSize	`number`	optional	Records per batch
deleteMode	`Enum<'hard_delete' \| 'soft_delete' \| 'ignore'>`	optional	Delete handling mode
filters	`Record<string, any>`	optional	Filter criteria for selective sync

DeclarativeConnectorEntry

Properties

Property	Type	Required	Description
name	`string`	✅	Unique connector identifier
label	`string`	✅	Display label
type	`Enum<'saas' \| 'database' \| 'file_storage' \| 'message_queue' \| 'api' \| 'custom'>`	✅	Connector type
description	`string`	optional	Connector description
icon	`string`	optional	Icon identifier
authentication	`{ type: 'oauth2'; authorizationUrl: string; tokenUrl: string; clientId: string; … } \| { type: 'api-key'; key: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; password: string } \| { type: 'bearer'; token: string } \| { type: 'none' }`	optional	Authentication configuration (runtime shape with inline secrets). Provider-bound declarative instances use `auth.credentialRef` instead.
provider	`string`	optional	Generic-executor key that materializes this declarative entry at boot (e.g. openapi/mcp/rest). Omit for a catalog-only descriptor. Unknown provider ⇒ hard boot error (ADR-0097).
providerConfig	`Record<string, any>`	optional	Provider-specific config validated by the provider factory at boot (e.g. `{ spec, baseUrl }` for openapi, where spec is an inline document, a package-relative file path like './billing-openapi.json', or an http(s) URL). Requires `provider`.
auth	`{ type: 'none' } \| { type: 'bearer'; credentialRef: string } \| { type: 'api-key'; credentialRef: string; headerName?: string; paramName?: string } \| { type: 'basic'; username: string; credentialRef: string }`	optional	Declarative instance auth — references credentials via `credentialRef` (resolved at boot), never inline secrets. Requires `provider` (ADR-0097).
actions	`{ key: string; label: string; description?: string; inputSchema?: Record<string, any>; … }[]`	optional
triggers	`{ key: string; label: string; description?: string; type: Enum<'polling' \| 'webhook'>; … }[]`	optional	Trigger definitions (not yet enforced — never read at registration; see #3197)
syncConfig	`{ strategy?: Enum<'full' \| 'incremental' \| 'upsert' \| 'append_only'>; direction?: Enum<'import' \| 'export' \| 'bidirectional'>; schedule?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; realtimeSync?: boolean; … }`	optional	Data sync configuration
fieldMappings	`{ source: string; target: string; transform?: { type: 'constant'; value: any } \| { type: 'cast'; targetType: Enum<'string' \| 'number' \| 'boolean' \| 'date'> } \| { type: 'lookup'; table: string; keyField: string; valueField: string } \| { type: 'javascript'; expression: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object } } \| { type: 'map'; mappings: Record<string, any> }; defaultValue?: any; … }[]`	optional	Field mapping rules
webhooks	`{ name: string; label?: string; object?: string; triggers?: Enum<'create' \| 'update' \| 'delete'>[]; … }[]`	optional	Webhook configurations (not yet enforced — never read at registration; see #3197)
rateLimitConfig	`{ strategy?: Enum<'fixed_window' \| 'sliding_window' \| 'token_bucket' \| 'leaky_bucket'>; maxRequests: number; windowSeconds: number; burstCapacity?: number; … }`	optional	Rate limiting configuration
retryConfig	`{ strategy?: Enum<'exponential_backoff' \| 'linear_backoff' \| 'fixed_delay' \| 'no_retry'>; maxAttempts?: number; initialDelayMs?: number; maxDelayMs?: number; … }`	optional	Retry configuration
connectionTimeoutMs	`number`	optional	Connection timeout in ms
requestTimeoutMs	`number`	optional	Request timeout in ms
status	`Enum<'active' \| 'inactive' \| 'error' \| 'configuring'>`	optional	Connector status
enabled	`boolean`	optional	Enable connector. On declarative stack entries, false marks a deliberate catalog-only descriptor (#2612).
errorMapping	`{ rules: { sourceCode: string \| number; sourceMessage?: string; targetCode: string; targetCategory: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; … }[]; defaultCategory?: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; unmappedBehavior: Enum<'passthrough' \| 'generic_error' \| 'throw'>; logUnmapped?: boolean }`	optional	Error mapping configuration
health	`{ healthCheck?: object; circuitBreaker?: object }`	optional	Health and resilience configuration
metadata	`Record<string, any>`	optional	Custom connector metadata

ErrorCategory

Standard error category

Allowed Values

validation
authorization
not_found
conflict
rate_limit
timeout
server_error
integration_error

ErrorMappingConfig

Error mapping configuration

Properties

Property	Type	Required	Description
rules	`{ sourceCode: string \| number; sourceMessage?: string; targetCode: string; targetCategory: Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>; … }[]`	✅	Error mapping rules
defaultCategory	`Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>`	✅	Default category for unmapped errors
unmappedBehavior	`Enum<'passthrough' \| 'generic_error' \| 'throw'>`	✅	What to do with unmapped errors
logUnmapped	`boolean`	✅	Log unmapped errors

ErrorMappingRule

Error mapping rule

Properties

Property	Type	Required	Description
sourceCode	`string \| number`	✅	External system error code
sourceMessage	`string`	optional	Pattern to match against error message
targetCode	`string`	✅	ObjectStack standard error code
targetCategory	`Enum<'validation' \| 'authorization' \| 'not_found' \| 'conflict' \| 'rate_limit' \| 'timeout' \| 'server_error' \| 'integration_error'>`	✅	Error category
severity	`Enum<'low' \| 'medium' \| 'high' \| 'critical'>`	✅	Error severity level
retryable	`boolean`	✅	Whether the error is retryable
userMessage	`string`	optional	Human-readable message to show users

HealthCheckConfig

Health check configuration

Properties

Property	Type	Required	Description
enabled	`boolean`	✅	Enable health checks
intervalMs	`number`	✅	Health check interval in milliseconds
timeoutMs	`number`	✅	Health check timeout in milliseconds
endpoint	`string`	optional	Health check endpoint path
method	`Enum<'GET' \| 'HEAD' \| 'OPTIONS'>`	optional	HTTP method for health check
expectedStatus	`number`	✅	Expected HTTP status code
unhealthyThreshold	`number`	✅	Consecutive failures before marking unhealthy
healthyThreshold	`number`	✅	Consecutive successes before marking healthy

RateLimitStrategy

Rate limiting strategy

Allowed Values

fixed_window
sliding_window
token_bucket
leaky_bucket

RetryConfig

Properties

Property	Type	Required	Description
strategy	`Enum<'exponential_backoff' \| 'linear_backoff' \| 'fixed_delay' \| 'no_retry'>`	✅	Retry strategy
maxAttempts	`number`	✅	Maximum retry attempts
initialDelayMs	`number`	✅	Initial retry delay in ms
maxDelayMs	`number`	✅	Maximum retry delay in ms
backoffMultiplier	`number`	✅	Exponential backoff multiplier
retryableStatusCodes	`number[]`	✅	HTTP status codes to retry
retryOnNetworkError	`boolean`	✅	Retry on network errors
jitter	`boolean`	✅	Add jitter to retry delays

RetryStrategy

Retry strategy

Allowed Values

exponential_backoff
linear_backoff
fixed_delay
no_retry

SyncStrategy

Synchronization strategy

Allowed Values

full
incremental
upsert
append_only

WebhookConfig

Properties

Property	Type	Required	Description
name	`string`	✅	Webhook unique name (lowercase snake_case)
label	`string`	optional	Human-readable webhook label
object	`string`	optional	Object whose record events (create/update/delete) trigger this webhook
triggers	`Enum<'create' \| 'update' \| 'delete'>[]`	optional	Events that trigger execution
url	`string`	✅	External webhook endpoint URL
method	`Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'>`	✅	HTTP method
headers	`Record<string, string>`	optional	Custom HTTP headers
body	`any`	optional	Request body payload (if not using default record data)
payloadFields	`string[]`	optional	Fields to include. Empty = All
includeSession	`boolean`	✅	Include user session info
authentication	`{ type: Enum<'none' \| 'bearer' \| 'basic' \| 'api-key'>; credentials?: Record<string, string> }`	optional	Authentication configuration
retryPolicy	`{ maxRetries: integer; backoffStrategy: Enum<'exponential' \| 'linear' \| 'fixed'>; initialDelayMs: integer; maxDelayMs: integer }`	optional	Retry policy configuration
timeoutMs	`integer`	✅	Request timeout in milliseconds
secret	`string`	optional	Signing secret for HMAC signature verification
isActive	`boolean`	✅	Whether webhook is active
description	`string`	optional	Webhook description
tags	`string[]`	optional	Tags for organization
events	`Enum<'record.created' \| 'record.updated' \| 'record.deleted' \| 'sync.started' \| 'sync.completed' \| 'sync.failed' \| 'auth.expired' \| 'rate_limit.exceeded'>[]`	optional	Connector events to subscribe to (not yet enforced — no runtime dispatches these; see #3197)
signatureAlgorithm	`Enum<'hmac_sha256' \| 'hmac_sha512' \| 'none'>`	✅	Webhook signature algorithm

WebhookEvent

Webhook event type

Allowed Values

record.created
record.updated
record.deleted
sync.started
sync.completed
sync.failed
auth.expired
rate_limit.exceeded

WebhookSignatureAlgorithm

Webhook signature algorithm

Allowed Values

hmac_sha256
hmac_sha512
none

Uh oh!

FilesExpand file tree

connector.mdx

Latest commit

History

connector.mdx

File metadata and controls

Runtime contract — descriptor vs. registered connector (#2612)

When to Use This Layer

When to use Integration Connector vs. Trigger Registry?

TypeScript Usage

CircuitBreakerConfig

Properties

Connector

Properties

ConnectorAction

Properties

ConnectorHealth

Properties

ConnectorStatus

Allowed Values

ConnectorTrigger

Properties

ConnectorType

Allowed Values

DataSyncConfig

Properties

DeclarativeConnectorEntry

Properties

ErrorCategory

Allowed Values

ErrorMappingConfig

Properties

ErrorMappingRule

Properties

HealthCheckConfig

Properties

RateLimitStrategy

Allowed Values

RetryConfig

Properties

RetryStrategy

Allowed Values

SyncStrategy

Allowed Values

WebhookConfig

Properties

WebhookEvent

Allowed Values

WebhookSignatureAlgorithm

Allowed Values