figmanage 1.0.1 → 1.1.0

package/dist/cli/permissions.js

@@ -0,0 +1,133 @@
+import { Command } from 'commander';
+import { getPermissions, setPermissions, share, revokeAccess, listRoleRequests, approveRoleRequest, denyRoleRequest, } from '../operations/permissions.js';
+import { output, error } from './format.js';
+import { requireCookie } from './helpers.js';
+export function permissionsCommand() {
+    const permissions = new Command('permissions')
+        .description('Manage file, project, and team permissions');
+    permissions
+        .command('get <resource-type> <resource-id>')
+        .description('See who has access to a file, project, or team')
+        .option('--json', 'Force JSON output')
+        .action(async (resourceType, resourceId, options) => {
+        try {
+            const config = requireCookie();
+            const result = await getPermissions(config, {
+                resource_type: resourceType,
+                resource_id: resourceId,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    permissions
+        .command('set <resource-type> <resource-id> <user-id> <role>')
+        .description('Change access level for a user on a file, project, or team')
+        .option('--json', 'Force JSON output')
+        .action(async (resourceType, resourceId, userId, role, options) => {
+        try {
+            const config = requireCookie();
+            const msg = await setPermissions(config, {
+                resource_type: resourceType,
+                resource_id: resourceId,
+                user_id: userId,
+                role,
+            });
+            output({ message: msg }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    permissions
+        .command('share <resource-type> <resource-id> <email>')
+        .description('Share a file or project with someone by email')
+        .option('--role <role>', 'Role to grant (editor or viewer)', 'viewer')
+        .option('--json', 'Force JSON output')
+        .action(async (resourceType, resourceId, email, options) => {
+        try {
+            const config = requireCookie();
+            const result = await share(config, {
+                resource_type: resourceType,
+                resource_id: resourceId,
+                email,
+                role: options.role,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    permissions
+        .command('revoke <resource-type> <resource-id> <user-id>')
+        .description("Remove someone's access to a file, project, or team")
+        .option('--json', 'Force JSON output')
+        .action(async (resourceType, resourceId, userId, options) => {
+        try {
+            const config = requireCookie();
+            const msg = await revokeAccess(config, {
+                resource_type: resourceType,
+                resource_id: resourceId,
+                user_id: userId,
+            });
+            output({ message: msg }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    permissions
+        .command('requests')
+        .description('List pending file access requests')
+        .option('--json', 'Force JSON output')
+        .action(async (options) => {
+        try {
+            const config = requireCookie();
+            const result = await listRoleRequests(config);
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    permissions
+        .command('approve <notification-id>')
+        .description('Approve a pending file access request')
+        .option('--json', 'Force JSON output')
+        .action(async (notificationId, options) => {
+        try {
+            const config = requireCookie();
+            const msg = await approveRoleRequest(config, { notification_id: notificationId });
+            output({ message: msg }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    permissions
+        .command('deny <notification-id>')
+        .description('Decline a pending file access request')
+        .option('--json', 'Force JSON output')
+        .action(async (notificationId, options) => {
+        try {
+            const config = requireCookie();
+            const msg = await denyRoleRequest(config, { notification_id: notificationId });
+            output({ message: msg }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return permissions;
+}
+//# sourceMappingURL=permissions.js.map

package/dist/cli/projects.d.ts

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

package/dist/cli/projects.js

@@ -0,0 +1,110 @@
+import { Command } from 'commander';
+import { createProject, renameProject, moveProject, trashProject, restoreProject, setProjectDescription, } from '../operations/projects.js';
+import { output, error } from './format.js';
+import { requireCookie } from './helpers.js';
+export function projectsCommand() {
+    const projects = new Command('projects')
+        .description('Manage Figma projects');
+    projects
+        .command('create <team-id>')
+        .description('Create a new project in a team')
+        .requiredOption('--name <name>', 'Project name')
+        .option('--json', 'Force JSON output')
+        .action(async (teamId, options) => {
+        try {
+            const config = requireCookie();
+            const result = await createProject(config, { team_id: teamId, name: options.name });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    projects
+        .command('rename <project-id>')
+        .description('Rename a project')
+        .requiredOption('--name <name>', 'New name')
+        .option('--json', 'Force JSON output')
+        .action(async (projectId, options) => {
+        try {
+            const config = requireCookie();
+            await renameProject(config, { project_id: projectId, name: options.name });
+            output({ renamed: projectId, name: options.name }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    projects
+        .command('move <project-id>')
+        .description('Move a project to a different team')
+        .requiredOption('--destination <team-id>', 'Destination team ID')
+        .option('--json', 'Force JSON output')
+        .action(async (projectId, options) => {
+        try {
+            const config = requireCookie();
+            await moveProject(config, {
+                project_id: projectId,
+                destination_team_id: options.destination,
+            });
+            output({ moved: projectId, destination_team_id: options.destination }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    projects
+        .command('trash <project-id>')
+        .description('Move a project to trash')
+        .option('--json', 'Force JSON output')
+        .action(async (projectId, options) => {
+        try {
+            const config = requireCookie();
+            await trashProject(config, { project_id: projectId });
+            output({ trashed: projectId }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    projects
+        .command('restore <project-id>')
+        .description('Restore a project from trash')
+        .option('--json', 'Force JSON output')
+        .action(async (projectId, options) => {
+        try {
+            const config = requireCookie();
+            await restoreProject(config, { project_id: projectId });
+            output({ restored: projectId }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    projects
+        .command('set-description <project-id>')
+        .description('Set or update a project description')
+        .requiredOption('--description <text>', 'Description text')
+        .option('--json', 'Force JSON output')
+        .action(async (projectId, options) => {
+        try {
+            const config = requireCookie();
+            await setProjectDescription(config, {
+                project_id: projectId,
+                description: options.description,
+            });
+            output({ updated: projectId }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return projects;
+}
+//# sourceMappingURL=projects.js.map

package/dist/cli/reading.d.ts

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

package/dist/cli/reading.js

@@ -0,0 +1,51 @@
+import { Command } from 'commander';
+import { getFile, getNodes } from '../operations/reading.js';
+import { output, error } from './format.js';
+import { requirePat } from './helpers.js';
+export function readingCommand() {
+    const reading = new Command('reading')
+        .description('Read file contents and node trees');
+    reading
+        .command('get-file <file-key>')
+        .description('Read file contents as a node tree')
+        .option('--depth <n>', 'Tree depth limit (0=root, 1=pages, 2=top-level frames)')
+        .option('--node-id <id>', 'Start from a specific node instead of document root')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requirePat();
+            const result = await getFile(config, {
+                file_key: fileKey,
+                depth: options.depth !== undefined ? parseInt(options.depth, 10) : undefined,
+                node_id: options.nodeId,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    reading
+        .command('get-nodes <file-key> <node-ids...>')
+        .description('Read specific nodes from a file')
+        .option('--depth <n>', 'Depth limit per node')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, nodeIds, options) => {
+        try {
+            const config = requirePat();
+            const result = await getNodes(config, {
+                file_key: fileKey,
+                node_ids: nodeIds,
+                depth: options.depth !== undefined ? parseInt(options.depth, 10) : undefined,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return reading;
+}
+//# sourceMappingURL=reading.js.map

package/dist/cli/teams.d.ts

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

package/dist/cli/teams.js

@@ -0,0 +1,56 @@
+import { Command } from 'commander';
+import { createTeam, renameTeam, deleteTeam } from '../operations/teams.js';
+import { output, error } from './format.js';
+import { requireCookie } from './helpers.js';
+export function teamsCommand() {
+    const teams = new Command('teams')
+        .description('Create, rename, and delete teams');
+    teams
+        .command('create <name>')
+        .description('Create a new team in the org')
+        .option('--org-id <id>', 'Org ID override')
+        .option('--json', 'Force JSON output')
+        .action(async (name, options) => {
+        try {
+            const config = requireCookie();
+            const result = await createTeam(config, { name, org_id: options.orgId });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    teams
+        .command('rename <team-id> <name>')
+        .description('Rename an existing team')
+        .option('--json', 'Force JSON output')
+        .action(async (teamId, name, options) => {
+        try {
+            const config = requireCookie();
+            const msg = await renameTeam(config, { team_id: teamId, name });
+            output({ message: msg }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    teams
+        .command('delete <team-id>')
+        .description('Delete a team (destructive, cannot be undone)')
+        .option('--json', 'Force JSON output')
+        .action(async (teamId, options) => {
+        try {
+            const config = requireCookie();
+            const msg = await deleteTeam(config, { team_id: teamId });
+            output({ message: msg }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return teams;
+}
+//# sourceMappingURL=teams.js.map

package/dist/cli/variables.d.ts

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

package/dist/cli/variables.js

@@ -0,0 +1,80 @@
+import { Command } from 'commander';
+import { listLocalVariables, listPublishedVariables, updateVariables, isEnterpriseScopeError, ENTERPRISE_ERROR, } from '../operations/variables.js';
+import { output, error } from './format.js';
+import { requirePat } from './helpers.js';
+export function variablesCommand() {
+    const variables = new Command('variables')
+        .description('Manage file variables (Enterprise)');
+    variables
+        .command('list-local <file-key>')
+        .description('List local variables and variable collections in a file')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requirePat();
+            const result = await listLocalVariables(config, { file_key: fileKey });
+            output(result, options);
+        }
+        catch (e) {
+            if (isEnterpriseScopeError(e)) {
+                error(ENTERPRISE_ERROR);
+            }
+            else {
+                error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            }
+            process.exit(1);
+        }
+    });
+    variables
+        .command('list-published <file-key>')
+        .description('List published variables from a library file')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requirePat();
+            const result = await listPublishedVariables(config, { file_key: fileKey });
+            output(result, options);
+        }
+        catch (e) {
+            if (isEnterpriseScopeError(e)) {
+                error(ENTERPRISE_ERROR);
+            }
+            else {
+                error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            }
+            process.exit(1);
+        }
+    });
+    variables
+        .command('update <file-key>')
+        .description('Bulk create, update, or delete variables, collections, modes, and mode values')
+        .option('--variable-collections <json>', 'Collection operations as JSON array')
+        .option('--variable-modes <json>', 'Mode operations as JSON array')
+        .option('--variables <json>', 'Variable operations as JSON array')
+        .option('--variable-mode-values <json>', 'Value assignments as JSON array')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requirePat();
+            const result = await updateVariables(config, {
+                file_key: fileKey,
+                variable_collections: options.variableCollections ? JSON.parse(options.variableCollections) : undefined,
+                variable_modes: options.variableModes ? JSON.parse(options.variableModes) : undefined,
+                variables: options.variables ? JSON.parse(options.variables) : undefined,
+                variable_mode_values: options.variableModeValues ? JSON.parse(options.variableModeValues) : undefined,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            if (isEnterpriseScopeError(e)) {
+                error(ENTERPRISE_ERROR);
+            }
+            else {
+                error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            }
+            process.exit(1);
+        }
+    });
+    return variables;
+}
+//# sourceMappingURL=variables.js.map

package/dist/cli/versions.d.ts

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

package/dist/cli/versions.js

@@ -0,0 +1,46 @@
+import { Command } from 'commander';
+import { listVersions, createVersion } from '../operations/versions.js';
+import { output, error } from './format.js';
+import { requirePat, requireCookie } from './helpers.js';
+export function versionsCommand() {
+    const versions = new Command('versions')
+        .description('Manage file version history');
+    versions
+        .command('list <file-key>')
+        .description('List version history for a file')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requirePat();
+            const result = await listVersions(config, { file_key: fileKey });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    versions
+        .command('create <file-key>')
+        .description('Create a named version (checkpoint)')
+        .requiredOption('--title <title>', 'Version title/label')
+        .option('--description <text>', 'Version description')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requireCookie();
+            const result = await createVersion(config, {
+                file_key: fileKey,
+                title: options.title,
+                description: options.description,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return versions;
+}
+//# sourceMappingURL=versions.js.map

package/dist/cli/webhooks.d.ts

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

package/dist/cli/webhooks.js

@@ -0,0 +1,100 @@
+import { Command } from 'commander';
+import { listWebhooks, createWebhook, updateWebhook, deleteWebhook, } from '../operations/webhooks.js';
+import { output, error } from './format.js';
+import { requirePat } from './helpers.js';
+const VALID_EVENT_TYPES = [
+    'FILE_UPDATE',
+    'FILE_DELETE',
+    'FILE_VERSION_UPDATE',
+    'LIBRARY_PUBLISH',
+    'FILE_COMMENT',
+    'PING',
+];
+export function webhooksCommand() {
+    const webhooks = new Command('webhooks')
+        .description('Manage team webhooks');
+    webhooks
+        .command('list <team-id>')
+        .description('List webhooks for a team')
+        .option('--json', 'Force JSON output')
+        .action(async (teamId, options) => {
+        try {
+            const config = requirePat();
+            const result = await listWebhooks(config, { team_id: teamId });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    webhooks
+        .command('create <team-id>')
+        .description('Create a webhook subscription for a team')
+        .requiredOption('--event-type <type>', `Event type (${VALID_EVENT_TYPES.join(', ')})`)
+        .requiredOption('--endpoint <url>', 'URL to receive webhook payloads')
+        .requiredOption('--passcode <secret>', 'Secret for signature verification')
+        .option('--description <text>', 'Webhook description')
+        .option('--json', 'Force JSON output')
+        .action(async (teamId, options) => {
+        try {
+            const config = requirePat();
+            const result = await createWebhook(config, {
+                team_id: teamId,
+                event_type: options.eventType,
+                endpoint: options.endpoint,
+                passcode: options.passcode,
+                description: options.description,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    webhooks
+        .command('update <webhook-id>')
+        .description('Update a webhook')
+        .option('--event-type <type>', `Event type (${VALID_EVENT_TYPES.join(', ')})`)
+        .option('--endpoint <url>', 'URL to receive webhook payloads')
+        .option('--passcode <secret>', 'Secret for signature verification')
+        .option('--description <text>', 'Webhook description')
+        .option('--status <status>', 'Webhook status (ACTIVE, PAUSED)')
+        .option('--json', 'Force JSON output')
+        .action(async (webhookId, options) => {
+        try {
+            const config = requirePat();
+            const result = await updateWebhook(config, {
+                webhook_id: webhookId,
+                event_type: options.eventType,
+                endpoint: options.endpoint,
+                passcode: options.passcode,
+                description: options.description,
+                status: options.status,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    webhooks
+        .command('delete <webhook-id>')
+        .description('Delete a webhook')
+        .option('--json', 'Force JSON output')
+        .action(async (webhookId, options) => {
+        try {
+            const config = requirePat();
+            await deleteWebhook(config, { webhook_id: webhookId });
+            output({ deleted: webhookId }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return webhooks;
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/operations/analytics.d.ts

@@ -0,0 +1,10 @@
+import type { AuthConfig } from '../auth/client.js';
+export declare function libraryUsage(config: AuthConfig, params: {
+    library_file_key: string;
+    days?: number;
+}): Promise<any>;
+export declare function componentUsage(config: AuthConfig, params: {
+    component_key: string;
+    org_id?: string;
+}): Promise<any>;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/operations/analytics.js

@@ -0,0 +1,15 @@
+import { internalClient } from '../clients/internal-api.js';
+import { requireOrgId } from '../tools/register.js';
+export async function libraryUsage(config, params) {
+    const lookback = params.days ?? 30;
+    const end_ts = Math.floor(Date.now() / 1000);
+    const start_ts = end_ts - lookback * 86400;
+    const res = await internalClient(config).get(`/api/dsa/library/${params.library_file_key}/team_usage`, { params: { start_ts, end_ts } });
+    return res.data;
+}
+export async function componentUsage(config, params) {
+    const orgId = requireOrgId(config, params.org_id);
+    const res = await internalClient(config).get(`/api/design_systems/component/${params.component_key}/file_usage`, { params: { org_id: orgId, fv: 4 } });
+    return res.data;
+}
+//# sourceMappingURL=analytics.js.map

package/dist/operations/branching.d.ts

@@ -0,0 +1,24 @@
+import type { AuthConfig } from '../auth/client.js';
+export interface Branch {
+    key: string;
+    name: string;
+    thumbnail_url: string | null;
+    last_modified: string | null;
+    link_access: string | null;
+}
+export interface CreatedBranch {
+    key: string | null;
+    name: string;
+    main_file_key: string;
+}
+export declare function listBranches(config: AuthConfig, params: {
+    file_key: string;
+}): Promise<Branch[]>;
+export declare function createBranch(config: AuthConfig, params: {
+    file_key: string;
+    name: string;
+}): Promise<CreatedBranch>;
+export declare function deleteBranch(config: AuthConfig, params: {
+    branch_key: string;
+}): Promise<void>;
+//# sourceMappingURL=branching.d.ts.map