Prepare Gmail work before sending

label:BookGmailPractice -in:drafts -in:spam -in:trash -subject:BookGmailReview

// This file combines two Gmail surfaces:
// Manual, single-operator exercise. There is no send function.
const GMAIL_WORKFLOW = {
  recipient: '', // Your test mailbox's primary address, not an alias or a list.
  labelName: 'BookGmailPractice',
  maxMessages: 3, // Allowed range: 1 through 3. Only one page is requested.
  allowDraftCreation: false,
  resolutionMessageId: '', // Copy sourceMessageId from inspectGmailWork().
  resolution: '', // KEPT_DRAFT, SENT_CONFIRMED, DISCARDED, or ABANDONED_UNCERTAIN.
  resolutionConfirmation: '' // CLOSE <sourceMessageId> AS <resolution>
};

/**
 * @typedef {{
 *   sourceMessageId: string,
 *   draftId: string,
 *   marker: string,
 *   state: string,
 *   resolution: string,
 *   updatedAt: string
 * }} GmailLedgerItem
 */

const GMAIL_WORKFLOW_LEDGER = 'gmail-workflows.v1';
const GMAIL_WORKFLOW_MAX_ITEMS = 5;

/** Read-only discovery: no draft, label, message, or property writes. */
function previewGmailWork() {
  const recipient = requireGmailConfiguration_();
  requireOwnMailbox_(recipient);
  const ledger = readGmailLedger_();
  const page = discoverGmailMessages_();
  for (const message of page.messages) {
    const item = ledger.find((entry) => entry.sourceMessageId === message.id);
    Logger.log(JSON.stringify({
      sourceMessageId: message.id,
      threadId: message.threadId,
      state: item ? item.state : 'NEW'
    }));
  }
  Logger.log(JSON.stringify({
    selectedMessages: page.messages.length,
    moreMatches: page.moreMatches,
    trackedItems: ledger.length,
    draftsCreated: 0
  }));
}

/** Creates at most three drafts addressed only to the configured own mailbox. */
function createGmailReviewDrafts() {
  const recipient = requireGmailConfiguration_();
  if (GMAIL_WORKFLOW.allowDraftCreation !== true) {
    throw new Error('Draft creation is off. Preview first, then set allowDraftCreation to true.');
  }
  withGmailWorkflowLock_(() => {
    requireOwnMailbox_(recipient);
    const ledger = readGmailLedger_();
    if (ledger.some((item) => item.state === 'CREATE_UNCERTAIN')) {
      throw new Error('An earlier draft attempt is uncertain. Inspect and reconcile it before more creation.');
    }
    const page = discoverGmailMessages_();
    const pending = page.messages.filter((message) =>
      !ledger.some((item) => item.sourceMessageId === message.id)
    );
    if (ledger.length + pending.length > GMAIL_WORKFLOW_MAX_ITEMS) {
      throw new Error('This exercise tracks at most five messages. Keep its markers; do not reset to retry.');
    }

    let created = 0;
    for (const message of pending) {
      const marker = 'BookGmailReview-' + Utilities.getUuid();
      const item = {
        sourceMessageId: message.id,
        draftId: '',
        marker: marker,
        state: 'CREATE_UNCERTAIN',
        resolution: '',
        updatedAt: new Date().toISOString()
      };
      const subject = '[' + marker + '] Review selected message';
      const body = [
        'Private review note. This is not a reply to the original sender.',
        '',
        'Selected subject: ' + message.subject,
        'Source message ID: ' + message.id,
        'Review marker: ' + marker,
        '',
        'Decision: review later. No source message body or attachment was copied.'
      ].join('\n');
      const attachment = Utilities.newBlob(
        'Review marker: ' + marker + '\nDecision: review later.\n',
        'text/plain',
        'review-note.txt'
      );

      // Save intent BEFORE dispatch. A later run must not retry an unclear result.
      ledger.push(item);
      writeGmailLedger_(ledger);
      try {
        const draft = GmailApp.createDraft(recipient, subject, body, {
          attachments: [attachment]
        });
        item.draftId = draft.getId();
        item.state = 'DRAFT_READY';
        item.updatedAt = new Date().toISOString();
        // Checkpoint this item now, not after all draft creations.
        writeGmailLedger_(ledger);
      } catch (error) {
        // Do not reset the marker or retry. The remote action may have succeeded.
        Logger.log(JSON.stringify({ sourceMessageId: message.id, marker: marker }));
        throw new Error('Draft creation or its checkpoint failed. Inspect this marker in Gmail before continuing.');
      }
      created += 1;
      Logger.log(JSON.stringify(item));
    }
    Logger.log(JSON.stringify({
      draftsCreated: created,
      alreadyTracked: page.messages.length - pending.length,
      moreMatches: page.moreMatches
    }));
  });
}

/** Reads saved observations only. It does not query Gmail or verify a draft exists. */
function inspectGmailWork() {
  const ledger = readGmailLedger_();
  for (const item of ledger) Logger.log(JSON.stringify(item));
  Logger.log('Tracked items: ' + ledger.length);
}

/** Records the operator's review, without sending, deleting, or querying mail. */
function recordGmailResolution() {
  const id = GMAIL_WORKFLOW.resolutionMessageId;
  const resolution = GMAIL_WORKFLOW.resolution;
  const outcomes = ['KEPT_DRAFT', 'SENT_CONFIRMED', 'DISCARDED', 'ABANDONED_UNCERTAIN'];
  if (typeof id !== 'string' || !id.trim() || id.length > 200 || !outcomes.includes(resolution)) {
    throw new Error('Set resolutionMessageId and one documented resolution after reviewing this item in Gmail.');
  }
  if (GMAIL_WORKFLOW.resolutionConfirmation !== 'CLOSE ' + id + ' AS ' + resolution) {
    throw new Error('Set resolutionConfirmation to CLOSE <sourceMessageId> AS <resolution>.');
  }
  withGmailWorkflowLock_(() => {
    const ledger = readGmailLedger_();
    const item = ledger.find((entry) => entry.sourceMessageId === id);
    if (!item) throw new Error('No tracked item has that sourceMessageId.');
    if (item.state === 'CLOSED' && item.resolution === resolution) {
      Logger.log('This resolution is already recorded. No write was needed.');
      return;
    }
    item.state = 'CLOSED';
    item.resolution = resolution;
    item.updatedAt = new Date().toISOString();
    writeGmailLedger_(ledger);
    Logger.log(JSON.stringify(item));
  });
}

function requireGmailConfiguration_() {
  const recipient = GMAIL_WORKFLOW.recipient.trim().toLowerCase();
  if (!/^[a-z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-z0-9.-]+\.[a-z]{2,}$/i.test(recipient) ||
      recipient.endsWith('@example.com')) {
    throw new Error('Set recipient to your own test mailbox primary address, with no display name or recipient list.');
  }
  if (!/^[A-Za-z][A-Za-z0-9_-]{0,59}$/.test(GMAIL_WORKFLOW.labelName)) {
    throw new Error('Use a label name of 1-60 letters, digits, underscores, or hyphens, starting with a letter.');
  }
  if (!Number.isInteger(GMAIL_WORKFLOW.maxMessages) ||
      GMAIL_WORKFLOW.maxMessages < 1 || GMAIL_WORKFLOW.maxMessages > 3) {
    throw new Error('maxMessages must be an integer from 1 through 3.');
  }
  return recipient;
}

/**
 * @param {string} recipient
 * @returns {void}
 */
function requireOwnMailbox_(recipient) {
  const profile = Gmail.Users.getProfile('me');
  if (!profile.emailAddress || profile.emailAddress.toLowerCase() !== recipient) {
    throw new Error('recipient does not match the executing Gmail mailbox primary address. Stop and check the signed-in account.');
  }
}

function discoverGmailMessages_() {
  if (!GmailApp.getUserLabelByName(GMAIL_WORKFLOW.labelName)) {
    throw new Error('Create the practice label in Gmail and apply it only to approved test messages.');
  }
  const query = 'label:' + GMAIL_WORKFLOW.labelName +
    ' -in:drafts -in:spam -in:trash -subject:BookGmailReview';
  const page = Gmail.Users.Messages.list('me', {
    q: query,
    maxResults: GMAIL_WORKFLOW.maxMessages,
    includeSpamTrash: false,
    fields: 'messages(id,threadId),nextPageToken'
  });
  const references = page.messages || [];
  if (references.length > GMAIL_WORKFLOW.maxMessages) {
    throw new Error('Message listing exceeded the requested bound. No drafts were created.');
  }
  const messages = [];
  for (const reference of references) {
    if (!reference.id) throw new Error('A listed message has no usable ID.');
    const message = Gmail.Users.Messages.get('me', reference.id, {
      format: 'metadata',
      metadataHeaders: ['Subject'],
      fields: 'id,threadId,labelIds,payload/headers'
    });
    // The message may have moved since listing. Never turn a draft into an input.
    const labels = message.labelIds || [];
    if (labels.some((label) => ['DRAFT', 'SPAM', 'TRASH'].includes(label))) continue;
    if (!message.id || !message.threadId) throw new Error('A listed message has no usable identity.');
    const headers = message.payload && message.payload.headers ? message.payload.headers : [];
    const subjectHeader = headers.find((header) => header.name && header.name.toLowerCase() === 'subject');
    const subject = subjectHeader && subjectHeader.value ? subjectHeader.value : '(no subject)';
    messages.push({
      id: message.id,
      threadId: message.threadId,
      subject: subject.replace(/[\u0000-\u001f\u007f]/g, ' ').slice(0, 160)
    });
  }
  return { messages: messages, moreMatches: Boolean(page.nextPageToken) };
}

/**
 * @returns {GmailLedgerItem[]}
 */
function readGmailLedger_() {
  const raw = PropertiesService.getUserProperties().getProperty(GMAIL_WORKFLOW_LEDGER);
  if (raw === null) return [];
  let ledger;
  try {
    ledger = JSON.parse(raw);
  } catch (error) {
    throw new Error('The saved ledger is not valid JSON. Preserve it and reconcile; do not clear it to retry.');
  }
  if (!Array.isArray(ledger) || ledger.length > GMAIL_WORKFLOW_MAX_ITEMS) {
    throw new Error('The saved ledger has an unexpected shape. Preserve it and reconcile.');
  }
  const ids = new Set();
  for (const item of ledger) {
    if (!item || typeof item.sourceMessageId !== 'string' ||
        !item.sourceMessageId.trim() || item.sourceMessageId.length > 200 || ids.has(item.sourceMessageId) ||
        typeof item.draftId !== 'string' || item.draftId.length > 200 ||
        typeof item.marker !== 'string' || !/^BookGmailReview-[a-f0-9-]{36}$/i.test(item.marker) ||
        !['CREATE_UNCERTAIN', 'DRAFT_READY', 'CLOSED'].includes(item.state) ||
        !['', 'KEPT_DRAFT', 'SENT_CONFIRMED', 'DISCARDED', 'ABANDONED_UNCERTAIN'].includes(item.resolution) ||
        typeof item.updatedAt !== 'string' || !Number.isFinite(Date.parse(item.updatedAt)) ||
        (item.state === 'DRAFT_READY' && !item.draftId) ||
        (item.state === 'CLOSED' && !item.resolution)) {
      throw new Error('A saved ledger item is invalid. Preserve it and reconcile; do not reset its marker.');
    }
    ids.add(item.sourceMessageId);
  }
  return ledger;
}

/**
 * @param {GmailLedgerItem[]} ledger
 * @returns {void}
 */
function writeGmailLedger_(ledger) {
  const text = JSON.stringify(ledger);
  if (ledger.length > GMAIL_WORKFLOW_MAX_ITEMS || text.length > 8000) {
    throw new Error('The exercise ledger is full. No automatic marker deletion is allowed.');
  }
  PropertiesService.getUserProperties().setProperty(GMAIL_WORKFLOW_LEDGER, text);
}

/**
 * @param {function(): void} operation
 * @returns {void}
 */
function withGmailWorkflowLock_(operation) {
  const lock = LockService.getUserLock();
  if (!lock.tryLock(1000)) throw new Error('Another run is using this ledger. Wait for it to finish.');
  try {
    operation();
  } finally {
    lock.releaseLock();
  }
}

{
  "timeZone": "Etc/UTC",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "Gmail",
        "version": "v1",
        "serviceId": "gmail"
      }
    ]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://mail.google.com/"
  ]
}

{"selectedMessages":2,"moreMatches":false,"trackedItems":0,"draftsCreated":0}

const template = `
<mjml>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text font-size="20px">Review ready</mj-text>
        <mj-text>The requested report is ready for review.</mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>`;

const output = mjml2html(template, { validationLevel: 'strict' });
if (output.errors && output.errors.length > 0) {
  throw new Error('MJML validation failed: ' + JSON.stringify(output.errors));
}

GmailApp.createDraft(recipient, subject, plainTextBody, {
  htmlBody: output.html
});