@payloadcms/figma 0.0.1-alpha.62 → 0.0.1-alpha.64

package/dist/oauth/defaults.js

@@ -2,10 +2,11 @@ import { parseCookies } from 'payload';
 import { v4 as uuid } from 'uuid';
 import { hasUserTokenPropsChanged } from './utilities/hasUserTokenPropsChanged.js';
 import { isDuplicateKeyError } from './utilities/isDuplicateKeyError.js';
-function getFigmaUserInfo(headers) {
+export const DEFAULT_USER_INFO_COOKIE_NAME = 'figma-user-info';
+function getFigmaUserInfo(headers, cookieName) {
     try {
         const cookies = parseCookies(headers);
-        const encoded = cookies.get('figma-user-info');
+        const encoded = cookies.get(cookieName);
         if (!encoded) {
             return null;
         }
@@ -28,7 +29,7 @@ export const defaultUsernameField = {
     },
     unique: true
 };
-export const defaultVerify = ({ collection, strategyName, usernameField })=>async ({ headers, payload, token })=>{
+export const defaultVerify = ({ collection, strategyName, userInfoCookieName = DEFAULT_USER_INFO_COOKIE_NAME, usernameField })=>async ({ headers, payload, token })=>{
         let tokenUsername = 'preferred_username';
         if (usernameField.name !== 'preferredUsername') {
             tokenUsername = usernameField.name;
@@ -38,12 +39,12 @@ export const defaultVerify = ({ collection, strategyName, usernameField })=>asyn
                 user: null
             };
         }
-        const figmaUserInfo = getFigmaUserInfo(headers);
+        const figmaUserInfo = getFigmaUserInfo(headers, userInfoCookieName);
         let responseHeaders;
         // Clear the cookie after reading
         if (figmaUserInfo) {
             responseHeaders = new Headers();
-            responseHeaders.append('Set-Cookie', 'figma-user-info=; Max-Age=0; Path=/;');
+            responseHeaders.append('Set-Cookie', `${userInfoCookieName}=; Max-Age=0; Path=/;`);
         }
         let user = null;
         const depth = typeof collection.auth === 'object' ? collection.auth.depth : undefined;

package/dist/oauth/endpoints/getLoginEndpoint.js

@@ -262,7 +262,7 @@ export const getLoginEndpoint = ({ collection, collectionOptions, endpointSlug,
                     })).toString('base64');
                     const userInfoCookie = generateCookie({
                         ...cookieOptions,
-                        name: 'figma-user-info',
+                        name: pluginOptions?.userInfoCookieName ?? 'figma-user-info',
                         expires: new Date(Date.now() + 60_000),
                         returnCookieAsObject: false,
                         value: userInfoValue

package/dist/oauth/index.js

@@ -144,6 +144,7 @@ export const oAuth2Plugin = (pluginOptions)=>(config)=>{
                     verify: collectionOptions.verify ?? defaultVerify({
                         collection: existingCollection,
                         strategyName,
+                        userInfoCookieName: pluginOptions?.userInfoCookieName,
                         usernameField
                     })
                 });

package/dist/oauth/types.d.ts

@@ -148,6 +148,16 @@ export interface PluginOptions {
      * @default 'oauth'
      */
     strategyName?: string;
+    /**
+     * The name of the short-lived cookie used to carry Figma user profile
+     * info from the login endpoint to `defaultVerify`.
+     *
+     * Override in local dev when running multiple Payload apps on localhost
+     * to avoid cookie collisions (all localhost apps share a cookie jar).
+     *
+     * @default 'figma-user-info'
+     */
+    userInfoCookieName?: string;
 }
 export type CookieOptions = {
     domain?: string;

package/dist/plugin/auth-preflight.d.ts

@@ -0,0 +1,8 @@
+import type { TokenStore } from '../auth/token-store.js';
+/**
+ * Print a one-shot banner when the plugin is about to use `tokenStore`
+ * auth but no valid OAuth credential is present. Keeps the dev loop
+ * actionable instead of relying on per-request middleware errors.
+ */
+export declare function logMissingCliAuth(tokenStore: TokenStore): void;
+//# sourceMappingURL=auth-preflight.d.ts.map

package/dist/plugin/auth-preflight.js

@@ -0,0 +1,20 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+/**
+ * Print a one-shot banner when the plugin is about to use `tokenStore`
+ * auth but no valid OAuth credential is present. Keeps the dev loop
+ * actionable instead of relying on per-request middleware errors.
+ */ export function logMissingCliAuth(tokenStore) {
+    if (tokenStore.hasValidOauthToken()) {
+        return;
+    }
+    const lines = [
+        'Not logged in to the Figma CLI.',
+        'Content API requests will fail until you authenticate.',
+        '',
+        `Run ${pc.cyan('npx @payloadcms/figma login')} to log in, then restart the dev server.`
+    ];
+    p.note(lines.join('\n'), pc.yellow('Figma authentication required'));
+}
+
+//# sourceMappingURL=auth-preflight.js.map

package/dist/plugin/bootstrap-preflight.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Reason the Content System ID could not be resolved. Drives the
+ * banner's copy so the dev sees the specific remediation step.
+ */
+export type MissingContentSystemIdReason = {
+    environmentName: string;
+    kind: 'environment-not-found';
+    projectId: string;
+} | {
+    kind: 'network';
+    message: string;
+} | {
+    kind: 'no-config';
+} | {
+    kind: 'unauthenticated';
+};
+/**
+ * Print a banner explaining why Content System ID resolution failed and
+ * what to run next. Called just before `buildFigmaConfig` throws, so the
+ * actionable step is visible above the stack trace.
+ */
+export declare function logMissingContentSystemId(reason: MissingContentSystemIdReason): void;
+//# sourceMappingURL=bootstrap-preflight.d.ts.map

package/dist/plugin/bootstrap-preflight.js

@@ -0,0 +1,45 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+/**
+ * Print a banner explaining why Content System ID resolution failed and
+ * what to run next. Called just before `buildFigmaConfig` throws, so the
+ * actionable step is visible above the stack trace.
+ */ export function logMissingContentSystemId(reason) {
+    const lines = buildBody(reason);
+    p.note(lines.join('\n'), pc.yellow('Figma project not configured'));
+}
+function buildBody(reason) {
+    const loginCmd = pc.cyan('npx @payloadcms/figma login');
+    const initCmd = pc.cyan('npx @payloadcms/figma init');
+    const initForceCmd = pc.cyan('npx @payloadcms/figma init --force');
+    if (reason.kind === 'no-config') {
+        return [
+            'No Figma project configuration found.',
+            '',
+            `Run ${initCmd} to set up this project.`
+        ];
+    }
+    if (reason.kind === 'unauthenticated') {
+        return [
+            'Project config found, but you are not logged in.',
+            'Cannot fetch bootstrap data without a valid session.',
+            '',
+            `Run ${loginCmd}, then restart the dev server.`
+        ];
+    }
+    if (reason.kind === 'network') {
+        return [
+            'Could not reach the Figma API to fetch bootstrap data.',
+            `Error: ${reason.message}`,
+            '',
+            'Check your network, then restart the dev server.'
+        ];
+    }
+    return [
+        `Environment ${pc.bold(reason.environmentName)} not found for project ${pc.bold(reason.projectId)}.`,
+        '',
+        `Run ${initForceCmd} to reconfigure, or set FIGMA_ENVIRONMENT_NAME to a valid environment.`
+    ];
+}
+
+//# sourceMappingURL=bootstrap-preflight.js.map

package/dist/plugin/build-config.js

@@ -15,7 +15,11 @@ import { createStorageClient } from '../storage-content-api/client.js';
 import { getGenerateSignedURLHandler } from '../storage-content-api/client-uploads/generateSignedURL.js';
 import { contentApiStorageAdapter } from '../storage-content-api/index.js';
 import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
+import { getEnvVarSync } from '../utils/env-management.js';
 import * as log from '../utils/log.js';
+import { logMissingCliAuth } from './auth-preflight.js';
+import { logMissingContentSystemId } from './bootstrap-preflight.js';
+import { getDevCookieNames } from './dev-cookie-names.js';
 /**
  * Fields added to users collection for Figma profile info
  */ const figmaUserFields = [
@@ -47,20 +51,118 @@ function missingOAuthCredential(name) {
 }
 /**
  * Fetch bootstrap data from the API and cache all environments locally.
- * Returns the requested environment's data, or null if resolution fails.
+ * Returns the requested environment's data, or a typed failure reason.
  */ async function resolveAndCacheBootstrap(store, projectId, environmentName) {
+    let credential;
+    try {
+        credential = await getValidCredential(store);
+    } catch (error) {
+        return {
+            ok: false,
+            reason: {
+                kind: 'network',
+                message: messageOf(error)
+            }
+        };
+    }
+    if (!credential) {
+        return {
+            ok: false,
+            reason: {
+                kind: 'unauthenticated'
+            }
+        };
+    }
     try {
-        const credential = await getValidCredential(store);
-        if (!credential) {
-            return null;
-        }
         const bootstrapInfo = await getBootstrapInfo(credential, projectId);
         cacheAllEnvironments(store, projectId, bootstrapInfo);
-        return store.getBootstrapData(projectId, environmentName);
     } catch (error) {
-        log.warning(`Failed to resolve bootstrap data: ${error instanceof Error ? error.message : 'Unknown error'}. ` + 'Try running `npx @payloadcms/figma login` to refresh authentication.');
-        return null;
+        return {
+            ok: false,
+            reason: {
+                kind: 'network',
+                message: messageOf(error)
+            }
+        };
     }
+    const data = store.getBootstrapData(projectId, environmentName);
+    if (!data) {
+        return {
+            ok: false,
+            reason: {
+                environmentName,
+                kind: 'environment-not-found',
+                projectId
+            }
+        };
+    }
+    return {
+        data,
+        ok: true
+    };
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : 'Unknown error';
+}
+/**
+ * Creates storage configuration for upload collections
+ */ function createStorageConfig(url, contentSystemId) {
+    const storageConfig = process.env.FIGMA_CONTENT_API_ACCESS_KEY ? {
+        baseUrl: url,
+        contentApiKey: process.env.FIGMA_CONTENT_API_ACCESS_KEY
+    } : process.env.FIGMA_DEV_JWT === 'true' ? {
+        auth: {
+            mode: 'devJwt'
+        },
+        baseUrl: url,
+        contentSystemId
+    } : {
+        auth: {
+            mode: 'tokenStore',
+            tokenStore: getTokenStore()
+        },
+        baseUrl: url,
+        contentSystemId
+    };
+    const adapter = contentApiStorageAdapter(storageConfig);
+    const storageClient = createStorageClient(storageConfig);
+    return {
+        adapter,
+        storageClient
+    };
+}
+/**
+ * Plugin that applies cloud storage configuration to all upload-enabled collections.
+ * Runs at the end of the plugin chain so it sees collections added by user plugins too.
+ */ function createStoragePlugin(url, contentSystemId) {
+    return (incomingConfig)=>{
+        const uploadCollections = (incomingConfig.collections || []).filter((c)=>c.upload);
+        if (uploadCollections.length === 0) {
+            return incomingConfig;
+        }
+        const { adapter, storageClient } = createStorageConfig(url, contentSystemId);
+        const collectionsMap = uploadCollections.reduce((acc, c)=>{
+            acc[c.slug] = {
+                adapter,
+                disableLocalStorage: true
+            };
+            return acc;
+        }, {});
+        initClientUploads({
+            clientHandler: '@payloadcms/figma/client#ContentApiClientUploadHandler',
+            collections: collectionsMap,
+            config: incomingConfig,
+            enabled: true,
+            serverHandler: getGenerateSignedURLHandler({
+                client: storageClient
+            }),
+            serverHandlerPath: '/content-api-storage-signed-url'
+        });
+        const storagePlugin = cloudStoragePlugin({
+            collections: collectionsMap
+        });
+        return storagePlugin(incomingConfig);
+    };
 }
 export async function buildFigmaConfig(config) {
     const envConfig = getEnvConfig();
@@ -68,16 +170,27 @@ export async function buildFigmaConfig(config) {
     let { contentSystemId } = config.figma;
     contentSystemId ??= process.env.FIGMA_CONTENT_API_CONTENT_SYSTEM_ID;
     let bootstrapData = null;
+    let bootstrapReason = null;
     // Local dev: resolve from project ID + bootstrap cache
+    // Use getEnvVarSync fallback because Next.js evaluates config before dotenv populates process.env
     if (!contentSystemId) {
-        const projectId = process.env.FIGMA_PROJECT_ID;
-        const environmentName = process.env.FIGMA_ENVIRONMENT_NAME;
-        if (projectId && environmentName) {
+        const projectId = process.env.FIGMA_PROJECT_ID ?? getEnvVarSync(process.cwd(), 'FIGMA_PROJECT_ID');
+        const environmentName = process.env.FIGMA_ENVIRONMENT_NAME ?? getEnvVarSync(process.cwd(), 'FIGMA_ENVIRONMENT_NAME');
+        if (!projectId || !environmentName) {
+            bootstrapReason = {
+                kind: 'no-config'
+            };
+        } else {
             const store = getTokenStore();
             bootstrapData = store.getBootstrapData(projectId, environmentName);
             // Runtime fallback: fetch from API if not cached (e.g. environment switch without re-init)
             if (!bootstrapData) {
-                bootstrapData = await resolveAndCacheBootstrap(store, projectId, environmentName);
+                const resolution = await resolveAndCacheBootstrap(store, projectId, environmentName);
+                if (resolution.ok) {
+                    bootstrapData = resolution.data;
+                } else {
+                    bootstrapReason = resolution.reason;
+                }
             }
             if (bootstrapData) {
                 contentSystemId = bootstrapData.contentSystemId;
@@ -85,10 +198,17 @@ export async function buildFigmaConfig(config) {
         }
     }
     if (!contentSystemId) {
+        logMissingContentSystemId(bootstrapReason ?? {
+            kind: 'no-config'
+        });
         throw new Error('Content System ID could not be resolved. ' + 'Run `npx @payloadcms/figma init` to set up your project.');
     }
     const url = process.env.FIGMA_CONTENT_API_URL || envConfig.contentApiUrl;
     const isProduction = process.env.NODE_ENV === 'production';
+    const usesTokenStoreAuth = !process.env.FIGMA_CONTENT_API_ACCESS_KEY && process.env.FIGMA_DEV_JWT !== 'true';
+    if (usesTokenStoreAuth) {
+        logMissingCliAuth(getTokenStore());
+    }
     // Determine database adapter based on environment
     let db;
     if (config.figma.useContentSystem === false) {
@@ -120,50 +240,6 @@ export async function buildFigmaConfig(config) {
             url
         });
     }
-    // Build storage plugin if there are upload collections and storage is not disabled
-    const uploadCollections = (config.collections || []).filter((c)=>c.upload);
-    let storagePlugin;
-    if (uploadCollections.length > 0 && config.figma.storage !== false) {
-        const storageConfig = process.env.FIGMA_CONTENT_API_ACCESS_KEY ? {
-            baseUrl: url,
-            contentApiKey: process.env.FIGMA_CONTENT_API_ACCESS_KEY
-        } : process.env.FIGMA_DEV_JWT === 'true' ? {
-            auth: {
-                mode: 'devJwt'
-            },
-            baseUrl: url,
-            contentSystemId
-        } : {
-            auth: {
-                mode: 'tokenStore',
-                tokenStore: getTokenStore()
-            },
-            baseUrl: url,
-            contentSystemId
-        };
-        const adapter = contentApiStorageAdapter(storageConfig);
-        const storageClient = createStorageClient(storageConfig);
-        const collectionsMap = uploadCollections.reduce((acc, c)=>{
-            acc[c.slug] = {
-                adapter,
-                disableLocalStorage: true
-            };
-            return acc;
-        }, {});
-        initClientUploads({
-            clientHandler: '@payloadcms/figma/client#ContentApiClientUploadHandler',
-            collections: collectionsMap,
-            config: config,
-            enabled: true,
-            serverHandler: getGenerateSignedURLHandler({
-                client: storageClient
-            }),
-            serverHandlerPath: '/content-api-storage-signed-url'
-        });
-        storagePlugin = cloudStoragePlugin({
-            collections: collectionsMap
-        });
-    }
     // Build complete config with Figma platform defaults
     const configWithFigmaDefaults = {
         ...config,
@@ -197,8 +273,8 @@ export async function buildFigmaConfig(config) {
         // Add oauth to plugins if not already present
         plugins: [
             ...config.plugins ?? [],
-            ...storagePlugin ? [
-                storagePlugin
+            ...config.figma.storage !== false ? [
+                createStoragePlugin(url, contentSystemId)
             ] : [],
             oAuth2Plugin({
                 collections: [
@@ -219,6 +295,7 @@ export async function buildFigmaConfig(config) {
                         usernameField: 'email'
                     }
                 ],
+                ...isProduction ? {} : getDevCookieNames(contentSystemId),
                 debug: !!process.env.DEBUG,
                 disabled: false
             }),

package/dist/plugin/dev-cookie-names.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Namespace OAuth cookies per-app in local dev so multiple Payload apps
+ * running on localhost (shared cookie jar across ports) don't clobber each
+ * other's sessions on logout. Uses projectId so the cookie stays stable when
+ * switching environments in the same checkout; falls back to contentSystemId
+ * when projectId isn't in `.env`.
+ *
+ * In production, cookies are isolated by unique hostnames and this is unused.
+ */
+export declare function getDevCookieNames(contentSystemId: string): {
+    cookieName: string;
+    userInfoCookieName: string;
+};
+//# sourceMappingURL=dev-cookie-names.d.ts.map

package/dist/plugin/dev-cookie-names.js

@@ -0,0 +1,19 @@
+import { getEnvVarSync } from '../utils/env-management.js';
+/**
+ * Namespace OAuth cookies per-app in local dev so multiple Payload apps
+ * running on localhost (shared cookie jar across ports) don't clobber each
+ * other's sessions on logout. Uses projectId so the cookie stays stable when
+ * switching environments in the same checkout; falls back to contentSystemId
+ * when projectId isn't in `.env`.
+ *
+ * In production, cookies are isolated by unique hostnames and this is unused.
+ */ export function getDevCookieNames(contentSystemId) {
+    const projectId = process.env.FIGMA_PROJECT_ID ?? getEnvVarSync(process.cwd(), 'FIGMA_PROJECT_ID') ?? contentSystemId;
+    const suffix = projectId.slice(0, 8);
+    return {
+        cookieName: `figma-${suffix}-oauth-token`,
+        userInfoCookieName: `figma-${suffix}-user-info`
+    };
+}
+
+//# sourceMappingURL=dev-cookie-names.js.map

package/dist/storage-content-api/client.js

@@ -18,7 +18,10 @@ function createStorageAuthMiddleware(config) {
                 if (auth.mode === 'apiKey') {
                     request.headers.set('X-Api-Key', auth.apiKey);
                 } else if (auth.mode === 'tokenStore') {
-                    const token = await getValidProjectToken(auth.tokenStore, contentSystemId);
+                    const token = await getValidProjectToken({
+                        tenantId: contentSystemId,
+                        tokenStore: auth.tokenStore
+                    });
                     if (!token) {
                         throw new Error('Authentication required. Run `npx @payloadcms/figma login` to authenticate.');
                     }

package/dist/utils/messages.js

@@ -14,6 +14,7 @@ export function helpMessage() {
       ${pc.cyan('logout')}           Clear all stored tokens
       ${pc.cyan('list-tokens')}      Show stored token information
       ${pc.cyan('init')}             Initialize a Figma CMS project
+      ${pc.cyan('bootstrap')}        Print bootstrap info (tenant IDs, OAuth creds) for a project
       ${pc.cyan('debug')}            Show debug info for troubleshooting
       ${pc.cyan('env')}              Switch active environment
       ${pc.cyan('deploy')}           Deploy your project to Figma
@@ -39,6 +40,12 @@ export function helpMessage() {
       ${pc.dim('--name, -n <name>')}                     Set project directory name (skips prompt)
       ${pc.dim('--force')}                               Force reconfiguration of existing project
 
+  ${pc.bold('BOOTSTRAP COMMAND')}
+
+      ${pc.cyan('@payloadcms/figma bootstrap --id <cms-resource-id>')}   Print bootstrap info
+      ${pc.dim('--env <environment>')}                   Filter to a single environment
+      ${pc.dim('--json')}                                 Output JSON instead of styled note
+
   ${pc.bold('ENV COMMAND')}
 
       ${pc.cyan('@payloadcms/figma env')}                    List and switch environments