Metadata-Version: 2.4
Name: reconcilly
Version: 0.2.0
Summary: Marketplace settlement reconciliation for QuickBooks Online
Author-email: Peter Sleiman <peter@reconcilly.app>
License: Proprietary
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn[standard]>=0.32
Requires-Dist: python-multipart>=0.0.12
Requires-Dist: jinja2>=3.1
Requires-Dist: pandas>=2.2
Requires-Dist: openpyxl>=3.1
Requires-Dist: pdfplumber>=0.11
Requires-Dist: pydantic>=2.9
Requires-Dist: pyyaml>=6.0
Requires-Dist: google-cloud-storage>=2.18
Requires-Dist: cryptography>=43
Requires-Dist: reportlab>=4.0
Requires-Dist: platformdirs>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: ruff>=0.7; extra == "dev"
Dynamic: license-file

# Reconcilly

Marketplace settlement reconciliation for QuickBooks Online.

Reconcilly turns marketplace export files into balanced journal entries
ready for QBO import, plus a reconciliation report and close memo. It
runs entirely on your computer; nothing is uploaded to a third party.

## What it does

| Channel | Inputs | Outputs |
|---|---|---|
| Amazon | Monthly Unified Transaction CSV (+ optional Monthly Summary PDF for reconciliation) | One JE CSV per settlement id, plus a close memo and (if PDF supplied) a reconciliation report |
| Shopify | Orders CSV, Payouts CSV, Taxes CSV | One monthly JE CSV plus a markdown reconciliation report with 9 validation gates |
| TikTok Shop | Income workbook XLSX | One monthly JE CSV plus a markdown reconciliation report with 11 validation gates |

Every JE balances debits = credits to the cent. Validation gates run
automatically; FAIL gates block emission unless you explicitly override
with a written reason that's recorded in the report.

## What it isn't

- Not a QBO connector. Reconcilly produces a CSV; you import it.
- Not multi-tenant. One `config.yaml` per deployment.
- Not a bookkeeping replacement. It assumes you already know what
  account names and policies you want; it just builds the JE mechanically
  from your exports.

## Quickstart

```sh
git clone <your-fork-or-zip>
cd reconcilly
pip install -e ".[dev]"
cp config.example.yaml config.yaml
# edit config.yaml: set entity codes, channels, cash account names

uvicorn app.main:app --reload
# browse to http://localhost:8000
```

The web UI lets you upload a settlement file and download a zip with the
JE CSV plus the markdown report. There's also a CLI for the Shopify
channel:

```sh
python -m app.reconciliation.shopify --period 2026-03 \
    --csv-dir samples/2026-03/ --entity ACME
```

## Configuration

All customer-specific values live in `config.yaml` (gitignored). Copy
`config.example.yaml` and edit:

```yaml
entities:
  - code: ACME
    label: "ACME LLC"
    channels: [amazon, shopify, tiktok]
    cash_accounts:
      amazon:  "Cash — ACME Amazon"
      shopify: "Cash — ACME Shopify"
      tiktok:  "Cash — ACME TikTok"
    shop_slugs:
      tiktok: ["YOURSHOPSLUG"]

tiktok:
  default_entity: ACME
```

The full schema is documented in `config.example.yaml`.

Environment variable overrides (whitelist):

- `RECONCILLY_CONFIG_PATH` — explicit config file path
- `RECONCILLY_USE_GCS` — toggle GCS storage (Cloud Run)
- `RECONCILLY_GCS_BUCKET` — GCS bucket name

## Development

```sh
pytest                # all synthetic; no setup required
ruff check .          # lint
```

To run integration tests against your own data, drop real export files
under a gitignored `samples/` directory; the existing test infrastructure
gates real-file tests behind `skipif(not PATH.exists())` so they auto-skip
when no samples are present.

## Deployment

A `Dockerfile` and `deploy/cloudbuild.yaml` are included for Google Cloud
Run. The cloudbuild substitutes the service / repo / image names; edit
those for your project before deploying. Set `RECONCILLY_USE_GCS=true`
and `RECONCILLY_GCS_BUCKET=<your-bucket>` on the Cloud Run service so
uploads and outputs persist across instances.

## License

Proprietary. See [LICENSE.md](./LICENSE.md) for terms (Reconcilly
Commercial License v1.0). Contact peter@horizonbrandsgroup.com for
licensing or refunds.
