linkedapi 1.0.0__py3-none-any.whl

linkedapi/core/operation.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from abc import ABC
+from typing import Any, Generic, TypeVar
+
+from linkedapi.core.polling import poll_workflow_result
+from linkedapi.errors import LinkedApiError, LinkedApiWorkflowTimeoutError
+from linkedapi.http import HttpClient
+from linkedapi.mappers import BaseMapper, MappedResponse
+from linkedapi.types import (
+    WorkflowCancelResponse,
+    WorkflowCompletion,
+    WorkflowInProgressResponse,
+    WorkflowResponse,
+    WorkflowStartedResponse,
+)
+
+TParams = TypeVar("TParams")
+TResult = TypeVar("TResult")
+
+
+class Operation(ABC, Generic[TParams, TResult]):
+    operation_name: str
+    mapper: BaseMapper[TParams, TResult]
+
+    def __init__(self, http_client: HttpClient[Any]) -> None:
+        self.http_client = http_client
+
+    def execute(self, params: TParams | None = None) -> WorkflowStartedResponse:
+        request = self.mapper.map_request(params)
+        response = self.http_client.post("/workflows", request)
+        if response.error:
+            raise LinkedApiError(response.error.type, response.error.message)
+        if response.result is None:
+            raise LinkedApiError.unknown_error()
+        return WorkflowStartedResponse.model_validate(response.result)
+
+    def result(
+        self,
+        workflow_id: str,
+        *,
+        poll_interval: float | None = None,
+        timeout: float | None = None,
+    ) -> MappedResponse[TResult]:
+        try:
+            return poll_workflow_result(
+                lambda: self.status(workflow_id),
+                poll_interval=5.0 if poll_interval is None else poll_interval,
+                timeout=86400.0 if timeout is None else timeout,
+            )
+        except LinkedApiError as error:
+            if error.type == "workflowTimeout":
+                raise LinkedApiWorkflowTimeoutError(workflow_id, self.operation_name) from error
+            raise
+
+    def status(self, workflow_id: str) -> WorkflowInProgressResponse | MappedResponse[TResult]:
+        workflow_result = self._get_workflow_result(workflow_id)
+        if workflow_result.workflow_status in {"running", "pending"}:
+            return WorkflowInProgressResponse(
+                workflow_id=workflow_id,
+                workflow_status=workflow_result.workflow_status,
+                message=workflow_result.message,
+            )
+
+        completion = self._get_completion(workflow_result)
+        return self.mapper.map_response(completion)
+
+    def cancel(self, workflow_id: str) -> bool:
+        response = self.http_client.delete(f"/workflows/{workflow_id}")
+        if response.error:
+            raise LinkedApiError(response.error.type, response.error.message)
+        if response.result is None:
+            raise LinkedApiError.unknown_error()
+        return WorkflowCancelResponse.model_validate(response.result).cancelled
+
+    def _get_workflow_result(self, workflow_id: str) -> WorkflowResponse:
+        response = self.http_client.get(f"/workflows/{workflow_id}")
+        if response.error:
+            raise LinkedApiError(response.error.type, response.error.message)
+        if response.result is None:
+            raise LinkedApiError.unknown_error()
+        return WorkflowResponse.model_validate(response.result)
+
+    def _get_completion(self, response: WorkflowResponse) -> WorkflowCompletion:
+        if response.completion is None:
+            if response.failure:
+                raise LinkedApiError(response.failure.reason, response.failure.message)
+            raise LinkedApiError.unknown_error()
+        return response.completion

linkedapi/core/polling.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import TypeVar, cast
+
+from linkedapi.errors import LinkedApiError
+from linkedapi.types import WorkflowInProgressResponse
+
+TResult = TypeVar("TResult")
+
+
+def poll_workflow_result(
+    workflow_result_fn: Callable[[], TResult | WorkflowInProgressResponse],
+    *,
+    poll_interval: float = 5.0,
+    timeout: float = 86400.0,
+    max_invalid_attempts: int = 15,
+) -> TResult:
+    start_time = time.monotonic()
+    invalid_attempts = 0
+
+    while time.monotonic() - start_time < timeout:
+        try:
+            result = workflow_result_fn()
+            if not _is_workflow_in_progress(result):
+                return cast(TResult, result)
+            invalid_attempts = 0
+        except LinkedApiError as error:
+            if error.type == "httpError":
+                invalid_attempts += 1
+                if invalid_attempts > max_invalid_attempts:
+                    raise
+            else:
+                raise
+
+        remaining = timeout - (time.monotonic() - start_time)
+        if remaining > 0:
+            time.sleep(min(poll_interval, remaining))
+
+    raise LinkedApiError("workflowTimeout", f"Workflow did not complete within {timeout}s")
+
+
+def _is_workflow_in_progress(value: object) -> bool:
+    status = getattr(value, "workflow_status", None)
+    if isinstance(value, dict):
+        status = value.get("workflowStatus") or value.get("workflow_status")
+    return status in {"running", "pending"}

linkedapi/errors.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+LinkedApiActionErrorType = Literal[
+    "personNotFound",
+    "selfProfileNotAllowed",
+    "messagingNotAllowed",
+    "alreadyPending",
+    "alreadyConnected",
+    "emailRequired",
+    "requestNotAllowed",
+    "notPending",
+    "retrievingNotAllowed",
+    "connectionNotFound",
+    "searchingNotAllowed",
+    "companyNotFound",
+    "postNotFound",
+    "commentingNotAllowed",
+    "noPostingPermission",
+    "noSalesNavigator",
+    "conversationsNotSynced",
+]
+LINKED_API_ACTION_ERROR_TYPES: tuple[str, ...] = (
+    "personNotFound",
+    "selfProfileNotAllowed",
+    "messagingNotAllowed",
+    "alreadyPending",
+    "alreadyConnected",
+    "emailRequired",
+    "requestNotAllowed",
+    "notPending",
+    "retrievingNotAllowed",
+    "connectionNotFound",
+    "searchingNotAllowed",
+    "companyNotFound",
+    "postNotFound",
+    "commentingNotAllowed",
+    "noPostingPermission",
+    "noSalesNavigator",
+    "conversationsNotSynced",
+)
+
+LinkedApiErrorType = Literal[
+    "linkedApiTokenRequired",
+    "invalidLinkedApiToken",
+    "identificationTokenRequired",
+    "invalidIdentificationToken",
+    "subscriptionRequired",
+    "invalidRequestPayload",
+    "invalidWorkflow",
+    "plusPlanRequired",
+    "linkedinAccountSignedOut",
+    "languageNotSupported",
+    "workflowTimeout",
+    "httpError",
+    "tooManyRequests",
+    "accountNotFound",
+    "accountIdRequired",
+    "sessionNotFound",
+    "noAvailableSeats",
+    "dailyConnectionAttemptsExceeded",
+]
+LINKED_API_ERROR_TYPES: tuple[str, ...] = (
+    "linkedApiTokenRequired",
+    "invalidLinkedApiToken",
+    "identificationTokenRequired",
+    "invalidIdentificationToken",
+    "subscriptionRequired",
+    "invalidRequestPayload",
+    "invalidWorkflow",
+    "plusPlanRequired",
+    "linkedinAccountSignedOut",
+    "languageNotSupported",
+    "workflowTimeout",
+    "httpError",
+    "tooManyRequests",
+    "accountNotFound",
+    "accountIdRequired",
+    "sessionNotFound",
+    "noAvailableSeats",
+    "dailyConnectionAttemptsExceeded",
+)
+
+
+class LinkedApiError(Exception):
+    type: str
+    message: str
+    details: Any | None
+
+    def __init__(self, type: str, message: str, details: Any | None = None) -> None:
+        super().__init__(message)
+        self.type = type
+        self.message = message
+        self.details = details
+
+    @classmethod
+    def unknown_error(
+        cls, message: str = "Unknown error. Please contact support."
+    ) -> LinkedApiError:
+        return cls("unknownError", message)
+
+
+class LinkedApiWorkflowTimeoutError(LinkedApiError):
+    workflow_id: str
+    operation_name: str
+
+    def __init__(self, workflow_id: str, operation_name: str) -> None:
+        message = (
+            f"Workflow {workflow_id} timed out. Call {operation_name}.result() again to continue "
+            "checking the workflow."
+        )
+        super().__init__(
+            "workflowTimeout",
+            message,
+            {"workflowId": workflow_id, "operationName": operation_name},
+        )
+        self.workflow_id = workflow_id
+        self.operation_name = operation_name

linkedapi/http/__init__.py

@@ -0,0 +1,4 @@
+from linkedapi.http.base import HttpClient
+from linkedapi.http.linked_api_http_client import LinkedApiHttpClient
+
+__all__ = ["HttpClient", "LinkedApiHttpClient"]

linkedapi/http/base.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Generic, TypeVar
+
+from linkedapi.types.responses import LinkedApiResponse
+
+TResult = TypeVar("TResult")
+
+
+class HttpClient(ABC, Generic[TResult]):
+    @abstractmethod
+    def get(self, path: str) -> LinkedApiResponse[Any]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def post(self, path: str, data: Any | None = None) -> LinkedApiResponse[Any]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete(self, path: str) -> LinkedApiResponse[Any]:
+        raise NotImplementedError

linkedapi/http/linked_api_http_client.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+
+from linkedapi.config import LinkedApiConfig
+from linkedapi.errors import LinkedApiError
+from linkedapi.http.base import HttpClient
+from linkedapi.types import LinkedApiResponse, serialize_value
+
+
+class LinkedApiHttpClient(HttpClient[Any]):
+    def __init__(
+        self,
+        config: LinkedApiConfig,
+        client: str | None = None,
+        base_url: str | None = None,
+        session: requests.Session | None = None,
+    ) -> None:
+        self.base_url = (base_url or config.base_url).rstrip("/")
+        self.session = session or requests.Session()
+        self.headers = {
+            "Content-Type": "application/json",
+            "linked-api-token": config.linked_api_token,
+            "identification-token": config.identification_token,
+            "client": client or config.client,
+        }
+
+    def get(self, path: str) -> LinkedApiResponse[Any]:
+        return self._request("GET", path)
+
+    def post(self, path: str, data: Any | None = None) -> LinkedApiResponse[Any]:
+        return self._request("POST", path, data)
+
+    def delete(self, path: str) -> LinkedApiResponse[Any]:
+        return self._request("DELETE", path)
+
+    def _request(self, method: str, path: str, data: Any | None = None) -> LinkedApiResponse[Any]:
+        try:
+            response = self.session.request(
+                method,
+                f"{self.base_url}{path}",
+                headers=self.headers,
+                json=serialize_value(data) if data is not None else None,
+            )
+            return self._handle_response(response)
+        except LinkedApiError:
+            raise
+        except requests.RequestException as error:
+            raise LinkedApiError(
+                "httpError", f"Request error: {error}", {"error": error}
+            ) from error
+
+    def _handle_response(self, response: requests.Response) -> LinkedApiResponse[Any]:
+        if response.ok:
+            return LinkedApiResponse[Any].model_validate(response.json())
+
+        try:
+            error_data = response.json()
+            error = error_data["error"]
+            raise LinkedApiError(error["type"], error["message"], error_data)
+        except LinkedApiError:
+            raise
+        except (KeyError, TypeError, ValueError) as error:
+            raise LinkedApiError(
+                "httpError",
+                f"HTTP {response.status_code}: {response.reason}",
+                {
+                    "status": response.status_code,
+                    "statusText": response.reason,
+                    "url": response.url,
+                },
+            ) from error

linkedapi/mappers/__init__.py

@@ -0,0 +1,16 @@
+from linkedapi.mappers.array import ArrayWorkflowMapper
+from linkedapi.mappers.base import BaseMapper, MappedResponse
+from linkedapi.mappers.simple import SimpleWorkflowMapper
+from linkedapi.mappers.then import ActionConfig, ResponseMapping, ThenWorkflowMapper
+from linkedapi.mappers.void import VoidWorkflowMapper
+
+__all__ = [
+    "ActionConfig",
+    "ArrayWorkflowMapper",
+    "BaseMapper",
+    "MappedResponse",
+    "ResponseMapping",
+    "SimpleWorkflowMapper",
+    "ThenWorkflowMapper",
+    "VoidWorkflowMapper",
+]

linkedapi/mappers/array.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Generic, TypeVar, cast
+
+from pydantic import BaseModel
+
+from linkedapi.mappers.base import (
+    BaseMapper,
+    MappedResponse,
+    as_action_dict,
+    collect_action_errors,
+    parse_action_error,
+    parse_result,
+)
+from linkedapi.types import WorkflowCompletion, WorkflowDefinition, serialize_model
+
+TParams = TypeVar("TParams")
+TItem = TypeVar("TItem")
+
+
+class ArrayWorkflowMapper(BaseMapper[TParams, list[TItem]], Generic[TParams, TItem]):
+    def __init__(self, base_action_type: str, item_model: type[BaseModel] | None = None) -> None:
+        self.base_action_type = base_action_type
+        self.item_model = item_model
+
+    def map_request(self, params: TParams | None = None) -> WorkflowDefinition:
+        return {"actionType": self.base_action_type, **serialize_model(params)}
+
+    def map_response(self, completion: WorkflowCompletion) -> MappedResponse[list[TItem]]:
+        if isinstance(completion, list):
+            data = [as_action_dict(action).get("data") for action in completion]
+            errors = collect_action_errors(
+                [as_action_dict(action).get("error") for action in completion]
+            )
+            return MappedResponse(
+                data=cast(list[TItem], parse_result(data, self.item_model)), errors=errors
+            )
+
+        action = as_action_dict(completion)
+        error = parse_action_error(action.get("error"))
+        if error is not None:
+            return MappedResponse(data=None, errors=[error])
+
+        single_data = action.get("data")
+        data_list = single_data if isinstance(single_data, list) else [single_data]
+        return MappedResponse(
+            data=cast(list[TItem], parse_result(data_list, self.item_model)),
+            errors=[],
+        )

linkedapi/mappers/base.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from linkedapi.errors import LinkedApiError
+from linkedapi.types import LinkedApiActionError, WorkflowCompletion, WorkflowDefinition
+
+TParams = TypeVar("TParams")
+TResult = TypeVar("TResult")
+
+
+@dataclass
+class MappedResponse(Generic[TResult]):
+    data: TResult | None = None
+    errors: list[LinkedApiActionError] = field(default_factory=list)
+
+
+class BaseMapper(ABC, Generic[TParams, TResult]):
+    @abstractmethod
+    def map_request(self, params: TParams | None = None) -> WorkflowDefinition:
+        raise NotImplementedError
+
+    @abstractmethod
+    def map_response(self, completion: WorkflowCompletion) -> MappedResponse[TResult]:
+        raise NotImplementedError
+
+
+def parse_action_error(value: Any) -> LinkedApiActionError | None:
+    if value is None:
+        return None
+    if isinstance(value, LinkedApiActionError):
+        return value
+    return LinkedApiActionError.model_validate(value)
+
+
+def collect_action_errors(values: list[Any]) -> list[LinkedApiActionError]:
+    errors: list[LinkedApiActionError] = []
+    for value in values:
+        parsed = parse_action_error(value)
+        if parsed is not None:
+            errors.append(parsed)
+    return errors
+
+
+def parse_result(data: Any, model: type[BaseModel] | None) -> Any:
+    if data is None or model is None:
+        return data
+    try:
+        if isinstance(data, list):
+            return [model.model_validate(item) for item in data]
+        return model.model_validate(data)
+    except ValidationError as error:
+        raise LinkedApiError(
+            "unknownError",
+            f"Failed to parse API response: {error}",
+            details=error.errors(),
+        ) from error
+
+
+def as_action_dict(action: Any) -> dict[str, Any]:
+    if isinstance(action, BaseModel):
+        return action.model_dump(by_alias=True, exclude_none=True)
+    if isinstance(action, dict):
+        return action
+    msg = "Expected action object"
+    raise TypeError(msg)

linkedapi/mappers/simple.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar, cast
+
+from pydantic import BaseModel
+
+from linkedapi.mappers.base import (
+    BaseMapper,
+    MappedResponse,
+    as_action_dict,
+    collect_action_errors,
+    parse_action_error,
+    parse_result,
+)
+from linkedapi.types import WorkflowCompletion, WorkflowDefinition, serialize_model
+
+TParams = TypeVar("TParams")
+TResult = TypeVar("TResult")
+
+
+class SimpleWorkflowMapper(BaseMapper[TParams, TResult], Generic[TParams, TResult]):
+    def __init__(
+        self,
+        action_type: str,
+        default_params: dict[str, Any] | None = None,
+        result_model: type[BaseModel] | None = None,
+    ) -> None:
+        self.action_type = action_type
+        self.default_params = default_params or {}
+        self.result_model = result_model
+
+    def map_request(self, params: TParams | None = None) -> WorkflowDefinition:
+        return {"actionType": self.action_type, **self.default_params, **serialize_model(params)}
+
+    def map_response(self, completion: WorkflowCompletion) -> MappedResponse[TResult]:
+        if isinstance(completion, list):
+            data = [
+                as_action_dict(action).get("data")
+                for action in completion
+                if as_action_dict(action).get("data")
+            ]
+            errors = collect_action_errors(
+                [as_action_dict(action).get("error") for action in completion]
+            )
+            return MappedResponse(
+                data=cast(TResult, parse_result(data, self.result_model)), errors=errors
+            )
+
+        action = as_action_dict(completion)
+        error = parse_action_error(action.get("error"))
+        if error is not None:
+            return MappedResponse(data=None, errors=[error])
+        return MappedResponse(
+            data=cast(TResult, parse_result(action.get("data"), self.result_model)),
+            errors=[],
+        )