figmanage 1.0.0 → 1.1.0

package/dist/operations/export.d.ts

@@ -0,0 +1,19 @@
+import type { AuthConfig } from '../auth/client.js';
+export interface ExportedImage {
+    node_id: string;
+    url: string | null;
+}
+export interface ImageFill {
+    image_ref: string;
+    url: string;
+}
+export declare function exportNodes(config: AuthConfig, params: {
+    file_key: string;
+    node_ids: string[];
+    format?: string;
+    scale?: number;
+}): Promise<ExportedImage[]>;
+export declare function getImageFills(config: AuthConfig, params: {
+    file_key: string;
+}): Promise<ImageFill[]>;
+//# sourceMappingURL=export.d.ts.map

package/dist/operations/export.js

@@ -0,0 +1,27 @@
+import { publicClient } from '../clients/public-api.js';
+export async function exportNodes(config, params) {
+    const queryParams = {
+        ids: params.node_ids.join(','),
+        format: params.format || 'png',
+    };
+    if (params.scale)
+        queryParams.scale = String(Math.min(Math.max(params.scale, 0.01), 4));
+    const res = await publicClient(config).get(`/v1/images/${params.file_key}`, { params: queryParams });
+    const images = res.data?.images || {};
+    const err = res.data?.err;
+    if (err)
+        throw new Error(`Export error: ${err}`);
+    return Object.entries(images).map(([nodeId, url]) => ({
+        node_id: nodeId,
+        url: url,
+    }));
+}
+export async function getImageFills(config, params) {
+    const res = await publicClient(config).get(`/v1/files/${params.file_key}/images`);
+    const images = res.data?.meta?.images || res.data?.images || {};
+    return Object.entries(images).map(([ref, url]) => ({
+        image_ref: ref,
+        url: url,
+    }));
+}
+//# sourceMappingURL=export.js.map

package/dist/operations/files.d.ts

@@ -0,0 +1,55 @@
+import type { AuthConfig } from '../auth/client.js';
+export interface CreatedFile {
+    key: string;
+    name: string;
+    editor_type: string;
+    url: string;
+}
+export interface DuplicatedFile {
+    key: string;
+    name: string;
+    url: string;
+}
+export interface MoveResult {
+    succeeded: number;
+    failed: number;
+    errors?: Record<string, unknown>;
+}
+export declare function createFile(config: AuthConfig, params: {
+    project_id: string;
+    editor_type?: string;
+    org_id?: string;
+}): Promise<CreatedFile>;
+export declare function renameFile(config: AuthConfig, params: {
+    file_key: string;
+    name: string;
+}): Promise<void>;
+export declare function moveFiles(config: AuthConfig, params: {
+    file_keys: string[];
+    destination_project_id: string;
+}): Promise<MoveResult>;
+export declare function duplicateFile(config: AuthConfig, params: {
+    file_key: string;
+    project_id?: string;
+}): Promise<DuplicatedFile>;
+export declare function trashFiles(config: AuthConfig, params: {
+    file_keys: string[];
+}): Promise<{
+    succeeded: number;
+}>;
+export declare function restoreFiles(config: AuthConfig, params: {
+    file_keys: string[];
+}): Promise<MoveResult>;
+export declare function favoriteFile(config: AuthConfig, params: {
+    file_key: string;
+    favorited?: boolean;
+}): Promise<{
+    favorited: boolean;
+}>;
+export declare function setLinkAccess(config: AuthConfig, params: {
+    file_key: string;
+    link_access?: string;
+}): Promise<{
+    link_access: string;
+}>;
+//# sourceMappingURL=files.d.ts.map

package/dist/operations/files.js

@@ -0,0 +1,89 @@
+import { internalClient } from '../clients/internal-api.js';
+import { resolveOrgId } from '../tools/register.js';
+export async function createFile(config, params) {
+    const res = await internalClient(config).post('/api/files/create', {
+        folder_id: params.project_id,
+        org_id: resolveOrgId(config, params.org_id),
+        editor_type: params.editor_type || 'design',
+    });
+    const f = res.data?.meta?.fig_file || res.data?.meta || res.data;
+    return {
+        key: f.key,
+        name: f.name,
+        editor_type: f.editor_type,
+        url: `https://www.figma.com/design/${f.key}`,
+    };
+}
+export async function renameFile(config, params) {
+    await internalClient(config).put(`/api/files/${params.file_key}`, {
+        key: params.file_key,
+        name: params.name,
+    });
+}
+export async function moveFiles(config, params) {
+    const files = params.file_keys.map(key => ({
+        key,
+        folder_id: params.destination_project_id,
+        is_multi_move: params.file_keys.length > 1,
+        restore_files: false,
+    }));
+    const res = await internalClient(config).put('/api/files_batch', { files });
+    const data = res.data?.meta || res.data;
+    const succeeded = Object.keys(data.success || {}).length;
+    const failed = Object.keys(data.errors || {}).length;
+    return {
+        succeeded,
+        failed,
+        errors: failed > 0 ? data.errors : undefined,
+    };
+}
+export async function duplicateFile(config, params) {
+    const res = await internalClient(config).post(`/api/multiplayer/${params.file_key}/copy`, null, {
+        headers: { 'Content-Length': '0' },
+        params: params.project_id ? { folder_id: params.project_id } : undefined,
+    });
+    const f = res.data?.meta?.fig_file || res.data?.meta || res.data;
+    return {
+        key: f.key,
+        name: f.name,
+        url: `https://www.figma.com/design/${f.key}`,
+    };
+}
+export async function trashFiles(config, params) {
+    const files = params.file_keys.map(key => ({ key }));
+    const res = await internalClient(config).delete('/api/files_batch', {
+        data: { files, trashed: true },
+    });
+    const data = res.data?.meta || res.data;
+    const succeeded = Object.keys(data.success || {}).length;
+    return { succeeded };
+}
+export async function restoreFiles(config, params) {
+    const files = params.file_keys.map(key => ({ key }));
+    const res = await internalClient(config).post('/api/files_batch/restore', { files });
+    const data = res.data?.meta || res.data;
+    const succeeded = Object.keys(data?.success || {}).length || params.file_keys.length;
+    const failed = Object.keys(data?.errors || {}).length;
+    return {
+        succeeded,
+        failed,
+        errors: failed > 0 ? data.errors : undefined,
+    };
+}
+export async function favoriteFile(config, params) {
+    const isFavorited = params.favorited !== false;
+    await internalClient(config).put('/api/favorited_resources', {
+        resource_type: 'file',
+        resource_id_or_key: params.file_key,
+        is_favorited: isFavorited,
+    });
+    return { favorited: isFavorited };
+}
+export async function setLinkAccess(config, params) {
+    const res = await internalClient(config).put(`/api/files/${params.file_key}`, {
+        link_access: params.link_access || 'inherit',
+    });
+    const newAccess = res.data?.meta?.link_access || params.link_access || 'inherit';
+    return { link_access: newAccess };
+}
+//# sourceMappingURL=files.js.map

package/dist/operations/libraries.d.ts

@@ -0,0 +1,5 @@
+import type { AuthConfig } from '../auth/client.js';
+export declare function listOrgLibraries(config: AuthConfig, params: {
+    org_id?: string;
+}): Promise<any>;
+//# sourceMappingURL=libraries.d.ts.map

package/dist/operations/libraries.js

@@ -0,0 +1,10 @@
+import { internalClient } from '../clients/internal-api.js';
+import { requireOrgId } from '../tools/register.js';
+export async function listOrgLibraries(config, params) {
+    const orgId = requireOrgId(config, params.org_id);
+    const res = await internalClient(config).get('/api/design_systems/libraries', {
+        params: { org_id: orgId, include_sharing_group_info: true },
+    });
+    return res.data;
+}
+//# sourceMappingURL=libraries.js.map

package/dist/operations/navigate.d.ts

@@ -0,0 +1,99 @@
+import type { AuthConfig } from '../auth/client.js';
+import type { AuthStatus } from '../types/figma.js';
+export interface AuthCheckResult {
+    status: AuthStatus;
+    formatted: string;
+}
+export interface OrgListEntry {
+    id: string;
+    name: string;
+    active: boolean;
+}
+export interface SwitchOrgResult {
+    previous: string;
+    current: {
+        id: string;
+        name: string;
+    };
+}
+export interface Team {
+    id: string;
+    name: string;
+}
+export interface Project {
+    id: string;
+    name: string;
+}
+export interface FileEntry {
+    key: string;
+    name: string;
+    last_modified?: string;
+    thumbnail_url?: string;
+    editor_type?: string;
+}
+export interface FileListResult {
+    files: FileEntry[];
+    pagination?: {
+        has_more: boolean;
+        hint: string;
+    };
+}
+export interface RecentFile {
+    key: string;
+    name: string;
+    team_id?: string;
+    folder_id?: string;
+    editor_type?: string;
+    last_touched?: string;
+    url: string;
+}
+export interface SearchResult {
+    key: string;
+    name: string;
+    editor_type?: string;
+    team_id?: string;
+    folder_id?: string;
+    last_modified?: string;
+    url: string;
+}
+export interface FileInfo {
+    key: string;
+    name: string;
+    last_modified?: string;
+    updated_at?: string;
+    editor_type?: string;
+    folder_id?: string;
+    team_id?: string;
+    link_access?: string;
+    url: string;
+}
+export interface Favorite {
+    key: string;
+    name: string;
+    type?: string;
+}
+export declare function checkAuthStatus(config: AuthConfig): Promise<AuthCheckResult>;
+export declare function listOrgs(config: AuthConfig): Promise<OrgListEntry[]>;
+export declare function switchOrg(config: AuthConfig, params: {
+    org: string;
+}): Promise<SwitchOrgResult>;
+export declare function listTeams(config: AuthConfig): Promise<Team[]>;
+export declare function listProjects(config: AuthConfig, params: {
+    team_id: string;
+}): Promise<Project[]>;
+export declare function listFiles(config: AuthConfig, params: {
+    project_id: string;
+    page_size?: number;
+    page_token?: string;
+}): Promise<FileListResult>;
+export declare function listRecentFiles(config: AuthConfig): Promise<RecentFile[]>;
+export declare function search(config: AuthConfig, params: {
+    query: string;
+    sort?: string;
+    org_id?: string;
+}): Promise<SearchResult[]>;
+export declare function getFileInfo(config: AuthConfig, params: {
+    file_key: string;
+}): Promise<FileInfo>;
+export declare function listFavorites(config: AuthConfig): Promise<Favorite[]>;
+//# sourceMappingURL=navigate.d.ts.map

package/dist/operations/navigate.js

@@ -0,0 +1,266 @@
+import { hasCookie, hasPat } from '../auth/client.js';
+import { publicClient } from '../clients/public-api.js';
+import { internalClient } from '../clients/internal-api.js';
+import { checkAuth, formatAuthStatus } from '../auth/health.js';
+function requireOrgId(config, explicit) {
+    const id = explicit || config.orgId;
+    if (!id)
+        throw new Error('Org context required. Run list_orgs to see available workspaces, or set FIGMA_ORG_ID.');
+    if (!/^[\w.:-]+$/.test(id))
+        throw new Error('Invalid org ID format');
+    return id;
+}
+export async function checkAuthStatus(config) {
+    const status = await checkAuth(config);
+    const formatted = formatAuthStatus(status, config);
+    return { status, formatted };
+}
+export async function listOrgs(config) {
+    const api = internalClient(config);
+    const res = await api.get('/api/user/state');
+    let orgs = (res.data?.meta?.orgs || [])
+        .filter((o) => o && o.id)
+        .map((o) => ({ id: String(o.id), name: o.name || String(o.id) }));
+    // Fallback: meta.orgs is empty for non-admin users.
+    // Extract unique org_ids from meta.roles instead.
+    if (orgs.length === 0) {
+        const roles = res.data?.meta?.roles || [];
+        const orgIds = [...new Set(roles
+                .map((r) => r.org_id)
+                .filter((id) => id != null)
+                .map(String))];
+        // Also include config.orgId if not already covered
+        if (config.orgId && !orgIds.includes(config.orgId)) {
+            orgIds.push(config.orgId);
+        }
+        // Resolve names via domain lookup
+        orgs = await Promise.all(orgIds.map(async (id) => {
+            let name = id;
+            try {
+                const domRes = await api.get(`/api/orgs/${id}/domains`);
+                const domains = domRes.data?.meta || [];
+                if (Array.isArray(domains) && domains.length > 0) {
+                    name = domains[0].domain || id;
+                }
+            }
+            catch { /* domain lookup optional */ }
+            return { id, name };
+        }));
+    }
+    // Merge with any existing registry entries (preserves names from setup)
+    if (config.orgs && config.orgs.length > 0) {
+        for (const existing of config.orgs) {
+            if (!orgs.find(o => o.id === existing.id)) {
+                orgs.push(existing);
+            }
+            else {
+                // Prefer stored name over ID-only fallback
+                const entry = orgs.find(o => o.id === existing.id);
+                if (entry.name === entry.id && existing.name !== existing.id) {
+                    entry.name = existing.name;
+                }
+            }
+        }
+    }
+    if (orgs.length === 0)
+        return [];
+    return orgs.map(o => ({
+        id: o.id,
+        name: o.name,
+        active: o.id === config.orgId,
+    }));
+}
+export async function switchOrg(config, params) {
+    // Ensure we have an org list
+    if (!config.orgs || config.orgs.length === 0) {
+        const res = await internalClient(config).get('/api/user/state');
+        const orgs = (res.data?.meta?.orgs || []).map((o) => ({
+            id: String(o.id),
+            name: o.name,
+        }));
+        if (orgs.length > 0)
+            config.orgs = orgs;
+    }
+    if (!config.orgs || config.orgs.length === 0) {
+        throw new Error('No workspaces found. You may be on a free/starter plan.');
+    }
+    // Try exact ID match first
+    let match = config.orgs.find(o => o.id === params.org);
+    // Then case-insensitive substring match on name
+    if (!match) {
+        const lower = params.org.toLowerCase();
+        const matches = config.orgs.filter(o => o.name.toLowerCase().includes(lower));
+        if (matches.length === 1) {
+            match = matches[0];
+        }
+        else if (matches.length > 1) {
+            const names = matches.map(o => `${o.name} (${o.id})`).join(', ');
+            throw new Error(`Ambiguous: "${params.org}" matches multiple workspaces: ${names}. Be more specific or use the org ID.`);
+        }
+    }
+    if (!match) {
+        const available = config.orgs.map(o => `${o.name} (${o.id})`).join(', ');
+        throw new Error(`No workspace matching "${params.org}". Available: ${available}`);
+    }
+    const previousId = config.orgId;
+    const previousOrg = config.orgs.find(o => o.id === previousId);
+    const previousLabel = previousOrg ? `${previousOrg.name} (${previousId})` : (previousId || 'none');
+    return {
+        previous: previousLabel,
+        current: { id: match.id, name: match.name },
+    };
+}
+export async function listTeams(config) {
+    if (config.orgId) {
+        const res = await internalClient(config).get(`/api/orgs/${config.orgId}/teams`);
+        const data = res.data?.meta || res.data;
+        return (data.teams || (Array.isArray(data) ? data : [])).map((t) => ({
+            id: String(t.id),
+            name: t.name,
+        }));
+    }
+    // Fallback: get teams from user/state
+    const res = await internalClient(config).get('/api/user/state');
+    return (res.data?.meta?.teams || []).map((t) => ({
+        id: String(t.id),
+        name: t.name,
+    }));
+}
+export async function listProjects(config, params) {
+    if (hasCookie(config)) {
+        const res = await internalClient(config).get(`/api/teams/${params.team_id}/folders`);
+        const rows = res.data?.meta?.folder_rows || res.data || [];
+        return (Array.isArray(rows) ? rows : []).map((p) => ({
+            id: String(p.id),
+            name: p.name || p.path,
+        }));
+    }
+    else {
+        const res = await publicClient(config).get(`/v1/teams/${params.team_id}/projects`);
+        return (res.data.projects || []).map((p) => ({
+            id: String(p.id),
+            name: p.name,
+        }));
+    }
+}
+export async function listFiles(config, params) {
+    // Prefer public API when PAT available -- returns keys compatible
+    // with all public endpoints (versions, comments, export).
+    if (hasPat(config)) {
+        const res = await publicClient(config).get(`/v1/projects/${params.project_id}/files`);
+        const files = (res.data.files || []).map((f) => ({
+            key: f.key,
+            name: f.name,
+            last_modified: f.last_modified,
+            thumbnail_url: f.thumbnail_url,
+        }));
+        return { files };
+    }
+    else {
+        const pageSize = Math.min(params.page_size || 25, 100);
+        const urlParams = new URLSearchParams({
+            folderId: params.project_id,
+            sort_column: 'touched_at',
+            sort_order: 'desc',
+            page_size: String(pageSize),
+            file_type: '',
+        });
+        if (params.page_token)
+            urlParams.set('before', params.page_token);
+        const res = await internalClient(config).get(`/api/folders/${params.project_id}/paginated_files?${urlParams}`);
+        const meta = res.data?.meta || res.data;
+        const files = (meta.files || meta.results || []).map((f) => ({
+            key: f.key,
+            name: f.name,
+            last_modified: f.touched_at || f.updated_at || f.last_modified,
+            editor_type: f.editor_type,
+        }));
+        const pagination = res.data?.pagination;
+        const result = { files };
+        if (pagination?.next_page || files.length === pageSize) {
+            result.pagination = {
+                has_more: true,
+                hint: `To get the next page, call list_files again with page_token="${pagination?.next_page || files[files.length - 1]?.last_modified || ''}"`,
+            };
+        }
+        return result;
+    }
+}
+export async function listRecentFiles(config) {
+    const res = await internalClient(config).get('/api/recent_files');
+    return (res.data?.meta?.recent_files || []).map((f) => ({
+        key: f.key,
+        name: f.name,
+        team_id: f.team_id,
+        folder_id: f.folder_id,
+        editor_type: f.editor_type,
+        last_touched: f.touched_at,
+        url: f.url || `https://www.figma.com/design/${f.key}`,
+    }));
+}
+export async function search(config, params) {
+    const orgId = requireOrgId(config, params.org_id);
+    const apiParams = {
+        query: params.query,
+        sort: params.sort || 'relevancy',
+        desc: 'true',
+        is_global: 'true',
+        org_id: orgId,
+        current_org_id: orgId,
+        plan_type: 'org',
+    };
+    const res = await internalClient(config).get('/api/search/file_browser_preview', { params: apiParams });
+    const meta = res.data?.meta;
+    const categories = Array.isArray(meta) ? meta : [];
+    const fileCategory = categories.find((c) => c.search_model_type === 'files') || categories[0];
+    const rawResults = fileCategory?.results || [];
+    return rawResults.map((r) => {
+        const m = r.model || r;
+        return {
+            key: m.key,
+            name: m.name,
+            editor_type: m.editor_type,
+            team_id: m.team_id ? String(m.team_id) : undefined,
+            folder_id: m.folder_id ? String(m.folder_id) : undefined,
+            last_modified: m.touched_at,
+            url: m.url || `https://www.figma.com/design/${m.key}`,
+        };
+    });
+}
+export async function getFileInfo(config, params) {
+    if (hasPat(config)) {
+        const res = await publicClient(config).get(`/v1/files/${params.file_key}/meta`);
+        const f = res.data.file || res.data;
+        return {
+            key: f.key || params.file_key,
+            name: f.name,
+            last_modified: f.lastModified || f.last_modified,
+            editor_type: f.editorType || f.editor_type,
+            url: `https://www.figma.com/design/${params.file_key}`,
+        };
+    }
+    else {
+        const res = await internalClient(config).get(`/api/files/${params.file_key}`);
+        const f = res.data?.meta || res.data;
+        return {
+            key: f.key || params.file_key,
+            name: f.name,
+            updated_at: f.updated_at,
+            editor_type: f.editor_type,
+            folder_id: f.folder_id ? String(f.folder_id) : undefined,
+            team_id: f.team_id ? String(f.team_id) : undefined,
+            link_access: f.link_access,
+            url: f.url || `https://www.figma.com/design/${params.file_key}`,
+        };
+    }
+}
+export async function listFavorites(config) {
+    const res = await internalClient(config).get('/api/user/favorited_resources');
+    const data = res.data?.meta || res.data;
+    return (Array.isArray(data) ? data : data.favorites || data.resources || []).map((f) => ({
+        key: f.key || f.file_key || f.id,
+        name: f.name,
+        type: f.resource_type || f.type,
+    }));
+}
+//# sourceMappingURL=navigate.js.map

package/dist/operations/org.d.ts

@@ -0,0 +1,95 @@
+import type { AuthConfig } from '../auth/client.js';
+export declare const SEAT_HIERARCHY: Record<string, number>;
+export declare const SEAT_LABELS: Record<string, string>;
+export declare const PAID_STATUSES: Record<string, Record<string, string>>;
+export declare const SEAT_KEY_TO_TYPE: Record<string, string>;
+export interface Admin {
+    user_id: string;
+    email: string | undefined;
+    name: string | undefined;
+    permission: string;
+    seat_type: string | null;
+    is_email_validated: boolean;
+    license_admin: boolean;
+}
+export declare function listAdmins(config: AuthConfig, params: {
+    org_id?: string;
+    include_license_admins?: boolean;
+}): Promise<Admin[]>;
+export interface OrgTeam {
+    id: string;
+    name: string;
+    member_count: number | null;
+    project_count: number | null;
+    access_level: string | null;
+}
+export declare function listOrgTeams(config: AuthConfig, params: {
+    org_id?: string;
+    include_secret_teams?: boolean;
+}): Promise<OrgTeam[]>;
+export declare function seatUsage(config: AuthConfig, params: {
+    org_id?: string;
+    search_query?: string;
+}): Promise<any>;
+export interface TeamMember {
+    id: string;
+    name: string;
+    email: string;
+    img_url: string;
+    last_active: string | null;
+    team_role: number | null;
+    permission: string | null;
+    seat_type: string | null;
+}
+export declare function listTeamMembers(config: AuthConfig, params: {
+    team_id: string;
+}): Promise<TeamMember[]>;
+export declare function billingOverview(config: AuthConfig, params: {
+    org_id?: string;
+}): Promise<any>;
+export declare function listInvoices(config: AuthConfig, params: {
+    org_id?: string;
+}): Promise<Record<string, any>>;
+export declare function orgDomains(config: AuthConfig, params: {
+    org_id?: string;
+}): Promise<Record<string, any>>;
+export declare function aiCreditUsage(config: AuthConfig, params: {
+    plan_id: string;
+}): Promise<any>;
+export declare function exportMembers(config: AuthConfig, params: {
+    org_id?: string;
+}): Promise<string>;
+export interface OrgMember {
+    org_user_id: string;
+    user_id: string;
+    email: string | undefined;
+    name: string | undefined;
+    permission: string;
+    seat_type: string | null;
+    last_active: string | null;
+}
+export declare function listOrgMembers(config: AuthConfig, params: {
+    org_id?: string;
+    search_query?: string;
+}): Promise<OrgMember[]>;
+export interface ContractRate {
+    product: string;
+    monthly_cents: number;
+    monthly_dollars: string;
+}
+export declare function contractRates(config: AuthConfig, params: {
+    org_id?: string;
+}): Promise<ContractRate[]>;
+export interface ChangeSeatResult {
+    user: string | undefined;
+    email: string | undefined;
+    old_seat: string;
+    new_seat: string;
+}
+export declare function changeSeat(config: AuthConfig, params: {
+    user_id: string;
+    seat_type: string;
+    org_id?: string;
+    confirm?: boolean;
+}): Promise<ChangeSeatResult | string>;
+//# sourceMappingURL=org.d.ts.map