@plotday/twister 0.57.0 → 0.59.0

package/src/tools/plot.ts

@@ -146,22 +146,26 @@ export type SearchOptions = {
  *
  * @example
  * ```typescript
- * class MyTwist extends Twist {
- *   private plot: Plot;
- *
- *   constructor(id: string, tools: ToolBuilder) {
- *     super();
- *     this.plot = tools.get(Plot);
+ * class MyTwist extends Twist<MyTwist> {
+ *   build(build: ToolBuilder) {
+ *     return {
+ *       plot: build(Plot, {
+ *         thread: { access: ThreadAccess.Create },
+ *       }),
+ *     };
  *   }
  *
  *   async activate() {
- *     // Create a welcome thread
- *     await this.plot.createThread({
+ *     // Create a welcome thread with an opening note
+ *     await this.tools.plot.createThread({
  *       title: "Welcome to Plot!",
- *       actions: [{
- *         title: "Get Started",
- *         type: ActionType.external,
- *         url: "https://plot.day/docs"
+ *       notes: [{
+ *         content: "Get started with Plot:",
+ *         actions: [{
+ *           type: ActionType.external,
+ *           title: "Get Started",
+ *           url: "https://plot.day/docs"
+ *         }]
  *       }]
  *     });
  *   }
@@ -330,8 +334,9 @@ export abstract class Plot extends ITool {
    * remain unchanged. This enables partial updates without needing to fetch and resend
    * the entire thread object.
    *
-   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.
-   * Tags not included in the update remain unchanged.
+   * For the twist's own tags, use `twistTags`: a record mapping tag ID to a
+   * boolean, where true adds the tag and false removes it. Tags not included
+   * in the update remain unchanged.
    *
    * Set `focus` to move the thread to a different focus.
    *
@@ -343,18 +348,18 @@ export abstract class Plot extends ITool {
    *
    * @example
    * ```typescript
-   * // Mark a task as complete
-   * await this.plot.updateThread({
-   *   id: "task-123",
-   *   done: new Date()
+   * // Archive a thread
+   * await this.tools.plot.updateThread({
+   *   id: threadId,
+   *   archived: true
    * });
    *
-   * // Add and remove tags
-   * await this.plot.updateThread({
-   *   id: "thread-789",
-   *   tags: {
-   *     1: true,  // Add tag with ID 1
-   *     2: false  // Remove tag with ID 2
+   * // Add and remove the twist's tags
+   * await this.tools.plot.updateThread({
+   *   id: threadId,
+   *   twistTags: {
+   *     [Tag.Todo]: true,  // Add the to-do tag
+   *     [Tag.Done]: false  // Remove the done tag
    *   }
    * });
    * ```
@@ -388,16 +393,16 @@ export abstract class Plot extends ITool {
    * @example
    * ```typescript
    * // Create a note with content
-   * await this.plot.createNote({
+   * await this.tools.plot.createNote({
    *   thread: { id: "thread-123" },
-   *   note: "Discussion notes from the meeting...",
+   *   content: "Discussion notes from the meeting...",
    *   contentType: "markdown"
    * });
    *
    * // Create a note with actions
-   * await this.plot.createNote({
+   * await this.tools.plot.createNote({
    *   thread: { id: "thread-456" },
-   *   note: "Meeting recording available",
+   *   content: "Meeting recording available",
    *   actions: [{
    *     type: ActionType.external,
    *     title: "View Recording",
@@ -422,14 +427,14 @@ export abstract class Plot extends ITool {
    * @example
    * ```typescript
    * // Create multiple notes in one batch
-   * await this.plot.createNotes([
+   * await this.tools.plot.createNotes([
    *   {
    *     thread: { id: "thread-123" },
-   *     note: "First message in thread"
+   *     content: "First message in thread"
    *   },
    *   {
    *     thread: { id: "thread-123" },
-   *     note: "Second message in thread"
+   *     content: "Second message in thread"
    *   }
    * ]);
    * ```
@@ -454,16 +459,16 @@ export abstract class Plot extends ITool {
    * @example
    * ```typescript
    * // Update note content
-   * await this.plot.updateNote({
+   * await this.tools.plot.updateNote({
    *   id: "note-123",
-   *   note: "Updated content with more details"
+   *   content: "Updated content with more details"
    * });
    *
    * // Add tags to a note
-   * await this.plot.updateNote({
+   * await this.tools.plot.updateNote({
    *   id: "note-456",
    *   twistTags: {
-   *     [Tag.Important]: true
+   *     [Tag.Todo]: true
    *   }
    * });
    * ```
@@ -573,10 +578,10 @@ export abstract class Plot extends ITool {
    * @example
    * ```typescript
    * // Schedule a timed event
-   * const threadId = await this.plot.createThread({
+   * const threadId = await this.tools.plot.createThread({
    *   title: "Team standup"
    * });
-   * await this.plot.createSchedule({
+   * await this.tools.plot.createSchedule({
    *   threadId,
    *   start: new Date("2025-01-15T10:00:00Z"),
    *   end: new Date("2025-01-15T10:30:00Z"),

package/src/tools/smtp.ts

@@ -76,7 +76,7 @@ export type SmtpSendResult = {
  * @example
  * ```typescript
  * class AppleMailConnector extends Connector<AppleMailConnector> {
- *   build(build: ConnectorBuilder) {
+ *   build(build: ToolBuilder) {
  *     return {
  *       options: build(Options, {
  *         email: { type: "text", label: "Apple ID Email", default: "" },

package/src/tools/tasks.ts

@@ -30,18 +30,18 @@ import type { Callback } from "./callbacks";
  *
  * @example
  * ```typescript
- * class SyncTool extends Tool {
+ * class SyncTool extends Tool<SyncTool> {
  *   async startBatchSync(totalItems: number) {
  *     // Store initial state using built-in set method
  *     await this.set("sync_progress", { processed: 0, total: totalItems });
  *
  *     // Create callback and queue first batch
- *     const callback = await this.callback("processBatch", { batchNumber: 1 });
+ *     const callback = await this.callback(this.processBatch, 1);
  *     // runTask creates NEW execution with fresh ~1000 request limit
  *     await this.runTask(callback);
  *   }
  *
- *   async processBatch(args: any, context: { batchNumber: number }) {
+ *   async processBatch(batchNumber: number) {
  *     // Process one batch of items (sized to stay under request limit)
  *     const progress = await this.get("sync_progress");
  *
@@ -61,9 +61,7 @@ import type { Callback } from "./callbacks";
  *
  *     if (progress.processed < progress.total) {
  *       // Queue next batch - creates NEW execution with fresh request limit
- *       const callback = await this.callback("processBatch", {
- *         batchNumber: context.batchNumber + 1
- *       });
+ *       const callback = await this.callback(this.processBatch, batchNumber + 1);
  *       await this.runTask(callback);
  *     }
  *   }
@@ -72,7 +70,7 @@ import type { Callback } from "./callbacks";
  *     const tomorrow = new Date();
  *     tomorrow.setDate(tomorrow.getDate() + 1);
  *
- *     const callback = await this.callback("cleanupOldData");
+ *     const callback = await this.callback(this.cleanupOldData);
  *     // Schedule for future execution
  *     return await this.runTask(callback, { runAt: tomorrow });
  *   }
@@ -103,7 +101,7 @@ export abstract class Tasks extends ITool {
    * @example
    * ```typescript
    * // Break large loop into batches to stay under request limit
-   * const callback = await this.callback("syncBatch", { page: 1 });
+   * const callback = await this.callback(this.syncBatch, 1);
    * await this.runTask(callback); // Fresh execution with ~1000 requests
    * ```
    */

package/src/tools/twists.ts

@@ -61,10 +61,10 @@ export type TwistPermissions = Record<string, Record<string, string[]>>;
  *
  * @example
  * ```typescript
- * class TwistBuilderTwist extends Twist {
+ * class TwistBuilderTwist extends Twist<TwistBuilderTwist> {
  *   build(build: ToolBuilder) {
  *    return {
- *      twists: build.get(Twists)
+ *      twists: build(Twists)
  *    }
  *   }
  *
@@ -77,14 +77,15 @@ export type TwistPermissions = Record<string, Record<string, string[]>>;
  */
 export abstract class Twists extends ITool {
   /**
-   * Creates a new twist ID and grants access to people in the current focus.
+   * Creates a new twist package ID. Ownership of the ID is claimed lazily
+   * on first deploy — no upfront registration happens beyond generating it.
    *
    * @returns Promise resolving to the generated twist ID
    * @throws When twist creation fails
    *
    * @example
    * ```typescript
-   * const twistId = await twist.create();
+   * const twistId = await this.tools.twists.create();
    * console.log(`Your twist ID: ${twistId}`);
    * ```
    */
@@ -103,15 +104,15 @@ export abstract class Twists extends ITool {
    *
    * @example
    * ```typescript
-   * const source = await twist.generate(`
+   * const source = await this.tools.twists.generate(`
    * # Calendar Sync Twist
    *
-   * This twist syncs Google Calendar events to Plot activities.
+   * This twist syncs Google Calendar events to Plot threads.
    *
    * ## Features
    * - Authenticate with Google
    * - Sync calendar events
-   * - Create activities from events
+   * - Create threads from events
    * `);
    *
    * // source.dependencies: { "@plotday/twister": "workspace:^", ... }
@@ -143,7 +144,7 @@ export abstract class Twists extends ITool {
    * @example
    * ```typescript
    * // Deploy with a module
-   * const result = await twist.deploy({
+   * const result = await this.tools.twists.deploy({
    *   twistId: 'abc-123-...',
    *   module: 'export default class MyTwist extends Twist {...}',
    *   environment: 'personal',
@@ -153,8 +154,8 @@ export abstract class Twists extends ITool {
    * console.log(`Deployed version ${result.version}`);
    *
    * // Deploy with source
-   * const source = await twist.generate(spec);
-   * const result = await twist.deploy({
+   * const source = await this.tools.twists.generate(spec);
+   * const result = await this.tools.twists.deploy({
    *   twistId: 'abc-123-...',
    *   source,
    *   environment: 'personal',
@@ -162,7 +163,7 @@ export abstract class Twists extends ITool {
    * });
    *
    * // Validate with dryRun
-   * const result = await twist.deploy({
+   * const result = await this.tools.twists.deploy({
    *   twistId: 'abc-123-...',
    *   source,
    *   dryRun: true,
@@ -209,11 +210,11 @@ export abstract class Twists extends ITool {
    * @example
    * ```typescript
    * // Create twist and callback
-   * const twistId = await this.twist.create();
-   * const callback = await this.callback.create("onLogs");
+   * const twistId = await this.tools.twists.create();
+   * const callback = await this.callback(this.onLogs);
    *
    * // Subscribe to logs
-   * await this.twist.watchLogs(twistId, callback);
+   * await this.tools.twists.watchLogs(twistId, callback);
    *
    * // Implement handler
    * async onLogs(logs: Log[]) {

package/src/twist.ts

@@ -225,8 +225,8 @@ export abstract class Twist<TSelf> {
    * await this.set("handler_token", token);
    *
    * // Later, execute the callback
-   * const token = await this.get<string>("handler_token");
-   * await this.run(token, args);
+   * const token = await this.get<Callback>("handler_token");
+   * await this.run(token);
    * ```
    *
    * @template T - The type of value being stored (must be Serializable)

package/dist/docs/media/MULTI_USER_AUTH.md

@@ -1,116 +0,0 @@
-# Multi-User Priority Auth
-
-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
-
-| Model                 | Use case                                       | Example                  |
-| --------------------- | ---------------------------------------------- | ------------------------ |
-| No auth               | Twist doesn't need external credentials        | Text-only twist          |
-| Read-only single auth | Installer connects, synced data visible to all | Calendar sync (read)     |
-| Two-way per-user auth | Write-backs use the acting user's credentials  | Comments, RSVP responses |
-
-## Private Auth Activities
-
-When a twist creates an auth activity in `activate()`, make it `private: true` and add `mentions` targeting `context.actor`. This ensures only the installing user sees the auth prompt — other priority members won't be spammed with irrelevant auth requests.
-
-```typescript
-async activate(_priority: Pick<Priority, "id">, context?: { actor: Actor }) {
-  const authLink = await this.tools.myTool.requestAuth(this.onAuthComplete, "provider");
-
-  await this.tools.plot.createActivity({
-    type: ActivityType.Action,
-    title: "Connect your account",
-    private: true,
-    notes: [{
-      content: "Connect to get started.",
-      links: [authLink],
-      ...(context?.actor ? { mentions: [{ id: context.actor.id }] } : {}),
-    }],
-  });
-}
-```
-
-Key points:
-
-- `private: true` — only the author and mentioned users can see the activity
-- `context?.actor` — the user who installed the twist (available from the SDK)
-- Always guard with `?.` since `context` is optional for backward compatibility
-
-## Per-User Auth for Write-Backs
-
-When a twist needs to write back to an external system (e.g., posting a comment on a Linear issue), it should use the acting user's credentials when available.
-
-### Pattern: Try Actor First, Fall Back to Installer
-
-The simplest approach passes the actor's ID as the `authToken` parameter. The tool's `getClient()` method will look it up via `integrations.get(provider, actorId)`:
-
-```typescript
-private async onNoteCreated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {
-  const provider = thread.meta?.provider;
-  const tool = this.getProviderTool(provider);
-
-  // Try actor's credentials first, then installer's
-  const actorId = note.author.id as string;
-  const installerAuthToken = await this.getAuthToken(provider);
-
-  const authTokensToTry = [
-    actorId,
-    ...(installerAuthToken && installerAuthToken !== actorId
-      ? [installerAuthToken]
-      : []),
-  ];
-
-  for (const authToken of authTokensToTry) {
-    try {
-      // addIssueComment returns { key, externalContent } — returning it
-      // directly lets the runtime set note.key AND record the sync
-      // baseline so future re-syncs preserve Plot's markdown.
-      return await tool.addIssueComment(authToken, thread.meta, note.content, note.id);
-    } catch {
-      continue; // Try next token
-    }
-  }
-}
-```
-
-### When Actor ID Is Not Available
-
-For callbacks like `onThreadUpdated` where the acting user's ID is not included in the callback signature, continue using the installer's stored auth token. This is acceptable because:
-
-- Activity field updates (title, assignee, done) are less user-specific
-- The change itself is the same regardless of who made it
-- Per-user auth is most valuable for user-attributed actions like comments
-
-### How Tools Resolve Auth Tokens
-
-Tools with per-user auth support resolve tokens in their `getClient()` method:
-
-1. Try `integrations.get(provider, authToken as ActorId)` — looks up per-actor credentials
-2. Fall back to legacy token lookup if the actor has no credentials
-3. Throw if neither works (caller catches and tries the next token)
-
-## On-Demand Auth Requests
-
-When a user without credentials performs a write-back action, you can optionally create a private auth-request activity prompting them to connect:
-
-```typescript
-// Create auth request for a specific actor
-const authLink = await tool.requestAuth(this.onActorAuth, actorId);
-
-await this.tools.plot.createActivity({
-  type: ActivityType.Action,
-  title: "Connect to sync your changes",
-  private: true,
-  source: `auth:${actorId}`, // Dedup: one auth request per user
-  notes: [
-    {
-      content: "Connect your account so your changes appear under your name.",
-      links: [authLink],
-      mentions: [{ id: actorId as ActorId }],
-    },
-  ],
-});
-```
-
-This is optional — the simpler approach is to silently fall back to the installer's credentials.