@noteplanco/noteplan-mcp 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (155) hide show
  1. package/README.md +257 -0
  2. package/dist/index.d.ts +3 -0
  3. package/dist/index.d.ts.map +1 -0
  4. package/dist/index.js +8 -0
  5. package/dist/index.js.map +1 -0
  6. package/dist/noteplan/embeddings.d.ts +170 -0
  7. package/dist/noteplan/embeddings.d.ts.map +1 -0
  8. package/dist/noteplan/embeddings.js +684 -0
  9. package/dist/noteplan/embeddings.js.map +1 -0
  10. package/dist/noteplan/file-reader.d.ts +77 -0
  11. package/dist/noteplan/file-reader.d.ts.map +1 -0
  12. package/dist/noteplan/file-reader.js +488 -0
  13. package/dist/noteplan/file-reader.js.map +1 -0
  14. package/dist/noteplan/file-writer.d.ts +108 -0
  15. package/dist/noteplan/file-writer.d.ts.map +1 -0
  16. package/dist/noteplan/file-writer.js +621 -0
  17. package/dist/noteplan/file-writer.js.map +1 -0
  18. package/dist/noteplan/filter-store.d.ts +28 -0
  19. package/dist/noteplan/filter-store.d.ts.map +1 -0
  20. package/dist/noteplan/filter-store.js +180 -0
  21. package/dist/noteplan/filter-store.js.map +1 -0
  22. package/dist/noteplan/frontmatter-parser.d.ts +45 -0
  23. package/dist/noteplan/frontmatter-parser.d.ts.map +1 -0
  24. package/dist/noteplan/frontmatter-parser.js +259 -0
  25. package/dist/noteplan/frontmatter-parser.js.map +1 -0
  26. package/dist/noteplan/fuzzy-search.d.ts +7 -0
  27. package/dist/noteplan/fuzzy-search.d.ts.map +1 -0
  28. package/dist/noteplan/fuzzy-search.js +66 -0
  29. package/dist/noteplan/fuzzy-search.js.map +1 -0
  30. package/dist/noteplan/markdown-parser.d.ts +87 -0
  31. package/dist/noteplan/markdown-parser.d.ts.map +1 -0
  32. package/dist/noteplan/markdown-parser.js +519 -0
  33. package/dist/noteplan/markdown-parser.js.map +1 -0
  34. package/dist/noteplan/preferences.d.ts +44 -0
  35. package/dist/noteplan/preferences.d.ts.map +1 -0
  36. package/dist/noteplan/preferences.js +156 -0
  37. package/dist/noteplan/preferences.js.map +1 -0
  38. package/dist/noteplan/ripgrep-search.d.ts +29 -0
  39. package/dist/noteplan/ripgrep-search.d.ts.map +1 -0
  40. package/dist/noteplan/ripgrep-search.js +110 -0
  41. package/dist/noteplan/ripgrep-search.js.map +1 -0
  42. package/dist/noteplan/sqlite-reader.d.ts +77 -0
  43. package/dist/noteplan/sqlite-reader.d.ts.map +1 -0
  44. package/dist/noteplan/sqlite-reader.js +605 -0
  45. package/dist/noteplan/sqlite-reader.js.map +1 -0
  46. package/dist/noteplan/sqlite-writer.d.ts +63 -0
  47. package/dist/noteplan/sqlite-writer.d.ts.map +1 -0
  48. package/dist/noteplan/sqlite-writer.js +574 -0
  49. package/dist/noteplan/sqlite-writer.js.map +1 -0
  50. package/dist/noteplan/types.d.ts +97 -0
  51. package/dist/noteplan/types.d.ts.map +1 -0
  52. package/dist/noteplan/types.js +33 -0
  53. package/dist/noteplan/types.js.map +1 -0
  54. package/dist/noteplan/unified-store.d.ts +289 -0
  55. package/dist/noteplan/unified-store.d.ts.map +1 -0
  56. package/dist/noteplan/unified-store.js +1308 -0
  57. package/dist/noteplan/unified-store.js.map +1 -0
  58. package/dist/server.d.ts +4 -0
  59. package/dist/server.d.ts.map +1 -0
  60. package/dist/server.js +2468 -0
  61. package/dist/server.js.map +1 -0
  62. package/dist/tools/calendar.d.ts +311 -0
  63. package/dist/tools/calendar.d.ts.map +1 -0
  64. package/dist/tools/calendar.js +504 -0
  65. package/dist/tools/calendar.js.map +1 -0
  66. package/dist/tools/embeddings.d.ts +244 -0
  67. package/dist/tools/embeddings.d.ts.map +1 -0
  68. package/dist/tools/embeddings.js +226 -0
  69. package/dist/tools/embeddings.js.map +1 -0
  70. package/dist/tools/events.d.ts +176 -0
  71. package/dist/tools/events.d.ts.map +1 -0
  72. package/dist/tools/events.js +326 -0
  73. package/dist/tools/events.js.map +1 -0
  74. package/dist/tools/filters.d.ts +205 -0
  75. package/dist/tools/filters.d.ts.map +1 -0
  76. package/dist/tools/filters.js +347 -0
  77. package/dist/tools/filters.js.map +1 -0
  78. package/dist/tools/memory.d.ts +6 -0
  79. package/dist/tools/memory.d.ts.map +1 -0
  80. package/dist/tools/memory.js +161 -0
  81. package/dist/tools/memory.js.map +1 -0
  82. package/dist/tools/notes.d.ts +1221 -0
  83. package/dist/tools/notes.d.ts.map +1 -0
  84. package/dist/tools/notes.js +1868 -0
  85. package/dist/tools/notes.js.map +1 -0
  86. package/dist/tools/plugins.d.ts +140 -0
  87. package/dist/tools/plugins.d.ts.map +1 -0
  88. package/dist/tools/plugins.js +782 -0
  89. package/dist/tools/plugins.js.map +1 -0
  90. package/dist/tools/reminders.d.ts +207 -0
  91. package/dist/tools/reminders.d.ts.map +1 -0
  92. package/dist/tools/reminders.js +323 -0
  93. package/dist/tools/reminders.js.map +1 -0
  94. package/dist/tools/search.d.ts +58 -0
  95. package/dist/tools/search.d.ts.map +1 -0
  96. package/dist/tools/search.js +373 -0
  97. package/dist/tools/search.js.map +1 -0
  98. package/dist/tools/spaces.d.ts +484 -0
  99. package/dist/tools/spaces.d.ts.map +1 -0
  100. package/dist/tools/spaces.js +870 -0
  101. package/dist/tools/spaces.js.map +1 -0
  102. package/dist/tools/tasks.d.ts +313 -0
  103. package/dist/tools/tasks.d.ts.map +1 -0
  104. package/dist/tools/tasks.js +690 -0
  105. package/dist/tools/tasks.js.map +1 -0
  106. package/dist/tools/themes.d.ts +91 -0
  107. package/dist/tools/themes.d.ts.map +1 -0
  108. package/dist/tools/themes.js +294 -0
  109. package/dist/tools/themes.js.map +1 -0
  110. package/dist/tools/ui.d.ts +89 -0
  111. package/dist/tools/ui.d.ts.map +1 -0
  112. package/dist/tools/ui.js +137 -0
  113. package/dist/tools/ui.js.map +1 -0
  114. package/dist/utils/applescript.d.ts +5 -0
  115. package/dist/utils/applescript.d.ts.map +1 -0
  116. package/dist/utils/applescript.js +27 -0
  117. package/dist/utils/applescript.js.map +1 -0
  118. package/dist/utils/confirmation-tokens.d.ts +19 -0
  119. package/dist/utils/confirmation-tokens.d.ts.map +1 -0
  120. package/dist/utils/confirmation-tokens.js +58 -0
  121. package/dist/utils/confirmation-tokens.js.map +1 -0
  122. package/dist/utils/date-filters.d.ts +15 -0
  123. package/dist/utils/date-filters.d.ts.map +1 -0
  124. package/dist/utils/date-filters.js +129 -0
  125. package/dist/utils/date-filters.js.map +1 -0
  126. package/dist/utils/date-utils.d.ts +113 -0
  127. package/dist/utils/date-utils.d.ts.map +1 -0
  128. package/dist/utils/date-utils.js +341 -0
  129. package/dist/utils/date-utils.js.map +1 -0
  130. package/dist/utils/folder-matcher.d.ts +14 -0
  131. package/dist/utils/folder-matcher.d.ts.map +1 -0
  132. package/dist/utils/folder-matcher.js +191 -0
  133. package/dist/utils/folder-matcher.js.map +1 -0
  134. package/dist/utils/version.d.ts +10 -0
  135. package/dist/utils/version.d.ts.map +1 -0
  136. package/dist/utils/version.js +88 -0
  137. package/dist/utils/version.js.map +1 -0
  138. package/docs/plugin-api/Calendar.md +448 -0
  139. package/docs/plugin-api/CalendarItem.md +198 -0
  140. package/docs/plugin-api/Clipboard.md +101 -0
  141. package/docs/plugin-api/CommandBar.md +251 -0
  142. package/docs/plugin-api/DataStore.md +700 -0
  143. package/docs/plugin-api/Editor.md +982 -0
  144. package/docs/plugin-api/HTMLView.md +337 -0
  145. package/docs/plugin-api/NoteObject.md +588 -0
  146. package/docs/plugin-api/NotePlan.md +398 -0
  147. package/docs/plugin-api/ParagraphObject.md +242 -0
  148. package/docs/plugin-api/RangeObject.md +56 -0
  149. package/docs/plugin-api/getting-started.md +545 -0
  150. package/docs/plugin-api/plugin-api-condensed.md +526 -0
  151. package/docs/plugin-api/plugin.json +26 -0
  152. package/docs/plugin-api/script.js +542 -0
  153. package/package.json +60 -0
  154. package/scripts/calendar-helper +0 -0
  155. package/scripts/reminders-helper +0 -0
package/docs/plugin-api/plugin-api-condensed.md ADDED
@@ -0,0 +1,526 @@
1
+ # NotePlan Plugin API — Condensed Reference
2
+
3
+ Complete API reference for building NotePlan plugins. All signatures, types, and essential patterns in one document.
4
+
5
+ ---
6
+
7
+ ## 1. Plugin Structure & Quick Start
8
+
9
+ A plugin = folder in `Plugins/` with two files:
10
+
11
+ ```
12
+ np.myplugin/
13
+ ├── plugin.json # Manifest: metadata + command mappings
14
+ └── script.js # JavaScript functions
15
+ ```
16
+
17
+ ### plugin.json format
18
+
19
+ ```json
20
+ {
21
+ "plugin.id": "np.myplugin",
22
+ "plugin.name": "My Plugin",
23
+ "plugin.description": "What it does",
24
+ "plugin.author": "@you",
25
+ "plugin.version": "1.0.0",
26
+ "plugin.script": "script.js",
27
+ "plugin.icon": "puzzle-piece",
28
+ "plugin.commands": [
29
+ {
30
+ "name": "myCommand",
31
+ "description": "What this command does",
32
+ "jsFunction": "myCommand",
33
+ "sidebarView": {
34
+ "title": "My View",
35
+ "icon": "calendar",
36
+ "iconColor": "blue-500"
37
+ }
38
+ }
39
+ ]
40
+ }
41
+ ```
42
+
43
+ ### script.js pattern
44
+
45
+ ```javascript
46
+ // Functions are assigned to globalThis for MCP-generated plugins,
47
+ // or defined at top level for manually-created plugins.
48
+ globalThis.myCommand = async function() {
49
+ const html = `<html>...</html>`;
50
+ await HTMLView.showInMainWindow(html, "My View", { id: "main:np.myplugin:My View" });
51
+ };
52
+ ```
53
+
54
+ ### API Availability Matrix
55
+
56
+ | API | Native (script.js) | HTML WebView |
57
+ |-----|:------------------:|:------------:|
58
+ | Editor | Yes | Via jsBridge only |
59
+ | DataStore | Yes | Via jsBridge only |
60
+ | Calendar | Yes | **Yes** (direct) |
61
+ | CommandBar | Yes | Via jsBridge only |
62
+ | NotePlan | Yes | Via jsBridge only |
63
+ | HTMLView | Yes | No |
64
+ | Clipboard | Yes | Via jsBridge only |
65
+ | fetch() | No | **Yes** (native, no CORS) |
66
+
67
+ ---
68
+
69
+ ## 2. HTMLView
70
+
71
+ ### Methods
72
+
73
+ - `.showInMainWindow(html, title, options?)` → `Promise` — Show in main content area (preferred). Options: `{ splitView, id/customId, icon, iconColor, autoTopPadding, showReloadButton, reloadPluginID, reloadCommandName, reloadCommandArgs }`
74
+ - `.showWindow(html, title, width?, height?)` → `Promise(Window)` — Non-modal floating window
75
+ - `.showWindowWithOptions(html, title, options?)` → `Promise(Window)` — Window with `{ x, y, width, height, customId, shouldFocus }`
76
+ - `.showSheet(html, width?, height?)` — Modal sheet
77
+ - `.runJavaScript(code, customId?)` → `Promise` — Execute JS in an open HTML window
78
+ - `.windowRect` `{get/set}` `{x, y, width, height}` — Window position/size (macOS)
79
+
80
+ ### JS Bridge (HTML → Plugin API)
81
+
82
+ Call non-Calendar APIs from HTML views:
83
+
84
+ ```javascript
85
+ // In script.js — stringify the API call:
86
+ const apiCode = JSON.stringify(`(function() { return Editor.filename; })()`);
87
+
88
+ // In HTML <script>:
89
+ window.webkit.messageHandlers.jsBridge.postMessage({
90
+ code: apiCode, // Stringified JS to run in plugin context
91
+ onHandle: "callback", // Name of callback function in HTML
92
+ id: "1" // Optional tracking ID
93
+ });
94
+
95
+ function callback(result, id) {
96
+ // result = return value from the code
97
+ }
98
+ ```
99
+
100
+ ### fetch() in HTML WebViews
101
+
102
+ ```javascript
103
+ const response = await fetch('https://api.example.com/data');
104
+ const data = await response.json();
105
+ // Standard Fetch API — response.ok, response.status, response.text(), etc.
106
+ // HTTPS only. 30s timeout. No CORS restrictions.
107
+ ```
108
+
109
+ ### Calendar API in HTML (direct access)
110
+
111
+ ```javascript
112
+ // Check availability, then use:
113
+ if (typeof Calendar !== 'undefined') {
114
+ const events = await Calendar.eventsToday('');
115
+ } else {
116
+ window.addEventListener('notePlanBridgeReady', loadEvents);
117
+ }
118
+ ```
119
+
120
+ ---
121
+
122
+ ## 3. Editor
123
+
124
+ ### Window Management
125
+
126
+ - `.id` `{get}` `String` — Unique editor ID
127
+ - `.customId` `{get/set}` `String` — Developer-assigned ID
128
+ - `.windowType` `{get}` `"main"|"split"|"floating"|"unsupported"` — Editor context
129
+ - `.focus()` — Bring window to front
130
+ - `.close()` — Close split/window
131
+ - `.windowRect` `{get/set}` `{x, y, width, height}` — Window frame (macOS, v3.9.1)
132
+
133
+ ### Properties
134
+
135
+ - `.note` `{get}` `NoteObject` — Current note object
136
+ - `.content` `{get/set}` `String` — Raw markdown (includes frontmatter)
137
+ - `.title` `{get}` `String` — First line
138
+ - `.type` `{get}` `"Notes"|"Calendar"` — Note type
139
+ - `.filename` `{get}` `String` — Relative path including folder
140
+ - `.paragraphs` `{get/set}` `[ParagraphObject]` — All paragraphs (includes frontmatter)
141
+ - `.selectedLinesText` `{get}` `[String]` — Selected lines (ignores frontmatter)
142
+ - `.selectedParagraphs` `{get}` `[ParagraphObject]` — Selected paragraphs
143
+ - `.selection` `{get}` `RangeObject` — Raw selection range
144
+ - `.renderedSelection` `{get}` `RangeObject` — Rendered selection (hides markdown)
145
+ - `.selectedText` `{get}` `String` — Selected text
146
+ - `.frontmatterAttributes` `{get/set}` `{[key]: string}` — Frontmatter key-value pairs (v3.16.3)
147
+ - `.frontmatterTypes` `{get}` `[String]` — Note types from frontmatter (v3.16.3)
148
+ - `.availableThemes` `{get}` `[{name, mode, filename, values}]` — All themes (v3.6.2)
149
+ - `.currentTheme` `{get}` `{name, mode, filename, values}` — Active theme (v3.6.2)
150
+ - `.currentSystemMode` `{get}` `"dark"|"light"` — System appearance (v3.6.2)
151
+ - `.skipNextRepeatDeletionCheck` `{set}` `Boolean` — Skip @repeat deletion dialog
152
+
153
+ ### Text & Selection Functions
154
+
155
+ - `.selectAll()`
156
+ - `.copySelection()`
157
+ - `.pasteClipboard()`
158
+ - `.insertTextAtCharacterIndex(text, index)`
159
+ - `.replaceTextInCharacterRange(text, location, length)`
160
+ - `.insertTextAtCursor(text)`
161
+ - `.replaceSelectionWithText(text)`
162
+ - `.select(start, length)` — Raw select
163
+ - `.renderedSelect(start, length)` — Rendered select
164
+ - `.highlight(paragraph)` — Scroll to paragraph
165
+ - `.highlightByRange(range, ignoreFrontmatter?)` — Scroll to range (v3.18)
166
+ - `.highlightByIndex(index, length, ignoreFrontmatter?)` — Scroll to index (v3.0.23)
167
+ - `.printNote(withBacklinksAndEvents)` — Print dialog (macOS, v3.4)
168
+
169
+ ### Frontmatter Functions
170
+
171
+ - `.setFrontmatterAttribute(key, value)` — Set single attribute (v3.17)
172
+ - `.updateFrontmatterAttributes([{key, value}])` — Batch update (v3.18.1)
173
+
174
+ ### Open Note Functions (all return `Promise(Note?)`)
175
+
176
+ - `.openNoteByFilename(filename, newWindow?, highlightStart?, highlightEnd?, splitView?, createIfNeeded?, content?)`
177
+ - `.openNoteByTitle(title, newWindow?, highlightStart?, highlightEnd?, splitView?)`
178
+ - `.openNoteByTitleCaseInsensitive(title, newWindow?, caseSensitive?, highlightStart?, highlightEnd?, splitView?)`
179
+ - `.openNoteByDate(date, newWindow?, highlightStart?, highlightEnd?, splitView?, timeframe?, parent?)`
180
+ - `.openNoteByDateString(dateString, newWindow?, highlightStart?, highlightEnd?, splitView?)`
181
+ - `.openWeeklyNote(year, weeknumber, newWindow?, highlightStart?, highlightEnd?, splitView?)`
182
+
183
+ ### Paragraph Functions
184
+
185
+ Note: After insert/remove operations that change line indices, re-fetch paragraphs.
186
+
187
+ - `.paragraphRangeAtCharacterIndex(pos)` → `RangeObject`
188
+ - `.insertParagraph(content, lineIndex, type)` — Types: `"open"|"done"|"scheduled"|"cancelled"|"quote"|"title"|"list"|"text"|"empty"`
189
+ - `.insertParagraphAtCursor(content, type, indents)`
190
+ - `.insertTodo(content, lineIndex)`
191
+ - `.insertCompletedTodo(content, lineIndex)`
192
+ - `.insertCancelledTodo(content, lineIndex)`
193
+ - `.insertScheduledTodo(content, lineIndex, date?)`
194
+ - `.insertQuote(content, lineIndex)`
195
+ - `.insertList(content, lineIndex)`
196
+ - `.insertHeading(content, lineIndex, level)`
197
+ - `.appendTodo(content)` / `.prependTodo(content)`
198
+ - `.appendParagraph(content, type)` / `.prependParagraph(content, type)`
199
+ - `.addTodoBelowHeadingTitle(content, headingTitle, shouldAppend, shouldCreate)`
200
+ - `.addParagraphBelowHeadingTitle(content, paragraphType, headingTitle, shouldAppend, shouldCreate)`
201
+ - `.appendTodoBelowHeadingLineIndex(content, headingLineIndex)`
202
+ - `.appendParagraphBelowHeadingLineIndex(content, paragraphType, headingLineIndex)`
203
+ - `.insertTodoAfterParagraph(content, paragraph)` / `.insertTodoBeforeParagraph(content, paragraph)`
204
+ - `.insertParagraphAfterParagraph(content, paragraph, type)` / `.insertParagraphBeforeParagraph(content, paragraph, type)`
205
+ - `.removeParagraphAtIndex(lineIndex)` / `.removeParagraph(paragraph)` / `.removeParagraphs([paragraph])`
206
+ - `.updateParagraph(paragraph)` / `.updateParagraphs([paragraph])`
207
+ - `.addBlockID(paragraph)` — Generate + assign unique block ID
208
+
209
+ ### Theme Functions
210
+
211
+ - `.setTheme(filename)` — Apply theme temporarily (v3.6.2)
212
+ - `.saveDefaultTheme(filename, mode)` — Save default for mode (v3.6.2)
213
+ - `.addTheme(stringifiedJSON, filename)` → `Boolean` — Add custom theme (v3.1)
214
+ - `.save(timeout?)` → `Promise` — Flush editor to file (v3.9.3)
215
+
216
+ ---
217
+
218
+ ## 4. DataStore
219
+
220
+ ### Properties
221
+
222
+ - `.defaultFileExtension` `{get}` `String` — e.g. "txt" or "md"
223
+ - `.folders` `{get}` `[String]` — All folders including "/" root
224
+ - `.calendarNotes` `{get}` `[NoteObject]` — All calendar notes
225
+ - `.projectNotes` `{get}` `[NoteObject]` — All project notes (excl. trash)
226
+ - `.teamspaces` `{get}` `[NoteObject]` — Teamspaces as note objects
227
+ - `.hashtags` `{get}` `[String]` — All cached #hashtags
228
+ - `.mentions` `{get}` `[String]` — All cached @mentions
229
+ - `.filters` `{get}` `[String]` — Filter names (v3.6)
230
+ - `.settings` `{get/set}` `Object?` — Plugin settings from settings.json (v3.3.2)
231
+
232
+ ### Note Lookup
233
+
234
+ - `.calendarNoteByDate(date, timeframe?, parent?)` → `NoteObject` — timeframe: "day"|"week"|"month"|"quarter"|"year"
235
+ - `.calendarNoteByDateString(dateString, parent?)` → `NoteObject` — Formats: "YYYYMMDD", "YYYY-Wwn", "YYYY-Qq", "YYYY-MM", "YYYY"
236
+ - `.projectNoteByTitle(title, caseInsensitive?, searchAllFolders?)` → `[NoteObject]`
237
+ - `.projectNoteByTitleCaseInsensitive(title)` → `[NoteObject]`
238
+ - `.projectNoteByFilename(filename)` → `NoteObject`
239
+ - `.noteByFilename(filename, type, parent?)` → `NoteObject` — type: "Notes"|"Calendar"
240
+ - `.referencedBlocks(paragraph?)` → `[ParagraphObject]` — Synced lines (v3.5.2)
241
+
242
+ ### Note Operations
243
+
244
+ - `.newNote(title, folder)` → `String` (filename)
245
+ - `.newNoteWithContent(content, folder, filename?)` → `String` (filename, v3.5)
246
+ - `.moveNote(filename, folder, type?)` → `String` (filename)
247
+ - `.trashNote(filename)` → `Boolean` (v3.18.2)
248
+ - `.createFolder(folderPath)` → `Boolean` (v3.8)
249
+ - `.updateCache(note, shouldUpdateTags)` → `NoteObject` (v3.7.1)
250
+
251
+ ### Preferences
252
+
253
+ - `.preference(key)` → `String?` — Keys: themeLight, themeDark, fontDelta, firstDayOfWeek, isAsteriskTodo, isDashTodo, defaultTodoCharacter, fontSize, fontFamily, isRenderingMarkdown, etc.
254
+ - `.setPreference(key, value)` — Save preference (v3.1)
255
+
256
+ ### Data Storage
257
+
258
+ - `.saveJSON(object, filename?)` → `Boolean` — Save to `Plugins/data/[plugin-id]/`
259
+ - `.loadJSON(filename?)` → `Object?` — Load from data folder
260
+ - `.saveData(data, filename, saveAsString)` → `Boolean` (v3.2)
261
+ - `.loadData(filename, loadAsString)` → `String?` (v3.2)
262
+ - `.fileExists(filename)` → `Boolean` (v3.8.1)
263
+
264
+ ### Search
265
+
266
+ - `.search(keyword, types?, inFolders?, notInFolders?, shouldLoadDatedTodos?)` → `Promise([ParagraphObject])` — Full search (v3.6)
267
+ - `.searchProjectNotes(keyword, inFolders?, notInFolders?)` → `Promise([ParagraphObject])`
268
+ - `.searchCalendarNotes(keyword, shouldLoadDatedTodos?)` → `Promise([ParagraphObject])`
269
+ - `.listOverdueTasks(keyword?)` → `Promise([ParagraphObject])` (v3.8.1)
270
+
271
+ ### Plugin Management
272
+
273
+ - `.listPlugins(showLoading, showHidden, skipMatchingLocalPlugins)` → `Promise` (v3.5.2)
274
+ - `.installedPlugins()` → `[PluginObject]` (v3.5.2)
275
+ - `.isPluginInstalledByID(pluginID)` → `Boolean` (v3.6)
276
+ - `.installPlugin(pluginObject, showLoading)` → `Promise` (v3.5.2)
277
+ - `.installOrUpdatePluginsByID([pluginID], showPrompt?, showProgress?, showFailed?)` → `Promise` (v3.6)
278
+ - `.invokePluginCommand(command, arguments)` → `Promise` (v3.5.2)
279
+ - `.invokePluginCommandByName(command, pluginId, arguments)` → `Promise` (v3.5.2)
280
+
281
+ ---
282
+
283
+ ## 5. NoteObject
284
+
285
+ ### Properties
286
+
287
+ - `.filename` `{get/set}` `String` — Relative path (set renames file, v3.6)
288
+ - `.resolvedFilename` `{get}` `String` — Human-readable path (teamspace-safe)
289
+ - `.isTeamspaceNote` `{get}` `Boolean`
290
+ - `.teamspaceTitle` `{get}` `String`
291
+ - `.teamspaceID` `{get}` `String`
292
+ - `.type` `{get}` `"Notes"|"Calendar"`
293
+ - `.title` `{get}` `String` — First line
294
+ - `.date` `{get}` `Date` — Calendar note date
295
+ - `.changedDate` `{get}` `Date`
296
+ - `.createdDate` `{get}` `Date`
297
+ - `.hashtags` `{get}` `[String]`
298
+ - `.mentions` `{get}` `[String]`
299
+ - `.content` `{get/set}` `String` — Raw text (writes to file immediately)
300
+ - `.contentWithAbsoluteAttachmentPaths` `{get}` `String`
301
+ - `.paragraphs` `{get/set}` `[ParagraphObject]`
302
+ - `.linkedItems` `{get}` `[ParagraphObject]` — Paragraphs linking to notes (v3.2)
303
+ - `.datedTodos` `{get}` `[ParagraphObject]` — Paragraphs linking to daily notes (v3.2)
304
+ - `.backlinks` `{get}` `[ParagraphObject]` — Notes linking to this note (v3.2)
305
+ - `.versions` `{get}` `[{content, date}]` — Version history (v3.7.2)
306
+ - `.frontmatterTypes` `{get}` `[String]` (v3.5)
307
+ - `.frontmatterAttributes` `{get}` `{[key]: string}`
308
+ - `.frontmatterAttributesArray` `{get}` `[{key, value}]` — Ordered
309
+ - `.publicRecordID` `{get}` `String?` — CloudKit ID (v3.9.1)
310
+ - `.conflictedVersion` `{get}` `{filename, url, content}?` (v3.9.3)
311
+
312
+ ### Methods
313
+
314
+ - `.rename(newFilename)` → `String` (v3.6.1)
315
+ - `.insertTextInCharacterIndex(text, index)`
316
+ - `.replaceTextAtCharacterRange(text, location, length)`
317
+ - `.setFrontmatterAttribute(key, value)` (v3.18.1)
318
+ - `.updateFrontmatterAttributes([{key, value}])` (v3.18.1)
319
+ - `.printNote(withBacklinksAndEvents)` (macOS, v3.4)
320
+ - `.publish()` → `Promise` / `.unpublish()` → `Promise` (v3.9.1)
321
+ - `.resolveConflictWithCurrentVersion()` / `.resolveConflictWithOtherVersion()` (v3.9.3)
322
+
323
+ ### Paragraph Methods (same as Editor)
324
+
325
+ - `.paragraphRangeAtCharacterIndex(pos)` → `RangeObject`
326
+ - `.insertParagraph(content, lineIndex, type)`
327
+ - `.insertTodo(content, lineIndex)` / `.insertCompletedTodo` / `.insertCancelledTodo` / `.insertScheduledTodo(content, lineIndex, date?)`
328
+ - `.insertQuote(content, lineIndex)` / `.insertList(content, lineIndex)` / `.insertHeading(content, lineIndex, level)`
329
+ - `.appendTodo(content)` / `.prependTodo(content)`
330
+ - `.appendParagraph(content, type)` / `.prependParagraph(content, type)`
331
+ - `.addTodoBelowHeadingTitle(content, headingTitle, shouldAppend, shouldCreate)`
332
+ - `.addParagraphBelowHeadingTitle(content, paragraphType, headingTitle, shouldAppend, shouldCreate)`
333
+ - `.appendTodoBelowHeadingLineIndex(content, headingLineIndex)`
334
+ - `.appendParagraphBelowHeadingLineIndex(content, paragraphType, headingLineIndex)`
335
+ - `.insertTodoAfterParagraph` / `.insertTodoBeforeParagraph` / `.insertParagraphAfterParagraph` / `.insertParagraphBeforeParagraph`
336
+ - `.removeParagraphAtIndex(lineIndex)` / `.removeParagraph(paragraph)` / `.removeParagraphs([paragraph])`
337
+ - `.updateParagraph(paragraph)` / `.updateParagraphs([paragraph])`
338
+ - `.addBlockID(paragraph)` / `.removeBlockID(paragraph)` (v3.5.2)
339
+
340
+ ---
341
+
342
+ ## 6. ParagraphObject
343
+
344
+ ### Properties
345
+
346
+ - `.type` `{get/set}` `"open"|"done"|"scheduled"|"cancelled"|"title"|"quote"|"list"|"empty"|"text"|"checklist"|"checklistDone"|"checklistCancelled"|"checklistScheduled"`
347
+ - `.content` `{get/set}` `String` — Text without markdown prefix or indents
348
+ - `.rawContent` `{get}` `String` — Full text including prefix and indents
349
+ - `.prefix` `{get}` `String` — Markdown prefix (e.g. "* [ ]")
350
+ - `.contentRange` `{get}` `RangeObject`
351
+ - `.lineIndex` `{get}` `Int`
352
+ - `.date` `{get}` `Date` — Scheduled date if any
353
+ - `.heading` `{get}` `String` — Parent heading text
354
+ - `.headingRange` `{get}` `RangeObject`
355
+ - `.headingLevel` `{get}` `Int` — 1-based (# = 1, ## = 2)
356
+ - `.isRecurring` `{get}` `Boolean` — Has @repeat(...)
357
+ - `.indents` `{get/set}` `Int`
358
+ - `.filename` `{get}` `String` — Source note filename
359
+ - `.noteType` `{get}` `String` — Source note type
360
+ - `.linkedNoteTitles` `{get}` `[String]` — [[links]] without brackets
361
+ - `.note` `{get}` `NoteObject?` — Parent note (v3.5.2)
362
+ - `.blockId` `{get}` `String?` — Block sync ID (v3.5.2)
363
+ - `.referencedBlocks` `{get}` `[ParagraphObject]` — Synced paragraphs (v3.5.2)
364
+
365
+ ### Methods
366
+
367
+ - `.duplicate()` → `ParagraphObject` — Deep copy
368
+ - `.children()` → `[ParagraphObject]?` — Indented children (v3.3)
369
+
370
+ ---
371
+
372
+ ## 7. CommandBar
373
+
374
+ - `.placeholder` `{get/set}` `String` — Input placeholder
375
+ - `.searchText` `{get}` `String` — Current input
376
+ - `.hide()` — Close command bar
377
+ - `.showOptions(options, placeholder, searchText?)` → `Promise(CommandBarResultObject)` — Options: `[String]` or `[{text, icon?, shortDescription?, color?, alpha?}]` (object format v3.18)
378
+ - `.showInput(placeholder, submitText, searchText?)` → `Promise(String)` — submitText supports `%@` variable
379
+ - `.showLoading(visible, text?, progress?)` — Loading indicator; progress: 0-1 for ring
380
+ - `.onAsyncThread()` → `Promise` — Switch to background thread
381
+ - `.onMainThread()` → `Promise` — Return to main thread
382
+ - `.prompt(title, message, buttons?)` → `Promise(Int)` — Button index (v3.3.2)
383
+ - `.textPrompt(title, message, defaultText?)` → `Promise(Bool|String)` — Text input dialog (v3.3.2)
384
+
385
+ ### CommandBarResultObject
386
+
387
+ - `.index` `Int` — Selected index
388
+ - `.value` `String` — Selected value
389
+ - `.keyModifiers` `[String]` — `"cmd"|"opt"|"shift"|"ctrl"` (v3.7)
390
+
391
+ ---
392
+
393
+ ## 8. Calendar + CalendarItem
394
+
395
+ ### Calendar Methods
396
+
397
+ - `.add(calendarItem)` → `CalendarItem` — Create event/reminder
398
+ - `.update(calendarItem)` → `Promise` — Update (needs ID)
399
+ - `.remove(calendarItem)` → `Promise` — Delete (needs ID)
400
+ - `.eventsBetween(startDate, endDate, filter?)` → `Promise([CalendarItem])`
401
+ - `.remindersBetween(startDate, endDate, filter?)` → `Promise([CalendarItem])`
402
+ - `.eventByID(id)` → `Promise(CalendarItem)`
403
+ - `.reminderByID(id)` → `Promise(CalendarItem)`
404
+ - `.eventsToday(filter?)` → `Promise([CalendarItem])`
405
+ - `.remindersToday(filter?)` → `Promise([CalendarItem])`
406
+ - `.remindersByLists(lists?)` → `Promise([CalendarItem])` (v3.5.2)
407
+ - `.parseDateText(text)` → `[DateRangeObject]` — Natural language dates
408
+ - `.dateFrom(year, month, day, hour, minute, second)` → `Date` — month is 1-based
409
+ - `.addUnitToDate(date, type, num)` → `Date`
410
+ - `.unitOf(date, type)` → `Int`
411
+ - `.timeAgoSinceNow(date)` → `String`
412
+ - `.unitsUntilNow(date, type)` → `Int` / `.unitsAgoFromNow(date, type)` → `Int` / `.unitsBetween(date1, date2, type)` → `Int`
413
+ - `.weekNumber(date)` → `Int` / `.weekYear(date)` → `Int` (v3.7)
414
+ - `.startOfWeek(date)` → `Date` / `.endOfWeek(date)` → `Date` (v3.7)
415
+ - `.dateUnits` `[String]` — `["year", "month", "day", "hour", "minute", "second"]`
416
+ - `.availableCalendarTitles(writeOnly?, enabledOnly?)` → `[String]` (v3.1)
417
+ - `.availableReminderListTitles()` → `[String]` (v3.1)
418
+ - `.availableCalendars(options?)` → `[{title, id, color, source, sourceType, isWritable, isEnabled, allowedEntityTypes}]` (v3.20)
419
+ - `.availableReminderLists(options?)` → `[{title, id, color, source, sourceType, isWritable, isEnabled, allowedEntityTypes}]` (v3.20)
420
+
421
+ ### CalendarItem Properties
422
+
423
+ - `.id` `String` — Set after add/query
424
+ - `.title` `String` — Event/reminder title
425
+ - `.date` `Date` — Start date/time
426
+ - `.endDate` `Date` — End date (events only)
427
+ - `.type` `"event"|"reminder"`
428
+ - `.isAllDay` `Boolean`
429
+ - `.isCompleted` `Boolean` — Reminders only
430
+ - `.occurences` `[Date]` — Multi-day dates
431
+ - `.calendar` `String` — Calendar/list name
432
+ - `.color` `String` — Hex color (v3.20)
433
+ - `.notes` `String` — Notes field
434
+ - `.url` `String` — Associated URL
435
+ - `.availability` `Int` — -1=notSupported, 0=busy, 1=free, 2=tentative, 3=unavailable
436
+ - `.attendees` `[String]` — Links (v3.5) / `.attendeeNames` `[String]` — Plain text (v3.5.2)
437
+ - `.calendarItemLink` `String` — Markdown link for note linking (v3.5)
438
+ - `.findLinkedFilenames()` → `Promise([String])` — Meeting notes (v3.9.1)
439
+
440
+ ### CalendarItem.create()
441
+
442
+ ```javascript
443
+ CalendarItem.create(title, date, endDate, type, isAllDay?, calendar?, isCompleted?, notes?, url?, availability?)
444
+ // type: "event" or "reminder"
445
+ ```
446
+
447
+ ### DateRangeObject
448
+
449
+ - `.start` `Date` / `.end` `Date` / `.text` `String` / `.index` `Int`
450
+
451
+ ---
452
+
453
+ ## 9. NotePlan Global
454
+
455
+ ### Properties
456
+
457
+ - `.environment` — `{languageCode, regionCode, is12hFormat, preferredLanguages, secondsFromGMT, localTimeZoneAbbreviation, localTimeZoneIdentifier, isDaylightSavingTime, platform ("macOS"|"iPadOS"|"iOS"), hasSettings, version, versionNumber, buildVersion, templateFolder, machineName, screenWidth, screenHeight, osVersion}`
458
+ - `.selectedSidebarFolder` `{get}` `String?` — Selected folder (macOS, v3.5)
459
+ - `.editors` `{get}` `[Editor]` — All open editors (v3.8.1)
460
+ - `.htmlWindows` `{get}` `[HTMLWindowObject]` — All HTML windows. Each has: `id, customId, type ("html"), displayType ("window"|"sheet"|"mainView"|"splitView"), windowRect, focus(), close(), runJavaScript(code)`
461
+
462
+ ### Methods
463
+
464
+ - `.ai(prompt, filenames?, useStrictFilenames?, model?)` → `Promise(String)` — OpenAI integration (v3.15.1). Filenames support relative expressions ("last 7 days"), folders ("/Projects"), calendar notes ("today", "this week")
465
+ - `.showConfigurationView()` → `Promise` — Plugin settings UI (macOS, v3.3.2)
466
+ - `.resetCaches()` — Rebuild sidebar (v3.5)
467
+ - `.openURL(url)` — Open in default browser (v3.5.2)
468
+ - `.stringDiff(version1, version2)` → `[RangeObject]` — Changed ranges (v3.7.2)
469
+ - `.toggleSidebar(forceCollapse, forceOpen, animated)` — Sidebar toggle (v3.19.2)
470
+ - `.setSidebarWidth(width)` / `.getSidebarWidth()` → `Number` — macOS only (v3.19.2)
471
+ - `.isSidebarCollapsed()` → `Boolean` (v3.19.2)
472
+ - `.getWeather(units, latitude, longitude)` → `Promise(Object)` — Weather via OpenWeatherMap (v3.19.2)
473
+
474
+ ---
475
+
476
+ ## 10. Clipboard & Range
477
+
478
+ ### Clipboard
479
+
480
+ - `.string` `{get/set}` `String` — Plain text
481
+ - `.types` `{get}` `[String]` — Available types
482
+ - `.setStringForType(string, type)` / `.stringForType(type)` → `String`
483
+ - `.setBase64DataStringForType(base64, type)` / `.base64DataStringForType(type)` → `String`
484
+ - `.dataForType(type)` → `Data` / `.setDataForType(data, type)`
485
+ - `.clearContents()`
486
+ - `.availableType(fromTypes)` → `String`
487
+
488
+ ### RangeObject
489
+
490
+ - `.start` `Int` / `.end` `Int` / `.length` `Int`
491
+ - `Range.create(start, end)` → `RangeObject`
492
+
493
+ ---
494
+
495
+ ## 11. Essential Patterns
496
+
497
+ ### console.log capture
498
+
499
+ All `console.log`, `console.warn`, `console.error` output is captured and readable via `noteplan_get_plugin_log`. Use liberally for debugging.
500
+
501
+ ### Frontmatter
502
+
503
+ ```javascript
504
+ // Read
505
+ const attrs = Editor.frontmatterAttributes; // {key: value, ...}
506
+ // Write single
507
+ Editor.setFrontmatterAttribute("status", "done");
508
+ // Write batch
509
+ Editor.updateFrontmatterAttributes([{key: "a", value: "1"}, {key: "b", value: "2"}]);
510
+ ```
511
+
512
+ ### Scheduling / Date links
513
+
514
+ Tasks with `>YYYY-MM-DD` or `>today` are scheduled. Use `Editor.insertScheduledTodo(content, lineIndex, date)` to create them.
515
+
516
+ ### Paragraph type values
517
+
518
+ `"open"` = `* [ ]`, `"done"` = `* [x]`, `"scheduled"` = `* [>]`, `"cancelled"` = `* [-]`, `"quote"` = `>`, `"title"` = `#`, `"list"` = `- ` (bullet), `"text"` = plain, `"empty"` = blank line, `"checklist"` = `+ [ ]`, `"checklistDone"` = `+ [x]`
519
+
520
+ ### PluginObject (from DataStore.listPlugins)
521
+
522
+ - `.id`, `.name`, `.desc`, `.author`, `.version`, `.script`, `.isOnline`, `.repoUrl`, `.releaseUrl`, `.availableUpdate`, `.commands`, `.lastUpdateInfo`, `.requiredFiles`
523
+
524
+ ### PluginCommandObject
525
+
526
+ - `.name`, `.desc`, `.pluginID`, `.pluginName`, `.arguments`
package/docs/plugin-api/plugin.json ADDED
@@ -0,0 +1,26 @@
1
+ {
2
+ "macOS.minVersion": "10.13.0",
3
+ "noteplan.minAppVersion": "3.20",
4
+ "plugin.id": "np.boilerplate",
5
+ "plugin.name": "Plugin Name",
6
+ "plugin.description": "A brief description of what this plugin does",
7
+ "plugin.author": "@yourusername",
8
+ "plugin.version": "1.0.0",
9
+ "plugin.lastUpdateInfo": "1.0.0: Initial release",
10
+ "plugin.dependencies": [],
11
+ "plugin.requiredFiles": [],
12
+ "plugin.script": "script.js",
13
+ "plugin.url": "https://github.com/yourusername/your-plugin-repo",
14
+ "plugin.commands": [
15
+ {
16
+ "name": "exampleCommand",
17
+ "description": "An example command that demonstrates plugin functionality",
18
+ "jsFunction": "exampleCommand",
19
+ "sidebarView": {
20
+ "title": "My Plugin View",
21
+ "icon": "calendar",
22
+ "iconColor": "blue-500"
23
+ }
24
+ }
25
+ ]
26
+ }