@ouija-dev/plugin-plane 0.1.0

package/dist/agent-user.d.ts

@@ -0,0 +1,19 @@
+import type { PlaneApiClient } from './api-client.js';
+import type { PluginLogger } from '@ouija-dev/types';
+export interface AgentUserRecord {
+    memberId: string;
+    email: string;
+    displayName: string;
+}
+/**
+ * Ensure an agent bot user exists in the given Plane workspace.
+ *
+ * - If the email is already a member: no-op (returns existing record).
+ * - If not: sends a workspace invitation.
+ *
+ * This is best-effort. If the invitation fails (e.g. Plane is in SSO-only
+ * mode or email is blocked) we log a warning but do NOT prevent the plugin
+ * from starting. The bot can still move cards; assignment will fail gracefully.
+ */
+export declare function ensureAgentUser(client: PlaneApiClient, workspaceSlug: string, agentEmail: string, logger: PluginLogger): Promise<AgentUserRecord | null>;
+//# sourceMappingURL=agent-user.d.ts.map

package/dist/agent-user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-user.d.ts","sourceRoot":"","sources":["../src/agent-user.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAuBjC"}

package/dist/agent-user.js

@@ -0,0 +1,41 @@
+// ---- Agent user registration and management on Plane ----
+// Agents need to be real Plane users so they can be assigned to issues,
+// appear in the board UI, and post comments attributed to their identity.
+//
+// This module handles creating / verifying agent bot users during plugin start.
+/**
+ * Ensure an agent bot user exists in the given Plane workspace.
+ *
+ * - If the email is already a member: no-op (returns existing record).
+ * - If not: sends a workspace invitation.
+ *
+ * This is best-effort. If the invitation fails (e.g. Plane is in SSO-only
+ * mode or email is blocked) we log a warning but do NOT prevent the plugin
+ * from starting. The bot can still move cards; assignment will fail gracefully.
+ */
+export async function ensureAgentUser(client, workspaceSlug, agentEmail, logger) {
+    try {
+        const result = await client.createMember(workspaceSlug, agentEmail, 10);
+        logger.info('Agent user provisioned on Plane', {
+            workspaceSlug,
+            email: agentEmail,
+            memberId: result.id,
+        });
+        return {
+            memberId: result.id,
+            email: result.email,
+            displayName: agentEmail,
+        };
+    }
+    catch (err) {
+        // A 400 often means "already a member" — treat as success by logging a warning.
+        // Callers should not block startup on this.
+        logger.warn('Could not provision agent user on Plane (non-fatal)', {
+            workspaceSlug,
+            email: agentEmail,
+            error: String(err),
+        });
+        return null;
+    }
+}
+//# sourceMappingURL=agent-user.js.map

package/dist/agent-user.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-user.js","sourceRoot":"","sources":["../src/agent-user.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,wEAAwE;AACxE,0EAA0E;AAC1E,EAAE;AACF,gFAAgF;AAWhF;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAsB,EACtB,aAAqB,EACrB,UAAkB,EAClB,MAAoB;IAEpB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,aAAa,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC;QACxE,MAAM,CAAC,IAAI,CAAC,iCAAiC,EAAE;YAC7C,aAAa;YACb,KAAK,EAAE,UAAU;YACjB,QAAQ,EAAE,MAAM,CAAC,EAAE;SACpB,CAAC,CAAC;QACH,OAAO;YACL,QAAQ,EAAE,MAAM,CAAC,EAAE;YACnB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,WAAW,EAAE,UAAU;SACxB,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,gFAAgF;QAChF,4CAA4C;QAC5C,MAAM,CAAC,IAAI,CAAC,qDAAqD,EAAE;YACjE,aAAa;YACb,KAAK,EAAE,UAAU;YACjB,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC;SACnB,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/api-client.d.ts

@@ -0,0 +1,104 @@
+export interface PlaneIssue {
+    id: string;
+    name: string;
+    description_html: string;
+    state: string;
+    project: string;
+    workspace: string;
+    label_details: Array<{
+        id: string;
+        name: string;
+    }>;
+    assignee_details: Array<{
+        id: string;
+        email: string;
+        display_name: string;
+    }>;
+    created_at: string;
+    updated_at: string;
+}
+export interface PlaneState {
+    id: string;
+    name: string;
+    color: string;
+    group: 'backlog' | 'unstarted' | 'started' | 'completed' | 'cancelled';
+    sequence: number;
+}
+export interface PlaneMember {
+    id: string;
+    email: string;
+    display_name: string;
+    role: number;
+}
+export interface PlaneComment {
+    id: string;
+    comment_html: string;
+    actor: string;
+    created_at: string;
+}
+export declare class PlaneRateLimitError extends Error {
+    readonly retryAfter: number;
+    constructor(retryAfter: number);
+}
+export declare class PlaneApiError extends Error {
+    readonly statusCode: number;
+    readonly body: string;
+    constructor(statusCode: number, body: string, path: string);
+}
+export declare class PlaneApiClient {
+    private readonly baseUrl;
+    private readonly apiToken;
+    constructor(baseUrl: string, apiToken: string);
+    private request;
+    private get;
+    private patch;
+    private post;
+    /**
+     * Fetch a single issue by ID.
+     * GET /api/v1/workspaces/:workspaceSlug/projects/:projectId/issues/:issueId/
+     */
+    getIssue(workspaceSlug: string, projectId: string, issueId: string): Promise<PlaneIssue>;
+    /**
+     * Update issue fields (e.g. state for column moves).
+     * PATCH /api/v1/workspaces/:workspaceSlug/projects/:projectId/issues/:issueId/
+     */
+    updateIssue(workspaceSlug: string, projectId: string, issueId: string, data: Partial<Pick<PlaneIssue, 'state'>> & Record<string, unknown>): Promise<PlaneIssue>;
+    /**
+     * Add a comment to an issue.
+     * POST /api/v1/workspaces/:workspaceSlug/projects/:projectId/issues/:issueId/comments/
+     */
+    addComment(workspaceSlug: string, projectId: string, issueId: string, body: string): Promise<PlaneComment>;
+    /**
+     * Fetch all states (columns) for a project.
+     * GET /api/v1/workspaces/:workspaceSlug/projects/:projectId/states/
+     */
+    getStates(workspaceSlug: string, projectId: string): Promise<PlaneState[]>;
+    /**
+     * List all members of a workspace.
+     * GET /api/v1/workspaces/:workspaceSlug/members/
+     */
+    getMembers(workspaceSlug: string): Promise<PlaneMember[]>;
+    /**
+     * Invite a member (e.g. agent bot user) to the workspace.
+     * POST /api/v1/workspaces/:workspaceSlug/invitations/
+     *
+     * Role codes: 5=Guest, 10=Member, 15=Viewer, 20=Admin
+     */
+    createMember(workspaceSlug: string, email: string, role?: 5 | 10 | 15 | 20): Promise<{
+        id: string;
+        email: string;
+        role: number;
+    }>;
+    /**
+     * Assign a member to an issue.
+     * Plane uses assignees as an array of member IDs on the issue resource.
+     * We fetch the current assignees and PATCH with the new list.
+     */
+    assignMember(workspaceSlug: string, projectId: string, issueId: string, memberId: string): Promise<PlaneIssue>;
+    /**
+     * Lightweight connectivity check: fetch workspace details.
+     * GET /api/v1/workspaces/:workspaceSlug/
+     */
+    ping(_workspaceSlug: string): Promise<void>;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

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

package/dist/api-client.js

@@ -0,0 +1,149 @@
+// ---- Plane REST API v1 client ----
+// All requests use the X-Api-Key header for authentication.
+// Base URL: https://<plane-host>/api/v1
+// ---- Rate limit error ----
+export class PlaneRateLimitError extends Error {
+    retryAfter;
+    constructor(retryAfter) {
+        super(`Plane API rate limit exceeded. Retry after ${retryAfter}s`);
+        this.name = 'PlaneRateLimitError';
+        this.retryAfter = retryAfter;
+    }
+}
+// ---- API error ----
+export class PlaneApiError extends Error {
+    statusCode;
+    body;
+    constructor(statusCode, body, path) {
+        super(`Plane API error ${statusCode} on ${path}: ${body}`);
+        this.name = 'PlaneApiError';
+        this.statusCode = statusCode;
+        this.body = body;
+    }
+}
+// ---- Client ----
+export class PlaneApiClient {
+    baseUrl;
+    apiToken;
+    constructor(baseUrl, apiToken) {
+        // Normalise: strip trailing slash so path construction is consistent.
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.apiToken = apiToken;
+    }
+    // ---- Private helpers ----
+    async request(method, path, body) {
+        const url = `${this.baseUrl}/api/v1${path}`;
+        const headers = {
+            'X-Api-Key': this.apiToken,
+            'Content-Type': 'application/json',
+        };
+        const init = {
+            method,
+            headers,
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        };
+        const response = await fetch(url, init);
+        // Rate limit: surface the retry-after header.
+        if (response.status === 429) {
+            const retryAfter = Number(response.headers.get('Retry-After') ?? '60');
+            throw new PlaneRateLimitError(retryAfter);
+        }
+        const text = await response.text();
+        if (!response.ok) {
+            throw new PlaneApiError(response.status, text, path);
+        }
+        // 204 No Content — return empty object cast to T.
+        if (response.status === 204 || text.trim() === '') {
+            return {};
+        }
+        return JSON.parse(text);
+    }
+    get(path) {
+        return this.request('GET', path);
+    }
+    patch(path, body) {
+        return this.request('PATCH', path, body);
+    }
+    post(path, body) {
+        return this.request('POST', path, body);
+    }
+    // ---- Issue operations ----
+    /**
+     * Fetch a single issue by ID.
+     * GET /api/v1/workspaces/:workspaceSlug/projects/:projectId/issues/:issueId/
+     */
+    async getIssue(workspaceSlug, projectId, issueId) {
+        return this.get(`/workspaces/${workspaceSlug}/projects/${projectId}/issues/${issueId}/`);
+    }
+    /**
+     * Update issue fields (e.g. state for column moves).
+     * PATCH /api/v1/workspaces/:workspaceSlug/projects/:projectId/issues/:issueId/
+     */
+    async updateIssue(workspaceSlug, projectId, issueId, data) {
+        return this.patch(`/workspaces/${workspaceSlug}/projects/${projectId}/issues/${issueId}/`, data);
+    }
+    /**
+     * Add a comment to an issue.
+     * POST /api/v1/workspaces/:workspaceSlug/projects/:projectId/issues/:issueId/comments/
+     */
+    async addComment(workspaceSlug, projectId, issueId, body) {
+        return this.post(`/workspaces/${workspaceSlug}/projects/${projectId}/issues/${issueId}/comments/`, { comment_html: body });
+    }
+    /**
+     * Fetch all states (columns) for a project.
+     * GET /api/v1/workspaces/:workspaceSlug/projects/:projectId/states/
+     */
+    async getStates(workspaceSlug, projectId) {
+        const response = await this.get(`/workspaces/${workspaceSlug}/projects/${projectId}/states/`);
+        // Plane may return a paginated envelope or a plain array depending on version.
+        if (Array.isArray(response)) {
+            return response;
+        }
+        return response.results;
+    }
+    /**
+     * List all members of a workspace.
+     * GET /api/v1/workspaces/:workspaceSlug/members/
+     */
+    async getMembers(workspaceSlug) {
+        const response = await this.get(`/workspaces/${workspaceSlug}/members/`);
+        if (Array.isArray(response)) {
+            return response;
+        }
+        return response.results;
+    }
+    /**
+     * Invite a member (e.g. agent bot user) to the workspace.
+     * POST /api/v1/workspaces/:workspaceSlug/invitations/
+     *
+     * Role codes: 5=Guest, 10=Member, 15=Viewer, 20=Admin
+     */
+    async createMember(workspaceSlug, email, role = 10) {
+        return this.post(`/workspaces/${workspaceSlug}/invitations/`, { email, role });
+    }
+    /**
+     * Assign a member to an issue.
+     * Plane uses assignees as an array of member IDs on the issue resource.
+     * We fetch the current assignees and PATCH with the new list.
+     */
+    async assignMember(workspaceSlug, projectId, issueId, memberId) {
+        // Fetch current issue to get existing assignees.
+        const issue = await this.getIssue(workspaceSlug, projectId, issueId);
+        const existing = issue.assignee_details.map((a) => a.id);
+        if (existing.includes(memberId)) {
+            // Already assigned — no-op.
+            return issue;
+        }
+        return this.patch(`/workspaces/${workspaceSlug}/projects/${projectId}/issues/${issueId}/`, { assignees: [...existing, memberId] });
+    }
+    /**
+     * Lightweight connectivity check: fetch workspace details.
+     * GET /api/v1/workspaces/:workspaceSlug/
+     */
+    async ping(_workspaceSlug) {
+        // /users/me/ is the lightest authenticated endpoint.
+        // /workspaces/:slug/ requires session auth on some Plane versions.
+        await this.get(`/users/me/`);
+    }
+}
+//# sourceMappingURL=api-client.js.map

package/dist/api-client.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+export declare const planeConfigSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly baseUrl: {
+            readonly type: "string";
+            readonly format: "uri";
+        };
+        readonly apiToken: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly workspaceSlug: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly webhookSecret: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+    };
+    readonly required: readonly ["baseUrl", "apiToken", "workspaceSlug", "webhookSecret"];
+    readonly additionalProperties: false;
+};
+export interface PlaneConfig {
+    baseUrl: string;
+    apiToken: string;
+    workspaceSlug: string;
+    webhookSecret: string;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;CAUpB,CAAC;AAIX,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/dist/config.js

@@ -0,0 +1,15 @@
+// ---- Plane plugin configuration schema ----
+// Defined as a const object so TypeScript preserves literal types.
+// Use with Ajv for runtime validation via @ouija-dev/plugin-sdk.
+export const planeConfigSchema = {
+    type: 'object',
+    properties: {
+        baseUrl: { type: 'string', format: 'uri' },
+        apiToken: { type: 'string', minLength: 1 },
+        workspaceSlug: { type: 'string', minLength: 1 },
+        webhookSecret: { type: 'string', minLength: 1 },
+    },
+    required: ['baseUrl', 'apiToken', 'workspaceSlug', 'webhookSecret'],
+    additionalProperties: false,
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,mEAAmE;AACnE,iEAAiE;AAEjE,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE;QAC1C,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;QAC1C,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;QAC/C,aAAa,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE;KAChD;IACD,QAAQ,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,eAAe,CAAC;IACnE,oBAAoB,EAAE,KAAK;CACnB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import type { FastifyInstance } from 'fastify';
+import type { KanbanPlugin, KanbanCard, KanbanColumn, PluginManifest, PluginContext, PluginHealth } from '@ouija-dev/types';
+import type { CardId, ColumnId, BoardId } from '@ouija-dev/types';
+import type { PlaneConfig } from './config.js';
+import type { PluginFactory } from '@ouija-dev/plugin-sdk';
+export declare class PlanePlugin implements KanbanPlugin<PlaneConfig> {
+    readonly manifest: PluginManifest;
+    private config;
+    private client;
+    private context;
+    init(context: PluginContext<PlaneConfig>): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    healthCheck(): Promise<PluginHealth>;
+    /**
+     * Register the Plane webhook ingress route on the Fastify server.
+     *
+     * Route: POST /hooks/plane/:secret
+     *
+     * Security (per spec §5.5):
+     *   1. Path secret — cheap first-pass filter
+     *   2. HMAC-SHA256 signature (X-Plane-Signature header)
+     *   3. Timestamp freshness — reject events older than 5 minutes
+     *
+     * Always responds 200 (even on auth failure) to prevent path enumeration.
+     */
+    registerRoutes(server: FastifyInstance): Promise<void>;
+    /**
+     * Fetch a single card (Plane issue) by its ID.
+     *
+     * The cardId must be in the form "<projectId>/<issueId>" so the plugin
+     * knows which project the issue belongs to, or a plain issue UUID when
+     * the default project from the plugin's workspace context is used.
+     *
+     * Convention adopted: cardId format is "<projectId>/<issueId>".
+     * This avoids storing project context separately and keeps card IDs
+     * self-contained.
+     */
+    getCard(id: CardId): Promise<KanbanCard>;
+    /**
+     * Move a card to a different column by updating the issue's state.
+     */
+    moveCard(id: CardId, toColumnId: ColumnId): Promise<void>;
+    /**
+     * Add a comment to a card (Plane issue).
+     */
+    addComment(id: CardId, body: string): Promise<void>;
+    /**
+     * Assign a user (member ID) to a card.
+     */
+    assignUser(id: CardId, userId: string): Promise<void>;
+    /** Expose getMembers for agent registry provisioning. */
+    getMembers(workspaceSlug?: string): Promise<import('./api-client.js').PlaneMember[]>;
+    /** Expose inviteMember for agent registry provisioning. */
+    inviteMember(workspaceSlug: string | undefined, email: string, role?: 5 | 10 | 15 | 20): Promise<{
+        id: string;
+        email: string;
+        role: number;
+    }>;
+    /**
+     * Return all columns (states) for a given board (project).
+     * The boardId is the Plane project UUID.
+     */
+    getColumns(board: BoardId): Promise<KanbanColumn[]>;
+}
+declare const planePluginFactory: PluginFactory<PlaneConfig>;
+export default planePluginFactory;
+export { planePluginFactory as PluginFactory };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AAC7E,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,YAAY,EACb,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAGlE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAmB3D,qBAAa,WAAY,YAAW,YAAY,CAAC,WAAW,CAAC;IAC3D,QAAQ,CAAC,QAAQ,iBAAY;IAE7B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,OAAO,CAA8B;IAIvC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,WAAW,IAAI,OAAO,CAAC,YAAY,CAAC;IAe1C;;;;;;;;;;;OAWG;IACG,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAyE5D;;;;;;;;;;OAUG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAoB9C;;OAEG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/D;;OAEG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOzD;;OAEG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3D,yDAAyD;IACnD,UAAU,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,iBAAiB,EAAE,WAAW,EAAE,CAAC;IAK1F,2DAA2D;IACrD,YAAY,CAChB,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAO,GAC1B,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAKvD;;;OAGG;IACG,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CAY1D;AAsCD,QAAA,MAAM,kBAAkB,EAAE,aAAa,CAAC,WAAW,CAKlD,CAAC;AAEF,eAAe,kBAAkB,CAAC;AAGlC,OAAO,EAAE,kBAAkB,IAAI,aAAa,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,244 @@
+// ---- Plane kanban plugin ----
+// Implements KanbanPlugin<PlaneConfig> against the Plane REST API v1.
+//
+// Responsibilities:
+//   - Lifecycle: init, start, stop, healthCheck
+//   - Route: POST /hooks/plane/:secret  (HMAC + path-secret verification)
+//   - KanbanPlugin: getCard, moveCard, addComment, assignUser, getColumns
+import { cardId, columnId, boardId } from '@ouija-dev/types';
+import { planeConfigSchema } from './config.js';
+import { PlaneApiClient } from './api-client.js';
+import { normalizeWebhook, verifyPlaneSignature, isWebhookFresh } from './webhook-handler.js';
+// ---- Plugin manifest (static — safe to read before init) ----
+const manifest = {
+    name: '@ouija-dev/plugin-plane',
+    version: '0.1.0',
+    type: 'kanban',
+    coreApiVersion: '>=1.0.0 <2.0.0',
+    configSchema: planeConfigSchema,
+    dependencies: [],
+    events: {
+        produces: ['kanban.card.moved', 'kanban.card.assigned'],
+        consumes: [],
+    },
+};
+// ---- PlanePlugin ----
+export class PlanePlugin {
+    manifest = manifest;
+    config;
+    client;
+    context;
+    // ---- Lifecycle ----
+    async init(context) {
+        this.context = context;
+        this.config = context.config;
+        this.client = new PlaneApiClient(this.config.baseUrl, this.config.apiToken);
+        context.logger.info('PlanePlugin initialised', {
+            baseUrl: this.config.baseUrl,
+            workspaceSlug: this.config.workspaceSlug,
+        });
+    }
+    async start() {
+        // Verify connectivity. This will throw and prevent the plugin starting
+        // if the API is unreachable, which is the correct behaviour.
+        await this.client.ping(this.config.workspaceSlug);
+        this.context.logger.info('PlanePlugin started — API connectivity verified');
+    }
+    async stop() {
+        this.context.logger.info('PlanePlugin stopped');
+    }
+    async healthCheck() {
+        try {
+            await this.client.ping(this.config.workspaceSlug);
+            return { healthy: true, message: 'Plane API reachable' };
+        }
+        catch (err) {
+            return {
+                healthy: false,
+                message: `Plane API unreachable: ${String(err)}`,
+                details: { error: String(err) },
+            };
+        }
+    }
+    // ---- Route registration ----
+    /**
+     * Register the Plane webhook ingress route on the Fastify server.
+     *
+     * Route: POST /hooks/plane/:secret
+     *
+     * Security (per spec §5.5):
+     *   1. Path secret — cheap first-pass filter
+     *   2. HMAC-SHA256 signature (X-Plane-Signature header)
+     *   3. Timestamp freshness — reject events older than 5 minutes
+     *
+     * Always responds 200 (even on auth failure) to prevent path enumeration.
+     */
+    async registerRoutes(server) {
+        const plugin = this;
+        server.post('/hooks/plane/:secret', {
+            config: {
+                // Fastify 5: disable built-in body parsing so we can read raw body for HMAC.
+                rawBody: true,
+            },
+        }, async (request, reply) => {
+            const { secret } = request.params;
+            // 1. Path secret check.
+            if (secret !== plugin.config.webhookSecret) {
+                plugin.context.logger.warn('Plane webhook: invalid path secret', {
+                    ip: request.ip,
+                });
+                // Return 200 to prevent enumeration.
+                return reply.status(200).send({ ok: false });
+            }
+            // 2. HMAC signature verification.
+            const sigHeader = request.headers['x-plane-signature'];
+            const rawBody = 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            request.rawBody ?? JSON.stringify(request.body);
+            if (!verifyPlaneSignature(plugin.config.webhookSecret, rawBody, sigHeader)) {
+                plugin.context.logger.warn('Plane webhook: invalid HMAC signature', {
+                    ip: request.ip,
+                });
+                return reply.status(200).send({ ok: false });
+            }
+            // 3. Timestamp freshness.
+            const body = request.body;
+            const timestamp = typeof body?.['timestamp'] === 'string' ? body['timestamp'] : undefined;
+            if (!isWebhookFresh(timestamp)) {
+                plugin.context.logger.warn('Plane webhook: stale timestamp', {
+                    timestamp,
+                    ip: request.ip,
+                });
+                return reply.status(200).send({ ok: false });
+            }
+            // 4. Normalize and publish.
+            const event = normalizeWebhook(body, manifest.name, plugin.config.baseUrl);
+            if (event !== null) {
+                await plugin.context.publishEvent(event.topic, event.payload);
+                plugin.context.logger.info('Plane webhook processed', {
+                    topic: event.topic,
+                    eventId: event.id,
+                });
+            }
+            else {
+                plugin.context.logger.debug('Plane webhook: no-op event (field not tracked)', {
+                    event: body?.['event'],
+                });
+            }
+            return reply.status(200).send({ ok: true });
+        });
+    }
+    // ---- KanbanPlugin methods ----
+    /**
+     * Fetch a single card (Plane issue) by its ID.
+     *
+     * The cardId must be in the form "<projectId>/<issueId>" so the plugin
+     * knows which project the issue belongs to, or a plain issue UUID when
+     * the default project from the plugin's workspace context is used.
+     *
+     * Convention adopted: cardId format is "<projectId>/<issueId>".
+     * This avoids storing project context separately and keeps card IDs
+     * self-contained.
+     */
+    async getCard(id) {
+        const { workspaceSlug } = this.config;
+        const { projectId, issueId } = splitCardId(id);
+        const issue = await this.client.getIssue(workspaceSlug, projectId, issueId);
+        return {
+            id: cardId(`${issue.project}/${issue.id}`),
+            title: issue.name,
+            description: issue.description_html,
+            columnId: columnId(typeof issue.state === 'string' ? issue.state : issue.state?.id ?? issue.state),
+            boardId: boardId(issue.project),
+            labels: (issue.label_details ?? issue['labels'] ?? []).map((l) => l.name),
+            assignees: (issue.assignee_details ?? issue['assignees'] ?? []).map((a) => a.id),
+            url: issueUrl(this.config.baseUrl, workspaceSlug, issue.project, issue.id),
+            createdAt: issue.created_at,
+            updatedAt: issue.updated_at,
+        };
+    }
+    /**
+     * Move a card to a different column by updating the issue's state.
+     */
+    async moveCard(id, toColumnId) {
+        const { workspaceSlug } = this.config;
+        const { projectId, issueId } = splitCardId(id);
+        await this.client.updateIssue(workspaceSlug, projectId, issueId, {
+            state: toColumnId,
+        });
+    }
+    /**
+     * Add a comment to a card (Plane issue).
+     */
+    async addComment(id, body) {
+        const { workspaceSlug } = this.config;
+        const { projectId, issueId } = splitCardId(id);
+        await this.client.addComment(workspaceSlug, projectId, issueId, body);
+    }
+    /**
+     * Assign a user (member ID) to a card.
+     */
+    async assignUser(id, userId) {
+        const { workspaceSlug } = this.config;
+        const { projectId, issueId } = splitCardId(id);
+        await this.client.assignMember(workspaceSlug, projectId, issueId, userId);
+    }
+    /** Expose getMembers for agent registry provisioning. */
+    async getMembers(workspaceSlug) {
+        const slug = workspaceSlug ?? this.config.workspaceSlug;
+        return this.client.getMembers(slug);
+    }
+    /** Expose inviteMember for agent registry provisioning. */
+    async inviteMember(workspaceSlug, email, role = 10) {
+        const slug = workspaceSlug ?? this.config.workspaceSlug;
+        return this.client.createMember(slug, email, role);
+    }
+    /**
+     * Return all columns (states) for a given board (project).
+     * The boardId is the Plane project UUID.
+     */
+    async getColumns(board) {
+        const { workspaceSlug } = this.config;
+        const states = await this.client.getStates(workspaceSlug, board);
+        return states
+            .sort((a, b) => a.sequence - b.sequence)
+            .map((s, index) => ({
+            id: columnId(s.id),
+            name: s.name,
+            position: index,
+        }));
+    }
+}
+// ---- Helpers ----
+/**
+ * Split a composite card ID "<projectId>/<issueId>" into its parts.
+ * Falls back to treating the whole string as the issueId if no slash present
+ * (to handle legacy or direct-issue-ID callers).
+ */
+function splitCardId(id) {
+    const raw = id;
+    const slashIdx = raw.indexOf('/');
+    if (slashIdx === -1) {
+        // Single UUID — assume it's the issue ID. Project must be inferred elsewhere.
+        // In practice, callers should always pass "<projectId>/<issueId>".
+        throw new Error(`PlanePlugin: cardId "${raw}" must be in "<projectId>/<issueId>" format`);
+    }
+    return {
+        projectId: raw.slice(0, slashIdx),
+        issueId: raw.slice(slashIdx + 1),
+    };
+}
+function issueUrl(baseUrl, workspaceSlug, projectId, issueId) {
+    return `${baseUrl.replace(/\/$/, '')}/${workspaceSlug}/projects/${projectId}/issues/${issueId}`;
+}
+// ---- PluginFactory (default export for plugin-loader) ----
+const planePluginFactory = {
+    manifest,
+    create() {
+        return new PlanePlugin();
+    },
+};
+export default planePluginFactory;
+// Named export for consumers who prefer it.
+export { planePluginFactory as PluginFactory };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/webhook-handler.d.ts

@@ -0,0 +1,68 @@
+import type { OuijaEvent, KanbanCard } from '@ouija-dev/types';
+interface PlaneWebhookIssueData {
+    id: string;
+    name: string;
+    description_html: string;
+    state: string | {
+        id: string;
+        name: string;
+        color?: string;
+        group?: string;
+    };
+    project: string;
+    workspace: string;
+    labels?: Array<{
+        id: string;
+        name: string;
+    }>;
+    assignees?: Array<{
+        id: string;
+        email?: string;
+        display_name?: string;
+    }>;
+    label_details?: Array<{
+        id: string;
+        name: string;
+    }>;
+    assignee_details?: Array<{
+        id: string;
+        email: string;
+        display_name: string;
+    }>;
+    created_at: string;
+    updated_at: string;
+}
+declare function toKanbanCard(data: PlaneWebhookIssueData, workspaceSlug: string, baseUrl: string): KanbanCard;
+export type NormalizedWebhookEvent = OuijaEvent<'kanban.card.moved'> | OuijaEvent<'kanban.card.assigned'> | null;
+/**
+ * Parse and normalize a raw Plane webhook payload.
+ *
+ * Returns:
+ *  - OuijaEvent<'kanban.card.moved'>    when field === "state"
+ *  - OuijaEvent<'kanban.card.assigned'> when field === "assignees"
+ *  - null for all other activity types or on any parse error
+ *
+ * This function never throws — all errors are swallowed and return null.
+ * Callers must not rely on thrown errors for control flow.
+ */
+export declare function normalizeWebhook(raw: unknown, sourcePlugin?: string, baseUrl?: string): NormalizedWebhookEvent;
+/**
+ * Verify the Plane webhook HMAC-SHA256 signature.
+ *
+ * Plane sends: X-Plane-Signature: sha256=<hex-digest>
+ *
+ * @param secret      The webhook secret configured in Plane
+ * @param rawBody     The raw request body bytes (Buffer or string)
+ * @param sigHeader   The value of X-Plane-Signature header
+ * @returns           true if valid, false if invalid or missing
+ */
+export declare function verifyPlaneSignature(secret: string, rawBody: Buffer | string, sigHeader: string | undefined): boolean;
+/**
+ * Reject webhooks older than maxAgeMs (default 5 minutes).
+ * Plane includes a top-level `timestamp` field in ISO 8601 format.
+ *
+ * @returns true if the timestamp is within the allowed window, false otherwise
+ */
+export declare function isWebhookFresh(timestamp: string | undefined, nowMs?: number, maxAgeMs?: number): boolean;
+export { toKanbanCard };
+//# sourceMappingURL=webhook-handler.d.ts.map

package/dist/webhook-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-handler.d.ts","sourceRoot":"","sources":["../src/webhook-handler.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,UAAU,EAGV,UAAU,EACX,MAAM,kBAAkB,CAAC;AA4B1B,UAAU,qBAAqB;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,CAAC;IAGzB,KAAK,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAElB,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7C,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEzE,aAAa,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,gBAAgB,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AA8CD,iBAAS,YAAY,CACnB,IAAI,EAAE,qBAAqB,EAC3B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,GACd,UAAU,CAgBZ;AAID,MAAM,MAAM,sBAAsB,GAC9B,UAAU,CAAC,mBAAmB,CAAC,GAC/B,UAAU,CAAC,sBAAsB,CAAC,GAClC,IAAI,CAAC;AAIT;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,OAAO,EACZ,YAAY,SAA4B,EACxC,OAAO,SAAK,GACX,sBAAsB,CAqFxB;AAID;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,OAAO,CAsBT;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,SAAa,EAClB,QAAQ,SAAgB,GACvB,OAAO,CAOT;AAGD,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/webhook-handler.js

@@ -0,0 +1,196 @@
+// ---- Plane webhook normalization ----
+// Converts raw Plane webhook payloads into typed OuijaEvents.
+//
+// Plane Community Edition webhook format:
+//   event:      "issue" (not "issue_activity")
+//   action:     "created" | "updated" | "deleted"
+//   data:       full issue snapshot (state is an object {id, name, group}, not a string)
+//   activity:   the specific change
+//     .field:   "state_id" | "assignees" | ... (note: "state_id", not "state")
+//     .actor:   {id, first_name, last_name, email, display_name}
+//
+// We only care about:
+//   field === "state_id" or field === "state" → kanban.card.moved
+//   field === "assignees"                     → kanban.card.assigned
+// Everything else returns null.
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { cardId, columnId } from '@ouija-dev/types';
+import { boardId as mkBoardId } from '@ouija-dev/types';
+// ---- Type guard ----
+function isPlaneWebhookPayload(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return false;
+    const p = raw;
+    // Must have event, data, activity, workspace_id
+    if (typeof p['event'] !== 'string')
+        return false;
+    if (typeof p['data'] !== 'object' || p['data'] === null)
+        return false;
+    if (typeof p['activity'] !== 'object' || p['activity'] === null)
+        return false;
+    if (typeof p['workspace_id'] !== 'string')
+        return false;
+    const data = p['data'];
+    if (typeof data['id'] !== 'string')
+        return false;
+    // state can be a string (UUID) or an object { id, name, ... }
+    if (typeof data['state'] !== 'string' && (typeof data['state'] !== 'object' || data['state'] === null))
+        return false;
+    const activity = p['activity'];
+    if (typeof activity['field'] !== 'string')
+        return false;
+    return true;
+}
+// ---- Normalize issue data → KanbanCard ----
+/** Extract state ID from either string or object form. */
+function extractStateId(state) {
+    return typeof state === 'string' ? state : state.id;
+}
+function toKanbanCard(data, workspaceSlug, baseUrl) {
+    const labels = data.labels ?? data.label_details ?? [];
+    const assignees = data.assignees ?? data.assignee_details ?? [];
+    return {
+        id: cardId(data.id),
+        title: data.name,
+        description: data.description_html,
+        columnId: columnId(extractStateId(data.state)),
+        boardId: mkBoardId(data.project),
+        labels: labels.map((l) => l.name),
+        assignees: assignees.map((a) => a.id),
+        url: `${baseUrl.replace(/\/$/, '')}/${workspaceSlug}/projects/${data.project}/issues/${data.id}`,
+        createdAt: data.created_at,
+        updatedAt: data.updated_at,
+    };
+}
+// ---- Main normalization function ----
+/**
+ * Parse and normalize a raw Plane webhook payload.
+ *
+ * Returns:
+ *  - OuijaEvent<'kanban.card.moved'>    when field === "state"
+ *  - OuijaEvent<'kanban.card.assigned'> when field === "assignees"
+ *  - null for all other activity types or on any parse error
+ *
+ * This function never throws — all errors are swallowed and return null.
+ * Callers must not rely on thrown errors for control flow.
+ */
+export function normalizeWebhook(raw, sourcePlugin = '@ouija-dev/plugin-plane', baseUrl = '') {
+    try {
+        if (!isPlaneWebhookPayload(raw)) {
+            return null;
+        }
+        const payload = raw;
+        const { data, activity } = payload;
+        // Accept both "issue" (community edition) and "issue_activity" (older versions).
+        if (payload.event !== 'issue' && payload.event !== 'issue_activity') {
+            return null;
+        }
+        const workspaceSlug = data.workspace ?? '';
+        const eventId = activity.id ?? payload.webhook_id ?? crypto.randomUUID();
+        const timestamp = activity.created_at ?? payload.timestamp ?? new Date().toISOString();
+        const correlationId = payload.activity_id ?? payload.webhook_id ?? eventId;
+        // Actor can be in "actor" (community) or "actor_detail" (older)
+        const actor = activity.actor ?? activity.actor_detail;
+        // "state_id" (community edition) or "state" (older) → card moved
+        if (activity.field === 'state_id' || activity.field === 'state') {
+            const fromColumnId = activity.old_identifier ?? activity.old_value;
+            const toColumnId = activity.new_identifier ?? activity.new_value ?? extractStateId(data.state);
+            if (!fromColumnId || !toColumnId) {
+                return null;
+            }
+            const movedBy = actor?.email ?? actor?.display_name ?? actor?.id ?? 'unknown';
+            const cardMovedPayload = {
+                cardId: cardId(data.id),
+                fromColumnId: columnId(fromColumnId),
+                toColumnId: columnId(toColumnId),
+                movedBy,
+            };
+            const event = {
+                id: eventId,
+                topic: 'kanban.card.moved',
+                payload: cardMovedPayload,
+                timestamp,
+                sourcePlugin,
+                correlationId,
+            };
+            return event;
+        }
+        if (activity.field === 'assignees') {
+            const assigneeId = activity.new_identifier ?? activity.new_value;
+            if (!assigneeId) {
+                return null;
+            }
+            const assignedBy = actor?.email ?? actor?.display_name ?? actor?.id ?? 'unknown';
+            const cardAssignedPayload = {
+                cardId: cardId(data.id),
+                assigneeId,
+                assignedBy,
+            };
+            const event = {
+                id: eventId,
+                topic: 'kanban.card.assigned',
+                payload: cardAssignedPayload,
+                timestamp,
+                sourcePlugin,
+                correlationId,
+            };
+            return event;
+        }
+        // Unrecognised activity field (comment, name change, etc.) — ignore.
+        return null;
+    }
+    catch {
+        // Never propagate parse errors to callers.
+        return null;
+    }
+}
+// ---- HMAC signature verification ----
+/**
+ * Verify the Plane webhook HMAC-SHA256 signature.
+ *
+ * Plane sends: X-Plane-Signature: sha256=<hex-digest>
+ *
+ * @param secret      The webhook secret configured in Plane
+ * @param rawBody     The raw request body bytes (Buffer or string)
+ * @param sigHeader   The value of X-Plane-Signature header
+ * @returns           true if valid, false if invalid or missing
+ */
+export function verifyPlaneSignature(secret, rawBody, sigHeader) {
+    if (!sigHeader)
+        return false;
+    const prefix = 'sha256=';
+    if (!sigHeader.startsWith(prefix))
+        return false;
+    const receivedHex = sigHeader.slice(prefix.length);
+    const bodyBuffer = typeof rawBody === 'string' ? Buffer.from(rawBody, 'utf8') : rawBody;
+    const expected = createHmac('sha256', secret).update(bodyBuffer).digest('hex');
+    // Constant-time comparison to prevent timing attacks.
+    try {
+        const expectedBuf = Buffer.from(expected, 'hex');
+        const receivedBuf = Buffer.from(receivedHex, 'hex');
+        if (expectedBuf.length !== receivedBuf.length)
+            return false;
+        return timingSafeEqual(expectedBuf, receivedBuf);
+    }
+    catch {
+        return false;
+    }
+}
+// ---- Timestamp freshness check ----
+/**
+ * Reject webhooks older than maxAgeMs (default 5 minutes).
+ * Plane includes a top-level `timestamp` field in ISO 8601 format.
+ *
+ * @returns true if the timestamp is within the allowed window, false otherwise
+ */
+export function isWebhookFresh(timestamp, nowMs = Date.now(), maxAgeMs = 5 * 60 * 1000) {
+    if (!timestamp)
+        return false;
+    const ts = Date.parse(timestamp);
+    if (Number.isNaN(ts))
+        return false;
+    return Math.abs(nowMs - ts) <= maxAgeMs;
+}
+// Re-export KanbanCard helper for consumers.
+export { toKanbanCard };
+//# sourceMappingURL=webhook-handler.js.map

package/dist/webhook-handler.js.map

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

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ouija-dev/plugin-plane",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist/", "README.md"],
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "https://github.com/muhammadkh4n/ouija.git" },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./webhook-handler": {
+      "types": "./dist/webhook-handler.d.ts",
+      "default": "./dist/webhook-handler.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@ouija-dev/types": "*",
+    "@ouija-dev/plugin-sdk": "*"
+  },
+  "devDependencies": {
+    "fastify": "^5.8.4",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0",
+    "@types/node": "^22.0.0"
+  }
+}