Integrations — Google Calendar & Keywords

The integrations package provides external service integrations: Google Calendar sync and keyword automation.

Google Calendar

Account Manager

class jot.integrations.gcal.account_manager.GoogleCalendarAccountManager

Bases: object

Manage multiple Google Calendar accounts

ACCOUNTS_DIR = PosixPath('/home/runner/.jot/gcal-accounts')

__init__()

Initialize account manager

discover_accounts()

Discover all configured Google Calendar accounts

Returns:

Account names (subdirectories with credentials.json)

Return type:

list

get_account_path(account_name)

Get path to account directory

Parameters:

account_name – Name of the account

Returns:

Path to account directory

Return type:

Path

account_exists(account_name)

Check if account is configured

Parameters:

account_name – Name of the account

Returns:

True if account directory exists with credentials.json

Return type:

bool

create_account(account_name)

Create new account directory

Parameters:

account_name – Name of the account

Returns:

Path to created account directory

Return type:

Path

Authentication

class jot.integrations.gcal.auth.GoogleCalendarAuth(account_name='default')

Bases: object

Handle Google Calendar OAuth authentication

SCOPES = ['https://www.googleapis.com/auth/calendar']

__init__(account_name='default')

Initialize with account-specific credentials directory

Parameters:

account_name – Name of the Google Calendar account (default: ‘default’)

get_credentials()

Get or refresh OAuth credentials

Returns:

Credentials object

Raises:

FileNotFoundError – If credentials.json not found

get_service()

Build and return Google Calendar service

Returns:

Google Calendar API service object

Events

Google Calendar event management

jot.integrations.gcal.events.create_gcal_event(service, task_text, start_time=None, duration_minutes=15, description=None)

Create a Google Calendar event from task text

Parameters:

• service – Google Calendar API service object

• task_text – Task text to use as event summary

• start_time – Optional timezone-aware datetime for event start (default: now rounded to 15 min)

• duration_minutes – Event duration in minutes (default: 15)

• description – Optional event description (default: ‘Created from jot task’)

Returns:

Event link (htmlLink) or None if failed

Raises:

HttpError – If API call fails

jot.integrations.gcal.events.fetch_gcal_events(service, date=None, days=1, direction='future')

Fetch events from Google Calendar for a specific date or date range

Parameters:

• service – Google Calendar API service object

• date – datetime.date object (default: today)

• days – Number of days to fetch events for (1-7)

• direction – ‘future’ for upcoming days, ‘past’ for previous days

Returns:

str, ‘start’: datetime/None, ‘end’: datetime/None, ‘all_day’: bool, ‘date’: date, ‘description’: str} Returns empty list if no events found

Return type:

List of dicts with {‘summary’

Raises:

HttpError – If API call fails

Keywords

KeywordHandler

class jot.integrations.keywords.handler.KeywordHandler(project_registry=None)

Bases: ConfigMixin, HandlersMixin

Manages keyword detection and action routing for task automation

MAX_KEYWORD_LENGTH = 50

__init__(project_registry=None)

Initialize keyword handler with built-in handlers.

Parameters:

project_registry – Optional ProjectRegistry for project name routing

extract_keyword(task_text)

Extract keyword from task text if present.

Keyword format: “keyword: rest of task text” - First word must end with ‘:’ - Keyword must be alphanumeric + hyphens/underscores - Case-insensitive (normalized to lowercase) - Project names are checked first before treating as action keyword

Returns:

(keyword, original_text, project_name) or (None, text, None)

Return type:

tuple

register(keyword, handler_func, auto_trigger=False, description='')

Register a keyword action handler.

handle(keyword, task)

Execute handler for detected keyword.

Returns:

Result message from handler, or None if not registered

Return type:

str

get_config(keyword)

Get configuration for a keyword

list_keywords()

List all registered keywords with their configurations

Config Mixin

Config mixin — load and create keyword configuration.

class jot.integrations.keywords._config_mixin.ConfigMixin

Bases: object

Keyword configuration file management.

Handlers Mixin

Handlers mixin — built-in keyword action handlers.

class jot.integrations.keywords._handlers_mixin.HandlersMixin

Bases: object

Built-in keyword action handlers.