@plotday/twister 0.38.0 → 0.40.0

package/dist/docs/media/AGENTS.md

@@ -1,20 +1,20 @@
-# Source Development Guide
+# Connector Development Guide
 
-This guide covers everything needed to build a Plot source correctly.
+This guide covers everything needed to build a Plot connector correctly.
 
 **For twist development**: See `../twister/cli/templates/AGENTS.template.md`
 **For general navigation**: See `../AGENTS.md`
 **For type definitions**: See `../twister/src/tools/*.ts` (comprehensive JSDoc)
 
-## Quick Start: Complete Source Scaffold
+## Quick Start: Complete Connector Scaffold
 
-Every source follows this structure:
+Every connector follows this structure:
 
 ```
-sources/<name>/
+connectors/<name>/
   src/
     index.ts              # Re-exports: export { default, ClassName } from "./class-file"
-    <class-name>.ts       # Main Source class
+    <class-name>.ts       # Main Connector class
     <api-name>.ts         # (optional) Separate API client + transform functions
   package.json
   tsconfig.json
@@ -26,7 +26,7 @@ sources/<name>/
 
 ```json
 {
-  "name": "@plotday/source-<name>",
+  "name": "@plotday/connector-<name>",
   "displayName": "Human Name",
   "description": "One-line purpose statement",
   "author": "Plot <team@plot.day> (https://plot.day)",
@@ -37,7 +37,7 @@ sources/<name>/
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "@plotday/source": "./src/index.ts",
+      "@plotday/connector": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     }
@@ -56,18 +56,18 @@ sources/<name>/
   "repository": {
     "type": "git",
     "url": "https://github.com/plotday/plot.git",
-    "directory": "sources/<name>"
+    "directory": "connectors/<name>"
   },
   "homepage": "https://plot.day",
-  "keywords": ["plot", "source", "<name>"],
+  "keywords": ["plot", "connector", "<name>"],
   "publishConfig": { "access": "public" }
 }
 ```
 
 **Notes:**
-- `"@plotday/source"` export condition resolves to TypeScript source during workspace development
+- `"@plotday/connector"` export condition resolves to TypeScript source during workspace development
 - Add third-party SDKs to `dependencies` (e.g., `"@linear/sdk": "^72.0.0"`)
-- Add `@plotday/source-google-contacts` as `"workspace:^"` if your source syncs contacts (Google sources only)
+- Add `@plotday/connector-google-contacts` as `"workspace:^"` if your connector syncs contacts (Google connectors only)
 
 ### tsconfig.json
 
@@ -85,10 +85,10 @@ sources/<name>/
 ### src/index.ts
 
 ```typescript
-export { default, SourceName } from "./source-name";
+export { default, ConnectorName } from "./connector-name";
 ```
 
-## Source Class Template
+## Connector Class Template
 
 ```typescript
 import {
@@ -98,8 +98,8 @@ import {
   type NewActivityWithNotes,
   type NewNote,
   type SyncToolOptions,
-  Source,
-  type SourceBuilder,
+  Connector,
+  type ConnectorBuilder,
 } from "@plotday/twister";
 import type { NewContact } from "@plotday/twister/plot";
 import { type Callback, Callbacks } from "@plotday/twister/tools/callbacks";
@@ -121,7 +121,7 @@ type SyncState = {
   initialSync: boolean;
 };
 
-export class MySource extends Source<MySource> {
+export class MyConnector extends Connector<MyConnector> {
   // 1. Static constants
   static readonly PROVIDER = AuthProvider.Linear; // Use appropriate provider
   static readonly SCOPES = ["read", "write"];
@@ -129,12 +129,12 @@ export class MySource extends Source<MySource> {
   declare readonly Options: SyncToolOptions;
 
   // 2. Declare dependencies
-  build(build: SourceBuilder) {
+  build(build: ConnectorBuilder) {
     return {
       integrations: build(Integrations, {
         providers: [{
-          provider: MySource.PROVIDER,
-          scopes: MySource.SCOPES,
+          provider: MyConnector.PROVIDER,
+          scopes: MyConnector.SCOPES,
           getChannels: this.getChannels,
           onChannelEnabled: this.onChannelEnabled,
           onChannelDisabled: this.onChannelDisabled,
@@ -149,7 +149,7 @@ export class MySource extends Source<MySource> {
 
   // 3. Create API client using channel-based auth
   private async getClient(channelId: string): Promise<any> {
-    const token = await this.tools.integrations.get(MySource.PROVIDER, channelId);
+    const token = await this.tools.integrations.get(MyConnector.PROVIDER, channelId);
     if (!token) throw new Error("No authentication token available");
     return new SomeApiClient({ accessToken: token.token });
   }
@@ -371,16 +371,16 @@ export class MySource extends Source<MySource> {
   }
 }
 
-export default MySource;
+export default MyConnector;
 ```
 
 ## The Integrations Pattern (Auth + Channels)
 
-**This is how ALL authentication works.** Auth is handled in the Flutter edit modal, not in code. Sources declare their provider config in `build()`.
+**This is how ALL authentication works.** Auth is handled in the Flutter edit modal, not in code. Connectors declare their provider config in `build()`.
 
 ### How It Works
 
-1. Source declares providers in `build()` with `getChannels`, `onChannelEnabled`, `onChannelDisabled` callbacks
+1. Connector declares providers in `build()` with `getChannels`, `onChannelEnabled`, `onChannelDisabled` callbacks
 2. User clicks "Connect" in the twist edit modal → OAuth flow happens automatically
 3. After auth, the runtime calls your `getChannels()` to list available resources
 4. User enables resources in the modal → `onChannelEnabled()` fires
@@ -397,7 +397,7 @@ For bidirectional sync where actions should be attributed to the acting user:
 
 ```typescript
 await this.tools.integrations.actAs(
-  MySource.PROVIDER,
+  MyConnector.PROVIDER,
   actorId,      // The user who performed the action
   activityId,   // Activity to create auth prompt in (if user hasn't connected)
   this.performWriteBack,
@@ -411,20 +411,20 @@ async performWriteBack(token: AuthToken, ...extraArgs: any[]): Promise<void> {
 }
 ```
 
-### Cross-Source Auth Sharing (Google Sources)
+### Cross-Connector Auth Sharing (Google Connectors)
 
-When building a Google source that should also sync contacts, merge scopes:
+When building a Google connector that should also sync contacts, merge scopes:
 
 ```typescript
-import GoogleContacts from "@plotday/source-google-contacts";
+import GoogleContacts from "@plotday/connector-google-contacts";
 
-build(build: SourceBuilder) {
+build(build: ConnectorBuilder) {
   return {
     integrations: build(Integrations, {
       providers: [{
         provider: AuthProvider.Google,
         scopes: Integrations.MergeScopes(
-          MyGoogleSource.SCOPES,
+          MyGoogleConnector.SCOPES,
           GoogleContacts.SCOPES
         ),
         getChannels: this.getChannels,
@@ -438,18 +438,18 @@ build(build: SourceBuilder) {
 }
 ```
 
-## Architecture: Sources Save Directly
+## Architecture: Connectors Save Directly
 
-**Sources save data directly** via `integrations.saveLink()`. Sources build `NewLinkWithNotes` objects and save them, rather than passing them through a parent twist.
+**Connectors save data directly** via `integrations.saveLink()`. Connectors build `NewLinkWithNotes` objects and save them, rather than passing them through a parent twist.
 
 This means:
-- Sources request `Plot` with `ContactAccess.Write` (for contacts on threads)
-- Sources declare providers via `Integrations` with lifecycle callbacks
-- Sources call save methods directly to persist synced data
+- Connectors request `Plot` with `ContactAccess.Write` (for contacts on threads)
+- Connectors declare providers via `Integrations` with lifecycle callbacks
+- Connectors call save methods directly to persist synced data
 
 ## Critical: Callback Serialization Pattern
 
-**The #1 mistake when building sources is passing function references as callback arguments.** Functions cannot be serialized across worker boundaries.
+**The #1 mistake when building connectors is passing function references as callback arguments.** Functions cannot be serialized across worker boundaries.
 
 ### ❌ WRONG - Passing Function as Callback Argument
 
@@ -500,7 +500,7 @@ async syncBatch(resourceId: string): Promise<void> {
 
 ## Callback Backward Compatibility
 
-**All callbacks automatically upgrade to new source versions on deployment.** You MUST maintain backward compatibility.
+**All callbacks automatically upgrade to new connector versions on deployment.** You MUST maintain backward compatibility.
 
 - ❌ Don't change function signatures (remove/reorder params, change types)
 - ✅ Do add optional parameters at the end
@@ -533,7 +533,7 @@ async preUpgrade(): Promise<void> {
 
 ## Storage Key Conventions
 
-All sources use consistent key prefixes:
+All connectors use consistent key prefixes:
 
 | Key Pattern | Purpose |
 |------------|---------|
@@ -545,7 +545,7 @@ All sources use consistent key prefixes:
 | `webhook_secret_<id>` | Webhook signing secret |
 | `watch_renewal_task_<id>` | Scheduled task token for webhook renewal |
 
-## Source URL Conventions
+## Activity Source URL Conventions
 
 The `activity.source` field is the idempotency key for automatic upserts. Use a canonical format:
 
@@ -554,7 +554,7 @@ The `activity.source` field is the idempotency key for automatic upserts. Use a
 <provider>:<namespace>:<id>     — When provider has multiple entity types
 ```
 
-Examples from existing sources:
+Examples from existing connectors:
 ```
 linear:issue:<issueId>
 asana:task:<taskGid>
@@ -659,7 +659,7 @@ async onChannelDisabled(filter: ActivityFilter): Promise<void> {
 
 ## Initial vs. Incremental Sync (REQUIRED)
 
-**Every source MUST track whether it is performing an initial sync (first import) or an incremental sync (ongoing updates).** Omitting this causes notification spam from bulk historical imports.
+**Every connector MUST track whether it is performing an initial sync (first import) or an incremental sync (ongoing updates).** Omitting this causes notification spam from bulk historical imports.
 
 | Field | Initial Sync | Incremental Sync | Reason |
 |-------|-------------|------------------|--------|
@@ -682,7 +682,7 @@ The `initialSync` flag must flow from the entry point (`onChannelEnabled` / `sta
 
 The scaffold's `SyncState` type includes `initialSync: boolean`. Set it to `true` in `startBatchSync`, read it in `syncBatch`, and preserve it across batches. Webhook/incremental handlers pass `false`.
 
-**Pattern B: Pass as callback argument** (used by sources like Gmail that don't store `initialSync` in state)
+**Pattern B: Pass as callback argument** (used by connectors like Gmail that don't store `initialSync` in state)
 
 Pass `initialSync` as an explicit argument through `this.callback()`:
 
@@ -715,7 +715,7 @@ async syncBatch(
 
 ### Localhost Guard (REQUIRED)
 
-All sources MUST skip webhook registration in local development:
+All connectors MUST skip webhook registration in local development:
 
 ```typescript
 const webhookUrl = await this.tools.network.createWebhook({}, this.onWebhook, resourceId);
@@ -754,7 +754,7 @@ private async scheduleWatchRenewal(resourceId: string): Promise<void> {
 
 ## Bidirectional Sync
 
-For sources that support write-backs (updating external items from Plot):
+For connectors that support write-backs (updating external items from Plot):
 
 ### Issue/Task Updates (`updateIssue`)
 
@@ -789,16 +789,33 @@ async addIssueComment(meta: ActivityMeta, body: string, noteId?: string): Promis
 The parent twist prevents infinite loops by checking note authorship:
 
 ```typescript
-// In the twist (not the source):
+// In the twist (not the connector):
 async onNoteCreated(note: Note): Promise<void> {
   if (note.author.type === ActorType.Twist) return; // Prevent loops
   // ... sync note to external service
 }
 ```
 
+### Default Mention on Replies
+
+Connectors with bidirectional sync should set `thread.defaultMention: true` in their Plot tool options so replies to synced threads automatically mention the connector:
+
+```typescript
+plot: build(Plot, {
+  thread: {
+    access: ThreadAccess.Create,
+    defaultMention: true,  // Replies to synced threads mention this connector by default
+    updated: this.onThreadUpdated,
+  },
+  note: { created: this.onNoteCreated },
+}),
+```
+
+Without this, users must manually toggle the connector's mention chip on each reply. Connectors that don't process replies (e.g., read-only calendar sync) should NOT set this flag.
+
 ## Contacts Pattern
 
-Sources that sync user data should create contacts for authors and assignees:
+Connectors that sync user data should create contacts for authors and assignees:
 
 ```typescript
 import type { NewContact } from "@plotday/twister/plot";
@@ -841,21 +858,21 @@ declare const Buffer: {
 ## Building and Testing
 
 ```bash
-# Build the source
-cd public/sources/<name> && pnpm build
+# Build the connector
+cd public/connectors/<name> && pnpm build
 
 # Type-check without building
-cd public/sources/<name> && pnpm exec tsc --noEmit
+cd public/connectors/<name> && pnpm exec tsc --noEmit
 
 # Install dependencies (from repo root)
 pnpm install
 ```
 
-After creating a new source, add it to `pnpm-workspace.yaml` if not already covered by the glob pattern.
+After creating a new connector, add it to `pnpm-workspace.yaml` if not already covered by the glob pattern.
 
-## Source Development Checklist
+## Connector Development Checklist
 
-- [ ] Extend `Source<YourSource>`
+- [ ] Extend `Connector<YourConnector>`
 - [ ] Declare `static readonly PROVIDER`, `static readonly SCOPES`
 - [ ] Declare `static readonly Options: SyncToolOptions` and `declare readonly Options: SyncToolOptions`
 - [ ] Declare all dependencies in `build()`: Integrations, Network, Callbacks, Tasks, Plot
@@ -875,7 +892,7 @@ After creating a new source, add it to `pnpm-workspace.yaml` if not already cove
 - [ ] Create contacts for authors/assignees with `NewContact`
 - [ ] Clean up all stored state and callbacks in `stopSync()` and `onChannelDisabled()`
 - [ ] Add `package.json` with correct structure, `tsconfig.json`, and `src/index.ts` re-export
-- [ ] Verify the source builds: `pnpm build`
+- [ ] Verify the connector builds: `pnpm build`
 
 ## Common Pitfalls
 
@@ -887,7 +904,7 @@ After creating a new source, add it to `pnpm-workspace.yaml` if not already cove
 6. **❌ Using mutable IDs in `source`** — Use immutable IDs (Jira issue ID, not issue key)
 7. **❌ Not breaking loops into batches** — Each execution has ~1000 request limit
 8. **❌ Missing localhost guard** — Webhook registration fails silently on localhost
-9. **❌ Calling `plot.createThread()` from a source** — Sources save data directly via `integrations.saveLink()`
+9. **❌ Calling `plot.createThread()` from a connector** — Connectors save data directly via `integrations.saveLink()`
 10. **❌ Breaking callback signatures** — Old callbacks auto-upgrade; add optional params at end only
 11. **❌ Passing `undefined` in serializable values** — Use `null` instead
 12. **❌ Forgetting to clean up on disable** — Delete callbacks, webhooks, and stored state
@@ -897,14 +914,14 @@ After creating a new source, add it to `pnpm-workspace.yaml` if not already cove
 
 ## Study These Examples
 
-| Source | Category | Key Patterns |
-|--------|----------|-------------|
-| `linear/` | ProjectSource | Clean reference implementation, webhook handling, bidirectional sync |
-| `google-calendar/` | CalendarSource | Recurring events, RSVP write-back, watch renewal, cross-source auth sharing |
-| `slack/` | MessagingSource | Team-sharded webhooks, thread model, Slack-specific auth |
-| `gmail/` | MessagingSource | PubSub webhooks, email thread transformation, HTML contentType, callback-arg initialSync pattern |
-| `google-drive/` | DocumentSource | Document comments, reply threading, file watching |
-| `jira/` | ProjectSource | Immutable vs mutable IDs, comment metadata for dedup |
-| `asana/` | ProjectSource | HMAC webhook verification, section-based projects |
-| `outlook-calendar/` | CalendarSource | Microsoft Graph API, subscription management |
-| `google-contacts/` | (Supporting) | Contact sync, cross-source `syncWithAuth()` pattern |
+| Connector | Category | Key Patterns |
+|-----------|----------|-------------|
+| `linear/` | ProjectConnector | Clean reference implementation, webhook handling, bidirectional sync |
+| `google-calendar/` | CalendarConnector | Recurring events, RSVP write-back, watch renewal, cross-connector auth sharing |
+| `slack/` | MessagingConnector | Team-sharded webhooks, thread model, Slack-specific auth |
+| `gmail/` | MessagingConnector | PubSub webhooks, email thread transformation, HTML contentType, callback-arg initialSync pattern |
+| `google-drive/` | DocumentConnector | Document comments, reply threading, file watching |
+| `jira/` | ProjectConnector | Immutable vs mutable IDs, comment metadata for dedup |
+| `asana/` | ProjectConnector | HMAC webhook verification, section-based projects |
+| `outlook-calendar/` | CalendarConnector | Microsoft Graph API, subscription management |
+| `google-contacts/` | (Supporting) | Contact sync, cross-connector `syncWithAuth()` pattern |

package/dist/docs/media/MULTI_USER_AUTH.md

@@ -1,6 +1,6 @@
 # Multi-User Priority Auth
 
-Twists and sources operating in shared priorities must handle authentication for multiple users. This guide covers the patterns for per-user auth and private auth activities.
+Twists and connectors operating in shared priorities must handle authentication for multiple users. This guide covers the patterns for per-user auth and private auth activities.
 
 ## Auth Models
 

package/dist/docs/media/SYNC_STRATEGIES.md

@@ -1,6 +1,6 @@
 # Sync Strategies
 
-This guide explains good ways to build sources that sync other services with Plot. Choosing the right strategy depends on whether you need to update items, deduplicate them, or simply create them once.
+This guide explains good ways to build connectors that sync other services with Plot. Choosing the right strategy depends on whether you need to update items, deduplicate them, or simply create them once.
 
 ## Table of Contents
 
@@ -115,7 +115,7 @@ interface Activity {
 ### Example: Calendar Event Sync
 
 ```typescript
-export default class GoogleCalendarSource extends Source<GoogleCalendarSource> {
+export default class GoogleCalendarConnector extends Connector<GoogleCalendarConnector> {
   async syncEvent(event: calendar_v3.Schema$Event): Promise<void> {
     const activity: NewActivityWithNotes = {
       // Use the event's canonical URL as the source
@@ -168,7 +168,7 @@ export default class GoogleCalendarSource extends Source<GoogleCalendarSource> {
 ### Example: Task/Issue Sync
 
 ```typescript
-export default class LinearSource extends Source<LinearSource> {
+export default class LinearConnector extends Connector<LinearConnector> {
   async syncIssue(issue: LinearIssue): Promise<void> {
     const activity: NewActivityWithNotes = {
       source: issue.url, // Linear provides stable URLs
@@ -274,7 +274,7 @@ Use this strategy when:
 ### Example: Multiple Activities from Single Source
 
 ```typescript
-export default class GmailSource extends Source<GmailSource> {
+export default class GmailConnector extends Connector<GmailConnector> {
   /**
    * Creates separate activities for email threads and individual messages.
    * One email thread can have multiple Plot activities.
@@ -505,7 +505,7 @@ When syncing activities from external systems, it's critical to distinguish betw
 
 ### The `initialSync` Flag Pattern
 
-All sync-based tools should track whether they're performing an initial sync or incremental sync:
+All sync-based connectors should track whether they're performing an initial sync or incremental sync:
 
 | Field | Initial Sync | Incremental Sync | Reason |
 |-------|--------------|------------------|---------|
@@ -588,7 +588,7 @@ async syncBatch(
 **Initial sync (first import):**
 - Activities are **unarchived** (`archived: false`) - gives user a fresh start
 - Activities are marked as **read** (`unread: false`) - prevents notification spam from bulk historical imports
-- Use case: When user first installs the tool or reconnects after disconnection
+- Use case: When user first installs the connector or reconnects after disconnection
 
 **Incremental sync (ongoing updates):**
 - New activities appear as **unread** (`unread: true`) - user gets notified of new items
@@ -694,9 +694,9 @@ if (existingId) {
 
 ## Best Practices
 
-### 1. Be Consistent Within a Source
+### 1. Be Consistent Within a Connector
 
-Choose one strategy per source and stick with it. Mixing strategies in the same source can lead to confusion and bugs.
+Choose one strategy per connector and stick with it. Mixing strategies in the same connector can lead to confusion and bugs.
 
 ### 2. Use Descriptive Keys
 
@@ -805,4 +805,4 @@ For more information:
 
 - [Core Concepts](CORE_CONCEPTS.md) - Understanding activities, notes, and priorities
 - [Tools Guide](TOOLS_GUIDE.md) - Complete reference for the Plot tool
-- [Building Sources](BUILDING_SOURCES.md) - Creating external service integrations
+- [Building Connectors](BUILDING_CONNECTORS.md) - Creating external service integrations