---
title: Connector
description: Connector protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

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.

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](../automation/sync.zod.ts)

- Data transformation only → Use [ETL Pipeline](../automation/etl.zod.ts)

@see [../automation/sync.zod.ts](../automation/sync.zod.ts) for Level 1 (simple sync)

@see [../automation/etl.zod.ts](../automation/etl.zod.ts) for Level 2 (data engineering)

## When to use Integration Connector vs. Trigger Registry?

**Use `integration/connector.zod.ts` 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` 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 ../../automation/trigger-registry.zod.ts for lightweight automation triggers

<Callout type="info">
**Source:** `packages/spec/src/integration/connector.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { CircuitBreakerConfig, ConnectorAction, ConnectorHealth, ConnectorStatus, ConnectorTrigger, ConnectorType, ErrorCategory, ErrorMappingConfig, ErrorMappingRule, HealthCheckConfig, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration';
import type { CircuitBreakerConfig, ConnectorAction, ConnectorHealth, ConnectorStatus, ConnectorTrigger, ConnectorType, 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 |


---

## 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** | `Object` | optional | Health check configuration |
| **circuitBreaker** | `Object` | 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`


---

## 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** | `Object[]` | ✅ | 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 to listen to (optional for manual webhooks) |
| **triggers** | `Enum<'create' \| 'update' \| 'delete' \| 'undelete' \| 'api'>[]` | 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** | `Object` | optional | Authentication configuration |
| **retryPolicy** | `Object` | 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 |
| **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`


---

