@mag.ni/process 1.0.0

package/dist/client.js

@@ -0,0 +1,701 @@
+/**
+ * MCP Processes - API Client
+ * HTTP client for the Process Workboard API
+ */
+import { OAuthManager } from './auth.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+// =============================================================================
+// Persistent Session ID
+// =============================================================================
+/**
+ * Load or create a persistent server session ID.
+ * This ensures the same MCP server instance always uses the same session ID
+ * across restarts, preventing force-claim churn on the backend.
+ */
+function getOrCreateSessionId() {
+    const configDir = path.join(os.homedir(), '.config', 'mcp-processes');
+    const sessionFile = path.join(configDir, 'session.json');
+    try {
+        const data = JSON.parse(fs.readFileSync(sessionFile, 'utf-8'));
+        if (data?.sessionId && typeof data.sessionId === 'string') {
+            return data.sessionId;
+        }
+    }
+    catch {
+        // File doesn't exist or is corrupted — generate a new one
+    }
+    const sessionId = crypto.randomUUID();
+    try {
+        fs.mkdirSync(configDir, { recursive: true });
+        fs.writeFileSync(sessionFile, JSON.stringify({ sessionId }, null, 2), 'utf-8');
+    }
+    catch {
+        // If we can't persist, the in-memory ID will still work for this session
+    }
+    return sessionId;
+}
+// =============================================================================
+// Error Classes
+// =============================================================================
+export class ApiClientError extends Error {
+    statusCode;
+    apiError;
+    constructor(message, statusCode, apiError) {
+        super(message);
+        this.statusCode = statusCode;
+        this.apiError = apiError;
+        this.name = 'ApiClientError';
+    }
+}
+export class SessionNotClaimedError extends Error {
+    constructor() {
+        super('No user claimed. Call claimUser() first.');
+        this.name = 'SessionNotClaimedError';
+    }
+}
+// =============================================================================
+// API Client
+// =============================================================================
+export class ProcessesApiClient {
+    baseUrl;
+    sessionId = null;
+    claimedUserId = null;
+    // OAuth2 authorization code + PKCE
+    oauthManager = null;
+    // BFF session cookies (set by /api/auth/session)
+    cookies = [];
+    sessionEstablished = false;
+    constructor(baseUrl, oauth) {
+        // Remove trailing slash if present
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        if (oauth) {
+            this.oauthManager = new OAuthManager(oauth);
+        }
+    }
+    // ===========================================================================
+    // Session State
+    // ===========================================================================
+    /**
+     * Get the current session ID (if claimed)
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Get the currently claimed user ID
+     */
+    getClaimedUserId() {
+        return this.claimedUserId;
+    }
+    /**
+     * Check if a user is currently claimed
+     */
+    hasClaimedUser() {
+        return this.sessionId !== null && this.claimedUserId !== null;
+    }
+    /**
+     * Set the session ID (for restoring sessions)
+     */
+    setSessionId(sessionId, userId) {
+        this.sessionId = sessionId;
+        this.claimedUserId = userId;
+    }
+    /**
+     * Clear the session state (used when lease expires)
+     */
+    clearSession() {
+        this.sessionId = null;
+        this.claimedUserId = null;
+    }
+    // ===========================================================================
+    // HTTP Helpers
+    // ===========================================================================
+    /**
+     * Establish a BFF session by exchanging the OAuth access token for a session cookie.
+     * This calls POST /api/auth/session with the Bearer token, and the backend validates
+     * it via the auth server's userinfo endpoint, then returns a session cookie.
+     */
+    async ensureBffSession() {
+        if (this.sessionEstablished && this.cookies.length > 0)
+            return;
+        if (!this.oauthManager)
+            return;
+        const token = await this.oauthManager.ensureAccessToken();
+        const response = await fetch(`${this.baseUrl}/api/auth/session`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'User-Agent': 'MCP-Processes/1.0',
+            },
+            redirect: 'manual',
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(`BFF session creation failed (${response.status}): ${text}`);
+        }
+        // Capture set-cookie headers
+        const setCookies = response.headers.getSetCookie?.() ?? [];
+        if (setCookies.length > 0) {
+            this.cookies = setCookies.map(c => c.split(';')[0]);
+        }
+        this.sessionEstablished = true;
+        console.error('BFF session established');
+    }
+    async getHeaders(includeSession = false) {
+        // Ensure we have a BFF session cookie
+        await this.ensureBffSession();
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        // Send session cookies instead of Bearer token
+        if (this.cookies.length > 0) {
+            headers['Cookie'] = this.cookies.join('; ');
+        }
+        if (includeSession && this.sessionId) {
+            headers['X-Session-Id'] = this.sessionId;
+        }
+        return headers;
+    }
+    async request(method, path, options = {}) {
+        const url = `${this.baseUrl}${path}`;
+        const { body, includeSession = false } = options;
+        const headers = await this.getHeaders(includeSession);
+        let response = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+            redirect: 'manual',
+        });
+        // If 401, session may have expired — re-establish and retry once
+        if (response.status === 401 && this.oauthManager) {
+            this.sessionEstablished = false;
+            this.cookies = [];
+            const retryHeaders = await this.getHeaders(includeSession);
+            response = await fetch(url, {
+                method,
+                headers: retryHeaders,
+                body: body ? JSON.stringify(body) : undefined,
+                redirect: 'manual',
+            });
+        }
+        // Capture any new cookies from the response (session sliding)
+        const setCookies = response.headers.getSetCookie?.() ?? [];
+        if (setCookies.length > 0) {
+            this.cookies = setCookies.map(c => c.split(';')[0]);
+        }
+        if (!response.ok) {
+            let apiError;
+            try {
+                const errorBody = await response.json();
+                apiError = errorBody;
+            }
+            catch {
+                // Response body is not JSON
+            }
+            throw new ApiClientError(apiError?.message || `HTTP ${response.status}: ${response.statusText}`, response.status, apiError);
+        }
+        // Handle 204 No Content
+        if (response.status === 204) {
+            return undefined;
+        }
+        return response.json();
+    }
+    requireSession() {
+        if (!this.sessionId) {
+            throw new SessionNotClaimedError();
+        }
+    }
+    // ===========================================================================
+    // Authentication
+    // ===========================================================================
+    /**
+     * Logout: destroy the server-side BFF session and clear local OAuth credentials.
+     * After this, the next API call will trigger a fresh interactive login.
+     */
+    async logout() {
+        // Destroy the server-side session
+        if (this.sessionEstablished && this.cookies.length > 0) {
+            try {
+                await fetch(`${this.baseUrl}/api/auth/session`, {
+                    method: 'DELETE',
+                    headers: {
+                        'Cookie': this.cookies.join('; '),
+                        'User-Agent': 'MCP-Processes/1.0',
+                    },
+                    redirect: 'manual',
+                });
+            }
+            catch {
+                // Best-effort — session will expire server-side anyway
+            }
+        }
+        // Clear local BFF session state
+        this.cookies = [];
+        this.sessionEstablished = false;
+        // Clear stored OAuth tokens so next call triggers fresh login
+        if (this.oauthManager) {
+            this.oauthManager.clearCredentials();
+        }
+    }
+    // ===========================================================================
+    // Agent User Management
+    // ===========================================================================
+    /**
+     * List all agent users with their claim status
+     */
+    async listAgentUsers() {
+        return this.request('GET', '/api/agents');
+    }
+    /**
+     * Create a new agent user
+     */
+    async createAgentUser(request) {
+        return this.request('POST', '/api/agents', {
+            body: request,
+        });
+    }
+    /**
+     * Delete an agent user (must be unclaimed)
+     */
+    async deleteAgentUser(userId) {
+        return this.request('DELETE', `/api/agents/${encodeURIComponent(userId)}`);
+    }
+    // ===========================================================================
+    // Session Management
+    // ===========================================================================
+    /**
+     * Claim a user identity to start working
+     * Returns a lease that must be kept alive with heartbeat()
+     */
+    async claimUser(userId) {
+        // Use a persistent session ID so the same server always reuses its identity
+        this.sessionId = getOrCreateSessionId();
+        const response = await this.request('POST', `/api/agents/${encodeURIComponent(userId)}/claim`, { includeSession: true });
+        this.claimedUserId = response.userId;
+        return response;
+    }
+    /**
+     * Send heartbeat to keep the lease alive
+     * Must be called periodically (recommended: every minute for 5-minute TTL)
+     */
+    async heartbeat() {
+        this.requireSession();
+        return this.request('POST', '/api/agents/heartbeat', {
+            includeSession: true,
+        });
+    }
+    /**
+     * Release the claimed user identity
+     * Should be called when done working
+     */
+    async releaseUser() {
+        this.requireSession();
+        const response = await this.request('POST', '/api/agents/release', {
+            includeSession: true,
+        });
+        // Clear session state
+        this.sessionId = null;
+        this.claimedUserId = null;
+        return response;
+    }
+    // ===========================================================================
+    // Instance Management
+    // ===========================================================================
+    /**
+     * Get instances assigned to the claimed user
+     * Returns WorkflowInstanceDto[] from the backend
+     */
+    async getMyInstances(status) {
+        this.requireSession();
+        let path = '/api/instances/my';
+        if (status) {
+            path += `?status=${encodeURIComponent(status)}`;
+        }
+        return this.request('GET', path, { includeSession: true });
+    }
+    /**
+     * Get full details for a specific instance
+     * Returns the raw WorkflowInstanceDto from the backend
+     */
+    async getInstanceDetails(instanceId) {
+        this.requireSession();
+        return this.request('GET', `/api/instances/${encodeURIComponent(instanceId)}`, { includeSession: true });
+    }
+    /**
+     * Get available actions for an instance at its current step
+     */
+    async getAvailableActions(instanceId) {
+        this.requireSession();
+        return this.request('GET', `/api/instances/${encodeURIComponent(instanceId)}/actions`, { includeSession: true });
+    }
+    /**
+     * Execute an action on an instance
+     */
+    async takeAction(instanceId, request) {
+        this.requireSession();
+        return this.request('POST', `/api/instances/${encodeURIComponent(instanceId)}/actions`, {
+            body: request,
+            includeSession: true,
+        });
+    }
+    // ===========================================================================
+    // Diagram Management
+    // ===========================================================================
+    /**
+     * Get a diagram by ID
+     * Maps the raw API response (arrows/from/to/shape) to the MCP type (edges/sourceNodeId/targetNodeId/type)
+     */
+    async getDiagram(diagramId) {
+        const raw = await this.request('GET', `/api/diagrams/${encodeURIComponent(diagramId)}`);
+        return this.mapRawDiagram(raw);
+    }
+    /**
+     * Map raw API diagram response to MCP Diagram type.
+     * The backend returns ArrowDto[] as "arrows" with "from"/"to" properties,
+     * while MCP types expect DiagramEdge[] as "edges" with "sourceNodeId"/"targetNodeId".
+     * Similarly, nodes use "shape"/"isStart"/"isEnd" instead of "type".
+     * Raw properties are preserved via spread for handlers that access them directly.
+     */
+    mapRawDiagram(raw) {
+        // Map nodes: API returns shape/isStart/isEnd, we derive NodeType
+        const rawNodes = raw.nodes || [];
+        const nodes = rawNodes.map((n) => {
+            let type = 'task';
+            if (n.isStart)
+                type = 'start';
+            else if (n.isEnd)
+                type = 'end';
+            else if (n.shape === 'diamond')
+                type = 'decision';
+            else if (n.childDiagramId)
+                type = 'subprocess';
+            return {
+                ...n,
+                id: n.id,
+                type,
+                label: n.label || '',
+                position: { x: n.x || 0, y: n.y || 0 },
+                data: n,
+            };
+        });
+        // Map arrows to edges: API uses from/to, MCP uses sourceNodeId/targetNodeId
+        const rawArrows = raw.arrows || [];
+        const edges = rawArrows.map((a) => ({
+            ...a,
+            id: a.id,
+            sourceNodeId: a.from,
+            targetNodeId: a.to,
+            label: a.label || null,
+            condition: null,
+        }));
+        return {
+            ...raw,
+            id: raw.id,
+            name: raw.title || '',
+            description: null,
+            nodes,
+            edges,
+            createdAt: raw.createdAt || '',
+            updatedAt: raw.updatedAt || '',
+        };
+    }
+    /**
+     * Get full context for a diagram including node details
+     */
+    async getDiagramContext(diagramId) {
+        const diagram = await this.getDiagram(diagramId);
+        const nodes = diagram.nodes ?? [];
+        const edges = diagram.edges ?? [];
+        // Build node context map
+        const nodeDetails = new Map();
+        for (const node of nodes) {
+            const incomingEdges = edges.filter((e) => e.targetNodeId === node.id);
+            const outgoingEdges = edges.filter((e) => e.sourceNodeId === node.id);
+            // Build available actions from outgoing edges
+            const availableActions = outgoingEdges.map((edge) => ({
+                id: edge.id,
+                name: edge.label || 'proceed',
+                description: edge.condition ? `Condition: ${edge.condition}` : null,
+                targetNodeId: edge.targetNodeId,
+                requiresData: false,
+                dataSchema: null,
+            }));
+            nodeDetails.set(node.id, {
+                node,
+                incomingEdges,
+                outgoingEdges,
+                availableActions,
+            });
+        }
+        return {
+            diagram,
+            nodeDetails,
+        };
+    }
+    // ===========================================================================
+    // Utility Methods
+    // ===========================================================================
+    /**
+     * Assign an instance to a user
+     */
+    async assignInstance(instanceId, userId) {
+        return this.request('POST', `/api/instances/${encodeURIComponent(instanceId)}/assign`, {
+            body: { userId },
+            includeSession: true,
+        });
+    }
+    /**
+     * Get a user by ID
+     */
+    async getUser(userId) {
+        return this.request('GET', `/api/users/${encodeURIComponent(userId)}`);
+    }
+    // ===========================================================================
+    // Instance Notes
+    // ===========================================================================
+    /**
+     * Get all notes for an instance
+     */
+    async getInstanceNotes(instanceId) {
+        this.requireSession();
+        return this.request('GET', `/api/instances/${encodeURIComponent(instanceId)}/notes`, { includeSession: true });
+    }
+    /**
+     * Add a note to an instance
+     */
+    async addInstanceNote(instanceId, text) {
+        this.requireSession();
+        return this.request('POST', `/api/instances/${encodeURIComponent(instanceId)}/notes`, {
+            body: {
+                userId: this.claimedUserId,
+                text,
+            },
+            includeSession: true,
+        });
+    }
+    // ===========================================================================
+    // Design Mode - Diagram Management
+    // ===========================================================================
+    /**
+     * List all diagrams with optional filtering
+     */
+    async listDiagrams(filter) {
+        const params = new URLSearchParams();
+        if (filter?.search)
+            params.append('search', filter.search);
+        if (filter?.diagramType)
+            params.append('diagramType', filter.diagramType);
+        if (filter?.sortBy)
+            params.append('sortBy', filter.sortBy);
+        if (filter?.sortOrder)
+            params.append('sortOrder', filter.sortOrder);
+        if (filter?.topLevelOnly)
+            params.append('topLevelOnly', 'true');
+        const queryString = params.toString();
+        const path = `/api/diagrams${queryString ? `?${queryString}` : ''}`;
+        return this.request('GET', path);
+    }
+    /**
+     * Get a diagram by ID (raw API response without mapping)
+     */
+    async getDiagramRaw(diagramId) {
+        return this.request('GET', `/api/diagrams/${encodeURIComponent(diagramId)}`);
+    }
+    /**
+     * Create a new diagram
+     */
+    async createDiagram(data) {
+        return this.request('POST', '/api/diagrams', {
+            body: {
+                title: data.title,
+                token: data.token,
+                diagramType: data.diagramType || 'process',
+                mode: data.mode || 'reactive',
+            },
+        });
+    }
+    /**
+     * Update a diagram's properties
+     */
+    async updateDiagram(diagramId, data) {
+        return this.request('PUT', `/api/diagrams/${encodeURIComponent(diagramId)}`, {
+            body: data,
+        });
+    }
+    /**
+     * Delete a diagram
+     */
+    async deleteDiagram(diagramId, confirm = false) {
+        const path = `/api/diagrams/${encodeURIComponent(diagramId)}${confirm ? '?confirm=true' : ''}`;
+        try {
+            await this.request('DELETE', path);
+            return { success: true };
+        }
+        catch (error) {
+            if (error instanceof ApiClientError && error.statusCode === 409) {
+                const apiError = error.apiError;
+                if (apiError?.requiresConfirmation) {
+                    return {
+                        requiresConfirmation: true,
+                        message: apiError.message,
+                        count: apiError.count,
+                    };
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * Duplicate a diagram
+     */
+    async duplicateDiagram(diagramId) {
+        return this.request('POST', `/api/diagrams/${encodeURIComponent(diagramId)}/duplicate`);
+    }
+    // ===========================================================================
+    // Design Mode - Node Management
+    // ===========================================================================
+    /**
+     * Add a node to a diagram
+     * Fetches the current diagram, adds the node, and saves
+     */
+    async addNode(diagramId, nodeData) {
+        // Get current diagram
+        const diagram = await this.getDiagramRaw(diagramId);
+        const nodes = diagram.nodes || [];
+        const arrows = diagram.arrows || [];
+        // Add the new node
+        nodes.push(nodeData);
+        // Update diagram with new nodes array
+        await this.updateDiagram(diagramId, { nodes, arrows });
+        return nodeData;
+    }
+    /**
+     * Update a node in a diagram
+     */
+    async updateNode(diagramId, nodeId, updateData) {
+        // Get current diagram
+        const diagram = await this.getDiagramRaw(diagramId);
+        const nodes = diagram.nodes || [];
+        const arrows = diagram.arrows || [];
+        // Find and update the node
+        const nodeIndex = nodes.findIndex((n) => n.id === nodeId);
+        if (nodeIndex === -1) {
+            throw new ApiClientError(`Node '${nodeId}' not found in diagram`, 404);
+        }
+        // Merge update data with existing node
+        nodes[nodeIndex] = { ...nodes[nodeIndex], ...updateData };
+        // Update diagram
+        await this.updateDiagram(diagramId, { nodes, arrows });
+        return nodes[nodeIndex];
+    }
+    /**
+     * Delete a node from a diagram
+     * Also removes any arrows connected to this node
+     */
+    async deleteNode(diagramId, nodeId) {
+        // Get current diagram
+        const diagram = await this.getDiagramRaw(diagramId);
+        const nodes = diagram.nodes || [];
+        const arrows = diagram.arrows || [];
+        // Find node
+        const nodeIndex = nodes.findIndex((n) => n.id === nodeId);
+        if (nodeIndex === -1) {
+            throw new ApiClientError(`Node '${nodeId}' not found in diagram`, 404);
+        }
+        // Remove node
+        nodes.splice(nodeIndex, 1);
+        // Remove arrows connected to this node
+        const originalArrowCount = arrows.length;
+        const filteredArrows = arrows.filter((a) => a.from !== nodeId && a.to !== nodeId);
+        const removedArrowCount = originalArrowCount - filteredArrows.length;
+        // Update diagram
+        await this.updateDiagram(diagramId, { nodes, arrows: filteredArrows });
+        return { removedArrowCount };
+    }
+    // ===========================================================================
+    // Design Mode - Arrow Management
+    // ===========================================================================
+    /**
+     * Add an arrow to a diagram
+     */
+    async addArrow(diagramId, arrowData) {
+        // Get current diagram
+        const diagram = await this.getDiagramRaw(diagramId);
+        const nodes = diagram.nodes || [];
+        const arrows = diagram.arrows || [];
+        // Validate that source and target nodes exist
+        const fromExists = nodes.some((n) => n.id === arrowData.from);
+        const toExists = nodes.some((n) => n.id === arrowData.to);
+        if (!fromExists) {
+            throw new ApiClientError(`Source node '${arrowData.from}' not found in diagram`, 404);
+        }
+        if (!toExists) {
+            throw new ApiClientError(`Target node '${arrowData.to}' not found in diagram`, 404);
+        }
+        // Add the new arrow
+        arrows.push(arrowData);
+        // Update diagram
+        await this.updateDiagram(diagramId, { nodes, arrows });
+        return arrowData;
+    }
+    /**
+     * Update an arrow in a diagram
+     */
+    async updateArrow(diagramId, arrowId, updateData) {
+        // Get current diagram
+        const diagram = await this.getDiagramRaw(diagramId);
+        const nodes = diagram.nodes || [];
+        const arrows = diagram.arrows || [];
+        // Find and update the arrow
+        const arrowIndex = arrows.findIndex((a) => a.id === arrowId);
+        if (arrowIndex === -1) {
+            throw new ApiClientError(`Arrow '${arrowId}' not found in diagram`, 404);
+        }
+        // Merge update data with existing arrow
+        arrows[arrowIndex] = { ...arrows[arrowIndex], ...updateData };
+        // Update diagram
+        await this.updateDiagram(diagramId, { nodes, arrows });
+        return arrows[arrowIndex];
+    }
+    /**
+     * Delete an arrow from a diagram
+     */
+    async deleteArrow(diagramId, arrowId) {
+        // Get current diagram
+        const diagram = await this.getDiagramRaw(diagramId);
+        const nodes = diagram.nodes || [];
+        const arrows = diagram.arrows || [];
+        // Find arrow
+        const arrowIndex = arrows.findIndex((a) => a.id === arrowId);
+        if (arrowIndex === -1) {
+            throw new ApiClientError(`Arrow '${arrowId}' not found in diagram`, 404);
+        }
+        // Remove arrow
+        arrows.splice(arrowIndex, 1);
+        // Update diagram
+        await this.updateDiagram(diagramId, { nodes, arrows });
+    }
+}
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a new API client instance from environment variables
+ */
+export function createClient() {
+    const baseUrl = (process.env.PROCESSES_API_URL || 'https://process.mag.ni').replace(/\/$/, '');
+    const authUrl = (process.env.PROCESSES_AUTH_URL || 'https://auth.mag.ni').replace(/\/$/, '');
+    const oauthClientId = process.env.PROCESSES_OAUTH_CLIENT_ID || 'process-mcp';
+    const oauthClientSecret = process.env.PROCESSES_OAUTH_CLIENT_SECRET;
+    const oauth = {
+        authUrl,
+        clientId: oauthClientId,
+        clientSecret: oauthClientSecret,
+        callbackPort: parseInt(process.env.PROCESSES_OAUTH_CALLBACK_PORT || '19823', 10),
+        scopes: ['openid', 'profile', 'email', 'offline_access', 'user.clientId_currently_logged'],
+    };
+    return new ProcessesApiClient(baseUrl, oauth);
+}
+//# sourceMappingURL=client.js.map