@omnicoreos/planka-mcp 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,96 @@
+export interface ClientConfig {
+    baseUrl: string;
+    email: string;
+    password: string;
+}
+export interface RequestOptions {
+    token?: string;
+    body?: unknown;
+    /**
+     * Multipart body (attachment uploads). Content-Type is left unset on
+     * purpose: fetch generates it together with the boundary.
+     */
+    form?: FormData;
+    /**
+     * Also send the token as an `accessToken` cookie. Planka 2.0 serves
+     * attachment downloads with either, and different deployments disagree on
+     * which one they honour.
+     */
+    cookieToken?: boolean;
+    signal?: AbortSignal;
+}
+export declare function createRequestInit(method: string, options?: RequestOptions): RequestInit;
+/**
+ * Validates and returns the configuration from environment variables.
+ */
+export declare function getConfig(env?: NodeJS.ProcessEnv): ClientConfig;
+/**
+ * PLANKA API client with automatic JWT token management.
+ */
+export declare class PlankaClient {
+    private readonly env;
+    private readonly fetchImpl;
+    private config;
+    private token;
+    private tokenExpiresAt;
+    constructor(env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch);
+    /**
+     * Gets or initializes the configuration.
+     */
+    private getConfig;
+    /** Request timeout in milliseconds */
+    private static readonly REQUEST_TIMEOUT_MS;
+    /**
+     * Creates an AbortSignal with timeout.
+     * Uses AbortSignal.timeout() which automatically cleans up when the request completes.
+     */
+    private createTimeoutSignal;
+    /**
+     * Authenticates and retrieves a new JWT token.
+     */
+    private authenticate;
+    /**
+     * Gets a valid token, refreshing if necessary.
+     */
+    private getToken;
+    /**
+     * Safely parses JSON from a response, returning null on failure.
+     */
+    private safeParseJson;
+    /**
+     * Makes an authenticated request to the PLANKA API.
+     * @param isRetry - Internal flag to prevent infinite retry loops on 401
+     */
+    private request;
+    /**
+     * POST multipart/form-data (attachment uploads).
+     * @param isRetry - Internal flag to prevent infinite retry loops on 401
+     */
+    postMultipart<T>(path: string, form: FormData, isRetry?: boolean): Promise<T>;
+    /**
+     * Authenticated binary download (attachment contents).
+     * Accepts an absolute URL on the same host, or a relative path.
+     */
+    getBinary(urlOrPath: string): Promise<{
+        bytes: Uint8Array;
+        mimeType: string | null;
+    }>;
+    /**
+     * GET request.
+     */
+    get<T>(path: string): Promise<T>;
+    /**
+     * POST request.
+     */
+    post<T>(path: string, body: unknown): Promise<T>;
+    /**
+     * PATCH request.
+     */
+    patch<T>(path: string, body: unknown): Promise<T>;
+    /**
+     * DELETE request.
+     */
+    delete(path: string): Promise<void>;
+}
+export declare const plankaClient: PlankaClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,cAAmB,GAC3B,WAAW,CAkBb;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,YAAY,CA6Bd;AAED;;GAEG;AACH,qBAAa,YAAY;IAMrB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAN5B,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,cAAc,CAAa;gBAGhB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,SAAS,GAAE,OAAO,KAAa;IAGlD;;OAEG;IACH,OAAO,CAAC,SAAS;IAOjB,sCAAsC;IACtC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAEnD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;YACW,YAAY;IA+D1B;;OAEG;YACW,QAAQ;IAOtB;;OAEG;YACW,aAAa;IAQ3B;;;OAGG;YACW,OAAO;IA+CrB;;;OAGG;IACG,aAAa,CAAC,CAAC,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,EACd,OAAO,UAAQ,GACd,OAAO,CAAC,CAAC,CAAC;IAoCb;;;OAGG;IACG,SAAS,CACb,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAmC1D;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAItC;;OAEG;IACG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAItD;;OAEG;IACG,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIvD;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C;AAGD,eAAO,MAAM,YAAY,cAAqB,CAAC"}

package/dist/client.js

@@ -0,0 +1,281 @@
+/**
+ * HTTP client for PLANKA API with automatic authentication.
+ */
+import { PlankaAuthError, PlankaConfigError, PlankaNetworkError, createPlankaError, } from "./errors.js";
+import { AuthResponse } from "./schemas/responses.js";
+export function createRequestInit(method, options = {}) {
+    const headers = {};
+    if (options.token)
+        headers.Authorization = `Bearer ${options.token}`;
+    if (options.token && options.cookieToken) {
+        headers.Cookie = `accessToken=${options.token}`;
+    }
+    if (options.form === undefined && options.body !== undefined) {
+        headers["Content-Type"] = "application/json";
+    }
+    return {
+        method,
+        headers,
+        body: options.form ??
+            (options.body !== undefined ? JSON.stringify(options.body) : undefined),
+        signal: options.signal,
+    };
+}
+/**
+ * Validates and returns the configuration from environment variables.
+ */
+export function getConfig(env = process.env) {
+    const baseUrl = env.PLANKA_BASE_URL;
+    const email = env.PLANKA_AGENT_EMAIL;
+    const password = env.PLANKA_AGENT_PASSWORD;
+    const missing = [];
+    if (!baseUrl)
+        missing.push("PLANKA_BASE_URL");
+    if (!email)
+        missing.push("PLANKA_AGENT_EMAIL");
+    if (!password)
+        missing.push("PLANKA_AGENT_PASSWORD");
+    if (missing.length > 0) {
+        throw new PlankaConfigError(`Missing required environment variables: ${missing.join(", ")}`);
+    }
+    // Validate URL format
+    try {
+        new URL(baseUrl);
+    }
+    catch {
+        throw new PlankaConfigError(`Invalid PLANKA_BASE_URL: ${baseUrl}`);
+    }
+    // TypeScript narrowing: after the check above, these are guaranteed to be defined
+    return {
+        baseUrl: baseUrl.replace(/\/+$/, ""), // Remove trailing slashes
+        email: email,
+        password: password,
+    };
+}
+/**
+ * PLANKA API client with automatic JWT token management.
+ */
+export class PlankaClient {
+    env;
+    fetchImpl;
+    config = null;
+    token = null;
+    tokenExpiresAt = 0;
+    constructor(env = process.env, fetchImpl = fetch) {
+        this.env = env;
+        this.fetchImpl = fetchImpl;
+    }
+    /**
+     * Gets or initializes the configuration.
+     */
+    getConfig() {
+        if (!this.config) {
+            this.config = getConfig(this.env);
+        }
+        return this.config;
+    }
+    /** Request timeout in milliseconds */
+    static REQUEST_TIMEOUT_MS = 30000;
+    /**
+     * Creates an AbortSignal with timeout.
+     * Uses AbortSignal.timeout() which automatically cleans up when the request completes.
+     */
+    createTimeoutSignal() {
+        return AbortSignal.timeout(PlankaClient.REQUEST_TIMEOUT_MS);
+    }
+    /**
+     * Authenticates and retrieves a new JWT token.
+     */
+    async authenticate() {
+        const config = this.getConfig();
+        const url = `${config.baseUrl}/api/access-tokens`;
+        let response;
+        try {
+            response = await this.fetchImpl(url, createRequestInit("POST", {
+                body: {
+                    emailOrUsername: config.email,
+                    password: config.password,
+                },
+                signal: this.createTimeoutSignal(),
+            }));
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new PlankaNetworkError(`Request timeout connecting to PLANKA at ${config.baseUrl}`, error);
+            }
+            throw new PlankaNetworkError(`Failed to connect to PLANKA at ${config.baseUrl}`, error);
+        }
+        if (!response.ok) {
+            await this.safeParseJson(response);
+            throw new PlankaAuthError(`Authentication failed: ${response.status} ${response.statusText}`);
+        }
+        const data = await this.safeParseJson(response);
+        if (data === null) {
+            const redirectHint = config.baseUrl.startsWith("http://") || response.redirected
+                ? " Your HTTP URL probably redirects to HTTPS; a 301/302 can drop the POST body. Configure the final https:// URL directly."
+                : " Check that PLANKA_BASE_URL points to the Planka API origin, not a proxy error page.";
+            throw new PlankaAuthError(`Authentication returned HTML or another non-JSON response.${redirectHint}`);
+        }
+        const parsed = AuthResponse.safeParse(data);
+        if (!parsed.success) {
+            throw new PlankaAuthError("Authentication returned JSON, but not a Planka access token response.");
+        }
+        // PLANKA tokens are valid for 30 minutes by default.
+        // We refresh after 25 minutes to avoid edge cases.
+        // If PLANKA's token lifetime changes, adjust this value.
+        this.tokenExpiresAt = Date.now() + 25 * 60 * 1000;
+        this.token = parsed.data.item;
+        return parsed.data.item;
+    }
+    /**
+     * Gets a valid token, refreshing if necessary.
+     */
+    async getToken() {
+        if (!this.token || Date.now() >= this.tokenExpiresAt) {
+            return this.authenticate();
+        }
+        return this.token;
+    }
+    /**
+     * Safely parses JSON from a response, returning null on failure.
+     */
+    async safeParseJson(response) {
+        try {
+            return await response.json();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Makes an authenticated request to the PLANKA API.
+     * @param isRetry - Internal flag to prevent infinite retry loops on 401
+     */
+    async request(method, path, body, isRetry = false) {
+        const config = this.getConfig();
+        const token = await this.getToken();
+        const url = `${config.baseUrl}${path}`;
+        let response;
+        try {
+            response = await this.fetchImpl(url, createRequestInit(method, {
+                token,
+                body,
+                signal: this.createTimeoutSignal(),
+            }));
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new PlankaNetworkError(`Request timeout: ${method} ${path}`, error);
+            }
+            throw new PlankaNetworkError(`Network error: ${method} ${path}`, error);
+        }
+        // Handle 204 No Content
+        if (response.status === 204) {
+            return undefined;
+        }
+        const data = await this.safeParseJson(response);
+        if (!response.ok) {
+            // If token expired and this is not already a retry, get fresh token and retry once
+            if (response.status === 401 && this.token && !isRetry) {
+                this.token = null;
+                this.tokenExpiresAt = 0;
+                return this.request(method, path, body, true);
+            }
+            throw createPlankaError(response.status, data, `${method} ${path}`);
+        }
+        return data;
+    }
+    /**
+     * POST multipart/form-data (attachment uploads).
+     * @param isRetry - Internal flag to prevent infinite retry loops on 401
+     */
+    async postMultipart(path, form, isRetry = false) {
+        const config = this.getConfig();
+        const token = await this.getToken();
+        const url = `${config.baseUrl}${path}`;
+        let response;
+        try {
+            response = await this.fetchImpl(url, createRequestInit("POST", {
+                token,
+                form,
+                signal: this.createTimeoutSignal(),
+            }));
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new PlankaNetworkError(`Request timeout: POST ${path}`, error);
+            }
+            throw new PlankaNetworkError(`Network error: POST ${path}`, error);
+        }
+        const data = await this.safeParseJson(response);
+        if (!response.ok) {
+            if (response.status === 401 && this.token && !isRetry) {
+                this.token = null;
+                this.tokenExpiresAt = 0;
+                return this.postMultipart(path, form, true);
+            }
+            throw createPlankaError(response.status, data, `POST ${path}`);
+        }
+        return data;
+    }
+    /**
+     * Authenticated binary download (attachment contents).
+     * Accepts an absolute URL on the same host, or a relative path.
+     */
+    async getBinary(urlOrPath) {
+        const config = this.getConfig();
+        const token = await this.getToken();
+        const url = urlOrPath.startsWith("http")
+            ? urlOrPath
+            : `${config.baseUrl}${urlOrPath}`;
+        let response;
+        try {
+            response = await this.fetchImpl(url, createRequestInit("GET", {
+                token,
+                cookieToken: true,
+                signal: this.createTimeoutSignal(),
+            }));
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new PlankaNetworkError(`Request timeout: GET ${url}`, error);
+            }
+            throw new PlankaNetworkError(`Network error: GET ${url}`, error);
+        }
+        if (!response.ok) {
+            throw createPlankaError(response.status, null, `GET ${url}`);
+        }
+        const buffer = await response.arrayBuffer();
+        return {
+            bytes: new Uint8Array(buffer),
+            mimeType: response.headers.get("content-type"),
+        };
+    }
+    /**
+     * GET request.
+     */
+    async get(path) {
+        return this.request("GET", path);
+    }
+    /**
+     * POST request.
+     */
+    async post(path, body) {
+        return this.request("POST", path, body);
+    }
+    /**
+     * PATCH request.
+     */
+    async patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+    /**
+     * DELETE request.
+     */
+    async delete(path) {
+        return this.request("DELETE", path);
+    }
+}
+// Singleton client instance
+export const plankaClient = new PlankaClient();
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Typed error classes for PLANKA API operations.
+ */
+import { z } from "zod";
+export declare class PlankaError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: string, status: number, details?: unknown | undefined);
+}
+export declare class PlankaAuthError extends PlankaError {
+    constructor(message?: string);
+}
+export declare class PlankaNotFoundError extends PlankaError {
+    constructor(resource: string, id: string);
+}
+export declare class PlankaValidationError extends PlankaError {
+    constructor(message: string, details?: unknown);
+}
+export declare class PlankaPermissionError extends PlankaError {
+    constructor(message?: string);
+}
+export declare class PlankaConfigError extends PlankaError {
+    constructor(message: string);
+}
+export declare class PlankaNetworkError extends PlankaError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Factory function to create typed errors from API responses.
+ * @param status HTTP status code
+ * @param body Response body (parsed JSON or null)
+ * @param context Optional context (e.g., "GET /api/cards/123")
+ */
+export declare function createPlankaError(status: number, body: unknown, context?: string): PlankaError;
+/**
+ * Type guard for PlankaError instances.
+ */
+export declare function isPlankaError(error: unknown): error is PlankaError;
+/**
+ * An operation's INPUT failed validation.
+ *
+ * Deliberately NOT a subclass of PlankaError: every tool catches PlankaError
+ * to report Planka API failures, and this error has to travel untouched to the
+ * dispatcher in `src/index.ts` — the only place that knows the tool name and
+ * its inputSchema, and therefore the only place that can build the actionable
+ * message.
+ */
+export declare class PlankaInputError extends Error {
+    readonly issues: z.ZodIssue[];
+    readonly received: unknown;
+    constructor(issues: z.ZodIssue[], received: unknown);
+}
+/**
+ * Validates an operation's input against its schema.
+ * Replaces `Schema.parse(input)`: instead of a bare ZodError it throws a
+ * PlankaInputError that keeps what was received, so it can be shown back.
+ */
+export declare function parseInput<S extends z.ZodTypeAny>(schema: S, input: unknown): z.output<S>;
+/** Type guard for Zod validation errors (response-shape failures). */
+export declare function isZodError(error: unknown): error is z.ZodError;
+/**
+ * The validation message the model sees: which tool failed, which field, what
+ * was expected and what arrived.
+ */
+export declare function formatInputError(toolName: string, error: PlankaInputError, schema?: {
+    properties?: Record<string, unknown>;
+    required?: string[];
+}): string;
+/**
+ * Required fields that never arrived, detected before entering the handler.
+ * Without this a missing `tasks` dies as "Cannot read properties of undefined
+ * (reading 'map')", which names neither the tool nor the field.
+ */
+export declare function formatMissingArgsError(toolName: string, missing: string[], args: unknown, schema?: {
+    properties?: Record<string, unknown>;
+    required?: string[];
+}): string;
+/**
+ * A ZodError that did NOT come from the input: Planka's response did not match
+ * the schema. Saying so explicitly keeps the model from assuming it got the
+ * arguments wrong.
+ */
+export declare function formatResponseShapeError(toolName: string, error: z.ZodError): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,qBAAa,WAAY,SAAQ,KAAK;aAGlB,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;aACd,OAAO,CAAC,EAAE,OAAO;gBAHjC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,OAAO,YAAA;CAKpC;AAED,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,SAA0B;CAI9C;AAED,qBAAa,mBAAoB,SAAQ,WAAW;gBACtC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM;CAIzC;AAED,qBAAa,qBAAsB,SAAQ,WAAW;gBACxC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C;AAED,qBAAa,qBAAsB,SAAQ,WAAW;gBACxC,OAAO,SAA6B;CAIjD;AAED,qBAAa,iBAAkB,SAAQ,WAAW;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAI/C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,MAAM,GACf,WAAW,CAoBb;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAMD;;;;;;;;GAQG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;aAEvB,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;aACpB,QAAQ,EAAE,OAAO;gBADjB,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,EACpB,QAAQ,EAAE,OAAO;CASpC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAC/C,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,OAAO,GACb,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAMb;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,CAAC,CAAC,QAAQ,CAE9D;AAwDD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,gBAAgB,EACvB,MAAM,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACrE,MAAM,CAuBR;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACrE,MAAM,CAaR;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,CAAC,CAAC,QAAQ,GAChB,MAAM,CAYR"}