feat: (p1)scaffold gst return export tool and (p2)persist raw gstn 2a/2b payload

Author: Priyal Rawal

india_compliance/gst_india/doctype/gst_return_export/__init__.py

@@ -0,0 +1,30 @@
+// Copyright (c) 2026, Resilient Tech and contributors
+// For license information, please see license.txt
+
+// GST Return Export — Phase 1 (GSTR-2A / 2B).
+// Built the Purchase Reconciliation Tool way: a Single DocType whose client
+// script is the tool. Filters are the DocType fields; page actions are Sync and
+// Export; the summary renders into the `summary_html` area (a frappe DataTable
+// in M4). Milestone 1 = scaffold: actions are inert placeholders.
+
+frappe.ui.form.on("GST Return Export", {
+    refresh(frm) {
+        frm.disable_save();
+        render_summary_placeholder(frm);
+    },
+
+    company(frm) {
+        frm.set_value("company_gstin", null);
+    },
+});
+
+function render_summary_placeholder(frm) {
+    const field = frm.get_field("summary_html");
+    if (!field) return;
+
+    field.$wrapper.html(`
+		<div class="text-muted" style="padding: 2.5rem 1rem; text-align: center; border: 1px dashed var(--border-color); border-radius: 8px;">
+			${__("Select Company, GSTIN, GST Return and period, then Sync. The summary will appear here.")}
+		</div>
+	`);
+}

india_compliance/gst_india/doctype/gst_return_export/gst_return_export.js

@@ -0,0 +1,121 @@
+{
+ "actions": [],
+ "allow_copy": 1,
+ "creation": "2026-06-26 00:00:00.000000",
+ "doctype": "DocType",
+ "engine": "InnoDB",
+ "field_order": [
+  "filters_section",
+  "company",
+  "company_gstin",
+  "column_break_filters_1",
+  "gst_return",
+  "column_break_filters_2",
+  "from_date",
+  "to_date",
+  "summary_section",
+  "summary_html"
+ ],
+ "fields": [
+  {
+   "fieldname": "filters_section",
+   "fieldtype": "Section Break",
+   "label": "Select Return"
+  },
+  {
+   "fieldname": "company",
+   "fieldtype": "Link",
+   "label": "Company",
+   "options": "Company",
+   "reqd": 1
+  },
+  {
+   "fieldname": "company_gstin",
+   "fieldtype": "Autocomplete",
+   "label": "Company GSTIN",
+   "reqd": 1
+  },
+  {
+   "fieldname": "column_break_filters_1",
+   "fieldtype": "Column Break"
+  },
+  {
+   "default": "GSTR-2B",
+   "fieldname": "gst_return",
+   "fieldtype": "Select",
+   "label": "GST Return",
+   "options": "GSTR-2A\nGSTR-2B",
+   "reqd": 1
+  },
+  {
+   "fieldname": "column_break_filters_2",
+   "fieldtype": "Column Break"
+  },
+  {
+   "fieldname": "from_date",
+   "fieldtype": "Date",
+   "label": "From Date"
+  },
+  {
+   "fieldname": "to_date",
+   "fieldtype": "Date",
+   "label": "To Date"
+  },
+  {
+   "fieldname": "summary_section",
+   "fieldtype": "Section Break",
+   "label": "Summary"
+  },
+  {
+   "fieldname": "summary_html",
+   "fieldtype": "HTML",
+   "label": "Summary"
+  }
+ ],
+ "hide_toolbar": 1,
+ "index_web_pages_for_search": 1,
+ "issingle": 1,
+ "links": [],
+ "modified": "2026-06-26 00:00:00.000000",
+ "modified_by": "Administrator",
+ "module": "GST India",
+ "name": "GST Return Export",
+ "owner": "Administrator",
+ "permissions": [
+  {
+   "create": 1,
+   "email": 1,
+   "export": 1,
+   "print": 1,
+   "read": 1,
+   "role": "System Manager",
+   "share": 1,
+   "write": 1
+  },
+  {
+   "create": 1,
+   "email": 1,
+   "export": 1,
+   "print": 1,
+   "read": 1,
+   "role": "Accounts Manager",
+   "share": 1,
+   "write": 1
+  },
+  {
+   "create": 1,
+   "email": 1,
+   "export": 1,
+   "print": 1,
+   "read": 1,
+   "role": "Accounts User",
+   "share": 1,
+   "write": 1
+  }
+ ],
+ "quick_entry": 0,
+ "sort_field": "modified",
+ "sort_order": "DESC",
+ "states": [],
+ "track_changes": 0
+}

india_compliance/gst_india/doctype/gst_return_export/gst_return_export.json

@@ -0,0 +1,20 @@
+# Copyright (c) 2026, Resilient Tech and contributors
+# For license information, please see license.txt
+
+from frappe.model.document import Document
+
+
+class GSTReturnExport(Document):
+    """
+    GST Return Export tool — Phase 1 (GSTR-2A / 2B).
+
+    Milestone 1: scaffolding only. This Single DocType holds the user's filter
+    selection (company, GSTIN, GST return, period). The actual behaviour lands
+    in later milestones:
+      - Sync from GSTN  -> M3 (single period), M6 (range)
+      - Prepared summary -> M4
+      - Export to Excel  -> M5
+    Raw GSTN payloads are persisted via india_compliance.gst_india.utils.returns_export.
+    """
+
+    pass

india_compliance/gst_india/doctype/gst_return_export/gst_return_export.py

@@ -14,7 +14,8 @@
   "data_not_found",
   "dont_redownload",
   "request_id",
-  "request_time"
+  "request_time",
+  "raw_data"
  ],
  "fields": [
   {
@@ -70,6 +71,15 @@
    "fieldname": "dont_redownload",
    "fieldtype": "Check",
    "label": "Redownload not Required"
+  },
+  {
+   "description": "Raw GSTN payload (gzipped) stored for the GST Return Export tool",
+   "fieldname": "raw_data",
+   "fieldtype": "Attach",
+   "hidden": 1,
+   "label": "Raw Data",
+   "no_copy": 1,
+   "read_only": 1
   }
  ],
  "index_web_pages_for_search": 1,

india_compliance/gst_india/doctype/gstr_import_log/gstr_import_log.json

@@ -19,7 +19,22 @@ def create_import_log(
     dont_redownload=False,
     request_id=None,
     retry_after_mins=None,
+    raw_data=None,
 ):
+
+    if raw_data is not None:
+        return _create_import_log(
+            gstin,
+            return_type,
+            return_period,
+            classification,
+            data_not_found,
+            dont_redownload,
+            request_id,
+            retry_after_mins,
+            raw_data=raw_data,
+        )
+
     frappe.enqueue(
         _create_import_log,
         queue="short",
@@ -44,6 +59,7 @@ def _create_import_log(
     dont_redownload=False,
     request_id=None,
     retry_after_mins=None,
+    raw_data=None,
 ):
     doctype = "GSTR Import Log"
     fields = {
@@ -68,10 +84,89 @@ def _create_import_log(
     log.dont_redownload = dont_redownload
     log.last_updated_on = frappe.utils.now()
     log.save(ignore_permissions=True)
+
+    if raw_data is not None:
+        _attach_raw_data(log, raw_data)
+
     if request_id:
         toggle_scheduled_jobs(False)
 
 
+def _attach_raw_data(log, json_data):
+    """
+    Attach raw GSTN payload to the Import Log row for the GST Return Export tool.
+    Always replaces. Caller must pre-merge GSTR-2B chunks before passing them here.
+    """
+    from india_compliance.gst_india.doctype.gst_return_log.gst_return_log import (
+        get_compressed_data,
+        get_file_doc,
+    )
+
+    content = get_compressed_data(json_data)
+
+    if file := get_file_doc(log.doctype, log.name, "raw_data"):
+        file.save_file(content=content, overwrite=True)
+    else:
+        file = frappe.get_doc(
+            {
+                "doctype": "File",
+                "attached_to_doctype": log.doctype,
+                "attached_to_name": log.name,
+                "attached_to_field": "raw_data",
+                "file_name": frappe.scrub(f"{log.name}-raw_data.json.gz"),
+                "is_private": 1,
+                "content": content,
+            }
+        ).insert(ignore_permissions=True)
+
+    log.db_set("raw_data", file.file_url)
+    return file
+
+
+def get_import_log_raw(gstin, return_type, return_period, classification=None):
+    """Return the stored raw GSTN payload (parsed), or None if not stored yet."""
+    from india_compliance.gst_india.doctype.gst_return_log.gst_return_log import (
+        get_decompressed_data,
+        get_file_doc,
+    )
+
+    doctype = "GSTR Import Log"
+    fields = {
+        "gstin": gstin,
+        "return_type": return_type,
+        "return_period": return_period,
+    }
+    if classification:
+        fields["classification"] = classification
+
+    name = frappe.db.get_value(doctype, fields)
+    if not name:
+        return None
+
+    file = get_file_doc(doctype, name, "raw_data")
+    if not file:
+        return None
+
+    return get_decompressed_data(file.get_content(encodings=[]))
+
+
+def merge_raw_payloads(existing, new):
+    """Merge a new raw chunk onto an existing one (for GSTR-2B multi-file)."""
+    if isinstance(existing, dict) and isinstance(new, dict):
+        merged = dict(existing)
+        for key, value in new.items():
+            if isinstance(merged.get(key), list) and isinstance(value, list):
+                merged[key] = merged[key] + value
+            else:
+                merged[key] = value
+        return merged
+
+    if isinstance(existing, list) and isinstance(new, list):
+        return existing + new
+
+    return new
+
+
 def toggle_scheduled_jobs(stopped):
     scheduled_job = frappe.db.get_value(
         "Scheduled Job Type",

india_compliance/gst_india/doctype/gstr_import_log/gstr_import_log.py

@@ -20,6 +20,7 @@
 from india_compliance.gst_india.utils import get_party_for_gstin
 from india_compliance.gst_india.utils.gstr_2 import gstr_2a, gstr_2b, ims
 from india_compliance.gst_india.utils.gstr_utils import ReturnType
+from india_compliance.gst_india.utils.returns_export import merge_raw
 
 
 class GSTRCategory(Enum):
@@ -207,10 +208,15 @@ def download_gstr_2b(gstin, return_periods):
 
         # Handle multiple files for GSTR2B
         if response.data and (file_count := response.data.get("fc")):
+            merged_docdata = {}
             for file_num in range(1, file_count + 1):
                 r = api.get_data(return_period, file_num=file_num)
-                save_gstr_2b(gstin, return_period, r)
+                # merge raw chunks in memory; let save_gstr_2b skip the raw write
+                merged_docdata = merge_raw(merged_docdata, r.data.get("docdata") or {})
+                save_gstr_2b(gstin, return_period, r, store_raw=False)
 
+            # write the merged raw payload once (no repeated decompress/recompress)
+            create_import_log(gstin, ReturnType.GSTR2B.value, return_period, raw_data=merged_docdata)
             continue  # skip first response if file_count is greater than 1
 
         save_gstr_2b(gstin, return_period, response)
@@ -293,15 +299,21 @@ def save_gstr_2a(gstin, return_period, json_data):
         if action.lower() not in json_data:
             continue
 
-        create_import_log(gstin, return_type.value, return_period, classification=category.value)
+        create_import_log(
+            gstin,
+            return_type.value,
+            return_period,
+            classification=category.value,
+            raw_data=json_data.get(action.lower()),
+        )
 
         # making consistent with GSTR2b
         json_data[category.value.lower()] = json_data.pop(action.lower())
 
     save_gstr(gstin, return_type, return_period, json_data)
 
 
-def save_gstr_2b(gstin, return_period, json_data):
+def save_gstr_2b(gstin, return_period, json_data, *, store_raw=True):
     json_data = json_data.data
     return_type = ReturnType.GSTR2B
     if not json_data or json_data.get("gstin") != gstin:
@@ -313,7 +325,15 @@ def save_gstr_2b(gstin, return_period, json_data):
             title=_("Invalid Response Received."),
         )
 
-    create_import_log(gstin, return_type.value, return_period)
+    if store_raw:
+        create_import_log(
+            gstin,
+            return_type.value,
+            return_period,
+            raw_data=json_data.get("docdata") or {},
+        )
+    else:
+        create_import_log(gstin, return_type.value, return_period)
     save_gstr(
         gstin,
         return_type,