-----------------------------------
Getting everything up and running
-----------------------------------

1. Copy .env.example to .env

2. Add your credentials to the .env file.
    PUSHER_APP_ID is required

3. Open a terminal configured to run Docker and then run:

./run setup

NOTE: If you get any permission errors, you can just add and run this command below instead:

chmod 0755 run &&  ./run fastapi:db:reset
  ./run fastapi:db:migrate stamp head
  ./run fastapi:seed


TIP:
  - Instead of ./run setup, you can use ./run setup_without_formatting instead. 
    So the whole project won't have to be formatted by `isort` and `black`.
  - This prevents unecessary files changes throughout the whole project.
    Which could be very confusing when adding your commits. 
  - If you want formatting, just run `isort` and `black` via terminal to your specific file changes only. 
    Or install a 3rd party extension in your IDE that could automatically format your files whenver you save them.
    Which saves you time and is less hassle. Just make sure that it applies the same standards followed in this project.

-----------------------------------
Troubleshooting
-----------------------------------

NOTE: An Updated Trouble Shooting Guide is now migrated into a separate document:

https://app.clickup.com/36622149/v/dc/12xku5-1376/12xku5-676

-----------------------------------
Swagger API Docs
-----------------------------------

* Swagger API Docs in JSON and YML are now available by accessing the following endpoints in Development environment:
  - /api/v1/swagger/apidocs/ (shows an interactive Swagger UI generated by Flasgger Docstrings)
  - /api/v1/swagger/apispec_1.json (returns json file format of Swagger API Doc)
  - /api/v1/swagger/download?format=json (automatically exports Swagger file in json format)
  - /api/v1/swagger/download?format=yaml (automatically exports Swaggger file in yaml format)
  - /api/v1/swagger/download?format=yml (automatically exports Swagger file in yml format)

* Swagger API Docs are also committed and available in the repo in this directories:
  - wilfie-flask-app/api-docs/swagger.json
  - wilfie-flask-app/api-docs/swagger.yml
  NOTE: Make sure to keep these copies up to date whenever there are changes in the APIs and Swagger API Docs

* SwaggerHub Auto API Mocking can also now be used for integration:
  - (Mock API URL) https://virtserver.swaggerhub.com/CJSALGO252/wilfie-ai-2/1.0
  - (Swagger Hub Playground) https://app.swaggerhub.com/apis/CJSALGO252/wilfie-ai-2/1.0

  NOTE: SwaggerHub API Auto Mocking - Setup Guide is also available in this document below:
    - https://app.clickup.com/36622149/v/dc/12xku5-1416/12xku5-716c
  
    Supported Response Content-Type:
      - application/json
      - application/xml
      - application/yaml

    Unsupported Response Content-Type:
      - text/event-stream
      - text/plain

    NOTE: The "Unsupported Response Content-Type" above are response types that cannot be mocked by the following:
      - SwaggerHub 
      - Swagger UI (Swagger API Docs) generated by Flasgger 
    "Try it out" options won't yield the expected Mocked Response Body since the Response Types are unsupported

-----------------------------------
Postman Collection
-----------------------------------

* Postman Collections and Environment are also committed and available in the repo in this directories:
  - wilfie-flask-app/api-docs/postman_collection.json
  - wilfie-flask-app/api-docs/postman_environment.json

  NOTE: Just import both the postman_collection.json and postman_environment.json on your Postman for usage

-----------------------------------
Pycharm Debug
-----------------------------------

configuration: python
script path: /app/bin/gunicorn
parameters: -b 0.0.0.0:8000 -t 200 -c python:src.config.gunicorn wilfie_flask_app.src.app:create_app()
working directory example: /Users/gavincliffe/Code/wilfie-flask-app
interpreter: remote
docker compose command and options: up web webpack worker sveltekit_app mcp_server
env tab -> enable env, add file: .env (command+shift+. to show hidden files on mac)

fastapi debug configuration:
remote interpreter
script path: /app/.venv/bin/uvicorn
script parameters: wilfie_fastapi_app.src.app:app --host 0.0.0.0 --port 8001 --reload --reload-dir /app/wilfie_fastapi_app
working directory example: /Users/gavincliffe/Code/wilfie-flask-app
docker compose command: up fastapi_app

Remote Interpreter
Docker-Compose
Server: Docker
Configuration files: ./docker-compose.yml; ./docker-compose.override.yml
Service: Web
Path mappings: <Project root>→/app

-----------------------------------
Ngrok
-----------------------------------

run terminal command:
ngrok http --region=au --hostname=wilfie.au.ngrok.io 7999

-----------------------------------
.ENV
-----------------------------------

SECRET_KEY= result from ./run flask secrets with test prefix

Ngrok :
    SERVER_NAME= your ngrok url

Pusher :
    PUSHER_APP_ID=
    PUSHER_KEY=
    PUSHER_SECRET=

AWS :
    AWS_ACCESS_KEY_ID=
    AWS_SECRET_ACCESS_KEY=
    AWS_SESSION_TOKEN=

Stripe :
    STRIPE_PUBLISHABLE_KEY=
    STRIPE_SECRET_KEY=

OpenAI :
    OPENAI_API_KEY

Sendinblue :
    SENDINBLUE_API_KEY

-----------------------------------
MCP Server
-----------------------------------

The project includes a standalone FastMCP server for running integrations and
workflows. It listens on `http://localhost:8003/mcp` and uses the Streamable
HTTP transport so responses can be streamed back to clients. Every request must
include `Authorization: Bearer <token>` where the token is a short lived JWT
signed with `SECRET_KEY`. Tokens are generated by the Flask application
whenever it calls the OpenAI Responses API and expire after
`MCP_TOKEN_EXPIRES_SECONDS` (defaults to 600 seconds). The server refuses to
start if `SECRET_KEY` is missing. Host and port can be configured with
`MCP_HOST` and `MCP_PORT`.
Use `FLASK_HOST` and `FLASK_PORT` to specify where the MCP server can
reach the Flask API.

-----------------------------------
Email Catcher
-----------------------------------

http://localhost:1080 to view emails sent in development

-----------------------------------
Wilfie API KEYs
-----------------------------------
create a test key for your local environment for AWS Lambdas to connect to:
./run flask redisinstance create-apikey --description "wilfie local api key"
add the key to .env

to check if your key already exists in redis run:
./run flask redisinstance get-apikeys


----------
ENCRYPTION
----------
To create a Fernet key for your environment:
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

use it in your .env file:
SECRET_ENCRYPTION_KEY=
