@payloadcms/figma 0.0.1-alpha.51 → 0.0.1-alpha.53

package/dist/api/control-plane.d.ts

@@ -151,4 +151,12 @@ export type BootstrapInfo = {
  * @param environmentName - Optional environment name filter
  */
 export declare function getBootstrapInfo(accessToken: string, cmsResourceId: string, environmentName?: string): Promise<BootstrapInfo>;
+/**
+ * Resolve a CMS Resource ID from a legacy dataset (content system) ID.
+ * Maps to: GET /v1/cms/dataset/:datasetId
+ *
+ * Used during upgrade migration to convert old FIGMA_CONTENT_API_CONTENT_SYSTEM_ID
+ * into the new FIGMA_PROJECT_ID (CMS Resource ID).
+ */
+export declare function getCmsResourceId(accessToken: string, datasetId: string): Promise<string>;
 //# sourceMappingURL=control-plane.d.ts.map

package/dist/api/control-plane.js

@@ -276,6 +276,27 @@ import * as log from '../utils/log.js';
         }
     };
 }
+/**
+ * Resolve a CMS Resource ID from a legacy dataset (content system) ID.
+ * Maps to: GET /v1/cms/dataset/:datasetId
+ *
+ * Used during upgrade migration to convert old FIGMA_CONTENT_API_CONTENT_SYSTEM_ID
+ * into the new FIGMA_PROJECT_ID (CMS Resource ID).
+ */ export async function getCmsResourceId(accessToken, datasetId) {
+    const url = `${getControlPlaneBaseUrl()}/v1/cms/dataset/${datasetId}`;
+    log.debug(`Calling getCmsResourceId API at ${url}`);
+    const response = await controlPlaneFetch({
+        context: 'get CMS resource ID from dataset',
+        options: {
+            headers: {
+                Authorization: `Bearer ${accessToken}`
+            }
+        },
+        url
+    });
+    const data = await response.json();
+    return data.meta.cms_resource_id;
+}
 const MAX_RETRIES = 3;
 const INITIAL_RETRY_DELAY = 1000;
 function sleep(ms) {

package/dist/cli.js

@@ -9,6 +9,7 @@ import { initCommand } from './commands/init.js';
 import { listTokensCommand } from './commands/list-tokens.js';
 import { loginCommand } from './commands/login.js';
 import { logoutCommand } from './commands/logout.js';
+import { upgradeCommand } from './commands/upgrade.js';
 import { setInfraEnvironment } from './constants.js';
 import { helpMessage } from './utils/messages.js';
 /**
@@ -30,6 +31,7 @@ class Main {
         this.args = arg({
             '--all': Boolean,
             '--debug': Boolean,
+            '--dry-run': Boolean,
             '--env': String,
             '--force': Boolean,
             '--help': Boolean,
@@ -137,6 +139,11 @@ class Main {
                         debug: this.args['--debug']
                     });
                     break;
+                case 'upgrade':
+                    await upgradeCommand({
+                        isDryRun: this.args['--dry-run']
+                    });
+                    break;
                 default:
                     p.log.error(pc.red(`Unknown command: ${subcommand}`));
                     p.note('Use --help to see available commands', 'Tip');

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,5 @@
+export type UpgradeCommandOptions = {
+    isDryRun?: boolean;
+};
+export declare function upgradeCommand(options?: UpgradeCommandOptions): Promise<void>;
+//# sourceMappingURL=upgrade.d.ts.map

package/dist/commands/upgrade.js

@@ -0,0 +1,331 @@
+import * as p from '@clack/prompts';
+import fs from 'fs/promises';
+import path from 'path';
+import pc from 'picocolors';
+import { Project } from 'ts-morph';
+import { fileURLToPath } from 'url';
+import { getBootstrapInfo, getCmsResourceId } from '../api/control-plane.js';
+import { getValidAccessToken } from '../auth/oauth-flow.js';
+import { getTokenStore } from '../auth/token-store.js';
+import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
+import { addOrUpdateEnvVar, getEnvVar, removeEnvVar } from '../utils/env-management.js';
+import { formatFile } from '../utils/formatter.js';
+import { getPackageManager } from '../utils/package-manager.js';
+import { removeFigmaContentSystemId } from '../utils/payload-config-ast.js';
+import { findPayloadConfig } from '../utils/payload-config-finder.js';
+import { checkPackageInstalled, installPackage } from '../utils/payload-package-check.js';
+import { getOwnVersion } from '../utils/version-check.js';
+export async function upgradeCommand(options = {}) {
+    const cwd = process.cwd();
+    const { isDryRun = false } = options;
+    const changes = [];
+    const warnings = [];
+    const spinner = p.spinner();
+    spinner.start('Checking for needed migrations...');
+    spinner.stop('Checking for needed migrations...');
+    await migrateEnvRename({
+        changes,
+        cwd,
+        isDryRun
+    });
+    await migrateProjectId({
+        changes,
+        cwd,
+        isDryRun,
+        warnings
+    });
+    await ensureBootstrapCached({
+        changes,
+        cwd,
+        isDryRun
+    });
+    await migrateRemoveDeprecatedEnvVars({
+        changes,
+        cwd,
+        isDryRun,
+        warnings
+    });
+    await migrateConfigAst({
+        changes,
+        cwd,
+        isDryRun
+    });
+    await migratePackageVersion({
+        changes,
+        cwd,
+        isDryRun
+    });
+    for (const warning of warnings){
+        p.log.warning(warning);
+    }
+    if (changes.length === 0) {
+        p.log.success('Everything is up to date.');
+        return;
+    }
+    if (isDryRun) {
+        p.log.info(`Dry run: ${changes.length} change(s) detected.`);
+    } else {
+        p.log.success(`${changes.length} change(s) applied.`);
+    }
+}
+const DEPRECATED_ENV_VARS = [
+    'FIGMA_CONTENT_API_CONTENT_SYSTEM_ID',
+    'FIGMA_TENANT_ID',
+    'FIGMA_OAUTH_CLIENT_ID',
+    'FIGMA_OAUTH_CLIENT_SECRET'
+];
+async function migrateEnvRename({ changes, cwd, isDryRun }) {
+    try {
+        const oldValue = await getEnvVar(cwd, 'FIGMA_ENV');
+        if (oldValue === null) {
+            return;
+        }
+        if (isDryRun) {
+            p.log.message(`${pc.dim('○')} Would rename FIGMA_ENV → FIGMA_INFRA_ENV`);
+            changes.push('Rename FIGMA_ENV → FIGMA_INFRA_ENV');
+            return;
+        }
+        await addOrUpdateEnvVar(cwd, 'FIGMA_INFRA_ENV', oldValue);
+        await removeEnvVar(cwd, 'FIGMA_ENV');
+        p.log.message(`${pc.green('●')} Env: Renamed FIGMA_ENV → FIGMA_INFRA_ENV`);
+        changes.push('Renamed FIGMA_ENV → FIGMA_INFRA_ENV');
+    } catch (error) {
+        const msg = error instanceof Error ? error.message : 'Unknown error';
+        p.log.warning(`Env rename migration failed: ${msg}`);
+    }
+}
+async function migrateProjectId({ changes, cwd, isDryRun, warnings = [] }) {
+    try {
+        const existingProjectId = await getEnvVar(cwd, 'FIGMA_PROJECT_ID');
+        if (existingProjectId) {
+            return;
+        }
+        const oldContentSystemId = await getEnvVar(cwd, 'FIGMA_CONTENT_API_CONTENT_SYSTEM_ID');
+        if (!oldContentSystemId) {
+            return;
+        }
+        if (isDryRun) {
+            p.log.message(`${pc.dim('○')} Would resolve FIGMA_PROJECT_ID from content system ID`);
+            changes.push('Resolve FIGMA_PROJECT_ID from content system ID');
+            return;
+        }
+        const store = getTokenStore();
+        const accessToken = await getValidAccessToken(store);
+        if (!accessToken) {
+            warnings.push('Not authenticated — could not resolve FIGMA_PROJECT_ID. Run `npx @payloadcms/figma login` first.');
+            return;
+        }
+        const cmsResourceId = await getCmsResourceId(accessToken, oldContentSystemId);
+        await addOrUpdateEnvVar(cwd, 'FIGMA_PROJECT_ID', cmsResourceId);
+        // Resolve actual environment name from bootstrap API
+        try {
+            const bootstrapInfo = await getBootstrapInfo(accessToken, cmsResourceId);
+            cacheAllEnvironments(store, cmsResourceId, bootstrapInfo);
+            const envName = bootstrapInfo.environments[0]?.name ?? 'production';
+            await addOrUpdateEnvVar(cwd, 'FIGMA_ENVIRONMENT_NAME', envName);
+        } catch  {
+            await addOrUpdateEnvVar(cwd, 'FIGMA_ENVIRONMENT_NAME', 'production');
+        }
+        p.log.message(`${pc.green('●')} Env: Resolved FIGMA_PROJECT_ID from content system ID`);
+        changes.push('Resolved FIGMA_PROJECT_ID from content system ID');
+    } catch (error) {
+        const msg = error instanceof Error ? error.message : 'Unknown error';
+        p.log.warning(`Project ID migration failed: ${msg}`);
+    }
+}
+async function ensureBootstrapCached(params) {
+    try {
+        const projectId = await getEnvVar(params.cwd, 'FIGMA_PROJECT_ID');
+        if (!projectId) {
+            return;
+        }
+        const environmentName = await getEnvVar(params.cwd, 'FIGMA_ENVIRONMENT_NAME') ?? 'production';
+        const store = getTokenStore();
+        if (store.getBootstrapData(projectId, environmentName)) {
+            return;
+        }
+        const accessToken = await getValidAccessToken(store);
+        if (!accessToken) {
+            return;
+        }
+        const bootstrapInfo = await getBootstrapInfo(accessToken, projectId);
+        cacheAllEnvironments(store, projectId, bootstrapInfo);
+        // Fix FIGMA_ENVIRONMENT_NAME if it doesn't match any actual environment
+        const envNames = bootstrapInfo.environments.map((e)=>e.name);
+        if (!envNames.includes(environmentName) && envNames.length > 0) {
+            const correctName = envNames[0];
+            if (params.isDryRun) {
+                p.log.message(`${pc.dim('○')} Would fix FIGMA_ENVIRONMENT_NAME: ${environmentName} → ${correctName}`);
+                params.changes.push(`Fix FIGMA_ENVIRONMENT_NAME`);
+                return;
+            }
+            await addOrUpdateEnvVar(params.cwd, 'FIGMA_ENVIRONMENT_NAME', correctName);
+            p.log.message(`${pc.green('●')} Env: Fixed FIGMA_ENVIRONMENT_NAME: ${environmentName} → ${correctName}`);
+            params.changes.push(`Fixed FIGMA_ENVIRONMENT_NAME: ${environmentName} → ${correctName}`);
+        }
+    } catch  {
+    // Best-effort — runtime will retry if needed
+    }
+}
+async function migrateRemoveDeprecatedEnvVars({ changes, cwd, isDryRun, warnings = [] }) {
+    try {
+        const presentVars = [];
+        for (const key of DEPRECATED_ENV_VARS){
+            const value = await getEnvVar(cwd, key);
+            if (value !== null) {
+                presentVars.push(key);
+            }
+        }
+        if (presentVars.length === 0) {
+            return;
+        }
+        // Only remove when bootstrap data is available (proves the project is set up correctly)
+        const projectId = await getEnvVar(cwd, 'FIGMA_PROJECT_ID');
+        if (!projectId) {
+            warnings.push('Cannot remove deprecated env vars without FIGMA_PROJECT_ID. Run upgrade again after project ID migration.');
+            return;
+        }
+        const environmentName = await getEnvVar(cwd, 'FIGMA_ENVIRONMENT_NAME') ?? 'production';
+        const store = getTokenStore();
+        const bootstrapData = store.getBootstrapData(projectId, environmentName);
+        if (!bootstrapData) {
+            // Try fetching from API
+            const accessToken = await getValidAccessToken(store);
+            if (accessToken) {
+                try {
+                    const bootstrapInfo = await getBootstrapInfo(accessToken, projectId);
+                    cacheAllEnvironments(store, projectId, bootstrapInfo);
+                } catch  {
+                    warnings.push('Could not verify bootstrap data — keeping deprecated env vars. Run `npx @payloadcms/figma init` to complete migration.');
+                    return;
+                }
+            } else {
+                warnings.push('Not authenticated — keeping deprecated env vars. Run `npx @payloadcms/figma login` first.');
+                return;
+            }
+        }
+        if (isDryRun) {
+            p.log.message(`${pc.dim('○')} Would remove deprecated env vars: ${presentVars.join(', ')}`);
+            changes.push(`Remove deprecated env vars: ${presentVars.join(', ')}`);
+            return;
+        }
+        const removed = [];
+        for (const key of presentVars){
+            await removeEnvVar(cwd, key);
+            removed.push(key);
+        }
+        p.log.message(`${pc.green('●')} Env: Removed deprecated env vars: ${removed.join(', ')}`);
+        changes.push(`Removed deprecated env vars: ${removed.join(', ')}`);
+    } catch (error) {
+        const msg = error instanceof Error ? error.message : 'Unknown error';
+        p.log.warning(`Deprecated env var removal failed: ${msg}`);
+    }
+}
+async function migrateConfigAst({ changes, cwd, isDryRun }) {
+    try {
+        const configPath = await findPayloadConfig(cwd);
+        if (!configPath) {
+            return;
+        }
+        const project = new Project({
+            skipAddingFilesFromTsConfig: true
+        });
+        const sourceFile = project.addSourceFileAtPath(configPath);
+        const wouldRemove = removeFigmaContentSystemId(sourceFile);
+        if (!wouldRemove) {
+            return;
+        }
+        if (isDryRun) {
+            p.log.message(`${pc.dim('○')} Would remove contentSystemId from payload.config.ts`);
+            changes.push('Remove contentSystemId from payload.config.ts');
+            return;
+        }
+        // Re-parse fresh since the detection already mutated the AST
+        const freshProject = new Project({
+            skipAddingFilesFromTsConfig: true
+        });
+        const freshSourceFile = freshProject.addSourceFileAtPath(configPath);
+        removeFigmaContentSystemId(freshSourceFile);
+        await freshSourceFile.save();
+        try {
+            const packageManager = await getPackageManager(cwd);
+            await formatFile(configPath, packageManager);
+        } catch  {
+        // Formatting is best-effort
+        }
+        p.log.message(`${pc.green('●')} Config: Removed contentSystemId from payload.config.ts`);
+        changes.push('Removed contentSystemId from payload.config.ts');
+    } catch (error) {
+        const msg = error instanceof Error ? error.message : 'Unknown error';
+        p.log.warning(`Config AST migration failed: ${msg}`);
+    }
+}
+async function migratePackageVersion({ changes, cwd, isDryRun }) {
+    try {
+        const isInstalled = await checkPackageInstalled(cwd, '@payloadcms/figma');
+        if (!isInstalled) {
+            return;
+        }
+        const cliDir = path.dirname(fileURLToPath(import.meta.url));
+        const isFromRegistry = cliDir.includes('node_modules') || cliDir.includes('.npm');
+        if (isFromRegistry) {
+            await migrateRegistryPackageVersion({
+                changes,
+                cliDir,
+                cwd,
+                isDryRun
+            });
+        } else {
+            await migrateLocalPackageVersion({
+                changes,
+                cliDir,
+                cwd,
+                isDryRun
+            });
+        }
+    } catch (error) {
+        const msg = error instanceof Error ? error.message : 'Unknown error';
+        p.log.warning(`Package version sync failed: ${msg}`);
+    }
+}
+async function migrateRegistryPackageVersion({ changes, cliDir: _cliDir, cwd, isDryRun }) {
+    const cliVersion = await getOwnVersion();
+    const pkgJsonPath = path.join(cwd, 'package.json');
+    const pkgJson = JSON.parse(await fs.readFile(pkgJsonPath, 'utf-8'));
+    const installedVersion = pkgJson.dependencies?.['@payloadcms/figma']?.replace(/^[\^~>=<]+/, '');
+    if (!installedVersion || installedVersion === cliVersion) {
+        return;
+    }
+    if (isDryRun) {
+        p.log.message(`${pc.dim('○')} Would update @payloadcms/figma ${installedVersion} → ${cliVersion}`);
+        changes.push(`Update @payloadcms/figma ${installedVersion} → ${cliVersion}`);
+        return;
+    }
+    const packageManager = await getPackageManager(cwd);
+    await installPackage(cwd, '@payloadcms/figma', packageManager, cliVersion);
+    p.log.message(`${pc.green('●')} Package: Updated @payloadcms/figma ${installedVersion} → ${cliVersion}`);
+    changes.push(`Updated @payloadcms/figma ${installedVersion} → ${cliVersion}`);
+}
+async function migrateLocalPackageVersion({ changes, cliDir, cwd, isDryRun }) {
+    if (isDryRun) {
+        p.log.message(`${pc.dim('○')} Would install @payloadcms/figma from local build`);
+        changes.push('Install @payloadcms/figma from local build');
+        return;
+    }
+    // Dynamic import — findPackageRoot and packLocalPackage will be exported in a later task
+    const { findPackageRoot, packLocalPackage } = await import('../utils/handle-upgrade.js');
+    const pkgDir = await findPackageRoot(cliDir);
+    if (!pkgDir) {
+        return;
+    }
+    const packageManager = await getPackageManager(cwd);
+    const tgzPath = packLocalPackage(pkgDir);
+    const destTgz = path.join(cwd, path.basename(tgzPath));
+    await fs.rename(tgzPath, destTgz);
+    await installPackage(cwd, destTgz, packageManager);
+    await fs.unlink(destTgz).catch(()=>{});
+    p.log.message(`${pc.green('●')} Package: Installed @payloadcms/figma from local build`);
+    changes.push('Installed @payloadcms/figma from local build');
+}
+
+//# sourceMappingURL=upgrade.js.map

package/dist/db-content-api/generated/content-api-types.d.ts

@@ -1494,6 +1494,117 @@ export type paths = {
                         };
                     };
                 };
+                /** @description Unauthorized */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        'application/json': {
+                            /** @example Error message describing the issue. */
+                            message: string;
+                        };
+                    };
+                };
+                /** @description Forbidden */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        'application/json': {
+                            /** @example Error message describing the issue. */
+                            message: string;
+                        };
+                    };
+                };
+                /** @description Not Found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        'application/json': {
+                            /** @example Error message describing the issue. */
+                            message: string;
+                        };
+                    };
+                };
+                /** @description Internal Server Error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        'application/json': {
+                            /** @example Error message describing the issue. */
+                            message: string;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/api/v0/documents:findDistinct': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    'application/json': components['schemas']['FindDistinctDocumentsRequest'];
+                };
+            };
+            responses: {
+                /** @description Distinct values found */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        'application/json': components['schemas']['FindDistinctDocumentsResponse'];
+                    };
+                };
+                /** @description Bad Request */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        'application/json': {
+                            /** @example Error message describing the issue. */
+                            message: string;
+                        };
+                    };
+                };
+                /** @description Unauthorized */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        'application/json': {
+                            /** @example Error message describing the issue. */
+                            message: string;
+                        };
+                    };
+                };
                 /** @description Forbidden */
                 403: {
                     headers: {
@@ -2953,12 +3064,21 @@ export type components = {
             contentSystemScope?: string;
         };
         HealthResponse: {
-            /** @example ok */
-            status: string;
-            /** @example connected */
-            database: string;
-            /** @example available */
-            s3: string;
+            /**
+             * @example ok
+             * @enum {string}
+             */
+            status: 'ok';
+            /**
+             * @example connected
+             * @enum {string}
+             */
+            database: 'connected' | 'disconnected';
+            /**
+             * @example available
+             * @enum {string}
+             */
+            s3: 'available' | 'unavailable';
             /** @example 2026-01-01T00:00:00.000Z */
             timestamp: string;
         };
@@ -3177,14 +3297,51 @@ export type components = {
                 count: number;
             };
         };
+        /** @example es */
+        LocaleClause: string;
         /**
-         * @example array
-         * @enum {string}
+         * @example {
+         *       "paths": [
+         *         "field_a",
+         *         "field_b"
+         *       ]
+         *     }
          */
-        PathType: 'array';
+        UniquePath: {
+            paths: string[];
+        };
+        PathTypeRelationship: {
+            /** @enum {string} */
+            type: 'relationship';
+            collection: string | string[];
+            hasMany?: boolean;
+        };
+        PathTypeJoin: {
+            /** @enum {string} */
+            type: 'join';
+            collection: string | string[];
+            hasMany?: boolean;
+            on: string;
+        };
+        /** @enum {string} */
+        PathTypeBlocks: 'blocks';
+        /** @example array */
+        PathType: 'array' | components['schemas']['PathTypeRelationship'] | components['schemas']['PathTypeJoin'] | components['schemas']['PathTypeBlocks'];
         /**
          * @example {
-         *       "author.tagIds": "array"
+         *       "author.tagIds": "array",
+         *       "author": {
+         *         "type": "relationship",
+         *         "collection": "users",
+         *         "hasMany": false
+         *       },
+         *       "relatedPosts": {
+         *         "type": "join",
+         *         "collection": "posts",
+         *         "hasMany": true,
+         *         "on": "category"
+         *       },
+         *       "blocks": "blocks"
          *     }
          */
         PathTypesMeta: {
@@ -3192,6 +3349,7 @@ export type components = {
         };
         RequestMeta: {
             localizedPaths?: string[];
+            uniquePaths?: components['schemas']['UniquePath'][];
             pathTypes?: components['schemas']['PathTypesMeta'];
         };
         DataValue: string | number | boolean | unknown | components['schemas']['DataValue'][] | {
@@ -3227,6 +3385,7 @@ export type components = {
             contentSystemId: string;
             /** @example posts */
             collection: string;
+            locale?: components['schemas']['LocaleClause'];
             meta?: components['schemas']['RequestMeta'];
             where?: components['schemas']['WhereClause'];
         };
@@ -3291,29 +3450,46 @@ export type components = {
             page?: number;
             sort?: components['schemas']['SortClause'];
         }[];
-        /** @example es */
-        LocaleClause: string;
         /**
          * @example {
-         *       "mode": "include",
-         *       "paths": [
-         *         "title",
-         *         "author.name",
-         *         "tags"
-         *       ]
+         *       "title": true,
+         *       "author": {
+         *         "name": true,
+         *         "email": true
+         *       },
+         *       "tags": true
          *     }
          */
-        SelectClause: {
-            /** @enum {string} */
-            mode: 'exclude' | 'include';
-            paths: string[];
+        IncludeSelectClause: {
+            [key: string]: true | {
+                [key: string]: components['schemas']['IncludeSelectClause'];
+            };
+        };
+        /**
+         * @example {
+         *       "title": false,
+         *       "author": {
+         *         "name": false,
+         *         "email": false
+         *       },
+         *       "tags": false
+         *     }
+         */
+        ExcludeSelectClause: {
+            [key: string]: false | {
+                [key: string]: components['schemas']['ExcludeSelectClause'];
+            };
         };
+        /** @description Field selection - use include mode (true) or exclude mode (false), but not both */
+        SelectClause: components['schemas']['IncludeSelectClause'] | components['schemas']['ExcludeSelectClause'];
         CreateDocumentRequest: {
             /** @example cms-xxxxx-xxxxx */
             contentSystemId: string;
             /** @example posts */
             collection: string;
             doc: components['schemas']['DocumentData'];
+            locale?: components['schemas']['LocaleClause'];
+            meta?: components['schemas']['RequestMeta'];
             returning?: false | {
                 join?: components['schemas']['JoinClause'];
                 locale?: components['schemas']['LocaleClause'];
@@ -3353,6 +3529,47 @@ export type components = {
             sort?: components['schemas']['SortClause'];
             where?: components['schemas']['WhereClause'];
         };
+        FindDistinctDocumentsResponse: {
+            result: {
+                /**
+                 * @example [
+                 *       "value1",
+                 *       "value2"
+                 *     ]
+                 */
+                data: unknown[];
+                totalDocs: number;
+                limit: number;
+                page: number;
+                totalPages: number;
+                pagingCounter: number;
+                hasPrevPage: boolean;
+                hasNextPage: boolean;
+                prevPage: number | null;
+                nextPage: number | null;
+            };
+        };
+        FindDistinctDocumentsRequest: {
+            /** @example cms-xxxxx-xxxxx */
+            contentSystemId: string;
+            /** @example posts */
+            collection: string;
+            /**
+             * @description Path to the field to get distinct values for
+             * @example title
+             */
+            distinctBy: string;
+            join?: components['schemas']['JoinClause'];
+            /** @example 10 */
+            limit?: number;
+            locale?: components['schemas']['LocaleClause'];
+            /** @example 1 */
+            page?: number;
+            meta?: components['schemas']['RequestMeta'];
+            select?: components['schemas']['SelectClause'];
+            sort?: components['schemas']['SortClause'];
+            where?: components['schemas']['WhereClause'];
+        };
         UpdateDocumentResponse: {
             result?: {
                 /** @example 1 */
@@ -3388,6 +3605,7 @@ export type components = {
             doc: components['schemas']['DataWithOperations'];
             /** @example 10 */
             limit?: number;
+            locale?: components['schemas']['LocaleClause'];
             meta?: components['schemas']['RequestMeta'];
             returning?: false | {
                 join?: components['schemas']['JoinClause'];
@@ -3396,7 +3614,6 @@ export type components = {
             };
             sort?: components['schemas']['SortClause'];
             where: components['schemas']['WhereClause'];
-            locale?: components['schemas']['LocaleClause'];
         };
         DeleteDocumentResponse: {
             result?: {
@@ -3414,6 +3631,7 @@ export type components = {
             contentSystemId: string;
             /** @example posts */
             collection: string;
+            locale?: components['schemas']['LocaleClause'];
             meta?: components['schemas']['RequestMeta'];
             returning?: false | {
                 join?: components['schemas']['JoinClause'];
@@ -3421,7 +3639,6 @@ export type components = {
                 select?: components['schemas']['SelectClause'];
             };
             where: components['schemas']['WhereClause'];
-            locale?: components['schemas']['LocaleClause'];
         };
         CountDocumentVersionResponse: {
             result: {
@@ -3434,6 +3651,7 @@ export type components = {
             contentSystemId: string;
             /** @example posts */
             collection: string;
+            locale?: components['schemas']['LocaleClause'];
             meta?: components['schemas']['RequestMeta'];
             where?: components['schemas']['WhereClause'];
         };
@@ -3495,6 +3713,8 @@ export type components = {
                 parent?: string | number;
                 version: components['schemas']['DocumentData'] & unknown;
             };
+            locale?: components['schemas']['LocaleClause'];
+            meta?: components['schemas']['RequestMeta'];
             returning?: false | {
                 join?: components['schemas']['JoinClause'];
                 locale?: components['schemas']['LocaleClause'];
@@ -3569,9 +3789,9 @@ export type components = {
             where: components['schemas']['WhereClause'];
             /** @example 10 */
             limit?: number;
+            locale?: components['schemas']['LocaleClause'];
             meta?: components['schemas']['RequestMeta'];
             sort?: components['schemas']['SortClause'];
-            locale?: components['schemas']['LocaleClause'];
             returning?: false | {
                 join?: components['schemas']['JoinClause'];
                 locale?: components['schemas']['LocaleClause'];
@@ -3594,6 +3814,7 @@ export type components = {
             contentSystemId: string;
             /** @example posts */
             collection: string;
+            locale?: components['schemas']['LocaleClause'];
             meta?: components['schemas']['RequestMeta'];
             returning?: false | {
                 join?: components['schemas']['JoinClause'];

package/dist/plugin/build-config.d.ts

@@ -8,20 +8,16 @@ import type { Config, SanitizedConfig } from 'payload';
  * - `editor`: Optional (defaults to lexicalEditor() if not provided)
  *
  * @example
- * // Minimal config
+ * // Minimal config (contentSystemId resolved from bootstrap data)
  * const config: FigmaConfig = {
- *   figma: {
- *     contentSystemId: process.env.FIGMA_CONTENT_API_CONTENT_SYSTEM_ID!
- *   },
+ *   figma: {},
  *   collections: [...]
  * }
  *
  * @example
  * // With custom editor
  * const config: FigmaConfig = {
- *   figma: {
- *     contentSystemId: process.env.FIGMA_CONTENT_API_CONTENT_SYSTEM_ID!
- *   },
+ *   figma: {},
  *   collections: [...],
  *   editor: lexicalEditor({ features: [...] })
  * }
@@ -30,7 +26,6 @@ import type { Config, SanitizedConfig } from 'payload';
  * // Disable Content System (use custom db)
  * const config: FigmaConfig = {
  *   figma: {
- *     contentSystemId: process.env.FIGMA_CONTENT_API_CONTENT_SYSTEM_ID!,
  *     useContentSystem: false
  *   },
  *   db: mongooseAdapter({ url: process.env.DATABASE_URI }),
@@ -41,7 +36,7 @@ export type FigmaConfig = {
     editor?: Config['editor'];
 } & {
     figma: {
-        contentSystemId: string;
+        contentSystemId?: string;
         storage?: boolean;
         useContentSystem?: boolean;
     };

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 import type arg from 'arg';
 export interface Args extends arg.Spec {
     '--debug': BooleanConstructor;
+    '--dry-run': BooleanConstructor;
     '--env': StringConstructor;
     '--force': BooleanConstructor;
     '--help': BooleanConstructor;

package/dist/utils/env-management.d.ts

@@ -22,4 +22,12 @@ export declare function getEnvVarSync(projectPath: string, key: string): null |
  * @param value - Environment variable value
  */
 export declare function addOrUpdateEnvVar(projectPath: string, key: string, value: string): Promise<void>;
+/**
+ * Remove an environment variable from .env file
+ *
+ * @param projectPath - Path to project directory
+ * @param key - Environment variable name to remove
+ * @returns true if key was found and removed, false otherwise
+ */
+export declare function removeEnvVar(projectPath: string, key: string): Promise<boolean>;
 //# sourceMappingURL=env-management.d.ts.map

package/dist/utils/env-management.js

@@ -115,5 +115,39 @@ import path from 'path';
         throw new Error(`Failed to update .env file: ${error instanceof Error ? error.message : 'Unknown error'}`);
     }
 }
+/**
+ * Remove an environment variable from .env file
+ *
+ * @param projectPath - Path to project directory
+ * @param key - Environment variable name to remove
+ * @returns true if key was found and removed, false otherwise
+ */ export async function removeEnvVar(projectPath, key) {
+    const envPath = path.join(projectPath, '.env');
+    try {
+        const contents = await fs.readFile(envPath, 'utf-8');
+        const lines = contents.split(/\r?\n/);
+        const filteredLines = [];
+        let found = false;
+        for (const line of lines){
+            if (line.trim() && !line.trim().startsWith('#') && line.includes('=')) {
+                const equalsIndex = line.indexOf('=');
+                const lineKey = line.substring(0, equalsIndex).trim();
+                if (lineKey === key) {
+                    found = true;
+                    continue;
+                }
+            }
+            filteredLines.push(line);
+        }
+        if (found) {
+            // Collapse consecutive blank lines and trim leading/trailing blank lines
+            const collapsed = filteredLines.join('\n').replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '');
+            await fs.writeFile(envPath, collapsed, 'utf-8');
+        }
+        return found;
+    } catch  {
+        return false;
+    }
+}
 
 //# sourceMappingURL=env-management.js.map

package/dist/utils/handle-upgrade.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Walk up from a directory to find the nearest package.json with name "@payloadcms/figma".
+ */
+export declare function findPackageRoot(startDir: string): Promise<null | string>;
+/**
+ * Build and pack the local @payloadcms/figma package, returning the tgz path.
+ */
+export declare function packLocalPackage(pkgDir: string): string;
+//# sourceMappingURL=handle-upgrade.d.ts.map

package/dist/utils/handle-upgrade.js

@@ -0,0 +1,41 @@
+import { execSync } from 'child_process';
+import fs from 'fs/promises';
+import path from 'path';
+/**
+ * Walk up from a directory to find the nearest package.json with name "@payloadcms/figma".
+ */ export async function findPackageRoot(startDir) {
+    let dir = startDir;
+    while(true){
+        const pkgPath = path.join(dir, 'package.json');
+        try {
+            const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf-8'));
+            if (pkg.name === '@payloadcms/figma') {
+                return dir;
+            }
+        } catch  {
+        // No package.json here
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            return null;
+        }
+        dir = parent;
+    }
+}
+/**
+ * Build and pack the local @payloadcms/figma package, returning the tgz path.
+ */ export function packLocalPackage(pkgDir) {
+    execSync('pnpm build', {
+        cwd: pkgDir,
+        stdio: 'pipe'
+    });
+    const tgzOutput = execSync('pnpm pack', {
+        cwd: pkgDir,
+        stdio: 'pipe'
+    }).toString().trim();
+    const tgzName = tgzOutput.split('\n').pop();
+    const tgzPath = path.join(pkgDir, tgzName);
+    return tgzPath;
+}
+
+//# sourceMappingURL=handle-upgrade.js.map

package/dist/utils/messages.js

@@ -17,6 +17,7 @@ export function helpMessage() {
       ${pc.cyan('debug')}            Show debug info for troubleshooting
       ${pc.cyan('env')}              Switch active environment
       ${pc.cyan('deploy')}           Deploy your project to Figma
+      ${pc.cyan('upgrade')}          Run upgrade migrations
       ${pc.cyan('build-lambda-zip')} Build Lambda deployment zip
 
   ${pc.bold('OPTIONS')}
@@ -50,6 +51,11 @@ export function helpMessage() {
       ${pc.dim('--yes, -y')}                             Skip confirmation prompts
       ${pc.dim('--skip-build')}                          Skip building and use existing build
 
+  ${pc.bold('UPGRADE COMMAND')}
+
+      ${pc.cyan('@payloadcms/figma upgrade')}              Run all upgrade migrations
+      ${pc.dim('--dry-run')}                               Preview changes without applying
+
   ${pc.bold('GLOBAL OPTIONS')}
 
       ${pc.dim('--infra-env <env>')}                     Target infrastructure (production or staging)

package/dist/utils/payload-config-ast.d.ts

@@ -62,4 +62,11 @@ export declare function addFigmaProperty(sourceFile: SourceFile, config: FigmaPr
  * Returns the figma object if it exists, null otherwise
  */
 export declare function readFigmaConfig(sourceFile: SourceFile): FigmaPropertyConfig | null;
+/**
+ * Remove the contentSystemId property from figma config object.
+ * Used during upgrade migration — contentSystemId is now resolved from bootstrap data.
+ *
+ * @returns true if the property was found and removed
+ */
+export declare function removeFigmaContentSystemId(sourceFile: SourceFile): boolean;
 //# sourceMappingURL=payload-config-ast.d.ts.map

package/dist/utils/payload-config-ast.js

@@ -472,5 +472,39 @@ import * as log from './log.js';
         useContentSystem
     };
 }
+/**
+ * Remove the contentSystemId property from figma config object.
+ * Used during upgrade migration — contentSystemId is now resolved from bootstrap data.
+ *
+ * @returns true if the property was found and removed
+ */ export function removeFigmaContentSystemId(sourceFile) {
+    const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+    const buildConfigCall = callExpressions.find((ce)=>{
+        const expr = ce.getExpression();
+        const text = expr.getText();
+        return text === 'buildFigmaConfig' || text.endsWith('.buildFigmaConfig');
+    });
+    if (!buildConfigCall) {
+        return false;
+    }
+    const configArg = buildConfigCall.getArguments()[0];
+    if (!configArg || !Node.isObjectLiteralExpression(configArg)) {
+        return false;
+    }
+    const figmaProperty = configArg.getProperty('figma');
+    if (!figmaProperty || !Node.isPropertyAssignment(figmaProperty)) {
+        return false;
+    }
+    const initializer = figmaProperty.getInitializer();
+    if (!initializer || !Node.isObjectLiteralExpression(initializer)) {
+        return false;
+    }
+    const contentSystemIdProp = initializer.getProperty('contentSystemId');
+    if (!contentSystemIdProp) {
+        return false;
+    }
+    contentSystemIdProp.remove();
+    return true;
+}
 
 //# sourceMappingURL=payload-config-ast.js.map

package/dist/utils/payload-package-check.js

@@ -42,7 +42,7 @@ import * as log from './log.js';
  */ export async function installPackage(projectPath, packageName, packageManager, version = 'latest') {
     return new Promise((resolve, reject)=>{
         const command = packageManager;
-        const packageSpec = `${packageName}@${version}`;
+        const packageSpec = packageName.endsWith('.tgz') ? packageName : `${packageName}@${version}`;
         const args = [
             'add',
             packageSpec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payloadcms/figma",
-  "version": "0.0.1-alpha.51",
+  "version": "0.0.1-alpha.53",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
   "exports": {