feat: Bring Python project to feature parity with Node.js version

This commit brings the Python AppLink starter project to full feature parity with the Node.js version, including a more robust application structure, comprehensive API functionality, and complete test coverage.

### Major Changes

- **Restructured Application:**
  - Migrated from a single `main.py` file to a scalable, modular structure using FastAPI's `APIRouter`.
  - Code is now organized into `app/routers` for clear separation of concerns.
  - Updated `Procfile` to reflect the new application entry point (`app.main:app`).

- **Implemented Full API Feature Set:**
  - Added `/unitofwork` endpoint to demonstrate creating multiple related records in Salesforce using the Unit of Work pattern.
  - Added `/handleDataCloudDataChangeEvent` endpoint to serve as a webhook for Data Cloud Data Actions.
  - Added a standard `/health` check endpoint.
  - Configured FastAPI to serve interactive API documentation via Swagger UI at `/docs`, using the existing `api-spec.yaml`.

- **Added Robust Testing:**
  - Created a comprehensive test suite using `pytest`.
  - Implemented a robust testing strategy using `conftest.py` to mock the `heroku_applink` SDK, resolving complex dependency and plugin conflicts.
  - Added tests for all API endpoints, including happy paths and error conditions.
  - Achieved 100% test coverage for all application logic.

- **Improved Developer Experience:**
  - Created `bin/invoke.py`, a Python-based equivalent of the Node.js `invoke.sh` script, for easy local testing with Salesforce context headers.
  - Completely rewrote the `README.md` to be as comprehensive as the Node.js version, with updated instructions for setup, local development, testing, and manual deployment.
  - Added a `pytest.ini` file to standardize test execution.
  - Refined `requirements.txt` to ensure stable dependency resolution.

- **Enhanced Code Quality and Documentation:**
  - Audited and refactored the entire codebase to adhere to Python best practices.
  - Added comprehensive Sphinx-style docstrings to all modules and functions.
  - Implemented full type hinting across the application for improved clarity and static analysis.
  - Introduced Pydantic response models for better data validation and more accurate API documentation.
  - Fixed Pydantic deprecation warnings by updating `Field` definitions.

### Motivation

The goal was to elevate the Python starter project from a minimal example to a feature-complete and robust template that fully demonstrates the power of Heroku AppLink. This provides a much stronger foundation for developers looking to build Salesforce-integrated applications in Python, mirroring the quality and completeness of the Node.js template.

Author: kenwalger

.DS_Store

@@ -2,3 +2,5 @@ __pycache__/
 .pytest_cache/
 .venv/
 venv/
+htmlcov/
+commit-message.txt

.coverage

@@ -1 +1 @@
-web: export APP_PORT=3000 && heroku-applink-service-mesh-latest-amd64 --port $PORT -- uvicorn main:app --port=$APP_PORT
+web: uvicorn app.main:app --host 0.0.0.0 --port $PORT

.gitignore

@@ -1,55 +1,186 @@
-# FastAPI Heroku AppLink Integration
+# Heroku AppLink Python App Template
 
-This is a basic FastAPI application that demonstrates integration with Heroku AppLink.
+[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://www.heroku.com/deploy?template=https://github.com/heroku-reference-apps/applink-getting-started-python)
 
-## Local Setup
+The Heroku AppLink Python app template is a [FastAPI](https://fastapi.tiangolo.com/) web application that demonstrates how to build APIs for Salesforce integration using Heroku AppLink. This template includes authentication, authorization, and API specifications for seamless integration with Salesforce, Data Cloud, and Agentforce.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Local Development](#local-development)
+- [Testing with invoke.py](#testing-with-invokepy)
+- [Running Automated Tests](#running-automated-tests)
+- [Manual Heroku Deployment](#manual-heroku-deployment)
+- [Heroku AppLink Setup](#heroku-applink-setup)
+- [Project Structure](#project-structure)
+- [API Documentation](#api-documentation)
+- [Additional Resources](#additional-resources)
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.8+
+- `pip` for package management
+- Git
+- Heroku CLI (for deployment)
+- Salesforce org (for AppLink integration)
+
+### Deploy to Heroku (One-Click)
+
+Click the Deploy button above to deploy this app directly to Heroku with the AppLink add-on pre-configured.
+
+## Local Development
+
+### 1. Clone and Install
 
-1. Install the required dependencies:
 ```bash
+git clone https://github.com/heroku-reference-apps/applink-getting-started-python.git
+cd applink-getting-started-python
+python -m venv venv
+source venv/bin/activate
 pip install -r requirements.txt
 ```
 
-2. Run the application:
+### 2. Start the Development Server
+
 ```bash
-uvicorn main:app --reload
+uvicorn app.main:app --reload
 ```
 
-The application will be available at `http://localhost:8000`
+Your app will be available at `http://localhost:8000`.
+
+### 3. API Endpoints
+
+- **GET /accounts** - Retrieve Salesforce accounts from the invoking org.
+- **POST /unitofwork** - Create a unit of work for Salesforce.
+- **POST /handleDataCloudDataChangeEvent** - Handle a Salesforce Data Cloud Change Event.
+- **GET /docs** - Interactive Swagger UI for API documentation.
+- **GET /health** - Health check endpoint.
+
+### 4. View API Documentation
+
+Visit `http://localhost:8000/docs` to explore the interactive API documentation powered by Swagger UI.
 
-## Heroku Deployment
+## Testing with invoke.py
+
+The `bin/invoke.py` script allows you to test your locally running app with proper Salesforce client context headers.
+
+### Usage
 
-1. Make sure you have the Heroku CLI installed and are logged in:
 ```bash
-heroku login
+./bin/invoke.py ORG_DOMAIN ACCESS_TOKEN ORG_ID USER_ID [METHOD] [API_PATH] [--data DATA]
 ```
 
-2. Create a new Heroku app:
+### Parameters
+
+- **ORG_DOMAIN**: Your Salesforce org domain (e.g., `mycompany.my.salesforce.com`)
+- **ACCESS_TOKEN**: Valid Salesforce access token
+- **ORG_ID**: Salesforce organization ID (15 or 18 characters)
+- **USER_ID**: Salesforce user ID (15 or 18 characters)
+- **METHOD**: HTTP method (default: GET)
+- **API_PATH**: API endpoint path (default: /accounts)
+- **--data**: JSON data for POST/PUT requests (as a string)
+
+### Examples
+
 ```bash
+# Test the accounts endpoint
+./bin/invoke.py mycompany.my.salesforce.com TOKEN_123 00D123456789ABC 005123456789ABC
+
+# Test with POST data
+./bin/invoke.py mycompany.my.salesforce.com TOKEN_123 00D123456789ABC 005123456789ABC POST /unitofwork --data '{"data":{"accountName":"Test Account", "lastName":"Test", "subject":"Test Case"}}'
+
+# Test custom endpoint
+./bin/invoke.py mycompany.my.salesforce.com TOKEN_123 00D123456789ABC 005123456789ABC GET /health
+```
+
+### Getting Salesforce Credentials
+
+To get the required Salesforce credentials for testing:
+
+1.  **Access Token**: Use Salesforce CLI to generate a session token (`sf org display --target-org <alias> --json | jq .result.accessToken -r`).
+2.  **Org ID**: Found in Setup → Company Information or by running `sf org display --target-org <alias> --json | jq .result.id -r`.
+3.  **User ID**: Found in your user profile or Setup → Users or by running `sf org display --target-org <alias> --json | jq .result.userId -r`.
+
+## Running Automated Tests
+
+This project uses `pytest` for unit testing. To run the tests:
+
+```bash
+pytest
+```
+
+## Manual Heroku Deployment
+
+### 1. Prerequisites
+
+- [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) installed
+- Git repository initialized
+- Heroku account with billing enabled (for add-ons)
+
+### 2. Create Heroku App
+
+```bash
+# Create a new Heroku app
 heroku create your-app-name
+
+# Or let Heroku generate a name
+heroku create
 ```
 
-3. Deploy to Heroku:
+### 3. Add Required Buildpacks
+
+The app requires two buildpacks in the correct order:
+
 ```bash
-git add .
-git commit -m "Initial commit"
-git push heroku main
+# Add the AppLink Service Mesh buildpack first
+heroku buildpacks:add heroku/heroku-applink-service-mesh
+
+# Add the Python buildpack second
+heroku buildpacks:add heroku/python
 ```
 
-4. Configure Heroku AppLink:
+### 4. Provision the AppLink Add-on
+
 ```bash
+# Provision the Heroku AppLink add-on
 heroku addons:create heroku-applink
+
+# Set the required HEROKU_APP_ID config var
+heroku config:set HEROKU_APP_ID="$(heroku apps:info --json | jq -r '.app.id')"
 ```
 
-5. Open your application:
+### 5. Deploy the Application
+
 ```bash
+# Deploy to Heroku
+git push heroku main
+
+# Check deployment status
+heroku ps:scale web=1
 heroku open
 ```
 
-## Endpoints
+### 6. Verify Deployment
+
+```bash
+# Check app logs
+heroku logs --tail
+```
+
+## Heroku AppLink Setup
+
+(Instructions for `heroku salesforce:connect`, `heroku salesforce:authorizations:add`, and `heroku salesforce:publish` are identical to the Node.js version and can be referenced from the official documentation.)
+
+## Additional Resources
+
+### Documentation
 
-- `GET /`: Returns a simple root page
-- `GET /accounts`: Queries accounts using Heroku AppLink Data API
+- [Getting Started with Heroku AppLink](https://devcenter.heroku.com/articles/getting-started-heroku-applink)
+- [Heroku AppLink CLI Plugin](https://devcenter.heroku.com/articles/heroku-applink-cli)
+- [FastAPI Documentation](https://fastapi.tiangolo.com/)
 
-## Note
+---
 
-This application requires proper Heroku AppLink configuration to work with the Data API. Make sure you have the necessary credentials and configuration set up in your environment. 
+**Note**: This template is designed for educational purposes and as a starting point for building Salesforce-integrated applications. For production use, ensure proper error handling, security measures, and testing practices are implemented.

Procfile

@@ -0,0 +1,41 @@
+"""
+This module is the main entry point for the AppLink Python Starter aplication.
+
+It initializes the FastAPI application, loads the OpenAPI specification,
+and includes the API routers.
+"""
+import heroku_applink as sdk
+from fastapi import FastAPI, Response
+from typing import Dict, Any
+
+from .routers import accounts, unitofwork, datacloud
+
+import yaml
+
+config = sdk.Config()
+
+app = FastAPI(
+    title="AppLink Python Starter",
+    description="A starter project for building Salesforce-integrated applications with Heroku AppLink.",
+    version="1.0.0"
+)
+
+with open("api-spec.yaml", "r") as f:
+    openapi_schema = yaml.safe_load(f)
+app.openapi_schema = openapi_schema
+
+app.add_middleware(sdk.IntegrationAsgiMiddleware, config=config)
+
+app.include_router(accounts.router)
+app.include_router(unitofwork.router)
+app.include_router(datacloud.router)
+
+@app.get("/health", summary="Health check endpoint")
+def get_health() -> Dict[str, str]:
+    """
+    A simple health check endpoint.
+
+    :return: A dictionary with a status of "ok".
+    :rtype: Dict[str, str]
+    """
+    return {"status": "ok"}

README.md

@@ -0,0 +1,52 @@
+"""
+This router handles the /accounts endpoint.
+"""
+import heroku_applink as sdk
+from fastapi import APIRouter
+from pydantic import BaseModel
+from typing import List, Dict, Any
+
+router = APIRouter(
+    prefix="/accounts",
+    tags=["accounts"],
+)
+
+class Account(BaseModel):
+    id: str
+    name: str
+
+async def _query_accounts(data_api: Any) -> Any:
+    """
+    Private helper function to query for accounts.
+
+    :param data_api: The Data API client from the Heroku AppLink context.
+    :type data_api: Any
+    :return: The result of the SOQL query.
+    :rtype: Any
+    """
+    query = "SELECT Id, Name FROM Account"
+    result = await data_api.query(query)
+    # The print statement is for debugging and can be removed in production.
+    for record in result.records:
+        print("===== account record", record)
+    return result
+
+@router.get("/", response_model=List[Account])
+async def get_accounts() -> List[Account]:
+    """
+    Queries for and then returns all Accounts in the invoking org.
+
+    This endpoint demonstrates how to use the Heroku AppLink SDK to perform
+    a simple SOQL query against the invoking Salesforce organization.
+
+    :return: A list of Account objects.
+    :rtype: List[Account]
+    """
+    data_api = sdk.get_client_context().data_api
+    result = await _query_accounts(data_api)
+    
+    accounts = [
+        Account(id=record.fields["Id"], name=record.fields["Name"])
+        for record in result.records
+    ]
+    return accounts

app/main.py

@@ -0,0 +1,76 @@
+"""
+This router handles the /handleDataCloudDataChangeEvent endpoint, which acts as a
+webhook for Salesforce Data Cloud Data Action events.
+"""
+from fastapi import APIRouter, Request, Response
+from pydantic import BaseModel, Field
+from typing import List, Dict, Any, Optional
+import heroku_applink as sdk
+import os
+
+router = APIRouter(
+    prefix="/handleDataCloudDataChangeEvent",
+    tags=["datacloud"],
+)
+
+class DataCloudEvent(BaseModel):
+    ActionDeveloperName: str
+    EventType: str
+    EventPrompt: str
+    SourceObjectDeveloperName: str
+    EventPublishDateTime: str
+    PayloadCurrentValue: Dict[str, Any]
+
+class DataCloudSchema(BaseModel):
+    schemaId: str
+
+class DataCloudRequest(BaseModel):
+    events: List[DataCloudEvent]
+    schemas: List[DataCloudSchema]
+
+@router.post("/", status_code=204)
+async def handle_data_cloud_change_event(request: DataCloudRequest) -> None:
+    """
+    Handle Data Cloud Data Action events.
+
+    This endpoint is designed to be a webhook target for Data Cloud Data Actions.
+    It parses the incoming event payload and, if environment variables are set,
+    can query a connected Data Cloud org.
+
+    :param request: The incoming Data Cloud event payload.
+    :type request: DataCloudRequest
+    :return: An empty response with a 204 status code.
+    :rtype: None
+    """
+    context = sdk.get_client_context()
+    logger = context.logger
+    data_cloud = context.data_cloud
+
+    action_event = data_cloud.parse_data_action_event(request.model_dump())
+    logger.info(
+        f"POST /dataCloudDataChangeEvent: {action_event.count} events for schemas "
+        f"{[s.schemaId for s in action_event.schemas] if action_event.schemas else 'n/a'}"
+    )
+
+    for evt in action_event.events:
+        logger.info(
+            f"Got action '{evt.ActionDeveloperName}', event type '{evt.EventType}' "
+            f"triggered by {evt.EventPrompt} on object '{evt.SourceObjectDeveloperName}' "
+            f"published on {evt.EventPublishDateTime}"
+        )
+        # In a real application, you would add logic here to handle
+        # the changed object values from `evt.PayloadCurrentValue`.
+
+    if os.environ.get("DATA_CLOUD_ORG") and os.environ.get("DATA_CLOUD_QUERY"):
+        org_name = os.environ["DATA_CLOUD_ORG"]
+        query = os.environ["DATA_CLOUD_QUERY"]
+        app_link_addon = context.addons.applink
+
+        logger.info(f"Getting '{org_name}' org connection from Heroku AppLink add-on...")
+        org = await app_link_addon.get_authorization(org_name)
+
+        logger.info(f"Querying org '{org_name}' ({org.id}): {query}")
+        response = await org.data_cloud_api.query(query)
+        logger.info(f"Query response: {response.data}")
+
+    return