@payloadcms/figma 0.0.1-alpha.6 → 0.0.1-alpha.60

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
@@ -27,6 +28,10 @@ export interface CreateTenantOptions {
  * Options for creating a new deployment
  */
 export interface CreateDeploymentOptions {
+    /** Pages keyed by route, each with its associated asset keys */
+    pages: Record<string, {
+        assets: string[];
+    }>;
     /** List of static asset paths that need upload URLs */
     staticAssets: string[];
 }
@@ -38,14 +43,17 @@ export interface CreateDeploymentResponse {
     codeUploadUrl: string;
     /** Unique deployment ID */
     deploymentId: string;
+    /** Map of page asset paths to their signed S3 upload URLs */
+    pageUploadUrls: Record<string, string>;
     /** Map of static asset paths to their signed S3 upload URLs */
     staticAssetUploadUrls: Record<string, string>;
 }
 export interface CreateDeploymentApiResponse {
     error: boolean;
     meta: {
-        code_upload_url: string;
         deployment_id: string;
+        lambda_zip_upload_url: string;
+        page_upload_urls: Record<string, string>;
         static_asset_upload_urls: Record<string, string>;
     };
     status: number;
@@ -65,6 +73,8 @@ export interface PerformDeploymentResponse {
     deploymentId: string;
     /** Status message */
     message: string;
+    /** List of tenant domains */
+    tenantDomains: string[];
 }
 export interface PerformDeploymentApiResponse {
     error: boolean;
@@ -72,6 +82,7 @@ export interface PerformDeploymentApiResponse {
         deployment_id: string;
         message: string;
         status: string;
+        tenant_domains: string[];
     };
     status: number;
 }
@@ -82,7 +93,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
@@ -91,7 +102,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}
@@ -100,7 +111,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
@@ -110,7 +121,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
@@ -120,5 +131,40 @@ 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
+ */
+export type BootstrapEnvironment = {
+    contentSystemId: string;
+    name: string;
+    tenantInstanceId: string;
+};
+/**
+ * Response from the bootstrap endpoint (camelCased)
+ */
+export type BootstrapInfo = {
+    environments: BootstrapEnvironment[];
+    oauthCredentials: {
+        oauthClientId: string;
+        oauthClientSecret: string;
+    };
+};
+/**
+ * Get bootstrap info for a CMS resource
+ * Maps to: GET /v1/cms/:cmsResourceId/bootstrap
+ *
+ * @param accessToken - OAuth access token
+ * @param cmsResourceId - CMS Resource ID (project ID)
+ * @param environmentName - Optional environment name filter
+ */
+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
+ *
+ * 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(credential: AuthCredential, datasetId: string): Promise<string>;
 //# sourceMappingURL=control-plane.d.ts.map

package/dist/api/control-plane.js

@@ -2,18 +2,13 @@
  * Control Plane API Client
  *
  * TODO: Replace with real API calls when Control Plane is available
- */ import { getEnvironment } from '../constants.js';
+ */ import { getAuthHeaders } from '../auth/credentials.js';
+import { getEnvConfig } from '../constants.js';
 import * as log from '../utils/log.js';
-/**
- * Control Plane API base URLs
- */ const CONTROL_PLANE_API_URLS = {
-    production: 'https://api.figma.com',
-    staging: 'https://api.staging.figma.com'
-};
 /**
  * Get the Control Plane API base URL based on environment
  */ function getControlPlaneBaseUrl() {
-    return process.env.FIGMA_API_BASE_URL || CONTROL_PLANE_API_URLS[getEnvironment()];
+    return process.env.FIGMA_API_BASE_URL || getEnvConfig().apiBaseUrl;
 }
 /**
  * Error thrown when Control Plane API calls fail
@@ -31,10 +26,8 @@ import * as log from '../utils/log.js';
  *
  * @param accessToken - OAuth access token
  * @returns Array of tenant instances
- */ export async function listTenants(accessToken) {
-    // Check if control plane API should be mocked
-    // Default to true until real API is available
-    const shouldMock = process.env.FIGMA_MOCK_CONTROL_PLANE !== 'false';
+ */ export async function listTenants(credential) {
+    const shouldMock = process.env.FIGMA_MOCK_CONTROL_PLANE === 'true';
     if (shouldMock) {
         // MOCK IMPLEMENTATION: Return sample tenants for testing
         log.debug('Using mock Control Plane API for listTenants (FIGMA_MOCK_CONTROL_PLANE != "false")');
@@ -58,14 +51,13 @@ import * as log from '../utils/log.js';
         ];
     }
     // REAL API IMPLEMENTATION
-    const response = await fetch(`${getControlPlaneBaseUrl()}/v1/tenant`, {
-        headers: {
-            Authorization: `Bearer ${accessToken}`
-        }
+    const response = await controlPlaneFetch({
+        context: 'list tenants',
+        options: {
+            headers: getAuthHeaders(credential)
+        },
+        url: `${getControlPlaneBaseUrl()}/v1/tenant`
     });
-    if (!response.ok) {
-        throw new ControlPlaneError(`Failed to list tenants: ${response.status} ${response.statusText}`, response.status);
-    }
     return response.json();
 }
 /**
@@ -75,9 +67,9 @@ 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 !== 'false';
+    const shouldMock = process.env.FIGMA_MOCK_CONTROL_PLANE === 'true';
     if (shouldMock) {
         // MOCK IMPLEMENTATION: Generate mock tenant for testing
         log.debug('Using mock Control Plane API for createTenant (FIGMA_MOCK_CONTROL_PLANE != "false")');
@@ -94,19 +86,20 @@ import * as log from '../utils/log.js';
         };
     }
     // REAL API IMPLEMENTATION
-    const response = await fetch(`${getControlPlaneBaseUrl()}/v1/tenant`, {
-        body: JSON.stringify({
-            name: options.name
-        }),
-        headers: {
-            Authorization: `Bearer ${accessToken}`,
-            'Content-Type': 'application/json'
+    const response = await controlPlaneFetch({
+        context: 'create tenant',
+        options: {
+            body: JSON.stringify({
+                name: options.name
+            }),
+            headers: {
+                ...getAuthHeaders(credential),
+                'Content-Type': 'application/json'
+            },
+            method: 'POST'
         },
-        method: 'POST'
+        url: `${getControlPlaneBaseUrl()}/v1/tenant`
     });
-    if (!response.ok) {
-        throw new ControlPlaneError(`Failed to create tenant: ${response.status} ${response.statusText}`, response.status);
-    }
     return response.json();
 }
 /**
@@ -116,9 +109,9 @@ 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 !== 'false';
+    const shouldMock = process.env.FIGMA_MOCK_CONTROL_PLANE === 'true';
     if (shouldMock) {
         // MOCK IMPLEMENTATION: Return mock tenant details for testing
         log.debug('Using mock Control Plane API for getTenantDetails (FIGMA_MOCK_CONTROL_PLANE != "false")');
@@ -132,14 +125,13 @@ import * as log from '../utils/log.js';
         };
     }
     // REAL API IMPLEMENTATION
-    const response = await fetch(`${getControlPlaneBaseUrl()}/v1/tenant/${tenantId}`, {
-        headers: {
-            Authorization: `Bearer ${accessToken}`
-        }
+    const response = await controlPlaneFetch({
+        context: 'get tenant details',
+        options: {
+            headers: getAuthHeaders(credential)
+        },
+        url: `${getControlPlaneBaseUrl()}/v1/tenant/${tenantId}`
     });
-    if (!response.ok) {
-        throw new ControlPlaneError(`Failed to get tenant details: ${response.status} ${response.statusText}`, response.status);
-    }
     return response.json();
 }
 /**
@@ -150,12 +142,12 @@ 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 !== 'false';
+    const shouldMock = process.env.FIGMA_MOCK_CONTROL_PLANE === 'true';
     if (shouldMock) {
         // MOCK IMPLEMENTATION: Generate mock deployment and signed URLs
-        log.debug('Using mock Control Plane API for createDeployment (FIGMA_MOCK_CONTROL_PLANE != "false")');
+        log.debug('Using mock Control Plane API for createDeployment (FIGMA_MOCK_CONTROL_PLANE === "true")');
         const deploymentId = `deploy_${Math.random().toString(36).substring(2, 11)}`;
         const mockBucket = 'figma-cms-deployments-mock';
         const mockRegion = 'us-west-2';
@@ -166,33 +158,54 @@ import * as log from '../utils/log.js';
             const encodedPath = encodeURIComponent(assetPath);
             staticAssetUploadUrls[assetPath] = `${mockBaseUrl}/${tenantId}/${deploymentId}/static/${encodedPath}?X-Amz-Signature=mock`;
         }
+        // Generate mock signed URLs for page assets
+        const pageUploadUrls = {};
+        for (const pageData of Object.values(options.pages)){
+            for (const assetPath of pageData.assets){
+                const encodedPath = encodeURIComponent(assetPath);
+                pageUploadUrls[assetPath] = `${mockBaseUrl}/${tenantId}/${deploymentId}/pages/${encodedPath}?X-Amz-Signature=mock`;
+            }
+        }
         // Generate mock signed URL for code zip
         const codeUploadUrl = `${mockBaseUrl}/${tenantId}/${deploymentId}/lambda.zip?X-Amz-Signature=mock`;
         return {
             codeUploadUrl,
             deploymentId,
+            pageUploadUrls,
             staticAssetUploadUrls
         };
     }
+    const url = `${getControlPlaneBaseUrl()}/v1/cms/tenant/${tenantId}/deploy/create`;
+    log.debug(`Calling createDeployment API at ${url}`);
+    // Build pages payload: { route: { assets: [...] } }
+    const pages = {};
+    for (const [route, pageData] of Object.entries(options.pages)){
+        pages[route] = {
+            assets: pageData.assets
+        };
+    }
     // REAL API IMPLEMENTATION
-    const response = await fetch(`${getControlPlaneBaseUrl()}/v1/tenant/${tenantId}/deploy/create`, {
-        body: JSON.stringify({
-            static_assets: options.staticAssets
-        }),
-        headers: {
-            Authorization: `Bearer ${accessToken}`,
-            'Content-Type': 'application/json'
+    const response = await controlPlaneFetch({
+        context: 'create deployment',
+        options: {
+            body: JSON.stringify({
+                pages,
+                static_assets: options.staticAssets
+            }),
+            headers: {
+                ...getAuthHeaders(credential),
+                'Content-Type': 'application/json'
+            },
+            method: 'POST'
         },
-        method: 'POST'
+        url
     });
-    if (!response.ok) {
-        throw new ControlPlaneError(`Failed to create deployment: ${response.status} ${response.statusText}`, response.status);
-    }
     const data = await response.json();
     // Map API response format to our interface
     return {
-        codeUploadUrl: data.meta.code_upload_url,
+        codeUploadUrl: data.meta.lambda_zip_upload_url,
         deploymentId: data.meta.deployment_id,
+        pageUploadUrls: data.meta.page_upload_urls,
         staticAssetUploadUrls: data.meta.static_asset_upload_urls
     };
 }
@@ -204,37 +217,126 @@ 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) {
-    // Check if control plane API should be mocked
-    const shouldMock = process.env.FIGMA_MOCK_CONTROL_PLANE !== 'false';
+ */ export async function performDeployment(credential, tenantId, options) {
+    const shouldMock = process.env.FIGMA_MOCK_CONTROL_PLANE === 'true';
     if (shouldMock) {
         // MOCK IMPLEMENTATION: Return mock deployment status
         log.debug('Using mock Control Plane API for performDeployment (FIGMA_MOCK_CONTROL_PLANE != "false")');
         return {
             deploymentId: options.deploymentId,
-            message: 'Deployment initiated successfully'
+            message: 'Deployment initiated successfully',
+            tenantDomains: [
+                'example.figmasource.site'
+            ]
         };
     }
+    const url = `${getControlPlaneBaseUrl()}/v1/cms/tenant/${tenantId}/deploy/perform`;
+    log.debug(`Calling performDeployment API at ${url}`);
     // REAL API IMPLEMENTATION
-    const response = await fetch(`${getControlPlaneBaseUrl()}/v1/tenant/${tenantId}/deploy/perform`, {
-        body: JSON.stringify({
-            deployment_id: options.deploymentId
-        }),
-        headers: {
-            Authorization: `Bearer ${accessToken}`,
-            'Content-Type': 'application/json'
+    const response = await controlPlaneFetch({
+        context: 'perform deployment',
+        options: {
+            body: JSON.stringify({
+                deployment_id: options.deploymentId
+            }),
+            headers: {
+                ...getAuthHeaders(credential),
+                'Content-Type': 'application/json'
+            },
+            method: 'POST'
         },
-        method: 'POST'
+        url
     });
-    if (!response.ok) {
-        throw new ControlPlaneError(`Failed to perform deployment: ${response.status} ${response.statusText}`, response.status);
-    }
     const data = await response.json();
     // Map API response to our interface
     return {
         deploymentId: data.meta.deployment_id,
-        message: data.meta.message || 'Deployment initiated'
+        message: data.meta.message || 'Deployment initiated',
+        tenantDomains: data.meta.tenant_domains
+    };
+}
+/**
+ * Get bootstrap info for a CMS resource
+ * Maps to: GET /v1/cms/:cmsResourceId/bootstrap
+ *
+ * @param accessToken - OAuth access token
+ * @param cmsResourceId - CMS Resource ID (project ID)
+ * @param environmentName - Optional environment name filter
+ */ export async function getBootstrapInfo(credential, cmsResourceId, environmentName) {
+    const baseUrl = getControlPlaneBaseUrl();
+    let url = `${baseUrl}/v1/cms/${cmsResourceId}/bootstrap`;
+    if (environmentName) {
+        url += `?environment_name=${encodeURIComponent(environmentName)}`;
+    }
+    log.debug(`Calling getBootstrapInfo API at ${url}`);
+    const response = await controlPlaneFetch({
+        context: 'get bootstrap info',
+        options: {
+            headers: getAuthHeaders(credential)
+        },
+        url
+    });
+    const data = await response.json();
+    return {
+        environments: data.meta.environments.map((env)=>({
+                name: env.name,
+                contentSystemId: env.content_system_id,
+                tenantInstanceId: env.tenant_instance_id
+            })),
+        oauthCredentials: {
+            oauthClientId: data.meta.oauth_credentials.oauth_client_id,
+            oauthClientSecret: data.meta.oauth_credentials.oauth_client_secret
+        }
     };
 }
+/**
+ * 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(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: getAuthHeaders(credential)
+        },
+        url
+    });
+    const data = await response.json();
+    return data.meta.cms_resource_id;
+}
+const MAX_RETRIES = 3;
+const INITIAL_RETRY_DELAY = 1000;
+function sleep(ms) {
+    return new Promise((resolve)=>setTimeout(resolve, ms));
+}
+async function controlPlaneFetch(params) {
+    const { context, options, url } = params;
+    let lastError;
+    for(let attempt = 0; attempt < MAX_RETRIES; attempt++){
+        try {
+            const response = await fetch(url, options);
+            if (response.ok) {
+                return response;
+            }
+            if (response.status < 500) {
+                throw new ControlPlaneError(`Failed to ${context}: ${response.status} ${response.statusText}`, response.status);
+            }
+            lastError = new ControlPlaneError(`Failed to ${context}: ${response.status} ${response.statusText}`, response.status);
+        } catch (error) {
+            if (error instanceof ControlPlaneError) {
+                throw error;
+            }
+            lastError = error instanceof Error ? error : new Error('Unknown error');
+        }
+        if (attempt < MAX_RETRIES - 1) {
+            await sleep(INITIAL_RETRY_DELAY * Math.pow(2, attempt));
+        }
+    }
+    throw new ControlPlaneError(`Network error while ${context}: ${lastError?.message || 'Unknown error'}`, undefined, lastError);
+}
 
 //# sourceMappingURL=control-plane.js.map

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

@@ -4,7 +4,17 @@
  * 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
+ */
+export type FigmaUserInfo = {
+    email: string;
+    handle: string;
+    id: string;
+    img_url: string;
+};
 /**
  * Error thrown when Figma API calls fail
  */
@@ -27,5 +37,16 @@ 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
+ *
+ * Endpoint: GET https://api.figma.com/v1/me
+ * Requires OAuth access_token (not project token)
+ *
+ * @param accessToken - OAuth access token for authentication
+ * @returns FigmaUserInfo with user profile data
+ * @throws {FigmaApiError} If the API call fails
+ */
+export declare function getUserInfo(credential: AuthCredential): Promise<FigmaUserInfo>;
 //# sourceMappingURL=figma-api.d.ts.map

package/dist/api/figma-api.js

@@ -3,7 +3,9 @@
  *
  * Client for Figma REST API (Pixie) endpoints
  * Handles project token generation and other CMS-related API calls
- */ import * as log from '../utils/log.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
  */ export class FigmaApiError extends Error {
@@ -14,19 +16,6 @@
         this.name = 'FigmaApiError';
     }
 }
-/**
- * Base URLs for Figma API
- */ const API_BASE_URLS = {
-    prod: 'https://api.figma.com',
-    staging: 'https://api.staging.figma.com'
-};
-/**
- * Get the Figma API base URL based on environment
- * TODO: Use this once real API endpoints are available
- */ function _getApiBaseUrl() {
-    // For now, default to staging to match OAuth config
-    return process.env.FIGMA_API_BASE_URL || API_BASE_URLS.staging;
-}
 /**
  * Get a project token (JWT) for a specific tenant/CMS
  *
@@ -40,14 +29,42 @@
  * @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) {
-    // Check if project token API should be mocked
-    // Default to true until real API is available
-    const shouldMock = process.env.FIGMA_MOCK_PROJECT_TOKEN !== 'false';
+ */ 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) {
+        log.debug('Using direct project token from FIGMA_MOCK_PROJECT_TOKEN_VALUE');
+        try {
+            // Parse JWT payload to extract claims
+            const parts = envTokenValue.split('.');
+            if (parts.length !== 3) {
+                throw new Error('Invalid JWT format: must have 3 parts (header.payload.signature)');
+            }
+            const payload = parts[1];
+            const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+            const paddedBase64 = base64.padEnd(base64.length + (4 - base64.length % 4) % 4, '=');
+            const decodedPayload = JSON.parse(Buffer.from(paddedBase64, 'base64').toString('utf-8'));
+            if (!decodedPayload.exp || typeof decodedPayload.exp !== 'number') {
+                throw new Error('JWT payload missing exp claim');
+            }
+            // Extract tenant ID from aud claim (use parameter as fallback)
+            const extractedTenantId = decodedPayload.aud || tenantId;
+            return {
+                expiresAt: decodedPayload.exp * 1000,
+                tenantId: extractedTenantId,
+                token: envTokenValue
+            };
+        } catch (error) {
+            throw new FigmaApiError(`Invalid JWT token in FIGMA_MOCK_PROJECT_TOKEN_VALUE: ${error instanceof Error ? error.message : 'Unknown error'}`, undefined, error instanceof Error ? error : undefined);
+        }
+    }
+    // Priority 2: Check if project token API should be mocked
+    // Default to false (use real API)
+    const shouldMock = process.env.FIGMA_MOCK_PROJECT_TOKEN === 'true';
     try {
         if (shouldMock) {
             // MOCK IMPLEMENTATION: Generate a mock JWT token for testing
-            log.debug('Using mock project token API for getProjectToken (FIGMA_MOCK_PROJECT_TOKEN != "false")');
+            log.debug('Using mock project token API for getProjectToken (FIGMA_MOCK_PROJECT_TOKEN = "true")');
             const mockToken = createMockJWT(tenantId, 25) // 25 minutes expiry
             ;
             // Mock response data
@@ -68,12 +85,10 @@
             };
         }
         // REAL API IMPLEMENTATION
-        const baseUrl = _getApiBaseUrl();
+        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) {
@@ -81,12 +96,19 @@
             let errorMessage = `Failed to get project token: ${response.status} ${response.statusText}`;
             try {
                 const errorBody = await response.json();
-                if (errorBody.error || errorBody.message) {
-                    errorMessage = errorBody.error || errorBody.message;
+                // Only use string error messages (API may return { error: true })
+                if (typeof errorBody.message === 'string') {
+                    errorMessage = errorBody.message;
+                } else if (typeof errorBody.error === 'string') {
+                    errorMessage = errorBody.error;
                 }
             } catch  {
             // Ignore JSON parse errors for error body
             }
+            // Provide actionable error for common cases
+            if (response.status === 404) {
+                errorMessage = `Content System ID "${tenantId}" not found. Ensure FIGMA_CONTENT_API_CONTENT_SYSTEM_ID is set to a valid content system ID in your .env file.`;
+            }
             throw new FigmaApiError(errorMessage, response.status);
         }
         const data = await response.json();
@@ -165,5 +187,36 @@
         throw new FigmaApiError(`Failed to parse JWT expiry: ${error instanceof Error ? error.message : 'Unknown error'}`, undefined, error instanceof Error ? error : undefined);
     }
 }
+/**
+ * Get user info from Figma API
+ *
+ * Endpoint: GET https://api.figma.com/v1/me
+ * Requires OAuth access_token (not project token)
+ *
+ * @param accessToken - OAuth access token for authentication
+ * @returns FigmaUserInfo with user profile data
+ * @throws {FigmaApiError} If the API call fails
+ */ 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: getAuthHeaders(credential)
+        });
+        if (!response.ok) {
+            throw new FigmaApiError(`Failed to get user info: ${response.status} ${response.statusText}`, response.status);
+        }
+        const data = await response.json();
+        if (!data.id || !data.email || typeof data.handle !== 'string') {
+            throw new FigmaApiError('Invalid user info response: missing required fields');
+        }
+        return data;
+    } catch (error) {
+        if (error instanceof FigmaApiError) {
+            throw error;
+        }
+        throw new FigmaApiError(`Failed to get user info: ${error instanceof Error ? error.message : 'Unknown error'}`, undefined, error instanceof Error ? error : undefined);
+    }
+}
 
 //# sourceMappingURL=figma-api.js.map