airbyte-agent-jira 0.1.22__py3-none-any.whl

airbyte_agent_jira/_vendored/connector_sdk/schema/components.py

@@ -0,0 +1,239 @@
+"""
+Component models for OpenAPI 3.1: Schema, Parameter, RequestBody, Response, Components.
+
+References:
+- https://spec.openapis.org/oas/v3.1.0#components-object
+- https://spec.openapis.org/oas/v3.1.0#schema-object
+- https://spec.openapis.org/oas/v3.1.0#parameter-object
+"""
+
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .security import SecurityScheme
+
+
+class Schema(BaseModel):
+    """
+    JSON Schema definition for data models.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#schema-object
+
+    Note: Uses Dict[str, Any] for properties to support nested schemas and $ref.
+    Reference resolution happens at runtime in config_loader.py.
+
+    Extensions:
+    - x-airbyte-resource-name: Name of the resource this schema represents (Airbyte extension)
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    # Core JSON Schema fields
+    type: Optional[str] = None
+    format: Optional[str] = None
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[Any] = None
+    example: Optional[Any] = None
+
+    # Object properties
+    properties: Dict[str, Any] = Field(default_factory=dict)  # May contain $ref
+    required: List[str] = Field(default_factory=list)
+    additional_properties: Optional[Any] = Field(None, alias="additionalProperties")
+
+    # Array properties
+    items: Optional[Any] = None  # May be Schema or $ref
+
+    # Validation
+    enum: Optional[List[Any]] = None
+    min_length: Optional[int] = Field(None, alias="minLength")
+    max_length: Optional[int] = Field(None, alias="maxLength")
+    minimum: Optional[float] = None
+    maximum: Optional[float] = None
+    pattern: Optional[str] = None
+
+    # Composition
+    all_of: Optional[List[Any]] = Field(None, alias="allOf")
+    any_of: Optional[List[Any]] = Field(None, alias="anyOf")
+    one_of: Optional[List[Any]] = Field(None, alias="oneOf")
+    not_: Optional[Any] = Field(None, alias="not")
+
+    # Metadata
+    nullable: Optional[bool] = Field(None, deprecated="Use type union with null instead (OpenAPI 3.1)")
+    read_only: Optional[bool] = Field(None, alias="readOnly")
+    write_only: Optional[bool] = Field(None, alias="writeOnly")
+    deprecated: Optional[bool] = None
+
+    # 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):
+    """
+    Operation parameter definition.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#parameter-object
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    name: str
+    in_: Literal["query", "header", "path", "cookie"] = Field(alias="in")
+    description: Optional[str] = None
+    required: Optional[bool] = None
+    deprecated: Optional[bool] = None
+    allow_empty_value: Optional[bool] = Field(None, alias="allowEmptyValue")
+
+    # Schema can be inline or reference
+    schema_: Optional[Dict[str, Any]] = Field(None, alias="schema")
+
+    # Style and examples
+    style: Optional[str] = None
+    explode: Optional[bool] = None
+    example: Optional[Any] = None
+    examples: Optional[Dict[str, Any]] = None
+
+
+class MediaType(BaseModel):
+    """
+    Media type object for request/response content.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#media-type-object
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    schema_: Optional[Dict[str, Any]] = Field(None, alias="schema")
+    example: Optional[Any] = None
+    examples: Optional[Dict[str, Any]] = None
+    encoding: Optional[Dict[str, Any]] = None
+
+
+class GraphQLBodyConfig(BaseModel):
+    """
+    GraphQL body type configuration for x-airbyte-body-type extension.
+
+    Used when x-airbyte-body-type.type = "graphql"
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    type: Literal["graphql"] = Field(..., description="Body type identifier (must be 'graphql')")
+    query: str = Field(
+        ...,
+        description="GraphQL query or mutation string with optional template placeholders (e.g., {{ variable }})",
+    )
+    variables: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Variables to substitute in the GraphQL query using template syntax (e.g., {{ param_name }})",
+    )
+    operationName: Optional[str] = Field(None, description="Operation name for queries with multiple operations")
+    default_fields: Optional[Union[str, List[str]]] = Field(
+        None,
+        description="Default fields to select if not provided in request parameters. Can be a string or array of field names.",
+    )
+
+
+# Union type for all body type configs (extensible for future types like XML, SOAP, etc.)
+BodyTypeConfig = Union[GraphQLBodyConfig]
+
+
+class PathOverrideConfig(BaseModel):
+    """
+    Path override configuration for x-airbyte-path-override extension.
+
+    Used when the OpenAPI path differs from the actual HTTP endpoint path.
+    Common for GraphQL APIs where multiple resources share the same endpoint (e.g., /graphql).
+
+    Example:
+        OpenAPI path: /graphql:repositories (for uniqueness)
+        Actual HTTP path: /graphql (configured here)
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    path: str = Field(
+        ...,
+        description=("Actual HTTP path to use for requests (e.g., '/graphql'). " "Must start with '/'"),
+    )
+
+
+class RequestBody(BaseModel):
+    """
+    Request body definition.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#request-body-object
+
+    Airbyte Extensions:
+    See connector_sdk.extensions for documentation:
+    - AIRBYTE_BODY_TYPE: Body type and configuration (nested structure)
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    description: Optional[str] = None
+    content: Dict[str, MediaType] = Field(default_factory=dict)
+    required: Optional[bool] = None
+
+    # Airbyte extensions for GraphQL support
+    # See connector_sdk.extensions for AIRBYTE_BODY_TYPE constant
+    x_airbyte_body_type: Optional[BodyTypeConfig] = Field(
+        None,
+        alias="x-airbyte-body-type",  # AIRBYTE_BODY_TYPE
+        description=(
+            "Body type and configuration. Contains 'type' field (e.g., 'graphql') " "and type-specific configuration (query, variables, etc.)."
+        ),
+    )
+
+
+class Header(BaseModel):
+    """
+    Header definition.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#header-object
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    description: Optional[str] = None
+    required: Optional[bool] = None
+    deprecated: Optional[bool] = None
+    schema_: Optional[Dict[str, Any]] = Field(None, alias="schema")
+    example: Optional[Any] = None
+
+
+class Response(BaseModel):
+    """
+    Response definition.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#response-object
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    description: str
+    headers: Optional[Dict[str, Header]] = None
+    content: Optional[Dict[str, MediaType]] = None
+    links: Optional[Dict[str, Any]] = None
+
+
+class Components(BaseModel):
+    """
+    Reusable component definitions.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#components-object
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    schemas: Dict[str, Schema] = Field(default_factory=dict)
+    responses: Dict[str, Response] = Field(default_factory=dict)
+    parameters: Dict[str, Parameter] = Field(default_factory=dict)
+    examples: Optional[Dict[str, Any]] = None
+    request_bodies: Dict[str, RequestBody] = Field(default_factory=dict, alias="requestBodies")
+    headers: Optional[Dict[str, Header]] = None
+    security_schemes: Dict[str, SecurityScheme] = Field(default_factory=dict, alias="securitySchemes")
+    links: Optional[Dict[str, Any]] = None
+    callbacks: Optional[Dict[str, Any]] = None

airbyte_agent_jira/_vendored/connector_sdk/schema/connector.py

@@ -0,0 +1,131 @@
+"""
+Root OpenAPI 3.1 connector specification model.
+
+References:
+- https://spec.openapis.org/oas/v3.1.0#openapi-object
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from ..constants import OPENAPI_VERSION_PREFIX
+
+from .base import Info, Server
+from .components import Components
+from .operations import PathItem
+from .security import SecurityRequirement
+
+
+class Tag(BaseModel):
+    """
+    Tag metadata for grouping operations.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#tag-object
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    name: str
+    description: str | None = None
+    external_docs: dict[str, Any] | None = Field(None, alias="externalDocs")
+
+
+class ExternalDocs(BaseModel):
+    """
+    External documentation reference.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#external-documentation-object
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    description: str | None = None
+    url: str
+
+
+class OpenAPIConnector(BaseModel):
+    """
+    Root OpenAPI 3.1 connector specification.
+
+    OpenAPI Reference: https://spec.openapis.org/oas/v3.1.0#openapi-object
+
+    This is the top-level model that represents a complete OpenAPI 3.1 specification
+    for an Airbyte connector. It enforces strict validation (extra='forbid') to catch
+    typos and unknown extensions.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid", validate_default=True)
+
+    # Required fields
+    openapi: str
+    info: Info
+    paths: dict[str, PathItem] = Field(default_factory=dict)
+
+    # Optional fields
+    servers: list[Server] = Field(default_factory=list)
+    components: Components | None = None
+    security: list[SecurityRequirement] | None = None
+    tags: list[Tag] | None = None
+    external_docs: ExternalDocs | None = Field(None, alias="externalDocs")
+
+    @field_validator("openapi")
+    @classmethod
+    def validate_openapi_version(cls, v: str) -> str:
+        """Validate that OpenAPI version is 3.1.x."""
+        if not v.startswith(OPENAPI_VERSION_PREFIX):
+            raise ValueError(f"OpenAPI version must be {OPENAPI_VERSION_PREFIX}x, got: {v}")
+        return v
+
+    def get_entity_operations(self, entity_name: str) -> list[tuple[str, str, Any]]:
+        """
+        Get all operations for a specific entity.
+
+        Args:
+            entity_name: The x-airbyte-entity value to filter by
+
+        Returns:
+            List of tuples: (path, method, operation)
+        """
+        results = []
+        for path, path_item in self.paths.items():
+            for method in [
+                "get",
+                "post",
+                "put",
+                "patch",
+                "delete",
+                "options",
+                "head",
+                "trace",
+            ]:
+                operation = getattr(path_item, method, None)
+                if operation and operation.x_airbyte_entity == entity_name:
+                    results.append((path, method, operation))
+        return results
+
+    def list_entities(self) -> list[str]:
+        """
+        List all unique entity names defined in x-airbyte-entity extensions.
+
+        Returns:
+            Sorted list of unique entity names
+        """
+        entities = set()
+        for path_item in self.paths.values():
+            for method in [
+                "get",
+                "post",
+                "put",
+                "patch",
+                "delete",
+                "options",
+                "head",
+                "trace",
+            ]:
+                operation = getattr(path_item, method, None)
+                if operation and operation.x_airbyte_entity:
+                    entities.add(operation.x_airbyte_entity)
+        return sorted(entities)

airbyte_agent_jira/_vendored/connector_sdk/schema/extensions.py

@@ -0,0 +1,109 @@
+"""
+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, Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+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: Optional[str] = None
+    cursor_source: Optional[Literal["body", "headers"]] = "body"
+    cursor_path: Optional[str] = None
+
+    # Offset-based pagination
+    offset_param: Optional[str] = None
+
+    # Page-based pagination
+    page_param: Optional[str] = None
+
+    # Response parsing
+    data_path: str = "data"
+    has_more_path: Optional[str] = None
+
+    # Limits
+    max_page_size: Optional[int] = 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: Optional[str] = "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"

airbyte_agent_jira/_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, Optional
+
+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: Optional[List[str]] = None
+    summary: Optional[str] = None
+    description: Optional[str] = None
+    external_docs: Optional[Dict[str, Any]] = Field(None, alias="externalDocs")
+    operation_id: Optional[str] = Field(None, alias="operationId")
+    parameters: Optional[List[Parameter]] = None
+    request_body: Optional[RequestBody] = Field(None, alias="requestBody")
+    responses: Dict[str, Response] = Field(default_factory=dict)
+    callbacks: Optional[Dict[str, Any]] = None
+    deprecated: Optional[bool] = None
+    security: Optional[List[SecurityRequirement]] = None
+    servers: Optional[List[Any]] = 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: Optional[PathOverrideConfig] = Field(
+        None,
+        alias="x-airbyte-path-override",
+        description=("Override path for HTTP requests when OpenAPI path " "differs from actual endpoint"),
+    )
+    x_airbyte_record_extractor: Optional[str] = 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/search actions, single record for "
+            "get/create/update/delete actions."
+        ),
+    )
+    x_airbyte_meta_extractor: Optional[Dict[str, str]] = 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: Optional[str] = Field(None, alias="x-airbyte-file-url")
+    x_airbyte_untested: Optional[bool] = 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: Optional[str] = None
+    description: Optional[str] = None
+    servers: Optional[List[Any]] = None
+    parameters: Optional[List[Parameter]] = None
+
+    # HTTP methods (all optional)
+    get: Optional[Operation] = None
+    put: Optional[Operation] = None
+    post: Optional[Operation] = None
+    delete: Optional[Operation] = None
+    options: Optional[Operation] = None
+    head: Optional[Operation] = None
+    patch: Optional[Operation] = None
+    trace: Optional[Operation] = None
+
+    # Reference support
+    ref: Optional[str] = Field(None, alias="$ref")