linkedapi 1.0.0__py3-none-any.whl

linkedapi/__init__.py

@@ -0,0 +1,127 @@
+from linkedapi.admin import (
+    AdminAccounts,
+    AdminHttpClient,
+    AdminLimits,
+    AdminSubscription,
+    LinkedApiAdmin,
+)
+from linkedapi.client import LinkedApi
+from linkedapi.config import LinkedApiConfig
+from linkedapi.core import Operation, poll_workflow_result
+from linkedapi.errors import (
+    LINKED_API_ACTION_ERROR_TYPES,
+    LINKED_API_ERROR_TYPES,
+    LinkedApiActionErrorType,
+    LinkedApiError,
+    LinkedApiErrorType,
+    LinkedApiWorkflowTimeoutError,
+)
+from linkedapi.http import HttpClient, LinkedApiHttpClient
+from linkedapi.mappers import (
+    ActionConfig,
+    ArrayWorkflowMapper,
+    BaseMapper,
+    MappedResponse,
+    ResponseMapping,
+    SimpleWorkflowMapper,
+    ThenWorkflowMapper,
+    VoidWorkflowMapper,
+)
+from linkedapi.operations import (
+    CheckConnectionStatus,
+    CommentOnPost,
+    CreatePost,
+    CustomWorkflow,
+    FetchCompany,
+    FetchCompanyMapper,
+    FetchPerson,
+    FetchPersonMapper,
+    FetchPost,
+    FetchPostMapper,
+    NvFetchCompany,
+    NvFetchCompanyMapper,
+    NvFetchPerson,
+    NvFetchPersonMapper,
+    NvSearchCompanies,
+    NvSearchPeople,
+    NvSendMessage,
+    NvSyncConversation,
+    ReactToPost,
+    RemoveConnection,
+    RetrieveConnections,
+    RetrievePendingRequests,
+    RetrievePerformance,
+    RetrieveSSI,
+    SearchCompanies,
+    SearchPeople,
+    SendConnectionRequest,
+    SendMessage,
+    SyncConversation,
+    WithdrawConnectionRequest,
+)
+from linkedapi.types import *  # noqa: F403
+from linkedapi.types import __all__ as _types_all
+
+__version__ = "1.0.0"
+PredefinedOperation = Operation
+
+__all__ = [
+    *_types_all,
+    "AdminAccounts",
+    "AdminHttpClient",
+    "AdminLimits",
+    "AdminSubscription",
+    "ActionConfig",
+    "ArrayWorkflowMapper",
+    "BaseMapper",
+    "CheckConnectionStatus",
+    "CommentOnPost",
+    "CreatePost",
+    "CustomWorkflow",
+    "FetchCompany",
+    "FetchCompanyMapper",
+    "FetchPerson",
+    "FetchPersonMapper",
+    "FetchPost",
+    "FetchPostMapper",
+    "HttpClient",
+    "LINKED_API_ACTION_ERROR_TYPES",
+    "LINKED_API_ERROR_TYPES",
+    "LinkedApi",
+    "LinkedApiActionErrorType",
+    "LinkedApiAdmin",
+    "LinkedApiConfig",
+    "LinkedApiError",
+    "LinkedApiErrorType",
+    "LinkedApiHttpClient",
+    "LinkedApiWorkflowTimeoutError",
+    "MappedResponse",
+    "NvFetchCompany",
+    "NvFetchCompanyMapper",
+    "NvFetchPerson",
+    "NvFetchPersonMapper",
+    "NvSearchCompanies",
+    "NvSearchPeople",
+    "NvSendMessage",
+    "NvSyncConversation",
+    "Operation",
+    "PredefinedOperation",
+    "ReactToPost",
+    "RemoveConnection",
+    "ResponseMapping",
+    "RetrieveConnections",
+    "RetrievePendingRequests",
+    "RetrievePerformance",
+    "RetrieveSSI",
+    "SearchCompanies",
+    "SearchPeople",
+    "SendConnectionRequest",
+    "SendMessage",
+    "SimpleWorkflowMapper",
+    "SyncConversation",
+    "ThenWorkflowMapper",
+    "VoidWorkflowMapper",
+    "WithdrawConnectionRequest",
+    "__version__",
+    "poll_workflow_result",
+]

linkedapi/admin/__init__.py

@@ -0,0 +1,13 @@
+from linkedapi.admin.accounts import AdminAccounts
+from linkedapi.admin.admin import LinkedApiAdmin
+from linkedapi.admin.http_client import AdminHttpClient
+from linkedapi.admin.limits import AdminLimits
+from linkedapi.admin.subscription import AdminSubscription
+
+__all__ = [
+    "AdminAccounts",
+    "AdminHttpClient",
+    "AdminLimits",
+    "AdminSubscription",
+    "LinkedApiAdmin",
+]

linkedapi/admin/accounts.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from linkedapi.errors import LinkedApiError
+from linkedapi.http import HttpClient
+from linkedapi.types.admin import (
+    AccountsResult,
+    CancelConnectionSessionParams,
+    ConnectionSessionResult,
+    CreateConnectionSessionResult,
+    DisconnectParams,
+    GetConnectionSessionParams,
+    RegenerateTokenParams,
+    RegenerateTokenResult,
+)
+
+TModel = TypeVar("TModel", bound=BaseModel)
+
+
+class AdminAccounts:
+    def __init__(self, http_client: HttpClient[Any]) -> None:
+        self.http_client = http_client
+
+    def get_all(self) -> AccountsResult:
+        return self._post_result("/admin/accounts.getAll", AccountsResult, "Failed to get accounts")
+
+    def disconnect(self, params: DisconnectParams) -> None:
+        self._post_void("/admin/accounts.disconnect", "Failed to disconnect account", params)
+
+    def regenerate_identification_token(
+        self,
+        params: RegenerateTokenParams,
+    ) -> RegenerateTokenResult:
+        return self._post_result(
+            "/admin/accounts.regenerateIdentificationToken",
+            RegenerateTokenResult,
+            "Failed to regenerate token",
+            params,
+        )
+
+    def create_connection_session(self) -> CreateConnectionSessionResult:
+        return self._post_result(
+            "/admin/accounts.createConnectionSession",
+            CreateConnectionSessionResult,
+            "Failed to create connection session",
+        )
+
+    def get_connection_session(
+        self,
+        params: GetConnectionSessionParams,
+    ) -> ConnectionSessionResult:
+        return self._post_result(
+            "/admin/accounts.getConnectionSession",
+            ConnectionSessionResult,
+            "Failed to get connection session",
+            params,
+        )
+
+    def cancel_connection_session(self, params: CancelConnectionSessionParams) -> None:
+        self._post_void(
+            "/admin/accounts.cancelConnectionSession",
+            "Failed to cancel connection session",
+            params,
+        )
+
+    def _post_result(
+        self,
+        path: str,
+        model: type[TModel],
+        default_message: str,
+        params: Any | None = None,
+    ) -> TModel:
+        response = self.http_client.post(path, params)
+        if response.success and response.result is not None:
+            return model.model_validate(response.result)
+        raise LinkedApiError(
+            response.error.type if response.error else "httpError",
+            response.error.message if response.error else default_message,
+        )
+
+    def _post_void(self, path: str, default_message: str, params: Any | None = None) -> None:
+        response = self.http_client.post(path, params)
+        if response.success:
+            return
+        raise LinkedApiError(
+            response.error.type if response.error else "httpError",
+            response.error.message if response.error else default_message,
+        )

linkedapi/admin/admin.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Any
+
+from linkedapi.admin.accounts import AdminAccounts
+from linkedapi.admin.http_client import AdminHttpClient
+from linkedapi.admin.limits import AdminLimits
+from linkedapi.admin.subscription import AdminSubscription
+from linkedapi.http import HttpClient
+from linkedapi.types.admin import AdminConfig
+
+
+class LinkedApiAdmin:
+    """Admin SDK for Linked API subscription, account, and limit management."""
+
+    def __init__(self, config: AdminConfig | HttpClient[Any]) -> None:
+        http_client = (
+            config if isinstance(config, HttpClient) else AdminHttpClient(config, config.client)
+        )
+        self.subscription = AdminSubscription(http_client)
+        self.accounts = AdminAccounts(http_client)
+        self.limits = AdminLimits(http_client)

linkedapi/admin/http_client.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+
+from linkedapi.errors import LinkedApiError
+from linkedapi.http import HttpClient
+from linkedapi.types import LinkedApiResponse, serialize_value
+from linkedapi.types.admin import AdminConfig
+
+
+class AdminHttpClient(HttpClient[Any]):
+    def __init__(
+        self,
+        config: AdminConfig,
+        client: str | None = None,
+        base_url: str = "https://api.linkedapi.io",
+        session: requests.Session | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.session = session or requests.Session()
+        self.headers = {
+            "Content-Type": "application/json",
+            "linked-api-token": config.linked_api_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/admin/limits.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from linkedapi.errors import LinkedApiError
+from linkedapi.http import HttpClient
+from linkedapi.types.admin import (
+    DeleteLimitsParams,
+    GetLimitsParams,
+    GetLimitsUsageParams,
+    LimitsResult,
+    LimitUsageResult,
+    ResetLimitsParams,
+    SetLimitsParams,
+)
+
+TModel = TypeVar("TModel", bound=BaseModel)
+
+
+class AdminLimits:
+    def __init__(self, http_client: HttpClient[Any]) -> None:
+        self.http_client = http_client
+
+    def get_defaults(self) -> LimitsResult:
+        return self._post_result(
+            "/admin/limits.getDefaults", LimitsResult, "Failed to get default limits"
+        )
+
+    def get(self, params: GetLimitsParams) -> LimitsResult:
+        return self._post_result("/admin/limits.get", LimitsResult, "Failed to get limits", params)
+
+    def get_usage(self, params: GetLimitsUsageParams) -> LimitUsageResult:
+        return self._post_result(
+            "/admin/limits.getUsage", LimitUsageResult, "Failed to get limits usage", params
+        )
+
+    def set(self, params: SetLimitsParams) -> None:
+        self._post_void("/admin/limits.set", "Failed to set limits", params)
+
+    def delete(self, params: DeleteLimitsParams) -> None:
+        self._post_void("/admin/limits.delete", "Failed to delete limits", params)
+
+    def reset_to_defaults(self, params: ResetLimitsParams) -> None:
+        self._post_void("/admin/limits.resetToDefaults", "Failed to reset limits", params)
+
+    def _post_result(
+        self,
+        path: str,
+        model: type[TModel],
+        default_message: str,
+        params: Any | None = None,
+    ) -> TModel:
+        response = self.http_client.post(path, params)
+        if response.success and response.result is not None:
+            return model.model_validate(response.result)
+        raise LinkedApiError(
+            response.error.type if response.error else "httpError",
+            response.error.message if response.error else default_message,
+        )
+
+    def _post_void(self, path: str, default_message: str, params: Any | None = None) -> None:
+        response = self.http_client.post(path, params)
+        if response.success:
+            return
+        raise LinkedApiError(
+            response.error.type if response.error else "httpError",
+            response.error.message if response.error else default_message,
+        )

linkedapi/admin/subscription.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from linkedapi.errors import LinkedApiError
+from linkedapi.http import HttpClient
+from linkedapi.types.admin import (
+    BillingLinkResult,
+    CancelResult,
+    SetSeatsParams,
+    SetSeatsResult,
+    SubscriptionPricingResult,
+    SubscriptionSeatsResult,
+    SubscriptionStatus,
+)
+
+TModel = TypeVar("TModel", bound=BaseModel)
+
+
+class AdminSubscription:
+    def __init__(self, http_client: HttpClient[Any]) -> None:
+        self.http_client = http_client
+
+    def get_status(self) -> SubscriptionStatus:
+        return self._post_result(
+            "/admin/subscription.getStatus", SubscriptionStatus, "Failed to get subscription status"
+        )
+
+    def get_seats(self) -> SubscriptionSeatsResult:
+        return self._post_result(
+            "/admin/subscription.getSeats", SubscriptionSeatsResult, "Failed to get seats"
+        )
+
+    def get_pricing(self) -> SubscriptionPricingResult:
+        return self._post_result(
+            "/admin/subscription.getPricing", SubscriptionPricingResult, "Failed to get pricing"
+        )
+
+    def set_seats(self, params: SetSeatsParams) -> SetSeatsResult:
+        return self._post_result(
+            "/admin/subscription.setSeats", SetSeatsResult, "Failed to set seats", params
+        )
+
+    def get_billing_link(self) -> BillingLinkResult:
+        return self._post_result(
+            "/admin/subscription.getBillingLink", BillingLinkResult, "Failed to get billing link"
+        )
+
+    def cancel(self) -> CancelResult:
+        return self._post_result(
+            "/admin/subscription.cancel", CancelResult, "Failed to cancel subscription"
+        )
+
+    def _post_result(
+        self,
+        path: str,
+        model: type[TModel],
+        default_message: str,
+        params: Any | None = None,
+    ) -> TModel:
+        response = self.http_client.post(path, params)
+        if response.success and response.result is not None:
+            return model.model_validate(response.result)
+        raise LinkedApiError(
+            response.error.type if response.error else "httpError",
+            response.error.message if response.error else default_message,
+        )

linkedapi/client.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlencode
+
+from linkedapi.config import LinkedApiConfig
+from linkedapi.errors import LinkedApiError
+from linkedapi.http import HttpClient, LinkedApiHttpClient
+from linkedapi.mappers import MappedResponse
+from linkedapi.operations import (
+    CheckConnectionStatus,
+    CommentOnPost,
+    CreatePost,
+    CustomWorkflow,
+    FetchCompany,
+    FetchPerson,
+    FetchPost,
+    NvFetchCompany,
+    NvFetchPerson,
+    NvSearchCompanies,
+    NvSearchPeople,
+    NvSendMessage,
+    NvSyncConversation,
+    ReactToPost,
+    RemoveConnection,
+    RetrieveConnections,
+    RetrievePendingRequests,
+    RetrievePerformance,
+    RetrieveSSI,
+    SearchCompanies,
+    SearchPeople,
+    SendConnectionRequest,
+    SendMessage,
+    SyncConversation,
+    WithdrawConnectionRequest,
+)
+from linkedapi.types import AccountInfo, LinkedApiActionError, serialize_value
+from linkedapi.types.message import ConversationPollRequest, ConversationPollResult
+from linkedapi.types.statistics import ApiUsageAction, ApiUsageParams
+
+
+class LinkedApi:
+    """Official synchronous Python SDK for Linked API."""
+
+    def __init__(self, config: LinkedApiConfig | HttpClient[Any]) -> None:
+        self.http_client = (
+            config
+            if isinstance(config, HttpClient)
+            else LinkedApiHttpClient(config, config.client, config.base_url)
+        )
+
+        self.custom_workflow = CustomWorkflow(self.http_client)
+        self.send_message = SendMessage(self.http_client)
+        self.sync_conversation = SyncConversation(self.http_client)
+        self.check_connection_status = CheckConnectionStatus(self.http_client)
+        self.send_connection_request = SendConnectionRequest(self.http_client)
+        self.withdraw_connection_request = WithdrawConnectionRequest(self.http_client)
+        self.retrieve_pending_requests = RetrievePendingRequests(self.http_client)
+        self.retrieve_connections = RetrieveConnections(self.http_client)
+        self.remove_connection = RemoveConnection(self.http_client)
+        self.search_companies = SearchCompanies(self.http_client)
+        self.search_people = SearchPeople(self.http_client)
+        self.fetch_company = FetchCompany(self.http_client)
+        self.fetch_person = FetchPerson(self.http_client)
+        self.fetch_post = FetchPost(self.http_client)
+        self.react_to_post = ReactToPost(self.http_client)
+        self.comment_on_post = CommentOnPost(self.http_client)
+        self.create_post = CreatePost(self.http_client)
+        self.retrieve_ssi = RetrieveSSI(self.http_client)
+        self.retrieve_performance = RetrievePerformance(self.http_client)
+        self.nv_send_message = NvSendMessage(self.http_client)
+        self.nv_sync_conversation = NvSyncConversation(self.http_client)
+        self.nv_search_companies = NvSearchCompanies(self.http_client)
+        self.nv_search_people = NvSearchPeople(self.http_client)
+        self.nv_fetch_company = NvFetchCompany(self.http_client)
+        self.nv_fetch_person = NvFetchPerson(self.http_client)
+
+        self.operations = [
+            self.custom_workflow,
+            self.send_message,
+            self.sync_conversation,
+            self.check_connection_status,
+            self.send_connection_request,
+            self.withdraw_connection_request,
+            self.retrieve_pending_requests,
+            self.retrieve_connections,
+            self.remove_connection,
+            self.search_companies,
+            self.search_people,
+            self.fetch_company,
+            self.fetch_person,
+            self.fetch_post,
+            self.react_to_post,
+            self.comment_on_post,
+            self.create_post,
+            self.retrieve_ssi,
+            self.retrieve_performance,
+            self.nv_send_message,
+            self.nv_sync_conversation,
+            self.nv_search_companies,
+            self.nv_search_people,
+            self.nv_fetch_company,
+            self.nv_fetch_person,
+        ]
+
+    def poll_conversations(
+        self,
+        conversations: list[ConversationPollRequest],
+    ) -> MappedResponse[list[ConversationPollResult]]:
+        """Poll previously synced standard or Sales Navigator conversations."""
+
+        try:
+            response = self.http_client.post("/conversations/poll", serialize_value(conversations))
+            if response.success and response.result is not None:
+                return MappedResponse(
+                    data=[ConversationPollResult.model_validate(item) for item in response.result],
+                    errors=[],
+                )
+            return MappedResponse(
+                data=None,
+                errors=[
+                    LinkedApiActionError(
+                        type=response.error.type if response.error else "",
+                        message=response.error.message if response.error else "",
+                    ),
+                ],
+            )
+        except LinkedApiError as error:
+            if error.type == "conversationsNotSynced":
+                return MappedResponse(
+                    data=None,
+                    errors=[LinkedApiActionError(type=error.type, message=error.message)],
+                )
+            raise
+
+    def get_account_info(self) -> MappedResponse[AccountInfo]:
+        """Retrieve basic information about the current LinkedIn account."""
+
+        response = self.http_client.get("/account")
+        if response.success and response.result is not None:
+            return MappedResponse(data=AccountInfo.model_validate(response.result), errors=[])
+        raise LinkedApiError(
+            response.error.type if response.error else "httpError",
+            response.error.message if response.error else "",
+        )
+
+    def get_api_usage(self, params: ApiUsageParams) -> MappedResponse[list[ApiUsageAction]]:
+        """Retrieve Linked API action usage statistics for a time period."""
+
+        query_params = urlencode({"start": params.start, "end": params.end})
+        response = self.http_client.get(f"/stats/actions?{query_params}")
+        if response.success and response.result is not None:
+            return MappedResponse(
+                data=[ApiUsageAction.model_validate(item) for item in response.result],
+                errors=[],
+            )
+        raise LinkedApiError(
+            response.error.type if response.error else "httpError",
+            response.error.message if response.error else "",
+        )

linkedapi/config.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from linkedapi.types.base import LinkedApiModel
+
+
+class LinkedApiConfig(LinkedApiModel):
+    linked_api_token: str
+    identification_token: str
+    client: str = "python"
+    base_url: str = "https://api.linkedapi.io"

linkedapi/core/__init__.py

@@ -0,0 +1,4 @@
+from linkedapi.core.operation import Operation
+from linkedapi.core.polling import poll_workflow_result
+
+__all__ = ["Operation", "poll_workflow_result"]