@ai-operations/ops-connectors

Connector framework with Gmail, Calendar, X/Twitter, and Shopify integrations for AI Operations OS.

Part of AI Operations OS — autonomous business workflow orchestration with safety enforcement.

Install

npm install @ai-operations/ops-connectors

Quick Start

import { ConnectorRegistry, GmailConnector, resilientFetch, RateLimiter } from '@ai-operations/ops-connectors';

const registry = new ConnectorRegistry();
registry.register(new GmailConnector({ name: 'gmail', enabled: true, credentials: { token: '...' } }));

const gmail = registry.get('gmail');
const result = await gmail.execute('send', { to: '[email protected]', body: 'Hello!' });

API

BaseConnector (abstract)

Abstract base class for all connectors. Subclasses implement supportedOperations, execute, and healthCheck.

abstract get supportedOperations(): string[]
abstract execute(operation: string, input: Record<string, unknown>): Promise<ConnectorResult>
abstract healthCheck(): Promise<boolean>
supportsOperation(operation: string): boolean
isEnabled(): boolean

• ConnectorConfig — { name: string; enabled: boolean; credentials?: Record<string, string> }
• ConnectorResult — { success: boolean; data?: Record<string, unknown>; error?: string }

Connector Implementations

| Connector | Class | Operations | |-----------|-------|-----------| | Gmail | GmailConnector | send, read, list, search | | Google Calendar | CalendarConnector | create_event, update_event, cancel_event, list | | X / Twitter | XTwitterConnector | post, delete, search | | Shopify | ShopifyConnector | fulfill, refund, list, get |

ConnectorRegistry

Central registry for managing connector instances with bulk health checks.

register(connector: BaseConnector): void
get(name: string): BaseConnector | undefined
list(): BaseConnector[]
healthCheckAll(): Promise<Map<string, boolean>>

resilientFetch(url, init?, options?): Promise<FetchAttemptResult>

Retry-aware HTTP client with exponential backoff, 429 Retry-After support, request timeouts, and jitter.

const { response, attempts, totalDurationMs } = await resilientFetch(
  'https://api.example.com/data',
  { method: 'GET', headers: { Authorization: 'Bearer token' } },
  { maxRetries: 3, timeoutMs: 10000 },
);

• ResilientFetchOptions — { maxRetries?, initialDelayMs?, maxDelayMs?, timeoutMs?, retryableStatuses? }

RateLimiter

Sliding-window rate limiter for per-connector request throttling.

const limiter = new RateLimiter({ maxRequests: 100, windowMs: 60000 });
if (limiter.canProceed()) {
  limiter.record();
  await fetch(...);
}
await limiter.waitAndRecord(); // Block until a slot opens

Related Packages

• @ai-operations/shared-types — Core types consumed by connectors
• @ai-operations/ops-core — WorkflowEngine that executes connector operations
• @ai-operations/cord-adapter — Safety gate evaluated before connector execution

License

MIT