@evanston/plankton-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan Kim
+
+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.

package/README.md

@@ -0,0 +1,18 @@
+# @evanston/plankton-core
+
+Provider-independent TypeScript client for Planka 2.0.0-rc.4. Requires Node.js 22+. Original code is MIT licensed. This initial version has only source/fixture validation against rc.4, not live production testing.
+
+```ts
+import { PlankaClient, errorResult } from '@evanston/plankton-core';
+const client = new PlankaClient({ url: 'https://planka.example', session: await yourVault.read() });
+try {
+  const result = await client.execute('create_card', {
+    board: 'Product', list: 'Todo', name: 'Review onboarding',
+  });
+  console.log(result.item);
+} catch (error) { console.error(errorResult(error)); }
+```
+
+Session input is `{ accessToken, httpOnlyToken? }`; keep it in a credential vault. Core uses native fetch and Zod. It has no browser, MCP, keyring or AI-provider dependency.
+
+`account()` verifies the current user. `execute(operation, input)` exposes projects, boards, lists, find_cards, read_card, create_card, edit_card, move_card, task_lists, create_task_list, edit_task_list, add_task and complete_task. Exported `operationSchemas` define each input. Board/card IDs and same-instance links work directly; names are scoped and ambiguous matches return choices. Card search is bounded and returns `truncated` when incomplete. Error results are safe to share; write uncertainty is never retried automatically. Moving/creating cards in trash is excluded.

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import { type Operation, type OperationInput } from './schemas.js';
+import { type ClientOptions } from './transport.js';
+export declare class PlankaClient {
+    readonly url: string;
+    private readonly transport;
+    constructor(options: ClientOptions);
+    private item;
+    private board;
+    private card;
+    private writableList;
+    private link;
+    account(): Promise<{
+        id: string;
+        name: string | undefined;
+        username: unknown;
+    }>;
+    private search;
+    execute<K extends Operation>(operation: K, input: OperationInput<K>): Promise<Record<string, unknown>>;
+    private writeItem;
+    private executeCard;
+    private executeTask;
+}

package/dist/client.js

@@ -0,0 +1,190 @@
+import { PlanktonError } from './errors.js';
+import { referenceId, resolveReference } from './references.js';
+import { operationSchemas, } from './schemas.js';
+import { PlankaTransport } from './transport.js';
+export class PlankaClient {
+    url;
+    transport;
+    constructor(options) {
+        this.transport = new PlankaTransport(options);
+        this.url = this.transport.url;
+    }
+    item(data) {
+        if (!data.item) {
+            throw new PlanktonError('API', 'Planka response is missing the expected resource.');
+        }
+        return data.item;
+    }
+    async board(value) {
+        const id = referenceId(this.url, value, 'boards') ??
+            resolveReference(this.url, value, (await this.transport.request('projects')).included?.boards ?? [], 'boards').id;
+        return this.transport.request(`boards/${id}`);
+    }
+    async card(value, board) {
+        let id = referenceId(this.url, value, 'cards');
+        if (!id) {
+            if (!board) {
+                throw new PlanktonError('VALIDATION', 'Supply a board to resolve a card name, or use a card ID/link.');
+            }
+            const found = await this.search(board, value, 100);
+            if (found.truncated) {
+                throw new PlanktonError('VALIDATION', 'Card search is incomplete. Use a card ID/link to avoid resolving the wrong card.');
+            }
+            id = resolveReference(this.url, value, found.items, 'cards').id;
+        }
+        return this.transport.request(`cards/${id}`);
+    }
+    writableList(list) {
+        if (list.type === 'trash') {
+            throw new PlanktonError('VALIDATION', 'Moving or creating cards in trash is outside the initial scope.');
+        }
+    }
+    link(item, kind = 'cards') {
+        return { ...item, url: `${this.url}/${kind}/${item.id}` };
+    }
+    async account() {
+        const item = this.item(await this.transport.request('users/me'));
+        return { id: item.id, name: item.name, username: item.username };
+    }
+    async search(board, query, limit) {
+        const data = await this.board(board);
+        const lists = data.included?.lists ?? [];
+        const cards = new Map((data.included?.cards ?? []).map((c) => [c.id, c]));
+        let truncated = false;
+        // Endless lists have separate pages; cap work and disclose incomplete results.
+        for (const list of lists.filter((l) => l.type === 'archive' || l.type === 'trash')) {
+            let before;
+            for (let page = 0; page < 10; page++) {
+                const params = new URLSearchParams();
+                if (before) {
+                    params.set('before', JSON.stringify(before));
+                }
+                const rows = (await this.transport.request(`lists/${list.id}/cards${params.size ? `?${params}` : ''}`))
+                    .items ?? [];
+                if (!rows.length) {
+                    break;
+                }
+                for (const row of rows) {
+                    cards.set(row.id, row);
+                }
+                const last = rows.at(-1);
+                if (!last.listChangedAt || page === 9) {
+                    truncated = true;
+                    break;
+                }
+                const next = { id: last.id, listChangedAt: last.listChangedAt };
+                if (JSON.stringify(next) === JSON.stringify(before)) {
+                    truncated = true;
+                    break;
+                }
+                before = next;
+            }
+        }
+        const matches = [...cards.values()].filter((c) => c.name?.toLocaleLowerCase().includes(query.toLocaleLowerCase()));
+        return {
+            items: matches.slice(0, limit).map((c) => this.link(c)),
+            truncated: truncated || matches.length > limit,
+        };
+    }
+    async execute(operation, input) {
+        // The public method validates independently of MCP callers.
+        const args = { ...operationSchemas[operation].parse(input), operation };
+        switch (args.operation) {
+            case 'projects':
+                return {
+                    items: ((await this.transport.request('projects')).items ?? []).map((i) => this.link(i, 'projects')),
+                };
+            case 'boards': {
+                const data = await this.transport.request('projects');
+                const projectId = args.project
+                    ? resolveReference(this.url, args.project, data.items ?? [], 'projects').id
+                    : undefined;
+                return {
+                    items: (data.included?.boards ?? [])
+                        .filter((b) => !projectId || b.projectId === projectId)
+                        .map((b) => this.link(b, 'boards')),
+                };
+            }
+            case 'lists':
+                return { items: (await this.board(args.board)).included?.lists ?? [] };
+            case 'find_cards':
+                return this.search(args.board, args.query, args.limit);
+            case 'create_card': {
+                const board = await this.board(args.board);
+                const list = resolveReference(this.url, args.list, board.included?.lists ?? [], 'lists');
+                this.writableList(list);
+                const item = await this.writeItem(`lists/${list.id}/cards`, 'POST', {
+                    name: args.name,
+                    description: args.description,
+                    type: args.type,
+                    position: args.position,
+                });
+                return { item: this.link(item) };
+            }
+            default:
+                return this.executeCard(args);
+        }
+    }
+    async writeItem(path, method, body) {
+        return this.item(await this.transport.request(path, method, body));
+    }
+    async executeCard(args) {
+        const data = await this.card(args.card, args.board);
+        const card = this.item(data);
+        const url = this.link(card).url;
+        switch (args.operation) {
+            case 'read_card':
+                return {
+                    item: this.link(card),
+                    taskLists: data.included?.taskLists ?? [],
+                    tasks: data.included?.tasks ?? [],
+                };
+            case 'edit_card': {
+                const item = await this.writeItem(`cards/${card.id}`, 'PATCH', {
+                    name: args.name,
+                    description: args.description,
+                });
+                return { item: this.link(item) };
+            }
+            case 'move_card': {
+                const board = await this.board(args.destinationBoard);
+                const list = resolveReference(this.url, args.list, board.included?.lists ?? [], 'lists');
+                this.writableList(list);
+                const item = await this.writeItem(`cards/${card.id}`, 'PATCH', {
+                    boardId: this.item(board).id,
+                    listId: list.id,
+                    position: args.position,
+                });
+                return { item: this.link(item) };
+            }
+            case 'task_lists':
+                return { items: data.included?.taskLists ?? [], tasks: data.included?.tasks ?? [], url };
+            case 'create_task_list': {
+                const item = await this.writeItem(`cards/${card.id}/task-lists`, 'POST', {
+                    name: args.name,
+                    position: args.position,
+                });
+                return { item, url };
+            }
+            default:
+                return { item: await this.executeTask(args, data), url };
+        }
+    }
+    async executeTask(args, data) {
+        const taskList = resolveReference(this.url, args.taskList, data.included?.taskLists ?? [], 'task-lists');
+        switch (args.operation) {
+            case 'edit_task_list':
+                return this.writeItem(`task-lists/${taskList.id}`, 'PATCH', { name: args.name });
+            case 'add_task':
+                return this.writeItem(`task-lists/${taskList.id}/tasks`, 'POST', {
+                    name: args.name,
+                    position: args.position,
+                });
+            case 'complete_task': {
+                const task = resolveReference(this.url, args.task, (data.included?.tasks ?? []).filter((task) => task.taskListId === taskList.id), 'tasks');
+                return this.writeItem(`tasks/${task.id}`, 'PATCH', { isCompleted: args.isCompleted });
+            }
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EACL,gBAAgB,GAMjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,eAAe,EAAsB,MAAM,gBAAgB,CAAC;AAErE,MAAM,OAAO,YAAY;IACd,GAAG,CAAS;IACJ,SAAS,CAAkB;IAE5C,YAAY,OAAsB;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;IAChC,CAAC;IAEO,IAAI,CAAC,IAAc;QACzB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,MAAM,IAAI,aAAa,CAAC,KAAK,EAAE,mDAAmD,CAAC,CAAC;QACtF,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAEO,KAAK,CAAC,KAAK,CAAC,KAAa;QAC/B,MAAM,EAAE,GACN,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC;YACtC,gBAAgB,CACd,IAAI,CAAC,GAAG,EACR,KAAK,EACL,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EACjE,QAAQ,CACT,CAAC,EAAE,CAAC;QACP,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAChD,CAAC;IAEO,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,KAAc;QAC9C,IAAI,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QAC/C,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,aAAa,CACrB,YAAY,EACZ,+DAA+D,CAChE,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;YACnD,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;gBACpB,MAAM,IAAI,aAAa,CACrB,YAAY,EACZ,kFAAkF,CACnF,CAAC;YACJ,CAAC;YACD,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;QAClE,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAC/C,CAAC;IAEO,YAAY,CAAC,IAAY;QAC/B,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC1B,MAAM,IAAI,aAAa,CACrB,YAAY,EACZ,iEAAiE,CAClE,CAAC;QACJ,CAAC;IACH,CAAC;IAEO,IAAI,CAAC,IAAY,EAAE,IAAI,GAAG,OAAO;QACvC,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;QACjE,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;IACnE,CAAC;IAEO,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,KAAa,EAAE,KAAa;QAC9D,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,+EAA+E;QAC/E,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,EAAE,CAAC;YACnF,IAAI,MAAe,CAAC;YACpB,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC;gBACrC,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;gBACrC,IAAI,MAAM,EAAE,CAAC;oBACX,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC/C,CAAC;gBACD,MAAM,IAAI,GACR,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,EAAE,SAAS,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;qBACvF,KAAK,IAAI,EAAE,CAAC;gBACjB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;oBACjB,MAAM;gBACR,CAAC;gBACD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;oBACvB,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;gBACzB,CAAC;gBACD,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC;gBAC1B,IAAI,CAAC,IAAI,CAAC,aAAa,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;oBACtC,SAAS,GAAG,IAAI,CAAC;oBACjB,MAAM;gBACR,CAAC;gBACD,MAAM,IAAI,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC;gBAChE,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;oBACpD,SAAS,GAAG,IAAI,CAAC;oBACjB,MAAM;gBACR,CAAC;gBACD,MAAM,GAAG,IAAI,CAAC;YAChB,CAAC;QACH,CAAC;QACD,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAC/C,CAAC,CAAC,IAAI,EAAE,iBAAiB,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,iBAAiB,EAAE,CAAC,CAChE,CAAC;QACF,OAAO;YACL,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACvD,SAAS,EAAE,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,KAAK;SAC/C,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,OAAO,CACX,SAAY,EACZ,KAAwB;QAExB,4DAA4D;QAC5D,MAAM,IAAI,GAAG,EAAE,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,SAAS,EAAqB,CAAC;QAC3F,QAAQ,IAAI,CAAC,SAAS,EAAE,CAAC;YACvB,KAAK,UAAU;gBACb,OAAO;oBACL,KAAK,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACxE,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,CACzB;iBACF,CAAC;YACJ,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;gBACtD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO;oBAC5B,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,UAAU,CAAC,CAAC,EAAE;oBAC3E,CAAC,CAAC,SAAS,CAAC;gBACd,OAAO;oBACL,KAAK,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,CAAC;yBACjC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC;yBACtD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;iBACtC,CAAC;YACJ,CAAC;YACD,KAAK,OAAO;gBACV,OAAO,EAAE,KAAK,EAAE,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;YACzE,KAAK,YAAY;gBACf,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YACzD,KAAK,aAAa,CAAC,CAAC,CAAC;gBACnB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC3C,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;gBACzF,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;gBACxB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE;oBAClE,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,WAAW,EAAE,IAAI,CAAC,WAAW;oBAC7B,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;iBACxB,CAAC,CAAC;gBACH,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,CAAC;YACD;gBACE,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,IAAY,EAAE,MAAwB,EAAE,IAAa;QAC3E,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IACrE,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,IAAgD;QACxE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACpD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC;QAEhC,QAAQ,IAAI,CAAC,SAAS,EAAE,CAAC;YACvB,KAAK,WAAW;gBACd,OAAO;oBACL,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;oBACrB,SAAS,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,IAAI,EAAE;oBACzC,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;iBAClC,CAAC;YACJ,KAAK,WAAW,CAAC,CAAC,CAAC;gBACjB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,IAAI,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE;oBAC7D,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,WAAW,EAAE,IAAI,CAAC,WAAW;iBAC9B,CAAC,CAAC;gBACH,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,CAAC;YACD,KAAK,WAAW,CAAC,CAAC,CAAC;gBACjB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;gBACtD,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;gBACzF,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;gBACxB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,IAAI,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE;oBAC7D,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE;oBAC5B,MAAM,EAAE,IAAI,CAAC,EAAE;oBACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;iBACxB,CAAC,CAAC;gBACH,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,CAAC;YACD,KAAK,YAAY;gBACf,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC;YAC3F,KAAK,kBAAkB,CAAC,CAAC,CAAC;gBACxB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,IAAI,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE;oBACvE,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;iBACxB,CAAC,CAAC;gBACH,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;YACvB,CAAC;YACD;gBACE,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QAC7D,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,IAAoD,EAAE,IAAc;QAC5F,MAAM,QAAQ,GAAG,gBAAgB,CAC/B,IAAI,CAAC,GAAG,EACR,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,QAAQ,EAAE,SAAS,IAAI,EAAE,EAC9B,YAAY,CACb,CAAC;QAEF,QAAQ,IAAI,CAAC,SAAS,EAAE,CAAC;YACvB,KAAK,gBAAgB;gBACnB,OAAO,IAAI,CAAC,SAAS,CAAC,cAAc,QAAQ,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YACnF,KAAK,UAAU;gBACb,OAAO,IAAI,CAAC,SAAS,CAAC,cAAc,QAAQ,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE;oBAC/D,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;iBACxB,CAAC,CAAC;YACL,KAAK,eAAe,CAAC,CAAC,CAAC;gBACrB,MAAM,IAAI,GAAG,gBAAgB,CAC3B,IAAI,CAAC,GAAG,EACR,IAAI,CAAC,IAAI,EACT,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,KAAK,QAAQ,CAAC,EAAE,CAAC,EAC9E,OAAO,CACR,CAAC;gBACF,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,IAAI,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;YACxF,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+export type ErrorCode = 'AUTHENTICATION' | 'PERMISSION' | 'VALIDATION' | 'NOT_FOUND' | 'AMBIGUOUS' | 'NETWORK' | 'UNCERTAIN_WRITE' | 'API' | 'STORAGE' | 'LOGIN';
+export declare class PlanktonError extends Error {
+    code: ErrorCode;
+    details?: Record<string, unknown> | undefined;
+    constructor(code: ErrorCode, message: string, details?: Record<string, unknown> | undefined);
+}
+export declare function errorResult(error: unknown): {
+    ok: false;
+    error: {
+        details?: Record<string, unknown> | undefined;
+        code: ErrorCode;
+        message: string;
+    };
+};

package/dist/errors.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export class PlanktonError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'PlanktonError';
+    }
+}
+export function errorResult(error) {
+    const e = error instanceof PlanktonError
+        ? error
+        : error instanceof z.ZodError
+            ? new PlanktonError('VALIDATION', 'Invalid input. Check field types, lengths and required references.', { fields: error.issues.map((i) => i.path.join('.')) })
+            : new PlanktonError('API', 'Operation failed. Run plankton doctor for connection diagnostics.');
+    return {
+        ok: false,
+        error: { code: e.code, message: e.message, ...(e.details ? { details: e.details } : {}) },
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,MAAM,OAAO,aAAc,SAAQ,KAAK;IAE7B;IAEA;IAHT,YACS,IAAe,EACtB,OAAe,EACR,OAAiC;QAExC,KAAK,CAAC,OAAO,CAAC,CAAC;QAJR,SAAI,GAAJ,IAAI,CAAW;QAEf,YAAO,GAAP,OAAO,CAA0B;QAGxC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,MAAM,CAAC,GACL,KAAK,YAAY,aAAa;QAC5B,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,KAAK,YAAY,CAAC,CAAC,QAAQ;YAC3B,CAAC,CAAC,IAAI,aAAa,CACf,YAAY,EACZ,oEAAoE,EACpE,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CACtD;YACH,CAAC,CAAC,IAAI,aAAa,CACf,KAAK,EACL,mEAAmE,CACpE,CAAC;IACV,OAAO;QACL,EAAE,EAAE,KAAc;QAClB,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;KAC1F,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { PlankaClient } from './client.js';
+export { PlanktonError, errorResult, type ErrorCode } from './errors.js';
+export { normalizeUrl, sessionSchema, type Session } from './session.js';
+export { operationSchemas, type Entity, type Operation, type OperationInput } from './schemas.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { PlankaClient } from './client.js';
+export { PlanktonError, errorResult } from './errors.js';
+export { normalizeUrl, sessionSchema } from './session.js';
+export { operationSchemas } from './schemas.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,WAAW,EAAkB,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAgB,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAoD,MAAM,cAAc,CAAC"}

package/dist/references.d.ts

@@ -0,0 +1,3 @@
+import type { Entity } from './schemas.js';
+export declare function referenceId(baseUrl: string, value: string, kind: string): string | undefined;
+export declare function resolveReference(baseUrl: string, value: string, items: Entity[], kind: string): Entity;

package/dist/references.js

@@ -0,0 +1,32 @@
+import { PlanktonError } from './errors.js';
+export function referenceId(baseUrl, value, kind) {
+    if (/^\d+$/.test(value)) {
+        return value;
+    }
+    if (/^https?:\/\//i.test(value)) {
+        const url = new URL(value);
+        const base = new URL(baseUrl);
+        const prefix = `${base.pathname.replace(/\/$/, '')}/${kind}/`;
+        if (url.origin !== base.origin ||
+            !url.pathname.startsWith(prefix) ||
+            !/^\d+$/.test(url.pathname.slice(prefix.length))) {
+            throw new PlanktonError('VALIDATION', `Use a ${kind} link from the active Planka instance.`);
+        }
+        return url.pathname.slice(prefix.length);
+    }
+    return undefined;
+}
+export function resolveReference(baseUrl, value, items, kind) {
+    const id = referenceId(baseUrl, value, kind);
+    const matches = items.filter((i) => id ? i.id === id : i.name?.toLocaleLowerCase() === value.toLocaleLowerCase());
+    if (!matches.length) {
+        throw new PlanktonError('NOT_FOUND', `No matching ${kind} in this scope.`);
+    }
+    if (matches.length > 1) {
+        throw new PlanktonError('AMBIGUOUS', `Multiple ${kind} match. Choose an ID.`, {
+            choices: matches.map((i) => ({ id: i.id, name: i.name })),
+        });
+    }
+    return matches[0];
+}
+//# sourceMappingURL=references.js.map

package/dist/references.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"references.js","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,KAAa,EAAE,IAAY;IACtE,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC;QAC9D,IACE,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;YAC1B,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;YAChC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAChD,CAAC;YACD,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,SAAS,IAAI,wCAAwC,CAAC,CAAC;QAC/F,CAAC;QACD,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,KAAa,EACb,KAAe,EACf,IAAY;IAEZ,MAAM,EAAE,GAAG,WAAW,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACjC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,iBAAiB,EAAE,KAAK,KAAK,CAAC,iBAAiB,EAAE,CAC7E,CAAC;IACF,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QACpB,MAAM,IAAI,aAAa,CAAC,WAAW,EAAE,eAAe,IAAI,iBAAiB,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,aAAa,CAAC,WAAW,EAAE,YAAY,IAAI,uBAAuB,EAAE;YAC5E,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;SAC1D,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC,CAAC,CAAE,CAAC;AACrB,CAAC"}

package/dist/schemas.d.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+declare const entitySchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$catchall<z.ZodUnknown>>;
+export type Entity = z.infer<typeof entitySchema>;
+export declare const envelopeSchema: z.ZodObject<{
+    item: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodUnknown>>>;
+    items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodUnknown>>>>;
+    included: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodUnknown>>>>>;
+}, z.core.$strip>;
+export type Envelope = z.infer<typeof envelopeSchema>;
+export declare const operationSchemas: {
+    projects: z.ZodObject<{}, z.core.$strict>;
+    boards: z.ZodObject<{
+        project: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    lists: z.ZodObject<{
+        board: z.ZodString;
+    }, z.core.$strict>;
+    find_cards: z.ZodObject<{
+        board: z.ZodString;
+        query: z.ZodString;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+    read_card: z.ZodObject<{
+        card: z.ZodString;
+        board: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    create_card: z.ZodObject<{
+        board: z.ZodString;
+        list: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        type: z.ZodDefault<z.ZodEnum<{
+            project: "project";
+            story: "story";
+        }>>;
+        position: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+    edit_card: z.ZodObject<{
+        card: z.ZodString;
+        board: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    move_card: z.ZodObject<{
+        card: z.ZodString;
+        board: z.ZodOptional<z.ZodString>;
+        destinationBoard: z.ZodString;
+        list: z.ZodString;
+        position: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+    task_lists: z.ZodObject<{
+        card: z.ZodString;
+        board: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    create_task_list: z.ZodObject<{
+        card: z.ZodString;
+        board: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        position: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+    edit_task_list: z.ZodObject<{
+        card: z.ZodString;
+        board: z.ZodOptional<z.ZodString>;
+        taskList: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>;
+    add_task: z.ZodObject<{
+        card: z.ZodString;
+        board: z.ZodOptional<z.ZodString>;
+        taskList: z.ZodString;
+        name: z.ZodString;
+        position: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+    complete_task: z.ZodObject<{
+        card: z.ZodString;
+        board: z.ZodOptional<z.ZodString>;
+        taskList: z.ZodString;
+        task: z.ZodString;
+        isCompleted: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>;
+};
+export type Operation = keyof typeof operationSchemas;
+export type OperationInput<K extends Operation> = z.input<(typeof operationSchemas)[K]>;
+export type ParsedOperation = {
+    [K in Operation]: z.output<(typeof operationSchemas)[K]> & {
+        operation: K;
+    };
+}[Operation];
+export {};

package/dist/schemas.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+const entitySchema = z
+    .object({ id: z.string().regex(/^\d+$/), name: z.string().optional() })
+    .catchall(z.unknown());
+export const envelopeSchema = z.object({
+    item: entitySchema.optional(),
+    items: z.array(entitySchema).optional(),
+    included: z.record(z.string(), z.array(entitySchema)).optional(),
+});
+const ref = z.string().trim().min(1).max(2048);
+const name = z.string().trim().min(1).max(1024);
+const position = z.number().finite().nonnegative().default(65535);
+const description = z.string().min(1).max(1048576).nullable();
+export const operationSchemas = {
+    projects: z.object({}).strict(),
+    boards: z.object({ project: ref.optional() }).strict(),
+    lists: z.object({ board: ref }).strict(),
+    find_cards: z
+        .object({
+        board: ref,
+        query: z.string().trim().min(1).max(128),
+        limit: z.number().int().min(1).max(100).default(25),
+    })
+        .strict(),
+    read_card: z.object({ card: ref, board: ref.optional() }).strict(),
+    create_card: z
+        .object({
+        board: ref,
+        list: ref,
+        name,
+        description: description.optional(),
+        type: z.enum(['project', 'story']).default('project'),
+        position,
+    })
+        .strict(),
+    edit_card: z
+        .object({
+        card: ref,
+        board: ref.optional(),
+        name: name.optional(),
+        description: description.optional(),
+    })
+        .strict()
+        .refine((v) => v.name !== undefined || v.description !== undefined),
+    move_card: z
+        .object({ card: ref, board: ref.optional(), destinationBoard: ref, list: ref, position })
+        .strict(),
+    task_lists: z.object({ card: ref, board: ref.optional() }).strict(),
+    create_task_list: z
+        .object({ card: ref, board: ref.optional(), name: name.max(128), position })
+        .strict(),
+    edit_task_list: z
+        .object({ card: ref, board: ref.optional(), taskList: ref, name: name.max(128) })
+        .strict(),
+    add_task: z.object({ card: ref, board: ref.optional(), taskList: ref, name, position }).strict(),
+    complete_task: z
+        .object({
+        card: ref,
+        board: ref.optional(),
+        taskList: ref,
+        task: ref,
+        isCompleted: z.boolean().default(true),
+    })
+        .strict(),
+};
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export declare const sessionSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    httpOnlyToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type Session = z.infer<typeof sessionSchema>;
+export declare function normalizeUrl(value: string): string;

package/dist/session.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { PlanktonError } from './errors.js';
+const token = z
+    .string()
+    .min(1)
+    .max(16384)
+    .regex(/^[A-Za-z0-9._~+%/=-]+$/);
+export const sessionSchema = z
+    .object({ accessToken: token, httpOnlyToken: token.optional() })
+    .strict();
+export function normalizeUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new PlanktonError('VALIDATION', 'Enter an absolute Planka URL.');
+    }
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash) {
+        throw new PlanktonError('VALIDATION', 'Use an HTTP(S) Planka URL without credentials, query or fragment.');
+    }
+    if (url.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) {
+        throw new PlanktonError('VALIDATION', 'Use HTTPS for remote Planka instances.');
+    }
+    return url.href.replace(/\/+$/, '');
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,MAAM,KAAK,GAAG,CAAC;KACZ,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,KAAK,CAAC;KACV,KAAK,CAAC,wBAAwB,CAAC,CAAC;AACnC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC;KAC3B,MAAM,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;KAC/D,MAAM,EAAE,CAAC;AAGZ,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,+BAA+B,CAAC,CAAC;IACzE,CAAC;IACD,IACE,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC;QAC3C,GAAG,CAAC,QAAQ;QACZ,GAAG,CAAC,QAAQ;QACZ,GAAG,CAAC,MAAM;QACV,GAAG,CAAC,IAAI,EACR,CAAC;QACD,MAAM,IAAI,aAAa,CACrB,YAAY,EACZ,mEAAmE,CACpE,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7F,MAAM,IAAI,aAAa,CAAC,YAAY,EAAE,wCAAwC,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC"}

package/dist/transport.d.ts

@@ -0,0 +1,16 @@
+import { type Session } from './session.js';
+import { type Envelope } from './schemas.js';
+export interface ClientOptions {
+    url: string;
+    session: Session;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+export declare class PlankaTransport {
+    readonly url: string;
+    private readonly session;
+    private readonly fetcher;
+    private readonly timeoutMs;
+    constructor(options: ClientOptions);
+    request(path: string, method?: string, body?: unknown): Promise<Envelope>;
+}

package/dist/transport.js

@@ -0,0 +1,67 @@
+import { PlanktonError } from './errors.js';
+import { normalizeUrl, sessionSchema } from './session.js';
+import { envelopeSchema } from './schemas.js';
+export class PlankaTransport {
+    url;
+    session;
+    fetcher;
+    timeoutMs;
+    constructor(options) {
+        this.url = normalizeUrl(options.url);
+        this.session = sessionSchema.parse(options.session);
+        this.fetcher = options.fetch ?? fetch;
+        this.timeoutMs = options.timeoutMs ?? 15000;
+    }
+    async request(path, method = 'GET', body) {
+        const write = method !== 'GET';
+        try {
+            const response = await this.fetcher(`${this.url}/api/${path}`, {
+                method,
+                redirect: 'error',
+                signal: AbortSignal.timeout(this.timeoutMs),
+                headers: {
+                    Accept: 'application/json',
+                    Authorization: `Bearer ${this.session.accessToken}`,
+                    ...(this.session.httpOnlyToken
+                        ? { Cookie: `httpOnlyToken=${this.session.httpOnlyToken}` }
+                        : {}),
+                    ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            });
+            if (response.status === 401) {
+                throw new PlanktonError('AUTHENTICATION', 'Planka session expired or invalid. Run plankton login.');
+            }
+            if (response.status === 403) {
+                throw new PlanktonError('PERMISSION', 'Planka denied this operation. Check the account’s board permissions.');
+            }
+            if (response.status === 404) {
+                throw new PlanktonError('NOT_FOUND', 'Resource not found or not accessible to this account.');
+            }
+            if ([400, 422].includes(response.status)) {
+                throw new PlanktonError('VALIDATION', 'Planka rejected the fields. Check the resource type and values.');
+            }
+            if (!response.ok) {
+                throw new PlanktonError(write && response.status >= 500 ? 'UNCERTAIN_WRITE' : 'API', write && response.status >= 500
+                    ? 'Planka failed during a write. Read the resource before trying again; the change may have completed.'
+                    : `Planka returned HTTP ${response.status}.`, { status: response.status });
+            }
+            const parsed = envelopeSchema.safeParse(await response.json());
+            if (!parsed.success ||
+                (write && !parsed.data.item) ||
+                (path === 'projects' && !parsed.data.items)) {
+                throw new Error('Invalid response');
+            }
+            return parsed.data;
+        }
+        catch (error) {
+            if (error instanceof PlanktonError) {
+                throw error;
+            }
+            throw new PlanktonError(write ? 'UNCERTAIN_WRITE' : 'NETWORK', write
+                ? 'The write outcome is unknown. Read the resource before retrying; do not repeat the write blindly.'
+                : 'Could not read Planka. Check the URL, network and server response.');
+        }
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "author": "Evan Kim",
+  "name": "@evanston/plankton-core",
+  "version": "0.1.0",
+  "description": "Local Planka integration core",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}