Collaborative Editing

// Acquire an edit lock
const lock = await client.templates.lock('template_xxxxx');
console.log(lock.lockedByName);  // "API Key ab12"
console.log(lock.expiresAt);     // "2026-01-31T12:30:00.000Z"

// If already locked by someone else, a 409 error is thrown
try {
  await client.templates.lock('template_xxxxx');
} catch (err) {
  if (err.statusCode === 409) {
    console.log('Template is locked by:', err.details.lock.lockedByName);
  }
}

// Extend the lock every 5 minutes while editing
const heartbeat = setInterval(async () => {
  try {
    await client.templates.extendLock('template_xxxxx');
  } catch (err) {
    console.error('Failed to extend lock:', err.message);
    clearInterval(heartbeat);
  }
}, 5 * 60 * 1000);

// Stop heartbeat when done editing
clearInterval(heartbeat);

// Explicitly release the lock
await client.templates.unlock('template_xxxxx');

// Save a new version with optimistic concurrency control
const version = await client.templates.saveVersion('template_xxxxx', {
  html: '<h1>Updated email content</h1>',
  subject: 'New subject line',
  message: 'Redesigned the header section',
  expectedVersion: 3,  // Must match the current version
});

console.log(version.version);  // 4
console.log(version.message);  // "Redesigned the header section"

// List version history (most recent first)
const { data: versions } = await client.templates.listVersions('template_xxxxx');

for (const v of versions) {
  console.log(`v${v.version} - ${v.editedByName} - ${v.message || 'No message'}`);
  console.log(`  Created: ${v.createdAt}`);
}

// Get a specific version to view or compare
const version = await client.templates.getVersion('template_xxxxx', 2);
console.log(version.html);     // Full HTML content of version 2
console.log(version.subject);  // Subject at version 2

// Restore version 2 as the latest version
const restored = await client.templates.restoreVersion('template_xxxxx', 2);
console.log(restored.version);  // 5 (new version number)
console.log(restored.message);  // "Restored from version 2"

// Start sending presence heartbeats
const presenceInterval = setInterval(async () => {
  await client.templates.updatePresence('template_xxxxx', {
    line: currentCursorLine,
    column: currentCursorColumn,
  });
}, 30_000); // Every 30 seconds

// Clean up on page leave
window.addEventListener('beforeunload', async () => {
  clearInterval(presenceInterval);
  await client.templates.removePresence('template_xxxxx');
});

// Poll for active editors
const { data: editors } = await client.templates.getPresence('template_xxxxx');

for (const editor of editors) {
  console.log(editor.userName, 'is viewing');
  if (editor.cursor) {
    console.log(`  Cursor at line ${editor.cursor.line}, col ${editor.cursor.column}`);
  }
}

// Remove your presence when leaving the editor
await client.templates.removePresence('template_xxxxx');

async function saveWithRetry(templateId: string, html: string) {
  // Get current template state
  let template = await client.templates.get(templateId);

  try {
    // Try to save with expected version
    return await client.templates.saveVersion(templateId, {
      html,
      expectedVersion: template.version,
      message: 'Updated content',
    });
  } catch (err) {
    if (err.statusCode === 409 && err.details?.currentVersion) {
      // Version conflict - another user saved first
      // Option 1: Reload and let the user resolve manually
      template = await client.templates.get(templateId);
      console.log('Conflict! Current version:', template.version);
      console.log('Please review the latest changes and try again.');

      // Option 2: Auto-retry with the new version (if no content conflict)
      // return await client.templates.saveVersion(templateId, {
      //   html,
      //   expectedVersion: err.details.currentVersion,
      //   message: 'Updated content (auto-retry)',
      // });
    }
    throw err;
  }
}

import { VeilMail } from '@veilmail/sdk';

const client = new VeilMail('veil_live_xxxxx');
const templateId = 'template_xxxxx';

// 1. Start editing: acquire lock and announce presence
const lock = await client.templates.lock(templateId);
console.log('Lock acquired, expires:', lock.expiresAt);

// 2. Set up heartbeats for both lock and presence
const lockHeartbeat = setInterval(async () => {
  await client.templates.extendLock(templateId);
}, 5 * 60 * 1000); // Every 5 minutes

const presenceHeartbeat = setInterval(async () => {
  await client.templates.updatePresence(templateId, {
    line: 42,
    column: 10,
  });
}, 30_000); // Every 30 seconds

// 3. Check who else is viewing
const { data: editors } = await client.templates.getPresence(templateId);
console.log(`${editors.length} editors currently viewing`);

// 4. Get the current template to read the version number
const template = await client.templates.get(templateId);

// 5. Make edits and save as a new version
const newVersion = await client.templates.saveVersion(templateId, {
  html: '<h1>Updated email content</h1><p>New paragraph.</p>',
  subject: 'Updated subject line',
  message: 'Redesigned header and added new CTA',
  expectedVersion: template.version,
});
console.log('Saved version:', newVersion.version);
// Note: Lock is auto-released after saving

// 6. Clean up
clearInterval(lockHeartbeat);
clearInterval(presenceHeartbeat);
await client.templates.removePresence(templateId);