figmanage 0.1.0

package/dist/tools/analytics.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { internalClient } from '../clients/internal-api.js';
+import { defineTool, toolResult, toolError, figmaId, requireOrgId } from './register.js';
+// -- library_usage --
+defineTool({
+    toolset: 'analytics',
+    auth: 'cookie',
+    register(server, config) {
+        server.registerTool('library_usage', {
+            description: 'Team-level library adoption metrics. Shows how a published library is used across teams.',
+            inputSchema: {
+                library_file_key: figmaId.describe('File key of the library'),
+                days: z.number().optional().describe('Lookback period in days (default 30). Suggest 30, 60, 90, or 365.'),
+            },
+        }, async ({ library_file_key, days }) => {
+            try {
+                const lookback = days ?? 30;
+                const end_ts = Math.floor(Date.now() / 1000);
+                const start_ts = end_ts - (lookback * 86400);
+                const res = await internalClient(config).get(`/api/dsa/library/${library_file_key}/team_usage`, { params: { start_ts, end_ts } });
+                return toolResult(JSON.stringify(res.data, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to fetch library usage: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- component_usage --
+defineTool({
+    toolset: 'analytics',
+    auth: 'cookie',
+    register(server, config) {
+        server.registerTool('component_usage', {
+            description: 'Per-file component usage analytics. Shows which files use a specific component.',
+            inputSchema: {
+                component_key: figmaId.describe('Component key'),
+                org_id: figmaId.optional().describe('Org ID override (defaults to current workspace)'),
+            },
+        }, async ({ component_key, org_id }) => {
+            try {
+                let orgId;
+                try {
+                    orgId = requireOrgId(config, org_id);
+                }
+                catch (e) {
+                    return toolError(e.message);
+                }
+                const res = await internalClient(config).get(`/api/design_systems/component/${component_key}/file_usage`, { params: { org_id: orgId, fv: 4 } });
+                return toolResult(JSON.stringify(res.data, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to fetch component usage: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+//# sourceMappingURL=analytics.js.map

package/dist/tools/branching.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=branching.d.ts.map

package/dist/tools/branching.js

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { hasCookie } from '../auth/client.js';
+import { publicClient } from '../clients/public-api.js';
+import { internalClient } from '../clients/internal-api.js';
+import { defineTool, toolResult, toolError, figmaId } from './register.js';
+// -- list_branches --
+defineTool({
+    toolset: 'branching',
+    auth: 'either',
+    register(server, config) {
+        server.registerTool('list_branches', {
+            description: 'List branches of a file.',
+            inputSchema: {
+                file_key: figmaId.describe('File key of the main file'),
+            },
+        }, async ({ file_key }) => {
+            try {
+                let branches;
+                if (hasCookie(config)) {
+                    const res = await internalClient(config).get(`/api/files/${file_key}`);
+                    const f = res.data?.meta || res.data;
+                    branches = f.branches || [];
+                }
+                else {
+                    const res = await publicClient(config).get(`/v1/files/${file_key}`, {
+                        params: { branch_data: 'true', depth: '0' },
+                    });
+                    branches = res.data?.branches || [];
+                }
+                if (branches.length === 0)
+                    return toolResult('No branches found.');
+                const mapped = branches.map((b) => ({
+                    key: b.key,
+                    name: b.name,
+                    thumbnail_url: b.thumbnail_url || null,
+                    last_modified: b.last_modified || null,
+                    link_access: b.link_access || null,
+                }));
+                return toolResult(JSON.stringify(mapped, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to list branches: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- create_branch --
+defineTool({
+    toolset: 'branching',
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('create_branch', {
+            description: 'Create a branch from a file.',
+            inputSchema: {
+                file_key: figmaId.describe('File key to branch from'),
+                name: z.string().describe('Branch name'),
+            },
+        }, async ({ file_key, name }) => {
+            try {
+                const res = await internalClient(config).post(`/api/multiplayer/${file_key}/branch_create?name=${encodeURIComponent(name)}`);
+                const meta = res.data?.meta || res.data || {};
+                const file = meta.file || meta;
+                const branchKey = file.key || file.file_key || null;
+                return toolResult(JSON.stringify({
+                    key: branchKey,
+                    name,
+                    main_file_key: file_key,
+                }, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to create branch: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- delete_branch --
+// Archiving a branch is the same as trashing the branch file.
+defineTool({
+    toolset: 'branching',
+    auth: 'cookie',
+    mutates: true,
+    destructive: true,
+    register(server, config) {
+        server.registerTool('delete_branch', {
+            description: 'Archive (delete) a branch. Uses the branch file key from list_branches.',
+            inputSchema: {
+                branch_key: figmaId.describe('Branch file key (from list_branches)'),
+            },
+        }, async ({ branch_key }) => {
+            try {
+                await internalClient(config).delete('/api/files_batch', {
+                    data: { files: [{ key: branch_key }], trashed: true },
+                });
+                return toolResult(`Archived branch ${branch_key}`);
+            }
+            catch (e) {
+                return toolError(`Failed to delete branch: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+//# sourceMappingURL=branching.js.map

package/dist/tools/comments.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=comments.d.ts.map

package/dist/tools/comments.js

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+import { publicClient } from '../clients/public-api.js';
+import { defineTool, toolResult, toolError, figmaId } from './register.js';
+// -- list_comments --
+defineTool({
+    toolset: 'comments',
+    auth: 'pat',
+    register(server, config) {
+        server.registerTool('list_comments', {
+            description: 'List comments on a file. Returns comment text, author, timestamps, and thread structure.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+                as_md: z.boolean().optional().describe('Format as markdown thread (default: false)'),
+            },
+        }, async ({ file_key, as_md }) => {
+            try {
+                const res = await publicClient(config).get(`/v1/files/${file_key}/comments`);
+                const comments = res.data?.comments || [];
+                if (as_md) {
+                    const threads = new Map();
+                    for (const c of comments) {
+                        const parentId = c.parent_id || c.id;
+                        if (!threads.has(parentId))
+                            threads.set(parentId, []);
+                        threads.get(parentId).push(c);
+                    }
+                    const lines = [];
+                    for (const [, thread] of threads) {
+                        thread.sort((a, b) => new Date(a.created_at).getTime() - new Date(b.created_at).getTime());
+                        for (const c of thread) {
+                            const indent = c.parent_id ? '  ' : '';
+                            const resolved = c.resolved_at ? ' [resolved]' : '';
+                            lines.push(`${indent}- **${c.user.handle}** (${c.created_at})${resolved}: ${c.message}`);
+                        }
+                        lines.push('');
+                    }
+                    return toolResult(lines.join('\n'));
+                }
+                const mapped = comments.map((c) => ({
+                    id: c.id,
+                    parent_id: c.parent_id || null,
+                    message: c.message,
+                    author: c.user?.handle,
+                    author_id: c.user?.id,
+                    created_at: c.created_at,
+                    resolved_at: c.resolved_at || null,
+                    node_id: c.client_meta?.node_id || c.client_meta?.node_offset?.node_id || null,
+                    order_id: c.order_id,
+                }));
+                return toolResult(JSON.stringify(mapped, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to list comments: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- post_comment --
+defineTool({
+    toolset: 'comments',
+    auth: 'pat',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('post_comment', {
+            description: 'Post a comment on a file. Optionally pin to a specific node or reply to an existing comment.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+                message: z.string().describe('Comment text'),
+                comment_id: figmaId.optional().describe('Parent comment ID to reply to'),
+                node_id: figmaId.optional().describe('Node ID to pin the comment to'),
+            },
+        }, async ({ file_key, message, comment_id, node_id }) => {
+            try {
+                const body = { message };
+                if (comment_id)
+                    body.comment_id = comment_id;
+                if (node_id)
+                    body.client_meta = { node_id, node_offset: { x: 0, y: 0 } };
+                const res = await publicClient(config).post(`/v1/files/${file_key}/comments`, body);
+                const c = res.data;
+                return toolResult(JSON.stringify({
+                    id: c.id,
+                    message: c.message,
+                    author: c.user?.handle,
+                    created_at: c.created_at,
+                    parent_id: c.parent_id || null,
+                }, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to post comment: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- delete_comment --
+defineTool({
+    toolset: 'comments',
+    auth: 'pat',
+    mutates: true,
+    destructive: true,
+    register(server, config) {
+        server.registerTool('delete_comment', {
+            description: 'Permanently delete a comment. For top-level comments, the entire thread is removed.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+                comment_id: figmaId.describe('Comment ID to delete'),
+            },
+        }, async ({ file_key, comment_id }) => {
+            try {
+                await publicClient(config).delete(`/v1/files/${file_key}/comments/${comment_id}`);
+                return toolResult(`Deleted comment ${comment_id}`);
+            }
+            catch (e) {
+                return toolError(`Failed to delete comment: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- list_comment_reactions --
+defineTool({
+    toolset: 'comments',
+    auth: 'pat',
+    register(server, config) {
+        server.registerTool('list_comment_reactions', {
+            description: 'List emoji reactions on a comment.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+                comment_id: figmaId.describe('Comment ID'),
+            },
+        }, async ({ file_key, comment_id }) => {
+            try {
+                const res = await publicClient(config).get(`/v1/files/${file_key}/comments/${comment_id}/reactions`);
+                const reactions = res.data?.reactions || [];
+                const mapped = reactions.map((r) => ({
+                    emoji: r.emoji,
+                    user: r.user?.handle,
+                    created_at: r.created_at,
+                }));
+                return toolResult(JSON.stringify(mapped, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to list reactions: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+//# sourceMappingURL=comments.js.map

package/dist/tools/components.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=components.d.ts.map

package/dist/tools/components.js

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import { publicClient } from '../clients/public-api.js';
+import { defineTool, toolResult, toolError, figmaId } from './register.js';
+// -- list_file_components --
+defineTool({
+    toolset: 'components',
+    auth: 'pat',
+    register(server, config) {
+        server.registerTool('list_file_components', {
+            description: 'List components published from a specific file.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+            },
+        }, async ({ file_key }) => {
+            try {
+                const res = await publicClient(config).get(`/v1/files/${file_key}/components`);
+                const components = res.data?.meta?.components || [];
+                return toolResult(JSON.stringify(components, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to list file components: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- list_file_styles --
+defineTool({
+    toolset: 'components',
+    auth: 'pat',
+    register(server, config) {
+        server.registerTool('list_file_styles', {
+            description: 'List styles in a specific file.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+            },
+        }, async ({ file_key }) => {
+            try {
+                const res = await publicClient(config).get(`/v1/files/${file_key}/styles`);
+                const styles = res.data?.meta?.styles || [];
+                return toolResult(JSON.stringify(styles, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to list file styles: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- list_team_components --
+defineTool({
+    toolset: 'components',
+    auth: 'pat',
+    register(server, config) {
+        server.registerTool('list_team_components', {
+            description: 'List published components across a team. Supports pagination.',
+            inputSchema: {
+                team_id: figmaId.describe('Team ID'),
+                page_size: z.number().optional().default(30).describe('Max items per page (default: 30)'),
+                cursor: z.string().optional().describe('Pagination cursor from previous response'),
+            },
+        }, async ({ team_id, page_size, cursor }) => {
+            try {
+                const params = { page_size };
+                if (cursor)
+                    params.after = cursor;
+                const res = await publicClient(config).get(`/v1/teams/${team_id}/components`, { params });
+                const components = res.data?.meta?.components || [];
+                const pagination = res.data?.pagination || null;
+                return toolResult(JSON.stringify({ components, pagination }, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to list team components: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- list_team_styles --
+defineTool({
+    toolset: 'components',
+    auth: 'pat',
+    register(server, config) {
+        server.registerTool('list_team_styles', {
+            description: 'List published styles across a team. Supports pagination.',
+            inputSchema: {
+                team_id: figmaId.describe('Team ID'),
+                page_size: z.number().optional().default(30).describe('Max items per page (default: 30)'),
+                cursor: z.string().optional().describe('Pagination cursor from previous response'),
+            },
+        }, async ({ team_id, page_size, cursor }) => {
+            try {
+                const params = { page_size };
+                if (cursor)
+                    params.after = cursor;
+                const res = await publicClient(config).get(`/v1/teams/${team_id}/styles`, { params });
+                const styles = res.data?.meta?.styles || [];
+                const pagination = res.data?.pagination || null;
+                return toolResult(JSON.stringify({ styles, pagination }, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to list team styles: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+//# sourceMappingURL=components.js.map

package/dist/tools/compound.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=compound.d.ts.map