rcvatkit 0.1.0__py3-none-any.whl

rcvatkit/__init__.py

@@ -0,0 +1,34 @@
+"""
+rcvatkit -- find and calculate the UK VAT reverse-charge adjustment for
+foreign-currency purchase invoices sitting in Sage 50, when they've been
+posted at the wrong tax code by an OCR/import tool.
+
+    from rcvatkit import find_reverse_charge_candidates, compute_adjustment
+    from rcvatkit import last_completed_quarter
+
+See README.md for the full walkthrough.
+"""
+
+from .checker import (
+    DEFAULT_BASE_CURRENCY_ID,
+    DEFAULT_TARGET_TAX_CODE,
+    DEFAULT_VAT_RATE,
+    ReverseChargeLine,
+    compute_adjustment,
+    find_reverse_charge_candidates,
+)
+from .quarters import VAT_STAGGERS, last_completed_quarter
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "find_reverse_charge_candidates",
+    "compute_adjustment",
+    "ReverseChargeLine",
+    "last_completed_quarter",
+    "VAT_STAGGERS",
+    "DEFAULT_VAT_RATE",
+    "DEFAULT_TARGET_TAX_CODE",
+    "DEFAULT_BASE_CURRENCY_ID",
+    "__version__",
+]

rcvatkit/checker.py

@@ -0,0 +1,170 @@
+"""
+rcvatkit.checker
+================
+Finds foreign-currency purchase invoices/credits in Sage 50 that have
+NOT yet been coded with the reverse-charge tax code, and calculates the
+VAT return manual adjustment needed to correct it.
+
+Background
+----------
+Many UK businesses receive non-GBP supplier invoices via an OCR/import
+tool (AutoEntry, Dext, Hubdoc, etc.), and these tools commonly post
+them at the standard "no VAT" tax code (often T0) rather than the
+reverse-charge code Sage expects for EU/foreign purchases (often T18).
+Sage 50 will not accept a reverse-charge tax code on a manual journal
+("This tax code cannot be used for Journal transactions"), so the fix
+is not a journal at all -- it's a manual adjustment on the VAT return
+itself: add the same amount to Box 1 (output VAT) and Box 4 (input
+VAT). The net effect on the VAT bill is nil, but the boxes are
+populated correctly for HMRC.
+
+This module finds the underlying transactions and does the arithmetic.
+It does not touch Sage or submit anything -- applying the adjustment is
+a manual step in Sage's VAT Return "Adjustments" screen (see README).
+
+A note on tax codes and VAT rates: T18 / 20% are the common UK default,
+but your Sage configuration may differ (different tax code numbering,
+a different rate for what you buy). Both are parameters here, not
+hardcoded assumptions -- check your own Sage tax code list if unsure.
+"""
+
+from dataclasses import dataclass
+from datetime import date
+from typing import Dict, List, Sequence
+
+from sagekit import get_columns
+
+DEFAULT_VAT_RATE = 0.20
+DEFAULT_TARGET_TAX_CODE = "T18"
+
+# Sage's ODBC currency IDs are offset by one from what the Sage 50 UI
+# dropdown shows (UI "0 -- Pound Sterling" is ODBC value 1, UI "1 -- US
+# Dollar" is ODBC value 2, and so on) -- confirmed by testing against a
+# live Sage 50 install. 1 is the near-universal default for a UK
+# company's base currency, but if your GBP shows up as a different ID,
+# override it -- see README for how to check.
+DEFAULT_BASE_CURRENCY_ID = 1
+
+
+@dataclass
+class ReverseChargeLine:
+    account_ref: str
+    txn_type: str
+    invoice_ref: str
+    txn_date: date
+    foreign_gross: float
+    gbp_gross: float
+
+
+def _find_col(available, candidates, label):
+    for c in candidates:
+        if c.upper() in available:
+            return c.upper()
+    raise KeyError(
+        f"Could not find a column for '{label}'.\n"
+        f"  Tried: {candidates}\n"
+        f"  Available: {sorted(available)}"
+    )
+
+
+def find_reverse_charge_candidates(
+    cursor,
+    date_from: date,
+    date_to: date,
+    target_tax_code: str = DEFAULT_TARGET_TAX_CODE,
+    base_currency_id: int = DEFAULT_BASE_CURRENCY_ID,
+    purchase_types: Sequence[str] = ("PI", "PC"),
+) -> List[ReverseChargeLine]:
+    """
+    Query Sage 50 for purchase invoices/credits (types PI/PC by
+    default) dated between date_from and date_to, in a currency other
+    than base_currency_id, that are NOT yet coded with
+    target_tax_code.
+
+    Column names are auto-detected against the live database (Sage
+    50's ODBC schema varies a little between versions), so this works
+    across installs without editing any SQL.
+    """
+    ah_cols = get_columns(cursor, "AUDIT_HEADER")
+    as_cols = get_columns(cursor, "AUDIT_SPLIT")
+    pl_cols = get_columns(cursor, "PURCHASE_LEDGER")
+
+    ah_date = _find_col(ah_cols, ["DATE", "INV_DATE", "TRANS_DATE"], "transaction date")
+    ah_fgross = _find_col(ah_cols, ["FOREIGN_GROSS_AMOUNT"], "foreign gross amount")
+    ah_gross = _find_col(ah_cols, ["GROSS_AMOUNT"], "GBP gross amount")
+    ah_ref = _find_col(ah_cols, ["ACCOUNT_REF"], "account ref")
+    ah_inv = _find_col(ah_cols, ["INV_REF", "REFERENCE"], "invoice ref")
+    ah_del = _find_col(ah_cols, ["DELETED_FLAG", "DELETED", "RECORD_DELETED"], "deleted flag")
+    ah_pk = _find_col(ah_cols, ["HEADER_NUMBER", "TRAN_NUMBER", "RECORD_NUMBER"], "header key")
+    as_fk = _find_col(as_cols, ["HEADER_NUMBER", "TRAN_NUMBER", "RECORD_NUMBER"], "split key")
+    as_tax = _find_col(as_cols, ["TAX_CODE", "TAX_TYPE", "VAT_CODE"], "tax code")
+    pl_ref = _find_col(pl_cols, ["ACCOUNT_REF"], "PL account ref")
+    pl_curr = _find_col(pl_cols, ["CURRENCY", "CURRENCY_CODE"], "PL currency")
+
+    type_list = ", ".join(f"'{t}'" for t in purchase_types)
+
+    # Sage's ODBC driver rejects INNER JOIN across 3+ tables ("Invalid
+    # outer join specification") -- the implicit (comma) join style
+    # below is required for a 3-table query, not a style choice.
+    sql = f"""
+        SELECT
+            h.{ah_ref}    AS ACCOUNT_REF,
+            h.TYPE        AS TXN_TYPE,
+            h.{ah_inv}    AS INV_REF,
+            h.{ah_date}   AS TXN_DATE,
+            h.{ah_fgross} AS FOREIGN_GROSS,
+            h.{ah_gross}  AS GBP_GROSS
+        FROM AUDIT_HEADER h, AUDIT_SPLIT s, PURCHASE_LEDGER p
+        WHERE h.{ah_pk} = s.{as_fk}
+          AND h.{ah_ref} = p.{pl_ref}
+          AND h.TYPE IN ({type_list})
+          AND h.{ah_del} = 0
+          AND p.{pl_curr} <> {int(base_currency_id)}
+          AND s.{as_tax} <> '{target_tax_code}'
+          AND h.{ah_date} >= {{d '{date_from.strftime("%Y-%m-%d")}'}}
+          AND h.{ah_date} <= {{d '{date_to.strftime("%Y-%m-%d")}'}}
+        ORDER BY h.{ah_ref}, h.{ah_date}, h.{ah_inv}
+    """
+
+    cursor.execute(sql)
+    rows = cursor.fetchall()
+
+    return [
+        ReverseChargeLine(
+            account_ref=str(r[0]),
+            txn_type=str(r[1]),
+            invoice_ref=str(r[2]),
+            txn_date=r[3],
+            foreign_gross=float(r[4] or 0),
+            gbp_gross=float(r[5] or 0),
+        )
+        for r in rows
+    ]
+
+
+def compute_adjustment(
+    lines: List[ReverseChargeLine], vat_rate: float = DEFAULT_VAT_RATE
+) -> Dict[str, float]:
+    """
+    Given the lines found by find_reverse_charge_candidates, calculate
+    the manual VAT return adjustment: the same amount added to both
+    Box 1 (output VAT) and Box 4 (input VAT), so the net effect on the
+    VAT bill is nil but both boxes are correctly populated for HMRC.
+
+    Returns a dict with net_gbp, vat_rate, box_1, box_4 and
+    net_liability_effect (always 0.0 -- included so callers don't have
+    to know that fact themselves).
+    """
+    total_gbp = sum(line.gbp_gross for line in lines)
+    # Purchase invoices are stored as negative amounts in Sage; take the
+    # absolute value to get a positive net figure to apply the rate to.
+    net_gbp = abs(total_gbp)
+    vat_gbp = round(net_gbp * vat_rate, 2)
+
+    return {
+        "net_gbp": net_gbp,
+        "vat_rate": vat_rate,
+        "box_1": vat_gbp,
+        "box_4": vat_gbp,
+        "net_liability_effect": 0.0,
+    }

rcvatkit/quarters.py

@@ -0,0 +1,85 @@
+"""
+rcvatkit.quarters
+==================
+Helpers for working with UK VAT quarters.
+
+HMRC assigns every VAT-registered business to one of three "stagger
+groups", which determine which months your VAT quarters end in:
+
+    Stagger 1 -- quarters end Mar / Jun / Sep / Dec
+    Stagger 2 -- quarters end Jan / Apr / Jul / Oct
+    Stagger 3 -- quarters end Feb / May / Aug / Nov
+
+You can find which stagger group you're in from your VAT registration
+certificate or your HMRC online account -- it doesn't change unless you
+specifically request it.
+
+These helpers don't touch Sage or make any network calls -- they're
+pure date arithmetic, useful for scripts that need to know "which VAT
+quarter just finished" without hardcoding one business's quarter-end
+months.
+"""
+
+import calendar
+from datetime import date
+from typing import Optional, Tuple
+
+# The four quarter-end months for each HMRC VAT stagger group.
+VAT_STAGGERS = {
+    1: (3, 6, 9, 12),
+    2: (1, 4, 7, 10),
+    3: (2, 5, 8, 11),
+}
+
+
+def last_completed_quarter(
+    stagger: int = 1, today: Optional[date] = None
+) -> Tuple[date, date]:
+    """
+    Return (start_date, end_date) of the most recently *completed* VAT
+    quarter for the given stagger group, as of `today` (defaults to the
+    real current date).
+
+    "Completed" means the quarter that has already ended -- if today
+    falls inside an in-progress quarter, this returns the one before it,
+    not the current one.
+
+    Example: stagger=3 (quarters ending Feb/May/Aug/Nov). If today is
+    any date in Mar/Apr/May, the last completed quarter is Dec-Feb.
+    """
+    if stagger not in VAT_STAGGERS:
+        raise ValueError(
+            f"Unknown stagger group {stagger!r} -- must be 1, 2, or 3. "
+            "Check your VAT registration certificate or HMRC online "
+            "account for which group you're in."
+        )
+
+    end_months = VAT_STAGGERS[stagger]
+    today = today or date.today()
+    y, m = today.year, today.month
+
+    # Walk backwards month by month looking for a quarter-end month whose
+    # quarter has genuinely finished (its end date is before the 1st of
+    # the month we're in now). A couple of years' worth of lookback is
+    # more than enough headroom.
+    for offset in range(0, 15):
+        mm = m - offset
+        yy = y
+        while mm <= 0:
+            mm += 12
+            yy -= 1
+
+        if mm in end_months:
+            end_date = date(yy, mm, calendar.monthrange(yy, mm)[1])
+            if end_date < date(y, m, 1):
+                start_month = mm - 2
+                start_year = yy
+                while start_month <= 0:
+                    start_month += 12
+                    start_year -= 1
+                return date(start_year, start_month, 1), end_date
+
+    raise RuntimeError(
+        "Could not determine the last completed VAT quarter -- "
+        "this shouldn't happen; please report it as a bug."
+    )

rcvatkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: rcvatkit
+Version: 0.1.0
+Summary: Find UK VAT reverse-charge purchase invoices sitting in Sage 50 at the wrong tax code, and calculate the Box 1 / Box 4 VAT return adjustment to correct it.
+Author: Duckboard
+License: MIT
+Project-URL: Homepage, https://github.com/Duckboard/rcvatkit
+Project-URL: Buy me a coffee, https://ko-fi.com/duckboard
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sagekit>=0.1.0
+Dynamic: license-file
+
+# rcvatkit
+
+Finds UK VAT **reverse-charge** purchase invoices sitting in **Sage 50**
+at the wrong tax code, and calculates the VAT return manual adjustment
+needed to correct it.
+
+If this saves you time, consider [buying me a coffee](https://ko-fi.com/duckboard).
+
+## What problem this solves
+
+If you receive foreign-currency (non-GBP) supplier invoices and use an
+OCR/import tool such as AutoEntry, Dext, or Hubdoc, there's a good
+chance those invoices are landing in Sage at the default "no VAT" tax
+code (often `T0`) instead of the reverse-charge code Sage expects
+(often `T18`). HMRC needs Boxes 1 and 4 of your VAT return to reflect
+these transactions correctly.
+
+Sage 50 won't let you post the reverse-charge code on a manual journal
+("This tax code cannot be used for Journal transactions"), so the fix
+isn't a journal at all -- it's a **manual adjustment** on the VAT
+return itself: add the same amount to Box 1 (output VAT) and Box 4
+(input VAT). The net effect on your VAT bill is nil, but the boxes are
+populated the way HMRC expects.
+
+This toolkit finds the transactions and does the arithmetic. It does
+not touch Sage or submit anything -- applying the adjustment is a
+manual step in Sage's VAT Return "Adjustments" screen.
+
+## Features
+
+- Finds non-GBP purchase invoices/credits not yet coded with your
+  reverse-charge tax code, using [sagekit](https://github.com/Duckboard/sagekit)
+  for the Sage 50 ODBC connection and its column auto-detection
+- Calculates the Box 1 / Box 4 adjustment amount
+- Built-in helper for UK VAT "stagger groups" -- works out which VAT
+  quarter just finished without you having to calculate the dates
+  by hand
+- One worked example, ready to adapt: a CLI script with date prompts,
+  a results table, and a saved log file
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+or, to install as an editable package:
+
+```bash
+pip install -e .
+```
+
+This installs [sagekit](https://github.com/Duckboard/sagekit)
+automatically -- rcvatkit builds on it rather than reimplementing the
+Sage connection. You'll also need the **Sage Line 50 ODBC driver**
+(installed alongside Sage 50 itself) and Sage 50 running while you
+query it -- see sagekit's README for how to find your DSN.
+
+## Configuration
+
+Copy `.env.example` to `.env` if you want to pre-fill values:
+
+```bash
+cp .env.example .env
+```
+
+```
+SAGE_DSN=SageLine50v33
+SAGE_UID=MANAGER
+SAGE_PWD=
+
+RCVAT_STAGGER=1
+RCVAT_TARGET_CODE=T18
+RCVAT_VAT_RATE=0.20
+```
+
+`.env` is already in `.gitignore` -- never commit real credentials.
+
+## Which VAT stagger group are you in?
+
+HMRC assigns every VAT-registered business to one of three stagger
+groups, which determine which months your VAT quarters end in. Check
+your VAT registration certificate or HMRC online account if you're not
+sure.
+
+| Stagger | Quarters end |
+|---|---|
+| 1 | Mar / Jun / Sep / Dec |
+| 2 | Jan / Apr / Jul / Oct |
+| 3 | Feb / May / Aug / Nov |
+
+## Usage
+
+```python
+from datetime import date
+from sagekit import connect_or_exit
+from rcvatkit import find_reverse_charge_candidates, compute_adjustment, last_completed_quarter
+
+conn = connect_or_exit()
+cursor = conn.cursor()
+
+# Work out the last completed quarter automatically...
+date_from, date_to = last_completed_quarter(stagger=1)
+
+# ...or just pass your own dates:
+# date_from, date_to = date(2026, 1, 1), date(2026, 3, 31)
+
+lines = find_reverse_charge_candidates(cursor, date_from, date_to)
+adjustment = compute_adjustment(lines)
+
+print(f"{len(lines)} invoice line(s) found, net GBP {adjustment['net_gbp']:.2f}")
+print(f"Add £{adjustment['box_1']:.2f} to Box 1 AND Box 4")
+
+conn.close()
+```
+
+### Example script
+
+```bash
+python examples/check_reverse_charge.py
+```
+
+Prompts for a date range (defaulting to the last completed quarter for
+your stagger group), connects to Sage, prints a table of the affected
+invoices grouped by supplier plus the Box 1/Box 4 adjustment, and saves
+everything to a timestamped log file alongside the script. Copy and
+adapt it -- it's a starting point, not a fixed report.
+
+### Concept reference
+
+| Concept | What it means |
+|---|---|
+| Reverse charge | The VAT treatment HMRC requires for certain foreign-currency purchases -- both output and input VAT are recorded, netting to nil but keeping Boxes 1 and 4 accurate |
+| `T18` | Sage's common default reverse-charge tax code (yours may differ -- check your Sage tax code list) |
+| Stagger group | Which three months your VAT quarters end in -- see table above |
+| `AUDIT_HEADER` / `AUDIT_SPLIT` / `PURCHASE_LEDGER` | The three Sage ODBC tables this toolkit joins to find purchase invoices, their tax code, and the supplier's currency |
+
+## A Sage ODBC quirk worth knowing
+
+Sage's ODBC driver **rejects `INNER JOIN` across three or more tables**
+("Invalid outer join specification"). `find_reverse_charge_candidates`
+uses the older implicit (comma) join style for exactly this reason --
+if you're adapting the SQL yourself and add a fourth table, keep using
+commas rather than `INNER JOIN`.
+
+Also, Sage's ODBC currency IDs are offset by one from what the Sage 50
+UI dropdown shows (UI "0 -- Pound Sterling" is ODBC value `1`, UI
+"1 -- US Dollar" is ODBC value `2`, and so on). `base_currency_id`
+defaults to `1` (the near-universal UK base currency ID), but if your
+own install differs, pass your own value -- run
+`SELECT DISTINCT CURRENCY FROM PURCHASE_LEDGER` via sagekit to check.
+
+## Testing
+
+```bash
+pip install pytest
+pytest
+```
+
+Tests use a fake cursor object, so they run offline without a real
+Sage install, ODBC driver, or sagekit dependency needing to connect
+anywhere.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `Invalid outer join specification` | SQL changed to use `INNER JOIN` across 3+ tables | Use the comma-join style -- see above |
+| `Column not found` / `COLUMN DETECTION ERROR` | Column name varies by Sage version | Check the error message's "Available" list against your install |
+| No rows returned | Wrong date range, or no non-GBP suppliers in that period | Confirm Sage is open, widen the date range, check `RCVAT_TARGET_CODE` matches what your install actually uses |
+| Adjustment looks too big/small | Wrong `RCVAT_VAT_RATE` or wrong `base_currency_id` | Confirm your VAT rate and check `PURCHASE_LEDGER.CURRENCY` values for your GBP accounts |
+| `This tax code cannot be used for Journal transactions` | Expected -- you tried to journal the reverse charge instead of using a manual VAT return adjustment | Use the Adjustments screen on the VAT return, not a journal |
+
+## Notes
+
+- This calculates the adjustment; it does not post anything to Sage or
+  submit your VAT return. Always sanity-check the figures before
+  applying them.
+- Not tax advice -- if you're unsure whether reverse charge applies to
+  your purchases, check with HMRC guidance or your accountant.
+
+## License
+
+MIT -- see [LICENSE](LICENSE). Do whatever you like with this; a
+credit or a [Ko-fi tip](https://ko-fi.com/duckboard) is appreciated
+but never required.

rcvatkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+rcvatkit/__init__.py,sha256=8C7dw51_LILp7DTMG9m9LzJpaqYB3Pf2KxYPM7s3C8E,903
+rcvatkit/checker.py,sha256=v63Ri7UsOJsC-finwmTukhsyDH3_WLVqM-HiqQp5P7s,6611
+rcvatkit/quarters.py,sha256=HS_QEJJ1PIYfzVo-K10vozgtODMYw-S9Jxi3Glnojy4,2886
+rcvatkit-0.1.0.dist-info/licenses/LICENSE,sha256=ChymOtwCDSjsL0VwJuqUn7dw8gqHr0Rt4jHcFsJa8Ec,1066
+rcvatkit-0.1.0.dist-info/METADATA,sha256=p3F830_mLwscRPlEIp_gwPyPxa0b7lgv7Cxl_a65MNQ,8000
+rcvatkit-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+rcvatkit-0.1.0.dist-info/top_level.txt,sha256=OoTWKIMPuBWw-GkCe4l5pBMWKV4TO_veF4F1O_YnJ4U,9
+rcvatkit-0.1.0.dist-info/RECORD,,

rcvatkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rcvatkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duckboard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rcvatkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rcvatkit