dfns-sdk 0.0.0.dev0__py3-none-any.whl

dfns_sdk/generated/webhooks/client.py

@@ -0,0 +1,193 @@
+"""Client for the webhooks domain."""
+
+from typing import Any, Literal, Optional, TypedDict, Union
+
+from ..._internal import HttpClient
+from . import types as T
+
+
+class WebhooksClient:
+    """Client for webhooks operations."""
+
+    def __init__(self, http_client: HttpClient):
+        self._http = http_client
+
+    def list_webhooks(self, query: Optional[T.ListWebhooksQuery] = None) -> T.ListWebhooksResponse:
+        """
+        List Webhooks.
+
+        List all webhooks for the authenticated user's organization. The results are paginated.
+
+        Args:
+        query: Query parameters.
+
+        Returns:
+            T.ListWebhooksResponse: The API response.
+        """
+        return self._http.request(
+            method="GET",
+            path="/webhooks",
+            path_params={},
+            query_params=query,
+            body=None,
+            requires_signature=False,
+        )
+
+    def create_webhook(self, body: T.CreateWebhookRequest) -> T.CreateWebhookResponse:
+        """
+        Create Webhook.
+
+        Register a new webhook.
+
+        Args:
+        body: Request body.
+
+        Returns:
+            T.CreateWebhookResponse: The API response.
+        """
+        return self._http.request(
+            method="POST",
+            path="/webhooks",
+            path_params={},
+            query_params=None,
+            body=body,
+            requires_signature=True,
+        )
+
+    def get_webhook(self, webhook_id: str) -> T.GetWebhookResponse:
+        """
+        Get Webhook.
+
+        Retrieve information about a specific webhook.
+
+        Args:
+        webhook_id: Path parameter.
+
+        Returns:
+            T.GetWebhookResponse: The API response.
+        """
+        return self._http.request(
+            method="GET",
+            path="/webhooks/{webhookId}",
+            path_params={"webhookId": webhook_id},
+            query_params=None,
+            body=None,
+            requires_signature=False,
+        )
+
+    def update_webhook(self, webhook_id: str, body: T.UpdateWebhookRequest) -> T.UpdateWebhookResponse:
+        """
+        Update Webhook.
+
+        Update the definition of an existing webhook.
+
+        Args:
+        webhook_id: Path parameter.
+        body: Request body.
+
+        Returns:
+            T.UpdateWebhookResponse: The API response.
+        """
+        return self._http.request(
+            method="PUT",
+            path="/webhooks/{webhookId}",
+            path_params={"webhookId": webhook_id},
+            query_params=None,
+            body=body,
+            requires_signature=True,
+        )
+
+    def delete_webhook(self, webhook_id: str) -> T.DeleteWebhookResponse:
+        """
+        Delete Webhook.
+
+        Deletes an existing webhook registration.
+
+        Args:
+        webhook_id: Path parameter.
+
+        Returns:
+            T.DeleteWebhookResponse: The API response.
+        """
+        return self._http.request(
+            method="DELETE",
+            path="/webhooks/{webhookId}",
+            path_params={"webhookId": webhook_id},
+            query_params=None,
+            body=None,
+            requires_signature=True,
+        )
+
+    def ping_webhook(self, webhook_id: str) -> T.PingWebhookResponse:
+        """
+        Ping Webhook.
+
+        This endpoint is meant for webhook setup and troubleshooting. Calling the endpoint will trigger a fake test event that will be pushed to the webhook url. The fake event will not be saved and not appear in further requests to Webhook Events.
+
+        Args:
+        webhook_id: Path parameter.
+
+        Returns:
+            T.PingWebhookResponse: The API response.
+        """
+        return self._http.request(
+            method="POST",
+            path="/webhooks/{webhookId}/ping",
+            path_params={"webhookId": webhook_id},
+            query_params=None,
+            body=None,
+            requires_signature=True,
+        )
+
+    def get_webhook_event(self, webhook_id: str, webhook_event_id: str) -> T.GetWebhookEventResponse:
+        """
+        Get Webhook Event.
+
+        Retrieve a specific webhook event details by its ID.
+  
+<Warning>
+We only keep a trace of those Webhook Events in our system for a **retention period of 31 days**. Past that, they are discarded, so you cannot see them using [List Webhook Events](https://docs.dfns.co/api-reference/webhooks/list-webhook-events) or [Get Webhook Event](https://docs.dfns.co/api-reference/webhooks/get-webhook-event) endpoints.
+</Warning>
+
+        Args:
+        webhook_id: Path parameter.
+        webhook_event_id: Path parameter.
+
+        Returns:
+            T.GetWebhookEventResponse: The API response.
+        """
+        return self._http.request(
+            method="GET",
+            path="/webhooks/{webhookId}/events/{webhookEventId}",
+            path_params={"webhookId": webhook_id, "webhookEventId": webhook_event_id},
+            query_params=None,
+            body=None,
+            requires_signature=False,
+        )
+
+    def list_webhook_events(self, webhook_id: str, query: Optional[T.ListWebhookEventsQuery] = None) -> T.ListWebhookEventsResponse:
+        """
+        List Webhook Events.
+
+        Lists all events for a given webhook. 
+
+
+<Warning>
+We only keep a trace of those Webhook Events in our system for a **retention period of 31 days**. Past that, they are discarded, so you cannot see them using [List Webhook Events](https://docs.dfns.co/api-reference/webhooks/list-webhook-events) or [Get Webhook Event](https://docs.dfns.co/api-reference/webhooks/get-webhook-event) endpoints.
+</Warning>
+
+        Args:
+        webhook_id: Path parameter.
+        query: Query parameters.
+
+        Returns:
+            T.ListWebhookEventsResponse: The API response.
+        """
+        return self._http.request(
+            method="GET",
+            path="/webhooks/{webhookId}/events",
+            path_params={"webhookId": webhook_id},
+            query_params=query,
+            body=None,
+            requires_signature=False,
+        )

dfns_sdk/generated/webhooks/delegated_client.py

@@ -0,0 +1,320 @@
+"""Delegated client for the webhooks domain."""
+
+import json
+from typing import Any, Literal, Optional, TypedDict, Union
+
+from ..._internal import HttpClient
+from ...base_auth_api import (
+    BaseAuthApi,
+    SignUserActionChallengeRequest,
+    UserActionChallengeResponse,
+)
+from . import types as T
+
+
+class DelegatedWebhooksClient:
+    """
+    Delegated client for webhooks operations.
+
+    This client separates user action signing into _init() and _complete() method pairs,
+    allowing external systems to handle the signing process.
+    """
+
+    def __init__(self, http_client: HttpClient):
+        self._http = http_client
+
+    def list_webhooks(self, query: Optional[T.ListWebhooksQuery] = None) -> T.ListWebhooksResponse:
+        """
+        List Webhooks.
+
+        List all webhooks for the authenticated user's organization. The results are paginated.
+
+        Args:
+        query: Query parameters.
+
+        Returns:
+            T.ListWebhooksResponse: The API response.
+        """
+        return self._http.request(
+            method="GET",
+            path="/webhooks",
+            path_params={},
+            query_params=query,
+            body=None,
+            requires_signature=False,
+        )
+
+    def create_webhook_init(self, body: T.CreateWebhookRequest) -> UserActionChallengeResponse:
+        """
+        Initialize Create Webhook.
+
+        Creates a user action challenge for external signing.
+
+        Args:
+        body: Request body.
+
+        Returns:
+            UserActionChallengeResponse: The challenge to sign externally.
+        """
+        path = "/webhooks"
+        payload = json.dumps(body, separators=(",", ":")) if body else ""
+
+        return BaseAuthApi.create_user_action_challenge(
+            self._http,
+            user_action_http_method="POST",
+            user_action_http_path=path,
+            user_action_payload=payload,
+        )
+
+    def create_webhook_complete(self, body: T.CreateWebhookRequest, signed_challenge: SignUserActionChallengeRequest) -> T.CreateWebhookResponse:
+        """
+        Complete Create Webhook.
+
+        Submits the signed challenge and makes the API request.
+
+        Args:
+        body: Request body.
+        signed_challenge: The signed challenge from external signing.
+
+        Returns:
+            T.CreateWebhookResponse: The API response.
+        """
+        user_action_result = BaseAuthApi.sign_user_action_challenge(
+            self._http, signed_challenge
+        )
+        user_action_token = user_action_result["userAction"]
+
+        return self._http.request_with_user_action(
+            method="POST",
+            path="/webhooks",
+            path_params={},
+            query_params=None,
+            body=body,
+            user_action=user_action_token,
+        )
+
+    def get_webhook(self, webhook_id: str) -> T.GetWebhookResponse:
+        """
+        Get Webhook.
+
+        Retrieve information about a specific webhook.
+
+        Args:
+        webhook_id: Path parameter.
+
+        Returns:
+            T.GetWebhookResponse: The API response.
+        """
+        return self._http.request(
+            method="GET",
+            path="/webhooks/{webhookId}",
+            path_params={"webhookId": webhook_id},
+            query_params=None,
+            body=None,
+            requires_signature=False,
+        )
+
+    def update_webhook_init(self, webhook_id: str, body: T.UpdateWebhookRequest) -> UserActionChallengeResponse:
+        """
+        Initialize Update Webhook.
+
+        Creates a user action challenge for external signing.
+
+        Args:
+        webhook_id: Path parameter.
+        body: Request body.
+
+        Returns:
+            UserActionChallengeResponse: The challenge to sign externally.
+        """
+        path = "/webhooks/{webhookId}"
+        path = path.replace("{webhookId}", str(webhook_id))
+        payload = json.dumps(body, separators=(",", ":")) if body else ""
+
+        return BaseAuthApi.create_user_action_challenge(
+            self._http,
+            user_action_http_method="PUT",
+            user_action_http_path=path,
+            user_action_payload=payload,
+        )
+
+    def update_webhook_complete(self, webhook_id: str, body: T.UpdateWebhookRequest, signed_challenge: SignUserActionChallengeRequest) -> T.UpdateWebhookResponse:
+        """
+        Complete Update Webhook.
+
+        Submits the signed challenge and makes the API request.
+
+        Args:
+        webhook_id: Path parameter.
+        body: Request body.
+        signed_challenge: The signed challenge from external signing.
+
+        Returns:
+            T.UpdateWebhookResponse: The API response.
+        """
+        user_action_result = BaseAuthApi.sign_user_action_challenge(
+            self._http, signed_challenge
+        )
+        user_action_token = user_action_result["userAction"]
+
+        return self._http.request_with_user_action(
+            method="PUT",
+            path="/webhooks/{webhookId}",
+            path_params={"webhookId": webhook_id},
+            query_params=None,
+            body=body,
+            user_action=user_action_token,
+        )
+
+    def delete_webhook_init(self, webhook_id: str) -> UserActionChallengeResponse:
+        """
+        Initialize Delete Webhook.
+
+        Creates a user action challenge for external signing.
+
+        Args:
+        webhook_id: Path parameter.
+
+        Returns:
+            UserActionChallengeResponse: The challenge to sign externally.
+        """
+        path = "/webhooks/{webhookId}"
+        path = path.replace("{webhookId}", str(webhook_id))
+        payload = ""
+
+        return BaseAuthApi.create_user_action_challenge(
+            self._http,
+            user_action_http_method="DELETE",
+            user_action_http_path=path,
+            user_action_payload=payload,
+        )
+
+    def delete_webhook_complete(self, webhook_id: str, signed_challenge: SignUserActionChallengeRequest) -> T.DeleteWebhookResponse:
+        """
+        Complete Delete Webhook.
+
+        Submits the signed challenge and makes the API request.
+
+        Args:
+        webhook_id: Path parameter.
+        signed_challenge: The signed challenge from external signing.
+
+        Returns:
+            T.DeleteWebhookResponse: The API response.
+        """
+        user_action_result = BaseAuthApi.sign_user_action_challenge(
+            self._http, signed_challenge
+        )
+        user_action_token = user_action_result["userAction"]
+
+        return self._http.request_with_user_action(
+            method="DELETE",
+            path="/webhooks/{webhookId}",
+            path_params={"webhookId": webhook_id},
+            query_params=None,
+            body=None,
+            user_action=user_action_token,
+        )
+
+    def ping_webhook_init(self, webhook_id: str) -> UserActionChallengeResponse:
+        """
+        Initialize Ping Webhook.
+
+        Creates a user action challenge for external signing.
+
+        Args:
+        webhook_id: Path parameter.
+
+        Returns:
+            UserActionChallengeResponse: The challenge to sign externally.
+        """
+        path = "/webhooks/{webhookId}/ping"
+        path = path.replace("{webhookId}", str(webhook_id))
+        payload = ""
+
+        return BaseAuthApi.create_user_action_challenge(
+            self._http,
+            user_action_http_method="POST",
+            user_action_http_path=path,
+            user_action_payload=payload,
+        )
+
+    def ping_webhook_complete(self, webhook_id: str, signed_challenge: SignUserActionChallengeRequest) -> T.PingWebhookResponse:
+        """
+        Complete Ping Webhook.
+
+        Submits the signed challenge and makes the API request.
+
+        Args:
+        webhook_id: Path parameter.
+        signed_challenge: The signed challenge from external signing.
+
+        Returns:
+            T.PingWebhookResponse: The API response.
+        """
+        user_action_result = BaseAuthApi.sign_user_action_challenge(
+            self._http, signed_challenge
+        )
+        user_action_token = user_action_result["userAction"]
+
+        return self._http.request_with_user_action(
+            method="POST",
+            path="/webhooks/{webhookId}/ping",
+            path_params={"webhookId": webhook_id},
+            query_params=None,
+            body=None,
+            user_action=user_action_token,
+        )
+
+    def get_webhook_event(self, webhook_id: str, webhook_event_id: str) -> T.GetWebhookEventResponse:
+        """
+        Get Webhook Event.
+
+        Retrieve a specific webhook event details by its ID.
+  
+<Warning>
+We only keep a trace of those Webhook Events in our system for a **retention period of 31 days**. Past that, they are discarded, so you cannot see them using [List Webhook Events](https://docs.dfns.co/api-reference/webhooks/list-webhook-events) or [Get Webhook Event](https://docs.dfns.co/api-reference/webhooks/get-webhook-event) endpoints.
+</Warning>
+
+        Args:
+        webhook_id: Path parameter.
+        webhook_event_id: Path parameter.
+
+        Returns:
+            T.GetWebhookEventResponse: The API response.
+        """
+        return self._http.request(
+            method="GET",
+            path="/webhooks/{webhookId}/events/{webhookEventId}",
+            path_params={"webhookId": webhook_id, "webhookEventId": webhook_event_id},
+            query_params=None,
+            body=None,
+            requires_signature=False,
+        )
+
+    def list_webhook_events(self, webhook_id: str, query: Optional[T.ListWebhookEventsQuery] = None) -> T.ListWebhookEventsResponse:
+        """
+        List Webhook Events.
+
+        Lists all events for a given webhook. 
+
+
+<Warning>
+We only keep a trace of those Webhook Events in our system for a **retention period of 31 days**. Past that, they are discarded, so you cannot see them using [List Webhook Events](https://docs.dfns.co/api-reference/webhooks/list-webhook-events) or [Get Webhook Event](https://docs.dfns.co/api-reference/webhooks/get-webhook-event) endpoints.
+</Warning>
+
+        Args:
+        webhook_id: Path parameter.
+        query: Query parameters.
+
+        Returns:
+            T.ListWebhookEventsResponse: The API response.
+        """
+        return self._http.request(
+            method="GET",
+            path="/webhooks/{webhookId}/events",
+            path_params={"webhookId": webhook_id},
+            query_params=query,
+            body=None,
+            requires_signature=False,
+        )

dfns_sdk/generated/webhooks/types.py

@@ -0,0 +1,101 @@
+"""Types for the webhooks domain."""
+
+from typing import Any, Literal, NotRequired, Optional, TypedDict, Union
+
+class ListWebhooksResponse(TypedDict, total=False):
+    """listWebhooks response."""
+
+    items: list[TypedDict]
+    next_page_token: NotRequired[str]
+
+class ListWebhooksQuery(TypedDict, total=False):
+    """listWebhooks query parameters."""
+
+    limit: NotRequired[int]
+    pagination_token: NotRequired[str]
+
+class CreateWebhookRequest(TypedDict, total=False):
+    """createWebhook request body."""
+
+    url: str
+    status: NotRequired[Literal["Enabled", "Disabled"]]
+    description: NotRequired[str]
+    events: list[Union[Literal["policy.triggered", "policy.approval.pending", "policy.approval.resolved", "key.created", "key.deleted", "key.delegated", "key.exported", "wallet.blockchainevent.detected", "wallet.created", "wallet.activated", "wallet.delegated", "wallet.exported", "wallet.signature.failed", "wallet.signature.rejected", "wallet.signature.requested", "wallet.signature.signed", "wallet.transaction.broadcasted", "wallet.transaction.confirmed", "wallet.transaction.failed", "wallet.transaction.rejected", "wallet.transaction.requested", "wallet.transfer.broadcasted", "wallet.transfer.confirmed", "wallet.transfer.failed", "wallet.transfer.rejected", "wallet.transfer.requested", "wallet.offer.received", "wallet.offer.accepted", "wallet.offer.rejected", "wallet.tags.modified"], Literal["*"]]]
+
+class CreateWebhookResponse(TypedDict, total=False):
+    """createWebhook response."""
+
+    id: str
+    url: str
+    events: list[Union[Literal["policy.triggered", "policy.approval.pending", "policy.approval.resolved", "key.created", "key.deleted", "key.delegated", "key.exported", "wallet.blockchainevent.detected", "wallet.created", "wallet.activated", "wallet.delegated", "wallet.exported", "wallet.signature.failed", "wallet.signature.rejected", "wallet.signature.requested", "wallet.signature.signed", "wallet.transaction.broadcasted", "wallet.transaction.confirmed", "wallet.transaction.failed", "wallet.transaction.rejected", "wallet.transaction.requested", "wallet.transfer.broadcasted", "wallet.transfer.confirmed", "wallet.transfer.failed", "wallet.transfer.rejected", "wallet.transfer.requested", "wallet.offer.received", "wallet.offer.accepted", "wallet.offer.rejected", "wallet.tags.modified"], Literal["*"]]]
+    status: Literal["Enabled", "Disabled"]
+    description: NotRequired[str]
+    date_created: str
+    date_updated: str
+    secret: str
+
+class GetWebhookResponse(TypedDict, total=False):
+    """getWebhook response."""
+
+    id: str
+    url: str
+    events: list[Union[Literal["policy.triggered", "policy.approval.pending", "policy.approval.resolved", "key.created", "key.deleted", "key.delegated", "key.exported", "wallet.blockchainevent.detected", "wallet.created", "wallet.activated", "wallet.delegated", "wallet.exported", "wallet.signature.failed", "wallet.signature.rejected", "wallet.signature.requested", "wallet.signature.signed", "wallet.transaction.broadcasted", "wallet.transaction.confirmed", "wallet.transaction.failed", "wallet.transaction.rejected", "wallet.transaction.requested", "wallet.transfer.broadcasted", "wallet.transfer.confirmed", "wallet.transfer.failed", "wallet.transfer.rejected", "wallet.transfer.requested", "wallet.offer.received", "wallet.offer.accepted", "wallet.offer.rejected", "wallet.tags.modified"], Literal["*"]]]
+    status: Literal["Enabled", "Disabled"]
+    description: NotRequired[str]
+    date_created: str
+    date_updated: str
+
+class UpdateWebhookRequest(TypedDict, total=False):
+    """updateWebhook request body."""
+
+    url: NotRequired[str]
+    description: NotRequired[str]
+    events: NotRequired[list[Union[Literal["policy.triggered", "policy.approval.pending", "policy.approval.resolved", "key.created", "key.deleted", "key.delegated", "key.exported", "wallet.blockchainevent.detected", "wallet.created", "wallet.activated", "wallet.delegated", "wallet.exported", "wallet.signature.failed", "wallet.signature.rejected", "wallet.signature.requested", "wallet.signature.signed", "wallet.transaction.broadcasted", "wallet.transaction.confirmed", "wallet.transaction.failed", "wallet.transaction.rejected", "wallet.transaction.requested", "wallet.transfer.broadcasted", "wallet.transfer.confirmed", "wallet.transfer.failed", "wallet.transfer.rejected", "wallet.transfer.requested", "wallet.offer.received", "wallet.offer.accepted", "wallet.offer.rejected", "wallet.tags.modified"], Literal["*"]]]]
+    status: NotRequired[Literal["Enabled", "Disabled"]]
+
+class UpdateWebhookResponse(TypedDict, total=False):
+    """updateWebhook response."""
+
+    id: str
+    url: str
+    events: list[Union[Literal["policy.triggered", "policy.approval.pending", "policy.approval.resolved", "key.created", "key.deleted", "key.delegated", "key.exported", "wallet.blockchainevent.detected", "wallet.created", "wallet.activated", "wallet.delegated", "wallet.exported", "wallet.signature.failed", "wallet.signature.rejected", "wallet.signature.requested", "wallet.signature.signed", "wallet.transaction.broadcasted", "wallet.transaction.confirmed", "wallet.transaction.failed", "wallet.transaction.rejected", "wallet.transaction.requested", "wallet.transfer.broadcasted", "wallet.transfer.confirmed", "wallet.transfer.failed", "wallet.transfer.rejected", "wallet.transfer.requested", "wallet.offer.received", "wallet.offer.accepted", "wallet.offer.rejected", "wallet.tags.modified"], Literal["*"]]]
+    status: Literal["Enabled", "Disabled"]
+    description: NotRequired[str]
+    date_created: str
+    date_updated: str
+
+class DeleteWebhookResponse(TypedDict, total=False):
+    """deleteWebhook response."""
+
+    deleted: Literal[True]
+
+class PingWebhookResponse(TypedDict, total=False):
+    """pingWebhook response."""
+
+    status: str
+    error: NotRequired[str]
+
+class GetWebhookEventResponse(TypedDict, total=False):
+    """getWebhookEvent response."""
+
+    id: str
+    date: str
+    kind: Literal["policy.triggered", "policy.approval.pending", "policy.approval.resolved", "key.created", "key.deleted", "key.delegated", "key.exported", "wallet.blockchainevent.detected", "wallet.created", "wallet.activated", "wallet.delegated", "wallet.exported", "wallet.signature.failed", "wallet.signature.rejected", "wallet.signature.requested", "wallet.signature.signed", "wallet.transaction.broadcasted", "wallet.transaction.confirmed", "wallet.transaction.failed", "wallet.transaction.rejected", "wallet.transaction.requested", "wallet.transfer.broadcasted", "wallet.transfer.confirmed", "wallet.transfer.failed", "wallet.transfer.rejected", "wallet.transfer.requested", "wallet.offer.received", "wallet.offer.accepted", "wallet.offer.rejected", "wallet.tags.modified"]
+    data: dict[str, dict[str, Any]]
+    status: str
+    error: NotRequired[str]
+    timestamp_sent: int
+
+class ListWebhookEventsResponse(TypedDict, total=False):
+    """listWebhookEvents response."""
+
+    items: list[TypedDict]
+    next_page_token: NotRequired[str]
+
+class ListWebhookEventsQuery(TypedDict, total=False):
+    """listWebhookEvents query parameters."""
+
+    kind: NotRequired[Literal["policy.triggered", "policy.approval.pending", "policy.approval.resolved", "key.created", "key.deleted", "key.delegated", "key.exported", "wallet.blockchainevent.detected", "wallet.created", "wallet.activated", "wallet.delegated", "wallet.exported", "wallet.signature.failed", "wallet.signature.rejected", "wallet.signature.requested", "wallet.signature.signed", "wallet.transaction.broadcasted", "wallet.transaction.confirmed", "wallet.transaction.failed", "wallet.transaction.rejected", "wallet.transaction.requested", "wallet.transfer.broadcasted", "wallet.transfer.confirmed", "wallet.transfer.failed", "wallet.transfer.rejected", "wallet.transfer.requested", "wallet.offer.received", "wallet.offer.accepted", "wallet.offer.rejected", "wallet.tags.modified"]]
+    delivery_failed: NotRequired[Literal["true", "false"]]
+    limit: NotRequired[int]
+    pagination_token: NotRequired[str]

dfns_sdk/types.py

@@ -0,0 +1,72 @@
+"""Base types for the Dfns SDK."""
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Awaitable, Optional
+
+
+@dataclass
+class DfnsClientConfig:
+    """Configuration for the Dfns client."""
+
+    auth_token: str
+    """Authentication token (JWT)."""
+
+    base_url: str = "https://api.dfns.io"
+    """Base URL for the Dfns API."""
+
+    signer: Optional["Signer"] = None
+    """Signer for user action requests."""
+
+    headers: dict[str, str] = field(default_factory=dict)
+    """Additional headers to include in requests."""
+
+
+@dataclass
+class DfnsDelegatedClientConfig:
+    """
+    Configuration for the delegated Dfns client.
+
+    Delegated clients are used when signing is handled externally,
+    separating the challenge init from the completion phase.
+    """
+
+    auth_token: str
+    """Authentication token (JWT) for the service account."""
+
+    base_url: str = "https://api.dfns.io"
+    """Base URL for the Dfns API."""
+
+    headers: dict[str, str] = field(default_factory=dict)
+    """Additional headers to include in requests."""
+
+
+class DfnsError(Exception):
+    """Exception raised by Dfns API errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        error_code: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code
+        self.details = details or {}
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.status_code:
+            parts.append(f"[{self.status_code}]")
+        if self.error_code:
+            parts.append(f"({self.error_code})")
+        return " ".join(parts)
+
+    def __repr__(self) -> str:
+        return f"DfnsError({self.message!r}, status_code={self.status_code}, error_code={self.error_code!r})"
+
+
+# Type alias for signer callback
+Signer = Callable[[str], Awaitable[str]]