bosa-connectors-binary 0.0.7.post1__cp312-cp312-manylinux_2_31_x86_64.whl

bosa_connectors/__init__.pyi

@@ -0,0 +1,5 @@
+from .connector import BosaConnector as BosaConnector
+from .module import BosaConnectorModule as BosaConnectorModule
+from bosa_connectors.helpers.authenticator import BosaAuthenticator as BosaAuthenticator
+
+__all__ = ['BosaAuthenticator', 'BosaConnector', 'BosaConnectorModule']

bosa_connectors/action.pyi

@@ -0,0 +1,80 @@
+from bosa_connectors.action_response import ActionResponse as ActionResponse
+from bosa_connectors.auth import BaseAuthenticator as BaseAuthenticator
+from bosa_connectors.models.file import ConnectorFile as ConnectorFile
+from bosa_connectors.module import BosaConnectorModule as BosaConnectorModule
+from typing import Any
+
+class ActionExecutor:
+    """Represents a specific action execution for a service.
+
+    Example:
+        # Direct execution with raw response
+        data, status = github.action('list_pull_requests')            .params({'owner': 'GDP-ADMIN', 'repo': 'bosa'})            .execute()
+
+        # Or with pagination support
+        response = github.action('list_pull_requests')            .params({'owner': 'GDP-ADMIN', 'repo': 'bosa'})            .run()
+
+        # Get data and handle pagination
+        data = response.get_data()
+        while response.has_next():
+            response = response.next_page()
+            data = response.get_data()
+    """
+    DEFAULT_MAX_ATTEMPTS: int
+    DEFAULT_TIMEOUT: int
+    def __init__(self, module: BosaConnectorModule, authenticator: BaseAuthenticator, action: str) -> None:
+        """Initialize the action executor.
+
+        Args:
+            module: The connector module to execute against
+            authenticator: The authenticator to use for requests
+            action: The action name to execute
+        """
+    def params(self, params: dict[str, Any]) -> ActionExecutor:
+        """Set additional parameters."""
+    def headers(self, headers: dict[str, str]) -> ActionExecutor:
+        """Set request headers."""
+    def max_attempts(self, attempts: int) -> ActionExecutor:
+        """Set maximum retry attempts."""
+    def token(self, token: str | None) -> ActionExecutor:
+        """Set the BOSA user token for this action."""
+    def timeout(self, timeout: int | None) -> ActionExecutor:
+        """Set the timeout for the request."""
+    def execute(self) -> tuple[dict[str, Any] | ConnectorFile, int]:
+        """Execute request and return raw response.
+
+        Returns:
+            Tuple of (response_data, status_code)
+        """
+    def run(self) -> ActionResponse:
+        """Execute request and return paginated response.
+
+        Returns an ActionResponse that supports pagination for list responses.
+        For single item responses, pagination methods will return the same item.
+
+        Returns:
+            ActionResponse with pagination support
+        """
+
+class Action:
+    """Base class for plugins to prepare action execution.
+
+    Example:
+        # Create a GitHub connector
+        github = bosa.connect('github')
+
+        # Execute with raw response
+        data, status = github.action('list_pull_requests')            .params({'owner': 'GDP-ADMIN', 'repo': 'bosa'})            .execute()
+
+        # Or with pagination support
+        response = github.action('list_pull_requests')            .params({'owner': 'GDP-ADMIN', 'repo': 'bosa'})            .run()
+    """
+    def __init__(self, module: BosaConnectorModule, authenticator: BaseAuthenticator) -> None:
+        """Initialize the action builder.
+
+        Args:
+            module: The connector module to use
+            authenticator: The authenticator to use for requests
+        """
+    def action(self, action: str) -> ActionExecutor:
+        """Create a new action executor for a service."""

bosa_connectors/action_response.pyi

@@ -0,0 +1,86 @@
+from bosa_connectors.models.action import ActionResponseData as ActionResponseData, InitialExecutorRequest as InitialExecutorRequest
+from bosa_connectors.models.file import ConnectorFile as ConnectorFile
+from typing import Any, Callable
+
+class ActionResponse:
+    '''Represents the response from an action execution.
+
+    Currently supports 2 pagination modes:
+    1. Page-based pagination: Using page numbers (page=1, page=2, etc.)
+    2. Cursor-based pagination: Using cursor tokens for forwards and backwards navigation
+
+    The class automatically detects which pagination mode to use based on the response metadata:
+    - If "forwards_cursor" and "backwards_cursor" are present, cursor-based pagination is used
+    - Otherwise, it falls back to page-based pagination using "page" parameter
+
+    Common pagination attributes:
+    - total: Total number of items
+    - total_page: Total number of pages
+    - has_next: Whether there is a next page
+    - has_prev: Whether there is a previous page
+
+    Followed by optional attributes
+    Cursor-based pagination attributes:
+    - forwards_cursor: Cursor for next page
+    - backwards_cursor: Cursor for previous page
+
+    Page-based pagination attributes:
+    - page: Current page number
+    - limit: Number of items per page
+
+    If the response is ConnectorFile, it will not support pagination and will return the file directly.
+    '''
+    def __init__(self, response_data: dict[str, Any] | ConnectorFile | None, status: int, response_creator: Callable[..., 'ActionResponse'], initial_executor_request: dict[str, Any]) -> None:
+        '''Initialize response wrapper.
+
+        Args:
+            response_data: Response data which could be:
+                 - List response: {"data": [...], "meta": {...}}
+                 - Single item response: {"data": {...}, "meta": {...}}
+            status: HTTP status code
+            response_creator: Callable to create a new ActionResponse
+            initial_executor_request: Initial action request attributes as dict
+        '''
+    def get_data(self) -> list[dict[str, Any]] | dict[str, Any] | ConnectorFile:
+        """Get the current page data.
+
+        Returns:
+            List of objects for paginated responses, or
+            Single object for single item responses
+        """
+    def get_meta(self) -> dict[str, Any]:
+        """Get the meta data."""
+    def get_status(self) -> int:
+        """Get the HTTP status code."""
+    def is_list(self) -> bool:
+        """Check if the response data is a list."""
+    def has_next(self) -> bool:
+        """Check if there is a next page.
+
+        Returns False if this is a single item response.
+        """
+    def has_prev(self) -> bool:
+        """Check if there is a previous page.
+
+        Returns False if this is a single item response.
+        """
+    def next_page(self) -> ActionResponse:
+        """Move to the next page and get the response.
+
+        Supports both page-based and cursor-based navigation:
+        1. If forwards_cursor is available, uses cursor-based navigation
+        2. Otherwise, falls back to page-based navigation
+
+        Returns self if this is a single item response or there is no next page.
+        """
+    def prev_page(self) -> ActionResponse:
+        """Move to the previous page and get the response.
+
+        Supports both page-based and cursor-based navigation:
+        1. If backwards_cursor is available, uses cursor-based navigation
+        2. Otherwise, falls back to page-based navigation
+
+        Returns self if this is a single item data or there is no previous page.
+        """
+    def get_all_items(self) -> list[Any]:
+        """Get all items from all pages."""

bosa_connectors/auth/__init__.pyi

@@ -0,0 +1,4 @@
+from .api_key import ApiKeyAuthenticator as ApiKeyAuthenticator
+from .base import BaseAuthenticator as BaseAuthenticator
+
+__all__ = ['BaseAuthenticator', 'ApiKeyAuthenticator']

bosa_connectors/auth/api_key.pyi

@@ -0,0 +1,19 @@
+from _typeshed import Incomplete
+from bosa_connectors.auth.base import BaseAuthenticator as BaseAuthenticator
+
+class ApiKeyAuthenticator(BaseAuthenticator):
+    """Injects API Key Headers to BOSA API for Authentication."""
+    API_KEY_HEADER: str
+    api_key: Incomplete
+    def __init__(self, api_key: str) -> None:
+        """Initializes the ApiKeyAuthenticator with the provided API key.
+
+        Args:
+            api_key (str): The API key for authentication.
+        """
+    def authenticate(self):
+        """Authenticates the request.
+
+        Raises:
+            AuthenticationError: If authentication fails.
+        """

bosa_connectors/auth/base.pyi

@@ -0,0 +1,12 @@
+import abc
+from abc import ABC, abstractmethod
+
+class BaseAuthenticator(ABC, metaclass=abc.ABCMeta):
+    """Base authenticator for BOSA API."""
+    @abstractmethod
+    def authenticate(self):
+        """Authenticates the request.
+
+        Raises:
+            AuthenticationError: If authentication fails.
+        """

bosa_connectors/connector.pyi

@@ -0,0 +1,161 @@
+from _typeshed import Incomplete
+from bosa_connectors.action import Action as Action
+from bosa_connectors.action_response import ActionResponse as ActionResponse
+from bosa_connectors.auth import ApiKeyAuthenticator as ApiKeyAuthenticator
+from bosa_connectors.helpers.authenticator import BosaAuthenticator as BosaAuthenticator
+from bosa_connectors.helpers.integrations import BosaIntegrationHelper as BosaIntegrationHelper
+from bosa_connectors.models.file import ConnectorFile as ConnectorFile
+from bosa_connectors.models.result import ActionResult as ActionResult
+from bosa_connectors.models.token import BosaToken as BosaToken
+from bosa_connectors.models.user import BosaUser as BosaUser, CreateUserResponse as CreateUserResponse
+from bosa_connectors.module import BosaConnectorError as BosaConnectorError, BosaConnectorModule as BosaConnectorModule
+from typing import Any
+
+class BosaConnector:
+    """Main connector class that manages all BOSA connector modules."""
+    DEFAULT_TIMEOUT: int
+    DEFAULT_MAX_ATTEMPTS: int
+    OAUTH2_FLOW_ENDPOINT: str
+    INTEGRATION_CHECK_ENDPOINT: str
+    api_base_url: Incomplete
+    auth_scheme: Incomplete
+    bosa_authenticator: Incomplete
+    bosa_integration_helper: Incomplete
+    def __init__(self, api_base_url: str = 'https://api.bosa.id', api_key: str = 'bosa') -> None:
+        """Initialization."""
+    def get_available_modules(self) -> list[str]:
+        """Scan and cache all available connector modules.
+
+        Returns:
+            List of available modules
+        """
+    def create_bosa_user(self, identifier: str) -> CreateUserResponse:
+        """Create a BOSA User in the scope of BOSA API.
+
+        Args:
+            identifier: BOSA Username
+
+        Returns:
+            BOSA User Data with the secret
+        """
+    def authenticate_bosa_user(self, identifier: str, secret: str) -> BosaToken:
+        """Triggers the authentication of the BOSA User in the scope of BOSA API.
+
+        Args:
+            identifier: BOSA Username
+            secret: BOSA Password
+
+        Returns:
+            BOSA User Token
+        """
+    def initiate_connector_auth(self, app_name: str, token: str, callback_uri: str) -> str:
+        """Triggers the OAuth2 flow for a connector for this API Key and User Token.
+
+        Args:
+            app_name: The name of the app/connector to use
+            token: The BOSA User Token
+            callback_uri: The callback URL to be used for the integration
+
+        Returns:
+            The redirect URL to be used for the integration
+        """
+    def get_user_info(self, token: str) -> BosaUser:
+        """Gets the user information for a given token.
+
+        Args:
+            token: The BOSA User Token
+
+        Returns:
+            BOSA User
+        """
+    def user_has_integration(self, app_name: str, token: str) -> bool:
+        """Checks whether or not a user has an integration for a given app in this client.
+
+        Args:
+            app_name: The name of the app/connector to use
+            token: The BOSA User Token
+
+        Returns:
+            True if the user has an integration for the given app
+        """
+    def remove_integration(self, app_name: str, token: str) -> ActionResult:
+        """Removes a 3rd party integration for a user against a certain client.
+
+        Args:
+            app_name: The name of the app/connector to use
+            token: The BOSA User Token
+
+        Returns:
+            Result that contains an error message (if any), and the success status.
+        """
+    def get_connector(self, app_name: str) -> BosaConnectorModule:
+        """Get or create an instance of a connector module.
+
+        Args:
+            app_name: The name of the app/connector to use
+
+        Returns:
+            BosaConnectorModule: The connector module
+        """
+    def refresh_connector(self, app_name: str) -> None:
+        """Refresh the connector module."""
+    def connect(self, app_name: str) -> Action:
+        """Connect to a specific module and prepare for action execution.
+
+        Creates an Action instance for the specified connector..
+
+        Example:
+            # Create action builders for different connectors
+            github = bosa.connect('github')
+            gdrive = bosa.connect('google_drive') # This is just an example
+
+        Args:
+            app_name: The name of the app/connector to use (eg: 'github', 'google_drive', etc)
+
+        Returns:
+            Action: A new Action instance for the specified connector
+        """
+    def execute(self, app_name: str, action: str, *, max_attempts: int = ..., input_: dict[str, Any] = None, token: str | None = None, headers: dict[str, str] | None = None, timeout: int | None = ..., **kwargs) -> tuple[dict[str, Any] | ConnectorFile, int]:
+        """Execute an action on a specific module and return raw response.
+
+        The method supports both ways of passing parameters:
+        1. As a dictionary: execute(app_name, action, params_dict)
+        2. As keyword arguments: execute(app_name, action, param1=value1, param2=value2)
+
+        Args:
+            app_name: The name of the app/connector to use
+            action: The action to execute
+            input_: Optional input data for the action
+            token: The BOSA User Token
+            headers: Optional headers to include in the request
+            max_attempts: The number of times the request can be retried for. Default is 0 (does not retry). Note that
+                the backoff factor is 2^(N - 1) with the basic value being 1 second (1, 2, 4, 8, 16, 32, ...).
+                Maximum number of retries is 10 with a maximum of 64 seconds per retry.
+            timeout: Optional timeout for the request in seconds. Default is 30 seconds.
+            **kwargs: Optional keyword arguments
+
+        Returns:
+            Tuple of (response, status_code) where response is the API response and status_code is the HTTP status code
+        """
+    def run(self, app_name: str, action: str, *, max_attempts: int = ..., input_: dict[str, Any] = None, token: str | None = None, headers: dict[str, str] | None = None, timeout: int | None = ..., **kwargs) -> ActionResponse:
+        """Execute an action on a specific module and return paginated response.
+
+        The method supports both ways of passing parameters:
+        1. As a dictionary: execute(app_name, action, input_dict)
+        2. As keyword arguments: execute(app_name, action, param1=value1, param2=value2)
+
+        Args:
+            app_name: The name of the app/connector to use
+            action: The action to execute
+            input_: Optional input data for the action
+            token: The BOSA User Token
+            headers: Optional headers to include in the request
+            max_attempts: The number of times the request can be retried for. Default is 0 (does not retry). Note that
+                the backoff factor is 2^(N - 1) with the basic value being 1 second (1, 2, 4, 8, 16, 32, ...).
+                Maximum number of retries is 10 with a maximum of 64 seconds per retry.
+            timeout: Optional timeout for the request in seconds. Default is 30 seconds.
+            **kwargs: Optional keyword arguments
+
+        Returns:
+            ActionResponse: Response wrapper with pagination support
+        """

bosa_connectors/helpers/authenticator.pyi

@@ -0,0 +1,45 @@
+from _typeshed import Incomplete
+from bosa_connectors.auth import ApiKeyAuthenticator as ApiKeyAuthenticator
+from bosa_connectors.models.token import BosaToken as BosaToken
+from bosa_connectors.models.user import BosaUser as BosaUser, CreateUserResponse as CreateUserResponse
+
+class BosaAuthenticator:
+    """Authenticator for BOSA API."""
+    DEFAULT_TIMEOUT: int
+    api_base_url: Incomplete
+    auth_scheme: Incomplete
+    def __init__(self, api_base_url: str = 'https://api.bosa.id', api_key: str = 'bosa') -> None:
+        '''Initialize the BosaAuthenticator with the provided API key.
+
+        Args:
+            api_base_url (str): The base URL for the BOSA API. Defaults to "https://api.bosa.id".
+            api_key (str): The API key for authentication. Defaults to "bosa".
+        '''
+    def register(self, identifier: str) -> CreateUserResponse:
+        """Register a BOSA User in the scope of BOSA API.
+
+        Args:
+            identifier: BOSA Username
+
+        Returns:
+            BOSA User Data with the secret
+        """
+    def authenticate(self, identifier: str, secret: str) -> BosaToken:
+        """Authenticate a BOSA User in the scope of BOSA API.
+
+        Args:
+            identifier: BOSA Username
+            secret: BOSA Password
+
+        Returns:
+            BOSA User Token
+        """
+    def get_user(self, token: str) -> BosaUser:
+        """Get the current user from BOSA API.
+
+        Args:
+            token: The BOSA User Token
+
+        Returns:
+            BOSA User
+        """

bosa_connectors/helpers/integrations.pyi

@@ -0,0 +1,49 @@
+from _typeshed import Incomplete
+from bosa_connectors.auth import ApiKeyAuthenticator as ApiKeyAuthenticator
+from bosa_connectors.models.result import ActionResult as ActionResult
+
+class BosaIntegrationHelper:
+    """Helper class for BOSA API integrations."""
+    OAUTH2_FLOW_ENDPOINT: str
+    INTEGRATION_CHECK_ENDPOINT: str
+    DEFAULT_TIMEOUT: int
+    api_base_url: Incomplete
+    auth_scheme: Incomplete
+    def __init__(self, api_base_url: str = 'https://api.bosa.id', api_key: str = 'bosa') -> None:
+        '''Initializes the BosaIntegrationHelper with the provided API key.
+
+        Args:
+            api_base_url (str): The base URL for the BOSA API. Defaults to "https://api.bosa.id".
+            api_key (str): The API key for authentication. Defaults to "bosa".
+        '''
+    def user_has_integration(self, app_name: str, token: str) -> bool:
+        """Checks whether or not a user has an integration for a given app in this client.
+
+        Args:
+            app_name: The name of the app/connector to use
+            token: The BOSA User Token
+
+        Returns:
+            True if the user has an integration for the given app
+        """
+    def initiate_integration(self, app_name: str, token: str, callback_uri: str) -> str:
+        """Initiates a 3rd party integration for a user against a certain client.
+
+        Args:
+            app_name: The name of the app/connector to use
+            token: The BOSA User Token
+            callback_uri: The callback URL to be used for the integration
+
+        Returns:
+            The integration URL
+        """
+    def remove_integration(self, app_name: str, token: str) -> ActionResult:
+        """Removes a 3rd party integration for a user against a certain client.
+
+        Args:
+            app_name: The name of the app/connector to use
+            token: The BOSA User Token
+
+        Returns:
+            Result that contains an error message (if any), and the success status.
+        """

bosa_connectors/models/action.pyi

@@ -0,0 +1,16 @@
+from bosa_connectors.models.file import ConnectorFile as ConnectorFile
+from pydantic import BaseModel
+from typing import Any
+
+class ActionResponseData(BaseModel):
+    """Response data model with data and meta information."""
+    data: list[Any] | dict[str, Any] | ConnectorFile
+    meta: dict[str, Any] | None
+
+class InitialExecutorRequest(BaseModel):
+    """Initial executor request model."""
+    params: dict[str, Any]
+    headers: dict[str, str] | None
+    max_attempts: int | None
+    token: str | None
+    timeout: int | None

bosa_connectors/models/file.pyi

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+
+class ConnectorFile(BaseModel):
+    """Model for a file in a BOSA Connector request or response."""
+    file: bytes
+    filename: str | None
+    content_type: str | None
+    headers: dict[str, str] | None

bosa_connectors/models/result.pyi

@@ -0,0 +1,6 @@
+from pydantic import BaseModel
+
+class ActionResult(BaseModel):
+    """Model for an action result."""
+    success: bool
+    message: str

bosa_connectors/models/token.pyi

@@ -0,0 +1,10 @@
+from pydantic import BaseModel
+
+class BosaToken(BaseModel):
+    """Model for a BOSA Token."""
+    token: str
+    token_type: str
+    expires_at: str
+    is_revoked: bool
+    user_id: str
+    client_id: str

bosa_connectors/models/user.pyi

@@ -0,0 +1,27 @@
+from pydantic import BaseModel
+from uuid import UUID
+
+class ThirdPartyIntegrationAuthBasic(BaseModel):
+    """Basic model for a third party integration authentication."""
+    id: UUID
+    client_id: UUID
+    user_id: UUID
+    connector: str
+    user_identifier: str
+
+class BosaUser(BaseModel):
+    """Model for a BOSA User."""
+    id: UUID
+    client_id: UUID
+    identifier: str
+    secret_preview: str
+    is_active: bool
+    integrations: list[ThirdPartyIntegrationAuthBasic]
+
+class CreateUserResponse(BaseModel):
+    """Model for a BOSA User creation response."""
+    id: UUID
+    identifier: str
+    secret: str
+    secret_preview: str
+    is_active: bool

bosa_connectors/module.pyi

@@ -0,0 +1,76 @@
+from _typeshed import Incomplete
+from bosa_connectors.auth import BaseAuthenticator as BaseAuthenticator
+from bosa_connectors.models.file import ConnectorFile as ConnectorFile
+from pydantic import BaseModel as BaseModel
+from typing import Any
+
+class BosaConnectorError(Exception):
+    """Base exception for BOSA connector errors."""
+
+class BosaConnectorModule:
+    """Base class for all BOSA connector modules."""
+    app_name: str
+    DEFAULT_TIMEOUT: int
+    MAX_RETRY: int
+    MAX_BACKOFF_SECONDS: int
+    INFO_PATH: str
+    EXCLUDED_ENDPOINTS: Incomplete
+    @staticmethod
+    def is_retryable_error(status_code: int) -> bool:
+        """Check if the status code indicates a retryable error (429 or 5xx).
+
+        Args:
+            status_code: HTTP status code to check
+
+        Returns:
+            bool: True if the error is retryable
+        """
+    api_base_url: Incomplete
+    info_path: Incomplete
+    def __init__(self, app_name: str, api_base_url: str = 'https://api.bosa.id', info_path: str = ...) -> None:
+        """Initialize a new connector module.
+
+        This constructor should only be called by BosaConnector.
+        """
+    def get_actions(self) -> list[tuple[str, str, str]]:
+        """Return list of available actions for this module."""
+    def get_action_parameters(self, action: str):
+        """Get flattened parameter information for an action.
+
+        Args:
+            action: The action endpoint
+
+        Returns:
+            List of parameter info dicts with name, type, and required fields.
+            Nested objects are flattened using dot notation, e.g.:
+                object.attr1, object.attr2, object.attr3.attr21
+        """
+    def validate_request(self, action: str, params: dict[str, Any]) -> tuple[dict[str, Any] | None, dict[str, str]]:
+        """Validate and clean request parameters.
+
+        Args:
+            action: The action endpoint
+            params: Dict of parameter values
+
+        Returns:
+            Tuple of (cleaned_params, error_details) where error_details is empty if validation passed
+        """
+    def execute(self, action: str, max_attempts: int, input_: dict = None, token: str | None = None, authenticator: BaseAuthenticator | None = None, headers: dict[str, str] | None = None, timeout: int | None = ...) -> tuple[dict[str, Any] | ConnectorFile, int]:
+        """Execute an action with validated parameters and return typed response.
+
+        Args:
+            action: The action to execute
+            max_attempts: Maximum number of attempts for failed requests (429 or 5xx errors). Must be at least 1.
+                  Will be capped at MAX_RETRY (10) to prevent excessive retries.
+            input_: Optional dictionary of parameters
+            token: Optional BOSA User Token. If not provided, will use the default token
+            authenticator: Optional authenticator to use for the request
+            headers: Optional headers to include in the request
+
+        The method supports both ways of passing parameters:
+        1. As a dictionary: execute(action, params_dict)
+        2. As keyword arguments: execute(action, param1=value1, param2=value2)
+
+        Raises:
+            ValueError: If action is invalid, parameters are invalid, or max_attempts is less than 1
+        """

bosa_connectors.build/.gitignore

@@ -0,0 +1 @@
+*

bosa_connectors.pyi

@@ -0,0 +1,26 @@
+# This file was generated by Nuitka
+
+# Stubs included by default
+from bosa_connectors.helpers.authenticator import BosaAuthenticator
+from module import BosaConnectorModule
+from connector import BosaConnector
+
+
+__name__ = ...
+
+
+
+# Modules used internally, to allow implicit dependencies to be seen:
+import os
+import typing
+import bosa_connectors.auth.BaseAuthenticator
+import abc
+import logging
+import requests
+import requests.exceptions
+import bosa_connectors.auth.ApiKeyAuthenticator
+import pydantic
+import uuid
+import cgi
+import random
+import time

bosa_connectors_binary-0.0.7.post1.dist-info/METADATA

@@ -0,0 +1,362 @@
+Metadata-Version: 2.1
+Name: bosa-connectors-binary
+Version: 0.0.7.post1
+Summary: BOSA Connectors
+Author: Bosa Engineers
+Author-email: bosa-eng@gdplabs.id
+Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: flag-embedding
+Provides-Extra: langchain-huggingface
+Provides-Extra: semantic-router
+Requires-Dist: pydantic (>=2.9.2,<3.0.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# BOSA API SDK (Bosa Connector)
+
+A Python SDK for seamlessly connecting to APIs that implement BOSA's Plugin Architecture under HTTP Interface. This connector acts as a proxy, simplifying the integration with BOSA-compatible APIs.
+
+## Features
+
+- Simple and intuitive API for connecting to BOSA-compatible services
+- Automatic endpoint discovery and schema validation
+- Built-in authentication support (BOSA API Key and User Token)
+- User management and OAuth2 integration flow support
+- Type-safe parameter validation
+- Flexible parameter passing (dictionary or keyword arguments)
+- Retry support for requests that fail (429 or 5xx)
+- Response fields filtering based on action and output
+
+## Installation
+
+To install the BOSA Connectors, you need to specify the following in your `pyproject.toml` file:
+
+```toml
+[tool.poetry.dependencies]
+bosa-connectors = { git = "ssh://git@github.com/GDP-ADMIN/bosa.git", branch = "bosa-python-connectors-0.0.3", subdirectory = "python/bosa-connectors" }
+```
+
+## Quick Start
+
+Here's a simple example of how to use the BOSA Connector with API key authentication and user token.
+
+### Initialization
+
+Before using the connector, you need to initialize it with your BOSA API base URL and API key.
+
+```python
+from bosa_connectors.connector import BosaConnector
+
+# Initialize the connector
+bosa = BosaConnector(api_base_url="YOUR_BOSA_API_BASE_URL", api_key="YOUR_API_KEY")
+```
+
+### Authentication
+
+After initializing the connector, you can authenticate with your BOSA API key.
+
+```python
+# User token from authentication
+user_token = "Enter your key here from authentication, or refer to User Authentication section below"
+
+# Check if a user has an integration for a connector
+has_integration = bosa.user_has_integration("github", user_token)
+
+if not has_integration:
+    # Initiate the OAuth2 flow for a connector
+    auth_url = bosa.initiate_connector_auth("github", user_token, "https://your-callback-uri.com")
+    # Redirect the user to auth_url to complete authentication, we exit here.
+    print("Integration with GitHub not found.")
+    print(f"Please visit {auth_url} to complete authentication.")
+    exit()
+```
+
+Alternatively, you can authenticate the user first and then use their token:
+
+```python
+user = bosa.authenticate_bosa_user("username", "password")
+
+# Get user token
+user_token = user.token
+```
+
+### Basic Example (Direct Execution)
+
+It is the basic way to execute actions, where you need to provide the connector name, action name, and user token. The response will contain the data and status:
+
+```python
+# Prepare input parameters
+params = {
+    "owner": "gdp-admin",
+    "author": "samuellusandi",
+    "per_page": 1,
+    "sort": "author_date",
+    "created_date_start": "2025-02-01",
+    "created_date_end": "2025-02-02"
+}
+
+# Execute the action with user token
+data, status = bosa.execute("github", "search_commits", token=user_token, max_attempts=1, input_=params)
+
+# Print the result
+print(data)
+print(status)
+```
+
+### Alternative Approach (Fluent Interface)
+
+For more complex scenarios or more control over the execution, you can use the fluent interface. We're recommending this approach if you:
+
+- Need to execute multiple actions with different parameters
+- Expecting list response
+- Need to execute actions in a loop
+
+```python
+# Prepare input parameters
+params = {
+    "owner": "gdp-admin",
+    "author": "samuellusandi",
+    "per_page": 1,
+    "sort": "author_date",
+    "created_date_start": "2025-02-01",
+    "created_date_end": "2025-02-02"
+}
+
+# Create a connector instance to a service
+github = bosa.connect('github')
+
+# Execute actions with fluent interface
+response = github.action('list_pull_requests')\
+    .params(params)\
+    .max_attempts(3)\
+    .token('user-token')\
+    .run()  # Execute and return ActionResponse for advanced data handling
+
+# Get initial data
+initial_data = response.get_data()
+
+# Iterate the following next pages
+while response.has_next():
+    response = response.next_page()
+    data = response.get_data()
+    # Process data here
+    ...
+
+# You can also navigate backwards
+while response.has_prev():
+    response = response.prev_page()
+    data = response.get_data()
+    # Process data here
+    ...
+
+# Execute multiple independent actions using the same connector instance
+commits_response = github.action('list_commits')\
+    .params({
+        'owner': 'GDP-ADMIN',
+        'repo': 'bosa',
+        'page': 1,
+        'per_page': 10
+    })\
+    .token('user-token')\
+    .run()
+```
+
+`run` method also available for direct execution from connector instance, without using fluent interface.
+
+```python
+# Prepare input parameters
+params = {
+    "owner": "gdp-admin",
+    "author": "samuellusandi",
+    "per_page": 1,
+    "sort": "author_date",
+    "created_date_start": "2025-02-01",
+    "created_date_end": "2025-02-02"
+}
+
+# Execute actions with run method
+response = bosa.run('github', 'list_pull_requests', params)
+print(response.get_data())
+```
+
+### Working with Files using ConnectorFile
+
+When working with APIs that require file uploads or return file downloads, use the `ConnectorFile` model:
+
+```python
+from bosa_connectors.models.file import ConnectorFile
+
+# For uploads: Create a ConnectorFile object
+with open("document.pdf", "rb") as f:
+    upload_file = ConnectorFile(
+        file=f.read(),
+        filename="document.pdf",
+        content_type="application/pdf"
+    )
+
+params = {
+  "file": upload_file,
+  "name": "My Document"
+}
+
+# Include in your parameters
+result, status = bosa.execute("google_drive", "upload_file", input_=params)
+
+# For downloads: Check response type
+file_result, status = bosa.execute("google_drive", "download_file", input_={"file_id": "123"})
+if isinstance(file_result, ConnectorFile):
+    # Save to disk
+    with open(file_result.filename or "downloaded_file", "wb") as f:
+        f.write(file_result.file)
+```
+
+## Available Methods
+
+### Connector Instance Methods
+
+The connector instance provides several methods for configuring and executing actions:
+
+- `connect(name)`: Create a connector instance to a service
+- `action(name)`: Specify the action to execute
+- `params(dict)`: Set request parameters (including pagination parameters like page and per_page). Note that params for each plugin and action could be different
+- `token(str)`: Set the BOSA user token
+- `headers(dict)`: Set custom request headers
+- `max_attempts(number)`: Set the maximum number of retry attempts (default: 1)
+  Execution Methods:
+
+- `run()`: Execute and return ActionResponse for advanced data handling
+- `execute()`: Execute and return data and status for basic data handling. The data part of the return value can be a ConnectorFile object when the API returns a non-JSON response (such as a file download).
+
+### Response Handling (ActionResponse)
+
+The ActionResponse class provides methods for handling the response and pagination:
+
+- `get_data()`: Get the current page data (returns the data field from the response). This can return a ConnectorFile object when the API returns a non-JSON response (such as a file download).
+- `get_meta()`: Get the metadata information from the response (e.g., pagination details, total count)
+- `get_status()`: Get the HTTP status code
+- `is_list()`: Check if response is a list
+- `has_next()`: Check if there is a next page
+- `has_prev()`: Check if there is a previous page
+- `next_page()`: Move to and execute next page
+- `prev_page()`: Move to and execute previous page
+- `get_all_items()`: Get all items from all pages (returns a list of objects containing data and meta for each page)
+
+## Data Models
+
+The SDK uses the following data models:
+
+- `ActionResponseData`: Contains the response data structure with `data` (list, object, or ConnectorFile instance) and `meta` (metadata) fields
+- `InitialExecutorRequest`: Stores the initial request parameters used for pagination and subsequent requests
+- `ConnectorFile`: Represents a file in requests and responses with these properties:
+  - `file`: Raw bytes content of the file
+  - `filename`: Optional name of the file
+  - `content_type`: Optional MIME type of the file
+  - `headers`: Optional HTTP headers for the file
+
+## Configuration Parameters
+
+- `api_base_url`: The base URL of your BOSA API endpoint (default: "https://api.bosa.id"). This parameter is extremely important as it determines the URL of the BOSA API you are connecting to, and it will be used to populate the available actions/endpoints and their parameters upon initialization.
+- `api_key`: Your BOSA API key for authentication. This is different from plugin-specific API keys, which are managed separately by the BOSA system.
+
+## Execution Parameters
+
+- `connector`: The name of the connector to use. This parameter is used to determine the connector's available actions and their parameters.
+- `action`: The name of the action to execute. This parameter is automatically populated by the connector based on the available actions and their parameters. The list of available actions per connector can be found in https://api.bosa.id/docs and are populated through https://api.bosa.id/connectors.
+- `max_attempts`: The maximum number of attempts to make the API request. If the request fails, the connector will retry the request up to this number of times. The default value is 1 if not provided.
+  - The retries are handled automatically by the connector, with exponential backoff.
+  - The retries are only done for errors that are considered retryable (429 or 5xx).
+- `input_`: The input parameters for the action. This parameter is a dictionary that contains the parameters for the action. The connector will validate the input parameters against the action's schema.
+  - To filter response fields, simply add the `response_fields` parameter to the input dictionary. This parameter is a list of field names that will be returned in the response. For nested fields, you can use dot notation, e.g. `user.login` will return the following:
+  ```json
+  {
+    "user": {
+      "login": "userlogin"
+    }
+  }
+  ```
+- `token`: Optional BOSA User Token for authenticating requests. When provided, the connector will include this token in the request headers. This is required for user-specific actions or when working with third-party integrations.
+
+## How It Works
+
+1. **Initialization**: When you create a `BosaConnector` instance, and trigger an `execute()`, the connector will first populate and cache the available actions and their parameters. This is done automatically.
+
+2. **Action Discovery**: The connector expects the BOSA API to expose an endpoint that lists all available actions and their parameters. This is handled automatically by BOSA's HTTP Interface.
+
+3. **Execution**: When you call `execute()`, the connector:
+   - Validates your input parameters against the action's schema
+   - Handles authentication
+   - Makes the API request
+   - Returns the formatted response
+
+## Compatibility
+
+While primarily tested with BOSA's HTTP Interface, this connector should theoretically work with any API that implements BOSA's Plugin Architecture, as long as it:
+
+1. Exposes an endpoint listing available actions and their parameters
+2. Follows BOSA's standard HTTP Interface specifications (through the Plugin Architecture)
+   - All actions must be exposed as `POST` endpoints.
+3. Implements the required authentication mechanisms
+
+## Error Handling
+
+The connector includes built-in error handling for:
+
+- Invalid parameters
+- Authentication failures
+- Connection issues
+- API response errors
+
+## User Authentication
+
+The BOSA Connector supports user-based authentication which allows for user-specific actions and third-party integrations:
+
+```python
+# Create a new BOSA user
+user_data = bosa.create_bosa_user("username")
+# Save the secret for later use
+user_secret = user_data.secret
+
+# Authenticate a user and get their token
+token = bosa.authenticate_bosa_user("username", user_secret)
+
+# Get user information
+user_info = bosa.get_user_info(token.token)
+```
+
+## Integration Management
+
+The BOSA Connector provides methods to manage third-party integrations for authenticated users:
+
+```python
+# Check if a user has an integration for a connector
+has_integration = bosa.user_has_integration("github", user_token)
+
+# Initiate the OAuth2 flow for a connector
+auth_url = bosa.initiate_connector_auth("github", user_token, "https://your-callback-uri.com")
+# Redirect the user to auth_url to complete authentication
+
+# Remove an integration
+remove_result = bosa.remove_integration("github", user_token)
+```
+
+## References
+
+Product Requirements Documents(PRD):
+
+- [BOSA Connector - Product Document](https://docs.google.com/document/d/1R6JIGWnKzNg2kRMRSiZ-wwPGe9pOR9rkkEI0Uz-Wtdw/edit?tab=t.y617gs6jfk15#heading=h.uss0d453lcbs)
+
+Architecture Documents:
+
+- [BOSA Connector - Architecture Document](https://docs.google.com/document/d/1HHUBAkbFAM8sM_Dtx6tmoatR1HeuM6VBfsWEjpgVCtg/edit?tab=t.0#heading=h.bj79ljx9eqg8)
+
+Design Documents:
+
+- [BOSA Connector - Design Document](https://docs.google.com/document/d/1PghW7uOJcEbT3WNSlZ0FI99o4y24ys0LCyAG8hg3T9o/edit?tab=t.0#heading=h.bj79ljx9eqg8)
+
+Implementation Documents:
+
+- [BOSA Connector - Implementation Document](https://docs.google.com/document/d/1a8BvggPu5a6PBStgUu2ILse075FjAAgoehUuvxxAajM/edit?tab=t.0#heading=h.bj79ljx9eqg8)
+

bosa_connectors_binary-0.0.7.post1.dist-info/RECORD

@@ -0,0 +1,23 @@
+bosa_connectors/__init__.pyi,sha256=dke2VapQq8neoGW57C-GdrtQCt5-9V51qG33R3C2I0E,279
+bosa_connectors/action.pyi,sha256=zGqRYx9bD7H0V4cMKwF83OLlwuVaDd_Oi4LG7gp7Lfc,3358
+bosa_connectors/action_response.pyi,sha256=8Dj8YZsgvS6hGS-wyb-4VUxZzNLZqisCouYe3V9_DKY,3674
+bosa_connectors/auth/__init__.pyi,sha256=gpzI0J6hSddF7xEZ7j5M1Lcy-MaICCTj5dJFhcaqxXc,177
+bosa_connectors/auth/api_key.pyi,sha256=uFKPef2dqRaQ-2N-3J1kYU3Oh-PsDuh4q2_3jB2KSNY,630
+bosa_connectors/auth/base.pyi,sha256=hjN2euyXyAuFGsxClgIFz_pOy-Q9jV3-vUcinZ-3J-Q,317
+bosa_connectors/connector.pyi,sha256=CARDA0JaXJkwbvHmqfAHq4VMhaQhPxgW6eH7ZmPxi20,7279
+bosa_connectors/helpers/__init__.pyi,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bosa_connectors/helpers/authenticator.pyi,sha256=QwsQ1a0U4Ah2Wg4xnco9Rf2jIsF7EYPvhSyUxxPpStk,1521
+bosa_connectors/helpers/integrations.pyi,sha256=v2PkmsotlT8eo3RAB7hiIC30BN3MN5BO8UjeCRoDu6Q,1961
+bosa_connectors/models/__init__.pyi,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bosa_connectors/models/action.pyi,sha256=Ru4n0xZflIp8Pjoqq-9eJoaDCacrWIA0OvMXmFwOZ7w,531
+bosa_connectors/models/file.pyi,sha256=PBZZkodDAeW1oysX5R5pJ9-d8yd5eKWVccAh1oYcjXM,237
+bosa_connectors/models/result.pyi,sha256=ISmHBFlkyVzyAxeQXwVVEqNXd4SZQI4YV1vd8i8S-NM,136
+bosa_connectors/models/token.pyi,sha256=NN7VfzoudeojK5oWVUmCi4Qo02RUjbveKzDpbh1RrGU,206
+bosa_connectors/models/user.pyi,sha256=KsVrc0MYB1z6fikCv1qSrjnP8ISWChxr9Fx0T0nbsKw,661
+bosa_connectors/module.pyi,sha256=O72bNcKGdfDL5yZzkUOth4BXTDjyUg4YAhYn2TiEgKs,3277
+bosa_connectors.build/.gitignore,sha256=aEiIwOuxfzdCmLZe4oB1JsBmCUxwG8x-u-HBCV9JT8E,1
+bosa_connectors.cpython-312-x86_64-linux-gnu.so,sha256=02iqwhH44PM-pDrW3sFZeETW3mPDEW_WiQ_f4E7ZZdg,1348488
+bosa_connectors.pyi,sha256=GpJC_3rac6Hzg8IhYq8D-OVxsnF2zP9XMrf34YtWOK0,549
+bosa_connectors_binary-0.0.7.post1.dist-info/METADATA,sha256=5pWs9HLFBL1Z8o7UNlV_zae-5AZPhra_9cV069DeYFg,13813
+bosa_connectors_binary-0.0.7.post1.dist-info/WHEEL,sha256=mNY4pwQL4AOAoPmLYEQs2SSpMIbATFeiJFktRD5iKkY,110
+bosa_connectors_binary-0.0.7.post1.dist-info/RECORD,,

bosa_connectors_binary-0.0.7.post1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: false
+Tag: cp312-cp312-manylinux_2_31_x86_64