@plotday/twister 0.38.0 → 0.39.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 (111) hide show
  1. package/README.md +22 -16
  2. package/bin/commands/create.js +4 -4
  3. package/bin/commands/create.js.map +1 -1
  4. package/bin/index.js +1 -1
  5. package/bin/index.js.map +1 -1
  6. package/bin/templates/AGENTS.template.md +32 -0
  7. package/bin/templates/README.template.md +2 -2
  8. package/bin/utils/bundle.js +1 -1
  9. package/bin/utils/bundle.js.map +1 -1
  10. package/cli/templates/AGENTS.template.md +32 -0
  11. package/cli/templates/README.template.md +2 -2
  12. package/dist/{source.d.ts → connector.d.ts} +24 -22
  13. package/dist/connector.d.ts.map +1 -0
  14. package/dist/{source.js → connector.js} +23 -21
  15. package/dist/connector.js.map +1 -0
  16. package/dist/docs/assets/hierarchy.js +1 -1
  17. package/dist/docs/assets/navigation.js +1 -1
  18. package/dist/docs/assets/search.js +1 -1
  19. package/dist/docs/classes/{index.Source.html → index.Connector.html} +27 -27
  20. package/dist/docs/classes/index.Options.html +1 -1
  21. package/dist/docs/classes/tools_ai.AI.html +7 -3
  22. package/dist/docs/classes/tools_callbacks.Callbacks.html +1 -1
  23. package/dist/docs/classes/tools_integrations.Integrations.html +11 -11
  24. package/dist/docs/classes/tools_network.Network.html +1 -1
  25. package/dist/docs/classes/tools_plot.Plot.html +23 -21
  26. package/dist/docs/classes/tools_store.Store.html +1 -1
  27. package/dist/docs/classes/tools_tasks.Tasks.html +1 -1
  28. package/dist/docs/classes/tools_twists.Twists.html +3 -3
  29. package/dist/docs/classes/twist.Twist.html +1 -1
  30. package/dist/docs/documents/Building_Connectors.html +137 -0
  31. package/dist/docs/documents/Built-in_Tools.html +3 -3
  32. package/dist/docs/documents/Core_Concepts.html +5 -5
  33. package/dist/docs/documents/Getting_Started.html +1 -1
  34. package/dist/docs/enums/tools_ai.AIModel.html +2 -2
  35. package/dist/docs/hierarchy.html +1 -1
  36. package/dist/docs/index.html +3 -3
  37. package/dist/docs/interfaces/tools_ai.AIRequest.html +11 -11
  38. package/dist/docs/interfaces/tools_ai.AIResponse.html +9 -9
  39. package/dist/docs/interfaces/tools_ai.FilePart.html +5 -5
  40. package/dist/docs/interfaces/tools_ai.ImagePart.html +4 -4
  41. package/dist/docs/interfaces/tools_ai.ReasoningPart.html +4 -4
  42. package/dist/docs/interfaces/tools_ai.RedactedReasoningPart.html +3 -3
  43. package/dist/docs/interfaces/tools_ai.TextPart.html +3 -3
  44. package/dist/docs/interfaces/tools_ai.ToolCallPart.html +5 -5
  45. package/dist/docs/interfaces/tools_ai.ToolExecutionOptions.html +4 -4
  46. package/dist/docs/interfaces/tools_ai.ToolResultPart.html +5 -5
  47. package/dist/docs/media/AGENTS.md +82 -65
  48. package/dist/docs/media/MULTI_USER_AUTH.md +1 -1
  49. package/dist/docs/media/SYNC_STRATEGIES.md +9 -9
  50. package/dist/docs/modules/index.html +1 -1
  51. package/dist/docs/modules/tools_ai.html +1 -1
  52. package/dist/docs/modules.html +1 -1
  53. package/dist/docs/types/tools_ai.AIAssistantMessage.html +2 -2
  54. package/dist/docs/types/tools_ai.AICapabilities.html +6 -0
  55. package/dist/docs/types/tools_ai.AIMessage.html +1 -1
  56. package/dist/docs/types/tools_ai.AIOptions.html +4 -0
  57. package/dist/docs/types/tools_ai.AISource.html +1 -1
  58. package/dist/docs/types/tools_ai.AISystemMessage.html +2 -2
  59. package/dist/docs/types/tools_ai.AITool.html +1 -1
  60. package/dist/docs/types/tools_ai.AIToolMessage.html +2 -2
  61. package/dist/docs/types/tools_ai.AIToolSet.html +1 -1
  62. package/dist/docs/types/tools_ai.AIUsage.html +5 -5
  63. package/dist/docs/types/tools_ai.AIUserMessage.html +2 -2
  64. package/dist/docs/types/tools_ai.DataContent.html +1 -1
  65. package/dist/docs/types/tools_ai.ModelPreferences.html +4 -4
  66. package/dist/docs/types/tools_integrations.LinkTypeConfig.html +1 -1
  67. package/dist/index.d.ts +1 -1
  68. package/dist/index.d.ts.map +1 -1
  69. package/dist/index.js +1 -1
  70. package/dist/index.js.map +1 -1
  71. package/dist/llm-docs/connector.d.ts +9 -0
  72. package/dist/llm-docs/connector.d.ts.map +1 -0
  73. package/dist/llm-docs/connector.js +8 -0
  74. package/dist/llm-docs/connector.js.map +1 -0
  75. package/dist/llm-docs/index.js +2 -2
  76. package/dist/llm-docs/index.js.map +1 -1
  77. package/dist/llm-docs/tools/ai.d.ts +1 -1
  78. package/dist/llm-docs/tools/ai.d.ts.map +1 -1
  79. package/dist/llm-docs/tools/ai.js +1 -1
  80. package/dist/llm-docs/tools/ai.js.map +1 -1
  81. package/dist/llm-docs/tools/integrations.d.ts +1 -1
  82. package/dist/llm-docs/tools/integrations.d.ts.map +1 -1
  83. package/dist/llm-docs/tools/integrations.js +1 -1
  84. package/dist/llm-docs/tools/integrations.js.map +1 -1
  85. package/dist/llm-docs/tools/plot.d.ts +1 -1
  86. package/dist/llm-docs/tools/plot.d.ts.map +1 -1
  87. package/dist/llm-docs/tools/plot.js +1 -1
  88. package/dist/llm-docs/tools/plot.js.map +1 -1
  89. package/dist/llm-docs/twist-guide-template.d.ts +1 -1
  90. package/dist/llm-docs/twist-guide-template.d.ts.map +1 -1
  91. package/dist/llm-docs/twist-guide-template.js +1 -1
  92. package/dist/llm-docs/twist-guide-template.js.map +1 -1
  93. package/dist/tools/ai.d.ts +18 -0
  94. package/dist/tools/ai.d.ts.map +1 -1
  95. package/dist/tools/ai.js.map +1 -1
  96. package/dist/tools/integrations.d.ts +11 -11
  97. package/dist/tools/integrations.js +3 -3
  98. package/dist/tools/plot.d.ts +4 -0
  99. package/dist/tools/plot.d.ts.map +1 -1
  100. package/dist/tools/plot.js.map +1 -1
  101. package/dist/twist-guide.d.ts +1 -1
  102. package/dist/twist-guide.d.ts.map +1 -1
  103. package/package.json +38 -38
  104. package/tsconfig.base.json +1 -1
  105. package/dist/docs/documents/Building_Sources.html +0 -137
  106. package/dist/llm-docs/source.d.ts +0 -9
  107. package/dist/llm-docs/source.d.ts.map +0 -1
  108. package/dist/llm-docs/source.js +0 -8
  109. package/dist/llm-docs/source.js.map +0 -1
  110. package/dist/source.d.ts.map +0 -1
  111. package/dist/source.js.map +0 -1
package/dist/docs/documents/Building_Connectors.html ADDED
@@ -0,0 +1,137 @@
1
+ <!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>Building Connectors | Creating Plot Twists</title><link rel="icon" href="../assets/favicon.svg" type="image/svg+xml"/><meta name="description" content="Documentation for Creating Plot Twists"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="/" class="title">Creating Plot Twists</a><div id="tsd-toolbar-links"><a href="https://plot.day">Plot</a><a href="https://github.com/plotday/plot">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister">NPM</a></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">Building Connectors</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="building-connectors" class="tsd-anchor-link">Building Connectors<a href="#building-connectors" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1><p>Connectors connect Plot to external services like Google Calendar, Slack, Linear, and more. They sync data into Plot and optionally support bidirectional updates. This guide covers everything you need to know about building connectors.</p>
2
+ <h2 id="table-of-contents" class="tsd-anchor-link">Table of Contents<a href="#table-of-contents" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><ul>
3
+ <li><a href="#connectors-vs-twists">Connectors vs Twists</a></li>
4
+ <li><a href="#connector-structure">Connector Structure</a></li>
5
+ <li><a href="#oauth-and-channel-lifecycle">OAuth and Channel Lifecycle</a></li>
6
+ <li><a href="#data-sync">Data Sync</a></li>
7
+ <li><a href="#batch-processing">Batch Processing</a></li>
8
+ <li><a href="#complete-example">Complete Example</a></li>
9
+ <li><a href="#best-practices">Best Practices</a></li>
10
+ </ul>
11
+ <hr>
12
+ <h2 id="connectors-vs-twists" class="tsd-anchor-link">Connectors vs Twists<a href="#connectors-vs-twists" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><table>
13
+ <thead>
14
+ <tr>
15
+ <th></th>
16
+ <th>Connectors</th>
17
+ <th>Twists</th>
18
+ </tr>
19
+ </thead>
20
+ <tbody>
21
+ <tr>
22
+ <td><strong>Purpose</strong></td>
23
+ <td>Sync data from external services</td>
24
+ <td>Implement opinionated workflows</td>
25
+ </tr>
26
+ <tr>
27
+ <td><strong>Base class</strong></td>
28
+ <td><code>Connector&lt;T&gt;</code> (extends <code>Twist&lt;T&gt;</code>)</td>
29
+ <td><code>Twist&lt;T&gt;</code></td>
30
+ </tr>
31
+ <tr>
32
+ <td><strong>Auth</strong></td>
33
+ <td>OAuth via <code>Integrations</code> with channel lifecycle</td>
34
+ <td>Optional</td>
35
+ </tr>
36
+ <tr>
37
+ <td><strong>Data flow</strong></td>
38
+ <td>External service -&gt; Plot (and optionally back)</td>
39
+ <td>Internal logic, orchestration</td>
40
+ </tr>
41
+ <tr>
42
+ <td><strong>Examples</strong></td>
43
+ <td>Google Calendar, Slack, Linear, Jira</td>
44
+ <td>Task automation, AI assistants</td>
45
+ </tr>
46
+ </tbody>
47
+ </table>
48
+ <p><strong>Build a Connector</strong> when you need to integrate an external service — syncing calendars, issues, messages, etc.</p>
49
+ <p><strong>Build a Twist</strong> when you need workflow logic that doesn't require external service integration, or when you want to orchestrate multiple connectors.</p>
50
+ <hr>
51
+ <h2 id="connector-structure" class="tsd-anchor-link">Connector Structure<a href="#connector-structure" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Connectors extend the <code>Connector&lt;T&gt;</code> base class and declare dependencies using <code>ConnectorBuilder</code>:</p>
52
+ <pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">Connector</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">ConnectorBuilder</span><span class="hl-1">,</span><br/><span class="hl-1">} </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">AuthProvider</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">AuthToken</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Authorization</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Channel</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">Integrations</span><span class="hl-1">,</span><br/><span class="hl-1">} </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/integrations&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Network</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/network&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Plot</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/plot&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Tasks</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/tasks&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Callbacks</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/callbacks&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-0">export</span><span class="hl-1"> </span><span class="hl-0">default</span><span class="hl-1"> </span><span class="hl-4">class</span><span class="hl-1"> </span><span class="hl-5">MyConnector</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Connector</span><span class="hl-1">&lt;</span><span class="hl-5">MyConnector</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-4">static</span><span class="hl-1"> </span><span class="hl-4">readonly</span><span class="hl-1"> </span><span class="hl-2">PROVIDER</span><span class="hl-1"> = </span><span class="hl-2">AuthProvider</span><span class="hl-1">.</span><span class="hl-2">Linear</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-4">static</span><span class="hl-1"> </span><span class="hl-4">readonly</span><span class="hl-1"> </span><span class="hl-2">SCOPES</span><span class="hl-1"> = [</span><span class="hl-3">&quot;read&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;write&quot;</span><span class="hl-1">];</span><br/><br/><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">build</span><span class="hl-1">: </span><span class="hl-5">ConnectorBuilder</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">return</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">integrations:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Integrations</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">providers:</span><span class="hl-1"> [{</span><br/><span class="hl-1"> </span><span class="hl-2">provider:</span><span class="hl-1"> </span><span class="hl-2">MyConnector</span><span class="hl-1">.</span><span class="hl-8">PROVIDER</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">scopes:</span><span class="hl-1"> </span><span class="hl-2">MyConnector</span><span class="hl-1">.</span><span class="hl-8">SCOPES</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">getChannels:</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">getChannels</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">onChannelEnabled:</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">onChannelEnabled</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">onChannelDisabled:</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">onChannelDisabled</span><span class="hl-1">,</span><br/><span class="hl-1"> }],</span><br/><span class="hl-1"> }),</span><br/><span class="hl-1"> </span><span class="hl-2">network:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Network</span><span class="hl-1">, { </span><span class="hl-2">urls:</span><span class="hl-1"> [</span><span class="hl-3">&quot;https://api.example.com/*&quot;</span><span class="hl-1">] }),</span><br/><span class="hl-1"> </span><span class="hl-2">plot:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Plot</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">tasks:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Tasks</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">callbacks:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Callbacks</span><span class="hl-1">),</span><br/><span class="hl-1"> };</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// ... lifecycle methods below</span><br/><span class="hl-1">}</span>
53
+ </code><button type="button">Copy</button></pre>
54
+
55
+ <h3 id="package-structure" class="tsd-anchor-link">Package Structure<a href="#package-structure" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code><span class="hl-2">connectors</span><span class="hl-1">/</span><span class="hl-2">my</span><span class="hl-1">-</span><span class="hl-2">connector</span><span class="hl-1">/</span><br/><span class="hl-1"> </span><span class="hl-2">src</span><span class="hl-1">/</span><br/><span class="hl-1"> </span><span class="hl-2">index</span><span class="hl-1">.</span><span class="hl-2">ts</span><span class="hl-1"> # </span><span class="hl-2">Re</span><span class="hl-1">-</span><span class="hl-15">exports</span><span class="hl-1">: </span><span class="hl-0">export</span><span class="hl-1"> { </span><span class="hl-0">default</span><span class="hl-1">, </span><span class="hl-2">MyConnector</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;./my-connector&quot;</span><br/><span class="hl-1"> </span><span class="hl-2">my</span><span class="hl-1">-</span><span class="hl-2">connector</span><span class="hl-1">.</span><span class="hl-2">ts</span><span class="hl-1"> # </span><span class="hl-2">Main</span><span class="hl-1"> </span><span class="hl-2">Connector</span><span class="hl-1"> </span><span class="hl-4">class</span><br/><span class="hl-1"> </span><span class="hl-5">package</span><span class="hl-1">.</span><span class="hl-5">json</span><br/><span class="hl-1"> </span><span class="hl-5">tsconfig</span><span class="hl-1">.</span><span class="hl-5">json</span>
56
+ </code><button>Copy</button></pre>
57
+
58
+ <hr>
59
+ <h2 id="oauth-and-channel-lifecycle" class="tsd-anchor-link">OAuth and Channel Lifecycle<a href="#oauth-and-channel-lifecycle" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Connectors use the Integrations tool for OAuth. Auth is handled automatically in the Flutter edit modal — you don't need to build UI for it.</p>
60
+ <h3 id="how-it-works" class="tsd-anchor-link">How It Works<a href="#how-it-works" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><ol>
61
+ <li>Connector declares providers in <code>build()</code> with <code>getChannels</code>, <code>onChannelEnabled</code>, <code>onChannelDisabled</code> callbacks</li>
62
+ <li>User clicks &quot;Connect&quot; in the twist edit modal -&gt; OAuth flow happens automatically</li>
63
+ <li>After auth, the runtime calls <code>getChannels()</code> to list available resources</li>
64
+ <li>User enables/disables resources in the modal</li>
65
+ </ol>
66
+ <h3 id="getchannels" class="tsd-anchor-link">getChannels<a href="#getchannels" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Return available resources after authentication:</p>
67
+ <pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">getChannels</span><span class="hl-1">(</span><span class="hl-2">_auth</span><span class="hl-1">: </span><span class="hl-2">Authorization</span><span class="hl-1">, </span><span class="hl-2">token</span><span class="hl-1">: </span><span class="hl-2">AuthToken</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">Channel</span><span class="hl-1">[]&gt; {</span><br/><span class="hl-1"> const </span><span class="hl-2">client</span><span class="hl-1"> = </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">ApiClient</span><span class="hl-1">({ </span><span class="hl-2">accessToken:</span><span class="hl-1"> </span><span class="hl-2">token</span><span class="hl-1">.</span><span class="hl-2">token</span><span class="hl-1"> });</span><br/><span class="hl-1"> const </span><span class="hl-2">resources</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">client</span><span class="hl-1">.</span><span class="hl-6">listResources</span><span class="hl-1">();</span><br/><span class="hl-1"> return resources.map(</span><span class="hl-2">r</span><span class="hl-1"> </span><span class="hl-4">=&gt;</span><span class="hl-1"> ({ </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-2">r</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">, </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-2">r</span><span class="hl-1">.</span><span class="hl-2">name</span><span class="hl-1"> }));</span><br/><span class="hl-1">}</span>
68
+ </code><button type="button">Copy</button></pre>
69
+
70
+ <h3 id="onchannelenabled" class="tsd-anchor-link">onChannelEnabled<a href="#onchannelenabled" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Called when the user enables a resource. Set up syncing:</p>
71
+ <pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">onChannelEnabled</span><span class="hl-1">(</span><span class="hl-2">channel</span><span class="hl-1">: </span><span class="hl-2">Channel</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-4">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> await this.setupWebhook(channel.id);</span><br/><span class="hl-1"> await this.startBatchSync(channel.id);</span><br/><span class="hl-1">}</span>
72
+ </code><button type="button">Copy</button></pre>
73
+
74
+ <h3 id="onchanneldisabled" class="tsd-anchor-link">onChannelDisabled<a href="#onchanneldisabled" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Called when the user disables a resource. Clean up:</p>
75
+ <pre><code class="typescript"><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">onChannelDisabled</span><span class="hl-1">(</span><span class="hl-2">channel</span><span class="hl-1">: </span><span class="hl-2">Channel</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-4">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-7">// Remove webhook</span><br/><span class="hl-1"> const </span><span class="hl-2">webhookId</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">string</span><span class="hl-1">&gt;(</span><span class="hl-3">`webhook_id_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">if</span><span class="hl-1"> (</span><span class="hl-2">webhookId</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">client</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">getClient</span><span class="hl-1">(</span><span class="hl-2">channel</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">client</span><span class="hl-1">.</span><span class="hl-6">deleteWebhook</span><span class="hl-1">(</span><span class="hl-2">webhookId</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">clear</span><span class="hl-1">(</span><span class="hl-3">`webhook_id_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Clean up stored state</span><br/><span class="hl-1"> await this.clear(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-2">);</span><br/><span class="hl-2">}</span>
76
+ </code><button type="button">Copy</button></pre>
77
+
78
+ <h3 id="getting-auth-tokens" class="tsd-anchor-link">Getting Auth Tokens<a href="#getting-auth-tokens" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Retrieve tokens for API calls using the channel ID:</p>
79
+ <pre><code class="typescript"><span class="hl-2">private</span><span class="hl-1"> </span><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">getClient</span><span class="hl-1">(</span><span class="hl-2">channelId</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">ApiClient</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> const </span><span class="hl-2">token</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">integrations</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">(</span><span class="hl-2">MyConnector</span><span class="hl-1">.</span><span class="hl-8">PROVIDER</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">if</span><span class="hl-1"> (!</span><span class="hl-2">token</span><span class="hl-1">) throw new </span><span class="hl-6">Error</span><span class="hl-1">(</span><span class="hl-3">&quot;No authentication token available&quot;</span><span class="hl-1">);</span><br/><span class="hl-1"> return new </span><span class="hl-6">ApiClient</span><span class="hl-1">({ </span><span class="hl-2">accessToken</span><span class="hl-1">: </span><span class="hl-2">token</span><span class="hl-1">.</span><span class="hl-2">token</span><span class="hl-1"> });</span><br/><span class="hl-1">}</span>
80
+ </code><button type="button">Copy</button></pre>
81
+
82
+ <hr>
83
+ <h2 id="data-sync" class="tsd-anchor-link">Data Sync<a href="#data-sync" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Connectors sync data using <code>Activity.source</code> and <code>Note.key</code> for automatic upserts (no manual ID tracking needed).</p>
84
+ <h3 id="transforming-external-items" class="tsd-anchor-link">Transforming External Items<a href="#transforming-external-items" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><pre><code class="typescript"><span class="hl-2">private</span><span class="hl-1"> </span><span class="hl-6">transformItem</span><span class="hl-1">(</span><span class="hl-2">item</span><span class="hl-1">: </span><span class="hl-2">any</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">, </span><span class="hl-2">initialSync</span><span class="hl-1">: </span><span class="hl-2">boolean</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">return</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">`myprovider:item:</span><span class="hl-4">${</span><span class="hl-2">item</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, </span><span class="hl-7">// Canonical source for deduplication</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-2">item</span><span class="hl-1">.</span><span class="hl-2">title</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">meta:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">externalId:</span><span class="hl-1"> </span><span class="hl-2">item</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">syncProvider:</span><span class="hl-1"> </span><span class="hl-3">&quot;myprovider&quot;</span><span class="hl-1">, </span><span class="hl-7">// Required for bulk operations</span><br/><span class="hl-1"> </span><span class="hl-2">channelId</span><span class="hl-1">, </span><span class="hl-7">// Required for bulk operations</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-2">notes:</span><span class="hl-1"> [{</span><br/><span class="hl-1"> </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&quot;description&quot;</span><span class="hl-1">, </span><span class="hl-7">// Enables note-level upserts</span><br/><span class="hl-1"> </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-2">item</span><span class="hl-1">.</span><span class="hl-2">description</span><span class="hl-1"> || </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">contentType:</span><span class="hl-1"> </span><span class="hl-2">item</span><span class="hl-1">.</span><span class="hl-2">descriptionHtml</span><span class="hl-1"> ? </span><span class="hl-3">&quot;html&quot;</span><span class="hl-1"> </span><span class="hl-0">as</span><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> : </span><span class="hl-3">&quot;text&quot;</span><span class="hl-1"> </span><span class="hl-0">as</span><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1">,</span><br/><span class="hl-1"> }],</span><br/><span class="hl-1"> ...(</span><span class="hl-2">initialSync</span><span class="hl-1"> ? { </span><span class="hl-2">unread:</span><span class="hl-1"> </span><span class="hl-4">false</span><span class="hl-1"> } : {}), </span><span class="hl-7">// Mark read on initial sync</span><br/><span class="hl-1"> ...(</span><span class="hl-2">initialSync</span><span class="hl-1"> ? { </span><span class="hl-2">archived:</span><span class="hl-1"> </span><span class="hl-4">false</span><span class="hl-1"> } : {}), </span><span class="hl-7">// Unarchive on initial sync</span><br/><span class="hl-1"> };</span><br/><span class="hl-1">}</span>
85
+ </code><button type="button">Copy</button></pre>
86
+
87
+ <h3 id="initial-vs-incremental-sync" class="tsd-anchor-link">Initial vs Incremental Sync<a href="#initial-vs-incremental-sync" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>All connectors <strong>must</strong> distinguish between initial sync (first import) and incremental sync (ongoing updates):</p>
88
+ <table>
89
+ <thead>
90
+ <tr>
91
+ <th>Field</th>
92
+ <th>Initial Sync</th>
93
+ <th>Incremental Sync</th>
94
+ <th>Reason</th>
95
+ </tr>
96
+ </thead>
97
+ <tbody>
98
+ <tr>
99
+ <td><code>unread</code></td>
100
+ <td><code>false</code></td>
101
+ <td><em>omit</em></td>
102
+ <td>Avoid notification spam from historical imports</td>
103
+ </tr>
104
+ <tr>
105
+ <td><code>archived</code></td>
106
+ <td><code>false</code></td>
107
+ <td><em>omit</em></td>
108
+ <td>Unarchive on install, preserve user choice on updates</td>
109
+ </tr>
110
+ </tbody>
111
+ </table>
112
+ <p>See <a href="../media/SYNC_STRATEGIES.md">Sync Strategies</a> for detailed patterns on deduplication, upserts, and tag management.</p>
113
+ <hr>
114
+ <h2 id="batch-processing" class="tsd-anchor-link">Batch Processing<a href="#batch-processing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Connectors run in an ephemeral environment with ~1000 requests per execution. Break long operations into batches using <code>runTask()</code>, which creates a new execution with fresh request limits.</p>
115
+ <pre><code class="typescript"><span class="hl-2">private</span><span class="hl-1"> </span><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">startBatchSync</span><span class="hl-1">(</span><span class="hl-2">channelId</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-4">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> await this.set(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channelId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-15">cursor</span><span class="hl-1">: </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-15">batchNumber</span><span class="hl-1">: </span><span class="hl-14">1</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-15">initialSync</span><span class="hl-1">: </span><span class="hl-4">true</span><span class="hl-1">,</span><br/><span class="hl-1"> });</span><br/><br/><span class="hl-1"> const </span><span class="hl-2">batchCallback</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">syncBatch</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">);</span><br/><span class="hl-1"> await this.tools.tasks.runTask(batchCallback);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-2">private</span><span class="hl-1"> </span><span class="hl-2">async</span><span class="hl-1"> </span><span class="hl-6">syncBatch</span><span class="hl-1">(</span><span class="hl-2">channelId</span><span class="hl-1">: </span><span class="hl-2">string</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-4">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> const </span><span class="hl-2">state</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channelId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">if</span><span class="hl-1"> (!</span><span class="hl-2">state</span><span class="hl-1">) return;</span><br/><br/><span class="hl-1"> const </span><span class="hl-2">client</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">getClient</span><span class="hl-1">(</span><span class="hl-2">channelId</span><span class="hl-1">);</span><br/><span class="hl-1"> const </span><span class="hl-2">result</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">client</span><span class="hl-1">.</span><span class="hl-6">listItems</span><span class="hl-1">({ </span><span class="hl-2">cursor:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">cursor</span><span class="hl-1">, </span><span class="hl-2">limit:</span><span class="hl-1"> </span><span class="hl-14">50</span><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-6">for</span><span class="hl-1"> (</span><span class="hl-2">const</span><span class="hl-1"> </span><span class="hl-2">item</span><span class="hl-1"> </span><span class="hl-2">of</span><span class="hl-1"> result.items) {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">activity</span><span class="hl-1"> = </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">transformItem</span><span class="hl-1">(</span><span class="hl-2">item</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">, </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">initialSync</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">(</span><span class="hl-2">activity</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-6">if</span><span class="hl-1"> (result.nextCursor) {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channelId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">cursor:</span><span class="hl-1"> </span><span class="hl-2">result</span><span class="hl-1">.</span><span class="hl-2">nextCursor</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">batchNumber:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">batchNumber</span><span class="hl-1"> + </span><span class="hl-14">1</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">initialSync:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">initialSync</span><span class="hl-1">,</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">nextBatch</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">syncBatch</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">tasks</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">nextBatch</span><span class="hl-1">);</span><br/><span class="hl-1"> } else {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">clear</span><span class="hl-1">(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channelId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
116
+ </code><button type="button">Copy</button></pre>
117
+
118
+ <hr>
119
+ <h2 id="complete-example" class="tsd-anchor-link">Complete Example<a href="#complete-example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>A minimal connector that syncs issues from an external service:</p>
120
+ <pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">LinkType</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">Connector</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">ConnectorBuilder</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">SyncToolOptions</span><span class="hl-1">,</span><br/><span class="hl-1">} </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">AuthProvider</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">AuthToken</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Authorization</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">Channel</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">Integrations</span><span class="hl-1">,</span><br/><span class="hl-1">} </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/integrations&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Network</span><span class="hl-1">, </span><span class="hl-0">type</span><span class="hl-1"> </span><span class="hl-2">WebhookRequest</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/network&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Plot</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/plot&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Tasks</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/tasks&quot;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">Callbacks</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/callbacks&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-0">export</span><span class="hl-1"> </span><span class="hl-0">default</span><span class="hl-1"> </span><span class="hl-4">class</span><span class="hl-1"> </span><span class="hl-5">IssueConnector</span><span class="hl-1"> </span><span class="hl-4">extends</span><span class="hl-1"> </span><span class="hl-5">Connector</span><span class="hl-1">&lt;</span><span class="hl-5">IssueConnector</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-4">static</span><span class="hl-1"> </span><span class="hl-4">readonly</span><span class="hl-1"> </span><span class="hl-2">PROVIDER</span><span class="hl-1"> = </span><span class="hl-2">AuthProvider</span><span class="hl-1">.</span><span class="hl-2">Linear</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-4">static</span><span class="hl-1"> </span><span class="hl-4">readonly</span><span class="hl-1"> </span><span class="hl-2">SCOPES</span><span class="hl-1"> = [</span><span class="hl-3">&quot;read&quot;</span><span class="hl-1">];</span><br/><span class="hl-1"> </span><span class="hl-4">static</span><span class="hl-1"> </span><span class="hl-4">readonly</span><span class="hl-1"> </span><span class="hl-2">Options</span><span class="hl-1">: </span><span class="hl-5">SyncToolOptions</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-4">declare</span><span class="hl-1"> </span><span class="hl-4">readonly</span><span class="hl-1"> </span><span class="hl-2">Options</span><span class="hl-1">: </span><span class="hl-5">SyncToolOptions</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">build</span><span class="hl-1">: </span><span class="hl-5">ConnectorBuilder</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">return</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">integrations:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Integrations</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">providers:</span><span class="hl-1"> [{</span><br/><span class="hl-1"> </span><span class="hl-2">provider:</span><span class="hl-1"> </span><span class="hl-2">IssueConnector</span><span class="hl-1">.</span><span class="hl-8">PROVIDER</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">scopes:</span><span class="hl-1"> </span><span class="hl-2">IssueConnector</span><span class="hl-1">.</span><span class="hl-8">SCOPES</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">getChannels:</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">getChannels</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">onChannelEnabled:</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">onChannelEnabled</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">onChannelDisabled:</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">onChannelDisabled</span><span class="hl-1">,</span><br/><span class="hl-1"> }],</span><br/><span class="hl-1"> }),</span><br/><span class="hl-1"> </span><span class="hl-2">network:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Network</span><span class="hl-1">, { </span><span class="hl-2">urls:</span><span class="hl-1"> [</span><span class="hl-3">&quot;https://api.linear.app/*&quot;</span><span class="hl-1">] }),</span><br/><span class="hl-1"> </span><span class="hl-2">plot:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Plot</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">tasks:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Tasks</span><span class="hl-1">),</span><br/><span class="hl-1"> </span><span class="hl-2">callbacks:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Callbacks</span><span class="hl-1">),</span><br/><span class="hl-1"> };</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">getChannels</span><span class="hl-1">(</span><span class="hl-2">_auth</span><span class="hl-1">: </span><span class="hl-5">Authorization</span><span class="hl-1">, </span><span class="hl-2">token</span><span class="hl-1">: </span><span class="hl-5">AuthToken</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-5">Channel</span><span class="hl-1">[]&gt; {</span><br/><span class="hl-1"> </span><span class="hl-7">// Return available projects/teams for the user to select</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">client</span><span class="hl-1"> = </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">LinearClient</span><span class="hl-1">({ </span><span class="hl-2">accessToken:</span><span class="hl-1"> </span><span class="hl-2">token</span><span class="hl-1">.</span><span class="hl-2">token</span><span class="hl-1"> });</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">teams</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">client</span><span class="hl-1">.</span><span class="hl-6">teams</span><span class="hl-1">();</span><br/><span class="hl-1"> </span><span class="hl-0">return</span><span class="hl-1"> </span><span class="hl-2">teams</span><span class="hl-1">.</span><span class="hl-2">nodes</span><span class="hl-1">.</span><span class="hl-6">map</span><span class="hl-1">(</span><span class="hl-2">t</span><span class="hl-1"> </span><span class="hl-4">=&gt;</span><span class="hl-1"> ({ </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-2">t</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">, </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-2">t</span><span class="hl-1">.</span><span class="hl-2">name</span><span class="hl-1"> }));</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">onChannelEnabled</span><span class="hl-1">(</span><span class="hl-2">channel</span><span class="hl-1">: </span><span class="hl-5">Channel</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-5">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-7">// Set up webhook</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">webhookUrl</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">network</span><span class="hl-1">.</span><span class="hl-6">createWebhook</span><span class="hl-1">(</span><br/><span class="hl-1"> {}, </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">onWebhook</span><span class="hl-1">, </span><span class="hl-2">channel</span><span class="hl-1">.</span><span class="hl-2">id</span><br/><span class="hl-1"> );</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (!</span><span class="hl-2">webhookUrl</span><span class="hl-1">.</span><span class="hl-6">includes</span><span class="hl-1">(</span><span class="hl-3">&quot;localhost&quot;</span><span class="hl-1">)) {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">client</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">getClient</span><span class="hl-1">(</span><span class="hl-2">channel</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">webhook</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">client</span><span class="hl-1">.</span><span class="hl-6">createWebhook</span><span class="hl-1">({ </span><span class="hl-2">url:</span><span class="hl-1"> </span><span class="hl-2">webhookUrl</span><span class="hl-1"> });</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">webhook</span><span class="hl-1">?.</span><span class="hl-2">id</span><span class="hl-1">) </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">`webhook_id_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, </span><span class="hl-2">webhook</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-7">// Start initial sync</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">cursor:</span><span class="hl-1"> </span><span class="hl-4">null</span><span class="hl-1">, </span><span class="hl-2">batchNumber:</span><span class="hl-1"> </span><span class="hl-14">1</span><span class="hl-1">, </span><span class="hl-2">initialSync:</span><span class="hl-1"> </span><span class="hl-4">true</span><span class="hl-1">,</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">batch</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">syncBatch</span><span class="hl-1">, </span><span class="hl-2">channel</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">tasks</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">batch</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">onChannelDisabled</span><span class="hl-1">(</span><span class="hl-2">channel</span><span class="hl-1">: </span><span class="hl-5">Channel</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-5">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">webhookId</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">string</span><span class="hl-1">&gt;(</span><span class="hl-3">`webhook_id_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">webhookId</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">try</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">client</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">getClient</span><span class="hl-1">(</span><span class="hl-2">channel</span><span class="hl-1">.</span><span class="hl-2">id</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">client</span><span class="hl-1">.</span><span class="hl-6">deleteWebhook</span><span class="hl-1">(</span><span class="hl-2">webhookId</span><span class="hl-1">);</span><br/><span class="hl-1"> } </span><span class="hl-0">catch</span><span class="hl-1"> { </span><span class="hl-7">/* ignore */</span><span class="hl-1"> }</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">clear</span><span class="hl-1">(</span><span class="hl-3">`webhook_id_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">clear</span><span class="hl-1">(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channel</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-4">private</span><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">getClient</span><span class="hl-1">(</span><span class="hl-2">channelId</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">token</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">integrations</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">(</span><span class="hl-2">IssueConnector</span><span class="hl-1">.</span><span class="hl-8">PROVIDER</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (!</span><span class="hl-2">token</span><span class="hl-1">) </span><span class="hl-0">throw</span><span class="hl-1"> </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Error</span><span class="hl-1">(</span><span class="hl-3">&quot;No auth token&quot;</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">return</span><span class="hl-1"> </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">LinearClient</span><span class="hl-1">({ </span><span class="hl-2">accessToken:</span><span class="hl-1"> </span><span class="hl-2">token</span><span class="hl-1">.</span><span class="hl-2">token</span><span class="hl-1"> });</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-4">private</span><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">syncBatch</span><span class="hl-1">(</span><span class="hl-2">channelId</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-5">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">state</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">get</span><span class="hl-1">&lt;</span><span class="hl-5">any</span><span class="hl-1">&gt;(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channelId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (!</span><span class="hl-2">state</span><span class="hl-1">) </span><span class="hl-0">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">client</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">getClient</span><span class="hl-1">(</span><span class="hl-2">channelId</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">result</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">client</span><span class="hl-1">.</span><span class="hl-6">issues</span><span class="hl-1">({ </span><span class="hl-2">teamId:</span><span class="hl-1"> </span><span class="hl-2">channelId</span><span class="hl-1">, </span><span class="hl-2">after:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">cursor</span><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-0">for</span><span class="hl-1"> (</span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">issue</span><span class="hl-1"> </span><span class="hl-4">of</span><span class="hl-1"> </span><span class="hl-2">result</span><span class="hl-1">.</span><span class="hl-2">nodes</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">`linear:issue:</span><span class="hl-4">${</span><span class="hl-2">issue</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">`</span><span class="hl-4">${</span><span class="hl-2">issue</span><span class="hl-13">.</span><span class="hl-2">identifier</span><span class="hl-4">}</span><span class="hl-3">: </span><span class="hl-4">${</span><span class="hl-2">issue</span><span class="hl-13">.</span><span class="hl-2">title</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">done:</span><span class="hl-1"> </span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">completedAt</span><span class="hl-1"> ? </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Date</span><span class="hl-1">(</span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">completedAt</span><span class="hl-1">) : </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">meta:</span><span class="hl-1"> { </span><span class="hl-2">syncProvider:</span><span class="hl-1"> </span><span class="hl-3">&quot;linear&quot;</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-2">notes:</span><span class="hl-1"> [{</span><br/><span class="hl-1"> </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&quot;description&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">description</span><span class="hl-1"> || </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">links:</span><span class="hl-1"> </span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">url</span><span class="hl-1"> ? [{</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">LinkType</span><span class="hl-1">.</span><span class="hl-2">external</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&quot;Open in Linear&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">url:</span><span class="hl-1"> </span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">url</span><span class="hl-1">,</span><br/><span class="hl-1"> }] : </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1"> }],</span><br/><span class="hl-1"> ...(</span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">initialSync</span><span class="hl-1"> ? { </span><span class="hl-2">unread:</span><span class="hl-1"> </span><span class="hl-4">false</span><span class="hl-1"> } : {}),</span><br/><span class="hl-1"> ...(</span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">initialSync</span><span class="hl-1"> ? { </span><span class="hl-2">archived:</span><span class="hl-1"> </span><span class="hl-4">false</span><span class="hl-1"> } : {}),</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">result</span><span class="hl-1">.</span><span class="hl-2">pageInfo</span><span class="hl-1">.</span><span class="hl-2">hasNextPage</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">set</span><span class="hl-1">(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channelId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">cursor:</span><span class="hl-1"> </span><span class="hl-2">result</span><span class="hl-1">.</span><span class="hl-2">pageInfo</span><span class="hl-1">.</span><span class="hl-2">endCursor</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">batchNumber:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">batchNumber</span><span class="hl-1"> + </span><span class="hl-14">1</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">initialSync:</span><span class="hl-1"> </span><span class="hl-2">state</span><span class="hl-1">.</span><span class="hl-2">initialSync</span><span class="hl-1">,</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">next</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">callback</span><span class="hl-1">(</span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">syncBatch</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">tasks</span><span class="hl-1">.</span><span class="hl-6">runTask</span><span class="hl-1">(</span><span class="hl-2">next</span><span class="hl-1">);</span><br/><span class="hl-1"> } </span><span class="hl-0">else</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-6">clear</span><span class="hl-1">(</span><span class="hl-3">`sync_state_</span><span class="hl-4">${</span><span class="hl-2">channelId</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> }</span><br/><br/><span class="hl-1"> </span><span class="hl-4">private</span><span class="hl-1"> </span><span class="hl-4">async</span><span class="hl-1"> </span><span class="hl-6">onWebhook</span><span class="hl-1">(</span><span class="hl-2">request</span><span class="hl-1">: </span><span class="hl-5">WebhookRequest</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1">: </span><span class="hl-5">string</span><span class="hl-1">): </span><span class="hl-5">Promise</span><span class="hl-1">&lt;</span><span class="hl-5">void</span><span class="hl-1">&gt; {</span><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">payload</span><span class="hl-1"> = </span><span class="hl-8">JSON</span><span class="hl-1">.</span><span class="hl-6">parse</span><span class="hl-1">(</span><span class="hl-2">request</span><span class="hl-1">.</span><span class="hl-2">rawBody</span><span class="hl-1"> || </span><span class="hl-3">&quot;{}&quot;</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-0">if</span><span class="hl-1"> (</span><span class="hl-2">payload</span><span class="hl-1">.</span><span class="hl-2">type</span><span class="hl-1"> !== </span><span class="hl-3">&quot;Issue&quot;</span><span class="hl-1">) </span><span class="hl-0">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">issue</span><span class="hl-1"> = </span><span class="hl-2">payload</span><span class="hl-1">.</span><span class="hl-2">data</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">this</span><span class="hl-1">.</span><span class="hl-2">tools</span><span class="hl-1">.</span><span class="hl-2">plot</span><span class="hl-1">.</span><span class="hl-6">createActivity</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">`linear:issue:</span><span class="hl-4">${</span><span class="hl-2">issue</span><span class="hl-13">.</span><span class="hl-2">id</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-2">ActivityType</span><span class="hl-1">.</span><span class="hl-2">Action</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">`</span><span class="hl-4">${</span><span class="hl-2">issue</span><span class="hl-13">.</span><span class="hl-2">identifier</span><span class="hl-4">}</span><span class="hl-3">: </span><span class="hl-4">${</span><span class="hl-2">issue</span><span class="hl-13">.</span><span class="hl-2">title</span><span class="hl-4">}</span><span class="hl-3">`</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">done:</span><span class="hl-1"> </span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">completedAt</span><span class="hl-1"> ? </span><span class="hl-4">new</span><span class="hl-1"> </span><span class="hl-6">Date</span><span class="hl-1">(</span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">completedAt</span><span class="hl-1">) : </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">meta:</span><span class="hl-1"> { </span><span class="hl-2">syncProvider:</span><span class="hl-1"> </span><span class="hl-3">&quot;linear&quot;</span><span class="hl-1">, </span><span class="hl-2">channelId</span><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-2">notes:</span><span class="hl-1"> [{</span><br/><span class="hl-1"> </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&quot;description&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">content:</span><span class="hl-1"> </span><span class="hl-2">issue</span><span class="hl-1">.</span><span class="hl-2">description</span><span class="hl-1"> || </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1"> }],</span><br/><span class="hl-1"> </span><span class="hl-7">// Incremental sync: omit unread and archived</span><br/><span class="hl-1"> });</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}</span>
121
+ </code><button type="button">Copy</button></pre>
122
+
123
+ <hr>
124
+ <h2 id="best-practices" class="tsd-anchor-link">Best Practices<a href="#best-practices" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><h3 id="1-always-inject-sync-metadata" class="tsd-anchor-link">1. Always Inject Sync Metadata<a href="#1-always-inject-sync-metadata" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Every synced activity must include <code>syncProvider</code> and <code>channelId</code> in <code>meta</code> for bulk operations (e.g., archiving all activities when a channel is disabled).</p>
125
+ <h3 id="2-use-canonical-source-urls" class="tsd-anchor-link">2. Use Canonical Source URLs<a href="#2-use-canonical-source-urls" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Use immutable IDs in <code>Activity.source</code> for deduplication. For services with mutable identifiers (like Jira issue keys), use the immutable ID in <code>source</code> and store the mutable key in <code>meta</code>.</p>
126
+ <h3 id="3-handle-html-content-correctly" class="tsd-anchor-link">3. Handle HTML Content Correctly<a href="#3-handle-html-content-correctly" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Never strip HTML tags locally. Pass raw HTML with <code>contentType: &quot;html&quot;</code> for server-side markdown conversion.</p>
127
+ <h3 id="4-add-localhost-guard-for-webhooks" class="tsd-anchor-link">4. Add Localhost Guard for Webhooks<a href="#4-add-localhost-guard-for-webhooks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Skip webhook registration in development when the URL contains &quot;localhost&quot;.</p>
128
+ <h3 id="5-maintain-callback-backward-compatibility" class="tsd-anchor-link">5. Maintain Callback Backward Compatibility<a href="#5-maintain-callback-backward-compatibility" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>All callbacks automatically upgrade to new connector versions. Only add optional parameters at the end of callback method signatures.</p>
129
+ <h3 id="6-clean-up-on-disable" class="tsd-anchor-link">6. Clean Up on Disable<a href="#6-clean-up-on-disable" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Delete webhooks, callbacks, and stored state in <code>onChannelDisabled()</code>.</p>
130
+ <hr>
131
+ <h2 id="next-steps" class="tsd-anchor-link">Next Steps<a href="#next-steps" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><ul>
132
+ <li><strong><a href="../media/AGENTS.md">Connector Development Guide</a></strong> - Comprehensive scaffold, patterns, and checklist</li>
133
+ <li><strong><a href="../media/SYNC_STRATEGIES.md">Sync Strategies</a></strong> - Deduplication, upserts, and tag management</li>
134
+ <li><strong><a href="Built-in_Tools.html">Built-in Tools Guide</a></strong> - Complete reference for Plot, Store, Integrations, and more</li>
135
+ <li><strong><a href="../media/MULTI_USER_AUTH.md">Multi-User Auth</a></strong> - Per-user auth for write-backs</li>
136
+ </ul>
137
+ </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#building-connectors"><span>Building <wbr/>Connectors</span></a><ul><li><a href="#table-of-contents"><span>Table of <wbr/>Contents</span></a></li><li><a href="#connectors-vs-twists"><span>Connectors vs <wbr/>Twists</span></a></li><li><a href="#connector-structure"><span>Connector <wbr/>Structure</span></a></li><li><ul><li><a href="#package-structure"><span>Package <wbr/>Structure</span></a></li></ul></li><li><a href="#oauth-and-channel-lifecycle"><span>O<wbr/>Auth and <wbr/>Channel <wbr/>Lifecycle</span></a></li><li><ul><li><a href="#how-it-works"><span>How <wbr/>It <wbr/>Works</span></a></li><li><a href="#getchannels"><span>get<wbr/>Channels</span></a></li><li><a href="#onchannelenabled"><span>on<wbr/>Channel<wbr/>Enabled</span></a></li><li><a href="#onchanneldisabled"><span>on<wbr/>Channel<wbr/>Disabled</span></a></li><li><a href="#getting-auth-tokens"><span>Getting <wbr/>Auth <wbr/>Tokens</span></a></li></ul></li><li><a href="#data-sync"><span>Data <wbr/>Sync</span></a></li><li><ul><li><a href="#transforming-external-items"><span>Transforming <wbr/>External <wbr/>Items</span></a></li><li><a href="#initial-vs-incremental-sync"><span>Initial vs <wbr/>Incremental <wbr/>Sync</span></a></li></ul></li><li><a href="#batch-processing"><span>Batch <wbr/>Processing</span></a></li><li><a href="#complete-example"><span>Complete <wbr/>Example</span></a></li><li><a href="#best-practices"><span>Best <wbr/>Practices</span></a></li><li><ul><li><a href="#1-always-inject-sync-metadata"><span>1. <wbr/>Always <wbr/>Inject <wbr/>Sync <wbr/>Metadata</span></a></li><li><a href="#2-use-canonical-source-urls"><span>2. <wbr/>Use <wbr/>Canonical <wbr/>Source <wbr/>UR<wbr/>Ls</span></a></li><li><a href="#3-handle-html-content-correctly"><span>3. <wbr/>Handle <wbr/>HTML <wbr/>Content <wbr/>Correctly</span></a></li><li><a href="#4-add-localhost-guard-for-webhooks"><span>4. <wbr/>Add <wbr/>Localhost <wbr/>Guard for <wbr/>Webhooks</span></a></li><li><a href="#5-maintain-callback-backward-compatibility"><span>5. <wbr/>Maintain <wbr/>Callback <wbr/>Backward <wbr/>Compatibility</span></a></li><li><a href="#6-clean-up-on-disable"><span>6. <wbr/>Clean <wbr/>Up on <wbr/>Disable</span></a></li></ul></li><li><a href="#next-steps"><span>Next <wbr/>Steps</span></a></li></ul></div></details></div><div class="site-menu"><nav id="tsd-sidebar-links" class="tsd-navigation"><a href="https://plot.day" class="tsd-nav-link">Plot</a><a href="https://github.com/plotday/plot" class="tsd-nav-link">GitHub</a><a href="https://www.npmjs.com/package/@plotday/twister" class="tsd-nav-link">NPM</a></nav><nav class="tsd-navigation"><a href="../modules.html">Creating Plot Twists</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
package/dist/docs/documents/Built-in_Tools.html CHANGED
@@ -223,17 +223,17 @@
223
223
  </code><button type="button">Copy</button></pre>
224
224
 
225
225
  <hr>
226
- <h2 id="link-type-safety-pattern" class="tsd-anchor-link">Link Type Safety Pattern<a href="#link-type-safety-pattern" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>When defining <code>linkTypes</code> in your source's provider config, use <code>as const satisfies</code> to get type-safe status strings:</p>
226
+ <h2 id="link-type-safety-pattern" class="tsd-anchor-link">Link Type Safety Pattern<a href="#link-type-safety-pattern" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><p>When defining <code>linkTypes</code> in your connector's provider config, use <code>as const satisfies</code> to get type-safe status strings:</p>
227
227
  <pre><code class="typescript"><span class="hl-0">import</span><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> { </span><span class="hl-2">LinkTypeConfig</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&quot;@plotday/twister/tools/integrations&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-8">LINK_TYPES</span><span class="hl-1"> = [</span><br/><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-3">&quot;issue&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">label:</span><span class="hl-1"> </span><span class="hl-3">&quot;Issue&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">logo:</span><span class="hl-1"> </span><span class="hl-3">&quot;https://api.iconify.design/simple-icons/linear.svg&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">statuses:</span><span class="hl-1"> [</span><br/><span class="hl-1"> { </span><span class="hl-2">status:</span><span class="hl-1"> </span><span class="hl-3">&quot;open&quot;</span><span class="hl-1">, </span><span class="hl-2">label:</span><span class="hl-1"> </span><span class="hl-3">&quot;Open&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> { </span><span class="hl-2">status:</span><span class="hl-1"> </span><span class="hl-3">&quot;done&quot;</span><span class="hl-1">, </span><span class="hl-2">label:</span><span class="hl-1"> </span><span class="hl-3">&quot;Done&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> ],</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-3">&quot;pull_request&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">label:</span><span class="hl-1"> </span><span class="hl-3">&quot;Pull Request&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">logo:</span><span class="hl-1"> </span><span class="hl-3">&quot;https://api.iconify.design/simple-icons/github.svg&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">statuses:</span><span class="hl-1"> [</span><br/><span class="hl-1"> { </span><span class="hl-2">status:</span><span class="hl-1"> </span><span class="hl-3">&quot;open&quot;</span><span class="hl-1">, </span><span class="hl-2">label:</span><span class="hl-1"> </span><span class="hl-3">&quot;Open&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> { </span><span class="hl-2">status:</span><span class="hl-1"> </span><span class="hl-3">&quot;merged&quot;</span><span class="hl-1">, </span><span class="hl-2">label:</span><span class="hl-1"> </span><span class="hl-3">&quot;Merged&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> { </span><span class="hl-2">status:</span><span class="hl-1"> </span><span class="hl-3">&quot;closed&quot;</span><span class="hl-1">, </span><span class="hl-2">label:</span><span class="hl-1"> </span><span class="hl-3">&quot;Closed&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1"> ],</span><br/><span class="hl-1"> },</span><br/><span class="hl-1">] </span><span class="hl-0">as</span><span class="hl-1"> </span><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-0">satisfies</span><span class="hl-1"> </span><span class="hl-5">LinkTypeConfig</span><span class="hl-1">[];</span><br/><br/><span class="hl-7">// Derive type-safe union types from the config</span><br/><span class="hl-4">type</span><span class="hl-1"> </span><span class="hl-5">IssueStatus</span><span class="hl-1"> = (</span><span class="hl-4">typeof</span><span class="hl-1"> </span><span class="hl-8">LINK_TYPES</span><span class="hl-1">)[</span><span class="hl-14">0</span><span class="hl-1">][</span><span class="hl-3">&quot;statuses&quot;</span><span class="hl-1">][</span><span class="hl-5">number</span><span class="hl-1">][</span><span class="hl-3">&quot;status&quot;</span><span class="hl-1">]; </span><span class="hl-7">// &quot;open&quot; | &quot;done&quot;</span><br/><span class="hl-4">type</span><span class="hl-1"> </span><span class="hl-5">PRStatus</span><span class="hl-1"> = (</span><span class="hl-4">typeof</span><span class="hl-1"> </span><span class="hl-8">LINK_TYPES</span><span class="hl-1">)[</span><span class="hl-14">1</span><span class="hl-1">][</span><span class="hl-3">&quot;statuses&quot;</span><span class="hl-1">][</span><span class="hl-5">number</span><span class="hl-1">][</span><span class="hl-3">&quot;status&quot;</span><span class="hl-1">]; </span><span class="hl-7">// &quot;open&quot; | &quot;merged&quot; | &quot;closed&quot;</span>
228
228
  </code><button type="button">Copy</button></pre>
229
229
 
230
230
  <p>Then reference <code>LINK_TYPES</code> in your provider config:</p>
231
- <pre><code class="typescript"><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">build</span><span class="hl-1">: </span><span class="hl-2">SourceBuilder</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">return</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">integrations:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Integrations</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">providers:</span><span class="hl-1"> [{</span><br/><span class="hl-1"> </span><span class="hl-2">provider:</span><span class="hl-1"> </span><span class="hl-2">MySource</span><span class="hl-1">.</span><span class="hl-8">PROVIDER</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">scopes:</span><span class="hl-1"> </span><span class="hl-2">MySource</span><span class="hl-1">.</span><span class="hl-8">SCOPES</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">linkTypes:</span><span class="hl-1"> [...</span><span class="hl-8">LINK_TYPES</span><span class="hl-1">],</span><br/><span class="hl-1"> </span><span class="hl-7">// ...</span><br/><span class="hl-1"> }],</span><br/><span class="hl-1"> }),</span><br/><span class="hl-1"> };</span><br/><span class="hl-1">}</span>
231
+ <pre><code class="typescript"><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">build</span><span class="hl-1">: </span><span class="hl-2">ConnectorBuilder</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-0">return</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-2">integrations:</span><span class="hl-1"> </span><span class="hl-6">build</span><span class="hl-1">(</span><span class="hl-2">Integrations</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-2">providers:</span><span class="hl-1"> [{</span><br/><span class="hl-1"> </span><span class="hl-2">provider:</span><span class="hl-1"> </span><span class="hl-2">MyConnector</span><span class="hl-1">.</span><span class="hl-8">PROVIDER</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">scopes:</span><span class="hl-1"> </span><span class="hl-2">MyConnector</span><span class="hl-1">.</span><span class="hl-8">SCOPES</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-2">linkTypes:</span><span class="hl-1"> [...</span><span class="hl-8">LINK_TYPES</span><span class="hl-1">],</span><br/><span class="hl-1"> </span><span class="hl-7">// ...</span><br/><span class="hl-1"> }],</span><br/><span class="hl-1"> }),</span><br/><span class="hl-1"> };</span><br/><span class="hl-1">}</span>
232
232
  </code><button type="button">Copy</button></pre>
233
233
 
234
234
  <hr>
235
235
  <h2 id="next-steps" class="tsd-anchor-link">Next Steps<a href="#next-steps" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2><ul>
236
- <li><strong><a href="Building_Sources.html">Building Sources</a></strong> - Build external service integrations</li>
236
+ <li><strong><a href="Building_Connectors.html">Building Connectors</a></strong> - Build external service integrations</li>
237
237
  <li><strong><a href="Runtime_Environment.html">Runtime Environment</a></strong> - Understanding execution constraints</li>
238
238
  <li><strong>API Reference</strong> - Explore detailed API docs in the sidebar</li>
239
239
  </ul>