Personal Planner API

A FastAPI backend for a personal planner application with calendar integration capabilities.

Setup

Step 1: Install Python from Microsoft Store

1. Open Microsoft Store (search for it in Start menu)
2. Search for "Python 3.12" or "Python 3.11"
3. Click on the Python app published by Python Software Foundation
4. Click "Install" or "Get"
5. Wait for installation to complete

Step 2: Verify Installation

Open PowerShell and verify Python is installed:

python --version

You should see something like Python 3.12.x or Python 3.11.x

Step 3: Install Dependencies

Navigate to your project folder and install the required packages:

cd path\to\plannerNew
python -m pip install -r requirements.txt

Step 4: Run the Server

Start the FastAPI server:

python -m uvicorn main:app --reload

You should see:

INFO:     Uvicorn running on http://127.0.0.1:8000

The API will be available at http://localhost:8000

API Endpoints

• POST /free-slots - Find free time slots within a date range
• POST /create-event - Create a new calendar event
• POST /upsert-event - Upsert an event: update if match found, create if not
• GET /day-plan - Get all events for a specific day

Testing the Upsert Event Endpoint

The /upsert-event endpoint prevents duplicate events by matching existing events and updating them instead of creating duplicates.

Example: Create then Update Gym Event

Step 1: Create "Gym 14–16"

curl -X POST "http://localhost:8000/upsert-event" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Gym",
    "start_time": "2024-01-15T14:00:00+00:00",
    "end_time": "2024-01-15T16:00:00+00:00"
  }'

Step 2: Update to "Gym 14–15" (should update, not duplicate)

curl -X POST "http://localhost:8000/upsert-event" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Gym",
    "start_time": "2024-01-15T14:00:00+00:00",
    "end_time": "2024-01-15T15:00:00+00:00"
  }'

The second call will update the existing event (change end time from 16:00 to 15:00) instead of creating a duplicate event.

Matching Logic

The endpoint matches events using:

1. Priority 1: Events with planner_uid in extendedProperties.private or description
2. Priority 2: Title similarity + time overlap (within ±match_window_minutes, default 180 minutes)

Matching parameters:

• match_window_minutes (default: 180) - Time window for matching events
• allow_title_fuzzy_match (default: true) - Enable title-based matching

API Documentation

Interactive API documentation is available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Railway Deployment

Prerequisites

1. Google OAuth Credentials: You need OAuth 2.0 client credentials from Google Cloud Console
2. Refresh Token: Generate a refresh token for your OAuth client

Step 1: Get OAuth Client JSON

1. Go to Google Cloud Console
2. Create or select an OAuth 2.0 Client ID (Desktop application type)
3. Download the credentials JSON file — it contains the installed client with client_id, client_secret, and the standard Google OAuth endpoints. Keep this file out of git.

Step 2: Generate Refresh Token

Option A: Using Local Development

1. Run the app locally with credentials.json in the project root
2. Complete the OAuth flow (browser will open)
3. After authentication, token.json will be created
4. Extract the refresh_token value from token.json

Option B: Using OAuth Playground

1. Go to OAuth 2.0 Playground
2. Click the gear icon (⚙️) → Check "Use your own OAuth credentials"
3. Enter your Client ID and Client Secret
4. Select "Calendar API v3" scopes
5. Click "Authorize APIs" and complete the flow
6. Click "Exchange authorization code for tokens"
7. Copy the refresh_token from the response

Step 3: Set Railway Environment Variables

In your Railway project, go to Variables and add:

1. ENV — set to production.
2. GOOGLE_OAUTH_CLIENT_JSON — the full OAuth client JSON from your credentials file, pasted as a single line (no line breaks).
3. GOOGLE_REFRESH_TOKEN — the refresh token string obtained from the OAuth flow.

Step 4: Deploy

1. Connect your GitHub repository to Railway
2. Railway will automatically detect the Procfile and deploy
3. The app will use environment variables for authentication (no local files needed)

Troubleshooting Railway Deployment

• "GOOGLE_OAUTH_CLIENT_JSON environment variable is required"

  • Make sure ENV=production is set
  • Verify GOOGLE_OAUTH_CLIENT_JSON contains valid JSON (check for proper escaping)

• "GOOGLE_REFRESH_TOKEN environment variable is required"

  • Verify the refresh token is correctly set
  • Make sure there are no extra spaces or quotes

• "Failed to refresh token"

  • The refresh token may have expired or been revoked
  • Generate a new refresh token and update the Railway variable

Local Development

For local development, the app uses credentials.json and token.json files:

1. Place credentials.json in the project root (not committed to git)
2. Run the app - it will open a browser for OAuth consent on first run
3. token.json will be automatically created and used for subsequent runs

Note: Do NOT set ENV=production when running locally, or the app will expect environment variables instead of local files.

Telegram Webhook Setup

The API includes a Telegram webhook endpoint at POST /telegram/webhook for receiving bot updates.

Environment Variables

Set these environment variables (for Railway, add them in the Variables section):

1. TELEGRAM_BOT_TOKEN — your Telegram bot token (get one from @BotFather).
2. TELEGRAM_WEBHOOK_SECRET — a random string of your choice used to authenticate incoming webhook calls.

Setting Up the Webhook

After deploying to Railway (or running locally with a public URL), set the webhook URL via the Telegram Bot API:

curl -X POST "https://api.telegram.org/bot<your_bot_token>/setWebhook" \
  -d "url=https://<your_railway_url>/telegram/webhook?secret=<your_webhook_secret>"

Substitute the three angle-bracketed placeholders with your own values. <your_webhook_secret> must match the TELEGRAM_WEBHOOK_SECRET env var.

Testing

1. Send /start to your bot in Telegram
2. The bot should reply with a greeting message
3. Check Railway logs to verify the webhook is receiving updates