@plotday/twister 0.36.0 → 0.38.0

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 (243) hide show
  1. package/README.md +4 -2
  2. package/bin/commands/create.js +37 -3
  3. package/bin/commands/create.js.map +1 -1
  4. package/bin/commands/deploy.js +4 -0
  5. package/bin/commands/deploy.js.map +1 -1
  6. package/bin/index.js +1 -0
  7. package/bin/index.js.map +1 -1
  8. package/bin/templates/AGENTS.template.md +101 -189
  9. package/bin/templates/README.template.md +2 -23
  10. package/cli/templates/AGENTS.template.md +101 -189
  11. package/cli/templates/README.template.md +2 -23
  12. package/dist/docs/assets/hierarchy.js +1 -1
  13. package/dist/docs/assets/navigation.js +1 -1
  14. package/dist/docs/assets/search.js +1 -1
  15. package/dist/docs/classes/index.Options.html +1 -1
  16. package/dist/docs/classes/index.Source.html +200 -0
  17. package/dist/docs/classes/tool.ITool.html +1 -1
  18. package/dist/docs/classes/tool.Tool.html +21 -21
  19. package/dist/docs/classes/tools_ai.AI.html +1 -1
  20. package/dist/docs/classes/tools_callbacks.Callbacks.html +2 -2
  21. package/dist/docs/classes/tools_integrations.Integrations.html +45 -16
  22. package/dist/docs/classes/tools_network.Network.html +1 -1
  23. package/dist/docs/classes/tools_plot.Plot.html +93 -60
  24. package/dist/docs/classes/tools_store.Store.html +1 -1
  25. package/dist/docs/classes/tools_tasks.Tasks.html +1 -1
  26. package/dist/docs/classes/tools_twists.Twists.html +1 -1
  27. package/dist/docs/classes/twist.Twist.html +42 -10
  28. package/dist/docs/documents/Building_Sources.html +137 -0
  29. package/dist/docs/documents/Built-in_Tools.html +11 -2
  30. package/dist/docs/documents/Core_Concepts.html +5 -10
  31. package/dist/docs/documents/Getting_Started.html +1 -1
  32. package/dist/docs/enums/{plot.ActivityLinkType.html → plot.ActionType.html} +10 -8
  33. package/dist/docs/enums/plot.ActorType.html +7 -7
  34. package/dist/docs/enums/plot.ConferencingProvider.html +6 -6
  35. package/dist/docs/enums/plot.ThemeColor.html +9 -9
  36. package/dist/docs/enums/tag.Tag.html +3 -10
  37. package/dist/docs/enums/tools_integrations.AuthProvider.html +11 -11
  38. package/dist/docs/enums/tools_plot.ContactAccess.html +3 -3
  39. package/dist/docs/enums/tools_plot.PriorityAccess.html +3 -3
  40. package/dist/docs/enums/{tools_plot.ActivityAccess.html → tools_plot.ThreadAccess.html} +6 -6
  41. package/dist/docs/hierarchy.html +1 -1
  42. package/dist/docs/index.html +5 -6
  43. package/dist/docs/media/AGENTS.md +910 -0
  44. package/dist/docs/media/MULTI_USER_AUTH.md +111 -0
  45. package/dist/docs/media/SYNC_STRATEGIES.md +7 -7
  46. package/dist/docs/modules/index.html +1 -1
  47. package/dist/docs/modules/plot.html +1 -1
  48. package/dist/docs/modules/tool.html +1 -1
  49. package/dist/docs/modules/tools_integrations.html +1 -1
  50. package/dist/docs/modules/tools_plot.html +1 -1
  51. package/dist/docs/modules.html +1 -1
  52. package/dist/docs/types/index.NewSchedule.html +33 -0
  53. package/dist/docs/types/index.NewScheduleContact.html +5 -0
  54. package/dist/docs/types/index.NewScheduleOccurrence.html +6 -0
  55. package/dist/docs/types/index.Schedule.html +37 -0
  56. package/dist/docs/types/index.ScheduleContact.html +5 -0
  57. package/dist/docs/types/index.ScheduleContactRole.html +1 -0
  58. package/dist/docs/types/index.ScheduleContactStatus.html +1 -0
  59. package/dist/docs/types/index.ScheduleOccurrence.html +17 -0
  60. package/dist/docs/types/index.ScheduleOccurrenceUpdate.html +2 -0
  61. package/dist/docs/types/plot.Action.html +28 -0
  62. package/dist/docs/types/plot.Actor.html +6 -6
  63. package/dist/docs/types/plot.ActorId.html +1 -1
  64. package/dist/docs/types/plot.ContentType.html +1 -1
  65. package/dist/docs/types/plot.Link.html +36 -0
  66. package/dist/docs/types/plot.NewActor.html +1 -1
  67. package/dist/docs/types/plot.NewContact.html +5 -5
  68. package/dist/docs/types/plot.NewLink.html +26 -0
  69. package/dist/docs/types/plot.NewLinkWithNotes.html +7 -0
  70. package/dist/docs/types/plot.NewNote.html +10 -10
  71. package/dist/docs/types/plot.NewPriority.html +1 -1
  72. package/dist/docs/types/plot.NewTags.html +1 -1
  73. package/dist/docs/types/plot.NewThread.html +27 -0
  74. package/dist/docs/types/plot.NewThreadWithNotes.html +1 -0
  75. package/dist/docs/types/plot.Note.html +9 -8
  76. package/dist/docs/types/plot.NoteUpdate.html +2 -2
  77. package/dist/docs/types/plot.PickPriorityConfig.html +8 -10
  78. package/dist/docs/types/plot.Priority.html +6 -6
  79. package/dist/docs/types/plot.PriorityUpdate.html +1 -1
  80. package/dist/docs/types/plot.Tags.html +1 -1
  81. package/dist/docs/types/plot.Thread.html +1 -0
  82. package/dist/docs/types/plot.ThreadCommon.html +17 -0
  83. package/dist/docs/types/plot.ThreadFilter.html +2 -0
  84. package/dist/docs/types/plot.ThreadMeta.html +11 -0
  85. package/dist/docs/types/plot.ThreadUpdate.html +3 -0
  86. package/dist/docs/types/plot.ThreadWithNotes.html +1 -0
  87. package/dist/docs/types/tools_integrations.ArchiveLinkFilter.html +11 -0
  88. package/dist/docs/types/tools_integrations.AuthToken.html +4 -4
  89. package/dist/docs/types/tools_integrations.Authorization.html +4 -4
  90. package/dist/docs/types/tools_integrations.Channel.html +11 -0
  91. package/dist/docs/types/tools_integrations.LinkTypeConfig.html +17 -0
  92. package/dist/docs/types/tools_plot.LinkFilter.html +10 -0
  93. package/dist/docs/types/tools_plot.LinkSearchResult.html +1 -0
  94. package/dist/docs/types/tools_plot.NoteIntentHandler.html +6 -6
  95. package/dist/docs/types/tools_plot.NoteSearchResult.html +1 -0
  96. package/dist/docs/types/tools_plot.SearchOptions.html +7 -0
  97. package/dist/docs/types/tools_plot.SearchResult.html +1 -0
  98. package/dist/docs/types/tools_twists.TwistPermissions.html +1 -1
  99. package/dist/docs/variables/tools_plot.SEARCH_DEFAULT_LIMIT.html +2 -0
  100. package/dist/docs/variables/tools_plot.SEARCH_MAX_LIMIT.html +2 -0
  101. package/dist/index.d.ts +2 -0
  102. package/dist/index.d.ts.map +1 -1
  103. package/dist/index.js +2 -0
  104. package/dist/index.js.map +1 -1
  105. package/dist/llm-docs/index.d.ts.map +1 -1
  106. package/dist/llm-docs/index.js +4 -8
  107. package/dist/llm-docs/index.js.map +1 -1
  108. package/dist/llm-docs/plot.d.ts +1 -1
  109. package/dist/llm-docs/plot.d.ts.map +1 -1
  110. package/dist/llm-docs/plot.js +1 -1
  111. package/dist/llm-docs/plot.js.map +1 -1
  112. package/dist/llm-docs/schedule.d.ts +9 -0
  113. package/dist/llm-docs/schedule.d.ts.map +1 -0
  114. package/dist/llm-docs/schedule.js +8 -0
  115. package/dist/llm-docs/schedule.js.map +1 -0
  116. package/dist/llm-docs/source.d.ts +9 -0
  117. package/dist/llm-docs/source.d.ts.map +1 -0
  118. package/dist/llm-docs/source.js +8 -0
  119. package/dist/llm-docs/source.js.map +1 -0
  120. package/dist/llm-docs/tag.d.ts +1 -1
  121. package/dist/llm-docs/tag.d.ts.map +1 -1
  122. package/dist/llm-docs/tag.js +1 -1
  123. package/dist/llm-docs/tag.js.map +1 -1
  124. package/dist/llm-docs/tool.d.ts +1 -1
  125. package/dist/llm-docs/tool.d.ts.map +1 -1
  126. package/dist/llm-docs/tool.js +1 -1
  127. package/dist/llm-docs/tool.js.map +1 -1
  128. package/dist/llm-docs/tools/callbacks.d.ts +1 -1
  129. package/dist/llm-docs/tools/callbacks.d.ts.map +1 -1
  130. package/dist/llm-docs/tools/callbacks.js +1 -1
  131. package/dist/llm-docs/tools/callbacks.js.map +1 -1
  132. package/dist/llm-docs/tools/integrations.d.ts +1 -1
  133. package/dist/llm-docs/tools/integrations.d.ts.map +1 -1
  134. package/dist/llm-docs/tools/integrations.js +1 -1
  135. package/dist/llm-docs/tools/integrations.js.map +1 -1
  136. package/dist/llm-docs/tools/plot.d.ts +1 -1
  137. package/dist/llm-docs/tools/plot.d.ts.map +1 -1
  138. package/dist/llm-docs/tools/plot.js +1 -1
  139. package/dist/llm-docs/tools/plot.js.map +1 -1
  140. package/dist/llm-docs/tools/twists.d.ts +1 -1
  141. package/dist/llm-docs/tools/twists.d.ts.map +1 -1
  142. package/dist/llm-docs/tools/twists.js +1 -1
  143. package/dist/llm-docs/tools/twists.js.map +1 -1
  144. package/dist/llm-docs/twist-guide-template.d.ts +1 -1
  145. package/dist/llm-docs/twist-guide-template.d.ts.map +1 -1
  146. package/dist/llm-docs/twist-guide-template.js +1 -1
  147. package/dist/llm-docs/twist-guide-template.js.map +1 -1
  148. package/dist/llm-docs/twist.d.ts +1 -1
  149. package/dist/llm-docs/twist.d.ts.map +1 -1
  150. package/dist/llm-docs/twist.js +1 -1
  151. package/dist/llm-docs/twist.js.map +1 -1
  152. package/dist/plot.d.ts +264 -589
  153. package/dist/plot.d.ts.map +1 -1
  154. package/dist/plot.js +18 -49
  155. package/dist/plot.js.map +1 -1
  156. package/dist/schedule.d.ts +172 -0
  157. package/dist/schedule.d.ts.map +1 -0
  158. package/dist/schedule.js +2 -0
  159. package/dist/schedule.js.map +1 -0
  160. package/dist/source.d.ts +158 -0
  161. package/dist/source.d.ts.map +1 -0
  162. package/dist/source.js +144 -0
  163. package/dist/source.js.map +1 -0
  164. package/dist/tag.d.ts +3 -10
  165. package/dist/tag.d.ts.map +1 -1
  166. package/dist/tag.js +2 -11
  167. package/dist/tag.js.map +1 -1
  168. package/dist/tool.d.ts +1 -15
  169. package/dist/tool.d.ts.map +1 -1
  170. package/dist/tool.js.map +1 -1
  171. package/dist/tools/callbacks.d.ts +1 -1
  172. package/dist/tools/callbacks.js +1 -1
  173. package/dist/tools/integrations.d.ts +119 -52
  174. package/dist/tools/integrations.d.ts.map +1 -1
  175. package/dist/tools/integrations.js +23 -22
  176. package/dist/tools/integrations.js.map +1 -1
  177. package/dist/tools/plot.d.ts +182 -117
  178. package/dist/tools/plot.d.ts.map +1 -1
  179. package/dist/tools/plot.js +23 -21
  180. package/dist/tools/plot.js.map +1 -1
  181. package/dist/tools/twists.d.ts +1 -1
  182. package/dist/twist-guide.d.ts +1 -1
  183. package/dist/twist-guide.d.ts.map +1 -1
  184. package/dist/twist.d.ts +66 -11
  185. package/dist/twist.d.ts.map +1 -1
  186. package/dist/twist.js +79 -10
  187. package/dist/twist.js.map +1 -1
  188. package/package.json +11 -41
  189. package/dist/common/calendar.d.ts +0 -135
  190. package/dist/common/calendar.d.ts.map +0 -1
  191. package/dist/common/calendar.js +0 -2
  192. package/dist/common/calendar.js.map +0 -1
  193. package/dist/common/documents.d.ts +0 -122
  194. package/dist/common/documents.d.ts.map +0 -1
  195. package/dist/common/documents.js +0 -2
  196. package/dist/common/documents.js.map +0 -1
  197. package/dist/common/messaging.d.ts +0 -84
  198. package/dist/common/messaging.d.ts.map +0 -1
  199. package/dist/common/messaging.js +0 -2
  200. package/dist/common/messaging.js.map +0 -1
  201. package/dist/common/projects.d.ts +0 -112
  202. package/dist/common/projects.d.ts.map +0 -1
  203. package/dist/common/projects.js +0 -2
  204. package/dist/common/projects.js.map +0 -1
  205. package/dist/docs/documents/Building_Custom_Tools.html +0 -215
  206. package/dist/docs/enums/plot.ActivityKind.html +0 -14
  207. package/dist/docs/enums/plot.ActivityType.html +0 -10
  208. package/dist/docs/modules/common_calendar.html +0 -1
  209. package/dist/docs/types/common_calendar.Calendar.html +0 -13
  210. package/dist/docs/types/common_calendar.CalendarTool.html +0 -81
  211. package/dist/docs/types/common_calendar.SyncOptions.html +0 -24
  212. package/dist/docs/types/plot.Activity.html +0 -2
  213. package/dist/docs/types/plot.ActivityCommon.html +0 -20
  214. package/dist/docs/types/plot.ActivityFilter.html +0 -3
  215. package/dist/docs/types/plot.ActivityLink.html +0 -26
  216. package/dist/docs/types/plot.ActivityMeta.html +0 -11
  217. package/dist/docs/types/plot.ActivityOccurrence.html +0 -22
  218. package/dist/docs/types/plot.ActivityOccurrenceUpdate.html +0 -3
  219. package/dist/docs/types/plot.ActivityUpdate.html +0 -3
  220. package/dist/docs/types/plot.ActivityWithNotes.html +0 -1
  221. package/dist/docs/types/plot.NewActivity.html +0 -81
  222. package/dist/docs/types/plot.NewActivityOccurrence.html +0 -24
  223. package/dist/docs/types/plot.NewActivityWithNotes.html +0 -1
  224. package/dist/docs/types/tool.SyncToolOptions.html +0 -9
  225. package/dist/docs/types/tools_integrations.IntegrationOptions.html +0 -4
  226. package/dist/docs/types/tools_integrations.IntegrationProviderConfig.html +0 -13
  227. package/dist/docs/types/tools_integrations.Syncable.html +0 -9
  228. package/dist/llm-docs/common/calendar.d.ts +0 -9
  229. package/dist/llm-docs/common/calendar.d.ts.map +0 -1
  230. package/dist/llm-docs/common/calendar.js +0 -8
  231. package/dist/llm-docs/common/calendar.js.map +0 -1
  232. package/dist/llm-docs/common/documents.d.ts +0 -9
  233. package/dist/llm-docs/common/documents.d.ts.map +0 -1
  234. package/dist/llm-docs/common/documents.js +0 -8
  235. package/dist/llm-docs/common/documents.js.map +0 -1
  236. package/dist/llm-docs/common/messaging.d.ts +0 -9
  237. package/dist/llm-docs/common/messaging.d.ts.map +0 -1
  238. package/dist/llm-docs/common/messaging.js +0 -8
  239. package/dist/llm-docs/common/messaging.js.map +0 -1
  240. package/dist/llm-docs/common/projects.d.ts +0 -9
  241. package/dist/llm-docs/common/projects.d.ts.map +0 -1
  242. package/dist/llm-docs/common/projects.js +0 -8
  243. package/dist/llm-docs/common/projects.js.map +0 -1
package/dist/docs/documents/Building_Sources.html ADDED
@@ -0,0 +1,137 @@
1
+ <!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>Building Sources | Creating Plot Twists</title><link rel="icon" href="../assets/favicon.svg" type="image/svg+xml"/><meta name="description" content="Documentation for Creating Plot Twists"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="/" class="title">Creating Plot Twists</a><div id="tsd-toolbar-links"><a href="https://plot.day">Plot</a><a href="https://github.com/plotday/plot">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister">NPM</a></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">Building Sources</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="building-sources" class="tsd-anchor-link">Building Sources<a href="#building-sources" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1><p>Sources connect Plot to external services like Google Calendar, Slack, Linear, and more. They sync data into Plot and optionally support bidirectional updates. This guide covers everything you need to know about building sources.</p>
2
+ <h2 id="table-of-contents" class="tsd-anchor-link">Table of Contents<a href="#table-of-contents" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><ul>
3
+ <li><a href="#sources-vs-twists">Sources vs Twists</a></li>
4
+ <li><a href="#source-structure">Source Structure</a></li>
5
+ <li><a href="#oauth-and-channel-lifecycle">OAuth and Channel Lifecycle</a></li>
6
+ <li><a href="#data-sync">Data Sync</a></li>
7
+ <li><a href="#batch-processing">Batch Processing</a></li>
8
+ <li><a href="#complete-example">Complete Example</a></li>
9
+ <li><a href="#best-practices">Best Practices</a></li>
10
+ </ul>
11
+ <hr>
12
+ <h2 id="sources-vs-twists" class="tsd-anchor-link">Sources vs Twists<a href="#sources-vs-twists" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><table>
13
+ <thead>
14
+ <tr>
15
+ <th></th>
16
+ <th>Sources</th>
17
+ <th>Twists</th>
18
+ </tr>
19
+ </thead>
20
+ <tbody>
21
+ <tr>
22
+ <td><strong>Purpose</strong></td>
23
+ <td>Sync data from external services</td>
24
+ <td>Implement opinionated workflows</td>
25
+ </tr>
26
+ <tr>
27
+ <td><strong>Base class</strong></td>
28
+ <td><code>Source&lt;T&gt;</code> (extends <code>Twist&lt;T&gt;</code>)</td>
29
+ <td><code>Twist&lt;T&gt;</code></td>
30
+ </tr>
31
+ <tr>
32
+ <td><strong>Auth</strong></td>
33
+ <td>OAuth via <code>Integrations</code> with channel lifecycle</td>
34
+ <td>Optional</td>
35
+ </tr>
36
+ <tr>
37
+ <td><strong>Data flow</strong></td>
38
+ <td>External service -&gt; Plot (and optionally back)</td>
39
+ <td>Internal logic, orchestration</td>
40
+ </tr>
41
+ <tr>
42
+ <td><strong>Examples</strong></td>
43
+ <td>Google Calendar, Slack, Linear, Jira</td>
44
+ <td>Task automation, AI assistants</td>
45
+ </tr>
46
+ </tbody>
47
+ </table>
48
+ <p><strong>Build a Source</strong> when you need to integrate an external service — syncing calendars, issues, messages, etc.</p>
49
+ <p><strong>Build a Twist</strong> when you need workflow logic that doesn't require external service integration, or when you want to orchestrate multiple sources.</p>
50
+ <hr>
51
+ <h2 id="source-structure" class="tsd-anchor-link">Source Structure<a href="#source-structure" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Sources extend the <code>Source&lt;T&gt;</code> base class and declare dependencies using <code>SourceBuilder</code>:</p>
52
+ <pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">Source</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">SourceBuilder</span><span class="hl-1">,</span><br/><span class="hl-1">} </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">AuthProvider</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">AuthToken</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Authorization</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Channel</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">Integrations</span><span class="hl-1">,</span><br/><span class="hl-1">} </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/integrations&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Network</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/network&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Plot</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/plot&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Tasks</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/tasks&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Callbacks</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/callbacks&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-0">export</span><span class="hl-1"> </span><span class="hl-0">default</span><span class="hl-1"> </span><span class="hl-4">class</span><span class="hl-1"> </span><span class="hl-5">MySource</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Source</span><span class="hl-1">&lt;</span><span class="hl-5">MySource</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-4">static</span><span class="hl-1"> </span><span class="hl-4">readonly</span><span class="hl-1"> </span><span class="hl-2">PROVIDER</span><span class="hl-1"> = </span><span class="hl-2">AuthProvider</span><span class="hl-1">.</span><span class="hl-2">Linear</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-4">static</span><span class="hl-1"> </span><span class="hl-4">readonly</span><span class="hl-1"> </span><span class="hl-2">SCOPES</span><span class="hl-1"> = [</span><span class="hl-3">&quot;read&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;write&quot;</span><span class="hl-1">];</span><br/><br/><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">build</span><span class="hl-1">: </span><span class="hl-5">SourceBuilder</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">return</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">integrations:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Integrations</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">providers:</span><span class="hl-1"> [{</span><br/><span class="hl-1"> </span><span class="hl-2">provider:</span><span class="hl-1"> </span><span class="hl-2">MySource</span><span class="hl-1">.</span><span class="hl-8">PROVIDER</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">scopes:</span><span class="hl-1"> </span><span class="hl-2">MySource</span><span class="hl-1">.</span><span class="hl-8">SCOPES</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">getChannels:</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">getChannels</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">onChannelEnabled:</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">onChannelEnabled</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">onChannelDisabled:</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">onChannelDisabled</span><span class="hl-1">,</span><br/><span class="hl-1"> }],</span><br/><span class="hl-1"> }),</span><br/><span class="hl-1"> </span><span class="hl-2">network:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Network</span><span class="hl-1">, { </span><span class="hl-2">urls:</span><span class="hl-1"> [</span><span class="hl-3">&quot;https://api.example.com/*&quot;</span><span class="hl-1">] }),</span><br/><span class="hl-1"> </span><span class="hl-2">plot:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Plot</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">tasks:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Tasks</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">callbacks:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Callbacks</span><span class="hl-1">),</span><br/><span class="hl-1"> };</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// ... lifecycle methods below</span><br/><span class="hl-1">}</span>
53
+ </code><button type="button">Copy</button></pre>
54
+
55
+ <h3 id="package-structure" class="tsd-anchor-link">Package Structure<a href="#package-structure" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code><span class="hl-2">sources</span><span class="hl-1">/</span><span class="hl-2">my</span><span class="hl-1">-</span><span class="hl-2">source</span><span class="hl-1">/</span><br/><span class="hl-1"> </span><span class="hl-2">src</span><span class="hl-1">/</span><br/><span class="hl-1"> </span><span class="hl-2">index</span><span class="hl-1">.</span><span class="hl-2">ts</span><span class="hl-1"> # </span><span class="hl-2">Re</span><span class="hl-1">-</span><span class="hl-15">exports</span><span class="hl-1">: </span><span class="hl-0">export</span><span class="hl-1"> { </span><span class="hl-0">default</span><span class="hl-1">, </span><span class="hl-2">MySource</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;./my-source&quot;</span><br/><span class="hl-1"> </span><span class="hl-2">my</span><span class="hl-1">-</span><span class="hl-2">source</span><span class="hl-1">.</span><span class="hl-2">ts</span><span class="hl-1"> # </span><span class="hl-2">Main</span><span class="hl-1"> </span><span class="hl-2">Source</span><span class="hl-1"> </span><span class="hl-4">class</span><br/><span class="hl-1"> </span><span class="hl-5">package</span><span class="hl-1">.</span><span class="hl-5">json</span><br/><span class="hl-1"> </span><span class="hl-5">tsconfig</span><span class="hl-1">.</span><span class="hl-5">json</span>
56
+ </code><button>Copy</button></pre>
57
+
58
+ <hr>
59
+ <h2 id="oauth-and-channel-lifecycle" class="tsd-anchor-link">OAuth and Channel Lifecycle<a href="#oauth-and-channel-lifecycle" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Sources use the Integrations tool for OAuth. Auth is handled automatically in the Flutter edit modal — you don't need to build UI for it.</p>
60
+ <h3 id="how-it-works" class="tsd-anchor-link">How It Works<a href="#how-it-works" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ol>
61
+ <li>Source declares providers in <code>build()</code> with <code>getChannels</code>, <code>onChannelEnabled</code>, <code>onChannelDisabled</code> callbacks</li>
62
+ <li>User clicks &quot;Connect&quot; in the twist edit modal -&gt; OAuth flow happens automatically</li>
63
+ <li>After auth, the runtime calls <code>getChannels()</code> to list available resources</li>
64
+ <li>User enables/disables resources in the modal</li>
65
+ </ol>
66
+ <h3 id="getchannels" class="tsd-anchor-link">getChannels<a href="#getchannels" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Return available resources after authentication:</p>
67
+ <pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">getChannels</span><span class="hl-1">(</span><span class="hl-2">_auth</span><span class="hl-1">: </span><span class="hl-2">Authorization</span><span class="hl-1">, </span><span class="hl-2">token</span><span class="hl-1">: </span><span class="hl-2">AuthToken</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">Channel</span><span class="hl-1">[]&gt; {</span><br/><span class="hl-1"> const </span><span class="hl-2">client</span><span class="hl-1"> = </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">ApiClient</span><span class="hl-1">({ </span><span class="hl-2">accessToken:</span><span class="hl-1"> </span><span class="hl-2">token</span><span class="hl-1">.</span><span class="hl-2">token</span><span class="hl-1"> });</span><br/><span class="hl-1"> const </span><span class="hl-2">resources</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">client</span><span class="hl-1">.</span><span class="hl-6">listResources</span><span class="hl-1">();</span><br/><span class="hl-1"> return resources.map(</span><span class="hl-2">r</span><span class="hl-1"> </span><span class="hl-4">=&gt;</span><span class="hl-1"> ({ </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-2">r</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">, </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-2">r</span><span class="hl-1">.</span><span class="hl-2">name</span><span class="hl-1"> }));</span><br/><span class="hl-1">}</span>
68
+ </code><button type="button">Copy</button></pre>
69
+
70
+ <h3 id="onchannelenabled" class="tsd-anchor-link">onChannelEnabled<a href="#onchannelenabled" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Called when the user enables a resource. Set up syncing:</p>
71
+ <pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">onChannelEnabled</span><span class="hl-1">(</span><span class="hl-2">channel</span><span class="hl-1">: </span><span class="hl-2">Channel</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-4">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> await this.setupWebhook(channel.id);</span><br/><span class="hl-1"> await this.startBatchSync(channel.id);</span><br/><span class="hl-1">}</span>
72
+ </code><button type="button">Copy</button></pre>
73
+
74
+ <h3 id="onchanneldisabled" class="tsd-anchor-link">onChannelDisabled<a href="#onchanneldisabled" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Called when the user disables a resource. Clean up:</p>
75
+ <pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">onChannelDisabled</span><span class="hl-1">(</span><span class="hl-2">channel</span><span class="hl-1">: </span><span class="hl-2">Channel</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-4">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-7">// Remove webhook</span><br/><span class="hl-1"> const </span><span class="hl-2">webhookId</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">string</span><span class="hl-1">&gt;(</span><span class="hl-3">`webhook_id_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">if</span><span class="hl-1"> (</span><span class="hl-2">webhookId</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">client</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">getClient</span><span class="hl-1">(</span><span class="hl-2">channel</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">client</span><span class="hl-1">.</span><span class="hl-6">deleteWebhook</span><span class="hl-1">(</span><span class="hl-2">webhookId</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">clear</span><span class="hl-1">(</span><span class="hl-3">`webhook_id_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Clean up stored state</span><br/><span class="hl-1"> await this.clear(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-2">);</span><br/><span class="hl-2">}</span>
76
+ </code><button type="button">Copy</button></pre>
77
+
78
+ <h3 id="getting-auth-tokens" class="tsd-anchor-link">Getting Auth Tokens<a href="#getting-auth-tokens" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Retrieve tokens for API calls using the channel ID:</p>
79
+ <pre><code class="typescript"><span class="hl-2">private</span><span class="hl-1"> </span><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">getClient</span><span class="hl-1">(</span><span class="hl-2">channelId</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">ApiClient</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> const </span><span class="hl-2">token</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">integrations</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">(</span><span class="hl-2">MySource</span><span class="hl-1">.</span><span class="hl-8">PROVIDER</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">if</span><span class="hl-1"> (!</span><span class="hl-2">token</span><span class="hl-1">) throw new </span><span class="hl-6">Error</span><span class="hl-1">(</span><span class="hl-3">&quot;No authentication token available&quot;</span><span class="hl-1">);</span><br/><span class="hl-1"> return new </span><span class="hl-6">ApiClient</span><span class="hl-1">({ </span><span class="hl-2">accessToken</span><span class="hl-1">: </span><span class="hl-2">token</span><span class="hl-1">.</span><span class="hl-2">token</span><span class="hl-1"> });</span><br/><span class="hl-1">}</span>
80
+ </code><button type="button">Copy</button></pre>
81
+
82
+ <hr>
83
+ <h2 id="data-sync" class="tsd-anchor-link">Data Sync<a href="#data-sync" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Sources sync data using <code>Activity.source</code> and <code>Note.key</code> for automatic upserts (no manual ID tracking needed).</p>
84
+ <h3 id="transforming-external-items" class="tsd-anchor-link">Transforming External Items<a href="#transforming-external-items" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-2">private</span><span class="hl-1"> </span><span class="hl-6">transformItem</span><span class="hl-1">(</span><span class="hl-2">item</span><span class="hl-1">: </span><span class="hl-2">any</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">, </span><span class="hl-2">initialSync</span><span class="hl-1">: </span><span class="hl-2">boolean</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">return</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">`myprovider:item:</span><span class="hl-4">${</span><span class="hl-2">item</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, </span><span class="hl-7">// Canonical source for deduplication</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-2">item</span><span class="hl-1">.</span><span class="hl-2">title</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">meta:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">externalId:</span><span class="hl-1"> </span><span class="hl-2">item</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">syncProvider:</span><span class="hl-1"> </span><span class="hl-3">&quot;myprovider&quot;</span><span class="hl-1">, </span><span class="hl-7">// Required for bulk operations</span><br/><span class="hl-1"> </span><span class="hl-2">channelId</span><span class="hl-1">, </span><span class="hl-7">// Required for bulk operations</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-2">notes:</span><span class="hl-1"> [{</span><br/><span class="hl-1"> </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&quot;description&quot;</span><span class="hl-1">, </span><span class="hl-7">// Enables note-level upserts</span><br/><span class="hl-1"> </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-2">item</span><span class="hl-1">.</span><span class="hl-2">description</span><span class="hl-1"> || </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">contentType:</span><span class="hl-1"> </span><span class="hl-2">item</span><span class="hl-1">.</span><span class="hl-2">descriptionHtml</span><span class="hl-1"> ? </span><span class="hl-3">&quot;html&quot;</span><span class="hl-1"> </span><span class="hl-0">as</span><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> : </span><span class="hl-3">&quot;text&quot;</span><span class="hl-1"> </span><span class="hl-0">as</span><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1">,</span><br/><span class="hl-1"> }],</span><br/><span class="hl-1"> ...(</span><span class="hl-2">initialSync</span><span class="hl-1"> ? { </span><span class="hl-2">unread:</span><span class="hl-1"> </span><span class="hl-4">false</span><span class="hl-1"> } : {}), </span><span class="hl-7">// Mark read on initial sync</span><br/><span class="hl-1"> ...(</span><span class="hl-2">initialSync</span><span class="hl-1"> ? { </span><span class="hl-2">archived:</span><span class="hl-1"> </span><span class="hl-4">false</span><span class="hl-1"> } : {}), </span><span class="hl-7">// Unarchive on initial sync</span><br/><span class="hl-1"> };</span><br/><span class="hl-1">}</span>
85
+ </code><button type="button">Copy</button></pre>
86
+
87
+ <h3 id="initial-vs-incremental-sync" class="tsd-anchor-link">Initial vs Incremental Sync<a href="#initial-vs-incremental-sync" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>All sources <strong>must</strong> distinguish between initial sync (first import) and incremental sync (ongoing updates):</p>
88
+ <table>
89
+ <thead>
90
+ <tr>
91
+ <th>Field</th>
92
+ <th>Initial Sync</th>
93
+ <th>Incremental Sync</th>
94
+ <th>Reason</th>
95
+ </tr>
96
+ </thead>
97
+ <tbody>
98
+ <tr>
99
+ <td><code>unread</code></td>
100
+ <td><code>false</code></td>
101
+ <td><em>omit</em></td>
102
+ <td>Avoid notification spam from historical imports</td>
103
+ </tr>
104
+ <tr>
105
+ <td><code>archived</code></td>
106
+ <td><code>false</code></td>
107
+ <td><em>omit</em></td>
108
+ <td>Unarchive on install, preserve user choice on updates</td>
109
+ </tr>
110
+ </tbody>
111
+ </table>
112
+ <p>See <a href="../media/SYNC_STRATEGIES.md">Sync Strategies</a> for detailed patterns on deduplication, upserts, and tag management.</p>
113
+ <hr>
114
+ <h2 id="batch-processing" class="tsd-anchor-link">Batch Processing<a href="#batch-processing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Sources run in an ephemeral environment with ~1000 requests per execution. Break long operations into batches using <code>runTask()</code>, which creates a new execution with fresh request limits.</p>
115
+ <pre><code class="typescript"><span class="hl-2">private</span><span class="hl-1"> </span><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">startBatchSync</span><span class="hl-1">(</span><span class="hl-2">channelId</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-4">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> await this.set(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channelId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-15">cursor</span><span class="hl-1">: </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-15">batchNumber</span><span class="hl-1">: </span><span class="hl-14">1</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-15">initialSync</span><span class="hl-1">: </span><span class="hl-4">true</span><span class="hl-1">,</span><br/><span class="hl-1"> });</span><br/><br/><span class="hl-1"> const </span><span class="hl-2">batchCallback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">syncBatch</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">);</span><br/><span class="hl-1"> await this.tools.tasks.runTask(batchCallback);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-2">private</span><span class="hl-1"> </span><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">syncBatch</span><span class="hl-1">(</span><span class="hl-2">channelId</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-4">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> const </span><span class="hl-2">state</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channelId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">if</span><span class="hl-1"> (!</span><span class="hl-2">state</span><span class="hl-1">) return;</span><br/><br/><span class="hl-1"> const </span><span class="hl-2">client</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">getClient</span><span class="hl-1">(</span><span class="hl-2">channelId</span><span class="hl-1">);</span><br/><span class="hl-1"> const </span><span class="hl-2">result</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">client</span><span class="hl-1">.</span><span class="hl-6">listItems</span><span class="hl-1">({ </span><span class="hl-2">cursor:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">cursor</span><span class="hl-1">, </span><span class="hl-2">limit:</span><span class="hl-1"> </span><span class="hl-14">50</span><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-6">for</span><span class="hl-1"> (</span><span class="hl-2">const</span><span class="hl-1"> </span><span class="hl-2">item</span><span class="hl-1"> </span><span class="hl-2">of</span><span class="hl-1"> result.items) {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">activity</span><span class="hl-1"> = </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">transformItem</span><span class="hl-1">(</span><span class="hl-2">item</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">, </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">initialSync</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">(</span><span class="hl-2">activity</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-6">if</span><span class="hl-1"> (result.nextCursor) {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channelId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">cursor:</span><span class="hl-1"> </span><span class="hl-2">result</span><span class="hl-1">.</span><span class="hl-2">nextCursor</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">batchNumber:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">batchNumber</span><span class="hl-1"> + </span><span class="hl-14">1</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">initialSync:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">initialSync</span><span class="hl-1">,</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">nextBatch</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">syncBatch</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">tasks</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">nextBatch</span><span class="hl-1">);</span><br/><span class="hl-1"> } else {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">clear</span><span class="hl-1">(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channelId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
116
+ </code><button type="button">Copy</button></pre>
117
+
118
+ <hr>
119
+ <h2 id="complete-example" class="tsd-anchor-link">Complete Example<a href="#complete-example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>A minimal source that syncs issues from an external service:</p>
120
+ <pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">LinkType</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">Source</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">SourceBuilder</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">SyncToolOptions</span><span class="hl-1">,</span><br/><span class="hl-1">} </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">AuthProvider</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">AuthToken</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Authorization</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Channel</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">Integrations</span><span class="hl-1">,</span><br/><span class="hl-1">} </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/integrations&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Network</span><span class="hl-1">, </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">WebhookRequest</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/network&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Plot</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/plot&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Tasks</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/tasks&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Callbacks</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/callbacks&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-0">export</span><span class="hl-1"> </span><span class="hl-0">default</span><span class="hl-1"> </span><span class="hl-4">class</span><span class="hl-1"> </span><span class="hl-5">IssueSource</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Source</span><span class="hl-1">&lt;</span><span class="hl-5">IssueSource</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-4">static</span><span class="hl-1"> </span><span class="hl-4">readonly</span><span class="hl-1"> </span><span class="hl-2">PROVIDER</span><span class="hl-1"> = </span><span class="hl-2">AuthProvider</span><span class="hl-1">.</span><span class="hl-2">Linear</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-4">static</span><span class="hl-1"> </span><span class="hl-4">readonly</span><span class="hl-1"> </span><span class="hl-2">SCOPES</span><span class="hl-1"> = [</span><span class="hl-3">&quot;read&quot;</span><span class="hl-1">];</span><br/><span class="hl-1"> </span><span class="hl-4">static</span><span class="hl-1"> </span><span class="hl-4">readonly</span><span class="hl-1"> </span><span class="hl-2">Options</span><span class="hl-1">: </span><span class="hl-5">SyncToolOptions</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-4">declare</span><span class="hl-1"> </span><span class="hl-4">readonly</span><span class="hl-1"> </span><span class="hl-2">Options</span><span class="hl-1">: </span><span class="hl-5">SyncToolOptions</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">build</span><span class="hl-1">: </span><span class="hl-5">SourceBuilder</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">return</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">integrations:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Integrations</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">providers:</span><span class="hl-1"> [{</span><br/><span class="hl-1"> </span><span class="hl-2">provider:</span><span class="hl-1"> </span><span class="hl-2">IssueSource</span><span class="hl-1">.</span><span class="hl-8">PROVIDER</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">scopes:</span><span class="hl-1"> </span><span class="hl-2">IssueSource</span><span class="hl-1">.</span><span class="hl-8">SCOPES</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">getChannels:</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">getChannels</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">onChannelEnabled:</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">onChannelEnabled</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">onChannelDisabled:</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">onChannelDisabled</span><span class="hl-1">,</span><br/><span class="hl-1"> }],</span><br/><span class="hl-1"> }),</span><br/><span class="hl-1"> </span><span class="hl-2">network:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Network</span><span class="hl-1">, { </span><span class="hl-2">urls:</span><span class="hl-1"> [</span><span class="hl-3">&quot;https://api.linear.app/*&quot;</span><span class="hl-1">] }),</span><br/><span class="hl-1"> </span><span class="hl-2">plot:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Plot</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">tasks:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Tasks</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">callbacks:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Callbacks</span><span class="hl-1">),</span><br/><span class="hl-1"> };</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">getChannels</span><span class="hl-1">(</span><span class="hl-2">_auth</span><span class="hl-1">: </span><span class="hl-5">Authorization</span><span class="hl-1">, </span><span class="hl-2">token</span><span class="hl-1">: </span><span class="hl-5">AuthToken</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-5">Channel</span><span class="hl-1">[]&gt; {</span><br/><span class="hl-1"> </span><span class="hl-7">// Return available projects/teams for the user to select</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">client</span><span class="hl-1"> = </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">LinearClient</span><span class="hl-1">({ </span><span class="hl-2">accessToken:</span><span class="hl-1"> </span><span class="hl-2">token</span><span class="hl-1">.</span><span class="hl-2">token</span><span class="hl-1"> });</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">teams</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">client</span><span class="hl-1">.</span><span class="hl-6">teams</span><span class="hl-1">();</span><br/><span class="hl-1"> </span><span class="hl-0">return</span><span class="hl-1"> </span><span class="hl-2">teams</span><span class="hl-1">.</span><span class="hl-2">nodes</span><span class="hl-1">.</span><span class="hl-6">map</span><span class="hl-1">(</span><span class="hl-2">t</span><span class="hl-1"> </span><span class="hl-4">=&gt;</span><span class="hl-1"> ({ </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-2">t</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">, </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-2">t</span><span class="hl-1">.</span><span class="hl-2">name</span><span class="hl-1"> }));</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">onChannelEnabled</span><span class="hl-1">(</span><span class="hl-2">channel</span><span class="hl-1">: </span><span class="hl-5">Channel</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-5">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-7">// Set up webhook</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">webhookUrl</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">network</span><span class="hl-1">.</span><span class="hl-6">createWebhook</span><span class="hl-1">(</span><br/><span class="hl-1"> {}, </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">onWebhook</span><span class="hl-1">, </span><span class="hl-2">channel</span><span class="hl-1">.</span><span class="hl-2">id</span><br/><span class="hl-1"> );</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (!</span><span class="hl-2">webhookUrl</span><span class="hl-1">.</span><span class="hl-6">includes</span><span class="hl-1">(</span><span class="hl-3">&quot;localhost&quot;</span><span class="hl-1">)) {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">client</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">getClient</span><span class="hl-1">(</span><span class="hl-2">channel</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">webhook</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">client</span><span class="hl-1">.</span><span class="hl-6">createWebhook</span><span class="hl-1">({ </span><span class="hl-2">url:</span><span class="hl-1"> </span><span class="hl-2">webhookUrl</span><span class="hl-1"> });</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">webhook</span><span class="hl-1">?.</span><span class="hl-2">id</span><span class="hl-1">) </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">`webhook_id_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, </span><span class="hl-2">webhook</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Start initial sync</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">cursor:</span><span class="hl-1"> </span><span class="hl-4">null</span><span class="hl-1">, </span><span class="hl-2">batchNumber:</span><span class="hl-1"> </span><span class="hl-14">1</span><span class="hl-1">, </span><span class="hl-2">initialSync:</span><span class="hl-1"> </span><span class="hl-4">true</span><span class="hl-1">,</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">batch</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">syncBatch</span><span class="hl-1">, </span><span class="hl-2">channel</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">tasks</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">batch</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">onChannelDisabled</span><span class="hl-1">(</span><span class="hl-2">channel</span><span class="hl-1">: </span><span class="hl-5">Channel</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-5">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">webhookId</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">string</span><span class="hl-1">&gt;(</span><span class="hl-3">`webhook_id_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">webhookId</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">try</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">client</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">getClient</span><span class="hl-1">(</span><span class="hl-2">channel</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">client</span><span class="hl-1">.</span><span class="hl-6">deleteWebhook</span><span class="hl-1">(</span><span class="hl-2">webhookId</span><span class="hl-1">);</span><br/><span class="hl-1"> } </span><span class="hl-0">catch</span><span class="hl-1"> { </span><span class="hl-7">/* ignore */</span><span class="hl-1"> }</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">clear</span><span class="hl-1">(</span><span class="hl-3">`webhook_id_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">clear</span><span class="hl-1">(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-4">private</span><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">getClient</span><span class="hl-1">(</span><span class="hl-2">channelId</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">token</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">integrations</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">(</span><span class="hl-2">IssueSource</span><span class="hl-1">.</span><span class="hl-8">PROVIDER</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (!</span><span class="hl-2">token</span><span class="hl-1">) </span><span class="hl-0">throw</span><span class="hl-1"> </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Error</span><span class="hl-1">(</span><span class="hl-3">&quot;No auth token&quot;</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">return</span><span class="hl-1"> </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">LinearClient</span><span class="hl-1">({ </span><span class="hl-2">accessToken:</span><span class="hl-1"> </span><span class="hl-2">token</span><span class="hl-1">.</span><span class="hl-2">token</span><span class="hl-1"> });</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-4">private</span><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">syncBatch</span><span class="hl-1">(</span><span class="hl-2">channelId</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-5">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">state</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">any</span><span class="hl-1">&gt;(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channelId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (!</span><span class="hl-2">state</span><span class="hl-1">) </span><span class="hl-0">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">client</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">getClient</span><span class="hl-1">(</span><span class="hl-2">channelId</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">result</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">client</span><span class="hl-1">.</span><span class="hl-6">issues</span><span class="hl-1">({ </span><span class="hl-2">teamId:</span><span class="hl-1"> </span><span class="hl-2">channelId</span><span class="hl-1">, </span><span class="hl-2">after:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">cursor</span><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-0">for</span><span class="hl-1"> (</span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">issue</span><span class="hl-1"> </span><span class="hl-4">of</span><span class="hl-1"> </span><span class="hl-2">result</span><span class="hl-1">.</span><span class="hl-2">nodes</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">`linear:issue:</span><span class="hl-4">${</span><span class="hl-2">issue</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">`</span><span class="hl-4">${</span><span class="hl-2">issue</span><span class="hl-13">.</span><span class="hl-2">identifier</span><span class="hl-4">}</span><span class="hl-3">: </span><span class="hl-4">${</span><span class="hl-2">issue</span><span class="hl-13">.</span><span class="hl-2">title</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">done:</span><span class="hl-1"> </span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">completedAt</span><span class="hl-1"> ? </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Date</span><span class="hl-1">(</span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">completedAt</span><span class="hl-1">) : </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">meta:</span><span class="hl-1"> { </span><span class="hl-2">syncProvider:</span><span class="hl-1"> </span><span class="hl-3">&quot;linear&quot;</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-2">notes:</span><span class="hl-1"> [{</span><br/><span class="hl-1"> </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&quot;description&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">description</span><span class="hl-1"> || </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">links:</span><span class="hl-1"> </span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">url</span><span class="hl-1"> ? [{</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">LinkType</span><span class="hl-1">.</span><span class="hl-2">external</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Open in Linear&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">url:</span><span class="hl-1"> </span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">url</span><span class="hl-1">,</span><br/><span class="hl-1"> }] : </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1"> }],</span><br/><span class="hl-1"> ...(</span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">initialSync</span><span class="hl-1"> ? { </span><span class="hl-2">unread:</span><span class="hl-1"> </span><span class="hl-4">false</span><span class="hl-1"> } : {}),</span><br/><span class="hl-1"> ...(</span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">initialSync</span><span class="hl-1"> ? { </span><span class="hl-2">archived:</span><span class="hl-1"> </span><span class="hl-4">false</span><span class="hl-1"> } : {}),</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">result</span><span class="hl-1">.</span><span class="hl-2">pageInfo</span><span class="hl-1">.</span><span class="hl-2">hasNextPage</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channelId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">cursor:</span><span class="hl-1"> </span><span class="hl-2">result</span><span class="hl-1">.</span><span class="hl-2">pageInfo</span><span class="hl-1">.</span><span class="hl-2">endCursor</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">batchNumber:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">batchNumber</span><span class="hl-1"> + </span><span class="hl-14">1</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">initialSync:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">initialSync</span><span class="hl-1">,</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">next</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">syncBatch</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">tasks</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">next</span><span class="hl-1">);</span><br/><span class="hl-1"> } </span><span class="hl-0">else</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">clear</span><span class="hl-1">(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channelId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-4">private</span><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">onWebhook</span><span class="hl-1">(</span><span class="hl-2">request</span><span class="hl-1">: </span><span class="hl-5">WebhookRequest</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-5">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">payload</span><span class="hl-1"> = </span><span class="hl-8">JSON</span><span class="hl-1">.</span><span class="hl-6">parse</span><span class="hl-1">(</span><span class="hl-2">request</span><span class="hl-1">.</span><span class="hl-2">rawBody</span><span class="hl-1"> || </span><span class="hl-3">&quot;{}&quot;</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">payload</span><span class="hl-1">.</span><span class="hl-2">type</span><span class="hl-1"> !== </span><span class="hl-3">&quot;Issue&quot;</span><span class="hl-1">) </span><span class="hl-0">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">issue</span><span class="hl-1"> = </span><span class="hl-2">payload</span><span class="hl-1">.</span><span class="hl-2">data</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">`linear:issue:</span><span class="hl-4">${</span><span class="hl-2">issue</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">`</span><span class="hl-4">${</span><span class="hl-2">issue</span><span class="hl-13">.</span><span class="hl-2">identifier</span><span class="hl-4">}</span><span class="hl-3">: </span><span class="hl-4">${</span><span class="hl-2">issue</span><span class="hl-13">.</span><span class="hl-2">title</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">done:</span><span class="hl-1"> </span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">completedAt</span><span class="hl-1"> ? </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Date</span><span class="hl-1">(</span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">completedAt</span><span class="hl-1">) : </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">meta:</span><span class="hl-1"> { </span><span class="hl-2">syncProvider:</span><span class="hl-1"> </span><span class="hl-3">&quot;linear&quot;</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-2">notes:</span><span class="hl-1"> [{</span><br/><span class="hl-1"> </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&quot;description&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">description</span><span class="hl-1"> || </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1"> }],</span><br/><span class="hl-1"> </span><span class="hl-7">// Incremental sync: omit unread and archived</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
121
+ </code><button type="button">Copy</button></pre>
122
+
123
+ <hr>
124
+ <h2 id="best-practices" class="tsd-anchor-link">Best Practices<a href="#best-practices" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><h3 id="1-always-inject-sync-metadata" class="tsd-anchor-link">1. Always Inject Sync Metadata<a href="#1-always-inject-sync-metadata" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Every synced activity must include <code>syncProvider</code> and <code>channelId</code> in <code>meta</code> for bulk operations (e.g., archiving all activities when a channel is disabled).</p>
125
+ <h3 id="2-use-canonical-source-urls" class="tsd-anchor-link">2. Use Canonical Source URLs<a href="#2-use-canonical-source-urls" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Use immutable IDs in <code>Activity.source</code> for deduplication. For services with mutable identifiers (like Jira issue keys), use the immutable ID in <code>source</code> and store the mutable key in <code>meta</code>.</p>
126
+ <h3 id="3-handle-html-content-correctly" class="tsd-anchor-link">3. Handle HTML Content Correctly<a href="#3-handle-html-content-correctly" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Never strip HTML tags locally. Pass raw HTML with <code>contentType: &quot;html&quot;</code> for server-side markdown conversion.</p>
127
+ <h3 id="4-add-localhost-guard-for-webhooks" class="tsd-anchor-link">4. Add Localhost Guard for Webhooks<a href="#4-add-localhost-guard-for-webhooks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Skip webhook registration in development when the URL contains &quot;localhost&quot;.</p>
128
+ <h3 id="5-maintain-callback-backward-compatibility" class="tsd-anchor-link">5. Maintain Callback Backward Compatibility<a href="#5-maintain-callback-backward-compatibility" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>All callbacks automatically upgrade to new source versions. Only add optional parameters at the end of callback method signatures.</p>
129
+ <h3 id="6-clean-up-on-disable" class="tsd-anchor-link">6. Clean Up on Disable<a href="#6-clean-up-on-disable" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Delete webhooks, callbacks, and stored state in <code>onChannelDisabled()</code>.</p>
130
+ <hr>
131
+ <h2 id="next-steps" class="tsd-anchor-link">Next Steps<a href="#next-steps" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><ul>
132
+ <li><strong><a href="../media/AGENTS.md">Source Development Guide</a></strong> - Comprehensive scaffold, patterns, and checklist</li>
133
+ <li><strong><a href="../media/SYNC_STRATEGIES.md">Sync Strategies</a></strong> - Deduplication, upserts, and tag management</li>
134
+ <li><strong><a href="Built-in_Tools.html">Built-in Tools Guide</a></strong> - Complete reference for Plot, Store, Integrations, and more</li>
135
+ <li><strong><a href="../media/MULTI_USER_AUTH.md">Multi-User Auth</a></strong> - Per-user auth for write-backs</li>
136
+ </ul>
137
+ </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#building-sources"><span>Building <wbr/>Sources</span></a><ul><li><a href="#table-of-contents"><span>Table of <wbr/>Contents</span></a></li><li><a href="#sources-vs-twists"><span>Sources vs <wbr/>Twists</span></a></li><li><a href="#source-structure"><span>Source <wbr/>Structure</span></a></li><li><ul><li><a href="#package-structure"><span>Package <wbr/>Structure</span></a></li></ul></li><li><a href="#oauth-and-channel-lifecycle"><span>O<wbr/>Auth and <wbr/>Channel <wbr/>Lifecycle</span></a></li><li><ul><li><a href="#how-it-works"><span>How <wbr/>It <wbr/>Works</span></a></li><li><a href="#getchannels"><span>get<wbr/>Channels</span></a></li><li><a href="#onchannelenabled"><span>on<wbr/>Channel<wbr/>Enabled</span></a></li><li><a href="#onchanneldisabled"><span>on<wbr/>Channel<wbr/>Disabled</span></a></li><li><a href="#getting-auth-tokens"><span>Getting <wbr/>Auth <wbr/>Tokens</span></a></li></ul></li><li><a href="#data-sync"><span>Data <wbr/>Sync</span></a></li><li><ul><li><a href="#transforming-external-items"><span>Transforming <wbr/>External <wbr/>Items</span></a></li><li><a href="#initial-vs-incremental-sync"><span>Initial vs <wbr/>Incremental <wbr/>Sync</span></a></li></ul></li><li><a href="#batch-processing"><span>Batch <wbr/>Processing</span></a></li><li><a href="#complete-example"><span>Complete <wbr/>Example</span></a></li><li><a href="#best-practices"><span>Best <wbr/>Practices</span></a></li><li><ul><li><a href="#1-always-inject-sync-metadata"><span>1. <wbr/>Always <wbr/>Inject <wbr/>Sync <wbr/>Metadata</span></a></li><li><a href="#2-use-canonical-source-urls"><span>2. <wbr/>Use <wbr/>Canonical <wbr/>Source <wbr/>UR<wbr/>Ls</span></a></li><li><a href="#3-handle-html-content-correctly"><span>3. <wbr/>Handle <wbr/>HTML <wbr/>Content <wbr/>Correctly</span></a></li><li><a href="#4-add-localhost-guard-for-webhooks"><span>4. <wbr/>Add <wbr/>Localhost <wbr/>Guard for <wbr/>Webhooks</span></a></li><li><a href="#5-maintain-callback-backward-compatibility"><span>5. <wbr/>Maintain <wbr/>Callback <wbr/>Backward <wbr/>Compatibility</span></a></li><li><a href="#6-clean-up-on-disable"><span>6. <wbr/>Clean <wbr/>Up on <wbr/>Disable</span></a></li></ul></li><li><a href="#next-steps"><span>Next <wbr/>Steps</span></a></li></ul></div></details></div><div class="site-menu"><nav id="tsd-sidebar-links" class="tsd-navigation"><a href="https://plot.day" class="tsd-nav-link">Plot</a><a href="https://github.com/plotday/plot" class="tsd-nav-link">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister" class="tsd-nav-link">NPM</a></nav><nav class="tsd-navigation"><a href="../modules.html">Creating Plot Twists</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
package/dist/docs/documents/Built-in_Tools.html CHANGED
@@ -222,10 +222,19 @@
222
222
  <h3 id="real-world-example-email-triage" class="tsd-anchor-link">Real-World Example: Email Triage<a href="#real-world-example-email-triage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Type</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;typebox&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">triageEmail</span><span class="hl-1">(</span><span class="hl-2">emailContent</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">schema</span><span class="hl-1"> = </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Object</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">category:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Union</span><span class="hl-1">([</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;urgent&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;important&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;informational&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;spam&quot;</span><span class="hl-1">)</span><br/><span class="hl-1"> ]),</span><br/><span class="hl-1"> </span><span class="hl-2">requiresResponse:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Boolean</span><span class="hl-1">(),</span><br/><span class="hl-1"> </span><span class="hl-2">suggestedActions:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Array</span><span class="hl-1">(</span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">String</span><span class="hl-1">()),</span><br/><span class="hl-1"> </span><span class="hl-2">summary:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">String</span><span class="hl-1">({ </span><span class="hl-2">maxLength:</span><span class="hl-1"> </span><span class="hl-14">200</span><span class="hl-1"> })</span><br/><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">response</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">ai</span><span class="hl-1">.</span><span class="hl-6">prompt</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">model:</span><span class="hl-1"> { </span><span class="hl-2">speed:</span><span class="hl-1"> </span><span class="hl-3">&quot;balanced&quot;</span><span class="hl-1">, </span><span class="hl-2">cost:</span><span class="hl-1"> </span><span class="hl-3">&quot;medium&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-2">prompt:</span><span class="hl-1"> </span><span class="hl-3">`Analyze this email and provide triage information:</span><span class="hl-12">\n\n</span><span class="hl-4">${</span><span class="hl-2">emailContent</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">outputSchema:</span><span class="hl-1"> </span><span class="hl-2">schema</span><br/><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Create activity based on triage</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">response</span><span class="hl-1">.</span><span class="hl-2">output</span><span class="hl-1">.</span><span class="hl-2">category</span><span class="hl-1"> === </span><span class="hl-3">&quot;urgent&quot;</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">`URGENT: </span><span class="hl-4">${</span><span class="hl-2">response</span><span class="hl-13">.</span><span class="hl-2">output</span><span class="hl-13">.</span><span class="hl-2">summary</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">note:</span><span class="hl-1"> </span><span class="hl-3">`Actions:</span><span class="hl-12">\n</span><span class="hl-4">${</span><span class="hl-2">response</span><span class="hl-13">.</span><span class="hl-2">output</span><span class="hl-13">.</span><span class="hl-2">suggestedActions</span><span class="hl-13">.</span><span class="hl-6">join</span><span class="hl-13">(</span><span class="hl-3">&quot;</span><span class="hl-12">\n</span><span class="hl-3">&quot;</span><span class="hl-13">)</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> ],</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
223
223
  </code><button type="button">Copy</button></pre>
224
224
 
225
+ <hr>
226
+ <h2 id="link-type-safety-pattern" class="tsd-anchor-link">Link Type Safety Pattern<a href="#link-type-safety-pattern" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>When defining <code>linkTypes</code> in your source's provider config, use <code>as const satisfies</code> to get type-safe status strings:</p>
227
+ <pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> { </span><span class="hl-2">LinkTypeConfig</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/integrations&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">LINK_TYPES</span><span class="hl-1"> = [</span><br/><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-3">&quot;issue&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">label:</span><span class="hl-1"> </span><span class="hl-3">&quot;Issue&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">logo:</span><span class="hl-1"> </span><span class="hl-3">&quot;https://api.iconify.design/simple-icons/linear.svg&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">statuses:</span><span class="hl-1"> [</span><br/><span class="hl-1"> { </span><span class="hl-2">status:</span><span class="hl-1"> </span><span class="hl-3">&quot;open&quot;</span><span class="hl-1">, </span><span class="hl-2">label:</span><span class="hl-1"> </span><span class="hl-3">&quot;Open&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> { </span><span class="hl-2">status:</span><span class="hl-1"> </span><span class="hl-3">&quot;done&quot;</span><span class="hl-1">, </span><span class="hl-2">label:</span><span class="hl-1"> </span><span class="hl-3">&quot;Done&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> ],</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-3">&quot;pull_request&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">label:</span><span class="hl-1"> </span><span class="hl-3">&quot;Pull Request&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">logo:</span><span class="hl-1"> </span><span class="hl-3">&quot;https://api.iconify.design/simple-icons/github.svg&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">statuses:</span><span class="hl-1"> [</span><br/><span class="hl-1"> { </span><span class="hl-2">status:</span><span class="hl-1"> </span><span class="hl-3">&quot;open&quot;</span><span class="hl-1">, </span><span class="hl-2">label:</span><span class="hl-1"> </span><span class="hl-3">&quot;Open&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> { </span><span class="hl-2">status:</span><span class="hl-1"> </span><span class="hl-3">&quot;merged&quot;</span><span class="hl-1">, </span><span class="hl-2">label:</span><span class="hl-1"> </span><span class="hl-3">&quot;Merged&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> { </span><span class="hl-2">status:</span><span class="hl-1"> </span><span class="hl-3">&quot;closed&quot;</span><span class="hl-1">, </span><span class="hl-2">label:</span><span class="hl-1"> </span><span class="hl-3">&quot;Closed&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> ],</span><br/><span class="hl-1"> },</span><br/><span class="hl-1">] </span><span class="hl-0">as</span><span class="hl-1"> </span><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-0">satisfies</span><span class="hl-1"> </span><span class="hl-5">LinkTypeConfig</span><span class="hl-1">[];</span><br/><br/><span class="hl-7">// Derive type-safe union types from the config</span><br/><span class="hl-4">type</span><span class="hl-1"> </span><span class="hl-5">IssueStatus</span><span class="hl-1"> = (</span><span class="hl-4">typeof</span><span class="hl-1"> </span><span class="hl-8">LINK_TYPES</span><span class="hl-1">)[</span><span class="hl-14">0</span><span class="hl-1">][</span><span class="hl-3">&quot;statuses&quot;</span><span class="hl-1">][</span><span class="hl-5">number</span><span class="hl-1">][</span><span class="hl-3">&quot;status&quot;</span><span class="hl-1">]; </span><span class="hl-7">// &quot;open&quot; | &quot;done&quot;</span><br/><span class="hl-4">type</span><span class="hl-1"> </span><span class="hl-5">PRStatus</span><span class="hl-1"> = (</span><span class="hl-4">typeof</span><span class="hl-1"> </span><span class="hl-8">LINK_TYPES</span><span class="hl-1">)[</span><span class="hl-14">1</span><span class="hl-1">][</span><span class="hl-3">&quot;statuses&quot;</span><span class="hl-1">][</span><span class="hl-5">number</span><span class="hl-1">][</span><span class="hl-3">&quot;status&quot;</span><span class="hl-1">]; </span><span class="hl-7">// &quot;open&quot; | &quot;merged&quot; | &quot;closed&quot;</span>
228
+ </code><button type="button">Copy</button></pre>
229
+
230
+ <p>Then reference <code>LINK_TYPES</code> in your provider config:</p>
231
+ <pre><code class="typescript"><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">build</span><span class="hl-1">: </span><span class="hl-2">SourceBuilder</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">return</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">integrations:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Integrations</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">providers:</span><span class="hl-1"> [{</span><br/><span class="hl-1"> </span><span class="hl-2">provider:</span><span class="hl-1"> </span><span class="hl-2">MySource</span><span class="hl-1">.</span><span class="hl-8">PROVIDER</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">scopes:</span><span class="hl-1"> </span><span class="hl-2">MySource</span><span class="hl-1">.</span><span class="hl-8">SCOPES</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">linkTypes:</span><span class="hl-1"> [...</span><span class="hl-8">LINK_TYPES</span><span class="hl-1">],</span><br/><span class="hl-1"> </span><span class="hl-7">// ...</span><br/><span class="hl-1"> }],</span><br/><span class="hl-1"> }),</span><br/><span class="hl-1"> };</span><br/><span class="hl-1">}</span>
232
+ </code><button type="button">Copy</button></pre>
233
+
225
234
  <hr>
226
235
  <h2 id="next-steps" class="tsd-anchor-link">Next Steps<a href="#next-steps" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><ul>
227
- <li><strong><a href="Building_Custom_Tools.html">Building Custom Tools</a></strong> - Create your own reusable tools</li>
236
+ <li><strong><a href="Building_Sources.html">Building Sources</a></strong> - Build external service integrations</li>
228
237
  <li><strong><a href="Runtime_Environment.html">Runtime Environment</a></strong> - Understanding execution constraints</li>
229
238
  <li><strong>API Reference</strong> - Explore detailed API docs in the sidebar</li>
230
239
  </ul>
231
- </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#built-in-tools"><span>Built-<wbr/>in <wbr/>Tools</span></a><ul><li><a href="#table-of-contents"><span>Table of <wbr/>Contents</span></a></li><li><a href="#plot"><span>Plot</span></a></li><li><ul><li><a href="#understanding-activities-and-notes"><span>Understanding <wbr/>Activities and <wbr/>Notes</span></a></li><li><a href="#setup"><span>Setup</span></a></li><li><a href="#creating-activities"><span>Creating <wbr/>Activities</span></a></li><li><ul><li><a href="#action-scheduling-states"><span>Action <wbr/>Scheduling <wbr/>States</span></a></li></ul></li><li><a href="#updating-activities"><span>Updating <wbr/>Activities</span></a></li><li><a href="#deleting-activities"><span>Deleting <wbr/>Activities</span></a></li><li><a href="#managing-priorities"><span>Managing <wbr/>Priorities</span></a></li><li><a href="#activity-data-synchronization"><span>Activity <wbr/>Data <wbr/>Synchronization</span></a></li><li><a href="#creating-and-managing-notes"><span>Creating and <wbr/>Managing <wbr/>Notes</span></a></li><li><ul><li><a href="#creating-notes-on-new-activities"><span>Creating <wbr/>Notes on <wbr/>New <wbr/>Activities</span></a></li><li><a href="#adding-notes-to-existing-activities"><span>Adding <wbr/>Notes to <wbr/>Existing <wbr/>Activities</span></a></li><li><a href="#pattern-email-threads-and-conversations"><span>Pattern: <wbr/>Email <wbr/>Threads and <wbr/>Conversations</span></a></li></ul></li></ul></li><li><a href="#store"><span>Store</span></a></li><li><ul><li><a href="#setup-1"><span>Setup</span></a></li><li><a href="#storing-data"><span>Storing <wbr/>Data</span></a></li><li><a href="#retrieving-data"><span>Retrieving <wbr/>Data</span></a></li><li><a href="#clearing-data"><span>Clearing <wbr/>Data</span></a></li><li><a href="#best-practices"><span>Best <wbr/>Practices</span></a></li><li><ul><li><a href="#type-safety"><span>Type <wbr/>Safety</span></a></li><li><a href="#namespacing"><span>Namespacing</span></a></li><li><a href="#serialization-limits"><span>Serialization <wbr/>Limits</span></a></li></ul></li></ul></li><li><a href="#integrations"><span>Integrations</span></a></li><li><ul><li><a href="#setup-2"><span>Setup</span></a></li><li><a href="#requesting-authentication"><span>Requesting <wbr/>Authentication</span></a></li><li><a href="#auth-providers"><span>Auth <wbr/>Providers</span></a></li><li><a href="#using-auth-tokens"><span>Using <wbr/>Auth <wbr/>Tokens</span></a></li></ul></li><li><a href="#tasks"><span>Tasks</span></a></li><li><ul><li><a href="#setup-3"><span>Setup</span></a></li><li><a href="#running-tasks-immediately"><span>Running <wbr/>Tasks <wbr/>Immediately</span></a></li><li><a href="#scheduling-tasks"><span>Scheduling <wbr/>Tasks</span></a></li><li><a href="#canceling-tasks"><span>Canceling <wbr/>Tasks</span></a></li><li><a href="#batch-processing-pattern"><span>Batch <wbr/>Processing <wbr/>Pattern</span></a></li></ul></li><li><a href="#network"><span>Network</span></a></li><li><ul><li><a href="#setup-4"><span>Setup</span></a></li><li><a href="#making-http-requests"><span>Making <wbr/>HTTP <wbr/>Requests</span></a></li><li><a href="#creating-webhooks"><span>Creating <wbr/>Webhooks</span></a></li><li><a href="#deleting-webhooks"><span>Deleting <wbr/>Webhooks</span></a></li></ul></li><li><a href="#callbacks"><span>Callbacks</span></a></li><li><ul><li><a href="#setup-5"><span>Setup</span></a></li><li><a href="#creating-callbacks"><span>Creating <wbr/>Callbacks</span></a></li><li><a href="#executing-callbacks"><span>Executing <wbr/>Callbacks</span></a></li><li><a href="#method-signature"><span>Method <wbr/>Signature</span></a></li><li><a href="#callback-versioning-and-upgrades"><span>Callback <wbr/>Versioning and <wbr/>Upgrades</span></a></li><li><ul><li><a href="#handling-version-transitions"><span>Handling <wbr/>Version <wbr/>Transitions</span></a></li><li><a href="#affected-callback-types"><span>Affected <wbr/>Callback <wbr/>Types</span></a></li><li><a href="#migration-in-upgrade"><span>Migration in upgrade()</span></a></li></ul></li><li><a href="#deleting-callbacks"><span>Deleting <wbr/>Callbacks</span></a></li><li><a href="#use-cases"><span>Use <wbr/>Cases</span></a></li></ul></li><li><a href="#ai"><span>AI</span></a></li><li><ul><li><a href="#setup-6"><span>Setup</span></a></li><li><a href="#simple-text-generation"><span>Simple <wbr/>Text <wbr/>Generation</span></a></li><li><a href="#structured-output"><span>Structured <wbr/>Output</span></a></li><li><a href="#tool-calling"><span>Tool <wbr/>Calling</span></a></li><li><a href="#multi-turn-conversations"><span>Multi-<wbr/>turn <wbr/>Conversations</span></a></li><li><a href="#model-selection"><span>Model <wbr/>Selection</span></a></li><li><a href="#typebox-schemas"><span>Typebox <wbr/>Schemas</span></a></li><li><a href="#real-world-example-email-triage"><span>Real-<wbr/>World <wbr/>Example: <wbr/>Email <wbr/>Triage</span></a></li></ul></li><li><a href="#next-steps"><span>Next <wbr/>Steps</span></a></li></ul></div></details></div><div class="site-menu"><nav id="tsd-sidebar-links" class="tsd-navigation"><a href="https://plot.day" class="tsd-nav-link">Plot</a><a href="https://github.com/plotday/plot" class="tsd-nav-link">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister" class="tsd-nav-link">NPM</a></nav><nav class="tsd-navigation"><a href="../modules.html">Creating Plot Twists</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
240
+ </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#built-in-tools"><span>Built-<wbr/>in <wbr/>Tools</span></a><ul><li><a href="#table-of-contents"><span>Table of <wbr/>Contents</span></a></li><li><a href="#plot"><span>Plot</span></a></li><li><ul><li><a href="#understanding-activities-and-notes"><span>Understanding <wbr/>Activities and <wbr/>Notes</span></a></li><li><a href="#setup"><span>Setup</span></a></li><li><a href="#creating-activities"><span>Creating <wbr/>Activities</span></a></li><li><ul><li><a href="#action-scheduling-states"><span>Action <wbr/>Scheduling <wbr/>States</span></a></li></ul></li><li><a href="#updating-activities"><span>Updating <wbr/>Activities</span></a></li><li><a href="#deleting-activities"><span>Deleting <wbr/>Activities</span></a></li><li><a href="#managing-priorities"><span>Managing <wbr/>Priorities</span></a></li><li><a href="#activity-data-synchronization"><span>Activity <wbr/>Data <wbr/>Synchronization</span></a></li><li><a href="#creating-and-managing-notes"><span>Creating and <wbr/>Managing <wbr/>Notes</span></a></li><li><ul><li><a href="#creating-notes-on-new-activities"><span>Creating <wbr/>Notes on <wbr/>New <wbr/>Activities</span></a></li><li><a href="#adding-notes-to-existing-activities"><span>Adding <wbr/>Notes to <wbr/>Existing <wbr/>Activities</span></a></li><li><a href="#pattern-email-threads-and-conversations"><span>Pattern: <wbr/>Email <wbr/>Threads and <wbr/>Conversations</span></a></li></ul></li></ul></li><li><a href="#store"><span>Store</span></a></li><li><ul><li><a href="#setup-1"><span>Setup</span></a></li><li><a href="#storing-data"><span>Storing <wbr/>Data</span></a></li><li><a href="#retrieving-data"><span>Retrieving <wbr/>Data</span></a></li><li><a href="#clearing-data"><span>Clearing <wbr/>Data</span></a></li><li><a href="#best-practices"><span>Best <wbr/>Practices</span></a></li><li><ul><li><a href="#type-safety"><span>Type <wbr/>Safety</span></a></li><li><a href="#namespacing"><span>Namespacing</span></a></li><li><a href="#serialization-limits"><span>Serialization <wbr/>Limits</span></a></li></ul></li></ul></li><li><a href="#integrations"><span>Integrations</span></a></li><li><ul><li><a href="#setup-2"><span>Setup</span></a></li><li><a href="#requesting-authentication"><span>Requesting <wbr/>Authentication</span></a></li><li><a href="#auth-providers"><span>Auth <wbr/>Providers</span></a></li><li><a href="#using-auth-tokens"><span>Using <wbr/>Auth <wbr/>Tokens</span></a></li></ul></li><li><a href="#tasks"><span>Tasks</span></a></li><li><ul><li><a href="#setup-3"><span>Setup</span></a></li><li><a href="#running-tasks-immediately"><span>Running <wbr/>Tasks <wbr/>Immediately</span></a></li><li><a href="#scheduling-tasks"><span>Scheduling <wbr/>Tasks</span></a></li><li><a href="#canceling-tasks"><span>Canceling <wbr/>Tasks</span></a></li><li><a href="#batch-processing-pattern"><span>Batch <wbr/>Processing <wbr/>Pattern</span></a></li></ul></li><li><a href="#network"><span>Network</span></a></li><li><ul><li><a href="#setup-4"><span>Setup</span></a></li><li><a href="#making-http-requests"><span>Making <wbr/>HTTP <wbr/>Requests</span></a></li><li><a href="#creating-webhooks"><span>Creating <wbr/>Webhooks</span></a></li><li><a href="#deleting-webhooks"><span>Deleting <wbr/>Webhooks</span></a></li></ul></li><li><a href="#callbacks"><span>Callbacks</span></a></li><li><ul><li><a href="#setup-5"><span>Setup</span></a></li><li><a href="#creating-callbacks"><span>Creating <wbr/>Callbacks</span></a></li><li><a href="#executing-callbacks"><span>Executing <wbr/>Callbacks</span></a></li><li><a href="#method-signature"><span>Method <wbr/>Signature</span></a></li><li><a href="#callback-versioning-and-upgrades"><span>Callback <wbr/>Versioning and <wbr/>Upgrades</span></a></li><li><ul><li><a href="#handling-version-transitions"><span>Handling <wbr/>Version <wbr/>Transitions</span></a></li><li><a href="#affected-callback-types"><span>Affected <wbr/>Callback <wbr/>Types</span></a></li><li><a href="#migration-in-upgrade"><span>Migration in upgrade()</span></a></li></ul></li><li><a href="#deleting-callbacks"><span>Deleting <wbr/>Callbacks</span></a></li><li><a href="#use-cases"><span>Use <wbr/>Cases</span></a></li></ul></li><li><a href="#ai"><span>AI</span></a></li><li><ul><li><a href="#setup-6"><span>Setup</span></a></li><li><a href="#simple-text-generation"><span>Simple <wbr/>Text <wbr/>Generation</span></a></li><li><a href="#structured-output"><span>Structured <wbr/>Output</span></a></li><li><a href="#tool-calling"><span>Tool <wbr/>Calling</span></a></li><li><a href="#multi-turn-conversations"><span>Multi-<wbr/>turn <wbr/>Conversations</span></a></li><li><a href="#model-selection"><span>Model <wbr/>Selection</span></a></li><li><a href="#typebox-schemas"><span>Typebox <wbr/>Schemas</span></a></li><li><a href="#real-world-example-email-triage"><span>Real-<wbr/>World <wbr/>Example: <wbr/>Email <wbr/>Triage</span></a></li></ul></li><li><a href="#link-type-safety-pattern"><span>Link <wbr/>Type <wbr/>Safety <wbr/>Pattern</span></a></li><li><a href="#next-steps"><span>Next <wbr/>Steps</span></a></li></ul></div></details></div><div class="site-menu"><nav id="tsd-sidebar-links" class="tsd-navigation"><a href="https://plot.day" class="tsd-nav-link">Plot</a><a href="https://github.com/plotday/plot" class="tsd-nav-link">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister" class="tsd-nav-link">NPM</a></nav><nav class="tsd-navigation"><a href="../modules.html">Creating Plot Twists</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>