@mcpher/gas-fakes 1.0.15 → 1.0.17

package/ghissues/issue-positioned-image.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+# A script to create a GitHub issue for the PositionedImage API limitation.
+
+# Issue details
+TITLE="Cannot emulate Paragraph.addPositionedImage() due to missing public API"
+BODY=$(cat <<'EOF'
+The `DocumentApp.Paragraph.addPositionedImage()` method exists in the live Google Apps Script environment, allowing for the creation of positioned images anchored to a paragraph.
+
+However, as of May 2024, there is no corresponding public endpoint in the Google Docs API v1 to programmatically create a `PositionedObject`. The `createPositionedObject` request does not exist in the public API.
+
+This has been a requested feature, but it appears that the Apps Script service uses a private, non-public API to achieve this functionality.
+
+Because `gas-fakes` relies exclusively on the public Google Workspace APIs, it is not possible to emulate this method. Tests that use `addPositionedImage` are skipped when run in the fake environment.
+
+This issue is to track this limitation and can be closed if Google exposes a public API for this feature.
+
+See this related issue tracker for the API feature request: https://issuetracker.google.com/issues/183845501 (Note: This is a guess at a relevant issue, a real one might need to be found or created).
+EOF
+)
+LABELS="emulation-accuracy,document-app"
+
+# Create the issue using the GitHub CLI
+gh issue create --title "$TITLE" --body "$BODY" --label "$LABELS"
+

package/ghissues/post-issue.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+
+# A shell script to post a markdown file from ./ghissues as a GitHub issue.
+# It automatically extracts the title, labels, and body from the file.
+#
+# Usage: ./ghissues/post-issue.sh <filename>
+# Example: ./ghissues/post-issue.sh document-clear-behavior.md
+
+set -e
+
+# The directory where issue files are stored, relative to the script's location.
+SCRIPT_DIR=$(dirname "$0")
+
+# Check for filename argument
+if [ -z "$1" ]; then
+  echo "Usage: $0 <filename_in_ghissues_dir>"
+  echo "Example: $0 document-clear-behavior.md"
+  exit 1
+fi
+
+ISSUE_FILE="$SCRIPT_DIR/$1"
+
+# Check if file exists
+if [ ! -f "$ISSUE_FILE" ]; then
+    echo "Error: Issue file not found at $ISSUE_FILE"
+    exit 1
+fi
+
+echo "Reading issue from $ISSUE_FILE..."
+
+# Extract the title (first line, remove markdown heading)
+TITLE=$(head -n 1 "$ISSUE_FILE" | sed 's/^# //')
+
+# Extract labels from the second line (e.g., **Labels**: `label1`, `label2`)
+LABELS_LINE=$(sed -n '2p' "$ISSUE_FILE")
+LABELS_STRING=$(echo "$LABELS_LINE" | grep -o '`.*`' | sed 's/`//g' || echo "")
+
+LABEL_ARGS=()
+if [ -n "$LABELS_STRING" ]; then
+  IFS=',' read -ra ADDR <<< "$LABELS_STRING"
+  for label in "${ADDR[@]}"; do
+      trimmed_label=$(echo "$label" | xargs) # trim whitespace
+      if [ -n "$trimmed_label" ]; then
+          LABEL_ARGS+=("--label" "$trimmed_label")
+      fi
+  done
+fi
+
+# Use the rest of the file (from line 3) as the body
+gh issue create --title "$TITLE" --body-file <(tail -n +3 "$ISSUE_FILE") "${LABEL_ARGS[@]}"
+
+echo "Issue '$TITLE' created successfully."
+

package/ghissues/setup-under-construction.sh

@@ -0,0 +1,107 @@
+#!/bin/bash
+
+echo "Welcome to the gas-fakes configuration tool!"
+echo "This script will help you set up your .env and gasfakes.json files."
+
+# --- Check for existing .env file ---
+if [ -f ".env" ]; then
+    echo ""
+    echo "An existing .env file was found. We will update the values."
+    UPDATE_MODE=true
+else
+    echo ""
+    echo "No .env file found. We will create a new one."
+    UPDATE_MODE=false
+fi
+
+# --- Get .env file details ---
+echo ""
+echo "First, let's configure your .env file for Application Default Credentials (ADC)."
+echo "These are necessary for gas-fakes to access Google Workspace APIs on your behalf."
+
+read -p "Enter your Google Cloud Project ID: " gcp_project_id
+read -p "Enter the ID of a Google Drive file you have access to: " drive_test_file_id
+read -p "Enter the default scopes (e.g., \"https://www.googleapis.com/auth/userinfo.email,openid,https://www.googleapis.com/auth/cloud-platform\"): " default_scopes
+read -p "Enter any EXTRA_SCOPES (e.g., ,https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/spreadsheets): " extra_scopes
+
+# --- Update or create .env file ---
+if [ "$UPDATE_MODE" = true ]; then
+    # Use sed to replace the values in the existing file
+    sed -i "s|^GCP_PROJECT_ID=.*|GCP_PROJECT_ID=$gcp_project_id|" .env
+    sed -i "s|^DRIVE_TEST_FILE_ID=.*|DRIVE_TEST_FILE_ID=$drive_test_file_id|" .env
+    sed -i "s|^DEFAULT_SCOPES=.*|DEFAULT_SCOPES=\"$default_scopes\"|" .env
+    sed -i "s|^EXTRA_SCOPES=.*|EXTRA_SCOPES=\"$extra_scopes\"|" .env
+    echo ""
+    echo "Successfully updated the .env file."
+else
+    # Write a new .env file
+    cat <<EOF > .env
+# Required for gas-fakes to use Application Default Credentials
+GCP_PROJECT_ID="$gcp_project_id"
+DRIVE_TEST_FILE_ID="$drive_test_file_id"
+
+# This should generally be left as default for ADC
+AC=default
+
+# These are the scopes set by default - customize as needed
+DEFAULT_SCOPES="$default_scopes"
+
+# Add additional scopes here
+EXTRA_SCOPES="$extra_scopes"
+EOF
+    echo ""
+    echo "Successfully created the .env file."
+fi
+
+# --- Get gasfakes.json details ---
+echo ""
+echo "Next, let's configure your gasfakes.json file."
+echo "This file informs gas-fakes about your local environment."
+
+# Using default values as suggested by the repository
+DEFAULT_MANIFEST="./appsscript.json"
+DEFAULT_CLASP="./.clasp.json"
+DEFAULT_CACHE="/tmp/gas-fakes/cache"
+DEFAULT_PROPERTIES="/tmp/gas-fakes/properties"
+DEFAULT_SCRIPT_ID=$(uuidgen) # A fake script ID if clasp file is not used
+
+read -p "Enter the path to your manifest file (default: $DEFAULT_MANIFEST): " manifest_path
+manifest_path=${manifest_path:-$DEFAULT_MANIFEST}
+
+read -p "Enter the path to your clasp file (default: $DEFAULT_CLASP): " clasp_path
+clasp_path=${clasp_path:-$DEFAULT_CLASP}
+
+read -p "Enter a bound document ID if applicable (leave blank for none): " document_id
+if [ -z "$document_id" ]; then
+    document_id="null"
+else
+    document_id="\"$document_id\""
+fi
+
+read -p "Enter the local cache directory (default: $DEFAULT_CACHE): " cache_path
+cache_path=${cache_path:-$DEFAULT_CACHE}
+
+read -p "Enter the local properties directory (default: $DEFAULT_PROPERTIES): " properties_path
+properties_path=${properties_path:-$DEFAULT_PROPERTIES}
+
+read -p "Enter the script ID (default: a new random ID will be created): " script_id
+script_id=${script_id:-$DEFAULT_SCRIPT_ID}
+
+# --- Write gasfakes.json file ---
+cat <<EOF > gasfakes.json
+{
+    "manifest": "$manifest_path",
+    "clasp": "$clasp_path",
+    "documentId": $document_id,
+    "cache": "$cache_path",
+    "properties": "$properties_path",
+    "scriptId": "$script_id"
+}
+EOF
+
+echo ""
+echo "Successfully created the gasfakes.json file."
+
+echo ""
+echo "Setup complete! You can now run your gas-fakes project locally."
+echo "Be sure to follow the remaining setup instructions in the gas-fakes repository."

package/package.json

@@ -12,6 +12,7 @@
     "googleapis": "^157.0.0",
     "got": "^14.4.7",
     "into-stream": "^8.0.1",
+    "is": "^3.3.2",
     "keyv": "^5.5.0",
     "keyv-file": "^5.1.3",
     "mime": "^4.0.7",
@@ -49,13 +50,17 @@
     "testsheetsrange": "cp mainlocal.js main.js &&  node --env-file=.env ./test/testsheetsrange.js execute",
     "testdocslistitems": "cp mainlocal.js main.js &&  node --env-file=.env ./test/testdocslistitems.js execute",
     "testdocsall": "cp mainlocal.js main.js &&  node --env-file=.env ./test/testdocsall.js",
+    "testdocsheaders": "cp mainlocal.js main.js &&  node --env-file=.env ./test/testdocsheaders.js execute",
+    "testdocsfooters": "cp mainlocal.js main.js &&  node --env-file=.env ./test/testdocsfooters.js execute",
+    "testdocsfootnotes": "cp mainlocal.js main.js &&  node --env-file=.env ./test/testdocsfootnotes.js execute",
+    "testdocsimages": "cp mainlocal.js main.js &&  node --env-file=.env ./test/testdocsimages.js execute",
     "pub": "cp mainlocal.js main.js && npm publish --access public"
   },
   "name": "@mcpher/gas-fakes",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "license": "MIT",
   "main": "main.js",
   "description": "A proof of concept implementation of Apps Script Environment on Node",
   "repository": "github:brucemcpherson/gas-fakes",
   "homepage": "https://ramblings.mcpher.com/a-proof-of-concept-implementation-of-apps-script-environment-on-node/"
-}
+}

package/src/services/advdocs/fakeadvdocuments.js

@@ -1,9 +1,8 @@
 /**
  * Advanced docs service
  */
-
 import { Proxies } from '../../support/proxies.js'
-import { signatureArgs, ssError } from '../../support/helpers.js'
+import { signatureArgs, gError } from '../../support/helpers.js'
 import { docsCacher } from '../../support/docscacher.js';
 import { Syncit } from '../../support/syncit.js'
 import is from '@sindresorhus/is'
@@ -44,7 +43,7 @@ class FakeAdvDocuments extends FakeAdvResource {
     }, options);
 
     // maybe we need to throw an error
-    ssError(response, "create")
+    gError(response, 'docs.documents', "create")
     this.__addAllowed(data.documentId);
     return data
   }
@@ -65,7 +64,7 @@ class FakeAdvDocuments extends FakeAdvResource {
       requestBody: requests
     });
 
-    ssError(response, "batchUpdate");
+    gError(response, 'docs.documents', "batchUpdate");
 
     return data;
   }
@@ -105,7 +104,7 @@ class FakeAdvDocuments extends FakeAdvResource {
     const params = {documentId: this.__allowed(documentId), ...(options || {}) };
 
     const { response, data } = this._call("get", params);
-    ssError(response, 'get');
+    gError(response, 'docs.documents', 'get');
     return {
       data,
       response

package/src/services/documentapp/appenderhelpers.js

@@ -1,10 +1,10 @@
 import { Utils } from "../../support/utils.js";
 import { ElementType } from '../enums/docsenums.js';
-const { is } = Utils
+const { is, isBlob } = Utils
 import { getElementFactory } from './elementRegistry.js'
-import { signatureArgs } from '../../support/helpers.js';
+import { signatureArgs, notYetImplemented } from '../../support/helpers.js';
 import { findItem } from './elementhelpers.js';
-import { paragraphOptions, pageBreakOptions, tableOptions, textOptions, listItemOptions } from './elementoptions.js';
+import { paragraphOptions, pageBreakOptions, tableOptions, textOptions, listItemOptions, imageOptions, positionedImageOptions } from './elementoptions.js';
 import { deleteContentRange, createParagraphBullets, reverseUpdateContent, deleteParagraphBullets } from "./elementblasters.js";
 
 /**
@@ -34,15 +34,21 @@ const validateInserterArgs = (elementOrText, childIndex, options) => {
   if (!packCanBeNull && is.nullOrUndefined(elementOrText)) matchThrow();
 
   if (isObject) {
-    // For element objects, the live API checks type first, then attached status.
-    const typeMatches = elementOrText.getType() === elementType;
-    if (!typeMatches) {
-      matchThrow();
-    }
+    // A blob is an object, but doesn't have getType().
+    // Other elements (Paragraph, Table, etc.) do.
+    if (is.function(elementOrText.getType)) {
+      const typeMatches = elementOrText.getType() === elementType;
+      if (!typeMatches) {
+        matchThrow();
+      }
 
-    isDetached = !!elementOrText.__isDetached;
-    if (!isDetached) {
-      throw new Error('Element must be detached.');
+      isDetached = !!elementOrText.__isDetached;
+      if (!isDetached) {
+        throw new Error('Element must be detached.');
+      }
+    } else if (!isBlob(elementOrText)) {
+      // It's an object, but not a blob and doesn't have getType(). Invalid.
+      matchThrow();
     }
   } else {
     // Handle non-object arguments (arrays, strings, null)
@@ -110,33 +116,46 @@ const calculateInsertionPointsAndInitialRequests = (self, childIndex, isAppend,
       // The shadow.refresh() call at the end of elementInserter handles all named range updates correctly.
     }
   } else {
-    // It's an insert operation, creating a new element.
-    // The equality case (childIndex === children.length) is handled by the caller (e.g., FakeBody) by converting to an append.
-    if (childIndex < 0 || childIndex >= children.length) {
-      throw new Error(`Child index (${childIndex}) must be less than or equal to the number of child elements (${children.length}).`);
-    }
-    const targetChildTwig = children[childIndex];
-    const targetChildItem = elementMap.get(targetChildTwig.name);
-
-    // rules with tables mean we have to insert before preceding paragrap
-    if (targetChildItem.__type === "TABLE") {
-      insertIndex = targetChildItem.startIndex - 1; // Insert before the table.
-      if (childIndex < 1) {
-        // because a table cant ever be the first child
-        throw new Error(`Cannot insert before the first child element table (${targetChildItem.name})`);
+    // It's an insert operation.
+    const isParaInsert = self.getType() === ElementType.PARAGRAPH;
+    if (isParaInsert) {
+      // Inserting into an existing paragraph. No newlines needed.
+      if (childIndex < 0 || childIndex > children.length) {
+        throw new Error(`Child index (${childIndex}) must be between 0 and the number of child elements (${children.length}).`);
       }
-      leading = '\n'
-      // in this case the new element startindex will be +1 to the insertIndex
-      newElementStartIndex = insertIndex + 1;
+      if (children.length === 0 || childIndex === children.length) {
+        // Inserting into an empty paragraph or at the end.
+        insertIndex = item.endIndex - 1;
+      } else {
+        // Inserting before an existing child.
+        const targetChildTwig = children[childIndex];
+        const targetChildItem = elementMap.get(targetChildTwig.name);
+        insertIndex = targetChildItem.startIndex;
+      }
+      newElementStartIndex = item.startIndex; // The container is the paragraph itself.
+      childStartIndex = insertIndex; // The new child will start where we insert it.
     } else {
-      insertIndex = targetChildItem.startIndex
-      trailing = '\n'
-      newElementStartIndex = insertIndex;
+      // It's an insert operation, creating a new element in a Body/Header/etc.
+      if (childIndex < 0 || childIndex >= children.length) {
+        throw new Error(`Child index (${childIndex}) must be less than or equal to the number of child elements (${children.length}).`);
+      }
+      const targetChildTwig = children[childIndex];
+      const targetChildItem = elementMap.get(targetChildTwig.name);
+
+      if (targetChildItem.__type === "TABLE") {
+        insertIndex = targetChildItem.startIndex - 1; // Insert before the table.
+        if (childIndex < 1) {
+          throw new Error(`Cannot insert before the first child element table (${targetChildItem.name})`);
+        }
+        leading = '\n'
+        newElementStartIndex = insertIndex + 1;
+      } else {
+        insertIndex = targetChildItem.startIndex
+        trailing = '\n'
+        newElementStartIndex = insertIndex;
+      }
+      childStartIndex = null; // Child start index is unknown, must be found within container.
     }
-
-
-    // TODO validate what this is used for
-    childStartIndex = null; // Child start index is unknown, must be found within container.
   }
 
   return { insertIndex, newElementStartIndex, childStartIndex, requests, leading, trailing };
@@ -146,7 +165,7 @@ const calculateInsertionPointsAndInitialRequests = (self, childIndex, isAppend,
  * Finds and creates the new element instance after a batch update.
  * @private
  */
-const findAndReturnNewElement = (shadow, newElementStartIndex, childStartIndex, isAppend, options) => {
+const findAndReturnNewElement = (shadow, newElementStartIndex, childStartIndex, isAppend, options, segmentId) => {
   const { elementType, findType, findChildType } = options;
 
   const findContainerType = (is.function(findType) ? findType(isAppend) : findType) || elementType.toString();
@@ -157,10 +176,10 @@ const findAndReturnNewElement = (shadow, newElementStartIndex, childStartIndex,
   if (childTypeToFind) {
     if (childStartIndex !== null) {
       // The child's start index was predictable (e.g., appending to an existing paragraph).
-      finalItem = findItem(shadow.elementMap, childTypeToFind, childStartIndex);
+      finalItem = findItem(shadow.elementMap, childTypeToFind, childStartIndex, segmentId);
     } else {
       // A new container was created. Find it, then find the child within it.
-      const containerItem = findItem(shadow.elementMap, findContainerType, newElementStartIndex);
+      const containerItem = findItem(shadow.elementMap, findContainerType, newElementStartIndex, segmentId);
       const childTwig = (containerItem.__twig.children || []).find(twig => {
         const childItem = shadow.elementMap.get(twig.name);
         return childItem && childItem.__type === childTypeToFind;
@@ -172,7 +191,7 @@ const findAndReturnNewElement = (shadow, newElementStartIndex, childStartIndex,
     }
   } else {
     // For operations that return the container element itself.
-    finalItem = findItem(shadow.elementMap, findContainerType, newElementStartIndex);
+    finalItem = findItem(shadow.elementMap, findContainerType, newElementStartIndex, segmentId);
   }
 
   const factory = getElementFactory(finalItem.__type);
@@ -192,6 +211,11 @@ const findAndReturnNewElement = (shadow, newElementStartIndex, childStartIndex,
  * @private
  */
 const elementInserter = (self, elementOrText, childIndex, options) => {
+  // Before the mutation, record the container's identity.
+  const selfName = self.__name;
+  const selfStartIndex = self.__elementMapItem.startIndex;
+  const selfType = self.getType().toString();
+
   // 1. Validate arguments and determine operation type.
   const { isAppend, isDetached } = validateInserterArgs(elementOrText, childIndex, options);
 
@@ -208,7 +232,7 @@ const elementInserter = (self, elementOrText, childIndex, options) => {
 
   // 4. Build the main batch update request list.
   const { getMainRequest, getStyleRequests } = options;
-  const mainRequests = [].concat(getMainRequest({
+  const mainRequestResult = getMainRequest({
     content: elementOrText,
     location: { index: insertIndex, segmentId, tabId },
     isAppend,
@@ -216,7 +240,17 @@ const elementInserter = (self, elementOrText, childIndex, options) => {
     structure,
     leading,
     trailing
-  }));
+  });
+
+  let mainRequests;
+  let cleanup = null;
+
+  if (is.plainObject(mainRequestResult) && mainRequestResult.requests) {
+    mainRequests = [].concat(mainRequestResult.requests);
+    cleanup = mainRequestResult.cleanup;
+  } else {
+    mainRequests = [].concat(mainRequestResult);
+  }
   // if we were inserting a table then there;ll be an unwanted \n to remove - this should be -2 from the insertIndex
   // TODO we need to check if that index is actually a paragraph or not otherwise this will fail/screw up
   if (!isAppend && options.elementType === ElementType.TABLE && insertIndex > 1) {
@@ -237,10 +271,24 @@ const elementInserter = (self, elementOrText, childIndex, options) => {
   }
 
   // 5. Execute the update and refresh the document state.
-  if (requests.length > 0) {
-    Docs.Documents.batchUpdate({ requests }, shadow.getId());
+  try {
+    if (requests.length > 0) {
+      Docs.Documents.batchUpdate({ requests }, shadow.getId());
+    }
+    shadow.refresh(); // must always refresh, as getMainRequest might have side effects
+  } finally {
+    if (cleanup) {
+      cleanup();
+    }
+  }
+
+  // After the refresh, the 'self' object is stale. We need to find its new representation
+  // in the updated element map and update its internal name. This "revives" the object
+  // for subsequent method calls in the user's script.
+  const newSelfItem = findItem(shadow.elementMap, selfType, selfStartIndex, segmentId);
+  if (newSelfItem && newSelfItem.__name !== selfName) {
+    self.__name = newSelfItem.__name;
   }
-  shadow.refresh(); // must always refresh, as getMainRequest might have side effects
 
   // 6. Handle table content population if necessary. This is a two-phase update
   // because we need the table to exist before we can get the indices to populate its cells.
@@ -249,13 +297,27 @@ const elementInserter = (self, elementOrText, childIndex, options) => {
 
     if (cells && cells.length > 0 && cells[0].length > 0) {
       // The table was created at newElementStartIndex
-      const populateRequests = reverseUpdateContent(
-        shadow.__unpackDocumentTab(shadow.resource).body.content,
-        newElementStartIndex,
-        cells,
-        segmentId,
-        tabId
-      );
+      const { body, headers, footers } = shadow.__unpackDocumentTab(shadow.resource);
+      let containerContent;
+
+      // Determine the correct content array based on the container type and segmentId
+      if (self.getType() === ElementType.BODY_SECTION) {
+        containerContent = body.content;
+      } else if (self.getType() === ElementType.HEADER_SECTION) {
+        containerContent = headers[segmentId]?.content;
+      } else if (self.getType() === ElementType.FOOTER_SECTION) {
+        containerContent = footers[segmentId]?.content;
+      } else {
+        // This logic is for top-level containers. TableCell would need a different approach.
+        // For now, this covers the failing case.
+        throw new Error(`Table population not supported in container of type: ${self.getType()}`);
+      }
+
+      if (!containerContent) {
+        throw new Error(`Could not find content for segmentId: ${segmentId}`);
+      }
+
+      const populateRequests = reverseUpdateContent(containerContent, newElementStartIndex, cells, segmentId, tabId);
       if (populateRequests.length > 0) {
         Docs.Documents.batchUpdate({ requests: populateRequests }, shadow.getId());
         shadow.refresh();
@@ -265,10 +327,10 @@ const elementInserter = (self, elementOrText, childIndex, options) => {
     // When the API inserts a table, it automatically adds a paragraph after it.
     // This new paragraph can sometimes inherit the list style of the element
     // preceding the table. We need to explicitly remove this bullet formatting.
-    const tableItem = findItem(shadow.elementMap, 'TABLE', newElementStartIndex);
+    const tableItem = findItem(shadow.elementMap, 'TABLE', newElementStartIndex, segmentId);
     if (tableItem) {
       const paragraphAfterTableIndex = tableItem.endIndex;
-      const paraItem = findItem(shadow.elementMap, 'PARAGRAPH', paragraphAfterTableIndex);
+      const paraItem = findItem(shadow.elementMap, 'PARAGRAPH', paragraphAfterTableIndex, segmentId);
 
       // findItem for PARAGRAPH will also find LIST_ITEM.
       // We check if the found item has a bullet, which indicates it wrongly inherited list properties.
@@ -280,9 +342,64 @@ const elementInserter = (self, elementOrText, childIndex, options) => {
   }
 
   // 7. Find and return the newly created element instance.
-  return findAndReturnNewElement(shadow, newElementStartIndex, childStartIndex, isAppend, options);
+  return findAndReturnNewElement(shadow, newElementStartIndex, childStartIndex, isAppend, options, segmentId);
 };
 
+/**
+ * Creates a footnote and a reference to it.
+ * @param {FakeContainerElement} parent The parent container.
+ * @param {string} text The text for the footnote.
+ * @returns {GoogleAppsScript.Document.Footnote} The new footnote element.
+ */
+export const createFootnote = (parent, text) => {
+  if (parent.__isDetached) {
+    throw new Error('Cannot append to a detached element.');
+  }
+  const shadow = parent.shadowDocument;
+  const segmentId = parent.__segmentId;
+  const tabId = parent.__tabId;
+
+  // Find the insertion point at the end of the parent container.
+  const parentItem = shadow.getElement(parent.__name);
+  const children = parentItem.__twig.children;
+  const lastChild = children.length > 0 ? shadow.getElement(children[children.length - 1].name) : parentItem;
+  const insertIndex = lastChild.endIndex - 1;
+
+  const requests = [{
+    // Create a new paragraph for the footnote reference by inserting a newline at the end of the parent.
+    insertText: {
+      text: '\n',
+      location: { index: insertIndex, segmentId, tabId },
+    },
+  }, {
+    // Create the footnote and its reference at the start of the new paragraph.
+    createFootnote: {
+      location: {
+        index: insertIndex + 1,
+        segmentId,
+        tabId,
+      },
+    },
+  }];
+
+  const response = Docs.Documents.batchUpdate({ requests }, shadow.getId());
+  const footnoteId = response.replies[1].createFootnote.footnoteId;
+
+  if (text) {
+    const textRequest = {
+      insertText: {
+        text,
+        location: {
+          segmentId: footnoteId, // The footnote content is its own segment
+          index: 1, // Insert at the beginning of the footnote content
+        },
+      },
+    };
+    Docs.Documents.batchUpdate({ requests: [textRequest] }, shadow.getId());
+  }
+  shadow.refresh();
+  return shadow.getFootnoteById(footnoteId);
+};
 
 
 // THE API has no way of inserting a horizontal rule
@@ -324,4 +441,17 @@ export const appendListItem = (self, listItemOrText) => {
 
 export const insertListItem = (self, childIndex, listItemOrText) => {
   return elementInserter(self, listItemOrText, childIndex, listItemOptions);
+};
+
+export const addPositionedImage = (self, image) => {
+  // Per the docs, this anchors the image to the beginning of the paragraph.
+  return elementInserter(self, image, 0, positionedImageOptions);
+};
+
+export const appendImage = (self, image) => {
+  return elementInserter(self, image, null, imageOptions);
+};
+
+export const insertImage = (self, childIndex, image) => {
+  return elementInserter(self, image, childIndex, imageOptions);
 };

package/src/services/documentapp/elementhelpers.js

@@ -30,6 +30,9 @@ export const getElementProp = (se) => {
   if (se.textRun) return { prop: null, type: 'TEXT' };
   if (se.pageBreak) return { prop: null, type: 'PAGE_BREAK' };
   if (se.horizontalRule) return { prop: null, type: 'HORIZONTAL_RULE' };
+  if (se.footnoteReference) return { prop: null, type: 'FOOTNOTE_REFERENCE' };
+  if (se.inlineObjectElement) return { prop: null, type: 'INLINE_IMAGE' };
+  if (se.positionedObjectElement) return { prop: null, type: 'POSITIONED_IMAGE' };
 
   if (se.body) {
     return { prop: 'body', type: 'BODY_SECTION' };
@@ -90,8 +93,21 @@ export const getText = (element) => {
   // Paragraphs in the Docs API have a trailing newline. The Apps Script getText() method removes it.
   return text.replace(/\n$/, '');
 };
-export const findItem = (elementMap, type, startIndex) => {
+export const findItem = (elementMap, type, startIndex, segmentId) => {
   const item = Array.from(elementMap.values()).find(f => {
+    // segmentId from API is empty string for body, but we might pass null. Normalize.
+    const itemSegmentId = f.__segmentId || '';
+    const searchSegmentId = segmentId || '';
+    if (itemSegmentId !== searchSegmentId) {
+      return false;
+    }
+
+    // For container elements that don't have a startIndex (like Header, Footer, Footnote),
+    // we can find them by type and segmentId alone.
+    if (is.undefined(startIndex)) {
+      return f.__type === type;
+    }
+
     // A ListItem is a specialized Paragraph. A search for a PARAGRAPH should also find a LIST_ITEM
     // at the given location.
     if (type === 'PARAGRAPH') {
@@ -101,7 +117,7 @@ export const findItem = (elementMap, type, startIndex) => {
   });
   if (!item) {
     console.log(elementMap.values())
-    throw new Error(`Couldnt find element ${type} at ${startIndex}`)
+    throw new Error(`Couldnt find element ${type} at ${startIndex} in segment ${segmentId || 'body'}`)
   }
   return item
 }