Merge pull request #274 from plotday/linkedin-channelid-followups-public

Require channelId on NewLinkWithNotes so connector write-back can't silently break

Author: KrisBraun

.changeset/require-link-channelid.md

@@ -0,0 +1,7 @@
+---
+"@plotday/twister": minor
+---
+
+Changed: `NewLinkWithNotes.channelId` (the type `integrations.saveLink()`/`saveLinks()` accept) is now required instead of optional. It was easy to set `channelId` only inside `meta` and forget the top-level field — that compiled fine but silently broke outbound write-back (`onNoteCreated` reads the channel back from the persisted `channelId`, not from `meta`) and bulk operations like `archiveLinks({ channelId })` on disable, with no error anywhere. The type system now catches this at compile time instead.
+
+Added: `CreateLinkResult` — the return type for `Connector.onCreateLink()`. Identical to `NewLinkWithNotes` except `channelId` stays optional, since the platform auto-fills it from the compose draft when omitted. Connectors implementing `onCreateLink` should update their return type from `NewLinkWithNotes | null` to `CreateLinkResult | null`.

connectors/AGENTS.md

@@ -301,13 +301,17 @@ Previews (`preview` fields) always use plain text — `snippet` or truncated tit
 
 ## Sync metadata injection
 
-Every synced link must carry provider and channel metadata — bulk operations (e.g. `integrations.archiveLinks({ channelId })` on disable) rely on it:
+Every synced link must carry provider and channel metadata:
 
 ```typescript
-link.channelId = resourceId; // first-class field on NewLink
+link.channelId = resourceId; // first-class field on NewLinkWithNotes — REQUIRED
 link.meta = { ...link.meta, syncProvider: "myprovider" };
 ```
 
+`channelId` is required on `NewLinkWithNotes` (the type `saveLink()`/`saveLinks()` accept) precisely because it's easy to set only inside `meta` and forget the top-level field — the type system will reject a link built that way. This isn't just about bulk operations like `integrations.archiveLinks({ channelId })` on disable: the platform persists `channelId` to the link's DB row and reads it back from there — not from `meta` — to populate `thread.meta.channelId` for connector callbacks like `onNoteCreated`. A link with `channelId` only inside `meta` will send replies to nobody: the connector's own `onNoteCreated` reads a channelId that was never actually saved, and typically no-ops silently (no error, nothing captured) because it can't resolve a client for the reply. Set `channelId` at the top level on every value you pass to `saveLink()`/`saveLinks()`.
+
+`onCreateLink` is the one exception: its return type is `CreateLinkResult`, where `channelId` is optional — the platform auto-fills it from `draft.channelId` (the channel the user composed into) if you omit it.
+
 ## Classifier facets (optional)
 
 Messaging-style connectors may set `link.facets` (`format` / `automation` / `reach` from `@plotday/twister/facets`) as internal classifier signal. Set a dimension only when a heuristic is confident; leave it `null`/omitted otherwise. See `gmail/src/gmail-facets.ts` and `slack/src/slack-facets.ts`.
@@ -520,7 +524,7 @@ For closed-roster DM-style compose set `compose.targets: "contacts"`; for open a
 Then implement `onCreateLink` — return the link, do NOT call `integrations.saveLink()` (platform wires it to the originating thread):
 
 ```typescript
-async onCreateLink(draft: CreateLinkDraft): Promise<NewLinkWithNotes | null> {
+async onCreateLink(draft: CreateLinkDraft): Promise<CreateLinkResult | null> {
   if (draft.type !== "issue") return null;
   const client = await this.getClient(draft.channelId);
   const payload = await client.createIssue({
@@ -609,7 +613,7 @@ Add to `pnpm-workspace.yaml` if not already covered by a glob.
 - [ ] Batch state writes use `this.setMany()`, never a per-item `set()` loop
 - [ ] Canonical, globally-unique `source` using immutable ids; mutable keys in `meta` only
 - [ ] `note.key` for note-level upserts
-- [ ] Set `link.channelId` and inject `syncProvider` into `link.meta`
+- [ ] Set `link.channelId` (top-level field, required) and inject `syncProvider` into `link.meta`
 - [ ] `contentType: "html"` for HTML — never strip tags locally
 - [ ] `created` on notes = external timestamp, not sync time
 - [ ] `initialSync` propagated through every entry point and batch; set `unread: false, archived: false` on initial, omit on incremental
@@ -622,7 +626,7 @@ Add to `pnpm-workspace.yaml` if not already covered by a glob.
 ## Common pitfalls
 
 1. Passing functions/`undefined`/RPC stubs to `this.callback()` → use tokens + `null`.
-2. Forgetting sync metadata (`link.channelId`, `meta.syncProvider`) → breaks bulk archive on disable.
+2. Setting `channelId` only inside `link.meta` instead of at the top level → `NewLinkWithNotes.channelId` is what the platform actually persists and reads back for connector callbacks (`thread.meta.channelId` in `onNoteCreated`, etc.) and for bulk operations like `integrations.archiveLinks({ channelId })` on disable. A `meta`-only channelId compiles fine structurally but leaves outbound replies (and disable-time cleanup) silently broken — no error, nothing captured. The type system now requires the top-level field on `NewLinkWithNotes`, so this fails to compile instead of failing silently in production.
 3. Not propagating `initialSync` through the whole pipeline → notification spam.
 4. Mutable ids in `source` (e.g. Jira issue key) → use immutable id, store key in `meta`.
 5. `source` that's only unique within one user's account → breaks cross-user dedup; add workspace/tenant/mailbox qualifier.

connectors/github/src/issue-sync.ts

@@ -94,7 +94,6 @@ export async function syncIssueBatch(
     );
 
     if (link) {
-      link.channelId = repositoryId;
       link.meta = {
         ...link.meta,
         syncProvider: "github",
@@ -209,6 +208,7 @@ async function convertIssueToLink(
   }
 
   const link: NewLinkWithNotes = {
+    channelId: repositoryId,
     source: `github:issue:${owner}/${repo}/${issue.number}`,
     type: "issue",
     title: issue.title,

connectors/github/src/pr-sync.ts

@@ -102,7 +102,6 @@ export async function syncPRBatch(
     );
 
     if (thread) {
-      thread.channelId = repositoryId;
       thread.meta = {
         ...thread.meta,
         syncProvider: "github",
@@ -219,6 +218,7 @@ async function convertPRToThread(
   }
 
   const thread: NewLinkWithNotes = {
+    channelId: repositoryId,
     source: `github:pr:${owner}/${repo}/${pr.number}`,
     type: "pull_request",
     title: pr.title,

connectors/gmail/src/gmail-api.ts

@@ -855,8 +855,11 @@ export function collectAttachments(
  */
 export function transformGmailThread(thread: GmailThread): NewLinkWithNotes {
   if (!thread.messages || thread.messages.length === 0) {
-    // Return empty structure for invalid threads
+    // Return empty structure for invalid threads. channelId is unknown at
+    // this call site — the caller always sets the real value right after
+    // (see "Inject channel ID" in sync.ts) before saving.
     return {
+      channelId: null,
       type: "email",
       title: "",
       notes: [],
@@ -909,8 +912,10 @@ export function transformGmailThread(thread: GmailThread): NewLinkWithNotes {
     }
   }
 
-  // Create link
+  // Create link. channelId is unknown here — the caller always sets the
+  // real value right after (see "Inject channel ID" in sync.ts) before saving.
   const plotThread: NewLinkWithNotes = {
+    channelId: null,
     source: canonicalUrl,
     type: "email",
     title: subject || "Email",

connectors/gmail/src/gmail.ts

@@ -4,7 +4,7 @@ import {
   type NoteWriteBackResult,
   type ToolBuilder,
 } from "@plotday/twister";
-import type { Actor, NewLinkWithNotes, Note, Thread } from "@plotday/twister/plot";
+import type { Actor, CreateLinkResult, Note, Thread } from "@plotday/twister/plot";
 import {
   AuthProvider,
   type AuthToken,
@@ -774,7 +774,7 @@ export class Gmail extends Connector<Gmail> {
    */
   override async onCreateLink(
     draft: CreateLinkDraft
-  ): Promise<NewLinkWithNotes | null> {
+  ): Promise<CreateLinkResult | null> {
     return onCreateLinkFn(this.makeHost(), draft);
   }
 

connectors/gmail/src/sync.ts

@@ -26,6 +26,7 @@ import { ActionType } from "@plotday/twister/plot";
 import type {
   Actor,
   ActorId,
+  CreateLinkResult,
   NewLinkWithNotes,
   Note,
   Thread,
@@ -1968,7 +1969,7 @@ async function onCreateLinkForwardFn(
   host: GmailSyncHost,
   draft: CreateLinkDraft,
   forwardKey: string
-): Promise<NewLinkWithNotes | null> {
+): Promise<CreateLinkResult | null> {
   const api = await getApiAnyFn(host);
   if (!api) {
     console.error(
@@ -2154,7 +2155,7 @@ async function onCreateLinkForwardFn(
 export async function onCreateLinkFn(
   host: GmailSyncHost,
   draft: CreateLinkDraft
-): Promise<NewLinkWithNotes | null> {
+): Promise<CreateLinkResult | null> {
   if (draft.type !== "email") return null;
 
   if (draft.forward) {

connectors/google-calendar/src/sync.ts

@@ -725,6 +725,7 @@ export async function processCalendarEventsFn(
           };
 
           const link: NewLinkWithNotes = {
+            channelId: calendarId,
             source: canonicalUrl,
             sources: buildEventSources({
               iCalUID: event.iCalUID,
@@ -760,7 +761,6 @@ export async function processCalendarEventsFn(
             ...(initialSync ? { archived: false } : {}),
           };
 
-          link.channelId = calendarId;
           link.meta = {
             ...link.meta,
             syncProvider: "google",
@@ -905,6 +905,7 @@ export async function processCalendarEventsFn(
         ];
 
         const link: NewLinkWithNotes = {
+          channelId: calendarId,
           source: canonicalUrl,
           sources: buildEventSources({
             iCalUID: event.iCalUID,
@@ -943,7 +944,6 @@ export async function processCalendarEventsFn(
           ...(initialSync ? { archived: false } : {}),
         };
 
-        link.channelId = calendarId;
         link.meta = {
           ...link.meta,
           syncProvider: "google",

connectors/google-chat/src/google-chat-api.ts

@@ -657,6 +657,7 @@ export function transformChatThread(
   const preview = firstMessage.text?.substring(0, 200) ?? null;
 
   return {
+    channelId: spaceId,
     source: `google-chat:${spaceId}:thread:${threadKey}`,
     type: "thread",
     title,

connectors/google/src/google.ts

@@ -67,7 +67,7 @@ import type {
   Thread,
   ToolBuilder,
 } from "@plotday/twister";
-import type { NewLinkWithNotes, Note } from "@plotday/twister/plot";
+import type { CreateLinkResult, Note } from "@plotday/twister/plot";
 import type { ScheduleContactStatus } from "@plotday/twister/schedule";
 import {
   AuthProvider,
@@ -871,7 +871,7 @@ export class Google extends Connector<Google> {
    */
   override async onCreateLink(
     draft: CreateLinkDraft
-  ): Promise<NewLinkWithNotes | null> {
+  ): Promise<CreateLinkResult | null> {
     if (draft.type === "task") {
       return tasksOnCreateLinkFn(this.makeTasksHost(), draft);
     }