"""Async start bulk import method for AsyncBulkImports."""

from __future__ import annotations

from typing import Any, Literal

import msgspec

from pinecone._internal.validation import require_non_empty
from pinecone.models.bulk_imports.start import StartImportResponse


_DECODER = msgspec.json.Decoder(StartImportResponse)


async def start(
    self: Any,
    *,
    uri: str,
    integration_id: str | None = None,
    error_mode: Literal["abort", "continue"] | None = None,
) -> StartImportResponse:
    """Start a bulk import operation.

    Args:
        uri (str): Source URI (S3, GCS, or Azure) containing the data to import.
        integration_id (str | None): Storage integration ID for authentication.
        error_mode (Literal["abort", "continue"] | None): How to handle errors
            during import. Either ``"abort"`` to stop on first error, or
            ``"continue"`` to skip bad records.

    Returns:
        StartImportResponse with the import operation ID.

    Raises:
        ValueError: If required parameters are empty.
        PineconeApiException: If the API request fails.

    Examples:
        >>> response = await index.bulk_imports.start(uri="s3://my-bucket/my-data/")
        >>> print(f"Import started: {response.id}")
    """
    require_non_empty("uri", uri)

    body: dict[str, Any] = {"uri": uri}
    if integration_id is not None:
        body["integrationId"] = integration_id
    if error_mode is not None:
        body["errorMode"] = {"onError": error_mode}

    data = await self._make_data_plane_request("POST", "/bulk/imports", body=body)
    return _DECODER.decode(data)
