@plotday/twister 0.54.0 → 0.56.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

@@ -17,12 +17,47 @@ export type Channel = {
   id: string;
   /** Display name shown in the UI */
   title: string;
+  /**
+   * Whether this channel should be selected by default when the user first
+   * adds the connection. Tri-state:
+   * - `true`  — pre-select it (e.g. the user's own/primary calendar).
+   * - `false` — exclude it from the default selection (low-value or
+   *   irrelevant resources that would crowd the user's view, or containers
+   *   whose contents are too broad to sync wholesale — e.g. a holiday or
+   *   someone-else's shared calendar, a GitHub org that cascades to every
+   *   repo, a Microsoft Teams team container). The user can still enable it
+   *   manually.
+   * - `undefined` — no opinion; the client decides. The client defaults to
+   *   enabling the channel unless its title looks low-value (holidays,
+   *   birthdays, spam/sent/draft, …).
+   *
+   * The guiding principle is "sync everything the user would reasonably want
+   * by default" — for most connectors that's all channels, so only set this
+   * where the connector can distinguish the user's own/relevant channels from
+   * low-value ones (e.g. Google Calendar via `accessRole === "owner"`).
+   */
+  enabledByDefault?: boolean;
   /** Optional nested channel resources (e.g., subfolders) */
   children?: Channel[];
   /** Per-channel link type configs. Overrides twist-level linkTypes when present. */
   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).
@@ -39,6 +74,28 @@ export type LinkTypeConfig = {
    * when omitted. Use the singular noun in title case (e.g. "Comment").
    */
   noteLabel?: string;
+  /**
+   * Placeholder shown in the editor when this link type is the target of a
+   * new thread (NewThreadPage). Example: "Send a Gmail email".
+   * If unset, Plot derives "Create a new {connector} {label.toLowerCase()}".
+   */
+  composePlaceholder?: string;
+  /**
+   * Label for the Send button on NewThreadPage when this link type is the
+   * target. Example: "Send". If unset, defaults to "Create".
+   */
+  composeVerb?: string;
+  /**
+   * Placeholder shown in the in-thread editor for the default reply mode.
+   * Example: "Reply" (Gmail), "Add a comment" (Linear). If unset, Plot derives
+   * "Add a {noteLabel.toLowerCase()}" or "Add a note".
+   */
+  replyPlaceholder?: string;
+  /**
+   * Label for the Send button in the in-thread editor. Example: "Send"
+   * (Gmail), "Comment" (Linear). If unset, defaults to "Send".
+   */
+  replyVerb?: string;
   /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */
   logo?: string;
   /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */
@@ -51,6 +108,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;
     /**
@@ -72,6 +137,16 @@ export type LinkTypeConfig = {
   }>;
   /** Whether this link type supports displaying and changing the assignee */
   supportsAssignee?: boolean;
+  /**
+   * Whether this link type produces time-anchored schedule/agenda items
+   * (i.e. calendar events). The Plot app shows the agenda (the bottom-nav
+   * tab on mobile and the left-sidebar agenda on desktop) only when the
+   * user has at least one active connection whose link types include one
+   * with `includesSchedules: true`. Calendar connectors (Google / Apple /
+   * Outlook Calendar) set this on their `event` link type. Defaults to
+   * false — non-calendar link types (messages, issues, tasks, docs) omit it.
+   */
+  includesSchedules?: boolean;
   /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */
   defaultCreateThreads?: string;
   /**
@@ -103,6 +178,22 @@ export type LinkTypeConfig = {
    * false when omitted.
    */
   supportsContactChanges?: boolean;
+  /**
+   * Whether a note/reply on this link type can carry a link (a pasted URL or
+   * connector-created item) that Plot forwards to the source. When false (the
+   * default), the "Add link" button is hidden for threads of this link type.
+   * Only set true if the connector's reply path actually forwards the link
+   * action to the source. Private Plot notes (no link type) always allow links.
+   */
+  supportsLinks?: boolean;
+  /**
+   * Whether a note/reply on this link type can carry an uploaded file that Plot
+   * forwards to the source as an attachment. When false (the default), the
+   * "Attach file" button is hidden for threads of this link type. Only set true
+   * if the connector's reply path actually uploads file actions to the source.
+   * Private Plot notes (no link type) always allow attachments.
+   */
+  supportsFileAttachments?: boolean;
   /**
    * Declares how sharing on threads of this link type is scoped:
    *
@@ -114,12 +205,16 @@ export type LinkTypeConfig = {
    * - `"message"`: each note carries its own recipient set via
    *   `note.access_contacts`; the thread roster is the union across
    *   all messages. Email.
+   * - `"none"`: the link type has no recipient roster at all. No
+   *   contacts/sharing UI is shown for these threads. Use for purely
+   *   personal destinations with no sharing concept (e.g. Google
+   *   Tasks). The per-thread `contacts` array is ignored for sharing UI.
    *
    * Omit to default to `"thread"`. When set to `"message"`, every
    * note this connector ingests must populate `access_contacts`
    * explicitly (never NULL).
    */
-  sharingModel?: "thread" | "channel" | "message";
+  sharingModel?: "thread" | "channel" | "message" | "none";
 };
 
 /**
@@ -155,8 +250,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
@@ -225,6 +323,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;
 };
 
 /**
@@ -427,6 +541,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>;
+
 }
 
 /**
@@ -444,6 +567,28 @@ export type ArchiveLinkFilter = {
   meta?: Record<string, JSONValue>;
 };
 
+/**
+ * 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.