airbyte-agent-amazon-ads 0.1.23__py3-none-any.whl → 0.1.25__py3-none-any.whl

airbyte_agent_amazon_ads/_vendored/connector_sdk/cloud_utils/client.py

@@ -161,6 +161,131 @@ class AirbyteCloudClient:
         connector_id = connectors[0]["id"]
         return connector_id
 
+    async def initiate_oauth(
+        self,
+        definition_id: str,
+        external_user_id: str,
+        redirect_url: str,
+    ) -> str:
+        """Initiate a server-side OAuth flow.
+
+        Starts the OAuth flow for a connector. Returns a consent URL where the
+        end user should be redirected to grant access. After completing consent,
+        they'll be redirected to your redirect_url with a `server_side_oauth_secret_id`
+        query parameter that can be used with `create_source()`.
+
+        Args:
+            definition_id: Connector definition UUID
+            external_user_id: Workspace identifier
+            redirect_url: URL where users will be redirected after OAuth consent
+
+        Returns:
+            The OAuth consent URL
+
+        Raises:
+            httpx.HTTPStatusError: If the request fails
+
+        Example:
+            consent_url = await client.initiate_oauth(
+                definition_id="d8313939-3782-41b0-be29-b3ca20d8dd3a",
+                external_user_id="my-workspace",
+                redirect_url="https://myapp.com/oauth/callback",
+            )
+            # Redirect user to: consent_url
+            # After consent: https://myapp.com/oauth/callback?server_side_oauth_secret_id=...
+        """
+        token = await self.get_bearer_token()
+        url = f"{self.API_BASE_URL}/api/v1/integrations/connectors/oauth/initiate"
+        headers = {"Authorization": f"Bearer {token}"}
+        request_body = {
+            "external_user_id": external_user_id,
+            "definition_id": definition_id,
+            "redirect_url": redirect_url,
+        }
+
+        response = await self._http_client.post(url, json=request_body, headers=headers)
+        response.raise_for_status()
+        return response.json()["consent_url"]
+
+    async def create_source(
+        self,
+        name: str,
+        connector_definition_id: str,
+        external_user_id: str,
+        credentials: dict[str, Any] | None = None,
+        replication_config: dict[str, Any] | None = None,
+        server_side_oauth_secret_id: str | None = None,
+        source_template_id: str | None = None,
+    ) -> str:
+        """Create a new source on Airbyte Cloud.
+
+        Supports two authentication modes:
+        1. Direct credentials: Provide `credentials` dict
+        2. Server-side OAuth: Provide `server_side_oauth_secret_id` from OAuth flow
+
+        Args:
+            name: Source name
+            connector_definition_id: UUID of the connector definition
+            external_user_id: User identifier
+            credentials: Connector auth config dict. Required unless using OAuth.
+            replication_config: Optional replication settings (e.g., start_date for
+                connectors with x-airbyte-replication-config). Required for REPLICATION
+                mode sources like Intercom.
+            server_side_oauth_secret_id: OAuth secret ID from initiate_oauth redirect.
+                When provided, credentials are not required.
+            source_template_id: Source template ID. Required when organization has
+                multiple source templates for this connector type.
+
+        Returns:
+            The created source ID (UUID string)
+
+        Raises:
+            httpx.HTTPStatusError: If creation fails
+
+        Example:
+            # With direct credentials:
+            source_id = await client.create_source(
+                name="My Intercom Source",
+                connector_definition_id="d8313939-3782-41b0-be29-b3ca20d8dd3a",
+                external_user_id="my-workspace",
+                credentials={"access_token": "..."},
+                replication_config={"start_date": "2024-01-01T00:00:00Z"}
+            )
+
+            # With server-side OAuth:
+            source_id = await client.create_source(
+                name="My Intercom Source",
+                connector_definition_id="d8313939-3782-41b0-be29-b3ca20d8dd3a",
+                external_user_id="my-workspace",
+                server_side_oauth_secret_id="airbyte_oauth_..._secret_...",
+                replication_config={"start_date": "2024-01-01T00:00:00Z"}
+            )
+        """
+        token = await self.get_bearer_token()
+        url = f"{self.API_BASE_URL}/v1/integrations/connectors"
+        headers = {"Authorization": f"Bearer {token}"}
+
+        request_body: dict[str, Any] = {
+            "name": name,
+            "definition_id": connector_definition_id,
+            "external_user_id": external_user_id,
+        }
+
+        if credentials is not None:
+            request_body["credentials"] = credentials
+        if replication_config is not None:
+            request_body["replication_config"] = replication_config
+        if server_side_oauth_secret_id is not None:
+            request_body["server_side_oauth_secret_id"] = server_side_oauth_secret_id
+        if source_template_id is not None:
+            request_body["source_template_id"] = source_template_id
+
+        response = await self._http_client.post(url, json=request_body, headers=headers)
+        response.raise_for_status()
+
+        data = response.json()
+        return data["id"]
+
     async def execute_connector(
         self,
         connector_id: str,

airbyte_agent_amazon_ads/_vendored/connector_sdk/connector_model_loader.py

@@ -1014,6 +1014,7 @@ def _parse_security_scheme_to_option(scheme_name: str, scheme: Any) -> AuthOptio
         type=single_auth.type,
         config=single_auth.config,
         user_config_spec=single_auth.user_config_spec,
+        untested=getattr(scheme, "x_airbyte_untested", False),
     )
 
 

airbyte_agent_amazon_ads/_vendored/connector_sdk/executor/hosted_executor.py

@@ -19,19 +19,26 @@ class HostedExecutor:
     instead of directly calling external services. The cloud API handles all
     connector logic, secrets management, and execution.
 
-    The executor takes an external_user_id and uses the AirbyteCloudClient to:
+    The executor uses the AirbyteCloudClient to:
     1. Authenticate with the Airbyte Platform (bearer token with caching)
-    2. Look up the user's connector
+    2. Look up the user's connector (if connector_id not provided)
     3. Execute the connector operation via the cloud API
 
     Implements ExecutorProtocol.
 
     Example:
-        # Create executor with user ID, credentials, and connector definition ID
+        # Create executor with explicit connector_id (no lookup needed)
+        executor = HostedExecutor(
+            airbyte_client_id="client_abc123",
+            airbyte_client_secret="secret_xyz789",
+            connector_id="existing-source-uuid",
+        )
+
+        # Or create executor with user ID for lookup
         executor = HostedExecutor(
-            external_user_id="user-123",
             airbyte_client_id="client_abc123",
             airbyte_client_secret="secret_xyz789",
+            external_user_id="user-123",
             connector_definition_id="abc123-def456-ghi789",
         )
 
@@ -51,28 +58,48 @@ class HostedExecutor:
 
     def __init__(
         self,
-        external_user_id: str,
         airbyte_client_id: str,
         airbyte_client_secret: str,
-        connector_definition_id: str,
+        connector_id: str | None = None,
+        external_user_id: str | None = None,
+        connector_definition_id: str | None = None,
     ):
         """Initialize hosted executor.
 
+        Either provide connector_id directly OR (external_user_id + connector_definition_id)
+        for lookup.
+
         Args:
-            external_user_id: User identifier in the Airbyte system
             airbyte_client_id: Airbyte client ID for authentication
             airbyte_client_secret: Airbyte client secret for authentication
-            connector_definition_id: Connector definition ID used to look up
-                the user's connector.
+            connector_id: Direct connector/source ID (skips lookup if provided)
+            external_user_id: User identifier in the Airbyte system (for lookup)
+            connector_definition_id: Connector definition ID (for lookup)
+
+        Raises:
+            ValueError: If neither connector_id nor (external_user_id + connector_definition_id) provided
 
         Example:
+            # With explicit connector_id (no lookup)
+            executor = HostedExecutor(
+                airbyte_client_id="client_abc123",
+                airbyte_client_secret="secret_xyz789",
+                connector_id="existing-source-uuid",
+            )
+
+            # With lookup by user + definition
             executor = HostedExecutor(
-                external_user_id="user-123",
                 airbyte_client_id="client_abc123",
                 airbyte_client_secret="secret_xyz789",
+                external_user_id="user-123",
                 connector_definition_id="abc123-def456-ghi789",
             )
         """
+        # Validate: either connector_id OR (external_user_id + connector_definition_id) required
+        if not connector_id and not (external_user_id and connector_definition_id):
+            raise ValueError("Either connector_id OR (external_user_id + connector_definition_id) must be provided")
+
+        self._connector_id = connector_id
         self._external_user_id = external_user_id
         self._connector_definition_id = connector_definition_id
 
@@ -86,10 +113,9 @@ class HostedExecutor:
         """Execute connector via cloud API (ExecutorProtocol implementation).
 
         Flow:
-        1. Get connector definition id from executor config
-        2. Look up the user's connector ID
-        3. Execute the connector operation via the cloud API
-        4. Parse the response into ExecutionResult
+        1. Use provided connector_id or look up from external_user_id + definition_id
+        2. Execute the connector operation via the cloud API
+        3. Parse the response into ExecutionResult
 
         Args:
             config: Execution configuration (entity, action, params)
@@ -98,7 +124,7 @@ class HostedExecutor:
             ExecutionResult with success/failure status
 
         Raises:
-            ValueError: If no connector or multiple connectors found for user
+            ValueError: If no connector or multiple connectors found for user (when doing lookup)
             httpx.HTTPStatusError: If API returns 4xx/5xx status code
             httpx.RequestError: If network request fails
 
@@ -114,23 +140,26 @@ class HostedExecutor:
 
         with tracer.start_as_current_span("airbyte.hosted_executor.execute") as span:
             # Add span attributes for observability
-            span.set_attribute("connector.definition_id", self._connector_definition_id)
+            if self._connector_definition_id:
+                span.set_attribute("connector.definition_id", self._connector_definition_id)
             span.set_attribute("connector.entity", config.entity)
             span.set_attribute("connector.action", config.action)
-            span.set_attribute("user.external_id", self._external_user_id)
+            if self._external_user_id:
+                span.set_attribute("user.external_id", self._external_user_id)
             if config.params:
                 # Only add non-sensitive param keys
                 span.set_attribute("connector.param_keys", list(config.params.keys()))
 
             try:
-                # Step 1: Get connector definition id
-                connector_definition_id = self._connector_definition_id
-
-                # Step 2: Get the connector ID for this user
-                connector_id = await self._cloud_client.get_connector_id(
-                    external_user_id=self._external_user_id,
-                    connector_definition_id=connector_definition_id,
-                )
+                # Use provided connector_id or look it up
+                if self._connector_id:
+                    connector_id = self._connector_id
+                else:
+                    # Look up connector by external_user_id + definition_id
+                    connector_id = await self._cloud_client.get_connector_id(
+                        external_user_id=self._external_user_id,  # type: ignore[arg-type]
+                        connector_definition_id=self._connector_definition_id,  # type: ignore[arg-type]
+                    )
 
                 span.set_attribute("connector.connector_id", connector_id)
 

airbyte_agent_amazon_ads/_vendored/connector_sdk/executor/local_executor.py

@@ -36,6 +36,7 @@ from ..types import (
     EndpointDefinition,
     EntityDefinition,
 )
+from ..utils import find_matching_auth_options
 
 from .models import (
     ActionNotSupportedError,
@@ -356,8 +357,8 @@ class LocalExecutor:
     ) -> tuple[AuthOption, dict[str, SecretStr]]:
         """Infer authentication scheme from provided credentials.
 
-        Matches user credentials against each auth option's required fields
-        to determine which scheme to use.
+        Uses shared utility find_matching_auth_options to match credentials
+        against each auth option's required fields.
 
         Args:
             user_credentials: User-provided credentials
@@ -375,16 +376,8 @@ class LocalExecutor:
         # Get the credential keys provided by the user
         provided_keys = set(user_credentials.keys())
 
-        # Find all options where all required fields are present
-        matching_options: list[AuthOption] = []
-        for option in 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)
+        # Use shared utility to find matching options
+        matching_options = find_matching_auth_options(provided_keys, options)
 
         # Handle matching results
         if len(matching_options) == 0:

airbyte_agent_amazon_ads/_vendored/connector_sdk/schema/security.py

@@ -199,6 +199,11 @@ class SecurityScheme(BaseModel):
         alias="x-airbyte-token-extract",
         description="List of fields to extract from OAuth2 token responses and use as server variables",
     )
+    x_airbyte_untested: bool = Field(
+        False,
+        alias="x-airbyte-untested",
+        description="Mark this auth scheme as untested to skip cassette coverage validation",
+    )
 
     @field_validator("x_airbyte_token_extract", mode="after")
     @classmethod

airbyte_agent_amazon_ads/_vendored/connector_sdk/types.py

@@ -90,6 +90,10 @@ class AuthOption(BaseModel):
         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):

airbyte_agent_amazon_ads/_vendored/connector_sdk/utils.py

@@ -1,7 +1,13 @@
 """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(
@@ -58,3 +64,64 @@ async def save_download(
         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

airbyte_agent_amazon_ads/_vendored/connector_sdk/validation.py

@@ -21,7 +21,8 @@ from .connector_model_loader import (
     load_connector_model,
 )
 from .testing.spec_loader import load_test_spec
-from .types import Action, EndpointDefinition
+from .types import Action, ConnectorModel, EndpointDefinition
+from .utils import infer_auth_scheme_name
 from .validation_replication import validate_replication_compatibility
 
 
@@ -53,6 +54,112 @@ def build_cassette_map(cassettes_dir: Path) -> Dict[Tuple[str, str], List[Path]]
     return dict(cassette_map)
 
 
+def build_auth_scheme_coverage(
+    cassettes_dir: Path,
+    auth_options: list | None = None,
+) -> Tuple[Dict[str | None, List[Path]], List[Tuple[Path, set[str]]]]:
+    """Build a map of auth_scheme -> list of cassette paths.
+
+    For multi-auth connectors, infers the auth scheme from the cassette's auth_config
+    keys using the same matching logic as the executor.
+
+    Args:
+        cassettes_dir: Directory containing cassette YAML files
+        auth_options: List of AuthOption from the connector model (for inference)
+
+    Returns:
+        Tuple of:
+        - Dictionary mapping auth_scheme names (or None for single-auth) to cassette paths
+        - List of (cassette_path, auth_config_keys) for cassettes that couldn't be matched
+    """
+    auth_scheme_map: Dict[str | None, List[Path]] = defaultdict(list)
+    unmatched_cassettes: List[Tuple[Path, set[str]]] = []
+
+    if not cassettes_dir.exists() or not cassettes_dir.is_dir():
+        return {}, []
+
+    for cassette_file in cassettes_dir.glob("*.yaml"):
+        try:
+            spec = load_test_spec(cassette_file, auth_config={})
+
+            # First, check if auth_scheme is explicitly set in the cassette
+            if spec.auth_scheme:
+                auth_scheme_map[spec.auth_scheme].append(cassette_file)
+            # Otherwise, try to infer from auth_config keys
+            elif spec.auth_config and auth_options:
+                auth_config_keys = set(spec.auth_config.keys())
+                inferred_scheme = infer_auth_scheme_name(auth_config_keys, auth_options)
+                if inferred_scheme is not None:
+                    auth_scheme_map[inferred_scheme].append(cassette_file)
+                else:
+                    # Couldn't infer - track as unmatched
+                    unmatched_cassettes.append((cassette_file, auth_config_keys))
+            else:
+                # No auth_scheme and no auth_config - treat as None
+                auth_scheme_map[None].append(cassette_file)
+        except Exception:
+            continue
+
+    return dict(auth_scheme_map), unmatched_cassettes
+
+
+def validate_auth_scheme_coverage(
+    config: ConnectorModel,
+    cassettes_dir: Path,
+) -> Tuple[bool, List[str], List[str], List[str], List[Tuple[Path, set[str]]]]:
+    """Validate that each auth scheme has at least one cassette.
+
+    For multi-auth connectors, every defined auth scheme must have coverage
+    unless marked with x-airbyte-untested: true.
+    For single-auth connectors, this check is skipped (existing cassette checks suffice).
+
+    Args:
+        config: Loaded connector model
+        cassettes_dir: Directory containing cassette files
+
+    Returns:
+        Tuple of (is_valid, errors, warnings, covered_schemes, unmatched_cassettes)
+    """
+    errors: List[str] = []
+    warnings: List[str] = []
+
+    # Skip check for single-auth connectors
+    if not config.auth.is_multi_auth():
+        return True, errors, warnings, [], []
+
+    # Get all defined auth schemes, separating tested from untested
+    options = config.auth.options or []
+
+    # Build auth scheme coverage from cassettes (pass options for inference)
+    auth_scheme_coverage, unmatched_cassettes = build_auth_scheme_coverage(cassettes_dir, options)
+    tested_schemes = {opt.scheme_name for opt in options if not opt.untested}
+    untested_schemes = {opt.scheme_name for opt in options if opt.untested}
+    covered_schemes = {scheme for scheme in auth_scheme_coverage.keys() if scheme is not None}
+
+    # Find missing tested schemes (errors)
+    missing_tested = tested_schemes - covered_schemes
+    for scheme in sorted(missing_tested):
+        errors.append(
+            f"Auth scheme '{scheme}' has no cassette coverage. "
+            f"Record at least one cassette using this authentication method, "
+            f"or add 'x-airbyte-untested: true' to skip this check."
+        )
+
+    # Warn about untested schemes without coverage
+    missing_untested = untested_schemes - covered_schemes
+    for scheme in sorted(missing_untested):
+        warnings.append(
+            f"Auth scheme '{scheme}' is marked as untested (x-airbyte-untested: true) " f"and has no cassette coverage. Validation skipped."
+        )
+
+    # Warn about cassettes that couldn't be matched to any auth scheme
+    for cassette_path, auth_config_keys in unmatched_cassettes:
+        warnings.append(f"Cassette '{cassette_path.name}' could not be matched to any auth scheme. " f"auth_config keys: {sorted(auth_config_keys)}")
+
+    is_valid = len(missing_tested) == 0
+    return is_valid, errors, warnings, sorted(covered_schemes), unmatched_cassettes
+
+
 def validate_response_against_schema(response_body: Any, schema: Dict[str, Any]) -> Tuple[bool, List[str]]:
     """Validate a response body against a JSON schema.
 
@@ -588,6 +695,9 @@ def validate_connector_readiness(connector_dir: str | Path) -> Dict[str, Any]:
     cassettes_dir = connector_path / "tests" / "cassettes"
     cassette_map = build_cassette_map(cassettes_dir)
 
+    # Validate auth scheme coverage for multi-auth connectors
+    auth_valid, auth_errors, auth_warnings, auth_covered_schemes, auth_unmatched_cassettes = validate_auth_scheme_coverage(config, cassettes_dir)
+
     validation_results = []
     total_operations = 0
     operations_with_cassettes = 0
@@ -827,8 +937,12 @@ def validate_connector_readiness(connector_dir: str | Path) -> Dict[str, Any]:
     if replication_result.get("registry_found", False):
         total_warnings += len(replication_warnings)
 
-    # Update success criteria to include replication validation
-    success = operations_missing_cassettes == 0 and cassettes_invalid == 0 and total_operations > 0 and len(replication_errors) == 0
+    # Merge auth scheme validation errors/warnings into totals
+    total_errors += len(auth_errors)
+    total_warnings += len(auth_warnings)
+
+    # Update success criteria to include replication and auth scheme validation
+    success = operations_missing_cassettes == 0 and cassettes_invalid == 0 and total_operations > 0 and len(replication_errors) == 0 and auth_valid
 
     # Check for preferred_for_check on at least one list operation
     has_preferred_check = False
@@ -849,12 +963,26 @@ def validate_connector_readiness(connector_dir: str | Path) -> Dict[str, Any]:
             "to enable reliable health checks."
         )
 
+    # Build auth scheme validation result
+    options = config.auth.options or []
+    tested_schemes = [opt.scheme_name for opt in options if not opt.untested]
+    untested_schemes_list = [opt.scheme_name for opt in options if opt.untested]
+    missing_tested = [s for s in tested_schemes if s not in auth_covered_schemes]
+
     return {
         "success": success,
         "connector_name": config.name,
         "connector_path": str(connector_path),
         "validation_results": validation_results,
         "replication_validation": replication_result,
+        "auth_scheme_validation": {
+            "valid": auth_valid,
+            "errors": auth_errors,
+            "warnings": auth_warnings,
+            "covered_schemes": auth_covered_schemes,
+            "missing_schemes": missing_tested,
+            "untested_schemes": untested_schemes_list,
+        },
         "readiness_warnings": readiness_warnings,
         "summary": {
             "total_operations": total_operations,

airbyte_agent_amazon_ads/connector.py

@@ -30,6 +30,7 @@ from .types import (
 )
 if TYPE_CHECKING:
     from .models import AmazonAdsAuthConfig
+
 # Import response models and envelope models at runtime
 from .models import (
     AmazonAdsCheckResult,
@@ -122,6 +123,7 @@ class AmazonAdsConnector:
         external_user_id: str | None = None,
         airbyte_client_id: str | None = None,
         airbyte_client_secret: str | None = None,
+        connector_id: str | None = None,
         on_token_refresh: Any | None = None,
         region: str | None = None    ):
         """
@@ -129,13 +131,14 @@ class AmazonAdsConnector:
 
         Supports both local and hosted execution modes:
         - Local mode: Provide `auth_config` for direct API calls
-        - Hosted mode: Provide `external_user_id`, `airbyte_client_id`, and `airbyte_client_secret` for hosted execution
+        - Hosted mode: Provide Airbyte credentials with either `connector_id` or `external_user_id`
 
         Args:
             auth_config: Typed authentication configuration (required for local mode)
-            external_user_id: External user ID (required for hosted mode)
+            external_user_id: External user ID (for hosted mode lookup)
             airbyte_client_id: Airbyte OAuth client ID (required for hosted mode)
             airbyte_client_secret: Airbyte OAuth client secret (required for hosted mode)
+            connector_id: Specific connector/source ID (for hosted mode, skips lookup)
             on_token_refresh: Optional callback for OAuth2 token refresh persistence.
                 Called with new_tokens dict when tokens are refreshed. Can be sync or async.
                 Example: lambda tokens: save_to_database(tokens)            region: The Amazon Ads API endpoint URL based on region:
@@ -146,7 +149,14 @@ class AmazonAdsConnector:
         Examples:
             # Local mode (direct API calls)
             connector = AmazonAdsConnector(auth_config=AmazonAdsAuthConfig(client_id="...", client_secret="...", refresh_token="..."))
-            # Hosted mode (executed on Airbyte cloud)
+            # Hosted mode with explicit connector_id (no lookup needed)
+            connector = AmazonAdsConnector(
+                airbyte_client_id="client_abc123",
+                airbyte_client_secret="secret_xyz789",
+                connector_id="existing-source-uuid"
+            )
+
+            # Hosted mode with lookup by external_user_id
             connector = AmazonAdsConnector(
                 external_user_id="user-123",
                 airbyte_client_id="client_abc123",
@@ -164,21 +174,24 @@ class AmazonAdsConnector:
                 on_token_refresh=save_tokens
             )
         """
-        # Hosted mode: external_user_id, airbyte_client_id, and airbyte_client_secret provided
-        if external_user_id and airbyte_client_id and airbyte_client_secret:
+        # Hosted mode: Airbyte credentials + either connector_id OR external_user_id
+        is_hosted = airbyte_client_id and airbyte_client_secret and (connector_id or external_user_id)
+
+        if is_hosted:
             from ._vendored.connector_sdk.executor import HostedExecutor
             self._executor = HostedExecutor(
-                external_user_id=external_user_id,
                 airbyte_client_id=airbyte_client_id,
                 airbyte_client_secret=airbyte_client_secret,
-                connector_definition_id=str(AmazonAdsConnectorModel.id),
+                connector_id=connector_id,
+                external_user_id=external_user_id,
+                connector_definition_id=str(AmazonAdsConnectorModel.id) if not connector_id else None,
             )
         else:
             # Local mode: auth_config required
             if not auth_config:
                 raise ValueError(
-                    "Either provide (external_user_id, airbyte_client_id, airbyte_client_secret) for hosted mode "
-                    "or auth_config for local mode"
+                    "Either provide Airbyte credentials (airbyte_client_id, airbyte_client_secret) with "
+                    "connector_id or external_user_id for hosted mode, or auth_config for local mode"
                 )
 
             from ._vendored.connector_sdk.executor import LocalExecutor
@@ -478,6 +491,183 @@ class AmazonAdsConnector:
             )
         return entity_def.entity_schema if entity_def else None
 
+    @property
+    def connector_id(self) -> str | None:
+        """Get the connector/source ID (only available in hosted mode).
+
+        Returns:
+            The connector ID if in hosted mode, None if in local mode.
+
+        Example:
+            connector = await AmazonAdsConnector.create_hosted(...)
+            print(f"Created connector: {connector.connector_id}")
+        """
+        if hasattr(self, '_executor') and hasattr(self._executor, '_connector_id'):
+            return self._executor._connector_id
+        return None
+
+    # ===== HOSTED MODE FACTORY =====
+
+    @classmethod
+    async def initiate_oauth(
+        cls,
+        *,
+        external_user_id: str,
+        redirect_url: str,
+        airbyte_client_id: str,
+        airbyte_client_secret: str,
+    ) -> str:
+        """
+        Initiate server-side OAuth flow for this connector.
+
+        Returns a consent URL where the end user should be redirected to grant access.
+        After completing consent, they'll be redirected to your redirect_url with a
+        `server_side_oauth_secret_id` query parameter that can be used with `create_hosted()`.
+
+        Args:
+            external_user_id: Workspace identifier in Airbyte Cloud
+            redirect_url: URL where users will be redirected after OAuth consent
+            airbyte_client_id: Airbyte OAuth client ID
+            airbyte_client_secret: Airbyte OAuth client secret
+
+        Returns:
+            The OAuth consent URL
+
+        Example:
+            consent_url = await AmazonAdsConnector.initiate_oauth(
+                external_user_id="my-workspace",
+                redirect_url="https://myapp.com/oauth/callback",
+                airbyte_client_id="client_abc",
+                airbyte_client_secret="secret_xyz",
+            )
+            # Redirect user to: consent_url
+            # After consent, user arrives at: https://myapp.com/oauth/callback?server_side_oauth_secret_id=...
+        """
+        from ._vendored.connector_sdk.cloud_utils import AirbyteCloudClient
+
+        client = AirbyteCloudClient(
+            client_id=airbyte_client_id,
+            client_secret=airbyte_client_secret,
+        )
+
+        try:
+            consent_url = await client.initiate_oauth(
+                definition_id=str(AmazonAdsConnectorModel.id),
+                external_user_id=external_user_id,
+                redirect_url=redirect_url,
+            )
+        finally:
+            await client.close()
+
+        return consent_url
+
+    @classmethod
+    async def create_hosted(
+        cls,
+        *,
+        external_user_id: str,
+        airbyte_client_id: str,
+        airbyte_client_secret: str,
+        auth_config: "AmazonAdsAuthConfig" | None = None,
+        server_side_oauth_secret_id: str | None = None,
+        name: str | None = None,
+        replication_config: dict[str, Any] | None = None,
+        source_template_id: str | None = None,
+    ) -> "AmazonAdsConnector":
+        """
+        Create a new hosted connector on Airbyte Cloud.
+
+        This factory method:
+        1. Creates a source on Airbyte Cloud with the provided credentials
+        2. Returns a connector configured with the new connector_id
+
+        Supports two authentication modes:
+        1. Direct credentials: Provide `auth_config` with typed credentials
+        2. Server-side OAuth: Provide `server_side_oauth_secret_id` from OAuth flow
+
+        Args:
+            external_user_id: Workspace identifier in Airbyte Cloud
+            airbyte_client_id: Airbyte OAuth client ID
+            airbyte_client_secret: Airbyte OAuth client secret
+            auth_config: Typed auth config. Required unless using server_side_oauth_secret_id.
+            server_side_oauth_secret_id: OAuth secret ID from initiate_oauth redirect.
+                When provided, auth_config is not required.
+            name: Optional source name (defaults to connector name + external_user_id)
+            replication_config: Optional replication settings dict.
+                Required for connectors with x-airbyte-replication-config (REPLICATION mode sources).
+            source_template_id: Source template ID. Required when organization has
+                multiple source templates for this connector type.
+
+        Returns:
+            A AmazonAdsConnector instance configured in hosted mode
+
+        Raises:
+            ValueError: If neither or both auth_config and server_side_oauth_secret_id provided
+
+        Example:
+            # Create a new hosted connector with API key auth
+            connector = await AmazonAdsConnector.create_hosted(
+                external_user_id="my-workspace",
+                airbyte_client_id="client_abc",
+                airbyte_client_secret="secret_xyz",
+                auth_config=AmazonAdsAuthConfig(client_id="...", client_secret="...", refresh_token="..."),
+            )
+
+            # With server-side OAuth:
+            connector = await AmazonAdsConnector.create_hosted(
+                external_user_id="my-workspace",
+                airbyte_client_id="client_abc",
+                airbyte_client_secret="secret_xyz",
+                server_side_oauth_secret_id="airbyte_oauth_..._secret_...",
+            )
+
+            # Use the connector
+            result = await connector.execute("entity", "list", {})
+        """
+        # Validate: exactly one of auth_config or server_side_oauth_secret_id required
+        if auth_config is None and server_side_oauth_secret_id is None:
+            raise ValueError(
+                "Either auth_config or server_side_oauth_secret_id must be provided"
+            )
+        if auth_config is not None and server_side_oauth_secret_id is not None:
+            raise ValueError(
+                "Cannot provide both auth_config and server_side_oauth_secret_id"
+            )
+
+        from ._vendored.connector_sdk.cloud_utils import AirbyteCloudClient
+
+        client = AirbyteCloudClient(
+            client_id=airbyte_client_id,
+            client_secret=airbyte_client_secret,
+        )
+
+        try:
+            # Build credentials from auth_config (if provided)
+            credentials = auth_config.model_dump(exclude_none=True) if auth_config else None
+            replication_config_dict = replication_config.model_dump(exclude_none=True) if replication_config else None
+
+            # Create source on Airbyte Cloud
+            source_name = name or f"{cls.connector_name} - {external_user_id}"
+            source_id = await client.create_source(
+                name=source_name,
+                connector_definition_id=str(AmazonAdsConnectorModel.id),
+                external_user_id=external_user_id,
+                credentials=credentials,
+                replication_config=replication_config_dict,
+                server_side_oauth_secret_id=server_side_oauth_secret_id,
+                source_template_id=source_template_id,
+            )
+        finally:
+            await client.close()
+
+        # Return connector configured with the new connector_id
+        return cls(
+            airbyte_client_id=airbyte_client_id,
+            airbyte_client_secret=airbyte_client_secret,
+            connector_id=source_id,
+        )
+
+
 
 
 class ProfilesQuery:

{airbyte_agent_amazon_ads-0.1.23.dist-info → airbyte_agent_amazon_ads-0.1.25.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: airbyte-agent-amazon-ads
-Version: 0.1.23
+Version: 0.1.25
 Summary: Airbyte Amazon-Ads Connector for AI platforms
 Project-URL: Homepage, https://github.com/airbytehq/airbyte-agent-connectors
 Project-URL: Documentation, https://docs.airbyte.com/ai-agents/
@@ -135,7 +135,7 @@ See the official [Amazon-Ads API reference](https://advertising.amazon.com/API/d
 
 ## Version information
 
-- **Package version:** 0.1.23
+- **Package version:** 0.1.25
 - **Connector version:** 1.0.5
-- **Generated with Connector SDK commit SHA:** 580ea1221eff062f41b1065a155124c85861cb18
+- **Generated with Connector SDK commit SHA:** 9d9866b0aae8c3494d04d34e193b9bd860bfc1c6
 - **Changelog:** [View changelog](https://github.com/airbytehq/airbyte-agent-connectors/blob/main/connectors/amazon-ads/CHANGELOG.md)

{airbyte_agent_amazon_ads-0.1.23.dist-info → airbyte_agent_amazon_ads-0.1.25.dist-info}/RECORD

@@ -1,5 +1,5 @@
 airbyte_agent_amazon_ads/__init__.py,sha256=MICR9abWiXLcSQ0jd4W7S6xyo2KgwRjOPIZTeHpz67I,1950
-airbyte_agent_amazon_ads/connector.py,sha256=lgYzmFTnjjGlMCmDAN-l3FlTYOZDTdOAQ3c7Re5B89g,25456
+airbyte_agent_amazon_ads/connector.py,sha256=9r5mxeos61jzP-tTNJf4UB2h6XCXoMs5T5E7r2xhqFg,33158
 airbyte_agent_amazon_ads/connector_model.py,sha256=QAxt_l2-RjUBxg2izmclOPTqVrjF9CL70fOkkYcwpTk,98041
 airbyte_agent_amazon_ads/models.py,sha256=KmYWz46e-8HuQdnuz6FQT99uDKwpcToEc9Xda2M7FL4,9781
 airbyte_agent_amazon_ads/types.py,sha256=EW-jvOmXyJQqe2ESiDCs7nCIIsFreDCIZBlA6aplxpA,6728
@@ -7,22 +7,22 @@ airbyte_agent_amazon_ads/_vendored/__init__.py,sha256=ILl7AHXMui__swyrjxrh9yRa4d
 airbyte_agent_amazon_ads/_vendored/connector_sdk/__init__.py,sha256=T5o7roU6NSpH-lCAGZ338sE5dlh4ZU6i6IkeG1zpems,1949
 airbyte_agent_amazon_ads/_vendored/connector_sdk/auth_strategies.py,sha256=5Sb9moUp623o67Q2wMa8iZldJH08y4gQdoutoO_75Iw,42088
 airbyte_agent_amazon_ads/_vendored/connector_sdk/auth_template.py,sha256=nju4jqlFC_KI82ILNumNIyiUtRJcy7J94INIZ0QraI4,4454
-airbyte_agent_amazon_ads/_vendored/connector_sdk/connector_model_loader.py,sha256=ecm0Cdj1SyhDOpEi2wUzzrJNkgt0wViB0Q-YTrDPsjU,41698
+airbyte_agent_amazon_ads/_vendored/connector_sdk/connector_model_loader.py,sha256=1AAvSvjxM9Nuto6w7D6skN5VXGb4e6na0lMFcFmmVkI,41761
 airbyte_agent_amazon_ads/_vendored/connector_sdk/constants.py,sha256=AtzOvhDMWbRJgpsQNWl5tkogHD6mWgEY668PgRmgtOY,2737
 airbyte_agent_amazon_ads/_vendored/connector_sdk/exceptions.py,sha256=ss5MGv9eVPmsbLcLWetuu3sDmvturwfo6Pw3M37Oq5k,481
 airbyte_agent_amazon_ads/_vendored/connector_sdk/extensions.py,sha256=XWRRoJOOrwUHSKbuQt5DU7CCu8ePzhd_HuP7c_uD77w,21376
 airbyte_agent_amazon_ads/_vendored/connector_sdk/http_client.py,sha256=09Fclbq4wrg38EM2Yh2kHiykQVXqdAGby024elcEz8E,28027
 airbyte_agent_amazon_ads/_vendored/connector_sdk/introspection.py,sha256=e9uWn2ofpeehoBbzNgts_bjlKLn8ayA1Y3OpDC3b7ZA,19517
 airbyte_agent_amazon_ads/_vendored/connector_sdk/secrets.py,sha256=J9ezMu4xNnLW11xY5RCre6DHP7YMKZCqwGJfk7ufHAM,6855
-airbyte_agent_amazon_ads/_vendored/connector_sdk/types.py,sha256=sRZ4rRkJXGfqdjfF3qb0kzrw_tu1cn-CmFSZKMMgF7o,9269
-airbyte_agent_amazon_ads/_vendored/connector_sdk/utils.py,sha256=G4LUXOC2HzPoND2v4tQW68R9uuPX9NQyCjaGxb7Kpl0,1958
-airbyte_agent_amazon_ads/_vendored/connector_sdk/validation.py,sha256=iz1wo5CrHT_yD4elBGM9TSCFAegVmkEZiRKCpjSu7IA,33997
+airbyte_agent_amazon_ads/_vendored/connector_sdk/types.py,sha256=MsWJsQy779r7Mqiqf_gh_4Vs6VDqieoMjLPyWt7qhu8,9412
+airbyte_agent_amazon_ads/_vendored/connector_sdk/utils.py,sha256=UYwYuSLhsDD-4C0dBs7Qy0E0gIcFZXb6VWadJORhQQU,4080
+airbyte_agent_amazon_ads/_vendored/connector_sdk/validation.py,sha256=w5WGnmILkdBslpXhAXhKhE-c8ANBc_OZQxr_fUeAgtc,39666
 airbyte_agent_amazon_ads/_vendored/connector_sdk/validation_replication.py,sha256=v7F5YWd5m4diIF7_4m4nOkC9crg97vqRUUkt9ka9HZ4,36043
 airbyte_agent_amazon_ads/_vendored/connector_sdk/cloud_utils/__init__.py,sha256=4799Hv9f2zxDVj1aLyQ8JpTEuFTp_oOZMRz-NZCdBJg,134
-airbyte_agent_amazon_ads/_vendored/connector_sdk/cloud_utils/client.py,sha256=YxdRpQr9XjDzih6csSseBVGn9kfMtaqbOCXP0TPuzFY,7189
+airbyte_agent_amazon_ads/_vendored/connector_sdk/cloud_utils/client.py,sha256=e0VLNCmesGGfo2uD0GiICgXsXTeTkh0GYiVgx_e4VEc,12296
 airbyte_agent_amazon_ads/_vendored/connector_sdk/executor/__init__.py,sha256=EmG9YQNAjSuYCVB4D5VoLm4qpD1KfeiiOf7bpALj8p8,702
-airbyte_agent_amazon_ads/_vendored/connector_sdk/executor/hosted_executor.py,sha256=AC5aJtdcMPQfRuam0ZGE4QdhUBu2oGEmNZ6oVQLHTE8,7212
-airbyte_agent_amazon_ads/_vendored/connector_sdk/executor/local_executor.py,sha256=l2b0VILgtOlUNyG19J0UkbCa6rJXkU8g1uzLot8BJjQ,77008
+airbyte_agent_amazon_ads/_vendored/connector_sdk/executor/hosted_executor.py,sha256=tv0njAdy-gdHBg4izgcxhEWYbrNiBifEYEca9AWzaL0,8693
+airbyte_agent_amazon_ads/_vendored/connector_sdk/executor/local_executor.py,sha256=RtdTXFzfoJz5Coz9nwQi81Df1402BRgO1Mgd3ZzTkfw,76581
 airbyte_agent_amazon_ads/_vendored/connector_sdk/executor/models.py,sha256=mUUBnuShKXxVIfsTOhMiI2rn2a-50jJG7SFGKT_P6Jk,6281
 airbyte_agent_amazon_ads/_vendored/connector_sdk/http/__init__.py,sha256=y8fbzZn-3yV9OxtYz8Dy6FFGI5v6TOqADd1G3xHH3Hw,911
 airbyte_agent_amazon_ads/_vendored/connector_sdk/http/config.py,sha256=6J7YIIwHC6sRu9i-yKa5XvArwK2KU60rlnmxzDZq3lw,3283
@@ -48,11 +48,11 @@ airbyte_agent_amazon_ads/_vendored/connector_sdk/schema/components.py,sha256=nJI
 airbyte_agent_amazon_ads/_vendored/connector_sdk/schema/connector.py,sha256=mSZk1wr2YSdRj9tTRsPAuIlCzd_xZLw-Bzl1sMwE0rE,3731
 airbyte_agent_amazon_ads/_vendored/connector_sdk/schema/extensions.py,sha256=5hgpFHK7fzpzegCkJk882DeIP79bCx_qairKJhvPMZ8,9590
 airbyte_agent_amazon_ads/_vendored/connector_sdk/schema/operations.py,sha256=St-A75m6sZUZlsoM6WcoPaShYu_X1K19pdyPvJbabOE,6214
-airbyte_agent_amazon_ads/_vendored/connector_sdk/schema/security.py,sha256=1CVCavrPdHHyk7B6JtUD75yRS_hWLCemZF1zwGbdqxg,9036
+airbyte_agent_amazon_ads/_vendored/connector_sdk/schema/security.py,sha256=R-21DLnp-ANIRO1Dzqo53TYFJL6lCp0aO8GSuxa_bDI,9225
 airbyte_agent_amazon_ads/_vendored/connector_sdk/telemetry/__init__.py,sha256=RaLgkBU4dfxn1LC5Y0Q9rr2PJbrwjxvPgBLmq8_WafE,211
 airbyte_agent_amazon_ads/_vendored/connector_sdk/telemetry/config.py,sha256=tLmQwAFD0kP1WyBGWBS3ysaudN9H3e-3EopKZi6cGKg,885
 airbyte_agent_amazon_ads/_vendored/connector_sdk/telemetry/events.py,sha256=8Y1NbXiwISX-V_wRofY7PqcwEXD0dLMnntKkY6XFU2s,1328
 airbyte_agent_amazon_ads/_vendored/connector_sdk/telemetry/tracker.py,sha256=SginFQbHqVUVYG82NnNzG34O-tAQ_wZYjGDcuo0q4Kk,5584
-airbyte_agent_amazon_ads-0.1.23.dist-info/METADATA,sha256=vx6N_n2UUPIp2UU7llrnkFlQbKeae4DBW_Xp-C3YeoU,5326
-airbyte_agent_amazon_ads-0.1.23.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-airbyte_agent_amazon_ads-0.1.23.dist-info/RECORD,,
+airbyte_agent_amazon_ads-0.1.25.dist-info/METADATA,sha256=mgsYZFR2QZ1zOj3x28WcdeuxnD6HibWamIMoq6vwF3o,5326
+airbyte_agent_amazon_ads-0.1.25.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+airbyte_agent_amazon_ads-0.1.25.dist-info/RECORD,,