@plotday/twister 0.55.0 → 0.57.0

package/src/plot.ts

@@ -788,6 +788,16 @@ export type NewNote = Partial<
      * - `undefined` (omitted): not a reply
      */
     reNote?: { id: Uuid } | { key: string } | null;
+
+    /**
+     * A link carried by this note (note-attached, NOT a thread-level canonical
+     * link). Use for augmenter content (e.g. Granola meeting notes) that should
+     * attach to an existing canonical thread without becoming its primary link.
+     * The runtime creates the link note-scoped, binds `note.link_id` to it, and
+     * — when `thread: { source }` resolves to no existing thread — find-or-creates
+     * the thread by that source so a later canonical sync can fill the primary.
+     */
+    link?: NewLink;
   };
 
 /**
@@ -1025,6 +1035,12 @@ export type Link = {
    * meeting-notes connector can bundle by setting the same alias.
    */
   sources: string[];
+  /**
+   * Connector-supplied ranking used by clients to choose the single displayed
+   * (primary) canonical link when a thread has more than one. Higher wins;
+   * ties break on earliest creation. Default 0.
+   */
+  priority: number;
 };
 
 /**
@@ -1082,12 +1098,36 @@ export type NewLink = Partial<
      * - undefined (default): Preserve current archive state
      */
     archived?: boolean;
+    /**
+     * Mark the thread as the connection owner's to-do at create time.
+     * - true: the thread is added to the owner's to-do (active) bucket and
+     *   their per-user archive is lifted, atomically with the save — no
+     *   separate `integrations.setThreadToDo()` round-trip needed.
+     * - false: the owner's thread_state is marked read (cleared from to-do).
+     * - undefined (omitted, default): leave to-do state untouched.
+     *
+     * Use for messaging-style "saved for later" flags (e.g. a starred Slack
+     * thread). This is the first-class replacement for overloading a
+     * `statuses[]` entry with `active: true`.
+     */
+    todo?: boolean;
+    /**
+     * The to-do date used when `todo` is true. Defaults to the "Now"
+     * sentinel (today's bucket) when omitted. Ignored when `todo` is not true.
+     */
+    todoDate?: Date | string;
     /**
      * Explicit focus (disables automatic focus matching).
      * Only used when the link creates a new thread. When omitted, the
      * server classifies the thread using the user's focus rules.
      */
     focus?: Pick<Focus, "id">;
+    /**
+     * Primary-link ranking for this canonical link (default 0). Set higher on
+     * the connection that "owns" the external item (e.g. the calendar that owns
+     * an event vs a subscribed copy) so clients display it as the primary.
+     */
+    priority?: number;
   };
 
 /**
@@ -1109,6 +1149,25 @@ export type NewLinkWithNotes = NewLink & {
   schedules?: Array<Omit<NewSchedule, "threadId">>;
   /** Schedule occurrence overrides */
   scheduleOccurrences?: NewScheduleOccurrence[];
+  /**
+   * For `onCreateLink` only: binds the thread's opening note (the message the
+   * user composed in Plot, which this hook just posted to the external system)
+   * to its external counterpart. Mirrors the `NoteWriteBackResult` a reply
+   * returns from `onNoteCreated` — `key` is the external message id and
+   * `externalContent` is the post-write content baseline. Without this the
+   * opening note stays keyless, so reactions and edits on it can't be routed
+   * back to the external system. Ignored outside `onCreateLink`.
+   */
+  originatingNote?: {
+    /** External message id; set as the opening note's `key`. */
+    key?: string;
+    /**
+     * Content as the external system stored it post-write, for the sync
+     * baseline. Must equal what your sync-in path emits as this note's
+     * `content` on re-ingest (same contract as `NoteWriteBackResult.externalContent`).
+     */
+    externalContent?: string;
+  };
 };
 
 /**

package/src/tools/integrations.ts

@@ -3,6 +3,7 @@ import {
   type ActorId,
   type NewContact,
   type NewLinkWithNotes,
+  type NewNote,
   ITool,
 } from "..";
 import type { JSONValue } from "../utils/types";
@@ -43,6 +44,21 @@ export type Channel = {
   linkTypes?: LinkTypeConfig[];
 };
 
+/**
+ * Curated status-icon vocabulary. Connectors map each declared status to the
+ * closest icon; clients render a single glyph per value. Required on every
+ * status so the UI always has something to show.
+ */
+export type StatusIcon =
+  | "backlog"
+  | "todo"
+  | "inProgress"
+  | "blocked"
+  | "done"
+  | "cancelled"
+  | "confirmed"
+  | "tentative";
+
 /**
  * Describes a link type that a connector creates.
  * Used for display in the UI (icons, labels).
@@ -93,6 +109,14 @@ export type LinkTypeConfig = {
     status: string;
     /** Human-readable label (e.g., "Open", "Done") */
     label: string;
+    /** Curated icon for this status (required so the UI always has a glyph). */
+    icon: StatusIcon;
+    /**
+     * Suppress this status's icon on the feed row (ThreadWidget) while still
+     * showing it in the ThreadPage header. Use for a "resting" default state
+     * that would otherwise clutter the feed (e.g. calendar "Confirmed").
+     */
+    hiddenDefault?: boolean;
     /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */
     done?: boolean;
     /**
@@ -227,8 +251,11 @@ export type ComposeConfig = {
    * `onCreateLink` resolves itself (e.g. Linear's `"unstarted"` category is
    * resolved per-team to a state UUID inside the connector — see
    * `connectors/linear/src/linear.ts`).
+   *
+   * Omit for status-less link types (e.g. messaging connectors that don't
+   * model a status): composed links are created with no status.
    */
-  status: string;
+  status?: string;
   /**
    * Optional override for the picker chip / "Create new …" copy. Defaults
    * to the parent linkType's `label`. Use to disambiguate compose entries
@@ -297,6 +324,22 @@ export type SyncContext = {
    * overwrites stored state rather than appending to it.
    */
   recovering?: boolean;
+
+  /**
+   * True when the channel is being observed because the user composed a Plot
+   * thread INTO it (via `onCreateLink`), not because they explicitly enabled
+   * it. The connector should register webhooks / mark the channel observed so
+   * inbound events (replies, reactions) on the composed thread sync back —
+   * but must NOT backfill history. Only go-forward events matter; pulling the
+   * channel's existing content would be surprising for a channel the user
+   * only posted one thread into.
+   *
+   * Connectors whose `onChannelEnabled` already skips historical backfill can
+   * ignore this flag. Connectors that initial-sync on enable MUST short-
+   * circuit that backfill when `observeOnly` is true (still set up webhooks
+   * and any go-forward state).
+   */
+  observeOnly?: boolean;
 };
 
 /**
@@ -410,6 +453,28 @@ export abstract class Integrations extends ITool {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;
 
+  /**
+   * Save one or more notes. Unlike saveLink (which creates a thread-level
+   * canonical link), these notes attach to an EXISTING thread — addressed by
+   * `note.thread: { id }` or `{ source }` — and may carry their own
+   * note-attached link via `note.link` (a note-scoped link, NOT a thread-level
+   * canonical link). When `{ source }` resolves to no thread yet, the runtime
+   * find-or-creates the thread by that source. Use for augmenter content
+   * (e.g. meeting notes attached to a calendar event).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract saveNotes(notes: NewNote[]): Promise<(Uuid | null)[]>;
+  /** Save a single note. See {@link saveNotes}. */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract saveNote(note: NewNote): Promise<Uuid | null>;
+  /**
+   * Archive every note this connector created (optionally scoped to a channel),
+   * plus their note-attached links. Mirror of {@link archiveLinks} for the
+   * note-attached content model. Use in `onChannelDisabled`.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract archiveNotes(filter: ArchiveNotesFilter): Promise<void>;
+
   /**
    * Upserts contacts into the connector's focus without requiring a Link.
    *
@@ -499,6 +564,15 @@ export abstract class Integrations extends ITool {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   abstract markNeedsReauth(channelId: string): Promise<void>;
 
+  /**
+   * Upsert workspace custom emoji into Plot's shared cache so reactions using
+   * `provider:workspace/name` refs render as images and round-trip. Idempotent;
+   * keyed on `id`. Pass `archived: true` to mark an emoji removed. Workspace-
+   * scoped (shared across all users of that workspace).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract saveCustomEmoji(emoji: NewCustomEmoji[]): Promise<void>;
+
 }
 
 /**
@@ -516,6 +590,37 @@ export type ArchiveLinkFilter = {
   meta?: Record<string, JSONValue>;
 };
 
+/**
+ * Filter criteria for archiving notes (and their note-attached links).
+ * All fields are optional; only provided fields are used for matching.
+ */
+export type ArchiveNotesFilter = {
+  /** Restrict to notes whose note-attached link is on this channel. */
+  channelId?: string;
+};
+
+/**
+ * A workspace custom emoji to cache so Plot can render and round-trip it as a
+ * reaction. `id` is the provider-scoped ref stored on reactions, of the form
+ * `<provider>:<workspace>/<name>` (e.g. `slack:T0123ABC/party_parrot`).
+ */
+export type NewCustomEmoji = {
+  /** Provider-scoped ref: `<provider>:<workspace>/<name>`. The reaction value. */
+  id: string;
+  /** e.g. "slack". */
+  provider: string;
+  /** Provider workspace/team id (e.g. Slack team id `T0123ABC`). */
+  workspace: string;
+  /** Bare emoji name without colons (e.g. "party_parrot"). */
+  name: string;
+  /** Image URL to render, or null for an alias (see `aliasOf`). */
+  imageUrl: string | null;
+  /** When this emoji aliases another, the target ref (`id` of the canonical emoji); else null. */
+  aliasOf: string | null;
+  /** True to mark the emoji removed (archive it) rather than upsert it. */
+  archived: boolean;
+};
+
 /**
  * Enumeration of supported OAuth providers.
  *

package/src/tools/network.ts

@@ -133,27 +133,27 @@ export abstract class Network extends ITool {
    *
    * **Provider-Specific Behavior:**
    * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.
-   * - **Gmail** (Google with Gmail scopes): Returns a Google Pub/Sub topic name instead of a webhook URL.
-   *   The topic name (e.g., "projects/plot-prod/topics/gmail-webhook-abc123") should be passed
-   *   to the Gmail API's `users.watch` endpoint. Requires `authorization` parameter with Gmail scopes.
-   * - **Pub/Sub** (`pubsub: true`): Returns a Google Pub/Sub topic name instead of a webhook URL.
-   *   Use this for services that deliver events via Pub/Sub (e.g., Google Workspace Events API).
-   *   A Pub/Sub topic and push subscription are created automatically; the returned topic name
-   *   can be passed to any Google API that accepts a Pub/Sub notification endpoint.
+   * - **Pub/Sub** (`pubsub: "gmail" | "workspace"`): Returns a Google Pub/Sub topic name instead
+   *   of a webhook URL. `"gmail"` targets Gmail `users.watch` (set this only on the Gmail
+   *   connector); `"workspace"` targets Google Workspace Events (Chat, etc.). A Pub/Sub topic and
+   *   push subscription are created automatically; the returned topic name (e.g.
+   *   "projects/plot-prod/topics/gmail-abc123") is passed to the relevant Google API. Other Google
+   *   connectors (Calendar, Drive) omit `pubsub` and use the default HTTPS webhook.
    * - **Default**: Returns a standard webhook URL for all other cases.
    *
    * @param options - Webhook creation options
    * @param options.provider - Optional provider for provider-specific webhook routing
-   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack and Gmail)
+   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack)
+   * @param options.pubsub - Optional Google Pub/Sub push product ("gmail" | "workspace")
    * @param callback - Function receiving (request, ...extraArgs)
    * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)
-   * @returns Promise resolving to the webhook URL, or for Gmail/Pub/Sub, a Pub/Sub topic name
+   * @returns Promise resolving to the webhook URL, or for Pub/Sub, a Pub/Sub topic name
    *
    * @example
    * ```typescript
-   * // Pub/Sub webhook for Workspace Events API
+   * // Pub/Sub webhook for Workspace Events API (Chat, etc.)
    * const topicName = await this.tools.network.createWebhook(
-   *   { pubsub: true },
+   *   { pubsub: "workspace" },
    *   this.onEventReceived,
    *   channelId
    * );
@@ -165,9 +165,9 @@ export abstract class Network extends ITool {
    *
    * @example
    * ```typescript
-   * // Gmail webhook - auto-detected from scopes, returns Pub/Sub topic name
+   * // Gmail webhook - returns a Gmail Pub/Sub topic name for users.watch
    * const topicName = await this.tools.network.createWebhook(
-   *   {},
+   *   { pubsub: "gmail" },
    *   this.onGmailNotification,
    *   "inbox"
    * );
@@ -180,8 +180,20 @@ export abstract class Network extends ITool {
     options: {
       provider?: AuthProvider;
       authorization?: Authorization;
-      /** When true, creates a Google Pub/Sub topic instead of a webhook URL. */
-      pubsub?: boolean;
+      /**
+       * Create a Google Pub/Sub topic instead of a webhook URL, and return
+       * the topic name. Selects the push product:
+       *
+       * - `"gmail"` — Gmail `users.watch` (topic published to by
+       *   `gmail-api-push`). Set this only on the Gmail connector.
+       * - `"workspace"` — Google Workspace Events (Chat, etc.).
+       *
+       * This opt-in must be explicit. Other Google connectors (Calendar,
+       * Drive) omit it and receive a standard HTTPS webhook URL — they must
+       * never be routed to a Pub/Sub topic, which `events.watch` /
+       * `files.watch` reject as non-HTTPS.
+       */
+      pubsub?: "gmail" | "workspace";
       /**
        * Controls whether the returned webhook URL runs callbacks synchronously
        * or asynchronously.