Build a personal Workspace add-on

const CHECKLIST_KEY = 'HANDOFF_CHECKLIST_V1';
const NOTE_LIMIT = 120;
const RECORD_BYTE_LIMIT = 2048;
const CHECKLIST_STEPS = [
  { id: 'owner', label: 'Confirm the next owner' },
  { id: 'access', label: 'Check requested access' },
  { id: 'next', label: 'Identify the next step' },
];

/**
 * @typedef {{version: number, revision: number, note: string, checked: string[]}} ChecklistState_
 */
/**
 * @typedef {{note: string, checked: string[]}} ChecklistDraft_
 */
/**
 * @typedef {{hostApp: string, parameters: Record<string, string>, formInputs?: Record<string, unknown>}} ChecklistEvent_
 */

class ChecklistError_ extends Error {
  /** @param {string} code */
  constructor(code) {
    super(code);
    this.code = code;
  }
}

// A manifest homepage trigger returns cards, not an ActionResponse or HTML.
/**
 * @param {unknown} e
 * @returns {CardService.Card[]}
 */
function onHomepage(e) {
  try {
    requireDriveEvent_(e, false);
    const state = withUserState_((_properties, current) => current);
    return [buildChecklistCard_(state)];
  } catch (error) {
    return [buildErrorCard_(messageFor_(error))];
  }
}

// Save replaces this user's one checklist, never a Drive file or its sharing.
/**
 * @param {unknown} e
 * @returns {CardService.ActionResponse}
 */
function saveChecklist(e) {
  try {
    const common = requireAction_(e, 'save');
    const revision = readRevision_(common.parameters.revision);
    const draft = readDraft_(common.formInputs);
    const result = withUserState_((properties, current) => {
      // A repeated submission can already match, even after a lost response.
      if (sameChecklist_(current, draft)) {
        return { state: current, changed: false };
      }
      if (revision !== current.revision) {
        throw new ChecklistError_('STALE');
      }
      if (current.revision === Number.MAX_SAFE_INTEGER) {
        throw new ChecklistError_('LIMIT');
      }
      const next = {
        version: 1,
        revision: current.revision + 1,
        note: draft.note,
        checked: draft.checked,
      };
      const serialized = JSON.stringify(next);
      if (utf8Length_(serialized) > RECORD_BYTE_LIMIT) {
        throw new ChecklistError_('LIMIT');
      }
      properties.setProperty(CHECKLIST_KEY, serialized);
      return { state: next, changed: true };
    });
    return replaceCard_(
      result.state,
      result.changed ? 'Checklist saved.' : 'Already current; nothing written.',
      result.changed,
    );
  } catch (error) {
    // Notification only: do not replace the card or erase an unsaved draft.
    // An unexpected failure can follow a completed property write.
    return notify_(messageFor_(error));
  }
}

// Deliberately discard the displayed draft and read the current saved record.
/**
 * @param {unknown} e
 * @returns {CardService.ActionResponse}
 */
function reloadChecklist(e) {
  try {
    requireAction_(e, 'reload');
    const state = withUserState_((_properties, current) => current);
    return replaceCard_(state, 'Saved checklist loaded.', false);
  } catch (error) {
    return notify_(messageFor_(error));
  }
}

/**
 * @param {unknown} e
 * @param {boolean} requireParameters
 * @returns {ChecklistEvent_}
 */
function requireDriveEvent_(e, requireParameters) {
  if (!isObject_(e) || !isObject_(e.commonEventObject)) {
    throw new ChecklistError_('EVENT');
  }
  const common = e.commonEventObject;
  // Google omits commonEventObject.parameters from homepage events; button
  // actions always carry the parameters their own card attached.
  const parameters = common.parameters === undefined && !requireParameters ? {} : common.parameters;
  if (common.hostApp !== 'DRIVE' || !isStringRecord_(parameters) ||
      (common.formInputs !== undefined && !isObject_(common.formInputs))) {
    throw new ChecklistError_('EVENT');
  }
  return {
    hostApp: 'DRIVE',
    parameters: parameters,
    ...(common.formInputs === undefined ? {} : { formInputs: common.formInputs }),
  };
}

/**
 * @param {unknown} e
 * @param {string} operation
 * @returns {ChecklistEvent_}
 */
function requireAction_(e, operation) {
  const common = requireDriveEvent_(e, true);
  const keys = operation === 'save' ? ['operation', 'revision'] : ['operation'];
  if (!exactKeys_(common.parameters, keys) ||
      common.parameters.operation !== operation) {
    throw new ChecklistError_('EVENT');
  }
  return common;
}

/**
 * @param {unknown} text
 * @returns {number}
 */
function readRevision_(text) {
  if (typeof text !== 'string' || !/^(0|[1-9][0-9]{0,15})$/.test(text)) {
    throw new ChecklistError_('EVENT');
  }
  const revision = Number(text);
  if (!Number.isSafeInteger(revision)) {
    throw new ChecklistError_('EVENT');
  }
  return revision;
}

/**
 * @param {unknown} formInputs
 * @returns {ChecklistDraft_}
 */
function readDraft_(formInputs) {
  // Empty widgets can be absent. A present malformed widget is not empty.
  const inputs = formInputs === undefined ? {} : formInputs;
  if (!isObject_(inputs) ||
      Object.keys(inputs).some((key) => key !== 'note' && key !== 'checked')) {
    throw new ChecklistError_('EVENT');
  }
  const notes = stringValues_(inputs, 'note', 1);
  const note = notes.length === 0 ? '' : notes[0];
  if (!validNote_(note)) {
    throw new ChecklistError_('NOTE');
  }
  const checked = normalizeChecked_(stringValues_(inputs, 'checked', 3), 'STEPS');
  return { note, checked };
}

/**
 * @param {Record<string, unknown>} inputs
 * @param {string} name
 * @param {number} maximum
 * @returns {string[]}
 */
function stringValues_(inputs, name, maximum) {
  if (!Object.prototype.hasOwnProperty.call(inputs, name)) return [];
  const widget = inputs[name];
  if (!isObject_(widget) || !isObject_(widget.stringInputs) ||
      !Array.isArray(widget.stringInputs.value)) {
    throw new ChecklistError_('EVENT');
  }
  const values = widget.stringInputs.value;
  if (values.length > maximum || values.some((value) => typeof value !== 'string')) {
    throw new ChecklistError_('EVENT');
  }
  return values;
}

/**
 * @param {unknown} note
 * @returns {boolean}
 */
function validNote_(note) {
  return typeof note === 'string' && note.length <= NOTE_LIMIT &&
    !/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/.test(note);
}

/**
 * @param {string[]} values
 * @param {string} errorCode
 * @returns {string[]}
 */
function normalizeChecked_(values, errorCode) {
  if (!Array.isArray(values) || values.length > CHECKLIST_STEPS.length ||
      values.some((value, index) =>
        typeof value !== 'string' ||
        !CHECKLIST_STEPS.some((step) => step.id === value) ||
        values.indexOf(value) !== index)) {
    throw new ChecklistError_(errorCode);
  }
  // Widget selection order must not turn the same choices into a new save.
  return CHECKLIST_STEPS.filter((step) => values.includes(step.id)).map((step) => step.id);
}

/**
 * @template T
 * @param {(properties: PropertiesService.Properties, current: ChecklistState_) => T} work
 * @returns {T}
 */
function withUserState_(work) {
  const lock = LockService.getUserLock();
  if (!lock.tryLock(1000)) throw new ChecklistError_('BUSY');
  try {
    const properties = PropertiesService.getUserProperties();
    return work(properties, readState_(properties));
  } finally {
    lock.releaseLock();
  }
}

/**
 * @param {PropertiesService.Properties} properties
 * @returns {ChecklistState_}
 */
function readState_(properties) {
  const raw = properties.getProperty(CHECKLIST_KEY);
  if (raw === null) {
    // First render does not create a record.
    return { version: 1, revision: 0, note: '', checked: [] };
  }
  if (typeof raw !== 'string' || raw.length > RECORD_BYTE_LIMIT ||
      utf8Length_(raw) > RECORD_BYTE_LIMIT) {
    throw new ChecklistError_('STATE');
  }
  let state;
  try {
    state = JSON.parse(raw);
  } catch (_error) {
    throw new ChecklistError_('STATE');
  }
  if (!exactKeys_(state, ['version', 'revision', 'note', 'checked']) ||
      state.version !== 1 || !Number.isSafeInteger(state.revision) ||
      state.revision < 1 || !validNote_(state.note)) {
    throw new ChecklistError_('STATE');
  }
  return {
    version: 1,
    revision: state.revision,
    note: state.note,
    checked: normalizeChecked_(state.checked, 'STATE'),
  };
}

/**
 * @param {ChecklistState_} state
 * @param {ChecklistDraft_} draft
 * @returns {boolean}
 */
function sameChecklist_(state, draft) {
  return state.note === draft.note &&
    state.checked.length === draft.checked.length &&
    state.checked.every((value, index) => value === draft.checked[index]);
}

/**
 * @param {unknown} value
 * @returns {value is Record<string, unknown>}
 */
function isObject_(value) {
  return value !== null && typeof value === 'object' && !Array.isArray(value);
}

/**
 * @param {unknown} value
 * @returns {value is Record<string, string>}
 */
function isStringRecord_(value) {
  return isObject_(value) && Object.values(value).every((entry) => typeof entry === 'string');
}

/**
 * @param {unknown} value
 * @param {string[]} keys
 * @returns {boolean}
 */
function exactKeys_(value, keys) {
  return isObject_(value) && Object.keys(value).length === keys.length &&
    keys.every((key) => Object.prototype.hasOwnProperty.call(value, key));
}

/**
 * @param {string} text
 * @returns {number}
 */
function utf8Length_(text) {
  return Utilities.newBlob(text).getBytes().length;
}

/**
 * @param {string} functionName
 * @param {Record<string, string>} parameters
 * @returns {CardService.Action}
 */
function cardAction_(functionName, parameters) {
  return CardService.newAction()
    .setFunctionName(functionName)
    .setParameters(parameters)
    .setLoadIndicator(CardService.LoadIndicator.SPINNER)
    .setPersistValues(false);
}

/**
 * CardService's generated declarations omit the shared widget base type for
 * input widgets, although the runtime accepts them in a card section.
 *
 * @param {CardService.SelectionInput | CardService.TextInput} widget
 * @returns {CardService.Widget}
 */
function inputWidget_(widget) {
  return /** @type {CardService.Widget} */ (/** @type {unknown} */ (widget));
}

function reloadButton_() {
  return CardService.newTextButton()
    .setText('Reload saved')
    .setOnClickAction(cardAction_('reloadChecklist', { operation: 'reload' }));
}

/**
 * @param {ChecklistState_} state
 * @returns {CardService.Card}
 */
function buildChecklistCard_(state) {
  const progress = state.revision === 0
    ? 'No saved checklist yet. 0 of 3 checked.'
    : 'Saved progress: ' + state.checked.length + ' of 3 checked. Revision ' + state.revision + '.';
  const choices = CardService.newSelectionInput()
    .setType(CardService.SelectionInputType.CHECK_BOX)
    .setFieldName('checked')
    .setTitle('Completed items');
  for (const step of CHECKLIST_STEPS) {
    choices.addItem(step.label, step.id, state.checked.includes(step.id));
  }
  const note = CardService.newTextInput()
    .setFieldName('note')
    .setTitle('Next-step note')
    .setHint('Optional; one line, up to 120 characters. Use fictional data.')
    .setMultiline(false)
    // A widget value, not interpolated HTML or a formatted TextParagraph.
    .setValue(state.note);
  const save = CardService.newTextButton()
    .setText('Save checklist')
    .setOnClickAction(cardAction_('saveChecklist', {
      operation: 'save',
      revision: String(state.revision),
    }));
  const buttons = CardService.newButtonSet().addButton(save).addButton(reloadButton_());
  const section = CardService.newCardSection()
    .addWidget(CardService.newTextParagraph().setText(progress))
    .addWidget(CardService.newTextParagraph().setText(
      'One personal checklist, not linked to a selected file. No files or permissions are checked.',
    ))
    .addWidget(inputWidget_(choices))
    .addWidget(inputWidget_(note))
    .addWidget(CardService.newTextParagraph().setText(
      'Edits are not saved until Save checklist. Reload saved discards unsaved edits.',
    ))
    .addWidget(buttons);
  return CardService.newCardBuilder()
    .setHeader(CardService.newCardHeader().setTitle('Handoff checklist'))
    .addSection(section)
    .build();
}

/**
 * @param {string} message
 * @returns {CardService.Card}
 */
function buildErrorCard_(message) {
  return CardService.newCardBuilder()
    .setHeader(CardService.newCardHeader().setTitle('Checklist unavailable'))
    .addSection(CardService.newCardSection()
      .addWidget(CardService.newTextParagraph().setText(message))
      .addWidget(CardService.newButtonSet().addButton(reloadButton_())))
    .build();
}

/**
 * @param {ChecklistState_} state
 * @param {string} message
 * @param {boolean} changed
 * @returns {CardService.ActionResponse}
 */
function replaceCard_(state, message, changed) {
  return CardService.newActionResponseBuilder()
    .setNavigation(CardService.newNavigation().updateCard(buildChecklistCard_(state)))
    .setNotification(CardService.newNotification().setText(message))
    .setStateChanged(changed)
    .build();
}

/**
 * @param {string} message
 * @returns {CardService.ActionResponse}
 */
function notify_(message) {
  return CardService.newActionResponseBuilder()
    .setNotification(CardService.newNotification().setText(message))
    .build();
}

/**
 * @param {unknown} error
 * @returns {string}
 */
function messageFor_(error) {
  if (error instanceof ChecklistError_) {
    switch (error.code) {
      case 'EVENT':
        return 'Invalid card input. Reopen the installed add-on in Drive; nothing was written.';
      case 'NOTE':
        return 'Note not saved. Use one line of at most 120 characters without control characters.';
      case 'STEPS':
        return 'Checklist not saved. Choose only the three displayed items, without duplicates.';
      case 'STALE':
        return 'Not saved: the stored checklist changed. Keep your draft elsewhere, then Reload saved.';
      case 'BUSY':
        return 'Another checklist operation is busy. Wait, then try again; this action wrote nothing.';
      case 'STATE':
        return 'Stored checklist is invalid. It was not reset. Preserve it and ask the project owner for help.';
      case 'LIMIT':
        return 'Checklist storage limit reached. Nothing was written; ask the project owner for help.';
    }
  }
  return 'Could not confirm the result. Keep your draft elsewhere, then Reload saved before saving again.';
}

{
  "timeZone": "Etc/UTC",
  "runtimeVersion": "V8",
  "oauthScopes": [],
  "addOns": {
    "common": {
      "name": "Handoff checklist",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/check_circle_black_48dp.png",
      "homepageTrigger": {
        "runFunction": "onHomepage",
        "enabled": true
      }
    },
    "drive": {}
  }
}

{
  "version": 1,
  "revision": 1,
  "note": "REQ-001: check access with the next owner.",
  "checked": ["owner", "access"]
}