autohive_integrations_sdk.integration

  1"""Autohive Integrations SDK — core module.
  2
  3Provides the building blocks for creating Autohive integrations:
  4
  5- `Integration` — load config and register action/trigger/connected-account handlers
  6- `ExecutionContext` — authenticated HTTP client passed to every handler
  7- `ActionHandler` — base class for action implementations (return `ActionResult`)
  8- `ConnectedAccountHandler` — base class for connected-account lookups (return `ConnectedAccountInfo`)
  9- `ActionResult` — standard return type wrapping action output data and optional billing cost
 10- `ActionError` — return type for expected application-level errors (bypasses output schema validation)
 11- `FetchResponse` — response object from ``context.fetch()`` with ``.status``, ``.headers``, and ``.data``
 12- `ConnectedAccountInfo` — structured account info returned by connected-account handlers
 13- `HTTPError` / `RateLimitError` — exceptions raised by ``context.fetch()`` for non-2xx responses
 14
 15Typical usage::
 16
 17    from autohive_integrations_sdk import Integration, ActionHandler, ActionResult, ExecutionContext
 18
 19    integration = Integration.load()
 20
 21    @integration.action("my_action")
 22    class MyAction(ActionHandler):
 23        async def execute(self, inputs, context):
 24            response = await context.fetch("https://api.example.com/resource")
 25            return ActionResult(data=response.data)
 26"""
 27
 28# Standard Library Imports
 29from abc import ABC, abstractmethod
 30import asyncio
 31from dataclasses import dataclass, field, asdict
 32from datetime import timedelta
 33from enum import Enum
 34import json
 35import json as jsonX  # Keep alias to avoid conflict with 'json' parameter in fetch
 36import logging
 37import os
 38import sys
 39from pathlib import Path
 40from typing import Dict, Any, List, Optional, Union, Type, TypeVar, Generic, ClassVar
 41from urllib.parse import urlencode
 42
 43# Third-Party Imports
 44import aiohttp
 45from jsonschema import validate, Draft7Validator
 46
 47
 48# Local Imports
 49from autohive_integrations_sdk import __version__
 50
 51
 52# ---- Type Definitions ----
 53T = TypeVar('T')
 54
 55# ---- Auth Types ----
 56class AuthType(Enum):
 57    """Authentication strategy used by an integration.
 58
 59    The platform stores the auth type alongside credentials and passes both
 60    to ``ExecutionContext``.  ``context.fetch()`` uses the type to decide
 61    whether to auto-inject an ``Authorization`` header.
 62
 63    Members:
 64        PlatformOauth2: Platform-managed OAuth 2.0 — the platform handles the
 65            token lifecycle and injects ``Bearer <access_token>`` automatically.
 66        PlatformTeams: Platform-managed Microsoft Teams auth.
 67        ApiKey: A single API key provided by the user.
 68        Basic: Username/password (HTTP Basic) credentials.
 69        Custom: Free-form credential fields defined by the integration's
 70            ``config.json`` auth schema.  The integration is responsible for
 71            reading individual fields from ``context.auth``.
 72    """
 73    PlatformOauth2 = "PlatformOauth2"
 74    PlatformTeams = "PlatformTeams"
 75    ApiKey = "ApiKey"
 76    Basic = "Basic"
 77    Custom = "Custom"
 78
 79class ResultType(Enum):
 80    """Type of result being returned"""
 81    ACTION = "action"
 82    ACTION_ERROR = "action_error"
 83    CONNECTED_ACCOUNT = "connected_account"
 84    ERROR = "error"
 85    VALIDATION_ERROR = "validation_error"
 86
 87# ---- Exceptions ----
 88class ValidationError(Exception):
 89    """Raised when SDK validation fails.
 90
 91    This covers several cases:
 92
 93    - Action inputs don't match the ``input_schema`` in ``config.json``
 94    - Action outputs don't match the ``output_schema``
 95    - Auth credentials don't match the ``auth.fields`` schema
 96    - An action handler returns something other than ``ActionResult``
 97    - A handler name isn't registered
 98    """
 99    def __init__(self, message: str, schema: str = None, inputs: str = None, source: str = "legacy"):
100        self.schema = schema
101        """The schema that failed validation"""
102        self.inputs = inputs
103        """The data that failed validation"""
104        self.message = message
105        """The error message"""
106        self.source = source
107        """Where the validation failed: 'input', 'output', 'auth', or 'legacy' (pre-versioning default)"""
108        super().__init__(message)
109
110class ConfigurationError(Exception):
111    """Raised when integration configuration is invalid"""
112    pass
113
114class HTTPError(Exception):
115    """Raised by ``ExecutionContext.fetch()`` for non-2xx HTTP responses (except 429)."""
116    def __init__(self, status: int, message: str, response_data: Any = None):
117        self.status = status
118        """Status code"""
119        self.message = message
120        """Error message"""
121        self.response_data = response_data
122        """Response data"""
123        super().__init__(f"HTTP {status}: {message}")
124
125class RateLimitError(HTTPError):
126    """Raised by ``ExecutionContext.fetch()`` on HTTP 429 (Too Many Requests).
127
128    Attributes:
129        retry_after: Seconds to wait before retrying, taken from the
130            ``Retry-After`` response header (defaults to 60 if absent).
131    """
132    def __init__(self, retry_after: int, *args, **kwargs):
133        self.retry_after = retry_after
134        """Seconds to wait before retrying."""
135        super().__init__(*args, **kwargs)
136
137# ---- Result Classes ----
138@dataclass
139class FetchResponse:
140    """Response object returned by ``ExecutionContext.fetch()``.
141
142    Wraps the full HTTP response so callers can inspect status codes and
143    headers in addition to the parsed body.
144
145    Attributes:
146        status: HTTP status code (e.g. ``200``, ``201``).
147        headers: Response headers as a plain ``dict``.
148        data: Parsed JSON (``dict``/``list``) when the response is
149            ``application/json``, otherwise the raw response text.
150            ``None`` for empty 200/201/204 responses.
151    """
152    status: int
153    headers: Dict[str, str]
154    data: Any
155
156@dataclass
157class ActionResult:
158    """Result returned by action handlers.
159
160    This class encapsulates the data returned by an action along with optional
161    billing information for cost tracking.
162
163    Args:
164        data: The actual result data from the action
165        cost_usd: Optional USD cost for billing purposes
166
167    Example:
168        ```python
169        return ActionResult(
170            data={"message": "Success", "result": 42},
171            cost_usd=0.05
172        )
173        ```
174    """
175    data: Any
176    cost_usd: Optional[float] = None
177
178@dataclass
179class ActionError:
180    """Error result returned by action handlers for expected/application-level errors.
181
182    When returned from an action handler, output schema validation is skipped
183    and the error is returned to the caller as a ResultType.ERROR result.
184
185    Args:
186        message: Human-readable error message
187        cost_usd: Optional USD cost incurred before the error occurred
188
189    Example:
190        ```python
191        return ActionError(
192            message="User not found",
193            cost_usd=0.01
194        )
195        ```
196    """
197    message: str
198    cost_usd: Optional[float] = None
199
200@dataclass
201class ConnectedAccountInfo:
202    """Account metadata returned by a ``ConnectedAccountHandler``.
203
204    The platform calls the connected-account handler after a user links
205    their external account.  The returned info is displayed in the
206    Autohive UI (avatar, name, email, etc.).
207
208    All fields are optional — populate whichever ones the external API provides.
209    """
210    email: Optional[str] = None
211    first_name: Optional[str] = None
212    last_name: Optional[str] = None
213    username: Optional[str] = None
214    user_id: Optional[str] = None
215    avatar_url: Optional[str] = None
216    organization: Optional[str] = None
217
218@dataclass
219class IntegrationResult:
220    """Result format sent from lambda wrapper to backend.
221
222    This class represents the standardized format that the lambda wrapper
223    sends to the Autohive backend, including SDK version and type-specific data.
224
225    Args:
226        version: SDK version (auto-populated)
227        type: Type of result payload (ResultType enum: ACTION, CONNECTED_ACCOUNT, ERROR)
228        result: The result object - ActionResult for actions, ActionError for
229                application-level action errors, or ConnectedAccountInfo for
230                connected accounts.
231                The lambda wrapper serializes these to dicts using asdict().
232
233    Note:
234        This type is returned by Integration methods and serialized by the lambda wrapper.
235        Integration developers should use ActionResult for action handlers and
236        ActionError for expected error conditions.
237    """
238    version: str
239    type: ResultType
240    result: Union[ActionResult, ActionError, ConnectedAccountInfo]
241
242# ---- Configuration Classes ----
243
244@dataclass
245class Parameter:
246    """Definition of a parameter"""
247    name: str
248    type: str
249    description: str
250    enum: Optional[List[str]] = None
251    required: bool = True
252    default: Any = None
253
254@dataclass
255class SchemaDefinition:
256    """Base class for components that have input/output schemas"""
257    name: str
258    description: str
259    input_schema: List[Parameter]
260    output_schema: Optional[Dict[str, Any]] = None
261
262@dataclass
263class Action(SchemaDefinition):
264    """Empty dataclass that inherits from SchemaDefinition"""
265    pass
266
267@dataclass
268class PollingTrigger(SchemaDefinition):
269    """Definition of a polling trigger"""
270    polling_interval: timedelta = field(default_factory=timedelta)
271
272@dataclass
273class IntegrationConfig:
274    """Configuration for an integration"""
275    name: str
276    version: str
277    description: str
278    auth: Dict[str, Any]
279    actions: Dict[str, Action]
280    polling_triggers: Dict[str, PollingTrigger]
281
282# ---- Base Handler Classes ----
283class ActionHandler(ABC):
284    """Base class for action handlers.
285
286    Subclass this and implement ``execute()`` to handle a specific action.
287    Register it with the ``@integration.action("action_name")`` decorator.
288
289    Example::
290
291        @integration.action("get_user")
292        class GetUser(ActionHandler):
293            async def execute(self, inputs, context):
294                user = (await context.fetch(f"https://api.example.com/users/{inputs['id']}")).data
295                return ActionResult(data=user)
296    """
297    @abstractmethod
298    async def execute(self, inputs: Dict[str, Any], context: 'ExecutionContext') -> Any:
299        """Run the action logic.
300
301        Args:
302            inputs: Validated action inputs matching the ``input_schema`` from ``config.json``.
303            context: Execution context providing ``fetch()``, ``auth``, and logging.
304
305        Returns:
306            An ``ActionResult`` containing the output data and optional ``cost_usd``.
307        """
308        pass
309
310class PollingTriggerHandler(ABC):
311    """Base class for polling trigger handlers"""
312    @abstractmethod
313    async def poll(self, inputs: Dict[str, Any], last_poll_ts: Optional[str], context: 'ExecutionContext') -> List[Dict[str, Any]]:
314        """Execute the polling trigger"""
315        pass
316
317class ConnectedAccountHandler(ABC):
318    """Base class for connected-account handlers.
319
320    The platform calls this after a user links their external account.
321    The returned ``ConnectedAccountInfo`` is shown in the Autohive UI.
322
323    Register with the ``@integration.connected_account()`` decorator.
324
325    Example::
326
327        @integration.connected_account()
328        class MyAccountHandler(ConnectedAccountHandler):
329            async def get_account_info(self, context):
330                me = (await context.fetch("https://api.example.com/me")).data
331                return ConnectedAccountInfo(
332                    email=me["email"],
333                    first_name=me["first_name"],
334                    last_name=me["last_name"],
335                )
336    """
337    @abstractmethod
338    async def get_account_info(self, context: 'ExecutionContext') -> ConnectedAccountInfo:
339        """Fetch account metadata from the external service.
340
341        For platform OAuth integrations, ``context.fetch()`` auto-injects
342        the Bearer token — no manual auth handling needed.
343
344        Returns:
345            A ``ConnectedAccountInfo`` with whichever fields the API provides.
346        """
347        pass
348
349# ---- Core SDK Classes ----
350class ExecutionContext:
351    """Context provided to integration handlers for making authenticated HTTP requests.
352
353    Manages an ``aiohttp`` session with automatic retries, error handling, and
354    optional Bearer-token injection for platform OAuth integrations.
355
356    Use as an async context manager::
357
358        async with ExecutionContext(auth=auth) as context:
359            result = await integration.execute_action("my_action", inputs, context)
360
361    Args:
362        auth: Authentication data.  This is always the platform auth envelope
363            ``{"auth_type": "...", "credentials": {...}}``.  The ``credentials``
364            object matches the ``auth.fields`` schema in ``config.json``.  Local
365            tests must use the same wrapped shape (e.g.
366            ``{"auth_type": "Custom", "credentials": {"api_key": "..."}}``); flat
367            auth is not supported.  Handlers should read
368            individual credentials via ``context.auth["credentials"]`` (for
369            example ``context.auth["credentials"].get("api_key", "")``); strict
370            validation guarantees this shape exists before a handler runs.
371        request_config: Override default ``max_retries`` (3) and ``timeout`` (30 s).
372        metadata: Arbitrary metadata forwarded to handlers.
373        logger: Custom logger; falls back to ``logging.getLogger(__name__)``.
374    """
375    def __init__(
376        self,
377        auth: Dict[str, Any] = {}, 
378        request_config: Optional[Dict[str, Any]] = None,
379        metadata: Optional[Dict[str, Any]] = None,
380        logger: Optional[logging.Logger] = None
381    ):
382        self.auth = auth
383        """Authentication configuration"""
384        self.config = request_config or {"max_retries": 3, "timeout": 30}
385        """Request configuration"""
386        self.metadata = metadata or {}
387        """Additional metadata"""
388        self.logger = logger or logging.getLogger(__name__)
389        """Logger instance"""
390        self._session: Optional[aiohttp.ClientSession] = None
391
392    async def __aenter__(self):
393        if not self._session:
394            self._session = aiohttp.ClientSession()
395        return self
396
397    async def __aexit__(self, exc_type, exc_val, exc_tb):
398        if self._session:
399            await self._session.close()
400            self._session = None
401
402    async def fetch(
403            self,
404            url: str,
405            method: str = "GET",
406            params: Optional[Dict[str, Any]] = None,
407            data: Any = None,
408            json: Any = None,
409            headers: Optional[Dict[str, str]] = None,
410            content_type: Optional[str] = None,
411            timeout: Optional[int] = None,
412            retry_count: int = 0
413    ) -> FetchResponse:
414        """Make an HTTP request with automatic retries and error handling.
415
416        For **platform OAuth** integrations (``auth_type == "PlatformOauth2"``),
417        a ``Bearer`` token is auto-injected from ``auth.credentials.access_token``
418        unless an ``Authorization`` header is explicitly provided.
419
420        Retries up to ``max_retries`` (default 3) on transient network errors
421        with exponential back-off.  HTTP 429 responses raise ``RateLimitError``
422        immediately (no automatic retry).
423
424        Args:
425            url: The URL to request.
426            method: HTTP method (``"GET"``, ``"POST"``, ``"PUT"``, etc.).
427            params: Query parameters appended to the URL.  Nested dicts/lists
428                are JSON-serialized automatically.
429            data: Raw request body.  Encoding depends on ``content_type``.
430            json: JSON-serializable payload.  Sets ``content_type`` to
431                ``application/json`` automatically.
432            headers: Additional HTTP headers.  Merged *after* any auto-injected
433                auth header, so an explicit ``Authorization`` takes precedence.
434            content_type: ``Content-Type`` header value.
435            timeout: Per-request timeout in seconds (overrides ``request_config``).
436            retry_count: Internal — current retry attempt number.
437
438        Returns:
439            A ``FetchResponse`` containing the HTTP status code, response
440            headers, and parsed body data.
441
442        Raises:
443            RateLimitError: On HTTP 429 with the ``Retry-After`` value.
444            HTTPError: On any other non-2xx status.
445        """
446        if not self._session:
447            self._session = aiohttp.ClientSession()
448
449        # Prepare request
450        if json is not None:
451            data = json
452            content_type = "application/json"
453
454        final_headers = {}
455        
456        if self.auth and "Authorization" not in (headers or {}):
457            auth_type = AuthType(self.auth.get("auth_type", "PlatformOauth2"))
458            credentials = self.auth.get("credentials", {})
459            
460            if auth_type == AuthType.PlatformOauth2 and "access_token" in credentials:
461                final_headers["Authorization"] = f"Bearer {credentials['access_token']}"
462
463        if content_type:
464            final_headers["Content-Type"] = content_type
465        if headers:
466            final_headers.update(headers)
467
468        if params:
469            # Handle nested dictionary parameters
470            flat_params = {}
471            for key, value in params.items():
472                if isinstance(value, (dict, list)):
473                    flat_params[key] = jsonX.dumps(value)
474                elif value is not None:
475                    flat_params[key] = str(value)
476            query_string = urlencode(flat_params)
477            url = f"{url}{'&' if '?' in url else '?'}{query_string}"
478
479        # Prepare body
480        if data is not None:
481            if content_type == "application/json":
482                data = jsonX.dumps(data)
483            elif content_type == "application/x-www-form-urlencoded":
484                data = urlencode(data) if isinstance(data, dict) else data
485
486        # Store the original timeout numeric value
487        original_timeout = timeout or self.config["timeout"]
488
489        # Convert the numeric timeout to a ClientTimeout instance for this request
490        client_timeout = aiohttp.ClientTimeout(total=original_timeout)
491
492        try:
493            async with self._session.request(
494                method=method,
495                url=url,
496                data=data,
497                headers=final_headers,
498                timeout=client_timeout,
499                ssl=True
500            ) as response:
501                content_type = response.headers.get("Content-Type", "")
502
503                if response.status == 429:  # Rate limit
504                    retry_after = int(response.headers.get("Retry-After", 60))
505                    raise RateLimitError(
506                        retry_after,
507                        response.status,
508                        "Rate limit exceeded",
509                        await response.text()
510                    )
511
512                try:
513                    if "application/json" in content_type:
514                        result = await response.json()
515                    else:
516                        result = await response.text()
517                        if not result and response.status in {200, 201, 204}:
518                            result = None
519                except Exception as e:
520                    self.logger.error(f"Error parsing response: {e}")
521                    result = await response.text()
522
523                response_headers = dict(response.headers)
524
525                if not response.ok:
526                    print(f"HTTP error encountered. Status: {response.status}. Result: {result}")
527                    raise HTTPError(response.status, str(result), result)
528
529                return FetchResponse(
530                    status=response.status,
531                    headers=response_headers,
532                    data=result,
533                )
534
535        except RateLimitError:
536            raise
537        except (aiohttp.ClientError, asyncio.TimeoutError) as e:
538            # Don't want to send this to Raygun here because this will be retried.
539            print(f"Error encountered: {e}. Retry count: {retry_count}. Backing off.")
540            if retry_count < self.config["max_retries"]:
541                await asyncio.sleep(2 ** retry_count)  # Exponential backoff
542                print("Retrying request...")
543                # Use original_timeout (numeric) for recursive calls
544                return await self.fetch(
545                    url, method, params, data, json,
546                    headers, content_type, original_timeout, retry_count + 1
547                )
548            else:
549                print("Max retries reached. Raising error.")
550                raise
551        except Exception as e:
552            self.logger.error(f"Unexpected error during {method} {url}: {e}")
553            print(f"Unexpected error encountered: {e}")
554            raise
555
556
557class Integration:
558    """Base integration class with handler registration and execution.
559    
560    This class manages the integration configuration, handler registration,
561    and provides methods to execute actions and triggers.
562    
563    Args:
564        config: Integration configuration
565        
566    Attributes:
567        config: Integration configuration
568    """
569
570    def __init__(self, config: IntegrationConfig):
571        self.config = config
572        """Integration configuration"""
573        self._action_handlers: Dict[str, Type[ActionHandler]] = {}
574        """Action handlers"""
575        self._polling_handlers: Dict[str, Type[PollingTriggerHandler]] = {}
576        """Polling handlers"""
577        self._connected_account_handler: Optional[Type[ConnectedAccountHandler]] = None
578        """Connected account handler"""
579
580    @classmethod
581    def load(cls, config_path: Union[str, Path] = None) -> 'Integration':
582        """Load an integration from its ``config.json``.
583
584        Args:
585            config_path: Explicit path to ``config.json``.  When omitted the
586                SDK resolves the path relative to its own package location,
587                which works when the SDK is vendored via
588                ``pip install --target dependencies``.  Multi-file integrations
589                that use ``actions/`` sub-packages should pass an explicit path
590                (e.g. ``Integration.load("config.json")``).
591
592        Returns:
593            A fully initialised ``Integration`` ready for handler registration.
594
595        Raises:
596            ConfigurationError: If the file is missing or contains invalid JSON.
597        """
598        if config_path is None:
599            config_path = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), 'config.json')
600        
601        config_path = Path(config_path)
602
603        if not config_path.exists():
604            raise ConfigurationError(f"Configuration file not found: {config_path}")
605
606        try:
607            with open(config_path, 'r') as f:
608                config_data = json.load(f)
609        except json.JSONDecodeError as e:
610            raise ConfigurationError(f"Invalid JSON configuration: {e}")
611        
612        # Parse configuration sections
613        actions = cls._parse_actions(config_data.get("actions", {}))
614        polling_triggers = cls._parse_polling_triggers(config_data.get("polling_triggers", {}))
615
616        config = IntegrationConfig(
617            name=config_data["name"],
618            version=config_data["version"],
619            description=config_data["description"],
620            auth=config_data.get("auth", {}),
621            actions=actions,
622            polling_triggers=polling_triggers
623        )
624
625        return cls(config)
626
627    @staticmethod
628    def _parse_interval(interval_str: str) -> timedelta:
629        """Parse interval string into timedelta"""
630        unit = interval_str[-1].lower()
631        value = int(interval_str[:-1])
632
633        if unit == 's':
634            return timedelta(seconds=value)
635        elif unit == 'm':
636            return timedelta(minutes=value)
637        elif unit == 'h':
638            return timedelta(hours=value)
639        elif unit == 'd':
640            return timedelta(days=value)
641        else:
642            raise ConfigurationError(f"Invalid interval format: {interval_str}")
643
644    @classmethod
645    def _parse_actions(cls, actions_config: Dict[str, Any]) -> Dict[str, Action]:
646        """Parse action configurations"""
647        actions = {}
648        for name, data in actions_config.items():
649            actions[name] = Action(
650                name=name,
651                description=data["description"],
652                input_schema=data["input_schema"],
653                output_schema=data["output_schema"]
654            )
655
656        return actions
657
658    @classmethod
659    def _parse_polling_triggers(cls, triggers_config: Dict[str, Any]) -> Dict[str, PollingTrigger]:
660        """Parse polling trigger configurations"""
661        triggers = {}
662        for name, data in triggers_config.items():
663            interval = cls._parse_interval(data["polling_interval"])
664
665            triggers[name] = PollingTrigger(
666                name=name,
667                description=data["description"],
668                polling_interval=interval,
669                input_schema=data["input_schema"],
670                output_schema=data["output_schema"]
671            )
672
673        return triggers
674
675    def action(self, name: str):
676        """Decorator to register an action handler.
677        
678        Args:
679            name: Name of the action to register
680            
681        Returns:
682            Decorator function
683            
684        Raises:
685            ConfigurationError: If action is not defined in config
686            
687        Example:
688            ```python
689            @integration.action("my_action")
690            class MyActionHandler(ActionHandler):
691                async def execute(self, inputs, context):
692                    # Implementation
693                    return result
694            ```
695        """
696        def decorator(handler_class: Type[ActionHandler]):
697            if name not in self.config.actions:
698                raise ConfigurationError(f"Action '{name}' not defined in config")
699            self._action_handlers[name] = handler_class
700            return handler_class
701        return decorator
702
703    def polling_trigger(self, name: str):
704        """Decorator to register a polling trigger handler
705        
706        Args:
707            name: Name of the polling trigger to register
708            
709        Returns:
710            Decorator function
711        
712        Raises:
713            ConfigurationError: If polling trigger is not defined in config
714
715        Example:
716            ```python
717            @integration.polling_trigger("my_polling_trigger")
718            class MyPollingTriggerHandler(PollingTriggerHandler):
719                async def poll(self, inputs, last_poll_ts, context):
720                    # Implementation
721                    return result
722            ```
723        """
724        def decorator(handler_class: Type[PollingTriggerHandler]):
725            if name not in self.config.polling_triggers:
726                raise ConfigurationError(f"Polling trigger '{name}' not defined in config")
727            self._polling_handlers[name] = handler_class
728            return handler_class
729        return decorator
730
731    def connected_account(self):
732        """Decorator to register a connected account handler
733        
734        Returns:
735            Decorator function
736
737        Example:
738            ```python
739            @integration.connected_account()
740            class MyConnectedAccountHandler(ConnectedAccountHandler):
741                async def get_account_info(self, context):
742                    # Implementation
743                    return {"email": "user@example.com", "name": "John Doe"}
744            ```
745        """
746        def decorator(handler_class: Type[ConnectedAccountHandler]):
747            self._connected_account_handler = handler_class
748            return handler_class
749        return decorator
750
751    def _validate_auth(self, context: ExecutionContext) -> None:
752        """Validate the auth envelope's credentials against ``auth.fields``.
753
754        The platform always passes ``context.auth`` as the
755        wrapped envelope ``{"auth_type": ..., "credentials": {...}}``.  The
756        ``auth.fields`` schema in ``config.json`` describes only the inner
757        ``credentials`` object, so validation runs against
758        ``context.auth["credentials"]`` — not the whole envelope.
759
760        Integrations with no auth or no ``fields`` key skip validation entirely.
761
762        Raises:
763            ValidationError: (source ``"auth"``) if ``context.auth`` is not a
764                wrapped envelope (a dict with a non-empty string ``auth_type``
765                and a dict ``credentials``), or if the credentials fail the
766                schema.
767        """
768        if "fields" not in self.config.auth:
769            return
770
771        auth = context.auth
772        has_valid_credentials = isinstance(auth, dict) and isinstance(auth.get("credentials"), dict)
773        has_valid_auth_type = (
774            isinstance(auth, dict)
775            and isinstance(auth.get("auth_type"), str)
776            and auth.get("auth_type") != ""
777        )
778        if not has_valid_credentials or not has_valid_auth_type:
779            raise ValidationError(
780                'context.auth must be the platform auth envelope '
781                '{"auth_type": ..., "credentials": {...}} with a non-empty '
782                'auth_type; flat auth is not supported.',
783                source="auth",
784            )
785
786        valid_auth_types = {member.value for member in AuthType}
787        if auth["auth_type"] not in valid_auth_types:
788            raise ValidationError(
789                f'Unknown auth_type "{auth["auth_type"]}" in context.auth; '
790                f'expected one of: {", ".join(sorted(valid_auth_types))}.',
791                source="auth",
792            )
793
794        auth_config = self.config.auth["fields"]
795        validator = Draft7Validator(auth_config)
796        errors = sorted(validator.iter_errors(context.auth["credentials"]), key=lambda e: e.path)
797        if errors:
798            message = ""
799            for error in errors:
800                message += f"{list(error.schema_path)}, {error.message},\n "
801            raise ValidationError(message, auth_config, context.auth["credentials"], source="auth")
802
803    async def execute_action(self,
804                           name: str,
805                           inputs: Dict[str, Any],
806                           context: ExecutionContext) -> IntegrationResult:
807        """Execute a registered action.
808
809        Args:
810            name: Name of the action to execute
811            inputs: Action inputs
812            context: Execution context
813
814        Returns:
815            IntegrationResult with action data (ResultType.ACTION),
816            action error (ResultType.ACTION_ERROR) if the handler returned ActionError,
817            or validation error (ResultType.VALIDATION_ERROR) if schema validation fails.
818        """
819        try:
820            if name not in self._action_handlers:
821                raise ValidationError(f"Action '{name}' not registered")
822
823            # Validate inputs against action schema
824            action_config = self.config.actions[name]
825            validator = Draft7Validator(action_config.input_schema)
826            errors = sorted(validator.iter_errors(inputs), key=lambda e: e.path)
827            if errors:
828                message = ""
829                for error in errors:
830                    message += f"{list(error.schema_path)}, {error.message},\n "
831                raise ValidationError(message, action_config.input_schema, inputs, source="input")
832
833            self._validate_auth(context)
834
835            # Create handler instance and execute
836            handler = self._action_handlers[name]()
837            result = await handler.execute(inputs, context)
838
839            # Handle ActionError - skip output schema validation
840            if isinstance(result, ActionError):
841                return IntegrationResult(
842                    version=__version__,
843                    type=ResultType.ACTION_ERROR,
844                    result=result
845                )
846
847            # Validate that result is ActionResult
848            if not isinstance(result, ActionResult):
849                raise ValidationError(
850                    f"Action handler '{name}' must return ActionResult or ActionError, got {type(result).__name__}",
851                    source="output"
852                )
853
854            # Validate output schema against the data inside ActionResult
855            validator = Draft7Validator(action_config.output_schema)
856            errors = sorted(validator.iter_errors(result.data), key=lambda e: e.path)
857            if errors:
858                message = ""
859                for error in errors:
860                    message += f"{list(error.schema_path)}, {error.message},\n "
861                raise ValidationError(message, action_config.output_schema, result.data, source="output")
862
863            # Return IntegrationResult with ActionResult directly
864            return IntegrationResult(
865                version=__version__,
866                type=ResultType.ACTION,
867                result=result
868            )
869        except ValidationError as e:
870            return IntegrationResult(
871                version=__version__,
872                type=ResultType.VALIDATION_ERROR,
873                result={
874                    'message': str(e),
875                    'property': None,
876                    'value': None,
877                    'source': getattr(e, 'source', 'legacy')
878                }
879            )
880
881    async def execute_polling_trigger(self,
882                                    name: str,
883                                    inputs: Dict[str, Any],
884                                    last_poll_ts: Optional[str],
885                                    context: ExecutionContext) -> List[Dict[str, Any]]:
886        """Execute a registered polling trigger
887        
888        Args:
889            name: Name of the polling trigger to execute
890            inputs: Trigger inputs
891            last_poll_ts: Last poll timestamp
892            context: Execution context
893            
894        Returns:
895            List of records
896            
897        Raises:
898            ValidationError: If inputs or outputs don't match schema
899        """
900        if name not in self._polling_handlers:
901            raise ValidationError(f"Polling trigger '{name}' not registered")
902
903        # Validate trigger configuration
904        trigger_config = self.config.polling_triggers[name]
905        try:
906            validate(inputs, trigger_config.input_schema)
907        except Exception as e:
908            raise ValidationError(e.message, e.schema, e.instance)
909
910        self._validate_auth(context)
911
912        # Create handler instance and execute
913        handler = self._polling_handlers[name]()
914        records = await handler.poll(inputs, last_poll_ts, context)
915        # Validate each record
916        for record in records:
917            if "id" not in record:
918                raise ValidationError(
919                    f"Polling trigger '{name}' returned record without required 'id' field")
920            if "data" not in record:
921                raise ValidationError(
922                    f"Polling trigger '{name}' returned record without required 'data' field")
923
924            # Validate record data against output schema
925            try:
926                validate(record["data"], trigger_config.output_schema)
927            except Exception as e:
928                raise ValidationError(e.message, e.schema, e.instance)
929            
930        return records
931
932    async def get_connected_account(self, context: ExecutionContext) -> IntegrationResult:
933        """Get connected account information
934
935        Args:
936            context: Execution context
937
938        Returns:
939            IntegrationResult containing connected account data
940
941        Raises:
942            ValidationError: If no connected account handler is registered or auth is invalid
943        """
944        if not self._connected_account_handler:
945            raise ValidationError("No connected account handler registered")
946
947        self._validate_auth(context)
948
949        handler = self._connected_account_handler()
950        account_info = await handler.get_account_info(context)
951
952        if not isinstance(account_info, ConnectedAccountInfo):
953            raise ValidationError(
954                f"Connected account handler must return ConnectedAccountInfo, got {type(account_info).__name__}"
955            )
956
957        # Return IntegrationResult with ConnectedAccountInfo object directly
958        return IntegrationResult(
959            version=__version__,
960            type=ResultType.CONNECTED_ACCOUNT,
961            result=account_info
962        )