@plotday/twister 0.22.0 → 0.26.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 (169) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +35 -6
  3. package/bin/commands/deploy.js +234 -2
  4. package/bin/commands/deploy.js.map +1 -1
  5. package/bin/commands/generate.js +11 -2
  6. package/bin/commands/generate.js.map +1 -1
  7. package/bin/commands/login.js +19 -3
  8. package/bin/commands/login.js.map +1 -1
  9. package/bin/commands/priority-create.js +7 -2
  10. package/bin/commands/priority-create.js.map +1 -1
  11. package/bin/commands/priority-list.js +6 -1
  12. package/bin/commands/priority-list.js.map +1 -1
  13. package/bin/commands/twist-logs.js +12 -3
  14. package/bin/commands/twist-logs.js.map +1 -1
  15. package/bin/templates/AGENTS.template.md +109 -20
  16. package/bin/utils/bundle.js +40 -0
  17. package/bin/utils/bundle.js.map +1 -1
  18. package/bin/utils/network-error.js +149 -0
  19. package/bin/utils/network-error.js.map +1 -0
  20. package/cli/templates/AGENTS.template.md +109 -20
  21. package/dist/common/calendar.d.ts +10 -2
  22. package/dist/common/calendar.d.ts.map +1 -1
  23. package/dist/common/projects.d.ts +123 -0
  24. package/dist/common/projects.d.ts.map +1 -0
  25. package/dist/common/projects.js +2 -0
  26. package/dist/common/projects.js.map +1 -0
  27. package/dist/docs/assets/hierarchy.js +1 -1
  28. package/dist/docs/assets/highlight.css +4 -4
  29. package/dist/docs/assets/navigation.js +1 -1
  30. package/dist/docs/assets/search.js +1 -1
  31. package/dist/docs/classes/tool.Tool.html +5 -5
  32. package/dist/docs/classes/tools_ai.AI.html +3 -3
  33. package/dist/docs/classes/tools_callbacks.Callbacks.html +4 -4
  34. package/dist/docs/classes/tools_integrations.Integrations.html +1 -1
  35. package/dist/docs/classes/tools_network.Network.html +4 -4
  36. package/dist/docs/classes/tools_plot.Plot.html +28 -14
  37. package/dist/docs/classes/tools_store.Store.html +1 -1
  38. package/dist/docs/classes/tools_tasks.Tasks.html +2 -2
  39. package/dist/docs/classes/tools_twists.Twists.html +4 -4
  40. package/dist/docs/classes/twist.Twist.html +1 -1
  41. package/dist/docs/documents/Building_Custom_Tools.html +6 -6
  42. package/dist/docs/documents/Built-in_Tools.html +24 -17
  43. package/dist/docs/documents/Core_Concepts.html +42 -9
  44. package/dist/docs/documents/Getting_Started.html +10 -3
  45. package/dist/docs/documents/Runtime_Environment.html +7 -7
  46. package/dist/docs/enums/plot.ActivityLinkType.html +5 -5
  47. package/dist/docs/enums/plot.ActivityType.html +4 -4
  48. package/dist/docs/enums/plot.ActorType.html +4 -4
  49. package/dist/docs/enums/plot.ConferencingProvider.html +6 -6
  50. package/dist/docs/enums/tag.Tag.html +3 -4
  51. package/dist/docs/enums/tools_plot.ActivityAccess.html +3 -3
  52. package/dist/docs/enums/tools_plot.ContactAccess.html +3 -3
  53. package/dist/docs/enums/tools_plot.PriorityAccess.html +3 -3
  54. package/dist/docs/hierarchy.html +1 -1
  55. package/dist/docs/interfaces/common_calendar.CalendarTool.html +13 -7
  56. package/dist/docs/interfaces/tools_ai.AIResponse.html +2 -2
  57. package/dist/docs/interfaces/tools_twists.TwistSource.html +1 -1
  58. package/dist/docs/modules/index.html +1 -1
  59. package/dist/docs/modules/plot.html +1 -1
  60. package/dist/docs/types/plot.Activity.html +28 -7
  61. package/dist/docs/types/plot.ActivityCommon.html +10 -8
  62. package/dist/docs/types/plot.ActivityLink.html +1 -1
  63. package/dist/docs/types/plot.ActivityMeta.html +24 -6
  64. package/dist/docs/types/plot.ActivityUpdate.html +2 -2
  65. package/dist/docs/types/plot.ActivityWithNotes.html +1 -1
  66. package/dist/docs/types/plot.Actor.html +5 -5
  67. package/dist/docs/types/plot.ActorId.html +8 -3
  68. package/dist/docs/types/plot.ContentType.html +1 -0
  69. package/dist/docs/types/plot.NewActivity.html +18 -3
  70. package/dist/docs/types/plot.NewActivityWithNotes.html +1 -1
  71. package/dist/docs/types/plot.NewContact.html +4 -4
  72. package/dist/docs/types/plot.NewNote.html +9 -3
  73. package/dist/docs/types/plot.NewPriority.html +1 -1
  74. package/dist/docs/types/plot.Note.html +3 -3
  75. package/dist/docs/types/plot.NoteUpdate.html +4 -4
  76. package/dist/docs/types/plot.PickPriorityConfig.html +3 -3
  77. package/dist/docs/types/plot.Priority.html +3 -3
  78. package/dist/docs/types/plot.Tags.html +1 -0
  79. package/dist/docs/types/tools_ai.DataContent.html +1 -1
  80. package/dist/docs/types/tools_network.WebhookRequest.html +5 -3
  81. package/dist/docs/types/tools_plot.NoteIntentHandler.html +4 -4
  82. package/dist/llm-docs/common/calendar.d.ts +2 -2
  83. package/dist/llm-docs/common/calendar.d.ts.map +1 -1
  84. package/dist/llm-docs/common/calendar.js +2 -2
  85. package/dist/llm-docs/common/calendar.js.map +1 -1
  86. package/dist/llm-docs/common/messaging.d.ts +1 -1
  87. package/dist/llm-docs/common/messaging.js +1 -1
  88. package/dist/llm-docs/common/projects.d.ts +9 -0
  89. package/dist/llm-docs/common/projects.d.ts.map +1 -0
  90. package/dist/llm-docs/common/projects.js +8 -0
  91. package/dist/llm-docs/common/projects.js.map +1 -0
  92. package/dist/llm-docs/index.d.ts +1 -1
  93. package/dist/llm-docs/index.js +17 -17
  94. package/dist/llm-docs/index.js.map +1 -1
  95. package/dist/llm-docs/plot.d.ts +2 -2
  96. package/dist/llm-docs/plot.d.ts.map +1 -1
  97. package/dist/llm-docs/plot.js +2 -2
  98. package/dist/llm-docs/plot.js.map +1 -1
  99. package/dist/llm-docs/tag.d.ts +2 -2
  100. package/dist/llm-docs/tag.d.ts.map +1 -1
  101. package/dist/llm-docs/tag.js +2 -2
  102. package/dist/llm-docs/tag.js.map +1 -1
  103. package/dist/llm-docs/tool.d.ts +2 -2
  104. package/dist/llm-docs/tool.d.ts.map +1 -1
  105. package/dist/llm-docs/tool.js +2 -2
  106. package/dist/llm-docs/tool.js.map +1 -1
  107. package/dist/llm-docs/tools/ai.d.ts +2 -2
  108. package/dist/llm-docs/tools/ai.d.ts.map +1 -1
  109. package/dist/llm-docs/tools/ai.js +2 -2
  110. package/dist/llm-docs/tools/ai.js.map +1 -1
  111. package/dist/llm-docs/tools/callbacks.d.ts +2 -2
  112. package/dist/llm-docs/tools/callbacks.d.ts.map +1 -1
  113. package/dist/llm-docs/tools/callbacks.js +2 -2
  114. package/dist/llm-docs/tools/callbacks.js.map +1 -1
  115. package/dist/llm-docs/tools/integrations.d.ts +1 -1
  116. package/dist/llm-docs/tools/integrations.js +1 -1
  117. package/dist/llm-docs/tools/network.d.ts +2 -2
  118. package/dist/llm-docs/tools/network.d.ts.map +1 -1
  119. package/dist/llm-docs/tools/network.js +2 -2
  120. package/dist/llm-docs/tools/network.js.map +1 -1
  121. package/dist/llm-docs/tools/plot.d.ts +2 -2
  122. package/dist/llm-docs/tools/plot.d.ts.map +1 -1
  123. package/dist/llm-docs/tools/plot.js +2 -2
  124. package/dist/llm-docs/tools/plot.js.map +1 -1
  125. package/dist/llm-docs/tools/store.d.ts +1 -1
  126. package/dist/llm-docs/tools/store.js +1 -1
  127. package/dist/llm-docs/tools/tasks.d.ts +1 -1
  128. package/dist/llm-docs/tools/tasks.js +1 -1
  129. package/dist/llm-docs/tools/twists.d.ts +2 -2
  130. package/dist/llm-docs/tools/twists.d.ts.map +1 -1
  131. package/dist/llm-docs/tools/twists.js +2 -2
  132. package/dist/llm-docs/tools/twists.js.map +1 -1
  133. package/dist/llm-docs/twist-guide-template.d.ts +1 -1
  134. package/dist/llm-docs/twist-guide-template.d.ts.map +1 -1
  135. package/dist/llm-docs/twist-guide-template.js +1 -1
  136. package/dist/llm-docs/twist-guide-template.js.map +1 -1
  137. package/dist/llm-docs/twist.d.ts +1 -1
  138. package/dist/llm-docs/twist.js +1 -1
  139. package/dist/plot.d.ts +203 -35
  140. package/dist/plot.d.ts.map +1 -1
  141. package/dist/plot.js.map +1 -1
  142. package/dist/tag.d.ts +2 -3
  143. package/dist/tag.d.ts.map +1 -1
  144. package/dist/tag.js +2 -3
  145. package/dist/tag.js.map +1 -1
  146. package/dist/tool.d.ts +2 -2
  147. package/dist/tool.d.ts.map +1 -1
  148. package/dist/tool.js +1 -1
  149. package/dist/tool.js.map +1 -1
  150. package/dist/tools/ai.d.ts +2 -2
  151. package/dist/tools/ai.d.ts.map +1 -1
  152. package/dist/tools/callbacks.d.ts +1 -1
  153. package/dist/tools/callbacks.d.ts.map +1 -1
  154. package/dist/tools/network.d.ts +2 -0
  155. package/dist/tools/network.d.ts.map +1 -1
  156. package/dist/tools/network.js.map +1 -1
  157. package/dist/tools/plot.d.ts +36 -4
  158. package/dist/tools/plot.d.ts.map +1 -1
  159. package/dist/tools/plot.js.map +1 -1
  160. package/dist/tools/twists.d.ts +2 -2
  161. package/dist/twist-guide.d.ts +1 -1
  162. package/dist/twist-guide.d.ts.map +1 -1
  163. package/package.json +52 -2
  164. package/tsconfig.base.json +1 -0
  165. package/dist/docs/types/plot.NoteType.html +0 -1
  166. package/dist/llm-docs/creator-docs.d.ts +0 -9
  167. package/dist/llm-docs/creator-docs.d.ts.map +0 -1
  168. package/dist/llm-docs/creator-docs.js +0 -8
  169. package/dist/llm-docs/creator-docs.js.map +0 -1
package/dist/docs/documents/Built-in_Tools.html CHANGED
@@ -10,12 +10,19 @@
10
10
  </ul>
11
11
  <hr>
12
12
  <h2 id="plot" class="tsd-anchor-link">Plot<a href="#plot" 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>The Plot tool is the core interface for creating and managing activities and priorities.</p>
13
+ <h3 id="understanding-activities-and-notes" class="tsd-anchor-link">Understanding Activities and Notes<a href="#understanding-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><p><strong>Activity</strong> represents something done or to be done (a task, event, or conversation), while <strong>Notes</strong> represent the updates and details on that activity.</p>
14
+ <p><strong>Think of an Activity as a thread</strong> on a messaging platform, and <strong>Notes as the messages in that thread</strong>. Always create activities with an initial note, and add notes to existing activities for updates rather than creating new activities.</p>
13
15
  <h3 id="setup" class="tsd-anchor-link">Setup<a href="#setup" 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">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-6">build</span><span class="hl-1">(</span><span class="hl-2">build</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">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>
14
16
  </code><button type="button">Copy</button></pre>
15
17
 
16
- <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">import</span><span class="hl-1"> { </span><span class="hl-2">ActivityLinkType</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">// Create a 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;Q1 Planning Meeting Notes&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;Discussed goals for Q1 and assigned action items.&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/><br/><span class="hl-7">// Create a task with a note containing links</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&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 changes and provide feedback&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><br/><br/><span class="hl-7">// Create an event with description in a 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">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><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;Daily standup meeting to sync on progress&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>
18
+ <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">import</span><span class="hl-1"> { </span><span class="hl-2">ActivityLinkType</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">// Create a note (thread with initial message)</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;Q1 Planning Meeting Notes&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">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Discussed goals for Q1 and assigned action items.&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/><br/><span class="hl-7">// Create a task with a note containing links</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&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">&quot;github:pr:123&quot;</span><span class="hl-1">, </span><span class="hl-7">// For deduplication</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">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Please review the changes and provide feedback.&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><br/><br/><span class="hl-7">// Create an event with description in a 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">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><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">&quot;google-calendar:event:abc123&quot;</span><span class="hl-1">, </span><span class="hl-7">// For deduplication</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">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Daily standup meeting to sync on progress.&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>
17
19
  </code><button type="button">Copy</button></pre>
18
20
 
21
+ <h4 id="action-scheduling-states" class="tsd-anchor-link">Action Scheduling States<a href="#action-scheduling-states" 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>When creating Actions (tasks), the <code>start</code> field determines their scheduling state. <strong>Important:</strong> Omitting <code>start</code> defaults to &quot;Do Now&quot; (current time). For most integrations, explicitly set <code>start: null</code> to create backlog items.</p>
22
+ <pre><code class="typescript"><span class="hl-7">// &quot;Do Now&quot; - Actionable today (DEFAULT - use sparingly!)</span><br/><span class="hl-7">// Only use for tasks that are urgent or actively in progress</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;Fix production bug&quot;</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">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Critical issue affecting users&quot;</span><span class="hl-1"> }],</span><br/><span class="hl-1"> </span><span class="hl-7">// Omitting start defaults to new Date() - becomes &quot;Do Now&quot;</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// &quot;Do Someday&quot; - Backlog item (RECOMMENDED default for most synced tasks)</span><br/><span class="hl-7">// Use for tasks from project management tools, backlog items, future work</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;Refactor user service&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">null</span><span class="hl-1">, </span><span class="hl-7">// Explicitly null for backlog</span><br/><span class="hl-1"> </span><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">&quot;linear:issue:ABC-123&quot;</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">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Technical debt to address&quot;</span><span class="hl-1"> }],</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// &quot;Do Later&quot; - Scheduled for specific date</span><br/><span class="hl-7">// Use when task has a concrete due date</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;Submit quarterly report&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-03-31&quot;</span><span class="hl-1">), </span><span class="hl-7">// Due date</span><br/><span class="hl-1"> </span><span class="hl-2">notes:</span><span class="hl-1"> [{ </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Q1 report due end of March&quot;</span><span class="hl-1"> }],</span><br/><span class="hl-1">});</span>
23
+ </code><button type="button">Copy</button></pre>
24
+
25
+ <p><strong>Best practice for integrations:</strong> Default to <code>start: null</code> for synced tasks, and only set <code>start</code> to current time if the task is explicitly marked as current/in-progress in the source system.</p>
19
26
  <h3 id="updating-activities" class="tsd-anchor-link">Updating Activities<a href="#updating-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-7">// Mark task as done</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">updateActivity</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">doneAt:</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><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Update 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">updateActivity</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">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Updated title&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;Additional information&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Reschedule 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">updateActivity</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">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-02T10: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-02T10:30:00Z&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">});</span>
20
27
  </code><button type="button">Copy</button></pre>
21
28
 
@@ -25,27 +32,27 @@
25
32
  <h3 id="managing-priorities" class="tsd-anchor-link">Managing Priorities<a href="#managing-priorities" 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">// Create a top-level priority</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">work</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">createPriority</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;Work&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Create a nested priority</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">project</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">createPriority</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;Project A&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">parentId:</span><span class="hl-1"> </span><span class="hl-2">work</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">,</span><br/><span class="hl-1">});</span>
26
33
  </code><button type="button">Copy</button></pre>
27
34
 
28
- <h3 id="activity-meta" class="tsd-anchor-link">Activity Meta<a href="#activity-meta" 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 meta fields to store custom data and link external resources:</p>
29
- <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 PR&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">meta:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">github_pr_id:</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><span class="hl-2">github_repo:</span><span class="hl-1"> </span><span class="hl-3">&quot;org/repo&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">review_status:</span><span class="hl-1"> </span><span class="hl-3">&quot;pending&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> },</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Later, find by meta</span><br/><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">github_pr_id:</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>
35
+ <h3 id="activity-source-and-meta" class="tsd-anchor-link">Activity Source and Meta<a href="#activity-source-and-meta" 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 the <code>source</code> field for deduplication and the <code>meta</code> field to store additional custom data:</p>
36
+ <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 PR&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">&quot;github:pr:123&quot;</span><span class="hl-1">, </span><span class="hl-7">// For deduplication</span><br/><span class="hl-1"> </span><span class="hl-2">meta:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">github_pr_id:</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><span class="hl-2">github_repo:</span><span class="hl-1"> </span><span class="hl-3">&quot;org/repo&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">review_status:</span><span class="hl-1"> </span><span class="hl-3">&quot;pending&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-2">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Please review this pull request.&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/><br/><span class="hl-7">// Later, find by source</span><br/><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><span class="hl-3">&quot;github:pr:123&quot;</span><span class="hl-1">);</span>
30
37
  </code><button type="button">Copy</button></pre>
31
38
 
32
- <h3 id="creating-and-managing-notes" class="tsd-anchor-link">Creating and Managing Notes<a href="#creating-and-managing-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="creating-notes-on-new-activities" class="tsd-anchor-link">Creating Notes on New Activities<a href="#creating-notes-on-new-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>Best Practice:</strong> Always create Activities with at least one initial Note containing detailed information. The <code>title</code> and <code>preview</code> are short summaries that may be truncated—detailed content should go in Notes.</p>
33
- <pre><code class="typescript"><span class="hl-7">// ✅ Recommended - Activity with initial 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;Customer feedback: Login issues&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;User reports problems with SSO authentication&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">source:</span><span class="hl-1"> </span><span class="hl-3">&quot;support-ticket:12345&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;Customer reported:</span><span class="hl-12">\n\n\&quot;</span><span class="hl-3">I&#39;m unable to log in using Google SSO. The page redirects but then shows an error &#39;Invalid state parameter&#39;.</span><span class="hl-12">\&quot;\n\n</span><span class="hl-3">Priority: High</span><span class="hl-12">\n</span><span class="hl-3">Affected users: ~15 reports&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 Support Ticket&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://support.example.com/tickets/12345&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>
39
+ <h3 id="creating-and-managing-notes" class="tsd-anchor-link">Creating and Managing Notes<a href="#creating-and-managing-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="creating-notes-on-new-activities" class="tsd-anchor-link">Creating Notes on New Activities<a href="#creating-notes-on-new-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>Best Practice:</strong> Always create Activities with at least one initial Note containing detailed information. The <code>title</code> is a short summary that may be truncated—detailed content should go in Notes.</p>
40
+ <pre><code class="typescript"><span class="hl-7">// ✅ Recommended - Activity with initial Note (thread with first message)</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;Customer feedback: Login issues&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">&quot;support-ticket:12345&quot;</span><span class="hl-1">, </span><span class="hl-7">// For deduplication</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">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Customer reported:</span><span class="hl-12">\n\n\&quot;</span><span class="hl-3">I&#39;m unable to log in using Google SSO. The page redirects but then shows an error &#39;Invalid state parameter&#39;.</span><span class="hl-12">\&quot;\n\n</span><span class="hl-3">Priority: High</span><span class="hl-12">\n</span><span class="hl-3">Affected users: ~15 reports&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 Support Ticket&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://support.example.com/tickets/12345&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>
34
41
  </code><button type="button">Copy</button></pre>
35
42
 
36
- <h4 id="adding-notes-to-existing-activities" class="tsd-anchor-link">Adding Notes to Existing Activities<a href="#adding-notes-to-existing-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>Best Practice:</strong> For related content (email threads, chat conversations, workflows), add Notes to the existing Activity rather than creating new Activities.</p>
37
- <pre><code class="typescript"><span class="hl-7">// Add a new Note to an existing Activity</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">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-3">&quot;Update: Engineering team has identified the root cause. Fix will be deployed in the next release.&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 Fix&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/789&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>
43
+ <h4 id="adding-notes-to-existing-activities" class="tsd-anchor-link">Adding Notes to Existing Activities<a href="#adding-notes-to-existing-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>Best Practice:</strong> For related content (email threads, chat conversations, workflows), add Notes to the existing Activity rather than creating new Activities. Think of it like adding a message to an existing thread.</p>
44
+ <pre><code class="typescript"><span class="hl-7">// Add a new Note to an existing Activity (add message to thread)</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">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">content:</span><span class="hl-1"> </span><span class="hl-3">&quot;Update: Engineering team has identified the root cause. Fix will be deployed in the next release.&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 Fix&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/789&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>
38
45
  </code><button type="button">Copy</button></pre>
39
46
 
40
- <h4 id="pattern-email-threads-and-conversations" class="tsd-anchor-link">Pattern: Email Threads and Conversations<a href="#pattern-email-threads-and-conversations" 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>Keep all messages in a thread or conversation within a single Activity:</p>
41
- <pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">handleEmailThread</span><span class="hl-1">(</span><span class="hl-2">thread</span><span class="hl-1">: </span><span class="hl-2">EmailThread</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-7">// Check if Activity exists 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">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">email_thread_id:</span><span class="hl-1"> </span><span class="hl-2">thread</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">,</span><br/><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-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 new messages as Notes</span><br/><span class="hl-1"> </span><span class="hl-0">for</span><span class="hl-1"> (</span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">message</span><span class="hl-1"> </span><span class="hl-4">of</span><span class="hl-1"> </span><span class="hl-2">thread</span><span class="hl-1">.</span><span class="hl-2">newMessages</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">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">message</span><span class="hl-1">.</span><span class="hl-2">body</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">sender</span><span class="hl-1">,</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> } </span><span class="hl-0">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-4">const</span><span class="hl-1"> </span><span class="hl-8">firstMessage</span><span class="hl-1"> = </span><span class="hl-2">thread</span><span class="hl-1">.</span><span class="hl-2">messages</span><span class="hl-1">[</span><span class="hl-13">0</span><span class="hl-1">];</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">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">thread</span><span class="hl-1">.</span><span class="hl-2">subject</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">firstMessage</span><span class="hl-1">.</span><span class="hl-2">body</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">email_thread_id:</span><span class="hl-1"> </span><span class="hl-2">thread</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">notes:</span><span class="hl-1"> </span><span class="hl-2">thread</span><span class="hl-1">.</span><span class="hl-2">messages</span><span class="hl-1">.</span><span class="hl-6">map</span><span class="hl-1">((</span><span class="hl-2">msg</span><span class="hl-1">) </span><span class="hl-4">=&gt;</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">msg</span><span class="hl-1">.</span><span class="hl-2">body</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">msg</span><span class="hl-1">.</span><span class="hl-2">sender</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>
47
+ <h4 id="pattern-email-threads-and-conversations" class="tsd-anchor-link">Pattern: Email Threads and Conversations<a href="#pattern-email-threads-and-conversations" 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>Keep all messages in a thread or conversation within a single Activity. Think of it like a messaging app - one thread, many messages:</p>
48
+ <pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">handleEmailThread</span><span class="hl-1">(</span><span class="hl-2">thread</span><span class="hl-1">: </span><span class="hl-2">EmailThread</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">source</span><span class="hl-1"> = </span><span class="hl-3">`email:thread:</span><span class="hl-4">${</span><span class="hl-2">thread</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Check if Activity exists 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">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><span class="hl-2">source</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">existing</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-7">// Add new messages as Notes to the existing thread</span><br/><span class="hl-1"> </span><span class="hl-0">for</span><span class="hl-1"> (</span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">message</span><span class="hl-1"> </span><span class="hl-4">of</span><span class="hl-1"> </span><span class="hl-2">thread</span><span class="hl-1">.</span><span class="hl-2">newMessages</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">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">content:</span><span class="hl-1"> </span><span class="hl-2">message</span><span class="hl-1">.</span><span class="hl-2">body</span><span class="hl-1">,</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> } </span><span class="hl-0">else</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-7">// Create new thread with initial messages</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">thread</span><span class="hl-1">.</span><span class="hl-2">subject</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">source</span><span class="hl-1">, </span><span class="hl-7">// For future deduplication</span><br/><span class="hl-1"> </span><span class="hl-2">notes:</span><span class="hl-1"> </span><span class="hl-2">thread</span><span class="hl-1">.</span><span class="hl-2">messages</span><span class="hl-1">.</span><span class="hl-6">map</span><span class="hl-1">((</span><span class="hl-2">msg</span><span class="hl-1">) </span><span class="hl-4">=&gt;</span><span class="hl-1"> ({</span><br/><span class="hl-1"> </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-2">msg</span><span class="hl-1">.</span><span class="hl-2">body</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>
42
49
  </code><button type="button">Copy</button></pre>
43
50
 
44
51
  <p><strong>Why this matters:</strong> A conversation with 20 messages should be one Activity with 20 Notes, not 20 separate Activities. This keeps the workspace organized and provides better context.</p>
45
52
  <hr>
46
53
  <h2 id="store" class="tsd-anchor-link">Store<a href="#store" 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>Persistent key-value storage for twist state. Store methods are available directly on the twist class.</p>
47
54
  <h3 id="setup-1" class="tsd-anchor-link">Setup<a href="#setup-1" 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>Store is available automatically - no build() declaration needed!</p>
48
- <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 a string</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">// Save an object</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;config&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">enabled:</span><span class="hl-1"> </span><span class="hl-4">true</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">interval:</span><span class="hl-1"> </span><span class="hl-13">3600</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Save an array</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;items&quot;</span><span class="hl-1">, [</span><span class="hl-3">&quot;a&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;b&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;c&quot;</span><span class="hl-1">]);</span>
55
+ <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 a string</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">// Save an object</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;config&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">enabled:</span><span class="hl-1"> </span><span class="hl-4">true</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">interval:</span><span class="hl-1"> </span><span class="hl-14">3600</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Save an array</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;items&quot;</span><span class="hl-1">, [</span><span class="hl-3">&quot;a&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;b&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;c&quot;</span><span class="hl-1">]);</span>
49
56
  </code><button type="button">Copy</button></pre>
50
57
 
51
58
  <h3 id="retrieving-data" class="tsd-anchor-link">Retrieving Data<a href="#retrieving-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">// Get with type safety</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><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">config</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-2">enabled</span><span class="hl-1">: </span><span class="hl-5">boolean</span><span class="hl-1">; </span><span class="hl-2">interval</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1"> }&gt;(</span><span class="hl-3">&quot;config&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// Handle missing data</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">value</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;key&quot;</span><span class="hl-1">);</span><br/><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">value</span><span class="hl-1"> === </span><span class="hl-4">null</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-7">// Key doesn&#39;t exist</span><br/><span class="hl-1">}</span>
@@ -59,7 +66,7 @@
59
66
  </code><button type="button">Copy</button></pre>
60
67
 
61
68
  <h4 id="namespacing" class="tsd-anchor-link">Namespacing<a href="#namespacing" 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>Use prefixes to organize related data:</p>
62
- <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-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;webhook:calendar&quot;</span><span class="hl-1">, </span><span class="hl-2">webhookUrl</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">set</span><span class="hl-1">(</span><span class="hl-3">&quot;webhook:github&quot;</span><span class="hl-1">, </span><span class="hl-2">githubWebhookUrl</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">set</span><span class="hl-1">(</span><span class="hl-3">&quot;config:sync_interval&quot;</span><span class="hl-1">, </span><span class="hl-13">3600</span><span class="hl-1">);</span>
69
+ <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-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;webhook:calendar&quot;</span><span class="hl-1">, </span><span class="hl-2">webhookUrl</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">set</span><span class="hl-1">(</span><span class="hl-3">&quot;webhook:github&quot;</span><span class="hl-1">, </span><span class="hl-2">githubWebhookUrl</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">set</span><span class="hl-1">(</span><span class="hl-3">&quot;config:sync_interval&quot;</span><span class="hl-1">, </span><span class="hl-14">3600</span><span class="hl-1">);</span>
63
70
  </code><button type="button">Copy</button></pre>
64
71
 
65
72
  <h4 id="serialization-limits" class="tsd-anchor-link">Serialization Limits<a href="#serialization-limits" 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>Remember: Values must be JSON-serializable. Functions, Symbols, and undefined values cannot be stored.</p>
@@ -82,13 +89,13 @@
82
89
  <li><strong>AuthLevel.Priority</strong> - Auth scoped to the current priority</li>
83
90
  <li><strong>AuthLevel.User</strong> - Auth scoped to the user across all priorities</li>
84
91
  </ul>
85
- <h3 id="using-auth-tokens" class="tsd-anchor-link">Using Auth Tokens<a href="#using-auth-tokens" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-7">// Retrieve saved authorization</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">authorization</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">Authorization</span><span class="hl-1">&gt;(</span><span class="hl-3">&quot;google_auth&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">authorization</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">authToken</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">integrations</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">(</span><span class="hl-2">authorization</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Use token with external API</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">response</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-6">fetch</span><span class="hl-1">(</span><br/><span class="hl-1"> </span><span class="hl-3">&quot;https://www.googleapis.com/calendar/v3/calendars/primary/events&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">headers:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">Authorization:</span><span class="hl-1"> </span><span class="hl-3">`Bearer </span><span class="hl-4">${</span><span class="hl-2">authToken</span><span class="hl-14">.</span><span class="hl-2">token</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> );</span><br/><span class="hl-1">}</span>
92
+ <h3 id="using-auth-tokens" class="tsd-anchor-link">Using Auth Tokens<a href="#using-auth-tokens" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-7">// Retrieve saved authorization</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">authorization</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">Authorization</span><span class="hl-1">&gt;(</span><span class="hl-3">&quot;google_auth&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">authorization</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">authToken</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">integrations</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">(</span><span class="hl-2">authorization</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Use token with external API</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">response</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-6">fetch</span><span class="hl-1">(</span><br/><span class="hl-1"> </span><span class="hl-3">&quot;https://www.googleapis.com/calendar/v3/calendars/primary/events&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">headers:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">Authorization:</span><span class="hl-1"> </span><span class="hl-3">`Bearer </span><span class="hl-4">${</span><span class="hl-2">authToken</span><span class="hl-13">.</span><span class="hl-2">token</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> );</span><br/><span class="hl-1">}</span>
86
93
  </code><button type="button">Copy</button></pre>
87
94
 
88
95
  <hr>
89
96
  <h2 id="tasks" class="tsd-anchor-link">Tasks<a href="#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><p>Queue background tasks and schedule operations. Tasks methods are available directly on the twist class.</p>
90
97
  <h3 id="setup-3" class="tsd-anchor-link">Setup<a href="#setup-3" 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>Tasks are available automatically - no build() declaration needed!</p>
91
- <h3 id="running-tasks-immediately" class="tsd-anchor-link">Running Tasks Immediately<a href="#running-tasks-immediately" 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">// Create a callback</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><span class="hl-2">batchId:</span><span class="hl-1"> </span><span class="hl-13">1</span><span class="hl-1"> });</span><br/><br/><span class="hl-7">// Run immediately</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">// The processData method will be called</span><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">processData</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">batchId:</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-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 batch:&quot;</span><span class="hl-1">, </span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">batchId</span><span class="hl-1">);</span><br/><span class="hl-1">}</span>
98
+ <h3 id="running-tasks-immediately" class="tsd-anchor-link">Running Tasks Immediately<a href="#running-tasks-immediately" 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">// Create a callback</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><span class="hl-2">batchId:</span><span class="hl-1"> </span><span class="hl-14">1</span><span class="hl-1"> });</span><br/><br/><span class="hl-7">// Run immediately</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">// The processData method will be called</span><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">processData</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">batchId:</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-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 batch:&quot;</span><span class="hl-1">, </span><span class="hl-2">context</span><span class="hl-1">.</span><span class="hl-2">batchId</span><span class="hl-1">);</span><br/><span class="hl-1">}</span>
92
99
  </code><button type="button">Copy</button></pre>
93
100
 
94
101
  <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">// Schedule for a specific time</span><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">reminderCallback</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;sendReminder&quot;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">userId:</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><span class="hl-2">message:</span><span class="hl-1"> </span><span class="hl-3">&quot;Meeting in 10 minutes&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">token</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">reminderCallback</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-01T09:50:00Z&quot;</span><span class="hl-1">),</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Save token to cancel later if needed</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;reminder_token&quot;</span><span class="hl-1">, </span><span class="hl-2">token</span><span class="hl-1">);</span>
@@ -98,7 +105,7 @@
98
105
  </code><button type="button">Copy</button></pre>
99
106
 
100
107
  <h3 id="batch-processing-pattern" class="tsd-anchor-link">Batch Processing Pattern<a href="#batch-processing-pattern" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Use tasks to break long operations into manageable chunks:</p>
101
- <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-7">// Initialize state</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_state&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-13">1</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">hasMore:</span><span class="hl-1"> </span><span class="hl-4">true</span><br/><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Start first 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-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><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">state</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;{ </span><span class="hl-2">page</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1">; </span><span class="hl-2">hasMore</span><span class="hl-1">: </span><span class="hl-5">boolean</span><span class="hl-1"> }&gt;(</span><span class="hl-3">&quot;sync_state&quot;</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (!</span><span class="hl-2">state</span><span class="hl-1"> || !</span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">hasMore</span><span class="hl-1">) </span><span class="hl-0">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-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">results</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">fetchPage</span><span class="hl-1">(</span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">page</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">processResults</span><span class="hl-1">(</span><span class="hl-2">results</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Check if more work remains</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">results</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-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;sync_state&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">state</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-2">hasMore:</span><span class="hl-1"> </span><span class="hl-4">true</span><br/><span class="hl-1"> });</span><br/><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-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-0">else</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_state&quot;</span><span class="hl-1">, { </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1">, </span><span class="hl-2">hasMore:</span><span class="hl-1"> </span><span class="hl-4">false</span><span class="hl-1"> });</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
108
+ <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-7">// Initialize state</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_state&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-14">1</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">hasMore:</span><span class="hl-1"> </span><span class="hl-4">true</span><br/><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Start first 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-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><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">state</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;{ </span><span class="hl-2">page</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1">; </span><span class="hl-2">hasMore</span><span class="hl-1">: </span><span class="hl-5">boolean</span><span class="hl-1"> }&gt;(</span><span class="hl-3">&quot;sync_state&quot;</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (!</span><span class="hl-2">state</span><span class="hl-1"> || !</span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">hasMore</span><span class="hl-1">) </span><span class="hl-0">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-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">results</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">fetchPage</span><span class="hl-1">(</span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">page</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">processResults</span><span class="hl-1">(</span><span class="hl-2">results</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Check if more work remains</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">results</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-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;sync_state&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">state</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1"> + </span><span class="hl-14">1</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">hasMore:</span><span class="hl-1"> </span><span class="hl-4">true</span><br/><span class="hl-1"> });</span><br/><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-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-0">else</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">&quot;sync_state&quot;</span><span class="hl-1">, { </span><span class="hl-2">page:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">page</span><span class="hl-1">, </span><span class="hl-2">hasMore:</span><span class="hl-1"> </span><span class="hl-4">false</span><span class="hl-1"> });</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
102
109
  </code><button type="button">Copy</button></pre>
103
110
 
104
111
  <p>See <a href="Runtime_Environment.html">Runtime Environment</a> for more about handling long operations.</p>
@@ -149,7 +156,7 @@
149
156
  </code><button type="button">Copy</button></pre>
150
157
 
151
158
  <h3 id="structured-output" class="tsd-anchor-link">Structured Output<a href="#structured-output" 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 Typebox schemas to get type-safe structured responses:</p>
152
- <pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Type</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;typebox&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">schema</span><span class="hl-1"> = </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Object</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">category:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Union</span><span class="hl-1">([</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;work&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;personal&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;urgent&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> ]),</span><br/><span class="hl-1"> </span><span class="hl-2">priority:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Number</span><span class="hl-1">({ </span><span class="hl-2">minimum:</span><span class="hl-1"> </span><span class="hl-13">1</span><span class="hl-1">, </span><span class="hl-2">maximum:</span><span class="hl-1"> </span><span class="hl-13">5</span><span class="hl-1"> }),</span><br/><span class="hl-1"> </span><span class="hl-2">summary:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">String</span><span class="hl-1">({ </span><span class="hl-2">description:</span><span class="hl-1"> </span><span class="hl-3">&quot;Brief summary&quot;</span><span class="hl-1"> }),</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">response</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">ai</span><span class="hl-1">.</span><span class="hl-6">prompt</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">model:</span><span class="hl-1"> { </span><span class="hl-2">speed:</span><span class="hl-1"> </span><span class="hl-3">&quot;balanced&quot;</span><span class="hl-1">, </span><span class="hl-2">cost:</span><span class="hl-1"> </span><span class="hl-3">&quot;medium&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-2">prompt:</span><span class="hl-1"> </span><span class="hl-3">&quot;Categorize this email: Meeting at 3pm tomorrow about Q1 planning&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">outputSchema:</span><span class="hl-1"> </span><span class="hl-2">schema</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Fully typed output!</span><br/><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-2">response</span><span class="hl-1">.</span><span class="hl-2">output</span><span class="hl-1">.</span><span class="hl-2">category</span><span class="hl-1">); </span><span class="hl-7">// &quot;work&quot; | &quot;personal&quot; | &quot;urgent&quot;</span><br/><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-2">response</span><span class="hl-1">.</span><span class="hl-2">output</span><span class="hl-1">.</span><span class="hl-2">priority</span><span class="hl-1">); </span><span class="hl-7">// number (1-5)</span><br/><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-2">response</span><span class="hl-1">.</span><span class="hl-2">output</span><span class="hl-1">.</span><span class="hl-2">summary</span><span class="hl-1">); </span><span class="hl-7">// string</span>
159
+ <pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Type</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;typebox&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">schema</span><span class="hl-1"> = </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Object</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">category:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Union</span><span class="hl-1">([</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;work&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;personal&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;urgent&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> ]),</span><br/><span class="hl-1"> </span><span class="hl-2">priority:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Number</span><span class="hl-1">({ </span><span class="hl-2">minimum:</span><span class="hl-1"> </span><span class="hl-14">1</span><span class="hl-1">, </span><span class="hl-2">maximum:</span><span class="hl-1"> </span><span class="hl-14">5</span><span class="hl-1"> }),</span><br/><span class="hl-1"> </span><span class="hl-2">summary:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">String</span><span class="hl-1">({ </span><span class="hl-2">description:</span><span class="hl-1"> </span><span class="hl-3">&quot;Brief summary&quot;</span><span class="hl-1"> }),</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">response</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">ai</span><span class="hl-1">.</span><span class="hl-6">prompt</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">model:</span><span class="hl-1"> { </span><span class="hl-2">speed:</span><span class="hl-1"> </span><span class="hl-3">&quot;balanced&quot;</span><span class="hl-1">, </span><span class="hl-2">cost:</span><span class="hl-1"> </span><span class="hl-3">&quot;medium&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-2">prompt:</span><span class="hl-1"> </span><span class="hl-3">&quot;Categorize this email: Meeting at 3pm tomorrow about Q1 planning&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">outputSchema:</span><span class="hl-1"> </span><span class="hl-2">schema</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// Fully typed output!</span><br/><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-2">response</span><span class="hl-1">.</span><span class="hl-2">output</span><span class="hl-1">.</span><span class="hl-2">category</span><span class="hl-1">); </span><span class="hl-7">// &quot;work&quot; | &quot;personal&quot; | &quot;urgent&quot;</span><br/><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-2">response</span><span class="hl-1">.</span><span class="hl-2">output</span><span class="hl-1">.</span><span class="hl-2">priority</span><span class="hl-1">); </span><span class="hl-7">// number (1-5)</span><br/><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-2">response</span><span class="hl-1">.</span><span class="hl-2">output</span><span class="hl-1">.</span><span class="hl-2">summary</span><span class="hl-1">); </span><span class="hl-7">// string</span>
153
160
  </code><button type="button">Copy</button></pre>
154
161
 
155
162
  <h3 id="tool-calling" class="tsd-anchor-link">Tool Calling<a href="#tool-calling" 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>Give the AI access to tools it can call:</p>
@@ -170,7 +177,7 @@
170
177
  </code><button type="button">Copy</button></pre>
171
178
 
172
179
  <p>See the <a href="https://github.com/sinclairzx81/typebox">Typebox documentation</a> for more schema types.</p>
173
- <h3 id="real-world-example-email-triage" class="tsd-anchor-link">Real-World Example: Email Triage<a href="#real-world-example-email-triage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Type</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;typebox&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">triageEmail</span><span class="hl-1">(</span><span class="hl-2">emailContent</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">schema</span><span class="hl-1"> = </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Object</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">category:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Union</span><span class="hl-1">([</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;urgent&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;important&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;informational&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;spam&quot;</span><span class="hl-1">)</span><br/><span class="hl-1"> ]),</span><br/><span class="hl-1"> </span><span class="hl-2">requiresResponse:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Boolean</span><span class="hl-1">(),</span><br/><span class="hl-1"> </span><span class="hl-2">suggestedActions:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Array</span><span class="hl-1">(</span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">String</span><span class="hl-1">()),</span><br/><span class="hl-1"> </span><span class="hl-2">summary:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">String</span><span class="hl-1">({ </span><span class="hl-2">maxLength:</span><span class="hl-1"> </span><span class="hl-13">200</span><span class="hl-1"> })</span><br/><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">response</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">ai</span><span class="hl-1">.</span><span class="hl-6">prompt</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">model:</span><span class="hl-1"> { </span><span class="hl-2">speed:</span><span class="hl-1"> </span><span class="hl-3">&quot;balanced&quot;</span><span class="hl-1">, </span><span class="hl-2">cost:</span><span class="hl-1"> </span><span class="hl-3">&quot;medium&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-2">prompt:</span><span class="hl-1"> </span><span class="hl-3">`Analyze this email and provide triage information:</span><span class="hl-12">\n\n</span><span class="hl-4">${</span><span class="hl-2">emailContent</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">outputSchema:</span><span class="hl-1"> </span><span class="hl-2">schema</span><br/><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Create activity based on triage</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">response</span><span class="hl-1">.</span><span class="hl-2">output</span><span class="hl-1">.</span><span class="hl-2">category</span><span class="hl-1"> === </span><span class="hl-3">&quot;urgent&quot;</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">`URGENT: </span><span class="hl-4">${</span><span class="hl-2">response</span><span class="hl-14">.</span><span class="hl-2">output</span><span class="hl-14">.</span><span class="hl-2">summary</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">note:</span><span class="hl-1"> </span><span class="hl-3">`Actions:</span><span class="hl-12">\n</span><span class="hl-4">${</span><span class="hl-2">response</span><span class="hl-14">.</span><span class="hl-2">output</span><span class="hl-14">.</span><span class="hl-2">suggestedActions</span><span class="hl-14">.</span><span class="hl-6">join</span><span class="hl-14">(</span><span class="hl-3">&quot;</span><span class="hl-12">\n</span><span class="hl-3">&quot;</span><span class="hl-14">)</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> ],</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
180
+ <h3 id="real-world-example-email-triage" class="tsd-anchor-link">Real-World Example: Email Triage<a href="#real-world-example-email-triage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Type</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;typebox&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">triageEmail</span><span class="hl-1">(</span><span class="hl-2">emailContent</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">schema</span><span class="hl-1"> = </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Object</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">category:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Union</span><span class="hl-1">([</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;urgent&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;important&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;informational&quot;</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Literal</span><span class="hl-1">(</span><span class="hl-3">&quot;spam&quot;</span><span class="hl-1">)</span><br/><span class="hl-1"> ]),</span><br/><span class="hl-1"> </span><span class="hl-2">requiresResponse:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Boolean</span><span class="hl-1">(),</span><br/><span class="hl-1"> </span><span class="hl-2">suggestedActions:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">Array</span><span class="hl-1">(</span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">String</span><span class="hl-1">()),</span><br/><span class="hl-1"> </span><span class="hl-2">summary:</span><span class="hl-1"> </span><span class="hl-2">Type</span><span class="hl-1">.</span><span class="hl-6">String</span><span class="hl-1">({ </span><span class="hl-2">maxLength:</span><span class="hl-1"> </span><span class="hl-14">200</span><span class="hl-1"> })</span><br/><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">response</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">ai</span><span class="hl-1">.</span><span class="hl-6">prompt</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">model:</span><span class="hl-1"> { </span><span class="hl-2">speed:</span><span class="hl-1"> </span><span class="hl-3">&quot;balanced&quot;</span><span class="hl-1">, </span><span class="hl-2">cost:</span><span class="hl-1"> </span><span class="hl-3">&quot;medium&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-2">prompt:</span><span class="hl-1"> </span><span class="hl-3">`Analyze this email and provide triage information:</span><span class="hl-12">\n\n</span><span class="hl-4">${</span><span class="hl-2">emailContent</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">outputSchema:</span><span class="hl-1"> </span><span class="hl-2">schema</span><br/><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Create activity based on triage</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">response</span><span class="hl-1">.</span><span class="hl-2">output</span><span class="hl-1">.</span><span class="hl-2">category</span><span class="hl-1"> === </span><span class="hl-3">&quot;urgent&quot;</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">`URGENT: </span><span class="hl-4">${</span><span class="hl-2">response</span><span class="hl-13">.</span><span class="hl-2">output</span><span class="hl-13">.</span><span class="hl-2">summary</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">notes:</span><span class="hl-1"> [</span><br/><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">note:</span><span class="hl-1"> </span><span class="hl-3">`Actions:</span><span class="hl-12">\n</span><span class="hl-4">${</span><span class="hl-2">response</span><span class="hl-13">.</span><span class="hl-2">output</span><span class="hl-13">.</span><span class="hl-2">suggestedActions</span><span class="hl-13">.</span><span class="hl-6">join</span><span class="hl-13">(</span><span class="hl-3">&quot;</span><span class="hl-12">\n</span><span class="hl-3">&quot;</span><span class="hl-13">)</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> ],</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
174
181
  </code><button type="button">Copy</button></pre>
175
182
 
176
183
  <hr>
@@ -179,4 +186,4 @@
179
186
  <li><strong><a href="Runtime_Environment.html">Runtime Environment</a></strong> - Understanding execution constraints</li>
180
187
  <li><strong>API Reference</strong> - Explore detailed API docs in the sidebar</li>
181
188
  </ul>
182
- </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#built-in-tools"><span>Built-<wbr/>in <wbr/>Tools</span></a><ul><li><a href="#table-of-contents"><span>Table of <wbr/>Contents</span></a></li><li><a href="#plot"><span>Plot</span></a></li><li><ul><li><a href="#setup"><span>Setup</span></a></li><li><a href="#creating-activities"><span>Creating <wbr/>Activities</span></a></li><li><a href="#updating-activities"><span>Updating <wbr/>Activities</span></a></li><li><a href="#deleting-activities"><span>Deleting <wbr/>Activities</span></a></li><li><a href="#managing-priorities"><span>Managing <wbr/>Priorities</span></a></li><li><a href="#activity-meta"><span>Activity <wbr/>Meta</span></a></li><li><a href="#creating-and-managing-notes"><span>Creating and <wbr/>Managing <wbr/>Notes</span></a></li><li><ul><li><a href="#creating-notes-on-new-activities"><span>Creating <wbr/>Notes on <wbr/>New <wbr/>Activities</span></a></li><li><a href="#adding-notes-to-existing-activities"><span>Adding <wbr/>Notes to <wbr/>Existing <wbr/>Activities</span></a></li><li><a href="#pattern-email-threads-and-conversations"><span>Pattern: <wbr/>Email <wbr/>Threads and <wbr/>Conversations</span></a></li></ul></li></ul></li><li><a href="#store"><span>Store</span></a></li><li><ul><li><a href="#setup-1"><span>Setup</span></a></li><li><a href="#storing-data"><span>Storing <wbr/>Data</span></a></li><li><a href="#retrieving-data"><span>Retrieving <wbr/>Data</span></a></li><li><a href="#clearing-data"><span>Clearing <wbr/>Data</span></a></li><li><a href="#best-practices"><span>Best <wbr/>Practices</span></a></li><li><ul><li><a href="#type-safety"><span>Type <wbr/>Safety</span></a></li><li><a href="#namespacing"><span>Namespacing</span></a></li><li><a href="#serialization-limits"><span>Serialization <wbr/>Limits</span></a></li></ul></li></ul></li><li><a href="#integrations"><span>Integrations</span></a></li><li><ul><li><a href="#setup-2"><span>Setup</span></a></li><li><a href="#requesting-authentication"><span>Requesting <wbr/>Authentication</span></a></li><li><a href="#auth-providers"><span>Auth <wbr/>Providers</span></a></li><li><a href="#auth-levels"><span>Auth <wbr/>Levels</span></a></li><li><a href="#using-auth-tokens"><span>Using <wbr/>Auth <wbr/>Tokens</span></a></li></ul></li><li><a href="#tasks"><span>Tasks</span></a></li><li><ul><li><a href="#setup-3"><span>Setup</span></a></li><li><a href="#running-tasks-immediately"><span>Running <wbr/>Tasks <wbr/>Immediately</span></a></li><li><a href="#scheduling-tasks"><span>Scheduling <wbr/>Tasks</span></a></li><li><a href="#canceling-tasks"><span>Canceling <wbr/>Tasks</span></a></li><li><a href="#batch-processing-pattern"><span>Batch <wbr/>Processing <wbr/>Pattern</span></a></li></ul></li><li><a href="#network"><span>Network</span></a></li><li><ul><li><a href="#setup-4"><span>Setup</span></a></li><li><a href="#making-http-requests"><span>Making <wbr/>HTTP <wbr/>Requests</span></a></li><li><a href="#creating-webhooks"><span>Creating <wbr/>Webhooks</span></a></li><li><a href="#deleting-webhooks"><span>Deleting <wbr/>Webhooks</span></a></li></ul></li><li><a href="#callbacks"><span>Callbacks</span></a></li><li><ul><li><a href="#setup-5"><span>Setup</span></a></li><li><a href="#creating-callbacks"><span>Creating <wbr/>Callbacks</span></a></li><li><a href="#executing-callbacks"><span>Executing <wbr/>Callbacks</span></a></li><li><a href="#method-signature"><span>Method <wbr/>Signature</span></a></li><li><a href="#deleting-callbacks"><span>Deleting <wbr/>Callbacks</span></a></li><li><a href="#use-cases"><span>Use <wbr/>Cases</span></a></li></ul></li><li><a href="#ai"><span>AI</span></a></li><li><ul><li><a href="#setup-6"><span>Setup</span></a></li><li><a href="#simple-text-generation"><span>Simple <wbr/>Text <wbr/>Generation</span></a></li><li><a href="#structured-output"><span>Structured <wbr/>Output</span></a></li><li><a href="#tool-calling"><span>Tool <wbr/>Calling</span></a></li><li><a href="#multi-turn-conversations"><span>Multi-<wbr/>turn <wbr/>Conversations</span></a></li><li><a href="#model-selection"><span>Model <wbr/>Selection</span></a></li><li><a href="#typebox-schemas"><span>Typebox <wbr/>Schemas</span></a></li><li><a href="#real-world-example-email-triage"><span>Real-<wbr/>World <wbr/>Example: <wbr/>Email <wbr/>Triage</span></a></li></ul></li><li><a href="#next-steps"><span>Next <wbr/>Steps</span></a></li></ul></div></details></div><div class="site-menu"><nav id="tsd-sidebar-links" class="tsd-navigation"><a href="https://plot.day" class="tsd-nav-link">Plot</a><a href="https://github.com/plotday/plot" class="tsd-nav-link">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister" class="tsd-nav-link">NPM</a></nav><nav class="tsd-navigation"><a href="../modules.html">Creating Plot Twists</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
189
+ </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#built-in-tools"><span>Built-<wbr/>in <wbr/>Tools</span></a><ul><li><a href="#table-of-contents"><span>Table of <wbr/>Contents</span></a></li><li><a href="#plot"><span>Plot</span></a></li><li><ul><li><a href="#understanding-activities-and-notes"><span>Understanding <wbr/>Activities and <wbr/>Notes</span></a></li><li><a href="#setup"><span>Setup</span></a></li><li><a href="#creating-activities"><span>Creating <wbr/>Activities</span></a></li><li><ul><li><a href="#action-scheduling-states"><span>Action <wbr/>Scheduling <wbr/>States</span></a></li></ul></li><li><a href="#updating-activities"><span>Updating <wbr/>Activities</span></a></li><li><a href="#deleting-activities"><span>Deleting <wbr/>Activities</span></a></li><li><a href="#managing-priorities"><span>Managing <wbr/>Priorities</span></a></li><li><a href="#activity-source-and-meta"><span>Activity <wbr/>Source and <wbr/>Meta</span></a></li><li><a href="#creating-and-managing-notes"><span>Creating and <wbr/>Managing <wbr/>Notes</span></a></li><li><ul><li><a href="#creating-notes-on-new-activities"><span>Creating <wbr/>Notes on <wbr/>New <wbr/>Activities</span></a></li><li><a href="#adding-notes-to-existing-activities"><span>Adding <wbr/>Notes to <wbr/>Existing <wbr/>Activities</span></a></li><li><a href="#pattern-email-threads-and-conversations"><span>Pattern: <wbr/>Email <wbr/>Threads and <wbr/>Conversations</span></a></li></ul></li></ul></li><li><a href="#store"><span>Store</span></a></li><li><ul><li><a href="#setup-1"><span>Setup</span></a></li><li><a href="#storing-data"><span>Storing <wbr/>Data</span></a></li><li><a href="#retrieving-data"><span>Retrieving <wbr/>Data</span></a></li><li><a href="#clearing-data"><span>Clearing <wbr/>Data</span></a></li><li><a href="#best-practices"><span>Best <wbr/>Practices</span></a></li><li><ul><li><a href="#type-safety"><span>Type <wbr/>Safety</span></a></li><li><a href="#namespacing"><span>Namespacing</span></a></li><li><a href="#serialization-limits"><span>Serialization <wbr/>Limits</span></a></li></ul></li></ul></li><li><a href="#integrations"><span>Integrations</span></a></li><li><ul><li><a href="#setup-2"><span>Setup</span></a></li><li><a href="#requesting-authentication"><span>Requesting <wbr/>Authentication</span></a></li><li><a href="#auth-providers"><span>Auth <wbr/>Providers</span></a></li><li><a href="#auth-levels"><span>Auth <wbr/>Levels</span></a></li><li><a href="#using-auth-tokens"><span>Using <wbr/>Auth <wbr/>Tokens</span></a></li></ul></li><li><a href="#tasks"><span>Tasks</span></a></li><li><ul><li><a href="#setup-3"><span>Setup</span></a></li><li><a href="#running-tasks-immediately"><span>Running <wbr/>Tasks <wbr/>Immediately</span></a></li><li><a href="#scheduling-tasks"><span>Scheduling <wbr/>Tasks</span></a></li><li><a href="#canceling-tasks"><span>Canceling <wbr/>Tasks</span></a></li><li><a href="#batch-processing-pattern"><span>Batch <wbr/>Processing <wbr/>Pattern</span></a></li></ul></li><li><a href="#network"><span>Network</span></a></li><li><ul><li><a href="#setup-4"><span>Setup</span></a></li><li><a href="#making-http-requests"><span>Making <wbr/>HTTP <wbr/>Requests</span></a></li><li><a href="#creating-webhooks"><span>Creating <wbr/>Webhooks</span></a></li><li><a href="#deleting-webhooks"><span>Deleting <wbr/>Webhooks</span></a></li></ul></li><li><a href="#callbacks"><span>Callbacks</span></a></li><li><ul><li><a href="#setup-5"><span>Setup</span></a></li><li><a href="#creating-callbacks"><span>Creating <wbr/>Callbacks</span></a></li><li><a href="#executing-callbacks"><span>Executing <wbr/>Callbacks</span></a></li><li><a href="#method-signature"><span>Method <wbr/>Signature</span></a></li><li><a href="#deleting-callbacks"><span>Deleting <wbr/>Callbacks</span></a></li><li><a href="#use-cases"><span>Use <wbr/>Cases</span></a></li></ul></li><li><a href="#ai"><span>AI</span></a></li><li><ul><li><a href="#setup-6"><span>Setup</span></a></li><li><a href="#simple-text-generation"><span>Simple <wbr/>Text <wbr/>Generation</span></a></li><li><a href="#structured-output"><span>Structured <wbr/>Output</span></a></li><li><a href="#tool-calling"><span>Tool <wbr/>Calling</span></a></li><li><a href="#multi-turn-conversations"><span>Multi-<wbr/>turn <wbr/>Conversations</span></a></li><li><a href="#model-selection"><span>Model <wbr/>Selection</span></a></li><li><a href="#typebox-schemas"><span>Typebox <wbr/>Schemas</span></a></li><li><a href="#real-world-example-email-triage"><span>Real-<wbr/>World <wbr/>Example: <wbr/>Email <wbr/>Triage</span></a></li></ul></li><li><a href="#next-steps"><span>Next <wbr/>Steps</span></a></li></ul></div></details></div><div class="site-menu"><nav id="tsd-sidebar-links" class="tsd-navigation"><a href="https://plot.day" class="tsd-nav-link">Plot</a><a href="https://github.com/plotday/plot" class="tsd-nav-link">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister" class="tsd-nav-link">NPM</a></nav><nav class="tsd-navigation"><a href="../modules.html">Creating Plot Twists</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>