figmanage 1.2.9 → 1.3.1

package/dist/operations/compound-manager.js

@@ -1,5 +1,5 @@
 import { internalClient } from '../clients/internal-api.js';
-import { requireOrgId } from '../tools/register.js';
+import { requireOrgId, formatApiError } from '../helpers.js';
 import { levelName } from './compound.js';
 // -- Shared helpers --
 const BATCH_SIZE = 5;
@@ -241,7 +241,7 @@ export async function offboardUser(config, params) {
                 actions.push({ action: 'transfer_ownership', status: 'done', detail: `${file.file_name} -> ${transfer_to}` });
             }
             catch (e) {
-                actions.push({ action: 'transfer_ownership', status: 'failed', detail: `${file.file_name}: ${e.response?.status || e.message}` });
+                actions.push({ action: 'transfer_ownership', status: 'failed', detail: `${file.file_name}: ${formatApiError(e)}` });
             }
         }
     }
@@ -257,7 +257,7 @@ export async function offboardUser(config, params) {
             }
         }
         catch (e) {
-            actions.push({ action: 'revoke_file', status: 'failed', detail: `${file.file_name}: ${e.response?.status || e.message}` });
+            actions.push({ action: 'revoke_file', status: 'failed', detail: `${file.file_name}: ${formatApiError(e)}` });
         }
     }
     // Step C: Revoke project access
@@ -312,7 +312,7 @@ export async function offboardUser(config, params) {
             actions.push({ action: 'downgrade_seat', status: 'done', detail: `${user.seat_type} -> viewer` });
         }
         catch (e) {
-            actions.push({ action: 'downgrade_seat', status: 'failed', detail: e.response?.status || e.message });
+            actions.push({ action: 'downgrade_seat', status: 'failed', detail: formatApiError(e) });
         }
     }
     const succeeded = actions.filter(a => a.status === 'done').length;
@@ -421,7 +421,7 @@ export async function onboardUser(config, params) {
             }
         }
         catch (e) {
-            seatChange = { status: 'failed', note: `Seat change failed: ${e.response?.status || e.message}` };
+            seatChange = { status: 'failed', note: `Seat change failed: ${formatApiError(e)}` };
         }
     }
     else if (seat_type && !confirm) {
@@ -482,7 +482,7 @@ export async function quarterlyDesignOpsReport(config, params) {
         }
         catch (e) {
             membersComplete = false;
-            errors.push(`members: pagination stopped at page ${page + 1} of ${maxPages}, fetched ${allMembers.length} members (${e.response?.status || e.message})`);
+            errors.push(`members: pagination stopped at page ${page + 1} of ${maxPages}, fetched ${allMembers.length} members (${formatApiError(e)})`);
             break;
         }
     }
@@ -609,6 +609,8 @@ export async function quarterlyDesignOpsReport(config, params) {
         highlights.push(`${totalInsertions} library component insertions across ${libraryAdoption.length} library/libraries.`);
     }
     const result = {
+        highlights,
+        ...(errors.length > 0 ? { errors } : {}),
         period: {
             start: periodStart.toISOString().split('T')[0],
             end: now.toISOString().split('T')[0],
@@ -628,10 +630,7 @@ export async function quarterlyDesignOpsReport(config, params) {
         teams,
         billing,
         library_adoption: libraryAdoption,
-        highlights,
     };
-    if (errors.length > 0)
-        result.errors = errors;
     return result;
 }
 //# sourceMappingURL=compound-manager.js.map

package/dist/operations/compound.d.ts

@@ -29,7 +29,9 @@ export declare function organizeProject(config: AuthConfig, params: {
     file_keys: string[];
     target_project_id: string;
 }): Promise<{
+    target_project_id: string;
     moved: number;
+    moved_file_keys: string[];
     failed: number;
     errors: any;
 }>;
@@ -87,6 +89,7 @@ export declare function branchCleanup(config: AuthConfig, params: {
     active_branches: any[];
     dry_run: boolean;
     archived: boolean;
+    archived_count: number;
     recommendations: string[];
 }>;
 //# sourceMappingURL=compound.d.ts.map

package/dist/operations/compound.js

@@ -1,7 +1,7 @@
 import { hasPat, hasCookie } from '../auth/client.js';
 import { publicClient } from '../clients/public-api.js';
 import { internalClient } from '../clients/internal-api.js';
-import { requireOrgId } from '../tools/register.js';
+import { requireOrgId, formatApiError } from '../helpers.js';
 // -- Shared helpers --
 const BATCH_SIZE = 5;
 async function batchProcess(items, fn) {
@@ -32,7 +32,7 @@ export async function fileSummary(config, params) {
         api.get(`/v1/files/${params.file_key}/comments`),
     ]);
     if (fileResult.status === 'rejected') {
-        throw new Error(`Failed to fetch file: ${fileResult.reason?.response?.status || fileResult.reason?.message}`);
+        throw new Error(`Failed to fetch file: ${formatApiError(fileResult.reason)}`);
     }
     const fileData = fileResult.value.data;
     const pages = (fileData.document?.children || []).map((c) => c.name);
@@ -78,11 +78,11 @@ export async function workspaceOverview(config, params) {
         delete billing.shipping_address;
     const errors = [];
     if (teamsResult.status === 'rejected')
-        errors.push(`teams: ${teamsResult.reason?.response?.status || teamsResult.reason?.message}`);
+        errors.push(`teams: ${formatApiError(teamsResult.reason)}`);
     if (seatsResult.status === 'rejected')
-        errors.push(`seats: ${seatsResult.reason?.response?.status || seatsResult.reason?.message}`);
+        errors.push(`seats: ${formatApiError(seatsResult.reason)}`);
     if (billingResult.status === 'rejected')
-        errors.push(`billing: ${billingResult.reason?.response?.status || billingResult.reason?.message}`);
+        errors.push(`billing: ${formatApiError(billingResult.reason)}`);
     const overview = { teams, seats, billing };
     if (errors.length > 0)
         overview.errors = errors;
@@ -104,7 +104,7 @@ export async function openComments(config, params) {
             commentResults.push({ file_key: f.key, file_name: f.name, comments });
         }
         catch (e) {
-            commentResults.push({ file_key: f.key, file_name: f.name, comments: [], error: e.response?.status || e.message });
+            commentResults.push({ file_key: f.key, file_name: f.name, comments: [], error: formatApiError(e) });
         }
     }
     const filesWithComments = commentResults
@@ -180,6 +180,8 @@ export async function cleanupStaleFiles(config, params) {
                 data: { files: staleFiles.map((f) => ({ key: f.key })), trashed: true },
             });
             result.trashed = true;
+            result.trashed_count = staleFiles.length;
+            result.trashed_file_keys = staleFiles.map((f) => f.key);
         }
     }
     return result;
@@ -199,7 +201,9 @@ export async function organizeProject(config, params) {
     const moved = Object.keys(data?.success || {}).length;
     const failed = Object.keys(data?.errors || {}).length;
     return {
+        target_project_id: params.target_project_id,
         moved: moved || (failed === 0 ? params.file_keys.length : 0),
+        moved_file_keys: params.file_keys,
         failed,
         errors: data?.errors || {},
     };
@@ -230,7 +234,7 @@ export async function setupProjectStructure(config, params) {
             created.push({ id: folderId, name: project.name, description: project.description || null });
         }
         catch (e) {
-            failed.push({ name: project.name, error: e.response?.status || e.message });
+            failed.push({ name: project.name, error: formatApiError(e) });
         }
     }
     return { created, failed };
@@ -265,7 +269,7 @@ export async function seatOptimization(config, params) {
         }
         catch (e) {
             membersComplete = false;
-            warnings.push(`members: pagination stopped at page ${page + 1}, fetched ${allMembers.length} members (${e.response?.status || e.message})`);
+            warnings.push(`members: pagination stopped at page ${page + 1}, fetched ${allMembers.length} members (${formatApiError(e)})`);
             break;
         }
     }
@@ -584,6 +588,7 @@ export async function branchCleanup(config, params) {
         });
         archived = true;
     }
+    const archived_count = archived ? staleBranches.length : 0;
     const recommendations = [];
     if (staleBranches.length > 0) {
         recommendations.push(`${staleBranches.length} branch(es) stale for ${days_stale}+ days. ${dry_run ? 'Set dry_run=false to archive.' : 'Archived.'}`);
@@ -606,6 +611,7 @@ export async function branchCleanup(config, params) {
         active_branches: activeBranches,
         dry_run,
         archived,
+        archived_count,
         recommendations,
     };
 }

package/dist/operations/files.js

@@ -1,5 +1,5 @@
 import { internalClient } from '../clients/internal-api.js';
-import { resolveOrgId } from '../tools/register.js';
+import { resolveOrgId } from '../helpers.js';
 export async function createFile(config, params) {
     const res = await internalClient(config).post('/api/files/create', {
         folder_id: params.project_id,

package/dist/operations/libraries.js

@@ -1,5 +1,5 @@
 import { internalClient } from '../clients/internal-api.js';
-import { requireOrgId } from '../tools/register.js';
+import { requireOrgId } from '../helpers.js';
 export async function listOrgLibraries(config, params) {
     const orgId = requireOrgId(config, params.org_id);
     const res = await internalClient(config).get('/api/design_systems/libraries', {

package/dist/operations/org.js

@@ -1,5 +1,5 @@
 import { internalClient } from '../clients/internal-api.js';
-import { requireOrgId } from '../tools/register.js';
+import { requireOrgId } from '../helpers.js';
 // -- Seat constants --
 export const SEAT_HIERARCHY = {
     view: 0,

package/dist/operations/reading.js

@@ -1,4 +1,6 @@
 import { publicClient } from '../clients/public-api.js';
+// WARNING: Response can be very large for complex files. Callers should
+// encourage use of depth and node_id params to limit payload size.
 export async function getFile(config, params) {
     const queryParams = {};
     if (params.depth !== undefined)

package/dist/operations/teams.js

@@ -1,5 +1,5 @@
 import { internalClient } from '../clients/internal-api.js';
-import { requireOrgId } from '../tools/register.js';
+import { requireOrgId } from '../helpers.js';
 export async function createTeam(config, params) {
     const orgId = requireOrgId(config, params.org_id);
     const res = await internalClient(config).post('/api/teams/create', { team_name: params.name, org_id: orgId, sharing_audience_control: 'org_view' });

package/dist/operations/variables.js

@@ -24,6 +24,17 @@ export async function updateVariables(config, params) {
         !params.variable_mode_values?.length) {
         throw new Error('At least one operation array is required.');
     }
+    const allOps = [
+        ...(params.variable_collections || []),
+        ...(params.variable_modes || []),
+        ...(params.variables || []),
+        ...(params.variable_mode_values || []),
+    ];
+    for (const op of allOps) {
+        if (!op.action || !['CREATE', 'UPDATE', 'DELETE'].includes(op.action)) {
+            throw new Error(`Each operation must have an action field (CREATE, UPDATE, or DELETE). Got: ${JSON.stringify(op.action)}`);
+        }
+    }
     const body = {};
     if (params.variable_collections)
         body.variableCollections = params.variable_collections;

package/dist/operations/webhooks.d.ts

@@ -3,7 +3,10 @@ export type WebhookEventType = 'FILE_UPDATE' | 'FILE_DELETE' | 'FILE_VERSION_UPD
 export type WebhookStatus = 'ACTIVE' | 'PAUSED';
 export declare function listWebhooks(config: AuthConfig, params: {
     team_id: string;
-}): Promise<any[]>;
+}): Promise<{
+    count: number;
+    webhooks: any[];
+}>;
 export declare function createWebhook(config: AuthConfig, params: {
     team_id: string;
     event_type: WebhookEventType;

package/dist/operations/webhooks.js

@@ -1,7 +1,8 @@
 import { publicClient } from '../clients/public-api.js';
 export async function listWebhooks(config, params) {
     const res = await publicClient(config).get(`/v2/teams/${params.team_id}/webhooks`);
-    return res.data?.webhooks || [];
+    const webhooks = res.data?.webhooks || [];
+    return { count: webhooks.length, webhooks };
 }
 export async function createWebhook(config, params) {
     const body = {

package/dist/tools/analytics.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { libraryUsage, componentUsage } from '../operations/analytics.js';
 // -- library_usage --
 defineTool({
@@ -15,10 +16,10 @@ defineTool({
         }, async ({ library_file_key, days }) => {
             try {
                 const result = await libraryUsage(config, { library_file_key, days });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Library usage:', result);
             }
             catch (e) {
-                return toolError(`Failed to fetch library usage: ${e.response?.status || e.message}`);
+                return toolError(`Failed to fetch library usage: ${formatApiError(e)}`);
             }
         });
     },
@@ -37,10 +38,10 @@ defineTool({
         }, async ({ component_key, org_id }) => {
             try {
                 const result = await componentUsage(config, { component_key, org_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Component usage:', result);
             }
             catch (e) {
-                return toolError(`Failed to fetch component usage: ${e.response?.status || e.message}`);
+                return toolError(`Failed to fetch component usage: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/branching.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { listBranches, createBranch, deleteBranch } from '../operations/branching.js';
 // -- list_branches --
 defineTool({
@@ -16,10 +17,10 @@ defineTool({
                 const result = await listBranches(config, { file_key });
                 if (result.length === 0)
                     return toolResult('No branches found.');
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`${result.length} branch(es).`, result, 'Use create_branch to add a branch, or delete_branch to archive one.');
             }
             catch (e) {
-                return toolError(`Failed to list branches: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list branches: ${formatApiError(e)}`);
             }
         });
     },
@@ -39,10 +40,10 @@ defineTool({
         }, async ({ file_key, name }) => {
             try {
                 const result = await createBranch(config, { file_key, name });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Created branch.', result, 'Use get_file with the branch file key to read the branch.');
             }
             catch (e) {
-                return toolError(`Failed to create branch: ${e.response?.status || e.message}`);
+                return toolError(`Failed to create branch: ${formatApiError(e)}`);
             }
         });
     },
@@ -66,7 +67,7 @@ defineTool({
                 return toolResult(`Archived branch ${branch_key}`);
             }
             catch (e) {
-                return toolError(`Failed to delete branch: ${e.response?.status || e.message}`);
+                return toolError(`Failed to delete branch: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/comments.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { listComments, formatCommentsAsMarkdown, postComment, deleteComment, listCommentReactions, } from '../operations/comments.js';
 // -- list_comments --
 defineTool({
@@ -18,10 +19,12 @@ defineTool({
                 if (as_md) {
                     return toolResult(formatCommentsAsMarkdown(comments));
                 }
-                return toolResult(JSON.stringify(comments, null, 2));
+                if (comments.length === 0)
+                    return toolResult('No comments on this file.');
+                return toolSummary(`${comments.length} comment(s).`, comments, 'Use post_comment to reply, or delete_comment to remove.');
             }
             catch (e) {
-                return toolError(`Failed to list comments: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list comments: ${formatApiError(e)}`);
             }
         });
     },
@@ -43,10 +46,10 @@ defineTool({
         }, async ({ file_key, message, comment_id, node_id }) => {
             try {
                 const result = await postComment(config, { file_key, message, comment_id, node_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Posted comment.', result);
             }
             catch (e) {
-                return toolError(`Failed to post comment: ${e.response?.status || e.message}`);
+                return toolError(`Failed to post comment: ${formatApiError(e)}`);
             }
         });
     },
@@ -59,7 +62,7 @@ defineTool({
     destructive: true,
     register(server, config) {
         server.registerTool('delete_comment', {
-            description: 'Permanently delete a comment. For top-level comments, the entire thread is removed.',
+            description: 'Permanently delete a comment. For top-level comments, the entire thread is removed. Cannot be undone.',
             inputSchema: {
                 file_key: figmaId.describe('File key'),
                 comment_id: figmaId.describe('Comment ID to delete'),
@@ -70,7 +73,7 @@ defineTool({
                 return toolResult(`Deleted comment ${comment_id}`);
             }
             catch (e) {
-                return toolError(`Failed to delete comment: ${e.response?.status || e.message}`);
+                return toolError(`Failed to delete comment: ${formatApiError(e)}`);
             }
         });
     },
@@ -89,10 +92,12 @@ defineTool({
         }, async ({ file_key, comment_id }) => {
             try {
                 const reactions = await listCommentReactions(config, { file_key, comment_id });
-                return toolResult(JSON.stringify(reactions, null, 2));
+                if (reactions.length === 0)
+                    return toolResult('No reactions on this comment.');
+                return toolSummary(`${reactions.length} reaction(s).`, reactions);
             }
             catch (e) {
-                return toolError(`Failed to list reactions: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list reactions: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/components.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { listFileComponents, listFileStyles, listTeamComponents, listTeamStyles, } from '../operations/components.js';
 // -- list_file_components --
 defineTool({
@@ -7,17 +8,19 @@ defineTool({
     auth: 'pat',
     register(server, config) {
         server.registerTool('list_file_components', {
-            description: 'List components published from a specific file.',
+            description: 'List components published from a file. Only published library components appear -- local unpublished components are not included.',
             inputSchema: {
                 file_key: figmaId.describe('File key'),
             },
         }, async ({ file_key }) => {
             try {
-                const components = await listFileComponents(config, { file_key });
-                return toolResult(JSON.stringify(components, null, 2));
+                const result = await listFileComponents(config, { file_key });
+                if (result.count === 0)
+                    return toolResult('No published components in this file. Components must be published to appear.');
+                return toolSummary(`${result.count} published component(s).`, result);
             }
             catch (e) {
-                return toolError(`Failed to list file components: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list file components: ${formatApiError(e)}`);
             }
         });
     },
@@ -28,17 +31,19 @@ defineTool({
     auth: 'pat',
     register(server, config) {
         server.registerTool('list_file_styles', {
-            description: 'List styles in a specific file.',
+            description: 'List styles published from a file. Only published library styles appear.',
             inputSchema: {
                 file_key: figmaId.describe('File key'),
             },
         }, async ({ file_key }) => {
             try {
-                const styles = await listFileStyles(config, { file_key });
-                return toolResult(JSON.stringify(styles, null, 2));
+                const result = await listFileStyles(config, { file_key });
+                if (result.count === 0)
+                    return toolResult('No published styles in this file.');
+                return toolSummary(`${result.count} published style(s).`, result);
             }
             catch (e) {
-                return toolError(`Failed to list file styles: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list file styles: ${formatApiError(e)}`);
             }
         });
     },
@@ -49,7 +54,7 @@ defineTool({
     auth: 'pat',
     register(server, config) {
         server.registerTool('list_team_components', {
-            description: 'List published components across a team. Supports pagination.',
+            description: 'List published components across a team. Pass the cursor from the response\'s pagination object to fetch the next page.',
             inputSchema: {
                 team_id: figmaId.describe('Team ID'),
                 page_size: z.number().optional().default(30).describe('Max items per page (default: 30)'),
@@ -58,10 +63,12 @@ defineTool({
         }, async ({ team_id, page_size, cursor }) => {
             try {
                 const result = await listTeamComponents(config, { team_id, page_size, cursor });
-                return toolResult(JSON.stringify(result, null, 2));
+                const count = result.components?.length || 0;
+                const hasMore = !!result.pagination?.cursor;
+                return toolSummary(`${count} component(s)${hasMore ? ' (more pages available)' : ''}.`, result, hasMore ? 'Pass the cursor from pagination to fetch the next page.' : undefined);
             }
             catch (e) {
-                return toolError(`Failed to list team components: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list team components: ${formatApiError(e)}`);
             }
         });
     },
@@ -72,7 +79,7 @@ defineTool({
     auth: 'pat',
     register(server, config) {
         server.registerTool('list_team_styles', {
-            description: 'List published styles across a team. Supports pagination.',
+            description: 'List published styles across a team. Pass the cursor from the response\'s pagination object to fetch the next page.',
             inputSchema: {
                 team_id: figmaId.describe('Team ID'),
                 page_size: z.number().optional().default(30).describe('Max items per page (default: 30)'),
@@ -81,10 +88,12 @@ defineTool({
         }, async ({ team_id, page_size, cursor }) => {
             try {
                 const result = await listTeamStyles(config, { team_id, page_size, cursor });
-                return toolResult(JSON.stringify(result, null, 2));
+                const count = result.styles?.length || 0;
+                const hasMore = !!result.pagination?.cursor;
+                return toolSummary(`${count} style(s)${hasMore ? ' (more pages available)' : ''}.`, result, hasMore ? 'Pass the cursor from pagination to fetch the next page.' : undefined);
             }
             catch (e) {
-                return toolError(`Failed to list team styles: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list team styles: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/compound-manager.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { offboardUser, onboardUser, quarterlyDesignOpsReport, } from '../operations/compound-manager.js';
 // -- offboard_user --
 defineTool({
@@ -24,10 +25,11 @@ defineTool({
                     transfer_to,
                     org_id,
                 });
-                return toolResult(JSON.stringify(result, null, 2));
+                const mode = (execute ?? false) ? 'Offboarding complete.' : 'Offboarding audit (read-only). Set execute=true to proceed.';
+                return toolSummary(mode, result);
             }
             catch (e) {
-                return toolError(`Failed to audit user for offboarding: ${e.response?.status || e.message}`);
+                return toolError(`Failed to audit user for offboarding: ${formatApiError(e)}`);
             }
         });
     },
@@ -60,10 +62,10 @@ defineTool({
                     confirm,
                     org_id,
                 });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`Onboarding complete for ${email}.`, result);
             }
             catch (e) {
-                return toolError(`Failed to onboard user: ${e.response?.status || e.message}`);
+                return toolError(`Failed to onboard user: ${formatApiError(e)}`);
             }
         });
     },
@@ -85,10 +87,11 @@ defineTool({
                     org_id,
                     days: days ?? 90,
                 });
-                return toolResult(JSON.stringify(result, null, 2));
+                const highlightText = result.highlights?.join(' ') || 'Report generated.';
+                return toolSummary(highlightText, result);
             }
             catch (e) {
-                return toolError(`Failed to generate design ops report: ${e.response?.status || e.message}`);
+                return toolError(`Failed to generate design ops report: ${formatApiError(e)}`);
             }
         });
     },