linkedapi 1.0.0__tar.gz

linkedapi-1.0.0/.github/workflows/publish.yaml

@@ -0,0 +1,70 @@
+name: PR Merged -> main
+
+on:
+  push:
+    branches: ['main']
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: pip install -e '.[dev]'
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Type check
+        run: mypy linkedapi
+
+      - name: Test
+        run: pytest -q
+
+  publish:
+    needs: [quality]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Check if version changed
+        id: version-check
+        run: |
+          PACKAGE_NAME=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['name'])")
+          PACKAGE_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          PYPI_VERSION=$(curl -fsSL "https://pypi.org/pypi/${PACKAGE_NAME}/json" | python -c "import json,sys; print(json.load(sys.stdin)['info']['version'])" 2>/dev/null || echo "none")
+          if [ "$PACKAGE_VERSION" != "$PYPI_VERSION" ]; then
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+            echo "Version changed: $PYPI_VERSION -> $PACKAGE_VERSION"
+          else
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+            echo "Version unchanged: $PACKAGE_VERSION"
+          fi
+
+      - name: Build distributions
+        if: steps.version-check.outputs.should_publish == 'true'
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        if: steps.version-check.outputs.should_publish == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1

linkedapi-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+dist/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.venv/
+build/

linkedapi-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Linked API <https://linkedapi.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

linkedapi-1.0.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: linkedapi
+Version: 1.0.0
+Summary: Official synchronous Python SDK for Linked API.
+Project-URL: Homepage, https://linkedapi.io
+Project-URL: Repository, https://github.com/Linked-API/linkedapi-python
+Project-URL: Documentation, https://linkedapi.io/docs/
+Author: Linked API
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,automation,data,linkedapi,linkedin,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: requests<3,>=2
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: requests-mock>=1.12; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Description-Content-Type: text/markdown
+
+This official Python SDK is the synchronous way to integrate with Linked API. It provides pre-defined workflow operations, direct account/statistics methods, admin APIs, authentication headers, polling, and structured error responses.
+
+## Get started
+
+To get started with Linked API Python SDK, read these essential guides first:
+
+1. [Core concepts](https://linkedapi.io/sdks/core-concepts-0/) - understand how Linked API works.
+2. [Installation & authorization](https://linkedapi.io/sdks/installation-authorization/) - install the SDK and authorize it.
+3. [Predefined vs. custom workflows](https://linkedapi.io/sdks/predefined-vs-custom-workflows/) - choose ready-made operations or custom workflow definitions.
+4. [Handling results and errors](https://linkedapi.io/sdks/handling-results-and-errors/) - process successful data and action errors.
+5. [Persisting and cancelling workflows](https://linkedapi.io/sdks/persisting-and-cancelling-workflows/) - save, resume, and cancel workflows.
+
+Install the package:
+
+```bash
+pip install linkedapi
+```
+
+Initialize the client:
+
+```python
+from linkedapi import LinkedApi, LinkedApiConfig
+
+linkedapi = LinkedApi(
+    LinkedApiConfig(
+        linked_api_token="your-linked-api-token",
+        identification_token="your-identification-token",
+    )
+)
+```
+
+Run a predefined workflow and poll the result:
+
+```python
+from linkedapi import FetchPersonParams
+
+workflow = linkedapi.fetch_person.execute(
+    FetchPersonParams(
+        person_url="https://www.linkedin.com/in/john-doe",
+        retrieve_experience=True,
+        retrieve_posts=True,
+        posts_retrieval_config={"limit": 10},
+    )
+)
+
+result = linkedapi.fetch_person.result(workflow.workflow_id)
+if result.data:
+    print(result.data.name)
+for error in result.errors:
+    print(error.type, error.message)
+```
+
+Execute a custom workflow:
+
+```python
+workflow = linkedapi.custom_workflow.execute(
+    {
+        "actionType": "st.searchCompanies",
+        "term": "Tech Inc",
+        "filter": {
+            "sizes": ["51-200", "2001-5000"],
+            "locations": ["San Francisco", "New York"],
+            "industries": ["Software Development"],
+        },
+        "then": {"actionType": "st.openCompanyPage", "basicInfo": True},
+    }
+)
+
+result = linkedapi.custom_workflow.result(workflow.workflow_id)
+print(result.data)
+```
+
+Continue polling after a workflow timeout:
+
+```python
+from linkedapi import LinkedApiWorkflowTimeoutError
+
+try:
+    result = linkedapi.fetch_person.result(workflow.workflow_id, timeout=30.0)
+except LinkedApiWorkflowTimeoutError as error:
+    result = linkedapi.fetch_person.result(error.workflow_id)
+```
+
+Cancel a workflow:
+
+```python
+cancelled = linkedapi.fetch_person.cancel(workflow.workflow_id)
+print(cancelled)
+```
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

linkedapi-1.0.0/README.md

@@ -0,0 +1,93 @@
+This official Python SDK is the synchronous way to integrate with Linked API. It provides pre-defined workflow operations, direct account/statistics methods, admin APIs, authentication headers, polling, and structured error responses.
+
+## Get started
+
+To get started with Linked API Python SDK, read these essential guides first:
+
+1. [Core concepts](https://linkedapi.io/sdks/core-concepts-0/) - understand how Linked API works.
+2. [Installation & authorization](https://linkedapi.io/sdks/installation-authorization/) - install the SDK and authorize it.
+3. [Predefined vs. custom workflows](https://linkedapi.io/sdks/predefined-vs-custom-workflows/) - choose ready-made operations or custom workflow definitions.
+4. [Handling results and errors](https://linkedapi.io/sdks/handling-results-and-errors/) - process successful data and action errors.
+5. [Persisting and cancelling workflows](https://linkedapi.io/sdks/persisting-and-cancelling-workflows/) - save, resume, and cancel workflows.
+
+Install the package:
+
+```bash
+pip install linkedapi
+```
+
+Initialize the client:
+
+```python
+from linkedapi import LinkedApi, LinkedApiConfig
+
+linkedapi = LinkedApi(
+    LinkedApiConfig(
+        linked_api_token="your-linked-api-token",
+        identification_token="your-identification-token",
+    )
+)
+```
+
+Run a predefined workflow and poll the result:
+
+```python
+from linkedapi import FetchPersonParams
+
+workflow = linkedapi.fetch_person.execute(
+    FetchPersonParams(
+        person_url="https://www.linkedin.com/in/john-doe",
+        retrieve_experience=True,
+        retrieve_posts=True,
+        posts_retrieval_config={"limit": 10},
+    )
+)
+
+result = linkedapi.fetch_person.result(workflow.workflow_id)
+if result.data:
+    print(result.data.name)
+for error in result.errors:
+    print(error.type, error.message)
+```
+
+Execute a custom workflow:
+
+```python
+workflow = linkedapi.custom_workflow.execute(
+    {
+        "actionType": "st.searchCompanies",
+        "term": "Tech Inc",
+        "filter": {
+            "sizes": ["51-200", "2001-5000"],
+            "locations": ["San Francisco", "New York"],
+            "industries": ["Software Development"],
+        },
+        "then": {"actionType": "st.openCompanyPage", "basicInfo": True},
+    }
+)
+
+result = linkedapi.custom_workflow.result(workflow.workflow_id)
+print(result.data)
+```
+
+Continue polling after a workflow timeout:
+
+```python
+from linkedapi import LinkedApiWorkflowTimeoutError
+
+try:
+    result = linkedapi.fetch_person.result(workflow.workflow_id, timeout=30.0)
+except LinkedApiWorkflowTimeoutError as error:
+    result = linkedapi.fetch_person.result(error.workflow_id)
+```
+
+Cancel a workflow:
+
+```python
+cancelled = linkedapi.fetch_person.cancel(workflow.workflow_id)
+print(cancelled)
+```
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

linkedapi-1.0.0/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-1.0.0/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-1.0.0/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-1.0.0/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-1.0.0/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