KoFi-API

An API to store and access Ko-fi donations

About Ko-fi API

Ko-fi Donation API is a FastAPI-based system that allows users to store and access Ko-fi transactions. It provides a set of API endpoints for handling donations, exporting and importing the database, and admin-specific operations like managing users and transactions.

Table of Contents

• KoFi-API
  • About Ko-fi API
  • Table of Contents
  • Features
  • Requirements
    • For testing purposes
  • Installation
  • Configuration
  • Running the Application
  • Deploying the Application
    • Docker
  • API Endpoints
    • Ko-fi Webhook Endpoints
    • User Management Endpoints
    • Admin Operations Endpoints
    • Database Management Endpoints
  • Running Tests
  • License
  • Useful CMD

Features

• User management: Create, retrieve, update, and delete LOCAL Ko-fi users.
• Donation transactions: Record and query transactions from Ko-fi's webhook API.
• Admin operations: Access ALL Ko-fi transactions and users.
• Database management: Export and import the SQLite database, as well as recover the database from backups (ONLY available for admin users).

Requirements

• Python 3.10+: Any Python 3.10+ version should be supported, built and tested using Python 3.12.6.
• FastAPI: A modern web framework for building APIs. The application uses FastAPI 0.115.0 by default.
• SQLAlchemy: A Python SQL toolkit and Object Relational Mapper (ORM) for database access.
• APScheduler: A background job scheduler for Python, to remove every day data older than 30 days (default) from the database.
• Alembic: A migration tool for SQLAlchemy.
• Pydantic: A data validation library for Python.

For testing purposes

• coverage: A tool for measuring code coverage of Python programs.
• pytest: A unit testing framework for Python.
• pylint: A tool for static code analysis.

Installation

To install and set up the project locally, follow these steps:

1. Clone the repository:

   git clone <https://github.com/yourusername/kofi-donation-api.git>
   cd kofi-donation-api

2. Create a virtual environment and activate it:

   python -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`

3. Install dependencies:

   cd app
   pip install -r requirements.txt

4. Set up the environment variables:

• DATA_RETENTION_DAYS: Default data retention period for users. Default is "30".

• ADMIN_SECRET_KEY: Secret key for admin operations. Default is changethis. An alert will be raised if the secret key is set to the default value.

• ENVIRONMENT: Provide the stage of the application. Possible values are local and production. Default is local and will not block if the secret key is set to the default value (in production it will block).

  DATA_RETENTION_DAYS="10"
  ADMIN_SECRET_KEY="your_admin_secret_key"
  ENVIRONMENT="production"

Configuration

The application uses Pydantic to manage environment variables. The configuration variables can be defined in the .env file or passed as environment variables. Key configuration options include:

PROJECT_NAME: The name of the project. Default is Ko-fi API. DATA_RETENTION_DAYS: Default data retention period for users. Default is "30". DATABASE_URL: The database connection URL (e.g., SQLite, PostgreSQL). Default is sqlite:///./KoFi.db. ADMIN_SECRET_KEY: Secret key for admin operations. Default is changethis. ENVIRONMENT: The environment in which the app is running (local, production). Default is local.

Running the Application

You can run the FastAPI application using Uvicorn:

cd app
fastapi run main.py

The API will be accessible at http://127.0.0.1:8000, and the documentation will be available at http://127.0.0.1:8000/docs or http://127.0.0.1:8000/redoc (Swagger UI/ReDoc).

Deploying the Application

Docker

You can deploy the application using Docker.

It is recommended to use Docker Compose to manage the application.

If you want to run without defining a separate database you can just deploy the kofi-api service without the db and adminer (optional in all cases) services.

For production it is IMPORTANT to define the ADMIN_SECRET_KEY as it is used to perform admin operations (import / export database).

version: "3.8"

# version: "3.8"

services:
  kofi-api:
    container_name: kofi-api
    image: lordlumineer/kofi-api:latest
    restart: unless-stopped
    # build: .

    ports:
      - 8080:8000
    # environment:
    #   - ENVIRONMENT=production
    #   - DATABASE_URL=postgresql+psycopg2://<POSTGRES_USER>:<POSTGRES_PASSWORD>@db:5432/KoFiAPI
    #   - ADMIN_SECRET_KEY=<ADMIN_SECRET_KEY>
    #   - DATA_RETENTION_DAYS=10
    # volumes:
    #   - <PATH>:/app/data  # Map local folder for persistent storage
    depends_on:
      db:
        condition: service_healthy

  db:
    container_name: kofi-postgres
    image: postgres
    restart: unless-stopped
    # set shared memory limit when using docker-compose
    shm_size: 128mb
    ports:
      - 5432:5432
    # volumes:
    #   - <PATH>:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: KoFiAPI
      POSTGRES_USER: <POSTGRES_USER>
      POSTGRES_PASSWORD: <POSTGRES_PASSWORD>
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U <POSTGRES_USER> -d KoFiAPI"]
      interval: 5s
      timeout: 5s
      retries: 30

  # Optional
  adminer:
    container_name: kofi-adminer
    image: adminer
    restart: unless-stopped
    ports:
      - 8181:8080
    depends_on:
      db:
        condition: service_healthy

API Endpoints

Ko-fi Webhook Endpoints

• POST /webhook: Receives a Ko-fi transaction via a webhook and stores the transaction.

  You can find the different Ko-fi webhook events and more information about them here.

User Management Endpoints

• POST /users/{verification_token}: Create a new user.
• GET /users/{verification_token}: Retrieve a user by their verification token.
• PATCH /users/{verification_token}: Update user data, such as data_retention_days.
• DELETE /users/{verification_token}: Delete a user and their associated transactions.

Admin Operations Endpoints

• GET /db/transactions: Retrieve all Ko-fi transactions (admin-only).
• GET /db/users: Retrieve all Ko-fi users (admin-only).

Database Management Endpoints

• GET /db/export: Export the database (admin-only).
• POST /db/recover: Recover the database from a file (admin-only).
• POST /db/import: Import a database (admin-only).

Running Tests

The project uses pytest for testing. To run the tests, first install the development dependencies:

cd app
pip install -r test/requirements-dev.txt

Then, run the tests:

coverage run -m pytest

This will execute all unit tests, including those for the FastAPI endpoints and database operations.

License

This project is licensed under the MIT License. See the LICENSE file for more details.

---

That's it! You're all set up to use the Ko-fi API.

Useful CMD

pip install -r app/requirements.txt
pip install -r app/test/requirements-dev.txt

fastapi dev app/main.py
fastapi dev app/main.py --host 0.0.0.0

pylint app/ 
pylint app/ --fail-under=8 --output-format=parseable | tee reports/pylint-report.txt

pytest --tb=no --md-report --md-report-verbose=1
pytest --tb=no --md-report --md-report-output=reports/pytest.md

coverage run -m pytest --tb=no --md-report
coverage run -m pytest --tb=no --md-report --md-report-output=reports/pytest.md 
coverage report | tee reports/coverage.txt

cd app
alembic revision --autogenerate -m "describe your changes"