decap-cms-lib-util 3.8.1 → 3.8.3

package/dist/esm/index.js

@@ -7,6 +7,8 @@ import { isAbsolutePath, basename, fileExtensionWithSeparator, fileExtension } f
 import { onlySuccessfulPromises, flowAsync, then } from './promise';
 import unsentRequest from './unsentRequest';
 import { filterByExtension, getAllResponses, parseLinkHeader, parseResponse, responseParser, getPathDepth } from './backendUtil';
+import { NotesPollingManager } from './notesPolling';
+import { formatNoteBody, parseNoteBody, commentToNote, commentsToNotes, markOwnNotes } from './notesFormat';
 import loadScript from './loadScript';
 import getBlobSHA from './getBlobSHA';
 import { asyncLock } from './asyncLock';
@@ -68,4 +70,4 @@ export const DecapCmsLibUtil = {
   AccessTokenError,
   throwOnConflictingBranches
 };
-export { APIError, Cursor, CURSOR_COMPATIBILITY_SYMBOL, EditorialWorkflowError, EDITORIAL_WORKFLOW_ERROR, localForage, basename, fileExtensionWithSeparator, fileExtension, onlySuccessfulPromises, flowAsync, then, unsentRequest, filterByExtension, parseLinkHeader, getAllResponses, parseResponse, responseParser, loadScript, getBlobSHA, asyncLock, isAbsolutePath, getPathDepth, entriesByFiles, entriesByFolder, unpublishedEntries, getMediaDisplayURL, getMediaAsBlob, readFile, readFileMetadata, CMS_BRANCH_PREFIX, generateContentKey, isCMSLabel, labelToStatus, statusToLabel, DEFAULT_PR_BODY, MERGE_COMMIT_MESSAGE, isPreviewContext, getPreviewStatus, runWithLock, PreviewState, parseContentKey, createPointerFile, getLargeMediaFilteredMediaFiles, getLargeMediaPatternsFromGitAttributesFile, parsePointerFile, getPointerFileForMediaFileObj, branchFromContentKey, contentKeyFromBranch, blobToFileObj, requestWithBackoff, getDefaultBranchName, allEntriesByFolder, AccessTokenError, throwOnConflictingBranches };
+export { NotesPollingManager, formatNoteBody, parseNoteBody, commentToNote, commentsToNotes, markOwnNotes, APIError, Cursor, CURSOR_COMPATIBILITY_SYMBOL, EditorialWorkflowError, EDITORIAL_WORKFLOW_ERROR, localForage, basename, fileExtensionWithSeparator, fileExtension, onlySuccessfulPromises, flowAsync, then, unsentRequest, filterByExtension, parseLinkHeader, getAllResponses, parseResponse, responseParser, loadScript, getBlobSHA, asyncLock, isAbsolutePath, getPathDepth, entriesByFiles, entriesByFolder, unpublishedEntries, getMediaDisplayURL, getMediaAsBlob, readFile, readFileMetadata, CMS_BRANCH_PREFIX, generateContentKey, isCMSLabel, labelToStatus, statusToLabel, DEFAULT_PR_BODY, MERGE_COMMIT_MESSAGE, isPreviewContext, getPreviewStatus, runWithLock, PreviewState, parseContentKey, createPointerFile, getLargeMediaFilteredMediaFiles, getLargeMediaPatternsFromGitAttributesFile, parsePointerFile, getPointerFileForMediaFileObj, branchFromContentKey, contentKeyFromBranch, blobToFileObj, requestWithBackoff, getDefaultBranchName, allEntriesByFolder, AccessTokenError, throwOnConflictingBranches };

package/dist/esm/notesFormat.js

@@ -0,0 +1,145 @@
+/**
+ * How a note is encoded inside a comment on the host
+ *
+ * A note is an ordinary comment with a leading HTML comment carrying
+ * whether the note is resolved and who wrote it - which can differ from
+ * the account that posted it.
+ * Hosts render HTML comments invisibly, so the marker stays out of the way
+ * when the thread is read on the host's own site.
+ *
+ * Encoding is identical across backends
+ */
+
+const MARKER_PREFIX = '<!-- DecapCMS Note ';
+const MARKER_SUFFIX = ' -->';
+const NOTE_PATTERN = /^<!-- DecapCMS Note (\{[\s\S]*?\}) -->\n?([\s\S]*)$/;
+const LEGACY_NOTE_PATTERN = /^<!-- DecapCMS Note - Status: (RESOLVED|OPEN) -->\n?([\s\S]*)$/;
+
+/**
+ * A JSON string may contain `-->`, which would close the HTML comment early.
+ * Escaping every hyphen that precedes another removes every `--`, so `-->`
+ * cannot survive; `JSON.parse` decodes `\u002d` back, so it stays lossless
+ * and a lone hyphen (`Jean-Luc`) stays readable.
+ *
+ * Replacing `--` instead is not enough - a run of five hyphens leaves one
+ * behind at the seam.
+ */
+function encode(payload) {
+  return JSON.stringify(payload).replace(/-(?=-)/g, '\\u002d');
+}
+export function formatNoteBody(note) {
+  // Both or neither: a name with no id to compare against buys nothing, and a
+  // backend whose poster IS the editor records neither.
+  const identity = note.authorId && note.author ? {
+    author: note.author,
+    authorId: note.authorId
+  } : {};
+  const marker = encode({
+    resolved: note.resolved,
+    ...identity
+  });
+  return `${MARKER_PREFIX}${marker}${MARKER_SUFFIX}\n${note.content}`;
+}
+
+/**
+ * The marker is hand-editable on the host, so nothing in it is trusted to be
+ * the type it should be. A non-string author reaching `Note` crashes the pane
+ * outright - the avatar initials call `.split()` on it - so anything that is
+ * not a usable string is treated as no recorded author, which falls back to
+ * the account that posted the comment.
+ */
+function asString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+export function parseNoteBody(body) {
+  const match = body.match(NOTE_PATTERN);
+  if (!match) {
+    const legacy = body.match(LEGACY_NOTE_PATTERN);
+    if (legacy) {
+      return {
+        content: legacy[2].trim(),
+        resolved: legacy[1] === 'RESOLVED'
+      };
+    }
+
+    // A comment typed straight into the thread on the host. It is still a note,
+    // just an unresolved one with no recorded author.
+    return {
+      content: body.trim(),
+      resolved: false
+    };
+  }
+  let payload;
+  try {
+    payload = JSON.parse(match[1]);
+  } catch {
+    // Someone edited the marker by hand into something unparseable. Treat the
+    // whole comment as content rather than dropping the note.
+    return {
+      content: body.trim(),
+      resolved: false
+    };
+  }
+  const author = asString(payload.author);
+  const authorId = asString(payload.authorId);
+
+  // Both or neither, as formatNoteBody writes them.
+  const identity = author && authorId ? {
+    author,
+    authorId
+  } : {};
+  return {
+    content: match[2].trim(),
+    resolved: payload.resolved === true,
+    author: identity.author,
+    authorId: identity.authorId
+  };
+}
+export function commentToNote(comment) {
+  if (!comment || !comment.body) {
+    throw new Error('Invalid comment structure');
+  }
+  const {
+    content,
+    resolved,
+    author,
+    authorId
+  } = parseNoteBody(comment.body);
+  if (!content) {
+    throw new Error('Empty note content');
+  }
+  return {
+    id: comment.id.toString(),
+    // Falls back to the account that posted, for a comment typed on the host
+    // and for any note with no recorded author.
+    author: author || comment.user?.login || 'Unknown',
+    authorId,
+    // Only when the posting account IS the note's author — a recorded author
+    // means someone posted on their behalf, and its avatar would mislabel the
+    // note. The pane shows initials instead.
+    avatarUrl: authorId ? undefined : comment.user?.avatar_url || undefined,
+    timestamp: comment.created_at,
+    content,
+    resolved,
+    entrySlug: ''
+  };
+}
+export function commentsToNotes(comments, issueUrl, toNote = commentToNote) {
+  return comments.reduce((notes, comment) => {
+    try {
+      notes.push({
+        ...toNote(comment),
+        issueUrl
+      });
+    } catch (error) {
+      // Not a note; skip it
+    }
+    return notes;
+  }, []);
+}
+export function markOwnNotes(notes, identity) {
+  return notes.map(note => ({
+    ...note,
+    isOwn: note.authorId ? note.authorId === identity.authorId : note.author === identity.author
+  }));
+}

package/dist/esm/notesPolling.js

@@ -0,0 +1,424 @@
+/**
+ * Notes polling
+ *
+ * Watches the thread an entry's notes live in and reports what changed, so
+ * notes another editor adds appear without a reload. Where the host supports
+ * conditional requests the poll is an ETag round trip that returns 304 and
+ * costs no rate limit; where it does not, the manager still only reports a
+ * change when the thread's contents actually differ, so a host that always
+ * answers 200 is slower, not wrong.
+ *
+ * Not specific to one host: it talks to `NotesPollingAPI` below,
+ * which any backend with a comment thread per entry can satisfy.
+ *
+ * @module notesPolling
+ */
+
+import { commentsToNotes } from './notesFormat';
+function noop() {
+  /* nothing to unwatch */
+}
+
+// Redux action types
+export const NOTES_POLLING_START = 'NOTES_POLLING_START';
+export const NOTES_POLLING_STOP = 'NOTES_POLLING_STOP';
+export const NOTES_POLLING_UPDATE = 'NOTES_POLLING_UPDATE';
+export const NOTES_CHANGE_DETECTED = 'NOTES_CHANGE_DETECTED';
+export class NotesPollingManager {
+  currentWatch = null;
+  currentIssueKey = null;
+  pollingInterval = 15000;
+  intervalId = null;
+  isDocumentVisible = true;
+  isPolling = false;
+  pendingRetryTimeout = null;
+  cancelPendingRetry = null;
+  pendingIssueKey = null;
+  watchGeneration = 0;
+  constructor(api, pollingInterval = 15000) {
+    this.api = api;
+    this.pollingInterval = pollingInterval;
+    this.setupVisibilityListener();
+  }
+
+  /**
+   * Setup Page Visibility API listener
+   * Pauses polling when tab is hidden
+   */
+  setupVisibilityListener() {
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', this.handleVisibilityChange);
+    }
+  }
+  handleVisibilityChange = () => {
+    this.isDocumentVisible = !document.hidden;
+    if (this.isDocumentVisible) {
+      this.startPolling();
+      this.checkAllIssuesNow();
+    } else {
+      this.stopPolling();
+    }
+  };
+
+  /**
+   * Start watching an issue for changes
+   * This will automatically stop watching any previously watched issue
+   *
+   * @param issueNumber - GitHub issue number
+   * @param collection - Collection name
+   * @param slug - Entry slug
+   * @returns Function to stop watching
+   */
+  async watchIssue(issueNumber, collection, slug, callbacks, initialState = null) {
+    const issueKey = this.getIssueKey(collection, slug);
+
+    // STOP ANY EXISTING WATCH FIRST
+    this.stopCurrentWatch();
+    const generation = this.watchGeneration;
+
+    // Get initial state if not provided
+    if (!initialState) {
+      try {
+        initialState = await this.api.getIssueState(issueNumber);
+      } catch (error) {
+        console.error('[DecapNotes Polling] Failed to get initial state:', error);
+      }
+      if (generation !== this.watchGeneration) {
+        return noop;
+      }
+    }
+    const watch = {
+      issueNumber,
+      collection,
+      slug,
+      etag: null,
+      lastState: initialState,
+      onUpdate: callbacks.onUpdate,
+      onChange: callbacks.onChange,
+      prepareNotes: callbacks.prepareNotes,
+      retryCount: 0,
+      maxRetries: 5
+    };
+    this.currentWatch = watch;
+    this.currentIssueKey = issueKey;
+
+    // Start polling if not already running
+    if (!this.intervalId && this.isDocumentVisible) {
+      this.startPolling();
+    }
+
+    // Do an immediate check
+    this.checkCurrentIssue();
+
+    // Return unwatch function
+    return () => {
+      if (this.currentWatch === watch) {
+        this.stopCurrentWatch();
+      }
+    };
+  }
+
+  /**
+   * Watch issue with retry logic for newly created issues
+   */
+  async watchIssueWithRetry(collection, slug, callbacks, maxRetries = 5, retryDelay = 2000) {
+    const issueKey = this.getIssueKey(collection, slug);
+
+    // STOP ANY EXISTING WATCH FIRST
+    this.stopCurrentWatch();
+    const generation = this.watchGeneration;
+    this.pendingIssueKey = issueKey;
+    const isSuperseded = () => generation !== this.watchGeneration;
+    const attemptWatch = async attempt => {
+      let lookupError;
+      let issue = null;
+      try {
+        issue = await this.api.findEntryIssue(collection, slug);
+      } catch (error) {
+        console.error(`[DecapNotes Polling] Error finding issue for ${issueKey}:`, error);
+        lookupError = error;
+      }
+      if (isSuperseded()) {
+        return noop;
+      }
+      if (issue) {
+        this.pendingIssueKey = null;
+        return this.watchIssue(issue.number, collection, slug, callbacks);
+      }
+      if (attempt < maxRetries) {
+        const elapsed = await this.waitForRetry(retryDelay);
+        return elapsed && !isSuperseded() ? attemptWatch(attempt + 1) : noop;
+      }
+      this.pendingIssueKey = null;
+      if (lookupError) {
+        throw lookupError;
+      }
+      console.log(`[DecapNotes Polling] No issue found for ${issueKey} after ${maxRetries} attempts. This is expected if there are no notes for this entry yet.`);
+      return noop;
+    };
+    return attemptWatch(1);
+  }
+  waitForRetry(delay) {
+    return new Promise(resolve => {
+      this.cancelPendingRetry = () => resolve(false);
+      this.pendingRetryTimeout = setTimeout(() => {
+        this.pendingRetryTimeout = null;
+        this.cancelPendingRetry = null;
+        resolve(true);
+      }, delay);
+    });
+  }
+  clearPendingRetry() {
+    if (this.pendingRetryTimeout) {
+      clearTimeout(this.pendingRetryTimeout);
+      this.pendingRetryTimeout = null;
+    }
+    this.cancelPendingRetry?.();
+    this.cancelPendingRetry = null;
+    this.pendingIssueKey = null;
+  }
+
+  /**
+   * Stop watching an entry, including a pending retry
+   */
+  stopWatching(collection, slug) {
+    const issueKey = this.getIssueKey(collection, slug);
+    if (this.currentIssueKey === issueKey || this.pendingIssueKey === issueKey) {
+      this.stopCurrentWatch();
+    }
+  }
+
+  /**
+   * Stop watching the current issue - complete cleanup
+   */
+  stopCurrentWatch() {
+    this.watchGeneration += 1;
+    this.clearPendingRetry();
+    if (!this.currentWatch) {
+      return;
+    }
+
+    // Clear current watch
+    this.currentWatch = null;
+    this.currentIssueKey = null;
+
+    // Stop polling since there's nothing to watch
+    this.stopPolling();
+  }
+
+  /**
+   * Start the polling loop
+   */
+  startPolling() {
+    if (this.intervalId || !this.isDocumentVisible || !this.currentWatch) return;
+    console.log(`[DecapNotes Polling] Starting polling loop (${this.pollingInterval}ms interval) for ${this.currentIssueKey}`);
+    this.intervalId = setInterval(() => {
+      this.pollAllIssues();
+    }, this.pollingInterval);
+  }
+
+  /**
+   * Stop the polling loop
+   */
+  stopPolling() {
+    if (this.intervalId) {
+      console.log('[DecapNotes Polling] Stopping polling loop');
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+
+  /**
+   * Poll current watched issue
+   */
+  async pollAllIssues() {
+    await this.checkCurrentIssue();
+  }
+
+  /**
+   * Check current issue for changes using ETag
+   */
+  async checkCurrentIssue() {
+    if (!this.currentWatch) {
+      return;
+    }
+    if (this.isPolling) {
+      return;
+    }
+    this.isPolling = true;
+    try {
+      const watch = this.currentWatch;
+      const response = await this.api.getIssueWithETag(watch.issueNumber, watch.etag);
+      if (response.status === 304) {
+        return;
+      }
+      if (this.currentWatch !== watch) {
+        return;
+      }
+      if (response.status === 200) {
+        const newState = response.data;
+
+        // Detect specific changes
+        const changes = this.detectChanges(watch.lastState, newState);
+        if (changes.length > 0) {
+          // Convert comments to notes
+          let newNotes = commentsToNotes(newState.comments, newState.html_url, this.api.parseCommentToNote && (comment => this.api.parseCommentToNote(comment)));
+          if (watch.prepareNotes) {
+            newNotes = await watch.prepareNotes(newNotes);
+            if (this.currentWatch !== watch) {
+              return;
+            }
+          }
+          if (watch.onUpdate) {
+            watch.onUpdate(newNotes, changes);
+          }
+          if (watch.onChange) {
+            changes.forEach(change => {
+              watch.onChange(change);
+            });
+          }
+        }
+
+        // Update ETag and stored state
+        watch.etag = response.etag || null;
+        watch.lastState = newState;
+      }
+    } catch (error) {
+      console.error(`[DecapNotes Polling] Error checking ${this.currentIssueKey}:`, error);
+    } finally {
+      this.isPolling = false;
+    }
+  }
+
+  /**
+   * Immediately check current issue
+   */
+  async checkAllIssuesNow() {
+    await this.checkCurrentIssue();
+  }
+
+  /**
+   * Manually trigger a check - only works if this is the current entry
+   */
+  async checkIssueNow(collection, slug) {
+    const issueKey = this.getIssueKey(collection, slug);
+    if (this.currentIssueKey !== issueKey) {
+      console.warn(`[DecapNotes Polling] Cannot check ${issueKey} - currently watching ${this.currentIssueKey}`);
+      return;
+    }
+    await this.checkCurrentIssue();
+  }
+
+  /**
+   * Detect what changed between two states
+   */
+  detectChanges(previous, current) {
+    if (!previous) {
+      return [];
+    }
+    const changes = [];
+
+    // New comments
+    const newComments = current.comments.filter(comment => !previous.comments.some(prev => prev.id === comment.id));
+    newComments.forEach(comment => {
+      changes.push({
+        type: 'comment_added',
+        data: comment,
+        timestamp: comment.created_at
+      });
+    });
+
+    // Updated comments
+    current.comments.forEach(comment => {
+      const prevComment = previous.comments.find(prev => prev.id === comment.id);
+      if (prevComment && prevComment.updated_at !== comment.updated_at) {
+        changes.push({
+          type: 'comment_updated',
+          data: comment,
+          previousData: prevComment,
+          timestamp: comment.updated_at
+        });
+      }
+    });
+
+    // Deleted comments
+    const deletedComments = previous.comments.filter(prevComment => !current.comments.some(comment => comment.id === prevComment.id));
+    deletedComments.forEach(comment => {
+      changes.push({
+        type: 'comment_deleted',
+        data: comment,
+        timestamp: new Date().toISOString()
+      });
+    });
+
+    // Issue state changed
+    if (previous.state !== current.state) {
+      changes.push({
+        type: 'issue_state_changed',
+        data: {
+          from: previous.state,
+          to: current.state
+        },
+        timestamp: current.updated_at
+      });
+    }
+
+    // Labels changed
+    if (this.hasLabelsChanged(previous.labels, current.labels)) {
+      changes.push({
+        type: 'issue_labels_changed',
+        data: {
+          from: previous.labels,
+          to: current.labels
+        },
+        timestamp: current.updated_at
+      });
+    }
+    return changes;
+  }
+
+  /**
+   * Check if labels changed
+   */
+  hasLabelsChanged(previous, current) {
+    if (previous.length !== current.length) return true;
+    const prevNames = previous.map(l => l.name).sort();
+    const currNames = current.map(l => l.name).sort();
+    return prevNames.join(',') !== currNames.join(',');
+  }
+
+  /**
+   * Get issue key for storage
+   */
+  getIssueKey(collection, slug) {
+    return `${collection}/${slug}`;
+  }
+
+  /**
+   * Get polling status
+   */
+  getStatus() {
+    return {
+      isPolling: this.intervalId !== null,
+      currentWatch: this.currentIssueKey,
+      watchedCount: this.currentWatch ? 1 : 0,
+      pollingInterval: this.pollingInterval,
+      isDocumentVisible: this.isDocumentVisible,
+      hasPendingRetry: this.pendingRetryTimeout !== null
+    };
+  }
+
+  /**
+   * Clean up - stop all polling
+   */
+  destroy() {
+    console.log('[DecapNotes Polling] Destroying polling manager');
+
+    // Stop current watch
+    this.stopCurrentWatch();
+    if (typeof document !== 'undefined') {
+      document.removeEventListener('visibilitychange', this.handleVisibilityChange);
+    }
+  }
+}
+export default NotesPollingManager;

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "decap-cms-lib-util",
   "description": "Shared utilities for Decap CMS.",
-  "version": "3.8.1",
-  "repository": "https://github.com/decaporg/decap-cms/tree/main/packages/decap-cms-lib-util",
+  "version": "3.8.3",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/decaporg/decap-cms/tree/main/packages/decap-cms-lib-util"
+  },
   "bugs": "https://github.com/decaporg/decap-cms/issues",
   "module": "dist/esm/index.js",
   "main": "dist/decap-cms-lib-util.js",
@@ -14,23 +17,22 @@
     "decap-cms"
   ],
   "sideEffects": false,
-  "scripts": {
-    "develop": "pnpm run build:esm --watch",
-    "build": "cross-env NODE_ENV=production webpack",
-    "build:esm": "cross-env NODE_ENV=esm babel src --out-dir dist/esm --ignore \"**/__tests__\" --root-mode upward --extensions \".js,.jsx,.ts,.tsx\""
-  },
   "dependencies": {
-    "js-sha256": "catalog:",
-    "localforage": "catalog:",
-    "semaphore": "catalog:"
+    "js-sha256": "^0.9.0",
+    "localforage": "^1.7.3",
+    "semaphore": "^1.1.0"
   },
   "peerDependencies": {
-    "common-tags": "catalog:",
-    "immutable": "catalog:",
-    "lodash": "catalog:"
+    "common-tags": "1.8.2",
+    "immutable": "^4.3.9",
+    "lodash": "^4.17.11"
   },
   "devDependencies": {
-    "common-tags": "catalog:"
+    "common-tags": "1.8.2"
   },
-  "gitHead": "570c3e7fbc399c455729964b9b5fdec079846393"
-}
+  "scripts": {
+    "develop": "pnpm run build:esm --watch",
+    "build": "cross-env NODE_ENV=production webpack",
+    "build:esm": "cross-env NODE_ENV=esm babel src --out-dir dist/esm --ignore \"**/__tests__\" --root-mode upward --extensions \".js,.jsx,.ts,.tsx\""
+  }
+}

package/LICENSE

@@ -1,22 +0,0 @@
-Copyright (c) 2016 Netlify <decap@p-m.si>
-
-MIT License
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.