Lumos Connector SDK Types

Common errors

• ModuleNotFoundError: No module named 'connector_sdk.types.account'

  cause The specific type or module was not found, possibly due to an incorrect import path, a missing dependency (`connector-py`), or an outdated version of `connector-sdk-types`.
  fix Verify the exact import path against the official Lumos Connector SDK documentation or the generated code. Ensure that `connector-py` is installed and that `connector-sdk-types` is a compatible version with the `connector-py` library you are using. Update both packages if necessary.

• TypeError: Argument 'identity' has an invalid type

  cause A mismatch between the data being processed or returned by your connector and the expected type hints defined in `connector-sdk-types`. This often occurs when API responses or internal data structures diverge from the generated types.
  fix Review the Lumos API documentation for the specific endpoint or data model you are interacting with. Adjust your connector's logic to correctly map data to the expected types, or update `connector-sdk-types` to a version compatible with the current API schema. Ensure consistent use of type hints throughout your connector implementation.

• Connection Error - Connection Reset by Peer

  cause This error typically indicates an underlying network issue, firewall blocking, or premature closing of the connection by the remote server. It's often not directly a `connector-sdk-types` issue but rather related to the network environment or the target API.
  fix For on-premise connectors, check network connectivity, firewall rules, and proxy settings. For cloud-hosted connectors, review security group configurations. Implement robust retry mechanisms with exponential backoff in your API client code. Investigate the logs of the target API for rejection reasons.

Warnings

• breaking Major version changes in the underlying Lumos Connector SDK (`connector-py`) or the Lumos API may introduce breaking changes to the generated types in `connector-sdk-types`. This could require updates to your custom connector's code.
  Fix: Refer to the Lumos Connector SDK's `CHANGELOG.md` or official documentation when upgrading to new major versions. Update your connector's code to align with any changed type definitions or API contracts. Pin `connector-py` and `connector-sdk-types` to specific versions in your `pyproject.toml` or `requirements.txt`.
• gotcha It is crucial to explicitly pin the versions of both `connector-py` and `connector-sdk-types` in your project's dependency file (`pyproject.toml` or `requirements.txt`). Failing to do so can lead to unexpected behavior or build failures if incompatible versions are automatically installed.
  Fix: Always specify exact versions (e.g., `connector-py==X.Y.Z`, `connector-sdk-types==A.B.C`) or use compatible range operators (e.g., `~=X.Y`) to ensure stable and reproducible builds across development and deployment environments.
• gotcha The Lumos Connector SDK, and thus its generated types, requires Python 3.10 or higher. Using older Python versions can lead to syntax errors, `ModuleNotFoundError` for modern typing features, or other runtime issues.
  Fix: Ensure your development and deployment environments use Python 3.10 or a newer supported version. Update your `pyproject.toml` or `setup.py` to specify `requires-python = '>=3.10'`.

Install

• pip install connector-sdk-types Install stable version

Imports

• ConnectorSettings

  from connector_sdk.settings import ConnectorSettings

  Commonly imported base class for defining connector configuration.
• Account

  from connector_sdk.models import Account

  Example of a data model type, representing a user account in the connected system.
• AuthType

  from connector_sdk.enums import AuthType

  Example of an enum type for authentication methods.

Quickstart

This quickstart demonstrates how to define custom connector settings and data models using the types provided by `connector-sdk-types`. In a typical Lumos Connector SDK project (built with `connector-py`), these types would be imported and utilized within the `settings.py`, `models.py`, and capability implementation files. It shows how to represent connector configuration and fetched user accounts using the SDK's type-safe structures.

import os
from typing import List, Dict, Any
from connector_sdk.settings import ConnectorSettings
from connector_sdk.models import Account, Identity

# This is a simplified example. In a real scenario, you'd scaffold with 'connector-py'
# and implement capabilities. The types are used within that implementation.

# Define a custom settings model using the generated types
class MyConnectorSettings(ConnectorSettings):
    api_key: str = os.environ.get('MY_CONNECTOR_API_KEY', '')
    base_url: str = os.environ.get('MY_CONNECTOR_BASE_URL', 'https://api.example.com')

# A hypothetical function demonstrating usage of types
def fetch_accounts(settings: MyConnectorSettings) -> List[Account]:
    print(f"Fetching accounts from {settings.base_url} with key: {settings.api_key[:5]}...")
    # In a real connector, this would make API calls and map responses to Account objects
    mock_accounts: List[Account] = [
        Account(identity=Identity(id='user1', username='john.doe', email='john.doe@example.com'), 
                attributes={'firstName': 'John', 'lastName': 'Doe'}),
        Account(identity=Identity(id='user2', username='jane.smith', email='jane.smith@example.com'), 
                attributes={'firstName': 'Jane', 'lastName': 'Smith'})
    ]
    return mock_accounts

if __name__ == '__main__':
    # Example usage (usually managed by the connector-py framework)
    settings_instance = MyConnectorSettings()
    if not settings_instance.api_key:
        print("Warning: MY_CONNECTOR_API_KEY not set in environment. Using empty string.")

    accounts = fetch_accounts(settings_instance)
    print(f"Fetched {len(accounts)} accounts:")
    for account in accounts:
        print(f" - ID: {account.identity.id}, Username: {account.identity.username}, Email: {account.identity.email}")