airbyte-agent-zendesk-support 0.18.18__py3-none-any.whl → 0.18.51__py3-none-any.whl

airbyte_agent_zendesk_support/_vendored/connector_sdk/http/response.py

@@ -80,6 +80,8 @@ class HTTPResponse:
             HTTPStatusError: For 4xx or 5xx status codes.
         """
         if 400 <= self._status_code < 600:
+            # NOTE: Import here intentionally to avoid circular import.
+            # exceptions.py imports HTTPResponse for type hints.
             from .exceptions import HTTPStatusError
 
             raise HTTPStatusError(

airbyte_agent_zendesk_support/_vendored/connector_sdk/http_client.py

@@ -147,6 +147,9 @@ class HTTPClient:
             self.base_url = self.base_url.replace(f"{{{var_name}}}", var_value)
 
         self.auth_config = auth_config
+        assert (
+            self.auth_config.type is not None
+        ), "auth_config.type cannot be None"  # Should never be None when instantiated via the local executor flow
         self.secrets = secrets
         self.logger = logger or NullLogger()
         self.metrics = HTTPMetrics()
@@ -296,12 +299,12 @@ class HTTPClient:
 
                         # Support both sync and async callbacks
                         callback_result = self.on_token_refresh(callback_data)
-                        if hasattr(callback_result, "__await__"):
+                        if callback_result is not None and hasattr(callback_result, "__await__"):
                             await callback_result
                     except Exception as callback_error:
                         self.logger.log_error(
                             request_id=None,
-                            error=("Token refresh callback failed during initialization: " f"{callback_error!s}"),
+                            error=(f"Token refresh callback failed during initialization: {callback_error!s}"),
                             status_code=None,
                         )
 
@@ -418,10 +421,14 @@ class HTTPClient:
         headers: dict[str, str] | None = None,
         *,
         stream: bool = False,
-    ):
+    ) -> tuple[dict[str, Any], dict[str, str]]:
         """Execute a single HTTP request attempt (no retries).
 
         This is the core request logic, separated from retry handling.
+
+        Returns:
+            Tuple of (response_data, response_headers) for non-streaming requests.
+            For streaming requests, returns (response_object, response_headers).
         """
         # Ensure auth credentials are initialized (proactive refresh if needed)
         await self._ensure_auth_initialized()
@@ -471,8 +478,9 @@ class HTTPClient:
                     request_id=request_id,
                     status_code=status_code,
                     response_body=f"<binary content, {response.headers.get('content-length', 'unknown')} bytes>",
+                    response_headers=dict(response.headers),
                 )
-                return response
+                return response, dict(response.headers)
 
             # Parse response - handle non-JSON responses gracefully
             content_type = response.headers.get("content-type", "")
@@ -485,7 +493,7 @@ class HTTPClient:
                 elif "application/json" in content_type or not content_type:
                     response_data = await response.json()
                 else:
-                    error_msg = f"Expected JSON response for {method.upper()} {url}, " f"got content-type: {content_type}"
+                    error_msg = f"Expected JSON response for {method.upper()} {url}, got content-type: {content_type}"
                     raise HTTPClientError(error_msg)
 
             except ValueError as e:
@@ -497,8 +505,9 @@ class HTTPClient:
                 request_id=request_id,
                 status_code=status_code,
                 response_body=response_data,
+                response_headers=dict(response.headers),
             )
-            return response_data
+            return response_data, dict(response.headers)
 
         except AuthenticationError as e:
             # Auth error (401, 403) - handle token refresh
@@ -556,6 +565,7 @@ class HTTPClient:
             current_token = self.secrets.get("access_token")
             strategy = AuthStrategyFactory.get_strategy(self.auth_config.type)
 
+            # Try to refresh credentials
             try:
                 result = await strategy.handle_auth_error(
                     status_code=status_code,
@@ -564,53 +574,56 @@ class HTTPClient:
                     config_values=self.config_values,
                     http_client=None,  # Let strategy create its own client
                 )
-
-                if result:
-                    # Notify callback if provided (for persistence)
-                    # Include both tokens AND extracted values for full persistence
-                    if self.on_token_refresh is not None:
-                        try:
-                            # Build callback data with both tokens and extracted values
-                            callback_data = dict(result.tokens)
-                            if result.extracted_values:
-                                callback_data.update(result.extracted_values)
-
-                            # Support both sync and async callbacks
-                            callback_result = self.on_token_refresh(callback_data)
-                            if hasattr(callback_result, "__await__"):
-                                await callback_result
-                        except Exception as callback_error:
-                            self.logger.log_error(
-                                request_id=request_id,
-                                error=f"Token refresh callback failed: {str(callback_error)}",
-                                status_code=status_code,
-                            )
-
-                    # Update secrets with new tokens (in-memory)
-                    self.secrets.update(result.tokens)
-
-                    # Update config_values and re-render base_url with extracted values
-                    if result.extracted_values:
-                        self._apply_token_extract(result.extracted_values)
-
-                    if self.secrets.get("access_token") != current_token:
-                        # Retry with new token - this will go through full retry logic
-                        return await self.request(
-                            method=method,
-                            path=path,
-                            params=params,
-                            json=json,
-                            data=data,
-                            headers=headers,
-                        )
-
             except Exception as refresh_error:
                 self.logger.log_error(
                     request_id=request_id,
                     error=f"Credential refresh failed: {str(refresh_error)}",
                     status_code=status_code,
                 )
+                result = None
+
+            # If refresh succeeded, update tokens and retry
+            if result:
+                # Notify callback if provided (for persistence)
+                # Include both tokens AND extracted values for full persistence
+                if self.on_token_refresh is not None:
+                    try:
+                        # Build callback data with both tokens and extracted values
+                        callback_data = dict(result.tokens)
+                        if result.extracted_values:
+                            callback_data.update(result.extracted_values)
 
+                        # Support both sync and async callbacks
+                        callback_result = self.on_token_refresh(callback_data)
+                        if callback_result is not None and hasattr(callback_result, "__await__"):
+                            await callback_result
+                    except Exception as callback_error:
+                        self.logger.log_error(
+                            request_id=request_id,
+                            error=f"Token refresh callback failed: {str(callback_error)}",
+                            status_code=status_code,
+                        )
+
+                # Update secrets with new tokens (in-memory)
+                self.secrets.update(result.tokens)
+
+                # Update config_values and re-render base_url with extracted values
+                if result.extracted_values:
+                    self._apply_token_extract(result.extracted_values)
+
+                if self.secrets.get("access_token") != current_token:
+                    # Retry with new token - this will go through full retry logic
+                    # Any errors from this retry will propagate to the caller
+                    return await self.request(
+                        method=method,
+                        path=path,
+                        params=params,
+                        json=json,
+                        data=data,
+                        headers=headers,
+                    )
+
+        # Refresh failed or token didn't change, log and let original error propagate
         self.logger.log_error(request_id=request_id, error=str(error), status_code=status_code)
 
     async def request(
@@ -624,7 +637,7 @@ class HTTPClient:
         *,
         stream: bool = False,
         _auth_retry_attempted: bool = False,
-    ):
+    ) -> tuple[dict[str, Any], dict[str, str]]:
         """Make an async HTTP request with optional streaming and automatic retries.
 
         Args:
@@ -637,8 +650,9 @@ class HTTPClient:
             stream: If True, do not eagerly read the body (useful for downloads)
 
         Returns:
-            - If stream=False: Parsed JSON (dict) or empty dict
-            - If stream=True: Response object suitable for streaming
+            Tuple of (response_data, response_headers):
+            - If stream=False: (parsed JSON dict or empty dict, response headers dict)
+            - If stream=True: (response object suitable for streaming, response headers dict)
 
         Raises:
             HTTPStatusError: If request fails with 4xx/5xx status after all retries

airbyte_agent_zendesk_support/_vendored/connector_sdk/introspection.py

@@ -0,0 +1,262 @@
+"""
+Shared introspection utilities for connector metadata.
+
+This module provides utilities for introspecting connector metadata,
+generating descriptions, and formatting parameter signatures. These
+functions are used by both the runtime decorators and the generated
+connector code.
+
+The module is designed to work with any object conforming to the
+ConnectorModel and EndpointDefinition interfaces from connector_sdk.types.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+# Constants
+MAX_EXAMPLE_QUESTIONS = 5  # Maximum number of example questions to include in description
+
+
+class EndpointProtocol(Protocol):
+    """Protocol defining the expected interface for endpoint parameters.
+
+    This allows functions to work with any endpoint-like object
+    that has these attributes, including EndpointDefinition and mock objects.
+    """
+
+    path_params: list[str]
+    path_params_schema: dict[str, dict[str, Any]]
+    query_params: list[str]
+    query_params_schema: dict[str, dict[str, Any]]
+    body_fields: list[str]
+    request_schema: dict[str, Any] | None
+
+
+class EntityProtocol(Protocol):
+    """Protocol defining the expected interface for entity definitions."""
+
+    name: str
+    actions: list[Any]
+    endpoints: dict[Any, EndpointProtocol]
+
+
+class ConnectorModelProtocol(Protocol):
+    """Protocol defining the expected interface for connector model parameters.
+
+    This allows functions to work with any connector-like object
+    that has these attributes, including ConnectorModel and mock objects.
+    """
+
+    @property
+    def entities(self) -> list[EntityProtocol]: ...
+
+    @property
+    def openapi_spec(self) -> Any: ...
+
+
+def format_param_signature(endpoint: EndpointProtocol) -> str:
+    """Format parameter signature for an endpoint action.
+
+    Returns a string like: (id*) or (limit?, starting_after?, email?)
+    where * = required, ? = optional
+
+    Args:
+        endpoint: Object conforming to EndpointProtocol (e.g., EndpointDefinition)
+
+    Returns:
+        Formatted parameter signature string
+    """
+    params = []
+
+    # Defensive: safely access attributes with defaults for malformed endpoints
+    path_params = getattr(endpoint, "path_params", []) or []
+    query_params = getattr(endpoint, "query_params", []) or []
+    query_params_schema = getattr(endpoint, "query_params_schema", {}) or {}
+    body_fields = getattr(endpoint, "body_fields", []) or []
+    request_schema = getattr(endpoint, "request_schema", None)
+
+    # Path params (always required)
+    for name in path_params:
+        params.append(f"{name}*")
+
+    # Query params
+    for name in query_params:
+        schema = query_params_schema.get(name, {})
+        required = schema.get("required", False)
+        params.append(f"{name}{'*' if required else '?'}")
+
+    # Body fields
+    if request_schema:
+        required_fields = set(request_schema.get("required", []))
+        for name in body_fields:
+            params.append(f"{name}{'*' if name in required_fields else '?'}")
+
+    return f"({', '.join(params)})" if params else "()"
+
+
+def describe_entities(model: ConnectorModelProtocol) -> list[dict[str, Any]]:
+    """Generate entity descriptions from ConnectorModel.
+
+    Returns a list of entity descriptions with detailed parameter information
+    for each action. This is used by generated connectors' describe() method.
+
+    Args:
+        model: Object conforming to ConnectorModelProtocol (e.g., ConnectorModel)
+
+    Returns:
+        List of entity description dicts with keys:
+        - entity_name: Name of the entity (e.g., "contacts", "deals")
+        - description: Entity description from the first endpoint
+        - available_actions: List of actions (e.g., ["list", "get", "create"])
+        - parameters: Dict mapping action -> list of parameter dicts
+    """
+    entities = []
+    for entity_def in model.entities:
+        description = ""
+        parameters: dict[str, list[dict[str, Any]]] = {}
+
+        endpoints = getattr(entity_def, "endpoints", {}) or {}
+        if endpoints:
+            for action, endpoint in endpoints.items():
+                # Get description from first endpoint that has one
+                if not description:
+                    endpoint_desc = getattr(endpoint, "description", None)
+                    if endpoint_desc:
+                        description = endpoint_desc
+
+                action_params: list[dict[str, Any]] = []
+
+                # Defensive: safely access endpoint attributes
+                path_params = getattr(endpoint, "path_params", []) or []
+                path_params_schema = getattr(endpoint, "path_params_schema", {}) or {}
+                query_params = getattr(endpoint, "query_params", []) or []
+                query_params_schema = getattr(endpoint, "query_params_schema", {}) or {}
+                body_fields = getattr(endpoint, "body_fields", []) or []
+                request_schema = getattr(endpoint, "request_schema", None)
+
+                # Path params (always required)
+                for param_name in path_params:
+                    schema = path_params_schema.get(param_name, {})
+                    action_params.append(
+                        {
+                            "name": param_name,
+                            "in": "path",
+                            "required": True,
+                            "type": schema.get("type", "string"),
+                            "description": schema.get("description", ""),
+                        }
+                    )
+
+                # Query params
+                for param_name in query_params:
+                    schema = query_params_schema.get(param_name, {})
+                    action_params.append(
+                        {
+                            "name": param_name,
+                            "in": "query",
+                            "required": schema.get("required", False),
+                            "type": schema.get("type", "string"),
+                            "description": schema.get("description", ""),
+                        }
+                    )
+
+                # Body fields
+                if request_schema:
+                    required_fields = request_schema.get("required", [])
+                    properties = request_schema.get("properties", {})
+                    for param_name in body_fields:
+                        prop = properties.get(param_name, {})
+                        action_params.append(
+                            {
+                                "name": param_name,
+                                "in": "body",
+                                "required": param_name in required_fields,
+                                "type": prop.get("type", "string"),
+                                "description": prop.get("description", ""),
+                            }
+                        )
+
+                if action_params:
+                    # Action is an enum, use .value to get string
+                    action_key = action.value if hasattr(action, "value") else str(action)
+                    parameters[action_key] = action_params
+
+        actions = getattr(entity_def, "actions", []) or []
+        entities.append(
+            {
+                "entity_name": entity_def.name,
+                "description": description,
+                "available_actions": [a.value if hasattr(a, "value") else str(a) for a in actions],
+                "parameters": parameters,
+            }
+        )
+
+    return entities
+
+
+def generate_tool_description(model: ConnectorModelProtocol) -> str:
+    """Generate AI tool description from connector metadata.
+
+    Produces a detailed description that includes:
+    - Per-entity/action parameter signatures with required (*) and optional (?) markers
+    - Response structure documentation with pagination hints
+    - Example questions if available in the OpenAPI spec
+
+    This is used by the Connector.describe class method decorator to populate
+    function docstrings for AI framework integration.
+
+    Args:
+        model: Object conforming to ConnectorModelProtocol (e.g., ConnectorModel)
+
+    Returns:
+        Formatted description string suitable for AI tool documentation
+    """
+    lines = []
+
+    # Entity/action parameter details (including pagination params like limit, starting_after)
+    lines.append("ENTITIES AND PARAMETERS:")
+    for entity in model.entities:
+        lines.append(f"  {entity.name}:")
+        actions = getattr(entity, "actions", []) or []
+        endpoints = getattr(entity, "endpoints", {}) or {}
+        for action in actions:
+            action_str = action.value if hasattr(action, "value") else str(action)
+            endpoint = endpoints.get(action)
+            if endpoint:
+                param_sig = format_param_signature(endpoint)
+                lines.append(f"    - {action_str}{param_sig}")
+            else:
+                lines.append(f"    - {action_str}()")
+
+    # Response structure (brief, includes pagination hint)
+    lines.append("")
+    lines.append("RESPONSE STRUCTURE:")
+    lines.append("  - list/api_search: {data: [...], meta: {has_more: bool}}")
+    lines.append("  - get: Returns entity directly (no envelope)")
+    lines.append("  To paginate: pass starting_after=<last_id> while has_more is true")
+
+    # Add example questions if available in openapi_spec
+    openapi_spec = getattr(model, "openapi_spec", None)
+    if openapi_spec:
+        info = getattr(openapi_spec, "info", None)
+        if info:
+            example_questions = getattr(info, "x_airbyte_example_questions", None)
+            if example_questions:
+                supported = getattr(example_questions, "supported", None)
+                if supported:
+                    lines.append("")
+                    lines.append("EXAMPLE QUESTIONS:")
+                    for q in supported[:MAX_EXAMPLE_QUESTIONS]:
+                        lines.append(f"  - {q}")
+
+    # Generic parameter description for function signature
+    lines.append("")
+    lines.append("FUNCTION PARAMETERS:")
+    lines.append("  - entity: Entity name (string)")
+    lines.append("  - action: Operation to perform (string)")
+    lines.append("  - params: Operation parameters (dict) - see entity details above")
+    lines.append("")
+    lines.append("Parameter markers: * = required, ? = optional")
+
+    return "\n".join(lines)

airbyte_agent_zendesk_support/_vendored/connector_sdk/logging/logger.py

@@ -5,7 +5,7 @@ import json
 import time
 import uuid
 from pathlib import Path
-from typing import Any, Dict, Optional, Set
+from typing import Any, Dict, Set
 
 from .types import LogSession, RequestLog
 
@@ -31,9 +31,9 @@ class RequestLogger:
 
     def __init__(
         self,
-        log_file: Optional[str] = None,
-        connector_name: Optional[str] = None,
-        max_logs: Optional[int] = 10000,
+        log_file: str | None = None,
+        connector_name: str | None = None,
+        max_logs: int | None = 10000,
     ):
         """
         Initialize the request logger.
@@ -99,9 +99,9 @@ class RequestLogger:
         method: str,
         url: str,
         path: str,
-        headers: Optional[Dict[str, str]] = None,
-        params: Optional[Dict[str, Any]] = None,
-        body: Optional[Any] = None,
+        headers: Dict[str, str] | None = None,
+        params: Dict[str, Any] | None = None,
+        body: Any | None = None,
     ) -> str:
         """
         Log the start of an HTTP request.
@@ -133,7 +133,8 @@ class RequestLogger:
         self,
         request_id: str,
         status_code: int,
-        response_body: Optional[Any] = None,
+        response_body: Any | None = None,
+        response_headers: Dict[str, str] | None = None,
     ) -> None:
         """
         Log a successful HTTP response.
@@ -142,6 +143,7 @@ class RequestLogger:
             request_id: ID returned from log_request
             status_code: HTTP status code
             response_body: Response body
+            response_headers: Response headers
         """
         if request_id not in self._active_requests:
             return
@@ -166,6 +168,7 @@ class RequestLogger:
             body=request_data["body"],
             response_status=status_code,
             response_body=serializable_body,
+            response_headers=response_headers or {},
             timing_ms=timing_ms,
         )
 
@@ -176,7 +179,7 @@ class RequestLogger:
         self,
         request_id: str,
         error: str,
-        status_code: Optional[int] = None,
+        status_code: int | None = None,
     ) -> None:
         """
         Log an HTTP request error.
@@ -243,7 +246,13 @@ class NullLogger:
         """No-op log_request."""
         return ""
 
-    def log_response(self, *args, **kwargs) -> None:
+    def log_response(
+        self,
+        request_id: str,
+        status_code: int,
+        response_body: Any | None = None,
+        response_headers: Dict[str, str] | None = None,
+    ) -> None:
         """No-op log_response."""
         pass
 

airbyte_agent_zendesk_support/_vendored/connector_sdk/logging/types.py

@@ -2,7 +2,7 @@
 
 import base64
 from datetime import UTC, datetime
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List
 
 from pydantic import BaseModel, ConfigDict, Field, field_serializer, field_validator
 
@@ -27,12 +27,13 @@ class RequestLog(BaseModel):
     url: str
     path: str
     headers: Dict[str, str] = Field(default_factory=dict)
-    params: Optional[Dict[str, Any]] = None
-    body: Optional[Any] = None
-    response_status: Optional[int] = None
-    response_body: Optional[Any] = None
-    timing_ms: Optional[float] = None
-    error: Optional[str] = None
+    params: Dict[str, Any] | None = None
+    body: Any | None = None
+    response_status: int | None = None
+    response_body: Any | None = None
+    response_headers: Dict[str, str] = Field(default_factory=dict)
+    timing_ms: float | None = None
+    error: str | None = None
 
     @field_serializer("timestamp")
     def serialize_datetime(self, value: datetime) -> str:
@@ -50,9 +51,9 @@ class LogSession(BaseModel):
 
     session_id: str
     started_at: datetime = Field(default_factory=_utc_now)
-    connector_name: Optional[str] = None
+    connector_name: str | None = None
     logs: List[RequestLog] = Field(default_factory=list)
-    max_logs: Optional[int] = Field(
+    max_logs: int | None = Field(
         default=10000,
         description="Maximum number of logs to keep in memory. "
         "When limit is reached, oldest logs should be flushed before removal. "
@@ -60,7 +61,7 @@ class LogSession(BaseModel):
     )
     chunk_logs: List[bytes] = Field(
         default_factory=list,
-        description="Captured chunks from streaming responses. " "Each chunk is logged when log_chunk_fetch() is called.",
+        description="Captured chunks from streaming responses. Each chunk is logged when log_chunk_fetch() is called.",
     )
 
     @field_validator("chunk_logs", mode="before")