Automating GST purchase invoices: AI reads the bill, code checks it

const text = { type: ["string", "null"] };
const money = { type: ["number", "null"] };
const party = {
  type: "object",
  properties: { name: text, gstin: text, address: text },
  required: ["name", "gstin", "address"],
  additionalProperties: false,
};

export const INVOICE_SCHEMA = {
  type: "object",
  properties: {
    supplier: party,
    buyer: party,
    invoice_number: text,
    invoice_date: { type: ["string", "null"], description: "YYYY-MM-DD" },
    place_of_supply: { type: ["string", "null"], description: "As printed, e.g. 29-Karnataka" },
    line_items: {
      type: "array",
      items: {
        type: "object",
        properties: {
          description: text,
          hsn: { type: ["string", "null"], description: "HSN or SAC code" },
          quantity: money,
          rate: { type: ["number", "null"], description: "Price per unit before tax" },
          taxable_value: { type: ["number", "null"], description: "Line amount before tax" },
          gst_rate: { type: ["number", "null"], description: "Total GST % for the line, e.g. 18 (not 9 + 9)" },
        },
        required: ["description", "hsn", "quantity", "rate", "taxable_value", "gst_rate"],
        additionalProperties: false,
      },
    },
    taxable_total: money,
    cgst: money,
    sgst: { type: ["number", "null"], description: "SGST or UTGST amount" },
    igst: money,
    cess: money,
    round_off: { type: ["number", "null"], description: "Negative if rounded down" },
    grand_total: money,
    confidence: { type: "string", enum: ["high", "medium", "low"] },
    unclear_fields: { type: "array", items: { type: "string" }, description: "Fields you could not read clearly" },
  },
  required: [
    "supplier", "buyer", "invoice_number", "invoice_date", "place_of_supply", "line_items",
    "taxable_total", "cgst", "sgst", "igst", "cess", "round_off", "grand_total",
    "confidence", "unclear_fields",
  ],
  additionalProperties: false,
};

export const SYSTEM = `You read Indian GST tax invoices for an accounts team.
Copy every value exactly as it is printed. Never calculate, correct or fill in anything:
if the printed total is wrong, return the wrong total. Our code checks the maths afterwards.
Use null for anything that is not printed. Amounts are plain numbers in rupees, no commas or symbols.
Dates as YYYY-MM-DD (Indian invoices print day first).
If the GST rate is only printed on the tax rows (e.g. "CGST @ 9%" and "SGST @ 9%"), give each line the combined rate (18).
The supplier is the business that issued the invoice. The buyer is who it is billed to.
List any field you had to guess in unclear_fields, and set confidence to low if the document is hard to read.`;

// Reads the invoice through OpenRouter: one fetch, no SDK.
// Swap models (Gemini, GPT, Claude...) by changing AI_MODEL, nothing else.

import { INVOICE_SCHEMA, PROMPT, SYSTEM } from "../extract.js";

const ENDPOINT = "https://openrouter.ai/api/v1/chat/completions";
export const MODEL = () => process.env.AI_MODEL ?? "google/gemini-3.8-flash";

/** The document as a message part: PDFs as a file, photos as an image. */
function documentPart({ fileName, mimeType, base64 }) {
  const dataUrl = `data:${mimeType};base64,${base64}`;
  return mimeType === "application/pdf"
    ? { type: "file", file: { filename: fileName, file_data: dataUrl } }
    : { type: "image_url", image_url: { url: dataUrl } };
}

export async function readInvoice(file) {
  const response = await fetch(ENDPOINT, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
      "Content-Type": "application/json",
      "X-Title": "GST invoice intake",
    },
    body: JSON.stringify({
      model: MODEL(),
      temperature: 0,
      messages: [
        { role: "system", content: SYSTEM },
        { role: "user", content: [documentPart(file), { type: "text", text: PROMPT }] },
      ],
      // The model must answer in exactly this shape.
      response_format: {
        type: "json_schema",
        json_schema: { name: "gst_invoice", strict: true, schema: INVOICE_SCHEMA },
      },
      // Only use providers that actually enforce the schema.
      provider: { require_parameters: true },
      // Let the model read the PDF itself (no extra OCR fee).
      plugins: [{ id: "file-parser", pdf: { engine: "native" } }],
    }),
    signal: AbortSignal.timeout(90_000),
  });

  if (!response.ok) {
    const detail = await response.text().catch(() => "");
    console.error("OpenRouter error", response.status, detail.slice(0, 800));
    const reason = { 401: "the OPENROUTER_API_KEY is wrong", 402: "your OpenRouter credits ran out", 404: `model "${MODEL()}" isn't available. Check AI_MODEL`, 429: "too many requests, wait a moment" }[response.status];
    throw new Error(reason ? `Couldn't read it: ${reason}.` : `OpenRouter returned ${response.status}. See the terminal for details.`);
  }

  const data = await response.json();
  const text = data.choices?.[0]?.message?.content;
  if (!text) throw new Error("The model returned nothing. Try a clearer photo or scan.");
  return JSON.parse(text.slice(text.indexOf("{"), text.lastIndexOf("}") + 1));
}

/** The 15th character of a GSTIN, worked out from the first 14. */
export function gstinCheckChar(first14) {
  let sum = 0;
  for (let i = 0; i < 14; i++) {
    const product = CHARS.indexOf(first14[i]) * (i % 2 === 0 ? 1 : 2);
    sum += Math.floor(product / 36) + (product % 36);
  }
  return CHARS[(36 - (sum % 36)) % 36];
}

/** Returns { ok, reason, stateCode, pan } for a GSTIN as printed. */
export function validateGstin(value) {
  const gstin = cleanGstin(value);
  if (!gstin) return { ok: false, reason: "missing" };
  if (gstin.length !== 15) return { ok: false, reason: `has ${gstin.length} characters, not 15` };
  if (!FORMAT.test(gstin)) return { ok: false, reason: "is not in the GSTIN format" };
  const stateCode = gstin.slice(0, 2);
  if (!STATES[stateCode]) return { ok: false, reason: `starts with ${stateCode}, which is not a state code` };
  const expected = gstinCheckChar(gstin.slice(0, 14));
  if (gstin[14] !== expected) {
    return { ok: false, reason: `check digit is ${gstin[14]} but should be ${expected}, so a character is wrong` };
  }
  return { ok: true, stateCode, pan: gstin.slice(2, 12) };
}

function taxType(inv) {
  const label = "Right type of GST";
  const from = validateGstin(inv.supplier?.gstin);
  if (!from.ok) return check("tax_type", label, "skip", "Needs a valid supplier GSTIN first.");
  const buyer = validateGstin(inv.buyer?.gstin);
  const to = stateCodeFromText(inv.place_of_supply) ?? (buyer.ok ? buyer.stateCode : null);
  if (!to) return check("tax_type", label, "warn", "Couldn't tell the place of supply, so check CGST/SGST vs IGST by hand.");

  const cgst = num(inv.cgst) ?? 0;
  const sgst = num(inv.sgst) ?? 0;
  const igst = num(inv.igst) ?? 0;
  if (cgst + sgst + igst === 0) return check("tax_type", label, "warn", "No GST charged. Fine if the goods are exempt, otherwise ask the supplier.");

  const fromName = STATES[from.stateCode];
  const toName = STATES[to];
  if (from.stateCode === to) {
    if (igst > 0) return check("tax_type", label, "fail", `Supplier and place of supply are both in ${fromName}, so this should be CGST + SGST, not IGST.`);
    if (!near(cgst, sgst)) return check("tax_type", label, "fail", `CGST (${inr(cgst)}) and SGST (${inr(sgst)}) should be equal.`);
    return check("tax_type", label, "pass", `Both in ${fromName}, so CGST + SGST is right.`);
  }
  if (cgst > 0 || sgst > 0) return check("tax_type", label, "fail", `Supplier is in ${fromName} and place of supply is ${toName}, so this should be IGST, not CGST + SGST.`);
  return check("tax_type", label, "pass", `${fromName} to ${toName}, so IGST is right.`);
}

const GST_RATES = [0.25, 1.5, 3, 5, 12, 18, 28, 40]; // % rates in use, old and new

// ...inside the tax check:
if (!priced.length) {
  // No rate per line: see whether the tax charged is a standard GST rate of the taxable value.
  const base = num(inv.taxable_total) ?? sum(lines.map((line) => line.taxable_value));
  const charged = sum([inv.cgst, inv.sgst, inv.igst]);
  if (!base || !charged) return check("tax_maths", label, "warn", "No GST rates printed, so the tax can't be recalculated.");
  const rate = (charged / base) * 100;
  const slab = GST_RATES.find((r) => near((base * r) / 100, charged));
  return slab !== undefined
    ? check("tax_maths", label, "pass", `${inr(charged)} is exactly ${slab}% of ${inr(base)}, a standard GST rate.`)
    : check("tax_maths", label, "warn", `Tax is ${rate.toFixed(2)}% of the taxable value, which isn't a standard GST rate. Check the bill.`);
}

app.post("/api/save", async (req, res) => {
  const { id, invoice, edited = [] } = req.body ?? {};
  const upload = pending.get(id);
  if (!upload || !invoice) return res.status(404).json({ error: "Read the invoice again, then save." });
  try {
    const checked = await report(invoice); // checked again on the server, never trusted from the page
    const corrected = Array.isArray(edited) ? edited.map(String).slice(0, 20) : [];
    const saved = await saveInvoice(invoice, checked, upload.fileName, corrected);
    pending.delete(id);
    res.json({ ...saved, report: checked, sheetUrl: saved.where === "sheets" ? sheetUrl() : null });
  } catch (error) {
    console.error(error);
    res.status(502).json({ error: `Couldn't save: ${error.message}` });
  }
});

async function appendSheet(client, row) {
  const range = encodeURIComponent(`${TAB()}!A1`);
  await client.request({
    url: api(`/values/${range}:append?valueInputOption=RAW&insertDataOption=INSERT_ROWS`),
    method: "POST",
    data: { values: [row] },
  });
}