airbyte-agent-mailchimp 0.1.4__py3-none-any.whl

airbyte_agent_mailchimp/_vendored/connector_sdk/schema/extensions.py

@@ -0,0 +1,230 @@
+"""
+Extension models for future features.
+
+These models are defined but NOT yet added to the main schema models.
+They serve as:
+1. Type hints for future use
+2. Documentation of planned extensions
+3. Ready-to-use structures when features are implemented
+
+NOTE: These are not currently active in the schema. They will be added
+to Operation, Schema, or other models when their respective features
+are implemented.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class PaginationConfig(BaseModel):
+    """
+    Configuration for pagination support.
+
+    NOT YET USED - Defined for future implementation.
+
+    When active, will be added to Operation model as:
+        x_pagination: Optional[PaginationConfig] = Field(None, alias="x-pagination")
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    style: Literal["cursor", "offset", "page", "link"]
+    limit_param: str = "limit"
+
+    # Cursor-based pagination
+    cursor_param: str | None = None
+    cursor_source: Literal["body", "headers"] | None = "body"
+    cursor_path: str | None = None
+
+    # Offset-based pagination
+    offset_param: str | None = None
+
+    # Page-based pagination
+    page_param: str | None = None
+
+    # Response parsing
+    data_path: str = "data"
+    has_more_path: str | None = None
+
+    # Limits
+    max_page_size: int | None = None
+    default_page_size: int = 100
+
+
+class RateLimitConfig(BaseModel):
+    """
+    Configuration for rate limiting.
+
+    NOT YET USED - Defined for future implementation.
+
+    When active, might be added to Server or root OpenAPIConnector as:
+        x_rate_limit: Optional[RateLimitConfig] = Field(None, alias="x-rate-limit")
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    max_requests: int
+    time_window_seconds: int
+    retry_after_header: str | None = "Retry-After"
+    respect_retry_after: bool = True
+
+
+class RetryConfig(BaseModel):
+    """
+    Configuration for retry strategy with exponential backoff.
+
+    Used to configure automatic retries for transient errors (429, 5xx, timeouts, network errors).
+    Can be specified at the connector level via x-airbyte-retry-config in the OpenAPI spec's info section.
+
+    By default, retries are enabled with max_attempts=3. To disable retries, set max_attempts=1
+    in your connector's x-airbyte-retry-config.
+
+    Example YAML usage:
+        info:
+          title: My API
+          x-airbyte-retry-config:
+            max_attempts: 5
+            initial_delay_seconds: 2.0
+            retry_after_header: "X-RateLimit-Reset"
+            retry_after_format: "unix_timestamp"
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    # Core retry settings (max_attempts=3 enables retries by default)
+    max_attempts: int = 3
+    initial_delay_seconds: float = 1.0
+    max_delay_seconds: float = 60.0
+    exponential_base: float = 2.0
+    jitter: bool = True
+
+    # Which errors to retry
+    retry_on_status_codes: list[int] = [429, 500, 502, 503, 504]
+    retry_on_timeout: bool = True
+    retry_on_network_error: bool = True
+
+    # Header-based delay extraction
+    retry_after_header: str = "Retry-After"
+    retry_after_format: Literal["seconds", "milliseconds", "unix_timestamp"] = "seconds"
+
+
+class CacheFieldProperty(BaseModel):
+    """
+    Nested property definition for object-type cache fields.
+
+    Supports recursive nesting to represent complex nested schemas in cache field definitions.
+    Used when a cache field has type 'object' and needs to define its internal structure.
+
+    Example YAML usage:
+        - name: collaboration
+          type: ['null', 'object']
+          description: "Collaboration data"
+          properties:
+            brief:
+              type: ['null', 'string']
+            comments:
+              type: ['null', 'array']
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    type: str | list[str]
+    properties: dict[str, "CacheFieldProperty"] | None = None
+
+
+class CacheFieldConfig(BaseModel):
+    """
+    Field configuration for cache mapping.
+
+    Defines a single field in a cache entity, with optional name aliasing
+    to map between user-facing field names and cache storage names.
+
+    For object-type fields, supports nested properties to define the internal structure
+    of complex nested schemas.
+
+    Used in x-airbyte-cache extension for api_search operations.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    name: str
+    x_airbyte_name: str | None = Field(default=None, alias="x-airbyte-name")
+    type: str | list[str]
+    description: str
+    properties: dict[str, CacheFieldProperty] | None = None
+
+    @property
+    def cache_name(self) -> str:
+        """Return cache name, falling back to name if alias not specified."""
+        return self.x_airbyte_name or self.name
+
+
+class CacheEntityConfig(BaseModel):
+    """
+    Entity configuration for cache mapping.
+
+    Defines a cache-enabled entity with its fields and optional name aliasing
+    to map between user-facing entity names and cache storage names.
+
+    Used in x-airbyte-cache extension for api_search operations.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    entity: str
+    x_airbyte_name: str | None = Field(default=None, alias="x-airbyte-name")
+    fields: list[CacheFieldConfig]
+
+    @property
+    def cache_name(self) -> str:
+        """Return cache entity name, falling back to entity if alias not specified."""
+        return self.x_airbyte_name or self.entity
+
+
+class CacheConfig(BaseModel):
+    """
+    Cache configuration extension (x-airbyte-cache).
+
+    Defines cache-enabled entities and their field mappings for api_search operations.
+    Supports optional name aliasing via x-airbyte-name for both entities and fields,
+    enabling bidirectional mapping between user-facing names and cache storage names.
+
+    This extension is added to the Info model and provides field-level mapping for
+    search operations that use cached data.
+
+    Example YAML usage:
+        info:
+          title: Stripe API
+          x-airbyte-cache:
+            entities:
+              - entity: customers
+                stream: customers
+                fields:
+                  - name: email
+                    type: ["null", "string"]
+                    description: "Customer email address"
+                  - name: customer_name
+                    x-airbyte-name: name
+                    type: ["null", "string"]
+                    description: "Customer full name"
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    entities: list[CacheEntityConfig]
+
+    def get_entity_mapping(self, user_entity: str) -> CacheEntityConfig | None:
+        """
+        Get entity config by user-facing name.
+
+        Args:
+            user_entity: User-facing entity name to look up
+
+        Returns:
+            CacheEntityConfig if found, None otherwise
+        """
+        for entity in self.entities:
+            if entity.entity == user_entity:
+                return entity
+        return None

airbyte_agent_mailchimp/_vendored/connector_sdk/schema/operations.py

@@ -0,0 +1,146 @@
+"""
+Operation and PathItem models for OpenAPI 3.1.
+
+References:
+- https://spec.openapis.org/oas/v3.1.0#operation-object
+- https://spec.openapis.org/oas/v3.1.0#path-item-object
+"""
+
+from typing import Any, Dict, List
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ..extensions import ActionTypeLiteral
+from .components import Parameter, PathOverrideConfig, RequestBody, Response
+from .security import SecurityRequirement
+
+
+class Operation(BaseModel):
+    """
+    Single API operation (GET, POST, PUT, PATCH, DELETE, etc.).
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#operation-object
+
+    Extensions:
+    - x-airbyte-entity: Entity name (Airbyte extension)
+    - x-airbyte-action: Semantic action (Airbyte extension)
+    - x-airbyte-path-override: Path override (Airbyte extension)
+    - x-airbyte-record-extractor: JSONPath to extract records from response (Airbyte extension)
+
+    Future extensions (not yet active):
+    - x-airbyte-pagination: Pagination configuration for list operations
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    # Standard OpenAPI fields
+    tags: List[str] | None = None
+    summary: str | None = None
+    description: str | None = None
+    external_docs: Dict[str, Any] | None = Field(None, alias="externalDocs")
+    operation_id: str | None = Field(None, alias="operationId")
+    parameters: List[Parameter] | None = None
+    request_body: RequestBody | None = Field(None, alias="requestBody")
+    responses: Dict[str, Response] = Field(default_factory=dict)
+    callbacks: Dict[str, Any] | None = None
+    deprecated: bool | None = None
+    security: List[SecurityRequirement] | None = None
+    servers: List[Any] | None = None  # Can override root servers
+
+    # Airbyte extensions
+    x_airbyte_entity: str = Field(..., alias="x-airbyte-entity")
+    x_airbyte_action: ActionTypeLiteral = Field(..., alias="x-airbyte-action")
+    x_airbyte_path_override: PathOverrideConfig | None = Field(
+        None,
+        alias="x-airbyte-path-override",
+        description=("Override path for HTTP requests when OpenAPI path differs from actual endpoint"),
+    )
+    x_airbyte_record_extractor: str | None = Field(
+        None,
+        alias="x-airbyte-record-extractor",
+        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/api_search actions, single record for "
+            "get/create/update/delete actions."
+        ),
+    )
+    x_airbyte_meta_extractor: Dict[str, str] | None = Field(
+        None,
+        alias="x-airbyte-meta-extractor",
+        description=(
+            "Dictionary mapping field names to JSONPath expressions for extracting "
+            "metadata (pagination info, request IDs, etc.) from API response envelopes. "
+            "Each key becomes a field in ExecutionResult.meta with the value extracted "
+            "using the corresponding JSONPath expression. "
+            "Example: {'pagination': '$.pagination', 'request_id': '$.requestId'}"
+        ),
+    )
+    x_airbyte_file_url: str | None = Field(None, alias="x-airbyte-file-url")
+    x_airbyte_untested: bool | None = Field(
+        None,
+        alias="x-airbyte-untested",
+        description=(
+            "Mark operation as untested to skip cassette validation in readiness checks. "
+            "Use this for operations that cannot be recorded (e.g., webhooks, real-time streams). "
+            "Validation will generate a warning instead of an error when cassettes are missing."
+        ),
+    )
+
+    # Future extensions (commented out, defined for future use)
+    # from .extensions import PaginationConfig
+    # x_pagination: Optional[PaginationConfig] = Field(None, alias="x-airbyte-pagination")
+
+    @model_validator(mode="after")
+    def validate_download_action_requirements(self) -> "Operation":
+        """
+        Validate download operation requirements.
+
+        Rules:
+        - If x-airbyte-action is "download":
+          - x-airbyte-file-url must be non-empty if provided
+        - If x-airbyte-action is not "download":
+          - x-airbyte-file-url must not be present
+        """
+        action = self.x_airbyte_action
+        file_url = self.x_airbyte_file_url
+
+        if action == "download":
+            # If file_url is provided, it must be non-empty
+            if file_url is not None and not file_url.strip():
+                raise ValueError("x-airbyte-file-url must be non-empty when provided for download operations")
+        else:
+            # Non-download actions cannot have file_url
+            if file_url is not None:
+                raise ValueError(f"x-airbyte-file-url can only be used with x-airbyte-action: download, but action is '{action}'")
+
+        return self
+
+
+class PathItem(BaseModel):
+    """
+    Path item containing operations for different HTTP methods.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#path-item-object
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    # Common fields for all operations
+    summary: str | None = None
+    description: str | None = None
+    servers: List[Any] | None = None
+    parameters: List[Parameter] | None = None
+
+    # HTTP methods (all optional)
+    get: Operation | None = None
+    put: Operation | None = None
+    post: Operation | None = None
+    delete: Operation | None = None
+    options: Operation | None = None
+    head: Operation | None = None
+    patch: Operation | None = None
+    trace: Operation | None = None
+
+    # Reference support
+    ref: str | None = Field(None, alias="$ref")

airbyte_agent_mailchimp/_vendored/connector_sdk/schema/security.py

@@ -0,0 +1,223 @@
+"""
+Security scheme models for OpenAPI 3.1.
+
+References:
+- https://spec.openapis.org/oas/v3.1.0#security-scheme-object
+- https://spec.openapis.org/oas/v3.1.0#oauth-flows-object
+"""
+
+from typing import Any, Dict, List, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+class OAuth2Flow(BaseModel):
+    """
+    OAuth 2.0 flow configuration.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#oauth-flow-object
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    authorization_url: str | None = Field(None, alias="authorizationUrl")
+    token_url: str | None = Field(None, alias="tokenUrl")
+    refresh_url: str | None = Field(None, alias="refreshUrl")
+    scopes: Dict[str, str] = Field(default_factory=dict)
+
+
+class OAuth2Flows(BaseModel):
+    """
+    Collection of OAuth 2.0 flows.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#oauth-flows-object
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    implicit: OAuth2Flow | None = None
+    password: OAuth2Flow | None = None
+    client_credentials: OAuth2Flow | None = Field(None, alias="clientCredentials")
+    authorization_code: OAuth2Flow | None = Field(None, alias="authorizationCode")
+
+
+class AuthConfigFieldSpec(BaseModel):
+    """
+    Specification for a user-facing authentication config field.
+
+    This defines a single input field that users provide for authentication.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    type: Literal["string", "integer", "boolean", "number"] = "string"
+    title: str | None = None
+    description: str | None = None
+    format: str | None = None  # e.g., "email", "uri"
+    pattern: str | None = None  # Regex validation
+    airbyte_secret: bool = Field(False, alias="airbyte_secret")
+    default: Any | None = None
+
+
+class AuthConfigOption(BaseModel):
+    """
+    A single authentication configuration option.
+
+    Defines user-facing fields and how they map to auth parameters.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    title: str | None = None
+    description: str | None = None
+    type: Literal["object"] = "object"
+    required: List[str] = Field(default_factory=list)
+    properties: Dict[str, AuthConfigFieldSpec] = Field(default_factory=dict)
+    auth_mapping: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Mapping from auth parameters (e.g., 'username', 'password', 'token') to template strings using ${field} syntax",
+    )
+    replication_auth_key_mapping: Dict[str, str] | None = Field(
+        None,
+        description="Mapping from source config paths (e.g., 'credentials.api_key') to auth config keys for direct connectors",
+    )
+
+
+class AirbyteAuthConfig(BaseModel):
+    """
+    Airbyte auth configuration extension (x-airbyte-auth-config).
+
+    Defines user-facing authentication configuration and how it maps to
+    the underlying OpenAPI security scheme.
+
+    Either a single auth option or multiple options via oneOf.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    # Single option fields
+    title: str | None = None
+    description: str | None = None
+    type: Literal["object"] | None = None
+    required: List[str] | None = None
+    properties: Dict[str, AuthConfigFieldSpec] | None = None
+    auth_mapping: Dict[str, str] | None = None
+
+    # Replication connector auth mapping
+    replication_auth_key_mapping: Dict[str, str] | None = 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: List[AuthConfigOption] | None = Field(None, alias="oneOf")
+
+    @model_validator(mode="after")
+    def validate_config_structure(self) -> "AirbyteAuthConfig":
+        """Validate that either single option or oneOf is provided, not both."""
+        has_single = self.type is not None or self.properties is not None or self.auth_mapping is not None
+        has_one_of = self.one_of is not None and len(self.one_of) > 0
+
+        if not has_single and not has_one_of:
+            raise ValueError("Either single auth option (type/properties/auth_mapping) or oneOf must be provided")
+
+        if has_single and has_one_of:
+            raise ValueError("Cannot have both single auth option and oneOf")
+
+        if has_single:
+            # Validate single option has required fields
+            if self.type != "object":
+                raise ValueError("Single auth option must have type='object'")
+            if not self.properties:
+                raise ValueError("Single auth option must have properties")
+            if not self.auth_mapping:
+                raise ValueError("Single auth option must have auth_mapping")
+
+        return self
+
+
+class SecurityScheme(BaseModel):
+    """
+    Security scheme definition.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#security-scheme-object
+
+    Supported Types:
+    - apiKey: API key in header/query/cookie
+    - http: HTTP authentication (basic, bearer, digest, etc.)
+    - oauth2: OAuth 2.0 flows
+
+    Extensions:
+    - x-airbyte-token-path: JSON path to extract token from auth response (Airbyte extension)
+    - x-airbyte-token-refresh: OAuth2 token refresh configuration (dict with auth_style, body_format)
+    - x-airbyte-auth-config: User-facing authentication configuration (Airbyte extension)
+
+    Future extensions (not yet active):
+    - x-grant-type: OAuth grant type for refresh tokens
+    - x-refresh-endpoint: Custom refresh endpoint URL
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    # Standard OpenAPI fields
+    type: Literal["apiKey", "http", "oauth2", "openIdConnect"]
+    description: str | None = None
+
+    # apiKey specific
+    name: str | None = None
+    in_: Literal["query", "header", "cookie"] | None = Field(None, alias="in")
+
+    # http specific
+    scheme: str | None = None  # e.g., "basic", "bearer", "digest"
+    bearer_format: str | None = Field(None, alias="bearerFormat")
+
+    # oauth2 specific
+    flows: OAuth2Flows | None = None
+
+    # openIdConnect specific
+    open_id_connect_url: str | None = Field(None, alias="openIdConnectUrl")
+
+    # Airbyte extensions
+    x_token_path: str | None = Field(None, alias="x-airbyte-token-path")
+    x_token_refresh: Dict[str, Any] | None = Field(None, alias="x-airbyte-token-refresh")
+    x_airbyte_auth_config: AirbyteAuthConfig | None = Field(None, alias="x-airbyte-auth-config")
+    x_airbyte_token_extract: List[str] | None = Field(
+        None,
+        alias="x-airbyte-token-extract",
+        description="List of fields to extract from OAuth2 token responses and use as server variables",
+    )
+
+    @field_validator("x_airbyte_token_extract", mode="after")
+    @classmethod
+    def validate_token_extract(cls, v: List[str] | None) -> List[str] | None:
+        """Validate x-airbyte-token-extract has no duplicates."""
+        if v is not None:
+            if len(v) != len(set(v)):
+                duplicates = [x for x in v if v.count(x) > 1]
+                raise ValueError(f"x-airbyte-token-extract contains duplicate fields: {set(duplicates)}")
+        return v
+
+    # Future extensions (commented out, defined for future use)
+    # x_grant_type: Optional[Literal["refresh_token", "client_credentials"]] = Field(None, alias="x-grant-type")
+    # x_refresh_endpoint: Optional[str] = Field(None, alias="x-refresh-endpoint")
+
+    @model_validator(mode="after")
+    def validate_security_scheme(self) -> "SecurityScheme":
+        """Validate that required fields are present based on security type."""
+        if self.type == "apiKey":
+            if not self.name or not self.in_:
+                raise ValueError("apiKey type requires 'name' and 'in' fields")
+        elif self.type == "http":
+            if not self.scheme:
+                raise ValueError("http type requires 'scheme' field")
+        elif self.type == "oauth2":
+            if not self.flows:
+                raise ValueError("oauth2 type requires 'flows' field")
+        elif self.type == "openIdConnect":
+            if not self.open_id_connect_url:
+                raise ValueError("openIdConnect type requires 'openIdConnectUrl' field")
+        return self
+
+
+# SecurityRequirement is a dict mapping security scheme name to list of scopes
+SecurityRequirement = Dict[str, List[str]]