@payloadcms/figma 0.0.1-alpha.58 → 0.0.1-alpha.59

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

@@ -3,6 +3,7 @@
  *
  * TODO: Replace with real API calls when Control Plane is available
  */
+import type { AuthCredential } from '../auth/credentials.js';
 import type { Tenant } from '../types/config.js';
 /**
  * Error thrown when Control Plane API calls fail
@@ -85,7 +86,7 @@ export interface PerformDeploymentApiResponse {
  * @param accessToken - OAuth access token
  * @returns Array of tenant instances
  */
-export declare function listTenants(accessToken: string): Promise<Tenant[]>;
+export declare function listTenants(credential: AuthCredential): Promise<Tenant[]>;
 /**
  * Create a new tenant instance
  * Maps to: POST /v1/tenant
@@ -94,7 +95,7 @@ export declare function listTenants(accessToken: string): Promise<Tenant[]>;
  * @param options - Tenant creation options
  * @returns Newly created tenant
  */
-export declare function createTenant(accessToken: string, options: CreateTenantOptions): Promise<Tenant>;
+export declare function createTenant(credential: AuthCredential, options: CreateTenantOptions): Promise<Tenant>;
 /**
  * Get details for a specific tenant
  * Maps to: GET /v1/tenant/{tenant_id}
@@ -103,7 +104,7 @@ export declare function createTenant(accessToken: string, options: CreateTenantO
  * @param tenantId - Tenant ID
  * @returns Tenant details
  */
-export declare function getTenantDetails(accessToken: string, tenantId: string): Promise<Tenant>;
+export declare function getTenantDetails(credential: AuthCredential, tenantId: string): Promise<Tenant>;
 /**
  * Create a new deployment and get signed upload URLs
  * Maps to: POST /v1/tenant/{tenant_id}/deploy/create
@@ -113,7 +114,7 @@ export declare function getTenantDetails(accessToken: string, tenantId: string):
  * @param options - Deployment creation options
  * @returns Deployment ID and upload URLs
  */
-export declare function createDeployment(accessToken: string, tenantId: string, options: CreateDeploymentOptions): Promise<CreateDeploymentResponse>;
+export declare function createDeployment(credential: AuthCredential, tenantId: string, options: CreateDeploymentOptions): Promise<CreateDeploymentResponse>;
 /**
  * Perform deployment for a created deployment ID
  * Maps to: POST /v1/tenant/{tenant_id}/deploy/perform
@@ -123,7 +124,7 @@ export declare function createDeployment(accessToken: string, tenantId: string,
  * @param options - Deployment perform options
  * @returns Deployment status and message
  */
-export declare function performDeployment(accessToken: string, tenantId: string, options: PerformDeploymentOptions): Promise<PerformDeploymentResponse>;
+export declare function performDeployment(credential: AuthCredential, tenantId: string, options: PerformDeploymentOptions): Promise<PerformDeploymentResponse>;
 /**
  * A single environment returned by the bootstrap endpoint
  */
@@ -150,7 +151,7 @@ export type BootstrapInfo = {
  * @param cmsResourceId - CMS Resource ID (project ID)
  * @param environmentName - Optional environment name filter
  */
-export declare function getBootstrapInfo(accessToken: string, cmsResourceId: string, environmentName?: string): Promise<BootstrapInfo>;
+export declare function getBootstrapInfo(credential: AuthCredential, 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
@@ -158,5 +159,5 @@ export declare function getBootstrapInfo(accessToken: string, cmsResourceId: str
  * 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>;
+export declare function getCmsResourceId(credential: AuthCredential, datasetId: string): Promise<string>;
 //# sourceMappingURL=control-plane.d.ts.map

package/dist/api/control-plane.js

@@ -2,7 +2,8 @@
  * Control Plane API Client
  *
  * TODO: Replace with real API calls when Control Plane is available
- */ import { getEnvConfig } from '../constants.js';
+ */ import { getAuthHeaders } from '../auth/credentials.js';
+import { getEnvConfig } from '../constants.js';
 import * as log from '../utils/log.js';
 /**
  * Get the Control Plane API base URL based on environment
@@ -25,7 +26,7 @@ import * as log from '../utils/log.js';
  *
  * @param accessToken - OAuth access token
  * @returns Array of tenant instances
- */ export async function listTenants(accessToken) {
+ */ export async function listTenants(credential) {
     const shouldMock = process.env.FIGMA_MOCK_CONTROL_PLANE === 'true';
     if (shouldMock) {
         // MOCK IMPLEMENTATION: Return sample tenants for testing
@@ -53,9 +54,7 @@ import * as log from '../utils/log.js';
     const response = await controlPlaneFetch({
         context: 'list tenants',
         options: {
-            headers: {
-                Authorization: `Bearer ${accessToken}`
-            }
+            headers: getAuthHeaders(credential)
         },
         url: `${getControlPlaneBaseUrl()}/v1/tenant`
     });
@@ -68,7 +67,7 @@ import * as log from '../utils/log.js';
  * @param accessToken - OAuth access token
  * @param options - Tenant creation options
  * @returns Newly created tenant
- */ export async function createTenant(accessToken, options) {
+ */ export async function createTenant(credential, options) {
     // Check if control plane API should be mocked
     const shouldMock = process.env.FIGMA_MOCK_CONTROL_PLANE === 'true';
     if (shouldMock) {
@@ -94,7 +93,7 @@ import * as log from '../utils/log.js';
                 name: options.name
             }),
             headers: {
-                Authorization: `Bearer ${accessToken}`,
+                ...getAuthHeaders(credential),
                 'Content-Type': 'application/json'
             },
             method: 'POST'
@@ -110,7 +109,7 @@ import * as log from '../utils/log.js';
  * @param accessToken - OAuth access token
  * @param tenantId - Tenant ID
  * @returns Tenant details
- */ export async function getTenantDetails(accessToken, tenantId) {
+ */ export async function getTenantDetails(credential, tenantId) {
     // Check if control plane API should be mocked
     const shouldMock = process.env.FIGMA_MOCK_CONTROL_PLANE === 'true';
     if (shouldMock) {
@@ -129,9 +128,7 @@ import * as log from '../utils/log.js';
     const response = await controlPlaneFetch({
         context: 'get tenant details',
         options: {
-            headers: {
-                Authorization: `Bearer ${accessToken}`
-            }
+            headers: getAuthHeaders(credential)
         },
         url: `${getControlPlaneBaseUrl()}/v1/tenant/${tenantId}`
     });
@@ -145,7 +142,7 @@ import * as log from '../utils/log.js';
  * @param tenantId - Tenant ID
  * @param options - Deployment creation options
  * @returns Deployment ID and upload URLs
- */ export async function createDeployment(accessToken, tenantId, options) {
+ */ export async function createDeployment(credential, tenantId, options) {
     // Check if control plane API should be mocked
     const shouldMock = process.env.FIGMA_MOCK_CONTROL_PLANE === 'true';
     if (shouldMock) {
@@ -179,7 +176,7 @@ import * as log from '../utils/log.js';
                 static_assets: options.staticAssets
             }),
             headers: {
-                Authorization: `Bearer ${accessToken}`,
+                ...getAuthHeaders(credential),
                 'Content-Type': 'application/json'
             },
             method: 'POST'
@@ -202,7 +199,7 @@ import * as log from '../utils/log.js';
  * @param tenantId - Tenant ID
  * @param options - Deployment perform options
  * @returns Deployment status and message
- */ export async function performDeployment(accessToken, tenantId, options) {
+ */ export async function performDeployment(credential, tenantId, options) {
     const shouldMock = process.env.FIGMA_MOCK_CONTROL_PLANE === 'true';
     if (shouldMock) {
         // MOCK IMPLEMENTATION: Return mock deployment status
@@ -225,7 +222,7 @@ import * as log from '../utils/log.js';
                 deployment_id: options.deploymentId
             }),
             headers: {
-                Authorization: `Bearer ${accessToken}`,
+                ...getAuthHeaders(credential),
                 'Content-Type': 'application/json'
             },
             method: 'POST'
@@ -247,7 +244,7 @@ import * as log from '../utils/log.js';
  * @param accessToken - OAuth access token
  * @param cmsResourceId - CMS Resource ID (project ID)
  * @param environmentName - Optional environment name filter
- */ export async function getBootstrapInfo(accessToken, cmsResourceId, environmentName) {
+ */ export async function getBootstrapInfo(credential, cmsResourceId, environmentName) {
     const baseUrl = getControlPlaneBaseUrl();
     let url = `${baseUrl}/v1/cms/${cmsResourceId}/bootstrap`;
     if (environmentName) {
@@ -257,9 +254,7 @@ import * as log from '../utils/log.js';
     const response = await controlPlaneFetch({
         context: 'get bootstrap info',
         options: {
-            headers: {
-                Authorization: `Bearer ${accessToken}`
-            }
+            headers: getAuthHeaders(credential)
         },
         url
     });
@@ -282,15 +277,13 @@ import * as log from '../utils/log.js';
  *
  * 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) {
+ */ export async function getCmsResourceId(credential, 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}`
-            }
+            headers: getAuthHeaders(credential)
         },
         url
     });

package/dist/api/figma-api.d.ts

@@ -4,6 +4,7 @@
  * Client for Figma REST API (Pixie) endpoints
  * Handles project token generation and other CMS-related API calls
  */
+import type { AuthCredential } from '../auth/credentials.js';
 import type { ProjectToken } from '../auth/types.js';
 /**
  * User info from Figma API /v1/me endpoint
@@ -36,7 +37,7 @@ export declare class FigmaApiError extends Error {
  * @returns ProjectToken with JWT and expiry information
  * @throws {FigmaApiError} If the API call fails
  */
-export declare function getProjectToken(accessToken: string, tenantId: string): Promise<ProjectToken>;
+export declare function getProjectToken(credential: AuthCredential, tenantId: string): Promise<ProjectToken>;
 /**
  * Get user info from Figma API
  *
@@ -47,5 +48,5 @@ export declare function getProjectToken(accessToken: string, tenantId: string):
  * @returns FigmaUserInfo with user profile data
  * @throws {FigmaApiError} If the API call fails
  */
-export declare function getUserInfo(accessToken: string): Promise<FigmaUserInfo>;
+export declare function getUserInfo(credential: AuthCredential): Promise<FigmaUserInfo>;
 //# sourceMappingURL=figma-api.d.ts.map

package/dist/api/figma-api.js

@@ -3,7 +3,8 @@
  *
  * Client for Figma REST API (Pixie) endpoints
  * Handles project token generation and other CMS-related API calls
- */ import { getEnvConfig } from '../constants.js';
+ */ import { getAuthHeaders } from '../auth/credentials.js';
+import { getEnvConfig } from '../constants.js';
 import * as log from '../utils/log.js';
 /**
  * Error thrown when Figma API calls fail
@@ -28,7 +29,7 @@ import * as log from '../utils/log.js';
  * @param tenantId - The tenant/CMS ID
  * @returns ProjectToken with JWT and expiry information
  * @throws {FigmaApiError} If the API call fails
- */ export async function getProjectToken(accessToken, tenantId) {
+ */ export async function getProjectToken(credential, tenantId) {
     // Priority 1: Check for direct token value from environment
     const envTokenValue = process.env.FIGMA_MOCK_PROJECT_TOKEN_VALUE;
     if (envTokenValue) {
@@ -87,9 +88,7 @@ import * as log from '../utils/log.js';
         const baseUrl = process.env.FIGMA_API_BASE_URL || getEnvConfig().apiBaseUrl;
         const url = `${baseUrl}/v1/cms/${tenantId}/token/`;
         const response = await fetch(url, {
-            headers: {
-                Authorization: `Bearer ${accessToken}`
-            },
+            headers: getAuthHeaders(credential),
             method: 'POST'
         });
         if (!response.ok) {
@@ -197,14 +196,12 @@ import * as log from '../utils/log.js';
  * @param accessToken - OAuth access token for authentication
  * @returns FigmaUserInfo with user profile data
  * @throws {FigmaApiError} If the API call fails
- */ export async function getUserInfo(accessToken) {
+ */ export async function getUserInfo(credential) {
     const baseUrl = process.env.FIGMA_API_BASE_URL || getEnvConfig().apiBaseUrl;
     const url = `${baseUrl}/v1/me`;
     try {
         const response = await fetch(url, {
-            headers: {
-                Authorization: `Bearer ${accessToken}`
-            }
+            headers: getAuthHeaders(credential)
         });
         if (!response.ok) {
             throw new FigmaApiError(`Failed to get user info: ${response.status} ${response.statusText}`, response.status);

package/dist/auth/credentials.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Auth Access Tokens types for CLI authentication
+ *
+ * Distinguishes between OAuth tokens (Authorization: Bearer) and
+ * Plan Access Tokens (X-Figma-Token header).
+ */
+/**
+ * Represents an authenticated credential — either OAuth or PAT
+ */
+export type AuthCredential = {
+    token: string;
+    type: 'oauth';
+} | {
+    token: string;
+    type: 'plan_access_token';
+};
+/**
+ * Build the correct auth headers for a credential
+ */
+export declare function getAuthHeaders(credential: AuthCredential): Record<string, string>;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/auth/credentials.js

@@ -0,0 +1,21 @@
+/**
+ * Auth Access Tokens types for CLI authentication
+ *
+ * Distinguishes between OAuth tokens (Authorization: Bearer) and
+ * Plan Access Tokens (X-Figma-Token header).
+ */ /**
+ * Represents an authenticated credential — either OAuth or PAT
+ */ /**
+ * Build the correct auth headers for a credential
+ */ export function getAuthHeaders(credential) {
+    if (credential.type === 'plan_access_token') {
+        return {
+            'X-Figma-Token': credential.token
+        };
+    }
+    return {
+        Authorization: `Bearer ${credential.token}`
+    };
+}
+
+//# sourceMappingURL=credentials.js.map

package/dist/auth/oauth-flow.d.ts

@@ -1,3 +1,4 @@
+import type { AuthCredential } from './credentials.js';
 import type { TokenStore } from './token-store.js';
 import type { FigmaTokens } from './types.js';
 /**
@@ -55,13 +56,21 @@ export declare function executeOAuthFlow(tokenStore: TokenStore, options?: OAuth
  * refreshes using the refresh token. If no tokens exist, returns null.
  *
  * @param tokenStore - Token store to use
- * @returns Promise resolving to access token or null if no valid tokens
+ * @returns Promise resolving to AuthCredential (wrapped access token) or null if no valid tokens
  * @throws OAuthFlowError if refresh fails
  */
-export declare function getValidAccessToken(tokenStore: TokenStore): Promise<null | string>;
+export declare function getValidOAuthAccessToken(tokenStore: TokenStore): Promise<AuthCredential | null>;
 /**
- * Like getValidAccessToken but returns null instead of throwing on refresh failure.
+ * Get a valid auth credential, checking process.env for plan access token
+ * first before checking tokenStore for OAuth tokens.
+ * *
+ * @param tokenStore - Token store to use for OAuth tokens
+ * @returns Promise resolving to AuthCredential or null
+ */
+export declare function getValidCredential(tokenStore: TokenStore): Promise<AuthCredential | null>;
+/**
+ * Like getValidCredential but returns null instead of throwing on refresh failure.
  * Use in commands that want to fall through to a login prompt on failure.
  */
-export declare function tryGetAccessToken(tokenStore: TokenStore): Promise<null | string>;
+export declare function tryGetCredential(tokenStore: TokenStore): Promise<AuthCredential | null>;
 //# sourceMappingURL=oauth-flow.d.ts.map

package/dist/auth/oauth-flow.js

@@ -143,12 +143,16 @@ import { exchangeCodeForTokens, refreshAccessToken, TokenRefreshError } from './
  * refreshes using the refresh token. If no tokens exist, returns null.
  *
  * @param tokenStore - Token store to use
- * @returns Promise resolving to access token or null if no valid tokens
+ * @returns Promise resolving to AuthCredential (wrapped access token) or null if no valid tokens
  * @throws OAuthFlowError if refresh fails
- */ export async function getValidAccessToken(tokenStore) {
+ */ export async function getValidOAuthAccessToken(tokenStore) {
     // Check if we have valid tokens
     if (tokenStore.hasValidTokens()) {
-        return tokenStore.getAccessToken();
+        const token = tokenStore.getAccessToken();
+        return token ? {
+            type: 'oauth',
+            token
+        } : null;
     }
     // Check if we have a refresh token
     const refreshToken = tokenStore.getRefreshToken();
@@ -159,7 +163,10 @@ import { exchangeCodeForTokens, refreshAccessToken, TokenRefreshError } from './
     try {
         const tokens = await refreshAccessToken(refreshToken);
         tokenStore.setTokens(tokens);
-        return tokens.accessToken;
+        return {
+            type: 'oauth',
+            token: tokens.accessToken
+        };
     } catch (error) {
         const isAuthFailure = error instanceof TokenRefreshError && (error.statusCode === 401 || error.statusCode === 403 || error.statusCode === 400 && error.errorCode === 'invalid_grant');
         if (isAuthFailure) {
@@ -167,7 +174,10 @@ import { exchangeCodeForTokens, refreshAccessToken, TokenRefreshError } from './
             try {
                 const tokens = await refreshAccessToken(refreshToken);
                 tokenStore.setTokens(tokens);
-                return tokens.accessToken;
+                return {
+                    type: 'oauth',
+                    token: tokens.accessToken
+                };
             } catch  {
                 // Retry also failed — token is genuinely revoked
                 tokenStore.clearTokens();
@@ -177,11 +187,27 @@ import { exchangeCodeForTokens, refreshAccessToken, TokenRefreshError } from './
     }
 }
 /**
- * Like getValidAccessToken but returns null instead of throwing on refresh failure.
+ * Get a valid auth credential, checking process.env for plan access token
+ * first before checking tokenStore for OAuth tokens.
+ * *
+ * @param tokenStore - Token store to use for OAuth tokens
+ * @returns Promise resolving to AuthCredential or null
+ */ export async function getValidCredential(tokenStore) {
+    const envFigmaAccessToken = process.env.FIGMA_ACCESS_TOKEN;
+    if (envFigmaAccessToken) {
+        return {
+            type: 'plan_access_token',
+            token: envFigmaAccessToken
+        };
+    }
+    return getValidOAuthAccessToken(tokenStore);
+}
+/**
+ * Like getValidCredential but returns null instead of throwing on refresh failure.
  * Use in commands that want to fall through to a login prompt on failure.
- */ export async function tryGetAccessToken(tokenStore) {
+ */ export async function tryGetCredential(tokenStore) {
     try {
-        return await getValidAccessToken(tokenStore);
+        return await getValidCredential(tokenStore);
     } catch  {
         return null;
     }

package/dist/auth/project-token.js

@@ -8,7 +8,7 @@
 import { getInfraEnvironment } from '../constants.js';
 import * as log from '../utils/log.js';
 import { JWTValidationError, validateProjectToken } from './jwt-validator.js';
-import { getValidAccessToken } from './oauth-flow.js';
+import { getValidCredential } from './oauth-flow.js';
 /**
  * Error during project token operations
  */ export class ProjectTokenError extends Error {
@@ -71,18 +71,18 @@ import { getValidAccessToken } from './oauth-flow.js';
     }
     // We need to refresh the project token
     // An oauth access token is required for the call
-    let accessToken;
+    let credential;
     try {
-        accessToken = await getValidAccessToken(tokenStore);
+        credential = await getValidCredential(tokenStore);
     } catch (error) {
         throw new ProjectTokenError('Failed to get valid access token for project token refresh', error instanceof Error ? error : undefined);
     }
-    if (!accessToken) {
+    if (!credential) {
         // No valid user tokens available - user needs to authenticate
         return null;
     }
     // Fetch a new project token from the Figma API
-    const projectToken = await fetchProjectToken(accessToken, tenantId);
+    const projectToken = await fetchProjectToken(credential, tenantId);
     // Validate the JWT signature and claims (skip for mocks)
     const hasEnvToken = !!process.env.FIGMA_MOCK_PROJECT_TOKEN_VALUE;
     const shouldMock = process.env.FIGMA_MOCK_PROJECT_TOKEN !== 'false';

package/dist/cli.js

@@ -29,6 +29,10 @@ class Main {
     constructor(){
         // @ts-expect-error bad typings
         this.args = arg({
+            // Hidden flag — intentionally not displayed in help output yet.
+            // Auto-detection covers most cases; this is an escape hatch for testing.
+            // May expose in help text once multi-framework support is public.
+            '--adapter': String,
             '--all': Boolean,
             '--debug': Boolean,
             '--dry-run': Boolean,
@@ -106,6 +110,7 @@ class Main {
                 case 'deploy':
                     await deployCommand({
                         id: this.args['--id'],
+                        adapter: this.args['--adapter'],
                         debug: this.args['--debug'],
                         env: this.args['--env'],
                         skipBuild: this.args['--skip-build'],

package/dist/commands/deploy.d.ts

@@ -1,7 +1,10 @@
+import type { AdapterName } from '../utils/deploy-adapter.js';
 /**
  * Options for deploy command
  */
 export interface DeployCommandOptions {
+    /** Framework adapter (nextjs, nitro, vite). Auto-detected if omitted. */
+    adapter?: AdapterName;
     /** Enable debug mode */
     debug?: boolean;
     /** Figma environment name (e.g. 'production', 'staging') */