figmanage 1.3.8 → 1.4.0

package/dist/operations/org.js

@@ -24,6 +24,16 @@ export const SEAT_KEY_TO_TYPE = {
     developer: 'dev',
     collaborator: 'collab',
 };
+// -- Helpers --
+/** Resolve a billing plan_id from a team's folders. */
+export async function resolvePlanId(client, teamId) {
+    const foldersRes = await client.get(`/api/teams/${teamId}/folders`);
+    const folders = foldersRes.data?.meta?.folder_rows || foldersRes.data?.meta || foldersRes.data || [];
+    const folder = (Array.isArray(folders) ? folders : []).find((f) => f.plan_id);
+    if (!folder?.plan_id)
+        throw new Error('No billing plan found for this team. Try providing plan_id directly.');
+    return folder.plan_id;
+}
 export async function listAdmins(config, params) {
     const orgId = requireOrgId(config, params.org_id);
     const res = await internalClient(config).get(`/api/orgs/${orgId}/admins`, { params: { include_license_admins: params.include_license_admins ?? false } });
@@ -121,7 +131,9 @@ export async function orgDomains(config, params) {
     return response;
 }
 export async function aiCreditUsage(config, params) {
-    const res = await internalClient(config).get(`/api/plans/${params.plan_id}/ai_credits/plan_usage_summary`);
+    const client = internalClient(config);
+    const planId = params.plan_id || await resolvePlanId(client, params.team_id);
+    const res = await client.get(`/api/plans/${planId}/ai_credits/plan_usage_summary`);
     return res.data;
 }
 export async function exportMembers(config, params) {
@@ -202,4 +214,103 @@ export async function changeSeat(config, params) {
         new_seat: SEAT_LABELS[params.seat_type],
     };
 }
+export async function activityLog(config, params) {
+    const orgId = requireOrgId(config, params.org_id);
+    const now = new Date();
+    const thirtyDaysAgo = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000);
+    const reqParams = {
+        org_id: orgId,
+        page_size: String(params.page_size || 50),
+        start_time: params.start_time || thirtyDaysAgo.toISOString().split('T')[0],
+        end_time: params.end_time || now.toISOString(),
+        emails: params.emails || '',
+    };
+    if (params.after)
+        reqParams.after = params.after;
+    const res = await internalClient(config).get('/api/activity_logs', { params: reqParams });
+    const meta = res.data?.meta;
+    const rawLogs = Array.isArray(meta) && meta.length > 0 ? meta[0] : [];
+    const pagination = Array.isArray(meta) && meta.length > 1 ? meta[1] : undefined;
+    const entries = (Array.isArray(rawLogs) ? rawLogs : []).map((e) => ({
+        id: e.id,
+        timestamp: e.created_at,
+        event: e.event_name,
+        actor: e.actor ? { id: e.actor.id, email: e.actor.email, name: e.actor.name } : null,
+        team: e.metadata?.team_name || null,
+        ip_address: e.ip_address || null,
+        target: e.acted_on_type ? { type: e.acted_on_type, id_or_key: e.acted_on_id_or_key } : null,
+        metadata: e.metadata || null,
+    }));
+    const result = { entries };
+    if (pagination?.after) {
+        result.pagination = { after: pagination.after, column: pagination.column };
+    }
+    return result;
+}
+export async function listPayments(config, params) {
+    const orgId = requireOrgId(config, params.org_id);
+    const res = await internalClient(config).get(`/api/orgs/${orgId}/billing_data`);
+    const invoices = res.data?.meta?.invoices || [];
+    return invoices.filter((inv) => inv.status === 'paid');
+}
+// -- Org member removal --
+export async function removeOrgMember(config, params) {
+    if (!params.confirm) {
+        throw new Error('Removing a member from the org is permanent and cannot be undone. ' +
+            'They lose access to all teams, projects, files, and apps. ' +
+            'Their drafts move to Unassigned drafts. Any paid seats are freed. ' +
+            'Set confirm: true to proceed.');
+    }
+    const orgId = requireOrgId(config, params.org_id);
+    const client = internalClient(config);
+    // Resolve org_user_id
+    const res = await client.get(`/api/v2/orgs/${orgId}/org_users`, {
+        params: params.user_identifier.includes('@') ? { search_query: params.user_identifier } : {},
+    });
+    const users = res.data?.meta?.users || res.data?.meta || res.data || [];
+    const members = Array.isArray(users) ? users : [];
+    const member = members.find((m) => params.user_identifier.includes('@')
+        ? m.user?.email === params.user_identifier
+        : String(m.user_id) === String(params.user_identifier));
+    if (!member)
+        throw new Error(`User not found: ${params.user_identifier}`);
+    if (String(member.user_id) === String(config.userId)) {
+        throw new Error('Cannot remove yourself from the org.');
+    }
+    await client.delete(`/api/orgs/${orgId}/org_users`, {
+        data: { org_user_ids: [String(member.id)] },
+    });
+    return `Removed ${member.user?.handle || member.user?.email || params.user_identifier} from the org. This cannot be undone.`;
+}
+export async function createUserGroup(config, params) {
+    const client = internalClient(config);
+    let planId = params.plan_id;
+    if (!planId) {
+        if (!params.team_id)
+            throw new Error('Either team_id or plan_id is required to create a user group.');
+        planId = await resolvePlanId(client, params.team_id);
+    }
+    const res = await client.post('/api/user_groups', {
+        name: params.name,
+        description: params.description || '',
+        plan_id: planId,
+        emails: params.emails || [],
+        should_notify: params.should_notify ?? true,
+    });
+    return res.data?.meta || res.data;
+}
+export async function deleteUserGroups(config, params) {
+    await internalClient(config).delete('/api/user_groups', {
+        data: { user_group_ids: params.user_group_ids },
+    });
+    return `Deleted ${params.user_group_ids.length} user group(s).`;
+}
+export async function addUserGroupMembers(config, params) {
+    const res = await internalClient(config).put(`/api/user_groups/${params.user_group_id}/add_members`, { emails: params.emails });
+    return res.data?.meta || res.data;
+}
+export async function removeUserGroupMembers(config, params) {
+    await internalClient(config).put(`/api/user_groups/${params.user_group_id}/remove_members`, { user_ids: params.user_ids });
+    return `Removed ${params.user_ids.length} member(s) from group.`;
+}
 //# sourceMappingURL=org.js.map

package/dist/operations/teams.d.ts

@@ -11,6 +11,15 @@ export declare function renameTeam(config: AuthConfig, params: {
     team_id: string;
     name: string;
 }): Promise<string>;
+export declare function addTeamMember(config: AuthConfig, params: {
+    team_id: string;
+    email: string;
+    level?: number;
+}): Promise<string>;
+export declare function removeTeamMember(config: AuthConfig, params: {
+    team_id: string;
+    user_id: string;
+}): Promise<string>;
 export declare function deleteTeam(config: AuthConfig, params: {
     team_id: string;
 }): Promise<string>;

package/dist/operations/teams.js

@@ -10,6 +10,29 @@ export async function renameTeam(config, params) {
     await internalClient(config).put(`/api/teams/${params.team_id}`, { name: params.name });
     return `Team ${params.team_id} renamed to "${params.name}".`;
 }
+export async function addTeamMember(config, params) {
+    await internalClient(config).post('/api/invites', {
+        emails: [params.email],
+        resource_type: 'team',
+        resource_id_or_key: params.team_id,
+        level: params.level ?? 100,
+        user_group_ids: [],
+    });
+    return `Invited ${params.email} to team ${params.team_id}.`;
+}
+export async function removeTeamMember(config, params) {
+    const res = await internalClient(config).get(`/api/teams/${params.team_id}/members`);
+    const members = res.data?.meta || res.data || [];
+    const list = Array.isArray(members) ? members : [];
+    const member = list.find((m) => String(m.id) === String(params.user_id) || m.email === params.user_id);
+    if (!member)
+        throw new Error(`User not found in team: ${params.user_id}`);
+    const roleId = member.team_role?.id;
+    if (!roleId)
+        throw new Error(`User has no direct team role to remove (may have org-level access).`);
+    await internalClient(config).delete(`/api/roles/${roleId}`);
+    return `Removed ${member.name || member.email} from team ${params.team_id}.`;
+}
 export async function deleteTeam(config, params) {
     await internalClient(config).delete(`/api/teams/${params.team_id}`);
     return `Team ${params.team_id} deleted.`;

package/dist/operations/webhooks.d.ts

@@ -22,6 +22,20 @@ export declare function updateWebhook(config: AuthConfig, params: {
     description?: string;
     status?: WebhookStatus;
 }): Promise<Record<string, any>>;
+export interface WebhookRequest {
+    id: string;
+    endpoint: string;
+    payload: Record<string, any> | null;
+    status: number | null;
+    error: string | null;
+    sent_at: string;
+}
+export declare function webhookRequests(config: AuthConfig, params: {
+    webhook_id: string;
+}): Promise<{
+    count: number;
+    requests: WebhookRequest[];
+}>;
 export declare function deleteWebhook(config: AuthConfig, params: {
     webhook_id: string;
 }): Promise<void>;

package/dist/operations/webhooks.js

@@ -33,6 +33,18 @@ export async function updateWebhook(config, params) {
     const { passcode: _, ...safe } = res.data || {};
     return safe;
 }
+export async function webhookRequests(config, params) {
+    const res = await publicClient(config).get(`/v2/webhooks/${params.webhook_id}/requests`);
+    const requests = (res.data?.requests || []).map((r) => ({
+        id: r.id,
+        endpoint: r.endpoint,
+        payload: r.payload || null,
+        status: r.response_status_code ?? null,
+        error: r.error_msg || null,
+        sent_at: r.sent_at,
+    }));
+    return { count: requests.length, requests };
+}
 export async function deleteWebhook(config, params) {
     await publicClient(config).delete(`/v2/webhooks/${params.webhook_id}`);
 }

package/dist/tools/analytics.js

@@ -5,6 +5,7 @@ import { libraryUsage, componentUsage } from '../operations/analytics.js';
 // -- library_usage --
 defineTool({
     toolset: 'analytics',
+    adminOnly: true,
     auth: 'cookie',
     register(server, config) {
         server.registerTool('library_usage', {
@@ -27,6 +28,7 @@ defineTool({
 // -- component_usage --
 defineTool({
     toolset: 'analytics',
+    adminOnly: true,
     auth: 'cookie',
     register(server, config) {
         server.registerTool('component_usage', {

package/dist/tools/comments.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
 import { formatApiError } from '../helpers.js';
-import { listComments, formatCommentsAsMarkdown, postComment, deleteComment, listCommentReactions, } from '../operations/comments.js';
+import { listComments, formatCommentsAsMarkdown, postComment, deleteComment, resolveComment, editComment, addCommentReaction, removeCommentReaction, listCommentReactions, } from '../operations/comments.js';
 // -- list_comments --
 defineTool({
     toolset: 'comments',
@@ -21,7 +21,7 @@ defineTool({
                 }
                 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.');
+                return toolSummary(`${comments.length} comment(s).`, comments, 'Use post_comment to reply, resolve_comment to close threads, or delete_comment to remove.');
             }
             catch (e) {
                 return toolError(`Failed to list comments: ${formatApiError(e)}`);
@@ -94,7 +94,7 @@ defineTool({
                 const reactions = await listCommentReactions(config, { file_key, comment_id });
                 if (reactions.length === 0)
                     return toolResult('No reactions on this comment.');
-                return toolSummary(`${reactions.length} reaction(s).`, reactions);
+                return toolSummary(`${reactions.length} reaction(s).`, reactions, 'Use add_comment_reaction or remove_comment_reaction to manage.');
             }
             catch (e) {
                 return toolError(`Failed to list reactions: ${formatApiError(e)}`);
@@ -102,4 +102,100 @@ defineTool({
         });
     },
 });
+// -- resolve_comment --
+defineTool({
+    toolset: 'comments',
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('resolve_comment', {
+            description: 'Resolve or unresolve a comment thread. Resolved comments are collapsed in the Figma UI.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+                comment_id: figmaId.describe('Comment ID to resolve'),
+                resolved: z.boolean().optional().describe('true to resolve (default), false to unresolve'),
+            },
+        }, async ({ file_key, comment_id, resolved }) => {
+            try {
+                const msg = await resolveComment(config, { file_key, comment_id, resolved });
+                return toolResult(msg);
+            }
+            catch (e) {
+                return toolError(`Failed to resolve comment: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
+// -- edit_comment --
+defineTool({
+    toolset: 'comments',
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('edit_comment', {
+            description: 'Edit the text of an existing comment.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+                comment_id: figmaId.describe('Comment ID'),
+                message: z.string().describe('New comment text'),
+            },
+        }, async ({ file_key, comment_id, message }) => {
+            try {
+                const msg = await editComment(config, { file_key, comment_id, message });
+                return toolResult(msg);
+            }
+            catch (e) {
+                return toolError(`Failed to edit comment: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
+// -- add_comment_reaction --
+defineTool({
+    toolset: 'comments',
+    auth: 'pat',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('add_comment_reaction', {
+            description: 'Add an emoji reaction to a comment.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+                comment_id: figmaId.describe('Comment ID'),
+                emoji: z.string().describe('Emoji shortcode (e.g. ":thumbsup:", ":heart:")'),
+            },
+        }, async ({ file_key, comment_id, emoji }) => {
+            try {
+                const result = await addCommentReaction(config, { file_key, comment_id, emoji });
+                return toolSummary(`Added ${result.emoji} reaction.`, result);
+            }
+            catch (e) {
+                return toolError(`Failed to add reaction: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
+// -- remove_comment_reaction --
+defineTool({
+    toolset: 'comments',
+    auth: 'pat',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('remove_comment_reaction', {
+            description: 'Remove your emoji reaction from a comment.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+                comment_id: figmaId.describe('Comment ID'),
+                emoji: z.string().describe('Emoji shortcode to remove (e.g. ":thumbsup:")'),
+            },
+        }, async ({ file_key, comment_id, emoji }) => {
+            try {
+                await removeCommentReaction(config, { file_key, comment_id, emoji });
+                return toolResult(`Removed ${emoji} reaction from comment ${comment_id}.`);
+            }
+            catch (e) {
+                return toolError(`Failed to remove reaction: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
 //# sourceMappingURL=comments.js.map

package/dist/tools/compound-manager.js

@@ -8,21 +8,24 @@ defineTool({
     auth: 'cookie',
     mutates: true,
     destructive: true,
+    adminOnly: true,
     register(server, config) {
         server.registerTool('offboard_user', {
-            description: 'Audit and optionally execute user offboarding. Default: read-only audit. With execute=true: transfers file ownership, revokes access, downgrades seat.',
+            description: 'Audit and optionally execute user offboarding. Default: read-only audit. With execute=true: transfers file ownership, revokes access, downgrades seat. With remove_from_org=true: also permanently removes the user from the org (cannot be undone).',
             inputSchema: {
                 user_identifier: z.string().describe('Email or user_id of the user to offboard'),
                 execute: z.boolean().optional().default(false).describe('Execute the offboarding (default: false, audit only)'),
                 transfer_to: z.string().optional().describe('Email or user_id to transfer file ownership to (required if user owns files and execute=true)'),
+                remove_from_org: z.boolean().optional().default(false).describe('Permanently remove from org after offboarding (cannot be undone). Requires execute=true.'),
                 org_id: figmaId.optional().describe('Org ID override (defaults to current workspace)'),
             },
-        }, async ({ user_identifier, execute, transfer_to, org_id }) => {
+        }, async ({ user_identifier, execute, transfer_to, remove_from_org, org_id }) => {
             try {
                 const result = await offboardUser(config, {
                     user_identifier,
                     execute: execute ?? false,
                     transfer_to,
+                    remove_from_org: remove_from_org ?? false,
                     org_id,
                 });
                 const mode = (execute ?? false) ? 'Offboarding complete.' : 'Offboarding audit (read-only). Set execute=true to proceed.';
@@ -39,6 +42,7 @@ defineTool({
     toolset: 'compound',
     auth: 'cookie',
     mutates: true,
+    adminOnly: true,
     register(server, config) {
         server.registerTool('onboard_user', {
             description: 'Invite a user to teams and optionally share files and set seat type. Sends invite emails per team.',
@@ -74,6 +78,7 @@ defineTool({
 defineTool({
     toolset: 'compound',
     auth: 'cookie',
+    adminOnly: true,
     register(server, config) {
         server.registerTool('quarterly_design_ops_report', {
             description: 'Org-wide design ops snapshot: seat utilization, team activity, billing, and library adoption over a given period.',

package/dist/tools/compound.js

@@ -27,6 +27,7 @@ defineTool({
 defineTool({
     toolset: 'compound',
     auth: 'cookie',
+    adminOnly: true,
     register(server, config) {
         server.registerTool('workspace_overview', {
             description: 'Full org snapshot: teams with member/project counts, seat breakdown, and billing summary.',
@@ -152,6 +153,7 @@ defineTool({
 defineTool({
     toolset: 'compound',
     auth: 'cookie',
+    adminOnly: true,
     register(server, config) {
         server.registerTool('seat_optimization', {
             description: 'Identify inactive paid seats and calculate potential savings. Fetches members, seat counts, and pricing to find optimization opportunities.',
@@ -182,6 +184,7 @@ defineTool({
 defineTool({
     toolset: 'compound',
     auth: 'cookie',
+    adminOnly: true,
     register(server, config) {
         server.registerTool('permission_audit', {
             description: 'Audit permissions across a team or project. Scans files for external editors, open link access, and elevated individual permissions.',

package/dist/tools/dev-resources.d.ts

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

package/dist/tools/dev-resources.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
+import { listDevResources, createDevResource, deleteDevResource, } from '../operations/dev-resources.js';
+// -- list_dev_resources --
+defineTool({
+    toolset: 'components',
+    auth: 'pat',
+    register(server, config) {
+        server.registerTool('list_dev_resources', {
+            description: 'List dev resources (links, annotations) attached to nodes in a file. Used in Dev Mode.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+                node_ids: z.array(figmaId).optional().describe('Filter by specific node IDs'),
+            },
+        }, async ({ file_key, node_ids }) => {
+            try {
+                const result = await listDevResources(config, { file_key, node_ids });
+                if (result.length === 0)
+                    return toolResult('No dev resources found.');
+                return toolSummary(`${result.length} dev resource(s).`, result, 'Use create_dev_resource to add, or delete_dev_resource to remove.');
+            }
+            catch (e) {
+                return toolError(`Failed to list dev resources: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
+// -- create_dev_resource --
+defineTool({
+    toolset: 'components',
+    auth: 'pat',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('create_dev_resource', {
+            description: 'Create a dev resource (link/annotation) on a node. Visible in Dev Mode.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+                node_id: figmaId.describe('Node ID to attach the resource to'),
+                name: z.string().describe('Resource name/label'),
+                url: z.string().describe('Resource URL'),
+            },
+        }, async ({ file_key, node_id, name, url }) => {
+            try {
+                const result = await createDevResource(config, { file_key, node_id, name, url });
+                return toolSummary('Created dev resource.', result);
+            }
+            catch (e) {
+                return toolError(`Failed to create dev resource: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
+// -- delete_dev_resource --
+defineTool({
+    toolset: 'components',
+    auth: 'pat',
+    mutates: true,
+    destructive: true,
+    register(server, config) {
+        server.registerTool('delete_dev_resource', {
+            description: 'Delete a dev resource from a file.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+                dev_resource_id: figmaId.describe('Dev resource ID (from list_dev_resources)'),
+            },
+        }, async ({ file_key, dev_resource_id }) => {
+            try {
+                await deleteDevResource(config, { file_key, dev_resource_id });
+                return toolResult(`Deleted dev resource ${dev_resource_id}.`);
+            }
+            catch (e) {
+                return toolError(`Failed to delete dev resource: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
+//# sourceMappingURL=dev-resources.js.map