feat(trello): Trello connector + structured-item SDK foundation

.changeset/structured-item-fields.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: structured-item note fields (`sectionKey`, `sectionLabel`, `sectionPosition`, `itemPosition`), `Note.tagActors` (dispatch-time hydrated assignees), and `Actor.source.accountId` (external account id resolved at dispatch).

.changeset/trello-auth-provider.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `AuthProvider.Trello` for the Trello connector's token-authorize flow.

connectors/trello/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plot Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

connectors/trello/README.md

@@ -0,0 +1,3 @@
+# @plotday/connector-trello
+
+This connector syncs your Trello boards and cards into Plot, giving you a unified view of all your work across tools. It supports bidirectional sync: cards appear in Plot with their current status (list), assignees, and comments, and changes you make in Plot — checking off a card, adding a comment — are written back to Trello automatically. When a card moves between lists or is archived in Trello, Plot reflects the change on the next sync cycle.

connectors/trello/package.json

@@ -0,0 +1,43 @@
+{
+ "name": "@plotday/connector-trello",
+ "plotTwistId": "06829c6d-d28f-42bd-8ca8-fede11dd0582",
+ "displayName": "Trello",
+ "description": "Track your Trello cards and check them off as work moves forward.",
+ "logoUrl": "https://api.iconify.design/logos/trello.svg",
+ "publisher": "Plot",
+ "publisherUrl": "https://plot.day",
+ "author": "Plot <team@plot.day> (https://plot.day)",
+ "license": "MIT",
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "private": true,
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "deploy": "plot deploy",
+ "lint": "plot lint",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "@types/node": "^25.0.3",
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ },
+ "repository": { "type": "git", "url": "https://github.com/plotday/plot.git", "directory": "connectors/trello" },
+ "homepage": "https://plot.day",
+ "bugs": { "url": "https://github.com/plotday/plot/issues" },
+ "keywords": ["plot", "connector", "trello", "project-management"]
+}

connectors/trello/src/index.ts

@@ -0,0 +1 @@
+export { default, Trello } from "./trello";

connectors/trello/src/trello-api.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TrelloApi, verifyTrelloWebhook, cardCreatedAt } from "./trello-api";
+
+afterEach(() => vi.restoreAllMocks());
+
+function mockFetchOnce(json: unknown, ok = true, status = 200) {
+ return vi.spyOn(globalThis, "fetch").mockResolvedValue(
+ new Response(JSON.stringify(json), { status: ok ? status : 400 }),
+ );
+}
+
+describe("TrelloApi request shaping", () => {
+ const api = new TrelloApi("KEY", "TOK");
+
+ it("getBoards calls /members/me/boards with key+token", async () => {
+ const f = mockFetchOnce([{ id: "b1", name: "Board" }]);
+ const boards = await api.getBoards();
+ expect(boards).toEqual([{ id: "b1", name: "Board" }]);
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("https://api.trello.com/1/members/me/boards");
+ expect(url).toContain("key=KEY");
+ expect(url).toContain("token=TOK");
+ expect(url).toContain("filter=open");
+ });
+
+ it("getCards passes limit + before for pagination", async () => {
+ const f = mockFetchOnce([]);
+ await api.getCards("b1", { limit: 50, before: "card9" });
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("/boards/b1/cards");
+ expect(url).toContain("limit=50");
+ expect(url).toContain("before=card9");
+ expect(url).toContain("actions=commentCard");
+ expect(url).toContain("attachments=true");
+ expect(url).toContain("members=true");
+ });
+
+ it("addComment POSTs to /cards/{id}/actions/comments and returns the action", async () => {
+ const f = mockFetchOnce({ id: "act1", type: "commentCard", date: "2026-01-01T00:00:00Z", data: { text: "hi" } });
+ const action = await api.addComment("c1", "hi");
+ expect(action.id).toBe("act1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/cards/c1/actions/comments");
+ expect(url).toContain("text=hi");
+ expect(init.method).toBe("POST");
+ });
+
+ it("createWebhook POSTs idModel + callbackURL", async () => {
+ const f = mockFetchOnce({ id: "wh1" });
+ const res = await api.createWebhook("b1", "https://api.plot.test/hook/abc");
+ expect(res.id).toBe("wh1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/webhooks");
+ expect(init.method).toBe("POST");
+ const body = String(init.body);
+ expect(body).toContain("idModel=b1");
+ expect(body).toContain("callbackURL=");
+ });
+});
+
+describe("cardCreatedAt", () => {
+ it("decodes the timestamp from the first 8 hex chars of the id", () => {
+ // 0x5f000000 = 1593817600 → 2020-07-03T...; assert it parses to that epoch.
+ const d = cardCreatedAt("5f000000aaaaaaaaaaaaaaaa");
+ expect(d.getTime()).toBe(0x5f000000 * 1000);
+ });
+});
+
+describe("verifyTrelloWebhook", () => {
+ it("accepts a correct HMAC-SHA1 signature and rejects a wrong one", async () => {
+ const secret = "shh";
+ const body = '{"action":{"type":"updateCard"}}';
+ const callbackURL = "https://api.plot.test/hook/abc";
+ // Compute the expected signature with the same primitive the impl uses.
+ const key = await crypto.subtle.importKey(
+ "raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-1" }, false, ["sign"],
+ );
+ const sigBuf = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(body + callbackURL));
+ const good = btoa(String.fromCharCode(...new Uint8Array(sigBuf)));
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, good)).toBe(true);
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, "wrong")).toBe(false);
+ });
+});

connectors/trello/src/trello-api.ts

@@ -0,0 +1,168 @@
+// Cloudflare Workers provide Buffer/crypto globally; we use Web Crypto + btoa.
+export type TrelloBoard = { id: string; name: string };
+export type TrelloList = { id: string; name: string; pos: number };
+export type TrelloMember = {
+ id: string;
+ fullName: string | null;
+ username: string | null;
+ avatarUrl: string | null;
+};
+export type TrelloAttachment = {
+ id: string;
+ name: string;
+ url: string;
+ bytes: number | null;
+ mimeType: string | null;
+};
+export type TrelloCommentAction = {
+ id: string;
+ type: "commentCard";
+ date: string;
+ memberCreator: TrelloMember | null;
+ data: { text: string };
+};
+export type TrelloCard = {
+ id: string;
+ name: string;
+ desc: string;
+ idList: string;
+ idBoard: string;
+ closed: boolean;
+ url: string;
+ idMembers: string[];
+ members?: TrelloMember[];
+ attachments?: TrelloAttachment[];
+ actions?: TrelloCommentAction[];
+ dateLastActivity: string;
+};
+
+const BASE = "https://api.trello.com/1";
+const CARD_FIELDS = "id,name,desc,idList,idBoard,closed,url,idMembers,dateLastActivity";
+const MEMBER_FIELDS = "id,fullName,username,avatarUrl";
+
+export class TrelloApi {
+ constructor(
+ private readonly key: string,
+ private readonly token: string,
+ ) {}
+
+ private auth(extra = ""): string {
+ const sep = extra ? "&" : "";
+ return `key=${encodeURIComponent(this.key)}&token=${encodeURIComponent(this.token)}${sep}${extra}`;
+ }
+
+ private async req<T>(method: string, path: string, query = "", body?: string): Promise<T> {
+ const url = `${BASE}${path}?${this.auth(body !== undefined ? "" : query)}`;
+ const headers: Record<string, string> = { Accept: "application/json" };
+ if (body !== undefined) headers["Content-Type"] = "application/x-www-form-urlencoded";
+ const res = await fetch(url, { method, headers, ...(body !== undefined ? { body } : {}) });
+ if (!res.ok) {
+ throw new Error(`Trello ${method} ${path} failed: ${res.status} ${await res.text()}`);
+ }
+ return (await res.json()) as T;
+ }
+
+ getBoards(): Promise<TrelloBoard[]> {
+ return this.req("GET", "/members/me/boards", "filter=open&fields=id,name");
+ }
+
+ getLists(boardId: string): Promise<TrelloList[]> {
+ return this.req("GET", `/boards/${boardId}/lists`, "filter=open&fields=id,name,pos");
+ }
+
+ getCards(boardId: string, opts: { limit: number; before?: string }): Promise<TrelloCard[]> {
+ const q = [
+ "filter=open",
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ `limit=${opts.limit}`,
+ ...(opts.before ? [`before=${opts.before}`] : []),
+ ].join("&");
+ return this.req("GET", `/boards/${boardId}/cards`, q);
+ }
+
+ getCard(cardId: string): Promise<TrelloCard> {
+ const q = [
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ ].join("&");
+ return this.req("GET", `/cards/${cardId}`, q);
+ }
+
+ createCard(p: { idList: string; name: string; desc?: string }): Promise<TrelloCard> {
+ const q = [
+ `idList=${encodeURIComponent(p.idList)}`,
+ `name=${encodeURIComponent(p.name)}`,
+ ...(p.desc ? [`desc=${encodeURIComponent(p.desc)}`] : []),
+ ].join("&");
+ return this.req("POST", "/cards", q);
+ }
+
+ updateCard(
+ cardId: string,
+ fields: { idList?: string; closed?: boolean; name?: string; desc?: string },
+ ): Promise<TrelloCard> {
+ const parts: string[] = [];
+ if (fields.idList !== undefined) parts.push(`idList=${encodeURIComponent(fields.idList)}`);
+ if (fields.closed !== undefined) parts.push(`closed=${fields.closed}`);
+ if (fields.name !== undefined) parts.push(`name=${encodeURIComponent(fields.name)}`);
+ if (fields.desc !== undefined) parts.push(`desc=${encodeURIComponent(fields.desc)}`);
+ return this.req("PUT", `/cards/${cardId}`, parts.join("&"));
+ }
+
+ addComment(cardId: string, text: string): Promise<TrelloCommentAction> {
+ return this.req("POST", `/cards/${cardId}/actions/comments`, `text=${encodeURIComponent(text)}`);
+ }
+
+ updateComment(actionId: string, text: string): Promise<{ id: string; data: { text: string } }> {
+ return this.req("PUT", `/actions/${actionId}`, `text=${encodeURIComponent(text)}`);
+ }
+
+ createWebhook(boardId: string, callbackURL: string): Promise<{ id: string }> {
+ const body = `idModel=${encodeURIComponent(boardId)}&callbackURL=${encodeURIComponent(callbackURL)}&description=${encodeURIComponent("Plot Trello sync")}`;
+ return this.req("POST", "/webhooks", "", body);
+ }
+
+ deleteWebhook(webhookId: string): Promise<unknown> {
+ return this.req("DELETE", `/webhooks/${webhookId}`);
+ }
+}
+
+/** Trello object ids encode their creation time in the first 8 hex chars (unix seconds). */
+export function cardCreatedAt(cardId: string): Date {
+ const seconds = parseInt(cardId.substring(0, 8), 16);
+ return new Date(seconds * 1000);
+}
+
+/** Verify a Trello webhook: base64(HMAC-SHA1(appSecret, rawBody + callbackURL)) === header. */
+export async function verifyTrelloWebhook(
+ secret: string,
+ rawBody: string,
+ callbackURL: string,
+ signature: string,
+): Promise<boolean> {
+ try {
+ const key = await crypto.subtle.importKey(
+ "raw",
+ new TextEncoder().encode(secret),
+ { name: "HMAC", hash: "SHA-1" },
+ false,
+ ["sign"],
+ );
+ const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(rawBody + callbackURL));
+ const expected = btoa(String.fromCharCode(...new Uint8Array(sig)));
+ return expected === signature;
+ } catch {
+ return false;
+ }
+}

connectors/trello/src/trello-channels.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { buildCardLinkType, DONE_LIST_RE } from "./trello-channels";
+import type { TrelloList } from "./trello-api";
+
+const lists: TrelloList[] = [
+ { id: "l1", name: "To Do", pos: 1 },
+ { id: "l2", name: "Doing", pos: 2 },
+ { id: "l3", name: "Done", pos: 3 },
+];
+
+describe("buildCardLinkType", () => {
+ it("maps lists to statuses: first=todo, middle=inProgress, done-name=done+done:true", () => {
+ const lt = buildCardLinkType(lists);
+ expect(lt.type).toBe("card");
+ expect(lt.statuses).toEqual([
+ { status: "l1", label: "To Do", icon: "todo" },
+ { status: "l2", label: "Doing", icon: "inProgress" },
+ { status: "l3", label: "Done", icon: "done", done: true },
+ ]);
+ // compose defaults to the first non-done list
+ expect(lt.compose).toEqual({ status: "l1" });
+ });
+
+ it("DONE_LIST_RE matches common done-column names", () => {
+ expect(DONE_LIST_RE.test("Done")).toBe(true);
+ expect(DONE_LIST_RE.test("Shipped")).toBe(true);
+ expect(DONE_LIST_RE.test("Complete")).toBe(true);
+ expect(DONE_LIST_RE.test("Backlog")).toBe(false);
+ });
+
+ it("falls back to the first list for compose when no non-done list exists", () => {
+ const lt = buildCardLinkType([{ id: "d", name: "Done", pos: 1 }]);
+ expect(lt.compose).toEqual({ status: "d" });
+ });
+});

.changeset/structured-item-fields.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: structured-item note fields (`sectionKey`, `sectionLabel`, `sectionPosition`, `itemPosition`), `Note.tagActors` (dispatch-time hydrated assignees), and `Actor.source.accountId` (external account id resolved at dispatch).

.changeset/trello-auth-provider.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `AuthProvider.Trello` for the Trello connector's token-authorize flow.

connectors/trello/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plot Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

connectors/trello/README.md

@@ -0,0 +1,3 @@
+# @plotday/connector-trello
+
+This connector syncs your Trello boards and cards into Plot, giving you a unified view of all your work across tools. It supports bidirectional sync: cards appear in Plot with their current status (list), assignees, and comments, and changes you make in Plot — checking off a card, adding a comment — are written back to Trello automatically. When a card moves between lists or is archived in Trello, Plot reflects the change on the next sync cycle.

connectors/trello/package.json

@@ -0,0 +1,43 @@
+{
+ "name": "@plotday/connector-trello",
+ "plotTwistId": "06829c6d-d28f-42bd-8ca8-fede11dd0582",
+ "displayName": "Trello",
+ "description": "Track your Trello cards and check them off as work moves forward.",
+ "logoUrl": "https://api.iconify.design/logos/trello.svg",
+ "publisher": "Plot",
+ "publisherUrl": "https://plot.day",
+ "author": "Plot <team@plot.day> (https://plot.day)",
+ "license": "MIT",
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "private": true,
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "deploy": "plot deploy",
+ "lint": "plot lint",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "@types/node": "^25.0.3",
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ },
+ "repository": { "type": "git", "url": "https://github.com/plotday/plot.git", "directory": "connectors/trello" },
+ "homepage": "https://plot.day",
+ "bugs": { "url": "https://github.com/plotday/plot/issues" },
+ "keywords": ["plot", "connector", "trello", "project-management"]
+}

connectors/trello/src/index.ts

@@ -0,0 +1 @@
+export { default, Trello } from "./trello";

connectors/trello/src/trello-api.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TrelloApi, verifyTrelloWebhook, cardCreatedAt } from "./trello-api";
+
+afterEach(() => vi.restoreAllMocks());
+
+function mockFetchOnce(json: unknown, ok = true, status = 200) {
+ return vi.spyOn(globalThis, "fetch").mockResolvedValue(
+ new Response(JSON.stringify(json), { status: ok ? status : 400 }),
+ );
+}
+
+describe("TrelloApi request shaping", () => {
+ const api = new TrelloApi("KEY", "TOK");
+
+ it("getBoards calls /members/me/boards with key+token", async () => {
+ const f = mockFetchOnce([{ id: "b1", name: "Board" }]);
+ const boards = await api.getBoards();
+ expect(boards).toEqual([{ id: "b1", name: "Board" }]);
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("https://api.trello.com/1/members/me/boards");
+ expect(url).toContain("key=KEY");
+ expect(url).toContain("token=TOK");
+ expect(url).toContain("filter=open");
+ });
+
+ it("getCards passes limit + before for pagination", async () => {
+ const f = mockFetchOnce([]);
+ await api.getCards("b1", { limit: 50, before: "card9" });
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("/boards/b1/cards");
+ expect(url).toContain("limit=50");
+ expect(url).toContain("before=card9");
+ expect(url).toContain("actions=commentCard");
+ expect(url).toContain("attachments=true");
+ expect(url).toContain("members=true");
+ });
+
+ it("addComment POSTs to /cards/{id}/actions/comments and returns the action", async () => {
+ const f = mockFetchOnce({ id: "act1", type: "commentCard", date: "2026-01-01T00:00:00Z", data: { text: "hi" } });
+ const action = await api.addComment("c1", "hi");
+ expect(action.id).toBe("act1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/cards/c1/actions/comments");
+ expect(url).toContain("text=hi");
+ expect(init.method).toBe("POST");
+ });
+
+ it("createWebhook POSTs idModel + callbackURL", async () => {
+ const f = mockFetchOnce({ id: "wh1" });
+ const res = await api.createWebhook("b1", "https://api.plot.test/hook/abc");
+ expect(res.id).toBe("wh1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/webhooks");
+ expect(init.method).toBe("POST");
+ const body = String(init.body);
+ expect(body).toContain("idModel=b1");
+ expect(body).toContain("callbackURL=");
+ });
+});
+
+describe("cardCreatedAt", () => {
+ it("decodes the timestamp from the first 8 hex chars of the id", () => {
+ // 0x5f000000 = 1593817600 → 2020-07-03T...; assert it parses to that epoch.
+ const d = cardCreatedAt("5f000000aaaaaaaaaaaaaaaa");
+ expect(d.getTime()).toBe(0x5f000000 * 1000);
+ });
+});
+
+describe("verifyTrelloWebhook", () => {
+ it("accepts a correct HMAC-SHA1 signature and rejects a wrong one", async () => {
+ const secret = "shh";
+ const body = '{"action":{"type":"updateCard"}}';
+ const callbackURL = "https://api.plot.test/hook/abc";
+ // Compute the expected signature with the same primitive the impl uses.
+ const key = await crypto.subtle.importKey(
+ "raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-1" }, false, ["sign"],
+ );
+ const sigBuf = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(body + callbackURL));
+ const good = btoa(String.fromCharCode(...new Uint8Array(sigBuf)));
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, good)).toBe(true);
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, "wrong")).toBe(false);
+ });
+});

connectors/trello/src/trello-api.ts

@@ -0,0 +1,168 @@
+// Cloudflare Workers provide Buffer/crypto globally; we use Web Crypto + btoa.
+export type TrelloBoard = { id: string; name: string };
+export type TrelloList = { id: string; name: string; pos: number };
+export type TrelloMember = {
+ id: string;
+ fullName: string | null;
+ username: string | null;
+ avatarUrl: string | null;
+};
+export type TrelloAttachment = {
+ id: string;
+ name: string;
+ url: string;
+ bytes: number | null;
+ mimeType: string | null;
+};
+export type TrelloCommentAction = {
+ id: string;
+ type: "commentCard";
+ date: string;
+ memberCreator: TrelloMember | null;
+ data: { text: string };
+};
+export type TrelloCard = {
+ id: string;
+ name: string;
+ desc: string;
+ idList: string;
+ idBoard: string;
+ closed: boolean;
+ url: string;
+ idMembers: string[];
+ members?: TrelloMember[];
+ attachments?: TrelloAttachment[];
+ actions?: TrelloCommentAction[];
+ dateLastActivity: string;
+};
+
+const BASE = "https://api.trello.com/1";
+const CARD_FIELDS = "id,name,desc,idList,idBoard,closed,url,idMembers,dateLastActivity";
+const MEMBER_FIELDS = "id,fullName,username,avatarUrl";
+
+export class TrelloApi {
+ constructor(
+ private readonly key: string,
+ private readonly token: string,
+ ) {}
+
+ private auth(extra = ""): string {
+ const sep = extra ? "&" : "";
+ return `key=${encodeURIComponent(this.key)}&token=${encodeURIComponent(this.token)}${sep}${extra}`;
+ }
+
+ private async req<T>(method: string, path: string, query = "", body?: string): Promise<T> {
+ const url = `${BASE}${path}?${this.auth(body !== undefined ? "" : query)}`;
+ const headers: Record<string, string> = { Accept: "application/json" };
+ if (body !== undefined) headers["Content-Type"] = "application/x-www-form-urlencoded";
+ const res = await fetch(url, { method, headers, ...(body !== undefined ? { body } : {}) });
+ if (!res.ok) {
+ throw new Error(`Trello ${method} ${path} failed: ${res.status} ${await res.text()}`);
+ }
+ return (await res.json()) as T;
+ }
+
+ getBoards(): Promise<TrelloBoard[]> {
+ return this.req("GET", "/members/me/boards", "filter=open&fields=id,name");
+ }
+
+ getLists(boardId: string): Promise<TrelloList[]> {
+ return this.req("GET", `/boards/${boardId}/lists`, "filter=open&fields=id,name,pos");
+ }
+
+ getCards(boardId: string, opts: { limit: number; before?: string }): Promise<TrelloCard[]> {
+ const q = [
+ "filter=open",
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ `limit=${opts.limit}`,
+ ...(opts.before ? [`before=${opts.before}`] : []),
+ ].join("&");
+ return this.req("GET", `/boards/${boardId}/cards`, q);
+ }
+
+ getCard(cardId: string): Promise<TrelloCard> {
+ const q = [
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ ].join("&");
+ return this.req("GET", `/cards/${cardId}`, q);
+ }
+
+ createCard(p: { idList: string; name: string; desc?: string }): Promise<TrelloCard> {
+ const q = [
+ `idList=${encodeURIComponent(p.idList)}`,
+ `name=${encodeURIComponent(p.name)}`,
+ ...(p.desc ? [`desc=${encodeURIComponent(p.desc)}`] : []),
+ ].join("&");
+ return this.req("POST", "/cards", q);
+ }
+
+ updateCard(
+ cardId: string,
+ fields: { idList?: string; closed?: boolean; name?: string; desc?: string },
+ ): Promise<TrelloCard> {
+ const parts: string[] = [];
+ if (fields.idList !== undefined) parts.push(`idList=${encodeURIComponent(fields.idList)}`);
+ if (fields.closed !== undefined) parts.push(`closed=${fields.closed}`);
+ if (fields.name !== undefined) parts.push(`name=${encodeURIComponent(fields.name)}`);
+ if (fields.desc !== undefined) parts.push(`desc=${encodeURIComponent(fields.desc)}`);
+ return this.req("PUT", `/cards/${cardId}`, parts.join("&"));
+ }
+
+ addComment(cardId: string, text: string): Promise<TrelloCommentAction> {
+ return this.req("POST", `/cards/${cardId}/actions/comments`, `text=${encodeURIComponent(text)}`);
+ }
+
+ updateComment(actionId: string, text: string): Promise<{ id: string; data: { text: string } }> {
+ return this.req("PUT", `/actions/${actionId}`, `text=${encodeURIComponent(text)}`);
+ }
+
+ createWebhook(boardId: string, callbackURL: string): Promise<{ id: string }> {
+ const body = `idModel=${encodeURIComponent(boardId)}&callbackURL=${encodeURIComponent(callbackURL)}&description=${encodeURIComponent("Plot Trello sync")}`;
+ return this.req("POST", "/webhooks", "", body);
+ }
+
+ deleteWebhook(webhookId: string): Promise<unknown> {
+ return this.req("DELETE", `/webhooks/${webhookId}`);
+ }
+}
+
+/** Trello object ids encode their creation time in the first 8 hex chars (unix seconds). */
+export function cardCreatedAt(cardId: string): Date {
+ const seconds = parseInt(cardId.substring(0, 8), 16);
+ return new Date(seconds * 1000);
+}
+
+/** Verify a Trello webhook: base64(HMAC-SHA1(appSecret, rawBody + callbackURL)) === header. */
+export async function verifyTrelloWebhook(
+ secret: string,
+ rawBody: string,
+ callbackURL: string,
+ signature: string,
+): Promise<boolean> {
+ try {
+ const key = await crypto.subtle.importKey(
+ "raw",
+ new TextEncoder().encode(secret),
+ { name: "HMAC", hash: "SHA-1" },
+ false,
+ ["sign"],
+ );
+ const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(rawBody + callbackURL));
+ const expected = btoa(String.fromCharCode(...new Uint8Array(sig)));
+ return expected === signature;
+ } catch {
+ return false;
+ }
+}

connectors/trello/src/trello-channels.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { buildCardLinkType, DONE_LIST_RE } from "./trello-channels";
+import type { TrelloList } from "./trello-api";
+
+const lists: TrelloList[] = [
+ { id: "l1", name: "To Do", pos: 1 },
+ { id: "l2", name: "Doing", pos: 2 },
+ { id: "l3", name: "Done", pos: 3 },
+];
+
+describe("buildCardLinkType", () => {
+ it("maps lists to statuses: first=todo, middle=inProgress, done-name=done+done:true", () => {
+ const lt = buildCardLinkType(lists);
+ expect(lt.type).toBe("card");
+ expect(lt.statuses).toEqual([
+ { status: "l1", label: "To Do", icon: "todo" },
+ { status: "l2", label: "Doing", icon: "inProgress" },
+ { status: "l3", label: "Done", icon: "done", done: true },
+ ]);
+ // compose defaults to the first non-done list
+ expect(lt.compose).toEqual({ status: "l1" });
+ });
+
+ it("DONE_LIST_RE matches common done-column names", () => {
+ expect(DONE_LIST_RE.test("Done")).toBe(true);
+ expect(DONE_LIST_RE.test("Shipped")).toBe(true);
+ expect(DONE_LIST_RE.test("Complete")).toBe(true);
+ expect(DONE_LIST_RE.test("Backlog")).toBe(false);
+ });
+
+ it("falls back to the first list for compose when no non-done list exists", () => {
+ const lt = buildCardLinkType([{ id: "d", name: "Done", pos: 1 }]);
+ expect(lt.compose).toEqual({ status: "d" });
+ });
+});

.changeset/structured-item-fields.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: structured-item note fields (`sectionKey`, `sectionLabel`, `sectionPosition`, `itemPosition`), `Note.tagActors` (dispatch-time hydrated assignees), and `Actor.source.accountId` (external account id resolved at dispatch).

.changeset/trello-auth-provider.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `AuthProvider.Trello` for the Trello connector's token-authorize flow.

connectors/trello/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plot Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

connectors/trello/README.md

@@ -0,0 +1,3 @@
+# @plotday/connector-trello
+
+This connector syncs your Trello boards and cards into Plot, giving you a unified view of all your work across tools. It supports bidirectional sync: cards appear in Plot with their current status (list), assignees, and comments, and changes you make in Plot — checking off a card, adding a comment — are written back to Trello automatically. When a card moves between lists or is archived in Trello, Plot reflects the change on the next sync cycle.

connectors/trello/package.json

@@ -0,0 +1,43 @@
+{
+ "name": "@plotday/connector-trello",
+ "plotTwistId": "06829c6d-d28f-42bd-8ca8-fede11dd0582",
+ "displayName": "Trello",
+ "description": "Track your Trello cards and check them off as work moves forward.",
+ "logoUrl": "https://api.iconify.design/logos/trello.svg",
+ "publisher": "Plot",
+ "publisherUrl": "https://plot.day",
+ "author": "Plot <team@plot.day> (https://plot.day)",
+ "license": "MIT",
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "private": true,
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "deploy": "plot deploy",
+ "lint": "plot lint",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "@types/node": "^25.0.3",
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ },
+ "repository": { "type": "git", "url": "https://github.com/plotday/plot.git", "directory": "connectors/trello" },
+ "homepage": "https://plot.day",
+ "bugs": { "url": "https://github.com/plotday/plot/issues" },
+ "keywords": ["plot", "connector", "trello", "project-management"]
+}

connectors/trello/src/index.ts

@@ -0,0 +1 @@
+export { default, Trello } from "./trello";

connectors/trello/src/trello-api.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TrelloApi, verifyTrelloWebhook, cardCreatedAt } from "./trello-api";
+
+afterEach(() => vi.restoreAllMocks());
+
+function mockFetchOnce(json: unknown, ok = true, status = 200) {
+ return vi.spyOn(globalThis, "fetch").mockResolvedValue(
+ new Response(JSON.stringify(json), { status: ok ? status : 400 }),
+ );
+}
+
+describe("TrelloApi request shaping", () => {
+ const api = new TrelloApi("KEY", "TOK");
+
+ it("getBoards calls /members/me/boards with key+token", async () => {
+ const f = mockFetchOnce([{ id: "b1", name: "Board" }]);
+ const boards = await api.getBoards();
+ expect(boards).toEqual([{ id: "b1", name: "Board" }]);
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("https://api.trello.com/1/members/me/boards");
+ expect(url).toContain("key=KEY");
+ expect(url).toContain("token=TOK");
+ expect(url).toContain("filter=open");
+ });
+
+ it("getCards passes limit + before for pagination", async () => {
+ const f = mockFetchOnce([]);
+ await api.getCards("b1", { limit: 50, before: "card9" });
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("/boards/b1/cards");
+ expect(url).toContain("limit=50");
+ expect(url).toContain("before=card9");
+ expect(url).toContain("actions=commentCard");
+ expect(url).toContain("attachments=true");
+ expect(url).toContain("members=true");
+ });
+
+ it("addComment POSTs to /cards/{id}/actions/comments and returns the action", async () => {
+ const f = mockFetchOnce({ id: "act1", type: "commentCard", date: "2026-01-01T00:00:00Z", data: { text: "hi" } });
+ const action = await api.addComment("c1", "hi");
+ expect(action.id).toBe("act1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/cards/c1/actions/comments");
+ expect(url).toContain("text=hi");
+ expect(init.method).toBe("POST");
+ });
+
+ it("createWebhook POSTs idModel + callbackURL", async () => {
+ const f = mockFetchOnce({ id: "wh1" });
+ const res = await api.createWebhook("b1", "https://api.plot.test/hook/abc");
+ expect(res.id).toBe("wh1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/webhooks");
+ expect(init.method).toBe("POST");
+ const body = String(init.body);
+ expect(body).toContain("idModel=b1");
+ expect(body).toContain("callbackURL=");
+ });
+});
+
+describe("cardCreatedAt", () => {
+ it("decodes the timestamp from the first 8 hex chars of the id", () => {
+ // 0x5f000000 = 1593817600 → 2020-07-03T...; assert it parses to that epoch.
+ const d = cardCreatedAt("5f000000aaaaaaaaaaaaaaaa");
+ expect(d.getTime()).toBe(0x5f000000 * 1000);
+ });
+});
+
+describe("verifyTrelloWebhook", () => {
+ it("accepts a correct HMAC-SHA1 signature and rejects a wrong one", async () => {
+ const secret = "shh";
+ const body = '{"action":{"type":"updateCard"}}';
+ const callbackURL = "https://api.plot.test/hook/abc";
+ // Compute the expected signature with the same primitive the impl uses.
+ const key = await crypto.subtle.importKey(
+ "raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-1" }, false, ["sign"],
+ );
+ const sigBuf = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(body + callbackURL));
+ const good = btoa(String.fromCharCode(...new Uint8Array(sigBuf)));
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, good)).toBe(true);
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, "wrong")).toBe(false);
+ });
+});

connectors/trello/src/trello-api.ts

@@ -0,0 +1,168 @@
+// Cloudflare Workers provide Buffer/crypto globally; we use Web Crypto + btoa.
+export type TrelloBoard = { id: string; name: string };
+export type TrelloList = { id: string; name: string; pos: number };
+export type TrelloMember = {
+ id: string;
+ fullName: string | null;
+ username: string | null;
+ avatarUrl: string | null;
+};
+export type TrelloAttachment = {
+ id: string;
+ name: string;
+ url: string;
+ bytes: number | null;
+ mimeType: string | null;
+};
+export type TrelloCommentAction = {
+ id: string;
+ type: "commentCard";
+ date: string;
+ memberCreator: TrelloMember | null;
+ data: { text: string };
+};
+export type TrelloCard = {
+ id: string;
+ name: string;
+ desc: string;
+ idList: string;
+ idBoard: string;
+ closed: boolean;
+ url: string;
+ idMembers: string[];
+ members?: TrelloMember[];
+ attachments?: TrelloAttachment[];
+ actions?: TrelloCommentAction[];
+ dateLastActivity: string;
+};
+
+const BASE = "https://api.trello.com/1";
+const CARD_FIELDS = "id,name,desc,idList,idBoard,closed,url,idMembers,dateLastActivity";
+const MEMBER_FIELDS = "id,fullName,username,avatarUrl";
+
+export class TrelloApi {
+ constructor(
+ private readonly key: string,
+ private readonly token: string,
+ ) {}
+
+ private auth(extra = ""): string {
+ const sep = extra ? "&" : "";
+ return `key=${encodeURIComponent(this.key)}&token=${encodeURIComponent(this.token)}${sep}${extra}`;
+ }
+
+ private async req<T>(method: string, path: string, query = "", body?: string): Promise<T> {
+ const url = `${BASE}${path}?${this.auth(body !== undefined ? "" : query)}`;
+ const headers: Record<string, string> = { Accept: "application/json" };
+ if (body !== undefined) headers["Content-Type"] = "application/x-www-form-urlencoded";
+ const res = await fetch(url, { method, headers, ...(body !== undefined ? { body } : {}) });
+ if (!res.ok) {
+ throw new Error(`Trello ${method} ${path} failed: ${res.status} ${await res.text()}`);
+ }
+ return (await res.json()) as T;
+ }
+
+ getBoards(): Promise<TrelloBoard[]> {
+ return this.req("GET", "/members/me/boards", "filter=open&fields=id,name");
+ }
+
+ getLists(boardId: string): Promise<TrelloList[]> {
+ return this.req("GET", `/boards/${boardId}/lists`, "filter=open&fields=id,name,pos");
+ }
+
+ getCards(boardId: string, opts: { limit: number; before?: string }): Promise<TrelloCard[]> {
+ const q = [
+ "filter=open",
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ `limit=${opts.limit}`,
+ ...(opts.before ? [`before=${opts.before}`] : []),
+ ].join("&");
+ return this.req("GET", `/boards/${boardId}/cards`, q);
+ }
+
+ getCard(cardId: string): Promise<TrelloCard> {
+ const q = [
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ ].join("&");
+ return this.req("GET", `/cards/${cardId}`, q);
+ }
+
+ createCard(p: { idList: string; name: string; desc?: string }): Promise<TrelloCard> {
+ const q = [
+ `idList=${encodeURIComponent(p.idList)}`,
+ `name=${encodeURIComponent(p.name)}`,
+ ...(p.desc ? [`desc=${encodeURIComponent(p.desc)}`] : []),
+ ].join("&");
+ return this.req("POST", "/cards", q);
+ }
+
+ updateCard(
+ cardId: string,
+ fields: { idList?: string; closed?: boolean; name?: string; desc?: string },
+ ): Promise<TrelloCard> {
+ const parts: string[] = [];
+ if (fields.idList !== undefined) parts.push(`idList=${encodeURIComponent(fields.idList)}`);
+ if (fields.closed !== undefined) parts.push(`closed=${fields.closed}`);
+ if (fields.name !== undefined) parts.push(`name=${encodeURIComponent(fields.name)}`);
+ if (fields.desc !== undefined) parts.push(`desc=${encodeURIComponent(fields.desc)}`);
+ return this.req("PUT", `/cards/${cardId}`, parts.join("&"));
+ }
+
+ addComment(cardId: string, text: string): Promise<TrelloCommentAction> {
+ return this.req("POST", `/cards/${cardId}/actions/comments`, `text=${encodeURIComponent(text)}`);
+ }
+
+ updateComment(actionId: string, text: string): Promise<{ id: string; data: { text: string } }> {
+ return this.req("PUT", `/actions/${actionId}`, `text=${encodeURIComponent(text)}`);
+ }
+
+ createWebhook(boardId: string, callbackURL: string): Promise<{ id: string }> {
+ const body = `idModel=${encodeURIComponent(boardId)}&callbackURL=${encodeURIComponent(callbackURL)}&description=${encodeURIComponent("Plot Trello sync")}`;
+ return this.req("POST", "/webhooks", "", body);
+ }
+
+ deleteWebhook(webhookId: string): Promise<unknown> {
+ return this.req("DELETE", `/webhooks/${webhookId}`);
+ }
+}
+
+/** Trello object ids encode their creation time in the first 8 hex chars (unix seconds). */
+export function cardCreatedAt(cardId: string): Date {
+ const seconds = parseInt(cardId.substring(0, 8), 16);
+ return new Date(seconds * 1000);
+}
+
+/** Verify a Trello webhook: base64(HMAC-SHA1(appSecret, rawBody + callbackURL)) === header. */
+export async function verifyTrelloWebhook(
+ secret: string,
+ rawBody: string,
+ callbackURL: string,
+ signature: string,
+): Promise<boolean> {
+ try {
+ const key = await crypto.subtle.importKey(
+ "raw",
+ new TextEncoder().encode(secret),
+ { name: "HMAC", hash: "SHA-1" },
+ false,
+ ["sign"],
+ );
+ const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(rawBody + callbackURL));
+ const expected = btoa(String.fromCharCode(...new Uint8Array(sig)));
+ return expected === signature;
+ } catch {
+ return false;
+ }
+}

connectors/trello/src/trello-channels.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { buildCardLinkType, DONE_LIST_RE } from "./trello-channels";
+import type { TrelloList } from "./trello-api";
+
+const lists: TrelloList[] = [
+ { id: "l1", name: "To Do", pos: 1 },
+ { id: "l2", name: "Doing", pos: 2 },
+ { id: "l3", name: "Done", pos: 3 },
+];
+
+describe("buildCardLinkType", () => {
+ it("maps lists to statuses: first=todo, middle=inProgress, done-name=done+done:true", () => {
+ const lt = buildCardLinkType(lists);
+ expect(lt.type).toBe("card");
+ expect(lt.statuses).toEqual([
+ { status: "l1", label: "To Do", icon: "todo" },
+ { status: "l2", label: "Doing", icon: "inProgress" },
+ { status: "l3", label: "Done", icon: "done", done: true },
+ ]);
+ // compose defaults to the first non-done list
+ expect(lt.compose).toEqual({ status: "l1" });
+ });
+
+ it("DONE_LIST_RE matches common done-column names", () => {
+ expect(DONE_LIST_RE.test("Done")).toBe(true);
+ expect(DONE_LIST_RE.test("Shipped")).toBe(true);
+ expect(DONE_LIST_RE.test("Complete")).toBe(true);
+ expect(DONE_LIST_RE.test("Backlog")).toBe(false);
+ });
+
+ it("falls back to the first list for compose when no non-done list exists", () => {
+ const lt = buildCardLinkType([{ id: "d", name: "Done", pos: 1 }]);
+ expect(lt.compose).toEqual({ status: "d" });
+ });
+});

.changeset/structured-item-fields.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: structured-item note fields (`sectionKey`, `sectionLabel`, `sectionPosition`, `itemPosition`), `Note.tagActors` (dispatch-time hydrated assignees), and `Actor.source.accountId` (external account id resolved at dispatch).

.changeset/trello-auth-provider.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `AuthProvider.Trello` for the Trello connector's token-authorize flow.

connectors/trello/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plot Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

connectors/trello/README.md

@@ -0,0 +1,3 @@
+# @plotday/connector-trello
+
+This connector syncs your Trello boards and cards into Plot, giving you a unified view of all your work across tools. It supports bidirectional sync: cards appear in Plot with their current status (list), assignees, and comments, and changes you make in Plot — checking off a card, adding a comment — are written back to Trello automatically. When a card moves between lists or is archived in Trello, Plot reflects the change on the next sync cycle.

connectors/trello/package.json

@@ -0,0 +1,43 @@
+{
+ "name": "@plotday/connector-trello",
+ "plotTwistId": "06829c6d-d28f-42bd-8ca8-fede11dd0582",
+ "displayName": "Trello",
+ "description": "Track your Trello cards and check them off as work moves forward.",
+ "logoUrl": "https://api.iconify.design/logos/trello.svg",
+ "publisher": "Plot",
+ "publisherUrl": "https://plot.day",
+ "author": "Plot <team@plot.day> (https://plot.day)",
+ "license": "MIT",
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "private": true,
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "deploy": "plot deploy",
+ "lint": "plot lint",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "@types/node": "^25.0.3",
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ },
+ "repository": { "type": "git", "url": "https://github.com/plotday/plot.git", "directory": "connectors/trello" },
+ "homepage": "https://plot.day",
+ "bugs": { "url": "https://github.com/plotday/plot/issues" },
+ "keywords": ["plot", "connector", "trello", "project-management"]
+}

connectors/trello/src/index.ts

@@ -0,0 +1 @@
+export { default, Trello } from "./trello";

connectors/trello/src/trello-api.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TrelloApi, verifyTrelloWebhook, cardCreatedAt } from "./trello-api";
+
+afterEach(() => vi.restoreAllMocks());
+
+function mockFetchOnce(json: unknown, ok = true, status = 200) {
+ return vi.spyOn(globalThis, "fetch").mockResolvedValue(
+ new Response(JSON.stringify(json), { status: ok ? status : 400 }),
+ );
+}
+
+describe("TrelloApi request shaping", () => {
+ const api = new TrelloApi("KEY", "TOK");
+
+ it("getBoards calls /members/me/boards with key+token", async () => {
+ const f = mockFetchOnce([{ id: "b1", name: "Board" }]);
+ const boards = await api.getBoards();
+ expect(boards).toEqual([{ id: "b1", name: "Board" }]);
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("https://api.trello.com/1/members/me/boards");
+ expect(url).toContain("key=KEY");
+ expect(url).toContain("token=TOK");
+ expect(url).toContain("filter=open");
+ });
+
+ it("getCards passes limit + before for pagination", async () => {
+ const f = mockFetchOnce([]);
+ await api.getCards("b1", { limit: 50, before: "card9" });
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("/boards/b1/cards");
+ expect(url).toContain("limit=50");
+ expect(url).toContain("before=card9");
+ expect(url).toContain("actions=commentCard");
+ expect(url).toContain("attachments=true");
+ expect(url).toContain("members=true");
+ });
+
+ it("addComment POSTs to /cards/{id}/actions/comments and returns the action", async () => {
+ const f = mockFetchOnce({ id: "act1", type: "commentCard", date: "2026-01-01T00:00:00Z", data: { text: "hi" } });
+ const action = await api.addComment("c1", "hi");
+ expect(action.id).toBe("act1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/cards/c1/actions/comments");
+ expect(url).toContain("text=hi");
+ expect(init.method).toBe("POST");
+ });
+
+ it("createWebhook POSTs idModel + callbackURL", async () => {
+ const f = mockFetchOnce({ id: "wh1" });
+ const res = await api.createWebhook("b1", "https://api.plot.test/hook/abc");
+ expect(res.id).toBe("wh1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/webhooks");
+ expect(init.method).toBe("POST");
+ const body = String(init.body);
+ expect(body).toContain("idModel=b1");
+ expect(body).toContain("callbackURL=");
+ });
+});
+
+describe("cardCreatedAt", () => {
+ it("decodes the timestamp from the first 8 hex chars of the id", () => {
+ // 0x5f000000 = 1593817600 → 2020-07-03T...; assert it parses to that epoch.
+ const d = cardCreatedAt("5f000000aaaaaaaaaaaaaaaa");
+ expect(d.getTime()).toBe(0x5f000000 * 1000);
+ });
+});
+
+describe("verifyTrelloWebhook", () => {
+ it("accepts a correct HMAC-SHA1 signature and rejects a wrong one", async () => {
+ const secret = "shh";
+ const body = '{"action":{"type":"updateCard"}}';
+ const callbackURL = "https://api.plot.test/hook/abc";
+ // Compute the expected signature with the same primitive the impl uses.
+ const key = await crypto.subtle.importKey(
+ "raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-1" }, false, ["sign"],
+ );
+ const sigBuf = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(body + callbackURL));
+ const good = btoa(String.fromCharCode(...new Uint8Array(sigBuf)));
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, good)).toBe(true);
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, "wrong")).toBe(false);
+ });
+});

connectors/trello/src/trello-api.ts

@@ -0,0 +1,168 @@
+// Cloudflare Workers provide Buffer/crypto globally; we use Web Crypto + btoa.
+export type TrelloBoard = { id: string; name: string };
+export type TrelloList = { id: string; name: string; pos: number };
+export type TrelloMember = {
+ id: string;
+ fullName: string | null;
+ username: string | null;
+ avatarUrl: string | null;
+};
+export type TrelloAttachment = {
+ id: string;
+ name: string;
+ url: string;
+ bytes: number | null;
+ mimeType: string | null;
+};
+export type TrelloCommentAction = {
+ id: string;
+ type: "commentCard";
+ date: string;
+ memberCreator: TrelloMember | null;
+ data: { text: string };
+};
+export type TrelloCard = {
+ id: string;
+ name: string;
+ desc: string;
+ idList: string;
+ idBoard: string;
+ closed: boolean;
+ url: string;
+ idMembers: string[];
+ members?: TrelloMember[];
+ attachments?: TrelloAttachment[];
+ actions?: TrelloCommentAction[];
+ dateLastActivity: string;
+};
+
+const BASE = "https://api.trello.com/1";
+const CARD_FIELDS = "id,name,desc,idList,idBoard,closed,url,idMembers,dateLastActivity";
+const MEMBER_FIELDS = "id,fullName,username,avatarUrl";
+
+export class TrelloApi {
+ constructor(
+ private readonly key: string,
+ private readonly token: string,
+ ) {}
+
+ private auth(extra = ""): string {
+ const sep = extra ? "&" : "";
+ return `key=${encodeURIComponent(this.key)}&token=${encodeURIComponent(this.token)}${sep}${extra}`;
+ }
+
+ private async req<T>(method: string, path: string, query = "", body?: string): Promise<T> {
+ const url = `${BASE}${path}?${this.auth(body !== undefined ? "" : query)}`;
+ const headers: Record<string, string> = { Accept: "application/json" };
+ if (body !== undefined) headers["Content-Type"] = "application/x-www-form-urlencoded";
+ const res = await fetch(url, { method, headers, ...(body !== undefined ? { body } : {}) });
+ if (!res.ok) {
+ throw new Error(`Trello ${method} ${path} failed: ${res.status} ${await res.text()}`);
+ }
+ return (await res.json()) as T;
+ }
+
+ getBoards(): Promise<TrelloBoard[]> {
+ return this.req("GET", "/members/me/boards", "filter=open&fields=id,name");
+ }
+
+ getLists(boardId: string): Promise<TrelloList[]> {
+ return this.req("GET", `/boards/${boardId}/lists`, "filter=open&fields=id,name,pos");
+ }
+
+ getCards(boardId: string, opts: { limit: number; before?: string }): Promise<TrelloCard[]> {
+ const q = [
+ "filter=open",
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ `limit=${opts.limit}`,
+ ...(opts.before ? [`before=${opts.before}`] : []),
+ ].join("&");
+ return this.req("GET", `/boards/${boardId}/cards`, q);
+ }
+
+ getCard(cardId: string): Promise<TrelloCard> {
+ const q = [
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ ].join("&");
+ return this.req("GET", `/cards/${cardId}`, q);
+ }
+
+ createCard(p: { idList: string; name: string; desc?: string }): Promise<TrelloCard> {
+ const q = [
+ `idList=${encodeURIComponent(p.idList)}`,
+ `name=${encodeURIComponent(p.name)}`,
+ ...(p.desc ? [`desc=${encodeURIComponent(p.desc)}`] : []),
+ ].join("&");
+ return this.req("POST", "/cards", q);
+ }
+
+ updateCard(
+ cardId: string,
+ fields: { idList?: string; closed?: boolean; name?: string; desc?: string },
+ ): Promise<TrelloCard> {
+ const parts: string[] = [];
+ if (fields.idList !== undefined) parts.push(`idList=${encodeURIComponent(fields.idList)}`);
+ if (fields.closed !== undefined) parts.push(`closed=${fields.closed}`);
+ if (fields.name !== undefined) parts.push(`name=${encodeURIComponent(fields.name)}`);
+ if (fields.desc !== undefined) parts.push(`desc=${encodeURIComponent(fields.desc)}`);
+ return this.req("PUT", `/cards/${cardId}`, parts.join("&"));
+ }
+
+ addComment(cardId: string, text: string): Promise<TrelloCommentAction> {
+ return this.req("POST", `/cards/${cardId}/actions/comments`, `text=${encodeURIComponent(text)}`);
+ }
+
+ updateComment(actionId: string, text: string): Promise<{ id: string; data: { text: string } }> {
+ return this.req("PUT", `/actions/${actionId}`, `text=${encodeURIComponent(text)}`);
+ }
+
+ createWebhook(boardId: string, callbackURL: string): Promise<{ id: string }> {
+ const body = `idModel=${encodeURIComponent(boardId)}&callbackURL=${encodeURIComponent(callbackURL)}&description=${encodeURIComponent("Plot Trello sync")}`;
+ return this.req("POST", "/webhooks", "", body);
+ }
+
+ deleteWebhook(webhookId: string): Promise<unknown> {
+ return this.req("DELETE", `/webhooks/${webhookId}`);
+ }
+}
+
+/** Trello object ids encode their creation time in the first 8 hex chars (unix seconds). */
+export function cardCreatedAt(cardId: string): Date {
+ const seconds = parseInt(cardId.substring(0, 8), 16);
+ return new Date(seconds * 1000);
+}
+
+/** Verify a Trello webhook: base64(HMAC-SHA1(appSecret, rawBody + callbackURL)) === header. */
+export async function verifyTrelloWebhook(
+ secret: string,
+ rawBody: string,
+ callbackURL: string,
+ signature: string,
+): Promise<boolean> {
+ try {
+ const key = await crypto.subtle.importKey(
+ "raw",
+ new TextEncoder().encode(secret),
+ { name: "HMAC", hash: "SHA-1" },
+ false,
+ ["sign"],
+ );
+ const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(rawBody + callbackURL));
+ const expected = btoa(String.fromCharCode(...new Uint8Array(sig)));
+ return expected === signature;
+ } catch {
+ return false;
+ }
+}

connectors/trello/src/trello-channels.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { buildCardLinkType, DONE_LIST_RE } from "./trello-channels";
+import type { TrelloList } from "./trello-api";
+
+const lists: TrelloList[] = [
+ { id: "l1", name: "To Do", pos: 1 },
+ { id: "l2", name: "Doing", pos: 2 },
+ { id: "l3", name: "Done", pos: 3 },
+];
+
+describe("buildCardLinkType", () => {
+ it("maps lists to statuses: first=todo, middle=inProgress, done-name=done+done:true", () => {
+ const lt = buildCardLinkType(lists);
+ expect(lt.type).toBe("card");
+ expect(lt.statuses).toEqual([
+ { status: "l1", label: "To Do", icon: "todo" },
+ { status: "l2", label: "Doing", icon: "inProgress" },
+ { status: "l3", label: "Done", icon: "done", done: true },
+ ]);
+ // compose defaults to the first non-done list
+ expect(lt.compose).toEqual({ status: "l1" });
+ });
+
+ it("DONE_LIST_RE matches common done-column names", () => {
+ expect(DONE_LIST_RE.test("Done")).toBe(true);
+ expect(DONE_LIST_RE.test("Shipped")).toBe(true);
+ expect(DONE_LIST_RE.test("Complete")).toBe(true);
+ expect(DONE_LIST_RE.test("Backlog")).toBe(false);
+ });
+
+ it("falls back to the first list for compose when no non-done list exists", () => {
+ const lt = buildCardLinkType([{ id: "d", name: "Done", pos: 1 }]);
+ expect(lt.compose).toEqual({ status: "d" });
+ });
+});

.changeset/structured-item-fields.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: structured-item note fields (`sectionKey`, `sectionLabel`, `sectionPosition`, `itemPosition`), `Note.tagActors` (dispatch-time hydrated assignees), and `Actor.source.accountId` (external account id resolved at dispatch).

.changeset/trello-auth-provider.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `AuthProvider.Trello` for the Trello connector's token-authorize flow.

connectors/trello/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plot Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

connectors/trello/README.md

@@ -0,0 +1,3 @@
+# @plotday/connector-trello
+
+This connector syncs your Trello boards and cards into Plot, giving you a unified view of all your work across tools. It supports bidirectional sync: cards appear in Plot with their current status (list), assignees, and comments, and changes you make in Plot — checking off a card, adding a comment — are written back to Trello automatically. When a card moves between lists or is archived in Trello, Plot reflects the change on the next sync cycle.

connectors/trello/package.json

@@ -0,0 +1,43 @@
+{
+ "name": "@plotday/connector-trello",
+ "plotTwistId": "06829c6d-d28f-42bd-8ca8-fede11dd0582",
+ "displayName": "Trello",
+ "description": "Track your Trello cards and check them off as work moves forward.",
+ "logoUrl": "https://api.iconify.design/logos/trello.svg",
+ "publisher": "Plot",
+ "publisherUrl": "https://plot.day",
+ "author": "Plot <team@plot.day> (https://plot.day)",
+ "license": "MIT",
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "private": true,
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "deploy": "plot deploy",
+ "lint": "plot lint",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "@types/node": "^25.0.3",
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ },
+ "repository": { "type": "git", "url": "https://github.com/plotday/plot.git", "directory": "connectors/trello" },
+ "homepage": "https://plot.day",
+ "bugs": { "url": "https://github.com/plotday/plot/issues" },
+ "keywords": ["plot", "connector", "trello", "project-management"]
+}

connectors/trello/src/index.ts

@@ -0,0 +1 @@
+export { default, Trello } from "./trello";

connectors/trello/src/trello-api.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TrelloApi, verifyTrelloWebhook, cardCreatedAt } from "./trello-api";
+
+afterEach(() => vi.restoreAllMocks());
+
+function mockFetchOnce(json: unknown, ok = true, status = 200) {
+ return vi.spyOn(globalThis, "fetch").mockResolvedValue(
+ new Response(JSON.stringify(json), { status: ok ? status : 400 }),
+ );
+}
+
+describe("TrelloApi request shaping", () => {
+ const api = new TrelloApi("KEY", "TOK");
+
+ it("getBoards calls /members/me/boards with key+token", async () => {
+ const f = mockFetchOnce([{ id: "b1", name: "Board" }]);
+ const boards = await api.getBoards();
+ expect(boards).toEqual([{ id: "b1", name: "Board" }]);
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("https://api.trello.com/1/members/me/boards");
+ expect(url).toContain("key=KEY");
+ expect(url).toContain("token=TOK");
+ expect(url).toContain("filter=open");
+ });
+
+ it("getCards passes limit + before for pagination", async () => {
+ const f = mockFetchOnce([]);
+ await api.getCards("b1", { limit: 50, before: "card9" });
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("/boards/b1/cards");
+ expect(url).toContain("limit=50");
+ expect(url).toContain("before=card9");
+ expect(url).toContain("actions=commentCard");
+ expect(url).toContain("attachments=true");
+ expect(url).toContain("members=true");
+ });
+
+ it("addComment POSTs to /cards/{id}/actions/comments and returns the action", async () => {
+ const f = mockFetchOnce({ id: "act1", type: "commentCard", date: "2026-01-01T00:00:00Z", data: { text: "hi" } });
+ const action = await api.addComment("c1", "hi");
+ expect(action.id).toBe("act1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/cards/c1/actions/comments");
+ expect(url).toContain("text=hi");
+ expect(init.method).toBe("POST");
+ });
+
+ it("createWebhook POSTs idModel + callbackURL", async () => {
+ const f = mockFetchOnce({ id: "wh1" });
+ const res = await api.createWebhook("b1", "https://api.plot.test/hook/abc");
+ expect(res.id).toBe("wh1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/webhooks");
+ expect(init.method).toBe("POST");
+ const body = String(init.body);
+ expect(body).toContain("idModel=b1");
+ expect(body).toContain("callbackURL=");
+ });
+});
+
+describe("cardCreatedAt", () => {
+ it("decodes the timestamp from the first 8 hex chars of the id", () => {
+ // 0x5f000000 = 1593817600 → 2020-07-03T...; assert it parses to that epoch.
+ const d = cardCreatedAt("5f000000aaaaaaaaaaaaaaaa");
+ expect(d.getTime()).toBe(0x5f000000 * 1000);
+ });
+});
+
+describe("verifyTrelloWebhook", () => {
+ it("accepts a correct HMAC-SHA1 signature and rejects a wrong one", async () => {
+ const secret = "shh";
+ const body = '{"action":{"type":"updateCard"}}';
+ const callbackURL = "https://api.plot.test/hook/abc";
+ // Compute the expected signature with the same primitive the impl uses.
+ const key = await crypto.subtle.importKey(
+ "raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-1" }, false, ["sign"],
+ );
+ const sigBuf = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(body + callbackURL));
+ const good = btoa(String.fromCharCode(...new Uint8Array(sigBuf)));
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, good)).toBe(true);
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, "wrong")).toBe(false);
+ });
+});

connectors/trello/src/trello-api.ts

@@ -0,0 +1,168 @@
+// Cloudflare Workers provide Buffer/crypto globally; we use Web Crypto + btoa.
+export type TrelloBoard = { id: string; name: string };
+export type TrelloList = { id: string; name: string; pos: number };
+export type TrelloMember = {
+ id: string;
+ fullName: string | null;
+ username: string | null;
+ avatarUrl: string | null;
+};
+export type TrelloAttachment = {
+ id: string;
+ name: string;
+ url: string;
+ bytes: number | null;
+ mimeType: string | null;
+};
+export type TrelloCommentAction = {
+ id: string;
+ type: "commentCard";
+ date: string;
+ memberCreator: TrelloMember | null;
+ data: { text: string };
+};
+export type TrelloCard = {
+ id: string;
+ name: string;
+ desc: string;
+ idList: string;
+ idBoard: string;
+ closed: boolean;
+ url: string;
+ idMembers: string[];
+ members?: TrelloMember[];
+ attachments?: TrelloAttachment[];
+ actions?: TrelloCommentAction[];
+ dateLastActivity: string;
+};
+
+const BASE = "https://api.trello.com/1";
+const CARD_FIELDS = "id,name,desc,idList,idBoard,closed,url,idMembers,dateLastActivity";
+const MEMBER_FIELDS = "id,fullName,username,avatarUrl";
+
+export class TrelloApi {
+ constructor(
+ private readonly key: string,
+ private readonly token: string,
+ ) {}
+
+ private auth(extra = ""): string {
+ const sep = extra ? "&" : "";
+ return `key=${encodeURIComponent(this.key)}&token=${encodeURIComponent(this.token)}${sep}${extra}`;
+ }
+
+ private async req<T>(method: string, path: string, query = "", body?: string): Promise<T> {
+ const url = `${BASE}${path}?${this.auth(body !== undefined ? "" : query)}`;
+ const headers: Record<string, string> = { Accept: "application/json" };
+ if (body !== undefined) headers["Content-Type"] = "application/x-www-form-urlencoded";
+ const res = await fetch(url, { method, headers, ...(body !== undefined ? { body } : {}) });
+ if (!res.ok) {
+ throw new Error(`Trello ${method} ${path} failed: ${res.status} ${await res.text()}`);
+ }
+ return (await res.json()) as T;
+ }
+
+ getBoards(): Promise<TrelloBoard[]> {
+ return this.req("GET", "/members/me/boards", "filter=open&fields=id,name");
+ }
+
+ getLists(boardId: string): Promise<TrelloList[]> {
+ return this.req("GET", `/boards/${boardId}/lists`, "filter=open&fields=id,name,pos");
+ }
+
+ getCards(boardId: string, opts: { limit: number; before?: string }): Promise<TrelloCard[]> {
+ const q = [
+ "filter=open",
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ `limit=${opts.limit}`,
+ ...(opts.before ? [`before=${opts.before}`] : []),
+ ].join("&");
+ return this.req("GET", `/boards/${boardId}/cards`, q);
+ }
+
+ getCard(cardId: string): Promise<TrelloCard> {
+ const q = [
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ ].join("&");
+ return this.req("GET", `/cards/${cardId}`, q);
+ }
+
+ createCard(p: { idList: string; name: string; desc?: string }): Promise<TrelloCard> {
+ const q = [
+ `idList=${encodeURIComponent(p.idList)}`,
+ `name=${encodeURIComponent(p.name)}`,
+ ...(p.desc ? [`desc=${encodeURIComponent(p.desc)}`] : []),
+ ].join("&");
+ return this.req("POST", "/cards", q);
+ }
+
+ updateCard(
+ cardId: string,
+ fields: { idList?: string; closed?: boolean; name?: string; desc?: string },
+ ): Promise<TrelloCard> {
+ const parts: string[] = [];
+ if (fields.idList !== undefined) parts.push(`idList=${encodeURIComponent(fields.idList)}`);
+ if (fields.closed !== undefined) parts.push(`closed=${fields.closed}`);
+ if (fields.name !== undefined) parts.push(`name=${encodeURIComponent(fields.name)}`);
+ if (fields.desc !== undefined) parts.push(`desc=${encodeURIComponent(fields.desc)}`);
+ return this.req("PUT", `/cards/${cardId}`, parts.join("&"));
+ }
+
+ addComment(cardId: string, text: string): Promise<TrelloCommentAction> {
+ return this.req("POST", `/cards/${cardId}/actions/comments`, `text=${encodeURIComponent(text)}`);
+ }
+
+ updateComment(actionId: string, text: string): Promise<{ id: string; data: { text: string } }> {
+ return this.req("PUT", `/actions/${actionId}`, `text=${encodeURIComponent(text)}`);
+ }
+
+ createWebhook(boardId: string, callbackURL: string): Promise<{ id: string }> {
+ const body = `idModel=${encodeURIComponent(boardId)}&callbackURL=${encodeURIComponent(callbackURL)}&description=${encodeURIComponent("Plot Trello sync")}`;
+ return this.req("POST", "/webhooks", "", body);
+ }
+
+ deleteWebhook(webhookId: string): Promise<unknown> {
+ return this.req("DELETE", `/webhooks/${webhookId}`);
+ }
+}
+
+/** Trello object ids encode their creation time in the first 8 hex chars (unix seconds). */
+export function cardCreatedAt(cardId: string): Date {
+ const seconds = parseInt(cardId.substring(0, 8), 16);
+ return new Date(seconds * 1000);
+}
+
+/** Verify a Trello webhook: base64(HMAC-SHA1(appSecret, rawBody + callbackURL)) === header. */
+export async function verifyTrelloWebhook(
+ secret: string,
+ rawBody: string,
+ callbackURL: string,
+ signature: string,
+): Promise<boolean> {
+ try {
+ const key = await crypto.subtle.importKey(
+ "raw",
+ new TextEncoder().encode(secret),
+ { name: "HMAC", hash: "SHA-1" },
+ false,
+ ["sign"],
+ );
+ const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(rawBody + callbackURL));
+ const expected = btoa(String.fromCharCode(...new Uint8Array(sig)));
+ return expected === signature;
+ } catch {
+ return false;
+ }
+}

connectors/trello/src/trello-channels.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { buildCardLinkType, DONE_LIST_RE } from "./trello-channels";
+import type { TrelloList } from "./trello-api";
+
+const lists: TrelloList[] = [
+ { id: "l1", name: "To Do", pos: 1 },
+ { id: "l2", name: "Doing", pos: 2 },
+ { id: "l3", name: "Done", pos: 3 },
+];
+
+describe("buildCardLinkType", () => {
+ it("maps lists to statuses: first=todo, middle=inProgress, done-name=done+done:true", () => {
+ const lt = buildCardLinkType(lists);
+ expect(lt.type).toBe("card");
+ expect(lt.statuses).toEqual([
+ { status: "l1", label: "To Do", icon: "todo" },
+ { status: "l2", label: "Doing", icon: "inProgress" },
+ { status: "l3", label: "Done", icon: "done", done: true },
+ ]);
+ // compose defaults to the first non-done list
+ expect(lt.compose).toEqual({ status: "l1" });
+ });
+
+ it("DONE_LIST_RE matches common done-column names", () => {
+ expect(DONE_LIST_RE.test("Done")).toBe(true);
+ expect(DONE_LIST_RE.test("Shipped")).toBe(true);
+ expect(DONE_LIST_RE.test("Complete")).toBe(true);
+ expect(DONE_LIST_RE.test("Backlog")).toBe(false);
+ });
+
+ it("falls back to the first list for compose when no non-done list exists", () => {
+ const lt = buildCardLinkType([{ id: "d", name: "Done", pos: 1 }]);
+ expect(lt.compose).toEqual({ status: "d" });
+ });
+});

.changeset/structured-item-fields.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: structured-item note fields (`sectionKey`, `sectionLabel`, `sectionPosition`, `itemPosition`), `Note.tagActors` (dispatch-time hydrated assignees), and `Actor.source.accountId` (external account id resolved at dispatch).

.changeset/trello-auth-provider.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `AuthProvider.Trello` for the Trello connector's token-authorize flow.

connectors/trello/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plot Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

connectors/trello/README.md

@@ -0,0 +1,3 @@
+# @plotday/connector-trello
+
+This connector syncs your Trello boards and cards into Plot, giving you a unified view of all your work across tools. It supports bidirectional sync: cards appear in Plot with their current status (list), assignees, and comments, and changes you make in Plot — checking off a card, adding a comment — are written back to Trello automatically. When a card moves between lists or is archived in Trello, Plot reflects the change on the next sync cycle.

connectors/trello/package.json

@@ -0,0 +1,43 @@
+{
+ "name": "@plotday/connector-trello",
+ "plotTwistId": "06829c6d-d28f-42bd-8ca8-fede11dd0582",
+ "displayName": "Trello",
+ "description": "Track your Trello cards and check them off as work moves forward.",
+ "logoUrl": "https://api.iconify.design/logos/trello.svg",
+ "publisher": "Plot",
+ "publisherUrl": "https://plot.day",
+ "author": "Plot <team@plot.day> (https://plot.day)",
+ "license": "MIT",
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "private": true,
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "deploy": "plot deploy",
+ "lint": "plot lint",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "@types/node": "^25.0.3",
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ },
+ "repository": { "type": "git", "url": "https://github.com/plotday/plot.git", "directory": "connectors/trello" },
+ "homepage": "https://plot.day",
+ "bugs": { "url": "https://github.com/plotday/plot/issues" },
+ "keywords": ["plot", "connector", "trello", "project-management"]
+}

connectors/trello/src/index.ts

@@ -0,0 +1 @@
+export { default, Trello } from "./trello";

connectors/trello/src/trello-api.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TrelloApi, verifyTrelloWebhook, cardCreatedAt } from "./trello-api";
+
+afterEach(() => vi.restoreAllMocks());
+
+function mockFetchOnce(json: unknown, ok = true, status = 200) {
+ return vi.spyOn(globalThis, "fetch").mockResolvedValue(
+ new Response(JSON.stringify(json), { status: ok ? status : 400 }),
+ );
+}
+
+describe("TrelloApi request shaping", () => {
+ const api = new TrelloApi("KEY", "TOK");
+
+ it("getBoards calls /members/me/boards with key+token", async () => {
+ const f = mockFetchOnce([{ id: "b1", name: "Board" }]);
+ const boards = await api.getBoards();
+ expect(boards).toEqual([{ id: "b1", name: "Board" }]);
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("https://api.trello.com/1/members/me/boards");
+ expect(url).toContain("key=KEY");
+ expect(url).toContain("token=TOK");
+ expect(url).toContain("filter=open");
+ });
+
+ it("getCards passes limit + before for pagination", async () => {
+ const f = mockFetchOnce([]);
+ await api.getCards("b1", { limit: 50, before: "card9" });
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("/boards/b1/cards");
+ expect(url).toContain("limit=50");
+ expect(url).toContain("before=card9");
+ expect(url).toContain("actions=commentCard");
+ expect(url).toContain("attachments=true");
+ expect(url).toContain("members=true");
+ });
+
+ it("addComment POSTs to /cards/{id}/actions/comments and returns the action", async () => {
+ const f = mockFetchOnce({ id: "act1", type: "commentCard", date: "2026-01-01T00:00:00Z", data: { text: "hi" } });
+ const action = await api.addComment("c1", "hi");
+ expect(action.id).toBe("act1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/cards/c1/actions/comments");
+ expect(url).toContain("text=hi");
+ expect(init.method).toBe("POST");
+ });
+
+ it("createWebhook POSTs idModel + callbackURL", async () => {
+ const f = mockFetchOnce({ id: "wh1" });
+ const res = await api.createWebhook("b1", "https://api.plot.test/hook/abc");
+ expect(res.id).toBe("wh1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/webhooks");
+ expect(init.method).toBe("POST");
+ const body = String(init.body);
+ expect(body).toContain("idModel=b1");
+ expect(body).toContain("callbackURL=");
+ });
+});
+
+describe("cardCreatedAt", () => {
+ it("decodes the timestamp from the first 8 hex chars of the id", () => {
+ // 0x5f000000 = 1593817600 → 2020-07-03T...; assert it parses to that epoch.
+ const d = cardCreatedAt("5f000000aaaaaaaaaaaaaaaa");
+ expect(d.getTime()).toBe(0x5f000000 * 1000);
+ });
+});
+
+describe("verifyTrelloWebhook", () => {
+ it("accepts a correct HMAC-SHA1 signature and rejects a wrong one", async () => {
+ const secret = "shh";
+ const body = '{"action":{"type":"updateCard"}}';
+ const callbackURL = "https://api.plot.test/hook/abc";
+ // Compute the expected signature with the same primitive the impl uses.
+ const key = await crypto.subtle.importKey(
+ "raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-1" }, false, ["sign"],
+ );
+ const sigBuf = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(body + callbackURL));
+ const good = btoa(String.fromCharCode(...new Uint8Array(sigBuf)));
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, good)).toBe(true);
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, "wrong")).toBe(false);
+ });
+});

connectors/trello/src/trello-api.ts

@@ -0,0 +1,168 @@
+// Cloudflare Workers provide Buffer/crypto globally; we use Web Crypto + btoa.
+export type TrelloBoard = { id: string; name: string };
+export type TrelloList = { id: string; name: string; pos: number };
+export type TrelloMember = {
+ id: string;
+ fullName: string | null;
+ username: string | null;
+ avatarUrl: string | null;
+};
+export type TrelloAttachment = {
+ id: string;
+ name: string;
+ url: string;
+ bytes: number | null;
+ mimeType: string | null;
+};
+export type TrelloCommentAction = {
+ id: string;
+ type: "commentCard";
+ date: string;
+ memberCreator: TrelloMember | null;
+ data: { text: string };
+};
+export type TrelloCard = {
+ id: string;
+ name: string;
+ desc: string;
+ idList: string;
+ idBoard: string;
+ closed: boolean;
+ url: string;
+ idMembers: string[];
+ members?: TrelloMember[];
+ attachments?: TrelloAttachment[];
+ actions?: TrelloCommentAction[];
+ dateLastActivity: string;
+};
+
+const BASE = "https://api.trello.com/1";
+const CARD_FIELDS = "id,name,desc,idList,idBoard,closed,url,idMembers,dateLastActivity";
+const MEMBER_FIELDS = "id,fullName,username,avatarUrl";
+
+export class TrelloApi {
+ constructor(
+ private readonly key: string,
+ private readonly token: string,
+ ) {}
+
+ private auth(extra = ""): string {
+ const sep = extra ? "&" : "";
+ return `key=${encodeURIComponent(this.key)}&token=${encodeURIComponent(this.token)}${sep}${extra}`;
+ }
+
+ private async req<T>(method: string, path: string, query = "", body?: string): Promise<T> {
+ const url = `${BASE}${path}?${this.auth(body !== undefined ? "" : query)}`;
+ const headers: Record<string, string> = { Accept: "application/json" };
+ if (body !== undefined) headers["Content-Type"] = "application/x-www-form-urlencoded";
+ const res = await fetch(url, { method, headers, ...(body !== undefined ? { body } : {}) });
+ if (!res.ok) {
+ throw new Error(`Trello ${method} ${path} failed: ${res.status} ${await res.text()}`);
+ }
+ return (await res.json()) as T;
+ }
+
+ getBoards(): Promise<TrelloBoard[]> {
+ return this.req("GET", "/members/me/boards", "filter=open&fields=id,name");
+ }
+
+ getLists(boardId: string): Promise<TrelloList[]> {
+ return this.req("GET", `/boards/${boardId}/lists`, "filter=open&fields=id,name,pos");
+ }
+
+ getCards(boardId: string, opts: { limit: number; before?: string }): Promise<TrelloCard[]> {
+ const q = [
+ "filter=open",
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ `limit=${opts.limit}`,
+ ...(opts.before ? [`before=${opts.before}`] : []),
+ ].join("&");
+ return this.req("GET", `/boards/${boardId}/cards`, q);
+ }
+
+ getCard(cardId: string): Promise<TrelloCard> {
+ const q = [
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ ].join("&");
+ return this.req("GET", `/cards/${cardId}`, q);
+ }
+
+ createCard(p: { idList: string; name: string; desc?: string }): Promise<TrelloCard> {
+ const q = [
+ `idList=${encodeURIComponent(p.idList)}`,
+ `name=${encodeURIComponent(p.name)}`,
+ ...(p.desc ? [`desc=${encodeURIComponent(p.desc)}`] : []),
+ ].join("&");
+ return this.req("POST", "/cards", q);
+ }
+
+ updateCard(
+ cardId: string,
+ fields: { idList?: string; closed?: boolean; name?: string; desc?: string },
+ ): Promise<TrelloCard> {
+ const parts: string[] = [];
+ if (fields.idList !== undefined) parts.push(`idList=${encodeURIComponent(fields.idList)}`);
+ if (fields.closed !== undefined) parts.push(`closed=${fields.closed}`);
+ if (fields.name !== undefined) parts.push(`name=${encodeURIComponent(fields.name)}`);
+ if (fields.desc !== undefined) parts.push(`desc=${encodeURIComponent(fields.desc)}`);
+ return this.req("PUT", `/cards/${cardId}`, parts.join("&"));
+ }
+
+ addComment(cardId: string, text: string): Promise<TrelloCommentAction> {
+ return this.req("POST", `/cards/${cardId}/actions/comments`, `text=${encodeURIComponent(text)}`);
+ }
+
+ updateComment(actionId: string, text: string): Promise<{ id: string; data: { text: string } }> {
+ return this.req("PUT", `/actions/${actionId}`, `text=${encodeURIComponent(text)}`);
+ }
+
+ createWebhook(boardId: string, callbackURL: string): Promise<{ id: string }> {
+ const body = `idModel=${encodeURIComponent(boardId)}&callbackURL=${encodeURIComponent(callbackURL)}&description=${encodeURIComponent("Plot Trello sync")}`;
+ return this.req("POST", "/webhooks", "", body);
+ }
+
+ deleteWebhook(webhookId: string): Promise<unknown> {
+ return this.req("DELETE", `/webhooks/${webhookId}`);
+ }
+}
+
+/** Trello object ids encode their creation time in the first 8 hex chars (unix seconds). */
+export function cardCreatedAt(cardId: string): Date {
+ const seconds = parseInt(cardId.substring(0, 8), 16);
+ return new Date(seconds * 1000);
+}
+
+/** Verify a Trello webhook: base64(HMAC-SHA1(appSecret, rawBody + callbackURL)) === header. */
+export async function verifyTrelloWebhook(
+ secret: string,
+ rawBody: string,
+ callbackURL: string,
+ signature: string,
+): Promise<boolean> {
+ try {
+ const key = await crypto.subtle.importKey(
+ "raw",
+ new TextEncoder().encode(secret),
+ { name: "HMAC", hash: "SHA-1" },
+ false,
+ ["sign"],
+ );
+ const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(rawBody + callbackURL));
+ const expected = btoa(String.fromCharCode(...new Uint8Array(sig)));
+ return expected === signature;
+ } catch {
+ return false;
+ }
+}

connectors/trello/src/trello-channels.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { buildCardLinkType, DONE_LIST_RE } from "./trello-channels";
+import type { TrelloList } from "./trello-api";
+
+const lists: TrelloList[] = [
+ { id: "l1", name: "To Do", pos: 1 },
+ { id: "l2", name: "Doing", pos: 2 },
+ { id: "l3", name: "Done", pos: 3 },
+];
+
+describe("buildCardLinkType", () => {
+ it("maps lists to statuses: first=todo, middle=inProgress, done-name=done+done:true", () => {
+ const lt = buildCardLinkType(lists);
+ expect(lt.type).toBe("card");
+ expect(lt.statuses).toEqual([
+ { status: "l1", label: "To Do", icon: "todo" },
+ { status: "l2", label: "Doing", icon: "inProgress" },
+ { status: "l3", label: "Done", icon: "done", done: true },
+ ]);
+ // compose defaults to the first non-done list
+ expect(lt.compose).toEqual({ status: "l1" });
+ });
+
+ it("DONE_LIST_RE matches common done-column names", () => {
+ expect(DONE_LIST_RE.test("Done")).toBe(true);
+ expect(DONE_LIST_RE.test("Shipped")).toBe(true);
+ expect(DONE_LIST_RE.test("Complete")).toBe(true);
+ expect(DONE_LIST_RE.test("Backlog")).toBe(false);
+ });
+
+ it("falls back to the first list for compose when no non-done list exists", () => {
+ const lt = buildCardLinkType([{ id: "d", name: "Done", pos: 1 }]);
+ expect(lt.compose).toEqual({ status: "d" });
+ });
+});

.changeset/structured-item-fields.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: structured-item note fields (`sectionKey`, `sectionLabel`, `sectionPosition`, `itemPosition`), `Note.tagActors` (dispatch-time hydrated assignees), and `Actor.source.accountId` (external account id resolved at dispatch).

.changeset/trello-auth-provider.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `AuthProvider.Trello` for the Trello connector's token-authorize flow.

connectors/trello/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plot Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

connectors/trello/README.md

@@ -0,0 +1,3 @@
+# @plotday/connector-trello
+
+This connector syncs your Trello boards and cards into Plot, giving you a unified view of all your work across tools. It supports bidirectional sync: cards appear in Plot with their current status (list), assignees, and comments, and changes you make in Plot — checking off a card, adding a comment — are written back to Trello automatically. When a card moves between lists or is archived in Trello, Plot reflects the change on the next sync cycle.

connectors/trello/package.json

@@ -0,0 +1,43 @@
+{
+ "name": "@plotday/connector-trello",
+ "plotTwistId": "06829c6d-d28f-42bd-8ca8-fede11dd0582",
+ "displayName": "Trello",
+ "description": "Track your Trello cards and check them off as work moves forward.",
+ "logoUrl": "https://api.iconify.design/logos/trello.svg",
+ "publisher": "Plot",
+ "publisherUrl": "https://plot.day",
+ "author": "Plot <team@plot.day> (https://plot.day)",
+ "license": "MIT",
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "private": true,
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "deploy": "plot deploy",
+ "lint": "plot lint",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "@types/node": "^25.0.3",
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ },
+ "repository": { "type": "git", "url": "https://github.com/plotday/plot.git", "directory": "connectors/trello" },
+ "homepage": "https://plot.day",
+ "bugs": { "url": "https://github.com/plotday/plot/issues" },
+ "keywords": ["plot", "connector", "trello", "project-management"]
+}

connectors/trello/src/index.ts

@@ -0,0 +1 @@
+export { default, Trello } from "./trello";

connectors/trello/src/trello-api.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TrelloApi, verifyTrelloWebhook, cardCreatedAt } from "./trello-api";
+
+afterEach(() => vi.restoreAllMocks());
+
+function mockFetchOnce(json: unknown, ok = true, status = 200) {
+ return vi.spyOn(globalThis, "fetch").mockResolvedValue(
+ new Response(JSON.stringify(json), { status: ok ? status : 400 }),
+ );
+}
+
+describe("TrelloApi request shaping", () => {
+ const api = new TrelloApi("KEY", "TOK");
+
+ it("getBoards calls /members/me/boards with key+token", async () => {
+ const f = mockFetchOnce([{ id: "b1", name: "Board" }]);
+ const boards = await api.getBoards();
+ expect(boards).toEqual([{ id: "b1", name: "Board" }]);
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("https://api.trello.com/1/members/me/boards");
+ expect(url).toContain("key=KEY");
+ expect(url).toContain("token=TOK");
+ expect(url).toContain("filter=open");
+ });
+
+ it("getCards passes limit + before for pagination", async () => {
+ const f = mockFetchOnce([]);
+ await api.getCards("b1", { limit: 50, before: "card9" });
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("/boards/b1/cards");
+ expect(url).toContain("limit=50");
+ expect(url).toContain("before=card9");
+ expect(url).toContain("actions=commentCard");
+ expect(url).toContain("attachments=true");
+ expect(url).toContain("members=true");
+ });
+
+ it("addComment POSTs to /cards/{id}/actions/comments and returns the action", async () => {
+ const f = mockFetchOnce({ id: "act1", type: "commentCard", date: "2026-01-01T00:00:00Z", data: { text: "hi" } });
+ const action = await api.addComment("c1", "hi");
+ expect(action.id).toBe("act1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/cards/c1/actions/comments");
+ expect(url).toContain("text=hi");
+ expect(init.method).toBe("POST");
+ });
+
+ it("createWebhook POSTs idModel + callbackURL", async () => {
+ const f = mockFetchOnce({ id: "wh1" });
+ const res = await api.createWebhook("b1", "https://api.plot.test/hook/abc");
+ expect(res.id).toBe("wh1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/webhooks");
+ expect(init.method).toBe("POST");
+ const body = String(init.body);
+ expect(body).toContain("idModel=b1");
+ expect(body).toContain("callbackURL=");
+ });
+});
+
+describe("cardCreatedAt", () => {
+ it("decodes the timestamp from the first 8 hex chars of the id", () => {
+ // 0x5f000000 = 1593817600 → 2020-07-03T...; assert it parses to that epoch.
+ const d = cardCreatedAt("5f000000aaaaaaaaaaaaaaaa");
+ expect(d.getTime()).toBe(0x5f000000 * 1000);
+ });
+});
+
+describe("verifyTrelloWebhook", () => {
+ it("accepts a correct HMAC-SHA1 signature and rejects a wrong one", async () => {
+ const secret = "shh";
+ const body = '{"action":{"type":"updateCard"}}';
+ const callbackURL = "https://api.plot.test/hook/abc";
+ // Compute the expected signature with the same primitive the impl uses.
+ const key = await crypto.subtle.importKey(
+ "raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-1" }, false, ["sign"],
+ );
+ const sigBuf = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(body + callbackURL));
+ const good = btoa(String.fromCharCode(...new Uint8Array(sigBuf)));
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, good)).toBe(true);
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, "wrong")).toBe(false);
+ });
+});

connectors/trello/src/trello-api.ts

@@ -0,0 +1,168 @@
+// Cloudflare Workers provide Buffer/crypto globally; we use Web Crypto + btoa.
+export type TrelloBoard = { id: string; name: string };
+export type TrelloList = { id: string; name: string; pos: number };
+export type TrelloMember = {
+ id: string;
+ fullName: string | null;
+ username: string | null;
+ avatarUrl: string | null;
+};
+export type TrelloAttachment = {
+ id: string;
+ name: string;
+ url: string;
+ bytes: number | null;
+ mimeType: string | null;
+};
+export type TrelloCommentAction = {
+ id: string;
+ type: "commentCard";
+ date: string;
+ memberCreator: TrelloMember | null;
+ data: { text: string };
+};
+export type TrelloCard = {
+ id: string;
+ name: string;
+ desc: string;
+ idList: string;
+ idBoard: string;
+ closed: boolean;
+ url: string;
+ idMembers: string[];
+ members?: TrelloMember[];
+ attachments?: TrelloAttachment[];
+ actions?: TrelloCommentAction[];
+ dateLastActivity: string;
+};
+
+const BASE = "https://api.trello.com/1";
+const CARD_FIELDS = "id,name,desc,idList,idBoard,closed,url,idMembers,dateLastActivity";
+const MEMBER_FIELDS = "id,fullName,username,avatarUrl";
+
+export class TrelloApi {
+ constructor(
+ private readonly key: string,
+ private readonly token: string,
+ ) {}
+
+ private auth(extra = ""): string {
+ const sep = extra ? "&" : "";
+ return `key=${encodeURIComponent(this.key)}&token=${encodeURIComponent(this.token)}${sep}${extra}`;
+ }
+
+ private async req<T>(method: string, path: string, query = "", body?: string): Promise<T> {
+ const url = `${BASE}${path}?${this.auth(body !== undefined ? "" : query)}`;
+ const headers: Record<string, string> = { Accept: "application/json" };
+ if (body !== undefined) headers["Content-Type"] = "application/x-www-form-urlencoded";
+ const res = await fetch(url, { method, headers, ...(body !== undefined ? { body } : {}) });
+ if (!res.ok) {
+ throw new Error(`Trello ${method} ${path} failed: ${res.status} ${await res.text()}`);
+ }
+ return (await res.json()) as T;
+ }
+
+ getBoards(): Promise<TrelloBoard[]> {
+ return this.req("GET", "/members/me/boards", "filter=open&fields=id,name");
+ }
+
+ getLists(boardId: string): Promise<TrelloList[]> {
+ return this.req("GET", `/boards/${boardId}/lists`, "filter=open&fields=id,name,pos");
+ }
+
+ getCards(boardId: string, opts: { limit: number; before?: string }): Promise<TrelloCard[]> {
+ const q = [
+ "filter=open",
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ `limit=${opts.limit}`,
+ ...(opts.before ? [`before=${opts.before}`] : []),
+ ].join("&");
+ return this.req("GET", `/boards/${boardId}/cards`, q);
+ }
+
+ getCard(cardId: string): Promise<TrelloCard> {
+ const q = [
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ ].join("&");
+ return this.req("GET", `/cards/${cardId}`, q);
+ }
+
+ createCard(p: { idList: string; name: string; desc?: string }): Promise<TrelloCard> {
+ const q = [
+ `idList=${encodeURIComponent(p.idList)}`,
+ `name=${encodeURIComponent(p.name)}`,
+ ...(p.desc ? [`desc=${encodeURIComponent(p.desc)}`] : []),
+ ].join("&");
+ return this.req("POST", "/cards", q);
+ }
+
+ updateCard(
+ cardId: string,
+ fields: { idList?: string; closed?: boolean; name?: string; desc?: string },
+ ): Promise<TrelloCard> {
+ const parts: string[] = [];
+ if (fields.idList !== undefined) parts.push(`idList=${encodeURIComponent(fields.idList)}`);
+ if (fields.closed !== undefined) parts.push(`closed=${fields.closed}`);
+ if (fields.name !== undefined) parts.push(`name=${encodeURIComponent(fields.name)}`);
+ if (fields.desc !== undefined) parts.push(`desc=${encodeURIComponent(fields.desc)}`);
+ return this.req("PUT", `/cards/${cardId}`, parts.join("&"));
+ }
+
+ addComment(cardId: string, text: string): Promise<TrelloCommentAction> {
+ return this.req("POST", `/cards/${cardId}/actions/comments`, `text=${encodeURIComponent(text)}`);
+ }
+
+ updateComment(actionId: string, text: string): Promise<{ id: string; data: { text: string } }> {
+ return this.req("PUT", `/actions/${actionId}`, `text=${encodeURIComponent(text)}`);
+ }
+
+ createWebhook(boardId: string, callbackURL: string): Promise<{ id: string }> {
+ const body = `idModel=${encodeURIComponent(boardId)}&callbackURL=${encodeURIComponent(callbackURL)}&description=${encodeURIComponent("Plot Trello sync")}`;
+ return this.req("POST", "/webhooks", "", body);
+ }
+
+ deleteWebhook(webhookId: string): Promise<unknown> {
+ return this.req("DELETE", `/webhooks/${webhookId}`);
+ }
+}
+
+/** Trello object ids encode their creation time in the first 8 hex chars (unix seconds). */
+export function cardCreatedAt(cardId: string): Date {
+ const seconds = parseInt(cardId.substring(0, 8), 16);
+ return new Date(seconds * 1000);
+}
+
+/** Verify a Trello webhook: base64(HMAC-SHA1(appSecret, rawBody + callbackURL)) === header. */
+export async function verifyTrelloWebhook(
+ secret: string,
+ rawBody: string,
+ callbackURL: string,
+ signature: string,
+): Promise<boolean> {
+ try {
+ const key = await crypto.subtle.importKey(
+ "raw",
+ new TextEncoder().encode(secret),
+ { name: "HMAC", hash: "SHA-1" },
+ false,
+ ["sign"],
+ );
+ const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(rawBody + callbackURL));
+ const expected = btoa(String.fromCharCode(...new Uint8Array(sig)));
+ return expected === signature;
+ } catch {
+ return false;
+ }
+}

connectors/trello/src/trello-channels.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { buildCardLinkType, DONE_LIST_RE } from "./trello-channels";
+import type { TrelloList } from "./trello-api";
+
+const lists: TrelloList[] = [
+ { id: "l1", name: "To Do", pos: 1 },
+ { id: "l2", name: "Doing", pos: 2 },
+ { id: "l3", name: "Done", pos: 3 },
+];
+
+describe("buildCardLinkType", () => {
+ it("maps lists to statuses: first=todo, middle=inProgress, done-name=done+done:true", () => {
+ const lt = buildCardLinkType(lists);
+ expect(lt.type).toBe("card");
+ expect(lt.statuses).toEqual([
+ { status: "l1", label: "To Do", icon: "todo" },
+ { status: "l2", label: "Doing", icon: "inProgress" },
+ { status: "l3", label: "Done", icon: "done", done: true },
+ ]);
+ // compose defaults to the first non-done list
+ expect(lt.compose).toEqual({ status: "l1" });
+ });
+
+ it("DONE_LIST_RE matches common done-column names", () => {
+ expect(DONE_LIST_RE.test("Done")).toBe(true);
+ expect(DONE_LIST_RE.test("Shipped")).toBe(true);
+ expect(DONE_LIST_RE.test("Complete")).toBe(true);
+ expect(DONE_LIST_RE.test("Backlog")).toBe(false);
+ });
+
+ it("falls back to the first list for compose when no non-done list exists", () => {
+ const lt = buildCardLinkType([{ id: "d", name: "Done", pos: 1 }]);
+ expect(lt.compose).toEqual({ status: "d" });
+ });
+});

.changeset/structured-item-fields.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: structured-item note fields (`sectionKey`, `sectionLabel`, `sectionPosition`, `itemPosition`), `Note.tagActors` (dispatch-time hydrated assignees), and `Actor.source.accountId` (external account id resolved at dispatch).

.changeset/trello-auth-provider.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `AuthProvider.Trello` for the Trello connector's token-authorize flow.

connectors/trello/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plot Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

connectors/trello/README.md

@@ -0,0 +1,3 @@
+# @plotday/connector-trello
+
+This connector syncs your Trello boards and cards into Plot, giving you a unified view of all your work across tools. It supports bidirectional sync: cards appear in Plot with their current status (list), assignees, and comments, and changes you make in Plot — checking off a card, adding a comment — are written back to Trello automatically. When a card moves between lists or is archived in Trello, Plot reflects the change on the next sync cycle.

connectors/trello/package.json

@@ -0,0 +1,43 @@
+{
+ "name": "@plotday/connector-trello",
+ "plotTwistId": "06829c6d-d28f-42bd-8ca8-fede11dd0582",
+ "displayName": "Trello",
+ "description": "Track your Trello cards and check them off as work moves forward.",
+ "logoUrl": "https://api.iconify.design/logos/trello.svg",
+ "publisher": "Plot",
+ "publisherUrl": "https://plot.day",
+ "author": "Plot <team@plot.day> (https://plot.day)",
+ "license": "MIT",
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "private": true,
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "deploy": "plot deploy",
+ "lint": "plot lint",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "@types/node": "^25.0.3",
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ },
+ "repository": { "type": "git", "url": "https://github.com/plotday/plot.git", "directory": "connectors/trello" },
+ "homepage": "https://plot.day",
+ "bugs": { "url": "https://github.com/plotday/plot/issues" },
+ "keywords": ["plot", "connector", "trello", "project-management"]
+}

connectors/trello/src/index.ts

@@ -0,0 +1 @@
+export { default, Trello } from "./trello";

connectors/trello/src/trello-api.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TrelloApi, verifyTrelloWebhook, cardCreatedAt } from "./trello-api";
+
+afterEach(() => vi.restoreAllMocks());
+
+function mockFetchOnce(json: unknown, ok = true, status = 200) {
+ return vi.spyOn(globalThis, "fetch").mockResolvedValue(
+ new Response(JSON.stringify(json), { status: ok ? status : 400 }),
+ );
+}
+
+describe("TrelloApi request shaping", () => {
+ const api = new TrelloApi("KEY", "TOK");
+
+ it("getBoards calls /members/me/boards with key+token", async () => {
+ const f = mockFetchOnce([{ id: "b1", name: "Board" }]);
+ const boards = await api.getBoards();
+ expect(boards).toEqual([{ id: "b1", name: "Board" }]);
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("https://api.trello.com/1/members/me/boards");
+ expect(url).toContain("key=KEY");
+ expect(url).toContain("token=TOK");
+ expect(url).toContain("filter=open");
+ });
+
+ it("getCards passes limit + before for pagination", async () => {
+ const f = mockFetchOnce([]);
+ await api.getCards("b1", { limit: 50, before: "card9" });
+ const url = f.mock.calls[0][0] as string;
+ expect(url).toContain("/boards/b1/cards");
+ expect(url).toContain("limit=50");
+ expect(url).toContain("before=card9");
+ expect(url).toContain("actions=commentCard");
+ expect(url).toContain("attachments=true");
+ expect(url).toContain("members=true");
+ });
+
+ it("addComment POSTs to /cards/{id}/actions/comments and returns the action", async () => {
+ const f = mockFetchOnce({ id: "act1", type: "commentCard", date: "2026-01-01T00:00:00Z", data: { text: "hi" } });
+ const action = await api.addComment("c1", "hi");
+ expect(action.id).toBe("act1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/cards/c1/actions/comments");
+ expect(url).toContain("text=hi");
+ expect(init.method).toBe("POST");
+ });
+
+ it("createWebhook POSTs idModel + callbackURL", async () => {
+ const f = mockFetchOnce({ id: "wh1" });
+ const res = await api.createWebhook("b1", "https://api.plot.test/hook/abc");
+ expect(res.id).toBe("wh1");
+ const [url, init] = f.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/webhooks");
+ expect(init.method).toBe("POST");
+ const body = String(init.body);
+ expect(body).toContain("idModel=b1");
+ expect(body).toContain("callbackURL=");
+ });
+});
+
+describe("cardCreatedAt", () => {
+ it("decodes the timestamp from the first 8 hex chars of the id", () => {
+ // 0x5f000000 = 1593817600 → 2020-07-03T...; assert it parses to that epoch.
+ const d = cardCreatedAt("5f000000aaaaaaaaaaaaaaaa");
+ expect(d.getTime()).toBe(0x5f000000 * 1000);
+ });
+});
+
+describe("verifyTrelloWebhook", () => {
+ it("accepts a correct HMAC-SHA1 signature and rejects a wrong one", async () => {
+ const secret = "shh";
+ const body = '{"action":{"type":"updateCard"}}';
+ const callbackURL = "https://api.plot.test/hook/abc";
+ // Compute the expected signature with the same primitive the impl uses.
+ const key = await crypto.subtle.importKey(
+ "raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-1" }, false, ["sign"],
+ );
+ const sigBuf = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(body + callbackURL));
+ const good = btoa(String.fromCharCode(...new Uint8Array(sigBuf)));
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, good)).toBe(true);
+ expect(await verifyTrelloWebhook(secret, body, callbackURL, "wrong")).toBe(false);
+ });
+});

connectors/trello/src/trello-api.ts

@@ -0,0 +1,168 @@
+// Cloudflare Workers provide Buffer/crypto globally; we use Web Crypto + btoa.
+export type TrelloBoard = { id: string; name: string };
+export type TrelloList = { id: string; name: string; pos: number };
+export type TrelloMember = {
+ id: string;
+ fullName: string | null;
+ username: string | null;
+ avatarUrl: string | null;
+};
+export type TrelloAttachment = {
+ id: string;
+ name: string;
+ url: string;
+ bytes: number | null;
+ mimeType: string | null;
+};
+export type TrelloCommentAction = {
+ id: string;
+ type: "commentCard";
+ date: string;
+ memberCreator: TrelloMember | null;
+ data: { text: string };
+};
+export type TrelloCard = {
+ id: string;
+ name: string;
+ desc: string;
+ idList: string;
+ idBoard: string;
+ closed: boolean;
+ url: string;
+ idMembers: string[];
+ members?: TrelloMember[];
+ attachments?: TrelloAttachment[];
+ actions?: TrelloCommentAction[];
+ dateLastActivity: string;
+};
+
+const BASE = "https://api.trello.com/1";
+const CARD_FIELDS = "id,name,desc,idList,idBoard,closed,url,idMembers,dateLastActivity";
+const MEMBER_FIELDS = "id,fullName,username,avatarUrl";
+
+export class TrelloApi {
+ constructor(
+ private readonly key: string,
+ private readonly token: string,
+ ) {}
+
+ private auth(extra = ""): string {
+ const sep = extra ? "&" : "";
+ return `key=${encodeURIComponent(this.key)}&token=${encodeURIComponent(this.token)}${sep}${extra}`;
+ }
+
+ private async req<T>(method: string, path: string, query = "", body?: string): Promise<T> {
+ const url = `${BASE}${path}?${this.auth(body !== undefined ? "" : query)}`;
+ const headers: Record<string, string> = { Accept: "application/json" };
+ if (body !== undefined) headers["Content-Type"] = "application/x-www-form-urlencoded";
+ const res = await fetch(url, { method, headers, ...(body !== undefined ? { body } : {}) });
+ if (!res.ok) {
+ throw new Error(`Trello ${method} ${path} failed: ${res.status} ${await res.text()}`);
+ }
+ return (await res.json()) as T;
+ }
+
+ getBoards(): Promise<TrelloBoard[]> {
+ return this.req("GET", "/members/me/boards", "filter=open&fields=id,name");
+ }
+
+ getLists(boardId: string): Promise<TrelloList[]> {
+ return this.req("GET", `/boards/${boardId}/lists`, "filter=open&fields=id,name,pos");
+ }
+
+ getCards(boardId: string, opts: { limit: number; before?: string }): Promise<TrelloCard[]> {
+ const q = [
+ "filter=open",
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ `limit=${opts.limit}`,
+ ...(opts.before ? [`before=${opts.before}`] : []),
+ ].join("&");
+ return this.req("GET", `/boards/${boardId}/cards`, q);
+ }
+
+ getCard(cardId: string): Promise<TrelloCard> {
+ const q = [
+ `fields=${CARD_FIELDS}`,
+ "members=true",
+ `member_fields=${MEMBER_FIELDS}`,
+ "attachments=true",
+ "attachment_fields=id,name,url,bytes,mimeType",
+ "actions=commentCard",
+ "actions_limit=50",
+ ].join("&");
+ return this.req("GET", `/cards/${cardId}`, q);
+ }
+
+ createCard(p: { idList: string; name: string; desc?: string }): Promise<TrelloCard> {
+ const q = [
+ `idList=${encodeURIComponent(p.idList)}`,
+ `name=${encodeURIComponent(p.name)}`,
+ ...(p.desc ? [`desc=${encodeURIComponent(p.desc)}`] : []),
+ ].join("&");
+ return this.req("POST", "/cards", q);
+ }
+
+ updateCard(
+ cardId: string,
+ fields: { idList?: string; closed?: boolean; name?: string; desc?: string },
+ ): Promise<TrelloCard> {
+ const parts: string[] = [];
+ if (fields.idList !== undefined) parts.push(`idList=${encodeURIComponent(fields.idList)}`);
+ if (fields.closed !== undefined) parts.push(`closed=${fields.closed}`);
+ if (fields.name !== undefined) parts.push(`name=${encodeURIComponent(fields.name)}`);
+ if (fields.desc !== undefined) parts.push(`desc=${encodeURIComponent(fields.desc)}`);
+ return this.req("PUT", `/cards/${cardId}`, parts.join("&"));
+ }
+
+ addComment(cardId: string, text: string): Promise<TrelloCommentAction> {
+ return this.req("POST", `/cards/${cardId}/actions/comments`, `text=${encodeURIComponent(text)}`);
+ }
+
+ updateComment(actionId: string, text: string): Promise<{ id: string; data: { text: string } }> {
+ return this.req("PUT", `/actions/${actionId}`, `text=${encodeURIComponent(text)}`);
+ }
+
+ createWebhook(boardId: string, callbackURL: string): Promise<{ id: string }> {
+ const body = `idModel=${encodeURIComponent(boardId)}&callbackURL=${encodeURIComponent(callbackURL)}&description=${encodeURIComponent("Plot Trello sync")}`;
+ return this.req("POST", "/webhooks", "", body);
+ }
+
+ deleteWebhook(webhookId: string): Promise<unknown> {
+ return this.req("DELETE", `/webhooks/${webhookId}`);
+ }
+}
+
+/** Trello object ids encode their creation time in the first 8 hex chars (unix seconds). */
+export function cardCreatedAt(cardId: string): Date {
+ const seconds = parseInt(cardId.substring(0, 8), 16);
+ return new Date(seconds * 1000);
+}
+
+/** Verify a Trello webhook: base64(HMAC-SHA1(appSecret, rawBody + callbackURL)) === header. */
+export async function verifyTrelloWebhook(
+ secret: string,
+ rawBody: string,
+ callbackURL: string,
+ signature: string,
+): Promise<boolean> {
+ try {
+ const key = await crypto.subtle.importKey(
+ "raw",
+ new TextEncoder().encode(secret),
+ { name: "HMAC", hash: "SHA-1" },
+ false,
+ ["sign"],
+ );
+ const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(rawBody + callbackURL));
+ const expected = btoa(String.fromCharCode(...new Uint8Array(sig)));
+ return expected === signature;
+ } catch {
+ return false;
+ }
+}

connectors/trello/src/trello-channels.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { buildCardLinkType, DONE_LIST_RE } from "./trello-channels";
+import type { TrelloList } from "./trello-api";
+
+const lists: TrelloList[] = [
+ { id: "l1", name: "To Do", pos: 1 },
+ { id: "l2", name: "Doing", pos: 2 },
+ { id: "l3", name: "Done", pos: 3 },
+];
+
+describe("buildCardLinkType", () => {
+ it("maps lists to statuses: first=todo, middle=inProgress, done-name=done+done:true", () => {
+ const lt = buildCardLinkType(lists);
+ expect(lt.type).toBe("card");
+ expect(lt.statuses).toEqual([
+ { status: "l1", label: "To Do", icon: "todo" },
+ { status: "l2", label: "Doing", icon: "inProgress" },
+ { status: "l3", label: "Done", icon: "done", done: true },
+ ]);
+ // compose defaults to the first non-done list
+ expect(lt.compose).toEqual({ status: "l1" });
+ });
+
+ it("DONE_LIST_RE matches common done-column names", () => {
+ expect(DONE_LIST_RE.test("Done")).toBe(true);
+ expect(DONE_LIST_RE.test("Shipped")).toBe(true);
+ expect(DONE_LIST_RE.test("Complete")).toBe(true);
+ expect(DONE_LIST_RE.test("Backlog")).toBe(false);
+ });
+
+ it("falls back to the first list for compose when no non-done list exists", () => {
+ const lt = buildCardLinkType([{ id: "d", name: "Done", pos: 1 }]);
+ expect(lt.compose).toEqual({ status: "d" });
+ });
+});