feat: Initial version

.gitignore

@@ -0,0 +1 @@
+data/*.json

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Klemen Košir
+
+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.

README.md

@@ -0,0 +1,49 @@
+# actual-parser
+
+A simple parser for [Saison Card][saison] and [SMBC][smbc] credit card statements,
+to easily import them into [Actual][actual].
+
+## Usage
+To use this script, download a CSV file from one of the supported sites, and run the following:
+```bash
+./actual-parser.py my-statement.csv
+```
+
+The output will be in CSV format, which can be [imported][import] into Actual:
+```csv
+Date,Payee,Notes,Category,Amount
+2024-12-01,GitHub,Sponsors,Donations,-500
+2024-12-02,Open Collective,Actual,Donations,-1000
+```
+
+## Configuration
+Transactions can be transformed using the mapping files under the `data` directory.
+All files are simple JSON mappings between the payee name and the target value.
+
+Once the transaction is identified using exact or prefix matching on the payee name,
+the desired field is replaced using the target value.
+
+For example, the `payee.json` file can contain the following object:
+```json
+{
+    "GITHUB": "GitHub"
+}
+```
+
+In this case, the **payee** field of any transaction with the payee `GITHUB` or `GITHUB.COM`
+will be changed to `GitHub`.
+
+The same works for the `notes.json` file:
+```json
+{
+    "GOOGLE*GSUITE": "G Suite"
+}
+```
+
+In this case, the **notes** field of any transaction with the payee `GOOGLE*GSUITE`
+will be changed to `G Suite`.
+
+[saison]: https://www.saisoncard.co.jp
+[smbc]: https://www.smbc-card.com
+[actual]: https://actualbudget.org
+[import]: https://actualbudget.org/docs/transactions/importing

actual-parser.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+
+import csv
+import datetime
+import json
+import os
+import sys
+
+
+def load_data(name):
+    base = os.path.dirname(__file__)
+    path = f"data/{name}.json"
+
+    with open(os.path.join(base, path)) as file:
+        return json.load(file)
+
+
+def find_entry(data, payee):
+    if payee in data:
+        return data[payee]
+
+    for prefix, value in data.items():
+        if payee.startswith(prefix):
+            return value
+
+    return None
+
+
+def get_payee(payee):
+    entry = find_entry(PAYEE, payee)
+    return entry or payee
+
+
+def get_notes(payee, notes):
+    if entry := find_entry(NOTES, payee):
+        return entry
+
+    # We don't care about these, we're already paying in JPY.
+    if ".00 JPY" in notes:
+        return ""
+
+    return notes.removeprefix("現地通貨額:")
+
+
+def get_category(payee):
+    entry = find_entry(CATEGORY, payee)
+    return entry or ""
+
+
+def format_row(date, payee, notes, amount):
+    date = datetime.datetime.strptime(date, "%Y/%m/%d").strftime("%Y-%m-%d")
+    notes = get_notes(payee, notes)
+    category = get_category(payee)
+    payee = get_payee(payee)
+    amount = f"{-float(amount):g}"
+
+    return [date, payee, notes, category, amount]
+
+
+def handle_saison(row):
+    date, payee, _, _, _, amount, notes, *_ = row
+
+    # Ignore rows with notes.
+    if date == "":
+        return None
+
+    return format_row(date, payee, notes, amount)
+
+
+def handle_smbc_current(row):
+    date, payee, _, _, _, _, amount, *_ = row
+    return format_row(date, payee, "", amount)
+
+
+def handle_smbc_finalized(row):
+    date, payee, _, _, _, amount, *_ = row
+    return format_row(date, payee, "", amount)
+
+
+if len(sys.argv) < 2:
+    print(f"Usage: {sys.argv[0]} <CSV-FILE>")
+    exit(1)
+
+csv_file = sys.argv[1]
+
+PAYEE = load_data("payee")
+NOTES = load_data("notes")
+CATEGORY = load_data("category")
+
+# Readable with: iconv -f Shift-JIS -t UTF-8 <file>
+with open(csv_file, newline="", encoding="shift_jis") as file:
+    rows = list(csv.reader(file, delimiter=","))
+
+    if len(rows) == 0:
+        print("ERROR: No data in file!")
+        sys.exit(1)
+
+    if rows[0] == ["カード名称", "ＪＱ　ＣＡＲＤセゾン"]:
+        # Remove headers.
+        rows = rows[5:]
+        handler = handle_saison
+    else:  # SMBC.
+        if "**-****-****" in rows[0][1]:
+            # Remove account names.
+            rows = list(filter(lambda row: len(row) > 3, rows))
+            # Remove row with month total.
+            rows = rows[:-1]
+            handler = handle_smbc_finalized
+        else:
+            handler = handle_smbc_current
+
+    output = filter(lambda row: row is not None, map(handler, rows))
+    output = sorted(output, key=lambda row: row[0])
+
+    print("Date,Payee,Notes,Category,Amount")
+    for row in output:
+        print(",".join(row))

data/category.json

@@ -0,0 +1,2 @@
+{
+}

data/notes.json

@@ -0,0 +1,2 @@
+{
+}

data/payee.json

@@ -0,0 +1,2 @@
+{
+}