@plotday/twister 0.51.0 → 0.53.0

package/src/tools/integrations.ts

@@ -4,9 +4,7 @@ import {
   type NewContact,
   type NewLinkWithNotes,
   ITool,
-  Serializable,
 } from "..";
-import { Tag } from "../tag";
 import type { JSONValue } from "../utils/types";
 import type { Uuid } from "../utils/uuid";
 
@@ -34,6 +32,13 @@ export type LinkTypeConfig = {
   type: string;
   /** Human-readable label (e.g., "Issue", "Pull Request") */
   label: string;
+  /**
+   * Connector's word for a note on a linked item of this type — used by the
+   * Flutter app to adapt note/composer copy ("Add a comment" on Linear,
+   * "Add a message" on Slack, "Add a reply" on Gmail). Defaults to "note"
+   * when omitted. Use the singular noun in title case (e.g. "Comment").
+   */
+  noteLabel?: 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=`). */
@@ -46,30 +51,155 @@ export type LinkTypeConfig = {
     status: string;
     /** Human-readable label (e.g., "Open", "Done") */
     label: string;
-    /** Tag to propagate to thread when this status is active (e.g., Tag.Done) */
-    tag?: Tag;
     /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */
     done?: boolean;
     /**
-     * Whether this status represents the connector's "to-do" / active state.
-     * When a user adds a thread to Plot's agenda, done-status links flip to
-     * the status marked `todo: true` (e.g., Gmail's "starred", Linear's
-     * "todo") so the link widget and thread tags reflect the active state.
-     * At most one status per type should set this.
+     * Mark the thread `active=true` in Plot when a link enters this status.
+     * Use for messaging-style flags where the user has indicated they want
+     * to act on the thread now — Gmail's "starred", Slack's "later", etc.
+     * The Plot user can later un-flag the thread without breaking the
+     * connector relationship.
      */
-    todo?: boolean;
+    active?: boolean;
+    /**
+     * Mark the thread `task=true` in Plot when a link enters this status.
+     * Use for project-tracker assignments — Linear / Todoist / Jira / etc.
+     * `task` puts the thread on the user's task list without flooding their
+     * inbox under `active`: the user explicitly flips it to `active` when
+     * they decide to start.
+     */
+    task?: boolean;
+    /**
+     * Mark the thread `to_read=true` in Plot when a link enters this status.
+     * Use for connectors that explicitly track read-later state (Pocket
+     * archives, Slack "remind me", etc).
+     */
+    toRead?: boolean;
     /**
-     * Default status applied when Plot asks the connector to create a new
-     * item of this type via `Connector.onCreateLink`. Declaring at least one
-     * status with `createDefault: true` is how a link type opts in to
-     * Plot-initiated creation. At most one status per type should set this.
+     * @deprecated Use `active` (messaging) or `task` (project tracker) instead.
+     * Treated as `task: true` for backward compatibility.
+     *
+     * Original meaning: whether this status represents the connector's
+     * "to-do" / active state. When a user adds a thread to Plot's agenda,
+     * done-status links flip to the status marked `todo: true` (e.g.,
+     * Gmail's "starred", Linear's "todo").
      */
-    createDefault?: boolean;
+    todo?: boolean;
   }>;
   /** Whether this link type supports displaying and changing the assignee */
   supportsAssignee?: boolean;
   /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */
   defaultCreateThreads?: string;
+  /**
+   * Opt-in: declares this link type is composable from Plot via
+   * `Connector.onCreateLink`. Omit to make the link type sync-only (no
+   * "Create new …" picker entry).
+   *
+   * Connectors that need multiple compose modes for what users perceive as
+   * the same kind of thing (e.g. Slack channel post vs DM) should declare
+   * **separate linkTypes**, one per user-facing thread type. That keeps
+   * each linkType isomorphic to one filter chip.
+   */
+  compose?: ComposeConfig;
+  /**
+   * Per-connector contact roles. Examples:
+   *   email   → [{id:"to",label:"To",default:true},{id:"cc",label:"CC"},{id:"bcc",label:"BCC",hidden:true}]
+   *   calendar → [{id:"required",label:"Required",default:true},{id:"optional",label:"Optional"}]
+   *
+   * Plot uses this list to render a role picker on each contact chip in the
+   * composer and to label non-default roles on existing threads. Exactly one
+   * role should be marked `default: true`. Connectors that don't distinguish
+   * roles (Slack, Linear) omit this field entirely.
+   */
+  contactRoles?: ContactRoleConfig[];
+  /**
+   * Whether contacts on an existing thread can be added, removed, or have
+   * their role changed (email-style mid-thread recipient changes). When
+   * false, the thread's contact list is fixed after creation. Defaults to
+   * false when omitted.
+   */
+  supportsContactChanges?: boolean;
+  /**
+   * Declares how sharing on threads of this link type is scoped:
+   *
+   * - `"thread"` (default): one roster shared across all notes in the
+   *   thread. Native Plot threads, Slack DMs, calendar events.
+   * - `"channel"`: visibility is the external channel's membership;
+   *   the per-thread `contacts` array is ignored for sharing UI.
+   *   Slack channels, Linear projects.
+   * - `"message"`: each note carries its own recipient set via
+   *   `note.access_contacts`; the thread roster is the union across
+   *   all messages. Email.
+   *
+   * 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";
+};
+
+/**
+ * Declares how a link type is composable from Plot via
+ * `Connector.onCreateLink`. Attached to {@link LinkTypeConfig.compose}.
+ */
+export type ComposeConfig = {
+  /**
+   * Selects the destination model for the "Create new …" picker.
+   *
+   * - `"channels"` (default): one chip per enabled channel (e.g. a Linear
+   *   team, a Slack channel). Existing behaviour for task-tracker / calendar
+   *   connectors.
+   * - `"contacts"`: one chip per connection (account); the user picks
+   *   recipients from their contacts. The runtime pre-resolves the chosen
+   *   Plot contacts to platform account IDs via the per-connection
+   *   `contact_external_account` rows and delivers them as
+   *   `CreateLinkDraft.recipients`. Contacts without a row for this specific
+   *   connection are filtered out of the picker — used by closed-roster
+   *   messaging platforms (Slack DM, Teams DM, Google Chat DM, LinkedIn DM).
+   * - `"addresses"`: one chip per connection; the picker accepts any
+   *   contact with an addressable identifier (e.g. an email) or a free-form
+   *   typed address. The runtime fills `recipients` for contacts with a
+   *   connection-scoped row and falls back to the contact's primary address
+   *   (e.g. `contact.email`) when no row exists. Free-form addresses arrive
+   *   via the thread's `inviteEmails`. Used by open address spaces like
+   *   Gmail.
+   */
+  targets?: "channels" | "contacts" | "addresses";
+  /**
+   * Status to assign newly-created links. Should match an entry in the
+   * parent linkType's `statuses[]`, OR a symbolic id that the connector's
+   * `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`).
+   */
+  status: string;
+  /**
+   * Optional override for the picker chip / "Create new …" copy. Defaults
+   * to the parent linkType's `label`. Use to disambiguate compose entries
+   * when the parent label alone isn't specific enough (e.g. "Direct
+   * messages" for a DM-mode compose on a chat connector).
+   */
+  label?: string;
+};
+
+/**
+ * Declares one contact role for a connector's link type. See
+ * `LinkTypeConfig.contactRoles`.
+ */
+export type ContactRoleConfig = {
+  /** Stable machine id, e.g. "to" / "cc" / "bcc" / "required" / "optional". */
+  id: string;
+  /** Display label shown next to a contact chip, e.g. "To", "CC", "Required". */
+  label: string;
+  /** Exactly one role per linkType should be marked default. */
+  default?: boolean;
+  /**
+   * Hidden roles are visible only to (a) the contact themselves and
+   * (b) the user who added them. The API filters them out of every other
+   * viewer's `thread.contacts` and `thread.contactMeta`. Use for BCC-style
+   * semantics where other recipients must not see the hidden contact.
+   */
+  hidden?: boolean;
 };
 
 /**
@@ -185,31 +315,6 @@ export abstract class Integrations extends ITool {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;
 
-  /**
-   * Execute a callback as a specific actor, requesting auth if needed.
-   *
-   * If the actor has a valid token, calls the callback immediately with it.
-   * If the actor has no token, creates a private auth note in the specified
-   * activity prompting them to connect. Once they authorize, this callback fires.
-   *
-   * @param provider - The OAuth provider
-   * @param actorId - The actor to act as
-   * @param activityId - The activity to create an auth note in (if needed)
-   * @param callback - Function to call with the token
-   * @param extraArgs - Additional arguments to pass to the callback
-   */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  abstract actAs<
-    TArgs extends Serializable[],
-    TCallback extends (token: AuthToken, ...args: TArgs) => any
-  >(
-    provider: AuthProvider,
-    actorId: ActorId,
-    activityId: Uuid,
-    callback: TCallback,
-    ...extraArgs: TArgs
-  ): Promise<void>;
-
   /**
    * Saves a link with notes to the connector's priority.
    *
@@ -250,10 +355,15 @@ export abstract class Integrations extends ITool {
   abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;
 
   /**
-   * Saves contacts to the connector's priority.
+   * Upserts contacts into the connector's priority without requiring a Link.
+   *
+   * Use this for messaging connectors to bulk-sync workspace members so the
+   * recipient picker can filter contacts by reachable platform account. Populate
+   * `NewContact.source` to persist `contact_external_account` rows (the platform
+   * identity used to address the contact). Returns one `Actor` per input, in order.
    *
-   * @param contacts - Array of contacts to save
-   * @returns Promise resolving to the saved actors
+   * @param contacts - Contacts to upsert, keyed by `source`/`key`
+   * @returns Promise resolving to the saved actors, 1:1 with input order
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;