Connections

Learn how to connect with third-party tools and services in your BDK project.

Implementing Connections

To implement an external connection, define a Python function in your Book class and decorate it with the @connect decorator. This function will act as the connection handler. For OAuth-based connections, refer to OAuth 2.0 Implementation.

Multiple Connections

You can define multiple connections within a Book, each with its own handler method. Use the noun_phrase keyword argument in the @connect decorator to assign a unique label to each connection and differentiate between authentication methods.

Method Docstrings

In your method docstring, include the following sections in addition to a brief summary:

1. Arguments: Specify the function's parameters.

2. Labels: Describe the arguments used for the connection (e.g., API key, credentials). These labels will appear in the UI.

Example

This is an example implementation of connecting to the OpenWeather API using an API key:

@connect(noun_phrase="api keys")
def connect(self, api_key: str):
  """
  Authenticate to Open Weather API using the specified API key. You can obtain your own API key by visiting
  Open Weather's website at https://openweathermap.org/appid.

  Arguments:
      api_key: The API key to be used for connecting

  Labels:
      api_key: API Key
  """
  api_key = os.getenv("API_KEY", api_key)
  test_url = f"{self._base_url}?appid={api_key}&q=London"
  response = requests.get(test_url, timeout=self._timeout)
  if response.status_code == 401:
      response_data = response.json()
      if "Invalid API key" in response_data.get("message", ""):
          raise ValueError("Invalid API key")

  self._api_key = api_key

---

OAuth 2.0 Implementation

Open Authorization 2.0 is a widely used authorization framework that provides secure and controlled access to third-party services. BDK supports authentication for Microsoft and Google services.

To implement this authentication flow in your book, the @connect decorator is not required. Instead, apply the @oauth decorator to a Python class and use the @oauthtoken decorator on a handler function to manage tokens.

Example

In this example, the @oauth decorator configures the OAuth2 flow for Microsoft, specifying endpoints and required scopes. The @oauthtoken decorator marks the handle_token method, which processes and stores the access token.

@oauth(
  id="oauth",
  provider=OAuthProvider.MICROSOFT,
  flows=[OAuthFlow.AUTHORIZATION_CODE],
  authorize_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize",
  token_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token",
  scopes=[
    "https://graph.microsoft.com/Files.ReadWrite",
    "https://graph.microsoft.com/Sites.ReadWrite.All",
    "https://graph.microsoft.com/Mail.ReadWrite",
  ],
)
@book(name="MicrosoftBook")
class BaseMicrosoftBook:
  """
  Base class for all Microsoft Books.
  """
  ...
  ...
  ...

  @oauthtoken
  def handle_token(self, access_token: str, expires_in: Optional[int] = None) -> None:
    """
    Handles the OAuth token.
    """
    self._acquired_token = AcquiredToken(access_token, expires_in or 3600)