From aaeff805479f973bd8631b2b8b845386626ff39e Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 9 Feb 2025 18:37:05 +0800
Subject: [PATCH 01/36] Remove TODO flag as it is fixed already

---
 Whatsapp_Chat_Exporter/ios_handler.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Whatsapp_Chat_Exporter/ios_handler.py b/Whatsapp_Chat_Exporter/ios_handler.py
index 97b0c88..2724392 100644
--- a/Whatsapp_Chat_Exporter/ios_handler.py
+++ b/Whatsapp_Chat_Exporter/ios_handler.py
@@ -149,7 +149,7 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
         message = Message(
             from_me=content["ZISFROMME"],
             timestamp=ts,
-            time=ts, # TODO: Could be bug
+            time=ts,
             key_id=content["ZSTANZAID"][:17],
             timezone_offset=timezone_offset if timezone_offset else CURRENT_TZ_OFFSET,
             message_type=content["ZMESSAGETYPE"]

From cfe04c8c0bd663040aea3e92cbedf78467523c53 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 9 Feb 2025 18:44:18 +0800
Subject: [PATCH 02/36] Display the metadata from the messages sent by "me"
 (#69)

For now, only the time for "delivered" (android & ios) and "read" (android only)  is support.
---
 Whatsapp_Chat_Exporter/android_handler.py | 21 +++++-----
 Whatsapp_Chat_Exporter/data_model.py      | 32 +++++++++++++--
 Whatsapp_Chat_Exporter/ios_handler.py     |  7 +++-
 Whatsapp_Chat_Exporter/whatsapp_new.html  | 47 ++++++++++++++++++++++-
 4 files changed, 89 insertions(+), 18 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/android_handler.py b/Whatsapp_Chat_Exporter/android_handler.py
index 0713232..0948fcd 100644
--- a/Whatsapp_Chat_Exporter/android_handler.py
+++ b/Whatsapp_Chat_Exporter/android_handler.py
@@ -230,11 +230,8 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                             jid_old.raw_string as old_jid,
                             jid_new.raw_string as new_jid,
                             jid_global.type as jid_type,
-                            group_concat(receipt_user.receipt_timestamp) as receipt_timestamp,
-                            group_concat(messages.received_timestamp) as received_timestamp,
-                            group_concat(receipt_user.read_timestamp) as read_timestamp,
-                            group_concat(receipt_user.played_timestamp) as played_timestamp,
-                            group_concat(messages.read_device_timestamp) as read_device_timestamp
+                            COALESCE(receipt_user.receipt_timestamp, messages.received_timestamp) as received_timestamp,
+                            COALESCE(receipt_user.read_timestamp, receipt_user.played_timestamp, messages.read_device_timestamp) as read_timestamp
                     FROM messages
                         LEFT JOIN messages_quotes
                             ON messages.quoted_row_id = messages_quotes._id
@@ -290,10 +287,8 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                             jid_old.raw_string as old_jid,
                             jid_new.raw_string as new_jid,
                             jid_global.type as jid_type,
-                            group_concat(receipt_user.receipt_timestamp) as receipt_timestamp,
-                            group_concat(message.received_timestamp) as received_timestamp,
-                            group_concat(receipt_user.read_timestamp) as read_timestamp,
-                            group_concat(receipt_user.played_timestamp) as played_timestamp
+                            COALESCE(receipt_user.receipt_timestamp, message.received_timestamp) as received_timestamp,
+                            COALESCE(receipt_user.read_timestamp, receipt_user.played_timestamp) as read_timestamp
                     FROM message
                         LEFT JOIN message_quoted
                             ON message_quoted.message_row_id = message._id
@@ -361,7 +356,9 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
             time=content["timestamp"],
             key_id=content["key_id"],
             timezone_offset=timezone_offset if timezone_offset else CURRENT_TZ_OFFSET,
-            message_type=content["media_wa_type"]
+            message_type=content["media_wa_type"],
+            received_timestamp=content["received_timestamp"],
+            read_timestamp=content["read_timestamp"]
         )
         if isinstance(content["data"], bytes):
             message.data = ("The message is binary data and its base64 is "
@@ -736,7 +733,9 @@ def calls(db, data, timezone_offset, filter_chat):
             timestamp=content["timestamp"],
             time=content["timestamp"],
             key_id=content["call_id"],
-            timezone_offset=timezone_offset if timezone_offset else CURRENT_TZ_OFFSET
+            timezone_offset=timezone_offset if timezone_offset else CURRENT_TZ_OFFSET,
+            received_timestamp=None, # TODO: Add timestamp
+            read_timestamp=None # TODO: Add timestamp
         )
         _jid = content["raw_string"]
         name = data[_jid].name if _jid in data else content["chat_subject"] or None
diff --git a/Whatsapp_Chat_Exporter/data_model.py b/Whatsapp_Chat_Exporter/data_model.py
index f08acca..ee4d066 100644
--- a/Whatsapp_Chat_Exporter/data_model.py
+++ b/Whatsapp_Chat_Exporter/data_model.py
@@ -5,6 +5,18 @@ from datetime import datetime, tzinfo, timedelta
 from typing import Union
 
 
+class Timing():
+    def __init__(self, timezone_offset: Union[int, None]):
+        self.timezone_offset = timezone_offset
+
+    def format_timestamp(self, timestamp, format):
+        if timestamp:
+            timestamp = timestamp / 1000 if timestamp > 9999999999 else timestamp
+            return datetime.fromtimestamp(timestamp, TimeZone(self.timezone_offset)).strftime(format)
+        else:
+            return None
+
+
 class TimeZone(tzinfo):
     def __init__(self, offset):
         self.offset = offset
@@ -65,11 +77,23 @@ class ChatStore():
 
 
 class Message():
-    def __init__(self, from_me: Union[bool,int], timestamp: int, time: Union[int,float,str], key_id: int, timezone_offset: int = 0, message_type: int = None):
+    def __init__(
+            self,
+            *,
+            from_me: Union[bool,int],
+            timestamp: int,
+            time: Union[int,float,str],
+            key_id: int,
+            received_timestamp: int,
+            read_timestamp: int,
+            timezone_offset: int = 0,
+            message_type: int = None
+        ):
         self.from_me = bool(from_me)
         self.timestamp = timestamp / 1000 if timestamp > 9999999999 else timestamp
+        timing = Timing(timezone_offset)
         if isinstance(time, int) or isinstance(time, float):
-            self.time = datetime.fromtimestamp(self.timestamp, TimeZone(timezone_offset)).strftime("%H:%M")
+            self.time = timing.format_timestamp(self.timestamp, "%H:%M")
         elif isinstance(time, str):
             self.time = time
         else:
@@ -81,7 +105,9 @@ class Message():
         self.sender = None
         self.safe = False
         self.mime = None
-        self.message_type = message_type
+        self.message_type = message_type,
+        self.received_timestamp = timing.format_timestamp(received_timestamp, "%Y/%m/%d %H:%M")
+        self.read_timestamp = timing.format_timestamp(read_timestamp, "%Y/%m/%d %H:%M") 
         # Extra
         self.reply = None
         self.quoted_data = None
diff --git a/Whatsapp_Chat_Exporter/ios_handler.py b/Whatsapp_Chat_Exporter/ios_handler.py
index 2724392..1c72072 100644
--- a/Whatsapp_Chat_Exporter/ios_handler.py
+++ b/Whatsapp_Chat_Exporter/ios_handler.py
@@ -114,7 +114,8 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                         ZWAGROUPMEMBER.ZMEMBERJID,
 						ZMETADATA,
                         ZSTANZAID,
-                        ZGROUPINFO
+                        ZGROUPINFO,
+                        ZSENTDATE
                  FROM ZWAMESSAGE
                     LEFT JOIN ZWAGROUPMEMBER
                         ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
@@ -152,7 +153,9 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
             time=ts,
             key_id=content["ZSTANZAID"][:17],
             timezone_offset=timezone_offset if timezone_offset else CURRENT_TZ_OFFSET,
-            message_type=content["ZMESSAGETYPE"]
+            message_type=content["ZMESSAGETYPE"],
+            received_timestamp=APPLE_TIME + content["ZSENTDATE"] if content["ZSENTDATE"] else None,
+            read_timestamp=None # TODO: Add timestamp
         )
         invalid = False
         if is_group_message and content["ZISFROMME"] == 0:
diff --git a/Whatsapp_Chat_Exporter/whatsapp_new.html b/Whatsapp_Chat_Exporter/whatsapp_new.html
index 7502a7b..2aa2b7e 100644
--- a/Whatsapp_Chat_Exporter/whatsapp_new.html
+++ b/Whatsapp_Chat_Exporter/whatsapp_new.html
@@ -123,6 +123,10 @@
         .reply-box:active {
             background-color:rgb(200 202 205 / var(--tw-bg-opacity, 1));
         }
+        .info-box-tooltip {
+            --tw-translate-x: -50%;
+            transform: translate(var(--tw-translate-x), var(--tw-translate-y)) rotate(var(--tw-rotate)) skewX(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y));
+        }
         </style>
         <script>
             function search(event) {
@@ -207,7 +211,25 @@
                         {% endif %}
                         <!--Actual messages-->
                         {% if msg.from_me == true %}
-                        <div class="flex justify-end" id="{{ msg.key_id }}">
+                        <div class="flex justify-end items-center group" id="{{ msg.key_id }}">
+                            <div class="opacity-0 group-hover:opacity-100 transition-opacity duration-200 relative mr-2">
+                                <div class="relative">
+                                    <div class="relative group/tooltip">
+                                        <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5 text-[#8696a0] hover:text-[#54656f] cursor-pointer" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                                            <use href="#info-icon"></use>
+                                        </svg>
+                                        <div class="absolute bottom-full info-box-tooltip mb-2 hidden group-hover/tooltip:block z-50">
+                                            <div class="bg-black text-white text-xs rounded py-1 px-2 whitespace-nowrap">
+                                                Delivered at {{msg.received_timestamp or 'unknown'}}
+                                                {% if msg.read_timestamp is not none %}
+                                                <br>Read at {{ msg.read_timestamp }}
+                                                {% endif %}
+                                            </div>
+                                            <div class="absolute top-full right-3 -mt-1 border-4 border-transparent border-t-black"></div>
+                                        </div>
+                                    </div>
+                                </div>
+                            </div>
                             <div class="bg-whatsapp-light rounded-lg p-2 max-w-[80%] shadow-sm">
                                 {% if msg.reply is not none %}
                                 <a href="#{{msg.reply}}" target="_self" class="no-base">
@@ -268,7 +290,7 @@
                             </div>
                         </div>
                         {% else %}
-                        <div class="flex justify-start" id="{{ msg.key_id }}">
+                        <div class="flex justify-start items-center group" id="{{ msg.key_id }}">
                             <div class="bg-white rounded-lg p-2 max-w-[80%] shadow-sm">
                                 {% if msg.reply is not none %}
                                 <a href="#{{msg.reply}}" target="_self" class="no-base">
@@ -335,6 +357,21 @@
                                     <span class="flex-shrink-0">{{ msg.time }}</span>
                                     </div>
                             </div>
+                            <!-- <div class="opacity-0 group-hover:opacity-100 transition-opacity duration-200 relative ml-2">
+                                <div class="relative">
+                                    <div class="relative group/tooltip">
+                                        <svg xmlns="http://www.w3.org/2000/svg" class="h-5 w-5 text-[#8696a0] hover:text-[#54656f] cursor-pointer" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                                            <use href="#info-icon"></use>
+                                        </svg>
+                                        <div class="absolute bottom-full info-box-tooltip mb-2 hidden group-hover/tooltip:block z-50">
+                                            <div class="bg-black text-white text-xs rounded py-1 px-2 whitespace-nowrap">
+                                                Received at {{msg.received_timestamp or 'unknown'}}
+                                            </div>
+                                            <div class="absolute top-full right-3 ml-1 border-4 border-transparent border-t-black"></div>
+                                        </div>
+                                    </div>
+                                </div>
+                            </div> -->
                         </div>
                         {% endif %}
                     {% endfor %}
@@ -348,6 +385,12 @@
                     <br>
                     Portions of this page are reproduced from <a href="https://web.dev/articles/lazy-loading-video">work</a> created and <a href="https://developers.google.com/readme/policies">shared by Google</a> and used according to terms described in the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache 2.0 License</a>. 
                 </footer>
+                <svg style="display: none;">
+                    <!-- Tooltip info icon -->
+                    <symbol id="info-icon" viewBox="0 0 24 24">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+                    </symbol>
+                </svg>
             </div>
         </article>
     </body>

From 0cbae4d2768a6ec49f2bef32f08e7a9011f6f09a Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Tue, 11 Feb 2025 00:52:05 +0800
Subject: [PATCH 03/36] Create a script to process Brazilian numbers in vcards
 #127

---
 scripts/brazilian-number-processing.py | 100 +++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 scripts/brazilian-number-processing.py

diff --git a/scripts/brazilian-number-processing.py b/scripts/brazilian-number-processing.py
new file mode 100644
index 0000000..2638a99
--- /dev/null
+++ b/scripts/brazilian-number-processing.py
@@ -0,0 +1,100 @@
+import re
+import argparse
+
+def process_phone_number(raw_phone):
+    """
+    Process the raw phone string from the VCARD and return two formatted numbers:
+      - The original formatted number, and
+      - A modified formatted number with the extra (ninth) digit removed, if applicable.
+      
+    Desired output:
+      For a number with a 9-digit subscriber:
+         Original: "+55 {area} {first 5 of subscriber}-{last 4 of subscriber}"
+         Modified: "+55 {area} {subscriber[1:5]}-{subscriber[5:]}" 
+      For example, for an input that should represent "027912345678", the outputs are:
+         "+55 27 91234-5678"  and  "+55 27 1234-5678"
+    
+    This function handles numbers that may already include a "+55" prefix.
+    It expects that after cleaning, a valid number (without the country code) should have either 10 digits 
+    (2 for area + 8 for subscriber) or 11 digits (2 for area + 9 for subscriber).
+    If extra digits are present, it takes the last 11 (or 10) digits.
+    """
+    # If the number starts with '+55', remove it for processing.
+    number_to_process = raw_phone.strip()
+    if number_to_process.startswith("+55"):
+        number_to_process = number_to_process[3:].strip()
+    
+    # Remove all non-digit characters.
+    digits = re.sub(r'\D', '', number_to_process)
+    
+    # Remove trunk zero if present.
+    if digits.startswith("0"):
+        digits = digits[1:]
+    
+    # After cleaning, we expect a valid number to have either 10 or 11 digits.
+    # If there are extra digits, use the last 11 (for a 9-digit subscriber) or last 10 (for an 8-digit subscriber).
+    if len(digits) > 11:
+        # Here, we assume the valid number is the last 11 digits.
+        digits = digits[-11:]
+    elif len(digits) == 12:
+        # In some cases with an 8-digit subscriber, take the last 10 digits.
+        digits = digits[-10:]
+    
+    if len(digits) not in (10, 11):
+        return None, None
+
+    area = digits[:2]
+    subscriber = digits[2:]
+
+    if len(subscriber) == 9:
+        # Format the original number (5-4 split, e.g., "91234-5678")
+        orig_subscriber = f"{subscriber[:5]}-{subscriber[5:]}"
+        # Create a modified version: drop the first digit of the subscriber to form an 8-digit subscriber (4-4 split)
+        mod_subscriber = f"{subscriber[1:5]}-{subscriber[5:]}"
+        original_formatted = f"+55 {area} {orig_subscriber}"
+        modified_formatted = f"+55 {area} {mod_subscriber}"
+    elif len(subscriber) == 8:
+        original_formatted = f"+55 {area} {subscriber[:4]}-{subscriber[4:]}"
+        modified_formatted = None
+
+    return original_formatted, modified_formatted
+
+def process_vcard(input_vcard, output_vcard):
+    with open(input_vcard, 'r', encoding='utf-8') as file:
+        lines = file.readlines()
+    
+    output_lines = []
+    
+    # Regex to capture any telephone line.
+    # It matches lines starting with "TEL:" or "TEL;TYPE=..." or with prefixes like "item1.TEL:".
+    phone_pattern = re.compile(r'^(?P<prefix>(?:TEL(?:;TYPE=[^:]+)?|(?:.*\.)?TEL)):(?P<number>.*)$')
+    
+    for line in lines:
+        stripped_line = line.rstrip("\n")
+        match = phone_pattern.match(stripped_line)
+        if match:
+            raw_phone = match.group("number").strip()
+            orig_formatted, mod_formatted = process_phone_number(raw_phone)
+            if orig_formatted:
+                # Always output using the standardized prefix.
+                output_lines.append(f"TEL;TYPE=CELL:{orig_formatted}\n")
+            else:
+                output_lines.append(line)
+            if mod_formatted:
+                output_lines.append(f"TEL;TYPE=CELL:{mod_formatted}\n")
+        else:
+            output_lines.append(line)
+    
+    with open(output_vcard, 'w', encoding='utf-8') as file:
+        file.writelines(output_lines)
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(
+        description="Process a VCARD file to standardize telephone entries and add a second TEL line with the modified number (removing the extra ninth digit) for contacts with 9-digit subscribers."
+    )
+    parser.add_argument('input_vcard', type=str, help='Input VCARD file')
+    parser.add_argument('output_vcard', type=str, help='Output VCARD file')
+    args = parser.parse_args()
+    
+    process_vcard(args.input_vcard, args.output_vcard)
+    print(f"VCARD processed and saved to {args.output_vcard}")
\ No newline at end of file

From 8c85656831e6b1b678c036bc90a795fcae8c305b Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Thu, 20 Feb 2025 23:46:26 +0800
Subject: [PATCH 04/36] Show different warning messages when enrich_from_vcards
 is set and contact db is empty

---
 Whatsapp_Chat_Exporter/__main__.py        | 2 +-
 Whatsapp_Chat_Exporter/android_handler.py | 7 +++++--
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/__main__.py b/Whatsapp_Chat_Exporter/__main__.py
index d8d9b2a..f747a05 100644
--- a/Whatsapp_Chat_Exporter/__main__.py
+++ b/Whatsapp_Chat_Exporter/__main__.py
@@ -472,7 +472,7 @@ def main():
         if os.path.isfile(contact_db):
             with sqlite3.connect(contact_db) as db:
                 db.row_factory = sqlite3.Row
-                contacts(db, data)
+                contacts(db, data, args.enrich_from_vcards)
     elif args.ios:
         contacts = ios_handler.contacts
         messages = ios_handler.messages
diff --git a/Whatsapp_Chat_Exporter/android_handler.py b/Whatsapp_Chat_Exporter/android_handler.py
index 0948fcd..f11703e 100644
--- a/Whatsapp_Chat_Exporter/android_handler.py
+++ b/Whatsapp_Chat_Exporter/android_handler.py
@@ -153,13 +153,16 @@ def decrypt_backup(database, key, output, crypt=Crypt.CRYPT14, show_crypt15=Fals
             raise ValueError("The plaintext is not a SQLite database. Did you use the key to encrypt something...")
 
 
-def contacts(db, data):
+def contacts(db, data, enrich_from_vcards):
     # Get contacts
     c = db.cursor()
     c.execute("""SELECT count() FROM wa_contacts""")
     total_row_number = c.fetchone()[0]
     if total_row_number == 0:
-        print("No contacts profiles found in the default database, consider using --enrich-from-vcards for adopting names from exported contacts from Google")
+        if enrich_from_vcards is not None:
+            print("No contacts profiles found in the default database, contacts will be imported from the specified vCard file.")
+        else:
+            print("No contacts profiles found in the default database, consider using --enrich-from-vcards for adopting names from exported contacts from Google")
         return False
     else:
         print(f"Processing contacts...({total_row_number})")

From d6b1d944bf303fd31a31d683691eae26e52b561e Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Fri, 21 Feb 2025 22:47:52 +0800
Subject: [PATCH 05/36] Implement dry-run for decrypting Android backup #130

---
 Whatsapp_Chat_Exporter/android_handler.py | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/android_handler.py b/Whatsapp_Chat_Exporter/android_handler.py
index f11703e..b21602d 100644
--- a/Whatsapp_Chat_Exporter/android_handler.py
+++ b/Whatsapp_Chat_Exporter/android_handler.py
@@ -53,9 +53,11 @@ def _extract_encrypted_key(keyfile):
     return _generate_hmac_of_hmac(key_stream)
 
 
-def decrypt_backup(database, key, output, crypt=Crypt.CRYPT14, show_crypt15=False, db_type=DbType.MESSAGE):
+def decrypt_backup(database, key, output=None, crypt=Crypt.CRYPT14, show_crypt15=False, db_type=DbType.MESSAGE, dry_run=False):
     if not support_backup:
         return 1
+    if not dry_run and output is None:
+        ValueError("The path to the decrypted database must be specified unless dry_run is true.")
     if isinstance(key, io.IOBase):
         key = key.read()
         if crypt is not Crypt.CRYPT15:
@@ -146,8 +148,9 @@ def decrypt_backup(database, key, output, crypt=Crypt.CRYPT14, show_crypt15=Fals
         else:
             decompressed = True
         if db[0:6].upper() == b"SQLITE":
-            with open(output, "wb") as f:
-                f.write(db)
+            if not dry_run:
+                with open(output, "wb") as f:
+                    f.write(db)
             return 0
         else:
             raise ValueError("The plaintext is not a SQLite database. Did you use the key to encrypt something...")

From b9f811c147d84433f00ffa76b27429282607159e Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sat, 22 Feb 2025 18:14:15 +0800
Subject: [PATCH 06/36] Add documentations, refactor and implement crypt15 key
 dynamical input

---
 Whatsapp_Chat_Exporter/__main__.py        | 18 ++++---
 Whatsapp_Chat_Exporter/android_handler.py | 62 ++++++++++++++++++++---
 2 files changed, 67 insertions(+), 13 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/__main__.py b/Whatsapp_Chat_Exporter/__main__.py
index f747a05..1794597 100644
--- a/Whatsapp_Chat_Exporter/__main__.py
+++ b/Whatsapp_Chat_Exporter/__main__.py
@@ -21,6 +21,7 @@ from Whatsapp_Chat_Exporter.utility import APPLE_TIME, Crypt, DbType, readable_t
 from Whatsapp_Chat_Exporter.utility import import_from_json, sanitize_filename, bytes_to_readable
 from argparse import ArgumentParser, SUPPRESS
 from datetime import datetime
+from getpass import getpass
 from sys import exit
 import importlib.metadata
 
@@ -114,7 +115,8 @@ def main():
         '--key',
         dest='key',
         default=None,
-        help="Path to key file"
+        nargs='?',
+        help="Path to key file. If this option is set for crypt15 backup but nothing is specified, you will be prompted to enter the key."
     )
     parser.add_argument(
         "-t",
@@ -384,6 +386,8 @@ def main():
                     args.filter_date = f"<= {_timestamp - APPLE_TIME}"
             else:
                 parser.error("Unsupported date format. See https://wts.knugi.dev/docs?dest=date")
+    if args.key is None and args.backup is not None and args.backup.endswith("crypt15"):
+        args.key = getpass("Enter your encryption key: ")
     if args.whatsapp_theme:
         args.template = "whatsapp_new.html"
     if args.filter_chat_include is not None and args.filter_chat_exclude is not None:
@@ -435,19 +439,21 @@ def main():
                 crypt = Crypt.CRYPT14
             elif "crypt15" in args.backup:
                 crypt = Crypt.CRYPT15
-            if os.path.isfile(args.key):
+            if not os.path.isfile(args.key) and all(char in string.hexdigits for char in args.key.replace(" ", "")):
+                key = bytes.fromhex(args.key.replace(" ", ""))
+                key_stream = False
+            else:
                 key = open(args.key, "rb")
-            elif all(char in string.hexdigits for char in args.key):
-                key = bytes.fromhex(args.key)
+                key_stream = True
             db = open(args.backup, "rb").read()
             if args.wab:
                 wab = open(args.wab, "rb").read()
-                error_wa = android_handler.decrypt_backup(wab, key, contact_db, crypt, args.showkey, DbType.CONTACT)
+                error_wa = android_handler.decrypt_backup(wab, key, key_stream, contact_db, crypt, args.showkey, DbType.CONTACT)
                 if isinstance(key, io.IOBase):
                     key.seek(0)
             else:
                 error_wa = 0
-            error_message = android_handler.decrypt_backup(db, key, msg_db, crypt, args.showkey, DbType.MESSAGE)               
+            error_message = android_handler.decrypt_backup(db, key, key_stream, msg_db, crypt, args.showkey, DbType.MESSAGE)               
             if error_wa != 0:
                 error = error_wa
             elif error_message != 0:
diff --git a/Whatsapp_Chat_Exporter/android_handler.py b/Whatsapp_Chat_Exporter/android_handler.py
index b21602d..c185034 100644
--- a/Whatsapp_Chat_Exporter/android_handler.py
+++ b/Whatsapp_Chat_Exporter/android_handler.py
@@ -7,6 +7,7 @@ import hmac
 import shutil
 from pathlib import Path
 from mimetypes import MimeTypes
+from typing import Tuple, Union
 from markupsafe import escape as htmle
 from hashlib import sha256
 from base64 import b64decode, b64encode
@@ -32,7 +33,16 @@ else:
     support_crypt15 = True
 
 
-def _generate_hmac_of_hmac(key_stream):
+def _derive_main_enc_key(key_stream: bytes) -> Tuple[bytes, bytes]:
+    """
+    Derive the main encryption key for the given key stream. The key is derived using HMAC of HMAC of the provided key stream.
+
+    Args:
+        key_stream (bytes): The key stream to generate HMAC of HMAC.
+
+    Returns:
+        Tuple[bytes, bytes]: A tuple containing the main encryption key and the original key stream.
+    """
     key = hmac.new(
         hmac.new(
             b'\x00' * 32,
@@ -45,15 +55,53 @@ def _generate_hmac_of_hmac(key_stream):
     return key.digest(), key_stream
 
 
-def _extract_encrypted_key(keyfile):
+def _extract_enc_key(keyfile: bytes) -> Tuple[bytes, bytes]:
+    """
+    Extract the encryption key from the keyfile.
+
+    Args:
+        keyfile (bytes): The keyfile containing the encrypted key.
+
+    Returns:
+        Tuple[bytes, bytes]: values from _derive_main_enc_key()
+    """
     key_stream = b""
     for byte in javaobj.loads(keyfile):
         key_stream += byte.to_bytes(1, "big", signed=True)
 
-    return _generate_hmac_of_hmac(key_stream)
+    return _derive_main_enc_key(key_stream)
 
 
-def decrypt_backup(database, key, output=None, crypt=Crypt.CRYPT14, show_crypt15=False, db_type=DbType.MESSAGE, dry_run=False):
+def decrypt_backup(
+    database: bytes,
+    key: Union[str, io.IOBase],
+    output: str = None,
+    crypt: Crypt = Crypt.CRYPT14,
+    show_crypt15: bool = False,
+    db_type: DbType = DbType.MESSAGE,
+    dry_run: bool = False,
+    key_stream: bool = False
+) -> int:
+    """
+    Decrypt the WhatsApp backup database.
+
+    Args:
+        database (bytes): The encrypted database file.
+        key (str or io.IOBase): The key to decrypt the database. The key should either be a string (32 bytes hex key) or a file object (encryption key file).
+        key_stream (bool, optional): Whether the key is a key stream. False for hex key. True for key stream.
+        output (str, optional): The path to save the decrypted database. Defaults to None. When dry_run is True, this parameter is ignored.
+        crypt (Crypt, optional): The encryption version of the database. Defaults to Crypt.CRYPT14.
+        show_crypt15 (bool, optional): Whether to show the HEX key of the crypt15 backup. Defaults to False.
+        db_type (DbType, optional): The type of database (MESSAGE or CONTACT). Defaults to DbType.MESSAGE.
+        dry_run (bool, optional): Whether to perform a dry run without saving the decrypted database. Defaults to False.
+
+    Returns:
+        int: The status code of the decryption process.
+            - 0: The decryption process was successful.
+            - 1: The decryption process failed because the necessary dependencies for backup decryption are not available.
+            - 2: The decryption process failed because the common offsets for the IV and database are not applicable, and the brute force attempt to find the correct offsets also failed.
+            - 3: The decryption process failed due to unknown error
+    """
     if not support_backup:
         return 1
     if not dry_run and output is None:
@@ -97,10 +145,10 @@ def decrypt_backup(database, key, output=None, crypt=Crypt.CRYPT14, show_crypt15
         raise ValueError("The signature of key file and backup file mismatch")
 
     if crypt == Crypt.CRYPT15:
-        if len(key) == 32:
-            main_key, hex_key = _generate_hmac_of_hmac(key)
+        if key_stream:
+            main_key, hex_key = _extract_enc_key(key)
         else:
-            main_key, hex_key = _extract_encrypted_key(key)
+            main_key, hex_key = _derive_main_enc_key(key)
         if show_crypt15:
             hex_key = [hex_key.hex()[c:c+4] for c in range(0, len(hex_key.hex()), 4)]
             print("The HEX key of the crypt15 backup is: " + ' '.join(hex_key))

From 26abfdd570624cb04549b107522bfa05cac739d2 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Wed, 26 Feb 2025 21:14:50 +0800
Subject: [PATCH 07/36] Bug fix on argument positions

---
 Whatsapp_Chat_Exporter/__main__.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/__main__.py b/Whatsapp_Chat_Exporter/__main__.py
index 1794597..611df91 100644
--- a/Whatsapp_Chat_Exporter/__main__.py
+++ b/Whatsapp_Chat_Exporter/__main__.py
@@ -448,12 +448,12 @@ def main():
             db = open(args.backup, "rb").read()
             if args.wab:
                 wab = open(args.wab, "rb").read()
-                error_wa = android_handler.decrypt_backup(wab, key, key_stream, contact_db, crypt, args.showkey, DbType.CONTACT)
+                error_wa = android_handler.decrypt_backup(wab, key, contact_db, crypt, args.showkey, DbType.CONTACT, key_stream)
                 if isinstance(key, io.IOBase):
                     key.seek(0)
             else:
                 error_wa = 0
-            error_message = android_handler.decrypt_backup(db, key, key_stream, msg_db, crypt, args.showkey, DbType.MESSAGE)               
+            error_message = android_handler.decrypt_backup(db, key, msg_db, crypt, args.showkey, DbType.MESSAGE, key_stream)
             if error_wa != 0:
                 error = error_wa
             elif error_message != 0:

From b2bcf366223d43ff9a3220a3445cce5f1aec3cdc Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Wed, 26 Feb 2025 21:20:11 +0800
Subject: [PATCH 08/36] Move Android backup decryption to a standalone module

---
 Whatsapp_Chat_Exporter/__main__.py        |  25 +--
 Whatsapp_Chat_Exporter/android_crypt.py   | 211 ++++++++++++++++++++++
 Whatsapp_Chat_Exporter/android_handler.py | 197 +-------------------
 Whatsapp_Chat_Exporter/utility.py         |   6 -
 4 files changed, 228 insertions(+), 211 deletions(-)
 create mode 100644 Whatsapp_Chat_Exporter/android_crypt.py

diff --git a/Whatsapp_Chat_Exporter/__main__.py b/Whatsapp_Chat_Exporter/__main__.py
index 611df91..9fc9378 100644
--- a/Whatsapp_Chat_Exporter/__main__.py
+++ b/Whatsapp_Chat_Exporter/__main__.py
@@ -7,6 +7,17 @@ import shutil
 import json
 import string
 import glob
+import importlib.metadata
+from Whatsapp_Chat_Exporter import android_crypt, exported_handler, android_handler
+from Whatsapp_Chat_Exporter import ios_handler, ios_media_handler
+from Whatsapp_Chat_Exporter.data_model import ChatStore
+from Whatsapp_Chat_Exporter.utility import APPLE_TIME, Crypt, check_update, DbType
+from Whatsapp_Chat_Exporter.utility import readable_to_bytes, sanitize_filename
+from Whatsapp_Chat_Exporter.utility import import_from_json, bytes_to_readable
+from argparse import ArgumentParser, SUPPRESS
+from datetime import datetime
+from getpass import getpass
+from sys import exit
 try:
     import vobject
 except ModuleNotFoundError:
@@ -14,16 +25,6 @@ except ModuleNotFoundError:
 else:
     from Whatsapp_Chat_Exporter.vcards_contacts import ContactsFromVCards
     vcards_deps_installed = True
-from Whatsapp_Chat_Exporter import exported_handler, android_handler
-from Whatsapp_Chat_Exporter import ios_handler, ios_media_handler
-from Whatsapp_Chat_Exporter.data_model import ChatStore
-from Whatsapp_Chat_Exporter.utility import APPLE_TIME, Crypt, DbType, readable_to_bytes, check_update
-from Whatsapp_Chat_Exporter.utility import import_from_json, sanitize_filename, bytes_to_readable
-from argparse import ArgumentParser, SUPPRESS
-from datetime import datetime
-from getpass import getpass
-from sys import exit
-import importlib.metadata
 
 
 def main():
@@ -448,12 +449,12 @@ def main():
             db = open(args.backup, "rb").read()
             if args.wab:
                 wab = open(args.wab, "rb").read()
-                error_wa = android_handler.decrypt_backup(wab, key, contact_db, crypt, args.showkey, DbType.CONTACT, key_stream)
+                error_wa = android_crypt.decrypt_backup(wab, key, contact_db, crypt, args.showkey, DbType.CONTACT, key_stream)
                 if isinstance(key, io.IOBase):
                     key.seek(0)
             else:
                 error_wa = 0
-            error_message = android_handler.decrypt_backup(db, key, msg_db, crypt, args.showkey, DbType.MESSAGE, key_stream)
+            error_message = android_crypt.decrypt_backup(db, key, msg_db, crypt, args.showkey, DbType.MESSAGE, key_stream)
             if error_wa != 0:
                 error = error_wa
             elif error_message != 0:
diff --git a/Whatsapp_Chat_Exporter/android_crypt.py b/Whatsapp_Chat_Exporter/android_crypt.py
new file mode 100644
index 0000000..45a807b
--- /dev/null
+++ b/Whatsapp_Chat_Exporter/android_crypt.py
@@ -0,0 +1,211 @@
+import hmac
+import io
+import zlib
+import javaobj
+from typing import Tuple, Union
+from hashlib import sha256
+from Whatsapp_Chat_Exporter.utility import CRYPT14_OFFSETS, Crypt, DbType
+try:
+    import zlib
+    from Crypto.Cipher import AES
+except ModuleNotFoundError:
+    support_backup = False
+else:
+    support_backup = True
+try:
+    import javaobj
+except ModuleNotFoundError:
+    support_crypt15 = False
+else:
+    support_crypt15 = True
+
+
+def _derive_main_enc_key(key_stream: bytes) -> Tuple[bytes, bytes]:
+    """
+    Derive the main encryption key for the given key stream. The key is derived using HMAC of HMAC of the provided key stream.
+
+    Args:
+        key_stream (bytes): The key stream to generate HMAC of HMAC.
+
+    Returns:
+        Tuple[bytes, bytes]: A tuple containing the main encryption key and the original key stream.
+    """
+    key = hmac.new(
+        hmac.new(
+            b'\x00' * 32,
+            key_stream,
+            sha256
+        ).digest(),
+        b"backup encryption\x01",
+        sha256
+    )
+    return key.digest(), key_stream
+
+
+def _extract_enc_key(keyfile: bytes) -> Tuple[bytes, bytes]:
+    """
+    Extract the encryption key from the keyfile.
+
+    Args:
+        keyfile (bytes): The keyfile containing the encrypted key.
+
+    Returns:
+        Tuple[bytes, bytes]: values from _derive_main_enc_key()
+    """
+    key_stream = b""
+    for byte in javaobj.loads(keyfile):
+        key_stream += byte.to_bytes(1, "big", signed=True)
+
+    return _derive_main_enc_key(key_stream)
+
+
+def brute_force_offset(max_iv: int = 200, max_db: int = 200):
+    """
+    Brute force the offsets for IV and database start position in WhatsApp backup files.
+    Used when common offsets are not applicable to a backup file.
+
+    Args:
+        max_iv (int, optional): Maximum value to try for IV offset. Defaults to 200.
+        max_db (int, optional): Maximum value to try for database start offset. Defaults to 200.
+
+    Yields:
+        tuple: A tuple containing:
+            - int: Start position of IV
+            - int: End position of IV (start + 16)
+            - int: Start position of database
+    """
+    for iv in range(0, max_iv):
+        for db in range(0, max_db):
+            yield iv, iv + 16, db
+
+
+def decrypt_backup(
+    database: bytes,
+    key: Union[str, io.IOBase],
+    output: str = None,
+    crypt: Crypt = Crypt.CRYPT14,
+    show_crypt15: bool = False,
+    db_type: DbType = DbType.MESSAGE,
+    dry_run: bool = False,
+    key_stream: bool = False
+) -> int:
+    """
+    Decrypt the WhatsApp backup database.
+
+    Args:
+        database (bytes): The encrypted database file.
+        key (str or io.IOBase): The key to decrypt the database. The key should either be a string (32 bytes hex key) or a file object (encryption key file).
+        key_stream (bool, optional): Whether the key is a key stream. False for hex key. True for key stream.
+        output (str, optional): The path to save the decrypted database. Defaults to None. When dry_run is True, this parameter is ignored.
+        crypt (Crypt, optional): The encryption version of the database. Defaults to Crypt.CRYPT14.
+        show_crypt15 (bool, optional): Whether to show the HEX key of the crypt15 backup. Defaults to False.
+        db_type (DbType, optional): The type of database (MESSAGE or CONTACT). Defaults to DbType.MESSAGE.
+        dry_run (bool, optional): Whether to perform a dry run without saving the decrypted database. Defaults to False.
+
+    Returns:
+        int: The status code of the decryption process.
+            - 0: The decryption process was successful.
+            - 1: The decryption process failed because the necessary dependencies for backup decryption are not available.
+            - 2: The decryption process failed because the common offsets for the IV and database are not applicable, and the brute force attempt to find the correct offsets also failed.
+            - 3: The decryption process failed due to unknown error
+    """
+    if not support_backup:
+        return 1
+    if not dry_run and output is None:
+        ValueError("The path to the decrypted database must be specified unless dry_run is true.")
+    if isinstance(key, io.IOBase):
+        key = key.read()
+        if crypt is not Crypt.CRYPT15:
+            t1 = key[30:62]
+    if crypt is not Crypt.CRYPT15 and len(key) != 158:
+        raise ValueError("The key file must be 158 bytes")
+    # Determine the IV and database offsets
+    if crypt == Crypt.CRYPT14:
+        if len(database) < 191:
+            raise ValueError("The crypt14 file must be at least 191 bytes")
+        current_try = 0
+        offsets = CRYPT14_OFFSETS[current_try]
+        t2 = database[15:47]
+        iv = database[offsets["iv"]:offsets["iv"] + 16]
+        db_ciphertext = database[offsets["db"]:]
+    elif crypt == Crypt.CRYPT12:
+        if len(database) < 67:
+            raise ValueError("The crypt12 file must be at least 67 bytes")
+        t2 = database[3:35]
+        iv = database[51:67]
+        db_ciphertext = database[67:-20]
+    elif crypt == Crypt.CRYPT15:
+        if not support_crypt15:
+            return 1
+        if len(database) < 131:
+            raise ValueError("The crypt15 file must be at least 131 bytes")
+        t1 = t2 = None
+        if db_type == DbType.MESSAGE:
+            iv = database[8:24]
+            db_offset = database[0] + 2  # Skip protobuf + protobuf size and backup type
+        elif db_type == DbType.CONTACT:
+            iv = database[7:23]
+            db_offset = database[0] + 1  # Skip protobuf + protobuf size
+        db_ciphertext = database[db_offset:]
+
+    if t1 != t2:
+        raise ValueError("The signature of key file and backup file mismatch")
+
+    if crypt == Crypt.CRYPT15:
+        if key_stream:
+            main_key, hex_key = _extract_enc_key(key)
+        else:
+            main_key, hex_key = _derive_main_enc_key(key)
+        if show_crypt15:
+            hex_key = [hex_key.hex()[c:c+4] for c in range(0, len(hex_key.hex()), 4)]
+            print("The HEX key of the crypt15 backup is: " + ' '.join(hex_key))
+    else:
+        main_key = key[126:]
+    decompressed = False
+    while not decompressed:
+        cipher = AES.new(main_key, AES.MODE_GCM, iv)
+        db_compressed = cipher.decrypt(db_ciphertext)
+        try:
+            db = zlib.decompress(db_compressed)
+        except zlib.error:
+            if crypt == Crypt.CRYPT14:
+                current_try += 1
+                if current_try < len(CRYPT14_OFFSETS):
+                    offsets = CRYPT14_OFFSETS[current_try]
+                    iv = database[offsets["iv"]:offsets["iv"] + 16]
+                    db_ciphertext = database[offsets["db"]:]
+                    continue
+                else:
+                    print("Common offsets are not applicable to "
+                          "your backup. Trying to brute force it...")
+                    for start_iv, end_iv, start_db in brute_force_offset():
+                        iv = database[start_iv:end_iv]
+                        db_ciphertext = database[start_db:]
+                        cipher = AES.new(main_key, AES.MODE_GCM, iv)
+                        db_compressed = cipher.decrypt(db_ciphertext)
+                        try:
+                            db = zlib.decompress(db_compressed)
+                        except zlib.error:
+                            continue
+                        else:
+                            decompressed = True
+                            print(
+                                f"The offsets of your IV and database are {start_iv} and "
+                                f"{start_db}, respectively. To include your offsets in the "
+                                "program, please report it by creating an issue on GitHub: "
+                                "https://github.com/KnugiHK/Whatsapp-Chat-Exporter/discussions/47"
+                            )
+                            break
+                    if not decompressed:
+                        return 2
+            else:
+                return 3
+        else:
+            decompressed = True
+        if db[0:6].upper() == b"SQLITE":
+            if not dry_run:
+                with open(output, "wb") as f:
+                    f.write(db)
+            return 0
+        else:
+            raise ValueError("The plaintext is not a SQLite database. Did you use the key to encrypt something...")
diff --git a/Whatsapp_Chat_Exporter/android_handler.py b/Whatsapp_Chat_Exporter/android_handler.py
index c185034..30284a0 100644
--- a/Whatsapp_Chat_Exporter/android_handler.py
+++ b/Whatsapp_Chat_Exporter/android_handler.py
@@ -2,206 +2,17 @@
 
 import sqlite3
 import os
-import io
-import hmac
 import shutil
 from pathlib import Path
 from mimetypes import MimeTypes
-from typing import Tuple, Union
 from markupsafe import escape as htmle
-from hashlib import sha256
 from base64 import b64decode, b64encode
 from datetime import datetime
 from Whatsapp_Chat_Exporter.data_model import ChatStore, Message
-from Whatsapp_Chat_Exporter.utility import CURRENT_TZ_OFFSET, MAX_SIZE, ROW_SIZE, DbType, convert_time_unit, determine_metadata, get_cond_for_empty
-from Whatsapp_Chat_Exporter.utility import rendering, Crypt, Device, get_file_name, setup_template
-from Whatsapp_Chat_Exporter.utility import brute_force_offset, CRYPT14_OFFSETS, get_status_location
-from Whatsapp_Chat_Exporter.utility import get_chat_condition, slugify, bytes_to_readable, JidType
-
-try:
-    import zlib
-    from Crypto.Cipher import AES
-except ModuleNotFoundError:
-    support_backup = False
-else:
-    support_backup = True
-try:
-    import javaobj
-except ModuleNotFoundError:
-    support_crypt15 = False
-else:
-    support_crypt15 = True
-
-
-def _derive_main_enc_key(key_stream: bytes) -> Tuple[bytes, bytes]:
-    """
-    Derive the main encryption key for the given key stream. The key is derived using HMAC of HMAC of the provided key stream.
-
-    Args:
-        key_stream (bytes): The key stream to generate HMAC of HMAC.
-
-    Returns:
-        Tuple[bytes, bytes]: A tuple containing the main encryption key and the original key stream.
-    """
-    key = hmac.new(
-        hmac.new(
-            b'\x00' * 32,
-            key_stream,
-            sha256
-        ).digest(),
-        b"backup encryption\x01",
-        sha256
-    )
-    return key.digest(), key_stream
-
-
-def _extract_enc_key(keyfile: bytes) -> Tuple[bytes, bytes]:
-    """
-    Extract the encryption key from the keyfile.
-
-    Args:
-        keyfile (bytes): The keyfile containing the encrypted key.
-
-    Returns:
-        Tuple[bytes, bytes]: values from _derive_main_enc_key()
-    """
-    key_stream = b""
-    for byte in javaobj.loads(keyfile):
-        key_stream += byte.to_bytes(1, "big", signed=True)
-
-    return _derive_main_enc_key(key_stream)
-
-
-def decrypt_backup(
-    database: bytes,
-    key: Union[str, io.IOBase],
-    output: str = None,
-    crypt: Crypt = Crypt.CRYPT14,
-    show_crypt15: bool = False,
-    db_type: DbType = DbType.MESSAGE,
-    dry_run: bool = False,
-    key_stream: bool = False
-) -> int:
-    """
-    Decrypt the WhatsApp backup database.
-
-    Args:
-        database (bytes): The encrypted database file.
-        key (str or io.IOBase): The key to decrypt the database. The key should either be a string (32 bytes hex key) or a file object (encryption key file).
-        key_stream (bool, optional): Whether the key is a key stream. False for hex key. True for key stream.
-        output (str, optional): The path to save the decrypted database. Defaults to None. When dry_run is True, this parameter is ignored.
-        crypt (Crypt, optional): The encryption version of the database. Defaults to Crypt.CRYPT14.
-        show_crypt15 (bool, optional): Whether to show the HEX key of the crypt15 backup. Defaults to False.
-        db_type (DbType, optional): The type of database (MESSAGE or CONTACT). Defaults to DbType.MESSAGE.
-        dry_run (bool, optional): Whether to perform a dry run without saving the decrypted database. Defaults to False.
-
-    Returns:
-        int: The status code of the decryption process.
-            - 0: The decryption process was successful.
-            - 1: The decryption process failed because the necessary dependencies for backup decryption are not available.
-            - 2: The decryption process failed because the common offsets for the IV and database are not applicable, and the brute force attempt to find the correct offsets also failed.
-            - 3: The decryption process failed due to unknown error
-    """
-    if not support_backup:
-        return 1
-    if not dry_run and output is None:
-        ValueError("The path to the decrypted database must be specified unless dry_run is true.")
-    if isinstance(key, io.IOBase):
-        key = key.read()
-        if crypt is not Crypt.CRYPT15:
-            t1 = key[30:62]
-    if crypt is not Crypt.CRYPT15 and len(key) != 158:
-        raise ValueError("The key file must be 158 bytes")
-    # Determine the IV and database offsets
-    if crypt == Crypt.CRYPT14:
-        if len(database) < 191:
-            raise ValueError("The crypt14 file must be at least 191 bytes")
-        current_try = 0
-        offsets = CRYPT14_OFFSETS[current_try]
-        t2 = database[15:47]
-        iv = database[offsets["iv"]:offsets["iv"] + 16]
-        db_ciphertext = database[offsets["db"]:]
-    elif crypt == Crypt.CRYPT12:
-        if len(database) < 67:
-            raise ValueError("The crypt12 file must be at least 67 bytes")
-        t2 = database[3:35]
-        iv = database[51:67]
-        db_ciphertext = database[67:-20]
-    elif crypt == Crypt.CRYPT15:
-        if not support_crypt15:
-            return 1
-        if len(database) < 131:
-            raise ValueError("The crypt15 file must be at least 131 bytes")
-        t1 = t2 = None
-        if db_type == DbType.MESSAGE:
-            iv = database[8:24]
-            db_offset = database[0] + 2  # Skip protobuf + protobuf size and backup type
-        elif db_type == DbType.CONTACT:
-            iv = database[7:23]
-            db_offset = database[0] + 1  # Skip protobuf + protobuf size
-        db_ciphertext = database[db_offset:]
-
-    if t1 != t2:
-        raise ValueError("The signature of key file and backup file mismatch")
-
-    if crypt == Crypt.CRYPT15:
-        if key_stream:
-            main_key, hex_key = _extract_enc_key(key)
-        else:
-            main_key, hex_key = _derive_main_enc_key(key)
-        if show_crypt15:
-            hex_key = [hex_key.hex()[c:c+4] for c in range(0, len(hex_key.hex()), 4)]
-            print("The HEX key of the crypt15 backup is: " + ' '.join(hex_key))
-    else:
-        main_key = key[126:]
-    decompressed = False
-    while not decompressed:
-        cipher = AES.new(main_key, AES.MODE_GCM, iv)
-        db_compressed = cipher.decrypt(db_ciphertext)
-        try:
-            db = zlib.decompress(db_compressed)
-        except zlib.error:
-            if crypt == Crypt.CRYPT14:
-                current_try += 1
-                if current_try < len(CRYPT14_OFFSETS):
-                    offsets = CRYPT14_OFFSETS[current_try]
-                    iv = database[offsets["iv"]:offsets["iv"] + 16]
-                    db_ciphertext = database[offsets["db"]:]
-                    continue
-                else:
-                    print("Common offsets are not applicable to "
-                          "your backup. Trying to brute force it...")
-                    for start_iv, end_iv, start_db in brute_force_offset():
-                        iv = database[start_iv:end_iv]
-                        db_ciphertext = database[start_db:]
-                        cipher = AES.new(main_key, AES.MODE_GCM, iv)
-                        db_compressed = cipher.decrypt(db_ciphertext)
-                        try:
-                            db = zlib.decompress(db_compressed)
-                        except zlib.error:
-                            continue
-                        else:
-                            decompressed = True
-                            print(
-                                f"The offsets of your IV and database are {start_iv} and "
-                                f"{start_db}, respectively. To include your offsets in the "
-                                "program, please report it by creating an issue on GitHub: "
-                                "https://github.com/KnugiHK/Whatsapp-Chat-Exporter/discussions/47"
-                            )
-                            break
-                    if not decompressed:
-                        return 2
-            else:
-                return 3
-        else:
-            decompressed = True
-        if db[0:6].upper() == b"SQLITE":
-            if not dry_run:
-                with open(output, "wb") as f:
-                    f.write(db)
-            return 0
-        else:
-            raise ValueError("The plaintext is not a SQLite database. Did you use the key to encrypt something...")
+from Whatsapp_Chat_Exporter.utility import CURRENT_TZ_OFFSET, MAX_SIZE, ROW_SIZE, JidType, Device
+from Whatsapp_Chat_Exporter.utility import rendering, get_file_name, setup_template, get_cond_for_empty
+from Whatsapp_Chat_Exporter.utility import get_status_location, convert_time_unit, determine_metadata
+from Whatsapp_Chat_Exporter.utility import get_chat_condition, slugify, bytes_to_readable
 
 
 def contacts(db, data, enrich_from_vcards):
diff --git a/Whatsapp_Chat_Exporter/utility.py b/Whatsapp_Chat_Exporter/utility.py
index 259c318..f51f21d 100644
--- a/Whatsapp_Chat_Exporter/utility.py
+++ b/Whatsapp_Chat_Exporter/utility.py
@@ -279,12 +279,6 @@ class DbType(StrEnum):
     CONTACT = "contact"
 
 
-def brute_force_offset(max_iv=200, max_db=200):
-    for iv in range(0, max_iv):
-        for db in range(0, max_db):
-            yield iv, iv + 16, db
-
-
 def determine_metadata(content, init_msg):
     msg = init_msg if init_msg else ""
     if content["is_me_joined"] == 1:  # Override

From a7496f80a7eb2c1fcaa97974003c343ab24e21f6 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Wed, 26 Feb 2025 21:20:17 +0800
Subject: [PATCH 09/36] Update bplist.py

---
 Whatsapp_Chat_Exporter/bplist.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Whatsapp_Chat_Exporter/bplist.py b/Whatsapp_Chat_Exporter/bplist.py
index fddd964..390fe6e 100644
--- a/Whatsapp_Chat_Exporter/bplist.py
+++ b/Whatsapp_Chat_Exporter/bplist.py
@@ -234,7 +234,7 @@ class BPListReader(object):
         # read trailer
         self.offset_size, self.object_ref_size, self.number_of_objects, self.top_object, self.table_offset = struct.unpack('!6xBB4xI4xI4xI', self.data[-32:])
         #print "** plist offset_size:",self.offset_size,"objref_size:",self.object_ref_size,"num_objs:",self.number_of_objects,"top:",self.top_object,"table_ofs:",self.table_offset
-        
+
         # read offset table
         self.offset_table = self.data[self.table_offset:-32]
         self.offsets = []

From 457ab209c187fb2e5a79155f4e1d94ca91aff8c1 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Wed, 26 Feb 2025 21:30:52 +0800
Subject: [PATCH 10/36] Bug fix on incorrectly positioned argument

This commit also made `dry_run` and `keyfile_stream` keyword arguments

Affects #130
---
 Whatsapp_Chat_Exporter/__main__.py      | 24 ++++++++++++++++++++----
 Whatsapp_Chat_Exporter/android_crypt.py |  5 +++--
 2 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/__main__.py b/Whatsapp_Chat_Exporter/__main__.py
index 9fc9378..ab0e05b 100644
--- a/Whatsapp_Chat_Exporter/__main__.py
+++ b/Whatsapp_Chat_Exporter/__main__.py
@@ -442,19 +442,35 @@ def main():
                 crypt = Crypt.CRYPT15
             if not os.path.isfile(args.key) and all(char in string.hexdigits for char in args.key.replace(" ", "")):
                 key = bytes.fromhex(args.key.replace(" ", ""))
-                key_stream = False
+                keyfile_stream = False
             else:
                 key = open(args.key, "rb")
-                key_stream = True
+                keyfile_stream = True
             db = open(args.backup, "rb").read()
             if args.wab:
                 wab = open(args.wab, "rb").read()
-                error_wa = android_crypt.decrypt_backup(wab, key, contact_db, crypt, args.showkey, DbType.CONTACT, key_stream)
+                error_wa = android_crypt.decrypt_backup(
+                    wab,
+                    key,
+                    contact_db,
+                    crypt,
+                    args.showkey,
+                    DbType.CONTACT,
+                    keyfile_stream=keyfile_stream
+                )
                 if isinstance(key, io.IOBase):
                     key.seek(0)
             else:
                 error_wa = 0
-            error_message = android_crypt.decrypt_backup(db, key, msg_db, crypt, args.showkey, DbType.MESSAGE, key_stream)
+            error_message = android_crypt.decrypt_backup(
+                db,
+                key,
+                msg_db,
+                crypt,
+                args.showkey,
+                DbType.MESSAGE,
+                keyfile_stream=keyfile_stream
+            )
             if error_wa != 0:
                 error = error_wa
             elif error_message != 0:
diff --git a/Whatsapp_Chat_Exporter/android_crypt.py b/Whatsapp_Chat_Exporter/android_crypt.py
index 45a807b..40a6a38 100644
--- a/Whatsapp_Chat_Exporter/android_crypt.py
+++ b/Whatsapp_Chat_Exporter/android_crypt.py
@@ -86,8 +86,9 @@ def decrypt_backup(
     crypt: Crypt = Crypt.CRYPT14,
     show_crypt15: bool = False,
     db_type: DbType = DbType.MESSAGE,
+    *,
     dry_run: bool = False,
-    key_stream: bool = False
+    keyfile_stream: bool = False
 ) -> int:
     """
     Decrypt the WhatsApp backup database.
@@ -152,7 +153,7 @@ def decrypt_backup(
         raise ValueError("The signature of key file and backup file mismatch")
 
     if crypt == Crypt.CRYPT15:
-        if key_stream:
+        if keyfile_stream:
             main_key, hex_key = _extract_enc_key(key)
         else:
             main_key, hex_key = _derive_main_enc_key(key)

From 6034937cf50da205f74b0bc9dc14b48bf86177b8 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sat, 1 Mar 2025 12:18:43 +0800
Subject: [PATCH 11/36] Terminate the process when unknown android backup
 format supplied

---
 Whatsapp_Chat_Exporter/__main__.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Whatsapp_Chat_Exporter/__main__.py b/Whatsapp_Chat_Exporter/__main__.py
index ab0e05b..849b1b6 100644
--- a/Whatsapp_Chat_Exporter/__main__.py
+++ b/Whatsapp_Chat_Exporter/__main__.py
@@ -440,6 +440,9 @@ def main():
                 crypt = Crypt.CRYPT14
             elif "crypt15" in args.backup:
                 crypt = Crypt.CRYPT15
+            else:
+                print("Unknown backup format. The backup file must be crypt12, crypt14 or crypt15.")
+                exit(1)
             if not os.path.isfile(args.key) and all(char in string.hexdigits for char in args.key.replace(" ", "")):
                 key = bytes.fromhex(args.key.replace(" ", ""))
                 keyfile_stream = False

From 272454c2cec5b32375c749c85471274e681d024f Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sat, 1 Mar 2025 23:59:12 +0800
Subject: [PATCH 12/36] Bug fix on missing `_version_` variable, introduced in
 0.11.0

---
 Whatsapp_Chat_Exporter/utility.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Whatsapp_Chat_Exporter/utility.py b/Whatsapp_Chat_Exporter/utility.py
index f51f21d..d009a4a 100644
--- a/Whatsapp_Chat_Exporter/utility.py
+++ b/Whatsapp_Chat_Exporter/utility.py
@@ -96,8 +96,8 @@ def determine_day(last, current):
 def check_update():
     import urllib.request
     import json
+    import importlib
     from sys import platform
-    from .__init__ import __version__
 
     package_url_json = "https://pypi.org/pypi/whatsapp-chat-exporter/json"
     try:
@@ -109,6 +109,7 @@ def check_update():
         with raw:
             package_info = json.load(raw)
             latest_version = tuple(map(int, package_info["info"]["version"].split(".")))
+            __version__ = importlib.metadata.version("whatsapp_chat_exporter")
             current_version = tuple(map(int, __version__.split(".")))
             if current_version < latest_version:
                 print("===============Update===============")

From 86cb44ced92f71af9610f0be26d360d541eea34d Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 2 Mar 2025 00:28:47 +0800
Subject: [PATCH 13/36] Add more docstrings

---
 Whatsapp_Chat_Exporter/data_model.py |   8 +-
 Whatsapp_Chat_Exporter/utility.py    | 169 ++++++++++++++++++++++++---
 2 files changed, 154 insertions(+), 23 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/data_model.py b/Whatsapp_Chat_Exporter/data_model.py
index ee4d066..da14cc7 100644
--- a/Whatsapp_Chat_Exporter/data_model.py
+++ b/Whatsapp_Chat_Exporter/data_model.py
@@ -2,11 +2,11 @@
 
 import os
 from datetime import datetime, tzinfo, timedelta
-from typing import Union
+from typing import Union, Optional
 
 
 class Timing():
-    def __init__(self, timezone_offset: Union[int, None]):
+    def __init__(self, timezone_offset: Optional[int]):
         self.timezone_offset = timezone_offset
 
     def format_timestamp(self, timestamp, format):
@@ -80,9 +80,9 @@ class Message():
     def __init__(
             self,
             *,
-            from_me: Union[bool,int],
+            from_me: Union[bool, int],
             timestamp: int,
-            time: Union[int,float,str],
+            time: Union[int, float, str],
             key_id: int,
             received_timestamp: int,
             read_timestamp: int,
diff --git a/Whatsapp_Chat_Exporter/utility.py b/Whatsapp_Chat_Exporter/utility.py
index d009a4a..172b748 100644
--- a/Whatsapp_Chat_Exporter/utility.py
+++ b/Whatsapp_Chat_Exporter/utility.py
@@ -1,3 +1,4 @@
+import sqlite3
 import jinja2
 import json
 import os
@@ -9,6 +10,7 @@ from markupsafe import Markup
 from datetime import datetime, timedelta
 from enum import IntEnum
 from Whatsapp_Chat_Exporter.data_model import ChatStore
+from typing import Dict, List, Optional, Tuple, Union
 try:
     from enum import StrEnum, IntEnum
 except ImportError:
@@ -26,7 +28,15 @@ ROW_SIZE = 0x3D0
 CURRENT_TZ_OFFSET = datetime.now().astimezone().utcoffset().seconds / 3600
 
 
-def convert_time_unit(time_second: int):
+def convert_time_unit(time_second: int) -> str:
+    """Converts a time duration in seconds to a human-readable string.
+
+    Args:
+        time_second: The time duration in seconds.
+
+    Returns:
+        str: A human-readable string representing the time duration.
+    """
     time = str(timedelta(seconds=time_second))
     if "day" not in time:
         if time_second < 1:
@@ -46,11 +56,19 @@ def convert_time_unit(time_second: int):
     return time
 
 
-def bytes_to_readable(size_bytes: int):
-    """From https://stackoverflow.com/a/14822210/9478891 
+def bytes_to_readable(size_bytes: int) -> str:
+    """Converts a file size in bytes to a human-readable string with units.
+
+    From https://stackoverflow.com/a/14822210/9478891
     Authors: james-sapam & other contributors
     Licensed under CC BY-SA 3.0
     See git commit logs for changes, if any.
+
+    Args:
+        size_bytes: The file size in bytes.
+
+    Returns:
+        A human-readable string representing the file size.
     """
     if size_bytes == 0:
        return "0B"
@@ -61,7 +79,18 @@ def bytes_to_readable(size_bytes: int):
     return "%s %s" % (s, size_name[i])
 
 
-def readable_to_bytes(size_str: str):
+def readable_to_bytes(size_str: str) -> int:
+    """Converts a human-readable file size string to bytes.
+
+    Args:
+        size_str: The human-readable file size string (e.g., "1024KB", "1MB", "2GB").
+
+    Returns:
+        The file size in bytes.
+
+    Raises:
+        ValueError: If the input string is invalid.
+    """
     SIZE_UNITS = {
         'B': 1,
         'KB': 1024,
@@ -80,11 +109,28 @@ def readable_to_bytes(size_str: str):
     return int(number) * SIZE_UNITS[unit]
 
 
-def sanitize_except(html):
+def sanitize_except(html: str) -> Markup:
+    """Sanitizes HTML, only allowing <br> tag.
+
+    Args:
+        html: The HTML string to sanitize.
+
+    Returns:
+        A Markup object containing the sanitized HTML.
+    """
     return Markup(sanitize(html, tags=["br"]))
 
 
-def determine_day(last, current):
+def determine_day(last: int, current: int) -> Optional[datetime.date]:
+    """Determines if the day has changed between two timestamps. Exposed to Jinja's environment.
+
+    Args:
+        last: The timestamp of the previous message.
+        current: The timestamp of the current message.
+
+    Returns:
+        The date of the current message if it's a different day than the last message, otherwise None.
+    """
     last = datetime.fromtimestamp(last).date()
     current = datetime.fromtimestamp(current).date()
     if last == current:
@@ -169,7 +215,13 @@ class Device(StrEnum):
     EXPORTED = "exported"
 
 
-def import_from_json(json_file, data):
+def import_from_json(json_file: str, data: Dict[str, ChatStore]):
+    """Imports chat data from a JSON file into the data dictionary.
+
+    Args:
+        json_file: The path to the JSON file.
+        data: The dictionary to store the imported chat data.
+    """
     from Whatsapp_Chat_Exporter.data_model import ChatStore, Message
     with open(json_file, "r") as f:
         temp_data = json.loads(f.read())
@@ -204,11 +256,31 @@ def import_from_json(json_file, data):
         print(f"Importing chats from JSON...({index + 1}/{total_row_number})", end="\r")
 
 
-def sanitize_filename(file_name: str):
+def sanitize_filename(file_name: str) -> str:
+    """Sanitizes a filename by removing invalid and unsafe characters.
+
+    Args:
+        file_name: The filename to sanitize.
+
+    Returns:
+        The sanitized filename.
+    """
     return "".join(x for x in file_name if x.isalnum() or x in "- ")
 
 
-def get_file_name(contact: str, chat: ChatStore):
+def get_file_name(contact: str, chat: ChatStore) -> Tuple[str, str]:
+    """Generates a sanitized filename and contact name for a chat.
+
+    Args:
+        contact: The contact identifier (e.g., a phone number or group ID).
+        chat: The ChatStore object for the chat.
+
+    Returns:
+        A tuple containing the sanitized filename and the contact name.
+
+    Raises:
+        ValueError: If the contact format is unexpected.
+    """
     if "@" not in contact and contact not in ("000000000000000", "000000000000001", "ExportedChat"):
         raise ValueError("Unexpected contact format: " + contact)
     phone_number = contact.split('@')[0]
@@ -228,11 +300,36 @@ def get_file_name(contact: str, chat: ChatStore):
     return sanitize_filename(file_name), name
 
 
-def get_cond_for_empty(enable, jid_field: str, broadcast_field: str):
+def get_cond_for_empty(enable: bool, jid_field: str, broadcast_field: str) -> str:
+    """Generates a SQL condition for filtering empty chats.
+
+    Args:
+        enable: True to include non-empty chats, False to include empty chats.
+        jid_field: The name of the JID field in the SQL query.
+        broadcast_field: The column name of the broadcast field in the SQL query.
+
+    Returns:
+        A SQL condition string.
+    """
     return f"AND (chat.hidden=0 OR {jid_field}='status@broadcast' OR {broadcast_field}>0)" if enable else ""
 
 
-def get_chat_condition(filter, include, columns, jid=None, platform=None):
+def get_chat_condition(filter: Optional[List[str]], include: bool, columns: List[str], jid: Optional[str] = None, platform: Optional[str] = None) -> str:
+    """Generates a SQL condition for filtering chats based on inclusion or exclusion criteria.
+
+    Args:
+        filter: A list of phone numbers to include or exclude.
+        include: True to include chats that match the filter, False to exclude them.
+        columns: A list of column names to check against the filter.
+        jid: The JID column name (used for group identification).
+        platform: The platform ("android" or "ios") for platform-specific JID queries.
+
+    Returns:
+        A SQL condition string.
+
+    Raises:
+        ValueError: If the column count is invalid or an unsupported platform is provided.
+    """
     if filter is not None:
         conditions = []
         if len(columns) < 2 and jid is not None:
@@ -280,7 +377,16 @@ class DbType(StrEnum):
     CONTACT = "contact"
 
 
-def determine_metadata(content, init_msg):
+def determine_metadata(content: sqlite3.Row, init_msg: Optional[str]) -> Optional[str]:
+    """Determines the metadata of a message.
+
+    Args:
+        content (sqlite3.Row): A row from the messages table.
+        init_msg (Optional[str]): The initial message, if any.
+
+    Returns:
+        The metadata as a string or None if the type is unsupported.
+    """
     msg = init_msg if init_msg else ""
     if content["is_me_joined"] == 1:  # Override
         return f"You were added into the group by {msg}"
@@ -361,7 +467,17 @@ def determine_metadata(content, init_msg):
     return msg
 
 
-def get_status_location(output_folder, offline_static):
+def get_status_location(output_folder: str, offline_static: str) -> str:
+    """
+    Gets the location of the W3.CSS file, either from web or local storage.
+
+    Args:
+        output_folder (str): The folder where offline static files will be stored.
+        offline_static (str): The subfolder name for static files. If falsy, returns web URL.
+
+    Returns:
+        str: The path or URL to the W3.CSS file.
+    """
     w3css = "https://www.w3schools.com/w3css/4/w3.css"
     if not offline_static:
         return w3css
@@ -376,7 +492,18 @@ def get_status_location(output_folder, offline_static):
     w3css = os.path.join(offline_static, "w3.css")
 
 
-def setup_template(template, no_avatar, experimental=False):
+def setup_template(template: Optional[str], no_avatar: bool, experimental: bool = False) -> jinja2.Template:
+    """
+    Sets up the Jinja2 template environment and loads the template.
+
+    Args:
+        template (Optional[str]): Path to custom template file. If None, uses default template.
+        no_avatar (bool): Whether to disable avatar display in the template.
+        experimental (bool, optional): Whether to use experimental template features. Defaults to False.
+
+    Returns:
+        jinja2.Template: The configured Jinja2 template object.
+    """
     if template is None or experimental:
         template_dir = os.path.dirname(__file__)
         template_file = "whatsapp.html" if not experimental else template
@@ -396,13 +523,17 @@ def setup_template(template, no_avatar, experimental=False):
 APPLE_TIME = 978307200
 
 
-def slugify(value, allow_unicode=False):
+def slugify(value: str, allow_unicode: bool = False) -> str:
     """
+    Convert text to ASCII-only slugs for URL-safe strings.
     Taken from https://github.com/django/django/blob/master/django/utils/text.py
-    Convert to ASCII if 'allow_unicode' is False. Convert spaces or repeated
-    dashes to single dashes. Remove characters that aren't alphanumerics,
-    underscores, or hyphens. Convert to lowercase. Also strip leading and
-    trailing whitespace, dashes, and underscores.
+
+    Args:
+        value (str): The string to convert to a slug.
+        allow_unicode (bool, optional): Whether to allow Unicode characters. Defaults to False.
+
+    Returns:
+        str: The slugified string with only alphanumerics, underscores, or hyphens.
     """
     value = str(value)
     if allow_unicode:

From 431dce7d24e61800284d83587d54b152dff718e4 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 2 Mar 2025 00:29:03 +0800
Subject: [PATCH 14/36] Change package_url_json to a constant

---
 Whatsapp_Chat_Exporter/utility.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/utility.py b/Whatsapp_Chat_Exporter/utility.py
index 172b748..2db7445 100644
--- a/Whatsapp_Chat_Exporter/utility.py
+++ b/Whatsapp_Chat_Exporter/utility.py
@@ -145,9 +145,9 @@ def check_update():
     import importlib
     from sys import platform
 
-    package_url_json = "https://pypi.org/pypi/whatsapp-chat-exporter/json"
+    PACKAGE_JSON = "https://pypi.org/pypi/whatsapp-chat-exporter/json"
     try:
-        raw = urllib.request.urlopen(package_url_json)
+        raw = urllib.request.urlopen(PACKAGE_JSON)
     except Exception:
         print("Failed to check for updates.")
         return 1

From 4d04e51ddac9c0bda06ddd92619953f9417a50f7 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 2 Mar 2025 00:47:34 +0800
Subject: [PATCH 15/36] Refactor and add docstrings

---
 Whatsapp_Chat_Exporter/data_model.py | 168 +++++++++++++++++++--------
 Whatsapp_Chat_Exporter/utility.py    |   2 +-
 2 files changed, 120 insertions(+), 50 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/data_model.py b/Whatsapp_Chat_Exporter/data_model.py
index da14cc7..411de1c 100644
--- a/Whatsapp_Chat_Exporter/data_model.py
+++ b/Whatsapp_Chat_Exporter/data_model.py
@@ -1,37 +1,80 @@
-#!/usr/bin/python3
-
 import os
 from datetime import datetime, tzinfo, timedelta
-from typing import Union, Optional
+from typing import Union, Optional, Dict, Any
 
 
-class Timing():
-    def __init__(self, timezone_offset: Optional[int]):
+class Timing:
+    """
+    Handles timestamp formatting with timezone support.
+    """
+    def __init__(self, timezone_offset: Optional[int]) -> None:
+        """
+        Initialize Timing object.
+
+        Args:
+            timezone_offset (Optional[int]): Hours offset from UTC
+        """
         self.timezone_offset = timezone_offset
 
-    def format_timestamp(self, timestamp, format):
+    def format_timestamp(self, timestamp: Optional[Union[int, float]], format: str) -> Optional[str]:
+        """
+        Format a timestamp with the specified format string.
+
+        Args:
+            timestamp (Optional[Union[int, float]]): Unix timestamp to format
+            format (str): strftime format string
+
+        Returns:
+            Optional[str]: Formatted timestamp string, or None if timestamp is None
+        """
         if timestamp:
             timestamp = timestamp / 1000 if timestamp > 9999999999 else timestamp
             return datetime.fromtimestamp(timestamp, TimeZone(self.timezone_offset)).strftime(format)
-        else:
-            return None
+        return None
 
 
 class TimeZone(tzinfo):
-    def __init__(self, offset):
+    """
+    Custom timezone class with fixed offset.
+    """
+    def __init__(self, offset: int) -> None:
+        """
+        Initialize TimeZone object.
+
+        Args:
+            offset (int): Hours offset from UTC
+        """
         self.offset = offset
-    def utcoffset(self, dt):
-       return timedelta(hours=self.offset)
-    def dst(self, dt):
-       return timedelta(0)
+
+    def utcoffset(self, dt: Optional[datetime]) -> timedelta:
+        """Get UTC offset."""
+        return timedelta(hours=self.offset)
+
+    def dst(self, dt: Optional[datetime]) -> timedelta:
+        """Get DST offset (always 0)."""
+        return timedelta(0)
 
 
-class ChatStore():
-    def __init__(self, type, name=None, media=None):
+class ChatStore:
+    """
+    Stores chat information and messages.
+    """
+    def __init__(self, type: str, name: Optional[str] = None, media: Optional[str] = None) -> None:
+        """
+        Initialize ChatStore object.
+
+        Args:
+            type (str): Device type (IOS or ANDROID)
+            name (Optional[str]): Chat name
+            media (Optional[str]): Path to media folder
+        
+        Raises:
+            TypeError: If name is not a string or None
+        """
         if name is not None and not isinstance(name, str):
             raise TypeError("Name must be a string or None")
         self.name = name
-        self.messages = {}
+        self.messages: Dict[str, 'Message'] = {}
         self.type = type
         if media is not None:
             from Whatsapp_Chat_Exporter.utility import Device
@@ -47,18 +90,20 @@ class ChatStore():
         self.their_avatar_thumb = None
         self.status = None
         self.media_base = ""
-    
-    def add_message(self, id, message):
+
+    def add_message(self, id: str, message: 'Message') -> None:
+        """Add a message to the chat store."""
         if not isinstance(message, Message):
             raise TypeError("message must be a Message object")
         self.messages[id] = message
 
-    def delete_message(self, id):
+    def delete_message(self, id: str) -> None:
+        """Delete a message from the chat store."""
         if id in self.messages:
             del self.messages[id]
 
-    def to_json(self):
-        serialized_msgs = {id: msg.to_json() for id, msg in self.messages.items()}
+    def to_json(self) -> Dict[str, Any]:
+        """Convert chat store to JSON-serializable dict."""
         return {
             'name': self.name,
             'type': self.type,
@@ -66,17 +111,22 @@ class ChatStore():
             'their_avatar': self.their_avatar,
             'their_avatar_thumb': self.their_avatar_thumb,
             'status': self.status,
-            'messages': serialized_msgs
+            'messages': {id: msg.to_json() for id, msg in self.messages.items()}
         }
 
-    def get_last_message(self):
+    def get_last_message(self) -> 'Message':
+        """Get the most recent message in the chat."""
         return tuple(self.messages.values())[-1]
 
-    def get_messages(self):
+    def get_messages(self) -> Dict[str, 'Message']:
+        """Get all messages in the chat."""
         return self.messages.values()
 
 
-class Message():
+class Message:
+    """
+    Represents a single message in a chat.
+    """
     def __init__(
             self,
             *,
@@ -87,17 +137,35 @@ class Message():
             received_timestamp: int,
             read_timestamp: int,
             timezone_offset: int = 0,
-            message_type: int = None
-        ):
+            message_type: Optional[int] = None
+    ) -> None:
+        """
+        Initialize Message object.
+
+        Args:
+            from_me (Union[bool, int]): Whether message was sent by the user
+            timestamp (int): Message timestamp
+            time (Union[int, float, str]): Message time
+            key_id (int): Message unique identifier
+            received_timestamp (int): When message was received
+            read_timestamp (int): When message was read
+            timezone_offset (int, optional): Hours offset from UTC. Defaults to 0
+            message_type (Optional[int], optional): Type of message. Defaults to None
+
+        Raises:
+            TypeError: If time is not a string or number
+        """
         self.from_me = bool(from_me)
         self.timestamp = timestamp / 1000 if timestamp > 9999999999 else timestamp
         timing = Timing(timezone_offset)
-        if isinstance(time, int) or isinstance(time, float):
+        
+        if isinstance(time, (int, float)):
             self.time = timing.format_timestamp(self.timestamp, "%H:%M")
         elif isinstance(time, str):
             self.time = time
         else:
             raise TypeError("Time must be a string or number")
+
         self.media = False
         self.key_id = key_id
         self.meta = False
@@ -107,29 +175,31 @@ class Message():
         self.mime = None
         self.message_type = message_type,
         self.received_timestamp = timing.format_timestamp(received_timestamp, "%Y/%m/%d %H:%M")
-        self.read_timestamp = timing.format_timestamp(read_timestamp, "%Y/%m/%d %H:%M") 
-        # Extra
+        self.read_timestamp = timing.format_timestamp(read_timestamp, "%Y/%m/%d %H:%M")
+        
+        # Extra attributes
         self.reply = None
         self.quoted_data = None
         self.caption = None
-        self.thumb = None # Android specific
+        self.thumb = None  # Android specific
         self.sticker = False
-    
-    def to_json(self):
+
+    def to_json(self) -> Dict[str, Any]:
+        """Convert message to JSON-serializable dict."""
         return {
-            'from_me'     : self.from_me,
-            'timestamp'   : self.timestamp,
-            'time'        : self.time,
-            'media'       : self.media,
-            'key_id'      : self.key_id,
-            'meta'        : self.meta,
-            'data'        : self.data,
-            'sender'      : self.sender,
-            'safe'        : self.safe,
-            'mime'        : self.mime,
-            'reply'       : self.reply,
-            'quoted_data' : self.quoted_data,
-            'caption'     : self.caption,
-            'thumb'       : self.thumb,
-            'sticker'     : self.sticker
-        }
+            'from_me': self.from_me,
+            'timestamp': self.timestamp,
+            'time': self.time,
+            'media': self.media,
+            'key_id': self.key_id,
+            'meta': self.meta,
+            'data': self.data,
+            'sender': self.sender,
+            'safe': self.safe,
+            'mime': self.mime,
+            'reply': self.reply,
+            'quoted_data': self.quoted_data,
+            'caption': self.caption,
+            'thumb': self.thumb,
+            'sticker': self.sticker
+        }
\ No newline at end of file
diff --git a/Whatsapp_Chat_Exporter/utility.py b/Whatsapp_Chat_Exporter/utility.py
index 2db7445..b5c4e10 100644
--- a/Whatsapp_Chat_Exporter/utility.py
+++ b/Whatsapp_Chat_Exporter/utility.py
@@ -10,7 +10,7 @@ from markupsafe import Markup
 from datetime import datetime, timedelta
 from enum import IntEnum
 from Whatsapp_Chat_Exporter.data_model import ChatStore
-from typing import Dict, List, Optional, Tuple, Union
+from typing import Dict, List, Optional, Tuple
 try:
     from enum import StrEnum, IntEnum
 except ImportError:

From 9f321384ece48e262d325b80b1fb1669cf90dae3 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 2 Mar 2025 00:52:28 +0800
Subject: [PATCH 16/36] Make ChatStore.messages private

---
 Whatsapp_Chat_Exporter/android_handler.py |  6 +++---
 Whatsapp_Chat_Exporter/data_model.py      | 18 +++++++++++-------
 Whatsapp_Chat_Exporter/ios_handler.py     |  4 ++--
 3 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/android_handler.py b/Whatsapp_Chat_Exporter/android_handler.py
index 30284a0..ca6e8a7 100644
--- a/Whatsapp_Chat_Exporter/android_handler.py
+++ b/Whatsapp_Chat_Exporter/android_handler.py
@@ -451,7 +451,7 @@ def media(db, data, media_folder, filter_date, filter_chat, filter_empty, separa
         Path(f"{media_folder}/thumbnails").mkdir(parents=True, exist_ok=True)
     while content is not None:
         file_path = f"{media_folder}/{content['file_path']}"
-        message = data[content["key_remote_jid"]].messages[content["message_row_id"]]
+        message = data[content["key_remote_jid"]].get_message(content["message_row_id"])
         message.media = True
         if os.path.isfile(file_path):
             message.data = file_path
@@ -547,7 +547,7 @@ def vcard(db, data, media_folder, filter_date, filter_chat, filter_empty):
         if not os.path.isfile(file_path):
             with open(file_path, "w", encoding="utf-8") as f:
                 f.write(row["vcard"])
-        message = data[row["key_remote_jid"]].messages[row["message_row_id"]]
+        message = data[row["key_remote_jid"]].get_message(row["message_row_id"])
         message.data = "This media include the following vCard file(s):<br>" \
             f'<a href="{htmle(file_path)}">{htmle(media_name)}</a>'
         message.mime = "text/x-vcard"
@@ -736,7 +736,7 @@ def create_txt(data, output):
             contact = jik.replace('+', '')
         output_file = os.path.join(output, f"{contact}.txt")
         with open(output_file, "w", encoding="utf8") as f:
-            for message in chat.messages.values():
+            for message in chat.get_messages():
                 date = datetime.fromtimestamp(message.timestamp).date()
                 if message.meta and message.mime != "media":
                     continue  # Skip any metadata in text format
diff --git a/Whatsapp_Chat_Exporter/data_model.py b/Whatsapp_Chat_Exporter/data_model.py
index 411de1c..20b9754 100644
--- a/Whatsapp_Chat_Exporter/data_model.py
+++ b/Whatsapp_Chat_Exporter/data_model.py
@@ -74,7 +74,7 @@ class ChatStore:
         if name is not None and not isinstance(name, str):
             raise TypeError("Name must be a string or None")
         self.name = name
-        self.messages: Dict[str, 'Message'] = {}
+        self._messages: Dict[str, 'Message'] = {}
         self.type = type
         if media is not None:
             from Whatsapp_Chat_Exporter.utility import Device
@@ -95,12 +95,16 @@ class ChatStore:
         """Add a message to the chat store."""
         if not isinstance(message, Message):
             raise TypeError("message must be a Message object")
-        self.messages[id] = message
+        self._messages[id] = message
+    
+    def get_message(self, id: str) -> 'Message':
+        """Get a message from the chat store."""
+        return self._messages.get(id)
 
     def delete_message(self, id: str) -> None:
         """Delete a message from the chat store."""
-        if id in self.messages:
-            del self.messages[id]
+        if id in self._messages:
+            del self._messages[id]
 
     def to_json(self) -> Dict[str, Any]:
         """Convert chat store to JSON-serializable dict."""
@@ -111,16 +115,16 @@ class ChatStore:
             'their_avatar': self.their_avatar,
             'their_avatar_thumb': self.their_avatar_thumb,
             'status': self.status,
-            'messages': {id: msg.to_json() for id, msg in self.messages.items()}
+            'messages': {id: msg.to_json() for id, msg in self._messages.items()}
         }
 
     def get_last_message(self) -> 'Message':
         """Get the most recent message in the chat."""
-        return tuple(self.messages.values())[-1]
+        return tuple(self._messages.values())[-1]
 
     def get_messages(self) -> Dict[str, 'Message']:
         """Get all messages in the chat."""
-        return self.messages.values()
+        return self._messages.values()
 
 
 class Message:
diff --git a/Whatsapp_Chat_Exporter/ios_handler.py b/Whatsapp_Chat_Exporter/ios_handler.py
index 258bc61..a164e2d 100644
--- a/Whatsapp_Chat_Exporter/ios_handler.py
+++ b/Whatsapp_Chat_Exporter/ios_handler.py
@@ -283,7 +283,7 @@ def media(db, data, media_folder, filter_date, filter_chat, filter_empty, separa
         file_path = f"{media_folder}/Message/{content['ZMEDIALOCALPATH']}"
         ZMESSAGE = content["ZMESSAGE"]
         contact = data[content["ZCONTACTJID"]]
-        message = contact.messages[ZMESSAGE]
+        message = contact.get_message(ZMESSAGE)
         message.media = True
         if contact.media_base == "":
             contact.media_base = media_folder + "/"
@@ -367,7 +367,7 @@ def vcard(db, data, media_folder, filter_date, filter_chat, filter_empty):
 
         vcard_summary = "This media include the following vCard file(s):<br>" 
         vcard_summary += " | ".join([f'<a href="{htmle(fp)}">{htmle(name)}</a>' for name, fp in zip(vcard_names, file_paths)])
-        message = data[content["ZCONTACTJID"]].messages[content["ZMESSAGE"]]
+        message = data[content["ZCONTACTJID"]].get_message(content["ZMESSAGE"])
         message.data = vcard_summary
         message.mime = "text/x-vcard"
         message.media = True

From 1ef223e2381a105ea89c5fe18dffe4b595c1370b Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 2 Mar 2025 01:41:44 +0800
Subject: [PATCH 17/36] Refactor the data model

---
 Whatsapp_Chat_Exporter/__main__.py        |  4 +-
 Whatsapp_Chat_Exporter/android_handler.py | 49 ++++++------
 Whatsapp_Chat_Exporter/data_model.py      | 96 ++++++++++++++++++++++-
 Whatsapp_Chat_Exporter/ios_handler.py     | 53 +++++++------
 4 files changed, 150 insertions(+), 52 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/__main__.py b/Whatsapp_Chat_Exporter/__main__.py
index 849b1b6..051f166 100644
--- a/Whatsapp_Chat_Exporter/__main__.py
+++ b/Whatsapp_Chat_Exporter/__main__.py
@@ -10,7 +10,7 @@ import glob
 import importlib.metadata
 from Whatsapp_Chat_Exporter import android_crypt, exported_handler, android_handler
 from Whatsapp_Chat_Exporter import ios_handler, ios_media_handler
-from Whatsapp_Chat_Exporter.data_model import ChatStore
+from Whatsapp_Chat_Exporter.data_model import ChatCollection, ChatStore
 from Whatsapp_Chat_Exporter.utility import APPLE_TIME, Crypt, check_update, DbType
 from Whatsapp_Chat_Exporter.utility import readable_to_bytes, sanitize_filename
 from Whatsapp_Chat_Exporter.utility import import_from_json, bytes_to_readable
@@ -403,7 +403,7 @@ def main():
                 parser.error("Enter a phone number in the chat filter. See https://wts.knugi.dev/docs?dest=chat")
     filter_chat = (args.filter_chat_include, args.filter_chat_exclude)
 
-    data = {}
+    data = ChatCollection()
 
     if args.enrich_from_vcards is not None:
         if not vcards_deps_installed:
diff --git a/Whatsapp_Chat_Exporter/android_handler.py b/Whatsapp_Chat_Exporter/android_handler.py
index ca6e8a7..3374c8c 100644
--- a/Whatsapp_Chat_Exporter/android_handler.py
+++ b/Whatsapp_Chat_Exporter/android_handler.py
@@ -32,9 +32,9 @@ def contacts(db, data, enrich_from_vcards):
     c.execute("""SELECT jid, COALESCE(display_name, wa_name) as display_name, status FROM wa_contacts; """)
     row = c.fetchone()
     while row is not None:
-        data[row["jid"]] = ChatStore(Device.ANDROID, row["display_name"])
+        current_chat = data.add_chat(row["jid"], ChatStore(Device.ANDROID, row["display_name"]))
         if row["status"] is not None:
-            data[row["jid"]].status = row["status"]
+            current_chat.status = row["status"]
         row = c.fetchone()
 
 
@@ -207,8 +207,10 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
         else:
             break
     while content is not None:
-        if content["key_remote_jid"] not in data:
-            data[content["key_remote_jid"]] = ChatStore(Device.ANDROID, content["chat_subject"])
+        if not data.get_chat(content["key_remote_jid"]):
+            current_chat = data.add_chat(content["key_remote_jid"], ChatStore(Device.ANDROID, content["chat_subject"]))
+        else:
+            current_chat = data.get_chat(content["key_remote_jid"])
         if content["key_remote_jid"] is None:
             continue  # Not sure
         if "sender_jid_row_id" in content:
@@ -232,7 +234,7 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                 f"""('Decode')&input={b64encode(b64encode(content["data"])).decode()}">""")
             message.data += b64encode(content["data"]).decode("utf-8") + "</a>"
             message.safe = message.meta = True
-            data[content["key_remote_jid"]].add_message(content["_id"], message)
+            current_chat.add_message(content["_id"], message)
             i += 1
             content = c.fetchone()
             continue
@@ -242,13 +244,13 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                 if content["sender_jid_row_id"] > 0:
                     _jid = content["group_sender_jid"]
                     if _jid in data:
-                        name = data[_jid].name
+                        name = data.get_chat(_jid).name
                     if "@" in _jid:
                         fallback = _jid.split('@')[0]
             else:
                 if content["remote_resource"] is not None:
                     if content["remote_resource"] in data:
-                        name = data[content["remote_resource"]].name
+                        name = data.get_chat(content["remote_resource"]).name
                     if "@" in content["remote_resource"]:
                         fallback = content["remote_resource"].split('@')[0]
 
@@ -281,7 +283,7 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                 if content["sender_jid_row_id"] > 0:
                     _jid = content["group_sender_jid"]
                     if _jid in data:
-                        name = data[_jid].name
+                        name = data.get_chat(_jid).name
                     if "@" in _jid:
                         fallback = _jid.split('@')[0]
                 else:
@@ -290,7 +292,7 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                 _jid = content["remote_resource"]
                 if _jid is not None:
                     if _jid in data:
-                        name = data[_jid].name
+                        name = data.get_chat(_jid).name
                     if "@" in _jid:
                         fallback = _jid.split('@')[0]
                 else:
@@ -343,7 +345,7 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                                 msg = msg.replace("\n", " <br>")
             message.data = msg
 
-        data[content["key_remote_jid"]].add_message(content["_id"], message)
+        current_chat.add_message(content["_id"], message)
         i += 1
         if i % 1000 == 0:
             print(f"Processing messages...({i}/{total_row_number})", end="\r")
@@ -451,7 +453,8 @@ def media(db, data, media_folder, filter_date, filter_chat, filter_empty, separa
         Path(f"{media_folder}/thumbnails").mkdir(parents=True, exist_ok=True)
     while content is not None:
         file_path = f"{media_folder}/{content['file_path']}"
-        message = data[content["key_remote_jid"]].get_message(content["message_row_id"])
+        current_chat = data.get_chat(content["key_remote_jid"])
+        message = current_chat.get_message(content["message_row_id"])
         message.media = True
         if os.path.isfile(file_path):
             message.data = file_path
@@ -464,7 +467,7 @@ def media(db, data, media_folder, filter_date, filter_chat, filter_empty, separa
             else:
                 message.mime = content["mime_type"]
             if separate_media:
-                chat_display_name = slugify(data[content["key_remote_jid"]].name or message.sender \
+                chat_display_name = slugify(current_chat.name or message.sender \
                                             or content["key_remote_jid"].split('@')[0], True)
                 current_filename = file_path.split("/")[-1]
                 new_folder = os.path.join(media_folder, "separated", chat_display_name)
@@ -547,7 +550,7 @@ def vcard(db, data, media_folder, filter_date, filter_chat, filter_empty):
         if not os.path.isfile(file_path):
             with open(file_path, "w", encoding="utf-8") as f:
                 f.write(row["vcard"])
-        message = data[row["key_remote_jid"]].get_message(row["message_row_id"])
+        message = data.get_chat(row["key_remote_jid"]).get_message(row["message_row_id"])
         message.data = "This media include the following vCard file(s):<br>" \
             f'<a href="{htmle(file_path)}">{htmle(media_name)}</a>'
         message.mime = "text/x-vcard"
@@ -603,7 +606,7 @@ def calls(db, data, timezone_offset, filter_chat):
             read_timestamp=None # TODO: Add timestamp
         )
         _jid = content["raw_string"]
-        name = data[_jid].name if _jid in data else content["chat_subject"] or None
+        name = data.get_chat(_jid).name if _jid in data else content["chat_subject"] or None
         if _jid is not None and "@" in _jid:
             fallback = _jid.split('@')[0]
         else:
@@ -632,7 +635,7 @@ def calls(db, data, timezone_offset, filter_chat):
             call.data += "in an unknown state."
         chat.add_message(content["_id"], call)
         content = c.fetchone()
-    data["000000000000000"] = chat
+    data.add_chat("000000000000000", chat)
 
 
 def create_html(
@@ -657,8 +660,8 @@ def create_html(
     w3css = get_status_location(output_folder, offline_static)
 
     for current, contact in enumerate(data):
-        chat = data[contact]
-        safe_file_name, name = get_file_name(contact, chat)
+        current_chat = data.get_chat(contact)
+        safe_file_name, name = get_file_name(contact, current_chat)
 
         if maximum_size is not None:
             current_size = 0
@@ -666,8 +669,8 @@ def create_html(
             render_box = []
             if maximum_size == 0:
                 maximum_size = MAX_SIZE
-            last_msg = chat.get_last_message().key_id
-            for message in chat.get_messages():
+            last_msg = current_chat.get_last_message().key_id
+            for message in current_chat.get_messages():
                 if message.data is not None and not message.meta and not message.media:
                     current_size += len(message.data) + ROW_SIZE
                 else:
@@ -681,7 +684,7 @@ def create_html(
                         render_box,
                         contact,
                         w3css,
-                        chat,
+                        current_chat,
                         headline,
                         next=f"{safe_file_name}-{current_page + 1}.html",
                         previous=f"{safe_file_name}-{current_page - 1}.html" if current_page > 1 else False
@@ -703,7 +706,7 @@ def create_html(
                             render_box,
                             contact,
                             w3css,
-                            chat,
+                            current_chat,
                             headline,
                             False,
                             previous=f"{safe_file_name}-{current_page - 1}.html"
@@ -714,10 +717,10 @@ def create_html(
                 output_file_name,
                 template,
                 name,
-                chat.get_messages(),
+                current_chat.get_messages(),
                 contact,
                 w3css,
-                chat,
+                current_chat,
                 headline,
                 False
             )
diff --git a/Whatsapp_Chat_Exporter/data_model.py b/Whatsapp_Chat_Exporter/data_model.py
index 20b9754..578713a 100644
--- a/Whatsapp_Chat_Exporter/data_model.py
+++ b/Whatsapp_Chat_Exporter/data_model.py
@@ -1,6 +1,6 @@
 import os
 from datetime import datetime, tzinfo, timedelta
-from typing import Union, Optional, Dict, Any
+from typing import MutableMapping, Union, Optional, Dict, Any
 
 
 class Timing:
@@ -55,6 +55,98 @@ class TimeZone(tzinfo):
         return timedelta(0)
 
 
+class ChatCollection(MutableMapping):
+    """
+    A collection of chats that provides dictionary-like access with additional chat management methods.
+    Inherits from MutableMapping to implement a custom dictionary-like behavior.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty chat collection."""
+        self._chats: Dict[str, ChatStore] = {}
+
+    def __getitem__(self, key: str) -> 'ChatStore':
+        """Get a chat by its ID. Required for dict-like access."""
+        return self._chats[key]
+
+    def __setitem__(self, key: str, value: 'ChatStore') -> None:
+        """Set a chat by its ID. Required for dict-like access."""
+        if not isinstance(value, ChatStore):
+            raise TypeError("Value must be a ChatStore object")
+        self._chats[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        """Delete a chat by its ID. Required for dict-like access."""
+        del self._chats[key]
+
+    def __iter__(self):
+        """Iterate over chat IDs. Required for dict-like access."""
+        return iter(self._chats)
+
+    def __len__(self) -> int:
+        """Get number of chats. Required for dict-like access."""
+        return len(self._chats)
+
+    def get_chat(self, chat_id: str) -> Optional['ChatStore']:
+        """
+        Get a chat by its ID.
+
+        Args:
+            chat_id (str): The ID of the chat to retrieve
+
+        Returns:
+            Optional['ChatStore']: The chat if found, None otherwise
+        """
+        return self._chats.get(chat_id)
+
+    def add_chat(self, chat_id: str, chat: 'ChatStore') -> None:
+        """
+        Add a new chat to the collection.
+
+        Args:
+            chat_id (str): The ID for the chat
+            chat (ChatStore): The chat to add
+
+        Raises:
+            TypeError: If chat is not a ChatStore object
+        """
+        if not isinstance(chat, ChatStore):
+            raise TypeError("Chat must be a ChatStore object")
+        self._chats[chat_id] = chat
+        return self._chats[chat_id]
+
+    def remove_chat(self, chat_id: str) -> None:
+        """
+        Remove a chat from the collection.
+
+        Args:
+            chat_id (str): The ID of the chat to remove
+        """
+        if chat_id in self._chats:
+            del self._chats[chat_id]
+
+    def items(self):
+        """Get chat items (id, chat) pairs."""
+        return self._chats.items()
+
+    def values(self):
+        """Get all chats."""
+        return self._chats.values()
+
+    def keys(self):
+        """Get all chat IDs."""
+        return self._chats.keys()
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert the collection to a dictionary.
+
+        Returns:
+            Dict[str, Any]: Dictionary representation of all chats
+        """
+        return {chat_id: chat.to_json() for chat_id, chat in self._chats.items()}
+
+
 class ChatStore:
     """
     Stores chat information and messages.
@@ -122,7 +214,7 @@ class ChatStore:
         """Get the most recent message in the chat."""
         return tuple(self._messages.values())[-1]
 
-    def get_messages(self) -> Dict[str, 'Message']:
+    def get_messages(self) -> 'Message':
         """Get all messages in the chat."""
         return self._messages.values()
 
diff --git a/Whatsapp_Chat_Exporter/ios_handler.py b/Whatsapp_Chat_Exporter/ios_handler.py
index a164e2d..a68183b 100644
--- a/Whatsapp_Chat_Exporter/ios_handler.py
+++ b/Whatsapp_Chat_Exporter/ios_handler.py
@@ -22,8 +22,9 @@ def contacts(db, data):
     while content is not None:
         if not content["ZWHATSAPPID"].endswith("@s.whatsapp.net"):
             ZWHATSAPPID = content["ZWHATSAPPID"] + "@s.whatsapp.net"
-        data[ZWHATSAPPID] = ChatStore(Device.IOS)
-        data[ZWHATSAPPID].status = content["ZABOUTTEXT"]
+        current_chat = ChatStore(Device.IOS)
+        current_chat.status = content["ZABOUTTEXT"]
+        data.add_chat(ZWHATSAPPID, current_chat)
         content = c.fetchone()
 
 
@@ -76,20 +77,21 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
             contact_name = content["ZPUSHNAME"]
         contact_id = content["ZCONTACTJID"]
         if contact_id not in data:
-            data[contact_id] = ChatStore(Device.IOS, contact_name, media_folder)
+            current_chat = data.add_chat(contact_id, ChatStore(Device.IOS, contact_name, media_folder))
         else:
-            data[contact_id].name = contact_name
-            data[contact_id].my_avatar = os.path.join(media_folder, "Media/Profile/Photo.jpg")
+            current_chat = data.get_chat(contact_id)
+            current_chat.name = contact_name
+            current_chat.my_avatar = os.path.join(media_folder, "Media/Profile/Photo.jpg")
         path = f'{media_folder}/Media/Profile/{contact_id.split("@")[0]}'
         avatars = glob(f"{path}*")
         if 0 < len(avatars) <= 1:
-            data[contact_id].their_avatar = avatars[0]
+            current_chat.their_avatar = avatars[0]
         else:
             for avatar in avatars:
-                if avatar.endswith(".thumb") and data[content["ZCONTACTJID"]].their_avatar_thumb is None:
-                    data[contact_id].their_avatar_thumb = avatar
-                elif avatar.endswith(".jpg") and data[content["ZCONTACTJID"]].their_avatar is None:
-                    data[contact_id].their_avatar = avatar
+                if avatar.endswith(".thumb") and current_chat.their_avatar_thumb is None:
+                    current_chat.their_avatar_thumb = avatar
+                elif avatar.endswith(".jpg") and current_chat.their_avatar is None:
+                    current_chat.their_avatar = avatar
         content = c.fetchone()
 
     # Get message history
@@ -135,17 +137,19 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
         Z_PK = content["Z_PK"]
         is_group_message = content["ZGROUPINFO"] is not None
         if ZCONTACTJID not in data:
-            data[ZCONTACTJID] = ChatStore(Device.IOS)
+            current_chat = data.add_chat(ZCONTACTJID, ChatStore(Device.IOS))
             path = f'{media_folder}/Media/Profile/{ZCONTACTJID.split("@")[0]}'
             avatars = glob(f"{path}*")
             if 0 < len(avatars) <= 1:
-                data[ZCONTACTJID].their_avatar = avatars[0]
+                current_chat.their_avatar = avatars[0]
             else:
                 for avatar in avatars:
                     if avatar.endswith(".thumb"):
-                        data[ZCONTACTJID].their_avatar_thumb = avatar
+                        current_chat.their_avatar_thumb = avatar
                     elif avatar.endswith(".jpg"):
-                        data[ZCONTACTJID].their_avatar = avatar
+                        current_chat.their_avatar = avatar
+        else:
+            current_chat = data.get_chat(ZCONTACTJID)
         ts = APPLE_TIME + content["ZMESSAGEDATE"]
         message = Message(
             from_me=content["ZISFROMME"],
@@ -162,7 +166,7 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
             name = None
             if content["ZMEMBERJID"] is not None:
                 if content["ZMEMBERJID"] in data:
-                    name = data[content["ZMEMBERJID"]].name
+                    name = data.get_chat(content["ZMEMBERJID"]).name
                 if "@" in content["ZMEMBERJID"]:
                     fallback = content["ZMEMBERJID"].split('@')[0]
                 else:
@@ -230,7 +234,7 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                             msg = msg.replace("\n", "<br>")
             message.data = msg
         if not invalid:
-            data[ZCONTACTJID].add_message(Z_PK, message)
+            current_chat.add_message(Z_PK, message)
         i += 1
         if i % 1000 == 0:
             print(f"Processing messages...({i}/{total_row_number})", end="\r")
@@ -281,12 +285,11 @@ def media(db, data, media_folder, filter_date, filter_chat, filter_empty, separa
     mime = MimeTypes()
     while content is not None:
         file_path = f"{media_folder}/Message/{content['ZMEDIALOCALPATH']}"
-        ZMESSAGE = content["ZMESSAGE"]
-        contact = data[content["ZCONTACTJID"]]
-        message = contact.get_message(ZMESSAGE)
+        current_chat = data.get_chat(content["ZCONTACTJID"])
+        message = current_chat.get_message(content["ZMESSAGE"])
         message.media = True
-        if contact.media_base == "":
-            contact.media_base = media_folder + "/"
+        if current_chat.media_base == "":
+            current_chat.media_base = media_folder + "/"
         if os.path.isfile(file_path):
             message.data = '/'.join(file_path.split("/")[1:])
             if content["ZVCARDSTRING"] is None:
@@ -298,7 +301,7 @@ def media(db, data, media_folder, filter_date, filter_chat, filter_empty, separa
             else:
                 message.mime = content["ZVCARDSTRING"]
             if separate_media:
-                chat_display_name = slugify(contact.name or message.sender \
+                chat_display_name = slugify(current_chat.name or message.sender \
                                             or content["ZCONTACTJID"].split('@')[0], True)
                 current_filename = file_path.split("/")[-1]
                 new_folder = os.path.join(media_folder, "separated", chat_display_name)
@@ -367,7 +370,7 @@ def vcard(db, data, media_folder, filter_date, filter_chat, filter_empty):
 
         vcard_summary = "This media include the following vCard file(s):<br>" 
         vcard_summary += " | ".join([f'<a href="{htmle(fp)}">{htmle(name)}</a>' for name, fp in zip(vcard_names, file_paths)])
-        message = data[content["ZCONTACTJID"]].get_message(content["ZMESSAGE"])
+        message = data.get_chat(content["ZCONTACTJID"]).get_message(content["ZMESSAGE"])
         message.data = vcard_summary
         message.mime = "text/x-vcard"
         message.media = True
@@ -415,7 +418,7 @@ def calls(db, data, timezone_offset, filter_chat):
             timezone_offset=timezone_offset if timezone_offset else CURRENT_TZ_OFFSET
         )
         _jid = content["ZGROUPCALLCREATORUSERJIDSTRING"]
-        name = data[_jid].name if _jid in data else None
+        name = data.get_chat(_jid).name if _jid in data else None
         if _jid is not None and "@" in _jid:
             fallback = _jid.split('@')[0]
         else:
@@ -443,4 +446,4 @@ def calls(db, data, timezone_offset, filter_chat):
             call.data += "in an unknown state."
         chat.add_message(call.key_id, call)
         content = c.fetchone()
-    data["000000000000000"] = chat
\ No newline at end of file
+    data.add_chat("000000000000000", chat)

From 2290be751a6d4977ad74c0cdefb10f02fb1f8224 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 2 Mar 2025 01:49:42 +0800
Subject: [PATCH 18/36] Update ios_handler.py

---
 Whatsapp_Chat_Exporter/ios_handler.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/ios_handler.py b/Whatsapp_Chat_Exporter/ios_handler.py
index a68183b..1232a3f 100644
--- a/Whatsapp_Chat_Exporter/ios_handler.py
+++ b/Whatsapp_Chat_Exporter/ios_handler.py
@@ -239,8 +239,7 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
         if i % 1000 == 0:
             print(f"Processing messages...({i}/{total_row_number})", end="\r")
         content = c.fetchone()
-    print(
-        f"Processing messages...({total_row_number}/{total_row_number})", end="\r")
+    print(f"Processing messages...({total_row_number}/{total_row_number})", end="\r")
 
 
 def media(db, data, media_folder, filter_date, filter_chat, filter_empty, separate_media=False):

From 4a0be0233cc789e6b4ee41e24ebeaab3203955d3 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 2 Mar 2025 11:25:01 +0800
Subject: [PATCH 19/36] Bug fix on model change for Message

---
 Whatsapp_Chat_Exporter/utility.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/utility.py b/Whatsapp_Chat_Exporter/utility.py
index b5c4e10..1ec302d 100644
--- a/Whatsapp_Chat_Exporter/utility.py
+++ b/Whatsapp_Chat_Exporter/utility.py
@@ -235,10 +235,12 @@ def import_from_json(json_file: str, data: Dict[str, ChatStore]):
         chat.status = chat_data.get("status")
         for id, msg in chat_data.get("messages").items():
             message = Message(
-                msg["from_me"],
-                msg["timestamp"],
-                msg["time"],
-                msg["key_id"],
+                from_me=msg["from_me"],
+                timestamp=msg["timestamp"],
+                time=msg["time"],
+                key_id=msg["key_id"],
+                received_timestamp=msg.get("received_timestamp"),
+                read_timestamp=msg.get("read_timestamp")
             )
             message.media = msg.get("media")
             message.meta = msg.get("meta")

From 7c4705d14969facfd254124a9bf2510752650198 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 2 Mar 2025 12:57:27 +0800
Subject: [PATCH 20/36] Major refactoring

This commit does not refactor Android handler
---
 Whatsapp_Chat_Exporter/__main__.py         | 1136 +++++++++++---------
 Whatsapp_Chat_Exporter/android_handler.py  |    6 +-
 Whatsapp_Chat_Exporter/data_model.py       |   10 +-
 Whatsapp_Chat_Exporter/exported_handler.py |  243 +++--
 Whatsapp_Chat_Exporter/ios_handler.py      |  844 +++++++++------
 5 files changed, 1280 insertions(+), 959 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/__main__.py b/Whatsapp_Chat_Exporter/__main__.py
index 051f166..1784723 100644
--- a/Whatsapp_Chat_Exporter/__main__.py
+++ b/Whatsapp_Chat_Exporter/__main__.py
@@ -18,6 +18,9 @@ from argparse import ArgumentParser, SUPPRESS
 from datetime import datetime
 from getpass import getpass
 from sys import exit
+from typing import Tuple, Optional, List, Dict, Any, Union
+
+# Try to import vobject for contacts processing
 try:
     import vobject
 except ModuleNotFoundError:
@@ -27,311 +30,212 @@ else:
     vcards_deps_installed = True
 
 
-def main():
+def setup_argument_parser() -> ArgumentParser:
+    """Set up and return the argument parser with all options."""
     parser = ArgumentParser(
-        description = 'A customizable Android and iOS/iPadOS WhatsApp database parser that '
-                      'will give you the history of your WhatsApp conversations in HTML '
-                      'and JSON. Android Backup Crypt12, Crypt14 and Crypt15 supported.',
-        epilog = f'WhatsApp Chat Exporter: {importlib.metadata.version("whatsapp_chat_exporter")} Licensed with MIT. See '
-                  'https://wts.knugi.dev/docs?dest=osl for all open source licenses.'
+        description='A customizable Android and iOS/iPadOS WhatsApp database parser that '
+                  'will give you the history of your WhatsApp conversations in HTML '
+                  'and JSON. Android Backup Crypt12, Crypt14 and Crypt15 supported.',
+        epilog=f'WhatsApp Chat Exporter: {importlib.metadata.version("whatsapp_chat_exporter")} Licensed with MIT. See '
+              'https://wts.knugi.dev/docs?dest=osl for all open source licenses.'
     )
-    parser.add_argument(
-        '-a',
-        '--android',
-        dest='android',
-        default=False,
-        action='store_true',
-        help="Define the target as Android")
-    parser.add_argument(
-        '-i',
-        '--ios',
-        dest='ios',
-        default=False,
-        action='store_true',
-        help="Define the target as iPhone/iPad")
-    parser.add_argument(
-        "-e",
-        "--exported",
-        dest="exported",
-        default=None,
+    
+    # Device type arguments
+    device_group = parser.add_argument_group('Device Type')
+    device_group.add_argument(
+        '-a', '--android', dest='android', default=False, action='store_true',
+        help="Define the target as Android"
+    )
+    device_group.add_argument(
+        '-i', '--ios', dest='ios', default=False, action='store_true',
+        help="Define the target as iPhone/iPad"
+    )
+    device_group.add_argument(
+        "-e", "--exported", dest="exported", default=None,
         help="Define the target as exported chat file and specify the path to the file"
     )
-    parser.add_argument(
-        "-w",
-        "--wa",
-        dest="wa",
-        default=None,
-        help="Path to contact database (default: wa.db/ContactsV2.sqlite)")
-    parser.add_argument(
-        "-m",
-        "--media",
-        dest="media",
-        default=None,
-        help="Path to WhatsApp media folder (default: WhatsApp)")
-    parser.add_argument(
-        "-b",
-        "--backup",
-        dest="backup",
-        default=None,
-        help="Path to Android (must be used together "
-             "with -k)/iOS WhatsApp backup")
-    parser.add_argument(
-        "-o",
-        "--output",
-        dest="output",
-        default="result",
-        help="Output to specific directory (default: result)")
-    parser.add_argument(
-        '-j',
-        '--json',
-        dest='json',
-        nargs='?',
-        default=None,
-        type=str,
-        const="result.json",
-        help="Save the result to a single JSON file (default if present: result.json)")
-    parser.add_argument(
-        '--avoid-encoding-json',
-        dest='avoid_encoding_json',
-        default=False,
-        action='store_true',
-        help="Don't encode non-ascii characters in the output JSON files")
-    parser.add_argument(
-        '--pretty-print-json',
-        dest='pretty_print_json',
-        default=None,
-        nargs='?',
-        const=2,
-        type=int,
-        help="Pretty print the output JSON.")
-    parser.add_argument(
-        '-d',
-        '--db',
-        dest='db',
-        default=None,
-        help="Path to database file (default: msgstore.db/"
-             "7c7fba66680ef796b916b067077cc246adacf01d)")
-    parser.add_argument(
-        '-k',
-        '--key',
-        dest='key',
-        default=None,
-        nargs='?',
+    
+    # Input file paths
+    input_group = parser.add_argument_group('Input Files')
+    input_group.add_argument(
+        "-w", "--wa", dest="wa", default=None,
+        help="Path to contact database (default: wa.db/ContactsV2.sqlite)"
+    )
+    input_group.add_argument(
+        "-m", "--media", dest="media", default=None,
+        help="Path to WhatsApp media folder (default: WhatsApp)"
+    )
+    input_group.add_argument(
+        "-b", "--backup", dest="backup", default=None,
+        help="Path to Android (must be used together with -k)/iOS WhatsApp backup"
+    )
+    input_group.add_argument(
+        "-d", "--db", dest="db", default=None,
+        help="Path to database file (default: msgstore.db/7c7fba66680ef796b916b067077cc246adacf01d)"
+    )
+    input_group.add_argument(
+        "-k", "--key", dest="key", default=None, nargs='?',
         help="Path to key file. If this option is set for crypt15 backup but nothing is specified, you will be prompted to enter the key."
     )
-    parser.add_argument(
-        "-t",
-        "--template",
-        dest="template",
-        default=None,
-        help="Path to custom HTML template"
+    input_group.add_argument(
+        "--call-db", dest="call_db_ios", nargs='?', default=None, type=str,
+        const="1b432994e958845fffe8e2f190f26d1511534088",
+        help="Path to call database (default: 1b432994e958845fffe8e2f190f26d1511534088) iOS only"
     )
-    parser.add_argument(
-        "--embedded",
-        dest="embedded",
-        default=False,
-        action='store_true',
-        help=SUPPRESS or "Embed media into HTML file (not yet implemented)"
-    )
-    parser.add_argument(
-        "-s",
-        "--showkey",
-        dest="showkey",
-        default=False,
-        action='store_true',
-        help="Show the HEX key used to decrypt the database"
-    )
-    parser.add_argument(
-        "-c",
-        "--move-media",
-        dest="move_media",
-        default=False,
-        action='store_true',
-        help="Move the media directory to output directory if the flag is set, otherwise copy it"
-    )
-    parser.add_argument(
-        "--offline",
-        dest="offline",
-        default=None,
-        help="Relative path to offline static files"
-    )
-    parser.add_argument(
-        "--size",
-        "--output-size",
-        "--split",
-        dest="size",
-        nargs='?',
-        const=0,
-        default=None,
-        help="Maximum (rough) size of a single output file in bytes, 0 for auto"
-    )
-    parser.add_argument(
-        "--no-html",
-        dest="no_html",
-        default=False,
-        action='store_true',
-        help="Do not output html files"
-    )
-    parser.add_argument(
-        "--check-update",
-        dest="check_update",
-        default=False,
-        action='store_true',
-        help="Check for updates (require Internet access)"
-    )
-    parser.add_argument(
-        "--assume-first-as-me",
-        dest="assume_first_as_me",
-        default=False,
-        action='store_true',
-        help="Assume the first message in a chat as sent by me (must be used together with -e)"
-    )
-    parser.add_argument(
-        "--no-avatar",
-        dest="no_avatar",
-        default=False,
-        action='store_true',
-        help="Do not render avatar in HTML output"
-    )
-    parser.add_argument(
-        "--import",
-        dest="import_json",
-        default=False,
-        action='store_true',
-        help="Import JSON file and convert to HTML output"
-    )
-    parser.add_argument(
-        "--business",
-        dest="business",
-        default=False,
-        action='store_true',
-        help="Use Whatsapp Business default files (iOS only)"
-    )
-    parser.add_argument(
-        "--wab",
-        "--wa-backup",
-        dest="wab",
-        default=None,
+    input_group.add_argument(
+        "--wab", "--wa-backup", dest="wab", default=None,
         help="Path to contact database in crypt15 format"
     )
-    parser.add_argument(
-        "--time-offset",
-        dest="timezone_offset",
-        default=0,
-        type=int,
-        choices=range(-12, 15),
-        metavar="{-12 to 14}",
-        help="Offset in hours (-12 to 14) for time displayed in the output"
+    
+    # Output options
+    output_group = parser.add_argument_group('Output Options')
+    output_group.add_argument(
+        "-o", "--output", dest="output", default="result",
+        help="Output to specific directory (default: result)"
     )
-    parser.add_argument(
-        "--date",
-        dest="filter_date",
-        default=None,
-        metavar="DATE",
+    output_group.add_argument(
+        '-j', '--json', dest='json', nargs='?', default=None, type=str, const="result.json",
+        help="Save the result to a single JSON file (default if present: result.json)"
+    )
+    output_group.add_argument(
+        "--txt", dest="text_format", nargs='?', default=None, type=str, const="result",
+        help="Export chats in text format similar to what WhatsApp officially provided (default if present: result/)"
+    )
+    output_group.add_argument(
+        "--no-html", dest="no_html", default=False, action='store_true',
+        help="Do not output html files"
+    )
+    output_group.add_argument(
+        "--size", "--output-size", "--split", dest="size", nargs='?', const=0, default=None,
+        help="Maximum (rough) size of a single output file in bytes, 0 for auto"
+    )
+    
+    # JSON formatting options
+    json_group = parser.add_argument_group('JSON Options')
+    json_group.add_argument(
+        '--avoid-encoding-json', dest='avoid_encoding_json', default=False, action='store_true',
+        help="Don't encode non-ascii characters in the output JSON files"
+    )
+    json_group.add_argument(
+        '--pretty-print-json', dest='pretty_print_json', default=None, nargs='?', const=2, type=int,
+        help="Pretty print the output JSON."
+    )
+    json_group.add_argument(
+        "--per-chat", dest="json_per_chat", default=False, action='store_true',
+        help="Output the JSON file per chat"
+    )
+    json_group.add_argument(
+        "--import", dest="import_json", default=False, action='store_true',
+        help="Import JSON file and convert to HTML output"
+    )
+    
+    # HTML options
+    html_group = parser.add_argument_group('HTML Options')
+    html_group.add_argument(
+        "-t", "--template", dest="template", default=None,
+        help="Path to custom HTML template"
+    )
+    html_group.add_argument(
+        "--embedded", dest="embedded", default=False, action='store_true',
+        help=SUPPRESS or "Embed media into HTML file (not yet implemented)"
+    )
+    html_group.add_argument(
+        "--offline", dest="offline", default=None,
+        help="Relative path to offline static files"
+    )
+    html_group.add_argument(
+        "--no-avatar", dest="no_avatar", default=False, action='store_true',
+        help="Do not render avatar in HTML output"
+    )
+    html_group.add_argument(
+        "--experimental-new-theme", dest="whatsapp_theme", default=False, action='store_true',
+        help="Use the newly designed WhatsApp-alike theme"
+    )
+    html_group.add_argument(
+        "--headline", dest="headline", default="Chat history with ??",
+        help="The custom headline for the HTML output. Use '??' as a placeholder for the chat name"
+    )
+    
+    # Media handling
+    media_group = parser.add_argument_group('Media Handling')
+    media_group.add_argument(
+        "-c", "--move-media", dest="move_media", default=False, action='store_true',
+        help="Move the media directory to output directory if the flag is set, otherwise copy it"
+    )
+    media_group.add_argument(
+        "--create-separated-media", dest="separate_media", default=False, action='store_true',
+        help="Create a copy of the media seperated per chat in <MEDIA>/separated/ directory"
+    )
+    
+    # Filtering options
+    filter_group = parser.add_argument_group('Filtering Options')
+    filter_group.add_argument(
+        "--time-offset", dest="timezone_offset", default=0, type=int, choices=range(-12, 15),
+        metavar="{-12 to 14}", help="Offset in hours (-12 to 14) for time displayed in the output"
+    )
+    filter_group.add_argument(
+        "--date", dest="filter_date", default=None, metavar="DATE",
         help="The date filter in specific format (inclusive)"
     )
-    parser.add_argument(
-        "--date-format",
-        dest="filter_date_format",
-        default="%Y-%m-%d %H:%M",
-        metavar="FORMAT",
+    filter_group.add_argument(
+        "--date-format", dest="filter_date_format", default="%Y-%m-%d %H:%M", metavar="FORMAT",
         help="The date format for the date filter"
     )
-    parser.add_argument(
-        "--include",
-        dest="filter_chat_include",
-        nargs='*',
-        metavar="phone number",
+    filter_group.add_argument(
+        "--include", dest="filter_chat_include", nargs='*', metavar="phone number",
         help="Include chats that match the supplied phone number"
     )
-    parser.add_argument(
-        "--exclude",
-        dest="filter_chat_exclude",
-        nargs='*',
-        metavar="phone number",
+    filter_group.add_argument(
+        "--exclude", dest="filter_chat_exclude", nargs='*', metavar="phone number",
         help="Exclude chats that match the supplied phone number"
     )
-    parser.add_argument(
-        "--dont-filter-empty",
-        dest="filter_empty",
-        default=True,
-        action='store_false',
+    filter_group.add_argument(
+        "--dont-filter-empty", dest="filter_empty", default=True, action='store_false',
         help=("By default, the exporter will not render chats with no valid message. "
               "Setting this flag will cause the exporter to render those. "
               "This is useful if chat(s) are missing from the output")
     )
-    parser.add_argument(
-        "--per-chat",
-        dest="json_per_chat",
-        default=False,
-        action='store_true',
-        help="Output the JSON file per chat"
-    )
-    parser.add_argument(
-        "--create-separated-media",
-        dest="separate_media",
-        default=False,
-        action='store_true',
-        help="Create a copy of the media seperated per chat in <MEDIA>/separated/ directory"
-    )
-    parser.add_argument(
-        "--decrypt-chunk-size",
-        dest="decrypt_chunk_size",
-        default=1 * 1024 * 1024,
-        type=int,
-        help="Specify the chunk size for decrypting iOS backup, which may affect the decryption speed."
-    )
-    parser.add_argument(
-        "--enrich-from-vcards",
-        dest="enrich_from_vcards",
-        default=None,
+    
+    # Contact enrichment
+    contact_group = parser.add_argument_group('Contact Enrichment')
+    contact_group.add_argument(
+        "--enrich-from-vcards", dest="enrich_from_vcards", default=None,
         help="Path to an exported vcf file from Google contacts export. Add names missing from WhatsApp's default database"
     )
-    parser.add_argument(
-        "--default-country-code",
-        dest="default_contry_code",
-        default=None,
+    contact_group.add_argument(
+        "--default-country-code", dest="default_country_code", default=None,
         help="Use with --enrich-from-vcards. When numbers in the vcf file does not have a country code, this will be used. 1 is for US, 66 for Thailand etc. Most likely use the number of your own country"
     )
-    parser.add_argument(
-        "--txt",
-        dest="text_format",
-        nargs='?',
-        default=None,
-        type=str,
-        const="result",
-        help="Export chats in text format similar to what WhatsApp officially provided (default if present: result/)"
+    
+    # Miscellaneous
+    misc_group = parser.add_argument_group('Miscellaneous')
+    misc_group.add_argument(
+        "-s", "--showkey", dest="showkey", default=False, action='store_true',
+        help="Show the HEX key used to decrypt the database"
     )
-    parser.add_argument(
-        "--experimental-new-theme",
-        dest="whatsapp_theme",
-        default=False,
-        action='store_true',
-        help="Use the newly designed WhatsApp-alike theme"
+    misc_group.add_argument(
+        "--check-update", dest="check_update", default=False, action='store_true',
+        help="Check for updates (require Internet access)"
     )
-    parser.add_argument(
-        "--call-db",
-        dest="call_db_ios",
-        nargs='?',
-        default=None,
-        type=str,
-        const="1b432994e958845fffe8e2f190f26d1511534088",
-        help="Path to call database (default: 1b432994e958845fffe8e2f190f26d1511534088) iOS only"
+    misc_group.add_argument(
+        "--assume-first-as-me", dest="assume_first_as_me", default=False, action='store_true',
+        help="Assume the first message in a chat as sent by me (must be used together with -e)"
     )
-    parser.add_argument(
-        "--headline",
-        dest="headline",
-        default="Chat history with ??",
-        help="The custom headline for the HTML output. Use '??' as a placeholder for the chat name"
+    misc_group.add_argument(
+        "--business", dest="business", default=False, action='store_true',
+        help="Use Whatsapp Business default files (iOS only)"
     )
+    misc_group.add_argument(
+        "--decrypt-chunk-size", dest="decrypt_chunk_size", default=1 * 1024 * 1024, type=int,
+        help="Specify the chunk size for decrypting iOS backup, which may affect the decryption speed."
+    )
+    
+    return parser
 
-    args = parser.parse_args()
 
-    # Check for updates
-    if args.check_update:
-        exit(check_update())
-
-    # Sanity checks
+def validate_args(parser: ArgumentParser, args) -> None:
+    """Validate command line arguments and modify them if needed."""
+    # Basic validation checks
     if args.android and args.ios and args.exported and args.import_json:
         parser.error("You must define only one device type.")
     if not args.android and not args.ios and not args.exported and not args.import_json:
@@ -346,258 +250,410 @@ def main():
         parser.error("WhatsApp Business is only available on iOS for now.")
     if "??" not in args.headline:
         parser.error("--headline must contain '??' for replacement.")
-    if args.json_per_chat and (
-        (args.json[-5:] != ".json" and os.path.isfile(args.json)) or \
-        (args.json[-5:] == ".json" and os.path.isfile(args.json[:-5]))
+    
+    # JSON validation
+    if args.json_per_chat and args.json and (
+        (args.json.endswith(".json") and os.path.isfile(args.json)) or 
+        (not args.json.endswith(".json") and os.path.isfile(args.json))
     ):
         parser.error("When --per-chat is enabled, the destination of --json must be a directory.")
-    if args.enrich_from_vcards is not None and args.default_contry_code is None:
+    
+    # vCards validation
+    if args.enrich_from_vcards is not None and args.default_country_code is None:
         parser.error("When --enrich-from-vcards is provided, you must also set --default-country-code")
+    
+    # Size validation
     if args.size is not None and not isinstance(args.size, int) and not args.size.isnumeric():
         try:
             args.size = readable_to_bytes(args.size)
         except ValueError:
             parser.error("The value for --split must be ended in pure bytes or with a proper unit (e.g., 1048576 or 1MB)")
+    
+    # Date filter validation and processing
     if args.filter_date is not None:
-        if " - " in args.filter_date:
-            start, end = args.filter_date.split(" - ")
-            start = int(datetime.strptime(start, args.filter_date_format).timestamp())
-            end = int(datetime.strptime(end, args.filter_date_format).timestamp())
-            if start < 1009843200 or end < 1009843200:
-                parser.error("WhatsApp was first released in 2009...")
-            if start > end:
-                parser.error("The start date cannot be a moment after the end date.")
-            if args.android:
-                args.filter_date = f"BETWEEN {start}000 AND {end}000"
-            elif args.ios:
-                args.filter_date = f"BETWEEN {start - APPLE_TIME} AND {end - APPLE_TIME}"
-        else:
-            _timestamp = int(datetime.strptime(args.filter_date[2:], args.filter_date_format).timestamp())
-            if _timestamp < 1009843200:
-                parser.error("WhatsApp was first released in 2009...")
-            if args.filter_date[:2] == "> ":
-                if args.android:
-                    args.filter_date = f">= {_timestamp}000"
-                elif args.ios:
-                    args.filter_date = f">= {_timestamp - APPLE_TIME}"
-            elif args.filter_date[:2] == "< ":
-                if args.android:
-                    args.filter_date = f"<= {_timestamp}000"
-                elif args.ios:
-                    args.filter_date = f"<= {_timestamp - APPLE_TIME}"
-            else:
-                parser.error("Unsupported date format. See https://wts.knugi.dev/docs?dest=date")
+        process_date_filter(parser, args)
+    
+    # Crypt15 key validation
     if args.key is None and args.backup is not None and args.backup.endswith("crypt15"):
         args.key = getpass("Enter your encryption key: ")
+    
+    # Theme validation
     if args.whatsapp_theme:
         args.template = "whatsapp_new.html"
+    
+    # Chat filter validation
     if args.filter_chat_include is not None and args.filter_chat_exclude is not None:
         parser.error("Chat inclusion and exclusion filters cannot be used together.")
-    if args.filter_chat_include is not None:
-        for chat in args.filter_chat_include:
+    
+    validate_chat_filters(parser, args.filter_chat_include)
+    validate_chat_filters(parser, args.filter_chat_exclude)
+
+
+def validate_chat_filters(parser: ArgumentParser, chat_filter: Optional[List[str]]) -> None:
+    """Validate chat filters to ensure they contain only phone numbers."""
+    if chat_filter is not None:
+        for chat in chat_filter:
             if not chat.isnumeric():
                 parser.error("Enter a phone number in the chat filter. See https://wts.knugi.dev/docs?dest=chat")
-    if args.filter_chat_exclude is not None:
-        for chat in args.filter_chat_exclude:
-            if not chat.isnumeric():
-                parser.error("Enter a phone number in the chat filter. See https://wts.knugi.dev/docs?dest=chat")
-    filter_chat = (args.filter_chat_include, args.filter_chat_exclude)
 
-    data = ChatCollection()
 
+def process_date_filter(parser: ArgumentParser, args) -> None:
+    """Process and validate date filter arguments."""
+    if " - " in args.filter_date:
+        start, end = args.filter_date.split(" - ")
+        start = int(datetime.strptime(start, args.filter_date_format).timestamp())
+        end = int(datetime.strptime(end, args.filter_date_format).timestamp())
+        
+        if start < 1009843200 or end < 1009843200:
+            parser.error("WhatsApp was first released in 2009...")
+        if start > end:
+            parser.error("The start date cannot be a moment after the end date.")
+        
+        if args.android:
+            args.filter_date = f"BETWEEN {start}000 AND {end}000"
+        elif args.ios:
+            args.filter_date = f"BETWEEN {start - APPLE_TIME} AND {end - APPLE_TIME}"
+    else:
+        process_single_date_filter(parser, args)
+
+
+def process_single_date_filter(parser: ArgumentParser, args) -> None:
+    """Process single date comparison filters."""
+    if len(args.filter_date) < 3:
+        parser.error("Unsupported date format. See https://wts.knugi.dev/docs?dest=date")
+        
+    _timestamp = int(datetime.strptime(args.filter_date[2:], args.filter_date_format).timestamp())
+    
+    if _timestamp < 1009843200:
+        parser.error("WhatsApp was first released in 2009...")
+    
+    if args.filter_date[:2] == "> ":
+        if args.android:
+            args.filter_date = f">= {_timestamp}000"
+        elif args.ios:
+            args.filter_date = f">= {_timestamp - APPLE_TIME}"
+    elif args.filter_date[:2] == "< ":
+        if args.android:
+            args.filter_date = f"<= {_timestamp}000"
+        elif args.ios:
+            args.filter_date = f"<= {_timestamp - APPLE_TIME}"
+    else:
+        parser.error("Unsupported date format. See https://wts.knugi.dev/docs?dest=date")
+
+
+def setup_contact_store(args) -> Optional['ContactsFromVCards']:
+    """Set up and return a contact store if needed."""
     if args.enrich_from_vcards is not None:
         if not vcards_deps_installed:
-            parser.error(
+            print(
                 "You don't have the dependency to enrich contacts with vCard.\n"
                 "Read more on how to deal with enriching contacts:\n"
                 "https://github.com/KnugiHK/Whatsapp-Chat-Exporter/blob/main/README.md#usage"
             )
+            exit(1)
         contact_store = ContactsFromVCards()
-        contact_store.load_vcf_file(args.enrich_from_vcards, args.default_contry_code)
+        contact_store.load_vcf_file(args.enrich_from_vcards, args.default_country_code)
+        return contact_store
+    return None
 
+
+def decrypt_android_backup(args) -> int:
+    """Decrypt Android backup files and return error code."""
+    if args.key is None or args.backup is None:
+        print("You must specify the backup file with -b and a key with -k")
+        return 1
+    
+    print("Decryption key specified, decrypting WhatsApp backup...")
+    
+    # Determine crypt type
+    if "crypt12" in args.backup:
+        crypt = Crypt.CRYPT12
+    elif "crypt14" in args.backup:
+        crypt = Crypt.CRYPT14
+    elif "crypt15" in args.backup:
+        crypt = Crypt.CRYPT15
+    else:
+        print("Unknown backup format. The backup file must be crypt12, crypt14 or crypt15.")
+        return 1
+    
+    # Get key
+    keyfile_stream = False
+    if not os.path.isfile(args.key) and all(char in string.hexdigits for char in args.key.replace(" ", "")):
+        key = bytes.fromhex(args.key.replace(" ", ""))
+    else:
+        key = open(args.key, "rb")
+        keyfile_stream = True
+    
+    # Read backup
+    db = open(args.backup, "rb").read()
+    
+    # Process WAB if provided
+    error_wa = 0
+    if args.wab:
+        wab = open(args.wab, "rb").read()
+        error_wa = android_crypt.decrypt_backup(
+            wab,
+            key,
+            args.wa,
+            crypt,
+            args.showkey,
+            DbType.CONTACT,
+            keyfile_stream=keyfile_stream
+        )
+        if isinstance(key, io.IOBase):
+            key.seek(0)
+    
+    # Decrypt message database
+    error_message = android_crypt.decrypt_backup(
+        db,
+        key,
+        args.db,
+        crypt,
+        args.showkey,
+        DbType.MESSAGE,
+        keyfile_stream=keyfile_stream
+    )
+    
+    # Handle errors
+    if error_wa != 0:
+        return error_wa
+    return error_message
+
+
+def handle_decrypt_error(error: int) -> None:
+    """Handle decryption errors with appropriate messages."""
+    if error == 1:
+        print("Dependencies of decrypt_backup and/or extract_encrypted_key"
+              " are not present. For details, see README.md.")
+        exit(3)
+    elif error == 2:
+        print("Failed when decompressing the decrypted backup. "
+              "Possibly incorrect offsets used in decryption.")
+        exit(4)
+    else:
+        print("Unknown error occurred.", error)
+        exit(5)
+
+
+def process_contacts(args, data: ChatCollection, contact_store=None) -> None:
+    """Process contacts from the database."""
+    contact_db = args.wa if args.wa else "wa.db" if args.android else "ContactsV2.sqlite"
+    
+    if os.path.isfile(contact_db):
+        with sqlite3.connect(contact_db) as db:
+            db.row_factory = sqlite3.Row
+            if args.android:
+                android_handler.contacts(db, data, args.enrich_from_vcards)
+            else:
+                ios_handler.contacts(db, data)
+
+
+def process_messages(args, data: ChatCollection) -> None:
+    """Process messages, media and vcards from the database."""
+    msg_db = args.db if args.db else "msgstore.db" if args.android else args.identifiers.MESSAGE
+    
+    if not os.path.isfile(msg_db):
+        print(
+            "The message database does not exist. You may specify the path "
+            "to database file with option -d or check your provided path."
+        )
+        exit(6)
+    
+    filter_chat = (args.filter_chat_include, args.filter_chat_exclude)
+    
+    with sqlite3.connect(msg_db) as db:
+        db.row_factory = sqlite3.Row
+        
+        # Process messages
+        if args.android:
+            message_handler = android_handler
+        else:
+            message_handler = ios_handler
+            
+        message_handler.messages(
+            db, data, args.media, args.timezone_offset, 
+            args.filter_date, filter_chat, args.filter_empty
+        )
+        
+        # Process media
+        message_handler.media(
+            db, data, args.media, args.filter_date, 
+            filter_chat, args.filter_empty, args.separate_media
+        )
+        
+        # Process vcards
+        message_handler.vcard(
+            db, data, args.media, args.filter_date, 
+            filter_chat, args.filter_empty
+        )
+        
+        # Process calls
+        process_calls(args, db, data, filter_chat)
+
+
+def process_calls(args, db, data: ChatCollection, filter_chat) -> None:
+    """Process call history if available."""
     if args.android:
-        contacts = android_handler.contacts
-        messages = android_handler.messages
-        media = android_handler.media
-        vcard = android_handler.vcard
-        create_html = android_handler.create_html
-        if args.db is None:
-            msg_db = "msgstore.db"
+        android_handler.calls(db, data, args.timezone_offset, filter_chat)
+    elif args.ios and args.call_db_ios is not None:
+        with sqlite3.connect(args.call_db_ios) as cdb:
+            cdb.row_factory = sqlite3.Row
+            ios_handler.calls(cdb, data, args.timezone_offset, filter_chat)
+
+
+def handle_media_directory(args) -> None:
+    """Handle media directory copying or moving."""
+    if os.path.isdir(args.media):
+        media_path = os.path.join(args.output, args.media)
+        
+        if os.path.isdir(media_path):
+            print("\nWhatsApp directory already exists in output directory. Skipping...", end="\n")
         else:
-            msg_db = args.db
-        if args.wa is None:
-            contact_db = "wa.db"
+            if args.move_media:
+                try:
+                    print("\nMoving media directory...", end="\n")
+                    shutil.move(args.media, f"{args.output}/")
+                except PermissionError:
+                    print("\nCannot remove original WhatsApp directory. "
+                          "Perhaps the directory is opened?", end="\n")
+            else:
+                print("\nCopying media directory...", end="\n")
+                shutil.copytree(args.media, media_path)
+
+
+def create_output_files(args, data: ChatCollection, contact_store=None) -> None:
+    """Create output files in the specified formats."""
+    # Create HTML files if requested
+    if not args.no_html:
+        # Enrich from vcards if available
+        if contact_store and not contact_store.is_empty():
+            contact_store.enrich_from_vcards(data)
+            
+        android_handler.create_html(
+            data,
+            args.output,
+            args.template,
+            args.embedded,
+            args.offline,
+            args.size,
+            args.no_avatar,
+            args.whatsapp_theme,
+            args.headline
+        )
+    
+    # Create text files if requested
+    if args.text_format:
+        print("Writing text file...")
+        android_handler.create_txt(data, args.text_format)
+    
+    # Create JSON files if requested
+    if args.json and not args.import_json:
+        export_json(args, data, contact_store)
+
+
+def export_json(args, data: ChatCollection, contact_store=None) -> None:
+    """Export data to JSON format."""
+    # Enrich from vcards if available
+    if contact_store and not contact_store.is_empty():
+        contact_store.enrich_from_vcards(data)
+    
+    # Convert ChatStore objects to JSON
+    if isinstance(data.get(next(iter(data), None)), ChatStore):
+        data = {jik: chat.to_json() for jik, chat in data.items()}
+    
+    # Export as a single file or per chat
+    if not args.json_per_chat:
+        export_single_json(args, data)
+    else:
+        export_multiple_json(args, data)
+
+
+def export_single_json(args, data: Dict) -> None:
+    """Export data to a single JSON file."""
+    with open(args.json, "w") as f:
+        json_data = json.dumps(
+            data,
+            ensure_ascii=not args.avoid_encoding_json,
+            indent=args.pretty_print_json
+        )
+        print(f"\nWriting JSON file...({bytes_to_readable(len(json_data))})")
+        f.write(json_data)
+
+
+def export_multiple_json(args, data: Dict) -> None:
+    """Export data to multiple JSON files, one per chat."""
+    # Adjust output path if needed
+    json_path = args.json[:-5] if args.json.endswith(".json") else args.json
+    
+    # Create directory if it doesn't exist
+    if not os.path.isdir(json_path):
+        os.makedirs(json_path, exist_ok=True)
+    
+    # Export each chat
+    total = len(data.keys())
+    for index, jik in enumerate(data.keys()):
+        if data[jik]["name"] is not None:
+            contact = data[jik]["name"].replace('/', '')
         else:
-            contact_db = args.wa
-        if args.key is not None:
-            if args.backup is None:
-                print("You must specify the backup file with -b")
-                exit(1)
-            print("Decryption key specified, decrypting WhatsApp backup...")
-            if "crypt12" in args.backup:
-                crypt = Crypt.CRYPT12
-            elif "crypt14" in args.backup:
-                crypt = Crypt.CRYPT14
-            elif "crypt15" in args.backup:
-                crypt = Crypt.CRYPT15
-            else:
-                print("Unknown backup format. The backup file must be crypt12, crypt14 or crypt15.")
-                exit(1)
-            if not os.path.isfile(args.key) and all(char in string.hexdigits for char in args.key.replace(" ", "")):
-                key = bytes.fromhex(args.key.replace(" ", ""))
-                keyfile_stream = False
-            else:
-                key = open(args.key, "rb")
-                keyfile_stream = True
-            db = open(args.backup, "rb").read()
-            if args.wab:
-                wab = open(args.wab, "rb").read()
-                error_wa = android_crypt.decrypt_backup(
-                    wab,
-                    key,
-                    contact_db,
-                    crypt,
-                    args.showkey,
-                    DbType.CONTACT,
-                    keyfile_stream=keyfile_stream
-                )
-                if isinstance(key, io.IOBase):
-                    key.seek(0)
-            else:
-                error_wa = 0
-            error_message = android_crypt.decrypt_backup(
-                db,
-                key,
-                msg_db,
-                crypt,
-                args.showkey,
-                DbType.MESSAGE,
-                keyfile_stream=keyfile_stream
+            contact = jik.replace('+', '')
+            
+        with open(f"{json_path}/{sanitize_filename(contact)}.json", "w") as f:
+            file_content = json.dumps(
+                {jik: data[jik]}, 
+                ensure_ascii=not args.avoid_encoding_json, 
+                indent=args.pretty_print_json
             )
-            if error_wa != 0:
-                error = error_wa
-            elif error_message != 0:
-                error = error_message
-            else:
-                error = 0
-            if error != 0:
-                if error == 1:
-                    print("Dependencies of decrypt_backup and/or extract_encrypted_key"
-                          " are not present. For details, see README.md.")
-                    exit(3)
-                elif error == 2:
-                    print("Failed when decompressing the decrypted backup. "
-                          "Possibly incorrect offsets used in decryption.")
-                    exit(4)
-                else:
-                    print("Unknown error occurred.", error)
-                    exit(5)
-        if args.media is None:
-            args.media = "WhatsApp"
+            f.write(file_content)
+            print(f"Writing JSON file...({index + 1}/{total})", end="\r")
+    print()
 
-        if os.path.isfile(contact_db):
-            with sqlite3.connect(contact_db) as db:
-                db.row_factory = sqlite3.Row
-                contacts(db, data, args.enrich_from_vcards)
-    elif args.ios:
-        contacts = ios_handler.contacts
-        messages = ios_handler.messages
-        media = ios_handler.media
-        vcard = ios_handler.vcard
-        create_html = android_handler.create_html
-        if args.business:
-            from Whatsapp_Chat_Exporter.utility import WhatsAppBusinessIdentifier as identifiers
-        else:
-            from Whatsapp_Chat_Exporter.utility import WhatsAppIdentifier as identifiers
-        if args.media is None:
-            args.media = identifiers.DOMAIN
-        if args.backup is not None:
-            if not os.path.isdir(args.media):
-                ios_media_handler.extract_media(args.backup, identifiers, args.decrypt_chunk_size)
-            else:
-                print("WhatsApp directory already exists, skipping WhatsApp file extraction.")
-        if args.db is None:
-            msg_db = identifiers.MESSAGE
-        else:
-            msg_db = args.db
-        if args.wa is None:
-            contact_db = "ContactsV2.sqlite"
-        else:
-            contact_db = args.wa
-        if os.path.isfile(contact_db):
-            with sqlite3.connect(contact_db) as db:
-                db.row_factory = sqlite3.Row
-                contacts(db, data)
 
-    if not args.exported and not args.import_json:
-        if os.path.isfile(msg_db):
-            with sqlite3.connect(msg_db) as db:
-                db.row_factory = sqlite3.Row
-                messages(db, data, args.media, args.timezone_offset, args.filter_date, filter_chat, args.filter_empty)
-                media(db, data, args.media, args.filter_date, filter_chat, args.filter_empty, args.separate_media)
-                vcard(db, data, args.media, args.filter_date, filter_chat, args.filter_empty)
-                if args.android:
-                    android_handler.calls(db, data, args.timezone_offset, filter_chat)
-                elif args.ios and args.call_db_ios is not None:
-                    with sqlite3.connect(args.call_db_ios) as cdb:
-                        cdb.row_factory = sqlite3.Row
-                        ios_handler.calls(cdb, data, args.timezone_offset, filter_chat)
-            if not args.no_html:
-                if args.enrich_from_vcards is not None and not contact_store.is_empty():
-                    contact_store.enrich_from_vcards(data)
+def process_exported_chat(args, data: ChatCollection) -> None:
+    """Process an exported chat file."""
+    exported_handler.messages(args.exported, data, args.assume_first_as_me)
+    
+    if not args.no_html:
+        android_handler.create_html(
+            data,
+            args.output,
+            args.template,
+            args.embedded,
+            args.offline,
+            args.size,
+            args.no_avatar,
+            args.whatsapp_theme,
+            args.headline
+        )
+    
+    # Copy files to output directory
+    for file in glob.glob(r'*.*'):
+        shutil.copy(file, args.output)
 
-                create_html(
-                    data,
-                    args.output,
-                    args.template,
-                    args.embedded,
-                    args.offline,
-                    args.size,
-                    args.no_avatar,
-                    args.whatsapp_theme,
-                    args.headline
-                )
-        else:
-            print(
-                "The message database does not exist. You may specify the path "
-                "to database file with option -d or check your provided path."
-            )
-            exit(6)
 
-        if os.path.isdir(args.media):
-            media_path = os.path.join(args.output, args.media)
-            if os.path.isdir(media_path):
-                print("\nWhatsApp directory already exists in output directory. Skipping...", end="\n")
-            else:
-                if not args.move_media:
-                    if os.path.isdir(media_path):
-                        print("\nWhatsApp directory already exists in output directory. Skipping...", end="\n")
-                    else:
-                        print("\nCopying media directory...", end="\n")
-                        shutil.copytree(args.media, media_path)
-                else:
-                    try:
-                        shutil.move(args.media, f"{args.output}/")
-                    except PermissionError:
-                        print("\nCannot remove original WhatsApp directory. "
-                            "Perhaps the directory is opened?", end="\n")
-    elif args.exported:
-        exported_handler.messages(args.exported, data, args.assume_first_as_me)
-        if not args.no_html:
-            android_handler.create_html(
-                data,
-                args.output,
-                args.template,
-                args.embedded,
-                args.offline,
-                args.size,
-                args.no_avatar,
-                args.whatsapp_theme,
-                args.headline
-            )
-        for file in glob.glob(r'*.*'):
-            shutil.copy(file, args.output)
-    elif args.import_json:
+def main():
+    """Main function to run the WhatsApp Chat Exporter."""
+    # Set up and parse arguments
+    parser = setup_argument_parser()
+    args = parser.parse_args()
+    
+    # Check for updates
+    if args.check_update:
+        exit(check_update())
+    
+    # Validate arguments
+    validate_args(parser, args)
+    
+    # Create output directory if it doesn't exist
+    os.makedirs(args.output, exist_ok=True)
+    
+    # Initialize data collection
+    data = ChatCollection()
+    
+    # Set up contact store for vCard enrichment if needed
+    contact_store = setup_contact_store(args)
+    
+    if args.import_json:
+        # Import from JSON
         import_from_json(args.json, data)
         android_handler.create_html(
             data,
@@ -610,48 +666,62 @@ def main():
             args.whatsapp_theme,
             args.headline
         )
-
-    if args.text_format:
-        print("Writing text file...")
-        android_handler.create_txt(data, args.text_format)
-
-    if args.json and not args.import_json:
-        if args.enrich_from_vcards is not None and not contact_store.is_empty():
-            contact_store.enrich_from_vcards(data)
-
-        if isinstance(data[next(iter(data))], ChatStore):
-            data = {jik: chat.to_json() for jik, chat in data.items()}
-            
-        if not args.json_per_chat:
-            with open(args.json, "w") as f:
-                data = json.dumps(
-                    data,
-                    ensure_ascii=not args.avoid_encoding_json,
-                    indent=args.pretty_print_json
-                )
-                print(f"\nWriting JSON file...({bytes_to_readable(len(data))})")
-                f.write(data)
-        else:
-            if args.json[-5:] == ".json":
-                args.json = args.json[:-5]
-            total = len(data.keys())
-            if not os.path.isdir(args.json):
-                os.mkdir(args.json)
-            for index, jik in enumerate(data.keys()):
-                if data[jik]["name"] is not None:
-                    contact = data[jik]["name"].replace('/', '')
-                else:
-                    contact = jik.replace('+', '')
-                with open(f"{args.json}/{sanitize_filename(contact)}.json", "w") as f:
-                    file_content_to_write = json.dumps({jik: data[jik]}, ensure_ascii=not args.avoid_encoding_json, indent=2 if args.pretty_print_json else None)
-                    f.write(file_content_to_write)
-                    print(f"Writing JSON file...({index + 1}/{total})", end="\r")
-            print()
+    elif args.exported:
+        # Process exported chat
+        process_exported_chat(args, data)
     else:
-        print()
+        # Process Android or iOS data
+        if args.android:
+            # Set default media path if not provided
+            if args.media is None:
+                args.media = "WhatsApp"
+                
+            # Set default DB paths if not provided
+            if args.db is None:
+                args.db = "msgstore.db"
+            if args.wa is None:
+                args.wa = "wa.db"
+                
+            # Decrypt backup if needed
+            if args.key is not None:
+                error = decrypt_android_backup(args)
+                if error != 0:
+                    handle_decrypt_error(error)
+        elif args.ios:
+            # Set up identifiers based on business flag
+            if args.business:
+                from Whatsapp_Chat_Exporter.utility import WhatsAppBusinessIdentifier as identifiers
+            else:
+                from Whatsapp_Chat_Exporter.utility import WhatsAppIdentifier as identifiers
+            args.identifiers = identifiers
+            
+            # Set default media path if not provided
+            if args.media is None:
+                args.media = identifiers.DOMAIN
+                
+            # Extract media from backup if needed
+            if args.backup is not None:
+                if not os.path.isdir(args.media):
+                    ios_media_handler.extract_media(args.backup, identifiers, args.decrypt_chunk_size)
+                else:
+                    print("WhatsApp directory already exists, skipping WhatsApp file extraction.")
+                    
+            # Set default DB paths if not provided
+            if args.db is None:
+                args.db = identifiers.MESSAGE
+            if args.wa is None:
+                args.wa = "ContactsV2.sqlite"
+        
+        # Process contacts
+        process_contacts(args, data, contact_store)
+        
+        # Process messages, media, and calls
+        process_messages(args, data)
+        
+        # Create output files
+        create_output_files(args, data, contact_store)
+        
+        # Handle media directory
+        handle_media_directory(args)
 
-    print("Everything is done!")
-
-
-if __name__ == "__main__":
-    main()
+        print("Everything is done!")
\ No newline at end of file
diff --git a/Whatsapp_Chat_Exporter/android_handler.py b/Whatsapp_Chat_Exporter/android_handler.py
index 3374c8c..71b5dcd 100644
--- a/Whatsapp_Chat_Exporter/android_handler.py
+++ b/Whatsapp_Chat_Exporter/android_handler.py
@@ -670,7 +670,7 @@ def create_html(
             if maximum_size == 0:
                 maximum_size = MAX_SIZE
             last_msg = current_chat.get_last_message().key_id
-            for message in current_chat.get_messages():
+            for message in current_chat.values():
                 if message.data is not None and not message.meta and not message.media:
                     current_size += len(message.data) + ROW_SIZE
                 else:
@@ -717,7 +717,7 @@ def create_html(
                 output_file_name,
                 template,
                 name,
-                current_chat.get_messages(),
+                current_chat.values(),
                 contact,
                 w3css,
                 current_chat,
@@ -739,7 +739,7 @@ def create_txt(data, output):
             contact = jik.replace('+', '')
         output_file = os.path.join(output, f"{contact}.txt")
         with open(output_file, "w", encoding="utf8") as f:
-            for message in chat.get_messages():
+            for message in chat.values():
                 date = datetime.fromtimestamp(message.timestamp).date()
                 if message.meta and message.mime != "media":
                     continue  # Skip any metadata in text format
diff --git a/Whatsapp_Chat_Exporter/data_model.py b/Whatsapp_Chat_Exporter/data_model.py
index 578713a..8989369 100644
--- a/Whatsapp_Chat_Exporter/data_model.py
+++ b/Whatsapp_Chat_Exporter/data_model.py
@@ -213,11 +213,19 @@ class ChatStore:
     def get_last_message(self) -> 'Message':
         """Get the most recent message in the chat."""
         return tuple(self._messages.values())[-1]
+    
+    def items(self):
+        """Get message items pairs."""
+        return self._messages.items()
 
-    def get_messages(self) -> 'Message':
+    def values(self):
         """Get all messages in the chat."""
         return self._messages.values()
 
+    def keys(self):
+        """Get all message keys in the chat."""
+        return self._messages.keys()
+
 
 class Message:
     """
diff --git a/Whatsapp_Chat_Exporter/exported_handler.py b/Whatsapp_Chat_Exporter/exported_handler.py
index 0aae498..7215f6f 100644
--- a/Whatsapp_Chat_Exporter/exported_handler.py
+++ b/Whatsapp_Chat_Exporter/exported_handler.py
@@ -8,85 +8,174 @@ from Whatsapp_Chat_Exporter.utility import Device
 
 
 def messages(path, data, assume_first_as_me=False):
-    """Extracts messages from the exported file"""
+    """
+    Extracts messages from an exported WhatsApp chat file.
+    
+    Args:
+        path: Path to the exported chat file
+        data: Data container object to store the parsed chat
+        assume_first_as_me: If True, assumes the first message is sent from the user without asking
+        
+    Returns:
+        Updated data container with extracted messages
+    """
+    # Create a new chat in the data container
+    chat = data.add_chat("ExportedChat", ChatStore(Device.EXPORTED))
+    you = ""  # Will store the username of the current user
+    user_identification_done = False  # Flag to track if user identification has been done
+    
+    # First pass: count total lines for progress reporting
+    with open(path, "r", encoding="utf8") as file:
+        total_row_number = sum(1 for _ in file)
+    
+    # Second pass: process the messages
     with open(path, "r", encoding="utf8") as file:
-        you = ""
-        data["ExportedChat"] = ChatStore(Device.EXPORTED)
-        chat = data["ExportedChat"]
-        total_row_number = len(file.readlines())
-        file.seek(0)
         for index, line in enumerate(file):
-            if len(line.split(" - ")) > 1:
-                time = line.split(" - ")[0]
-                if ":" not in line.split(time)[1]:
-                    msg.data = line.split(time)[1][3:]
-                    msg.meta = True
-                else:
-                    name = line.split(time)[1].split(":")[0]
-                    message = line.split(time)[1].split(name + ":")[1].strip()
-                    name = name[3:]
-                    if you == "":
-                        if chat.name is None:
-                            if not assume_first_as_me:
-                                while True:
-                                    ans = input(f"Is '{name}' you? (Y/N)").lower()
-                                    if ans == "y":
-                                        you = name
-                                        break
-                                    elif ans == "n":
-                                        chat.name = name
-                                        break
-                            else:
-                                you = name
-                        else:
-                            if name != chat.name:
-                                you = name
-                    elif chat.name is None:
-                        if name != you:
-                            chat.name = name
-                    msg = Message(
-                        you == name,
-                        datetime.strptime(time, "%d/%m/%Y, %H:%M").timestamp(),
-                        time.split(", ")[1].strip(),
-                        index
-                    )
-                    if "<Media omitted>" in message:
-                        msg.data = "The media is omitted in the chat"
-                        msg.mime = "media"
-                        msg.meta = True
-                    elif "(file attached)" in message:
-                        mime = MimeTypes()
-                        msg.media = True
-                        file_path = os.path.join(os.path.dirname(path), message.split("(file attached)")[0].strip())
-                        if os.path.isfile(file_path):
-                            msg.data = file_path
-                            guess = mime.guess_type(file_path)[0]
-                            if guess is not None:
-                                msg.mime = guess
-                            else:
-                                msg.mime = "application/octet-stream"
-                        else:
-                            msg.data = "The media is missing"
-                            msg.mime = "media"
-                            msg.meta = True
-                    else:
-                        msg.data = message
-                        if "\r\n" in message:
-                            msg.data = message.replace("\r\n", "<br>")
-                        if "\n" in message:
-                            msg.data = message.replace("\n", "<br>")
-                chat.add_message(index, msg)
-            else:
-                lookback = index - 1
-                while lookback not in chat.messages:
-                    lookback -= 1
-                msg = chat.messages[lookback]
-                if msg.media:
-                    msg.caption = line.strip()
-                else:
-                    msg.data += "<br>" + line.strip()
-            
+            you, user_identification_done = process_line(
+                line, index, chat, path, you, 
+                assume_first_as_me, user_identification_done
+            )
+
+            # Show progress
             if index % 1000 == 0:
                 print(f"Processing messages & media...({index}/{total_row_number})", end="\r")
-    print(f"Processing messages & media...({total_row_number}/{total_row_number})", end="\r")
+
+    print(f"Processing messages & media...({total_row_number}/{total_row_number})")
     return data
+
+
+def process_line(line, index, chat, file_path, you, assume_first_as_me, user_identification_done):
+    """
+    Process a single line from the chat file
+    
+    Returns:
+        Tuple of (updated_you_value, updated_user_identification_done_flag)
+    """
+    parts = line.split(" - ", 1)
+    
+    # Check if this is a new message (has timestamp format)
+    if len(parts) > 1:
+        time = parts[0]
+        you, user_identification_done = process_new_message(
+            time, parts[1], index, chat, you, file_path, 
+            assume_first_as_me, user_identification_done
+        )
+    else:
+        # This is a continuation of the previous message
+        process_message_continuation(line, index, chat)
+    
+    return you, user_identification_done
+
+
+def process_new_message(time, content, index, chat, you, file_path, 
+                        assume_first_as_me, user_identification_done):
+    """
+    Process a line that contains a new message
+    
+    Returns:
+        Tuple of (updated_you_value, updated_user_identification_done_flag)
+    """
+    # Create a new message
+    msg = Message(
+        from_me=False,  # Will be updated later if needed
+        timestamp=datetime.strptime(time, "%d/%m/%Y, %H:%M").timestamp(),
+        time=time.split(", ")[1].strip(),
+        key_id=index,
+        received_timestamp=None,
+        read_timestamp=None
+    )
+    
+    # Check if this is a system message (no name:message format)
+    if ":" not in content:
+        msg.data = content
+        msg.meta = True
+    else:
+        # Process user message
+        name, message = content.strip().split(":", 1)
+        
+        # Handle user identification
+        if you == "":
+            if chat.name is None:
+                # First sender identification
+                if not user_identification_done:
+                    if not assume_first_as_me:
+                        # Ask only once if this is the user
+                        you = prompt_for_user_identification(name)
+                        user_identification_done = True
+                    else:
+                        you = name
+                        user_identification_done = True
+            else:
+                # If we know the chat name, anyone else must be "you"
+                if name != chat.name:
+                    you = name
+        
+        # Set the chat name if needed
+        if chat.name is None and name != you:
+            chat.name = name
+        
+        # Determine if this message is from the current user
+        msg.from_me = (name == you)
+        
+        # Process message content
+        process_message_content(msg, message, file_path)
+    
+    chat.add_message(index, msg)
+    return you, user_identification_done
+
+
+def process_message_content(msg, message, file_path):
+    """Process and set the content of a message based on its type"""
+    if "<Media omitted>" in message:
+        msg.data = "The media is omitted in the chat"
+        msg.mime = "media"
+        msg.meta = True
+    elif "(file attached)" in message:
+        process_attached_file(msg, message, file_path)
+    else:
+        msg.data = message.replace("\r\n", "<br>").replace("\n", "<br>")
+
+
+def process_attached_file(msg, message, file_path):
+    """Process an attached file in a message"""
+    mime = MimeTypes()
+    msg.media = True
+    
+    # Extract file path and check if it exists
+    file_name = message.split("(file attached)")[0].strip()
+    attached_file_path = os.path.join(os.path.dirname(file_path), file_name)
+    
+    if os.path.isfile(attached_file_path):
+        msg.data = attached_file_path
+        guess = mime.guess_type(attached_file_path)[0]
+        msg.mime = guess if guess is not None else "application/octet-stream"
+    else:
+        msg.data = "The media is missing"
+        msg.mime = "media"
+        msg.meta = True
+
+
+def process_message_continuation(line, index, chat):
+    """Process a line that continues a previous message"""
+    # Find the previous message
+    lookback = index - 1
+    while lookback not in chat.keys():
+        lookback -= 1
+    
+    msg = chat.get_message(lookback)
+    
+    # Add the continuation line to the message
+    if msg.media:
+        msg.caption = line.strip()
+    else:
+        msg.data += "<br>" + line.strip()
+
+
+def prompt_for_user_identification(name):
+    """Ask the user if the given name is their username"""
+    while True:
+        ans = input(f"Is '{name}' you? (Y/N)").lower()
+        if ans == "y":
+            return name
+        elif ans == "n":
+            return ""
\ No newline at end of file
diff --git a/Whatsapp_Chat_Exporter/ios_handler.py b/Whatsapp_Chat_Exporter/ios_handler.py
index 1232a3f..7a15835 100644
--- a/Whatsapp_Chat_Exporter/ios_handler.py
+++ b/Whatsapp_Chat_Exporter/ios_handler.py
@@ -12,144 +12,179 @@ from Whatsapp_Chat_Exporter.utility import bytes_to_readable, convert_time_unit,
 
 
 def contacts(db, data):
+    """Process WhatsApp contacts with status information."""
     c = db.cursor()
-    # Get status only lol
     c.execute("""SELECT count() FROM ZWAADDRESSBOOKCONTACT WHERE ZABOUTTEXT IS NOT NULL""")
     total_row_number = c.fetchone()[0]
     print(f"Pre-processing contacts...({total_row_number})")
+    
     c.execute("""SELECT ZWHATSAPPID, ZABOUTTEXT FROM ZWAADDRESSBOOKCONTACT WHERE ZABOUTTEXT IS NOT NULL""")
     content = c.fetchone()
     while content is not None:
-        if not content["ZWHATSAPPID"].endswith("@s.whatsapp.net"):
-            ZWHATSAPPID = content["ZWHATSAPPID"] + "@s.whatsapp.net"
+        zwhatsapp_id = content["ZWHATSAPPID"]
+        if not zwhatsapp_id.endswith("@s.whatsapp.net"):
+            zwhatsapp_id += "@s.whatsapp.net"
+            
         current_chat = ChatStore(Device.IOS)
         current_chat.status = content["ZABOUTTEXT"]
-        data.add_chat(ZWHATSAPPID, current_chat)
+        data.add_chat(zwhatsapp_id, current_chat)
         content = c.fetchone()
 
 
+def process_contact_avatars(current_chat, media_folder, contact_id):
+    """Process and assign avatar images for a contact."""
+    path = f'{media_folder}/Media/Profile/{contact_id.split("@")[0]}'
+    avatars = glob(f"{path}*")
+    
+    if 0 < len(avatars) <= 1:
+        current_chat.their_avatar = avatars[0]
+    else:
+        for avatar in avatars:
+            if avatar.endswith(".thumb") and current_chat.their_avatar_thumb is None:
+                current_chat.their_avatar_thumb = avatar
+            elif avatar.endswith(".jpg") and current_chat.their_avatar is None:
+                current_chat.their_avatar = avatar
+
+
+def get_contact_name(content):
+    """Determine the appropriate contact name based on push name and partner name."""
+    is_phone = content["ZPARTNERNAME"].replace("+", "").replace(" ", "").isdigit()
+    if content["ZPUSHNAME"] is None or (content["ZPUSHNAME"] and not is_phone):
+        return content["ZPARTNERNAME"]
+    else:
+        return content["ZPUSHNAME"]
+
+
 def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat, filter_empty):
+    """Process WhatsApp messages and contacts from the database."""
     c = db.cursor()
     cursor2 = db.cursor()
-    # Get contacts
-    c.execute(
-        f"""SELECT count() 
-            FROM (SELECT DISTINCT ZCONTACTJID,
-                ZPARTNERNAME,
-                ZWAPROFILEPUSHNAME.ZPUSHNAME
-            FROM ZWACHATSESSION
-                INNER JOIN ZWAMESSAGE
-                    ON ZWAMESSAGE.ZCHATSESSION = ZWACHATSESSION.Z_PK
-                LEFT JOIN ZWAPROFILEPUSHNAME
-                    ON ZWACHATSESSION.ZCONTACTJID = ZWAPROFILEPUSHNAME.ZJID
-                LEFT JOIN ZWAGROUPMEMBER
-                        ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
-            WHERE 1=1
-                {get_chat_condition(filter_chat[0], True, ["ZWACHATSESSION.ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")}
-                {get_chat_condition(filter_chat[1], False, ["ZWACHATSESSION.ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")}
-            GROUP BY ZCONTACTJID);"""
-    )
+    
+    # Build the chat filter conditions
+    chat_filter_include = get_chat_condition(filter_chat[0], True, ["ZWACHATSESSION.ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")
+    chat_filter_exclude = get_chat_condition(filter_chat[1], False, ["ZWACHATSESSION.ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")
+    date_filter = f'AND ZMESSAGEDATE {filter_date}' if filter_date is not None else ''
+    
+    # Process contacts first
+    contact_query = f"""
+        SELECT count() 
+        FROM (SELECT DISTINCT ZCONTACTJID,
+            ZPARTNERNAME,
+            ZWAPROFILEPUSHNAME.ZPUSHNAME
+        FROM ZWACHATSESSION
+            INNER JOIN ZWAMESSAGE
+                ON ZWAMESSAGE.ZCHATSESSION = ZWACHATSESSION.Z_PK
+            LEFT JOIN ZWAPROFILEPUSHNAME
+                ON ZWACHATSESSION.ZCONTACTJID = ZWAPROFILEPUSHNAME.ZJID
+            LEFT JOIN ZWAGROUPMEMBER
+                    ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
+        WHERE 1=1
+            {chat_filter_include}
+            {chat_filter_exclude}
+        GROUP BY ZCONTACTJID);
+    """
+    c.execute(contact_query)
     total_row_number = c.fetchone()[0]
     print(f"Processing contacts...({total_row_number})")
 
-    c.execute(
-        f"""SELECT DISTINCT ZCONTACTJID,
-                ZPARTNERNAME,
-                ZWAPROFILEPUSHNAME.ZPUSHNAME
-            FROM ZWACHATSESSION
-                INNER JOIN ZWAMESSAGE
-                    ON ZWAMESSAGE.ZCHATSESSION = ZWACHATSESSION.Z_PK
-                LEFT JOIN ZWAPROFILEPUSHNAME
-                    ON ZWACHATSESSION.ZCONTACTJID = ZWAPROFILEPUSHNAME.ZJID
-                LEFT JOIN ZWAGROUPMEMBER
-                        ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
-            WHERE 1=1
-                {get_chat_condition(filter_chat[0], True, ["ZWACHATSESSION.ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")}
-                {get_chat_condition(filter_chat[1], False, ["ZWACHATSESSION.ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")}
-            GROUP BY ZCONTACTJID;"""
-    )
+    # Get distinct contacts
+    contacts_query = f"""
+        SELECT DISTINCT ZCONTACTJID,
+            ZPARTNERNAME,
+            ZWAPROFILEPUSHNAME.ZPUSHNAME
+        FROM ZWACHATSESSION
+            INNER JOIN ZWAMESSAGE
+                ON ZWAMESSAGE.ZCHATSESSION = ZWACHATSESSION.Z_PK
+            LEFT JOIN ZWAPROFILEPUSHNAME
+                ON ZWACHATSESSION.ZCONTACTJID = ZWAPROFILEPUSHNAME.ZJID
+            LEFT JOIN ZWAGROUPMEMBER
+                    ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
+        WHERE 1=1
+            {chat_filter_include}
+            {chat_filter_exclude}
+        GROUP BY ZCONTACTJID;
+    """
+    c.execute(contacts_query)
+    
+    # Process each contact
     content = c.fetchone()
     while content is not None:
-        is_phone = content["ZPARTNERNAME"].replace("+", "").replace(" ", "").isdigit()
-        if content["ZPUSHNAME"] is None or (content["ZPUSHNAME"] and not is_phone):
-            contact_name = content["ZPARTNERNAME"]
-        else:
-            contact_name = content["ZPUSHNAME"]
+        contact_name = get_contact_name(content)
         contact_id = content["ZCONTACTJID"]
+        
+        # Add or update chat
         if contact_id not in data:
             current_chat = data.add_chat(contact_id, ChatStore(Device.IOS, contact_name, media_folder))
         else:
             current_chat = data.get_chat(contact_id)
             current_chat.name = contact_name
             current_chat.my_avatar = os.path.join(media_folder, "Media/Profile/Photo.jpg")
-        path = f'{media_folder}/Media/Profile/{contact_id.split("@")[0]}'
-        avatars = glob(f"{path}*")
-        if 0 < len(avatars) <= 1:
-            current_chat.their_avatar = avatars[0]
-        else:
-            for avatar in avatars:
-                if avatar.endswith(".thumb") and current_chat.their_avatar_thumb is None:
-                    current_chat.their_avatar_thumb = avatar
-                elif avatar.endswith(".jpg") and current_chat.their_avatar is None:
-                    current_chat.their_avatar = avatar
+        
+        # Process avatar images
+        process_contact_avatars(current_chat, media_folder, contact_id)
         content = c.fetchone()
 
-    # Get message history
-    c.execute(f"""SELECT count()
-                  FROM ZWAMESSAGE
-                        INNER JOIN ZWACHATSESSION
-                            ON ZWAMESSAGE.ZCHATSESSION = ZWACHATSESSION.Z_PK
-                        LEFT JOIN ZWAGROUPMEMBER
-                            ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
-                  WHERE 1=1
-                    {f'AND ZMESSAGEDATE {filter_date}' if filter_date is not None else ''}
-                    {get_chat_condition(filter_chat[0], True, ["ZWACHATSESSION.ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")}
-                    {get_chat_condition(filter_chat[1], False, ["ZWACHATSESSION.ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")}""")
+    # Get message count
+    message_count_query = f"""
+        SELECT count()
+        FROM ZWAMESSAGE
+            INNER JOIN ZWACHATSESSION
+                ON ZWAMESSAGE.ZCHATSESSION = ZWACHATSESSION.Z_PK
+            LEFT JOIN ZWAGROUPMEMBER
+                ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
+        WHERE 1=1
+            {date_filter}
+            {chat_filter_include}
+            {chat_filter_exclude}
+    """
+    c.execute(message_count_query)
     total_row_number = c.fetchone()[0]
     print(f"Processing messages...(0/{total_row_number})", end="\r")
-    c.execute(f"""SELECT ZCONTACTJID,
-                        ZWAMESSAGE.Z_PK,
-                        ZISFROMME,
-                        ZMESSAGEDATE,
-                        ZTEXT,
-                        ZMESSAGETYPE,
-                        ZWAGROUPMEMBER.ZMEMBERJID,
-						ZMETADATA,
-                        ZSTANZAID,
-                        ZGROUPINFO,
-                        ZSENTDATE
-                 FROM ZWAMESSAGE
-                    LEFT JOIN ZWAGROUPMEMBER
-                        ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
-					LEFT JOIN ZWAMEDIAITEM
-						ON ZWAMESSAGE.Z_PK = ZWAMEDIAITEM.ZMESSAGE
-                    INNER JOIN ZWACHATSESSION
-                        ON ZWAMESSAGE.ZCHATSESSION = ZWACHATSESSION.Z_PK
-                 WHERE 1=1   
-                    {f'AND ZMESSAGEDATE {filter_date}' if filter_date is not None else ''}
-                    {get_chat_condition(filter_chat[0], True, ["ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")}
-                    {get_chat_condition(filter_chat[1], False, ["ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")}
-                 ORDER BY ZMESSAGEDATE ASC;""")
+    
+    # Fetch messages
+    messages_query = f"""
+        SELECT ZCONTACTJID,
+            ZWAMESSAGE.Z_PK,
+            ZISFROMME,
+            ZMESSAGEDATE,
+            ZTEXT,
+            ZMESSAGETYPE,
+            ZWAGROUPMEMBER.ZMEMBERJID,
+            ZMETADATA,
+            ZSTANZAID,
+            ZGROUPINFO,
+            ZSENTDATE
+        FROM ZWAMESSAGE
+            LEFT JOIN ZWAGROUPMEMBER
+                ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
+            LEFT JOIN ZWAMEDIAITEM
+                ON ZWAMESSAGE.Z_PK = ZWAMEDIAITEM.ZMESSAGE
+            INNER JOIN ZWACHATSESSION
+                ON ZWAMESSAGE.ZCHATSESSION = ZWACHATSESSION.Z_PK
+        WHERE 1=1   
+            {date_filter}
+            {chat_filter_include}
+            {chat_filter_exclude}
+        ORDER BY ZMESSAGEDATE ASC;
+    """
+    c.execute(messages_query)
+    
+    # Process each message
     i = 0
     content = c.fetchone()
     while content is not None:
-        ZCONTACTJID = content["ZCONTACTJID"]
-        Z_PK = content["Z_PK"]
+        contact_id = content["ZCONTACTJID"]
+        message_pk = content["Z_PK"]
         is_group_message = content["ZGROUPINFO"] is not None
-        if ZCONTACTJID not in data:
-            current_chat = data.add_chat(ZCONTACTJID, ChatStore(Device.IOS))
-            path = f'{media_folder}/Media/Profile/{ZCONTACTJID.split("@")[0]}'
-            avatars = glob(f"{path}*")
-            if 0 < len(avatars) <= 1:
-                current_chat.their_avatar = avatars[0]
-            else:
-                for avatar in avatars:
-                    if avatar.endswith(".thumb"):
-                        current_chat.their_avatar_thumb = avatar
-                    elif avatar.endswith(".jpg"):
-                        current_chat.their_avatar = avatar
+        
+        # Ensure chat exists
+        if contact_id not in data:
+            current_chat = data.add_chat(contact_id, ChatStore(Device.IOS))
+            process_contact_avatars(current_chat, media_folder, contact_id)
         else:
-            current_chat = data.get_chat(ZCONTACTJID)
+            current_chat = data.get_chat(contact_id)
+        
+        # Create message object
         ts = APPLE_TIME + content["ZMESSAGEDATE"]
         message = Message(
             from_me=content["ZISFROMME"],
@@ -159,290 +194,409 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
             timezone_offset=timezone_offset if timezone_offset else CURRENT_TZ_OFFSET,
             message_type=content["ZMESSAGETYPE"],
             received_timestamp=APPLE_TIME + content["ZSENTDATE"] if content["ZSENTDATE"] else None,
-            read_timestamp=None # TODO: Add timestamp
+            read_timestamp=None  # TODO: Add timestamp
         )
-        invalid = False
-        if is_group_message and content["ZISFROMME"] == 0:
-            name = None
-            if content["ZMEMBERJID"] is not None:
-                if content["ZMEMBERJID"] in data:
-                    name = data.get_chat(content["ZMEMBERJID"]).name
-                if "@" in content["ZMEMBERJID"]:
-                    fallback = content["ZMEMBERJID"].split('@')[0]
-                else:
-                    fallback = None
-            else:
-                fallback = None
-            message.sender = name or fallback
-        else:
-            message.sender = None
-        if content["ZMESSAGETYPE"] == 6:
-            # Metadata
-            if is_group_message:
-                # Group
-                if content["ZTEXT"] is not None:
-                    # Chnaged name
-                    try:
-                        int(content["ZTEXT"])
-                    except ValueError:
-                        msg = f"The group name changed to {content['ZTEXT']}"
-                        message.data = msg
-                        message.meta = True
-                    else:
-                        invalid = True
-                else:
-                    message.data = None
-            else:
-                message.data = None
-        else:
-            # real message
-            if content["ZMETADATA"] is not None and content["ZMETADATA"].startswith(b"\x2a\x14"):
-                quoted = content["ZMETADATA"][2:19]
-                message.reply = quoted.decode()
-                cursor2.execute(f"""SELECT ZTEXT
-                                    FROM ZWAMESSAGE
-                                    WHERE ZSTANZAID LIKE '{message.reply}%'""")
-                quoted_content = cursor2.fetchone()
-                if quoted_content and "ZTEXT" in quoted_content:
-                    message.quoted_data = quoted_content["ZTEXT"] 
-                else:
-                    message.quoted_data = None
-            if content["ZMESSAGETYPE"] == 15: # Sticker
-                message.sticker = True
-
-            if content["ZISFROMME"] == 1:
-                if content["ZMESSAGETYPE"] == 14:
-                    msg = "Message deleted"
-                    message.meta = True
-                else:
-                    msg = content["ZTEXT"]
-                    if msg is not None:
-                        if "\r\n" in msg:
-                            msg = msg.replace("\r\n", "<br>")
-                        if "\n" in msg:
-                            msg = msg.replace("\n", "<br>")
-            else:
-                if content["ZMESSAGETYPE"] == 14:
-                    msg = "Message deleted"
-                    message.meta = True
-                else:
-                    msg = content["ZTEXT"]
-                    if msg is not None:
-                        if "\r\n" in msg:
-                            msg = msg.replace("\r\n", "<br>")
-                        if "\n" in msg:
-                            msg = msg.replace("\n", "<br>")
-            message.data = msg
+        
+        # Process message data
+        invalid = process_message_data(message, content, is_group_message, data, cursor2)
+        
+        # Add valid messages to chat
         if not invalid:
-            current_chat.add_message(Z_PK, message)
+            current_chat.add_message(message_pk, message)
+        
+        # Update progress
         i += 1
         if i % 1000 == 0:
             print(f"Processing messages...({i}/{total_row_number})", end="\r")
         content = c.fetchone()
+    
     print(f"Processing messages...({total_row_number}/{total_row_number})", end="\r")
 
 
+def process_message_data(message, content, is_group_message, data, cursor2):
+    """Process and set message data from content row."""
+    # Handle group sender info
+    if is_group_message and content["ZISFROMME"] == 0:
+        name = None
+        if content["ZMEMBERJID"] is not None:
+            if content["ZMEMBERJID"] in data:
+                name = data.get_chat(content["ZMEMBERJID"]).name
+            if "@" in content["ZMEMBERJID"]:
+                fallback = content["ZMEMBERJID"].split('@')[0]
+            else:
+                fallback = None
+        else:
+            fallback = None
+        message.sender = name or fallback
+    else:
+        message.sender = None
+    
+    # Handle metadata messages
+    if content["ZMESSAGETYPE"] == 6:
+        return process_metadata_message(message, content, is_group_message)
+    
+    # Handle quoted replies
+    if content["ZMETADATA"] is not None and content["ZMETADATA"].startswith(b"\x2a\x14") and False:
+        quoted = content["ZMETADATA"][2:19]
+        message.reply = quoted.decode()
+        cursor2.execute(f"""SELECT ZTEXT
+                            FROM ZWAMESSAGE
+                            WHERE ZSTANZAID LIKE '{message.reply}%'""")
+        quoted_content = cursor2.fetchone()
+        if quoted_content and "ZTEXT" in quoted_content:
+            message.quoted_data = quoted_content["ZTEXT"] 
+        else:
+            message.quoted_data = None
+    
+    # Handle stickers
+    if content["ZMESSAGETYPE"] == 15:
+        message.sticker = True
+
+    # Process message text
+    process_message_text(message, content)
+    
+    return False  # Message is valid
+
+
+def process_metadata_message(message, content, is_group_message):
+    """Process metadata messages (action_type 6)."""
+    if is_group_message:
+        # Group
+        if content["ZTEXT"] is not None:
+            # Changed name
+            try:
+                int(content["ZTEXT"])
+            except ValueError:
+                msg = f"The group name changed to {content['ZTEXT']}"
+                message.data = msg
+                message.meta = True
+                return False  # Valid message
+            else:
+                return True  # Invalid message
+        else:
+            message.data = None
+            return False
+    else:
+        message.data = None
+        return False
+
+
+def process_message_text(message, content):
+    """Process and format message text content."""
+    if content["ZISFROMME"] == 1:
+        if content["ZMESSAGETYPE"] == 14:
+            msg = "Message deleted"
+            message.meta = True
+        else:
+            msg = content["ZTEXT"]
+            if msg is not None:
+                msg = msg.replace("\r\n", "<br>").replace("\n", "<br>")
+    else:
+        if content["ZMESSAGETYPE"] == 14:
+            msg = "Message deleted"
+            message.meta = True
+        else:
+            msg = content["ZTEXT"]
+            if msg is not None:
+                msg = msg.replace("\r\n", "<br>").replace("\n", "<br>")
+    
+    message.data = msg
+
+
 def media(db, data, media_folder, filter_date, filter_chat, filter_empty, separate_media=False):
+    """Process media files from WhatsApp messages."""
     c = db.cursor()
-    # Get media
-    c.execute(f"""SELECT count()
-                  FROM ZWAMEDIAITEM
-                    INNER JOIN ZWAMESSAGE
-                        ON ZWAMEDIAITEM.ZMESSAGE = ZWAMESSAGE.Z_PK
-                    INNER JOIN ZWACHATSESSION
-                        ON ZWAMESSAGE.ZCHATSESSION = ZWACHATSESSION.Z_PK
-                    LEFT JOIN ZWAGROUPMEMBER
-                        ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
-                  WHERE 1=1
-                    {f'AND ZMESSAGEDATE {filter_date}' if filter_date is not None else ''}
-                    {get_chat_condition(filter_chat[0], True, ["ZWACHATSESSION.ZCONTACTJID","ZMEMBERJID"], "ZGROUPINFO", "ios")}
-                    {get_chat_condition(filter_chat[1], False, ["ZWACHATSESSION.ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")}
-                """)
+    
+    # Build filter conditions
+    chat_filter_include = get_chat_condition(filter_chat[0], True, ["ZWACHATSESSION.ZCONTACTJID","ZMEMBERJID"], "ZGROUPINFO", "ios")
+    chat_filter_exclude = get_chat_condition(filter_chat[1], False, ["ZWACHATSESSION.ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")
+    date_filter = f'AND ZMESSAGEDATE {filter_date}' if filter_date is not None else ''
+    
+    # Get media count
+    media_count_query = f"""
+        SELECT count()
+        FROM ZWAMEDIAITEM
+            INNER JOIN ZWAMESSAGE
+                ON ZWAMEDIAITEM.ZMESSAGE = ZWAMESSAGE.Z_PK
+            INNER JOIN ZWACHATSESSION
+                ON ZWAMESSAGE.ZCHATSESSION = ZWACHATSESSION.Z_PK
+            LEFT JOIN ZWAGROUPMEMBER
+                ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
+        WHERE 1=1
+            {date_filter}
+            {chat_filter_include}
+            {chat_filter_exclude}
+    """
+    c.execute(media_count_query)
     total_row_number = c.fetchone()[0]
     print(f"\nProcessing media...(0/{total_row_number})", end="\r")
-    i = 0
-    c.execute(f"""SELECT ZCONTACTJID,
-                        ZMESSAGE,
-                        ZMEDIALOCALPATH,
-                        ZMEDIAURL,
-                        ZVCARDSTRING,
-                        ZMEDIAKEY,
-                        ZTITLE
-                 FROM ZWAMEDIAITEM
-                    INNER JOIN ZWAMESSAGE
-                        ON ZWAMEDIAITEM.ZMESSAGE = ZWAMESSAGE.Z_PK
-                    INNER JOIN ZWACHATSESSION
-                        ON ZWAMESSAGE.ZCHATSESSION = ZWACHATSESSION.Z_PK
-                    LEFT JOIN ZWAGROUPMEMBER
-                        ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
-                 WHERE ZMEDIALOCALPATH IS NOT NULL
-                    {f'AND ZWAMESSAGE.ZMESSAGEDATE {filter_date}' if filter_date is not None else ''}
-                    {get_chat_condition(filter_chat[0], True, ["ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")}
-                    {get_chat_condition(filter_chat[1], False, ["ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")}
-                 ORDER BY ZCONTACTJID ASC""")
-    content = c.fetchone()
+    
+    # Fetch media items
+    media_query = f"""
+        SELECT ZCONTACTJID,
+            ZMESSAGE,
+            ZMEDIALOCALPATH,
+            ZMEDIAURL,
+            ZVCARDSTRING,
+            ZMEDIAKEY,
+            ZTITLE
+        FROM ZWAMEDIAITEM
+            INNER JOIN ZWAMESSAGE
+                ON ZWAMEDIAITEM.ZMESSAGE = ZWAMESSAGE.Z_PK
+            INNER JOIN ZWACHATSESSION
+                ON ZWAMESSAGE.ZCHATSESSION = ZWACHATSESSION.Z_PK
+            LEFT JOIN ZWAGROUPMEMBER
+                ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
+        WHERE ZMEDIALOCALPATH IS NOT NULL
+            {date_filter}
+            {chat_filter_include}
+            {chat_filter_exclude}
+        ORDER BY ZCONTACTJID ASC
+    """
+    c.execute(media_query)
+    
+    # Process each media item
     mime = MimeTypes()
+    i = 0
+    content = c.fetchone()
     while content is not None:
-        file_path = f"{media_folder}/Message/{content['ZMEDIALOCALPATH']}"
-        current_chat = data.get_chat(content["ZCONTACTJID"])
-        message = current_chat.get_message(content["ZMESSAGE"])
-        message.media = True
-        if current_chat.media_base == "":
-            current_chat.media_base = media_folder + "/"
-        if os.path.isfile(file_path):
-            message.data = '/'.join(file_path.split("/")[1:])
-            if content["ZVCARDSTRING"] is None:
-                guess = mime.guess_type(file_path)[0]
-                if guess is not None:
-                    message.mime = guess
-                else:
-                    message.mime = "application/octet-stream"
-            else:
-                message.mime = content["ZVCARDSTRING"]
-            if separate_media:
-                chat_display_name = slugify(current_chat.name or message.sender \
-                                            or content["ZCONTACTJID"].split('@')[0], True)
-                current_filename = file_path.split("/")[-1]
-                new_folder = os.path.join(media_folder, "separated", chat_display_name)
-                Path(new_folder).mkdir(parents=True, exist_ok=True)
-                new_path = os.path.join(new_folder, current_filename)
-                shutil.copy2(file_path, new_path)
-                message.data = '/'.join(new_path.split("\\")[1:])
-        else:
-            message.data = "The media is missing"
-            message.mime = "media"
-            message.meta = True
-        if content["ZTITLE"] is not None:
-            message.caption = content["ZTITLE"]
+        process_media_item(content, data, media_folder, mime, separate_media)
+        
+        # Update progress
         i += 1
         if i % 100 == 0:
             print(f"Processing media...({i}/{total_row_number})", end="\r")
         content = c.fetchone()
-    print(
-        f"Processing media...({total_row_number}/{total_row_number})", end="\r")
+    
+    print(f"Processing media...({total_row_number}/{total_row_number})", end="\r")
+
+
+def process_media_item(content, data, media_folder, mime, separate_media):
+    """Process a single media item."""
+    file_path = f"{media_folder}/Message/{content['ZMEDIALOCALPATH']}"
+    current_chat = data.get_chat(content["ZCONTACTJID"])
+    message = current_chat.get_message(content["ZMESSAGE"])
+    message.media = True
+    
+    if current_chat.media_base == "":
+        current_chat.media_base = media_folder + "/"
+    
+    if os.path.isfile(file_path):
+        message.data = '/'.join(file_path.split("/")[1:])
+        
+        # Set MIME type
+        if content["ZVCARDSTRING"] is None:
+            guess = mime.guess_type(file_path)[0]
+            message.mime = guess if guess is not None else "application/octet-stream"
+        else:
+            message.mime = content["ZVCARDSTRING"]
+        
+        # Handle separate media option
+        if separate_media:
+            chat_display_name = slugify(current_chat.name or message.sender or content["ZCONTACTJID"].split('@')[0], True)
+            current_filename = file_path.split("/")[-1]
+            new_folder = os.path.join(media_folder, "separated", chat_display_name)
+            Path(new_folder).mkdir(parents=True, exist_ok=True)
+            new_path = os.path.join(new_folder, current_filename)
+            shutil.copy2(file_path, new_path)
+            message.data = '/'.join(new_path.split("\\")[1:])
+    else:
+        # Handle missing media
+        message.data = "The media is missing"
+        message.mime = "media"
+        message.meta = True
+    
+    # Add caption if available
+    if content["ZTITLE"] is not None:
+        message.caption = content["ZTITLE"]
 
 
 def vcard(db, data, media_folder, filter_date, filter_chat, filter_empty):
+    """Process vCard contacts from WhatsApp messages."""
     c = db.cursor()
-    c.execute(f"""SELECT DISTINCT ZWAVCARDMENTION.ZMEDIAITEM,
-                        ZWAMEDIAITEM.ZMESSAGE,
-                        ZCONTACTJID,
-                        ZVCARDNAME,
-                        ZVCARDSTRING
-                 FROM ZWAVCARDMENTION
-                    INNER JOIN ZWAMEDIAITEM
-                        ON ZWAVCARDMENTION.ZMEDIAITEM = ZWAMEDIAITEM.Z_PK
-                    INNER JOIN ZWAMESSAGE
-                        ON ZWAMEDIAITEM.ZMESSAGE = ZWAMESSAGE.Z_PK
-                    INNER JOIN ZWACHATSESSION
-                        ON ZWAMESSAGE.ZCHATSESSION = ZWACHATSESSION.Z_PK
-                    LEFT JOIN ZWAGROUPMEMBER
-                        ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
-                 WHERE 1=1
-                    {f'AND ZWAMESSAGE.ZMESSAGEDATE {filter_date}' if filter_date is not None else ''}
-                    {get_chat_condition(filter_chat[0], True, ["ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")}
-                    {get_chat_condition(filter_chat[1], False, ["ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")};""")
+    
+    # Build filter conditions
+    chat_filter_include = get_chat_condition(filter_chat[0], True, ["ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")
+    chat_filter_exclude = get_chat_condition(filter_chat[1], False, ["ZCONTACTJID", "ZMEMBERJID"], "ZGROUPINFO", "ios")
+    date_filter = f'AND ZWAMESSAGE.ZMESSAGEDATE {filter_date}' if filter_date is not None else ''
+    
+    # Fetch vCard mentions
+    vcard_query = f"""
+        SELECT DISTINCT ZWAVCARDMENTION.ZMEDIAITEM,
+            ZWAMEDIAITEM.ZMESSAGE,
+            ZCONTACTJID,
+            ZVCARDNAME,
+            ZVCARDSTRING
+        FROM ZWAVCARDMENTION
+            INNER JOIN ZWAMEDIAITEM
+                ON ZWAVCARDMENTION.ZMEDIAITEM = ZWAMEDIAITEM.Z_PK
+            INNER JOIN ZWAMESSAGE
+                ON ZWAMEDIAITEM.ZMESSAGE = ZWAMESSAGE.Z_PK
+            INNER JOIN ZWACHATSESSION
+                ON ZWAMESSAGE.ZCHATSESSION = ZWACHATSESSION.Z_PK
+            LEFT JOIN ZWAGROUPMEMBER
+                ON ZWAMESSAGE.ZGROUPMEMBER = ZWAGROUPMEMBER.Z_PK
+        WHERE 1=1
+            {date_filter}
+            {chat_filter_include}
+            {chat_filter_exclude}
+    """
+    c.execute(vcard_query)
     contents = c.fetchall()
     total_row_number = len(contents)
     print(f"\nProcessing vCards...(0/{total_row_number})", end="\r")
+    
+    # Create vCards directory
     path = f'{media_folder}/Message/vCards'
     Path(path).mkdir(parents=True, exist_ok=True)
 
+    # Process each vCard
     for index, content in enumerate(contents):
-        file_paths = []
-        vcard_names = content["ZVCARDNAME"].split("_$!<Name-Separator>!$_")
-        vcard_strings = content["ZVCARDSTRING"].split("_$!<VCard-Separator>!$_")
-
-        # If this is a list of contacts
-        if len(vcard_names) > len(vcard_strings):
-            vcard_names.pop(0)  # Dismiss the first element, which is the group name
-
-        for name, vcard_string in zip(vcard_names, vcard_strings):
-            file_name = "".join(x for x in name if x.isalnum())
-            file_name = file_name.encode('utf-8')[:230].decode('utf-8', 'ignore')
-            file_path = os.path.join(path, f"{file_name}.vcf")
-            file_paths.append(file_path)
-
-            if not os.path.isfile(file_path):
-                with open(file_path, "w", encoding="utf-8") as f:
-                    f.write(vcard_string)
-
-        vcard_summary = "This media include the following vCard file(s):<br>" 
-        vcard_summary += " | ".join([f'<a href="{htmle(fp)}">{htmle(name)}</a>' for name, fp in zip(vcard_names, file_paths)])
-        message = data.get_chat(content["ZCONTACTJID"]).get_message(content["ZMESSAGE"])
-        message.data = vcard_summary
-        message.mime = "text/x-vcard"
-        message.media = True
-        message.meta = True
-        message.safe = True
+        process_vcard_item(content, path, data)
         print(f"Processing vCards...({index + 1}/{total_row_number})", end="\r")
 
 
+def process_vcard_item(content, path, data):
+    """Process a single vCard item."""
+    file_paths = []
+    vcard_names = content["ZVCARDNAME"].split("_$!<Name-Separator>!$_")
+    vcard_strings = content["ZVCARDSTRING"].split("_$!<VCard-Separator>!$_")
+
+    # If this is a list of contacts
+    if len(vcard_names) > len(vcard_strings):
+        vcard_names.pop(0)  # Dismiss the first element, which is the group name
+
+    # Save each vCard file
+    for name, vcard_string in zip(vcard_names, vcard_strings):
+        file_name = "".join(x for x in name if x.isalnum())
+        file_name = file_name.encode('utf-8')[:230].decode('utf-8', 'ignore')
+        file_path = os.path.join(path, f"{file_name}.vcf")
+        file_paths.append(file_path)
+
+        if not os.path.isfile(file_path):
+            with open(file_path, "w", encoding="utf-8") as f:
+                f.write(vcard_string)
+
+    # Create vCard summary and update message
+    vcard_summary = "This media include the following vCard file(s):<br>" 
+    vcard_summary += " | ".join([f'<a href="{htmle(fp)}">{htmle(name)}</a>' for name, fp in zip(vcard_names, file_paths)])
+    
+    message = data.get_chat(content["ZCONTACTJID"]).get_message(content["ZMESSAGE"])
+    message.data = vcard_summary
+    message.mime = "text/x-vcard"
+    message.media = True
+    message.meta = True
+    message.safe = True
+
+
 def calls(db, data, timezone_offset, filter_chat):
+    """Process WhatsApp call records."""
     c = db.cursor()
-    c.execute(f"""SELECT count()
-                FROM ZWACDCALLEVENT
-                WHERE 1=1
-                    {get_chat_condition(filter_chat[0], True, ["ZGROUPCALLCREATORUSERJIDSTRING"], None, "ios")}
-                    {get_chat_condition(filter_chat[1], False, ["ZGROUPCALLCREATORUSERJIDSTRING"], None, "ios")}""")
+    
+    # Build filter conditions
+    chat_filter_include = get_chat_condition(filter_chat[0], True, ["ZGROUPCALLCREATORUSERJIDSTRING"], None, "ios")
+    chat_filter_exclude = get_chat_condition(filter_chat[1], False, ["ZGROUPCALLCREATORUSERJIDSTRING"], None, "ios")
+    
+    # Get call count
+    call_count_query = f"""
+        SELECT count()
+        FROM ZWACDCALLEVENT
+        WHERE 1=1
+            {chat_filter_include}
+            {chat_filter_exclude}
+    """
+    c.execute(call_count_query)
     total_row_number = c.fetchone()[0]
     if total_row_number == 0:
         return
+    
     print(f"\nProcessing calls...({total_row_number})", end="\r")
-    c.execute(f"""SELECT ZCALLIDSTRING,
-                        ZGROUPCALLCREATORUSERJIDSTRING,
-                        ZGROUPJIDSTRING,
-                        ZDATE,
-                        ZOUTCOME,
-                        ZBYTESRECEIVED + ZBYTESSENT AS bytes_transferred,
-                        ZDURATION,
-                        ZVIDEO,
-                        ZMISSED,
-                        ZINCOMING
-                FROM ZWACDCALLEVENT
-                    INNER JOIN ZWAAGGREGATECALLEVENT
-                        ON ZWACDCALLEVENT.Z1CALLEVENTS = ZWAAGGREGATECALLEVENT.Z_PK
-                WHERE 1=1
-                    {get_chat_condition(filter_chat[0], True, ["ZGROUPCALLCREATORUSERJIDSTRING"], None, "ios")}
-                    {get_chat_condition(filter_chat[1], False, ["ZGROUPCALLCREATORUSERJIDSTRING"], None, "ios")}""")
+    
+    # Fetch call records
+    calls_query = f"""
+        SELECT ZCALLIDSTRING,
+            ZGROUPCALLCREATORUSERJIDSTRING,
+            ZGROUPJIDSTRING,
+            ZDATE,
+            ZOUTCOME,
+            ZBYTESRECEIVED + ZBYTESSENT AS bytes_transferred,
+            ZDURATION,
+            ZVIDEO,
+            ZMISSED,
+            ZINCOMING
+        FROM ZWACDCALLEVENT
+            INNER JOIN ZWAAGGREGATECALLEVENT
+                ON ZWACDCALLEVENT.Z1CALLEVENTS = ZWAAGGREGATECALLEVENT.Z_PK
+        WHERE 1=1
+            {chat_filter_include}
+            {chat_filter_exclude}
+    """
+    c.execute(calls_query)
+    
+    # Create calls chat
     chat = ChatStore(Device.ANDROID, "WhatsApp Calls")
+    
+    # Process each call
     content = c.fetchone()
     while content is not None:
-        ts = APPLE_TIME + int(content["ZDATE"])
-        call = Message(
-            from_me=content["ZINCOMING"] == 0,
-            timestamp=ts,
-            time=ts,
-            key_id=content["ZCALLIDSTRING"],
-            timezone_offset=timezone_offset if timezone_offset else CURRENT_TZ_OFFSET
-        )
-        _jid = content["ZGROUPCALLCREATORUSERJIDSTRING"]
-        name = data.get_chat(_jid).name if _jid in data else None
-        if _jid is not None and "@" in _jid:
-            fallback = _jid.split('@')[0]
-        else:
-            fallback = None
-        call.sender = name or fallback
-        call.meta = True
-        call.data = (
-            f"A {'group ' if content['ZGROUPJIDSTRING'] is not None else ''}"
-            f"{'video' if content['ZVIDEO'] == 1 else 'voice'} "
-            f"call {'to' if call.from_me else 'from'} "
-            f"{call.sender} was "
-        )
-        if content['ZOUTCOME'] in (1, 4):
-            call.data += "not answered." if call.from_me else "missed."
-        elif content['ZOUTCOME'] == 2:
-            call.data += "failed."
-        elif content['ZOUTCOME'] == 0:
-            call_time = convert_time_unit(int(content['ZDURATION']))
-            call_bytes = bytes_to_readable(content['bytes_transferred'])
-            call.data += (
-                f"initiated and lasted for {call_time} "
-                f"with {call_bytes} data transferred."
-            )
-        else:
-            call.data += "in an unknown state."
-        chat.add_message(call.key_id, call)
+        process_call_record(content, chat, data, timezone_offset)
         content = c.fetchone()
+    
+    # Add calls chat to data
     data.add_chat("000000000000000", chat)
+
+
+def process_call_record(content, chat, data, timezone_offset):
+    """Process a single call record."""
+    ts = APPLE_TIME + int(content["ZDATE"])
+    call = Message(
+        from_me=content["ZINCOMING"] == 0,
+        timestamp=ts,
+        time=ts,
+        key_id=content["ZCALLIDSTRING"],
+        timezone_offset=timezone_offset if timezone_offset else CURRENT_TZ_OFFSET
+    )
+    
+    # Set sender info
+    _jid = content["ZGROUPCALLCREATORUSERJIDSTRING"]
+    name = data.get_chat(_jid).name if _jid in data else None
+    if _jid is not None and "@" in _jid:
+        fallback = _jid.split('@')[0]
+    else:
+        fallback = None
+    call.sender = name or fallback
+    
+    # Set call metadata
+    call.meta = True
+    call.data = format_call_data(call, content)
+    
+    # Add call to chat
+    chat.add_message(call.key_id, call)
+
+
+def format_call_data(call, content):
+    """Format call data message based on call attributes."""
+    # Basic call info
+    call_data = (
+        f"A {'group ' if content['ZGROUPJIDSTRING'] is not None else ''}"
+        f"{'video' if content['ZVIDEO'] == 1 else 'voice'} "
+        f"call {'to' if call.from_me else 'from'} "
+        f"{call.sender} was "
+    )
+    
+    # Call outcome
+    if content['ZOUTCOME'] in (1, 4):
+        call_data += "not answered." if call.from_me else "missed."
+    elif content['ZOUTCOME'] == 2:
+        call_data += "failed."
+    elif content['ZOUTCOME'] == 0:
+        call_time = convert_time_unit(int(content['ZDURATION']))
+        call_bytes = bytes_to_readable(content['bytes_transferred'])
+        call_data += (
+            f"initiated and lasted for {call_time} "
+            f"with {call_bytes} data transferred."
+        )
+    else:
+        call_data += "in an unknown state."
+    
+    return call_data
\ No newline at end of file

From 1bb3f2ccea2de81b8ea4b0ebb5fe61b619032882 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 2 Mar 2025 13:06:45 +0800
Subject: [PATCH 21/36] Skip generating chats that do not contain any message

---
 Whatsapp_Chat_Exporter/android_handler.py | 5 +++++
 Whatsapp_Chat_Exporter/data_model.py      | 4 ++++
 2 files changed, 9 insertions(+)

diff --git a/Whatsapp_Chat_Exporter/android_handler.py b/Whatsapp_Chat_Exporter/android_handler.py
index 3374c8c..ea89455 100644
--- a/Whatsapp_Chat_Exporter/android_handler.py
+++ b/Whatsapp_Chat_Exporter/android_handler.py
@@ -661,6 +661,9 @@ def create_html(
 
     for current, contact in enumerate(data):
         current_chat = data.get_chat(contact)
+        if len(current_chat) == 0:
+            # Skip empty chats
+            continue
         safe_file_name, name = get_file_name(contact, current_chat)
 
         if maximum_size is not None:
@@ -733,6 +736,8 @@ def create_html(
 def create_txt(data, output):
     os.makedirs(output, exist_ok=True)
     for jik, chat in data.items():
+        if len(chat) == 0:
+            continue
         if chat.name is not None:
             contact = chat.name.replace('/', '')
         else:
diff --git a/Whatsapp_Chat_Exporter/data_model.py b/Whatsapp_Chat_Exporter/data_model.py
index 578713a..d724279 100644
--- a/Whatsapp_Chat_Exporter/data_model.py
+++ b/Whatsapp_Chat_Exporter/data_model.py
@@ -182,6 +182,10 @@ class ChatStore:
         self.their_avatar_thumb = None
         self.status = None
         self.media_base = ""
+    
+    def __len__(self) -> int:
+        """Get number of chats. Required for dict-like access."""
+        return len(self._messages)
 
     def add_message(self, id: str, message: 'Message') -> None:
         """Add a message to the chat store."""

From 0ebd01444a2fe61ff9b86e7177c1de8c3a3e2a30 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 2 Mar 2025 14:17:22 +0800
Subject: [PATCH 22/36] Refactor android_handler

---
 Whatsapp_Chat_Exporter/android_handler.py | 1279 +++++++++++++--------
 1 file changed, 803 insertions(+), 476 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/android_handler.py b/Whatsapp_Chat_Exporter/android_handler.py
index 3047c69..5133d6c 100644
--- a/Whatsapp_Chat_Exporter/android_handler.py
+++ b/Whatsapp_Chat_Exporter/android_handler.py
@@ -16,10 +16,21 @@ from Whatsapp_Chat_Exporter.utility import get_chat_condition, slugify, bytes_to
 
 
 def contacts(db, data, enrich_from_vcards):
-    # Get contacts
+    """
+    Process WhatsApp contacts from the database.
+    
+    Args:
+        db: Database connection
+        data: Data store object
+        enrich_from_vcards: Path to vCard file for contact enrichment
+        
+    Returns:
+        bool: False if no contacts found, True otherwise
+    """
     c = db.cursor()
-    c.execute("""SELECT count() FROM wa_contacts""")
+    c.execute("SELECT count() FROM wa_contacts")
     total_row_number = c.fetchone()[0]
+    
     if total_row_number == 0:
         if enrich_from_vcards is not None:
             print("No contacts profiles found in the default database, contacts will be imported from the specified vCard file.")
@@ -29,33 +40,89 @@ def contacts(db, data, enrich_from_vcards):
     else:
         print(f"Processing contacts...({total_row_number})")
 
-    c.execute("""SELECT jid, COALESCE(display_name, wa_name) as display_name, status FROM wa_contacts; """)
+    c.execute("SELECT jid, COALESCE(display_name, wa_name) as display_name, status FROM wa_contacts;")
     row = c.fetchone()
     while row is not None:
         current_chat = data.add_chat(row["jid"], ChatStore(Device.ANDROID, row["display_name"]))
         if row["status"] is not None:
             current_chat.status = row["status"]
         row = c.fetchone()
+    
+    return True
 
 
 def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat, filter_empty):
-    # Get message history
+    """
+    Process WhatsApp messages from the database.
+    
+    Args:
+        db: Database connection
+        data: Data store object
+        media_folder: Folder containing media files
+        timezone_offset: Timezone offset
+        filter_date: Date filter condition
+        filter_chat: Chat filter conditions
+        filter_empty: Filter for empty chats
+    """
     c = db.cursor()
+    total_row_number = _get_message_count(c, filter_empty, filter_date, filter_chat)
+    print(f"Processing messages...(0/{total_row_number})", end="\r")
+
     try:
-        c.execute(f"""SELECT count()
+        content_cursor = _get_messages_cursor_legacy(c, filter_empty, filter_date, filter_chat)
+        table_message = False
+    except sqlite3.OperationalError:
+        try:
+            content_cursor = _get_messages_cursor_new(c, filter_empty, filter_date, filter_chat)
+            table_message = True
+        except Exception as e:
+            raise e
+
+    i = 0
+    # Fetch the first row safely
+    content = _fetch_row_safely(content_cursor)
+    
+    while content is not None:
+        _process_single_message(data, content, table_message, timezone_offset)
+        
+        i += 1
+        if i % 1000 == 0:
+            print(f"Processing messages...({i}/{total_row_number})", end="\r")
+        
+        # Fetch the next row safely
+        content = _fetch_row_safely(content_cursor)
+    
+    print(f"Processing messages...({total_row_number}/{total_row_number})", end="\r")
+
+
+# Helper functions for message processing
+
+def _get_message_count(cursor, filter_empty, filter_date, filter_chat):
+    """Get the total number of messages to process."""
+    try:
+        empty_filter = get_cond_for_empty(filter_empty, "messages.key_remote_jid", "messages.needs_push")
+        date_filter = f'AND timestamp {filter_date}' if filter_date is not None else ''
+        include_filter = get_chat_condition(filter_chat[0], True, ["messages.key_remote_jid", "messages.remote_resource"], "jid", "android")
+        exclude_filter = get_chat_condition(filter_chat[1], False, ["messages.key_remote_jid", "messages.remote_resource"], "jid", "android")
+
+        cursor.execute(f"""SELECT count()
                       FROM messages
                         INNER JOIN jid
                             ON messages.key_remote_jid = jid.raw_string
                         LEFT JOIN chat
                             ON chat.jid_row_id = jid._id
                       WHERE 1=1
-                        {get_cond_for_empty(filter_empty, "messages.key_remote_jid", "messages.needs_push")}
-                        {f'AND timestamp {filter_date}' if filter_date is not None else ''}
-                        {get_chat_condition(filter_chat[0], True, ["messages.key_remote_jid", "messages.remote_resource"], "jid", "android")}
-                        {get_chat_condition(filter_chat[1], False, ["messages.key_remote_jid", "messages.remote_resource"], "jid", "android")}""")
-
+                        {empty_filter}
+                        {date_filter}
+                        {include_filter}
+                        {exclude_filter}""")
     except sqlite3.OperationalError:
-        c.execute(f"""SELECT count()
+        empty_filter = get_cond_for_empty(filter_empty, "jid.raw_string", "broadcast")
+        date_filter = f'AND timestamp {filter_date}' if filter_date is not None else ''
+        include_filter = get_chat_condition(filter_chat[0], True, ["jid.raw_string", "jid_group.raw_string"], "jid", "android")
+        exclude_filter = get_chat_condition(filter_chat[1], False, ["jid.raw_string", "jid_group.raw_string"], "jid", "android")
+
+        cursor.execute(f"""SELECT count()
                       FROM message
                         LEFT JOIN chat
                             ON chat._id = message.chat_row_id
@@ -64,15 +131,21 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                         LEFT JOIN jid jid_group
                             ON jid_group._id = message.sender_jid_row_id
                       WHERE 1=1
-                        {get_cond_for_empty(filter_empty, "jid.raw_string", "broadcast")}
-                        {f'AND timestamp {filter_date}' if filter_date is not None else ''}
-                        {get_chat_condition(filter_chat[0], True, ["jid.raw_string", "jid_group.raw_string"], "jid", "android")}
-                        {get_chat_condition(filter_chat[1], False, ["jid.raw_string", "jid_group.raw_string"], "jid", "android")}""")
-    total_row_number = c.fetchone()[0]
-    print(f"Processing messages...(0/{total_row_number})", end="\r")
+                        {empty_filter}
+                        {date_filter}
+                        {include_filter}
+                        {exclude_filter}""")
+    return cursor.fetchone()[0]
 
-    try:
-        c.execute(f"""SELECT messages.key_remote_jid,
+
+def _get_messages_cursor_legacy(cursor, filter_empty, filter_date, filter_chat):
+    """Get cursor for legacy database schema."""
+    empty_filter = get_cond_for_empty(filter_empty, "messages.key_remote_jid", "messages.needs_push")
+    date_filter = f'AND messages.timestamp {filter_date}' if filter_date is not None else ''
+    include_filter = get_chat_condition(filter_chat[0], True, ["messages.key_remote_jid", "messages.remote_resource"], "jid_global", "android")
+    exclude_filter = get_chat_condition(filter_chat[1], False, ["messages.key_remote_jid", "messages.remote_resource"], "jid_global", "android")
+
+    cursor.execute(f"""SELECT messages.key_remote_jid,
                             messages._id,
                             messages.key_from_me,
                             messages.timestamp,
@@ -100,8 +173,8 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                     FROM messages
                         LEFT JOIN messages_quotes
                             ON messages.quoted_row_id = messages_quotes._id
-						LEFT JOIN missed_call_logs
-							ON messages._id = missed_call_logs.message_row_id
+                        LEFT JOIN missed_call_logs
+                            ON messages._id = missed_call_logs.message_row_id
                         INNER JOIN jid jid_global
                             ON messages.key_remote_jid = jid_global.raw_string
                         LEFT JOIN chat
@@ -119,16 +192,23 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                         LEFT JOIN receipt_user
                             ON receipt_user.message_row_id = messages._id
                     WHERE messages.key_remote_jid <> '-1'
-                        {get_cond_for_empty(filter_empty, "messages.key_remote_jid", "messages.needs_push")}
-                        {f'AND messages.timestamp {filter_date}' if filter_date is not None else ''}
-                        {get_chat_condition(filter_chat[0], True, ["messages.key_remote_jid", "messages.remote_resource"], "jid_global", "android")}
-                        {get_chat_condition(filter_chat[1], False, ["messages.key_remote_jid", "messages.remote_resource"], "jid_global", "android")}
+                        {empty_filter}
+                        {date_filter}
+                        {include_filter}
+                        {exclude_filter}
                     GROUP BY messages._id
-                    ORDER BY messages.timestamp ASC;"""
-        )
-    except sqlite3.OperationalError:
-        try:
-            c.execute(f"""SELECT jid_global.raw_string as key_remote_jid,
+                    ORDER BY messages.timestamp ASC;""")
+    return cursor
+
+
+def _get_messages_cursor_new(cursor, filter_empty, filter_date, filter_chat):
+    """Get cursor for new database schema."""
+    empty_filter = get_cond_for_empty(filter_empty, "key_remote_jid", "broadcast")
+    date_filter = f'AND message.timestamp {filter_date}' if filter_date is not None else ''
+    include_filter = get_chat_condition(filter_chat[0], True, ["key_remote_jid", "jid_group.raw_string"], "jid_global", "android")
+    exclude_filter = get_chat_condition(filter_chat[1], False, ["key_remote_jid", "jid_group.raw_string"], "jid_global", "android")
+
+    cursor.execute(f"""SELECT jid_global.raw_string as key_remote_jid,
                             message._id,
                             message.from_me as key_from_me,
                             message.timestamp,
@@ -145,7 +225,7 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                             message.message_type as media_wa_type,
                             jid_group.raw_string as group_sender_jid,
                             chat.subject as chat_subject,
-							missed_call_logs.video_call,
+                            missed_call_logs.video_call,
                             message.sender_jid_row_id,
                             message_system.action_type,
                             message_system_group.is_me_joined,
@@ -171,8 +251,8 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                             ON jid_global._id = chat.jid_row_id
                         LEFT JOIN jid jid_group
                             ON jid_group._id = message.sender_jid_row_id
-						LEFT JOIN missed_call_logs
-							ON message._id = missed_call_logs.message_row_id
+                        LEFT JOIN missed_call_logs
+                            ON message._id = missed_call_logs.message_row_id
                         LEFT JOIN message_system
                             ON message_system.message_row_id = message._id
                         LEFT JOIN message_system_group
@@ -186,184 +266,259 @@ def messages(db, data, media_folder, timezone_offset, filter_date, filter_chat,
                         LEFT JOIN receipt_user
                             ON receipt_user.message_row_id = message._id
                     WHERE key_remote_jid <> '-1'
-                        {get_cond_for_empty(filter_empty, "key_remote_jid", "broadcast")}
-                        {f'AND message.timestamp {filter_date}' if filter_date is not None else ''}
-                        {get_chat_condition(filter_chat[0], True, ["key_remote_jid", "jid_group.raw_string"], "jid_global", "android")}
-                        {get_chat_condition(filter_chat[1], False, ["key_remote_jid", "jid_group.raw_string"], "jid_global", "android")}
-                    GROUP BY message._id;"""
-            )
-        except Exception as e:
-            raise e
-        else:
-            table_message = True
-    else:
-        table_message = False
-    i = 0
+                        {empty_filter}
+                        {date_filter}
+                        {include_filter}
+                        {exclude_filter}
+                    GROUP BY message._id;""")
+    return cursor
+
+
+def _fetch_row_safely(cursor):
+    """Safely fetch a row from cursor, handling operational errors."""
     while True:
         try:
-            content = c.fetchone()
+            content = cursor.fetchone()
+            return content
         except sqlite3.OperationalError:
             continue
-        else:
-            break
-    while content is not None:
-        if not data.get_chat(content["key_remote_jid"]):
-            current_chat = data.add_chat(content["key_remote_jid"], ChatStore(Device.ANDROID, content["chat_subject"]))
-        else:
-            current_chat = data.get_chat(content["key_remote_jid"])
-        if content["key_remote_jid"] is None:
-            continue  # Not sure
-        if "sender_jid_row_id" in content:
-            sender_jid_row_id = content["sender_jid_row_id"]
-        else:
-            sender_jid_row_id = None
-        message = Message(
-            from_me=not sender_jid_row_id and content["key_from_me"],
-            timestamp=content["timestamp"],
-            time=content["timestamp"],
-            key_id=content["key_id"],
-            timezone_offset=timezone_offset if timezone_offset else CURRENT_TZ_OFFSET,
-            message_type=content["media_wa_type"],
-            received_timestamp=content["received_timestamp"],
-            read_timestamp=content["read_timestamp"]
-        )
-        if isinstance(content["data"], bytes):
-            message.data = ("The message is binary data and its base64 is "
-                '<a href="https://gchq.github.io/CyberChef/#recipe=From_Base64'
-                "('A-Za-z0-9%2B/%3D',true,false)Text_Encoding_Brute_Force"
-                f"""('Decode')&input={b64encode(b64encode(content["data"])).decode()}">""")
-            message.data += b64encode(content["data"]).decode("utf-8") + "</a>"
-            message.safe = message.meta = True
-            current_chat.add_message(content["_id"], message)
-            i += 1
-            content = c.fetchone()
-            continue
-        if content["jid_type"] == JidType.GROUP and content["key_from_me"] == 0:
-            name = fallback = None
-            if table_message:
-                if content["sender_jid_row_id"] > 0:
-                    _jid = content["group_sender_jid"]
-                    if _jid in data:
-                        name = data.get_chat(_jid).name
-                    if "@" in _jid:
-                        fallback = _jid.split('@')[0]
-            else:
-                if content["remote_resource"] is not None:
-                    if content["remote_resource"] in data:
-                        name = data.get_chat(content["remote_resource"]).name
-                    if "@" in content["remote_resource"]:
-                        fallback = content["remote_resource"].split('@')[0]
 
-            message.sender = name or fallback
-        else:
-            message.sender = None
-
-        if content["quoted"] is not None:
-            message.reply = content["quoted"]
-            if content["quoted_data"] is not None and len(content["quoted_data"]) > 200:
-                message.quoted_data = content["quoted_data"][:201] + "..."
-            else:
-                message.quoted_data = content["quoted_data"]
-        else:
-            message.reply = None
-
-        if not table_message and content["media_caption"] is not None:
-            # Old schema
-            message.caption = content["media_caption"]
-        elif table_message and content["media_wa_type"] == 1 and content["data"] is not None:
-            # New schema
-            message.caption = content["data"]
-        else:
-            message.caption = None
-
-        if content["status"] == 6:  # 6 = Metadata, otherwise assume a message
-            message.meta = True
-            name = fallback = None
-            if table_message:
-                if content["sender_jid_row_id"] > 0:
-                    _jid = content["group_sender_jid"]
-                    if _jid in data:
-                        name = data.get_chat(_jid).name
-                    if "@" in _jid:
-                        fallback = _jid.split('@')[0]
-                else:
-                    name = "You"
-            else:
-                _jid = content["remote_resource"]
-                if _jid is not None:
-                    if _jid in data:
-                        name = data.get_chat(_jid).name
-                    if "@" in _jid:
-                        fallback = _jid.split('@')[0]
-                else:
-                    name = "You"
-            message.data = determine_metadata(content, name or fallback)
-            if isinstance(message.data, str) and "<br>" in message.data:
-                message.safe = True
-            if message.data is None:
-                if content["video_call"] is not None:  # Missed call
-                    message.meta = True
-                    if content["video_call"] == 1:
-                        message.data = "A video call was missed"
-                    elif content["video_call"] == 0:
-                        message.data = "A voice call was missed"
-                elif content["data"] is None and content["thumb_image"] is None:
-                    message.meta = True
-                    message.data = None
-        else:
-            # Real message
-            message.sticker = content["media_wa_type"] == 20  # Sticker is a message
-            if content["key_from_me"] == 1:
-                if content["status"] == 5 and content["edit_version"] == 7 or table_message and content["media_wa_type"] == 15:
-                    msg = "Message deleted"
-                    message.meta = True
-                else:
-                    if content["media_wa_type"] == 5:
-                        msg = f"Location shared: {content['latitude'], content['longitude']}"
-                        message.meta = True
-                    else:
-                        msg = content["data"]
-                        if msg is not None:
-                            if "\r\n" in msg:
-                                msg = msg.replace("\r\n", " <br>")
-                            if "\n" in msg:
-                                msg = msg.replace("\n", " <br>")
-            else:
-                if content["status"] == 0 and content["edit_version"] == 7 or table_message and content["media_wa_type"] == 15:
-                    msg = "Message deleted"
-                    message.meta = True
-                else:
-                    if content["media_wa_type"] == 5:
-                        msg = f"Location shared: {content['latitude'], content['longitude']}"
-                        message.meta = True
-                    else:
-                        msg = content["data"]
-                        if msg is not None:
-                            if "\r\n" in msg:
-                                msg = msg.replace("\r\n", " <br>")
-                            if "\n" in msg:
-                                msg = msg.replace("\n", " <br>")
-            message.data = msg
 
+def _process_single_message(data, content, table_message, timezone_offset):
+    """Process a single message row."""
+    if content["key_remote_jid"] is None:
+        return
+        
+    # Get or create the chat
+    if not data.get_chat(content["key_remote_jid"]):
+        current_chat = data.add_chat(content["key_remote_jid"], ChatStore(Device.ANDROID, content["chat_subject"]))
+    else:
+        current_chat = data.get_chat(content["key_remote_jid"])
+    
+    # Determine sender_jid_row_id
+    if "sender_jid_row_id" in content:
+        sender_jid_row_id = content["sender_jid_row_id"]
+    else:
+        sender_jid_row_id = None
+    
+    # Create message object
+    message = Message(
+        from_me=not sender_jid_row_id and content["key_from_me"],
+        timestamp=content["timestamp"],
+        time=content["timestamp"],
+        key_id=content["key_id"],
+        timezone_offset=timezone_offset if timezone_offset else CURRENT_TZ_OFFSET,
+        message_type=content["media_wa_type"],
+        received_timestamp=content["received_timestamp"],
+        read_timestamp=content["read_timestamp"]
+    )
+    
+    # Handle binary data
+    if isinstance(content["data"], bytes):
+        _process_binary_message(message, content)
         current_chat.add_message(content["_id"], message)
-        i += 1
-        if i % 1000 == 0:
-            print(f"Processing messages...({i}/{total_row_number})", end="\r")
-        while True:
-            try:
-                content = c.fetchone()
-            except sqlite3.OperationalError:
-                continue
+        return
+    
+    # Set sender for group chats
+    if content["jid_type"] == JidType.GROUP and content["key_from_me"] == 0:
+        _set_group_sender(message, content, data, table_message)
+    else:
+        message.sender = None
+    
+    # Handle quoted messages
+    if content["quoted"] is not None:
+        message.reply = content["quoted"]
+        if content["quoted_data"] is not None and len(content["quoted_data"]) > 200:
+            message.quoted_data = content["quoted_data"][:201] + "..."
+        else:
+            message.quoted_data = content["quoted_data"]
+    else:
+        message.reply = None
+    
+    # Handle message caption
+    if not table_message and content["media_caption"] is not None:
+        # Old schema
+        message.caption = content["media_caption"]
+    elif table_message and content["media_wa_type"] == 1 and content["data"] is not None:
+        # New schema
+        message.caption = content["data"]
+    else:
+        message.caption = None
+    
+    # Handle message content based on status
+    if content["status"] == 6:  # 6 = Metadata
+        _process_metadata_message(message, content, data, table_message)
+    else:
+        # Real message
+        _process_regular_message(message, content, table_message)
+    
+    current_chat.add_message(content["_id"], message)
+
+
+def _process_binary_message(message, content):
+    """Process binary message data."""
+    message.data = ("The message is binary data and its base64 is "
+                    '<a href="https://gchq.github.io/CyberChef/#recipe=From_Base64'
+                    "('A-Za-z0-9%2B/%3D',true,false)Text_Encoding_Brute_Force"
+                    f"""('Decode')&input={b64encode(b64encode(content["data"])).decode()}">""")
+    message.data += b64encode(content["data"]).decode("utf-8") + "</a>"
+    message.safe = message.meta = True
+
+
+def _set_group_sender(message, content, data, table_message):
+    """Set sender name for group messages."""
+    name = fallback = None
+    if table_message:
+        if content["sender_jid_row_id"] > 0:
+            _jid = content["group_sender_jid"]
+            if _jid in data:
+                name = data.get_chat(_jid).name
+            if "@" in _jid:
+                fallback = _jid.split('@')[0]
+    else:
+        if content["remote_resource"] is not None:
+            if content["remote_resource"] in data:
+                name = data.get_chat(content["remote_resource"]).name
+            if "@" in content["remote_resource"]:
+                fallback = content["remote_resource"].split('@')[0]
+    
+    message.sender = name or fallback
+
+
+def _process_metadata_message(message, content, data, table_message):
+    """Process metadata message."""
+    message.meta = True
+    name = fallback = None
+    
+    if table_message:
+        if content["sender_jid_row_id"] > 0:
+            _jid = content["group_sender_jid"]
+            if _jid in data:
+                name = data.get_chat(_jid).name
+            if "@" in _jid:
+                fallback = _jid.split('@')[0]
+        else:
+            name = "You"
+    else:
+        _jid = content["remote_resource"]
+        if _jid is not None:
+            if _jid in data:
+                name = data.get_chat(_jid).name
+            if "@" in _jid:
+                fallback = _jid.split('@')[0]
+        else:
+            name = "You"
+    
+    message.data = determine_metadata(content, name or fallback)
+    
+    if isinstance(message.data, str) and "<br>" in message.data:
+        message.safe = True
+    
+    if message.data is None:
+        if content["video_call"] is not None:  # Missed call
+            message.meta = True
+            if content["video_call"] == 1:
+                message.data = "A video call was missed"
+            elif content["video_call"] == 0:
+                message.data = "A voice call was missed"
+        elif content["data"] is None and content["thumb_image"] is None:
+            message.meta = True
+            message.data = None
+
+
+def _process_regular_message(message, content, table_message):
+    """Process regular (non-metadata) message."""
+    message.sticker = content["media_wa_type"] == 20  # Sticker is a message
+    
+    if content["key_from_me"] == 1:
+        if content["status"] == 5 and content["edit_version"] == 7 or table_message and content["media_wa_type"] == 15:
+            msg = "Message deleted"
+            message.meta = True
+        else:
+            if content["media_wa_type"] == 5:
+                msg = f"Location shared: {content['latitude'], content['longitude']}"
+                message.meta = True
             else:
-                break
-    print(f"Processing messages...({total_row_number}/{total_row_number})", end="\r")
+                msg = content["data"]
+                if msg is not None:
+                    msg = _format_message_text(msg)
+    else:
+        if content["status"] == 0 and content["edit_version"] == 7 or table_message and content["media_wa_type"] == 15:
+            msg = "Message deleted"
+            message.meta = True
+        else:
+            if content["media_wa_type"] == 5:
+                msg = f"Location shared: {content['latitude'], content['longitude']}"
+                message.meta = True
+            else:
+                msg = content["data"]
+                if msg is not None:
+                    msg = _format_message_text(msg)
+    
+    message.data = msg
+
+
+def _format_message_text(text):
+    """Format message text, replacing newlines with HTML breaks."""
+    if "\r\n" in text:
+        text = text.replace("\r\n", " <br>")
+    if "\n" in text:
+        text = text.replace("\n", " <br>")
+    return text
 
 
 def media(db, data, media_folder, filter_date, filter_chat, filter_empty, separate_media=True):
-    # Get media
+    """
+    Process WhatsApp media files from the database.
+    
+    Args:
+        db: Database connection
+        data: Data store object
+        media_folder: Folder containing media files
+        filter_date: Date filter condition
+        filter_chat: Chat filter conditions
+        filter_empty: Filter for empty chats
+        separate_media: Whether to separate media files by chat
+    """
     c = db.cursor()
+    total_row_number = _get_media_count(c, filter_empty, filter_date, filter_chat)
+    print(f"\nProcessing media...(0/{total_row_number})", end="\r")
+    
     try:
-        c.execute(f"""SELECT count()
+        content_cursor = _get_media_cursor_legacy(c, filter_empty, filter_date, filter_chat)
+    except sqlite3.OperationalError:
+        content_cursor = _get_media_cursor_new(c, filter_empty, filter_date, filter_chat)
+    
+    content = content_cursor.fetchone()
+    mime = MimeTypes()
+    
+    # Ensure thumbnails directory exists
+    Path(f"{media_folder}/thumbnails").mkdir(parents=True, exist_ok=True)
+    
+    i = 0
+    while content is not None:
+        _process_single_media(data, content, media_folder, mime, separate_media)
+        
+        i += 1
+        if i % 100 == 0:
+            print(f"Processing media...({i}/{total_row_number})", end="\r")
+        
+        content = content_cursor.fetchone()
+    
+    print(f"Processing media...({total_row_number}/{total_row_number})", end="\r")
+
+
+# Helper functions for media processing
+
+def _get_media_count(cursor, filter_empty, filter_date, filter_chat):
+    """Get the total number of media files to process."""
+    try:
+        empty_filter = get_cond_for_empty(filter_empty, "key_remote_jid", "messages.needs_push")
+        date_filter = f'AND messages.timestamp {filter_date}' if filter_date is not None else ''
+        include_filter = get_chat_condition(filter_chat[0], True, ["messages.key_remote_jid", "remote_resource"], "jid", "android")
+        exclude_filter = get_chat_condition(filter_chat[1], False, ["messages.key_remote_jid", "remote_resource"], "jid", "android")
+
+        cursor.execute(f"""SELECT count()
                     FROM message_media
                         INNER JOIN messages
                             ON message_media.message_row_id = messages._id
@@ -372,12 +527,17 @@ def media(db, data, media_folder, filter_date, filter_chat, filter_empty, separa
                         LEFT JOIN chat
                             ON chat.jid_row_id = jid._id
                     WHERE 1=1  
-                        {get_cond_for_empty(filter_empty, "key_remote_jid", "messages.needs_push")}
-                        {f'AND messages.timestamp {filter_date}' if filter_date is not None else ''}
-                        {get_chat_condition(filter_chat[0], True, ["messages.key_remote_jid", "remote_resource"], "jid", "android")}
-                        {get_chat_condition(filter_chat[1], False, ["messages.key_remote_jid", "remote_resource"], "jid", "android")}""")
+                        {empty_filter}
+                        {date_filter}
+                        {include_filter}
+                        {exclude_filter}""")
     except sqlite3.OperationalError:
-        c.execute(f"""SELECT count()
+        empty_filter = get_cond_for_empty(filter_empty, "jid.raw_string", "broadcast")
+        date_filter = f'AND message.timestamp {filter_date}' if filter_date is not None else ''
+        include_filter = get_chat_condition(filter_chat[0], True, ["jid.raw_string", "jid_group.raw_string"], "jid", "android")
+        exclude_filter = get_chat_condition(filter_chat[1], False, ["jid.raw_string", "jid_group.raw_string"], "jid", "android")
+
+        cursor.execute(f"""SELECT count()
                     FROM message_media
                         INNER JOIN message
                             ON message_media.message_row_id = message._id
@@ -388,40 +548,54 @@ def media(db, data, media_folder, filter_date, filter_chat, filter_empty, separa
                         LEFT JOIN jid jid_group
                             ON jid_group._id = message.sender_jid_row_id
                     WHERE 1=1    
-                        {get_cond_for_empty(filter_empty, "jid.raw_string", "broadcast")}
-                        {f'AND message.timestamp {filter_date}' if filter_date is not None else ''}
-                        {get_chat_condition(filter_chat[0], True, ["jid.raw_string", "jid_group.raw_string"], "jid", "android")}
-                        {get_chat_condition(filter_chat[1], False, ["jid.raw_string", "jid_group.raw_string"], "jid", "android")}""")
-    total_row_number = c.fetchone()[0]
-    print(f"\nProcessing media...(0/{total_row_number})", end="\r")
-    i = 0
-    try:
-        c.execute(f"""SELECT messages.key_remote_jid,
+                        {empty_filter}
+                        {date_filter}
+                        {include_filter}
+                        {exclude_filter}""")
+    return cursor.fetchone()[0]
+
+
+def _get_media_cursor_legacy(cursor, filter_empty, filter_date, filter_chat):
+    """Get cursor for legacy media database schema."""
+    empty_filter = get_cond_for_empty(filter_empty, "key_remote_jid", "broadcast")
+    date_filter = f'AND messages.timestamp {filter_date}' if filter_date is not None else ''
+    include_filter = get_chat_condition(filter_chat[0], True, ["messages.key_remote_jid", "remote_resource"], "jid", "android")
+    exclude_filter = get_chat_condition(filter_chat[1], False, ["messages.key_remote_jid", "remote_resource"], "jid", "android")
+
+    cursor.execute(f"""SELECT messages.key_remote_jid,
                         message_row_id,
                         file_path,
                         message_url,
                         mime_type,
                         media_key,
                         file_hash,
-						thumbnail
+                        thumbnail
                  FROM message_media
                     INNER JOIN messages
                         ON message_media.message_row_id = messages._id
-					LEFT JOIN media_hash_thumbnail
-						ON message_media.file_hash = media_hash_thumbnail.media_hash
+                    LEFT JOIN media_hash_thumbnail
+                        ON message_media.file_hash = media_hash_thumbnail.media_hash
                     INNER JOIN jid
                         ON messages.key_remote_jid = jid.raw_string
                     LEFT JOIN chat
                         ON chat.jid_row_id = jid._id
                 WHERE jid.type <> 7
-                    {get_cond_for_empty(filter_empty, "key_remote_jid", "broadcast")}
-                    {f'AND messages.timestamp {filter_date}' if filter_date is not None else ''}
-                    {get_chat_condition(filter_chat[0], True, ["messages.key_remote_jid", "remote_resource"], "jid", "android")}
-                    {get_chat_condition(filter_chat[1], False, ["messages.key_remote_jid", "remote_resource"], "jid", "android")}
-                ORDER BY messages.key_remote_jid ASC"""
-        )
-    except sqlite3.OperationalError:
-        c.execute(f"""SELECT jid.raw_string as key_remote_jid,
+                    {empty_filter}
+                    {date_filter}
+                    {include_filter}
+                    {exclude_filter}
+                ORDER BY messages.key_remote_jid ASC""")
+    return cursor
+
+
+def _get_media_cursor_new(cursor, filter_empty, filter_date, filter_chat):
+    """Get cursor for new media database schema."""
+    empty_filter = get_cond_for_empty(filter_empty, "key_remote_jid", "broadcast")
+    date_filter = f'AND message.timestamp {filter_date}' if filter_date is not None else ''
+    include_filter = get_chat_condition(filter_chat[0], True, ["key_remote_jid", "jid_group.raw_string"], "jid", "android")
+    exclude_filter = get_chat_condition(filter_chat[1], False, ["key_remote_jid", "jid_group.raw_string"], "jid", "android")
+
+    cursor.execute(f"""SELECT jid.raw_string as key_remote_jid,
                     message_row_id,
                     file_path,
                     message_url,
@@ -437,207 +611,297 @@ def media(db, data, media_folder, filter_date, filter_chat, filter_empty, separa
                     INNER JOIN jid
                         ON jid._id = chat.jid_row_id
                     LEFT JOIN media_hash_thumbnail
-						ON message_media.file_hash = media_hash_thumbnail.media_hash
+                        ON message_media.file_hash = media_hash_thumbnail.media_hash
                     LEFT JOIN jid jid_group
                         ON jid_group._id = message.sender_jid_row_id
                 WHERE jid.type <> 7
-                    {get_cond_for_empty(filter_empty, "key_remote_jid", "broadcast")}
-                    {f'AND message.timestamp {filter_date}' if filter_date is not None else ''}
-                    {get_chat_condition(filter_chat[0], True, ["key_remote_jid", "jid_group.raw_string"], "jid", "android")}
-                    {get_chat_condition(filter_chat[1], False, ["key_remote_jid", "jid_group.raw_string"], "jid", "android")}
-                ORDER BY jid.raw_string ASC"""
-        )
-    content = c.fetchone()
-    mime = MimeTypes()
-    if not os.path.isdir(f"{media_folder}/thumbnails"):
-        Path(f"{media_folder}/thumbnails").mkdir(parents=True, exist_ok=True)
-    while content is not None:
-        file_path = f"{media_folder}/{content['file_path']}"
-        current_chat = data.get_chat(content["key_remote_jid"])
-        message = current_chat.get_message(content["message_row_id"])
-        message.media = True
-        if os.path.isfile(file_path):
-            message.data = file_path
-            if content["mime_type"] is None:
-                guess = mime.guess_type(file_path)[0]
-                if guess is not None:
-                    message.mime = guess
-                else:
-                    message.mime = "application/octet-stream"
+                    {empty_filter}
+                    {date_filter}
+                    {include_filter}
+                    {exclude_filter}
+                ORDER BY jid.raw_string ASC""")
+    return cursor
+
+
+def _process_single_media(data, content, media_folder, mime, separate_media):
+    """Process a single media file."""
+    file_path = f"{media_folder}/{content['file_path']}"
+    current_chat = data.get_chat(content["key_remote_jid"])
+    message = current_chat.get_message(content["message_row_id"])
+    message.media = True
+    
+    if os.path.isfile(file_path):
+        message.data = file_path
+        
+        # Set mime type
+        if content["mime_type"] is None:
+            guess = mime.guess_type(file_path)[0]
+            if guess is not None:
+                message.mime = guess
             else:
-                message.mime = content["mime_type"]
-            if separate_media:
-                chat_display_name = slugify(current_chat.name or message.sender \
-                                            or content["key_remote_jid"].split('@')[0], True)
-                current_filename = file_path.split("/")[-1]
-                new_folder = os.path.join(media_folder, "separated", chat_display_name)
-                Path(new_folder).mkdir(parents=True, exist_ok=True)
-                new_path = os.path.join(new_folder, current_filename)
-                shutil.copy2(file_path, new_path)
-                message.data = new_path
+                message.mime = "application/octet-stream"
         else:
-            message.data = "The media is missing"
-            message.mime = "media"
-            message.meta = True
-        if content["thumbnail"] is not None:
-            thumb_path = f"{media_folder}/thumbnails/{b64decode(content['file_hash']).hex()}.png"
-            if not os.path.isfile(thumb_path):
-                with open(thumb_path, "wb") as f:
-                    f.write(content["thumbnail"])
-            message.thumb = thumb_path
-        i += 1
-        if i % 100 == 0:
-            print(f"Processing media...({i}/{total_row_number})", end="\r")
-        content = c.fetchone()
-    print(
-        f"Processing media...({total_row_number}/{total_row_number})", end="\r")
+            message.mime = content["mime_type"]
+        
+        # Copy media to separate folder if needed
+        if separate_media:
+            chat_display_name = slugify(current_chat.name or message.sender 
+                                     or content["key_remote_jid"].split('@')[0], True)
+            current_filename = file_path.split("/")[-1]
+            new_folder = os.path.join(media_folder, "separated", chat_display_name)
+            Path(new_folder).mkdir(parents=True, exist_ok=True)
+            new_path = os.path.join(new_folder, current_filename)
+            shutil.copy2(file_path, new_path)
+            message.data = new_path
+    else:
+        message.data = "The media is missing"
+        message.mime = "media"
+        message.meta = True
+    
+    # Handle thumbnail
+    if content["thumbnail"] is not None:
+        thumb_path = f"{media_folder}/thumbnails/{b64decode(content['file_hash']).hex()}.png"
+        if not os.path.isfile(thumb_path):
+            with open(thumb_path, "wb") as f:
+                f.write(content["thumbnail"])
+        message.thumb = thumb_path
 
 
 def vcard(db, data, media_folder, filter_date, filter_chat, filter_empty):
+    """Process vCard data from WhatsApp database and save to files."""
     c = db.cursor()
     try:
-        c.execute(f"""SELECT message_row_id,
-                        messages.key_remote_jid,
-                        vcard,
-                        messages.media_name
-                 FROM messages_vcards
-                    INNER JOIN messages
-                        ON messages_vcards.message_row_id = messages._id
-                    INNER JOIN jid
-                        ON messages.key_remote_jid = jid.raw_string
-                    LEFT JOIN chat
-                        ON chat.jid_row_id = jid._id
-                 WHERE 1=1
-                    {get_cond_for_empty(filter_empty, "key_remote_jid", "messages.needs_push")}
-                    {f'AND messages.timestamp {filter_date}' if filter_date is not None else ''}
-                    {get_chat_condition(filter_chat[0], True, ["messages.key_remote_jid", "remote_resource"], "jid", "android")}
-                    {get_chat_condition(filter_chat[1], False, ["messages.key_remote_jid", "remote_resource"], "jid", "android")}
-                 ORDER BY messages.key_remote_jid ASC;"""
-        )
+        rows = _execute_vcard_query_modern(c, filter_date, filter_chat, filter_empty)
     except sqlite3.OperationalError:
-        c.execute(f"""SELECT message_row_id,
-                        jid.raw_string as key_remote_jid,
-                        vcard,
-                        message.text_data as media_name
-                 FROM message_vcard
-                    INNER JOIN message
-                        ON message_vcard.message_row_id = message._id
-                    LEFT JOIN chat
-                        ON chat._id = message.chat_row_id
-                    INNER JOIN jid
-                        ON jid._id = chat.jid_row_id
-                    LEFT JOIN jid jid_group
-                        ON jid_group._id = message.sender_jid_row_id
-                WHERE 1=1
-                    {get_cond_for_empty(filter_empty, "key_remote_jid", "broadcast")}
-                    {f'AND message.timestamp {filter_date}' if filter_date is not None else ''}
-                    {get_chat_condition(filter_chat[0], True, ["key_remote_jid", "jid_group.raw_string"], "jid", "android")}
-                    {get_chat_condition(filter_chat[1], False, ["key_remote_jid", "jid_group.raw_string"], "jid", "android")}
-                 ORDER BY message.chat_row_id ASC;"""
-        )
+        rows = _execute_vcard_query_legacy(c, filter_date, filter_chat, filter_empty)
 
-    rows = c.fetchall()
     total_row_number = len(rows)
     print(f"\nProcessing vCards...(0/{total_row_number})", end="\r")
-    path = f"{media_folder}/vCards"
-    if not os.path.isdir(path):
-        Path(path).mkdir(parents=True, exist_ok=True)
+    
+    # Create vCards directory if it doesn't exist
+    path = os.path.join(media_folder, "vCards")
+    Path(path).mkdir(parents=True, exist_ok=True)
+    
     for index, row in enumerate(rows):
-        media_name = row["media_name"] if row["media_name"] is not None else "Undefined vCard File"
-        file_name = "".join(x for x in media_name if x.isalnum())
-        file_name = file_name.encode('utf-8')[:230].decode('utf-8', 'ignore')
-        file_path = os.path.join(path, f"{file_name}.vcf")
-        if not os.path.isfile(file_path):
-            with open(file_path, "w", encoding="utf-8") as f:
-                f.write(row["vcard"])
-        message = data.get_chat(row["key_remote_jid"]).get_message(row["message_row_id"])
-        message.data = "This media include the following vCard file(s):<br>" \
-            f'<a href="{htmle(file_path)}">{htmle(media_name)}</a>'
-        message.mime = "text/x-vcard"
-        message.meta = True
-        message.safe = True
+        _process_vcard_row(row, path, data)
         print(f"Processing vCards...({index + 1}/{total_row_number})", end="\r")
 
 
+def _execute_vcard_query_modern(c, filter_date, filter_chat, filter_empty):
+    """Execute vCard query for modern WhatsApp database schema."""
+
+    # Build the filter conditions
+    chat_filter_include = get_chat_condition(filter_chat[0], True, ["messages.key_remote_jid", "remote_resource"], "jid", "android")
+    chat_filter_exclude = get_chat_condition(filter_chat[1], False, ["messages.key_remote_jid", "remote_resource"], "jid", "android")
+    date_filter = f'AND messages.timestamp {filter_date}' if filter_date is not None else ''
+    empty_filter = get_cond_for_empty(filter_empty, "key_remote_jid", "messages.needs_push")
+
+    query = f"""SELECT message_row_id,
+                messages.key_remote_jid,
+                vcard,
+                messages.media_name
+             FROM messages_vcards
+                INNER JOIN messages
+                    ON messages_vcards.message_row_id = messages._id
+                INNER JOIN jid
+                    ON messages.key_remote_jid = jid.raw_string
+                LEFT JOIN chat
+                    ON chat.jid_row_id = jid._id
+             WHERE 1=1
+                {empty_filter}
+                {date_filter}
+                {chat_filter_include}
+                {chat_filter_exclude}
+             ORDER BY messages.key_remote_jid ASC;"""
+    c.execute(query)
+    return c.fetchall()
+
+
+def _execute_vcard_query_legacy(c, filter_date, filter_chat, filter_empty):
+    """Execute vCard query for legacy WhatsApp database schema."""
+
+    # Build the filter conditions
+    chat_filter_include = get_chat_condition(filter_chat[0], True, ["key_remote_jid", "jid_group.raw_string"], "jid", "android")
+    chat_filter_exclude = get_chat_condition(filter_chat[1], False, ["key_remote_jid", "jid_group.raw_string"], "jid", "android")
+    date_filter = f'AND message.timestamp {filter_date}' if filter_date is not None else ''
+    empty_filter = get_cond_for_empty(filter_empty, "key_remote_jid", "broadcast")
+
+    query = f"""SELECT message_row_id,
+                jid.raw_string as key_remote_jid,
+                vcard,
+                message.text_data as media_name
+             FROM message_vcard
+                INNER JOIN message
+                    ON message_vcard.message_row_id = message._id
+                LEFT JOIN chat
+                    ON chat._id = message.chat_row_id
+                INNER JOIN jid
+                    ON jid._id = chat.jid_row_id
+                LEFT JOIN jid jid_group
+                    ON jid_group._id = message.sender_jid_row_id
+            WHERE 1=1
+                {empty_filter}
+                {date_filter}
+                {chat_filter_include}
+                {chat_filter_exclude}
+             ORDER BY message.chat_row_id ASC;"""
+    c.execute(query)
+    return c.fetchall()
+
+
+def _process_vcard_row(row, path, data):
+    """Process a single vCard row and save to file."""
+    media_name = row["media_name"] if row["media_name"] is not None else "Undefined vCard File"
+    file_name = "".join(x for x in media_name if x.isalnum())
+    file_name = file_name.encode('utf-8')[:230].decode('utf-8', 'ignore')
+    file_path = os.path.join(path, f"{file_name}.vcf")
+    
+    if not os.path.isfile(file_path):
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write(row["vcard"])
+            
+    message = data.get_chat(row["key_remote_jid"]).get_message(row["message_row_id"])
+    message.data = "This media include the following vCard file(s):<br>" \
+        f'<a href="{htmle(file_path)}">{htmle(media_name)}</a>'
+    message.mime = "text/x-vcard"
+    message.meta = True
+    message.safe = True
+
+
 def calls(db, data, timezone_offset, filter_chat):
+    """Process call logs from WhatsApp database."""
     c = db.cursor()
-    c.execute(f"""SELECT count()
-                FROM call_log
-                    INNER JOIN jid
-                        ON call_log.jid_row_id = jid._id
-                    LEFT JOIN chat
-                        ON call_log.jid_row_id = chat.jid_row_id
-                WHERE 1=1
-                    {get_chat_condition(filter_chat[0], True, ["jid.raw_string"])}
-                    {get_chat_condition(filter_chat[1], False, ["jid.raw_string"])}""")
-    total_row_number = c.fetchone()[0]
+    
+    # Check if there are any calls that match the filter
+    total_row_number = _get_calls_count(c, filter_chat)
     if total_row_number == 0:
         return
+        
     print(f"\nProcessing calls...({total_row_number})", end="\r")
-    c.execute(f"""SELECT call_log._id,
-                        jid.raw_string,
-                        from_me,
-                        call_id,
-                        timestamp,
-                        video_call,
-                        duration,
-                        call_result,
-                        bytes_transferred,
-                        chat.subject as chat_subject
-                FROM call_log
-                    INNER JOIN jid
-                        ON call_log.jid_row_id = jid._id
-                    LEFT JOIN chat
-                        ON call_log.jid_row_id = chat.jid_row_id
-                WHERE 1=1
-                    {get_chat_condition(filter_chat[0], True, ["jid.raw_string"])}
-                    {get_chat_condition(filter_chat[1], False, ["jid.raw_string"])}"""
-    )
+    
+    # Fetch call data
+    calls_data = _fetch_calls_data(c, filter_chat)
+    
+    # Create a chat store for all calls
     chat = ChatStore(Device.ANDROID, "WhatsApp Calls")
-    content = c.fetchone()
+    
+    # Process each call
+    content = calls_data.fetchone()
     while content is not None:
-        call = Message(
-            from_me=content["from_me"],
-            timestamp=content["timestamp"],
-            time=content["timestamp"],
-            key_id=content["call_id"],
-            timezone_offset=timezone_offset if timezone_offset else CURRENT_TZ_OFFSET,
-            received_timestamp=None, # TODO: Add timestamp
-            read_timestamp=None # TODO: Add timestamp
-        )
-        _jid = content["raw_string"]
-        name = data.get_chat(_jid).name if _jid in data else content["chat_subject"] or None
-        if _jid is not None and "@" in _jid:
-            fallback = _jid.split('@')[0]
-        else:
-            fallback = None
-        call.sender = name or fallback
-        call.meta = True
-        call.data = (
-            f"A {'video' if content['video_call'] else 'voice'} "
-            f"call {'to' if call.from_me else 'from'} "
-            f"{call.sender} was "
-        )
-        if content['call_result'] in (0, 4, 7):
-            call.data += "cancelled." if call.from_me else "missed."
-        elif content['call_result'] == 2:
-            call.data += "not answered." if call.from_me else "missed."
-        elif content['call_result'] == 3:
-            call.data += "unavailable."
-        elif content['call_result'] == 5:
-            call_time = convert_time_unit(content['duration'])
-            call_bytes = bytes_to_readable(content['bytes_transferred'])
-            call.data += (
-                f"initiated and lasted for {call_time} "
-                f"with {call_bytes} data transferred."
-            )
-        else:
-            call.data += "in an unknown state."
-        chat.add_message(content["_id"], call)
-        content = c.fetchone()
+        _process_call_record(content, chat, data, timezone_offset)
+        content = calls_data.fetchone()
+        
+    # Add the calls chat to the data
     data.add_chat("000000000000000", chat)
 
 
+def _get_calls_count(c, filter_chat):
+    """Get the count of call records that match the filter."""
+
+    # Build the filter conditions
+    chat_filter_include = get_chat_condition(filter_chat[0], True, ["jid.raw_string"])
+    chat_filter_exclude = get_chat_condition(filter_chat[1], False, ["jid.raw_string"])
+
+    query = f"""SELECT count()
+            FROM call_log
+                INNER JOIN jid
+                    ON call_log.jid_row_id = jid._id
+                LEFT JOIN chat
+                    ON call_log.jid_row_id = chat.jid_row_id
+            WHERE 1=1
+                {chat_filter_include}
+                {chat_filter_exclude}"""
+    c.execute(query)
+    return c.fetchone()[0]
+
+
+def _fetch_calls_data(c, filter_chat):
+    """Fetch call data from the database."""
+
+    # Build the filter conditions
+    chat_filter_include = get_chat_condition(filter_chat[0], True, ["jid.raw_string"])
+    chat_filter_exclude = get_chat_condition(filter_chat[1], False, ["jid.raw_string"])
+
+    query = f"""SELECT call_log._id,
+                    jid.raw_string,
+                    from_me,
+                    call_id,
+                    timestamp,
+                    video_call,
+                    duration,
+                    call_result,
+                    bytes_transferred,
+                    chat.subject as chat_subject
+            FROM call_log
+                INNER JOIN jid
+                    ON call_log.jid_row_id = jid._id
+                LEFT JOIN chat
+                    ON call_log.jid_row_id = chat.jid_row_id
+            WHERE 1=1
+                {chat_filter_include}
+                {chat_filter_exclude}"""
+    c.execute(query)
+    return c
+
+
+def _process_call_record(content, chat, data, timezone_offset):
+    """Process a single call record and add it to the chat."""
+    call = Message(
+        from_me=content["from_me"],
+        timestamp=content["timestamp"],
+        time=content["timestamp"],
+        key_id=content["call_id"],
+        timezone_offset=timezone_offset if timezone_offset else CURRENT_TZ_OFFSET,
+        received_timestamp=None,  # TODO: Add timestamp
+        read_timestamp=None  # TODO: Add timestamp
+    )
+    
+    # Get caller/callee name
+    _jid = content["raw_string"]
+    name = data.get_chat(_jid).name if _jid in data else content["chat_subject"] or None
+    if _jid is not None and "@" in _jid:
+        fallback = _jid.split('@')[0]
+    else:
+        fallback = None
+    call.sender = name or fallback
+    
+    # Set metadata
+    call.meta = True
+    
+    # Construct call description based on call type and result
+    call.data = _construct_call_description(content, call)
+    
+    # Add call to chat
+    chat.add_message(content["_id"], call)
+
+
+def _construct_call_description(content, call):
+    """Construct a description of the call based on its type and result."""
+    description = (
+        f"A {'video' if content['video_call'] else 'voice'} "
+        f"call {'to' if call.from_me else 'from'} "
+        f"{call.sender} was "
+    )
+    
+    if content['call_result'] in (0, 4, 7):
+        description += "cancelled." if call.from_me else "missed."
+    elif content['call_result'] == 2:
+        description += "not answered." if call.from_me else "missed."
+    elif content['call_result'] == 3:
+        description += "unavailable."
+    elif content['call_result'] == 5:
+        call_time = convert_time_unit(content['duration'])
+        call_bytes = bytes_to_readable(content['bytes_transferred'])
+        description += (
+            f"initiated and lasted for {call_time} "
+            f"with {call_bytes} data transferred."
+        )
+    else:
+        description += "in an unknown state."
+        
+    return description
+
+
 def create_html(
         data,
         output_folder,
@@ -649,11 +913,13 @@ def create_html(
         experimental=False,
         headline=None
     ):
+    """Generate HTML chat files from data."""
     template = setup_template(template, no_avatar, experimental)
 
     total_row_number = len(data)
     print(f"\nGenerating chats...(0/{total_row_number})", end="\r")
 
+    # Create output directory if it doesn't exist
     if not os.path.isdir(output_folder):
         os.mkdir(output_folder)
 
@@ -664,107 +930,168 @@ def create_html(
         if len(current_chat) == 0:
             # Skip empty chats
             continue
+            
         safe_file_name, name = get_file_name(contact, current_chat)
 
         if maximum_size is not None:
-            current_size = 0
-            current_page = 1
-            render_box = []
-            if maximum_size == 0:
-                maximum_size = MAX_SIZE
-            last_msg = current_chat.get_last_message().key_id
-            for message in current_chat.values():
-                if message.data is not None and not message.meta and not message.media:
-                    current_size += len(message.data) + ROW_SIZE
-                else:
-                    current_size += ROW_SIZE + 100  # Assume media and meta HTML are 100 bytes
-                if current_size > maximum_size:
-                    output_file_name = f"{output_folder}/{safe_file_name}-{current_page}.html"
-                    rendering(
-                        output_file_name,
-                        template,
-                        name,
-                        render_box,
-                        contact,
-                        w3css,
-                        current_chat,
-                        headline,
-                        next=f"{safe_file_name}-{current_page + 1}.html",
-                        previous=f"{safe_file_name}-{current_page - 1}.html" if current_page > 1 else False
-                    )
-                    render_box = [message]
-                    current_size = 0
-                    current_page += 1
-                else:
-                    render_box.append(message)
-                    if message.key_id == last_msg:
-                        if current_page == 1:
-                            output_file_name = f"{output_folder}/{safe_file_name}.html"
-                        else:
-                            output_file_name = f"{output_folder}/{safe_file_name}-{current_page}.html"
-                        rendering(
-                            output_file_name,
-                            template,
-                            name,
-                            render_box,
-                            contact,
-                            w3css,
-                            current_chat,
-                            headline,
-                            False,
-                            previous=f"{safe_file_name}-{current_page - 1}.html"
-                        )
-        else:
-            output_file_name = f"{output_folder}/{safe_file_name}.html"
-            rendering(
-                output_file_name,
-                template,
-                name,
-                current_chat.values(),
-                contact,
-                w3css,
-                current_chat,
-                headline,
-                False
+            _generate_paginated_chat(
+                current_chat, 
+                safe_file_name, 
+                name, 
+                contact, 
+                output_folder, 
+                template, 
+                w3css, 
+                maximum_size, 
+                headline
             )
+        else:
+            _generate_single_chat(
+                current_chat, 
+                safe_file_name, 
+                name, 
+                contact, 
+                output_folder, 
+                template, 
+                w3css, 
+                headline
+            )
+            
         if current % 10 == 0:
             print(f"Generating chats...({current}/{total_row_number})", end="\r")
 
     print(f"Generating chats...({total_row_number}/{total_row_number})", end="\r")
 
 
+def _generate_single_chat(current_chat, safe_file_name, name, contact, output_folder, template, w3css, headline):
+    """Generate a single HTML file for a chat."""
+    output_file_name = f"{output_folder}/{safe_file_name}.html"
+    rendering(
+        output_file_name,
+        template,
+        name,
+        current_chat.values(),
+        contact,
+        w3css,
+        current_chat,
+        headline,
+        False
+    )
+
+
+def _generate_paginated_chat(current_chat, safe_file_name, name, contact, output_folder, template, w3css, maximum_size, headline):
+    """Generate multiple HTML files for a chat when pagination is required."""
+    current_size = 0
+    current_page = 1
+    render_box = []
+    
+    # Use default maximum size if set to 0
+    if maximum_size == 0:
+        maximum_size = MAX_SIZE
+        
+    last_msg = current_chat.get_last_message().key_id
+    
+    for message in current_chat.values():
+        # Calculate message size
+        if message.data is not None and not message.meta and not message.media:
+            current_size += len(message.data) + ROW_SIZE
+        else:
+            current_size += ROW_SIZE + 100  # Assume media and meta HTML are 100 bytes
+            
+        if current_size > maximum_size:
+            # Create a new page
+            output_file_name = f"{output_folder}/{safe_file_name}-{current_page}.html"
+            rendering(
+                output_file_name,
+                template,
+                name,
+                render_box,
+                contact,
+                w3css,
+                current_chat,
+                headline,
+                next=f"{safe_file_name}-{current_page + 1}.html",
+                previous=f"{safe_file_name}-{current_page - 1}.html" if current_page > 1 else False
+            )
+            render_box = [message]
+            current_size = 0
+            current_page += 1
+        else:
+            render_box.append(message)
+            if message.key_id == last_msg:
+                # Last message, create final page
+                if current_page == 1:
+                    output_file_name = f"{output_folder}/{safe_file_name}.html"
+                else:
+                    output_file_name = f"{output_folder}/{safe_file_name}-{current_page}.html"
+                rendering(
+                    output_file_name,
+                    template,
+                    name,
+                    render_box,
+                    contact,
+                    w3css,
+                    current_chat,
+                    headline,
+                    False,
+                    previous=f"{safe_file_name}-{current_page - 1}.html"
+                )
+
+
 def create_txt(data, output):
+    """Generate text files from chat data."""
     os.makedirs(output, exist_ok=True)
+    
     for jik, chat in data.items():
         if len(chat) == 0:
             continue
+            
+        # Determine file name
         if chat.name is not None:
             contact = chat.name.replace('/', '')
         else:
             contact = jik.replace('+', '')
+            
         output_file = os.path.join(output, f"{contact}.txt")
+        
         with open(output_file, "w", encoding="utf8") as f:
             for message in chat.values():
-                date = datetime.fromtimestamp(message.timestamp).date()
+                # Skip metadata in text format
                 if message.meta and message.mime != "media":
-                    continue  # Skip any metadata in text format
-                if message.from_me:
-                    name = "You"
-                else:
-                    name = message.sender if message.sender else contact
-                prefix = f"[{date} {message.time}] {name}: "
-                prefix_length = len(prefix)
-                if message.media and ("/" in message.mime or message.mime == "media"):
-                    if message.data == "The media is missing":
-                        message_text = "<The media is missing>"
-                    else:
-                        message_text = f"<media file in {message.data}>"
-                else:
-                    if message.data is None:
-                        message_text = ""
-                    else:
-                        message_text = message.data.replace('<br>', f'\n{" " * prefix_length}')
-                if message.caption is not None:
-                    message_text += "\n" + ' ' * len(prefix) + message.caption.replace('<br>', f'\n{" " * prefix_length}')
-                f.write(f"{prefix}{message_text}\n")
+                    continue
+                
+                # Format the message
+                formatted_message = _format_message_for_txt(message, contact)
+                f.write(f"{formatted_message}\n")
 
+
+def _format_message_for_txt(message, contact):
+    """Format a message for text output."""
+    date = datetime.fromtimestamp(message.timestamp).date()
+    
+    # Determine the sender name
+    if message.from_me:
+        name = "You"
+    else:
+        name = message.sender if message.sender else contact
+        
+    prefix = f"[{date} {message.time}] {name}: "
+    prefix_length = len(prefix)
+    
+    # Handle different message types
+    if message.media and ("/" in message.mime or message.mime == "media"):
+        if message.data == "The media is missing":
+            message_text = "<The media is missing>"
+        else:
+            message_text = f"<media file in {message.data}>"
+    else:
+        if message.data is None:
+            message_text = ""
+        else:
+            message_text = message.data.replace('<br>', f'\n{" " * prefix_length}')
+            
+    # Add caption if present
+    if message.caption is not None:
+        message_text += "\n" + ' ' * len(prefix) + message.caption.replace('<br>', f'\n{" " * prefix_length}')
+        
+    return f"{prefix}{message_text}"

From 6a67f72ff37200f0fa197be9017893f9e8297149 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 2 Mar 2025 14:57:35 +0800
Subject: [PATCH 23/36] Refactor ios_media_handler

---
 Whatsapp_Chat_Exporter/ios_media_handler.py | 254 ++++++++++++--------
 1 file changed, 160 insertions(+), 94 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/ios_media_handler.py b/Whatsapp_Chat_Exporter/ios_media_handler.py
index dc817b6..317eb61 100644
--- a/Whatsapp_Chat_Exporter/ios_media_handler.py
+++ b/Whatsapp_Chat_Exporter/ios_media_handler.py
@@ -14,143 +14,209 @@ else:
     support_encrypted = True
 
 
-def extract_encrypted(base_dir, password, identifiers, decrypt_chunk_size):
-    print("Trying to decrypt the iOS backup...", end="")
-    backup = EncryptedBackup(
-        backup_directory=base_dir,
-        passphrase=password,
-        cleanup=False,
-        check_same_thread=False,
-        decrypt_chunk_size=decrypt_chunk_size
-    )
-    print("Done\nDecrypting WhatsApp database...", end="")
-    try:
-        backup.extract_file(
-            relative_path=RelativePath.WHATSAPP_MESSAGES,
-            domain_like=identifiers.DOMAIN,
-            output_filename=identifiers.MESSAGE
-        )
-        backup.extract_file(
-            relative_path=RelativePath.WHATSAPP_CONTACTS,
-            domain_like=identifiers.DOMAIN,
-            output_filename=identifiers.CONTACT
-        )
-        backup.extract_file(
-            relative_path=RelativePath.WHATSAPP_CALLS,
-            domain_like=identifiers.DOMAIN,
-            output_filename=identifiers.CALL
-        )
-    except ValueError:
-        print("Failed to decrypt backup: incorrect password?")
-        exit(7)
-    except FileNotFoundError:
-        print("Essential WhatsApp files are missing from the iOS backup.")
-        exit(6)
-    else:
-        print("Done")
+class BackupExtractor:
+    """
+    A class to handle the extraction of WhatsApp data from iOS backups,
+    including encrypted and unencrypted backups.
+    """
 
-    def extract_progress_handler(file_id, domain, relative_path, n, total_files):
-        if n % 100 == 0:
-            print(f"Decrypting and extracting files...({n}/{total_files})", end="\r")   
-        return True
+    def __init__(self, base_dir, identifiers, decrypt_chunk_size):
+        self.base_dir = base_dir
+        self.identifiers = identifiers
+        self.decrypt_chunk_size = decrypt_chunk_size
 
-    backup.extract_files(
-        domain_like=identifiers.DOMAIN,
-        output_folder=identifiers.DOMAIN,
-        preserve_folders=True,
-        filter_callback=extract_progress_handler
-    )
-    print(f"All required files are decrypted and extracted.          ", end="\n")
-    return backup
-
-
-def is_encrypted(base_dir):
-    with sqlite3.connect(os.path.join(base_dir, "Manifest.db")) as f:
-        c = f.cursor()
-        try:
-            c.execute("""SELECT count()
-                    FROM Files
-                    """)
-        except sqlite3.OperationalError as e:
-            raise e  # These error cannot be used to determine if the backup is encrypted
-        except sqlite3.DatabaseError:
-            return True
+    def extract(self):
+        """
+        Extracts WhatsApp data from the backup based on whether it's encrypted or not.
+        """
+        if self._is_encrypted():
+            self._extract_encrypted_backup()
         else:
-            return False
+            self._extract_unencrypted_backup()
 
+    def _is_encrypted(self):
+        """
+        Checks if the iOS backup is encrypted.
 
-def extract_media(base_dir, identifiers, decrypt_chunk_size):
-    if is_encrypted(base_dir):
+        Returns:
+            bool: True if encrypted, False otherwise.
+        """
+        with sqlite3.connect(os.path.join(self.base_dir, "Manifest.db")) as db:
+            c = db.cursor()
+            try:
+                c.execute("SELECT count() FROM Files")
+                c.fetchone()  # Execute and fetch to trigger potential errors
+            except (sqlite3.OperationalError, sqlite3.DatabaseError):
+                return True
+            else:
+                return False
+
+    def _extract_encrypted_backup(self):
+        """
+        Handles the extraction of data from an encrypted iOS backup.
+        """
         if not support_encrypted:
             print("You don't have the dependencies to handle encrypted backup.")
             print("Read more on how to deal with encrypted backup:")
             print("https://github.com/KnugiHK/Whatsapp-Chat-Exporter/blob/main/README.md#usage")
-            return False
+            return
+
         print("Encryption detected on the backup!")
         password = getpass.getpass("Enter the password for the backup:")
-        extract_encrypted(base_dir, password, identifiers, decrypt_chunk_size)
-    else:
-        wts_db = os.path.join(base_dir, identifiers.MESSAGE[:2], identifiers.MESSAGE)
-        contact_db = os.path.join(base_dir, identifiers.CONTACT[:2], identifiers.CONTACT)
-        call_db = os.path.join(base_dir, identifiers.CALL[:2], identifiers.CALL)
-        if not os.path.isfile(wts_db):
-            if identifiers is WhatsAppIdentifier:
+        self._decrypt_backup(password)
+        self._extract_decrypted_files()
+
+    def _decrypt_backup(self, password):
+        """
+        Decrypts the iOS backup using the provided password.
+
+        Args:
+            password (str): The password for the encrypted backup.
+        """
+        print("Trying to decrypt the iOS backup...", end="")
+        self.backup = EncryptedBackup(
+            backup_directory=self.base_dir,
+            passphrase=password,
+            cleanup=False,
+            check_same_thread=False,
+            decrypt_chunk_size=self.decrypt_chunk_size,
+        )
+        print("Done\nDecrypting WhatsApp database...", end="")
+        try:
+            self.backup.extract_file(
+                relative_path=RelativePath.WHATSAPP_MESSAGES,
+                domain_like=self.identifiers.DOMAIN,
+                output_filename=self.identifiers.MESSAGE,
+            )
+            self.backup.extract_file(
+                relative_path=RelativePath.WHATSAPP_CONTACTS,
+                domain_like=self.identifiers.DOMAIN,
+                output_filename=self.identifiers.CONTACT,
+            )
+            self.backup.extract_file(
+                relative_path=RelativePath.WHATSAPP_CALLS,
+                domain_like=self.identifiers.DOMAIN,
+                output_filename=self.identifiers.CALL,
+            )
+        except ValueError:
+            print("Failed to decrypt backup: incorrect password?")
+            exit(7)
+        except FileNotFoundError:
+            print("Essential WhatsApp files are missing from the iOS backup.")
+            exit(6)
+        else:
+            print("Done")
+    
+    def _extract_decrypted_files(self):
+        """Extract all WhatsApp files after decryption"""
+        def extract_progress_handler(file_id, domain, relative_path, n, total_files):
+            if n % 100 == 0:
+                print(f"Decrypting and extracting files...({n}/{total_files})", end="\r")   
+            return True
+
+        self.backup.extract_files(
+            domain_like=self.identifiers.DOMAIN,
+            output_folder=self.identifiers.DOMAIN,
+            preserve_folders=True,
+            filter_callback=extract_progress_handler
+        )
+        print(f"All required files are decrypted and extracted.          ", end="\n")
+
+    def _extract_unencrypted_backup(self):
+        """
+        Handles the extraction of data from an unencrypted iOS backup.
+        """
+        self._copy_whatsapp_databases()
+        self._extract_media_files()
+
+    def _copy_whatsapp_databases(self):
+        """
+        Copies the WhatsApp message, contact, and call databases to the working directory.
+        """
+        wts_db_path = os.path.join(self.base_dir, self.identifiers.MESSAGE[:2], self.identifiers.MESSAGE)
+        contact_db_path = os.path.join(self.base_dir, self.identifiers.CONTACT[:2], self.identifiers.CONTACT)
+        call_db_path = os.path.join(self.base_dir, self.identifiers.CALL[:2], self.identifiers.CALL)
+
+        if not os.path.isfile(wts_db_path):
+            if self.identifiers is WhatsAppIdentifier:
                 print("WhatsApp database not found.")
             else:
                 print("WhatsApp Business database not found.")
             exit()
         else:
-            shutil.copyfile(wts_db, identifiers.MESSAGE)
-        if not os.path.isfile(contact_db):
+            shutil.copyfile(wts_db_path, self.identifiers.MESSAGE)
+
+        if not os.path.isfile(contact_db_path):
             print("Contact database not found. Skipping...")
         else:
-            shutil.copyfile(contact_db, identifiers.CONTACT)
-        if not os.path.isfile(call_db):
+            shutil.copyfile(contact_db_path, self.identifiers.CONTACT)
+
+        if not os.path.isfile(call_db_path):
             print("Call database not found. Skipping...")
         else:
-            shutil.copyfile(call_db, identifiers.CALL)
-        _wts_id = identifiers.DOMAIN
-        with sqlite3.connect(os.path.join(base_dir, "Manifest.db")) as manifest:
+            shutil.copyfile(call_db_path, self.identifiers.CALL)
+
+    def _extract_media_files(self):
+        """
+        Extracts media files from the unencrypted backup.
+        """
+        _wts_id = self.identifiers.DOMAIN
+        with sqlite3.connect(os.path.join(self.base_dir, "Manifest.db")) as manifest:
             manifest.row_factory = sqlite3.Row
             c = manifest.cursor()
-            c.execute(
-                f"""SELECT count()
-                    FROM Files
-                    WHERE domain = '{_wts_id}'"""
-            )
+            c.execute(f"SELECT count() FROM Files WHERE domain = '{_wts_id}'")
             total_row_number = c.fetchone()[0]
             print(f"Extracting WhatsApp files...(0/{total_row_number})", end="\r")
-            c.execute(f"""SELECT fileID,
-                                relativePath,
-                                flags,
-                                file AS metadata,
-                                ROW_NUMBER() OVER(ORDER BY relativePath) AS _index
-                        FROM Files
-                        WHERE domain = '{_wts_id}'
-                        ORDER BY relativePath""")
+            c.execute(
+                f"""
+                SELECT fileID, relativePath, flags, file AS metadata,
+                ROW_NUMBER() OVER(ORDER BY relativePath) AS _index
+                FROM Files
+                WHERE domain = '{_wts_id}'
+                ORDER BY relativePath
+                """
+            )
             if not os.path.isdir(_wts_id):
                 os.mkdir(_wts_id)
+
             row = c.fetchone()
             while row is not None:
-                if row["relativePath"] == "":
+                if not row["relativePath"]:  # Skip empty relative paths
                     row = c.fetchone()
                     continue
+
                 destination = os.path.join(_wts_id, row["relativePath"])
                 hashes = row["fileID"]
                 folder = hashes[:2]
                 flags = row["flags"]
-                if flags == 2:
+
+                if flags == 2:  # Directory
                     try:
                         os.mkdir(destination)
                     except FileExistsError:
                         pass
-                elif flags == 1:
-                    shutil.copyfile(os.path.join(base_dir, folder, hashes), destination)
+                elif flags == 1:  # File
+                    shutil.copyfile(os.path.join(self.base_dir, folder, hashes), destination)
                     metadata = BPListReader(row["metadata"]).parse()
                     creation = metadata["$objects"][1]["Birth"]
                     modification = metadata["$objects"][1]["LastModified"]
                     os.utime(destination, (modification, modification))
+
                 if row["_index"] % 100 == 0:
                     print(f"Extracting WhatsApp files...({row['_index']}/{total_row_number})", end="\r")
                 row = c.fetchone()
             print(f"Extracting WhatsApp files...({total_row_number}/{total_row_number})", end="\n")
+
+
+def extract_media(base_dir, identifiers, decrypt_chunk_size):
+    """
+    Extracts WhatsApp data (media, messages, contacts, calls) from an iOS backup.
+
+    Args:
+        base_dir (str): The path to the iOS backup directory.
+        identifiers (WhatsAppIdentifier): An object containing WhatsApp file identifiers.
+        decrypt_chunk_size (int): The chunk size for decryption.
+    """
+    extractor = BackupExtractor(base_dir, identifiers, decrypt_chunk_size)
+    extractor.extract()
+

From 8f0a9c3cc515af4e41c8f14cbb12e8eb52a58961 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 2 Mar 2025 15:32:37 +0800
Subject: [PATCH 24/36] Refactor android_crypt.py

---
 Whatsapp_Chat_Exporter/android_crypt.py | 335 ++++++++++++++++--------
 1 file changed, 224 insertions(+), 111 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/android_crypt.py b/Whatsapp_Chat_Exporter/android_crypt.py
index 40a6a38..8e83ed5 100644
--- a/Whatsapp_Chat_Exporter/android_crypt.py
+++ b/Whatsapp_Chat_Exporter/android_crypt.py
@@ -1,10 +1,11 @@
 import hmac
 import io
 import zlib
-import javaobj
+import concurrent.futures
 from typing import Tuple, Union
 from hashlib import sha256
 from Whatsapp_Chat_Exporter.utility import CRYPT14_OFFSETS, Crypt, DbType
+
 try:
     import zlib
     from Crypto.Cipher import AES
@@ -12,6 +13,7 @@ except ModuleNotFoundError:
     support_backup = False
 else:
     support_backup = True
+
 try:
     import javaobj
 except ModuleNotFoundError:
@@ -20,9 +22,29 @@ else:
     support_crypt15 = True
 
 
+class DecryptionError(Exception):
+    """Base class for decryption-related exceptions."""
+    pass
+
+
+class InvalidKeyError(DecryptionError):
+    """Raised when the provided key is invalid."""
+    pass
+
+
+class InvalidFileFormatError(DecryptionError):
+    """Raised when the input file format is invalid."""
+    pass
+
+
+class OffsetNotFoundError(DecryptionError):
+    """Raised when the correct offsets for decryption cannot be found."""
+    pass
+
+
 def _derive_main_enc_key(key_stream: bytes) -> Tuple[bytes, bytes]:
     """
-    Derive the main encryption key for the given key stream. The key is derived using HMAC of HMAC of the provided key stream.
+    Derive the main encryption key for the given key stream.
 
     Args:
         key_stream (bytes): The key stream to generate HMAC of HMAC.
@@ -30,16 +52,9 @@ def _derive_main_enc_key(key_stream: bytes) -> Tuple[bytes, bytes]:
     Returns:
         Tuple[bytes, bytes]: A tuple containing the main encryption key and the original key stream.
     """
-    key = hmac.new(
-        hmac.new(
-            b'\x00' * 32,
-            key_stream,
-            sha256
-        ).digest(),
-        b"backup encryption\x01",
-        sha256
-    )
-    return key.digest(), key_stream
+    intermediate_hmac = hmac.new(b'\x00' * 32, key_stream, sha256).digest()
+    key = hmac.new(intermediate_hmac, b"backup encryption\x01", sha256).digest()
+    return key, key_stream
 
 
 def _extract_enc_key(keyfile: bytes) -> Tuple[bytes, bytes]:
@@ -52,17 +67,13 @@ def _extract_enc_key(keyfile: bytes) -> Tuple[bytes, bytes]:
     Returns:
         Tuple[bytes, bytes]: values from _derive_main_enc_key()
     """
-    key_stream = b""
-    for byte in javaobj.loads(keyfile):
-        key_stream += byte.to_bytes(1, "big", signed=True)
-
+    key_stream = b''.join([byte.to_bytes(1, "big", signed=True) for byte in javaobj.loads(keyfile)])
     return _derive_main_enc_key(key_stream)
 
 
 def brute_force_offset(max_iv: int = 200, max_db: int = 200):
     """
     Brute force the offsets for IV and database start position in WhatsApp backup files.
-    Used when common offsets are not applicable to a backup file.
 
     Args:
         max_iv (int, optional): Maximum value to try for IV offset. Defaults to 200.
@@ -79,6 +90,154 @@ def brute_force_offset(max_iv: int = 200, max_db: int = 200):
             yield iv, iv + 16, db
 
 
+def _decrypt_database(db_ciphertext: bytes, main_key: bytes, iv: bytes) -> bytes:
+    """Decrypt and decompress a database chunk.
+
+        Args:
+            db_ciphertext (bytes): The encrypted chunk of the database.
+            main_key (bytes): The main decryption key.
+            iv (bytes): The initialization vector.
+
+        Returns:
+            bytes: The decrypted and decompressed database.
+
+        Raises:
+            zlib.error: If decompression fails.
+            ValueError: if the plaintext is not a SQLite database.
+    """
+    cipher = AES.new(main_key, AES.MODE_GCM, iv)
+    db_compressed = cipher.decrypt(db_ciphertext)
+    db = zlib.decompress(db_compressed)
+    if db[0:6].upper() != b"SQLITE":
+        raise ValueError(
+            "The plaintext is not a SQLite database. Ensure you are using the correct key."
+        )
+    return db
+
+def _decrypt_crypt14(database: bytes, main_key: bytes) -> bytes:
+    """Decrypt a crypt14 database using multithreading for brute-force offset detection.
+
+    Args:
+        database (bytes): The encrypted database.
+        main_key (bytes): The decryption key.
+
+    Returns:
+        bytes: The decrypted database.
+
+    Raises:
+        InvalidFileFormatError: If the file is too small.
+        OffsetNotFoundError: If no valid offsets are found.
+    """
+    if len(database) < 191:
+        raise InvalidFileFormatError("The crypt14 file must be at least 191 bytes")
+
+    # Attempt known offsets first
+    for offsets in CRYPT14_OFFSETS:
+        iv = database[offsets["iv"]:offsets["iv"] + 16]
+        db_ciphertext = database[offsets["db"]:]
+        try:
+            return _decrypt_database(db_ciphertext, main_key, iv)
+        except (zlib.error, ValueError):
+            pass  # Try next offset
+
+    print("Common offsets failed. Initiating brute-force with multithreading...")
+
+    # Convert brute force generator into a list for parallel processing
+    offset_combinations = list(brute_force_offset())
+
+    def attempt_decrypt(offset_tuple):
+        """Attempt decryption with the given offsets."""
+        start_iv, end_iv, start_db = offset_tuple
+        iv = database[start_iv:end_iv]
+        db_ciphertext = database[start_db:]
+
+        try:
+            db = _decrypt_database(db_ciphertext, main_key, iv)
+            print(
+                f"The offsets of your IV and database are {start_iv} and "
+                f"{start_db}, respectively. To include your offsets in the "
+                "program, please report it by creating an issue on GitHub: "
+                "https://github.com/KnugiHK/Whatsapp-Chat-Exporter/discussions/47"
+                "\nShutting down other threads..."
+            )
+            return db
+        except (zlib.error, ValueError):
+            return None  # Decryption failed, move to next
+
+    with concurrent.futures.ThreadPoolExecutor(10) as executor:
+        future_to_offset = {executor.submit(attempt_decrypt, offset): offset for offset in offset_combinations}
+
+        try:
+            for future in concurrent.futures.as_completed(future_to_offset):
+                result = future.result()
+                if result is not None:
+                    # Shutdown remaining threads
+                    executor.shutdown(wait=False, cancel_futures=True)
+                    return result
+
+        except KeyboardInterrupt:
+            print("\nBrute force interrupted by user (Ctrl+C). Exiting gracefully...")
+            executor.shutdown(wait=False, cancel_futures=True)
+            exit(1)
+
+    raise OffsetNotFoundError("Could not find the correct offsets for decryption.")
+
+
+
+def _decrypt_crypt12(database: bytes, main_key: bytes) -> bytes:
+    """Decrypt a crypt12 database.
+
+        Args:
+            database (bytes): The encrypted database.
+            main_key (bytes): The decryption key.
+
+        Returns:
+            bytes: The decrypted database.
+
+        Raises:
+            ValueError: If the file format is invalid or the signature mismatches.
+    """
+    if len(database) < 67:
+        raise InvalidFileFormatError("The crypt12 file must be at least 67 bytes")
+
+    t2 = database[3:35]
+    iv = database[51:67]
+    db_ciphertext = database[67:-20]
+    return _decrypt_database(db_ciphertext, main_key, iv)
+
+
+def _decrypt_crypt15(database: bytes, main_key: bytes, db_type: DbType) -> bytes:
+    """Decrypt a crypt15 database.
+
+        Args:
+            database (bytes): The encrypted database.
+            main_key (bytes): The decryption key.
+            db_type (DbType): The type of database.
+
+        Returns:
+            bytes: The decrypted database.
+
+        Raises:
+            ValueError: If the file format is invalid or the signature mismatches.
+    """
+    if not support_crypt15:
+        raise RuntimeError("Crypt15 is not supported")
+    if len(database) < 131:
+        raise InvalidFileFormatError("The crypt15 file must be at least 131 bytes")
+
+    if db_type == DbType.MESSAGE:
+        iv = database[8:24]
+        db_offset = database[0] + 2
+    elif db_type == DbType.CONTACT:
+        iv = database[7:23]
+        db_offset = database[0] + 1
+    else:
+        raise ValueError(f"Invalid db_type: {db_type}")
+
+    db_ciphertext = database[db_offset:]
+    return _decrypt_database(db_ciphertext, main_key, iv)
+
+
 def decrypt_backup(
     database: bytes,
     key: Union[str, io.IOBase],
@@ -95,62 +254,46 @@ def decrypt_backup(
 
     Args:
         database (bytes): The encrypted database file.
-        key (str or io.IOBase): The key to decrypt the database. The key should either be a string (32 bytes hex key) or a file object (encryption key file).
-        key_stream (bool, optional): Whether the key is a key stream. False for hex key. True for key stream.
-        output (str, optional): The path to save the decrypted database. Defaults to None. When dry_run is True, this parameter is ignored.
+        key (str or io.IOBase): The key to decrypt the database.
+        output (str, optional): The path to save the decrypted database. Defaults to None.
         crypt (Crypt, optional): The encryption version of the database. Defaults to Crypt.CRYPT14.
         show_crypt15 (bool, optional): Whether to show the HEX key of the crypt15 backup. Defaults to False.
         db_type (DbType, optional): The type of database (MESSAGE or CONTACT). Defaults to DbType.MESSAGE.
-        dry_run (bool, optional): Whether to perform a dry run without saving the decrypted database. Defaults to False.
+        dry_run (bool, optional): Whether to perform a dry run. Defaults to False.
+        keyfile_stream (bool, optional): Whether the key is a key stream. Defaults to False.
 
     Returns:
-        int: The status code of the decryption process.
-            - 0: The decryption process was successful.
-            - 1: The decryption process failed because the necessary dependencies for backup decryption are not available.
-            - 2: The decryption process failed because the common offsets for the IV and database are not applicable, and the brute force attempt to find the correct offsets also failed.
-            - 3: The decryption process failed due to unknown error
+        int: The status code of the decryption process (0 for success).
+
+    Raises:
+        ValueError: If the key is invalid or output file not provided when dry_run is False.
+        DecryptionError: for errors during decryption
+        RuntimeError: for dependency errors
     """
     if not support_backup:
-        return 1
+        raise RuntimeError("Dependencies for backup decryption are not available.")
+
     if not dry_run and output is None:
-        ValueError("The path to the decrypted database must be specified unless dry_run is true.")
+        raise ValueError(
+            "The path to the decrypted database must be specified unless dry_run is true."
+        )
+
     if isinstance(key, io.IOBase):
         key = key.read()
-        if crypt is not Crypt.CRYPT15:
-            t1 = key[30:62]
-    if crypt is not Crypt.CRYPT15 and len(key) != 158:
-        raise ValueError("The key file must be 158 bytes")
-    # Determine the IV and database offsets
-    if crypt == Crypt.CRYPT14:
-        if len(database) < 191:
-            raise ValueError("The crypt14 file must be at least 191 bytes")
-        current_try = 0
-        offsets = CRYPT14_OFFSETS[current_try]
-        t2 = database[15:47]
-        iv = database[offsets["iv"]:offsets["iv"] + 16]
-        db_ciphertext = database[offsets["db"]:]
-    elif crypt == Crypt.CRYPT12:
-        if len(database) < 67:
-            raise ValueError("The crypt12 file must be at least 67 bytes")
-        t2 = database[3:35]
-        iv = database[51:67]
-        db_ciphertext = database[67:-20]
-    elif crypt == Crypt.CRYPT15:
-        if not support_crypt15:
-            return 1
-        if len(database) < 131:
-            raise ValueError("The crypt15 file must be at least 131 bytes")
-        t1 = t2 = None
-        if db_type == DbType.MESSAGE:
-            iv = database[8:24]
-            db_offset = database[0] + 2  # Skip protobuf + protobuf size and backup type
-        elif db_type == DbType.CONTACT:
-            iv = database[7:23]
-            db_offset = database[0] + 1  # Skip protobuf + protobuf size
-        db_ciphertext = database[db_offset:]
 
-    if t1 != t2:
-        raise ValueError("The signature of key file and backup file mismatch")
+    if crypt is not Crypt.CRYPT15 and len(key) != 158:
+        raise InvalidKeyError("The key file must be 158 bytes")
+
+    #signature check, this is check is used in crypt 12 and 14
+    if crypt != Crypt.CRYPT15:
+        t1 = key[30:62]
+
+        if t1 != database[15:47] and crypt == Crypt.CRYPT14:
+            raise ValueError("The signature of key file and backup file mismatch")
+
+        if t1 != database[3:35] and crypt == Crypt.CRYPT12:
+            raise ValueError("The signature of key file and backup file mismatch")
+
 
     if crypt == Crypt.CRYPT15:
         if keyfile_stream:
@@ -158,55 +301,25 @@ def decrypt_backup(
         else:
             main_key, hex_key = _derive_main_enc_key(key)
         if show_crypt15:
-            hex_key = [hex_key.hex()[c:c+4] for c in range(0, len(hex_key.hex()), 4)]
-            print("The HEX key of the crypt15 backup is: " + ' '.join(hex_key))
+            hex_key_str = ' '.join([hex_key.hex()[c:c+4] for c in range(0, len(hex_key.hex()), 4)])
+            print(f"The HEX key of the crypt15 backup is: {hex_key_str}")
     else:
         main_key = key[126:]
-    decompressed = False
-    while not decompressed:
-        cipher = AES.new(main_key, AES.MODE_GCM, iv)
-        db_compressed = cipher.decrypt(db_ciphertext)
-        try:
-            db = zlib.decompress(db_compressed)
-        except zlib.error:
-            if crypt == Crypt.CRYPT14:
-                current_try += 1
-                if current_try < len(CRYPT14_OFFSETS):
-                    offsets = CRYPT14_OFFSETS[current_try]
-                    iv = database[offsets["iv"]:offsets["iv"] + 16]
-                    db_ciphertext = database[offsets["db"]:]
-                    continue
-                else:
-                    print("Common offsets are not applicable to "
-                          "your backup. Trying to brute force it...")
-                    for start_iv, end_iv, start_db in brute_force_offset():
-                        iv = database[start_iv:end_iv]
-                        db_ciphertext = database[start_db:]
-                        cipher = AES.new(main_key, AES.MODE_GCM, iv)
-                        db_compressed = cipher.decrypt(db_ciphertext)
-                        try:
-                            db = zlib.decompress(db_compressed)
-                        except zlib.error:
-                            continue
-                        else:
-                            decompressed = True
-                            print(
-                                f"The offsets of your IV and database are {start_iv} and "
-                                f"{start_db}, respectively. To include your offsets in the "
-                                "program, please report it by creating an issue on GitHub: "
-                                "https://github.com/KnugiHK/Whatsapp-Chat-Exporter/discussions/47"
-                            )
-                            break
-                    if not decompressed:
-                        return 2
-            else:
-                return 3
+
+    try:
+        if crypt == Crypt.CRYPT14:
+            db = _decrypt_crypt14(database, main_key)
+        elif crypt == Crypt.CRYPT12:
+            db = _decrypt_crypt12(database, main_key)
+        elif crypt == Crypt.CRYPT15:
+            db = _decrypt_crypt15(database, main_key, db_type)
         else:
-            decompressed = True
-        if db[0:6].upper() == b"SQLITE":
-            if not dry_run:
-                with open(output, "wb") as f:
-                    f.write(db)
-            return 0
-        else:
-            raise ValueError("The plaintext is not a SQLite database. Did you use the key to encrypt something...")
+            raise ValueError(f"Unsupported crypt type: {crypt}")
+    except (InvalidFileFormatError, OffsetNotFoundError, ValueError) as e:
+        raise DecryptionError(f"Decryption failed: {e}") from e
+
+
+    if not dry_run:
+        with open(output, "wb") as f:
+            f.write(db)
+    return 0

From 0074acca7aae648f76e4ee44c3c2035b82cb0974 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 2 Mar 2025 15:44:40 +0800
Subject: [PATCH 25/36] Allow users to set the number of threads for
 bruteforcing offsets

---
 Whatsapp_Chat_Exporter/__main__.py      | 10 ++++++++--
 Whatsapp_Chat_Exporter/android_crypt.py | 10 ++++++----
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/__main__.py b/Whatsapp_Chat_Exporter/__main__.py
index 1784723..bf130be 100644
--- a/Whatsapp_Chat_Exporter/__main__.py
+++ b/Whatsapp_Chat_Exporter/__main__.py
@@ -229,6 +229,10 @@ def setup_argument_parser() -> ArgumentParser:
         "--decrypt-chunk-size", dest="decrypt_chunk_size", default=1 * 1024 * 1024, type=int,
         help="Specify the chunk size for decrypting iOS backup, which may affect the decryption speed."
     )
+    misc_group.add_argument(
+        "--max-bruteforce-worker", dest="max_bruteforce_worker", default=10, type=int,
+        help="Specify the maximum number of worker for bruteforce decryption."
+    )
     
     return parser
 
@@ -398,7 +402,8 @@ def decrypt_android_backup(args) -> int:
             crypt,
             args.showkey,
             DbType.CONTACT,
-            keyfile_stream=keyfile_stream
+            keyfile_stream=keyfile_stream,
+            max_worker=args.max_bruteforce_worker
         )
         if isinstance(key, io.IOBase):
             key.seek(0)
@@ -411,7 +416,8 @@ def decrypt_android_backup(args) -> int:
         crypt,
         args.showkey,
         DbType.MESSAGE,
-        keyfile_stream=keyfile_stream
+        keyfile_stream=keyfile_stream,
+        max_worker=args.max_bruteforce_worker
     )
     
     # Handle errors
diff --git a/Whatsapp_Chat_Exporter/android_crypt.py b/Whatsapp_Chat_Exporter/android_crypt.py
index 8e83ed5..2f764dd 100644
--- a/Whatsapp_Chat_Exporter/android_crypt.py
+++ b/Whatsapp_Chat_Exporter/android_crypt.py
@@ -114,12 +114,13 @@ def _decrypt_database(db_ciphertext: bytes, main_key: bytes, iv: bytes) -> bytes
         )
     return db
 
-def _decrypt_crypt14(database: bytes, main_key: bytes) -> bytes:
+def _decrypt_crypt14(database: bytes, main_key: bytes, max_worker: int = 10) -> bytes:
     """Decrypt a crypt14 database using multithreading for brute-force offset detection.
 
     Args:
         database (bytes): The encrypted database.
         main_key (bytes): The decryption key.
+        max_worker (int, optional): The maximum number of threads to use for brute force. Defaults to 10.
 
     Returns:
         bytes: The decrypted database.
@@ -164,7 +165,7 @@ def _decrypt_crypt14(database: bytes, main_key: bytes) -> bytes:
         except (zlib.error, ValueError):
             return None  # Decryption failed, move to next
 
-    with concurrent.futures.ThreadPoolExecutor(10) as executor:
+    with concurrent.futures.ThreadPoolExecutor(max_worker) as executor:
         future_to_offset = {executor.submit(attempt_decrypt, offset): offset for offset in offset_combinations}
 
         try:
@@ -247,7 +248,8 @@ def decrypt_backup(
     db_type: DbType = DbType.MESSAGE,
     *,
     dry_run: bool = False,
-    keyfile_stream: bool = False
+    keyfile_stream: bool = False,
+    max_worker: int = 10
 ) -> int:
     """
     Decrypt the WhatsApp backup database.
@@ -308,7 +310,7 @@ def decrypt_backup(
 
     try:
         if crypt == Crypt.CRYPT14:
-            db = _decrypt_crypt14(database, main_key)
+            db = _decrypt_crypt14(database, main_key, max_worker)
         elif crypt == Crypt.CRYPT12:
             db = _decrypt_crypt12(database, main_key)
         elif crypt == Crypt.CRYPT15:

From d75c485a3d3ef68019362ee4d55d9462b7fbc923 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 2 Mar 2025 15:45:28 +0800
Subject: [PATCH 26/36] Update README.md

---
 README.md | 114 +++++++++++++++++++++++++++++++-----------------------
 1 file changed, 66 insertions(+), 48 deletions(-)

diff --git a/README.md b/README.md
index b9f502c..dfd1b70 100644
--- a/README.md
+++ b/README.md
@@ -135,55 +135,73 @@ After extracting, you will get these:
 Invoke the wtsexporter with --help option will show you all options available.
 ```sh
 > wtsexporter --help
-usage: wtsexporter [-h] [-a] [-i] [-e EXPORTED] [-w WA] [-m MEDIA] [-b BACKUP] [-o OUTPUT] [-j [JSON]]
-                   [--avoid-encoding-json] [--pretty-print-json [PRETTY_PRINT_JSON]] [-d DB] [-k KEY] [-t TEMPLATE]
-                   [-s] [-c] [--offline OFFLINE] [--size [SIZE]] [--no-html] [--check-update] [--assume-first-as-me]
-                   [--no-avatar] [--import] [--business] [--wab WAB] [--time-offset {-12 to 14}] [--date DATE]
+usage: wtsexporter [-h] [-a] [-i] [-e EXPORTED] [-w WA] [-m MEDIA] [-b BACKUP] [-d DB] [-k [KEY]]
+                   [--call-db [CALL_DB_IOS]] [--wab WAB] [-o OUTPUT] [-j [JSON]] [--txt [TEXT_FORMAT]] [--no-html]
+                   [--size [SIZE]] [--avoid-encoding-json] [--pretty-print-json [PRETTY_PRINT_JSON]] [--per-chat]
+                   [--import] [-t TEMPLATE] [--offline OFFLINE] [--no-avatar] [--experimental-new-theme]
+                   [--headline HEADLINE] [-c] [--create-separated-media] [--time-offset {-12 to 14}] [--date DATE]
                    [--date-format FORMAT] [--include [phone number ...]] [--exclude [phone number ...]]
-                   [--dont-filter-empty] [--per-chat] [--create-separated-media]
-                   [--decrypt-chunk-size DECRYPT_CHUNK_SIZE] [--enrich-from-vcards ENRICH_FROM_VCARDS]
-                   [--default-country-code DEFAULT_CONTRY_CODE] [--txt [TEXT_FORMAT]] [--experimental-new-theme]
-                   [--call-db [CALL_DB_IOS]] [--headline HEADLINE]
+                   [--dont-filter-empty] [--enrich-from-vcards ENRICH_FROM_VCARDS]
+                   [--default-country-code DEFAULT_COUNTRY_CODE] [-s] [--check-update] [--assume-first-as-me]
+                   [--business] [--decrypt-chunk-size DECRYPT_CHUNK_SIZE]
+                   [--max-bruteforce-worker MAX_BRUTEFORCE_WORKER]
 
 A customizable Android and iOS/iPadOS WhatsApp database parser that will give you the history of your WhatsApp
 conversations in HTML and JSON. Android Backup Crypt12, Crypt14 and Crypt15 supported.
 
 options:
   -h, --help            show this help message and exit
+
+Device Type:
   -a, --android         Define the target as Android
-  -i, --ios,            Define the target as iPhone/iPad
-  -e EXPORTED, --exported EXPORTED
+  -i, --ios             Define the target as iPhone/iPad
+  -e, --exported EXPORTED
                         Define the target as exported chat file and specify the path to the file
-  -w WA, --wa WA        Path to contact database (default: wa.db/ContactsV2.sqlite)
-  -m MEDIA, --media MEDIA
-                        Path to WhatsApp media folder (default: WhatsApp)
-  -b BACKUP, --backup BACKUP
-                        Path to Android (must be used together with -k)/iOS WhatsApp backup
-  -o OUTPUT, --output OUTPUT
-                        Output to specific directory (default: result)
-  -j [JSON], --json [JSON]
-                        Save the result to a single JSON file (default if present: result.json)
+
+Input Files:
+  -w, --wa WA           Path to contact database (default: wa.db/ContactsV2.sqlite)
+  -m, --media MEDIA     Path to WhatsApp media folder (default: WhatsApp)
+  -b, --backup BACKUP   Path to Android (must be used together with -k)/iOS WhatsApp backup
+  -d, --db DB           Path to database file (default: msgstore.db/7c7fba66680ef796b916b067077cc246adacf01d)
+  -k, --key [KEY]       Path to key file. If this option is set for crypt15 backup but nothing is specified, you will
+                        be prompted to enter the key.
+  --call-db [CALL_DB_IOS]
+                        Path to call database (default: 1b432994e958845fffe8e2f190f26d1511534088) iOS only
+  --wab, --wa-backup WAB
+                        Path to contact database in crypt15 format
+
+Output Options:
+  -o, --output OUTPUT   Output to specific directory (default: result)
+  -j, --json [JSON]     Save the result to a single JSON file (default if present: result.json)
+  --txt [TEXT_FORMAT]   Export chats in text format similar to what WhatsApp officially provided (default if present:
+                        result/)
+  --no-html             Do not output html files
+  --size, --output-size, --split [SIZE]
+                        Maximum (rough) size of a single output file in bytes, 0 for auto
+
+JSON Options:
   --avoid-encoding-json
                         Don't encode non-ascii characters in the output JSON files
   --pretty-print-json [PRETTY_PRINT_JSON]
                         Pretty print the output JSON.
-  -d DB, --db DB        Path to database file (default: msgstore.db/7c7fba66680ef796b916b067077cc246adacf01d)
-  -k KEY, --key KEY     Path to key file
-  -t TEMPLATE, --template TEMPLATE
-                        Path to custom HTML template
-  -s, --showkey         Show the HEX key used to decrypt the database
-  -c, --move-media      Move the media directory to output directory if the flag is set, otherwise copy it
-  --offline OFFLINE     Relative path to offline static files
-  --size [SIZE], --output-size [SIZE], --split [SIZE]
-                        Maximum (rough) size of a single output file in bytes, 0 for auto
-  --no-html             Do not output html files
-  --check-update        Check for updates (require Internet access)
-  --assume-first-as-me  Assume the first message in a chat as sent by me (must be used together with -e)
-  --no-avatar           Do not render avatar in HTML output
+  --per-chat            Output the JSON file per chat
   --import              Import JSON file and convert to HTML output
-  --business            Use Whatsapp Business default files (iOS only)
-  --wab WAB, --wa-backup WAB
-                        Path to contact database in crypt15 format
+
+HTML Options:
+  -t, --template TEMPLATE
+                        Path to custom HTML template
+  --offline OFFLINE     Relative path to offline static files
+  --no-avatar           Do not render avatar in HTML output
+  --experimental-new-theme
+                        Use the newly designed WhatsApp-alike theme
+  --headline HEADLINE   The custom headline for the HTML output. Use '??' as a placeholder for the chat name
+
+Media Handling:
+  -c, --move-media      Move the media directory to output directory if the flag is set, otherwise copy it
+  --create-separated-media
+                        Create a copy of the media seperated per chat in <MEDIA>/separated/ directory
+
+Filtering Options:
   --time-offset {-12 to 14}
                         Offset in hours (-12 to 14) for time displayed in the output
   --date DATE           The date filter in specific format (inclusive)
@@ -194,24 +212,24 @@ options:
                         Exclude chats that match the supplied phone number
   --dont-filter-empty   By default, the exporter will not render chats with no valid message. Setting this flag will
                         cause the exporter to render those. This is useful if chat(s) are missing from the output
-  --per-chat            Output the JSON file per chat
-  --create-separated-media
-                        Create a copy of the media seperated per chat in <MEDIA>/separated/ directory
-  --decrypt-chunk-size DECRYPT_CHUNK_SIZE
-                        Specify the chunk size for decrypting iOS backup, which may affect the decryption speed.
+
+Contact Enrichment:
   --enrich-from-vcards ENRICH_FROM_VCARDS
                         Path to an exported vcf file from Google contacts export. Add names missing from WhatsApp's
                         default database
-  --default-country-code DEFAULT_CONTRY_CODE
+  --default-country-code DEFAULT_COUNTRY_CODE
                         Use with --enrich-from-vcards. When numbers in the vcf file does not have a country code, this
                         will be used. 1 is for US, 66 for Thailand etc. Most likely use the number of your own country
-  --txt [TEXT_FORMAT]   Export chats in text format similar to what WhatsApp officially provided (default if present:
-                        result/)
-  --experimental-new-theme
-                        Use the newly designed WhatsApp-alike theme
-  --call-db [CALL_DB_IOS]
-                        Path to call database (default: 1b432994e958845fffe8e2f190f26d1511534088) iOS only
-  --headline HEADLINE   The custom headline for the HTML output. Use '??' as a placeholder for the chat name
+
+Miscellaneous:
+  -s, --showkey         Show the HEX key used to decrypt the database
+  --check-update        Check for updates (require Internet access)
+  --assume-first-as-me  Assume the first message in a chat as sent by me (must be used together with -e)
+  --business            Use Whatsapp Business default files (iOS only)
+  --decrypt-chunk-size DECRYPT_CHUNK_SIZE
+                        Specify the chunk size for decrypting iOS backup, which may affect the decryption speed.
+  --max-bruteforce-worker MAX_BRUTEFORCE_WORKER
+                        Specify the maximum number of worker for bruteforce decryption.
 
 WhatsApp Chat Exporter: 0.11.2 Licensed with MIT. See https://wts.knugi.dev/docs?dest=osl for all open source
 licenses.

From c56682ff8d727979cb049f8116e8994346a526ca Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sat, 29 Mar 2025 23:32:48 +0800
Subject: [PATCH 27/36] Add a potential solution for missing the database in
 iOS #125

---
 Whatsapp_Chat_Exporter/ios_media_handler.py | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/Whatsapp_Chat_Exporter/ios_media_handler.py b/Whatsapp_Chat_Exporter/ios_media_handler.py
index 317eb61..1ab6796 100644
--- a/Whatsapp_Chat_Exporter/ios_media_handler.py
+++ b/Whatsapp_Chat_Exporter/ios_media_handler.py
@@ -102,7 +102,11 @@ class BackupExtractor:
             print("Failed to decrypt backup: incorrect password?")
             exit(7)
         except FileNotFoundError:
-            print("Essential WhatsApp files are missing from the iOS backup.")
+            print(
+                "Essential WhatsApp files are missing from the iOS backup. "
+                "Perhapse you enabled end-to-end encryption for the backup? "
+                "See https://wts.knugi.dev/docs.html?dest=iose2e"
+            )
             exit(6)
         else:
             print("Done")
@@ -142,6 +146,11 @@ class BackupExtractor:
                 print("WhatsApp database not found.")
             else:
                 print("WhatsApp Business database not found.")
+            print(
+                "Essential WhatsApp files are missing from the iOS backup. "
+                "Perhapse you enabled end-to-end encryption for the backup? "
+                "See https://wts.knugi.dev/docs.html?dest=iose2e"
+            )
             exit()
         else:
             shutil.copyfile(wts_db_path, self.identifiers.MESSAGE)

From 09503069b7c52361629e7b5358b2b32be17dea77 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Tue, 8 Apr 2025 22:35:16 +0800
Subject: [PATCH 28/36] Fix name 'exit' is not defined (#107)

---
 Whatsapp_Chat_Exporter/android_crypt.py     | 1 +
 Whatsapp_Chat_Exporter/ios_media_handler.py | 3 ++-
 scripts/bruteforce_crypt15.py               | 1 +
 3 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/Whatsapp_Chat_Exporter/android_crypt.py b/Whatsapp_Chat_Exporter/android_crypt.py
index 2f764dd..84e629e 100644
--- a/Whatsapp_Chat_Exporter/android_crypt.py
+++ b/Whatsapp_Chat_Exporter/android_crypt.py
@@ -4,6 +4,7 @@ import zlib
 import concurrent.futures
 from typing import Tuple, Union
 from hashlib import sha256
+from sys import exit
 from Whatsapp_Chat_Exporter.utility import CRYPT14_OFFSETS, Crypt, DbType
 
 try:
diff --git a/Whatsapp_Chat_Exporter/ios_media_handler.py b/Whatsapp_Chat_Exporter/ios_media_handler.py
index 1ab6796..a1dcd30 100644
--- a/Whatsapp_Chat_Exporter/ios_media_handler.py
+++ b/Whatsapp_Chat_Exporter/ios_media_handler.py
@@ -4,6 +4,7 @@ import shutil
 import sqlite3
 import os
 import getpass
+from sys import exit
 from Whatsapp_Chat_Exporter.utility import WhatsAppIdentifier
 from Whatsapp_Chat_Exporter.bplist import BPListReader
 try:
@@ -151,7 +152,7 @@ class BackupExtractor:
                 "Perhapse you enabled end-to-end encryption for the backup? "
                 "See https://wts.knugi.dev/docs.html?dest=iose2e"
             )
-            exit()
+            exit(1)
         else:
             shutil.copyfile(wts_db_path, self.identifiers.MESSAGE)
 
diff --git a/scripts/bruteforce_crypt15.py b/scripts/bruteforce_crypt15.py
index 56cf912..852176c 100644
--- a/scripts/bruteforce_crypt15.py
+++ b/scripts/bruteforce_crypt15.py
@@ -3,6 +3,7 @@ import javaobj
 import zlib
 from Crypto.Cipher import AES
 from hashlib import sha256
+from sys import exit
 
 
 def _generate_hmac_of_hmac(key_stream):

From 7c7260893d8629e227c66446a262d2aab3a3dd0e Mon Sep 17 00:00:00 2001
From: Nickson Yap <nickson@seamlessx.com>
Date: Fri, 18 Apr 2025 03:02:10 +0800
Subject: [PATCH 29/36] Add the fileID / SHA-1 for CallHistory.sqlite of
 WhatsApp for Business

---
 Whatsapp_Chat_Exporter/utility.py | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/Whatsapp_Chat_Exporter/utility.py b/Whatsapp_Chat_Exporter/utility.py
index 259c318..6aef483 100644
--- a/Whatsapp_Chat_Exporter/utility.py
+++ b/Whatsapp_Chat_Exporter/utility.py
@@ -419,16 +419,17 @@ def slugify(value, allow_unicode=False):
 
 
 class WhatsAppIdentifier(StrEnum):
-    MESSAGE = "7c7fba66680ef796b916b067077cc246adacf01d"
-    CONTACT = "b8548dc30aa1030df0ce18ef08b882cf7ab5212f"
-    CALL = "1b432994e958845fffe8e2f190f26d1511534088"
+    MESSAGE = "7c7fba66680ef796b916b067077cc246adacf01d" # AppDomainGroup-group.net.whatsapp.WhatsApp.shared-ChatStorage.sqlite
+    CONTACT = "b8548dc30aa1030df0ce18ef08b882cf7ab5212f" # AppDomainGroup-group.net.whatsapp.WhatsApp.shared-ContactsV2.sqlite
+    CALL = "1b432994e958845fffe8e2f190f26d1511534088" # AppDomainGroup-group.net.whatsapp.WhatsApp.shared-CallHistory.sqlite
     DOMAIN = "AppDomainGroup-group.net.whatsapp.WhatsApp.shared"
 
 
 class WhatsAppBusinessIdentifier(StrEnum):
-    MESSAGE = "724bd3b98b18518b455a87c1f3ac3a0d189c4466"
-    CONTACT = "d7246a707f51ddf8b17ee2dddabd9e0a4da5c552"
-    DOMAIN = "AppDomainGroup-group.net.whatsapp.WhatsAppSMB.shared"
+    MESSAGE = "724bd3b98b18518b455a87c1f3ac3a0d189c4466" # AppDomainGroup-group.net.whatsapp.WhatsAppSMB.shared-ChatStorage.sqlite
+    CONTACT = "d7246a707f51ddf8b17ee2dddabd9e0a4da5c552" # AppDomainGroup-group.net.whatsapp.WhatsAppSMB.shared-ContactsV2.sqlite
+    CALL = "b463f7c4365eefc5a8723930d97928d4e907c603" # AppDomainGroup-group.net.whatsapp.WhatsAppSMB.shared-CallHistory.sqlite
+    DOMAIN = "AppDomainGroup-group.net.whatsapp.WhatsAppSMB.shared" 
 
 class JidType(IntEnum):
     PM = 0

From e287ccb724686a1e77432ba77d5a0b9528fd867c Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sat, 26 Apr 2025 17:59:10 +0800
Subject: [PATCH 30/36] Bug fix on None metadata #148

---
 Whatsapp_Chat_Exporter/utility.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Whatsapp_Chat_Exporter/utility.py b/Whatsapp_Chat_Exporter/utility.py
index f465362..6d9fd36 100644
--- a/Whatsapp_Chat_Exporter/utility.py
+++ b/Whatsapp_Chat_Exporter/utility.py
@@ -436,7 +436,7 @@ def determine_metadata(content: sqlite3.Row, init_msg: Optional[str]) -> Optiona
         msg = "Someone joined this group by using a invite link"  # TODO: Find out who
     elif content["action_type"] == 27:
         msg += " changed the group description to:<br>"
-        msg += content['data'].replace("\n", '<br>')
+        msg += (content['data'] or "Unknown").replace("\n", '<br>')
     elif content["action_type"] == 28:
         try:
             old = content['old_jid'].split('@')[0]

From a22427e1557ab0ed3240ccefd80f4e571f868559 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sat, 26 Apr 2025 18:16:57 +0800
Subject: [PATCH 31/36] Rename the script

---
 ...zilian-number-processing.py => brazilian_number_processing.py} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename scripts/{brazilian-number-processing.py => brazilian_number_processing.py} (100%)

diff --git a/scripts/brazilian-number-processing.py b/scripts/brazilian_number_processing.py
similarity index 100%
rename from scripts/brazilian-number-processing.py
rename to scripts/brazilian_number_processing.py

From eaba41b60443bb2ea39ffd2350dcfd6044da16f1 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sat, 26 Apr 2025 18:17:10 +0800
Subject: [PATCH 32/36] Add introduction to the script

---
 scripts/brazilian_number_processing.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/scripts/brazilian_number_processing.py b/scripts/brazilian_number_processing.py
index 2638a99..0981d12 100644
--- a/scripts/brazilian_number_processing.py
+++ b/scripts/brazilian_number_processing.py
@@ -1,3 +1,8 @@
+"""
+This script processes a VCARD file to standardize telephone entries and add a second TEL line with the modified number (removing the extra ninth digit) for contacts with 9-digit subscribers.
+It handles numbers that may already include a "+55" prefix and ensures that the output format is consistent.
+Contributed by @magpires https://github.com/KnugiHK/WhatsApp-Chat-Exporter/issues/127#issuecomment-2646660625
+"""
 import re
 import argparse
 

From 6dde72d3302b937477c598d98720b3518d108d1a Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sat, 26 Apr 2025 18:46:10 +0800
Subject: [PATCH 33/36] Add testing for brazilian_number_processing.py

---
 scripts/brazilian_number_processing_test.py | 269 ++++++++++++++++++++
 1 file changed, 269 insertions(+)
 create mode 100644 scripts/brazilian_number_processing_test.py

diff --git a/scripts/brazilian_number_processing_test.py b/scripts/brazilian_number_processing_test.py
new file mode 100644
index 0000000..8c6a38b
--- /dev/null
+++ b/scripts/brazilian_number_processing_test.py
@@ -0,0 +1,269 @@
+import subprocess
+import unittest
+import tempfile
+import os
+from unittest.mock import patch
+
+from brazilian_number_processing import process_phone_number, process_vcard
+
+class TestVCardProcessor(unittest.TestCase):
+    
+    def test_process_phone_number(self):
+        """Test the process_phone_number function with various inputs."""
+        
+        # Test cases for 9-digit subscriber numbers
+        test_cases_9_digit = [
+            # Standard 11-digit number (2 area + 9 subscriber)
+            ("27912345678", "+55 27 91234-5678", "+55 27 1234-5678"),
+            # With country code prefix
+            ("5527912345678", "+55 27 91234-5678", "+55 27 1234-5678"),
+            # With plus in country code
+            ("+5527912345678", "+55 27 91234-5678", "+55 27 1234-5678"),
+            # With spaces and formatting
+            ("+55 27 9 1234-5678", "+55 27 91234-5678", "+55 27 1234-5678"),
+            # With trunk zero
+            ("027912345678", "+55 27 91234-5678", "+55 27 1234-5678"),
+            # With country code and trunk zero
+            ("+55027912345678", "+55 27 91234-5678", "+55 27 1234-5678"),
+            # With extra digits at the beginning (should use last 11)
+            ("99927912345678", "+55 27 91234-5678", "+55 27 1234-5678"),
+            # With extra non-digit characters
+            ("+55-27-9.1234_5678", "+55 27 91234-5678", "+55 27 1234-5678"),
+        ]
+        
+        # Test cases for 8-digit subscriber numbers
+        test_cases_8_digit = [
+            # Standard 10-digit number (2 area + 8 subscriber)
+            ("2712345678", "+55 27 1234-5678", None),
+            # With country code prefix
+            ("552712345678", "+55 27 1234-5678", None),
+            # With plus in country code
+            ("+552712345678", "+55 27 1234-5678", None),
+            # With spaces and formatting
+            ("+55 27 1234-5678", "+55 27 1234-5678", None),
+            # With trunk zero
+            ("02712345678", "+55 27 1234-5678", None),
+            # With country code and trunk zero
+            ("+55 0 27 1234-5678", "+55 27 1234-5678", None),
+        ]
+        
+        # Edge cases
+        edge_cases = [
+            # Too few digits
+            ("271234567", None, None),
+            # Empty string
+            ("", None, None),
+            # Non-numeric characters only
+            ("abc-def+ghi", None, None),
+            # Single digit
+            ("1", None, None),
+            # Unusual formatting but valid number
+            ("(+55) [27] 9.1234_5678", "+55 27 91234-5678", "+55 27 1234-5678"),
+        ]
+        
+        # Run tests for all cases
+        all_cases = test_cases_9_digit + test_cases_8_digit + edge_cases
+        
+        for raw_phone, expected_orig, expected_mod in all_cases:
+            with self.subTest(raw_phone=raw_phone):
+                orig, mod = process_phone_number(raw_phone)
+                self.assertEqual(orig, expected_orig)
+                self.assertEqual(mod, expected_mod)
+    
+    def test_process_vcard(self):
+        """Test the process_vcard function with various VCARD formats."""
+        
+        # Test case 1: Standard TEL entries
+        vcard1 = """BEGIN:VCARD
+VERSION:3.0
+N:Doe;John;;;
+FN:John Doe
+TEL:+5527912345678
+TEL:+552712345678
+END:VCARD
+"""
+        expected1 = """BEGIN:VCARD
+VERSION:3.0
+N:Doe;John;;;
+FN:John Doe
+TEL;TYPE=CELL:+55 27 91234-5678
+TEL;TYPE=CELL:+55 27 1234-5678
+TEL;TYPE=CELL:+55 27 1234-5678
+END:VCARD
+"""
+
+        # Test case 2: TEL entries with TYPE attributes
+        vcard2 = """BEGIN:VCARD
+VERSION:3.0
+N:Smith;Jane;;;
+FN:Jane Smith
+TEL;TYPE=CELL:+5527912345678
+TEL;TYPE=HOME:+552712345678
+END:VCARD
+"""
+        expected2 = """BEGIN:VCARD
+VERSION:3.0
+N:Smith;Jane;;;
+FN:Jane Smith
+TEL;TYPE=CELL:+55 27 91234-5678
+TEL;TYPE=CELL:+55 27 1234-5678
+TEL;TYPE=CELL:+55 27 1234-5678
+END:VCARD
+"""
+
+        # Test case 3: Complex TEL entries with prefixes
+        vcard3 = """BEGIN:VCARD
+VERSION:3.0
+N:Brown;Robert;;;
+FN:Robert Brown
+item1.TEL:+5527912345678
+item2.TEL;TYPE=CELL:+552712345678
+END:VCARD
+"""
+        expected3 = """BEGIN:VCARD
+VERSION:3.0
+N:Brown;Robert;;;
+FN:Robert Brown
+TEL;TYPE=CELL:+55 27 91234-5678
+TEL;TYPE=CELL:+55 27 1234-5678
+TEL;TYPE=CELL:+55 27 1234-5678
+END:VCARD
+"""
+
+        # Test case 4: Mixed valid and invalid phone numbers
+        vcard4 = """BEGIN:VCARD
+VERSION:3.0
+N:White;Alice;;;
+FN:Alice White
+TEL:123
+TEL:+5527912345678
+END:VCARD
+"""
+        expected4 = """BEGIN:VCARD
+VERSION:3.0
+N:White;Alice;;;
+FN:Alice White
+TEL:123
+TEL;TYPE=CELL:+55 27 91234-5678
+TEL;TYPE=CELL:+55 27 1234-5678
+END:VCARD
+"""
+
+        # Test case 5: Multiple contacts with different formats
+        vcard5 = """BEGIN:VCARD
+VERSION:3.0
+N:Johnson;Mike;;;
+FN:Mike Johnson
+TEL:27912345678
+END:VCARD
+BEGIN:VCARD
+VERSION:3.0
+N:Williams;Sarah;;;
+FN:Sarah Williams
+TEL;TYPE=CELL:2712345678
+END:VCARD
+"""
+        expected5 = """BEGIN:VCARD
+VERSION:3.0
+N:Johnson;Mike;;;
+FN:Mike Johnson
+TEL;TYPE=CELL:+55 27 91234-5678
+TEL;TYPE=CELL:+55 27 1234-5678
+END:VCARD
+BEGIN:VCARD
+VERSION:3.0
+N:Williams;Sarah;;;
+FN:Sarah Williams
+TEL;TYPE=CELL:+55 27 1234-5678
+END:VCARD
+"""
+
+        # Test case 6: VCARD with no phone numbers
+        vcard6 = """BEGIN:VCARD
+VERSION:3.0
+N:Davis;Tom;;;
+FN:Tom Davis
+EMAIL:tom@example.com
+END:VCARD
+"""
+        expected6 = """BEGIN:VCARD
+VERSION:3.0
+N:Davis;Tom;;;
+FN:Tom Davis
+EMAIL:tom@example.com
+END:VCARD
+"""
+
+        test_cases = [
+            (vcard1, expected1),
+            (vcard2, expected2),
+            (vcard3, expected3),
+            (vcard4, expected4),
+            (vcard5, expected5),
+            (vcard6, expected6)
+        ]
+        
+        for i, (input_vcard, expected_output) in enumerate(test_cases):
+            with self.subTest(case=i+1):
+                # Create temporary files for input and output
+                with tempfile.NamedTemporaryFile(mode='w+', delete=False, encoding='utf-8') as input_file:
+                    input_file.write(input_vcard)
+                    input_path = input_file.name
+                
+                output_path = input_path + '.out'
+                
+                try:
+                    # Process the VCARD
+                    process_vcard(input_path, output_path)
+                    
+                    # Read and verify the output
+                    with open(output_path, 'r', encoding='utf-8') as output_file:
+                        actual_output = output_file.read()
+
+                    self.assertEqual(actual_output, expected_output)
+                    
+                finally:
+                    # Clean up temporary files
+                    if os.path.exists(input_path):
+                        os.unlink(input_path)
+                    if os.path.exists(output_path):
+                        os.unlink(output_path)
+
+    def test_script_argument_handling(self):
+        """Test the script's command-line argument handling."""
+        
+        test_input = """BEGIN:VCARD
+VERSION:3.0
+N:Test;User;;;
+FN:User Test
+TEL:+5527912345678
+END:VCARD
+"""
+        
+        # Create a temporary input file
+        with tempfile.NamedTemporaryFile(mode='w+', delete=False, encoding='utf-8') as input_file:
+            input_file.write(test_input)
+            input_path = input_file.name
+        
+        output_path = input_path + '.out'
+        
+        try:
+            test_args = ['python' if os.name == 'nt' else 'python3', 'brazilian_number_processing.py', input_path, output_path]
+            # We're just testing that the argument parsing works
+            subprocess.call(
+                test_args,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.STDOUT
+            )
+            # Check if the output file was created
+            self.assertTrue(os.path.exists(output_path))
+                    
+        finally:
+            # Clean up temporary files
+            if os.path.exists(input_path):
+                os.unlink(input_path)
+            if os.path.exists(output_path):
+                os.unlink(output_path)
+
+if __name__ == '__main__':
+    unittest.main()

From 40dc3b657e48dce73529afcf68cc10a743e1cfba Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sat, 26 Apr 2025 18:46:28 +0800
Subject: [PATCH 34/36] Fixed the regex to match any prefix for TEL fields

---
 scripts/brazilian_number_processing.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/brazilian_number_processing.py b/scripts/brazilian_number_processing.py
index 0981d12..4dd15bf 100644
--- a/scripts/brazilian_number_processing.py
+++ b/scripts/brazilian_number_processing.py
@@ -72,7 +72,7 @@ def process_vcard(input_vcard, output_vcard):
     
     # Regex to capture any telephone line.
     # It matches lines starting with "TEL:" or "TEL;TYPE=..." or with prefixes like "item1.TEL:".
-    phone_pattern = re.compile(r'^(?P<prefix>(?:TEL(?:;TYPE=[^:]+)?|(?:.*\.)?TEL)):(?P<number>.*)$')
+    phone_pattern = re.compile(r'^(?P<prefix>.*TEL(?:;TYPE=[^:]+)?):(?P<number>.*)$')
     
     for line in lines:
         stripped_line = line.rstrip("\n")

From df6bc43aa9a620c514d21104eddd548fb825c3c1 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sat, 26 Apr 2025 18:47:56 +0800
Subject: [PATCH 35/36] Handle numbers prefixing the country code without +

---
 scripts/brazilian_number_processing.py | 30 +++++++++++++++++---------
 1 file changed, 20 insertions(+), 10 deletions(-)

diff --git a/scripts/brazilian_number_processing.py b/scripts/brazilian_number_processing.py
index 4dd15bf..bb51213 100644
--- a/scripts/brazilian_number_processing.py
+++ b/scripts/brazilian_number_processing.py
@@ -24,27 +24,30 @@ def process_phone_number(raw_phone):
     (2 for area + 8 for subscriber) or 11 digits (2 for area + 9 for subscriber).
     If extra digits are present, it takes the last 11 (or 10) digits.
     """
-    # If the number starts with '+55', remove it for processing.
+    # Store the original input for processing
     number_to_process = raw_phone.strip()
-    if number_to_process.startswith("+55"):
-        number_to_process = number_to_process[3:].strip()
     
-    # Remove all non-digit characters.
+    # Remove all non-digit characters
     digits = re.sub(r'\D', '', number_to_process)
     
-    # Remove trunk zero if present.
+    # If the number starts with '55', remove it for processing
+    if digits.startswith("55") and len(digits) > 11:
+        digits = digits[2:]
+    
+    # Remove trunk zero if present
     if digits.startswith("0"):
         digits = digits[1:]
     
-    # After cleaning, we expect a valid number to have either 10 or 11 digits.
-    # If there are extra digits, use the last 11 (for a 9-digit subscriber) or last 10 (for an 8-digit subscriber).
+    # After cleaning, we expect a valid number to have either 10 or 11 digits
+    # If there are extra digits, use the last 11 (for a 9-digit subscriber) or last 10 (for an 8-digit subscriber)
     if len(digits) > 11:
-        # Here, we assume the valid number is the last 11 digits.
+        # Here, we assume the valid number is the last 11 digits
         digits = digits[-11:]
-    elif len(digits) == 12:
-        # In some cases with an 8-digit subscriber, take the last 10 digits.
+    elif len(digits) > 10 and len(digits) < 11:
+        # In some cases with an 8-digit subscriber, take the last 10 digits
         digits = digits[-10:]
     
+    # Check if we have a valid number after processing
     if len(digits) not in (10, 11):
         return None, None
 
@@ -61,10 +64,17 @@ def process_phone_number(raw_phone):
     elif len(subscriber) == 8:
         original_formatted = f"+55 {area} {subscriber[:4]}-{subscriber[4:]}"
         modified_formatted = None
+    else:
+        # This shouldn't happen given the earlier check, but just to be safe
+        return None, None
 
     return original_formatted, modified_formatted
 
 def process_vcard(input_vcard, output_vcard):
+    """
+    Process a VCARD file to standardize telephone entries and add a second TEL line
+    with the modified number (removing the extra ninth digit) for contacts with 9-digit subscribers.
+    """
     with open(input_vcard, 'r', encoding='utf-8') as file:
         lines = file.readlines()
     

From 4faf8e3e16aaa546b4fad49abc6db23c46dc8666 Mon Sep 17 00:00:00 2001
From: KnugiHK <24708955+KnugiHK@users.noreply.github.com>
Date: Sun, 27 Apr 2025 11:34:27 +0800
Subject: [PATCH 36/36] Bump version

---
 README.md      | 2 +-
 pyproject.toml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1b62513..2e303c5 100644
--- a/README.md
+++ b/README.md
@@ -239,7 +239,7 @@ Miscellaneous:
   --max-bruteforce-worker MAX_BRUTEFORCE_WORKER
                         Specify the maximum number of worker for bruteforce decryption.
 
-WhatsApp Chat Exporter: 0.11.2 Licensed with MIT. See https://wts.knugi.dev/docs?dest=osl for all open source
+WhatsApp Chat Exporter: 0.12.0 Licensed with MIT. See https://wts.knugi.dev/docs?dest=osl for all open source
 licenses.
 ```
 
diff --git a/pyproject.toml b/pyproject.toml
index e41557a..7514020 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "whatsapp-chat-exporter"
-version = "0.11.2"
+version = "0.12.0"
 description = "A Whatsapp database parser that provides history of your Whatsapp conversations in HTML and JSON. Android, iOS, iPadOS, Crypt12, Crypt14, Crypt15 supported."
 readme = "README.md"
 authors = [