@plotday/twister 0.44.0 → 0.46.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 +7 -7
- package/dist/connector.d.ts.map +1 -1
- package/dist/connector.js +5 -6
- package/dist/connector.js.map +1 -1
- package/dist/docs/assets/hierarchy.js +1 -1
- package/dist/docs/assets/navigation.js +1 -1
- package/dist/docs/assets/search.js +1 -1
- package/dist/docs/classes/index.Connector.html +55 -44
- 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 +23 -25
- 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 +11 -10
- package/dist/docs/classes/tools_network.Network.html +29 -4
- package/dist/docs/classes/tools_plot.Plot.html +41 -28
- package/dist/docs/classes/tools_store.Store.html +1 -1
- package/dist/docs/classes/tools_tasks.Tasks.html +1 -1
- package/dist/docs/classes/tools_twists.Twists.html +1 -1
- package/dist/docs/classes/twist.Twist.html +50 -35
- package/dist/docs/documents/Built-in_Tools.html +5 -3
- package/dist/docs/enums/plot.ActorType.html +4 -4
- package/dist/docs/enums/tools_integrations.AuthProvider.html +12 -12
- package/dist/docs/enums/tools_plot.LinkAccess.html +2 -2
- package/dist/docs/enums/tools_plot.PriorityAccess.html +5 -5
- package/dist/docs/enums/tools_plot.ThreadAccess.html +1 -1
- package/dist/docs/hierarchy.html +1 -1
- package/dist/docs/media/AGENTS.md +31 -11
- package/dist/docs/media/SYNC_STRATEGIES.md +5 -1
- package/dist/docs/modules/index.html +1 -1
- package/dist/docs/modules/plot.html +1 -1
- package/dist/docs/modules/tools_integrations.html +1 -1
- package/dist/docs/types/plot.Actor.html +5 -5
- package/dist/docs/types/plot.Contact.html +9 -0
- package/dist/docs/types/plot.ContentType.html +1 -1
- package/dist/docs/types/plot.Link.html +15 -15
- package/dist/docs/types/plot.LinkUpdate.html +2 -2
- package/dist/docs/types/plot.NewActor.html +1 -1
- package/dist/docs/types/plot.NewContact.html +1 -1
- package/dist/docs/types/plot.NewLink.html +9 -8
- package/dist/docs/types/plot.NewLinkWithNotes.html +1 -1
- package/dist/docs/types/plot.NewNote.html +9 -3
- package/dist/docs/types/plot.NewThread.html +7 -5
- package/dist/docs/types/plot.NewThreadWithNotes.html +1 -1
- package/dist/docs/types/plot.Note.html +5 -2
- package/dist/docs/types/plot.NoteUpdate.html +4 -3
- package/dist/docs/types/plot.PlanOperation.html +1 -1
- package/dist/docs/types/plot.Thread.html +1 -1
- package/dist/docs/types/plot.ThreadAccessLevel.html +7 -0
- package/dist/docs/types/plot.ThreadCommon.html +5 -9
- package/dist/docs/types/plot.ThreadFilter.html +2 -2
- package/dist/docs/types/plot.ThreadUpdate.html +1 -1
- package/dist/docs/types/plot.ThreadWithNotes.html +1 -1
- package/dist/docs/types/tools_integrations.ArchiveLinkFilter.html +5 -5
- package/dist/docs/types/tools_integrations.AuthToken.html +4 -4
- package/dist/docs/types/tools_integrations.Authorization.html +4 -4
- package/dist/docs/types/tools_integrations.Channel.html +3 -5
- package/dist/docs/types/tools_integrations.LinkTypeConfig.html +14 -9
- package/dist/docs/types/tools_integrations.SyncContext.html +10 -0
- package/dist/docs/types/tools_plot.SearchOptions.html +4 -2
- 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/plot.d.ts +1 -1
- package/dist/llm-docs/plot.d.ts.map +1 -1
- package/dist/llm-docs/plot.js +1 -1
- package/dist/llm-docs/plot.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/integrations.d.ts +1 -1
- package/dist/llm-docs/tools/integrations.d.ts.map +1 -1
- package/dist/llm-docs/tools/integrations.js +1 -1
- package/dist/llm-docs/tools/integrations.js.map +1 -1
- package/dist/llm-docs/tools/network.d.ts +1 -1
- package/dist/llm-docs/tools/network.d.ts.map +1 -1
- package/dist/llm-docs/tools/network.js +1 -1
- package/dist/llm-docs/tools/network.js.map +1 -1
- package/dist/llm-docs/tools/plot.d.ts +1 -1
- package/dist/llm-docs/tools/plot.d.ts.map +1 -1
- package/dist/llm-docs/tools/plot.js +1 -1
- package/dist/llm-docs/tools/plot.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/plot.d.ts +72 -61
- package/dist/plot.d.ts.map +1 -1
- package/dist/plot.js.map +1 -1
- package/dist/tool.d.ts +3 -5
- package/dist/tool.d.ts.map +1 -1
- package/dist/tool.js +2 -4
- package/dist/tool.js.map +1 -1
- package/dist/tools/integrations.d.ts +28 -4
- package/dist/tools/integrations.d.ts.map +1 -1
- package/dist/tools/integrations.js.map +1 -1
- package/dist/tools/network.d.ts +30 -0
- package/dist/tools/network.d.ts.map +1 -1
- package/dist/tools/network.js.map +1 -1
- package/dist/tools/plot.d.ts +41 -15
- package/dist/tools/plot.d.ts.map +1 -1
- package/dist/tools/plot.js +9 -9
- package/dist/tools/plot.js.map +1 -1
- package/dist/twist.d.ts +38 -14
- package/dist/twist.d.ts.map +1 -1
- package/dist/twist.js +37 -13
- package/dist/twist.js.map +1 -1
- package/package.json +1 -1
- package/dist/docs/types/plot.PickPriorityConfig.html +0 -20
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="126" 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="129" 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="545" 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="575" 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="766" 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="841" 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="919" 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="991" 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="1117" 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="1138" 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="1570" 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="1635" 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="1689" 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="9" 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="1204" 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>
|
|
@@ -27,6 +27,7 @@ connectors/<name>/
|
|
|
27
27
|
```json
|
|
28
28
|
{
|
|
29
29
|
"name": "@plotday/connector-<name>",
|
|
30
|
+
"private": true,
|
|
30
31
|
"displayName": "Human Name",
|
|
31
32
|
"description": "One-line purpose statement",
|
|
32
33
|
"author": "Plot <team@plot.day> (https://plot.day)",
|
|
@@ -60,7 +61,6 @@ connectors/<name>/
|
|
|
60
61
|
},
|
|
61
62
|
"homepage": "https://plot.day",
|
|
62
63
|
"keywords": ["plot", "connector", "<name>"],
|
|
63
|
-
"publishConfig": { "access": "public" }
|
|
64
64
|
}
|
|
65
65
|
```
|
|
66
66
|
|
|
@@ -556,19 +556,39 @@ The `activity.source` field is the idempotency key for automatic upserts. Use a
|
|
|
556
556
|
<provider>:<namespace>:<id> — When provider has multiple entity types
|
|
557
557
|
```
|
|
558
558
|
|
|
559
|
-
|
|
559
|
+
### Source identifier uniqueness (CRITICAL)
|
|
560
|
+
|
|
561
|
+
`source` is the **cross-user deduplication key** for the Plot runtime. Two instances of the same connector that emit the same `source` string will **converge on a single shared thread** across users — that's how two users on the same Gmail message see one shared thread rather than two parallel ones.
|
|
562
|
+
|
|
563
|
+
This means your `source` must be globally unique for the logical external item — not merely unique within a single user's account. Before committing a source pattern, ask yourself: *"Could two different users' connector instances emit this exact string for different external items?"* If yes, you must include a qualifier (workspace, tenant, mailbox, project, …).
|
|
564
|
+
|
|
565
|
+
Safe patterns (globally unique external ids):
|
|
566
|
+
```
|
|
567
|
+
linear:issue:<uuid> — Linear issue UUIDs are globally unique
|
|
568
|
+
github:<owner>/<repo>/issue:<number> — Scoped by owner+repo
|
|
569
|
+
google-chat:<spaceId>:thread:<threadKey> — Space id globally unique
|
|
570
|
+
ms-teams:channel:<channelId>:message:<id> — Teams channel id globally unique
|
|
571
|
+
ms-teams:dm:<chatId> — Chat ids globally unique
|
|
572
|
+
https://mail.google.com/mail/u/0/#inbox/<threadId> — Gmail thread id globally unique
|
|
573
|
+
```
|
|
574
|
+
|
|
575
|
+
Patterns that need disambiguation:
|
|
560
576
|
```
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
outlook-calendar:<eventId>
|
|
566
|
-
google-drive:file:<fileId>
|
|
567
|
-
https://mail.google.com/mail/u/0/#inbox/<threadId> — Gmail uses full URL
|
|
568
|
-
https://slack.com/app_redirect?channel=<id>&message_ts=<ts> — Slack uses full URL
|
|
577
|
+
attio:<workspaceId>:<type>:<recordId> — Attio record ids are workspace-scoped
|
|
578
|
+
posthog:<projectId>:person:<distinctId> — distinct_id is project-scoped (often just an email)
|
|
579
|
+
outlook-calendar:<mailboxId>:<eventId> — Graph event ids are mailbox-local
|
|
580
|
+
fellow:<tenantId>:note:<id> — Fellow ids are tenant-scoped
|
|
569
581
|
```
|
|
570
582
|
|
|
571
|
-
**
|
|
583
|
+
**If you're adding a new connector, pick a source format that encodes the tenant/workspace/mailbox upfront.** Retrofits are possible but require a backfill migration.
|
|
584
|
+
|
|
585
|
+
**Mutable IDs:** For services where identifiers can change (like Jira issue keys that change on project move), use the immutable ID in `source` and store the mutable key in `meta` only.
|
|
586
|
+
|
|
587
|
+
### Attestation-based visibility for shared threads
|
|
588
|
+
|
|
589
|
+
When your connector populates `thread.contacts` from an external item's recipients, listing someone there does NOT automatically admit them to the thread. The runtime requires that each user's own connector instance independently sync the item (proof that it's in their authenticated account) before they gain a `thread_priority` row. Users whose own sync arrives before any other user has attested them land in `thread.pending_contacts` and are promoted to `thread.contacts` on the next attester's sync.
|
|
590
|
+
|
|
591
|
+
You don't need to do anything special for this — just continue to populate `contacts` with every recipient you see. The runtime's `upsert_thread` enforces attestation; connectors can treat visibility as a server-side concern.
|
|
572
592
|
|
|
573
593
|
## Note Key Conventions
|
|
574
594
|
|
|
@@ -98,7 +98,11 @@ The `source` field should be:
|
|
|
98
98
|
|
|
99
99
|
- A canonical URL from the external system (preferred)
|
|
100
100
|
- A stable identifier in a namespaced format (e.g., `gmail:thread-id-123`)
|
|
101
|
-
-
|
|
101
|
+
- **Globally unique for the logical external item** — see "Source identifier uniqueness" below
|
|
102
|
+
|
|
103
|
+
> **Cross-user dedup:** Two instances of the same connector (run by two different Plot users) that emit the same `source` for the same external item will converge on a **single shared thread**. This is how two users on the same Gmail message, calendar event, or Linear issue see one thread rather than two.
|
|
104
|
+
>
|
|
105
|
+
> This means `source` must not merely be unique within one user's account — it must be globally unique for the item. If an external id is workspace- or tenant-scoped (Attio record ids, PostHog distinct_ids, Outlook event ids, Fellow note ids, etc.), include the workspace/tenant/mailbox id as a qualifier: `attio:<workspaceId>:person:<recordId>`, not `attio:person:<recordId>`. See `connectors/AGENTS.md` → "Source identifier uniqueness" for the full guidance.
|
|
102
106
|
|
|
103
107
|
```typescript
|
|
104
108
|
// Activity.source field definition
|