lordlumineer/kofi-api repository overview

⁠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⁠
  • API Endpoints⁠
    • Ko-fi Webhook Endpoints⁠
    • User Management Endpoints⁠
    • Admin Operations Endpoints⁠
    • Database Management Endpoints⁠
  • Running Tests⁠
  • License⁠

⁠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
   

   Copy

2. Create a virtual environment and activate it:

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

   Copy

3. Install dependencies:

   cd app
   pip install -r requirements.txt
   

   Copy

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"
  

  Copy

⁠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).

⁠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.