@plotday/twister 0.22.0 → 0.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (186) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +35 -6
  3. package/bin/commands/deploy.js +246 -6
  4. package/bin/commands/deploy.js.map +1 -1
  5. package/bin/commands/generate.js +11 -2
  6. package/bin/commands/generate.js.map +1 -1
  7. package/bin/commands/login.js +19 -3
  8. package/bin/commands/login.js.map +1 -1
  9. package/bin/commands/priority-create.js +7 -2
  10. package/bin/commands/priority-create.js.map +1 -1
  11. package/bin/commands/priority-list.js +6 -1
  12. package/bin/commands/priority-list.js.map +1 -1
  13. package/bin/commands/twist-logs.js +12 -3
  14. package/bin/commands/twist-logs.js.map +1 -1
  15. package/bin/templates/AGENTS.template.md +133 -20
  16. package/bin/utils/bundle.js +40 -0
  17. package/bin/utils/bundle.js.map +1 -1
  18. package/bin/utils/network-error.js +149 -0
  19. package/bin/utils/network-error.js.map +1 -0
  20. package/bin/utils/sse.js +19 -1
  21. package/bin/utils/sse.js.map +1 -1
  22. package/cli/templates/AGENTS.template.md +133 -20
  23. package/dist/common/calendar.d.ts +28 -5
  24. package/dist/common/calendar.d.ts.map +1 -1
  25. package/dist/common/messaging.d.ts +12 -6
  26. package/dist/common/messaging.d.ts.map +1 -1
  27. package/dist/common/projects.d.ts +121 -0
  28. package/dist/common/projects.d.ts.map +1 -0
  29. package/dist/common/projects.js +2 -0
  30. package/dist/common/projects.js.map +1 -0
  31. package/dist/docs/assets/hierarchy.js +1 -1
  32. package/dist/docs/assets/highlight.css +4 -4
  33. package/dist/docs/assets/navigation.js +1 -1
  34. package/dist/docs/assets/search.js +1 -1
  35. package/dist/docs/classes/tool.Tool.html +5 -5
  36. package/dist/docs/classes/tools_ai.AI.html +3 -3
  37. package/dist/docs/classes/tools_callbacks.Callbacks.html +4 -4
  38. package/dist/docs/classes/tools_integrations.Integrations.html +1 -1
  39. package/dist/docs/classes/tools_network.Network.html +4 -4
  40. package/dist/docs/classes/tools_plot.Plot.html +28 -14
  41. package/dist/docs/classes/tools_store.Store.html +1 -1
  42. package/dist/docs/classes/tools_tasks.Tasks.html +2 -2
  43. package/dist/docs/classes/tools_twists.Twists.html +4 -4
  44. package/dist/docs/classes/twist.Twist.html +1 -1
  45. package/dist/docs/documents/Building_Custom_Tools.html +6 -6
  46. package/dist/docs/documents/Built-in_Tools.html +24 -17
  47. package/dist/docs/documents/Core_Concepts.html +42 -9
  48. package/dist/docs/documents/Getting_Started.html +10 -3
  49. package/dist/docs/documents/Runtime_Environment.html +7 -7
  50. package/dist/docs/enums/plot.ActivityLinkType.html +5 -5
  51. package/dist/docs/enums/plot.ActivityType.html +4 -4
  52. package/dist/docs/enums/plot.ActorType.html +4 -4
  53. package/dist/docs/enums/plot.ConferencingProvider.html +6 -6
  54. package/dist/docs/enums/tag.Tag.html +3 -4
  55. package/dist/docs/enums/tools_plot.ActivityAccess.html +3 -3
  56. package/dist/docs/enums/tools_plot.ContactAccess.html +3 -3
  57. package/dist/docs/enums/tools_plot.PriorityAccess.html +3 -3
  58. package/dist/docs/functions/index.Uuid.Generate.html +1 -0
  59. package/dist/docs/hierarchy.html +1 -1
  60. package/dist/docs/interfaces/common_calendar.CalendarTool.html +17 -9
  61. package/dist/docs/interfaces/tools_ai.AIResponse.html +2 -2
  62. package/dist/docs/interfaces/tools_twists.TwistSource.html +1 -1
  63. package/dist/docs/modules/index.Uuid.html +1 -0
  64. package/dist/docs/modules/index.html +1 -1
  65. package/dist/docs/modules/plot.html +1 -1
  66. package/dist/docs/types/index.Uuid.html +1 -0
  67. package/dist/docs/types/plot.Activity.html +21 -7
  68. package/dist/docs/types/plot.ActivityCommon.html +17 -15
  69. package/dist/docs/types/plot.ActivityLink.html +1 -1
  70. package/dist/docs/types/plot.ActivityMeta.html +7 -9
  71. package/dist/docs/types/plot.ActivityUpdate.html +3 -4
  72. package/dist/docs/types/plot.ActivityWithNotes.html +1 -1
  73. package/dist/docs/types/plot.Actor.html +5 -5
  74. package/dist/docs/types/plot.ActorId.html +8 -3
  75. package/dist/docs/types/plot.ContentType.html +1 -0
  76. package/dist/docs/types/plot.NewActivity.html +24 -5
  77. package/dist/docs/types/plot.NewActivityWithNotes.html +1 -1
  78. package/dist/docs/types/plot.NewActor.html +3 -0
  79. package/dist/docs/types/plot.NewContact.html +4 -4
  80. package/dist/docs/types/plot.NewNote.html +15 -4
  81. package/dist/docs/types/plot.NewPriority.html +1 -1
  82. package/dist/docs/types/plot.NewTags.html +2 -0
  83. package/dist/docs/types/plot.Note.html +3 -3
  84. package/dist/docs/types/plot.NoteUpdate.html +6 -6
  85. package/dist/docs/types/plot.PickPriorityConfig.html +3 -3
  86. package/dist/docs/types/plot.Priority.html +3 -3
  87. package/dist/docs/types/plot.SyncUpdate.html +15 -0
  88. package/dist/docs/types/plot.Tags.html +2 -0
  89. package/dist/docs/types/tools_ai.DataContent.html +1 -1
  90. package/dist/docs/types/tools_network.WebhookRequest.html +5 -3
  91. package/dist/docs/types/tools_plot.NoteIntentHandler.html +4 -4
  92. package/dist/llm-docs/common/calendar.d.ts +2 -2
  93. package/dist/llm-docs/common/calendar.d.ts.map +1 -1
  94. package/dist/llm-docs/common/calendar.js +2 -2
  95. package/dist/llm-docs/common/calendar.js.map +1 -1
  96. package/dist/llm-docs/common/messaging.d.ts +2 -2
  97. package/dist/llm-docs/common/messaging.d.ts.map +1 -1
  98. package/dist/llm-docs/common/messaging.js +2 -2
  99. package/dist/llm-docs/common/messaging.js.map +1 -1
  100. package/dist/llm-docs/common/projects.d.ts +9 -0
  101. package/dist/llm-docs/common/projects.d.ts.map +1 -0
  102. package/dist/llm-docs/common/projects.js +8 -0
  103. package/dist/llm-docs/common/projects.js.map +1 -0
  104. package/dist/llm-docs/index.d.ts +1 -1
  105. package/dist/llm-docs/index.js +17 -17
  106. package/dist/llm-docs/index.js.map +1 -1
  107. package/dist/llm-docs/plot.d.ts +2 -2
  108. package/dist/llm-docs/plot.d.ts.map +1 -1
  109. package/dist/llm-docs/plot.js +2 -2
  110. package/dist/llm-docs/plot.js.map +1 -1
  111. package/dist/llm-docs/tag.d.ts +2 -2
  112. package/dist/llm-docs/tag.d.ts.map +1 -1
  113. package/dist/llm-docs/tag.js +2 -2
  114. package/dist/llm-docs/tag.js.map +1 -1
  115. package/dist/llm-docs/tool.d.ts +2 -2
  116. package/dist/llm-docs/tool.d.ts.map +1 -1
  117. package/dist/llm-docs/tool.js +2 -2
  118. package/dist/llm-docs/tool.js.map +1 -1
  119. package/dist/llm-docs/tools/ai.d.ts +2 -2
  120. package/dist/llm-docs/tools/ai.d.ts.map +1 -1
  121. package/dist/llm-docs/tools/ai.js +2 -2
  122. package/dist/llm-docs/tools/ai.js.map +1 -1
  123. package/dist/llm-docs/tools/callbacks.d.ts +2 -2
  124. package/dist/llm-docs/tools/callbacks.d.ts.map +1 -1
  125. package/dist/llm-docs/tools/callbacks.js +2 -2
  126. package/dist/llm-docs/tools/callbacks.js.map +1 -1
  127. package/dist/llm-docs/tools/integrations.d.ts +1 -1
  128. package/dist/llm-docs/tools/integrations.js +1 -1
  129. package/dist/llm-docs/tools/network.d.ts +2 -2
  130. package/dist/llm-docs/tools/network.d.ts.map +1 -1
  131. package/dist/llm-docs/tools/network.js +2 -2
  132. package/dist/llm-docs/tools/network.js.map +1 -1
  133. package/dist/llm-docs/tools/plot.d.ts +2 -2
  134. package/dist/llm-docs/tools/plot.d.ts.map +1 -1
  135. package/dist/llm-docs/tools/plot.js +2 -2
  136. package/dist/llm-docs/tools/plot.js.map +1 -1
  137. package/dist/llm-docs/tools/store.d.ts +1 -1
  138. package/dist/llm-docs/tools/store.js +1 -1
  139. package/dist/llm-docs/tools/tasks.d.ts +1 -1
  140. package/dist/llm-docs/tools/tasks.js +1 -1
  141. package/dist/llm-docs/tools/twists.d.ts +2 -2
  142. package/dist/llm-docs/tools/twists.d.ts.map +1 -1
  143. package/dist/llm-docs/tools/twists.js +2 -2
  144. package/dist/llm-docs/tools/twists.js.map +1 -1
  145. package/dist/llm-docs/twist-guide-template.d.ts +1 -1
  146. package/dist/llm-docs/twist-guide-template.d.ts.map +1 -1
  147. package/dist/llm-docs/twist-guide-template.js +1 -1
  148. package/dist/llm-docs/twist-guide-template.js.map +1 -1
  149. package/dist/llm-docs/twist.d.ts +1 -1
  150. package/dist/llm-docs/twist.js +1 -1
  151. package/dist/plot.d.ts +271 -87
  152. package/dist/plot.d.ts.map +1 -1
  153. package/dist/plot.js +1 -0
  154. package/dist/plot.js.map +1 -1
  155. package/dist/tag.d.ts +2 -3
  156. package/dist/tag.d.ts.map +1 -1
  157. package/dist/tag.js +2 -3
  158. package/dist/tag.js.map +1 -1
  159. package/dist/tool.d.ts +2 -2
  160. package/dist/tool.d.ts.map +1 -1
  161. package/dist/tool.js +1 -1
  162. package/dist/tool.js.map +1 -1
  163. package/dist/tools/ai.d.ts +2 -2
  164. package/dist/tools/ai.d.ts.map +1 -1
  165. package/dist/tools/callbacks.d.ts +1 -1
  166. package/dist/tools/callbacks.d.ts.map +1 -1
  167. package/dist/tools/network.d.ts +2 -0
  168. package/dist/tools/network.d.ts.map +1 -1
  169. package/dist/tools/network.js.map +1 -1
  170. package/dist/tools/plot.d.ts +36 -4
  171. package/dist/tools/plot.d.ts.map +1 -1
  172. package/dist/tools/plot.js.map +1 -1
  173. package/dist/tools/twists.d.ts +2 -2
  174. package/dist/twist-guide.d.ts +1 -1
  175. package/dist/twist-guide.d.ts.map +1 -1
  176. package/dist/utils/uuid.d.ts +7 -0
  177. package/dist/utils/uuid.d.ts.map +1 -0
  178. package/dist/utils/uuid.js +9 -0
  179. package/dist/utils/uuid.js.map +1 -0
  180. package/package.json +60 -3
  181. package/tsconfig.base.json +1 -0
  182. package/dist/docs/types/plot.NoteType.html +0 -1
  183. package/dist/llm-docs/creator-docs.d.ts +0 -9
  184. package/dist/llm-docs/creator-docs.d.ts.map +0 -1
  185. package/dist/llm-docs/creator-docs.js +0 -8
  186. package/dist/llm-docs/creator-docs.js.map +0 -1
@@ -4,5 +4,5 @@
4
4
  * This file is auto-generated during build. Do not edit manually.
5
5
  * Generated from: cli/templates/AGENTS.template.md
6
6
  */
7
- export default "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.\n- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)\n- **Use the Run tool**: Queue separate chunks of work with `run.now(functionName, context)`\n- **Break long operations**: Split large operations into smaller batches that can be processed independently\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## twist Structure Pattern\n\n```typescript\nimport {\n type Activity,\n twist,\n type Priority,\n type ToolBuilder,\n} from \"@plotday/twister\";\nimport { Plot } from \"@plotday/twister/tools/plot\";\n\nexport default class MyTwist extends Twist<MyTwist> {\n build(build: ToolBuilder) {\n return {\n plot: build(Plot),\n };\n }\n\n async activate(priority: Pick<Priority, \"id\">) {\n // Called when twist is enabled for a priority\n // Common actions: request auth, create setup activities\n }\n\n async activity(activity: Activity) {\n // Called when an activity is routed to this twist\n // Common actions: process external events, update activities\n }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n return {\n toolName: build(ToolClass),\n };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n### External Tools (Add to package.json)\n\nAdd tool dependencies to `package.json`:\n\n```json\n{\n \"dependencies\": {\n \"@plotday/twister\": \"workspace:^\",\n \"@plotday/tool-google-calendar\": \"workspace:^\"\n }\n}\n```\n\n#### Common External Tools\n\n- `@plotday/tool-google-calendar`: Google Calendar integration\n- `@plotday/tool-outlook-calendar`: Outlook Calendar integration\n- `@plotday/tool-google-contacts`: Google Contacts integration\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled when the twist is enabled for a priority. Common patterns:\n\n**Request Authentication:**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n const authLink = await this.tools.externalTool.requestAuth(\n this.onAuthComplete,\n \"google\"\n );\n\n await this.tools.plot.createActivity({\n type: ActivityType.Action,\n title: \"Connect your account\",\n links: [authLink],\n });\n}\n```\n\n**Store Parent Activity for Later:**\n\n```typescript\nconst activity = await this.tools.plot.createActivity({\n type: ActivityType.Action,\n title: \"Setup\",\n});\n\nawait this.set(\"setup_activity_id\", activity.id);\n```\n\n### activity(activity: Activity)\n\nCalled when an activity is routed to the twist. Common patterns:\n\n**Create Activities from External Events:**\n\n```typescript\nasync activity(activity: Activity) {\n await this.tools.plot.createActivity(activity);\n}\n```\n\n**Update Based on User Action:**\n\n```typescript\nasync activity(activity: Activity) {\n if (activity.completed) {\n await this.handleCompletion(activity);\n }\n}\n```\n\n## Activity Links\n\nActivity links enable user interaction:\n\n```typescript\nimport { type ActivityLink, ActivityLinkType } from \"@plotday/twister\";\n\n// URL link\nconst urlLink: ActivityLink = {\n title: \"Open website\",\n type: ActivityLinkType.url,\n url: \"https://example.com\",\n};\n\n// Callback link (uses Callbacks tool)\nconst token = await this.callback(this.onLinkClicked, \"context\");\nconst callbackLink: ActivityLink = {\n title: \"Click me\",\n type: ActivityLinkType.callback,\n token: token,\n};\n\n// Add to activity\nawait this.tools.plot.createActivity({\n type: ActivityType.Action,\n title: \"Task with links\",\n links: [urlLink, callbackLink],\n});\n```\n\n## Authentication Pattern\n\nCommon pattern for OAuth authentication:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n // Request auth link from tool with callback\n const authLink = await this.tools.googleTool.requestAuth(\n this.onAuthComplete,\n \"google\"\n );\n\n // Create activity with auth link\n const activity = await this.tools.plot.createActivity({\n type: ActivityType.Action,\n title: \"Connect Google account\",\n links: [authLink],\n });\n\n // Store for later use\n await this.set(\"auth_activity_id\", activity.id);\n}\n\nasync onAuthComplete(authResult: { authToken: string }, provider: string) {\n // Store auth token\n await this.set(`${provider}_auth`, authResult.authToken);\n\n // Continue setup flow\n await this.setupSyncOptions(authResult.authToken);\n}\n```\n\n## Sync Pattern\n\nPattern for syncing external data with callbacks:\n\n```typescript\nasync startSync(calendarId: string): Promise<void> {\n const authToken = await this.get<string>(\"auth_token\");\n\n await this.tools.calendarTool.startSync(\n authToken,\n calendarId,\n this.handleEvent,\n calendarId\n );\n}\n\nasync handleEvent(activity: Activity, calendarId: string): Promise<void> {\n // Process incoming event from external service\n await this.tools.plot.createActivity(activity);\n}\n\nasync stopSync(calendarId: string): Promise<void> {\n const authToken = await this.get<string>(\"auth_token\");\n await this.tools.calendarTool.stopSync(authToken, calendarId);\n}\n```\n\n## Calendar Selection Pattern\n\nPattern for letting users select from multiple calendars/accounts:\n\n```typescript\nprivate async createCalendarSelectionActivity(\n provider: string,\n calendars: Calendar[],\n authToken: string\n): Promise<void> {\n const links: ActivityLink[] = [];\n\n for (const calendar of calendars) {\n const token = await this.callback(\n this.onCalendarSelected,\n provider,\n calendar.id,\n calendar.name,\n authToken\n );\n\n links.push({\n title: `📅 ${calendar.name}${calendar.primary ? \" (Primary)\" : \"\"}`,\n type: ActivityLinkType.callback,\n token: token,\n });\n }\n\n await this.tools.plot.createActivity({\n type: ActivityType.Note,\n title: \"Which calendars would you like to connect?\",\n links,\n });\n}\n\nasync onCalendarSelected(\n link: ActivityLink,\n provider: string,\n calendarId: string,\n calendarName: string,\n authToken: string\n): Promise<void> {\n // Start sync for selected calendar\n await this.tools.tool.startSync(\n authToken,\n calendarId,\n this.handleEvent,\n provider,\n calendarId\n );\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited execution time, you must break long operations into batches. Each batch runs independently in a new execution context.\n\n### Key Principles\n\n1. **Store state between batches**: Use the Store tool to persist progress\n2. **Queue next batch**: Use the Run tool to schedule the next chunk\n3. **Clean up when done**: Delete stored state after completion\n4. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n // Initialize state in Store (persists between executions)\n await this.set(`sync_state_${resourceId}`, {\n nextPageToken: null,\n batchNumber: 1,\n itemsProcessed: 0,\n });\n\n // Queue first batch using runTask method\n const callback = await this.callback(this.syncBatch, resourceId);\n await this.runTask(callback);\n}\n\nasync syncBatch(args: any, resourceId: string): Promise<void> {\n // Load state from Store (set by previous execution)\n const state = await this.get(`sync_state_${resourceId}`);\n\n // Process one batch (keep under time limit)\n const result = await this.fetchBatch(state.nextPageToken);\n\n // Process results\n for (const item of result.items) {\n await this.tools.plot.createActivity(item);\n }\n\n if (result.nextPageToken) {\n // Update state in Store for next batch\n await this.set(`sync_state_${resourceId}`, {\n nextPageToken: result.nextPageToken,\n batchNumber: state.batchNumber + 1,\n itemsProcessed: state.itemsProcessed + result.items.length,\n });\n\n // Queue next batch (runs in new execution context)\n const nextCallback = await this.callback(this.syncBatch, resourceId);\n await this.runTask(nextCallback);\n } else {\n // Cleanup when complete\n await this.clear(`sync_state_${resourceId}`);\n\n // Optionally notify user of completion\n await this.tools.plot.createActivity({\n type: ActivityType.Note,\n note: `Sync complete: ${state.itemsProcessed + result.items.length} items processed`,\n });\n }\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n await this.externalOperation();\n} catch (error) {\n console.error(\"Operation failed:\", error);\n\n await this.tools.plot.createActivity({\n type: ActivityType.Note,\n note: `Failed to complete operation: ${error.message}`,\n });\n}\n```\n\n## Common Pitfalls\n\n- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.\n- **Processing self-created activities** - Other users may change an Activity created by the twist, resulting in an \\`activity\\` call. Be sure to check the \\`changes === null\\` and/or \\`activity.author.id !== this.id\\` to avoid re-processing.\n- Most activity should be `type = ActivityType.Note` with a `title` and `note`, and no `start` or `end`. This represents a typical message. `start` and `end` should only be used for a note if it should be displayed for a specific date or time, such as a birthday.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **Don't forget runtime limits** - Each execution has ~10 seconds. Break long operations into batches with the Tasks tool. Process enough items per batch to be efficient, but few enough to stay under time limits.\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";
7
+ export default "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.\n- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)\n- **Use the Run tool**: Queue separate chunks of work with `run.now(functionName, context)`\n- **Break long operations**: Split large operations into smaller batches that can be processed independently\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## Understanding Activities and Notes\n\n**CRITICAL CONCEPT**: An **Activity** represents something done or to be done (a task, event, or conversation), while **Notes** represent the updates and details on that activity.\n\n**Think of an Activity as a thread** on a messaging platform, and **Notes as the messages in that thread**.\n\n### Key Guidelines\n\n1. **Always create Activities with an initial Note** - The title is just a summary; detailed content goes in Notes\n2. **Add Notes to existing Activities for updates** - Don't create a new Activity for each related message\n3. **Track external items using generated UUIDs** - Store mappings between external IDs and Plot UUIDs for deduplication\n4. **Most Activities should be `ActivityType.Note`** - Use `Action` only for tasks with `doneAt`, use `Event` only for items with `start`/`end`\n\n### Decision Tree\n\n```\nNew event/task/conversation?\n ├─ Yes → Generate UUID with Uuid.Generate()\n │ Create new Activity with that UUID\n │ Store mapping: external_id → activity_uuid\n │\n └─ No (update/reply/comment) → Look up mapping by external_id\n ├─ Found → Add Note to existing Activity using stored UUID\n └─ Not found → Create new Activity with UUID + store mapping\n```\n\n## Twist Structure Pattern\n\n```typescript\nimport {\n type Activity,\n type Priority,\n type ToolBuilder,\n twist,\n} from \"@plotday/twister\";\nimport { Plot } from \"@plotday/twister/tools/plot\";\nimport { Uuid } from \"@plotday/twister/utils/uuid\";\n\nexport default class MyTwist extends Twist<MyTwist> {\n build(build: ToolBuilder) {\n return {\n plot: build(Plot),\n };\n }\n\n async activate(priority: Pick<Priority, \"id\">) {\n // Called when twist is enabled for a priority\n // Common actions: request auth, create setup activities\n }\n\n async activity(activity: Activity) {\n // Called when an activity is routed to this twist\n // Common actions: process external events, update activities\n }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n return {\n toolName: build(ToolClass),\n };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n### External Tools (Add to package.json)\n\nAdd tool dependencies to `package.json`:\n\n```json\n{\n \"dependencies\": {\n \"@plotday/twister\": \"workspace:^\",\n \"@plotday/tool-google-calendar\": \"workspace:^\"\n }\n}\n```\n\n#### Common External Tools\n\n- `@plotday/tool-google-calendar`: Google Calendar integration\n- `@plotday/tool-outlook-calendar`: Outlook Calendar integration\n- `@plotday/tool-google-contacts`: Google Contacts integration\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled when the twist is enabled for a priority. Common patterns:\n\n**Request Authentication:**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n const authLink = await this.tools.externalTool.requestAuth(\n this.onAuthComplete,\n \"google\"\n );\n\n await this.tools.plot.createActivity({\n type: ActivityType.Note,\n title: \"Connect your account\",\n notes: [\n {\n content: \"Click the link below to connect your account and start syncing.\",\n links: [authLink],\n },\n ],\n });\n}\n```\n\n**Store Parent Activity for Later:**\n\n```typescript\nconst activity = await this.tools.plot.createActivity({\n type: ActivityType.Note,\n title: \"Setup\",\n notes: [\n {\n content: \"Your twist is being set up. Configuration steps will appear here.\",\n },\n ],\n});\n\nawait this.set(\"setup_activity_id\", activity.id);\n```\n\n### activity(activity: Activity)\n\nCalled when an activity is routed to the twist. Common patterns:\n\n**Create Activities from External Events:**\n\n```typescript\nasync activity(activity: Activity) {\n await this.tools.plot.createActivity(activity);\n}\n```\n\n**Update Based on User Action:**\n\n```typescript\nasync activity(activity: Activity) {\n if (activity.completed) {\n await this.handleCompletion(activity);\n }\n}\n```\n\n## Activity Links\n\nActivity links enable user interaction:\n\n```typescript\nimport { type ActivityLink, ActivityLinkType } from \"@plotday/twister\";\n\n// URL link\nconst urlLink: ActivityLink = {\n title: \"Open website\",\n type: ActivityLinkType.url,\n url: \"https://example.com\",\n};\n\n// Callback link (uses Callbacks tool)\nconst token = await this.callback(this.onLinkClicked, \"context\");\nconst callbackLink: ActivityLink = {\n title: \"Click me\",\n type: ActivityLinkType.callback,\n token: token,\n};\n\n// Add to activity note\nawait this.tools.plot.createActivity({\n type: ActivityType.Note,\n title: \"Task with links\",\n notes: [\n {\n content: \"Click the links below to take action.\",\n links: [urlLink, callbackLink],\n },\n ],\n});\n```\n\n## Authentication Pattern\n\nCommon pattern for OAuth authentication:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n // Request auth link from tool with callback\n const authLink = await this.tools.googleTool.requestAuth(\n this.onAuthComplete,\n \"google\"\n );\n\n // Create activity with auth link\n const activity = await this.tools.plot.createActivity({\n type: ActivityType.Note,\n title: \"Connect Google account\",\n notes: [\n {\n content: \"Click below to connect your Google account and start syncing.\",\n links: [authLink],\n },\n ],\n });\n\n // Store for later use\n await this.set(\"auth_activity_id\", activity.id);\n}\n\nasync onAuthComplete(authResult: { authToken: string }, provider: string) {\n // Store auth token\n await this.set(`${provider}_auth`, authResult.authToken);\n\n // Continue setup flow\n await this.setupSyncOptions(authResult.authToken);\n}\n```\n\n## Sync Pattern\n\nPattern for syncing external data - demonstrates adding Notes to existing Activities:\n\n```typescript\nasync startSync(calendarId: string): Promise<void> {\n const authToken = await this.get<string>(\"auth_token\");\n\n await this.tools.calendarTool.startSync(\n authToken,\n calendarId,\n this.handleEvent,\n calendarId\n );\n}\n\nasync handleEvent(\n incomingActivity: NewActivityWithNotes,\n calendarId: string\n): Promise<void> {\n // Extract external event ID from meta (adapt based on your tool's data)\n const externalId = incomingActivity.meta?.eventId;\n\n if (!externalId) {\n console.error(\"Event missing external ID\");\n return;\n }\n\n // Check if we've already synced this event\n const mappingKey = `event_mapping:${calendarId}:${externalId}`;\n const existingActivityId = await this.get<Uuid>(mappingKey);\n\n if (existingActivityId) {\n // Event already exists - add update as a Note (add message to thread)\n if (incomingActivity.notes?.[0]?.content) {\n await this.tools.plot.createNote({\n activity: { id: existingActivityId },\n content: incomingActivity.notes[0].content,\n });\n }\n return;\n }\n\n // New event - generate UUID and store mapping\n const activityId = Uuid.Generate();\n await this.set(mappingKey, activityId);\n\n // Create new Activity with initial Note (new thread with first message)\n await this.tools.plot.createActivity({\n ...incomingActivity,\n id: activityId,\n });\n}\n\nasync stopSync(calendarId: string): Promise<void> {\n const authToken = await this.get<string>(\"auth_token\");\n await this.tools.calendarTool.stopSync(authToken, calendarId);\n}\n```\n\n## Calendar Selection Pattern\n\nPattern for letting users select from multiple calendars/accounts:\n\n```typescript\nprivate async createCalendarSelectionActivity(\n provider: string,\n calendars: Calendar[],\n authToken: string\n): Promise<void> {\n const links: ActivityLink[] = [];\n\n for (const calendar of calendars) {\n const token = await this.callback(\n this.onCalendarSelected,\n provider,\n calendar.id,\n calendar.name,\n authToken\n );\n\n links.push({\n title: `📅 ${calendar.name}${calendar.primary ? \" (Primary)\" : \"\"}`,\n type: ActivityLinkType.callback,\n token: token,\n });\n }\n\n await this.tools.plot.createActivity({\n type: ActivityType.Note,\n title: \"Which calendars would you like to connect?\",\n notes: [\n {\n content: \"Select the calendars you want to sync:\",\n links,\n },\n ],\n });\n}\n\nasync onCalendarSelected(\n link: ActivityLink,\n provider: string,\n calendarId: string,\n calendarName: string,\n authToken: string\n): Promise<void> {\n // Start sync for selected calendar\n await this.tools.tool.startSync(\n authToken,\n calendarId,\n this.handleEvent,\n provider,\n calendarId\n );\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited execution time, you must break long operations into batches. Each batch runs independently in a new execution context.\n\n### Key Principles\n\n1. **Store state between batches**: Use the Store tool to persist progress\n2. **Queue next batch**: Use the Run tool to schedule the next chunk\n3. **Clean up when done**: Delete stored state after completion\n4. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n // Initialize state in Store (persists between executions)\n await this.set(`sync_state_${resourceId}`, {\n nextPageToken: null,\n batchNumber: 1,\n itemsProcessed: 0,\n });\n\n // Queue first batch using runTask method\n const callback = await this.callback(this.syncBatch, resourceId);\n await this.runTask(callback);\n}\n\nasync syncBatch(args: any, resourceId: string): Promise<void> {\n // Load state from Store (set by previous execution)\n const state = await this.get(`sync_state_${resourceId}`);\n\n // Process one batch (keep under time limit)\n const result = await this.fetchBatch(state.nextPageToken);\n\n // Process results (create activities with Notes)\n for (const item of result.items) {\n // Check if already synced\n const mappingKey = `item_mapping:${resourceId}:${item.id}`;\n const existingId = await this.get<Uuid>(mappingKey);\n\n if (!existingId) {\n // New item - generate UUID and store mapping\n const activityId = Uuid.Generate();\n await this.set(mappingKey, activityId);\n\n await this.tools.plot.createActivity({\n id: activityId,\n type: ActivityType.Note,\n title: item.title,\n notes: [{ id: Uuid.Generate(), content: item.description }],\n });\n }\n }\n\n if (result.nextPageToken) {\n // Update state in Store for next batch\n await this.set(`sync_state_${resourceId}`, {\n nextPageToken: result.nextPageToken,\n batchNumber: state.batchNumber + 1,\n itemsProcessed: state.itemsProcessed + result.items.length,\n });\n\n // Queue next batch (runs in new execution context)\n const nextCallback = await this.callback(this.syncBatch, resourceId);\n await this.runTask(nextCallback);\n } else {\n // Cleanup when complete\n await this.clear(`sync_state_${resourceId}`);\n\n // Optionally notify user of completion\n await this.tools.plot.createActivity({\n type: ActivityType.Note,\n title: \"Sync complete\",\n notes: [\n {\n content: `Successfully processed ${state.itemsProcessed + result.items.length} items.`,\n },\n ],\n });\n }\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n await this.externalOperation();\n} catch (error) {\n console.error(\"Operation failed:\", error);\n\n await this.tools.plot.createActivity({\n type: ActivityType.Note,\n title: \"Operation failed\",\n notes: [\n {\n content: `Failed to complete operation: ${error.message}`,\n },\n ],\n });\n}\n```\n\n## Common Pitfalls\n\n- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.\n- **Processing self-created activities** - Other users may change an Activity created by the twist, resulting in an \\`activity\\` call. Be sure to check the \\`changes === null\\` and/or \\`activity.author.id !== this.id\\` to avoid re-processing.\n- **Always create Activities with Notes** - See \"Understanding Activities and Notes\" section above for the thread/message pattern and decision tree.\n- **Use correct Activity types** - Most should be `ActivityType.Note`. Only use `Action` for tasks with `doneAt`, and `Event` for items with `start`/`end`.\n- **Track external items with UUID mappings** - Generate UUIDs with `Uuid.Generate()` and store mappings (`external_id → uuid`) for deduplication. Never rely on the `source` field.\n- **Add Notes to existing Activities** - Look up stored UUID mappings before creating new Activities. Think thread replies, not new threads.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **Don't forget runtime limits** - Each execution has ~10 seconds. Break long operations into batches with the Tasks tool. Process enough items per batch to be efficient, but few enough to stay under time limits.\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";
8
8
  //# sourceMappingURL=twist-guide-template.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"twist-guide-template.js","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,+mZAA+mZ,CAAC"}
1
+ {"version":3,"file":"twist-guide-template.js","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,2/gBAA2/gB,CAAC"}
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Generated LLM documentation for @plotday/sdk/twist
2
+ * Generated LLM documentation for @plotday/twister/twist
3
3
  *
4
4
  * This file is auto-generated during build. Do not edit manually.
5
5
  * Generated from: prebuild.ts
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Generated LLM documentation for @plotday/sdk/twist
2
+ * Generated LLM documentation for @plotday/twister/twist
3
3
  *
4
4
  * This file is auto-generated during build. Do not edit manually.
5
5
  * Generated from: prebuild.ts
package/dist/plot.d.ts CHANGED
@@ -1,11 +1,16 @@
1
1
  import { type Tag } from "./tag";
2
2
  import { type Callback } from "./tools/callbacks";
3
+ import { Uuid } from "./utils/uuid";
3
4
  export { Tag } from "./tag";
5
+ export { Uuid } from "./utils/uuid";
4
6
  /**
5
7
  * Represents a unique user, contact, or twist in Plot.
6
8
  *
7
- * Note contacts (i.e. people not using Plot) are also represented by ActorIds. They may be
8
- * people interacting with other connected services (e.g. an email sender or event attendee).
9
+ * ActorIds are used throughout Plot for:
10
+ * - Activity authors and assignees
11
+ * - Tag creators (actor_id in activity_tag/note_tag)
12
+ * - Mentions in activities and notes
13
+ * - Any entity that can perform actions in Plot
9
14
  */
10
15
  export type ActorId = string & {
11
16
  readonly __brand: "ActorId";
@@ -158,84 +163,125 @@ export type ActivityLink = {
158
163
  /**
159
164
  * Represents metadata about an activity, typically from an external system.
160
165
  *
161
- * Activity metadata enables tracking where activities originated from,
162
- * which is useful for synchronization, deduplication, and linking
163
- * back to external systems.
166
+ * Activity metadata enables storing additional information about activities,
167
+ * which is useful for synchronization, linking back to external systems,
168
+ * and storing tool-specific data.
164
169
  *
165
170
  * @example
166
171
  * ```typescript
167
- * const googleCalendarMeta: ActivityMeta = {
168
- * type: "google-calendar-event",
169
- * id: "event-123",
170
- * calendarId: "primary",
171
- * htmlLink: "https://calendar.google.com/event/123"
172
- * };
172
+ * // Calendar event metadata
173
+ * await plot.createActivity({
174
+ * type: ActivityType.Event,
175
+ * title: "Team Meeting",
176
+ * start: new Date("2024-01-15T10:00:00Z"),
177
+ * meta: {
178
+ * calendarId: "primary",
179
+ * htmlLink: "https://calendar.google.com/event/abc123",
180
+ * conferenceData: { ... }
181
+ * }
182
+ * });
183
+ *
184
+ * // Project issue metadata
185
+ * await plot.createActivity({
186
+ * type: ActivityType.Action,
187
+ * title: "Fix login bug",
188
+ * meta: {
189
+ * projectId: "TEAM",
190
+ * issueNumber: 123,
191
+ * url: "https://linear.app/team/issue/TEAM-123"
192
+ * }
193
+ * });
173
194
  * ```
174
195
  */
175
196
  export type ActivityMeta = {
176
- /** The type identifier for the source system */
177
- source: string;
178
- /** Additional source-specific properties */
197
+ /** Source-specific properties and metadata */
179
198
  [key: string]: any;
180
199
  };
181
200
  /**
182
- * Represents a complete activity within the Plot system.
183
- *
184
- * Activities are the core entities in Plot, representing anything from simple notes
185
- * to complex recurring events. They support rich metadata including scheduling,
186
- * recurrence patterns, links, and external source tracking.
187
- *
188
- * @example
189
- * ```typescript
190
- * // Simple note
191
- * const task: Activity = {
192
- * type: ActivityType.Note,
193
- * title: "New campaign brainstorming ideas",
194
- * note: "We could rent a bouncy castle...",
195
- * author: { id: "user-1", name: "John Doe", type: ActorType.User },
196
- * priority: { id: "work", title: "Work" },
197
- * // ... other fields
198
- * };
199
- *
200
- * // Simple action
201
- * const action: Activity = {
202
- * type: ActivityType.Action,
203
- * title: "Review budget proposal",
204
- * author: { id: "user-1", name: "John Doe", type: ActorType.User },
205
- * priority: { id: "work", title: "Work" },
206
- * // ... other fields
207
- * };
208
- *
209
- * // Recurring event
210
- * const meeting: Activity = {
211
- * type: ActivityType.Event,
212
- * title: "Weekly standup",
213
- * recurrenceRule: "FREQ=WEEKLY;BYDAY=MO",
214
- * recurrenceCount: 12,
215
- * // ... other fields
216
- * };
217
- * ```
201
+ * Tags on an item, along with the actors who added each tag.
202
+ */
203
+ export type Tags = {
204
+ [K in Tag]?: ActorId[];
205
+ };
206
+ /**
207
+ * A set of tags to add to an item, along with the actors adding each tag.
208
+ */
209
+ export type NewTags = {
210
+ [K in Tag]?: NewActor[];
211
+ };
212
+ /**
213
+ * Common fields shared by both Activity and Note entities.
218
214
  */
219
215
  export type ActivityCommon = {
220
216
  /** Unique identifier for the activity */
221
- id: string;
217
+ id: Uuid;
218
+ /**
219
+ * When this activity was originally created in its source system.
220
+ *
221
+ * For activities created in Plot, this is when the user created it.
222
+ * For activities synced from external systems (GitHub issues, emails, calendar events),
223
+ * this is the original creation time in that system.
224
+ *
225
+ * Defaults to the current time when creating new activities.
226
+ */
227
+ createdAt: Date;
222
228
  /** Information about who created the activity */
223
229
  author: Actor;
224
230
  /** Whether this activity is in draft state (not shown in do now view) */
225
231
  draft: boolean;
226
232
  /** Whether this activity is private (only visible to author) */
227
233
  private: boolean;
234
+ /** Whether this activity has been archived */
235
+ archived: boolean;
228
236
  /** Tags attached to this activity. Maps tag ID to array of actor IDs who added that tag. */
229
- tags: Partial<Record<Tag, ActorId[]>> | null;
237
+ tags: Tags;
230
238
  /** Array of actor IDs (users, contacts, or twists) mentioned in this activity via @-mentions */
231
- mentions: ActorId[] | null;
239
+ mentions: ActorId[];
232
240
  };
233
241
  export type Activity = ActivityCommon & {
234
242
  /** The display title/summary of the activity */
235
- title: string | null;
243
+ title: string;
236
244
  /** The type of activity (Note, Task, or Event) */
237
245
  type: ActivityType;
238
- /** Who this activity note is assigned to */
246
+ /**
247
+ * The actor assigned to this activity.
248
+ *
249
+ * **For actions (tasks):** An assignee is required. If not explicitly provided when creating
250
+ * an action, the assignee will default to the user who installed the twist (the twist owner).
251
+ *
252
+ * **For notes and events:** Assignee is optional and typically null.
253
+ *
254
+ * @example
255
+ * ```typescript
256
+ * // Create action with explicit assignee
257
+ * const task: NewActivity = {
258
+ * type: ActivityType.Action,
259
+ * title: "Review PR #123",
260
+ * assignee: {
261
+ * id: userId as ActorId,
262
+ * type: ActorType.User,
263
+ * name: "Alice"
264
+ * }
265
+ * };
266
+ *
267
+ * // Create action with auto-assignment (defaults to twist owner)
268
+ * const task: NewActivity = {
269
+ * type: ActivityType.Action,
270
+ * title: "Follow up on email"
271
+ * // assignee will be set automatically to twist owner
272
+ * };
273
+ *
274
+ * // Update assignee
275
+ * await plot.updateActivity({
276
+ * id: activityId,
277
+ * assignee: {
278
+ * id: newUserId as ActorId,
279
+ * type: ActorType.User,
280
+ * name: "Bob"
281
+ * }
282
+ * });
283
+ * ```
284
+ */
239
285
  assignee: Actor | null;
240
286
  /** Timestamp when the activity was marked as complete. Null if not completed. */
241
287
  doneAt: Date | null;
@@ -243,7 +289,31 @@ export type Activity = ActivityCommon & {
243
289
  * Start time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.
244
290
  * For recurring events, this represents the start of the first occurrence.
245
291
  * Can be a Date object for timed events or a date string in "YYYY-MM-DD" format for all-day events.
246
- * Null for activities without scheduled start times.
292
+ *
293
+ * **Activity Scheduling States** (for Actions):
294
+ * - **Do Now** (current/actionable): When creating a NewActivity of type Action, omitting `start` defaults to current time
295
+ * - **Do Later** (future scheduled): Set `start` to a future Date or date string
296
+ * - **Do Someday** (unscheduled backlog): Explicitly set `start: null`
297
+ *
298
+ * @example
299
+ * ```typescript
300
+ * // "Do Now" - defaults to current time when start is omitted
301
+ * await this.tools.plot.createActivity({ type: ActivityType.Action, title: "Urgent task" });
302
+ *
303
+ * // "Do Later" - scheduled for a specific time
304
+ * await this.tools.plot.createActivity({
305
+ * type: ActivityType.Action,
306
+ * title: "Future task",
307
+ * start: new Date("2025-02-01")
308
+ * });
309
+ *
310
+ * // "Do Someday" - unscheduled backlog item
311
+ * await this.tools.plot.createActivity({
312
+ * type: ActivityType.Action,
313
+ * title: "Backlog task",
314
+ * start: null
315
+ * });
316
+ * ```
247
317
  */
248
318
  start: Date | string | null;
249
319
  /**
@@ -330,8 +400,19 @@ export type PickPriorityConfig = {
330
400
  * Type for creating new activities.
331
401
  *
332
402
  * Requires only the activity type, with all other fields optional.
333
- * The ID and author will be automatically assigned by the Plot system
334
- * based on the current execution context.
403
+ * The author will be automatically assigned by the Plot system based on
404
+ * the current execution context. The ID can be optionally provided by
405
+ * tools for tracking and update detection purposes.
406
+ *
407
+ * **Important: Scheduling Defaults for Actions**
408
+ *
409
+ * When creating an Activity of type `Action`, the `start` field determines its scheduling state:
410
+ * - **Omit `start`** → Defaults to current time → "Do Now" (appears in today's actionable list)
411
+ * - **Set `start: null`** → Unscheduled → "Do Someday" (backlog item, no specific time)
412
+ * - **Set `start` to future Date** → Scheduled → "Do Later" (appears on that date)
413
+ *
414
+ * For most external task integrations (project management, issue trackers), use `start: null`
415
+ * to create backlog items unless the task is explicitly marked as current/active.
335
416
  *
336
417
  * Priority can be specified in three ways:
337
418
  * 1. Explicit priority: `priority: { id: "..." }` - Use specific priority (disables pickPriority)
@@ -340,43 +421,78 @@ export type PickPriorityConfig = {
340
421
  *
341
422
  * @example
342
423
  * ```typescript
343
- * // Explicit priority (disables automatic matching)
344
- * const newTask: NewActivity = {
424
+ * // "Do Now" - Action defaults to current time (actionable today)
425
+ * const urgentTask: NewActivity = {
426
+ * type: ActivityType.Action,
427
+ * title: "Review pull request"
428
+ * // Omitting start defaults to new Date()
429
+ * };
430
+ *
431
+ * // "Do Someday" - Backlog item (recommended for most synced tasks)
432
+ * const backlogTask: NewActivity = {
433
+ * type: ActivityType.Action,
434
+ * title: "Refactor user service",
435
+ * start: null // Explicitly set to null for backlog
436
+ * };
437
+ *
438
+ * // "Do Later" - Scheduled for specific date
439
+ * const futureTask: NewActivity = {
345
440
  * type: ActivityType.Action,
346
- * title: "Review pull request",
347
- * priority: { id: "work-project-123" }
441
+ * title: "Prepare Q1 review",
442
+ * start: new Date("2025-03-15")
348
443
  * };
349
444
  *
350
- * // Automatic priority matching (default behavior)
351
- * const newNote: NewActivity = {
445
+ * // Note (typically unscheduled)
446
+ * const note: NewActivity = {
352
447
  * type: ActivityType.Note,
353
448
  * title: "Meeting notes",
354
- * note: "Discussed Q4 roadmap..."
355
- * // Defaults to pickPriority: { content: true }
449
+ * content: "Discussed Q4 roadmap...",
450
+ * start: null // Notes typically don't have scheduled times
356
451
  * };
357
452
  *
358
- * // Custom priority matching
359
- * const newEvent: NewActivity = {
453
+ * // Event (always has explicit start/end times)
454
+ * const event: NewActivity = {
360
455
  * type: ActivityType.Event,
361
456
  * title: "Team standup",
362
- * pickPriority: { type: true, content: 50 }
457
+ * start: new Date("2025-01-15T10:00:00"),
458
+ * end: new Date("2025-01-15T10:30:00")
363
459
  * };
364
460
  * ```
365
461
  */
366
- export type NewActivity = Pick<Activity, "type"> & Partial<Omit<Activity, "id" | "author" | "type" | "priority" | "mentions">> & ({
462
+ export type NewActivity = Pick<Activity, "type"> & Partial<Omit<Activity, "author" | "assignee" | "type" | "priority" | "tags" | "mentions">> & ({
367
463
  /** Explicit priority (required when specified) - disables automatic priority matching */
368
464
  priority: Pick<Priority, "id">;
369
465
  } | {
370
466
  /** Configuration for automatic priority selection based on similarity */
371
467
  pickPriority?: PickPriorityConfig;
372
- } | {});
373
- export type ActivityUpdate = Pick<Activity, "id"> & Partial<Pick<Activity, "type" | "start" | "end" | "doneAt" | "title" | "draft" | "private" | "meta" | "recurrenceRule" | "recurrenceDates" | "recurrenceExdates" | "recurrenceUntil" | "recurrenceCount" | "occurrence">> & {
468
+ } | {}) & {
374
469
  /**
375
- * Full tags object from Activity. Maps tag ID to array of actor IDs who added that tag.
376
- * Only allowed for activities created by the twist.
377
- * Use twistTags instead for adding/removing the twist's tags on other activities.
470
+ * The person that created the item. By default, it will be the twist itself.
378
471
  */
379
- tags?: Partial<Record<Tag, ActorId[]>>;
472
+ author?: NewActor;
473
+ /**
474
+ * The person that assigned to the item.
475
+ */
476
+ assignee?: NewActor | null;
477
+ /**
478
+ * All tags to set on the new activity.
479
+ */
480
+ tags?: NewTags;
481
+ /**
482
+ * Whether the activity should be marked as unread for users.
483
+ * - true (default): Activity is unread for all users in the priority
484
+ * - false: Activity is marked as read for all users in the priority at creation time
485
+ *
486
+ * Use false for historical imports to avoid marking old items as unread.
487
+ */
488
+ unread?: boolean;
489
+ };
490
+ export type ActivityUpdate = Pick<Activity, "id"> & Partial<Pick<Activity, "type" | "start" | "end" | "doneAt" | "title" | "assignee" | "draft" | "private" | "meta" | "recurrenceRule" | "recurrenceDates" | "recurrenceExdates" | "recurrenceUntil" | "recurrenceCount" | "occurrence">> & {
491
+ /**
492
+ * Tags to change on the activity. Use an empty array of NewActor to remove a tag.
493
+ * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.
494
+ */
495
+ tags?: NewTags;
380
496
  /**
381
497
  * Add or remove the twist's tags.
382
498
  * Maps tag ID to boolean: true = add tag, false = remove tag.
@@ -384,17 +500,53 @@ export type ActivityUpdate = Pick<Activity, "id"> & Partial<Pick<Activity, "type
384
500
  */
385
501
  twistTags?: Partial<Record<Tag, boolean>>;
386
502
  };
503
+ /**
504
+ * Represents a sync update from a tool.
505
+ *
506
+ * Tools that sync from external sources can send either:
507
+ * - A new activity with notes (for newly discovered items)
508
+ * - An update to an existing activity with optional new notes (for changed items)
509
+ *
510
+ * This allows tools to manage their own update detection logic locally,
511
+ * providing Plot with the appropriate operation to perform.
512
+ *
513
+ * @example
514
+ * ```typescript
515
+ * // Send a new activity
516
+ * const newItem: SyncUpdate = {
517
+ * type: ActivityType.Event,
518
+ * title: "New Meeting",
519
+ * id: Uuid.Generate(), // Tool-generated ID
520
+ * notes: [{ id: Uuid.Generate(), content: "Description" }]
521
+ * };
522
+ *
523
+ * // Send an update to existing activity
524
+ * const update: SyncUpdate = {
525
+ * activityId: existingActivityId,
526
+ * update: { title: "Updated Meeting Title" },
527
+ * notes: [{ id: Uuid.Generate(), content: "New comment" }]
528
+ * };
529
+ * ```
530
+ */
531
+ export type SyncUpdate = NewActivityWithNotes | {
532
+ /** ID of the activity to update */
533
+ activityId: string;
534
+ /** Optional updates to the activity itself */
535
+ update?: ActivityUpdate;
536
+ /** Optional new notes to add to the activity */
537
+ notes?: NewNote[];
538
+ };
387
539
  /**
388
540
  * Represents a note within an activity.
389
541
  *
390
542
  * Notes contain the detailed content (note text, links) associated with an activity.
391
543
  * They are always ordered by creation time within their parent activity.
392
544
  */
393
- export type Note = Omit<ActivityCommon, "type"> & {
545
+ export type Note = ActivityCommon & {
394
546
  /** The parent activity this note belongs to */
395
547
  activity: Activity;
396
548
  /** Primary content for the note (markdown) */
397
- note: string | null;
549
+ content: string | null;
398
550
  /** Array of interactive links attached to the note */
399
551
  links: Array<ActivityLink> | null;
400
552
  };
@@ -402,41 +554,66 @@ export type Note = Omit<ActivityCommon, "type"> & {
402
554
  * Type for creating new notes.
403
555
  *
404
556
  * Requires the activity reference, with all other fields optional.
557
+ * The id field can be optionally provided by tools for tracking purposes.
405
558
  */
406
- export type NewNote = Partial<Omit<Note, "id" | "author" | "activity">> & {
559
+ export type NewNote = Partial<Omit<Note, "author" | "activity" | "tags" | "mentions">> & {
407
560
  /** Reference to the parent activity (required) */
408
561
  activity: Pick<Activity, "id">;
562
+ /**
563
+ * The person that created the item, or leave undefined to use the twist as author.
564
+ */
565
+ author?: NewActor;
409
566
  /**
410
567
  * Format of the note content. Determines how the note is processed:
411
568
  * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)
412
569
  * - 'markdown': Already in markdown format (default, no conversion)
413
570
  * - 'html': HTML content that will be converted to markdown
414
571
  */
415
- noteType?: NoteType;
572
+ contentType?: ContentType;
573
+ /**
574
+ * Tags to change on the activity. Use an empty array of NewActor to remove a tag.
575
+ * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.
576
+ */
577
+ tags?: NewTags;
578
+ /**
579
+ * Change the mentions on the note.
580
+ */
581
+ mentions?: NewActor[];
582
+ /**
583
+ * Whether the note should mark the parent activity as unread for users.
584
+ * - true (default): Activity becomes unread for users who haven't authored the note
585
+ * - false: Activity is marked as read for all users in the priority at note creation time
586
+ *
587
+ * Use false for historical imports to avoid marking old items as unread.
588
+ */
589
+ unread?: boolean;
416
590
  };
417
591
  /**
418
592
  * Type for updating existing notes.
419
593
  */
420
- export type NoteUpdate = Pick<Note, "id"> & Partial<Pick<Note, "draft" | "private" | "note" | "links" | "mentions">> & {
594
+ export type NoteUpdate = Pick<Note, "id"> & Partial<Pick<Note, "draft" | "private" | "content" | "links">> & {
421
595
  /**
422
596
  * Format of the note content. Determines how the note is processed:
423
597
  * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)
424
598
  * - 'markdown': Already in markdown format (default, no conversion)
425
599
  * - 'html': HTML content that will be converted to markdown
426
600
  */
427
- noteType?: NoteType;
601
+ contentType?: ContentType;
428
602
  /**
429
- * Full tags object from Note. Maps tag ID to array of actor IDs who added that tag.
430
- * Only allowed for notes created by the twist.
431
- * Use twistTags instead for adding/removing the twist's tags on other notes.
603
+ * Tags to change on the note. Use an empty array of NewActor to remove a tag.
604
+ * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.
432
605
  */
433
- tags?: Partial<Record<Tag, ActorId[]>>;
606
+ tags?: NewTags;
434
607
  /**
435
608
  * Add or remove the twist's tags.
436
609
  * Maps tag ID to boolean: true = add tag, false = remove tag.
437
610
  * This is allowed on all notes the twist has access to.
438
611
  */
439
612
  twistTags?: Partial<Record<Tag, boolean>>;
613
+ /**
614
+ * Change the mentions on the note.
615
+ */
616
+ mentions?: NewActor[];
440
617
  };
441
618
  /**
442
619
  * Represents an actor in Plot - a user, contact, or twist.
@@ -464,6 +641,13 @@ export type Actor = {
464
641
  /** Display name (undefined if not included due to permissions, null if not set) */
465
642
  name?: string | null;
466
643
  };
644
+ /**
645
+ * An existing or new contact.
646
+ */
647
+ export type NewActor = {
648
+ /** Unique identifier for the actor */
649
+ id: ActorId;
650
+ } | NewContact;
467
651
  /**
468
652
  * Enumeration of author types that can create activities.
469
653
  *
@@ -501,5 +685,5 @@ export type NewContact = {
501
685
  /** Optional avatar image URL for the contact */
502
686
  avatar?: string;
503
687
  };
504
- export type NoteType = "text" | "markdown" | "html";
688
+ export type ContentType = "text" | "markdown" | "html";
505
689
  //# sourceMappingURL=plot.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../src/plot.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../src/plot.ts"],"names":[],"mappings":"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"}
package/dist/plot.js CHANGED
@@ -1,4 +1,5 @@
1
1
  export { Tag } from "./tag";
2
+ export { Uuid } from "./utils/uuid";
2
3
  /**
3
4
  * Enumeration of supported activity types in Plot.
4
5
  *
package/dist/plot.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"plot.js","sourceRoot":"","sources":["../src/plot.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAkC5B;;;;;GAKG;AACH,MAAM,CAAN,IAAY,YAOX;AAPD,WAAY,YAAY;IACtB,qEAAqE;IACrE,+CAAI,CAAA;IACJ,+CAA+C;IAC/C,mDAAM,CAAA;IACN,8DAA8D;IAC9D,iDAAK,CAAA;AACP,CAAC,EAPW,YAAY,KAAZ,YAAY,QAOvB;AAED;;;;;GAKG;AACH,MAAM,CAAN,IAAY,gBASX;AATD,WAAY,gBAAgB;IAC1B,8CAA8C;IAC9C,yCAAqB,CAAA;IACrB,mDAAmD;IACnD,iCAAa,CAAA;IACb,6DAA6D;IAC7D,yCAAqB,CAAA;IACrB,+DAA+D;IAC/D,iDAA6B,CAAA;AAC/B,CAAC,EATW,gBAAgB,KAAhB,gBAAgB,QAS3B;AAED;;;;;GAKG;AACH,MAAM,CAAN,IAAY,oBAWX;AAXD,WAAY,oBAAoB;IAC9B,kBAAkB;IAClB,iDAAyB,CAAA;IACzB,WAAW;IACX,qCAAa,CAAA;IACb,sBAAsB;IACtB,yDAAiC,CAAA;IACjC,kBAAkB;IAClB,uCAAe,CAAA;IACf,6CAA6C;IAC7C,uCAAe,CAAA;AACjB,CAAC,EAXW,oBAAoB,KAApB,oBAAoB,QAW/B;AAibD;;;;;GAKG;AACH,MAAM,CAAN,IAAY,SAOX;AAPD,WAAY,SAAS;IACnB,wCAAwC;IACxC,yCAAI,CAAA;IACJ,8CAA8C;IAC9C,+CAAO,CAAA;IACP,6CAA6C;IAC7C,2CAAK,CAAA;AACP,CAAC,EAPW,SAAS,KAAT,SAAS,QAOpB"}
1
+ {"version":3,"file":"plot.js","sourceRoot":"","sources":["../src/plot.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAqCpC;;;;;GAKG;AACH,MAAM,CAAN,IAAY,YAOX;AAPD,WAAY,YAAY;IACtB,qEAAqE;IACrE,+CAAI,CAAA;IACJ,+CAA+C;IAC/C,mDAAM,CAAA;IACN,8DAA8D;IAC9D,iDAAK,CAAA;AACP,CAAC,EAPW,YAAY,KAAZ,YAAY,QAOvB;AAED;;;;;GAKG;AACH,MAAM,CAAN,IAAY,gBASX;AATD,WAAY,gBAAgB;IAC1B,8CAA8C;IAC9C,yCAAqB,CAAA;IACrB,mDAAmD;IACnD,iCAAa,CAAA;IACb,6DAA6D;IAC7D,yCAAqB,CAAA;IACrB,+DAA+D;IAC/D,iDAA6B,CAAA;AAC/B,CAAC,EATW,gBAAgB,KAAhB,gBAAgB,QAS3B;AAED;;;;;GAKG;AACH,MAAM,CAAN,IAAY,oBAWX;AAXD,WAAY,oBAAoB;IAC9B,kBAAkB;IAClB,iDAAyB,CAAA;IACzB,WAAW;IACX,qCAAa,CAAA;IACb,sBAAsB;IACtB,yDAAiC,CAAA;IACjC,kBAAkB;IAClB,uCAAe,CAAA;IACf,6CAA6C;IAC7C,uCAAe,CAAA;AACjB,CAAC,EAXW,oBAAoB,KAApB,oBAAoB,QAW/B;AAwnBD;;;;;GAKG;AACH,MAAM,CAAN,IAAY,SAOX;AAPD,WAAY,SAAS;IACnB,wCAAwC;IACxC,yCAAI,CAAA;IACJ,8CAA8C;IAC9C,+CAAO,CAAA;IACP,6CAA6C;IAC7C,2CAAK,CAAA;AACP,CAAC,EAPW,SAAS,KAAT,SAAS,QAOpB"}