@plotday/twister 0.20.0 → 0.22.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 (95) hide show
  1. package/README.md +5 -5
  2. package/bin/templates/AGENTS.template.md +5 -5
  3. package/bin/templates/README.template.md +1 -1
  4. package/cli/templates/AGENTS.template.md +5 -5
  5. package/cli/templates/README.template.md +1 -1
  6. package/dist/common/calendar.d.ts +4 -4
  7. package/dist/common/calendar.d.ts.map +1 -1
  8. package/dist/common/messaging.d.ts +8 -7
  9. package/dist/common/messaging.d.ts.map +1 -1
  10. package/dist/docs/assets/hierarchy.js +1 -1
  11. package/dist/docs/assets/highlight.css +8 -8
  12. package/dist/docs/assets/navigation.js +1 -1
  13. package/dist/docs/assets/search.js +1 -1
  14. package/dist/docs/classes/tool.ITool.html +1 -1
  15. package/dist/docs/classes/tool.Tool.html +1 -1
  16. package/dist/docs/classes/tools_ai.AI.html +3 -3
  17. package/dist/docs/classes/tools_callbacks.Callbacks.html +1 -1
  18. package/dist/docs/classes/tools_integrations.Integrations.html +1 -1
  19. package/dist/docs/classes/tools_network.Network.html +1 -1
  20. package/dist/docs/classes/tools_plot.Plot.html +52 -31
  21. package/dist/docs/classes/tools_store.Store.html +1 -1
  22. package/dist/docs/classes/tools_tasks.Tasks.html +2 -2
  23. package/dist/docs/classes/tools_twists.Twists.html +6 -6
  24. package/dist/docs/classes/twist.Twist.html +1 -1
  25. package/dist/docs/documents/Building_Custom_Tools.html +8 -9
  26. package/dist/docs/documents/Built-in_Tools.html +26 -14
  27. package/dist/docs/documents/Core_Concepts.html +27 -9
  28. package/dist/docs/documents/Getting_Started.html +12 -3
  29. package/dist/docs/documents/Runtime_Environment.html +8 -9
  30. package/dist/docs/enums/plot.ActivityType.html +3 -3
  31. package/dist/docs/enums/plot.ActorType.html +4 -4
  32. package/dist/docs/enums/tools_plot.ActivityAccess.html +6 -6
  33. package/dist/docs/enums/tools_plot.ContactAccess.html +3 -3
  34. package/dist/docs/enums/tools_plot.PriorityAccess.html +3 -3
  35. package/dist/docs/functions/utils_hash.quickHash.html +1 -0
  36. package/dist/docs/hierarchy.html +1 -1
  37. package/dist/docs/index.html +2 -11
  38. package/dist/docs/interfaces/common_calendar.CalendarTool.html +5 -5
  39. package/dist/docs/interfaces/tools_ai.AIRequest.html +4 -4
  40. package/dist/docs/modules/index.html +1 -1
  41. package/dist/docs/modules/plot.html +1 -1
  42. package/dist/docs/modules/tools_plot.html +1 -1
  43. package/dist/docs/modules/utils_hash.html +1 -0
  44. package/dist/docs/modules.html +1 -1
  45. package/dist/docs/types/plot.Activity.html +16 -52
  46. package/dist/docs/types/plot.ActivityCommon.html +20 -0
  47. package/dist/docs/types/plot.ActivityUpdate.html +2 -8
  48. package/dist/docs/types/plot.ActivityWithNotes.html +1 -0
  49. package/dist/docs/types/plot.Actor.html +5 -5
  50. package/dist/docs/types/plot.NewActivity.html +3 -3
  51. package/dist/docs/types/plot.NewActivityWithNotes.html +1 -0
  52. package/dist/docs/types/plot.NewContact.html +4 -4
  53. package/dist/docs/types/plot.NewNote.html +10 -0
  54. package/dist/docs/types/plot.Note.html +7 -0
  55. package/dist/docs/types/plot.NoteType.html +1 -1
  56. package/dist/docs/types/plot.NoteUpdate.html +14 -0
  57. package/dist/docs/types/plot.PickPriorityConfig.html +3 -3
  58. package/dist/docs/types/tools_network.WebhookRequest.html +1 -1
  59. package/dist/docs/types/{tools_plot.ActivityIntentHandler.html → tools_plot.NoteIntentHandler.html} +5 -5
  60. package/dist/llm-docs/common/calendar.d.ts +1 -1
  61. package/dist/llm-docs/common/calendar.d.ts.map +1 -1
  62. package/dist/llm-docs/common/calendar.js +1 -1
  63. package/dist/llm-docs/common/calendar.js.map +1 -1
  64. package/dist/llm-docs/common/messaging.d.ts +1 -1
  65. package/dist/llm-docs/common/messaging.d.ts.map +1 -1
  66. package/dist/llm-docs/common/messaging.js +1 -1
  67. package/dist/llm-docs/common/messaging.js.map +1 -1
  68. package/dist/llm-docs/plot.d.ts +1 -1
  69. package/dist/llm-docs/plot.d.ts.map +1 -1
  70. package/dist/llm-docs/plot.js +1 -1
  71. package/dist/llm-docs/plot.js.map +1 -1
  72. package/dist/llm-docs/tools/plot.d.ts +1 -1
  73. package/dist/llm-docs/tools/plot.d.ts.map +1 -1
  74. package/dist/llm-docs/tools/plot.js +1 -1
  75. package/dist/llm-docs/tools/plot.js.map +1 -1
  76. package/dist/llm-docs/twist-guide-template.d.ts +1 -1
  77. package/dist/llm-docs/twist-guide-template.d.ts.map +1 -1
  78. package/dist/llm-docs/twist-guide-template.js +1 -1
  79. package/dist/llm-docs/twist-guide-template.js.map +1 -1
  80. package/dist/plot.d.ts +80 -38
  81. package/dist/plot.d.ts.map +1 -1
  82. package/dist/plot.js +1 -1
  83. package/dist/plot.js.map +1 -1
  84. package/dist/tools/plot.d.ts +118 -29
  85. package/dist/tools/plot.d.ts.map +1 -1
  86. package/dist/tools/plot.js +4 -4
  87. package/dist/tools/plot.js.map +1 -1
  88. package/dist/twist-guide.d.ts +1 -1
  89. package/dist/twist-guide.d.ts.map +1 -1
  90. package/dist/utils/hash.d.ts +2 -0
  91. package/dist/utils/hash.d.ts.map +1 -0
  92. package/dist/utils/hash.js +9 -0
  93. package/dist/utils/hash.js.map +1 -0
  94. package/package.json +5 -1
  95. package/dist/docs/documents/Advanced.html +0 -91
package/dist/docs/documents/Core_Concepts.html CHANGED
@@ -16,7 +16,7 @@
16
16
  <li>Responds to lifecycle events (<code>activate</code>, <code>deactivate</code>, <code>upgrade</code>)</li>
17
17
  <li>Can process activities and create new ones</li>
18
18
  </ul>
19
- <h3 id="twist-anatomy" class="tsd-anchor-link">Twist Anatomy<a href="#twist-anatomy" 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">Twist</span><span class="hl-1">, </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Priority</span><span class="hl-1">, </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">ToolBuilder</span><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><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/><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">MyTwist</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Twist</span><span class="hl-1">&lt;</span><span class="hl-5">MyTwist</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-7">// 1. Declare dependencies</span><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">ToolBuilder</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">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><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// 2. Initialize on activation</span><br/><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">activate</span><span class="hl-1">(</span><span class="hl-2">priority</span><span class="hl-1">: </span><span class="hl-5">Pick</span><span class="hl-1">&lt;</span><span class="hl-5">Priority</span><span class="hl-1">, </span><span class="hl-3">&quot;id&quot;</span><span class="hl-1">&gt;) {</span><br/><span class="hl-1"> </span><span class="hl-7">// Setup code - runs once when twist is added to a priority</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// 3. Handle lifecycle events</span><br/><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">upgrade</span><span class="hl-1">() {</span><br/><span class="hl-1"> </span><span class="hl-7">// Runs when a new version is deployed</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">deactivate</span><span class="hl-1">() {</span><br/><span class="hl-1"> </span><span class="hl-7">// Cleanup - runs when twist is removed</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
19
+ <h3 id="twist-anatomy" class="tsd-anchor-link">Twist Anatomy<a href="#twist-anatomy" 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-0">type</span><span class="hl-1"> </span><span class="hl-2">Priority</span><span class="hl-1">, </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">ToolBuilder</span><span class="hl-1">, </span><span class="hl-2">Twist</span><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><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/><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">MyTwist</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Twist</span><span class="hl-1">&lt;</span><span class="hl-5">MyTwist</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-7">// 1. Declare dependencies</span><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">ToolBuilder</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">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><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// 2. Initialize on activation</span><br/><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">activate</span><span class="hl-1">(</span><span class="hl-2">priority</span><span class="hl-1">: </span><span class="hl-5">Pick</span><span class="hl-1">&lt;</span><span class="hl-5">Priority</span><span class="hl-1">, </span><span class="hl-3">&quot;id&quot;</span><span class="hl-1">&gt;) {</span><br/><span class="hl-1"> </span><span class="hl-7">// Setup code - runs once when twist is added to a priority</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// 3. Handle lifecycle events</span><br/><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">upgrade</span><span class="hl-1">() {</span><br/><span class="hl-1"> </span><span class="hl-7">// Runs when a new version is deployed</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">deactivate</span><span class="hl-1">() {</span><br/><span class="hl-1"> </span><span class="hl-7">// Cleanup - runs when twist is removed</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
20
20
  </code><button type="button">Copy</button></pre>
21
21
 
22
22
  <h3 id="when-to-use-twists" class="tsd-anchor-link">When to Use Twists<a href="#when-to-use-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></h3><p>Use twists for:</p>
@@ -78,14 +78,14 @@
78
78
  <li><strong>Task</strong> - Actionable items that can be completed</li>
79
79
  <li><strong>Event</strong> - Scheduled occurrences with start/end times</li>
80
80
  </ul>
81
- <pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">ActivityType</span><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/><br/><span class="hl-7">// Note</span><br/><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">Note</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;Meeting notes from sync&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Task</span><br/><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">Task</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;Review pull request&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">doneAt:</span><span class="hl-1"> </span><span class="hl-4">null</span><span class="hl-1">, </span><span class="hl-7">// null = not done</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Event</span><br/><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">Event</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;Team standup&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">start:</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-3">&quot;2025-02-01T10:00:00Z&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">end:</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-3">&quot;2025-02-01T10:30:00Z&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">});</span>
81
+ <pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">ActivityType</span><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/><br/><span class="hl-7">// Note</span><br/><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">Note</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;Meeting notes from sync&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Task</span><br/><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">&quot;Review pull request&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">doneAt:</span><span class="hl-1"> </span><span class="hl-4">null</span><span class="hl-1">, </span><span class="hl-7">// null = not done</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Event</span><br/><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">Event</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;Team standup&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">start:</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-3">&quot;2025-02-01T10:00:00Z&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">end:</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-3">&quot;2025-02-01T10:30:00Z&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">});</span>
82
82
  </code><button type="button">Copy</button></pre>
83
83
 
84
- <h3 id="activity-properties" class="tsd-anchor-link">Activity Properties<a href="#activity-properties" 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-4">type</span><span class="hl-1"> </span><span class="hl-5">Activity</span><span class="hl-1"> = {</span><br/><span class="hl-1"> </span><span class="hl-2">id</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1">; </span><span class="hl-7">// Unique identifier</span><br/><span class="hl-1"> </span><span class="hl-2">type</span><span class="hl-1">: </span><span class="hl-5">ActivityType</span><span class="hl-1">; </span><span class="hl-7">// Note, Task, or Event</span><br/><span class="hl-1"> </span><span class="hl-2">title</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Display title</span><br/><span class="hl-1"> </span><span class="hl-2">note</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Additional details</span><br/><span class="hl-1"> </span><span class="hl-2">start</span><span class="hl-1">: </span><span class="hl-5">Date</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Event start time</span><br/><span class="hl-1"> </span><span class="hl-2">end</span><span class="hl-1">: </span><span class="hl-5">Date</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Event end time</span><br/><span class="hl-1"> </span><span class="hl-2">doneAt</span><span class="hl-1">: </span><span class="hl-5">Date</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Task completion time</span><br/><span class="hl-1"> </span><span class="hl-2">links</span><span class="hl-1">: </span><span class="hl-5">ActivityLink</span><span class="hl-1">[]; </span><span class="hl-7">// Action links</span><br/><span class="hl-1"> </span><span class="hl-2">tags</span><span class="hl-1">: </span><span class="hl-5">Record</span><span class="hl-1">&lt;</span><span class="hl-5">Tag</span><span class="hl-1">, </span><span class="hl-5">ActorId</span><span class="hl-1">[]&gt;; </span><span class="hl-7">// Tag assignments</span><br/><span class="hl-1"> </span><span class="hl-7">// ... and more</span><br/><span class="hl-1">};</span>
84
+ <h3 id="activity-properties" class="tsd-anchor-link">Activity Properties<a href="#activity-properties" 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-4">type</span><span class="hl-1"> </span><span class="hl-5">Activity</span><span class="hl-1"> = {</span><br/><span class="hl-1"> </span><span class="hl-2">id</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1">; </span><span class="hl-7">// Unique identifier</span><br/><span class="hl-1"> </span><span class="hl-2">type</span><span class="hl-1">: </span><span class="hl-5">ActivityType</span><span class="hl-1">; </span><span class="hl-7">// Note, Task, or Event</span><br/><span class="hl-1"> </span><span class="hl-2">title</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Display title</span><br/><span class="hl-1"> </span><span class="hl-2">preview</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Brief preview text</span><br/><span class="hl-1"> </span><span class="hl-2">start</span><span class="hl-1">: </span><span class="hl-5">Date</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Event start time</span><br/><span class="hl-1"> </span><span class="hl-2">end</span><span class="hl-1">: </span><span class="hl-5">Date</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Event end time</span><br/><span class="hl-1"> </span><span class="hl-2">doneAt</span><span class="hl-1">: </span><span class="hl-5">Date</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">; </span><span class="hl-7">// Task completion time</span><br/><span class="hl-1"> </span><span class="hl-2">tags</span><span class="hl-1">: </span><span class="hl-5">Record</span><span class="hl-1">&lt;</span><span class="hl-5">Tag</span><span class="hl-1">, </span><span class="hl-5">ActorId</span><span class="hl-1">[]&gt;; </span><span class="hl-7">// Tag assignments</span><br/><span class="hl-1"> </span><span class="hl-7">// ... and more</span><br/><span class="hl-1">};</span>
85
85
  </code><button type="button">Copy</button></pre>
86
86
 
87
- <h3 id="activity-links" class="tsd-anchor-link">Activity Links<a href="#activity-links" 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>Links enable user interaction with activities:</p>
88
- <pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">ActivityLinkType</span><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/><br/><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">Task</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;Fix bug #123&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">links:</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-2">ActivityLinkType</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;View Issue&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-3">&quot;https://github.com/org/repo/issues/123&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-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityLinkType</span><span class="hl-1">.</span><span class="hl-2">callback</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;Mark as Fixed&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">callback:</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-3">&quot;markAsFixed&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;123&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>
87
+ <h3 id="activity-notes" class="tsd-anchor-link">Activity Notes<a href="#activity-notes" 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>Activities can have multiple Notes attached to them. Notes contain detailed content and links:</p>
88
+ <pre><code class="typescript"><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">&quot;Fix bug #123&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">preview:</span><span class="hl-1"> </span><span class="hl-3">&quot;Critical bug affecting login flow&quot;</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">&quot;Users are unable to log in with SSO. Error occurs in auth middleware.&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">links:</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-2">ActivityLinkType</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;View Issue&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-3">&quot;https://github.com/org/repo/issues/123&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-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityLinkType</span><span class="hl-1">.</span><span class="hl-2">callback</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;Mark as Fixed&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">callback:</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-3">&quot;markAsFixed&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;123&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><br/><span class="hl-1">});</span>
89
89
  </code><button type="button">Copy</button></pre>
90
90
 
91
91
  <p><strong>Link Types:</strong></p>
@@ -93,7 +93,26 @@
93
93
  <li><strong>external</strong> - Opens URL in browser</li>
94
94
  <li><strong>auth</strong> - Initiates OAuth flow</li>
95
95
  <li><strong>callback</strong> - Triggers twist method when clicked</li>
96
+ <li><strong>conferencing</strong> - Video conferencing links (Zoom, Meet, Teams, etc.)</li>
96
97
  </ul>
98
+ <h3 id="best-practices-for-activities-and-notes" class="tsd-anchor-link">Best Practices for Activities and Notes<a href="#best-practices-for-activities-and-notes" 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><h4 id="always-create-activities-with-an-initial-note" class="tsd-anchor-link">Always Create Activities with an Initial Note<a href="#always-create-activities-with-an-initial-note" 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></h4><p><strong>In most cases, an Activity should be created with at least one initial Note.</strong> The Activity's <code>title</code> and <code>preview</code> are just short summaries that may be truncated in the UI. Detailed information, context, and links should always go in Notes.</p>
99
+ <pre><code class="typescript"><span class="hl-7">// ✅ GOOD - Activity with detailed Note</span><br/><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">&quot;Review PR #456&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">preview:</span><span class="hl-1"> </span><span class="hl-3">&quot;New authentication feature&quot;</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">&quot;Please review the OAuth 2.0 implementation. Key changes include:</span><span class="hl-12">\n</span><span class="hl-3">- Token refresh logic</span><span class="hl-12">\n</span><span class="hl-3">- Session management</span><span class="hl-12">\n</span><span class="hl-3">- Error handling for expired tokens&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">links:</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-2">ActivityLinkType</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;View PR&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-3">&quot;https://github.com/org/repo/pull/456&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><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// ❌ BAD - Relying only on title and preview</span><br/><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><br/><span class="hl-1"> </span><span class="hl-3">&quot;Review PR #456 - OAuth implementation with token refresh and session management&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">preview:</span><span class="hl-1"> </span><span class="hl-3">&quot;New authentication feature with detailed changes&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-7">// Missing Notes with full context</span><br/><span class="hl-1">});</span>
100
+ </code><button type="button">Copy</button></pre>
101
+
102
+ <p><strong>Why?</strong> The title may be truncated when viewing Activity Notes, and detailed information is essential for understanding the full context.</p>
103
+ <h4 id="add-notes-to-existing-activities-for-related-content" class="tsd-anchor-link">Add Notes to Existing Activities for Related Content<a href="#add-notes-to-existing-activities-for-related-content" 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></h4><p><strong>Wherever possible, related messages should be added to an existing Activity rather than creating a new Activity.</strong> This keeps conversations, workflows, and related information together.</p>
104
+ <p><strong>Use this pattern for:</strong></p>
105
+ <ul>
106
+ <li><strong>Email threads</strong> - All messages in a thread as Notes on one Activity</li>
107
+ <li><strong>Chat conversations</strong> - All messages in a channel or thread as Notes</li>
108
+ <li><strong>Workflows</strong> - All steps in an end-to-end process as Notes</li>
109
+ <li><strong>Document collaboration</strong> - All comments and updates as Notes</li>
110
+ <li><strong>Issue tracking</strong> - All comments and status updates as Notes</li>
111
+ </ul>
112
+ <pre><code class="typescript"><span class="hl-7">// ✅ GOOD - Add to existing Activity</span><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">onNewMessage</span><span class="hl-1">(</span><span class="hl-2">message</span><span class="hl-1">: </span><span class="hl-2">Message</span><span class="hl-1">, </span><span class="hl-2">threadId</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-7">// Find existing activity for this thread</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-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">getActivityBySource</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">thread_id:</span><span class="hl-1"> </span><span class="hl-2">threadId</span><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">activity</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-7">// Add new message as a Note</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">createNote</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">activity:</span><span class="hl-1"> { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-2">activity</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">note:</span><span class="hl-1"> </span><span class="hl-2">message</span><span class="hl-1">.</span><span class="hl-2">text</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">author:</span><span class="hl-1"> </span><span class="hl-2">message</span><span class="hl-1">.</span><span class="hl-2">author</span><span class="hl-1">,</span><br/><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-7">// Create new Activity with initial Note</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">Note</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">message</span><span class="hl-1">.</span><span class="hl-2">subject</span><span class="hl-1"> || </span><span class="hl-3">&quot;New conversation&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">preview:</span><span class="hl-1"> </span><span class="hl-2">message</span><span class="hl-1">.</span><span class="hl-2">text</span><span class="hl-1">.</span><span class="hl-6">substring</span><span class="hl-1">(</span><span class="hl-13">0</span><span class="hl-1">, </span><span class="hl-13">100</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">thread_id:</span><span class="hl-1"> </span><span class="hl-2">threadId</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-2">message</span><span class="hl-1">.</span><span class="hl-2">text</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><br/><br/><span class="hl-7">// ❌ BAD - Creating separate Activity for each message</span><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">onNewMessage</span><span class="hl-1">(</span><span class="hl-2">message</span><span class="hl-1">: </span><span class="hl-2">Message</span><span class="hl-1">, </span><span class="hl-2">threadId</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-7">// This creates clutter - each message becomes its own Activity</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">Note</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">`Message from </span><span class="hl-4">${</span><span class="hl-2">message</span><span class="hl-14">.</span><span class="hl-2">author</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">preview:</span><span class="hl-1"> </span><span class="hl-2">message</span><span class="hl-1">.</span><span class="hl-2">text</span><span class="hl-1">,</span><br/><span class="hl-1"> });</span><br/><span class="hl-1">}</span>
113
+ </code><button type="button">Copy</button></pre>
114
+
115
+ <p><strong>Why?</strong> Grouping related content keeps the user's workspace organized and provides better context. A chat conversation with 20 messages should be one Activity with 20 Notes, not 20 separate Activities.</p>
97
116
  <hr>
98
117
  <h2 id="lifecycle-methods" class="tsd-anchor-link">Lifecycle Methods<a href="#lifecycle-methods" 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>Twists have several lifecycle methods that are called at specific times.</p>
99
118
  <h3 id="activatepriority" class="tsd-anchor-link">activate(priority)<a href="#activatepriority" 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 twist is first activated for a priority.</p>
@@ -137,7 +156,7 @@
137
156
  </code><button type="button">Copy</button></pre>
138
157
 
139
158
  <h3 id="3-batch-long-operations" class="tsd-anchor-link">3. Batch Long Operations<a href="#3-batch-long-operations" 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>Break long-running operations into batches:</p>
140
- <pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">startSync</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">callback</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-3">&quot;syncBatch&quot;</span><span class="hl-1">, { </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-12">1</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">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><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">args</span><span class="hl-1">: </span><span class="hl-2">any</span><span class="hl-1">, </span><span class="hl-2">context</span><span class="hl-1">: { </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-2">number</span><span class="hl-1"> }) {</span><br/><span class="hl-1"> </span><span class="hl-7">// Process one page</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">hasMore</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-6">processPage</span><span class="hl-1">(</span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">page</span><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">hasMore</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-7">// Queue next batch</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</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-3">&quot;syncBatch&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1"> + </span><span class="hl-12">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">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
159
+ <pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">startSync</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">callback</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-3">&quot;syncBatch&quot;</span><span class="hl-1">, { </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-13">1</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">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><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">args</span><span class="hl-1">: </span><span class="hl-2">any</span><span class="hl-1">, </span><span class="hl-2">context</span><span class="hl-1">: { </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-2">number</span><span class="hl-1"> }) {</span><br/><span class="hl-1"> </span><span class="hl-7">// Process one page</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">hasMore</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-6">processPage</span><span class="hl-1">(</span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">page</span><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">hasMore</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-7">// Queue next batch</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</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-3">&quot;syncBatch&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1"> + </span><span class="hl-13">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">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
141
160
  </code><button type="button">Copy</button></pre>
142
161
 
143
162
  <p>See <a href="Runtime_Environment.html">Runtime Environment</a> for more details.</p>
@@ -150,7 +169,7 @@
150
169
  </code><button type="button">Copy</button></pre>
151
170
 
152
171
  <h3 id="6-clear-activity-titles" class="tsd-anchor-link">6. Clear Activity Titles<a href="#6-clear-activity-titles" 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>Make activity titles clear and actionable:</p>
153
- <pre><code class="typescript"><span class="hl-7">// ❌ Vague</span><br/><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">Task</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;Thing&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// ✅ Clear</span><br/><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">Task</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;Review pull request #123 for authentication fix&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span>
172
+ <pre><code class="typescript"><span class="hl-7">// ❌ Vague</span><br/><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">&quot;Thing&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// ✅ Clear</span><br/><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">&quot;Review pull request #123 for authentication fix&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span>
154
173
  </code><button type="button">Copy</button></pre>
155
174
 
156
175
  <hr>
@@ -158,6 +177,5 @@
158
177
  <li><strong><a href="Built-in_Tools.html">Built-in Tools Guide</a></strong> - Learn about Plot, Store, AI, and more</li>
159
178
  <li><strong><a href="Building_Custom_Tools.html">Building Custom Tools</a></strong> - Create reusable tools</li>
160
179
  <li><strong><a href="Runtime_Environment.html">Runtime Environment</a></strong> - Understand execution constraints</li>
161
- <li><strong><a href="Advanced.html">Advanced Topics</a></strong> - Complex patterns and techniques</li>
162
180
  </ul>
163
- </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="#core-concepts"><span>Core <wbr/>Concepts</span></a><ul><li><a href="#table-of-contents"><span>Table of <wbr/>Contents</span></a></li><li><a href="#twists"><span>Twists</span></a></li><li><ul><li><a href="#what-is-a-twist"><span>What is a <wbr/>Twist?</span></a></li><li><a href="#twist-anatomy"><span>Twist <wbr/>Anatomy</span></a></li><li><a href="#when-to-use-twists"><span>When to <wbr/>Use <wbr/>Twists</span></a></li></ul></li><li><a href="#twist-tools"><span>Twist <wbr/>Tools</span></a></li><li><ul><li><a href="#types-of-tools"><span>Types of <wbr/>Tools</span></a></li><li><ul><li><a href="#1-built-in-tools"><span>1. <wbr/>Built-<wbr/>in <wbr/>Tools</span></a></li><li><a href="#2-custom-tools"><span>2. <wbr/>Custom <wbr/>Tools</span></a></li></ul></li><li><a href="#declaring-tool-dependencies"><span>Declaring <wbr/>Tool <wbr/>Dependencies</span></a></li><li><a href="#accessing-tools"><span>Accessing <wbr/>Tools</span></a></li><li><a href="#direct-access-methods"><span>Direct <wbr/>Access <wbr/>Methods</span></a></li></ul></li><li><a href="#priorities"><span>Priorities</span></a></li><li><ul><li><a href="#priority-hierarchy"><span>Priority <wbr/>Hierarchy</span></a></li><li><a href="#creating-priorities"><span>Creating <wbr/>Priorities</span></a></li><li><a href="#twist-activation"><span>Twist <wbr/>Activation</span></a></li></ul></li><li><a href="#activities"><span>Activities</span></a></li><li><ul><li><a href="#activity-types"><span>Activity <wbr/>Types</span></a></li><li><a href="#activity-properties"><span>Activity <wbr/>Properties</span></a></li><li><a href="#activity-links"><span>Activity <wbr/>Links</span></a></li></ul></li><li><a href="#lifecycle-methods"><span>Lifecycle <wbr/>Methods</span></a></li><li><ul><li><a href="#activatepriority"><span>activate(priority)</span></a></li><li><a href="#upgrade"><span>upgrade()</span></a></li><li><a href="#deactivate"><span>deactivate()</span></a></li></ul></li><li><a href="#best-practices"><span>Best <wbr/>Practices</span></a></li><li><ul><li><a href="#1-state-management"><span>1. <wbr/>State <wbr/>Management</span></a></li><li><a href="#2-error-handling"><span>2. <wbr/>Error <wbr/>Handling</span></a></li><li><a href="#3-batch-long-operations"><span>3. <wbr/>Batch <wbr/>Long <wbr/>Operations</span></a></li><li><a href="#4-type-safety"><span>4. <wbr/>Type <wbr/>Safety</span></a></li><li><a href="#5-tool-composition"><span>5. <wbr/>Tool <wbr/>Composition</span></a></li><li><a href="#6-clear-activity-titles"><span>6. <wbr/>Clear <wbr/>Activity <wbr/>Titles</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>
181
+ </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="#core-concepts"><span>Core <wbr/>Concepts</span></a><ul><li><a href="#table-of-contents"><span>Table of <wbr/>Contents</span></a></li><li><a href="#twists"><span>Twists</span></a></li><li><ul><li><a href="#what-is-a-twist"><span>What is a <wbr/>Twist?</span></a></li><li><a href="#twist-anatomy"><span>Twist <wbr/>Anatomy</span></a></li><li><a href="#when-to-use-twists"><span>When to <wbr/>Use <wbr/>Twists</span></a></li></ul></li><li><a href="#twist-tools"><span>Twist <wbr/>Tools</span></a></li><li><ul><li><a href="#types-of-tools"><span>Types of <wbr/>Tools</span></a></li><li><ul><li><a href="#1-built-in-tools"><span>1. <wbr/>Built-<wbr/>in <wbr/>Tools</span></a></li><li><a href="#2-custom-tools"><span>2. <wbr/>Custom <wbr/>Tools</span></a></li></ul></li><li><a href="#declaring-tool-dependencies"><span>Declaring <wbr/>Tool <wbr/>Dependencies</span></a></li><li><a href="#accessing-tools"><span>Accessing <wbr/>Tools</span></a></li><li><a href="#direct-access-methods"><span>Direct <wbr/>Access <wbr/>Methods</span></a></li></ul></li><li><a href="#priorities"><span>Priorities</span></a></li><li><ul><li><a href="#priority-hierarchy"><span>Priority <wbr/>Hierarchy</span></a></li><li><a href="#creating-priorities"><span>Creating <wbr/>Priorities</span></a></li><li><a href="#twist-activation"><span>Twist <wbr/>Activation</span></a></li></ul></li><li><a href="#activities"><span>Activities</span></a></li><li><ul><li><a href="#activity-types"><span>Activity <wbr/>Types</span></a></li><li><a href="#activity-properties"><span>Activity <wbr/>Properties</span></a></li><li><a href="#activity-notes"><span>Activity <wbr/>Notes</span></a></li><li><a href="#best-practices-for-activities-and-notes"><span>Best <wbr/>Practices for <wbr/>Activities and <wbr/>Notes</span></a></li><li><ul><li><a href="#always-create-activities-with-an-initial-note"><span>Always <wbr/>Create <wbr/>Activities with an <wbr/>Initial <wbr/>Note</span></a></li><li><a href="#add-notes-to-existing-activities-for-related-content"><span>Add <wbr/>Notes to <wbr/>Existing <wbr/>Activities for <wbr/>Related <wbr/>Content</span></a></li></ul></li></ul></li><li><a href="#lifecycle-methods"><span>Lifecycle <wbr/>Methods</span></a></li><li><ul><li><a href="#activatepriority"><span>activate(priority)</span></a></li><li><a href="#upgrade"><span>upgrade()</span></a></li><li><a href="#deactivate"><span>deactivate()</span></a></li></ul></li><li><a href="#best-practices"><span>Best <wbr/>Practices</span></a></li><li><ul><li><a href="#1-state-management"><span>1. <wbr/>State <wbr/>Management</span></a></li><li><a href="#2-error-handling"><span>2. <wbr/>Error <wbr/>Handling</span></a></li><li><a href="#3-batch-long-operations"><span>3. <wbr/>Batch <wbr/>Long <wbr/>Operations</span></a></li><li><a href="#4-type-safety"><span>4. <wbr/>Type <wbr/>Safety</span></a></li><li><a href="#5-tool-composition"><span>5. <wbr/>Tool <wbr/>Composition</span></a></li><li><a href="#6-clear-activity-titles"><span>6. <wbr/>Clear <wbr/>Activity <wbr/>Titles</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/Getting_Started.html CHANGED
@@ -41,7 +41,7 @@
41
41
  </code><button>Copy</button></pre>
42
42
 
43
43
  <h3 id="step-2-implement-your-twist" class="tsd-anchor-link">Step 2: Implement Your Twist<a href="#step-2-implement-your-twist" 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>Edit <code>src/index.ts</code> to add your twist logic:</p>
44
- <pre><code class="typescript"><span class="hl-0">import</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">Activity</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">Twist</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">Priority</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">ToolBuilder</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><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/><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">MyTwist</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Twist</span><span class="hl-1">&lt;</span><span class="hl-5">MyTwist</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-7">// Declare tool dependencies</span><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">ToolBuilder</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">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><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Called when the twist is activated for a priority</span><br/><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">activate</span><span class="hl-1">(</span><span class="hl-2">priority</span><span class="hl-1">: </span><span class="hl-5">Pick</span><span class="hl-1">&lt;</span><span class="hl-5">Priority</span><span class="hl-1">, </span><span class="hl-3">&quot;id&quot;</span><span class="hl-1">&gt;) {</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">Note</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;Welcome! Your twist is now active.&quot;</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">// Called when an activity is routed to this twist</span><br/><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">activity</span><span class="hl-1">(</span><span class="hl-2">activity</span><span class="hl-1">: </span><span class="hl-5">Activity</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-3">&quot;Processing activity:&quot;</span><span class="hl-1">, </span><span class="hl-2">activity</span><span class="hl-1">.</span><span class="hl-2">title</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
44
+ <pre><code class="typescript"><span class="hl-0">import</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">Activity</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-0">type</span><span class="hl-1"> </span><span class="hl-2">Priority</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">ToolBuilder</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">Twist</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><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/><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">MyTwist</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Twist</span><span class="hl-1">&lt;</span><span class="hl-5">MyTwist</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-7">// Declare tool dependencies</span><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">ToolBuilder</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">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><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Called when the twist is activated for a priority</span><br/><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">activate</span><span class="hl-1">(</span><span class="hl-2">priority</span><span class="hl-1">: </span><span class="hl-5">Pick</span><span class="hl-1">&lt;</span><span class="hl-5">Priority</span><span class="hl-1">, </span><span class="hl-3">&quot;id&quot;</span><span class="hl-1">&gt;) {</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">Note</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;Welcome! Your twist is now active.&quot;</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">// Called when an activity is routed to this twist</span><br/><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">activity</span><span class="hl-1">(</span><span class="hl-2">activity</span><span class="hl-1">: </span><span class="hl-5">Activity</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-2">console</span><span class="hl-1">.</span><span class="hl-6">log</span><span class="hl-1">(</span><span class="hl-3">&quot;Processing activity:&quot;</span><span class="hl-1">, </span><span class="hl-2">activity</span><span class="hl-1">.</span><span class="hl-2">title</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
45
45
  </code><button type="button">Copy</button></pre>
46
46
 
47
47
  <h3 id="step-3-test-locally" class="tsd-anchor-link">Step 3: Test Locally<a href="#step-3-test-locally" 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>Build and check for errors:</p>
@@ -77,7 +77,7 @@
77
77
  <li><strong><a href="Building_Custom_Tools.html">Building Custom Tools</a></strong> - Create your own reusable twist tools</li>
78
78
  <li><strong><a href="Runtime_Environment.html">Runtime Environment</a></strong> - Understand execution constraints and optimization</li>
79
79
  </ul>
80
- <h2 id="common-first-tasks" class="tsd-anchor-link">Common First Tasks<a href="#common-first-tasks" 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="creating-activities" class="tsd-anchor-link">Creating Activities<a href="#creating-activities" 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">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">Task</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;Review pull request&quot;</span><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">&quot;Check the new authentication flow&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">links:</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-2">ActivityLinkType</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;View PR&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-3">&quot;https://github.com/org/repo/pull/123&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>
80
+ <h2 id="common-first-tasks" class="tsd-anchor-link">Common First Tasks<a href="#common-first-tasks" 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="creating-activities" class="tsd-anchor-link">Creating Activities<a href="#creating-activities" 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">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">&quot;Review pull request&quot;</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">&quot;Please review the authentication changes and ensure they follow security best practices&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">links:</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-2">ActivityLinkType</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;View PR&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-3">&quot;https://github.com/org/repo/pull/123&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><br/><span class="hl-1">});</span>
81
81
  </code><button type="button">Copy</button></pre>
82
82
 
83
83
  <h3 id="storing-data" class="tsd-anchor-link">Storing Data<a href="#storing-data" 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-7">// Save</span><br/><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">&quot;last_sync&quot;</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-6">toISOString</span><span class="hl-1">());</span><br/><br/><span class="hl-7">// Retrieve</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">lastSync</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">&quot;last_sync&quot;</span><span class="hl-1">);</span>
@@ -86,9 +86,18 @@
86
86
  <h3 id="scheduling-tasks" class="tsd-anchor-link">Scheduling Tasks<a href="#scheduling-tasks" 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-7">// Run immediately</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">callback</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-3">&quot;processData&quot;</span><span class="hl-1">);</span><br/><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">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// Schedule for later</span><br/><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">runTask</span><span class="hl-1">(</span><span class="hl-2">callback</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">runAt:</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-3">&quot;2025-02-01T10:00:00Z&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">});</span>
87
87
  </code><button type="button">Copy</button></pre>
88
88
 
89
+ <h3 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></h3><h4 id="always-include-notes-with-activities" class="tsd-anchor-link">Always Include Notes with Activities<a href="#always-include-notes-with-activities" 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></h4><p><strong>Important:</strong> Always create Activities with at least one initial Note. The <code>title</code> and <code>preview</code> are brief summaries that may be truncated in the UI. Detailed information should go in Notes.</p>
90
+ <pre><code class="typescript"><span class="hl-7">// ✅ Good - Activity with detailed Note</span><br/><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">&quot;Deploy v2.0&quot;</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">&quot;Deployment checklist:</span><span class="hl-12">\n</span><span class="hl-3">- Run database migrations</span><span class="hl-12">\n</span><span class="hl-3">- Update environment variables</span><span class="hl-12">\n</span><span class="hl-3">- Deploy backend services</span><span class="hl-12">\n</span><span class="hl-3">- Deploy frontend</span><span class="hl-12">\n</span><span class="hl-3">- Run smoke tests&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">links:</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-2">ActivityLinkType</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;Deployment Guide&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-3">&quot;https://docs.example.com/deploy&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><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// ❌ Bad - No detailed information</span><br/><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">&quot;Deploy v2.0&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-7">// Missing Notes with context and steps</span><br/><span class="hl-1">});</span>
91
+ </code><button type="button">Copy</button></pre>
92
+
93
+ <h4 id="add-notes-to-existing-activities-for-related-content" class="tsd-anchor-link">Add Notes to Existing Activities for Related Content<a href="#add-notes-to-existing-activities-for-related-content" 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></h4><p>For conversations, email threads, or workflows, add Notes to the existing Activity instead of creating new Activities:</p>
94
+ <pre><code class="typescript"><span class="hl-7">// Check if Activity exists</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">existing</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">plot</span><span class="hl-1">.</span><span class="hl-6">getActivityBySource</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">conversation_id:</span><span class="hl-1"> </span><span class="hl-2">conversationId</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">existing</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-7">// Add to existing Activity</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">createNote</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">activity:</span><span class="hl-1"> { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-2">existing</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">note:</span><span class="hl-1"> </span><span class="hl-2">newMessage</span><span class="hl-1">.</span><span class="hl-2">text</span><span class="hl-1">,</span><br/><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-7">// Create new Activity with initial Note</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">Note</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;New conversation&quot;</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">conversation_id:</span><span class="hl-1"> </span><span class="hl-2">conversationId</span><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-2">notes:</span><span class="hl-1"> [{ </span><span class="hl-2">note:</span><span class="hl-1"> </span><span class="hl-2">newMessage</span><span class="hl-1">.</span><span class="hl-2">text</span><span class="hl-1"> }],</span><br/><span class="hl-1"> });</span><br/><span class="hl-1">}</span>
95
+ </code><button type="button">Copy</button></pre>
96
+
97
+ <p>See <a href="Core_Concepts.html#best-practices-for-activities-and-notes">Core Concepts - Best Practices</a> for more details.</p>
89
98
  <h2 id="need-help" class="tsd-anchor-link">Need Help?<a href="#need-help" 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>
90
99
  <li><strong>Documentation</strong>: Continue reading the guides</li>
91
100
  <li><strong>Examples</strong>: Check the <a href="https://github.com/plotday/plot/tree/main/twists">examples directory</a></li>
92
101
  <li><strong>Issues</strong>: <a href="https://github.com/plotday/plot/issues">Report bugs or request features</a></li>
93
102
  </ul>
94
- </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="#getting-started-with-plot-twists"><span>Getting <wbr/>Started with <wbr/>Plot <wbr/>Twists</span></a><ul><li><a href="#choose-your-path"><span>Choose <wbr/>Your <wbr/>Path</span></a></li><li><a href="#no-code-twists"><span>No-<wbr/>Code <wbr/>Twists</span></a></li><li><ul><li><a href="#step-1-create-a-plot-twistmd-file"><span>Step 1: <wbr/>Create a plot-<wbr/>twist.md <wbr/>File</span></a></li><li><a href="#step-2-deploy-your-twist"><span>Step 2: <wbr/>Deploy <wbr/>Your <wbr/>Twist</span></a></li><li><a href="#optional-generate-code-first"><span>Optional: <wbr/>Generate <wbr/>Code <wbr/>First</span></a></li></ul></li><li><a href="#developer-twists"><span>Developer <wbr/>Twists</span></a></li><li><ul><li><a href="#step-1-create-a-new-twist-project"><span>Step 1: <wbr/>Create a <wbr/>New <wbr/>Twist <wbr/>Project</span></a></li><li><a href="#step-2-implement-your-twist"><span>Step 2: <wbr/>Implement <wbr/>Your <wbr/>Twist</span></a></li><li><a href="#step-3-test-locally"><span>Step 3: <wbr/>Test <wbr/>Locally</span></a></li><li><a href="#step-4-deploy"><span>Step 4: <wbr/>Deploy</span></a></li></ul></li><li><a href="#understanding-the-project-structure"><span>Understanding the <wbr/>Project <wbr/>Structure</span></a></li><li><ul><li><a href="#twist-file-srcindexts"><span>Twist <wbr/>File (src/index.ts)</span></a></li><li><a href="#configuration-plot-twistjson"><span>Configuration (plot-<wbr/>twist.json)</span></a></li><li><a href="#typescript-config-tsconfigjson"><span>Type<wbr/>Script <wbr/>Config (tsconfig.json)</span></a></li></ul></li><li><a href="#next-steps"><span>Next <wbr/>Steps</span></a></li><li><a href="#common-first-tasks"><span>Common <wbr/>First <wbr/>Tasks</span></a></li><li><ul><li><a href="#creating-activities"><span>Creating <wbr/>Activities</span></a></li><li><a href="#storing-data"><span>Storing <wbr/>Data</span></a></li><li><a href="#scheduling-tasks"><span>Scheduling <wbr/>Tasks</span></a></li></ul></li><li><a href="#need-help"><span>Need <wbr/>Help?</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>
103
+ </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="#getting-started-with-plot-twists"><span>Getting <wbr/>Started with <wbr/>Plot <wbr/>Twists</span></a><ul><li><a href="#choose-your-path"><span>Choose <wbr/>Your <wbr/>Path</span></a></li><li><a href="#no-code-twists"><span>No-<wbr/>Code <wbr/>Twists</span></a></li><li><ul><li><a href="#step-1-create-a-plot-twistmd-file"><span>Step 1: <wbr/>Create a plot-<wbr/>twist.md <wbr/>File</span></a></li><li><a href="#step-2-deploy-your-twist"><span>Step 2: <wbr/>Deploy <wbr/>Your <wbr/>Twist</span></a></li><li><a href="#optional-generate-code-first"><span>Optional: <wbr/>Generate <wbr/>Code <wbr/>First</span></a></li></ul></li><li><a href="#developer-twists"><span>Developer <wbr/>Twists</span></a></li><li><ul><li><a href="#step-1-create-a-new-twist-project"><span>Step 1: <wbr/>Create a <wbr/>New <wbr/>Twist <wbr/>Project</span></a></li><li><a href="#step-2-implement-your-twist"><span>Step 2: <wbr/>Implement <wbr/>Your <wbr/>Twist</span></a></li><li><a href="#step-3-test-locally"><span>Step 3: <wbr/>Test <wbr/>Locally</span></a></li><li><a href="#step-4-deploy"><span>Step 4: <wbr/>Deploy</span></a></li></ul></li><li><a href="#understanding-the-project-structure"><span>Understanding the <wbr/>Project <wbr/>Structure</span></a></li><li><ul><li><a href="#twist-file-srcindexts"><span>Twist <wbr/>File (src/index.ts)</span></a></li><li><a href="#configuration-plot-twistjson"><span>Configuration (plot-<wbr/>twist.json)</span></a></li><li><a href="#typescript-config-tsconfigjson"><span>Type<wbr/>Script <wbr/>Config (tsconfig.json)</span></a></li></ul></li><li><a href="#next-steps"><span>Next <wbr/>Steps</span></a></li><li><a href="#common-first-tasks"><span>Common <wbr/>First <wbr/>Tasks</span></a></li><li><ul><li><a href="#creating-activities"><span>Creating <wbr/>Activities</span></a></li><li><a href="#storing-data"><span>Storing <wbr/>Data</span></a></li><li><a href="#scheduling-tasks"><span>Scheduling <wbr/>Tasks</span></a></li><li><a href="#best-practices"><span>Best <wbr/>Practices</span></a></li><li><ul><li><a href="#always-include-notes-with-activities"><span>Always <wbr/>Include <wbr/>Notes with <wbr/>Activities</span></a></li><li><a href="#add-notes-to-existing-activities-for-related-content"><span>Add <wbr/>Notes to <wbr/>Existing <wbr/>Activities for <wbr/>Related <wbr/>Content</span></a></li></ul></li></ul></li><li><a href="#need-help"><span>Need <wbr/>Help?</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>