figmanage 0.1.0

package/dist/tools/libraries.js

@@ -0,0 +1,31 @@
+import { internalClient } from '../clients/internal-api.js';
+import { defineTool, toolResult, toolError, figmaId, requireOrgId } from './register.js';
+// -- list_org_libraries --
+defineTool({
+    toolset: 'libraries',
+    auth: 'cookie',
+    register(server, config) {
+        server.registerTool('list_org_libraries', {
+            description: 'List all design system libraries in the org with sharing group info.',
+            inputSchema: {
+                org_id: figmaId.optional().describe('Org ID override (defaults to current workspace)'),
+            },
+        }, async ({ 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/libraries', { params: { org_id: orgId, include_sharing_group_info: true } });
+                return toolResult(JSON.stringify(res.data, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to list org libraries: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+//# sourceMappingURL=libraries.js.map

package/dist/tools/navigate.d.ts

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

package/dist/tools/navigate.js

@@ -0,0 +1,436 @@
+import { z } from 'zod';
+import { publicClient } from '../clients/public-api.js';
+import { internalClient } from '../clients/internal-api.js';
+import { hasCookie, hasPat } from '../auth/client.js';
+import { defineTool, toolResult, toolError, figmaId, requireOrgId } from './register.js';
+import { checkAuth, formatAuthStatus } from '../auth/health.js';
+// -- check_auth --
+defineTool({
+    toolset: 'navigate',
+    auth: 'either',
+    register(server, config) {
+        server.registerTool('check_auth', { description: 'Check authentication status for both PAT and session cookie' }, async () => {
+            try {
+                const status = await checkAuth(config);
+                return toolResult(formatAuthStatus(status, config));
+            }
+            catch (e) {
+                return toolError(`Auth check failed: ${e.message}`);
+            }
+        });
+    },
+});
+// -- list_orgs --
+defineTool({
+    toolset: 'navigate',
+    auth: 'cookie',
+    register(server, config) {
+        server.registerTool('list_orgs', {
+            description: 'List all Figma workspaces (orgs) you belong to. Shows which is currently active.',
+        }, async () => {
+            try {
+                const api = internalClient(config);
+                const res = await api.get('/api/user/state');
+                let orgs = (res.data?.meta?.orgs || [])
+                    .filter((o) => o && o.id)
+                    .map((o) => ({ id: String(o.id), name: o.name || String(o.id) }));
+                // Fallback: meta.orgs is empty for non-admin users.
+                // Extract unique org_ids from meta.roles instead.
+                if (orgs.length === 0) {
+                    const roles = res.data?.meta?.roles || [];
+                    const orgIds = [...new Set(roles
+                            .map((r) => r.org_id)
+                            .filter((id) => id != null)
+                            .map(String))];
+                    // Also include config.orgId if not already covered
+                    if (config.orgId && !orgIds.includes(config.orgId)) {
+                        orgIds.push(config.orgId);
+                    }
+                    // Resolve names via domain lookup
+                    orgs = await Promise.all(orgIds.map(async (id) => {
+                        let name = id;
+                        try {
+                            const domRes = await api.get(`/api/orgs/${id}/domains`);
+                            const domains = domRes.data?.meta || [];
+                            if (Array.isArray(domains) && domains.length > 0) {
+                                name = domains[0].domain || id;
+                            }
+                        }
+                        catch { /* domain lookup optional */ }
+                        return { id, name };
+                    }));
+                }
+                // Merge with any existing registry entries (preserves names from setup)
+                if (config.orgs && config.orgs.length > 0) {
+                    for (const existing of config.orgs) {
+                        if (!orgs.find(o => o.id === existing.id)) {
+                            orgs.push(existing);
+                        }
+                        else {
+                            // Prefer stored name over ID-only fallback
+                            const entry = orgs.find(o => o.id === existing.id);
+                            if (entry.name === entry.id && existing.name !== existing.id) {
+                                entry.name = existing.name;
+                            }
+                        }
+                    }
+                }
+                if (orgs.length > 0)
+                    config.orgs = orgs;
+                if (orgs.length === 0) {
+                    return toolResult('No workspaces found. You may be on a free/starter plan.');
+                }
+                const result = orgs.map(o => ({
+                    id: o.id,
+                    name: o.name,
+                    active: o.id === config.orgId,
+                }));
+                return toolResult(JSON.stringify(result, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to list orgs: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- switch_org --
+defineTool({
+    toolset: 'navigate',
+    auth: 'cookie',
+    register(server, config) {
+        server.registerTool('switch_org', {
+            description: 'Switch active workspace. Accepts org name (fuzzy match) or ID. Use list_orgs to see available workspaces.',
+            inputSchema: {
+                org: z.string().describe('Org name or ID to switch to'),
+            },
+        }, async ({ org }) => {
+            try {
+                // Ensure we have an org list
+                if (!config.orgs || config.orgs.length === 0) {
+                    const res = await internalClient(config).get('/api/user/state');
+                    const orgs = (res.data?.meta?.orgs || []).map((o) => ({
+                        id: String(o.id),
+                        name: o.name,
+                    }));
+                    if (orgs.length > 0)
+                        config.orgs = orgs;
+                }
+                if (!config.orgs || config.orgs.length === 0) {
+                    return toolError('No workspaces found. You may be on a free/starter plan.');
+                }
+                // Try exact ID match first
+                let match = config.orgs.find(o => o.id === org);
+                // Then case-insensitive substring match on name
+                if (!match) {
+                    const lower = org.toLowerCase();
+                    const matches = config.orgs.filter(o => o.name.toLowerCase().includes(lower));
+                    if (matches.length === 1) {
+                        match = matches[0];
+                    }
+                    else if (matches.length > 1) {
+                        const names = matches.map(o => `${o.name} (${o.id})`).join(', ');
+                        return toolError(`Ambiguous: "${org}" matches multiple workspaces: ${names}. Be more specific or use the org ID.`);
+                    }
+                }
+                if (!match) {
+                    const available = config.orgs.map(o => `${o.name} (${o.id})`).join(', ');
+                    return toolError(`No workspace matching "${org}". Available: ${available}`);
+                }
+                const previousId = config.orgId;
+                const previousOrg = config.orgs.find(o => o.id === previousId);
+                const previousLabel = previousOrg ? `${previousOrg.name} (${previousId})` : (previousId || 'none');
+                config.orgId = match.id;
+                return toolResult(`Switched workspace: ${previousLabel} -> ${match.name} (${match.id})`);
+            }
+            catch (e) {
+                return toolError(`Failed to switch org: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- list_teams --
+defineTool({
+    toolset: 'navigate',
+    auth: 'cookie',
+    register(server, config) {
+        server.registerTool('list_teams', {
+            description: 'List all teams you belong to. Returns team IDs and names.',
+        }, async () => {
+            try {
+                if (config.orgId) {
+                    const res = await internalClient(config).get(`/api/orgs/${config.orgId}/teams`);
+                    const data = res.data?.meta || res.data;
+                    const teams = (data.teams || (Array.isArray(data) ? data : [])).map((t) => ({
+                        id: String(t.id),
+                        name: t.name,
+                    }));
+                    return toolResult(JSON.stringify(teams, null, 2));
+                }
+                // Fallback: get teams from user/state
+                const res = await internalClient(config).get('/api/user/state');
+                const teams = (res.data?.meta?.teams || []).map((t) => ({
+                    id: String(t.id),
+                    name: t.name,
+                }));
+                return toolResult(JSON.stringify(teams, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to list teams: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- list_projects --
+defineTool({
+    toolset: 'navigate',
+    auth: 'either',
+    register(server, config) {
+        server.registerTool('list_projects', {
+            description: 'List projects (folders) in a team. Returns project IDs, names.',
+            inputSchema: {
+                team_id: figmaId.describe('Team ID'),
+            },
+        }, async ({ team_id }) => {
+            try {
+                if (hasCookie(config)) {
+                    const res = await internalClient(config).get(`/api/teams/${team_id}/folders`);
+                    const rows = res.data?.meta?.folder_rows || res.data || [];
+                    const projects = (Array.isArray(rows) ? rows : []).map((p) => ({
+                        id: String(p.id),
+                        name: p.name || p.path,
+                    }));
+                    return toolResult(JSON.stringify(projects, null, 2));
+                }
+                else {
+                    const res = await publicClient(config).get(`/v1/teams/${team_id}/projects`);
+                    const projects = (res.data.projects || []).map((p) => ({
+                        id: String(p.id),
+                        name: p.name,
+                    }));
+                    return toolResult(JSON.stringify(projects, null, 2));
+                }
+            }
+            catch (e) {
+                return toolError(`Failed to list projects: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- list_files --
+defineTool({
+    toolset: 'navigate',
+    auth: 'either',
+    register(server, config) {
+        server.registerTool('list_files', {
+            description: 'List files in a project. Returns file keys, names, last modified, editor type. Supports pagination.',
+            inputSchema: {
+                project_id: figmaId.describe('Project (folder) ID'),
+                page_size: z.number().optional().describe('Results per page (default 25, max 100)'),
+                page_token: z.string().optional().describe('Pagination token from previous response'),
+            },
+        }, async ({ project_id, page_size, page_token }) => {
+            try {
+                // Prefer public API when PAT available -- returns keys compatible
+                // with all public endpoints (versions, comments, export).
+                if (hasPat(config)) {
+                    const res = await publicClient(config).get(`/v1/projects/${project_id}/files`);
+                    const files = (res.data.files || []).map((f) => ({
+                        key: f.key,
+                        name: f.name,
+                        last_modified: f.last_modified,
+                        thumbnail_url: f.thumbnail_url,
+                    }));
+                    return toolResult(JSON.stringify({ files }, null, 2));
+                }
+                else {
+                    const pageSize = Math.min(page_size || 25, 100);
+                    const params = new URLSearchParams({
+                        folderId: project_id,
+                        sort_column: 'touched_at',
+                        sort_order: 'desc',
+                        page_size: String(pageSize),
+                        file_type: '',
+                    });
+                    if (page_token)
+                        params.set('before', page_token);
+                    const res = await internalClient(config).get(`/api/folders/${project_id}/paginated_files?${params}`);
+                    const meta = res.data?.meta || res.data;
+                    const files = (meta.files || meta.results || []).map((f) => ({
+                        key: f.key,
+                        name: f.name,
+                        last_modified: f.touched_at || f.updated_at || f.last_modified,
+                        editor_type: f.editor_type,
+                    }));
+                    const pagination = res.data?.pagination;
+                    const result = { files };
+                    if (pagination?.next_page || files.length === pageSize) {
+                        result.pagination = {
+                            has_more: true,
+                            hint: `To get the next page, call list_files again with page_token="${pagination?.next_page || files[files.length - 1]?.last_modified || ''}"`,
+                        };
+                    }
+                    return toolResult(JSON.stringify(result, null, 2));
+                }
+            }
+            catch (e) {
+                return toolError(`Failed to list files: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- list_recent_files --
+defineTool({
+    toolset: 'navigate',
+    auth: 'cookie',
+    register(server, config) {
+        server.registerTool('list_recent_files', {
+            description: 'List your recently viewed/edited files across all teams.',
+        }, async () => {
+            try {
+                const res = await internalClient(config).get('/api/recent_files');
+                const files = (res.data?.meta?.recent_files || []).map((f) => ({
+                    key: f.key,
+                    name: f.name,
+                    team_id: f.team_id,
+                    folder_id: f.folder_id,
+                    editor_type: f.editor_type,
+                    last_touched: f.touched_at,
+                    url: f.url || `https://www.figma.com/design/${f.key}`,
+                }));
+                return toolResult(JSON.stringify(files, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to list recent files: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- search --
+defineTool({
+    toolset: 'navigate',
+    auth: 'cookie',
+    register(server, config) {
+        server.registerTool('search', {
+            description: 'Search for files across the workspace. Requires org context for results.',
+            inputSchema: {
+                query: z.string().describe('Search query'),
+                sort: z.enum(['relevancy', 'last_modified']).optional().describe('Sort order (default: relevancy)'),
+                org_id: figmaId.optional().describe('Org ID override (defaults to current workspace)'),
+            },
+        }, async ({ query, sort, org_id }) => {
+            try {
+                let orgId;
+                try {
+                    orgId = requireOrgId(config, org_id);
+                }
+                catch (e) {
+                    return toolError(e.message);
+                }
+                const params = {
+                    query,
+                    sort: sort || 'relevancy',
+                    desc: 'true',
+                    is_global: 'true',
+                    org_id: orgId,
+                    current_org_id: orgId,
+                    plan_type: 'org',
+                };
+                const res = await internalClient(config).get('/api/search/file_browser_preview', { params });
+                const meta = res.data?.meta;
+                // Response is an array of category objects; files are in the first entry
+                const categories = Array.isArray(meta) ? meta : [];
+                const fileCategory = categories.find((c) => c.search_model_type === 'files') || categories[0];
+                const rawResults = fileCategory?.results || [];
+                const results = rawResults.map((r) => {
+                    const m = r.model || r;
+                    return {
+                        key: m.key,
+                        name: m.name,
+                        editor_type: m.editor_type,
+                        team_id: m.team_id ? String(m.team_id) : undefined,
+                        folder_id: m.folder_id ? String(m.folder_id) : undefined,
+                        last_modified: m.touched_at,
+                        url: m.url || `https://www.figma.com/design/${m.key}`,
+                    };
+                });
+                if (results.length === 0) {
+                    return toolResult('No results. Try list_recent_files or browse via list_projects + list_files.');
+                }
+                return toolResult(JSON.stringify(results, null, 2));
+            }
+            catch (e) {
+                return toolError(`Search failed: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- get_file_info --
+defineTool({
+    toolset: 'navigate',
+    auth: 'either',
+    register(server, config) {
+        server.registerTool('get_file_info', {
+            description: 'Get metadata for a file: name, last modified, editor type, project, team.',
+            inputSchema: {
+                file_key: figmaId.describe('Figma file key (from the URL)'),
+            },
+        }, async ({ file_key }) => {
+            try {
+                // Prefer public API for consistent key format.
+                if (hasPat(config)) {
+                    const res = await publicClient(config).get(`/v1/files/${file_key}/meta`);
+                    const f = res.data.file || res.data;
+                    return toolResult(JSON.stringify({
+                        key: f.key || file_key,
+                        name: f.name,
+                        last_modified: f.lastModified || f.last_modified,
+                        editor_type: f.editorType || f.editor_type,
+                        url: `https://www.figma.com/design/${file_key}`,
+                    }, null, 2));
+                }
+                else {
+                    const res = await internalClient(config).get(`/api/files/${file_key}`);
+                    const f = res.data?.meta || res.data;
+                    return toolResult(JSON.stringify({
+                        key: f.key || file_key,
+                        name: f.name,
+                        updated_at: f.updated_at,
+                        editor_type: f.editor_type,
+                        folder_id: f.folder_id ? String(f.folder_id) : undefined,
+                        team_id: f.team_id ? String(f.team_id) : undefined,
+                        link_access: f.link_access,
+                        url: f.url || `https://www.figma.com/design/${file_key}`,
+                    }, null, 2));
+                }
+            }
+            catch (e) {
+                return toolError(`Failed to get file info: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- list_favorites --
+defineTool({
+    toolset: 'navigate',
+    auth: 'cookie',
+    register(server, config) {
+        server.registerTool('list_favorites', {
+            description: 'List your starred/favorited files. Note: may not work on all account types.',
+        }, async () => {
+            try {
+                const res = await internalClient(config).get('/api/user/favorited_resources');
+                const data = res.data?.meta || res.data;
+                const favorites = (Array.isArray(data) ? data : data.favorites || data.resources || []).map((f) => ({
+                    key: f.key || f.file_key || f.id,
+                    name: f.name,
+                    type: f.resource_type || f.type,
+                }));
+                return toolResult(JSON.stringify(favorites, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to list favorites: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+//# sourceMappingURL=navigate.js.map

package/dist/tools/org.d.ts

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