Intercom Integration Architecture

┌─────────────────────────────────────────────────────────────┐
│                    MyNATCA Platform                         │
│                                                             │
│  ┌──────────────┐     ┌──────────────┐   ┌──────────────┐ │
│  │   Supabase   │────▶│  Daily Sync  │──▶│   Intercom   │ │
│  │   (Members,  │     │    Script    │   │     API      │ │
│  │  Positions)  │     └──────────────┘   └──────────────┘ │
│  └──────────────┘                               ▲          │
│                                                  │          │
│  ┌──────────────┐     ┌──────────────┐         │          │
│  │    MySQL     │────▶│   Webhook    │─────────┘          │
│  │  (Fallback)  │     │   Handler    │                    │
│  └──────────────┘     └──────────────┘                    │
│                                                             │
│                       ┌──────────────┐                     │
│                       │ Audit Script │                     │
│                       │  (One-time)  │                     │
│                       └──────────────┘                     │
└─────────────────────────────────────────────────────────────┘
                                │
                                ▼
                        ┌──────────────┐
                        │  Intercom    │
                        │  Contacts    │
                        └──────────────┘

┌─────────────────┐
│  Cron Trigger   │
│  2:30 AM UTC    │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────┐
│  Fetch Active/Retired Members   │
│  FROM Supabase members table    │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  For Each Member:               │
│  1. Get positions (Supabase)    │
│  2. Get region/facility codes   │
│  3. Format phone to E.164       │
│  4. Determine member_type       │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  Upsert to Intercom (by email)  │
│  - Create if new                │
│  - Update if exists             │
│  - Handle 409 conflicts         │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  Handle Duplicates              │
│  - Find all with same email     │
│  - Keep newest (by created_at)  │
│  - Archive older duplicates     │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  Log Results & Errors           │
│  - Created count                │
│  - Updated count                │
│  - Duplicates resolved          │
│  - Failed count                 │
└─────────────────────────────────┘

┌─────────────────────────────────┐
│  Member Messages Intercom       │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  Intercom Webhook Fires         │
│  POST /api/intercom/webhook     │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  Extract Contact ID             │
│  from conversation data         │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  Fetch Full Contact from        │
│  Intercom API                   │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  Check: Has member_number?      │
└────────┬───────────┬────────────┘
         │ No        │ Yes
         ▼           ▼
┌──────────────┐  ┌──────────────┐
│ Lookup Email │  │ Skip (done)  │
│ in MySQL     │  └──────────────┘
└──────┬───────┘
       │
       ▼
┌─────────────────────────────────┐
│  Get Positions from Supabase    │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  Update Intercom Contact        │
│  with Member Data               │
└─────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    Contact Lifecycle States                      │
└─────────────────────────────────────────────────────────────────┘

    ┌────────────┐
    │   Active   │ ◀──── Normal operational state
    └─────┬──────┘       Can be updated/deleted
          │
          │ Archive (manual or auto)
          ▼
    ┌────────────┐
    │  Archived  │ ◀──── Soft-deleted state
    └─────┬──────┘       Can be unarchived
          │
          │ Block (spam/abuse)
          ▼
    ┌────────────┐
    │  Blocked   │ ◀──── Cannot be restored until unblocked
    └────────────┘       not_restorable error

Recovery Flow:
  Blocked → Unblock → Unarchive → Active → Update

// Try to upsert
try {
  await intercomClient.upsertContact(email, data);
} catch (error) {
  if (error.includes('409') && error.includes('archived contact')) {
    // Extract contact ID
    const contactId = extractIdFromError(error);
 
    // Try to unarchive
    try {
      await intercomClient.unarchiveContact(contactId);
    } catch (unarchiveError) {
      if (unarchiveError.includes('not_restorable')) {
        // Contact is blocked - unblock first
        await intercomClient.unblockContact(contactId);
        await intercomClient.unarchiveContact(contactId);
      }
    }
 
    // Now update
    await intercomClient.updateContact(contactId, data);
  }
}

class IntercomClient {
  constructor() {
    this.maxRequestsPer10Seconds = 166;
    this.windowDuration = 10000; // 10 seconds
    this.requestsInWindow = 0;
    this.windowStart = Date.now();
  }
 
  async waitForRateLimit() {
    const now = Date.now();
    const windowElapsed = now - this.windowStart;
 
    if (windowElapsed >= this.windowDuration) {
      this.requestsInWindow = 0;
      this.windowStart = now;
      return;
    }
 
    if (this.requestsInWindow >= this.maxRequestsPer10Seconds) {
      const waitTime = this.windowDuration - windowElapsed;
      await sleep(waitTime);
      this.requestsInWindow = 0;
      this.windowStart = Date.now();
    }
  }
}

// Intercom returns 409 conflict when email/external_id already exists
try {
  await intercomClient.upsertContact(email, data);
} catch (error) {
  if (error.message.includes('409') && error.message.includes('conflict')) {
    // Handle duplicate: find all contacts, keep newest, archive older ones
    const contactId = await handleDuplicateContact(email);
    // Update the specific contact
    await intercomClient.updateContact(contactId, customAttributes, builtInFields);
  }
}

// Another contact already has this member number
try {
  await intercomClient.updateContact(id, attrs, { external_id: memberNumber });
} catch (error) {
  if (error.message.includes('unique_user_constraint')) {
    // Find existing contact with this member number
    const existingContact = await intercomClient.searchContactByExternalId(memberNumber);
    // Keep newer contact, archive older one
    if (currentContact.created_at > existingContact.created_at) {
      await intercomClient.archiveContact(existingContact.id);
      // Retry update
    } else {
      await intercomClient.archiveContact(currentContact.id);
    }
  }
}

async function getMemberPositions(supabase, memberNumber, retryCount = 0) {
  try {
    const { data, error } = await supabase
      .from('positions')
      .select('positiontype')
      .eq('membernumber', memberNumber);
 
    if (error) throw new Error(`Failed: ${error.message}`);
    return data.map(p => POSITION_CODE_TO_NAME[p.positiontype]);
  } catch (error) {
    // Retry on network failures with exponential backoff
    if (retryCount < 3 && isNetworkError(error)) {
      const delay = Math.pow(2, retryCount) * 1000; // 1s, 2s, 4s
      await sleep(delay);
      return getMemberPositions(supabase, memberNumber, retryCount + 1);
    }
    throw error;
  }
}