AT Protocol Calendar Import#

A Python library and CLI tool for importing calendar events from external providers (Google, Outlook, Apple, ICS) into the AT Protocol.

Features#

• 📅 Multiple Calendar Sources: Google Calendar, Microsoft Outlook, Apple Calendar (CalDAV), ICS files/URLs
• 🔄 AT Protocol Integration: Publish events directly to AT Protocol/Bluesky
• 🌐 REST API: FastAPI-based server for integration
• 💻 CLI Tool: Command-line interface for batch imports
• 🔍 Smart Event Detection: Automatically detects virtual/hybrid/in-person events
• 🚀 Async Support: Built with modern async/await patterns
• 🛡️ Type Safety: Full type hints with Pydantic models

Quick Start#

Installation#

# Basic installation
pip install -e .

# With API server support
pip install -e ".[api]"

# With development tools
pip install -e ".[dev]"

CLI Usage#

# Import from ICS URL
atproto-calendar import --provider ics --source "https://calendar.example.com/events.ics"

# Import from Google Calendar (requires OAuth setup)
atproto-calendar import --provider google --credentials-file google_creds.json

# Import and publish to AT Protocol
atproto-calendar import \
  --provider ics \
  --source "events.ics" \
  --publish \
  --handle "user.bsky.social" \
  --password "app-password"

API Server#

# Start the API server
python -m atproto_calendar.api.server

# Make import request
curl -X POST "http://localhost:8000/import" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "ics",
    "source": "https://calendar.example.com/events.ics"
  }'

Python API#

from atproto_calendar.import.ics import ICSImporter
from atproto_calendar.transform.converter import EventConverter

# Import events
importer = ICSImporter("https://calendar.example.com/events.ics")
external_events = await importer.import_events()

# Convert to AT Protocol format
at_events = [
    EventConverter.convert_external_event(event)
    for event in external_events
]

Supported Calendar Providers#

Configuration#

The application can be configured via environment variables or configuration files:

# AT Protocol settings
ATPROTO_HANDLE=user.bsky.social
ATPROTO_PASSWORD=app-password
ATPROTO_PDS_URL=https://bsky.social

# API server settings
API_HOST=0.0.0.0
API_PORT=8000
DEBUG=false

# Optional: Database settings
REDIS_URL=redis://localhost:6379
POSTGRES_URL=postgresql://user:pass@localhost/db

Development#

Setup Development Environment#

# Clone the repository
git clone <repository-url>
cd atproto-calendar-import/PYTHON

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests#

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_import/test_ics.py

Code Quality#

# Format code
black . && isort .

# Lint code
flake8 . && mypy .

# Run pre-commit checks
pre-commit run --all-files

Architecture#

The project follows a modular architecture:

• Import Layer: Handles importing from various calendar providers
• Transform Layer: Converts external events to AT Protocol format
• AT Protocol Layer: Manages authentication and publishing to AT Protocol
• API Layer: Provides REST endpoints for integration
• CLI Layer: Command-line interface for batch operations

Contributing#

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License#

This project is licensed under the MIT License - see the LICENSE file for details.

Support#

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions