@plotday/twister 0.61.0 → 0.63.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.
- package/dist/connector.d.ts +14 -0
- package/dist/connector.d.ts.map +1 -1
- package/dist/connector.js +14 -0
- package/dist/connector.js.map +1 -1
- package/dist/docs/assets/hierarchy.js +1 -1
- package/dist/docs/assets/search.js +1 -1
- package/dist/docs/classes/index.Connector.html +47 -26
- package/dist/docs/classes/index.FileNotFoundError.html +1 -1
- package/dist/docs/classes/index.Files.html +1 -1
- package/dist/docs/classes/index.Imap.html +1 -1
- package/dist/docs/classes/index.Options.html +1 -1
- package/dist/docs/classes/index.Smtp.html +1 -1
- package/dist/docs/classes/tool.ITool.html +1 -1
- package/dist/docs/classes/tool.Tool.html +17 -7
- package/dist/docs/classes/tools_ai.AI.html +1 -1
- package/dist/docs/classes/tools_callbacks.Callbacks.html +1 -1
- package/dist/docs/classes/tools_integrations.Integrations.html +1 -1
- package/dist/docs/classes/tools_network.Network.html +1 -1
- package/dist/docs/classes/tools_plot.Plot.html +1 -1
- package/dist/docs/classes/tools_store.Store.html +1 -1
- package/dist/docs/classes/tools_tasks.Tasks.html +40 -14
- package/dist/docs/classes/tools_twists.Twists.html +1 -1
- package/dist/docs/classes/twist.Twist.html +21 -11
- package/dist/docs/documents/Built-in_Tools.html +15 -13
- package/dist/docs/documents/Runtime_Environment.html +7 -5
- package/dist/docs/hierarchy.html +1 -1
- package/dist/docs/media/AGENTS.md +23 -19
- package/dist/llm-docs/connector.d.ts +1 -1
- package/dist/llm-docs/connector.d.ts.map +1 -1
- package/dist/llm-docs/connector.js +1 -1
- package/dist/llm-docs/connector.js.map +1 -1
- package/dist/llm-docs/tool.d.ts +1 -1
- package/dist/llm-docs/tool.d.ts.map +1 -1
- package/dist/llm-docs/tool.js +1 -1
- package/dist/llm-docs/tool.js.map +1 -1
- package/dist/llm-docs/tools/tasks.d.ts +1 -1
- package/dist/llm-docs/tools/tasks.d.ts.map +1 -1
- package/dist/llm-docs/tools/tasks.js +1 -1
- package/dist/llm-docs/tools/tasks.js.map +1 -1
- package/dist/llm-docs/twist.d.ts +1 -1
- package/dist/llm-docs/twist.d.ts.map +1 -1
- package/dist/llm-docs/twist.js +1 -1
- package/dist/llm-docs/twist.js.map +1 -1
- package/dist/tool.d.ts +16 -0
- package/dist/tool.d.ts.map +1 -1
- package/dist/tool.js +15 -0
- package/dist/tool.js.map +1 -1
- package/dist/tools/tasks.d.ts +58 -12
- package/dist/tools/tasks.d.ts.map +1 -1
- package/dist/tools/tasks.js.map +1 -1
- package/dist/twist.d.ts +16 -0
- package/dist/twist.d.ts.map +1 -1
- package/dist/twist.js +15 -0
- package/dist/twist.js.map +1 -1
- package/dist/utils/markdown-html.d.ts +15 -0
- package/dist/utils/markdown-html.d.ts.map +1 -0
- package/dist/utils/markdown-html.js +35 -0
- package/dist/utils/markdown-html.js.map +1 -0
- package/package.json +7 -1
- package/src/connector.ts +15 -0
- package/src/llm-docs/connector.ts +1 -1
- package/src/llm-docs/tool.ts +1 -1
- package/src/llm-docs/tools/tasks.ts +1 -1
- package/src/llm-docs/twist.ts +1 -1
- package/src/tool.ts +20 -0
- package/src/tools/tasks.ts +61 -12
- package/src/twist.ts +20 -0
- package/src/utils/markdown-html.ts +40 -0
package/dist/docs/hierarchy.html
CHANGED
|
@@ -1 +1 @@
|
|
|
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>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"><h1>Creating Plot Twists</h1></div><h2>Hierarchy Summary</h2><ul class="tsd-full-hierarchy"><li data-refl="
|
|
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>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"><h1>Creating Plot Twists</h1></div><h2>Hierarchy Summary</h2><ul class="tsd-full-hierarchy"><li data-refl="146" id="tool.ITool"><a href="classes/tool.ITool.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>ITool</a><ul><li data-refl="149" id="tool.Tool"><a href="classes/tool.Tool.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>Tool</a></li><li data-refl="577" id="tools/twists.Twists"><a href="classes/tools_twists.Twists.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>Twists</a></li><li data-refl="607" id="tools/ai.AI"><a href="classes/tools_ai.AI.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>AI</a></li><li data-refl="803" id="tools/callbacks.Callbacks"><a href="classes/tools_callbacks.Callbacks.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>Callbacks</a></li><li data-refl="907" id="tools/integrations.Integrations"><a href="classes/tools_integrations.Integrations.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>Integrations</a></li><li data-refl="1006" id="tools/network.Network"><a href="classes/tools_network.Network.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>Network</a></li><li data-refl="1078" id="tools/plot.Plot"><a href="classes/tools_plot.Plot.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>Plot</a></li><li data-refl="1203" id="tools/store.Store"><a href="classes/tools_store.Store.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>Store</a></li><li data-refl="1231" id="tools/tasks.Tasks"><a href="classes/tools_tasks.Tasks.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>Tasks</a></li><li data-refl="1713" id="index.Files"><a href="classes/index.Files.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>Files</a></li><li data-refl="1814" id="index.Imap"><a href="classes/index.Imap.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>Imap</a></li><li data-refl="1879" id="index.Smtp"><a href="classes/index.Smtp.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>Smtp</a></li><li data-refl="1933" id="index.Options"><a href="classes/index.Options.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>Options</a></li></ul></li></ul><ul class="tsd-full-hierarchy"><li data-refl="11" id="twist.Twist"><a href="classes/twist.Twist.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>Twist</a><ul><li data-refl="1357" id="index.Connector"><a href="classes/index.Connector.html"><svg class="tsd-kind-icon" viewBox="0 0 24 24" aria-label="Class"><use href="assets/icons.svg#icon-128"></use></svg>Connector</a></li></ul></li></ul></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></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>
|
|
@@ -335,32 +335,36 @@ if (webhookUrl.includes("localhost") || webhookUrl.includes("127.0.0.1")) return
|
|
|
335
335
|
|
|
336
336
|
### Watch renewal (Calendar/Drive)
|
|
337
337
|
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
`
|
|
346
|
-
|
|
338
|
+
Use **`this.scheduleRecurring(key, callback, { intervalMs, firstRunAt? })`** for
|
|
339
|
+
watch renewals (and all other recurring/self-renewing jobs). The platform owns
|
|
340
|
+
the cadence: it re-arms the task every `intervalMs` (the safety ceiling)
|
|
341
|
+
automatically, so the chain survives a dropped queue message, a suspension, a
|
|
342
|
+
deploy, or a callback that throws before it could reschedule. The callback does
|
|
343
|
+
NOT need to reschedule itself.
|
|
344
|
+
|
|
345
|
+
`intervalMs` is the **maximum gap** between fires. For watch renewals the
|
|
346
|
+
ceiling should be at most half the provider-issued lifetime (e.g. 3.5 days for
|
|
347
|
+
a 7-day watch). Pass `firstRunAt` for the precise next fire (e.g. 24h before
|
|
348
|
+
expiry); the callback can re-register under the same key with a fresh `firstRunAt`
|
|
349
|
+
on each successful renewal to keep tightening the schedule. Re-scheduling under
|
|
350
|
+
the same key atomically replaces the pending occurrence.
|
|
347
351
|
|
|
348
352
|
```typescript
|
|
349
353
|
const renewalTime = new Date(expiresAt.getTime() - 24 * 60 * 60 * 1000);
|
|
350
354
|
const renewal = await this.callback(this.renewWatch, resourceId);
|
|
351
|
-
//
|
|
352
|
-
await this.
|
|
355
|
+
// Platform re-arms every intervalMs; firstRunAt fires earlier (at renewal time).
|
|
356
|
+
await this.scheduleRecurring(`watch-renewal:${resourceId}`, renewal, {
|
|
357
|
+
intervalMs: 3.5 * 24 * 60 * 60 * 1000, // ceiling: half the 7-day watch lifetime
|
|
358
|
+
firstRunAt: renewalTime,
|
|
359
|
+
});
|
|
353
360
|
|
|
354
361
|
// On teardown (onChannelDisabled / stopSync):
|
|
355
362
|
await this.cancelScheduledTask(`watch-renewal:${resourceId}`);
|
|
356
363
|
```
|
|
357
364
|
|
|
358
|
-
> ⚠️
|
|
359
|
-
>
|
|
360
|
-
>
|
|
361
|
-
> chains. Use `scheduleTask`; it does the dedup atomically on the server. This
|
|
362
|
-
> applies to **any** recurring/self-renewing task (polling, deferred cleanup),
|
|
363
|
-
> not just watch renewals.
|
|
365
|
+
> ⚠️ `scheduleTask` is for **one-shot** keyed deferred work. `scheduleRecurring`
|
|
366
|
+
> is the durable primitive for any recurring or self-renewing chain — the
|
|
367
|
+
> platform guarantees the chain re-fires even if a single run is lost.
|
|
364
368
|
|
|
365
369
|
## Bidirectional sync
|
|
366
370
|
|
|
@@ -562,7 +566,7 @@ Add to `pnpm-workspace.yaml` if not already covered by a glob.
|
|
|
562
566
|
- [ ] `initialSync` propagated through every entry point and batch; set `unread: false, archived: false` on initial, omit on incremental
|
|
563
567
|
- [ ] Create `NewContact` for authors/assignees
|
|
564
568
|
- [ ] Clean up callbacks, webhooks, stored state in `stopSync()` and `onChannelDisabled()`
|
|
565
|
-
- [ ] Recurring/self-renewing tasks (watch renewals, polling) use `this.
|
|
569
|
+
- [ ] Recurring/self-renewing tasks (watch renewals, polling, periodic syncs, self-heal) use `this.scheduleRecurring(key, …)` — NOT `scheduleTask` or `runTask({ runAt })` + manual token bookkeeping — and `cancelScheduledTask(key)` on teardown
|
|
566
570
|
- [ ] For Plot-initiated creation: add a `compose` block to the `LinkTypeConfig` AND implement `onCreateLink` — don't call `saveLink` from inside it
|
|
567
571
|
- [ ] `pnpm build` succeeds
|
|
568
572
|
|
|
@@ -588,7 +592,7 @@ Add to `pnpm-workspace.yaml` if not already covered by a glob.
|
|
|
588
592
|
18. Returning a bare `string` (key only) from `onNoteCreated` when the external stores content lossily (plain-text comments APIs, ADF, sanitised HTML) → next sync-in clobbers Plot's content with the round-tripped form (e.g. `1.` → `1\.`). Return a `NoteWriteBackResult` with `externalContent` matching sync-in's shape instead.
|
|
589
593
|
19. Returning `externalContent` that doesn't match what sync-in emits for the same note (e.g. post-write raw HTML when sync-in extracts plain text; pre-translation mentions when sync-in translates them) → baseline hash always mismatches and every sync clobbers. Inspect the sync-in `build*Note` path and return exactly what it produces.
|
|
590
594
|
20. Calling `integrations.saveLink()` inside `onNoteCreated` to set the note's `key` → legacy workaround, no longer needed. The runtime sets `key` automatically from the `NoteWriteBackResult` return.
|
|
591
|
-
21. Scheduling a recurring/self-renewing task with `runTask({ runAt })` + manual
|
|
595
|
+
21. Scheduling a recurring/self-renewing task with `scheduleTask` or `runTask({ runAt })` + manual token bookkeeping → `scheduleTask` is one-shot (the task fires once and is gone; a self-rescheduling callback leaks a new parallel chain on every redundant setup call). Use `this.scheduleRecurring(key, …)` — the durable recurring primitive where the platform owns the cadence and re-arms the task every `intervalMs`. The callback does NOT need to reschedule itself; re-scheduling under the same key with a new `firstRunAt` is safe and atomic (tightens the next fire without leaking a second chain).
|
|
592
596
|
|
|
593
597
|
## Examples
|
|
594
598
|
|
|
@@ -4,6 +4,6 @@
|
|
|
4
4
|
* This file is auto-generated during build. Do not edit manually.
|
|
5
5
|
* Generated from: prebuild.ts
|
|
6
6
|
*/
|
|
7
|
-
declare const _default: "import { type Actor, type ActorId, type Contact, type DeliveryError, type Link, type NewLinkWithNotes, type Note, type Thread, type Uuid } from \"./plot\";\nimport type { ScheduleContactStatus } from \"./schedule\";\nimport {\n type AuthProvider,\n type AuthToken,\n type Authorization,\n type Channel,\n type LinkTypeConfig,\n type SyncContext,\n} from \"./tools/integrations\";\nimport { Twist } from \"./twist\";\n\n/**\n * Declares how a connector's platform handles emoji reactions.\n *\n * Drives Plot UI behavior (e.g. the picker filters the available\n * reactions on notes whose primary connector declares `fixed`) and\n * outbound dispatch (Plot won't try to push an emoji the platform\n * can't accept).\n *\n * Variants:\n * - `open-unicode`: Platform accepts any Unicode emoji. `customEmoji`\n * indicates whether the platform additionally supports workspace\n * custom emoji (Slack, Google Chat).\n * - `unicode-subset`: Platform accepts Unicode but only a finite set.\n * `subset` lists the allowed emoji (omit for \"currently full Unicode\n * per docs, future-proofed for shrinkage\").\n * - `fixed`: Platform only accepts a fixed set (e.g. LinkedIn\n * Messaging's 7-reaction set). `allowed` lists every supported emoji.\n */\nexport type ReactionCapabilities =\n | { mode: \"open-unicode\"; customEmoji?: \"workspace\" | \"none\" }\n | { mode: \"unicode-subset\"; subset?: readonly string[] }\n | { mode: \"fixed\"; allowed: readonly string[] };\n\n/**\n * Result returned from {@link Connector.onNoteCreated} and\n * {@link Connector.onNoteUpdated} to report what the external system now\n * has stored for the note.\n *\n * The runtime hashes `externalContent` and stores it as the note's sync\n * baseline. On the next sync-in, if the incoming content hashes to the\n * same value, the runtime knows the external side hasn't changed and\n * preserves Plot's (possibly formatted) content. When the external side\n * is edited, the hash diverges and the runtime overwrites Plot's content\n * with the new external version.\n *\n * Omitting `externalContent` skips baseline tracking \u2014 the next sync-in\n * will overwrite Plot's content (previous behavior). Always provide it\n * when the write-back's return value reflects what the external system\n * actually stored (often lossy plain-text), so the round-trip does not\n * clobber the original Plot markdown.\n *\n * The hash covers only the content string \u2014 the runtime intentionally\n * does not include a content-type in the hash, so write-back and sync-in\n * do not have to agree on a content-type label for the same underlying\n * bytes. Return exactly the string your connector's sync-in path will\n * emit as `NewNote.content` for this note on the next re-ingest.\n *\n * For back-compat, `onNoteCreated` may also return a plain string, which\n * is treated as `{ key }` with no baseline.\n */\nexport type NoteWriteBackResult = {\n /**\n * External system identifier assigned to this note. Set as the note's\n * `key` for future upsert matching. Required when the runtime does not\n * already know the key (i.e., from `onNoteCreated`); ignored from\n * `onNoteUpdated` when the key was already established on create.\n */\n key?: string;\n /**\n * The content string as the external system now stores it, post-write.\n * For systems whose write-back returns a representation of what was\n * actually stored (e.g. Google Drive comment `content` after a create),\n * pass that verbatim. For systems that only accept plain text, this\n * will often be a lossy plain-text version of the Plot markdown \u2014 that\n * is exactly the point: storing the lossy form as baseline lets the\n * next sync-in recognize it and skip overwriting the richer Plot\n * version.\n *\n * Must exactly match the string your connector's sync-in path emits as\n * `NewNote.content` for this note on re-ingest.\n */\n externalContent?: string;\n /**\n * Reports that the outbound send / write-back for this note FAILED and\n * could not be recovered (after the connector's own retries). The runtime\n * records it on the note \u2014 surfacing a \"Failed to send\" affordance (Retry /\n * Discard) to the user \u2014 and marks the thread unread.\n *\n * - object \u2192 record the failure.\n * - `null` \u2192 clear a previously-recorded failure (e.g. a successful retry).\n * - omitted (`undefined`) \u2192 leave any existing delivery state untouched.\n *\n * A successful write-back (any result without a `deliveryError`) also clears\n * a previously-recorded failure, so connectors usually only need to SET this\n * on failure.\n *\n * Prefer RETURNING this over throwing for expected, user-visible failures\n * (rejected recipient, message too large, quota exhausted): a thrown error\n * pages error tracking, whereas a returned `deliveryError` does not. Reserve\n * throwing for genuinely unexpected errors. Connectors that simply throw on a\n * failed write-back still get a generic \"Failed to send\" surfaced by the\n * runtime, just without a specific reason.\n */\n deliveryError?: DeliveryError | null;\n};\n\n/**\n * A Plot contact pre-resolved to its platform account ID, ready for use\n * in a messaging dispatch.\n *\n * Populated by the runtime for link types with `compose.targets: \"contacts\"` before\n * `onCreateLink` is called. The connector should use `externalAccountId`\n * directly to address the recipient on the platform (e.g. Slack user ID,\n * LinkedIn URN, Gmail address) without performing its own contact lookup.\n */\nexport type ResolvedRecipient = {\n /** Plot contact UUID */\n id: Uuid;\n /** Display name, or null if not set */\n name: string | null;\n /** Platform-specific account identifier pre-resolved at dispatch time (e.g. Slack `U\u2026`, LinkedIn URN, Gmail email address) */\n externalAccountId: string;\n /**\n * The contact's role on the originating thread, resolved from\n * `thread.contact_meta` against the link type's `contactRoles` (e.g.\n * `\"to\"` / `\"cc\"` / `\"bcc\"` for Gmail). `null` when the contact had no\n * explicit role entry \u2014 connectors should treat `null` as the link\n * type's default role (the `contactRoles` entry marked `default: true`).\n *\n * Connectors that distinguish roles MUST honor this when addressing the\n * recipient \u2014 e.g. Gmail must place `\"cc\"`/`\"bcc\"` recipients in the\n * Cc/Bcc headers, never the To header, so BCC recipients are not\n * exposed to the other recipients. Connectors that don't distinguish\n * roles (Slack, Linear) can ignore it.\n */\n role: string | null;\n};\n\n/**\n * Fields captured in Plot when a user initiates creation of a new external\n * item via a connector's `onCreateLink` hook.\n *\n * Thread-agnostic on purpose \u2014 connectors do not receive the Plot thread.\n * The platform attaches the returned `NewLinkWithNotes` to the originating\n * thread once `onCreateLink` resolves.\n */\nexport type CreateLinkDraft = {\n /** The channel (account + resource) the new item belongs to. */\n channelId: string;\n /** Link type identifier, matches a `LinkTypeConfig.type`. */\n type: string;\n /**\n * Status the user selected. Matches a `statuses[].status` for `type`,\n * or null for status-less link types (the parent linkType declares no\n * `statuses` and no `compose.status`).\n */\n status: string | null;\n /** Title of the originating Plot thread (post AI title generation). */\n title: string;\n /** Markdown content of the thread's first note, or null if none. */\n noteContent: string | null;\n /**\n * Contacts attached to the originating Plot thread, excluding the\n * creating user. Use these as recipients (email, chat DM members, etc.)\n * when the external item is a message or invite. An empty list means\n * the user did not add anyone to the thread.\n *\n * For link types with `compose.targets: \"contacts\"`, prefer `recipients` over\n * re-resolving contacts yourself: the runtime pre-resolves each contact\n * to its platform account ID (`externalAccountId`) and populates\n * `recipients` before `onCreateLink` is called.\n */\n contacts: Actor[];\n /**\n * Pre-resolved recipients for link types whose `compose.targets` is\n * `\"contacts\"` or `\"addresses\"`.\n *\n * Only populated for those link types; otherwise undefined. Each entry contains the Plot\n * contact UUID, the platform-specific account ID\n * (`externalAccountId`) the connector should use to address the\n * recipient without performing its own lookup, and the contact's\n * `role` on the thread (e.g. `\"to\"` / `\"cc\"` / `\"bcc\"`) resolved from\n * `thread.contact_meta`. For `\"addresses\"` link types, contacts without\n * a connection-scoped row fall back to `contact.email`.\n */\n recipients?: ResolvedRecipient[];\n /**\n * Free-form addresses the user typed into the picker (no Plot contact\n * row). Only populated for link types with `compose.targets: \"addresses\"`; otherwise\n * undefined. Connectors should append these alongside `recipients`\n * when constructing the recipient list (e.g. `To:` header for Gmail).\n */\n inviteEmails?: string[];\n};\n\n/** An optional OAuth scope group the user can toggle at connect time. */\nexport type OptionalScopeGroup = {\n /** Stable id used to track the user's selection. */\n id: string;\n /** Value-forward switch label, e.g. \"Add names to events using contacts\". */\n label: string;\n /** Optional secondary line shown under the label. */\n description?: string;\n /** The OAuth scope strings this group grants. */\n scopes: string[];\n /** Whether the group is requested by default (switch on). */\n default: boolean;\n};\n\n/**\n * Structured scope declaration. `required` scopes must be granted \u2014 auth fails\n * and re-prompts if any is declined. `optional` groups are requested by default\n * but auth still succeeds if the user declines them; the connector should detect\n * the absence via the granted `token.scopes` and degrade gracefully.\n */\nexport type ScopeConfig = {\n required: string[];\n optional?: OptionalScopeGroup[];\n};\n\n/**\n * Base class for connectors \u2014 twists that sync data from external services.\n *\n * Connectors declare a single OAuth provider and scopes, and implement channel\n * lifecycle methods for discovering and syncing external resources. They save\n * data directly via `integrations.saveLink()` instead of using the Plot tool.\n *\n * @example\n * ```typescript\n * class LinearConnector extends Connector<LinearConnector> {\n * readonly provider = AuthProvider.Linear;\n * readonly scopes = [\"read\", \"write\"];\n * readonly linkTypes = [{\n * type: \"issue\",\n * label: \"Issue\",\n * statuses: [\n * { status: \"open\", label: \"Open\", icon: \"todo\" },\n * { status: \"done\", label: \"Done\", icon: \"done\", done: true },\n * ],\n * }];\n *\n * build(build: ToolBuilder) {\n * return {\n * integrations: build(Integrations),\n * };\n * }\n *\n * async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n * const teams = await this.listTeams(token);\n * return teams.map(t => ({ id: t.id, title: t.name }));\n * }\n *\n * async onChannelEnabled(channel: Channel) {\n * const issues = await this.fetchIssues(channel.id);\n * for (const issue of issues) {\n * await this.tools.integrations.saveLink(issue);\n * }\n * }\n *\n * async onChannelDisabled(channel: Channel) {\n * // Clean up webhooks, sync state, etc.\n * }\n * }\n * ```\n */\nexport abstract class Connector<TSelf> extends Twist<TSelf> {\n /**\n * Static marker to identify Connector subclasses without instanceof checks\n * across worker boundaries.\n */\n static readonly isConnector = true;\n\n // ---- Identity (abstract \u2014 every connector must declare) ----\n\n /** The OAuth provider this connector authenticates with. */\n readonly provider?: AuthProvider;\n\n /** OAuth scopes to request for this connector \u2014 a flat list (all required), or\n * a {@link ScopeConfig} declaring required + optional scope groups. */\n readonly scopes?: string[] | ScopeConfig;\n\n /**\n * Plain-language bullets describing what access connecting this service\n * grants the user \u2014 shown on the connect screen regardless of auth mechanism\n * (OAuth, API key, or hosted). For OAuth connectors it also previews what the\n * provider's consent screen will request. These are justifications for what\n * Plot accesses, not a one-to-one mapping of scope strings.\n */\n readonly access?: string[];\n\n // ---- Auth model ----\n\n /**\n * When true, one credential is shared across all users in the workspace,\n * entered once by the installer. When false (default), each user provides\n * their own credential.\n *\n * Applies to both OAuth and key-based connectors:\n * - Shared OAuth: e.g. Slack bot token (workspace-level)\n * - Shared key: e.g. Attio workspace API key\n * - Individual OAuth: e.g. Google Calendar (per-user)\n * - Individual key: e.g. Fellow (per-user API key)\n */\n readonly shared?: boolean;\n\n /**\n * The Options field name that contains the authentication key (e.g. \"apiKey\").\n * Must reference a `secure: true` field in the Options schema.\n *\n * When set, this connector uses key-based auth instead of OAuth.\n * For individual connectors (`shared` is false), this field is stored\n * per-user rather than in shared config.\n */\n readonly keyOption?: string;\n\n // ---- Optional metadata ----\n\n /**\n * When true, this connector has a single implicit channel.\n * `getChannels()` must return exactly one Channel.\n * The UI will show channel config inline instead of a channel list.\n */\n readonly singleChannel?: boolean;\n\n /**\n * The user-facing noun for this connector's channels \u2014 what each\n * {@link Channel} returned by {@link getChannels} actually represents in the\n * external service. Many connectors map \"channels\" onto a domain concept\n * (folders, projects, calendars, labels, spaces, repositories, \u2026), so the\n * generic word \"channel\" reads as jargon. Set this and the UI substitutes it\n * everywhere it would otherwise say \"channel(s)\" \u2014 e.g. the per-connection\n * toggle becomes \"Sync new folders\" / \"When a new folder is added, \u2026\".\n *\n * Provide lowercase nouns (the UI capitalizes where needed):\n * `{ singular: \"folder\", plural: \"folders\" }`. Defaults to\n * `{ singular: \"channel\", plural: \"channels\" }` when omitted.\n */\n readonly channelNoun?: { singular: string; plural: string };\n\n /**\n * Whether the per-connection \"Sync new channels\" preference starts ON for\n * newly added connections of this connector. Defaults to `false` (opt-in).\n *\n * Set `true` for connectors that select **all** of their channels by default\n * (i.e. {@link getChannels} returns no channels marked\n * `enabledByDefault: false`). If syncing every channel is the intended\n * default, then channels discovered later should also sync automatically.\n * Leave `false`/omitted for selective connectors that exclude some channels\n * by default (e.g. Gmail syncs only Inbox/Sent, Google Calendar only\n * owner calendars) \u2014 for those, a newly discovered channel is just as\n * uncertain and should wait for the user to opt in.\n *\n * Only affects the **default** for new connections; the user's explicit\n * toggle always wins, and existing connections keep their stored preference.\n */\n readonly autoEnableNewChannelsByDefault?: boolean;\n\n /**\n * Whether this connector supports the platform's sequential auto-threading \u2014\n * folding a conversation that arrives as a run of separate top-level messages\n * into a single thread. Set `true` for conversational connectors (chat,\n * messaging) that mark eligible links with {@link NewLink.autoThread}. The UI\n * shows a per-connection \"Group related messages into conversations\" toggle\n * only for connectors that declare this.\n *\n * Leave undefined/false for connectors whose items are not conversational\n * (calendars, issue trackers, file storage) \u2014 marking a link does nothing\n * unless the connection both declares support and the user opted in.\n */\n readonly autoThreading?: boolean;\n\n /**\n * Whether the per-connection auto-threading preference starts ON for newly\n * added connections of this connector. Defaults to `false` (opt-in) \u2014 the\n * least-surprise default, since a wrong fold is irreversible. Only meaningful\n * when {@link autoThreading} is `true`. The user's explicit toggle always\n * wins, and existing connections keep their stored preference.\n */\n readonly autoThreadingByDefault?: boolean;\n\n /**\n * Registry of link types this connector creates (e.g., issue, event, message).\n * Used for display in the UI (icons, labels, statuses).\n */\n readonly linkTypes?: LinkTypeConfig[];\n\n /**\n * Declares how this connector's platform handles emoji reactions.\n * Used to filter the reaction picker for notes whose primary connector\n * is this one, and to guard outbound dispatch from sending emoji the\n * platform can't accept.\n *\n * Leave undefined for connectors whose platform has no concept of\n * reactions (calendar, file storage, issue trackers without reactions).\n */\n readonly reactionCapabilities?: ReactionCapabilities;\n\n /**\n * When true, this connector is mentioned by default on replies to threads it created.\n * When false (default), this connector cannot be mentioned at all.\n *\n * Set this to true for connectors with bidirectional sync (e.g., issue trackers,\n * messaging) where user replies should be written back to the external service.\n */\n static readonly handleReplies?: boolean;\n\n // ---- Account identity (abstract \u2014 every connector must implement) ----\n\n /**\n * Returns a human-readable name for the connected account.\n * Shown in the connections list and edit modal to identify this connection.\n *\n * For OAuth connectors, this is typically the workspace or organization name\n * (e.g., \"Acme Corp\" for a Linear workspace). For API key connectors, this\n * could be the workspace name from the external service.\n *\n * Override this in your connector to return a meaningful account name.\n *\n * @param auth - The authorization (null for no-provider connectors)\n * @param token - The access token (null for no-provider connectors)\n * @returns Promise resolving to the account display name\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n getAccountName(\n auth: Authorization | null,\n token: AuthToken | null\n ): Promise<string | null> {\n return Promise.resolve(null);\n }\n\n // ---- Channel lifecycle (abstract \u2014 every connector must implement) ----\n\n /**\n * Returns available channels for the authorized actor.\n * Called after OAuth is complete, during the setup/edit modal.\n *\n * @param auth - The completed authorization with provider and actor info\n * @param token - The access token for making API calls\n * @returns Promise resolving to available channels for the user to select\n */\n abstract getChannels(\n auth: Authorization | null,\n token: AuthToken | null\n ): Promise<Channel[]>;\n\n /**\n * Called when a channel resource is enabled for syncing.\n *\n * The framework dispatches this in three cases:\n * 1. **Initial enable** \u2014 user toggled the channel on for the first time.\n * 2. **Auto-enable** \u2014 `setChannels` discovered a new channel on a\n * connection with `auto_enable_new_channels` set.\n * 3. **Recovery after re-auth** \u2014 the user re-authorized a previously-\n * broken connection. The framework calls `onChannelEnabled` for every\n * channel that was already enabled at the time of re-auth, with\n * `context.recovering = true`. See {@link SyncContext.recovering}.\n *\n * Implementations should be **idempotent and overwrite stored state**:\n * the same channel may receive multiple `onChannelEnabled` calls across\n * its lifetime. Use unconditional `this.set()` writes rather than\n * coalesce/skip-if-present logic so a recovery dispatch wipes stale\n * cursors and state from the prior session.\n *\n * **Sync state tracking is automatic.** The framework stamps the\n * connection as \"syncing\" when it dispatches this method and clears\n * that state when:\n * - the connector calls `tools.integrations.channelSyncCompleted(id)`\n * once the initial backfill is done, OR\n * - this method throws an unhandled exception (auto-cleared so the UI\n * doesn't get stuck in \"syncing\" forever).\n *\n * **IMPORTANT: This method runs inline in the HTTP request handler.**\n * Any long-running work (webhook setup, API calls, sync) MUST be queued\n * as a separate task via `this.runTask()`, not executed inline. Blocking\n * here causes the client to spin waiting for the response.\n *\n * Only lightweight operations should appear directly in this method:\n * `this.set()`, `this.get()`, `this.callback()`, and `this.runTask()`.\n *\n * @example\n * ```typescript\n * async onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void> {\n * // Recovery: drop stale cursors so the next sync re-walks history.\n * if (context?.recovering) {\n * await this.clear(`last_sync_token_${channel.id}`);\n * }\n *\n * await this.set(`sync_state_${channel.id}`, { channelId: channel.id });\n *\n * // Queue sync as a task \u2014 do NOT use this.run() or call sync methods inline\n * const syncCallback = await this.callback(this.syncBatch, 1, \"full\", channel.id, true);\n * await this.runTask(syncCallback);\n *\n * // Queue webhook setup as a task \u2014 do NOT call setupWebhook() inline\n * const webhookCallback = await this.callback(this.setupWebhook, channel.id);\n * await this.runTask(webhookCallback);\n * }\n * ```\n *\n * @param channel - The channel that was enabled\n * @param context - Optional sync context (plan-based hints, recovery flag)\n */\n abstract onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void>;\n\n /**\n * Called when a channel resource is disabled.\n * Should stop sync, clean up webhooks, and remove state.\n *\n * @param channel - The channel that was disabled\n */\n abstract onChannelDisabled(channel: Channel): Promise<void>;\n\n // ---- Write-back hooks (optional, default no-ops) ----\n\n /**\n * Called when a link created by this connector is updated by the user.\n * Override to write back changes to the external service\n * (e.g., changing issue status in Linear when marked done in Plot).\n *\n * @param link - The updated link\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onLinkUpdated(link: Link): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user creates a thread in Plot that should create a new\n * item in this connector's external system.\n *\n * A connector opts in to Plot-initiated creation by declaring a\n * `compose` block on the relevant `LinkTypeConfig` (see\n * {@link ComposeConfig}). When a user picks \"Create new <type>\" from the\n * Add link modal and the thread is synced, the runtime calls this method\n * with the draft fields.\n *\n * Implementations should create the item in the external service and\n * return a `NewLinkWithNotes` describing the created item. The platform\n * attaches the returned link to the originating thread \u2014 do not call\n * `integrations.saveLink` yourself.\n *\n * Returning `null` aborts creation silently (the thread is still saved\n * without a link).\n *\n * @param draft - The fields captured in Plot for the new item.\n * @returns The link to attach, or null to abort creation.\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onCreateLink(draft: CreateLinkDraft): Promise<NewLinkWithNotes | null> {\n return Promise.resolve(null);\n }\n\n /**\n * Called when a note is created on a thread owned by this connector.\n * Override to write back comments to the external service\n * (e.g., adding a comment to a Linear issue).\n *\n * Returning a string or {@link NoteWriteBackResult} links the Plot note\n * to its external counterpart. A plain string sets the note's `key`.\n * A `NoteWriteBackResult` additionally sets a sync baseline (via\n * `externalContent`) so the next sync-in can recognize the round-tripped\n * content and preserve Plot's formatted version. See\n * {@link NoteWriteBackResult} for details.\n *\n * @param note - The created note\n * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n * @returns Optional note key or NoteWriteBackResult for external dedup + baseline tracking\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onNoteCreated(note: Note, thread: Thread): Promise<string | NoteWriteBackResult | void> {\n return Promise.resolve();\n }\n\n /**\n * Resolve a `fileRef` action's bytes for download. Called when a user opens\n * an attachment in Plot. Return either a redirect URL (preferred for sources\n * that issue signed URLs, like Linear S3 or Slack permalink_public) or a\n * streamed body (required when bytes are only reachable through an\n * authenticated API call, like Gmail attachments.get).\n *\n * @param ref Opaque value the connector previously emitted on a fileRef action.\n * @returns Either `{ redirectUrl }` or `{ body, mimeType, fileName? }`.\n * @throws If the source is unavailable, the connection is broken, or `ref` is invalid.\n *\n * If not overridden, fileRef actions on this connector's notes will return 410 Gone.\n */\n async downloadAttachment(\n ref: string,\n ): Promise<\n | { redirectUrl: string }\n | { body: ReadableStream | Uint8Array; mimeType: string; fileName?: string }\n > {\n throw new Error(\n `downloadAttachment not implemented for ${this.constructor.name} (ref=${ref})`,\n );\n }\n\n /**\n * Called when a note on a thread owned by this connector is updated.\n * Override to write back changes to the external service\n * (e.g., syncing reaction tags as emoji reactions, or editing a comment\n * whose content changed in Plot).\n *\n * Return a {@link NoteWriteBackResult} with `externalContent` to update\n * the sync baseline after a successful write-back, so the next sync-in\n * recognizes the external version as already-seen and preserves Plot's\n * content.\n *\n * @param note - The updated note (includes current tags)\n * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n * @returns Optional NoteWriteBackResult for baseline tracking\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onNoteUpdated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user reads or unreads a thread owned by this connector.\n * Override to write back read status to the external service\n * (e.g., marking an email as read in Gmail).\n *\n * @param thread - The thread that was read/unread (includes thread.meta with connector-specific data)\n * @param actor - The user who performed the action\n * @param unread - false when marked as read, true when marked as unread\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onThreadRead(thread: Thread, actor: Actor, unread: boolean): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user changes the **thread-level sharing** of a thread owned\n * by this connector \u2014 adding or removing a contact, or (for connectors with\n * roles) changing a contact's role. Override on connectors whose external\n * source can reflect that membership change, e.g. a group DM / multi-party\n * chat (`LinkTypeConfig.sharingModel: \"thread\"`) or an email's To/Cc/Bcc\n * recipients (`sharingModel: \"message\"`). Connectors backed by an immutable\n * roster (most group DMs today) or by channel-level membership\n * (`sharingModel: \"channel\"`) leave this as the default no-op.\n *\n * `role`/`from`/`to` are **null** for connectors without roles (group DMs\n * have no roles); they carry a `contactRoles` id only for connectors that\n * declare roles (e.g. email `to`/`cc`/`bcc`).\n *\n * The dispatch fires after Plot has persisted the change. A connector may\n * reflect it actively (e.g. add/remove a participant on the external chat)\n * or passively on the next outbound note (e.g. building To/Cc/Bcc headers\n * from the current `thread.contacts` \u00D7 `thread.contactMeta`) \u2014 this callback\n * is not the right place to send a standalone notification.\n *\n * @param thread - The thread whose contacts changed\n * @param changes - The added/removed contacts and any role transitions on existing contacts\n */\n /* eslint-disable @typescript-eslint/no-unused-vars */\n onContactsChanged(\n thread: Thread,\n changes: {\n added: Array<{ contact: Contact; role: string | null }>;\n removed: Array<{ contact: Contact; role: string | null }>;\n changed: Array<{ contact: Contact; from: string | null; to: string | null }>;\n },\n ): Promise<void> {\n return Promise.resolve();\n }\n /* eslint-enable @typescript-eslint/no-unused-vars */\n\n /**\n * Called when a user marks or unmarks a thread as todo.\n * Override to sync todo status to the external service\n * (e.g., starring an email in Gmail when marked as todo).\n *\n * @param thread - The thread (includes thread.meta with connector-specific data)\n * @param actor - The user who changed the todo status\n * @param todo - true when marked as todo, false when done or removed\n * @param options - Additional context\n * @param options.date - The todo date (when todo=true)\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onThreadToDo(thread: Thread, actor: Actor, todo: boolean, options: { date?: Date }): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a schedule contact's RSVP status changes on a thread owned by this connector.\n * Override to sync RSVP changes back to the external calendar.\n *\n * @param thread - The thread (includes thread.meta with connector-specific data)\n * @param scheduleId - The schedule ID\n * @param contactId - The contact whose status changed\n * @param status - The new RSVP status ('attend', 'skip', or null)\n * @param actor - The user who changed the status\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onScheduleContactUpdated(thread: Thread, scheduleId: string, contactId: ActorId, status: ScheduleContactStatus | null, actor: Actor): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user adds or removes a single emoji reaction on a note\n * (one event per `(note, actor, emoji)` state transition).\n *\n * Dispatch is routed to the reacting user's own connector instance via\n * `twist_instance_for_actor` on `note_reaction.actor_id`, so this method\n * already runs under the reactor's auth. Fetch the API client with the\n * connector's normal token-fetch path (`this.tools.integrations.get(...)`)\n * and the external write \u2014 e.g. Slack `reactions.add` \u2014 will be attributed\n * to the correct user. No `actAs` step required.\n *\n * If the reacting user has no connection of this type, no dispatch fires\n * for that reaction (it stays in Plot only).\n *\n * Override to sync per-actor reactions back to the external system.\n *\n * @param note - The note that was reacted on (partial; `id`, `key`, `content` populated)\n * @param thread - The thread the note belongs to (partial; `id`, `title`, `archived`, `meta` populated)\n * @param actor - The contact who added/removed the reaction\n * @param emoji - The emoji (Unicode grapheme or `provider:workspace/name` custom-emoji ref)\n * @param added - `true` if the reaction is now present, `false` if it was removed\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onNoteReactionChanged(note: Note, thread: Thread, actor: Actor, emoji: string, added: boolean): Promise<void> {\n return Promise.resolve();\n }\n\n // ---- Activation ----\n\n /**\n * Called when the connector is activated after OAuth is complete.\n *\n * Connectors receive the authorization in addition to the activating actor.\n * When this runs, `this.userId` is already populated with the installing\n * user's ID.\n *\n * Default implementation does nothing. Override for custom setup.\n *\n * @param context - The activation context\n * @param context.auth - The completed OAuth authorization\n * @param context.actor - The actor who activated the connector\n */\n // @ts-ignore - Connector.activate() has a Connector-specific context type.\n activate(context: { auth?: Authorization; actor?: Actor }): Promise<void> {\n return Promise.resolve();\n }\n}\n\n/** @deprecated Use `Connector` instead. */\nexport { Connector as Source };\n";
|
|
7
|
+
declare const _default: "import { type Actor, type ActorId, type Contact, type DeliveryError, type Link, type NewLinkWithNotes, type Note, type Thread, type Uuid } from \"./plot\";\nimport type { ScheduleContactStatus } from \"./schedule\";\nimport {\n type AuthProvider,\n type AuthToken,\n type Authorization,\n type Channel,\n type LinkTypeConfig,\n type SyncContext,\n} from \"./tools/integrations\";\nimport { Twist } from \"./twist\";\n\n/**\n * Declares how a connector's platform handles emoji reactions.\n *\n * Drives Plot UI behavior (e.g. the picker filters the available\n * reactions on notes whose primary connector declares `fixed`) and\n * outbound dispatch (Plot won't try to push an emoji the platform\n * can't accept).\n *\n * Variants:\n * - `open-unicode`: Platform accepts any Unicode emoji. `customEmoji`\n * indicates whether the platform additionally supports workspace\n * custom emoji (Slack, Google Chat).\n * - `unicode-subset`: Platform accepts Unicode but only a finite set.\n * `subset` lists the allowed emoji (omit for \"currently full Unicode\n * per docs, future-proofed for shrinkage\").\n * - `fixed`: Platform only accepts a fixed set (e.g. LinkedIn\n * Messaging's 7-reaction set). `allowed` lists every supported emoji.\n */\nexport type ReactionCapabilities =\n | { mode: \"open-unicode\"; customEmoji?: \"workspace\" | \"none\" }\n | { mode: \"unicode-subset\"; subset?: readonly string[] }\n | { mode: \"fixed\"; allowed: readonly string[] };\n\n/**\n * Result returned from {@link Connector.onNoteCreated} and\n * {@link Connector.onNoteUpdated} to report what the external system now\n * has stored for the note.\n *\n * The runtime hashes `externalContent` and stores it as the note's sync\n * baseline. On the next sync-in, if the incoming content hashes to the\n * same value, the runtime knows the external side hasn't changed and\n * preserves Plot's (possibly formatted) content. When the external side\n * is edited, the hash diverges and the runtime overwrites Plot's content\n * with the new external version.\n *\n * Omitting `externalContent` skips baseline tracking \u2014 the next sync-in\n * will overwrite Plot's content (previous behavior). Always provide it\n * when the write-back's return value reflects what the external system\n * actually stored (often lossy plain-text), so the round-trip does not\n * clobber the original Plot markdown.\n *\n * The hash covers only the content string \u2014 the runtime intentionally\n * does not include a content-type in the hash, so write-back and sync-in\n * do not have to agree on a content-type label for the same underlying\n * bytes. Return exactly the string your connector's sync-in path will\n * emit as `NewNote.content` for this note on the next re-ingest.\n *\n * For back-compat, `onNoteCreated` may also return a plain string, which\n * is treated as `{ key }` with no baseline.\n */\nexport type NoteWriteBackResult = {\n /**\n * External system identifier assigned to this note. Set as the note's\n * `key` for future upsert matching. Required when the runtime does not\n * already know the key (i.e., from `onNoteCreated`); ignored from\n * `onNoteUpdated` when the key was already established on create.\n */\n key?: string;\n /**\n * The content string as the external system now stores it, post-write.\n * For systems whose write-back returns a representation of what was\n * actually stored (e.g. Google Drive comment `content` after a create),\n * pass that verbatim. For systems that only accept plain text, this\n * will often be a lossy plain-text version of the Plot markdown \u2014 that\n * is exactly the point: storing the lossy form as baseline lets the\n * next sync-in recognize it and skip overwriting the richer Plot\n * version.\n *\n * Must exactly match the string your connector's sync-in path emits as\n * `NewNote.content` for this note on re-ingest.\n */\n externalContent?: string;\n /**\n * Reports that the outbound send / write-back for this note FAILED and\n * could not be recovered (after the connector's own retries). The runtime\n * records it on the note \u2014 surfacing a \"Failed to send\" affordance (Retry /\n * Discard) to the user \u2014 and marks the thread unread.\n *\n * - object \u2192 record the failure.\n * - `null` \u2192 clear a previously-recorded failure (e.g. a successful retry).\n * - omitted (`undefined`) \u2192 leave any existing delivery state untouched.\n *\n * A successful write-back (any result without a `deliveryError`) also clears\n * a previously-recorded failure, so connectors usually only need to SET this\n * on failure.\n *\n * Prefer RETURNING this over throwing for expected, user-visible failures\n * (rejected recipient, message too large, quota exhausted): a thrown error\n * pages error tracking, whereas a returned `deliveryError` does not. Reserve\n * throwing for genuinely unexpected errors. Connectors that simply throw on a\n * failed write-back still get a generic \"Failed to send\" surfaced by the\n * runtime, just without a specific reason.\n */\n deliveryError?: DeliveryError | null;\n};\n\n/**\n * A Plot contact pre-resolved to its platform account ID, ready for use\n * in a messaging dispatch.\n *\n * Populated by the runtime for link types with `compose.targets: \"contacts\"` before\n * `onCreateLink` is called. The connector should use `externalAccountId`\n * directly to address the recipient on the platform (e.g. Slack user ID,\n * LinkedIn URN, Gmail address) without performing its own contact lookup.\n */\nexport type ResolvedRecipient = {\n /** Plot contact UUID */\n id: Uuid;\n /** Display name, or null if not set */\n name: string | null;\n /** Platform-specific account identifier pre-resolved at dispatch time (e.g. Slack `U\u2026`, LinkedIn URN, Gmail email address) */\n externalAccountId: string;\n /**\n * The contact's role on the originating thread, resolved from\n * `thread.contact_meta` against the link type's `contactRoles` (e.g.\n * `\"to\"` / `\"cc\"` / `\"bcc\"` for Gmail). `null` when the contact had no\n * explicit role entry \u2014 connectors should treat `null` as the link\n * type's default role (the `contactRoles` entry marked `default: true`).\n *\n * Connectors that distinguish roles MUST honor this when addressing the\n * recipient \u2014 e.g. Gmail must place `\"cc\"`/`\"bcc\"` recipients in the\n * Cc/Bcc headers, never the To header, so BCC recipients are not\n * exposed to the other recipients. Connectors that don't distinguish\n * roles (Slack, Linear) can ignore it.\n */\n role: string | null;\n};\n\n/**\n * Fields captured in Plot when a user initiates creation of a new external\n * item via a connector's `onCreateLink` hook.\n *\n * Thread-agnostic on purpose \u2014 connectors do not receive the Plot thread.\n * The platform attaches the returned `NewLinkWithNotes` to the originating\n * thread once `onCreateLink` resolves.\n */\nexport type CreateLinkDraft = {\n /** The channel (account + resource) the new item belongs to. */\n channelId: string;\n /** Link type identifier, matches a `LinkTypeConfig.type`. */\n type: string;\n /**\n * Status the user selected. Matches a `statuses[].status` for `type`,\n * or null for status-less link types (the parent linkType declares no\n * `statuses` and no `compose.status`).\n */\n status: string | null;\n /** Title of the originating Plot thread (post AI title generation). */\n title: string;\n /** Markdown content of the thread's first note, or null if none. */\n noteContent: string | null;\n /**\n * Contacts attached to the originating Plot thread, excluding the\n * creating user. Use these as recipients (email, chat DM members, etc.)\n * when the external item is a message or invite. An empty list means\n * the user did not add anyone to the thread.\n *\n * For link types with `compose.targets: \"contacts\"`, prefer `recipients` over\n * re-resolving contacts yourself: the runtime pre-resolves each contact\n * to its platform account ID (`externalAccountId`) and populates\n * `recipients` before `onCreateLink` is called.\n */\n contacts: Actor[];\n /**\n * Pre-resolved recipients for link types whose `compose.targets` is\n * `\"contacts\"` or `\"addresses\"`.\n *\n * Only populated for those link types; otherwise undefined. Each entry contains the Plot\n * contact UUID, the platform-specific account ID\n * (`externalAccountId`) the connector should use to address the\n * recipient without performing its own lookup, and the contact's\n * `role` on the thread (e.g. `\"to\"` / `\"cc\"` / `\"bcc\"`) resolved from\n * `thread.contact_meta`. For `\"addresses\"` link types, contacts without\n * a connection-scoped row fall back to `contact.email`.\n */\n recipients?: ResolvedRecipient[];\n /**\n * Free-form addresses the user typed into the picker (no Plot contact\n * row). Only populated for link types with `compose.targets: \"addresses\"`; otherwise\n * undefined. Connectors should append these alongside `recipients`\n * when constructing the recipient list (e.g. `To:` header for Gmail).\n */\n inviteEmails?: string[];\n};\n\n/** An optional OAuth scope group the user can toggle at connect time. */\nexport type OptionalScopeGroup = {\n /** Stable id used to track the user's selection. */\n id: string;\n /** Value-forward switch label, e.g. \"Add names to events using contacts\". */\n label: string;\n /** Optional secondary line shown under the label. */\n description?: string;\n /** The OAuth scope strings this group grants. */\n scopes: string[];\n /** Whether the group is requested by default (switch on). */\n default: boolean;\n};\n\n/**\n * Structured scope declaration. `required` scopes must be granted \u2014 auth fails\n * and re-prompts if any is declined. `optional` groups are requested by default\n * but auth still succeeds if the user declines them; the connector should detect\n * the absence via the granted `token.scopes` and degrade gracefully.\n */\nexport type ScopeConfig = {\n required: string[];\n optional?: OptionalScopeGroup[];\n};\n\n/**\n * Base class for connectors \u2014 twists that sync data from external services.\n *\n * Connectors declare a single OAuth provider and scopes, and implement channel\n * lifecycle methods for discovering and syncing external resources. They save\n * data directly via `integrations.saveLink()` instead of using the Plot tool.\n *\n * @example\n * ```typescript\n * class LinearConnector extends Connector<LinearConnector> {\n * readonly provider = AuthProvider.Linear;\n * readonly scopes = [\"read\", \"write\"];\n * readonly linkTypes = [{\n * type: \"issue\",\n * label: \"Issue\",\n * statuses: [\n * { status: \"open\", label: \"Open\", icon: \"todo\" },\n * { status: \"done\", label: \"Done\", icon: \"done\", done: true },\n * ],\n * }];\n *\n * build(build: ToolBuilder) {\n * return {\n * integrations: build(Integrations),\n * };\n * }\n *\n * async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n * const teams = await this.listTeams(token);\n * return teams.map(t => ({ id: t.id, title: t.name }));\n * }\n *\n * async onChannelEnabled(channel: Channel) {\n * const issues = await this.fetchIssues(channel.id);\n * for (const issue of issues) {\n * await this.tools.integrations.saveLink(issue);\n * }\n * }\n *\n * async onChannelDisabled(channel: Channel) {\n * // Clean up webhooks, sync state, etc.\n * }\n * }\n * ```\n */\nexport abstract class Connector<TSelf> extends Twist<TSelf> {\n /**\n * Static marker to identify Connector subclasses without instanceof checks\n * across worker boundaries.\n */\n static readonly isConnector = true;\n\n // ---- Identity (abstract \u2014 every connector must declare) ----\n\n /** The OAuth provider this connector authenticates with. */\n readonly provider?: AuthProvider;\n\n /** OAuth scopes to request for this connector \u2014 a flat list (all required), or\n * a {@link ScopeConfig} declaring required + optional scope groups. */\n readonly scopes?: string[] | ScopeConfig;\n\n /**\n * Plain-language bullets describing what access connecting this service\n * grants the user \u2014 shown on the connect screen regardless of auth mechanism\n * (OAuth, API key, or hosted). For OAuth connectors it also previews what the\n * provider's consent screen will request. These are justifications for what\n * Plot accesses, not a one-to-one mapping of scope strings.\n */\n readonly access?: string[];\n\n // ---- Auth model ----\n\n /**\n * When true, one credential is shared across all users in the workspace,\n * entered once by the installer. When false (default), each user provides\n * their own credential.\n *\n * Applies to both OAuth and key-based connectors:\n * - Shared OAuth: e.g. Slack bot token (workspace-level)\n * - Shared key: e.g. Attio workspace API key\n * - Individual OAuth: e.g. Google Calendar (per-user)\n * - Individual key: e.g. Fellow (per-user API key)\n */\n readonly shared?: boolean;\n\n /**\n * The Options field name that contains the authentication key (e.g. \"apiKey\").\n * Must reference a `secure: true` field in the Options schema.\n *\n * When set, this connector uses key-based auth instead of OAuth.\n * For individual connectors (`shared` is false), this field is stored\n * per-user rather than in shared config.\n */\n readonly keyOption?: string;\n\n // ---- Optional metadata ----\n\n /**\n * When true, this connector has a single implicit channel.\n * `getChannels()` must return exactly one Channel.\n * The UI will show channel config inline instead of a channel list.\n */\n readonly singleChannel?: boolean;\n\n /**\n * The user-facing noun for this connector's channels \u2014 what each\n * {@link Channel} returned by {@link getChannels} actually represents in the\n * external service. Many connectors map \"channels\" onto a domain concept\n * (folders, projects, calendars, labels, spaces, repositories, \u2026), so the\n * generic word \"channel\" reads as jargon. Set this and the UI substitutes it\n * everywhere it would otherwise say \"channel(s)\" \u2014 e.g. the per-connection\n * toggle becomes \"Sync new folders\" / \"When a new folder is added, \u2026\".\n *\n * Provide lowercase nouns (the UI capitalizes where needed):\n * `{ singular: \"folder\", plural: \"folders\" }`. Defaults to\n * `{ singular: \"channel\", plural: \"channels\" }` when omitted.\n */\n readonly channelNoun?: { singular: string; plural: string };\n\n /**\n * Whether the per-connection \"Sync new channels\" preference starts ON for\n * newly added connections of this connector. Defaults to `false` (opt-in).\n *\n * Set `true` for connectors that select **all** of their channels by default\n * (i.e. {@link getChannels} returns no channels marked\n * `enabledByDefault: false`). If syncing every channel is the intended\n * default, then channels discovered later should also sync automatically.\n * Leave `false`/omitted for selective connectors that exclude some channels\n * by default (e.g. Gmail syncs only Inbox/Sent, Google Calendar only\n * owner calendars) \u2014 for those, a newly discovered channel is just as\n * uncertain and should wait for the user to opt in.\n *\n * Only affects the **default** for new connections; the user's explicit\n * toggle always wins, and existing connections keep their stored preference.\n */\n readonly autoEnableNewChannelsByDefault?: boolean;\n\n /**\n * Whether this connector supports the platform's sequential auto-threading \u2014\n * folding a conversation that arrives as a run of separate top-level messages\n * into a single thread. Set `true` for conversational connectors (chat,\n * messaging) that mark eligible links with {@link NewLink.autoThread}. The UI\n * shows a per-connection \"Group related messages into conversations\" toggle\n * only for connectors that declare this.\n *\n * Leave undefined/false for connectors whose items are not conversational\n * (calendars, issue trackers, file storage) \u2014 marking a link does nothing\n * unless the connection both declares support and the user opted in.\n */\n readonly autoThreading?: boolean;\n\n /**\n * Whether the per-connection auto-threading preference starts ON for newly\n * added connections of this connector. Defaults to `false` (opt-in) \u2014 the\n * least-surprise default, since a wrong fold is irreversible. Only meaningful\n * when {@link autoThreading} is `true`. The user's explicit toggle always\n * wins, and existing connections keep their stored preference.\n */\n readonly autoThreadingByDefault?: boolean;\n\n /**\n * Registry of link types this connector creates (e.g., issue, event, message).\n * Used for display in the UI (icons, labels, statuses).\n */\n readonly linkTypes?: LinkTypeConfig[];\n\n /**\n * Declares how this connector's platform handles emoji reactions.\n * Used to filter the reaction picker for notes whose primary connector\n * is this one, and to guard outbound dispatch from sending emoji the\n * platform can't accept.\n *\n * Leave undefined for connectors whose platform has no concept of\n * reactions (calendar, file storage, issue trackers without reactions).\n */\n readonly reactionCapabilities?: ReactionCapabilities;\n\n /**\n * When true, this connector's effective link types are computed dynamically\n * from its enabled channels' per-channel link types (each channel carries the\n * link types for whatever product/resource it represents), rather than the\n * static union of all declared providers' link types. Lets one connection\n * surface different link types depending on what the user has enabled \u2014 e.g.\n * a combined Google connection shows calendar/event link types (and thus the\n * agenda) only when a calendar channel is enabled.\n *\n * Defaults to false (static link types \u2014 the behavior for every connector\n * that doesn't set this). Requires the connector to attach per-channel\n * `linkTypes` on the channels returned by `getChannels`.\n */\n readonly dynamicLinkTypes?: boolean;\n\n /**\n * When true, this connector is mentioned by default on replies to threads it created.\n * When false (default), this connector cannot be mentioned at all.\n *\n * Set this to true for connectors with bidirectional sync (e.g., issue trackers,\n * messaging) where user replies should be written back to the external service.\n */\n static readonly handleReplies?: boolean;\n\n // ---- Account identity (abstract \u2014 every connector must implement) ----\n\n /**\n * Returns a human-readable name for the connected account.\n * Shown in the connections list and edit modal to identify this connection.\n *\n * For OAuth connectors, this is typically the workspace or organization name\n * (e.g., \"Acme Corp\" for a Linear workspace). For API key connectors, this\n * could be the workspace name from the external service.\n *\n * Override this in your connector to return a meaningful account name.\n *\n * @param auth - The authorization (null for no-provider connectors)\n * @param token - The access token (null for no-provider connectors)\n * @returns Promise resolving to the account display name\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n getAccountName(\n auth: Authorization | null,\n token: AuthToken | null\n ): Promise<string | null> {\n return Promise.resolve(null);\n }\n\n // ---- Channel lifecycle (abstract \u2014 every connector must implement) ----\n\n /**\n * Returns available channels for the authorized actor.\n * Called after OAuth is complete, during the setup/edit modal.\n *\n * @param auth - The completed authorization with provider and actor info\n * @param token - The access token for making API calls\n * @returns Promise resolving to available channels for the user to select\n */\n abstract getChannels(\n auth: Authorization | null,\n token: AuthToken | null\n ): Promise<Channel[]>;\n\n /**\n * Called when a channel resource is enabled for syncing.\n *\n * The framework dispatches this in three cases:\n * 1. **Initial enable** \u2014 user toggled the channel on for the first time.\n * 2. **Auto-enable** \u2014 `setChannels` discovered a new channel on a\n * connection with `auto_enable_new_channels` set.\n * 3. **Recovery after re-auth** \u2014 the user re-authorized a previously-\n * broken connection. The framework calls `onChannelEnabled` for every\n * channel that was already enabled at the time of re-auth, with\n * `context.recovering = true`. See {@link SyncContext.recovering}.\n *\n * Implementations should be **idempotent and overwrite stored state**:\n * the same channel may receive multiple `onChannelEnabled` calls across\n * its lifetime. Use unconditional `this.set()` writes rather than\n * coalesce/skip-if-present logic so a recovery dispatch wipes stale\n * cursors and state from the prior session.\n *\n * **Sync state tracking is automatic.** The framework stamps the\n * connection as \"syncing\" when it dispatches this method and clears\n * that state when:\n * - the connector calls `tools.integrations.channelSyncCompleted(id)`\n * once the initial backfill is done, OR\n * - this method throws an unhandled exception (auto-cleared so the UI\n * doesn't get stuck in \"syncing\" forever).\n *\n * **IMPORTANT: This method runs inline in the HTTP request handler.**\n * Any long-running work (webhook setup, API calls, sync) MUST be queued\n * as a separate task via `this.runTask()`, not executed inline. Blocking\n * here causes the client to spin waiting for the response.\n *\n * Only lightweight operations should appear directly in this method:\n * `this.set()`, `this.get()`, `this.callback()`, and `this.runTask()`.\n *\n * @example\n * ```typescript\n * async onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void> {\n * // Recovery: drop stale cursors so the next sync re-walks history.\n * if (context?.recovering) {\n * await this.clear(`last_sync_token_${channel.id}`);\n * }\n *\n * await this.set(`sync_state_${channel.id}`, { channelId: channel.id });\n *\n * // Queue sync as a task \u2014 do NOT use this.run() or call sync methods inline\n * const syncCallback = await this.callback(this.syncBatch, 1, \"full\", channel.id, true);\n * await this.runTask(syncCallback);\n *\n * // Queue webhook setup as a task \u2014 do NOT call setupWebhook() inline\n * const webhookCallback = await this.callback(this.setupWebhook, channel.id);\n * await this.runTask(webhookCallback);\n * }\n * ```\n *\n * @param channel - The channel that was enabled\n * @param context - Optional sync context (plan-based hints, recovery flag)\n */\n abstract onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void>;\n\n /**\n * Called when a channel resource is disabled.\n * Should stop sync, clean up webhooks, and remove state.\n *\n * @param channel - The channel that was disabled\n */\n abstract onChannelDisabled(channel: Channel): Promise<void>;\n\n // ---- Write-back hooks (optional, default no-ops) ----\n\n /**\n * Called when a link created by this connector is updated by the user.\n * Override to write back changes to the external service\n * (e.g., changing issue status in Linear when marked done in Plot).\n *\n * @param link - The updated link\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onLinkUpdated(link: Link): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user creates a thread in Plot that should create a new\n * item in this connector's external system.\n *\n * A connector opts in to Plot-initiated creation by declaring a\n * `compose` block on the relevant `LinkTypeConfig` (see\n * {@link ComposeConfig}). When a user picks \"Create new <type>\" from the\n * Add link modal and the thread is synced, the runtime calls this method\n * with the draft fields.\n *\n * Implementations should create the item in the external service and\n * return a `NewLinkWithNotes` describing the created item. The platform\n * attaches the returned link to the originating thread \u2014 do not call\n * `integrations.saveLink` yourself.\n *\n * Returning `null` aborts creation silently (the thread is still saved\n * without a link).\n *\n * @param draft - The fields captured in Plot for the new item.\n * @returns The link to attach, or null to abort creation.\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onCreateLink(draft: CreateLinkDraft): Promise<NewLinkWithNotes | null> {\n return Promise.resolve(null);\n }\n\n /**\n * Called when a note is created on a thread owned by this connector.\n * Override to write back comments to the external service\n * (e.g., adding a comment to a Linear issue).\n *\n * Returning a string or {@link NoteWriteBackResult} links the Plot note\n * to its external counterpart. A plain string sets the note's `key`.\n * A `NoteWriteBackResult` additionally sets a sync baseline (via\n * `externalContent`) so the next sync-in can recognize the round-tripped\n * content and preserve Plot's formatted version. See\n * {@link NoteWriteBackResult} for details.\n *\n * @param note - The created note\n * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n * @returns Optional note key or NoteWriteBackResult for external dedup + baseline tracking\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onNoteCreated(note: Note, thread: Thread): Promise<string | NoteWriteBackResult | void> {\n return Promise.resolve();\n }\n\n /**\n * Resolve a `fileRef` action's bytes for download. Called when a user opens\n * an attachment in Plot. Return either a redirect URL (preferred for sources\n * that issue signed URLs, like Linear S3 or Slack permalink_public) or a\n * streamed body (required when bytes are only reachable through an\n * authenticated API call, like Gmail attachments.get).\n *\n * @param ref Opaque value the connector previously emitted on a fileRef action.\n * @returns Either `{ redirectUrl }` or `{ body, mimeType, fileName? }`.\n * @throws If the source is unavailable, the connection is broken, or `ref` is invalid.\n *\n * If not overridden, fileRef actions on this connector's notes will return 410 Gone.\n */\n async downloadAttachment(\n ref: string,\n ): Promise<\n | { redirectUrl: string }\n | { body: ReadableStream | Uint8Array; mimeType: string; fileName?: string }\n > {\n throw new Error(\n `downloadAttachment not implemented for ${this.constructor.name} (ref=${ref})`,\n );\n }\n\n /**\n * Called when a note on a thread owned by this connector is updated.\n * Override to write back changes to the external service\n * (e.g., syncing reaction tags as emoji reactions, or editing a comment\n * whose content changed in Plot).\n *\n * Return a {@link NoteWriteBackResult} with `externalContent` to update\n * the sync baseline after a successful write-back, so the next sync-in\n * recognizes the external version as already-seen and preserves Plot's\n * content.\n *\n * @param note - The updated note (includes current tags)\n * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n * @returns Optional NoteWriteBackResult for baseline tracking\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onNoteUpdated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user reads or unreads a thread owned by this connector.\n * Override to write back read status to the external service\n * (e.g., marking an email as read in Gmail).\n *\n * @param thread - The thread that was read/unread (includes thread.meta with connector-specific data)\n * @param actor - The user who performed the action\n * @param unread - false when marked as read, true when marked as unread\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onThreadRead(thread: Thread, actor: Actor, unread: boolean): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user changes the **thread-level sharing** of a thread owned\n * by this connector \u2014 adding or removing a contact, or (for connectors with\n * roles) changing a contact's role. Override on connectors whose external\n * source can reflect that membership change, e.g. a group DM / multi-party\n * chat (`LinkTypeConfig.sharingModel: \"thread\"`) or an email's To/Cc/Bcc\n * recipients (`sharingModel: \"message\"`). Connectors backed by an immutable\n * roster (most group DMs today) or by channel-level membership\n * (`sharingModel: \"channel\"`) leave this as the default no-op.\n *\n * `role`/`from`/`to` are **null** for connectors without roles (group DMs\n * have no roles); they carry a `contactRoles` id only for connectors that\n * declare roles (e.g. email `to`/`cc`/`bcc`).\n *\n * The dispatch fires after Plot has persisted the change. A connector may\n * reflect it actively (e.g. add/remove a participant on the external chat)\n * or passively on the next outbound note (e.g. building To/Cc/Bcc headers\n * from the current `thread.contacts` \u00D7 `thread.contactMeta`) \u2014 this callback\n * is not the right place to send a standalone notification.\n *\n * @param thread - The thread whose contacts changed\n * @param changes - The added/removed contacts and any role transitions on existing contacts\n */\n /* eslint-disable @typescript-eslint/no-unused-vars */\n onContactsChanged(\n thread: Thread,\n changes: {\n added: Array<{ contact: Contact; role: string | null }>;\n removed: Array<{ contact: Contact; role: string | null }>;\n changed: Array<{ contact: Contact; from: string | null; to: string | null }>;\n },\n ): Promise<void> {\n return Promise.resolve();\n }\n /* eslint-enable @typescript-eslint/no-unused-vars */\n\n /**\n * Called when a user marks or unmarks a thread as todo.\n * Override to sync todo status to the external service\n * (e.g., starring an email in Gmail when marked as todo).\n *\n * @param thread - The thread (includes thread.meta with connector-specific data)\n * @param actor - The user who changed the todo status\n * @param todo - true when marked as todo, false when done or removed\n * @param options - Additional context\n * @param options.date - The todo date (when todo=true)\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onThreadToDo(thread: Thread, actor: Actor, todo: boolean, options: { date?: Date }): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a schedule contact's RSVP status changes on a thread owned by this connector.\n * Override to sync RSVP changes back to the external calendar.\n *\n * @param thread - The thread (includes thread.meta with connector-specific data)\n * @param scheduleId - The schedule ID\n * @param contactId - The contact whose status changed\n * @param status - The new RSVP status ('attend', 'skip', or null)\n * @param actor - The user who changed the status\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onScheduleContactUpdated(thread: Thread, scheduleId: string, contactId: ActorId, status: ScheduleContactStatus | null, actor: Actor): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user adds or removes a single emoji reaction on a note\n * (one event per `(note, actor, emoji)` state transition).\n *\n * Dispatch is routed to the reacting user's own connector instance via\n * `twist_instance_for_actor` on `note_reaction.actor_id`, so this method\n * already runs under the reactor's auth. Fetch the API client with the\n * connector's normal token-fetch path (`this.tools.integrations.get(...)`)\n * and the external write \u2014 e.g. Slack `reactions.add` \u2014 will be attributed\n * to the correct user. No `actAs` step required.\n *\n * If the reacting user has no connection of this type, no dispatch fires\n * for that reaction (it stays in Plot only).\n *\n * Override to sync per-actor reactions back to the external system.\n *\n * @param note - The note that was reacted on (partial; `id`, `key`, `content` populated)\n * @param thread - The thread the note belongs to (partial; `id`, `title`, `archived`, `meta` populated)\n * @param actor - The contact who added/removed the reaction\n * @param emoji - The emoji (Unicode grapheme or `provider:workspace/name` custom-emoji ref)\n * @param added - `true` if the reaction is now present, `false` if it was removed\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onNoteReactionChanged(note: Note, thread: Thread, actor: Actor, emoji: string, added: boolean): Promise<void> {\n return Promise.resolve();\n }\n\n // ---- Activation ----\n\n /**\n * Called when the connector is activated after OAuth is complete.\n *\n * Connectors receive the authorization in addition to the activating actor.\n * When this runs, `this.userId` is already populated with the installing\n * user's ID.\n *\n * Default implementation does nothing. Override for custom setup.\n *\n * @param context - The activation context\n * @param context.auth - The completed OAuth authorization\n * @param context.actor - The actor who activated the connector\n */\n // @ts-ignore - Connector.activate() has a Connector-specific context type.\n activate(context: { auth?: Authorization; actor?: Actor }): Promise<void> {\n return Promise.resolve();\n }\n}\n\n/** @deprecated Use `Connector` instead. */\nexport { Connector as Source };\n";
|
|
8
8
|
export default _default;
|
|
9
9
|
//# sourceMappingURL=connector.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../src/llm-docs/connector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,
|
|
1
|
+
{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../src/llm-docs/connector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,2wjCAAmkjC;AAAlljC,wBAAmljC"}
|
|
@@ -4,5 +4,5 @@
|
|
|
4
4
|
* This file is auto-generated during build. Do not edit manually.
|
|
5
5
|
* Generated from: prebuild.ts
|
|
6
6
|
*/
|
|
7
|
-
export default "import { type Actor, type ActorId, type Contact, type DeliveryError, type Link, type NewLinkWithNotes, type Note, type Thread, type Uuid } from \"./plot\";\nimport type { ScheduleContactStatus } from \"./schedule\";\nimport {\n type AuthProvider,\n type AuthToken,\n type Authorization,\n type Channel,\n type LinkTypeConfig,\n type SyncContext,\n} from \"./tools/integrations\";\nimport { Twist } from \"./twist\";\n\n/**\n * Declares how a connector's platform handles emoji reactions.\n *\n * Drives Plot UI behavior (e.g. the picker filters the available\n * reactions on notes whose primary connector declares `fixed`) and\n * outbound dispatch (Plot won't try to push an emoji the platform\n * can't accept).\n *\n * Variants:\n * - `open-unicode`: Platform accepts any Unicode emoji. `customEmoji`\n * indicates whether the platform additionally supports workspace\n * custom emoji (Slack, Google Chat).\n * - `unicode-subset`: Platform accepts Unicode but only a finite set.\n * `subset` lists the allowed emoji (omit for \"currently full Unicode\n * per docs, future-proofed for shrinkage\").\n * - `fixed`: Platform only accepts a fixed set (e.g. LinkedIn\n * Messaging's 7-reaction set). `allowed` lists every supported emoji.\n */\nexport type ReactionCapabilities =\n | { mode: \"open-unicode\"; customEmoji?: \"workspace\" | \"none\" }\n | { mode: \"unicode-subset\"; subset?: readonly string[] }\n | { mode: \"fixed\"; allowed: readonly string[] };\n\n/**\n * Result returned from {@link Connector.onNoteCreated} and\n * {@link Connector.onNoteUpdated} to report what the external system now\n * has stored for the note.\n *\n * The runtime hashes `externalContent` and stores it as the note's sync\n * baseline. On the next sync-in, if the incoming content hashes to the\n * same value, the runtime knows the external side hasn't changed and\n * preserves Plot's (possibly formatted) content. When the external side\n * is edited, the hash diverges and the runtime overwrites Plot's content\n * with the new external version.\n *\n * Omitting `externalContent` skips baseline tracking — the next sync-in\n * will overwrite Plot's content (previous behavior). Always provide it\n * when the write-back's return value reflects what the external system\n * actually stored (often lossy plain-text), so the round-trip does not\n * clobber the original Plot markdown.\n *\n * The hash covers only the content string — the runtime intentionally\n * does not include a content-type in the hash, so write-back and sync-in\n * do not have to agree on a content-type label for the same underlying\n * bytes. Return exactly the string your connector's sync-in path will\n * emit as `NewNote.content` for this note on the next re-ingest.\n *\n * For back-compat, `onNoteCreated` may also return a plain string, which\n * is treated as `{ key }` with no baseline.\n */\nexport type NoteWriteBackResult = {\n /**\n * External system identifier assigned to this note. Set as the note's\n * `key` for future upsert matching. Required when the runtime does not\n * already know the key (i.e., from `onNoteCreated`); ignored from\n * `onNoteUpdated` when the key was already established on create.\n */\n key?: string;\n /**\n * The content string as the external system now stores it, post-write.\n * For systems whose write-back returns a representation of what was\n * actually stored (e.g. Google Drive comment `content` after a create),\n * pass that verbatim. For systems that only accept plain text, this\n * will often be a lossy plain-text version of the Plot markdown — that\n * is exactly the point: storing the lossy form as baseline lets the\n * next sync-in recognize it and skip overwriting the richer Plot\n * version.\n *\n * Must exactly match the string your connector's sync-in path emits as\n * `NewNote.content` for this note on re-ingest.\n */\n externalContent?: string;\n /**\n * Reports that the outbound send / write-back for this note FAILED and\n * could not be recovered (after the connector's own retries). The runtime\n * records it on the note — surfacing a \"Failed to send\" affordance (Retry /\n * Discard) to the user — and marks the thread unread.\n *\n * - object → record the failure.\n * - `null` → clear a previously-recorded failure (e.g. a successful retry).\n * - omitted (`undefined`) → leave any existing delivery state untouched.\n *\n * A successful write-back (any result without a `deliveryError`) also clears\n * a previously-recorded failure, so connectors usually only need to SET this\n * on failure.\n *\n * Prefer RETURNING this over throwing for expected, user-visible failures\n * (rejected recipient, message too large, quota exhausted): a thrown error\n * pages error tracking, whereas a returned `deliveryError` does not. Reserve\n * throwing for genuinely unexpected errors. Connectors that simply throw on a\n * failed write-back still get a generic \"Failed to send\" surfaced by the\n * runtime, just without a specific reason.\n */\n deliveryError?: DeliveryError | null;\n};\n\n/**\n * A Plot contact pre-resolved to its platform account ID, ready for use\n * in a messaging dispatch.\n *\n * Populated by the runtime for link types with `compose.targets: \"contacts\"` before\n * `onCreateLink` is called. The connector should use `externalAccountId`\n * directly to address the recipient on the platform (e.g. Slack user ID,\n * LinkedIn URN, Gmail address) without performing its own contact lookup.\n */\nexport type ResolvedRecipient = {\n /** Plot contact UUID */\n id: Uuid;\n /** Display name, or null if not set */\n name: string | null;\n /** Platform-specific account identifier pre-resolved at dispatch time (e.g. Slack `U…`, LinkedIn URN, Gmail email address) */\n externalAccountId: string;\n /**\n * The contact's role on the originating thread, resolved from\n * `thread.contact_meta` against the link type's `contactRoles` (e.g.\n * `\"to\"` / `\"cc\"` / `\"bcc\"` for Gmail). `null` when the contact had no\n * explicit role entry — connectors should treat `null` as the link\n * type's default role (the `contactRoles` entry marked `default: true`).\n *\n * Connectors that distinguish roles MUST honor this when addressing the\n * recipient — e.g. Gmail must place `\"cc\"`/`\"bcc\"` recipients in the\n * Cc/Bcc headers, never the To header, so BCC recipients are not\n * exposed to the other recipients. Connectors that don't distinguish\n * roles (Slack, Linear) can ignore it.\n */\n role: string | null;\n};\n\n/**\n * Fields captured in Plot when a user initiates creation of a new external\n * item via a connector's `onCreateLink` hook.\n *\n * Thread-agnostic on purpose — connectors do not receive the Plot thread.\n * The platform attaches the returned `NewLinkWithNotes` to the originating\n * thread once `onCreateLink` resolves.\n */\nexport type CreateLinkDraft = {\n /** The channel (account + resource) the new item belongs to. */\n channelId: string;\n /** Link type identifier, matches a `LinkTypeConfig.type`. */\n type: string;\n /**\n * Status the user selected. Matches a `statuses[].status` for `type`,\n * or null for status-less link types (the parent linkType declares no\n * `statuses` and no `compose.status`).\n */\n status: string | null;\n /** Title of the originating Plot thread (post AI title generation). */\n title: string;\n /** Markdown content of the thread's first note, or null if none. */\n noteContent: string | null;\n /**\n * Contacts attached to the originating Plot thread, excluding the\n * creating user. Use these as recipients (email, chat DM members, etc.)\n * when the external item is a message or invite. An empty list means\n * the user did not add anyone to the thread.\n *\n * For link types with `compose.targets: \"contacts\"`, prefer `recipients` over\n * re-resolving contacts yourself: the runtime pre-resolves each contact\n * to its platform account ID (`externalAccountId`) and populates\n * `recipients` before `onCreateLink` is called.\n */\n contacts: Actor[];\n /**\n * Pre-resolved recipients for link types whose `compose.targets` is\n * `\"contacts\"` or `\"addresses\"`.\n *\n * Only populated for those link types; otherwise undefined. Each entry contains the Plot\n * contact UUID, the platform-specific account ID\n * (`externalAccountId`) the connector should use to address the\n * recipient without performing its own lookup, and the contact's\n * `role` on the thread (e.g. `\"to\"` / `\"cc\"` / `\"bcc\"`) resolved from\n * `thread.contact_meta`. For `\"addresses\"` link types, contacts without\n * a connection-scoped row fall back to `contact.email`.\n */\n recipients?: ResolvedRecipient[];\n /**\n * Free-form addresses the user typed into the picker (no Plot contact\n * row). Only populated for link types with `compose.targets: \"addresses\"`; otherwise\n * undefined. Connectors should append these alongside `recipients`\n * when constructing the recipient list (e.g. `To:` header for Gmail).\n */\n inviteEmails?: string[];\n};\n\n/** An optional OAuth scope group the user can toggle at connect time. */\nexport type OptionalScopeGroup = {\n /** Stable id used to track the user's selection. */\n id: string;\n /** Value-forward switch label, e.g. \"Add names to events using contacts\". */\n label: string;\n /** Optional secondary line shown under the label. */\n description?: string;\n /** The OAuth scope strings this group grants. */\n scopes: string[];\n /** Whether the group is requested by default (switch on). */\n default: boolean;\n};\n\n/**\n * Structured scope declaration. `required` scopes must be granted — auth fails\n * and re-prompts if any is declined. `optional` groups are requested by default\n * but auth still succeeds if the user declines them; the connector should detect\n * the absence via the granted `token.scopes` and degrade gracefully.\n */\nexport type ScopeConfig = {\n required: string[];\n optional?: OptionalScopeGroup[];\n};\n\n/**\n * Base class for connectors — twists that sync data from external services.\n *\n * Connectors declare a single OAuth provider and scopes, and implement channel\n * lifecycle methods for discovering and syncing external resources. They save\n * data directly via `integrations.saveLink()` instead of using the Plot tool.\n *\n * @example\n * ```typescript\n * class LinearConnector extends Connector<LinearConnector> {\n * readonly provider = AuthProvider.Linear;\n * readonly scopes = [\"read\", \"write\"];\n * readonly linkTypes = [{\n * type: \"issue\",\n * label: \"Issue\",\n * statuses: [\n * { status: \"open\", label: \"Open\", icon: \"todo\" },\n * { status: \"done\", label: \"Done\", icon: \"done\", done: true },\n * ],\n * }];\n *\n * build(build: ToolBuilder) {\n * return {\n * integrations: build(Integrations),\n * };\n * }\n *\n * async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n * const teams = await this.listTeams(token);\n * return teams.map(t => ({ id: t.id, title: t.name }));\n * }\n *\n * async onChannelEnabled(channel: Channel) {\n * const issues = await this.fetchIssues(channel.id);\n * for (const issue of issues) {\n * await this.tools.integrations.saveLink(issue);\n * }\n * }\n *\n * async onChannelDisabled(channel: Channel) {\n * // Clean up webhooks, sync state, etc.\n * }\n * }\n * ```\n */\nexport abstract class Connector<TSelf> extends Twist<TSelf> {\n /**\n * Static marker to identify Connector subclasses without instanceof checks\n * across worker boundaries.\n */\n static readonly isConnector = true;\n\n // ---- Identity (abstract — every connector must declare) ----\n\n /** The OAuth provider this connector authenticates with. */\n readonly provider?: AuthProvider;\n\n /** OAuth scopes to request for this connector — a flat list (all required), or\n * a {@link ScopeConfig} declaring required + optional scope groups. */\n readonly scopes?: string[] | ScopeConfig;\n\n /**\n * Plain-language bullets describing what access connecting this service\n * grants the user — shown on the connect screen regardless of auth mechanism\n * (OAuth, API key, or hosted). For OAuth connectors it also previews what the\n * provider's consent screen will request. These are justifications for what\n * Plot accesses, not a one-to-one mapping of scope strings.\n */\n readonly access?: string[];\n\n // ---- Auth model ----\n\n /**\n * When true, one credential is shared across all users in the workspace,\n * entered once by the installer. When false (default), each user provides\n * their own credential.\n *\n * Applies to both OAuth and key-based connectors:\n * - Shared OAuth: e.g. Slack bot token (workspace-level)\n * - Shared key: e.g. Attio workspace API key\n * - Individual OAuth: e.g. Google Calendar (per-user)\n * - Individual key: e.g. Fellow (per-user API key)\n */\n readonly shared?: boolean;\n\n /**\n * The Options field name that contains the authentication key (e.g. \"apiKey\").\n * Must reference a `secure: true` field in the Options schema.\n *\n * When set, this connector uses key-based auth instead of OAuth.\n * For individual connectors (`shared` is false), this field is stored\n * per-user rather than in shared config.\n */\n readonly keyOption?: string;\n\n // ---- Optional metadata ----\n\n /**\n * When true, this connector has a single implicit channel.\n * `getChannels()` must return exactly one Channel.\n * The UI will show channel config inline instead of a channel list.\n */\n readonly singleChannel?: boolean;\n\n /**\n * The user-facing noun for this connector's channels — what each\n * {@link Channel} returned by {@link getChannels} actually represents in the\n * external service. Many connectors map \"channels\" onto a domain concept\n * (folders, projects, calendars, labels, spaces, repositories, …), so the\n * generic word \"channel\" reads as jargon. Set this and the UI substitutes it\n * everywhere it would otherwise say \"channel(s)\" — e.g. the per-connection\n * toggle becomes \"Sync new folders\" / \"When a new folder is added, …\".\n *\n * Provide lowercase nouns (the UI capitalizes where needed):\n * `{ singular: \"folder\", plural: \"folders\" }`. Defaults to\n * `{ singular: \"channel\", plural: \"channels\" }` when omitted.\n */\n readonly channelNoun?: { singular: string; plural: string };\n\n /**\n * Whether the per-connection \"Sync new channels\" preference starts ON for\n * newly added connections of this connector. Defaults to `false` (opt-in).\n *\n * Set `true` for connectors that select **all** of their channels by default\n * (i.e. {@link getChannels} returns no channels marked\n * `enabledByDefault: false`). If syncing every channel is the intended\n * default, then channels discovered later should also sync automatically.\n * Leave `false`/omitted for selective connectors that exclude some channels\n * by default (e.g. Gmail syncs only Inbox/Sent, Google Calendar only\n * owner calendars) — for those, a newly discovered channel is just as\n * uncertain and should wait for the user to opt in.\n *\n * Only affects the **default** for new connections; the user's explicit\n * toggle always wins, and existing connections keep their stored preference.\n */\n readonly autoEnableNewChannelsByDefault?: boolean;\n\n /**\n * Whether this connector supports the platform's sequential auto-threading —\n * folding a conversation that arrives as a run of separate top-level messages\n * into a single thread. Set `true` for conversational connectors (chat,\n * messaging) that mark eligible links with {@link NewLink.autoThread}. The UI\n * shows a per-connection \"Group related messages into conversations\" toggle\n * only for connectors that declare this.\n *\n * Leave undefined/false for connectors whose items are not conversational\n * (calendars, issue trackers, file storage) — marking a link does nothing\n * unless the connection both declares support and the user opted in.\n */\n readonly autoThreading?: boolean;\n\n /**\n * Whether the per-connection auto-threading preference starts ON for newly\n * added connections of this connector. Defaults to `false` (opt-in) — the\n * least-surprise default, since a wrong fold is irreversible. Only meaningful\n * when {@link autoThreading} is `true`. The user's explicit toggle always\n * wins, and existing connections keep their stored preference.\n */\n readonly autoThreadingByDefault?: boolean;\n\n /**\n * Registry of link types this connector creates (e.g., issue, event, message).\n * Used for display in the UI (icons, labels, statuses).\n */\n readonly linkTypes?: LinkTypeConfig[];\n\n /**\n * Declares how this connector's platform handles emoji reactions.\n * Used to filter the reaction picker for notes whose primary connector\n * is this one, and to guard outbound dispatch from sending emoji the\n * platform can't accept.\n *\n * Leave undefined for connectors whose platform has no concept of\n * reactions (calendar, file storage, issue trackers without reactions).\n */\n readonly reactionCapabilities?: ReactionCapabilities;\n\n /**\n * When true, this connector is mentioned by default on replies to threads it created.\n * When false (default), this connector cannot be mentioned at all.\n *\n * Set this to true for connectors with bidirectional sync (e.g., issue trackers,\n * messaging) where user replies should be written back to the external service.\n */\n static readonly handleReplies?: boolean;\n\n // ---- Account identity (abstract — every connector must implement) ----\n\n /**\n * Returns a human-readable name for the connected account.\n * Shown in the connections list and edit modal to identify this connection.\n *\n * For OAuth connectors, this is typically the workspace or organization name\n * (e.g., \"Acme Corp\" for a Linear workspace). For API key connectors, this\n * could be the workspace name from the external service.\n *\n * Override this in your connector to return a meaningful account name.\n *\n * @param auth - The authorization (null for no-provider connectors)\n * @param token - The access token (null for no-provider connectors)\n * @returns Promise resolving to the account display name\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n getAccountName(\n auth: Authorization | null,\n token: AuthToken | null\n ): Promise<string | null> {\n return Promise.resolve(null);\n }\n\n // ---- Channel lifecycle (abstract — every connector must implement) ----\n\n /**\n * Returns available channels for the authorized actor.\n * Called after OAuth is complete, during the setup/edit modal.\n *\n * @param auth - The completed authorization with provider and actor info\n * @param token - The access token for making API calls\n * @returns Promise resolving to available channels for the user to select\n */\n abstract getChannels(\n auth: Authorization | null,\n token: AuthToken | null\n ): Promise<Channel[]>;\n\n /**\n * Called when a channel resource is enabled for syncing.\n *\n * The framework dispatches this in three cases:\n * 1. **Initial enable** — user toggled the channel on for the first time.\n * 2. **Auto-enable** — `setChannels` discovered a new channel on a\n * connection with `auto_enable_new_channels` set.\n * 3. **Recovery after re-auth** — the user re-authorized a previously-\n * broken connection. The framework calls `onChannelEnabled` for every\n * channel that was already enabled at the time of re-auth, with\n * `context.recovering = true`. See {@link SyncContext.recovering}.\n *\n * Implementations should be **idempotent and overwrite stored state**:\n * the same channel may receive multiple `onChannelEnabled` calls across\n * its lifetime. Use unconditional `this.set()` writes rather than\n * coalesce/skip-if-present logic so a recovery dispatch wipes stale\n * cursors and state from the prior session.\n *\n * **Sync state tracking is automatic.** The framework stamps the\n * connection as \"syncing\" when it dispatches this method and clears\n * that state when:\n * - the connector calls `tools.integrations.channelSyncCompleted(id)`\n * once the initial backfill is done, OR\n * - this method throws an unhandled exception (auto-cleared so the UI\n * doesn't get stuck in \"syncing\" forever).\n *\n * **IMPORTANT: This method runs inline in the HTTP request handler.**\n * Any long-running work (webhook setup, API calls, sync) MUST be queued\n * as a separate task via `this.runTask()`, not executed inline. Blocking\n * here causes the client to spin waiting for the response.\n *\n * Only lightweight operations should appear directly in this method:\n * `this.set()`, `this.get()`, `this.callback()`, and `this.runTask()`.\n *\n * @example\n * ```typescript\n * async onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void> {\n * // Recovery: drop stale cursors so the next sync re-walks history.\n * if (context?.recovering) {\n * await this.clear(`last_sync_token_${channel.id}`);\n * }\n *\n * await this.set(`sync_state_${channel.id}`, { channelId: channel.id });\n *\n * // Queue sync as a task — do NOT use this.run() or call sync methods inline\n * const syncCallback = await this.callback(this.syncBatch, 1, \"full\", channel.id, true);\n * await this.runTask(syncCallback);\n *\n * // Queue webhook setup as a task — do NOT call setupWebhook() inline\n * const webhookCallback = await this.callback(this.setupWebhook, channel.id);\n * await this.runTask(webhookCallback);\n * }\n * ```\n *\n * @param channel - The channel that was enabled\n * @param context - Optional sync context (plan-based hints, recovery flag)\n */\n abstract onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void>;\n\n /**\n * Called when a channel resource is disabled.\n * Should stop sync, clean up webhooks, and remove state.\n *\n * @param channel - The channel that was disabled\n */\n abstract onChannelDisabled(channel: Channel): Promise<void>;\n\n // ---- Write-back hooks (optional, default no-ops) ----\n\n /**\n * Called when a link created by this connector is updated by the user.\n * Override to write back changes to the external service\n * (e.g., changing issue status in Linear when marked done in Plot).\n *\n * @param link - The updated link\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onLinkUpdated(link: Link): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user creates a thread in Plot that should create a new\n * item in this connector's external system.\n *\n * A connector opts in to Plot-initiated creation by declaring a\n * `compose` block on the relevant `LinkTypeConfig` (see\n * {@link ComposeConfig}). When a user picks \"Create new <type>\" from the\n * Add link modal and the thread is synced, the runtime calls this method\n * with the draft fields.\n *\n * Implementations should create the item in the external service and\n * return a `NewLinkWithNotes` describing the created item. The platform\n * attaches the returned link to the originating thread — do not call\n * `integrations.saveLink` yourself.\n *\n * Returning `null` aborts creation silently (the thread is still saved\n * without a link).\n *\n * @param draft - The fields captured in Plot for the new item.\n * @returns The link to attach, or null to abort creation.\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onCreateLink(draft: CreateLinkDraft): Promise<NewLinkWithNotes | null> {\n return Promise.resolve(null);\n }\n\n /**\n * Called when a note is created on a thread owned by this connector.\n * Override to write back comments to the external service\n * (e.g., adding a comment to a Linear issue).\n *\n * Returning a string or {@link NoteWriteBackResult} links the Plot note\n * to its external counterpart. A plain string sets the note's `key`.\n * A `NoteWriteBackResult` additionally sets a sync baseline (via\n * `externalContent`) so the next sync-in can recognize the round-tripped\n * content and preserve Plot's formatted version. See\n * {@link NoteWriteBackResult} for details.\n *\n * @param note - The created note\n * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n * @returns Optional note key or NoteWriteBackResult for external dedup + baseline tracking\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onNoteCreated(note: Note, thread: Thread): Promise<string | NoteWriteBackResult | void> {\n return Promise.resolve();\n }\n\n /**\n * Resolve a `fileRef` action's bytes for download. Called when a user opens\n * an attachment in Plot. Return either a redirect URL (preferred for sources\n * that issue signed URLs, like Linear S3 or Slack permalink_public) or a\n * streamed body (required when bytes are only reachable through an\n * authenticated API call, like Gmail attachments.get).\n *\n * @param ref Opaque value the connector previously emitted on a fileRef action.\n * @returns Either `{ redirectUrl }` or `{ body, mimeType, fileName? }`.\n * @throws If the source is unavailable, the connection is broken, or `ref` is invalid.\n *\n * If not overridden, fileRef actions on this connector's notes will return 410 Gone.\n */\n async downloadAttachment(\n ref: string,\n ): Promise<\n | { redirectUrl: string }\n | { body: ReadableStream | Uint8Array; mimeType: string; fileName?: string }\n > {\n throw new Error(\n `downloadAttachment not implemented for ${this.constructor.name} (ref=${ref})`,\n );\n }\n\n /**\n * Called when a note on a thread owned by this connector is updated.\n * Override to write back changes to the external service\n * (e.g., syncing reaction tags as emoji reactions, or editing a comment\n * whose content changed in Plot).\n *\n * Return a {@link NoteWriteBackResult} with `externalContent` to update\n * the sync baseline after a successful write-back, so the next sync-in\n * recognizes the external version as already-seen and preserves Plot's\n * content.\n *\n * @param note - The updated note (includes current tags)\n * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n * @returns Optional NoteWriteBackResult for baseline tracking\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onNoteUpdated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user reads or unreads a thread owned by this connector.\n * Override to write back read status to the external service\n * (e.g., marking an email as read in Gmail).\n *\n * @param thread - The thread that was read/unread (includes thread.meta with connector-specific data)\n * @param actor - The user who performed the action\n * @param unread - false when marked as read, true when marked as unread\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onThreadRead(thread: Thread, actor: Actor, unread: boolean): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user changes the **thread-level sharing** of a thread owned\n * by this connector — adding or removing a contact, or (for connectors with\n * roles) changing a contact's role. Override on connectors whose external\n * source can reflect that membership change, e.g. a group DM / multi-party\n * chat (`LinkTypeConfig.sharingModel: \"thread\"`) or an email's To/Cc/Bcc\n * recipients (`sharingModel: \"message\"`). Connectors backed by an immutable\n * roster (most group DMs today) or by channel-level membership\n * (`sharingModel: \"channel\"`) leave this as the default no-op.\n *\n * `role`/`from`/`to` are **null** for connectors without roles (group DMs\n * have no roles); they carry a `contactRoles` id only for connectors that\n * declare roles (e.g. email `to`/`cc`/`bcc`).\n *\n * The dispatch fires after Plot has persisted the change. A connector may\n * reflect it actively (e.g. add/remove a participant on the external chat)\n * or passively on the next outbound note (e.g. building To/Cc/Bcc headers\n * from the current `thread.contacts` × `thread.contactMeta`) — this callback\n * is not the right place to send a standalone notification.\n *\n * @param thread - The thread whose contacts changed\n * @param changes - The added/removed contacts and any role transitions on existing contacts\n */\n /* eslint-disable @typescript-eslint/no-unused-vars */\n onContactsChanged(\n thread: Thread,\n changes: {\n added: Array<{ contact: Contact; role: string | null }>;\n removed: Array<{ contact: Contact; role: string | null }>;\n changed: Array<{ contact: Contact; from: string | null; to: string | null }>;\n },\n ): Promise<void> {\n return Promise.resolve();\n }\n /* eslint-enable @typescript-eslint/no-unused-vars */\n\n /**\n * Called when a user marks or unmarks a thread as todo.\n * Override to sync todo status to the external service\n * (e.g., starring an email in Gmail when marked as todo).\n *\n * @param thread - The thread (includes thread.meta with connector-specific data)\n * @param actor - The user who changed the todo status\n * @param todo - true when marked as todo, false when done or removed\n * @param options - Additional context\n * @param options.date - The todo date (when todo=true)\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onThreadToDo(thread: Thread, actor: Actor, todo: boolean, options: { date?: Date }): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a schedule contact's RSVP status changes on a thread owned by this connector.\n * Override to sync RSVP changes back to the external calendar.\n *\n * @param thread - The thread (includes thread.meta with connector-specific data)\n * @param scheduleId - The schedule ID\n * @param contactId - The contact whose status changed\n * @param status - The new RSVP status ('attend', 'skip', or null)\n * @param actor - The user who changed the status\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onScheduleContactUpdated(thread: Thread, scheduleId: string, contactId: ActorId, status: ScheduleContactStatus | null, actor: Actor): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user adds or removes a single emoji reaction on a note\n * (one event per `(note, actor, emoji)` state transition).\n *\n * Dispatch is routed to the reacting user's own connector instance via\n * `twist_instance_for_actor` on `note_reaction.actor_id`, so this method\n * already runs under the reactor's auth. Fetch the API client with the\n * connector's normal token-fetch path (`this.tools.integrations.get(...)`)\n * and the external write — e.g. Slack `reactions.add` — will be attributed\n * to the correct user. No `actAs` step required.\n *\n * If the reacting user has no connection of this type, no dispatch fires\n * for that reaction (it stays in Plot only).\n *\n * Override to sync per-actor reactions back to the external system.\n *\n * @param note - The note that was reacted on (partial; `id`, `key`, `content` populated)\n * @param thread - The thread the note belongs to (partial; `id`, `title`, `archived`, `meta` populated)\n * @param actor - The contact who added/removed the reaction\n * @param emoji - The emoji (Unicode grapheme or `provider:workspace/name` custom-emoji ref)\n * @param added - `true` if the reaction is now present, `false` if it was removed\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onNoteReactionChanged(note: Note, thread: Thread, actor: Actor, emoji: string, added: boolean): Promise<void> {\n return Promise.resolve();\n }\n\n // ---- Activation ----\n\n /**\n * Called when the connector is activated after OAuth is complete.\n *\n * Connectors receive the authorization in addition to the activating actor.\n * When this runs, `this.userId` is already populated with the installing\n * user's ID.\n *\n * Default implementation does nothing. Override for custom setup.\n *\n * @param context - The activation context\n * @param context.auth - The completed OAuth authorization\n * @param context.actor - The actor who activated the connector\n */\n // @ts-ignore - Connector.activate() has a Connector-specific context type.\n activate(context: { auth?: Authorization; actor?: Actor }): Promise<void> {\n return Promise.resolve();\n }\n}\n\n/** @deprecated Use `Connector` instead. */\nexport { Connector as Source };\n";
|
|
7
|
+
export default "import { type Actor, type ActorId, type Contact, type DeliveryError, type Link, type NewLinkWithNotes, type Note, type Thread, type Uuid } from \"./plot\";\nimport type { ScheduleContactStatus } from \"./schedule\";\nimport {\n type AuthProvider,\n type AuthToken,\n type Authorization,\n type Channel,\n type LinkTypeConfig,\n type SyncContext,\n} from \"./tools/integrations\";\nimport { Twist } from \"./twist\";\n\n/**\n * Declares how a connector's platform handles emoji reactions.\n *\n * Drives Plot UI behavior (e.g. the picker filters the available\n * reactions on notes whose primary connector declares `fixed`) and\n * outbound dispatch (Plot won't try to push an emoji the platform\n * can't accept).\n *\n * Variants:\n * - `open-unicode`: Platform accepts any Unicode emoji. `customEmoji`\n * indicates whether the platform additionally supports workspace\n * custom emoji (Slack, Google Chat).\n * - `unicode-subset`: Platform accepts Unicode but only a finite set.\n * `subset` lists the allowed emoji (omit for \"currently full Unicode\n * per docs, future-proofed for shrinkage\").\n * - `fixed`: Platform only accepts a fixed set (e.g. LinkedIn\n * Messaging's 7-reaction set). `allowed` lists every supported emoji.\n */\nexport type ReactionCapabilities =\n | { mode: \"open-unicode\"; customEmoji?: \"workspace\" | \"none\" }\n | { mode: \"unicode-subset\"; subset?: readonly string[] }\n | { mode: \"fixed\"; allowed: readonly string[] };\n\n/**\n * Result returned from {@link Connector.onNoteCreated} and\n * {@link Connector.onNoteUpdated} to report what the external system now\n * has stored for the note.\n *\n * The runtime hashes `externalContent` and stores it as the note's sync\n * baseline. On the next sync-in, if the incoming content hashes to the\n * same value, the runtime knows the external side hasn't changed and\n * preserves Plot's (possibly formatted) content. When the external side\n * is edited, the hash diverges and the runtime overwrites Plot's content\n * with the new external version.\n *\n * Omitting `externalContent` skips baseline tracking — the next sync-in\n * will overwrite Plot's content (previous behavior). Always provide it\n * when the write-back's return value reflects what the external system\n * actually stored (often lossy plain-text), so the round-trip does not\n * clobber the original Plot markdown.\n *\n * The hash covers only the content string — the runtime intentionally\n * does not include a content-type in the hash, so write-back and sync-in\n * do not have to agree on a content-type label for the same underlying\n * bytes. Return exactly the string your connector's sync-in path will\n * emit as `NewNote.content` for this note on the next re-ingest.\n *\n * For back-compat, `onNoteCreated` may also return a plain string, which\n * is treated as `{ key }` with no baseline.\n */\nexport type NoteWriteBackResult = {\n /**\n * External system identifier assigned to this note. Set as the note's\n * `key` for future upsert matching. Required when the runtime does not\n * already know the key (i.e., from `onNoteCreated`); ignored from\n * `onNoteUpdated` when the key was already established on create.\n */\n key?: string;\n /**\n * The content string as the external system now stores it, post-write.\n * For systems whose write-back returns a representation of what was\n * actually stored (e.g. Google Drive comment `content` after a create),\n * pass that verbatim. For systems that only accept plain text, this\n * will often be a lossy plain-text version of the Plot markdown — that\n * is exactly the point: storing the lossy form as baseline lets the\n * next sync-in recognize it and skip overwriting the richer Plot\n * version.\n *\n * Must exactly match the string your connector's sync-in path emits as\n * `NewNote.content` for this note on re-ingest.\n */\n externalContent?: string;\n /**\n * Reports that the outbound send / write-back for this note FAILED and\n * could not be recovered (after the connector's own retries). The runtime\n * records it on the note — surfacing a \"Failed to send\" affordance (Retry /\n * Discard) to the user — and marks the thread unread.\n *\n * - object → record the failure.\n * - `null` → clear a previously-recorded failure (e.g. a successful retry).\n * - omitted (`undefined`) → leave any existing delivery state untouched.\n *\n * A successful write-back (any result without a `deliveryError`) also clears\n * a previously-recorded failure, so connectors usually only need to SET this\n * on failure.\n *\n * Prefer RETURNING this over throwing for expected, user-visible failures\n * (rejected recipient, message too large, quota exhausted): a thrown error\n * pages error tracking, whereas a returned `deliveryError` does not. Reserve\n * throwing for genuinely unexpected errors. Connectors that simply throw on a\n * failed write-back still get a generic \"Failed to send\" surfaced by the\n * runtime, just without a specific reason.\n */\n deliveryError?: DeliveryError | null;\n};\n\n/**\n * A Plot contact pre-resolved to its platform account ID, ready for use\n * in a messaging dispatch.\n *\n * Populated by the runtime for link types with `compose.targets: \"contacts\"` before\n * `onCreateLink` is called. The connector should use `externalAccountId`\n * directly to address the recipient on the platform (e.g. Slack user ID,\n * LinkedIn URN, Gmail address) without performing its own contact lookup.\n */\nexport type ResolvedRecipient = {\n /** Plot contact UUID */\n id: Uuid;\n /** Display name, or null if not set */\n name: string | null;\n /** Platform-specific account identifier pre-resolved at dispatch time (e.g. Slack `U…`, LinkedIn URN, Gmail email address) */\n externalAccountId: string;\n /**\n * The contact's role on the originating thread, resolved from\n * `thread.contact_meta` against the link type's `contactRoles` (e.g.\n * `\"to\"` / `\"cc\"` / `\"bcc\"` for Gmail). `null` when the contact had no\n * explicit role entry — connectors should treat `null` as the link\n * type's default role (the `contactRoles` entry marked `default: true`).\n *\n * Connectors that distinguish roles MUST honor this when addressing the\n * recipient — e.g. Gmail must place `\"cc\"`/`\"bcc\"` recipients in the\n * Cc/Bcc headers, never the To header, so BCC recipients are not\n * exposed to the other recipients. Connectors that don't distinguish\n * roles (Slack, Linear) can ignore it.\n */\n role: string | null;\n};\n\n/**\n * Fields captured in Plot when a user initiates creation of a new external\n * item via a connector's `onCreateLink` hook.\n *\n * Thread-agnostic on purpose — connectors do not receive the Plot thread.\n * The platform attaches the returned `NewLinkWithNotes` to the originating\n * thread once `onCreateLink` resolves.\n */\nexport type CreateLinkDraft = {\n /** The channel (account + resource) the new item belongs to. */\n channelId: string;\n /** Link type identifier, matches a `LinkTypeConfig.type`. */\n type: string;\n /**\n * Status the user selected. Matches a `statuses[].status` for `type`,\n * or null for status-less link types (the parent linkType declares no\n * `statuses` and no `compose.status`).\n */\n status: string | null;\n /** Title of the originating Plot thread (post AI title generation). */\n title: string;\n /** Markdown content of the thread's first note, or null if none. */\n noteContent: string | null;\n /**\n * Contacts attached to the originating Plot thread, excluding the\n * creating user. Use these as recipients (email, chat DM members, etc.)\n * when the external item is a message or invite. An empty list means\n * the user did not add anyone to the thread.\n *\n * For link types with `compose.targets: \"contacts\"`, prefer `recipients` over\n * re-resolving contacts yourself: the runtime pre-resolves each contact\n * to its platform account ID (`externalAccountId`) and populates\n * `recipients` before `onCreateLink` is called.\n */\n contacts: Actor[];\n /**\n * Pre-resolved recipients for link types whose `compose.targets` is\n * `\"contacts\"` or `\"addresses\"`.\n *\n * Only populated for those link types; otherwise undefined. Each entry contains the Plot\n * contact UUID, the platform-specific account ID\n * (`externalAccountId`) the connector should use to address the\n * recipient without performing its own lookup, and the contact's\n * `role` on the thread (e.g. `\"to\"` / `\"cc\"` / `\"bcc\"`) resolved from\n * `thread.contact_meta`. For `\"addresses\"` link types, contacts without\n * a connection-scoped row fall back to `contact.email`.\n */\n recipients?: ResolvedRecipient[];\n /**\n * Free-form addresses the user typed into the picker (no Plot contact\n * row). Only populated for link types with `compose.targets: \"addresses\"`; otherwise\n * undefined. Connectors should append these alongside `recipients`\n * when constructing the recipient list (e.g. `To:` header for Gmail).\n */\n inviteEmails?: string[];\n};\n\n/** An optional OAuth scope group the user can toggle at connect time. */\nexport type OptionalScopeGroup = {\n /** Stable id used to track the user's selection. */\n id: string;\n /** Value-forward switch label, e.g. \"Add names to events using contacts\". */\n label: string;\n /** Optional secondary line shown under the label. */\n description?: string;\n /** The OAuth scope strings this group grants. */\n scopes: string[];\n /** Whether the group is requested by default (switch on). */\n default: boolean;\n};\n\n/**\n * Structured scope declaration. `required` scopes must be granted — auth fails\n * and re-prompts if any is declined. `optional` groups are requested by default\n * but auth still succeeds if the user declines them; the connector should detect\n * the absence via the granted `token.scopes` and degrade gracefully.\n */\nexport type ScopeConfig = {\n required: string[];\n optional?: OptionalScopeGroup[];\n};\n\n/**\n * Base class for connectors — twists that sync data from external services.\n *\n * Connectors declare a single OAuth provider and scopes, and implement channel\n * lifecycle methods for discovering and syncing external resources. They save\n * data directly via `integrations.saveLink()` instead of using the Plot tool.\n *\n * @example\n * ```typescript\n * class LinearConnector extends Connector<LinearConnector> {\n * readonly provider = AuthProvider.Linear;\n * readonly scopes = [\"read\", \"write\"];\n * readonly linkTypes = [{\n * type: \"issue\",\n * label: \"Issue\",\n * statuses: [\n * { status: \"open\", label: \"Open\", icon: \"todo\" },\n * { status: \"done\", label: \"Done\", icon: \"done\", done: true },\n * ],\n * }];\n *\n * build(build: ToolBuilder) {\n * return {\n * integrations: build(Integrations),\n * };\n * }\n *\n * async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n * const teams = await this.listTeams(token);\n * return teams.map(t => ({ id: t.id, title: t.name }));\n * }\n *\n * async onChannelEnabled(channel: Channel) {\n * const issues = await this.fetchIssues(channel.id);\n * for (const issue of issues) {\n * await this.tools.integrations.saveLink(issue);\n * }\n * }\n *\n * async onChannelDisabled(channel: Channel) {\n * // Clean up webhooks, sync state, etc.\n * }\n * }\n * ```\n */\nexport abstract class Connector<TSelf> extends Twist<TSelf> {\n /**\n * Static marker to identify Connector subclasses without instanceof checks\n * across worker boundaries.\n */\n static readonly isConnector = true;\n\n // ---- Identity (abstract — every connector must declare) ----\n\n /** The OAuth provider this connector authenticates with. */\n readonly provider?: AuthProvider;\n\n /** OAuth scopes to request for this connector — a flat list (all required), or\n * a {@link ScopeConfig} declaring required + optional scope groups. */\n readonly scopes?: string[] | ScopeConfig;\n\n /**\n * Plain-language bullets describing what access connecting this service\n * grants the user — shown on the connect screen regardless of auth mechanism\n * (OAuth, API key, or hosted). For OAuth connectors it also previews what the\n * provider's consent screen will request. These are justifications for what\n * Plot accesses, not a one-to-one mapping of scope strings.\n */\n readonly access?: string[];\n\n // ---- Auth model ----\n\n /**\n * When true, one credential is shared across all users in the workspace,\n * entered once by the installer. When false (default), each user provides\n * their own credential.\n *\n * Applies to both OAuth and key-based connectors:\n * - Shared OAuth: e.g. Slack bot token (workspace-level)\n * - Shared key: e.g. Attio workspace API key\n * - Individual OAuth: e.g. Google Calendar (per-user)\n * - Individual key: e.g. Fellow (per-user API key)\n */\n readonly shared?: boolean;\n\n /**\n * The Options field name that contains the authentication key (e.g. \"apiKey\").\n * Must reference a `secure: true` field in the Options schema.\n *\n * When set, this connector uses key-based auth instead of OAuth.\n * For individual connectors (`shared` is false), this field is stored\n * per-user rather than in shared config.\n */\n readonly keyOption?: string;\n\n // ---- Optional metadata ----\n\n /**\n * When true, this connector has a single implicit channel.\n * `getChannels()` must return exactly one Channel.\n * The UI will show channel config inline instead of a channel list.\n */\n readonly singleChannel?: boolean;\n\n /**\n * The user-facing noun for this connector's channels — what each\n * {@link Channel} returned by {@link getChannels} actually represents in the\n * external service. Many connectors map \"channels\" onto a domain concept\n * (folders, projects, calendars, labels, spaces, repositories, …), so the\n * generic word \"channel\" reads as jargon. Set this and the UI substitutes it\n * everywhere it would otherwise say \"channel(s)\" — e.g. the per-connection\n * toggle becomes \"Sync new folders\" / \"When a new folder is added, …\".\n *\n * Provide lowercase nouns (the UI capitalizes where needed):\n * `{ singular: \"folder\", plural: \"folders\" }`. Defaults to\n * `{ singular: \"channel\", plural: \"channels\" }` when omitted.\n */\n readonly channelNoun?: { singular: string; plural: string };\n\n /**\n * Whether the per-connection \"Sync new channels\" preference starts ON for\n * newly added connections of this connector. Defaults to `false` (opt-in).\n *\n * Set `true` for connectors that select **all** of their channels by default\n * (i.e. {@link getChannels} returns no channels marked\n * `enabledByDefault: false`). If syncing every channel is the intended\n * default, then channels discovered later should also sync automatically.\n * Leave `false`/omitted for selective connectors that exclude some channels\n * by default (e.g. Gmail syncs only Inbox/Sent, Google Calendar only\n * owner calendars) — for those, a newly discovered channel is just as\n * uncertain and should wait for the user to opt in.\n *\n * Only affects the **default** for new connections; the user's explicit\n * toggle always wins, and existing connections keep their stored preference.\n */\n readonly autoEnableNewChannelsByDefault?: boolean;\n\n /**\n * Whether this connector supports the platform's sequential auto-threading —\n * folding a conversation that arrives as a run of separate top-level messages\n * into a single thread. Set `true` for conversational connectors (chat,\n * messaging) that mark eligible links with {@link NewLink.autoThread}. The UI\n * shows a per-connection \"Group related messages into conversations\" toggle\n * only for connectors that declare this.\n *\n * Leave undefined/false for connectors whose items are not conversational\n * (calendars, issue trackers, file storage) — marking a link does nothing\n * unless the connection both declares support and the user opted in.\n */\n readonly autoThreading?: boolean;\n\n /**\n * Whether the per-connection auto-threading preference starts ON for newly\n * added connections of this connector. Defaults to `false` (opt-in) — the\n * least-surprise default, since a wrong fold is irreversible. Only meaningful\n * when {@link autoThreading} is `true`. The user's explicit toggle always\n * wins, and existing connections keep their stored preference.\n */\n readonly autoThreadingByDefault?: boolean;\n\n /**\n * Registry of link types this connector creates (e.g., issue, event, message).\n * Used for display in the UI (icons, labels, statuses).\n */\n readonly linkTypes?: LinkTypeConfig[];\n\n /**\n * Declares how this connector's platform handles emoji reactions.\n * Used to filter the reaction picker for notes whose primary connector\n * is this one, and to guard outbound dispatch from sending emoji the\n * platform can't accept.\n *\n * Leave undefined for connectors whose platform has no concept of\n * reactions (calendar, file storage, issue trackers without reactions).\n */\n readonly reactionCapabilities?: ReactionCapabilities;\n\n /**\n * When true, this connector's effective link types are computed dynamically\n * from its enabled channels' per-channel link types (each channel carries the\n * link types for whatever product/resource it represents), rather than the\n * static union of all declared providers' link types. Lets one connection\n * surface different link types depending on what the user has enabled — e.g.\n * a combined Google connection shows calendar/event link types (and thus the\n * agenda) only when a calendar channel is enabled.\n *\n * Defaults to false (static link types — the behavior for every connector\n * that doesn't set this). Requires the connector to attach per-channel\n * `linkTypes` on the channels returned by `getChannels`.\n */\n readonly dynamicLinkTypes?: boolean;\n\n /**\n * When true, this connector is mentioned by default on replies to threads it created.\n * When false (default), this connector cannot be mentioned at all.\n *\n * Set this to true for connectors with bidirectional sync (e.g., issue trackers,\n * messaging) where user replies should be written back to the external service.\n */\n static readonly handleReplies?: boolean;\n\n // ---- Account identity (abstract — every connector must implement) ----\n\n /**\n * Returns a human-readable name for the connected account.\n * Shown in the connections list and edit modal to identify this connection.\n *\n * For OAuth connectors, this is typically the workspace or organization name\n * (e.g., \"Acme Corp\" for a Linear workspace). For API key connectors, this\n * could be the workspace name from the external service.\n *\n * Override this in your connector to return a meaningful account name.\n *\n * @param auth - The authorization (null for no-provider connectors)\n * @param token - The access token (null for no-provider connectors)\n * @returns Promise resolving to the account display name\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n getAccountName(\n auth: Authorization | null,\n token: AuthToken | null\n ): Promise<string | null> {\n return Promise.resolve(null);\n }\n\n // ---- Channel lifecycle (abstract — every connector must implement) ----\n\n /**\n * Returns available channels for the authorized actor.\n * Called after OAuth is complete, during the setup/edit modal.\n *\n * @param auth - The completed authorization with provider and actor info\n * @param token - The access token for making API calls\n * @returns Promise resolving to available channels for the user to select\n */\n abstract getChannels(\n auth: Authorization | null,\n token: AuthToken | null\n ): Promise<Channel[]>;\n\n /**\n * Called when a channel resource is enabled for syncing.\n *\n * The framework dispatches this in three cases:\n * 1. **Initial enable** — user toggled the channel on for the first time.\n * 2. **Auto-enable** — `setChannels` discovered a new channel on a\n * connection with `auto_enable_new_channels` set.\n * 3. **Recovery after re-auth** — the user re-authorized a previously-\n * broken connection. The framework calls `onChannelEnabled` for every\n * channel that was already enabled at the time of re-auth, with\n * `context.recovering = true`. See {@link SyncContext.recovering}.\n *\n * Implementations should be **idempotent and overwrite stored state**:\n * the same channel may receive multiple `onChannelEnabled` calls across\n * its lifetime. Use unconditional `this.set()` writes rather than\n * coalesce/skip-if-present logic so a recovery dispatch wipes stale\n * cursors and state from the prior session.\n *\n * **Sync state tracking is automatic.** The framework stamps the\n * connection as \"syncing\" when it dispatches this method and clears\n * that state when:\n * - the connector calls `tools.integrations.channelSyncCompleted(id)`\n * once the initial backfill is done, OR\n * - this method throws an unhandled exception (auto-cleared so the UI\n * doesn't get stuck in \"syncing\" forever).\n *\n * **IMPORTANT: This method runs inline in the HTTP request handler.**\n * Any long-running work (webhook setup, API calls, sync) MUST be queued\n * as a separate task via `this.runTask()`, not executed inline. Blocking\n * here causes the client to spin waiting for the response.\n *\n * Only lightweight operations should appear directly in this method:\n * `this.set()`, `this.get()`, `this.callback()`, and `this.runTask()`.\n *\n * @example\n * ```typescript\n * async onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void> {\n * // Recovery: drop stale cursors so the next sync re-walks history.\n * if (context?.recovering) {\n * await this.clear(`last_sync_token_${channel.id}`);\n * }\n *\n * await this.set(`sync_state_${channel.id}`, { channelId: channel.id });\n *\n * // Queue sync as a task — do NOT use this.run() or call sync methods inline\n * const syncCallback = await this.callback(this.syncBatch, 1, \"full\", channel.id, true);\n * await this.runTask(syncCallback);\n *\n * // Queue webhook setup as a task — do NOT call setupWebhook() inline\n * const webhookCallback = await this.callback(this.setupWebhook, channel.id);\n * await this.runTask(webhookCallback);\n * }\n * ```\n *\n * @param channel - The channel that was enabled\n * @param context - Optional sync context (plan-based hints, recovery flag)\n */\n abstract onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void>;\n\n /**\n * Called when a channel resource is disabled.\n * Should stop sync, clean up webhooks, and remove state.\n *\n * @param channel - The channel that was disabled\n */\n abstract onChannelDisabled(channel: Channel): Promise<void>;\n\n // ---- Write-back hooks (optional, default no-ops) ----\n\n /**\n * Called when a link created by this connector is updated by the user.\n * Override to write back changes to the external service\n * (e.g., changing issue status in Linear when marked done in Plot).\n *\n * @param link - The updated link\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onLinkUpdated(link: Link): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user creates a thread in Plot that should create a new\n * item in this connector's external system.\n *\n * A connector opts in to Plot-initiated creation by declaring a\n * `compose` block on the relevant `LinkTypeConfig` (see\n * {@link ComposeConfig}). When a user picks \"Create new <type>\" from the\n * Add link modal and the thread is synced, the runtime calls this method\n * with the draft fields.\n *\n * Implementations should create the item in the external service and\n * return a `NewLinkWithNotes` describing the created item. The platform\n * attaches the returned link to the originating thread — do not call\n * `integrations.saveLink` yourself.\n *\n * Returning `null` aborts creation silently (the thread is still saved\n * without a link).\n *\n * @param draft - The fields captured in Plot for the new item.\n * @returns The link to attach, or null to abort creation.\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onCreateLink(draft: CreateLinkDraft): Promise<NewLinkWithNotes | null> {\n return Promise.resolve(null);\n }\n\n /**\n * Called when a note is created on a thread owned by this connector.\n * Override to write back comments to the external service\n * (e.g., adding a comment to a Linear issue).\n *\n * Returning a string or {@link NoteWriteBackResult} links the Plot note\n * to its external counterpart. A plain string sets the note's `key`.\n * A `NoteWriteBackResult` additionally sets a sync baseline (via\n * `externalContent`) so the next sync-in can recognize the round-tripped\n * content and preserve Plot's formatted version. See\n * {@link NoteWriteBackResult} for details.\n *\n * @param note - The created note\n * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n * @returns Optional note key or NoteWriteBackResult for external dedup + baseline tracking\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onNoteCreated(note: Note, thread: Thread): Promise<string | NoteWriteBackResult | void> {\n return Promise.resolve();\n }\n\n /**\n * Resolve a `fileRef` action's bytes for download. Called when a user opens\n * an attachment in Plot. Return either a redirect URL (preferred for sources\n * that issue signed URLs, like Linear S3 or Slack permalink_public) or a\n * streamed body (required when bytes are only reachable through an\n * authenticated API call, like Gmail attachments.get).\n *\n * @param ref Opaque value the connector previously emitted on a fileRef action.\n * @returns Either `{ redirectUrl }` or `{ body, mimeType, fileName? }`.\n * @throws If the source is unavailable, the connection is broken, or `ref` is invalid.\n *\n * If not overridden, fileRef actions on this connector's notes will return 410 Gone.\n */\n async downloadAttachment(\n ref: string,\n ): Promise<\n | { redirectUrl: string }\n | { body: ReadableStream | Uint8Array; mimeType: string; fileName?: string }\n > {\n throw new Error(\n `downloadAttachment not implemented for ${this.constructor.name} (ref=${ref})`,\n );\n }\n\n /**\n * Called when a note on a thread owned by this connector is updated.\n * Override to write back changes to the external service\n * (e.g., syncing reaction tags as emoji reactions, or editing a comment\n * whose content changed in Plot).\n *\n * Return a {@link NoteWriteBackResult} with `externalContent` to update\n * the sync baseline after a successful write-back, so the next sync-in\n * recognizes the external version as already-seen and preserves Plot's\n * content.\n *\n * @param note - The updated note (includes current tags)\n * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n * @returns Optional NoteWriteBackResult for baseline tracking\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onNoteUpdated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user reads or unreads a thread owned by this connector.\n * Override to write back read status to the external service\n * (e.g., marking an email as read in Gmail).\n *\n * @param thread - The thread that was read/unread (includes thread.meta with connector-specific data)\n * @param actor - The user who performed the action\n * @param unread - false when marked as read, true when marked as unread\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onThreadRead(thread: Thread, actor: Actor, unread: boolean): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user changes the **thread-level sharing** of a thread owned\n * by this connector — adding or removing a contact, or (for connectors with\n * roles) changing a contact's role. Override on connectors whose external\n * source can reflect that membership change, e.g. a group DM / multi-party\n * chat (`LinkTypeConfig.sharingModel: \"thread\"`) or an email's To/Cc/Bcc\n * recipients (`sharingModel: \"message\"`). Connectors backed by an immutable\n * roster (most group DMs today) or by channel-level membership\n * (`sharingModel: \"channel\"`) leave this as the default no-op.\n *\n * `role`/`from`/`to` are **null** for connectors without roles (group DMs\n * have no roles); they carry a `contactRoles` id only for connectors that\n * declare roles (e.g. email `to`/`cc`/`bcc`).\n *\n * The dispatch fires after Plot has persisted the change. A connector may\n * reflect it actively (e.g. add/remove a participant on the external chat)\n * or passively on the next outbound note (e.g. building To/Cc/Bcc headers\n * from the current `thread.contacts` × `thread.contactMeta`) — this callback\n * is not the right place to send a standalone notification.\n *\n * @param thread - The thread whose contacts changed\n * @param changes - The added/removed contacts and any role transitions on existing contacts\n */\n /* eslint-disable @typescript-eslint/no-unused-vars */\n onContactsChanged(\n thread: Thread,\n changes: {\n added: Array<{ contact: Contact; role: string | null }>;\n removed: Array<{ contact: Contact; role: string | null }>;\n changed: Array<{ contact: Contact; from: string | null; to: string | null }>;\n },\n ): Promise<void> {\n return Promise.resolve();\n }\n /* eslint-enable @typescript-eslint/no-unused-vars */\n\n /**\n * Called when a user marks or unmarks a thread as todo.\n * Override to sync todo status to the external service\n * (e.g., starring an email in Gmail when marked as todo).\n *\n * @param thread - The thread (includes thread.meta with connector-specific data)\n * @param actor - The user who changed the todo status\n * @param todo - true when marked as todo, false when done or removed\n * @param options - Additional context\n * @param options.date - The todo date (when todo=true)\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onThreadToDo(thread: Thread, actor: Actor, todo: boolean, options: { date?: Date }): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a schedule contact's RSVP status changes on a thread owned by this connector.\n * Override to sync RSVP changes back to the external calendar.\n *\n * @param thread - The thread (includes thread.meta with connector-specific data)\n * @param scheduleId - The schedule ID\n * @param contactId - The contact whose status changed\n * @param status - The new RSVP status ('attend', 'skip', or null)\n * @param actor - The user who changed the status\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onScheduleContactUpdated(thread: Thread, scheduleId: string, contactId: ActorId, status: ScheduleContactStatus | null, actor: Actor): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called when a user adds or removes a single emoji reaction on a note\n * (one event per `(note, actor, emoji)` state transition).\n *\n * Dispatch is routed to the reacting user's own connector instance via\n * `twist_instance_for_actor` on `note_reaction.actor_id`, so this method\n * already runs under the reactor's auth. Fetch the API client with the\n * connector's normal token-fetch path (`this.tools.integrations.get(...)`)\n * and the external write — e.g. Slack `reactions.add` — will be attributed\n * to the correct user. No `actAs` step required.\n *\n * If the reacting user has no connection of this type, no dispatch fires\n * for that reaction (it stays in Plot only).\n *\n * Override to sync per-actor reactions back to the external system.\n *\n * @param note - The note that was reacted on (partial; `id`, `key`, `content` populated)\n * @param thread - The thread the note belongs to (partial; `id`, `title`, `archived`, `meta` populated)\n * @param actor - The contact who added/removed the reaction\n * @param emoji - The emoji (Unicode grapheme or `provider:workspace/name` custom-emoji ref)\n * @param added - `true` if the reaction is now present, `false` if it was removed\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n onNoteReactionChanged(note: Note, thread: Thread, actor: Actor, emoji: string, added: boolean): Promise<void> {\n return Promise.resolve();\n }\n\n // ---- Activation ----\n\n /**\n * Called when the connector is activated after OAuth is complete.\n *\n * Connectors receive the authorization in addition to the activating actor.\n * When this runs, `this.userId` is already populated with the installing\n * user's ID.\n *\n * Default implementation does nothing. Override for custom setup.\n *\n * @param context - The activation context\n * @param context.auth - The completed OAuth authorization\n * @param context.actor - The actor who activated the connector\n */\n // @ts-ignore - Connector.activate() has a Connector-specific context type.\n activate(context: { auth?: Authorization; actor?: Actor }): Promise<void> {\n return Promise.resolve();\n }\n}\n\n/** @deprecated Use `Connector` instead. */\nexport { Connector as Source };\n";
|
|
8
8
|
//# sourceMappingURL=connector.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"connector.js","sourceRoot":"","sources":["../../src/llm-docs/connector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,
|
|
1
|
+
{"version":3,"file":"connector.js","sourceRoot":"","sources":["../../src/llm-docs/connector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,mkjCAAmkjC,CAAC"}
|
package/dist/llm-docs/tool.d.ts
CHANGED
|
@@ -4,6 +4,6 @@
|
|
|
4
4
|
* This file is auto-generated during build. Do not edit manually.
|
|
5
5
|
* Generated from: prebuild.ts
|
|
6
6
|
*/
|
|
7
|
-
declare const _default: "import {\n type Actor,\n} from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n InferOptions,\n InferTools,\n Serializable,\n ToolBuilder,\n ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Abstract parent for both built-in tools and regular Tools.\n * Regular tools extend Tool.\n */\nexport abstract class ITool {}\n\n/**\n * Base class for regular tools.\n *\n * Regular tools run in isolation and can only access other tools declared\n * in their build method. They are ideal for external API integrations\n * and reusable functionality that doesn't require Plot's internal infrastructure.\n *\n * @example\n * ```typescript\n * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {\n * constructor(id: string, options: { clientId: string }) {\n * super(id, options);\n * }\n *\n * build(tools: ToolBuilder) {\n * return {\n * auth: tools.build(Integrations),\n * network: tools.build(Network),\n * };\n * }\n *\n * async getCalendars() {\n * const token = await this.tools.auth.get(...);\n * // Implementation\n * }\n * }\n * ```\n */\nexport abstract class Tool<TSelf> implements ITool {\n constructor(\n protected id: string,\n protected options: InferOptions<TSelf>,\n private toolShed: ToolShed\n ) {}\n\n /**\n * Gets the initialized tools for this tool.\n * @throws Error if called before initialization is complete\n */\n protected get tools() {\n return this.toolShed.getTools<InferTools<TSelf>>();\n }\n\n /**\n * Declares tool dependencies for this tool.\n * Return an object mapping tool names to build() promises.\n * Default implementation returns empty object (no custom tools).\n *\n * @param build - The build function to use for declaring dependencies\n * @returns Object mapping tool names to tool promises\n *\n * @example\n * ```typescript\n * build(build: ToolBuilder) {\n * return {\n * network: build(Network, { urls: [\"https://api.example.com/*\"] }),\n * };\n * }\n * ```\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n build(build: ToolBuilder): Record<string, Promise<ITool>> {\n return {};\n }\n\n /**\n * Creates a persistent callback to a method on this tool.\n *\n * ExtraArgs are strongly typed to match the method's signature.\n *\n * @param fn - The method to callback\n * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n * @returns Promise resolving to a persistent callback token\n *\n * @example\n * ```typescript\n * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n * ```\n */\n protected async callback<\n TArgs extends Serializable[],\n Fn extends (...args: TArgs) => any\n >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {\n return this.tools.callbacks.create(fn, ...extraArgs);\n }\n\n /**\n * Deletes a specific callback by its token.\n *\n * @param token - The callback token to delete\n * @returns Promise that resolves when the callback is deleted\n */\n protected async deleteCallback(token: Callback): Promise<void> {\n return this.tools.callbacks.delete(token);\n }\n\n /**\n * Deletes all callbacks for this tool.\n *\n * @returns Promise that resolves when all callbacks are deleted\n */\n protected async deleteAllCallbacks(): Promise<void> {\n return this.tools.callbacks.deleteAll();\n }\n\n /**\n * Executes a callback by its token inline in the current execution.\n *\n * **Use `this.runTask()` instead for batch continuations and long-running work.**\n * `this.run()` executes inline, sharing the current request count (~1000 limit)\n * and blocking the HTTP response. This causes timeouts when used in lifecycle\n * methods like `onChannelEnabled` or `syncBatch` continuations.\n *\n * `this.run()` is appropriate when you need the callback's **return value** \u2014\n * e.g., running a parent callback token that returns data. For fire-and-forget\n * work, always prefer `this.runTask()`.\n *\n * @param token - The callback token to execute\n * @param args - Optional arguments to pass to the callback\n * @returns Promise resolving to the callback result\n */\n protected async run(token: Callback, ...args: any[]): Promise<any> {\n return this.tools.callbacks.run(token, ...args);\n }\n\n /**\n * Retrieves a value from persistent storage by key.\n *\n * Values are automatically deserialized using SuperJSON, which\n * properly restores Date objects, Maps, Sets, and other complex types.\n *\n * @template T - The expected type of the stored value (must be Serializable)\n * @param key - The storage key to retrieve\n * @returns Promise resolving to the stored value or null\n */\n protected async get<T extends Serializable>(key: string): Promise<T | null> {\n return this.tools.store.get(key);\n }\n\n /**\n * Stores a value in persistent storage.\n *\n * The value will be serialized using SuperJSON and stored persistently.\n * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n * and other complex types that standard JSON doesn't support.\n *\n * **Important**: Functions and Symbols cannot be stored.\n * **For function references**: Use callbacks instead of storing functions directly.\n *\n * @example\n * ```typescript\n * // \u2705 Date objects are preserved\n * await this.set(\"sync_state\", {\n * lastSync: new Date(),\n * minDate: new Date(2024, 0, 1)\n * });\n *\n * // \u2705 undefined is now supported\n * await this.set(\"data\", { name: \"test\", optional: undefined });\n *\n * // \u2705 Arrays with undefined are supported\n * await this.set(\"items\", [1, undefined, 3]);\n * await this.set(\"items\", [1, null, 3]); // Also works\n *\n * // \u2705 Maps and Sets are supported\n * await this.set(\"mapping\", new Map([[\"key\", \"value\"]]));\n * await this.set(\"tags\", new Set([\"tag1\", \"tag2\"]));\n *\n * // \u274C WRONG: Cannot store functions directly\n * await this.set(\"handler\", this.myHandler);\n *\n * // \u2705 CORRECT: Create a callback token first\n * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n * await this.set(\"handler_token\", token);\n *\n * // Later, execute the callback\n * const token = await this.get<Callback>(\"handler_token\");\n * await this.run(token);\n * ```\n *\n * @template T - The type of value being stored (must be Serializable)\n * @param key - The storage key to use\n * @param value - The value to store (must be SuperJSON-serializable)\n * @returns Promise that resolves when the value is stored\n */\n protected async set<T extends Serializable>(\n key: string,\n value: T\n ): Promise<void> {\n return this.tools.store.set(key, value);\n }\n\n /**\n * Lists all storage keys matching a prefix.\n *\n * @param prefix - The prefix to match keys against\n * @returns Promise resolving to an array of matching key strings\n */\n protected async list(prefix: string): Promise<string[]> {\n return this.tools.store.list(prefix);\n }\n\n /**\n * Removes a specific key from persistent storage.\n *\n * @param key - The storage key to remove\n * @returns Promise that resolves when the key is removed\n */\n protected async clear(key: string): Promise<void> {\n return this.tools.store.clear(key);\n }\n\n /**\n * Removes all keys from this tool's storage.\n *\n * @returns Promise that resolves when all keys are removed\n */\n protected async clearAll(): Promise<void> {\n return this.tools.store.clearAll();\n }\n\n /**\n * Queues a callback to execute in a separate worker context with a fresh request limit.\n *\n * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n * tool calls, database operations). This is the primary way to stay under request limits\n * when processing large datasets or making many API calls.\n *\n * Use this to break long loops into chunks that each stay under the ~1000 request limit.\n * Each task runs in an isolated execution environment with ~1000 requests and ~60 seconds CPU time.\n *\n * @param callback - The callback token created with `this.callback()`\n * @param options - Optional configuration for the execution\n * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n * @returns Promise resolving to a cancellation token (only for scheduled executions)\n *\n * @example\n * ```typescript\n * // Break large loop into batches\n * const callback = await this.callback(this.processBatch, 1);\n * await this.runTask(callback); // New execution with fresh request limit\n * ```\n */\n protected async runTask(\n callback: Callback,\n options?: { runAt?: Date }\n ): Promise<string | void> {\n return this.tools.tasks.runTask(callback, options);\n }\n\n /**\n * Cancels a previously scheduled execution.\n *\n * @param token - The cancellation token returned by runTask() with runAt option\n * @returns Promise that resolves when the cancellation is processed\n */\n protected async cancelTask(token: string): Promise<void> {\n return this.tools.tasks.cancelTask(token);\n }\n\n /**\n * Cancels all scheduled executions for this tool.\n *\n * @returns Promise that resolves when all cancellations are processed\n */\n protected async cancelAllTasks(): Promise<void> {\n return this.tools.tasks.cancelAllTasks();\n }\n\n /**\n * Schedules a **singleton** task keyed by `key`: re-scheduling under the same\n * key atomically replaces any pending task, so at most one is ever live.\n *\n * Prefer this over `runTask({ runAt })` for recurring/self-renewing jobs\n * (watch renewals, polling, deferred cleanup) \u2014 it removes the error-prone\n * \"store token, cancel before re-scheduling\" bookkeeping that otherwise leaks\n * parallel task chains. See {@link Tasks.scheduleTask}.\n *\n * @param key - Stable identifier scoped to what the task renews\n * @param callback - The callback token created with `this.callback()`\n * @param options.runAt - When to run (required)\n * @returns Promise resolving to the scheduled task's cancellation token\n */\n protected async scheduleTask(\n key: string,\n callback: Callback,\n options: { runAt: Date }\n ): Promise<string | void> {\n return this.tools.tasks.scheduleTask(key, callback, options);\n }\n\n /**\n * Cancels the singleton task previously scheduled under `key` (if any).\n * No-op if none exists or it already ran. See {@link Tasks.cancelScheduledTask}.\n *\n * @param key - The same key passed to {@link scheduleTask}\n * @returns Promise that resolves when the cancellation is processed\n */\n protected async cancelScheduledTask(key: string): Promise<void> {\n return this.tools.tasks.cancelScheduledTask(key);\n }\n\n /**\n * Called before the twist's activate method, starting from the deepest tool dependencies.\n *\n * This method is called in a depth-first manner, with the deepest dependencies\n * being called first, bubbling up to the top-level tools before the twist's\n * activate method is called.\n *\n * @param context - Optional context containing the actor who triggered activation\n * @returns Promise that resolves when pre-activation is complete\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n preActivate(context?: { actor: Actor }): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called after the twist's activate method, starting from the top-level tools.\n *\n * This method is called in reverse order, with top-level tools being called\n * first, then cascading down to the deepest dependencies.\n *\n * @param context - Optional context containing the actor who triggered activation\n * @returns Promise that resolves when post-activation is complete\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n postActivate(context?: { actor: Actor }): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called before the twist's upgrade method, starting from the deepest tool dependencies.\n *\n * This method is called in a depth-first manner, with the deepest dependencies\n * being called first, bubbling up to the top-level tools before the twist's\n * upgrade method is called.\n *\n * @returns Promise that resolves when pre-upgrade is complete\n */\n preUpgrade(): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called after the twist's upgrade method, starting from the top-level tools.\n *\n * This method is called in reverse order, with top-level tools being called\n * first, then cascading down to the deepest dependencies.\n *\n * @returns Promise that resolves when post-upgrade is complete\n */\n postUpgrade(): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called before the twist's deactivate method, starting from the deepest tool dependencies.\n *\n * This method is called in a depth-first manner, with the deepest dependencies\n * being called first, bubbling up to the top-level tools before the twist's\n * deactivate method is called.\n *\n * @returns Promise that resolves when pre-deactivation is complete\n */\n preDeactivate(): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called after the twist's deactivate method, starting from the top-level tools.\n *\n * This method is called in reverse order, with top-level tools being called\n * first, then cascading down to the deepest dependencies.\n *\n * @returns Promise that resolves when post-deactivation is complete\n */\n postDeactivate(): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Waits for tool initialization to complete.\n * Called automatically by the entrypoint before lifecycle methods.\n * @internal\n */\n async waitForReady(): Promise<void> {\n await this.toolShed.waitForReady();\n }\n}\n";
|
|
7
|
+
declare const _default: "import {\n type Actor,\n} from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n InferOptions,\n InferTools,\n Serializable,\n ToolBuilder,\n ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Abstract parent for both built-in tools and regular Tools.\n * Regular tools extend Tool.\n */\nexport abstract class ITool {}\n\n/**\n * Base class for regular tools.\n *\n * Regular tools run in isolation and can only access other tools declared\n * in their build method. They are ideal for external API integrations\n * and reusable functionality that doesn't require Plot's internal infrastructure.\n *\n * @example\n * ```typescript\n * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {\n * constructor(id: string, options: { clientId: string }) {\n * super(id, options);\n * }\n *\n * build(tools: ToolBuilder) {\n * return {\n * auth: tools.build(Integrations),\n * network: tools.build(Network),\n * };\n * }\n *\n * async getCalendars() {\n * const token = await this.tools.auth.get(...);\n * // Implementation\n * }\n * }\n * ```\n */\nexport abstract class Tool<TSelf> implements ITool {\n constructor(\n protected id: string,\n protected options: InferOptions<TSelf>,\n private toolShed: ToolShed\n ) {}\n\n /**\n * Gets the initialized tools for this tool.\n * @throws Error if called before initialization is complete\n */\n protected get tools() {\n return this.toolShed.getTools<InferTools<TSelf>>();\n }\n\n /**\n * Declares tool dependencies for this tool.\n * Return an object mapping tool names to build() promises.\n * Default implementation returns empty object (no custom tools).\n *\n * @param build - The build function to use for declaring dependencies\n * @returns Object mapping tool names to tool promises\n *\n * @example\n * ```typescript\n * build(build: ToolBuilder) {\n * return {\n * network: build(Network, { urls: [\"https://api.example.com/*\"] }),\n * };\n * }\n * ```\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n build(build: ToolBuilder): Record<string, Promise<ITool>> {\n return {};\n }\n\n /**\n * Creates a persistent callback to a method on this tool.\n *\n * ExtraArgs are strongly typed to match the method's signature.\n *\n * @param fn - The method to callback\n * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n * @returns Promise resolving to a persistent callback token\n *\n * @example\n * ```typescript\n * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n * ```\n */\n protected async callback<\n TArgs extends Serializable[],\n Fn extends (...args: TArgs) => any\n >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {\n return this.tools.callbacks.create(fn, ...extraArgs);\n }\n\n /**\n * Deletes a specific callback by its token.\n *\n * @param token - The callback token to delete\n * @returns Promise that resolves when the callback is deleted\n */\n protected async deleteCallback(token: Callback): Promise<void> {\n return this.tools.callbacks.delete(token);\n }\n\n /**\n * Deletes all callbacks for this tool.\n *\n * @returns Promise that resolves when all callbacks are deleted\n */\n protected async deleteAllCallbacks(): Promise<void> {\n return this.tools.callbacks.deleteAll();\n }\n\n /**\n * Executes a callback by its token inline in the current execution.\n *\n * **Use `this.runTask()` instead for batch continuations and long-running work.**\n * `this.run()` executes inline, sharing the current request count (~1000 limit)\n * and blocking the HTTP response. This causes timeouts when used in lifecycle\n * methods like `onChannelEnabled` or `syncBatch` continuations.\n *\n * `this.run()` is appropriate when you need the callback's **return value** \u2014\n * e.g., running a parent callback token that returns data. For fire-and-forget\n * work, always prefer `this.runTask()`.\n *\n * @param token - The callback token to execute\n * @param args - Optional arguments to pass to the callback\n * @returns Promise resolving to the callback result\n */\n protected async run(token: Callback, ...args: any[]): Promise<any> {\n return this.tools.callbacks.run(token, ...args);\n }\n\n /**\n * Retrieves a value from persistent storage by key.\n *\n * Values are automatically deserialized using SuperJSON, which\n * properly restores Date objects, Maps, Sets, and other complex types.\n *\n * @template T - The expected type of the stored value (must be Serializable)\n * @param key - The storage key to retrieve\n * @returns Promise resolving to the stored value or null\n */\n protected async get<T extends Serializable>(key: string): Promise<T | null> {\n return this.tools.store.get(key);\n }\n\n /**\n * Stores a value in persistent storage.\n *\n * The value will be serialized using SuperJSON and stored persistently.\n * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n * and other complex types that standard JSON doesn't support.\n *\n * **Important**: Functions and Symbols cannot be stored.\n * **For function references**: Use callbacks instead of storing functions directly.\n *\n * @example\n * ```typescript\n * // \u2705 Date objects are preserved\n * await this.set(\"sync_state\", {\n * lastSync: new Date(),\n * minDate: new Date(2024, 0, 1)\n * });\n *\n * // \u2705 undefined is now supported\n * await this.set(\"data\", { name: \"test\", optional: undefined });\n *\n * // \u2705 Arrays with undefined are supported\n * await this.set(\"items\", [1, undefined, 3]);\n * await this.set(\"items\", [1, null, 3]); // Also works\n *\n * // \u2705 Maps and Sets are supported\n * await this.set(\"mapping\", new Map([[\"key\", \"value\"]]));\n * await this.set(\"tags\", new Set([\"tag1\", \"tag2\"]));\n *\n * // \u274C WRONG: Cannot store functions directly\n * await this.set(\"handler\", this.myHandler);\n *\n * // \u2705 CORRECT: Create a callback token first\n * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n * await this.set(\"handler_token\", token);\n *\n * // Later, execute the callback\n * const token = await this.get<Callback>(\"handler_token\");\n * await this.run(token);\n * ```\n *\n * @template T - The type of value being stored (must be Serializable)\n * @param key - The storage key to use\n * @param value - The value to store (must be SuperJSON-serializable)\n * @returns Promise that resolves when the value is stored\n */\n protected async set<T extends Serializable>(\n key: string,\n value: T\n ): Promise<void> {\n return this.tools.store.set(key, value);\n }\n\n /**\n * Lists all storage keys matching a prefix.\n *\n * @param prefix - The prefix to match keys against\n * @returns Promise resolving to an array of matching key strings\n */\n protected async list(prefix: string): Promise<string[]> {\n return this.tools.store.list(prefix);\n }\n\n /**\n * Removes a specific key from persistent storage.\n *\n * @param key - The storage key to remove\n * @returns Promise that resolves when the key is removed\n */\n protected async clear(key: string): Promise<void> {\n return this.tools.store.clear(key);\n }\n\n /**\n * Removes all keys from this tool's storage.\n *\n * @returns Promise that resolves when all keys are removed\n */\n protected async clearAll(): Promise<void> {\n return this.tools.store.clearAll();\n }\n\n /**\n * Queues a callback to execute in a separate worker context with a fresh request limit.\n *\n * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n * tool calls, database operations). This is the primary way to stay under request limits\n * when processing large datasets or making many API calls.\n *\n * Use this to break long loops into chunks that each stay under the ~1000 request limit.\n * Each task runs in an isolated execution environment with ~1000 requests and ~60 seconds CPU time.\n *\n * @param callback - The callback token created with `this.callback()`\n * @param options - Optional configuration for the execution\n * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n * @returns Promise resolving to a cancellation token (only for scheduled executions)\n *\n * @example\n * ```typescript\n * // Break large loop into batches\n * const callback = await this.callback(this.processBatch, 1);\n * await this.runTask(callback); // New execution with fresh request limit\n * ```\n */\n protected async runTask(\n callback: Callback,\n options?: { runAt?: Date }\n ): Promise<string | void> {\n return this.tools.tasks.runTask(callback, options);\n }\n\n /**\n * Cancels a previously scheduled execution.\n *\n * @param token - The cancellation token returned by runTask() with runAt option\n * @returns Promise that resolves when the cancellation is processed\n */\n protected async cancelTask(token: string): Promise<void> {\n return this.tools.tasks.cancelTask(token);\n }\n\n /**\n * Cancels all scheduled executions for this tool.\n *\n * @returns Promise that resolves when all cancellations are processed\n */\n protected async cancelAllTasks(): Promise<void> {\n return this.tools.tasks.cancelAllTasks();\n }\n\n /**\n * Schedules a **singleton** task keyed by `key`: re-scheduling under the same\n * key atomically replaces any pending task, so at most one is ever live.\n *\n * Prefer this over `runTask({ runAt })` for recurring/self-renewing jobs\n * (watch renewals, polling, deferred cleanup) \u2014 it removes the error-prone\n * \"store token, cancel before re-scheduling\" bookkeeping that otherwise leaks\n * parallel task chains. See {@link Tasks.scheduleTask}.\n *\n * @param key - Stable identifier scoped to what the task renews\n * @param callback - The callback token created with `this.callback()`\n * @param options.runAt - When to run (required)\n * @returns Promise resolving to the scheduled task's cancellation token\n */\n protected async scheduleTask(\n key: string,\n callback: Callback,\n options: { runAt: Date }\n ): Promise<string | void> {\n return this.tools.tasks.scheduleTask(key, callback, options);\n }\n\n /**\n * Cancels the singleton task previously scheduled under `key` (if any).\n * No-op if none exists or it already ran. See {@link Tasks.cancelScheduledTask}.\n *\n * @param key - The same key passed to {@link scheduleTask}\n * @returns Promise that resolves when the cancellation is processed\n */\n protected async cancelScheduledTask(key: string): Promise<void> {\n return this.tools.tasks.cancelScheduledTask(key);\n }\n\n /**\n * Schedules a durable recurring task under a stable key. The platform\n * re-arms the task every `intervalMs` automatically \u2014 the callback does NOT\n * need to reschedule itself. Re-scheduling under the same key atomically\n * replaces the pending occurrence (at most one live task per key). Tear down\n * with {@link cancelScheduledTask}. See {@link Tasks.scheduleRecurring}.\n *\n * @param key - Stable identifier, e.g. `\"mailbox-self-heal\"`\n * @param callback - Callback token created with `this.callback()`\n * @param options.intervalMs - Safety-ceiling cadence in milliseconds\n * @param options.firstRunAt - Optional precise time for the next fire\n */\n protected async scheduleRecurring(\n key: string,\n callback: Callback,\n options: { intervalMs: number; firstRunAt?: Date }\n ): Promise<void> {\n return this.tools.tasks.scheduleRecurring(key, callback, options);\n }\n\n /**\n * Called before the twist's activate method, starting from the deepest tool dependencies.\n *\n * This method is called in a depth-first manner, with the deepest dependencies\n * being called first, bubbling up to the top-level tools before the twist's\n * activate method is called.\n *\n * @param context - Optional context containing the actor who triggered activation\n * @returns Promise that resolves when pre-activation is complete\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n preActivate(context?: { actor: Actor }): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called after the twist's activate method, starting from the top-level tools.\n *\n * This method is called in reverse order, with top-level tools being called\n * first, then cascading down to the deepest dependencies.\n *\n * @param context - Optional context containing the actor who triggered activation\n * @returns Promise that resolves when post-activation is complete\n */\n // eslint-disable-next-line @typescript-eslint/no-unused-vars\n postActivate(context?: { actor: Actor }): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called before the twist's upgrade method, starting from the deepest tool dependencies.\n *\n * This method is called in a depth-first manner, with the deepest dependencies\n * being called first, bubbling up to the top-level tools before the twist's\n * upgrade method is called.\n *\n * @returns Promise that resolves when pre-upgrade is complete\n */\n preUpgrade(): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called after the twist's upgrade method, starting from the top-level tools.\n *\n * This method is called in reverse order, with top-level tools being called\n * first, then cascading down to the deepest dependencies.\n *\n * @returns Promise that resolves when post-upgrade is complete\n */\n postUpgrade(): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called before the twist's deactivate method, starting from the deepest tool dependencies.\n *\n * This method is called in a depth-first manner, with the deepest dependencies\n * being called first, bubbling up to the top-level tools before the twist's\n * deactivate method is called.\n *\n * @returns Promise that resolves when pre-deactivation is complete\n */\n preDeactivate(): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Called after the twist's deactivate method, starting from the top-level tools.\n *\n * This method is called in reverse order, with top-level tools being called\n * first, then cascading down to the deepest dependencies.\n *\n * @returns Promise that resolves when post-deactivation is complete\n */\n postDeactivate(): Promise<void> {\n return Promise.resolve();\n }\n\n /**\n * Waits for tool initialization to complete.\n * Called automatically by the entrypoint before lifecycle methods.\n * @internal\n */\n async waitForReady(): Promise<void> {\n await this.toolShed.waitForReady();\n }\n}\n";
|
|
8
8
|
export default _default;
|
|
9
9
|
//# sourceMappingURL=tool.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/llm-docs/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,
|
|
1
|
+
{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/llm-docs/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,m1dAAsyd;AAArzd,wBAAszd"}
|