airbyte-agent-stripe 0.5.28__py3-none-any.whl → 0.5.37__py3-none-any.whl

airbyte_agent_stripe/_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_stripe/_vendored/connector_sdk/observability/config.py

@@ -0,0 +1,179 @@
+"""Unified configuration for connector-sdk."""
+
+import logging
+import os
+import tempfile
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+# New config location
+CONFIG_DIR = Path.home() / ".airbyte" / "connector-sdk"
+CONFIG_PATH = CONFIG_DIR / "config.yaml"
+
+# Legacy file locations (for migration)
+LEGACY_USER_ID_PATH = Path.home() / ".airbyte" / "ai_sdk_user_id"
+LEGACY_INTERNAL_MARKER_PATH = Path.home() / ".airbyte" / "internal_user"
+
+
+@dataclass
+class SDKConfig:
+    """Connector SDK configuration."""
+
+    user_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    is_internal_user: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for YAML serialization."""
+        return {
+            "user_id": self.user_id,
+            "is_internal_user": self.is_internal_user,
+        }
+
+
+def _delete_legacy_files() -> None:
+    """
+    Delete legacy config files after successful migration.
+
+    Removes:
+    - ~/.airbyte/ai_sdk_user_id
+    - ~/.airbyte/internal_user
+    """
+    for legacy_path in [LEGACY_USER_ID_PATH, LEGACY_INTERNAL_MARKER_PATH]:
+        try:
+            if legacy_path.exists():
+                legacy_path.unlink()
+                logger.debug(f"Deleted legacy config file: {legacy_path}")
+        except Exception as e:
+            logger.debug(f"Could not delete legacy file {legacy_path}: {e}")
+
+
+def _migrate_legacy_config() -> Optional[SDKConfig]:
+    """
+    Migrate from legacy file-based config to new YAML format.
+
+    Reads from:
+    - ~/.airbyte/ai_sdk_user_id (user_id)
+    - ~/.airbyte/internal_user (is_internal_user marker)
+
+    Returns SDKConfig if migration was successful, None otherwise.
+    """
+    user_id = None
+    is_internal = False
+
+    # Try to read legacy user_id
+    try:
+        if LEGACY_USER_ID_PATH.exists():
+            user_id = LEGACY_USER_ID_PATH.read_text().strip()
+            if not user_id:
+                user_id = None
+    except Exception:
+        pass
+
+    # Check legacy internal_user marker
+    try:
+        is_internal = LEGACY_INTERNAL_MARKER_PATH.exists()
+    except Exception:
+        pass
+
+    if user_id or is_internal:
+        return SDKConfig(
+            user_id=user_id or str(uuid.uuid4()),
+            is_internal_user=is_internal,
+        )
+
+    return None
+
+
+def load_config() -> SDKConfig:
+    """
+    Load SDK configuration from config file.
+
+    Checks (in order):
+    1. New config file at ~/.airbyte/connector-sdk/config.yaml
+    2. Legacy files at ~/.airbyte/ai_sdk_user_id and ~/.airbyte/internal_user
+    3. Creates new config with generated user_id if nothing exists
+
+    Environment variable AIRBYTE_INTERNAL_USER can override is_internal_user.
+
+    Returns:
+        SDKConfig with user_id and is_internal_user
+    """
+    config = None
+
+    # Try to load from new config file
+    try:
+        if CONFIG_PATH.exists():
+            content = CONFIG_PATH.read_text()
+            data = yaml.safe_load(content) or {}
+            config = SDKConfig(
+                user_id=data.get("user_id", str(uuid.uuid4())),
+                is_internal_user=data.get("is_internal_user", False),
+            )
+            # Always clean up legacy files if they exist (even if new config exists)
+            _delete_legacy_files()
+    except Exception as e:
+        logger.debug(f"Could not load config from {CONFIG_PATH}: {e}")
+
+    # Try to migrate from legacy files if new config doesn't exist
+    if config is None:
+        config = _migrate_legacy_config()
+        if config:
+            # Save migrated config to new location
+            try:
+                save_config(config)
+                logger.debug("Migrated legacy config to new location")
+                # Delete legacy files after successful migration
+                _delete_legacy_files()
+            except Exception as e:
+                logger.debug(f"Could not save migrated config: {e}")
+
+    # Create new config if nothing exists
+    if config is None:
+        config = SDKConfig()
+        try:
+            save_config(config)
+        except Exception as e:
+            logger.debug(f"Could not save new config: {e}")
+
+    # Environment variable override for is_internal_user
+    env_value = os.getenv("AIRBYTE_INTERNAL_USER", "").lower()
+    if env_value in ("true", "1", "yes"):
+        config.is_internal_user = True
+    elif env_value:
+        # Any other non-empty value (including "false", "0", "no") defaults to False
+        config.is_internal_user = False
+
+    return config
+
+
+def save_config(config: SDKConfig) -> None:
+    """
+    Save SDK configuration to config file.
+
+    Creates the config directory if it doesn't exist.
+    Uses atomic writes to prevent corruption from concurrent access.
+
+    Args:
+        config: SDKConfig to save
+    """
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Use atomic write: write to temp file then rename (atomic on POSIX)
+    fd, temp_path = tempfile.mkstemp(dir=CONFIG_DIR, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as f:
+            yaml.dump(config.to_dict(), f, default_flow_style=False)
+        os.rename(temp_path, CONFIG_PATH)
+    except Exception:
+        # Clean up temp file on failure
+        try:
+            os.unlink(temp_path)
+        except OSError:
+            pass
+        raise

airbyte_agent_stripe/_vendored/connector_sdk/observability/session.py

@@ -3,46 +3,40 @@
 import logging
 import uuid
 from datetime import UTC, datetime
-from pathlib import Path
 from typing import Any, Dict, Optional
 
+from .config import SDKConfig, load_config
+
 logger = logging.getLogger(__name__)
 
+# Cache the config at module level to avoid repeated reads
+_cached_config: Optional[SDKConfig] = None
+
+
+def _get_config() -> SDKConfig:
+    """Get cached SDK config or load from file."""
+    global _cached_config
+    if _cached_config is None:
+        _cached_config = load_config()
+    return _cached_config
+
+
+def _clear_config_cache() -> None:
+    """Clear the cached config. Used for testing."""
+    global _cached_config
+    _cached_config = None
+
 
 def get_persistent_user_id() -> str:
     """
-    Get or create an anonymous user ID stored in the home directory.
+    Get the persistent anonymous user ID.
 
-    The ID is stored in ~/.airbyte/ai_sdk_user_id and persists across all sessions.
-    If the file doesn't exist, a new UUID is generated and saved.
+    Now reads from ~/.airbyte/connector-sdk/config.yaml
 
     Returns:
         An anonymous UUID string that uniquely identifies this user across sessions.
     """
-    try:
-        # Create .airbyte directory in home folder if it doesn't exist
-        airbyte_dir = Path.home() / ".airbyte"
-        airbyte_dir.mkdir(exist_ok=True)
-
-        # Path to user ID file
-        user_id_file = airbyte_dir / "ai_sdk_user_id"
-
-        # Try to read existing user ID
-        if user_id_file.exists():
-            user_id = user_id_file.read_text().strip()
-            if user_id:  # Validate it's not empty
-                return user_id
-
-        # Generate new user ID if file doesn't exist or is empty
-        user_id = str(uuid.uuid4())
-        user_id_file.write_text(user_id)
-        logger.debug(f"Generated new anonymous user ID: {user_id}")
-
-        return user_id
-    except Exception as e:
-        # If we can't read/write the file, generate a session-only ID
-        logger.debug(f"Could not access anonymous user ID file: {e}")
-        return str(uuid.uuid4())
+    return _get_config().user_id
 
 
 def get_public_ip() -> Optional[str]:
@@ -65,6 +59,18 @@ def get_public_ip() -> Optional[str]:
         return None
 
 
+def get_is_internal_user() -> bool:
+    """
+    Check if the current user is an internal Airbyte user.
+
+    Now reads from ~/.airbyte/connector-sdk/config.yaml
+    Environment variable AIRBYTE_INTERNAL_USER can override.
+
+    Returns False if not set or on any error.
+    """
+    return _get_config().is_internal_user
+
+
 class ObservabilitySession:
     """Shared session context for both logging and telemetry."""
 
@@ -84,6 +90,7 @@ class ObservabilitySession:
         self.operation_count = 0
         self.metadata: Dict[str, Any] = {}
         self.public_ip = get_public_ip()
+        self.is_internal_user = get_is_internal_user()
 
     def increment_operations(self):
         """Increment the operation counter."""

airbyte_agent_stripe/_vendored/connector_sdk/schema/components.py

@@ -65,8 +65,9 @@ class Schema(BaseModel):
     write_only: Optional[bool] = Field(None, alias="writeOnly")
     deprecated: Optional[bool] = None
 
-    # Airbyte extension
+    # Airbyte extensions
     x_airbyte_entity_name: Optional[str] = Field(None, alias="x-airbyte-entity-name")
+    x_airbyte_stream_name: Optional[str] = Field(None, alias="x-airbyte-stream-name")
 
 
 class Parameter(BaseModel):

airbyte_agent_stripe/_vendored/connector_sdk/schema/operations.py

@@ -61,7 +61,7 @@ class Operation(BaseModel):
         description=(
             "JSONPath expression to extract records from API response envelopes. "
             "When specified, executor extracts data at this path instead of returning "
-            "full response. Returns array for list/search actions, single record for "
+            "full response. Returns array for list/api_search actions, single record for "
             "get/create/update/delete actions."
         ),
     )

airbyte_agent_stripe/_vendored/connector_sdk/schema/security.py

@@ -77,6 +77,10 @@ class AuthConfigOption(BaseModel):
         default_factory=dict,
         description="Mapping from auth parameters (e.g., 'username', 'password', 'token') to template strings using ${field} syntax",
     )
+    replication_auth_key_mapping: Optional[Dict[str, str]] = Field(
+        None,
+        description="Mapping from source config paths (e.g., 'credentials.api_key') to auth config keys for direct connectors",
+    )
 
 
 class AirbyteAuthConfig(BaseModel):
@@ -99,6 +103,12 @@ class AirbyteAuthConfig(BaseModel):
     properties: Optional[Dict[str, AuthConfigFieldSpec]] = None
     auth_mapping: Optional[Dict[str, str]] = None
 
+    # Replication connector auth mapping
+    replication_auth_key_mapping: Optional[Dict[str, str]] = Field(
+        None,
+        description="Mapping from source config paths (e.g., 'credentials.api_key') to auth config keys for direct connectors",
+    )
+
     # Multiple options (oneOf)
     one_of: Optional[List[AuthConfigOption]] = Field(None, alias="oneOf")
 

airbyte_agent_stripe/_vendored/connector_sdk/telemetry/events.py

@@ -1,6 +1,6 @@
 """Telemetry event models."""
 
-from dataclasses import asdict, dataclass
+from dataclasses import asdict, dataclass, field
 from datetime import datetime
 from typing import Any, Dict, Optional
 
@@ -13,6 +13,7 @@ class BaseEvent:
     session_id: str
     user_id: str
     execution_context: str
+    is_internal_user: bool = field(default=False, kw_only=True)
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert event to dictionary with ISO formatted timestamp."""

airbyte_agent_stripe/_vendored/connector_sdk/telemetry/tracker.py

@@ -59,6 +59,7 @@ class SegmentTracker:
                 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,
@@ -101,6 +102,7 @@ class SegmentTracker:
                 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,
@@ -130,6 +132,7 @@ class SegmentTracker:
                 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(),

airbyte_agent_stripe/_vendored/connector_sdk/types.py

@@ -22,7 +22,7 @@ class Action(str, Enum):
     UPDATE = "update"
     DELETE = "delete"
     LIST = "list"
-    SEARCH = "search"
+    API_SEARCH = "api_search"
     DOWNLOAD = "download"
     AUTHORIZE = "authorize"
 
@@ -221,6 +221,10 @@ class EntityDefinition(BaseModel):
     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")