@gabrielerandelli/minus-tracker 0.5.7 → 0.6.0

package/dist/index.cjs

@@ -32,6 +32,8 @@ var src_exports = {};
 __export(src_exports, {
   CalculationError: () => CalculationError,
   Calculator: () => Calculator,
+  ClassificationError: () => ClassificationError,
+  Classifier: () => Classifier,
   DEGIROParser: () => DEGIROParser,
   ParseError: () => ParseError
 });
@@ -59,6 +61,16 @@ var CalculationError = class extends Error {
     this.date = date;
   }
 };
+var ClassificationError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(
+      message ?? (code === "SIDECAR_NOT_FOUND" ? "Sidecar file not found" : code === "SIDECAR_VERSION" ? "Sidecar version mismatch" : code === "SIDECAR_MALFORMED" ? "Sidecar file is malformed JSON" : code === "NETWORK_ERROR" ? "Network error contacting OpenFIGI" : "Failed to write sidecar file")
+    );
+    this.name = "ClassificationError";
+    this.code = code;
+  }
+};
 
 // src/rates/index.ts
 var import_node_url = require("url");
@@ -199,6 +211,17 @@ var DEGIROParser = class {
   constructor(snapshot) {
     this._snapshot = snapshot;
   }
+  /**
+   * Parse a DEGIRO Transactions CSV export string.
+   *
+   * @param csv - Raw UTF-8 string from the DEGIRO Transactions export.
+   * @returns Array of normalised Transaction objects. Empty if no data rows are found.
+   * @throws {ParseError} code `"INVALID_CSV"` — malformed CSV or binary content.
+   * @throws {ParseError} code `"MISSING_COLUMN"` (+ `columnName`) — required column absent.
+   *
+   * Rows with missing ISIN, unsupported currency, zero quantity, or no ECB rate within
+   * 3 trading days are skipped silently. Inspect `parser.warnings` for details.
+   */
   parse(csv) {
     this._warningEntries = [];
     if (typeof csv !== "string" || csv.includes("\0")) {
@@ -322,10 +345,21 @@ function inferTaxYear(transactions) {
 var Calculator = class {
   _transactions;
   _parseWarnings;
-  constructor(transactions, parseWarnings) {
+  _options;
+  constructor(transactions, parseWarnings, options) {
     this._transactions = transactions;
     this._parseWarnings = parseWarnings ?? [];
+    this._options = options ?? {};
   }
+  /**
+   * Run LIFO or FIFO lot-matching over the transaction list.
+   *
+   * @param method - `"LIFO"` or `"FIFO"`.
+   * @returns GainsReport with `plusvalenze`, `minusvalenze`, `netResult`, per-lot breakdown,
+   *          ECB rates used, and any accumulated warnings.
+   * @throws {CalculationError} when a SELL has no matching open buy lots.
+   *         `error.isin` and `error.date` identify the problematic transaction.
+   */
   calculateGains(method) {
     const warnings = [...this._parseWarnings];
     const sorted = [...this._transactions].sort((a, b) => {
@@ -409,6 +443,104 @@ var Calculator = class {
       if (lot.gainLossEUR > 0) plusvalenze += lot.gainLossEUR;
       else minusvalenze += Math.abs(lot.gainLossEUR);
     }
+    if (this._options.classification) {
+      const classification = this._options.classification;
+      const unclassifiedIsins = /* @__PURE__ */ new Set();
+      for (const lot of matchedLots) {
+        const entry = classification[lot.isin];
+        if (!entry) {
+          lot.bucket = "B";
+          unclassifiedIsins.add(lot.isin);
+        } else if (entry.bucketGain === "A" && lot.gainLossEUR >= 0) {
+          lot.bucket = "A";
+        } else {
+          lot.bucket = "B";
+        }
+      }
+      for (const isin of unclassifiedIsins) {
+        warnings.push(
+          `ISIN ${isin} not found in classification map \u2014 assigned to Bucket B.`
+        );
+      }
+      const bucketALots = matchedLots.filter((l) => l.bucket === "A");
+      const groupsByRate = /* @__PURE__ */ new Map();
+      for (const lot of bucketALots) {
+        const entry = classification[lot.isin];
+        const rate = entry.taxRate;
+        if (!groupsByRate.has(rate))
+          groupsByRate.set(rate, { assetClasses: /* @__PURE__ */ new Set(), plusvalenze: 0 });
+        const g = groupsByRate.get(rate);
+        g.assetClasses.add(entry.assetClass);
+        g.plusvalenze += lot.gainLossEUR;
+      }
+      const bucketAGroups = [...groupsByRate.entries()].map(([taxRate, g]) => ({
+        taxRate,
+        assetClasses: [...g.assetClasses],
+        plusvalenze: roundHalfUp(g.plusvalenze),
+        imposta: roundHalfUp(g.plusvalenze * taxRate)
+      }));
+      const bucketAReport = {
+        groups: bucketAGroups,
+        totalImposta: roundHalfUp(
+          bucketAGroups.reduce((s, g) => s + g.imposta, 0)
+        )
+      };
+      const bucketBLots = matchedLots.filter((l) => l.bucket === "B");
+      let bPlusvalenze = 0;
+      let bMinusvalenze = 0;
+      for (const lot of bucketBLots) {
+        if (lot.gainLossEUR >= 0) bPlusvalenze += lot.gainLossEUR;
+        else bMinusvalenze += Math.abs(lot.gainLossEUR);
+      }
+      bPlusvalenze = roundHalfUp(bPlusvalenze);
+      bMinusvalenze = roundHalfUp(bMinusvalenze);
+      const carryForwards = [...this._options.carryForward ?? []].sort(
+        (a, b) => a.year - b.year
+      );
+      let remaining = bPlusvalenze - bMinusvalenze;
+      let carryForwardApplied = 0;
+      for (const entry of carryForwards) {
+        if (taxYear - entry.year > 4) continue;
+        if (remaining <= 0) break;
+        const consumed = Math.min(entry.amount, remaining);
+        carryForwardApplied += consumed;
+        remaining -= consumed;
+      }
+      carryForwardApplied = roundHalfUp(carryForwardApplied);
+      const bNetResult = roundHalfUp(
+        bPlusvalenze - bMinusvalenze - carryForwardApplied
+      );
+      const carryForwardRemaining = roundHalfUp(Math.max(0, -bNetResult));
+      const bucketBReport = {
+        plusvalenze: bPlusvalenze,
+        minusvalenze: bMinusvalenze,
+        carryForwardApplied,
+        carryForwardRemaining,
+        netResult: bNetResult
+      };
+      return {
+        method,
+        taxYear,
+        plusvalenze: roundHalfUp(plusvalenze),
+        minusvalenze: roundHalfUp(minusvalenze),
+        netResult: roundHalfUp(plusvalenze - minusvalenze),
+        lots: matchedLots,
+        ratesUsed,
+        warnings,
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        bucketA: bucketAGroups.length > 0 ? bucketAReport : void 0,
+        bucketB: bucketBReport
+      };
+    } else {
+      const allIsins = [...new Set(this._transactions.map((t) => t.isin))];
+      const hasIePrefix = allIsins.some((isin) => isin.startsWith("IE"));
+      const hasOther = allIsins.some((isin) => !isin.startsWith("IE"));
+      if (hasIePrefix && hasOther) {
+        warnings.push(
+          "AVVISO: CSV contiene tipi di strumenti misti (es. ETF + Azioni).\n   Il calcolo a bucket unico pu\xF2 non essere fiscalmente corretto.\n   Esegui: minus-tracker classify trades.csv"
+        );
+      }
+    }
     return {
       method,
       taxYear,
@@ -422,10 +554,358 @@ var Calculator = class {
     };
   }
 };
+
+// src/classifier/index.ts
+var fs2 = __toESM(require("fs"), 1);
+var https = __toESM(require("https"), 1);
+function httpsPost(url, body, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const req = https.request(
+      {
+        hostname: u.hostname,
+        path: u.pathname + u.search,
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(body)
+        }
+      },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => {
+          data += chunk;
+        });
+        res.on("end", () => resolve({ status: res.statusCode ?? 0, data }));
+      }
+    );
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      reject(new Error("timeout"));
+    });
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+var GOVT_BOND_WHITELIST = /* @__PURE__ */ new Set([
+  "IT",
+  "DE",
+  "FR",
+  "AT",
+  "BE",
+  "NL",
+  "ES",
+  "PT",
+  "FI",
+  "IE",
+  "LU",
+  "GR",
+  "SK",
+  "SI",
+  "LT",
+  "LV",
+  "EE",
+  "MT",
+  "CY",
+  "US",
+  "GB",
+  "CH",
+  "NO",
+  "SE",
+  "DK",
+  "JP",
+  "CA",
+  "AU",
+  "NZ",
+  "SG",
+  "HK",
+  "KR"
+]);
+var SECURITY_TYPE_MAP = {
+  ETP: {
+    assetClass: "ETF",
+    bucketGain: "A",
+    bucketLoss: "B",
+    taxRate: 0.26,
+    whiteListed: null
+  },
+  ETF: {
+    assetClass: "ETF",
+    bucketGain: "A",
+    bucketLoss: "B",
+    taxRate: 0.26,
+    whiteListed: null
+  },
+  "Mutual Fund": {
+    assetClass: "ETF",
+    bucketGain: "A",
+    bucketLoss: "B",
+    taxRate: 0.26,
+    whiteListed: null
+  },
+  "Open-End Fund": {
+    assetClass: "ETF",
+    bucketGain: "A",
+    bucketLoss: "B",
+    taxRate: 0.26,
+    whiteListed: null
+  },
+  "Common Stock": {
+    assetClass: "Stock",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  Equity: {
+    assetClass: "Stock",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  "Exchange Traded Commodity": {
+    assetClass: "ETC",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  "Corporate Bond": {
+    assetClass: "CorpBond",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  Option: {
+    assetClass: "Derivative",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  Future: {
+    assetClass: "Derivative",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  Warrant: {
+    assetClass: "Derivative",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  CFD: {
+    assetClass: "Derivative",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  Swap: {
+    assetClass: "Derivative",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  "Leverage Certificate": {
+    assetClass: "LeverageCert",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  "Turbo Certificate": {
+    assetClass: "LeverageCert",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  "Capital Protected Certificate": {
+    assetClass: "CapProtectedCert",
+    bucketGain: "A",
+    bucketLoss: "B",
+    taxRate: 0.26,
+    whiteListed: null
+  }
+};
+function isKnownType(t) {
+  return t === "Government Bond" || t in SECURITY_TYPE_MAP;
+}
+function classifyByType(isin, securityType, product, warnings) {
+  if (securityType === "Government Bond") {
+    const prefix = isin.slice(0, 2).toUpperCase();
+    const whiteListed = GOVT_BOND_WHITELIST.has(prefix);
+    return {
+      product,
+      assetClass: whiteListed ? "GovtBondWL" : "GovtBondOther",
+      bucketGain: "A",
+      bucketLoss: "B",
+      taxRate: whiteListed ? 0.125 : 0.26,
+      whiteListed,
+      confirmedByUser: false,
+      source: "openfigi"
+    };
+  }
+  const mapped = SECURITY_TYPE_MAP[securityType];
+  if (mapped) {
+    return {
+      product,
+      assetClass: mapped.assetClass,
+      bucketGain: mapped.bucketGain,
+      bucketLoss: mapped.bucketLoss,
+      taxRate: mapped.taxRate,
+      whiteListed: mapped.whiteListed,
+      confirmedByUser: false,
+      source: "openfigi"
+    };
+  }
+  warnings.push(
+    `Unrecognized type: ${securityType}. Please classify manually.`
+  );
+  return {
+    product,
+    assetClass: "Stock",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null,
+    confirmedByUser: false,
+    source: "user"
+  };
+}
+var Classifier = class {
+  interactive;
+  constructor(options) {
+    this.interactive = options?.interactive ?? true;
+  }
+  async load(sidecarPath) {
+    if (!fs2.existsSync(sidecarPath)) {
+      throw new ClassificationError("SIDECAR_NOT_FOUND");
+    }
+    let parsed;
+    try {
+      const raw = fs2.readFileSync(sidecarPath, "utf-8");
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new ClassificationError("SIDECAR_MALFORMED");
+    }
+    if (typeof parsed !== "object" || parsed === null || parsed["version"] !== 1) {
+      throw new ClassificationError("SIDECAR_VERSION");
+    }
+    return parsed.classifications;
+  }
+  async classify(transactions, sidecarPath, _httpPost = httpsPost) {
+    const isinToProduct = /* @__PURE__ */ new Map();
+    for (const tx of transactions) {
+      if (tx.isin && !isinToProduct.has(tx.isin)) {
+        isinToProduct.set(tx.isin, tx.product);
+      }
+    }
+    const confirmed = {};
+    if (fs2.existsSync(sidecarPath)) {
+      const existingMap = await this.load(sidecarPath);
+      for (const [isin, entry] of Object.entries(existingMap)) {
+        if (entry.confirmedByUser) {
+          confirmed[isin] = entry;
+        }
+      }
+    }
+    const toProcess = [];
+    for (const isin of isinToProduct.keys()) {
+      if (!(isin in confirmed)) {
+        toProcess.push(isin);
+      }
+    }
+    const warnings = [];
+    const newEntries = {};
+    const BATCH_SIZE = 10;
+    for (let i = 0; i < toProcess.length; i += BATCH_SIZE) {
+      if (i > 0) {
+        await new Promise((resolve) => setTimeout(resolve, 6e3));
+      }
+      const batch = toProcess.slice(i, i + BATCH_SIZE);
+      const requestBody = JSON.stringify(
+        batch.map((isin) => ({ idType: "ID_ISIN", idValue: isin }))
+      );
+      let response = null;
+      for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+          const r = await _httpPost(
+            "https://api.openfigi.com/v3/mapping",
+            requestBody,
+            1e4
+          );
+          if (r.status < 500) {
+            response = r;
+            break;
+          }
+        } catch {
+          throw new ClassificationError("NETWORK_ERROR");
+        }
+      }
+      if (response === null) {
+        throw new ClassificationError("NETWORK_ERROR");
+      }
+      const results = JSON.parse(response.data);
+      for (let j = 0; j < batch.length; j++) {
+        const isin = batch[j];
+        const result = results[j];
+        const product = isinToProduct.get(isin) ?? isin;
+        if (!result || result.error || !result.data || result.data.length === 0) {
+          warnings.push(
+            `Unrecognized type: unknown. Please classify manually.`
+          );
+          newEntries[isin] = {
+            product,
+            assetClass: "Stock",
+            bucketGain: "B",
+            bucketLoss: "B",
+            taxRate: 0,
+            whiteListed: null,
+            confirmedByUser: false,
+            source: "user"
+          };
+          continue;
+        }
+        const st = result.data[0]?.securityType;
+        const st2 = result.data[0]?.securityType2;
+        const typeToUse = st && isKnownType(st) ? st : st2 && isKnownType(st2) ? st2 : st ?? st2 ?? "Unknown";
+        newEntries[isin] = classifyByType(isin, typeToUse, product, warnings);
+      }
+    }
+    const mergedMap = { ...newEntries, ...confirmed };
+    const sidecarContent = JSON.stringify(
+      {
+        version: 1,
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        classifications: mergedMap,
+        warnings
+      },
+      null,
+      2
+    );
+    try {
+      fs2.writeFileSync(sidecarPath, sidecarContent, "utf-8");
+    } catch {
+      throw new ClassificationError("WRITE_ERROR");
+    }
+    return mergedMap;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CalculationError,
   Calculator,
+  ClassificationError,
+  Classifier,
   DEGIROParser,
   ParseError
 });