@plotday/twister 0.47.0 → 0.49.0

package/src/schedule.ts

@@ -0,0 +1,203 @@
+import { type Tag } from "./tag";
+import {
+  type Actor,
+  type ActorId,
+  type NewActor,
+  type NewTags,
+  type Tags,
+} from "./plot";
+import { Uuid } from "./utils/uuid";
+
+export { Uuid } from "./utils/uuid";
+
+/**
+ * Represents a schedule entry for a thread.
+ *
+ * Schedules define when a thread occurs in time. A thread may have zero or more schedules:
+ * - Shared schedules (userId is null): visible to all members of the thread's priority
+ * - Per-user schedules (userId set): private ordering/scheduling for a specific user
+ *
+ * For recurring events in the SDK, start/end represent the first occurrence's
+ * time. In the database, the `at`/`on` range is expanded to span from the first
+ * occurrence start to the last occurrence end (or open-ended if no fixed end).
+ * The `duration` column stores the per-occurrence duration, enabling range overlap
+ * queries to correctly find all recurring events with occurrences in a given window.
+ */
+export type Schedule = {
+  /** When this schedule was created */
+  created: Date;
+  /** Whether this schedule has been archived */
+  archived: boolean;
+  /** If set, this is a per-user schedule visible only to this user */
+  userId: ActorId | null;
+  /** Per-user ordering within a day (only set for per-user schedules) */
+  order: number | null;
+  /**
+   * Start time of the schedule.
+   * Date object for timed events, date string in "YYYY-MM-DD" format for all-day events.
+   */
+  start: Date | string | null;
+  /**
+   * End time of the schedule.
+   * Date object for timed events, date string in "YYYY-MM-DD" format for all-day events.
+   */
+  end: Date | string | null;
+  /** Recurrence rule in RFC 5545 RRULE format (e.g., "FREQ=WEEKLY;BYDAY=MO,WE,FR") */
+  recurrenceRule: string | null;
+  /** Duration of each occurrence in milliseconds (required for recurring schedules) */
+  duration: number | null;
+  /** Array of dates to exclude from the recurrence pattern */
+  recurrenceExdates: Date[] | null;
+  /**
+   * For occurrence exceptions: the original date/time of this occurrence in the series.
+   * Format: Date object or "YYYY-MM-DD" for all-day events.
+   */
+  occurrence: Date | string | null;
+  /** Contacts invited to this schedule (attendees/participants) */
+  contacts: ScheduleContact[];
+};
+
+export type ScheduleContactStatus = "attend" | "skip";
+export type ScheduleContactRole = "organizer" | "required" | "optional";
+
+export type ScheduleContact = {
+  contact: Actor;
+  status: ScheduleContactStatus | null;
+  role: ScheduleContactRole;
+  archived: boolean;
+};
+
+export type NewScheduleContact = {
+  contact: NewActor;
+  status?: ScheduleContactStatus | null;
+  role?: ScheduleContactRole | null;
+  archived?: boolean;
+};
+
+/**
+ * Type for creating new schedules.
+ *
+ * Requires `threadId` and `start`. All other fields are optional.
+ *
+ * @example
+ * ```typescript
+ * // Simple timed event
+ * const schedule: NewSchedule = {
+ *   threadId: threadId,
+ *   start: new Date("2025-03-15T10:00:00Z"),
+ *   end: new Date("2025-03-15T11:00:00Z")
+ * };
+ *
+ * // All-day event
+ * const allDay: NewSchedule = {
+ *   threadId: threadId,
+ *   start: "2025-03-15",
+ *   end: "2025-03-16"
+ * };
+ *
+ * // Recurring weekly event
+ * const recurring: NewSchedule = {
+ *   threadId: threadId,
+ *   start: new Date("2025-01-20T14:00:00Z"),
+ *   end: new Date("2025-01-20T15:00:00Z"),
+ *   recurrenceRule: "FREQ=WEEKLY;BYDAY=MO",
+ *   recurrenceUntil: new Date("2025-06-30")
+ * };
+ * ```
+ */
+export type NewSchedule = {
+  /** The thread this schedule belongs to */
+  threadId: Uuid;
+  /**
+   * Start time. Date for timed events, "YYYY-MM-DD" for all-day.
+   * Determines whether the schedule uses `at` (timed) or `on` (all-day) storage.
+   */
+  start: Date | string;
+  /** End time. Date for timed events, "YYYY-MM-DD" for all-day. */
+  end?: Date | string | null;
+  /** Recurrence rule in RFC 5545 RRULE format */
+  recurrenceRule?: string | null;
+  /**
+   * For recurring schedules, the last occurrence date (inclusive).
+   * When both recurrenceCount and recurrenceUntil are provided, recurrenceCount takes precedence.
+   */
+  recurrenceUntil?: Date | string | null;
+  /**
+   * For recurring schedules, the number of occurrences to generate.
+   * Takes precedence over recurrenceUntil if both are provided.
+   */
+  recurrenceCount?: number | null;
+  /** Array of dates to exclude from the recurrence pattern */
+  recurrenceExdates?: Date[] | null;
+  /**
+   * For occurrence exceptions: the original date/time of this occurrence.
+   */
+  occurrence?: Date | string | null;
+  /** If set, this is a per-user schedule for the specified user */
+  userId?: ActorId | null;
+  /** Per-user ordering (only valid with userId) */
+  order?: number | null;
+  /** Whether to archive this schedule */
+  archived?: boolean;
+  /** Contacts to upsert on this schedule. Upserted by contact identity. */
+  contacts?: NewScheduleContact[];
+};
+
+/**
+ * Represents a specific instance of a recurring schedule.
+ * All field values are computed by merging the recurring schedule's
+ * defaults with any occurrence-specific overrides.
+ */
+export type ScheduleOccurrence = {
+  /**
+   * Original date/datetime of this occurrence.
+   * Use start for the occurrence's current start time.
+   */
+  occurrence: Date | string;
+
+  /** The recurring schedule of which this is an occurrence */
+  schedule: Schedule;
+
+  /** Effective start for this occurrence (series default + override) */
+  start: Date | string;
+  /** Effective end for this occurrence */
+  end: Date | string | null;
+
+  /** Tags for this occurrence */
+  tags: Tags;
+
+  /** True if the occurrence is archived */
+  archived: boolean;
+};
+
+/**
+ * Type for creating or updating schedule occurrences.
+ */
+export type NewScheduleOccurrence = Pick<
+  ScheduleOccurrence,
+  "occurrence" | "start"
+> &
+  Partial<
+    Omit<ScheduleOccurrence, "occurrence" | "start" | "schedule" | "tags">
+  > & {
+    /** Tags for this occurrence */
+    tags?: NewTags;
+
+    /** Add or remove the twist's tags on this occurrence */
+    twistTags?: Partial<Record<Tag, boolean>>;
+
+    /** Whether this occurrence should be marked as unread */
+    unread?: boolean;
+
+    /** Contacts to upsert on this occurrence's schedule */
+    contacts?: NewScheduleContact[];
+  };
+
+/**
+ * Type for updating schedule occurrences inline.
+ */
+export type ScheduleOccurrenceUpdate = Pick<
+  NewScheduleOccurrence,
+  "occurrence"
+> &
+  Partial<Omit<NewScheduleOccurrence, "occurrence" | "schedule">>;

package/src/tag.ts

@@ -0,0 +1,54 @@
+/**
+ * Thread tags. Three types:
+ * 1. Special tags, which trigger other behaviors
+ * 2. Toggle tags, which anyone can toggle a shared value on or off
+ * 3. Count tags, where everyone can add or remove their own
+ */
+export enum Tag {
+  // Special tags
+  Todo = 1,
+  Done = 3,
+
+  // Toggle tags
+  Pinned = 100,
+  Urgent = 101,
+  Goal = 103,
+  Decision = 104,
+  Waiting = 105,
+  Blocked = 106,
+  Warning = 107,
+  Question = 108,
+  Twist = 109,
+  Star = 110,
+  Idea = 111,
+
+  // Count tags
+  Yes = 1000,
+  No = 1001,
+  Volunteer = 1002,
+  Tada = 1003,
+  Fire = 1004,
+  Totally = 1005,
+  Looking = 1006,
+  Love = 1007,
+  Rocket = 1008,
+  Sparkles = 1009,
+  Thanks = 1010,
+  Smile = 1011,
+  Wave = 1012,
+  Praise = 1015,
+  Applause = 1016,
+  Cool = 1017,
+  Sad = 1018,
+  Reply = 1019,
+  Thinking = 1013,
+  Remember = 1014,
+  Agreed = 1020,
+  Relieved = 1021,
+  Send = 1022,
+  Noted = 1023,
+  Laugh = 1024,
+  Surprised = 1025,
+  Confused = 1026,
+  Dismayed = 1027,
+}

package/src/tool.ts

@@ -0,0 +1,377 @@
+import {
+  type Actor,
+} from "./plot";
+import type { Callback } from "./tools/callbacks";
+import type {
+  InferOptions,
+  InferTools,
+  Serializable,
+  ToolBuilder,
+  ToolShed,
+} from "./utils/types";
+
+export type { ToolBuilder };
+
+/**
+ * Abstrtact parent for both built-in tools and regular Tools.
+ * Regular tools extend Tool.
+ */
+export abstract class ITool {}
+
+/**
+ * Base class for regular tools.
+ *
+ * Regular tools run in isolation and can only access other tools declared
+ * in their build method. They are ideal for external API integrations
+ * and reusable functionality that doesn't require Plot's internal infrastructure.
+ *
+ * @example
+ * ```typescript
+ * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {
+ *   constructor(id: string, options: { clientId: string }) {
+ *     super(id, options);
+ *   }
+ *
+ *   build(tools: ToolBuilder) {
+ *     return {
+ *       auth: tools.build(Integrations),
+ *       network: tools.build(Network),
+ *     };
+ *   }
+ *
+ *   async getCalendars() {
+ *     const token = await this.tools.auth.get(...);
+ *     // Implementation
+ *   }
+ * }
+ * ```
+ */
+export abstract class Tool<TSelf> implements ITool {
+  constructor(
+    protected id: string,
+    protected options: InferOptions<TSelf>,
+    private toolShed: ToolShed
+  ) {}
+
+  /**
+   * Gets the initialized tools for this tool.
+   * @throws Error if called before initialization is complete
+   */
+  protected get tools() {
+    return this.toolShed.getTools<InferTools<TSelf>>();
+  }
+
+  /**
+   * Declares tool dependencies for this tool.
+   * Return an object mapping tool names to build() promises.
+   * Default implementation returns empty object (no custom tools).
+   *
+   * @param build - The build function to use for declaring dependencies
+   * @returns Object mapping tool names to tool promises
+   *
+   * @example
+   * ```typescript
+   * build(build: ToolBuilder) {
+   *   return {
+   *     network: build(Network, { urls: ["https://api.example.com/*"] }),
+   *   };
+   * }
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  build(build: ToolBuilder): Record<string, Promise<ITool>> {
+    return {};
+  }
+
+  /**
+   * Creates a persistent callback to a method on this tool.
+   *
+   * ExtraArgs are strongly typed to match the method's signature.
+   *
+   * @param fn - The method to callback
+   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)
+   * @returns Promise resolving to a persistent callback token
+   *
+   * @example
+   * ```typescript
+   * const callback = await this.callback(this.onWebhook, "calendar", 123);
+   * ```
+   */
+  protected async callback<
+    TArgs extends Serializable[],
+    Fn extends (...args: TArgs) => any
+  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {
+    return this.tools.callbacks.create(fn, ...extraArgs);
+  }
+
+  /**
+   * Deletes a specific callback by its token.
+   *
+   * @param token - The callback token to delete
+   * @returns Promise that resolves when the callback is deleted
+   */
+  protected async deleteCallback(token: Callback): Promise<void> {
+    return this.tools.callbacks.delete(token);
+  }
+
+  /**
+   * Deletes all callbacks for this tool.
+   *
+   * @returns Promise that resolves when all callbacks are deleted
+   */
+  protected async deleteAllCallbacks(): Promise<void> {
+    return this.tools.callbacks.deleteAll();
+  }
+
+  /**
+   * Executes a callback by its token inline in the current execution.
+   *
+   * **Use `this.runTask()` instead for batch continuations and long-running work.**
+   * `this.run()` executes inline, sharing the current request count (~1000 limit)
+   * and blocking the HTTP response. This causes timeouts when used in lifecycle
+   * methods like `onChannelEnabled` or `syncBatch` continuations.
+   *
+   * `this.run()` is appropriate when you need the callback's **return value** —
+   * e.g., running a parent callback token that returns data. For fire-and-forget
+   * work, always prefer `this.runTask()`.
+   *
+   * @param token - The callback token to execute
+   * @param args - Optional arguments to pass to the callback
+   * @returns Promise resolving to the callback result
+   */
+  protected async run(token: Callback, ...args: any[]): Promise<any> {
+    return this.tools.callbacks.run(token, ...args);
+  }
+
+  /**
+   * Retrieves a value from persistent storage by key.
+   *
+   * Values are automatically deserialized using SuperJSON, which
+   * properly restores Date objects, Maps, Sets, and other complex types.
+   *
+   * @template T - The expected type of the stored value (must be Serializable)
+   * @param key - The storage key to retrieve
+   * @returns Promise resolving to the stored value or null
+   */
+  protected async get<T extends Serializable>(key: string): Promise<T | null> {
+    return this.tools.store.get(key);
+  }
+
+  /**
+   * Stores a value in persistent storage.
+   *
+   * The value will be serialized using SuperJSON and stored persistently.
+   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,
+   * and other complex types that standard JSON doesn't support.
+   *
+   * **Important**: Functions and Symbols cannot be stored.
+   * **For function references**: Use callbacks instead of storing functions directly.
+   *
+   * @example
+   * ```typescript
+   * // ✅ Date objects are preserved
+   * await this.set("sync_state", {
+   *   lastSync: new Date(),
+   *   minDate: new Date(2024, 0, 1)
+   * });
+   *
+   * // ✅ undefined is now supported
+   * await this.set("data", { name: "test", optional: undefined });
+   *
+   * // ✅ Arrays with undefined are supported
+   * await this.set("items", [1, undefined, 3]);
+   * await this.set("items", [1, null, 3]); // Also works
+   *
+   * // ✅ Maps and Sets are supported
+   * await this.set("mapping", new Map([["key", "value"]]));
+   * await this.set("tags", new Set(["tag1", "tag2"]));
+   *
+   * // ❌ WRONG: Cannot store functions directly
+   * await this.set("handler", this.myHandler);
+   *
+   * // ✅ CORRECT: Create a callback token first
+   * const token = await this.callback(this.myHandler, "arg1", "arg2");
+   * await this.set("handler_token", token);
+   *
+   * // Later, execute the callback
+   * const token = await this.get<string>("handler_token");
+   * await this.run(token, args);
+   * ```
+   *
+   * @template T - The type of value being stored (must be Serializable)
+   * @param key - The storage key to use
+   * @param value - The value to store (must be SuperJSON-serializable)
+   * @returns Promise that resolves when the value is stored
+   */
+  protected async set<T extends Serializable>(
+    key: string,
+    value: T
+  ): Promise<void> {
+    return this.tools.store.set(key, value);
+  }
+
+  /**
+   * Lists all storage keys matching a prefix.
+   *
+   * @param prefix - The prefix to match keys against
+   * @returns Promise resolving to an array of matching key strings
+   */
+  protected async list(prefix: string): Promise<string[]> {
+    return this.tools.store.list(prefix);
+  }
+
+  /**
+   * Removes a specific key from persistent storage.
+   *
+   * @param key - The storage key to remove
+   * @returns Promise that resolves when the key is removed
+   */
+  protected async clear(key: string): Promise<void> {
+    return this.tools.store.clear(key);
+  }
+
+  /**
+   * Removes all keys from this tool's storage.
+   *
+   * @returns Promise that resolves when all keys are removed
+   */
+  protected async clearAll(): Promise<void> {
+    return this.tools.store.clearAll();
+  }
+
+  /**
+   * Queues a callback to execute in a separate worker context with a fresh request limit.
+   *
+   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,
+   * tool calls, database operations). This is the primary way to stay under request limits
+   * when processing large datasets or making many API calls.
+   *
+   * Use this to break long loops into chunks that each stay under the ~1000 request limit.
+   * Each task runs in an isolated execution environment with ~1000 requests and ~60 seconds CPU time.
+   *
+   * @param callback - The callback token created with `this.callback()`
+   * @param options - Optional configuration for the execution
+   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately
+   * @returns Promise resolving to a cancellation token (only for scheduled executions)
+   *
+   * @example
+   * ```typescript
+   * // Break large loop into batches
+   * const callback = await this.callback("processBatch", { page: 1 });
+   * await this.runTask(callback); // New execution with fresh request limit
+   * ```
+   */
+  protected async runTask(
+    callback: Callback,
+    options?: { runAt?: Date }
+  ): Promise<string | void> {
+    return this.tools.tasks.runTask(callback, options);
+  }
+
+  /**
+   * Cancels a previously scheduled execution.
+   *
+   * @param token - The cancellation token returned by runTask() with runAt option
+   * @returns Promise that resolves when the cancellation is processed
+   */
+  protected async cancelTask(token: string): Promise<void> {
+    return this.tools.tasks.cancelTask(token);
+  }
+
+  /**
+   * Cancels all scheduled executions for this tool.
+   *
+   * @returns Promise that resolves when all cancellations are processed
+   */
+  protected async cancelAllTasks(): Promise<void> {
+    return this.tools.tasks.cancelAllTasks();
+  }
+
+  /**
+   * Called before the twist's activate method, starting from the deepest tool dependencies.
+   *
+   * This method is called in a depth-first manner, with the deepest dependencies
+   * being called first, bubbling up to the top-level tools before the twist's
+   * activate method is called.
+   *
+   * @param context - Optional context containing the actor who triggered activation
+   * @returns Promise that resolves when pre-activation is complete
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  preActivate(context?: { actor: Actor }): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Called after the twist's activate method, starting from the top-level tools.
+   *
+   * This method is called in reverse order, with top-level tools being called
+   * first, then cascading down to the deepest dependencies.
+   *
+   * @param context - Optional context containing the actor who triggered activation
+   * @returns Promise that resolves when post-activation is complete
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  postActivate(context?: { actor: Actor }): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Called before the twist's upgrade method, starting from the deepest tool dependencies.
+   *
+   * This method is called in a depth-first manner, with the deepest dependencies
+   * being called first, bubbling up to the top-level tools before the twist's
+   * upgrade method is called.
+   *
+   * @returns Promise that resolves when pre-upgrade is complete
+   */
+  preUpgrade(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Called after the twist's upgrade method, starting from the top-level tools.
+   *
+   * This method is called in reverse order, with top-level tools being called
+   * first, then cascading down to the deepest dependencies.
+   *
+   * @returns Promise that resolves when post-upgrade is complete
+   */
+  postUpgrade(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Called before the twist's deactivate method, starting from the deepest tool dependencies.
+   *
+   * This method is called in a depth-first manner, with the deepest dependencies
+   * being called first, bubbling up to the top-level tools before the twist's
+   * deactivate method is called.
+   *
+   * @returns Promise that resolves when pre-deactivation is complete
+   */
+  preDeactivate(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Called after the twist's deactivate method, starting from the top-level tools.
+   *
+   * This method is called in reverse order, with top-level tools being called
+   * first, then cascading down to the deepest dependencies.
+   *
+   * @returns Promise that resolves when post-deactivation is complete
+   */
+  postDeactivate(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Waits for tool initialization to complete.
+   * Called automatically by the entrypoint before lifecycle methods.
+   * @internal
+   */
+  async waitForReady(): Promise<void> {
+    await this.toolShed.waitForReady();
+  }
+}