# This file is auto-generated by oagen. Do not edit.

from __future__ import annotations

from typing import TYPE_CHECKING, Any, Dict, Literal, Optional, Union

if TYPE_CHECKING:
    from .._client import AsyncWorkOSClient, WorkOSClient

from .._types import RequestOptions, enum_value
from .models import (
    AgentAdminLinkClaimAttemptToExternalUserRequestUser,
    AgentCredentialValidation,
    AgentRegistration,
    ClaimViewResponse,
)
from workos.common.models.agent_admin_validate_credential_request_type import (
    AgentAdminValidateCredentialRequestType,
)


class Agents:
    """Agents API resources."""

    def __init__(self, client: "WorkOSClient") -> None:
        self._client = client

    def update_attempts(
        self,
        *,
        type: Literal["link_external_user"],
        claim_attempt_token: str,
        user: AgentAdminLinkClaimAttemptToExternalUserRequestUser,
        organization_id: Optional[str] = None,
        request_options: Optional[RequestOptions] = None,
    ) -> ClaimViewResponse:
        """Link a claim attempt to an external user

        Link an external user to a claim attempt and retrieve the code needed for the agent to complete the claim. The user is looked up by external ID; if no user exists, one is created. When the user belongs to multiple organizations, an explicit organization must be provided.

        Args:
            type: The operation to perform on the claim attempt. Currently only `link_external_user` is supported.
            claim_attempt_token: The token identifying the claim attempt.
            user: The user to attach to the claim attempt, identified by email and external ID.
            organization_id: The organization to place the agent in. Required when the user belongs to more than one organization.
            request_options: Per-request options. Supports extra_headers, timeout, max_retries, and base_url override.

        Returns:
            ClaimViewResponse

        Raises:
            BadRequestError: If the request is malformed (400).
            AuthorizationError: If the request is forbidden (403).
            ConflictError: If a conflict occurs (409).
            AuthenticationError: If the API key is invalid (401).
            RateLimitExceededError: If rate limited (429).
            ServerError: If the server returns a 5xx error.
        """
        body: Dict[str, Any] = {
            k: v
            for k, v in {
                "type": type,
                "claim_attempt_token": claim_attempt_token,
                "user": user.to_dict(),
                "organization_id": organization_id,
            }.items()
            if v is not None
        }
        return self._client.request(
            method="patch",
            path=("agents", "claims", "attempts"),
            body=body,
            model=ClaimViewResponse,
            request_options=request_options,
        )

    def create_validate(
        self,
        *,
        type: Union[AgentAdminValidateCredentialRequestType, str],
        credential: str,
        audience: Optional[str] = None,
        request_options: Optional[RequestOptions] = None,
    ) -> AgentCredentialValidation:
        """Validate an agent credential

        Validate an agent credential — an API key or access token — against the environment of the API key used to authenticate the request. This is a read-only check: it never consumes or mutates the credential.

        Args:
            type: The kind of credential being validated — an agent API key or an agent access token.
            credential: The credential value to validate: the API key value for `api_key`, or the access token (JWT) for `access_token`.
            audience: When provided, the access token's `aud` claim is verified against this value. Tokens issued for a different resource are rejected.
            request_options: Per-request options. Supports extra_headers, timeout, max_retries, and base_url override.

        Returns:
            AgentCredentialValidation

        Raises:
            BadRequestError: If the request is malformed (400).
            AuthenticationError: If the API key is invalid (401).
            RateLimitExceededError: If rate limited (429).
            ServerError: If the server returns a 5xx error.
        """
        body: Dict[str, Any] = {
            k: v
            for k, v in {
                "type": enum_value(type),
                "credential": credential,
                "audience": audience,
            }.items()
            if v is not None
        }
        return self._client.request(
            method="post",
            path=("agents", "credentials", "validate"),
            body=body,
            model=AgentCredentialValidation,
            request_options=request_options,
        )

    def get_registration(
        self,
        id: str,
        *,
        request_options: Optional[RequestOptions] = None,
    ) -> AgentRegistration:
        """Get an agent registration

        Retrieve the details of an agent registration by ID. The registration is scoped to the environment of the API key used to authenticate the request.

        Args:
            id: The unique ID of the agent registration.
            request_options: Per-request options. Supports extra_headers, timeout, max_retries, and base_url override.

        Returns:
            AgentRegistration

        Raises:
            NotFoundError: If the resource is not found (404).
            AuthenticationError: If the API key is invalid (401).
            RateLimitExceededError: If rate limited (429).
            ServerError: If the server returns a 5xx error.
        """
        return self._client.request(
            method="get",
            path=("agents", "registrations", str(id)),
            model=AgentRegistration,
            request_options=request_options,
        )


class AsyncAgents:
    """Agents API resources (async)."""

    def __init__(self, client: "AsyncWorkOSClient") -> None:
        self._client = client

    async def update_attempts(
        self,
        *,
        type: Literal["link_external_user"],
        claim_attempt_token: str,
        user: AgentAdminLinkClaimAttemptToExternalUserRequestUser,
        organization_id: Optional[str] = None,
        request_options: Optional[RequestOptions] = None,
    ) -> ClaimViewResponse:
        """Link a claim attempt to an external user

        Link an external user to a claim attempt and retrieve the code needed for the agent to complete the claim. The user is looked up by external ID; if no user exists, one is created. When the user belongs to multiple organizations, an explicit organization must be provided.

        Args:
            type: The operation to perform on the claim attempt. Currently only `link_external_user` is supported.
            claim_attempt_token: The token identifying the claim attempt.
            user: The user to attach to the claim attempt, identified by email and external ID.
            organization_id: The organization to place the agent in. Required when the user belongs to more than one organization.
            request_options: Per-request options. Supports extra_headers, timeout, max_retries, and base_url override.

        Returns:
            ClaimViewResponse

        Raises:
            BadRequestError: If the request is malformed (400).
            AuthorizationError: If the request is forbidden (403).
            ConflictError: If a conflict occurs (409).
            AuthenticationError: If the API key is invalid (401).
            RateLimitExceededError: If rate limited (429).
            ServerError: If the server returns a 5xx error.
        """
        body: Dict[str, Any] = {
            k: v
            for k, v in {
                "type": type,
                "claim_attempt_token": claim_attempt_token,
                "user": user.to_dict(),
                "organization_id": organization_id,
            }.items()
            if v is not None
        }
        return await self._client.request(
            method="patch",
            path=("agents", "claims", "attempts"),
            body=body,
            model=ClaimViewResponse,
            request_options=request_options,
        )

    async def create_validate(
        self,
        *,
        type: Union[AgentAdminValidateCredentialRequestType, str],
        credential: str,
        audience: Optional[str] = None,
        request_options: Optional[RequestOptions] = None,
    ) -> AgentCredentialValidation:
        """Validate an agent credential

        Validate an agent credential — an API key or access token — against the environment of the API key used to authenticate the request. This is a read-only check: it never consumes or mutates the credential.

        Args:
            type: The kind of credential being validated — an agent API key or an agent access token.
            credential: The credential value to validate: the API key value for `api_key`, or the access token (JWT) for `access_token`.
            audience: When provided, the access token's `aud` claim is verified against this value. Tokens issued for a different resource are rejected.
            request_options: Per-request options. Supports extra_headers, timeout, max_retries, and base_url override.

        Returns:
            AgentCredentialValidation

        Raises:
            BadRequestError: If the request is malformed (400).
            AuthenticationError: If the API key is invalid (401).
            RateLimitExceededError: If rate limited (429).
            ServerError: If the server returns a 5xx error.
        """
        body: Dict[str, Any] = {
            k: v
            for k, v in {
                "type": enum_value(type),
                "credential": credential,
                "audience": audience,
            }.items()
            if v is not None
        }
        return await self._client.request(
            method="post",
            path=("agents", "credentials", "validate"),
            body=body,
            model=AgentCredentialValidation,
            request_options=request_options,
        )

    async def get_registration(
        self,
        id: str,
        *,
        request_options: Optional[RequestOptions] = None,
    ) -> AgentRegistration:
        """Get an agent registration

        Retrieve the details of an agent registration by ID. The registration is scoped to the environment of the API key used to authenticate the request.

        Args:
            id: The unique ID of the agent registration.
            request_options: Per-request options. Supports extra_headers, timeout, max_retries, and base_url override.

        Returns:
            AgentRegistration

        Raises:
            NotFoundError: If the resource is not found (404).
            AuthenticationError: If the API key is invalid (401).
            RateLimitExceededError: If rate limited (429).
            ServerError: If the server returns a 5xx error.
        """
        return await self._client.request(
            method="get",
            path=("agents", "registrations", str(id)),
            model=AgentRegistration,
            request_options=request_options,
        )
