@auxiora/connectors 1.0.0

package/dist/trigger-manager.js

@@ -0,0 +1,62 @@
+export class TriggerManager {
+    registry;
+    authManager;
+    subscriptions = new Map();
+    constructor(registry, authManager) {
+        this.registry = registry;
+        this.authManager = authManager;
+    }
+    /** Subscribe to a trigger on a connector instance. Returns a subscription ID. */
+    subscribe(connectorId, triggerId, instanceId, handler) {
+        const connector = this.registry.get(connectorId);
+        if (!connector) {
+            throw new Error(`Connector "${connectorId}" not found`);
+        }
+        const trigger = connector.triggers.find((t) => t.id === triggerId);
+        if (!trigger) {
+            throw new Error(`Trigger "${triggerId}" not found in connector "${connectorId}"`);
+        }
+        const subId = `${connectorId}:${triggerId}:${instanceId}`;
+        this.subscriptions.set(subId, {
+            connectorId,
+            triggerId,
+            instanceId,
+            handler,
+            lastPollAt: Date.now(),
+        });
+        return subId;
+    }
+    /** Unsubscribe from a trigger. */
+    unsubscribe(subscriptionId) {
+        return this.subscriptions.delete(subscriptionId);
+    }
+    /** Poll all subscriptions and invoke handlers for new events. */
+    async pollAll() {
+        const allEvents = [];
+        for (const [subId, sub] of this.subscriptions) {
+            const connector = this.registry.get(sub.connectorId);
+            if (!connector?.pollTrigger)
+                continue;
+            const token = this.authManager.getToken(sub.instanceId);
+            if (!token)
+                continue;
+            try {
+                const events = await connector.pollTrigger(sub.triggerId, token.accessToken, sub.lastPollAt);
+                if (events.length > 0) {
+                    await sub.handler(events);
+                    allEvents.push(...events);
+                }
+                sub.lastPollAt = Date.now();
+            }
+            catch {
+                // Poll errors are silently ignored to avoid breaking other subscriptions
+            }
+        }
+        return allEvents;
+    }
+    /** Get all active subscription IDs. */
+    getSubscriptions() {
+        return [...this.subscriptions.keys()];
+    }
+}
+//# sourceMappingURL=trigger-manager.js.map

package/dist/trigger-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger-manager.js","sourceRoot":"","sources":["../src/trigger-manager.ts"],"names":[],"mappings":"AAcA,MAAM,OAAO,cAAc;IACjB,QAAQ,CAAoB;IAC5B,WAAW,CAAc;IACzB,aAAa,GAAG,IAAI,GAAG,EAAwB,CAAC;IAExD,YAAY,QAA2B,EAAE,WAAwB;QAC/D,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;IAED,iFAAiF;IACjF,SAAS,CACP,WAAmB,EACnB,SAAiB,EACjB,UAAkB,EAClB,OAAuB;QAEvB,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACjD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,cAAc,WAAW,aAAa,CAAC,CAAC;QAC1D,CAAC;QAED,MAAM,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC;QACnE,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,YAAY,SAAS,6BAA6B,WAAW,GAAG,CAAC,CAAC;QACpF,CAAC;QAED,MAAM,KAAK,GAAG,GAAG,WAAW,IAAI,SAAS,IAAI,UAAU,EAAE,CAAC;QAC1D,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE;YAC5B,WAAW;YACX,SAAS;YACT,UAAU;YACV,OAAO;YACP,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;SACvB,CAAC,CAAC;QAEH,OAAO,KAAK,CAAC;IACf,CAAC;IAED,kCAAkC;IAClC,WAAW,CAAC,cAAsB;QAChC,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IACnD,CAAC;IAED,iEAAiE;IACjE,KAAK,CAAC,OAAO;QACX,MAAM,SAAS,GAAmB,EAAE,CAAC;QAErC,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YACrD,IAAI,CAAC,SAAS,EAAE,WAAW;gBAAE,SAAS;YAEtC,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACxD,IAAI,CAAC,KAAK;gBAAE,SAAS;YAErB,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,WAAW,CACxC,GAAG,CAAC,SAAS,EACb,KAAK,CAAC,WAAW,EACjB,GAAG,CAAC,UAAU,CACf,CAAC;gBAEF,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACtB,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;oBAC1B,SAAS,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;gBAC5B,CAAC;gBAED,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC9B,CAAC;YAAC,MAAM,CAAC;gBACP,yEAAyE;YAC3E,CAAC;QACH,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,uCAAuC;IACvC,gBAAgB;QACd,OAAO,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;IACxC,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+import type { TrustLevel, TrustDomain } from '@auxiora/autonomy';
+/** Supported authentication methods for connectors. */
+export type AuthType = 'oauth2' | 'api_key' | 'token';
+/** OAuth2 configuration for connectors that use OAuth2 auth. */
+export interface OAuth2Config {
+    authUrl: string;
+    tokenUrl: string;
+    scopes: string[];
+    clientId?: string;
+    clientSecret?: string;
+}
+/** Authentication configuration for a connector. */
+export interface AuthConfig {
+    type: AuthType;
+    oauth2?: OAuth2Config;
+    /** Human-readable instructions for obtaining credentials. */
+    instructions?: string;
+}
+/** Defines a single action that a connector can perform. */
+export interface ActionDefinition {
+    id: string;
+    name: string;
+    description: string;
+    /** Minimum trust level required to execute this action. */
+    trustMinimum: TrustLevel;
+    /** Trust domain this action operates in. */
+    trustDomain: TrustDomain;
+    /** Whether this action can be reversed/undone. */
+    reversible: boolean;
+    /** Whether this action has external side effects. */
+    sideEffects: boolean;
+    /** Parameter schema (JSON Schema-like). */
+    params: Record<string, ParamDefinition>;
+}
+/** Parameter definition for an action. */
+export interface ParamDefinition {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    description: string;
+    required?: boolean;
+    default?: unknown;
+}
+/** Defines a trigger that a connector can listen for. */
+export interface TriggerDefinition {
+    id: string;
+    name: string;
+    description: string;
+    /** How this trigger is detected. */
+    type: 'poll' | 'webhook';
+    /** Polling interval in ms (for poll triggers). */
+    pollIntervalMs?: number;
+}
+/** Defines an entity type that a connector exposes. */
+export interface EntityDefinition {
+    id: string;
+    name: string;
+    description: string;
+    /** Fields exposed by this entity. */
+    fields: Record<string, string>;
+}
+/** Full connector definition. */
+export interface Connector {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    category: string;
+    icon?: string;
+    auth: AuthConfig;
+    actions: ActionDefinition[];
+    triggers: TriggerDefinition[];
+    entities: EntityDefinition[];
+    /** Action handler called to execute actions. */
+    executeAction: (actionId: string, params: Record<string, unknown>, token: string) => Promise<unknown>;
+    /** Trigger poll handler. */
+    pollTrigger?: (triggerId: string, token: string, lastPollAt?: number) => Promise<TriggerEvent[]>;
+}
+/** Event emitted by a trigger. */
+export interface TriggerEvent {
+    triggerId: string;
+    connectorId: string;
+    data: Record<string, unknown>;
+    timestamp: number;
+}
+/** Stored token data for a connector instance. */
+export interface StoredToken {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    tokenType?: string;
+    scopes?: string[];
+}
+/** A configured instance of a connector with auth credentials. */
+export interface ConnectorInstance {
+    id: string;
+    connectorId: string;
+    label: string;
+    createdAt: number;
+    /** Whether auth is configured and valid. */
+    authenticated: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEjE,uDAAuD;AACvD,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEtD,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,YAAY,EAAE,UAAU,CAAC;IACzB,4CAA4C;IAC5C,WAAW,EAAE,WAAW,CAAC;IACzB,kDAAkD;IAClD,UAAU,EAAE,OAAO,CAAC;IACpB,qDAAqD;IACrD,WAAW,EAAE,OAAO,CAAC;IACrB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACzC;AAED,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,iCAAiC;AACjC,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,gDAAgD;IAChD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACtG,4BAA4B;IAC5B,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAClG;AAED,kCAAkC;AAClC,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,aAAa,EAAE,OAAO,CAAC;CACxB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@auxiora/connectors",
+  "version": "1.0.0",
+  "description": "Connector SDK, registry, auth manager, and action executor",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@auxiora/autonomy": "1.0.0",
+    "@auxiora/core": "1.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/auth-manager.ts

@@ -0,0 +1,177 @@
+import type { AuthConfig, StoredToken } from './types.js';
+
+const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
+
+export interface AuthManagerVault {
+  get(name: string): string | undefined;
+  has(name: string): boolean;
+  add(name: string, value: string): Promise<void>;
+}
+
+/** In-memory token store with vault-like interface for connector auth tokens. */
+export class AuthManager {
+  private tokens = new Map<string, StoredToken>();
+  private vault?: AuthManagerVault;
+
+  constructor(vault?: AuthManagerVault) {
+    this.vault = vault;
+  }
+
+  /** Authenticate a connector instance with the given credentials. */
+  async authenticate(
+    instanceId: string,
+    authConfig: AuthConfig,
+    credentials: Record<string, string>,
+  ): Promise<StoredToken> {
+    let token: StoredToken;
+
+    switch (authConfig.type) {
+      case 'oauth2': {
+        if (!credentials.accessToken) {
+          throw new Error('OAuth2 authentication requires an accessToken');
+        }
+        token = {
+          accessToken: credentials.accessToken,
+          refreshToken: credentials.refreshToken,
+          expiresAt: credentials.expiresAt ? parseInt(credentials.expiresAt, 10) : undefined,
+          tokenType: credentials.tokenType ?? 'Bearer',
+          scopes: authConfig.oauth2?.scopes,
+        };
+        break;
+      }
+      case 'api_key': {
+        if (!credentials.apiKey) {
+          throw new Error('API key authentication requires an apiKey');
+        }
+        token = {
+          accessToken: credentials.apiKey,
+          tokenType: 'api_key',
+        };
+        break;
+      }
+      case 'token': {
+        if (!credentials.token) {
+          throw new Error('Token authentication requires a token');
+        }
+        token = {
+          accessToken: credentials.token,
+          tokenType: 'Bearer',
+        };
+        break;
+      }
+      default:
+        throw new Error(`Unsupported auth type: ${authConfig.type as string}`);
+    }
+
+    this.tokens.set(instanceId, token);
+
+    // Persist tokens to vault if available
+    if (this.vault) {
+      await this.vault.add(`connectors.${instanceId}.tokens`, JSON.stringify(token));
+    }
+
+    return token;
+  }
+
+  /** Refresh an OAuth2 token for a connector instance. */
+  async refreshToken(
+    instanceId: string,
+    authConfig: AuthConfig,
+  ): Promise<StoredToken> {
+    const existing = this.tokens.get(instanceId);
+    if (!existing) {
+      throw new Error(`No token found for instance "${instanceId}"`);
+    }
+    if (authConfig.type !== 'oauth2') {
+      throw new Error('Token refresh is only supported for OAuth2');
+    }
+    if (!existing.refreshToken) {
+      throw new Error('No refresh token available');
+    }
+
+    // Load client credentials from vault
+    const credsJson = this.vault?.get(`connectors.${instanceId}.credentials`);
+    if (!credsJson) {
+      throw new Error(`No client credentials found for instance "${instanceId}"`);
+    }
+    const creds = JSON.parse(credsJson) as { clientId: string; clientSecret: string };
+
+    // Call Google's token endpoint to refresh
+    const body = new URLSearchParams({
+      client_id: creds.clientId,
+      client_secret: creds.clientSecret,
+      refresh_token: existing.refreshToken,
+      grant_type: 'refresh_token',
+    });
+
+    const response = await fetch(GOOGLE_TOKEN_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+    });
+
+    if (!response.ok) {
+      const errBody = await response.text();
+      throw new Error(`Token refresh failed: ${response.status} ${errBody}`);
+    }
+
+    const data = await response.json() as {
+      access_token: string;
+      refresh_token?: string;
+      expires_in?: number;
+      token_type?: string;
+    };
+
+    const refreshed: StoredToken = {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token ?? existing.refreshToken,
+      expiresAt: data.expires_in ? Date.now() + data.expires_in * 1000 : Date.now() + 3600_000,
+      tokenType: data.token_type ?? 'Bearer',
+      scopes: existing.scopes,
+    };
+
+    this.tokens.set(instanceId, refreshed);
+
+    // Persist updated tokens to vault
+    if (this.vault) {
+      await this.vault.add(`connectors.${instanceId}.tokens`, JSON.stringify(refreshed));
+    }
+
+    return refreshed;
+  }
+
+  /** Restore a token from vault into the in-memory store. */
+  restoreToken(instanceId: string, token: StoredToken): void {
+    this.tokens.set(instanceId, token);
+  }
+
+  /** Get the stored token for a connector instance. */
+  getToken(instanceId: string): StoredToken | undefined {
+    return this.tokens.get(instanceId);
+  }
+
+  /** Check if a token is expired. */
+  isTokenExpired(instanceId: string): boolean {
+    const token = this.tokens.get(instanceId);
+    if (!token || !token.expiresAt) return false;
+    return Date.now() >= token.expiresAt;
+  }
+
+  /** Revoke and remove a token for a connector instance. */
+  async revokeToken(instanceId: string): Promise<boolean> {
+    const deleted = this.tokens.delete(instanceId);
+    if (deleted && this.vault) {
+      try {
+        await this.vault.add(`connectors.${instanceId}.tokens`, '');
+      } catch {
+        // Best-effort vault cleanup
+      }
+    }
+    return deleted;
+  }
+
+  /** Check whether a connector instance has a stored token. */
+  hasToken(instanceId: string): boolean {
+    return this.tokens.has(instanceId);
+  }
+}

package/src/define-connector.ts

@@ -0,0 +1,45 @@
+import type { Connector, ActionDefinition, TriggerDefinition, EntityDefinition, AuthConfig, TriggerEvent } from './types.js';
+
+/** Options for defining a connector via the SDK helper. */
+export interface DefineConnectorOptions {
+  id: string;
+  name: string;
+  description: string;
+  version: string;
+  category: string;
+  icon?: string;
+  auth: AuthConfig;
+  actions: ActionDefinition[];
+  triggers?: TriggerDefinition[];
+  entities?: EntityDefinition[];
+  executeAction: (actionId: string, params: Record<string, unknown>, token: string) => Promise<unknown>;
+  pollTrigger?: (triggerId: string, token: string, lastPollAt?: number) => Promise<TriggerEvent[]>;
+}
+
+/** SDK helper to define a connector with validated structure. */
+export function defineConnector(options: DefineConnectorOptions): Connector {
+  if (!options.id || !options.name) {
+    throw new Error('Connector id and name are required');
+  }
+  if (!options.auth) {
+    throw new Error('Connector auth config is required');
+  }
+  if (!options.actions || options.actions.length === 0) {
+    throw new Error('Connector must define at least one action');
+  }
+
+  return {
+    id: options.id,
+    name: options.name,
+    description: options.description,
+    version: options.version,
+    category: options.category,
+    icon: options.icon,
+    auth: options.auth,
+    actions: options.actions,
+    triggers: options.triggers ?? [],
+    entities: options.entities ?? [],
+    executeAction: options.executeAction,
+    pollTrigger: options.pollTrigger,
+  };
+}

package/src/executor.ts

@@ -0,0 +1,108 @@
+import type { TrustGate } from '@auxiora/autonomy';
+import type { ActionAuditTrail } from '@auxiora/autonomy';
+import type { ConnectorRegistry } from './registry.js';
+import type { AuthManager } from './auth-manager.js';
+import type { TrustDomain, TrustLevel } from '@auxiora/autonomy';
+
+export interface ExecutionResult {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+  auditId?: string;
+}
+
+export class ActionExecutor {
+  private registry: ConnectorRegistry;
+  private authManager: AuthManager;
+  private trustGate: TrustGate;
+  private auditTrail: ActionAuditTrail;
+
+  constructor(
+    registry: ConnectorRegistry,
+    authManager: AuthManager,
+    trustGate: TrustGate,
+    auditTrail: ActionAuditTrail,
+  ) {
+    this.registry = registry;
+    this.authManager = authManager;
+    this.trustGate = trustGate;
+    this.auditTrail = auditTrail;
+  }
+
+  async execute(
+    connectorId: string,
+    actionId: string,
+    params: Record<string, unknown>,
+    instanceId: string,
+  ): Promise<ExecutionResult> {
+    const connector = this.registry.get(connectorId);
+    if (!connector) {
+      return { success: false, error: `Connector "${connectorId}" not found` };
+    }
+
+    const action = connector.actions.find((a) => a.id === actionId);
+    if (!action) {
+      return { success: false, error: `Action "${actionId}" not found in connector "${connectorId}"` };
+    }
+
+    // Check trust gate
+    const gateResult = this.trustGate.gate(
+      action.trustDomain,
+      `${connectorId}:${actionId}`,
+      action.trustMinimum,
+    );
+
+    if (!gateResult.allowed) {
+      const audit = await this.auditTrail.record({
+        trustLevel: gateResult.currentLevel,
+        domain: action.trustDomain,
+        intent: `${connectorId}:${actionId}`,
+        plan: JSON.stringify(params),
+        executed: false,
+        outcome: 'failure',
+        reasoning: gateResult.message,
+        rollbackAvailable: false,
+      });
+      return { success: false, error: gateResult.message, auditId: audit.id };
+    }
+
+    // Get token
+    const token = this.authManager.getToken(instanceId);
+    if (!token) {
+      return { success: false, error: `No authentication token for instance "${instanceId}"` };
+    }
+
+    // Execute
+    try {
+      const data = await connector.executeAction(actionId, params, token.accessToken);
+
+      const audit = await this.auditTrail.record({
+        trustLevel: gateResult.currentLevel,
+        domain: action.trustDomain,
+        intent: `${connectorId}:${actionId}`,
+        plan: JSON.stringify(params),
+        executed: true,
+        outcome: 'success',
+        reasoning: gateResult.message,
+        rollbackAvailable: action.reversible,
+      });
+
+      return { success: true, data, auditId: audit.id };
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : 'Unknown error';
+
+      const audit = await this.auditTrail.record({
+        trustLevel: gateResult.currentLevel,
+        domain: action.trustDomain,
+        intent: `${connectorId}:${actionId}`,
+        plan: JSON.stringify(params),
+        executed: true,
+        outcome: 'failure',
+        reasoning: msg,
+        rollbackAvailable: false,
+      });
+
+      return { success: false, error: msg, auditId: audit.id };
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export type {
+  AuthType,
+  OAuth2Config,
+  AuthConfig,
+  ActionDefinition,
+  ParamDefinition,
+  TriggerDefinition,
+  EntityDefinition,
+  Connector,
+  TriggerEvent,
+  StoredToken,
+  ConnectorInstance,
+} from './types.js';
+export { ConnectorRegistry } from './registry.js';
+export { AuthManager } from './auth-manager.js';
+export { ActionExecutor, type ExecutionResult } from './executor.js';
+export { TriggerManager, type TriggerHandler } from './trigger-manager.js';
+export { defineConnector, type DefineConnectorOptions } from './define-connector.js';

package/src/registry.ts

@@ -0,0 +1,42 @@
+import type { Connector, ActionDefinition, TriggerDefinition } from './types.js';
+
+export class ConnectorRegistry {
+  private connectors = new Map<string, Connector>();
+
+  register(connector: Connector): void {
+    if (this.connectors.has(connector.id)) {
+      throw new Error(`Connector "${connector.id}" is already registered`);
+    }
+    this.connectors.set(connector.id, connector);
+  }
+
+  get(id: string): Connector | undefined {
+    return this.connectors.get(id);
+  }
+
+  list(): Connector[] {
+    return [...this.connectors.values()];
+  }
+
+  listByCategory(category: string): Connector[] {
+    return [...this.connectors.values()].filter((c) => c.category === category);
+  }
+
+  getActions(connectorId: string): ActionDefinition[] {
+    const connector = this.connectors.get(connectorId);
+    return connector ? connector.actions : [];
+  }
+
+  getTriggers(connectorId: string): TriggerDefinition[] {
+    const connector = this.connectors.get(connectorId);
+    return connector ? connector.triggers : [];
+  }
+
+  has(id: string): boolean {
+    return this.connectors.has(id);
+  }
+
+  unregister(id: string): boolean {
+    return this.connectors.delete(id);
+  }
+}