airbyte-agent-airtable 0.1.5__py3-none-any.whl

airbyte_agent_airtable/_vendored/connector_sdk/telemetry/tracker.py

@@ -0,0 +1,155 @@
+"""Anonymous telemetry tracker using Segment."""
+
+import logging
+import platform
+import sys
+from datetime import UTC, datetime
+
+from ..observability import ObservabilitySession
+
+from .config import SEGMENT_WRITE_KEY, TelemetryConfig, TelemetryMode
+from .events import ConnectorInitEvent, OperationEvent, SessionEndEvent
+
+logger = logging.getLogger(__name__)
+
+
+class SegmentTracker:
+    """Anonymous telemetry tracker using Segment."""
+
+    def __init__(
+        self,
+        session: ObservabilitySession,
+        mode: TelemetryMode | None = None,
+    ):
+        self.session = session
+        self.mode = mode or TelemetryConfig.get_mode()
+        self.success_count = 0
+        self.failure_count = 0
+        self.enabled = TelemetryConfig.is_enabled()
+        self._analytics = None
+
+        if self.enabled:
+            try:
+                # NOTE: Import here intentionally - segment is an optional dependency.
+                # This allows the SDK to work without telemetry if segment is not installed.
+                import segment.analytics as analytics
+
+                analytics.write_key = SEGMENT_WRITE_KEY
+                self._analytics = analytics
+                self._log_startup_message()
+            except ImportError:
+                logger.warning("Telemetry disabled: segment-analytics-python not installed")
+                self.enabled = False
+
+    def _log_startup_message(self):
+        """Log message when telemetry is enabled."""
+        logger.info(f"Anonymous telemetry enabled (mode: {self.mode.value})")
+        logger.info("To opt-out: export AIRBYTE_TELEMETRY_MODE=disabled")
+
+    def track_connector_init(
+        self,
+        connector_version: str | None = None,
+    ) -> None:
+        """Track connector initialization."""
+        if not self.enabled or not self._analytics:
+            return
+
+        try:
+            event = ConnectorInitEvent(
+                timestamp=datetime.now(UTC),
+                session_id=self.session.session_id,
+                user_id=self.session.user_id,
+                execution_context=self.session.execution_context,
+                is_internal_user=self.session.is_internal_user,
+                public_ip=self.session.public_ip,
+                connector_name=self.session.connector_name,
+                connector_version=connector_version,
+                python_version=f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+                os_name=platform.system(),
+                os_version=platform.release(),
+            )
+
+            self._analytics.track(
+                user_id=self.session.user_id,
+                anonymous_id=event.session_id,
+                event="Connector Initialized",
+                properties=event.to_dict(),
+            )
+        except Exception as e:
+            # Never fail on tracking errors
+            logger.error(f"Telemetry error: {e}")
+
+    def track_operation(
+        self,
+        entity: str,
+        action: str,
+        status_code: int | None,
+        timing_ms: float,
+        error_type: str | None = None,
+    ) -> None:
+        """Track API operation."""
+        # Always track success/failure counts (useful even when tracking is disabled)
+        if status_code and 200 <= status_code < 300:
+            self.success_count += 1
+        else:
+            self.failure_count += 1
+
+        if not self.enabled or not self._analytics:
+            return
+
+        try:
+            event = OperationEvent(
+                timestamp=datetime.now(UTC),
+                session_id=self.session.session_id,
+                user_id=self.session.user_id,
+                execution_context=self.session.execution_context,
+                is_internal_user=self.session.is_internal_user,
+                public_ip=self.session.public_ip,
+                connector_name=self.session.connector_name,
+                entity=entity,
+                action=action,
+                status_code=status_code,
+                timing_ms=timing_ms,
+                error_type=error_type,
+            )
+
+            self._analytics.track(
+                user_id=self.session.user_id,
+                anonymous_id=event.session_id,
+                event="Operation Executed",
+                properties=event.to_dict(),
+            )
+        except Exception as e:
+            logger.error(f"Telemetry error: {e}")
+
+    def track_session_end(self) -> None:
+        """Track session end."""
+        if not self.enabled or not self._analytics:
+            return
+
+        try:
+            event = SessionEndEvent(
+                timestamp=datetime.now(UTC),
+                session_id=self.session.session_id,
+                user_id=self.session.user_id,
+                execution_context=self.session.execution_context,
+                is_internal_user=self.session.is_internal_user,
+                public_ip=self.session.public_ip,
+                connector_name=self.session.connector_name,
+                duration_seconds=self.session.duration_seconds(),
+                operation_count=self.session.operation_count,
+                success_count=self.success_count,
+                failure_count=self.failure_count,
+            )
+
+            self._analytics.track(
+                user_id=self.session.user_id,
+                anonymous_id=event.session_id,
+                event="Session Ended",
+                properties=event.to_dict(),
+            )
+
+            # Ensure events are sent before shutdown
+            self._analytics.flush()
+        except Exception as e:
+            logger.error(f"Telemetry error: {e}")

airbyte_agent_airtable/_vendored/connector_sdk/types.py

@@ -0,0 +1,274 @@
+"""Type definitions for Airbyte SDK."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .constants import OPENAPI_DEFAULT_VERSION
+from .schema.components import PathOverrideConfig
+from .schema.extensions import RetryConfig
+from .schema.security import AirbyteAuthConfig
+
+
+class Action(str, Enum):
+    """Supported actions for Entity operations.
+
+    Standard CRUD actions:
+        GET, CREATE, UPDATE, DELETE, LIST
+
+    Special actions:
+        API_SEARCH - Search via API endpoint
+        DOWNLOAD - Download file content
+        AUTHORIZE - OAuth authorization flow
+    """
+
+    GET = "get"
+    CREATE = "create"
+    UPDATE = "update"
+    DELETE = "delete"
+    LIST = "list"
+    API_SEARCH = "api_search"
+    DOWNLOAD = "download"
+    AUTHORIZE = "authorize"
+
+
+class AuthType(str, Enum):
+    """Supported authentication types."""
+
+    API_KEY = "api_key"
+    BEARER = "bearer"
+    HTTP = "http"
+    BASIC = "basic"
+    OAUTH2 = "oauth2"
+
+
+class ContentType(str, Enum):
+    """Supported content types for request bodies."""
+
+    JSON = "application/json"
+    FORM_URLENCODED = "application/x-www-form-urlencoded"
+    FORM_DATA = "multipart/form-data"
+
+
+class ParameterLocation(str, Enum):
+    """Location of operation parameters."""
+
+    PATH = "path"
+    QUERY = "query"
+    HEADER = "header"
+    COOKIE = "cookie"
+
+
+# All comprehensive OpenAPI 3.0 models are now in connector_sdk.schema package
+# Import from connector_sdk.schema for: OpenAPIConnector, Components, Schema, Operation, etc.
+
+
+class AuthOption(BaseModel):
+    """A single authentication option in a multi-auth connector.
+
+    Represents one security scheme from OpenAPI components.securitySchemes.
+    Each option defines a complete authentication method with its own type,
+    configuration, and user-facing credential specification.
+
+    Example:
+        For a connector supporting both OAuth2 and API Key auth:
+        - AuthOption(scheme_name="oauth", type=OAUTH2, ...)
+        - AuthOption(scheme_name="apikey", type=BEARER, ...)
+    """
+
+    scheme_name: str = Field(description="Security scheme name from OpenAPI spec (e.g., 'githubOAuth', 'githubPAT')")
+    type: AuthType = Field(description="Authentication type for this option")
+    config: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Auth-specific configuration (e.g., OAuth2 refresh settings)",
+    )
+    user_config_spec: AirbyteAuthConfig | None = Field(
+        None,
+        description="User-facing credential specification from x-airbyte-auth-config",
+    )
+    untested: bool = Field(
+        False,
+        description="Mark this auth scheme as untested to skip cassette coverage validation",
+    )
+
+
+class AuthConfig(BaseModel):
+    """Authentication configuration supporting single or multiple auth methods.
+
+    Connectors can define either:
+    - Single auth: One authentication method (backwards compatible)
+    - Multi-auth: Multiple authentication methods (user/agent selects one)
+
+    For single-auth connectors (most common):
+        AuthConfig(type=OAUTH2, config={...}, user_config_spec={...})
+
+    For multi-auth connectors:
+        AuthConfig(options=[
+            AuthOption(scheme_name="oauth", type=OAUTH2, ...),
+            AuthOption(scheme_name="apikey", type=BEARER, ...)
+        ])
+    """
+
+    # Single-auth mode (backwards compatible)
+    type: AuthType | None = Field(
+        None,
+        description="Authentication type (single-auth mode only)",
+    )
+    config: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Auth configuration (single-auth mode only)",
+    )
+    user_config_spec: AirbyteAuthConfig | None = Field(
+        None,
+        description="User-facing config spec from x-airbyte-auth-config (single-auth mode)",
+    )
+
+    # Multi-auth mode
+    options: list[AuthOption] | None = Field(
+        None,
+        description="Multiple authentication options (multi-auth mode only)",
+    )
+
+    def is_multi_auth(self) -> bool:
+        """Check if this configuration supports multiple authentication methods.
+
+        Returns:
+            True if multiple auth options are available, False for single-auth
+        """
+        return self.options is not None and len(self.options) > 0
+
+    def get_single_option(self) -> AuthOption:
+        """Get single auth option (for backwards compatibility).
+
+        Converts single-auth config to AuthOption format for uniform handling.
+
+        Returns:
+            AuthOption containing the single auth configuration
+
+        Raises:
+            ValueError: If this is a multi-auth config or invalid
+        """
+        if self.is_multi_auth():
+            raise ValueError("Cannot call get_single_option() on multi-auth config. Use options list instead.")
+
+        if self.type is None:
+            raise ValueError("Invalid AuthConfig: neither single-auth nor multi-auth")
+
+        return AuthOption(
+            scheme_name="default",
+            type=self.type,
+            config=self.config,
+            user_config_spec=self.user_config_spec,
+        )
+
+
+# Executor types (used by executor.py)
+class EndpointDefinition(BaseModel):
+    """Definition of an API endpoint."""
+
+    method: str  # GET, POST, PUT, DELETE, etc.
+    path: str  # e.g., /v1/customers/{id} (OpenAPI path)
+    path_override: PathOverrideConfig | None = Field(
+        None,
+        description=("Path override config from x-airbyte-path-override. When set, overrides the path for actual HTTP requests."),
+    )
+    action: Action | None = None  # Semantic action (get, list, create, update, delete)
+    description: str | None = None
+    body_fields: list[str] = Field(default_factory=list)  # For POST/PUT
+    query_params: list[str] = Field(default_factory=list)  # For GET
+    query_params_schema: dict[str, dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Schema for query params including defaults: {name: {type, default, required}}",
+    )
+    deep_object_params: list[str] = Field(
+        default_factory=list,
+        description="Query parameters using deepObject style (e.g., filter[key]=value)",
+    )  # For GET with deepObject query params
+    path_params: list[str] = Field(default_factory=list)  # Extracted from path
+    path_params_schema: dict[str, dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Schema for path params including defaults: {name: {type, default, required}}",
+    )
+    header_params: list[str] = Field(default_factory=list)  # Header parameters from OpenAPI
+    header_params_schema: dict[str, dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Schema for header params including defaults: {name: {type, default, required}}",
+    )
+    request_body_defaults: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Default values for request body fields from OpenAPI schema",
+    )
+    content_type: ContentType = ContentType.JSON
+    request_schema: dict[str, Any] | None = None
+    response_schema: dict[str, Any] | None = None
+
+    # GraphQL support (Airbyte extension)
+    graphql_body: dict[str, Any] | None = Field(
+        None,
+        description="GraphQL body configuration from x-airbyte-body-type extension",
+    )
+
+    # Record extractor support (Airbyte extension)
+    record_extractor: str | None = Field(
+        None,
+        description="JSONPath expression to extract records from response envelopes",
+    )
+
+    # Metadata extractor support (Airbyte extension)
+    meta_extractor: dict[str, str] | None = Field(
+        None,
+        description="Dictionary mapping field names to JSONPath expressions for extracting metadata from response envelopes",
+    )
+
+    # Download support (Airbyte extension)
+    file_field: str | None = Field(
+        None,
+        description="Field in metadata response containing download URL (from x-airbyte-file-url extension)",
+    )
+
+    # Test validation support (Airbyte extension)
+    untested: bool = Field(
+        False,
+        description="Mark operation as untested to skip cassette validation (from x-airbyte-untested extension)",
+    )
+
+    # Health check support (Airbyte extension)
+    preferred_for_check: bool = Field(
+        False,
+        description="Mark this list operation as preferred for health checks (from x-airbyte-preferred-for-check extension)",
+    )
+
+
+class EntityDefinition(BaseModel):
+    """Definition of an API entity."""
+
+    model_config = {"populate_by_name": True}
+
+    name: str
+    stream_name: str | None = Field(
+        default=None,
+        description="Airbyte stream name for cache lookup (from x-airbyte-stream-name schema extension)",
+    )
+    actions: list[Action]
+    endpoints: dict[Action, EndpointDefinition]
+    entity_schema: dict[str, Any] | None = Field(default=None, alias="schema")
+
+
+class ConnectorModel(BaseModel):
+    """Complete connector model loaded from YAML definition."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    id: UUID
+    name: str
+    version: str = OPENAPI_DEFAULT_VERSION
+    base_url: str
+    auth: AuthConfig
+    entities: list[EntityDefinition]
+    openapi_spec: Any | None = None  # Optional reference to OpenAPIConnector
+    retry_config: RetryConfig | None = None  # Optional retry configuration
+    search_field_paths: dict[str, list[str]] | None = None

airbyte_agent_airtable/_vendored/connector_sdk/utils.py

@@ -0,0 +1,127 @@
+"""Utility functions for working with connectors."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .types import AuthOption
+
+
+async def save_download(
+    download_iterator: AsyncIterator[bytes],
+    path: str | Path,
+    *,
+    overwrite: bool = False,
+) -> Path:
+    """Save a download iterator to a file.
+
+    Args:
+        download_iterator: AsyncIterator[bytes] from a download operation
+        path: File path where content should be saved
+        overwrite: Whether to overwrite existing file (default: False)
+
+    Returns:
+        Absolute Path to the saved file
+
+    Raises:
+        FileExistsError: If file exists and overwrite=False
+        OSError: If file cannot be written
+
+    Example:
+        >>> from .utils import save_download
+        >>>
+        >>> # Download and save a file
+        >>> result = await connector.download_article_attachment(id="123")
+        >>> file_path = await save_download(result, "./downloads/attachment.pdf")
+        >>> print(f"Downloaded to {file_path}")
+        Downloaded to /absolute/path/to/downloads/attachment.pdf
+        >>>
+        >>> # Overwrite existing file
+        >>> file_path = await save_download(result, "./downloads/attachment.pdf", overwrite=True)
+    """
+    # Convert to Path object
+    file_path = Path(path).expanduser().resolve()
+
+    # Check if file exists
+    if file_path.exists() and not overwrite:
+        raise FileExistsError(f"File already exists: {file_path}. Use overwrite=True to replace it.")
+
+    # Create parent directories if needed
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Stream content to file
+    try:
+        with open(file_path, "wb") as f:
+            async for chunk in download_iterator:
+                f.write(chunk)
+    except Exception as e:
+        # Clean up partial file on error
+        if file_path.exists():
+            file_path.unlink()
+        raise OSError(f"Failed to write file {file_path}: {e}") from e
+
+    return file_path
+
+
+def find_matching_auth_options(
+    provided_keys: set[str],
+    auth_options: list[AuthOption],
+) -> list[AuthOption]:
+    """Find auth options that match the provided credential keys.
+
+    This is the single source of truth for auth scheme inference logic,
+    used by both the executor (at runtime) and validation (for cassettes).
+
+    Matching logic:
+    - An option matches if all its required fields are present in provided_keys
+    - Options with no required fields match any credentials
+
+    Args:
+        provided_keys: Set of credential/auth_config keys
+        auth_options: List of AuthOption from the connector model
+
+    Returns:
+        List of AuthOption that match the provided keys
+    """
+    matching_options: list[AuthOption] = []
+
+    for option in auth_options:
+        if option.user_config_spec and option.user_config_spec.required:
+            required_fields = set(option.user_config_spec.required)
+            if required_fields.issubset(provided_keys):
+                matching_options.append(option)
+        elif not option.user_config_spec or not option.user_config_spec.required:
+            # Option has no required fields - it matches any credentials
+            matching_options.append(option)
+
+    return matching_options
+
+
+def infer_auth_scheme_name(
+    provided_keys: set[str],
+    auth_options: list[AuthOption],
+) -> str | None:
+    """Infer the auth scheme name from provided credential keys.
+
+    Uses find_matching_auth_options to find matches, then returns
+    the scheme name only if exactly one option matches.
+
+    Args:
+        provided_keys: Set of credential/auth_config keys
+        auth_options: List of AuthOption from the connector model
+
+    Returns:
+        The scheme_name if exactly one match, None otherwise
+    """
+    if not provided_keys or not auth_options:
+        return None
+
+    matching = find_matching_auth_options(provided_keys, auth_options)
+
+    if len(matching) == 1:
+        return matching[0].scheme_name
+
+    return None