figmanage 1.0.1 → 1.2.0

package/dist/cli/components.js

@@ -0,0 +1,82 @@
+import { Command } from 'commander';
+import { listFileComponents, listFileStyles, listTeamComponents, listTeamStyles, } from '../operations/components.js';
+import { output, error } from './format.js';
+import { requirePat } from './helpers.js';
+export function componentsCommand() {
+    const components = new Command('components')
+        .description('Manage components and styles');
+    components
+        .command('list-file-components <file-key>')
+        .description('List components published from a specific file')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requirePat();
+            const result = await listFileComponents(config, { file_key: fileKey });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    components
+        .command('list-file-styles <file-key>')
+        .description('List styles in a specific file')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requirePat();
+            const result = await listFileStyles(config, { file_key: fileKey });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    components
+        .command('list-team-components <team-id>')
+        .description('List published components across a team')
+        .option('--page-size <n>', 'Max items per page (default: 30)')
+        .option('--cursor <cursor>', 'Pagination cursor from previous response')
+        .option('--json', 'Force JSON output')
+        .action(async (teamId, options) => {
+        try {
+            const config = requirePat();
+            const result = await listTeamComponents(config, {
+                team_id: teamId,
+                page_size: options.pageSize ? parseInt(options.pageSize, 10) : undefined,
+                cursor: options.cursor,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    components
+        .command('list-team-styles <team-id>')
+        .description('List published styles across a team')
+        .option('--page-size <n>', 'Max items per page (default: 30)')
+        .option('--cursor <cursor>', 'Pagination cursor from previous response')
+        .option('--json', 'Force JSON output')
+        .action(async (teamId, options) => {
+        try {
+            const config = requirePat();
+            const result = await listTeamStyles(config, {
+                team_id: teamId,
+                page_size: options.pageSize ? parseInt(options.pageSize, 10) : undefined,
+                cursor: options.cursor,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return components;
+}
+//# sourceMappingURL=components.js.map

package/dist/cli/compound-commands.d.ts

@@ -0,0 +1,14 @@
+import { Command } from 'commander';
+export declare function fileSummaryCommand(): Command;
+export declare function workspaceOverviewCommand(): Command;
+export declare function openCommentsCommand(): Command;
+export declare function cleanupStaleFilesCommand(): Command;
+export declare function organizeProjectCommand(): Command;
+export declare function setupProjectStructureCommand(): Command;
+export declare function seatOptimizationCommand(): Command;
+export declare function permissionAuditCommand(): Command;
+export declare function branchCleanupCommand(): Command;
+export declare function offboardUserCommand(): Command;
+export declare function onboardUserCommand(): Command;
+export declare function quarterlyReportCommand(): Command;
+//# sourceMappingURL=compound-commands.d.ts.map

package/dist/cli/compound-commands.js

@@ -0,0 +1,291 @@
+import { Command } from 'commander';
+import { fileSummary, workspaceOverview, openComments, cleanupStaleFiles, organizeProject, setupProjectStructure, seatOptimization, permissionAudit, branchCleanup, } from '../operations/compound.js';
+import { offboardUser, onboardUser, quarterlyDesignOpsReport, } from '../operations/compound-manager.js';
+import { output, error } from './format.js';
+import { requireAuth, requirePat, requireCookie, validateId, parsePositiveInt } from './helpers.js';
+// -- compound.ts tools --
+export function fileSummaryCommand() {
+    return new Command('summary')
+        .description('Quick overview of a Figma file')
+        .argument('<file-key>', 'File key')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            validateId(fileKey, 'file key');
+            const config = requirePat();
+            const result = await fileSummary(config, { file_key: fileKey });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+}
+export function workspaceOverviewCommand() {
+    return new Command('overview')
+        .description('Full org snapshot: teams, seats, and billing')
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            const config = requireCookie();
+            const result = await workspaceOverview(config, {});
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+}
+export function openCommentsCommand() {
+    return new Command('open')
+        .description('Aggregated unresolved comments across project files')
+        .argument('<project-id>', 'Project ID')
+        .option('--json', 'Force JSON output')
+        .action(async (projectId, options) => {
+        try {
+            validateId(projectId, 'project ID');
+            const config = requirePat();
+            const result = await openComments(config, { project_id: projectId });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+}
+export function cleanupStaleFilesCommand() {
+    return new Command('cleanup-stale')
+        .description('Find and optionally trash stale files in a project')
+        .argument('<project-id>', 'Project ID')
+        .option('--days-stale <days>', 'Days since last modification', '90')
+        .option('--execute', 'Trash stale files (default: dry run)')
+        .option('--json', 'Force JSON output')
+        .action(async (projectId, options) => {
+        try {
+            validateId(projectId, 'project ID');
+            const config = requireAuth();
+            const daysStale = parsePositiveInt(options.daysStale || '90', '--days-stale', 90);
+            const result = await cleanupStaleFiles(config, {
+                project_id: projectId,
+                days_stale: daysStale,
+                dry_run: !options.execute,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+}
+export function organizeProjectCommand() {
+    return new Command('organize')
+        .description('Move multiple files into a target project')
+        .requiredOption('--files <keys...>', 'File keys to move')
+        .requiredOption('--target <project-id>', 'Destination project ID')
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            for (const key of options.files)
+                validateId(key, 'file key');
+            validateId(options.target, 'target project ID');
+            const config = requireCookie();
+            const result = await organizeProject(config, {
+                file_keys: options.files,
+                target_project_id: options.target,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+}
+export function setupProjectStructureCommand() {
+    return new Command('setup-structure')
+        .description('Create multiple projects in a team from a JSON plan')
+        .argument('<team-id>', 'Team ID')
+        .requiredOption('--projects <json>', 'JSON array of {name, description?} objects')
+        .option('--json', 'Force JSON output')
+        .action(async (teamId, options) => {
+        try {
+            validateId(teamId, 'team ID');
+            let projects;
+            try {
+                projects = JSON.parse(options.projects);
+            }
+            catch {
+                error('--projects must be valid JSON. Example: \'[{"name":"Design","description":"Main design files"}]\'');
+                process.exit(1);
+            }
+            if (!Array.isArray(projects) || projects.length === 0) {
+                error('--projects must be a non-empty array.');
+                process.exit(1);
+            }
+            const config = requireCookie();
+            const result = await setupProjectStructure(config, { team_id: teamId, projects });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+}
+export function seatOptimizationCommand() {
+    return new Command('seat-optimization')
+        .description('Identify inactive paid seats and calculate savings')
+        .option('--days-inactive <days>', 'Days threshold', '90')
+        .option('--no-cost', 'Skip cost analysis')
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            const config = requireCookie();
+            const daysInactive = parsePositiveInt(options.daysInactive || '90', '--days-inactive', 90);
+            const result = await seatOptimization(config, {
+                days_inactive: daysInactive,
+                include_cost: options.cost !== false,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+}
+export function permissionAuditCommand() {
+    return new Command('audit')
+        .description('Audit permissions across a team or project')
+        .requiredOption('--scope <type>', 'Scope to audit: team or project', 'team')
+        .requiredOption('--id <id>', 'Team ID or project ID')
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            const scopeType = options.scope;
+            if (scopeType !== 'team' && scopeType !== 'project') {
+                error(`Invalid scope: ${scopeType}. Must be "team" or "project".`);
+                process.exit(1);
+            }
+            validateId(options.id, 'scope ID');
+            const config = requireCookie();
+            const result = await permissionAudit(config, {
+                scope_type: scopeType,
+                scope_id: options.id,
+                flag_external: true,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+}
+export function branchCleanupCommand() {
+    return new Command('cleanup')
+        .description('Find and optionally archive stale branches in a project')
+        .argument('<project-id>', 'Project ID')
+        .option('--days-stale <days>', 'Days threshold', '60')
+        .option('--execute', 'Archive stale branches (default: dry run)')
+        .option('--json', 'Force JSON output')
+        .action(async (projectId, options) => {
+        try {
+            validateId(projectId, 'project ID');
+            const config = requireAuth();
+            const daysStale = parsePositiveInt(options.daysStale || '60', '--days-stale', 60);
+            const result = await branchCleanup(config, {
+                project_id: projectId,
+                days_stale: daysStale,
+                dry_run: !options.execute,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+}
+// -- compound-manager.ts tools --
+export function offboardUserCommand() {
+    return new Command('offboard')
+        .description('Audit and optionally execute user offboarding')
+        .argument('<user>', 'Email or user_id to offboard')
+        .option('--execute', 'Execute the offboarding (default: audit only)')
+        .option('--transfer-to <user>', 'Email or user_id to transfer file ownership to')
+        .option('--json', 'Force JSON output')
+        .action(async (user, options) => {
+        try {
+            const config = requireCookie();
+            const result = await offboardUser(config, {
+                user_identifier: user,
+                execute: options.execute === true,
+                transfer_to: options.transferTo,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+}
+export function onboardUserCommand() {
+    return new Command('onboard')
+        .description('Invite a user to teams and optionally share files and set seat type')
+        .argument('<email>', 'Email address to invite')
+        .requiredOption('--teams <ids...>', 'Team IDs to invite the user to')
+        .option('--role <role>', 'Role for team access: editor or viewer', 'editor')
+        .option('--share-files <keys...>', 'File keys to share (viewer access)')
+        .option('--seat <type>', 'Seat type: full, dev, collab, view')
+        .option('--confirm', 'Required to execute seat change')
+        .option('--json', 'Force JSON output')
+        .action(async (email, options) => {
+        try {
+            for (const id of options.teams)
+                validateId(id, 'team ID');
+            if (options.shareFiles) {
+                for (const key of options.shareFiles)
+                    validateId(key, 'file key');
+            }
+            const config = requireCookie();
+            const result = await onboardUser(config, {
+                email,
+                team_ids: options.teams,
+                role: options.role || 'editor',
+                share_files: options.shareFiles,
+                seat_type: options.seat,
+                confirm: options.confirm,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+}
+export function quarterlyReportCommand() {
+    return new Command('quarterly-report')
+        .description('Org-wide design ops report: seats, teams, billing, library adoption')
+        .option('--days <days>', 'Lookback period in days', '90')
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            const config = requireCookie();
+            const days = parsePositiveInt(options.days || '90', '--days', 90);
+            const result = await quarterlyDesignOpsReport(config, { days });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=compound-commands.js.map

package/dist/cli/export.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function exportCommand(): Command;
+//# sourceMappingURL=export.d.ts.map

package/dist/cli/export.js

@@ -0,0 +1,51 @@
+import { Command } from 'commander';
+import { exportNodes, getImageFills } from '../operations/export.js';
+import { output, error } from './format.js';
+import { requirePat } from './helpers.js';
+export function exportCommand() {
+    const exp = new Command('export')
+        .description('Export images and fills from files');
+    exp
+        .command('nodes <file-key> <node-ids...>')
+        .description('Export nodes as images (returns temporary URLs)')
+        .option('--format <fmt>', 'Image format: png, svg, pdf, jpg (default: png)')
+        .option('--scale <n>', 'Scale factor, 0.01-4 (default: 1)')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, nodeIds, options) => {
+        try {
+            const config = requirePat();
+            const result = await exportNodes(config, {
+                file_key: fileKey,
+                node_ids: nodeIds,
+                format: options.format,
+                scale: options.scale ? parseFloat(options.scale) : undefined,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    exp
+        .command('image-fills <file-key>')
+        .description('Get download URLs for all images used as fills')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requirePat();
+            const result = await getImageFills(config, { file_key: fileKey });
+            if (result.length === 0) {
+                console.log('No image fills in this file.');
+                return;
+            }
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return exp;
+}
+//# sourceMappingURL=export.js.map

package/dist/cli/files.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function filesCommand(): Command;
+//# sourceMappingURL=files.d.ts.map

package/dist/cli/files.js

@@ -0,0 +1,156 @@
+import { Command } from 'commander';
+import { createFile, renameFile, moveFiles, duplicateFile, trashFiles, restoreFiles, favoriteFile, setLinkAccess, } from '../operations/files.js';
+import { output, error } from './format.js';
+import { requireCookie } from './helpers.js';
+export function filesCommand() {
+    const files = new Command('files')
+        .description('Manage Figma files');
+    files
+        .command('create <project-id>')
+        .description('Create a new file in a project')
+        .option('--editor-type <type>', 'File type: design, whiteboard, slides, sites', 'design')
+        .option('--org-id <id>', 'Org ID override')
+        .option('--json', 'Force JSON output')
+        .action(async (projectId, options) => {
+        try {
+            const config = requireCookie();
+            const result = await createFile(config, {
+                project_id: projectId,
+                editor_type: options.editorType,
+                org_id: options.orgId,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    files
+        .command('rename <file-key>')
+        .description('Rename a file')
+        .requiredOption('--name <name>', 'New name')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requireCookie();
+            await renameFile(config, { file_key: fileKey, name: options.name });
+            output({ renamed: fileKey, name: options.name }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    files
+        .command('move')
+        .description('Move files to a different project')
+        .requiredOption('--file-keys <keys>', 'Comma-separated file keys', (v) => v.split(','))
+        .requiredOption('--destination <project-id>', 'Destination project ID')
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            const config = requireCookie();
+            const result = await moveFiles(config, {
+                file_keys: options.fileKeys,
+                destination_project_id: options.destination,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    files
+        .command('duplicate <file-key>')
+        .description('Duplicate a file')
+        .option('--project-id <id>', 'Destination project ID')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requireCookie();
+            const result = await duplicateFile(config, {
+                file_key: fileKey,
+                project_id: options.projectId,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    files
+        .command('trash')
+        .description('Move files to trash')
+        .requiredOption('--file-keys <keys>', 'Comma-separated file keys', (v) => v.split(','))
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            const config = requireCookie();
+            const result = await trashFiles(config, { file_keys: options.fileKeys });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    files
+        .command('restore')
+        .description('Restore files from trash')
+        .requiredOption('--file-keys <keys>', 'Comma-separated file keys', (v) => v.split(','))
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            const config = requireCookie();
+            const result = await restoreFiles(config, { file_keys: options.fileKeys });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    files
+        .command('favorite <file-key>')
+        .description('Add or remove a file from favorites')
+        .option('--unfavorite', 'Remove from favorites')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requireCookie();
+            const result = await favoriteFile(config, {
+                file_key: fileKey,
+                favorited: !options.unfavorite,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    files
+        .command('link-access <file-key>')
+        .description('Set link access on a file')
+        .option('--level <level>', 'Access level: inherit, view, edit, org_view, org_edit', 'inherit')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requireCookie();
+            const result = await setLinkAccess(config, {
+                file_key: fileKey,
+                link_access: options.level,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return files;
+}
+//# sourceMappingURL=files.js.map