fix: normalize updated page items to always return ContactChange

Author: omarsdev

README.md

@@ -93,9 +93,10 @@ type UpdatedPageBase = {
   totalContacts: number;
 };
 
-type UpdatedPage =
-  | (UpdatedPageBase & { mode: 'full'; items: Contact[] })
-  | (UpdatedPageBase & { mode: 'delta'; items: ContactChange[] });
+type UpdatedPage = UpdatedPageBase & {
+  mode: 'delta' | 'full';
+  items: ContactChange[];
+};
 ```
 
 API reference & examples
@@ -108,7 +109,7 @@ API reference & examples
 | `type PhoneNumberUpdate`  | Represents an individual phone number that changed within a contact delta (`previous` → `current`).                              |
 | `type PhoneNumberChanges` | Buckets the numbers added/removed/updated in a `ContactChange`. Useful when reconciling diffs.                                   |
 | `type ContactChange`      | Extends `Contact` with delta metadata (`changeType`, `isDeleted`, `phoneNumberChanges`, and an optional `previous` snapshot).    |
-| `type UpdatedPage`        | Union returned by paging APIs (`mode`, `items`, `nextSince`, and `totalContacts` so you know the device book size).              |
+| `type UpdatedPage`        | Page returned by paging APIs (`mode`, `items`, `nextSince`, and `totalContacts` so you know the device book size). Items are always `ContactChange[]`. |
 
 ### Functions (promise / async)
 
@@ -151,7 +152,7 @@ API reference & examples
   ```ts
   const page = await getUpdatedSincePaged(lastToken, 0, 200);
   if (page.mode === 'full') {
-    page.items.forEach((contact) => console.log('Full contact', contact.id));
+    page.items.forEach((change) => console.log('Full contact', change.id));
   } else {
     page.items.forEach((change) => console.log(change.changeType, change.id));
   }

example/src/screens/ContactsDemoScreen.tsx

@@ -105,24 +105,10 @@ const ContactsDemoScreen = ({ onTotalContactsChange }: Props) => {
           if (response.items.length === 0) {
             return false;
           }
-          if (response.mode === 'delta') {
-            collected.push(...response.items);
-          } else {
+          if (response.mode === 'full') {
             usedFullFallback = true;
-            collected.push(
-              ...response.items.map((contact) => ({
-                ...contact,
-                changeType: 'created' as ContactChange['changeType'],
-                isDeleted: false,
-                phoneNumberChanges: {
-                  created: contact.phoneNumbers,
-                  deleted: [],
-                  updated: [],
-                },
-                previous: null,
-              }))
-            );
           }
+          collected.push(...response.items);
           pageOffset += response.items.length;
           return true;
         }

src/index.tsx

@@ -12,18 +12,11 @@ type UpdatedPageBase = {
   totalContacts: number;
 };
 
-type DeltaPage = UpdatedPageBase & {
-  mode: 'delta';
+export type UpdatedPage = UpdatedPageBase & {
+  mode: 'delta' | 'full';
   items: ContactChange[];
 };
 
-type FullPage = UpdatedPageBase & {
-  mode: 'full';
-  items: Contact[];
-};
-
-export type UpdatedPage = DeltaPage | FullPage;
-
 type UpdatedPageHandler = (
   page: UpdatedPage
 ) => void | boolean | Promise<void | boolean>;
@@ -95,6 +88,47 @@ function resolveTotalContacts(nativeResult: {
   return Array.isArray(nativeResult.items) ? nativeResult.items.length : 0;
 }
 
+function synthesizeChangeFromContact(contact: Contact): ContactChange {
+  const numbers = Array.isArray(contact.phoneNumbers)
+    ? contact.phoneNumbers
+    : [];
+
+  return {
+    ...contact,
+    changeType: 'created',
+    isDeleted: false,
+    phoneNumberChanges: {
+      created: numbers,
+      deleted: [],
+      updated: [],
+    },
+    previous: null,
+  };
+}
+
+function normalizeDeltaChange(change: ContactChange): ContactChange {
+  const changes = change.phoneNumberChanges ?? {
+    created: [],
+    deleted: [],
+    updated: [],
+  };
+
+  return {
+    ...change,
+    changeType: change.changeType ?? (change.isDeleted ? 'deleted' : 'updated'),
+    isDeleted: Boolean(change.isDeleted),
+    phoneNumberChanges: {
+      created: Array.isArray(changes.created) ? changes.created : [],
+      deleted: Array.isArray(changes.deleted) ? changes.deleted : [],
+      updated: Array.isArray(changes.updated) ? changes.updated : [],
+    },
+    previous:
+      change.previous && typeof change.previous === 'object'
+        ? change.previous
+        : null,
+  };
+}
+
 // Convenience: fetch the entire contacts list in one call.
 export async function getAll(): Promise<Contact[]> {
   const contacts = await ContactsLastUpdated.getAll();
@@ -116,25 +150,31 @@ const getUpdatedSincePagedImpl = async (
   );
   const nextSince = result.nextSince ?? '';
   const totalContacts = resolveTotalContacts(result);
-  if (result.mode === 'full') {
-    return {
-      mode: 'full',
-      items: result.items,
-      nextSince,
-      totalContacts,
-    };
-  }
-  if (!nextSince && since.trim().length === 0) {
+  const shouldTreatAsFull =
+    result.mode === 'full' || (since.trim().length === 0 && !nextSince);
+
+  if (shouldTreatAsFull) {
+    const contacts =
+      result.mode === 'full'
+        ? result.items
+        : (result as unknown as { items: Contact[] }).items;
     return {
       mode: 'full',
-      items: (result as unknown as { items: Contact[] }).items,
+      items: Array.isArray(contacts)
+        ? contacts.map(synthesizeChangeFromContact)
+        : [],
       nextSince,
       totalContacts,
     };
   }
+
+  const deltas =
+    result.mode === 'delta'
+      ? result.items
+      : (result as unknown as { items: ContactChange[] }).items;
   return {
     mode: 'delta',
-    items: result.items,
+    items: Array.isArray(deltas) ? deltas.map(normalizeDeltaChange) : [],
     nextSince,
     totalContacts,
   };