================================================================================
                     SECUREPAY PYTHON LIBRARY — USEFUL INFO
               Build, Test & Deploy Guide for PyPI Publication
================================================================================


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 STEP 1 — PREREQUISITES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Make sure you have Python 3.9+ installed:

    python --version

Install the global build and publish tools:

    pip install build twine hatchling


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 STEP 2 — SET UP VIRTUAL ENVIRONMENT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Navigate into the project folder, then:

    python -m venv .venv

Activate the virtual environment:

    # Mac / Linux:
    source .venv/bin/activate

    # Windows (Command Prompt):
    .venv\Scripts\activate.bat

    # Windows (PowerShell):
    .venv\Scripts\Activate.ps1

You will know it is active when you see (.venv) in your terminal prompt.


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 STEP 3 — INSTALL DEPENDENCIES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

With the virtual environment active, install everything (runtime + dev tools):

    pip install -e ".[dev]"

The -e flag installs the package in editable mode, meaning any changes you
make to the source files are immediately reflected without reinstalling.


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 STEP 4 — RUN TESTS & LINT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

All tests must pass and lint must be clean before building:

    # Run all tests
    pytest

    # Check for code style and lint errors
    ruff check .

    # Check types (optional but recommended)
    mypy securepay/

Fix any errors or failures before proceeding to the build step.


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 STEP 5 — BUILD THE DISTRIBUTION PACKAGE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This bundles your code into the two formats PyPI requires:

    python -m build

After running this, a dist/ folder will be created in your project root:

    dist/
    ├── securepay_api-0.0.1.tar.gz           ← source distribution
    └── securepay_api-0.0.1-py3-none-any.whl ← wheel (what pip installs)

NOTE: If dist/ already exists from a previous build, delete it first to
avoid uploading old versions accidentally:

    # Mac / Linux:
    rm -rf dist/

    # Windows:
    rmdir /s /q dist


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 STEP 6 — CREATE A PYPI ACCOUNT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Go to https://pypi.org and click Register
2. Fill in your username, email, and password
3. Verify your email address
4. Go to Account Settings → API Tokens → Add API Token
5. Give it a name (e.g. securepay-publish)
6. Set the scope to "Entire account" for a first publish,
   or restrict it to the specific project after first upload
7. Copy the token immediately — you will only see it once
8. Store it somewhere safe (e.g. a password manager)

Your token will look like this:
    pypi-AgEIcHlwaS5vcmcCJDk4...


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 STEP 7 — TEST ON TESTPYPI FIRST (STRONGLY RECOMMENDED)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

TestPyPI is a sandbox version of PyPI. Always do a test upload here before
going live — mistakes on real PyPI cannot be deleted, only yanked.

1. Create a separate account at https://test.pypi.org (same process as above)
2. Generate a TestPyPI API token from your TestPyPI account settings
3. Upload to TestPyPI:

    twine upload --repository testpypi dist/*

    When prompted:
        Username: __token__
        Password: <paste your TestPyPI API token>

4. Verify the upload at:
    https://test.pypi.org/project/securepay-api/

5. Install from TestPyPI to confirm it works end-to-end:

    pip install --index-url https://test.pypi.org/simple/ securepay-api

6. Run a quick smoke test:

    python -c "from securepay import SecurePayApi; print('Import successful')"

If everything looks good, proceed to the real PyPI upload.


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 STEP 8 — PUBLISH TO PYPI (GO LIVE)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    twine upload dist/*

    When prompted:
        Username: __token__
        Password: <paste your real PyPI API token>

Your package is now live. Verify at:

    https://pypi.org/project/securepay-api/

Anyone can now install it with:

    pip install securepay-api


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 STEP 9 — PUBLISHING UPDATES (NEW VERSIONS)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Every time you add a new API section or fix a bug:

    1. Bump the version number in pyproject.toml
       e.g. version = "0.0.1"  →  version = "0.1.0"

    2. Add an entry to CHANGELOG.md describing what changed:
       ## 0.1.0
       - Added TransfersService
       - Added CollectionsService

    3. Delete the old dist/ folder:
       rm -rf dist/               (Mac/Linux)
       rmdir /s /q dist           (Windows)

    4. Rebuild:
       python -m build

    5. Upload the new version:
       twine upload dist/*

NOTE: PyPI does not allow re-uploading the same version number.
Always increment the version before publishing.


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 SEMANTIC VERSIONING GUIDE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Follow MAJOR.MINOR.PATCH versioning:

    PATCH  (0.0.x) — Bug fixes, no new features, no breaking changes
                     e.g. 0.0.1 → 0.0.2

    MINOR  (0.x.0) — New features added (e.g. new API service added)
                     backwards compatible, no breaking changes
                     e.g. 0.0.2 → 0.1.0

    MAJOR  (x.0.0) — Breaking changes (e.g. renamed classes, removed methods,
                     changed method signatures)
                     e.g. 0.1.0 → 1.0.0


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 QUICK REFERENCE — COMMANDS CHEAT SHEET
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    # Activate virtual environment (run this every time you open the project)
    source .venv/bin/activate              # Mac/Linux
    .venv\Scripts\Activate.ps1             # Windows PowerShell

    # Install / sync dependencies
    pip install -e ".[dev]"

    # Run tests
    pytest

    # Lint
    ruff check .

    # Type check
    mypy securepay/

    # Build
    python -m build

    # Upload to TestPyPI
    twine upload --repository testpypi dist/*

    # Upload to PyPI (live)
    twine upload dist/*


================================================================================
                              END OF USEFUL INFO
================================================================================
