Python: provide breakdown to differentiate net new and modified new appendix

Summary:
Add breakdown to differentiate net new (0->1) event and modified event.

- Add new appendix type constants: APPENDIX_GENERAL_NEW (0x01), APPENDIX_NET_NEW (0x02), APPENDIX_MODIFIED_NEW (0x03), APPENDIX_NO_CHANGE (0x00)
- Change _get_appendix() API from boolean to appendix type constant
- Update all usages to use appropriate appendix type:
  - APPENDIX_NET_NEW: Brand new cookies/PII (0->1)
  - APPENDIX_MODIFIED_NEW: Updated existing cookies with new payload
  - APPENDIX_NO_CHANGE: Existing values without modification

TODO: cleanup the APPENDIX_GENERAL_NEW flag, since no longer in use

Differential Revision: D91706612

fbshipit-source-id: 3b78f1a87c0a838a732398f6305b9de390253cca

Author: hongj-src

python/capi_param_builder/capi_param_builder/param_builder.py

@@ -31,6 +31,12 @@
 APPENDIX_LENGTH_V1: Final[int] = 2
 APPENDIX_LENGTH_V2: Final[int] = 8
 
+# Appendix type constants
+APPENDIX_NO_CHANGE: Final[int] = 0x00
+APPENDIX_GENERAL_NEW: Final[int] = 0x01
+APPENDIX_NET_NEW: Final[int] = 0x02
+APPENDIX_MODIFIED_NEW: Final[int] = 0x03
+
 
 class ParamBuilder:
     """
@@ -54,8 +60,9 @@ def __init__(self, input: Union[EtldPlusOneResolver, List, None] = None) -> None
         self.domain_list: Optional[List] = None
         self.etld_plus_one_resolver: Optional[EtldPlusOneResolver] = None
         ## Appendix with version number
-        self.appendix_new: str = self._get_appendix(True)
-        self.appendix_normal: str = self._get_appendix(False)
+        self.appendix_net_new: str = self._get_appendix(APPENDIX_NET_NEW)
+        self.appendix_modified_new: str = self._get_appendix(APPENDIX_MODIFIED_NEW)
+        self.appendix_no_change: str = self._get_appendix(APPENDIX_NO_CHANGE)
 
         if isinstance(input, List):
             self.domain_list = []
@@ -77,20 +84,29 @@ def _get_version(self) -> str:
             # Fallback version on any error
             return "1.0.0"
 
-    def _get_appendix(self, is_new: bool) -> str:
+    def _get_appendix(self, appendix_type: int) -> str:
         try:
             version = self._get_version()
             version_parts = version.split(".")
             major = int(version_parts[0])
             minor = int(version_parts[1])
             patch = int(version_parts[2])
 
-            is_new_byte = 0x01 if is_new else 0x00
+            # Validate appendix type
+            valid_types = [
+                APPENDIX_NET_NEW,
+                APPENDIX_GENERAL_NEW,
+                APPENDIX_MODIFIED_NEW,
+            ]
+            if appendix_type in valid_types:
+                type_byte = appendix_type
+            else:
+                type_byte = APPENDIX_NO_CHANGE
 
             bytes_array = [
                 DEFAULT_FORMAT,
                 LANGUAGE_TOKEN_INDEX,
-                is_new_byte,
+                type_byte,
                 major,
                 minor,
                 patch,
@@ -134,7 +150,7 @@ def _pre_process_cookies(
                 return None
 
         if len(cookie_split) == MIN_PAYLOAD_SPLIT_LENGTH:
-            updated_cookie = cookie_value + "." + self.appendix_normal
+            updated_cookie = cookie_value + "." + self.appendix_no_change
             self.cookies_to_set_dict[cookie_name] = CookieSettings(
                 cookie_name, updated_cookie, self.etld_plus_one, DEFAULT_1PC_AGE
             )
@@ -251,17 +267,24 @@ def _get_updated_fbc_cookie(
 
         # cookie update
         cookie_update = False
+        is_net_new = False
         if existing_fbc is None:
             cookie_update = True
+            is_net_new = True
         else:
             parts = existing_fbc.split(".")
-            cookie_update = new_fbc_payload != parts[3]
+            if len(parts) < MIN_PAYLOAD_SPLIT_LENGTH:
+                cookie_update = True  # corrupt fbc, overwrite
+                is_net_new = True
+            else:
+                cookie_update = new_fbc_payload != parts[3]
 
         if cookie_update is False:
             return None
 
         # Get ms
         now_ts = int(time.time() * 1000)
+        appendix = self.appendix_net_new if is_net_new else self.appendix_modified_new
         new_fbc = (
             "fb."
             + str(self.sub_domain_index)
@@ -270,7 +293,7 @@ def _get_updated_fbc_cookie(
             + "."
             + new_fbc_payload
             + "."
-            + self.appendix_new
+            + appendix
         )
         # TODO: update etld+1 to get proper etld+1.
         udpated_cookie_setting = CookieSettings(
@@ -297,7 +320,7 @@ def _get_updated_fbp_cookie(
             + "."
             + new_fbp_payload
             + "."
-            + self.appendix_new
+            + self.appendix_net_new
         )
         udpated_cookie_setting = CookieSettings(
             FBP_COOKIE_NAME, new_fbp, self.etld_plus_one, DEFAULT_1PC_AGE