{
  "team": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Real Estate"
  },
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "email": "[email protected]"
  },
  "person": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "firstName": "Jane",
    "lastName": "Doe",
    "stage": {
      "name": "Lead"
    },
    "emails": [
      {
        "id": "email-uuid",
        "email": "[email protected]",
        "value": "[email protected]",
        "isPrimary": 1,
        "created_at": "2025-10-01T12:00:00Z",
        "updated_at": "2025-10-01T12:00:00Z"
      }
    ],
    "phones": [
      {
        "id": "phone-uuid",
        "phone": "+1-555-1234",
        "type": "mobile",
        "isPrimary": 1,
        "normalized": "15551234",
        "created_at": "2025-10-01T12:00:00Z",
        "updated_at": "2025-10-01T12:00:00Z"
      }
    ]
  },
  "timestamp": "2025-10-27T15:30:00Z"
}

{
  "team": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Real Estate"
  },
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "email": "[email protected]"
  },
  "company": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Corporation",
    "industry": "Real Estate",
    "website": "https://acme.com",
    "description": "Leading real estate development company",
    "companySize": "201-500",
    "annualRevenue": 50000000,
    "foundedDate": "2010-01-15T00:00:00Z",
    "registrationNumber": "REG-12345",
    "taxId": "TAX-67890",
    "stage": {
      "name": "Customer"
    },
    "emails": [
      {
        "id": "email-uuid",
        "email": "[email protected]",
        "value": "[email protected]",
        "isPrimary": 1,
        "created_at": "2025-10-01T12:00:00Z",
        "updated_at": "2025-10-01T12:00:00Z"
      }
    ],
    "phones": [
      {
        "id": "phone-uuid",
        "phone": "+1-555-1234",
        "type": "work",
        "isPrimary": 1,
        "normalized": "15551234",
        "created_at": "2025-10-01T12:00:00Z",
        "updated_at": "2025-10-01T12:00:00Z"
      }
    ],
    "addresses": [
      {
        "id": "address-uuid",
        "type": "office",
        "street": "123 Main Street",
        "city": "San Francisco",
        "state": "CA",
        "code": "94105",
        "country": "United States",
        "isPrimary": 1
      }
    ]
  },
  "timestamp": "2025-10-27T15:30:00Z"
}

{
  "team": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Acme Real Estate"
  },
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "email": "[email protected]"
  },
  "timestamp": "2025-10-27T15:30:00Z"
}

// JavaScript example
const data = parseContext(context);
if (data.person) {
  // This is a person view context
  displayPersonWidget(data.person);
} else if (data.company) {
  // This is a company view context
  displayCompanyWidget(data.company);
} else {
  // This is a tools view context (no contact data)
  displayToolsWidget(data.team, data.user);
}

# Python example
data = parse_context(context)
if 'person' in data:
    # This is a person view context
    render_person_widget(data['person'])
elif 'company' in data:
    # This is a company view context
    render_company_widget(data['company'])
else:
    # This is a tools view context (no contact data)
    render_tools_widget(data['team'], data['user'])

const crypto = require('crypto');

function verifySignature(context, signature, secretKey) {
  // Compute HMAC SHA-256 of the Base64-encoded context
  const computedSignature = crypto
    .createHmac('sha256', secretKey)
    .update(context)
    .digest('hex');

  // Use constant-time comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computedSignature)
  );
}

function parseContext(contextBase64) {
  const contextJson = Buffer.from(contextBase64, 'base64').toString('utf-8');
  return JSON.parse(contextJson);
}

// Usage in your widget
const urlParams = new URLSearchParams(window.location.search);
const context = urlParams.get('context');
const signature = urlParams.get('signature');

if (verifySignature(context, signature, YOUR_SECRET_KEY)) {
  const data = parseContext(context);
  // Check if this is a person or company context
  if (data.person) {
    console.log('Person:', data.person.firstName, data.person.lastName);
  } else if (data.company) {
    console.log('Company:', data.company.name);
  }
} else {
  console.error('Invalid signature!');
}

import hmac
import hashlib
import base64
import json
from flask import request

def verify_signature(context, signature, secret_key):
    """Verify HMAC SHA-256 signature"""
    computed_signature = hmac.new(
        secret_key.encode('utf-8'),
        context.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    # Use constant-time comparison
    return hmac.compare_digest(signature, computed_signature)

def parse_context(context_base64):
    """Decode and parse the context"""
    context_json = base64.b64decode(context_base64).decode('utf-8')
    return json.loads(context_json)

@app.route('/widget')
def widget():
    context = request.args.get('context')
    signature = request.args.get('signature')

    if not verify_signature(context, signature, YOUR_SECRET_KEY):
        return 'Invalid signature', 403

    data = parse_context(context)
    # Check if this is a person or company context
    if 'person' in data:
        contact = data['person']
        contact_type = 'person'
    elif 'company' in data:
        contact = data['company']
        contact_type = 'company'
    else:
        return 'Invalid context', 400

    return render_template('widget.html', contact=contact, contact_type=contact_type)

require 'openssl'
require 'base64'
require 'json'

def verify_signature(context, signature, secret_key)
  computed_signature = OpenSSL::HMAC.hexdigest(
    'sha256',
    secret_key,
    context
  )

  # Use constant-time comparison
  Rack::Utils.secure_compare(signature, computed_signature)
end

def parse_context(context_base64)
  context_json = Base64.strict_decode64(context_base64)
  JSON.parse(context_json)
end

# Usage in Sinatra/Rails controller
context = params[:context]
signature = params[:signature]

if verify_signature(context, signature, YOUR_SECRET_KEY)
  data = parse_context(context)
  # Check if this is a person or company context
  if data['person']
    @contact = data['person']
    @contact_type = 'person'
  elsif data['company']
    @contact = data['company']
    @contact_type = 'company'
  else
    halt 400, 'Invalid context'
  end
  render :widget
else
  halt 403, 'Invalid signature'
end

<?php
function verifySignature($context, $signature, $secretKey) {
    $computedSignature = hash_hmac('sha256', $context, $secretKey);
    return hash_equals($signature, $computedSignature);
}

function parseContext($contextBase64) {
    $contextJson = base64_decode($contextBase64);
    return json_decode($contextJson, true);
}

// Usage
$context = $_GET['context'];
$signature = $_GET['signature'];

if (verifySignature($context, $signature, YOUR_SECRET_KEY)) {
    $data = parseContext($context);
    // Check if this is a person or company context
    if (isset($data['person'])) {
        $contact = $data['person'];
        echo "Person: " . $contact['firstName'] . " " . $contact['lastName'];
    } elseif (isset($data['company'])) {
        $contact = $data['company'];
        echo "Company: " . $contact['name'];
    }
} else {
    http_response_code(403);
    echo "Invalid signature";
}
?>

// ❌ BAD: Using context without verification
const data = parseContext(context);

// ✅ GOOD: Verify first, then use
if (verifySignature(context, signature, secretKey)) {
  const data = parseContext(context);
}

// ❌ BAD: Vulnerable to timing attacks
if (signature === computedSignature) { ... }

// ✅ GOOD: Constant-time comparison
if (crypto.timingSafeEqual(signature, computedSignature)) { ... }

function isContextFresh(context, maxAgeSeconds = 300) {
  const timestamp = new Date(context.timestamp);
  const now = new Date();
  const ageSeconds = (now - timestamp) / 1000;
  return ageSeconds <= maxAgeSeconds;
}

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Property Recommendations</title>
    <style>
        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            margin: 0;
            padding: 20px;
            background: white;
        }
        .loading {
            text-align: center;
            padding: 40px;
            color: #666;
        }
        .error {
            background: #fee;
            border: 1px solid #fcc;
            padding: 15px;
            border-radius: 4px;
            color: #c33;
        }
        .contact-header {
            background: #f5f5f5;
            padding: 15px;
            border-radius: 8px;
            margin-bottom: 20px;
        }
        .property-card {
            border: 1px solid #e0e0e0;
            border-radius: 8px;
            padding: 15px;
            margin-bottom: 15px;
            transition: box-shadow 0.2s;
        }
        .property-card:hover {
            box-shadow: 0 2px 8px rgba(0,0,0,0.1);
        }
    </style>
</head>
<body>
    <div id="app">
        <div class="loading">Loading...</div>
    </div>

    <script>
        const SECRET_KEY = 'YOUR_SECRET_KEY_HERE';

        async function initWidget() {
            const urlParams = new URLSearchParams(window.location.search);
            const context = urlParams.get('context');
            const signature = urlParams.get('signature');

            if (!context || !signature) {
                showError('Missing context or signature');
                return;
            }

            if (!await verifySignature(context, signature)) {
                showError('Invalid signature');
                return;
            }

            const data = parseContext(context);
            renderWidget(data);
        }

        async function verifySignature(context, signature) {
            const encoder = new TextEncoder();
            const key = await crypto.subtle.importKey(
                'raw',
                encoder.encode(SECRET_KEY),
                { name: 'HMAC', hash: 'SHA-256' },
                false,
                ['sign']
            );

            const signatureBuffer = await crypto.subtle.sign(
                'HMAC',
                key,
                encoder.encode(context)
            );

            const computed = Array.from(new Uint8Array(signatureBuffer))
                .map(b => b.toString(16).padStart(2, '0'))
                .join('');

            return signature === computed;
        }

        function parseContext(contextBase64) {
            const contextJson = atob(contextBase64);
            return JSON.parse(contextJson);
        }

        function renderWidget(data) {
            const app = document.getElementById('app');
            let contact, contactType, contactName;

            // Determine if this is person or company context
            if (data.person) {
                contact = data.person;
                contactType = 'person';
                contactName = `${contact.firstName} ${contact.lastName}`;
            } else if (data.company) {
                contact = data.company;
                contactType = 'company';
                contactName = contact.name;
            } else {
                showError('Invalid context: missing person or company data');
                return;
            }

            app.innerHTML = `
                <div class="contact-header">
                    <h2>${contactName}</h2>
                    <p>Type: ${contactType === 'person' ? 'Person' : 'Company'}</p>
                    <p>Stage: ${contact.stage?.name || 'Unknown'}</p>
                    <p>Agent: ${data.user.email}</p>
                    ${contactType === 'company' ? `<p>Industry: ${contact.industry || 'N/A'}</p>` : ''}
                </div>

                <h3>Recommended Properties</h3>
                <div class="property-card">
                    <h4>Beautiful 3BR Home</h4>
                    <p>123 Main St, Anytown, USA</p>
                    <p><strong>$450,000</strong></p>
                    <button onclick="viewProperty('prop-123')">View Details</button>
                </div>

                <div class="property-card">
                    <h4>Spacious 4BR Colonial</h4>
                    <p>456 Oak Ave, Anytown, USA</p>
                    <p><strong>$575,000</strong></p>
                    <button onclick="viewProperty('prop-456')">View Details</button>
                </div>
            `;
        }

        function showError(message) {
            const app = document.getElementById('app');
            app.innerHTML = `<div class="error">${message}</div>`;
        }

        function viewProperty(id) {
            alert('Viewing property: ' + id);
            // In a real widget, you'd navigate or show details
        }

        // Initialize on page load
        initWidget();
    </script>
</body>
</html>

const crypto = require('crypto');

// Example: Person context
const personContext = {
  team: {
    id: "team-uuid-here",
    name: "Test Team"
  },
  user: {
    id: "user-uuid-here",
    email: "[email protected]"
  },
  person: {
    id: "123e4567-e89b-12d3-a456-426614174000",
    firstName: "Test",
    lastName: "User",
    stage: { name: "Lead" },
    emails: [{ value: "[email protected]", isPrimary: 1 }],
    phones: [{ phone: "+1-555-1234", type: "mobile", isPrimary: 1, normalized: "15551234" }]
  },
  timestamp: new Date().toISOString()
};

// Example: Company context
const companyContext = {
  team: {
    id: "team-uuid-here",
    name: "Test Team"
  },
  user: {
    id: "user-uuid-here",
    email: "[email protected]"
  },
  company: {
    id: "123e4567-e89b-12d3-a456-426614174000",
    name: "Test Company",
    industry: "Real Estate",
    website: "https://test.com",
    stage: { name: "Lead" },
    emails: [{ value: "[email protected]", isPrimary: 1 }],
    phones: [{ phone: "+1-555-1234", type: "work", isPrimary: 1, normalized: "15551234" }],
    addresses: [{
      type: "office",
      street: "123 Main St",
      city: "San Francisco",
      state: "CA",
      code: "94105",
      country: "United States",
      isPrimary: 1
    }]
  },
  timestamp: new Date().toISOString()
};

// Example: Tools context (no contact data)
const toolsContext = {
  team: {
    id: "team-uuid-here",
    name: "Test Team"
  },
  user: {
    id: "user-uuid-here",
    email: "[email protected]"
  },
  timestamp: new Date().toISOString()
};

function generateTestUrl(context) {
  const contextBase64 = Buffer.from(JSON.stringify(context)).toString('base64');
  const signature = crypto.createHmac('sha256', YOUR_SECRET_KEY)
    .update(contextBase64)
    .digest('hex');
  return `http://localhost:3000/widget?context=${contextBase64}&signature=${signature}`;
}

console.log('Person view:', generateTestUrl(personContext));
console.log('Company view:', generateTestUrl(companyContext));
console.log('Tools view:', generateTestUrl(toolsContext));

{
  "team": { "id": "...", "name": "..." },
  "user": { "id": "...", "email": "..." },
  "person": { ... },
  "timestamp": "2026-01-23T15:30:00Z",
  "authorization": {
    "status": "not_authorized",
    "authorization_url": "https://suresend.ai/api/widget_authorizations/initiate?widget_id=abc123&expires_at=1737654321&sig=...",
    "requested_scopes": ["read_people", "read_tasks", "write_tasks"],
    "scope_descriptions": [
      { "scope": "read_people", "description": "View people/contacts" },
      { "scope": "read_tasks", "description": "View tasks" },
      { "scope": "write_tasks", "description": "Create and update tasks" }
    ],
    "requires_team_authorization": false
  }
}

{
  "team": { "id": "...", "name": "..." },
  "user": { "id": "...", "email": "..." },
  "person": { ... },
  "timestamp": "2026-01-23T15:30:00Z",
  "authorization": {
    "status": "authorized",
    "authorization_type": "user",
    "authorized_at": "2026-01-20T10:00:00Z",
    "scopes": ["read_people", "read_tasks", "write_tasks"]
  }
}

function initWidget() {
  const data = parseContext(context);

  // Check if widget requests API access
  if (data.authorization) {
    if (data.authorization.status === 'authorized') {
      // Widget is authorized - check if we have a stored token
      const token = getStoredToken(data.team.id, data.user.id);
      if (token) {
        initializeWithApiAccess(data, token);
      } else {
        // Authorized but token not stored - show reconnect prompt
        showReconnectPrompt(data.authorization);
      }
    } else {
      // Not authorized - show connect button
      showConnectButton(data.authorization);
    }
  } else {
    // Widget doesn't require API access
    initializeBasicWidget(data);
  }
}

function showConnectButton(authorization) {
  const container = document.getElementById('auth-container');
  container.innerHTML = `
    <div class="connect-prompt">
      <h3>Connect to Sure Send CRM</h3>
      <p>This widget needs access to your CRM data to work properly.</p>
      <p><strong>Requested permissions:</strong></p>
      <ul>
        ${authorization.scope_descriptions.map(s =>
          `<li>${s.description}</li>`
        ).join('')}
      </ul>
      <button onclick="startAuthorization('${authorization.authorization_url}')">
        Connect to Sure Send
      </button>
    </div>
  `;
}

function startAuthorization(authUrl) {
  // IMPORTANT: Must open in a popup or new tab, NOT navigate the iframe!
  // This is required because:
  // 1. The iframe runs on your domain, but auth happens on suresend.ai
  // 2. Browser security blocks session cookies in cross-site iframe navigation
  // 3. Opening a popup creates a top-level navigation where cookies work properly
  window.open(authUrl, 'suresend_auth', 'popup,width=600,height=700');
}

// Alternative: Open in new tab (also works)
function startAuthorizationTab(authUrl) {
  window.open(authUrl, '_blank');
}

// DO NOT do this - will fail with "Unauthorized" error:
// window.location.href = authUrl;  // ❌ Navigates iframe, cookies blocked
// iframe.src = authUrl;            // ❌ Same issue

{
  type: 'suresend_widget_authorized',
  widget_id: 'uuid-of-widget',
  authorization_id: 'uuid-of-authorization',
  api_token: 'suresendcrm_xxxxx...',  // Full API token
  display_token: 'suresendcrm_xxxx...xxxx',  // Truncated for display
  scopes: ['read_people', 'read_tasks', 'write_tasks']
}

// Store reference to popup for cleanup
let authPopup = null;

function startAuthorization(authUrl) {
  // Open consent page in popup
  authPopup = window.open(authUrl, 'suresend_auth', 'popup,width=600,height=700');

  // Listen for the authorization callback
  window.addEventListener('message', handleAuthMessage);
}

function handleAuthMessage(event) {
  // Verify origin - use Sure Send's production domain
  // Note: 'message' is the standard Web API event for postMessage communication.
  // The origin + type checks below ensure only legitimate messages are processed.
  const allowedOrigins = [
    'https://suresend.ai'
  ];

  if (!allowedOrigins.includes(event.origin)) {
    return;
  }

  // Handle successful authorization
  if (event.data.type === 'suresend_widget_authorized') {
    console.log('Authorization received!', {
      widget_id: event.data.widget_id,
      scopes: event.data.scopes
    });

    // Store the token securely on your backend
    saveTokenToBackend(event.data.api_token, event.data.scopes)
      .then(() => {
        showSuccess('Connected to Sure Send CRM!');
        // Reload widget with API access
        initializeWithApiAccess(event.data.api_token);
      })
      .catch(err => {
        showError('Failed to save token: ' + err.message);
      });

    // Close popup if still open
    if (authPopup && !authPopup.closed) {
      authPopup.close();
    }

    // Clean up listener
    window.removeEventListener('message', handleAuthMessage);
  }
}

// Example: Save token to your widget's backend
async function saveTokenToBackend(token, scopes) {
  const response = await fetch('https://your-widget.com/api/save-token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      team_id: currentContext.team.id,
      user_id: currentContext.user.id,
      api_token: token,
      scopes: scopes
    })
  });

  if (!response.ok) {
    throw new Error('Failed to save token');
  }
}

// Token states to handle:
// 1. Token never obtained (first use)
// 2. Token valid and working
// 3. Token revoked by user
// 4. Token expired (if expiration is set)
// 5. Token lost (localStorage cleared, etc.)

async function makeApiCall(endpoint, options = {}) {
  const token = getStoredToken();

  if (!token) {
    // Case 1 or 5: No token available
    showAuthorizationPrompt();
    throw new Error('No API token - authorization required');
  }

  try {
    const response = await fetch(`https://api.suresend.ai/api/partner${endpoint}`, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    });

    if (response.status === 401) {
      // Case 3 or 4: Token revoked or expired
      handleTokenInvalid();
      throw new Error('Token invalid - re-authorization required');
    }

    if (response.status === 403) {
      // Scope insufficient for this operation
      throw new Error('Insufficient permissions for this action');
    }

    return response;
  } catch (error) {
    if (error.message.includes('authorization')) {
      throw error;
    }
    // Network or other error
    throw new Error(`API call failed: ${error.message}`);
  }
}

function handleTokenInvalid() {
  // 1. Clear the invalid token
  clearStoredToken();

  // 2. Update UI to show disconnected state
  showAuthorizationPrompt();

  // 3. Log for debugging (optional)
  console.log('Widget token invalidated - re-authorization required');
}

function initWidget() {
  const data = parseContext(context);
  const storedToken = getStoredToken(data.team.id, data.user.id);

  // Check context authorization status
  if (data.authorization) {
    if (data.authorization.status === 'authorized') {
      // CRM says we're authorized
      if (storedToken) {
        // We have a token - verify it works
        verifyTokenAndInitialize(storedToken, data);
      } else {
        // Authorized but no token stored
        // This happens if:
        // - User cleared browser storage
        // - Token was stored on a different device
        // - Previous authorization but widget never received token
        showReauthorizationPrompt(
          'Your authorization is active, but the API token was not found. ' +
          'Please reconnect to receive a new token.'
        );
      }
    } else {
      // Not authorized according to CRM
      if (storedToken) {
        // We have a stale token - clear it
        clearStoredToken(data.team.id, data.user.id);
      }
      showAuthorizationPrompt(data.authorization);
    }
  } else {
    // Widget doesn't request API access
    initializeBasicWidget(data);
  }
}

async function verifyTokenAndInitialize(token, data) {
  try {
    // Make a lightweight API call to verify token
    const response = await fetch('https://api.suresend.ai/api/partner/me', {
      headers: { 'Authorization': `Bearer ${token}` }
    });

    if (response.ok) {
      // Token is valid
      initializeWithApiAccess(data, token);
    } else if (response.status === 401) {
      // Token was revoked but context hasn't updated yet
      clearStoredToken(data.team.id, data.user.id);
      showReauthorizationPrompt(
        'Your previous authorization has been revoked. Please reconnect.'
      );
    }
  } catch (error) {
    // Network error - initialize with stored token optimistically
    initializeWithApiAccess(data, token);
  }
}

function showReauthorizationPrompt(message) {
  const container = document.getElementById('auth-container');
  container.innerHTML = `
    <div class="reauth-prompt">
      <div class="warning-icon">⚠️</div>
      <h3>Reconnection Required</h3>
      <p>${message || 'Please reconnect to continue using this widget.'}</p>
      <button onclick="startAuthorization('${currentAuthUrl}')">
        Reconnect to Sure Send
      </button>
    </div>
  `;
}

async function createTask(personId, title, dueDate) {
  const token = secureStorage.get('suresend_api_token');

  const response = await fetch('https://api.suresend.ai/api/partner/tasks', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      task: {
        taskable_type: 'Person',
        taskable_id: personId,
        title: title,
        due_date: dueDate
      }
    })
  });

  if (response.status === 401) {
    // Token expired or revoked - prompt for re-authorization
    handleTokenExpired();
    return null;
  }

  return await response.json();
}

async function makeApiCall(endpoint, options) {
  const response = await fetch(`https://api.suresend.ai/api/partner${endpoint}`, {
    ...options,
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${getToken()}`
    }
  });

  if (response.status === 401) {
    // Token was revoked or expired
    clearStoredToken();
    showConnectButton();
    throw new Error('Authorization revoked - please reconnect');
  }

  return response;
}