@payloadcms/figma 0.0.1-alpha.9 → 0.1.0-alpha.0

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,14 @@ export interface CreateTenantOptions {
  * Options for creating a new deployment
  */
 export interface CreateDeploymentOptions {
+    /** Framework adapter name (e.g., "vite", "nextjs"). Forwarded to Gatekeeper. */
+    adapter?: string;
+    /** SPA fallback path (e.g., "/index.html"). Vite-only. */
+    fallback?: string;
+    /** 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 +47,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 +77,8 @@ export interface PerformDeploymentResponse {
     deploymentId: string;
     /** Status message */
     message: string;
+    /** List of tenant domains */
+    tenantDomains: string[];
 }
 export interface PerformDeploymentApiResponse {
     error: boolean;
@@ -72,6 +86,7 @@ export interface PerformDeploymentApiResponse {
         deployment_id: string;
         message: string;
         status: string;
+        tenant_domains: string[];
     };
     status: number;
 }
@@ -82,7 +97,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 +106,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 +115,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 +125,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 +135,39 @@ 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>;
-//# sourceMappingURL=control-plane.d.ts.map
+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>;

package/dist/api/control-plane.js

@@ -2,18 +2,14 @@
  * 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'
-};
+import { parseControlPlaneApiError } from './error-response.js';
 /**
  * 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 getEnvConfig().apiBaseUrl;
 }
 /**
  * Error thrown when Control Plane API calls fail
@@ -31,10 +27,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 +52,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 +68,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 +87,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 +110,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 +126,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 +143,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 +159,61 @@ 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
+        };
+    }
+    const body = {
+        pages,
+        static_assets: options.staticAssets
+    };
+    if (options.adapter) {
+        body.adapter = options.adapter;
+    }
+    if (options.fallback) {
+        body.fallback = options.fallback;
+    }
     // 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(body),
+            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 +225,130 @@ 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
     };
 }
-
-//# sourceMappingURL=control-plane.js.map
+/**
+ * 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(await parseControlPlaneApiError({
+                    context,
+                    response
+                }), response.status);
+            }
+            lastError = new ControlPlaneError(await parseControlPlaneApiError({
+                context,
+                response
+            }), 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);
+}

package/dist/api/error-response.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Extract a human-readable error message from a non-ok control-plane API Response.
+ *
+ * Sinatra's error helpers (api_error, api_reject, api_not_found, api_needs_upgrade)
+ * all serialize the user-facing string under a `message` key. Surfacing it lets the
+ * CLI show the real reason (e.g. "Deployment package is too large...") instead of a
+ * bare status code.
+ *
+ * Scoped to JSON `{ message }` bodies. S3 upload errors arrive as XML and need a
+ * separate parser.
+ *
+ * Only called on the error path, immediately before throwing — the body is never read
+ * again, so consuming it here is safe (no clone needed). Never throws: any parse
+ * failure or missing message falls back to the HTTP status line.
+ */
+export declare function parseControlPlaneApiError(params: {
+    context: string;
+    response: Response;
+}): Promise<string>;
+/**
+ * Extract a human-readable error message from a non-ok S3 upload Response.
+ *
+ * S3 reports failures (e.g. SignatureDoesNotMatch, AccessDenied / expired signatures)
+ * as an XML document whose first `<Code>` and `<Message>` carry the reason — not the
+ * JSON shape {@link parseControlPlaneApiError} expects. The document also includes
+ * sibling tags (StringToSign, CanonicalRequest, RequestId), so we extract only those
+ * two so the CLI can show the real reason instead of a bare status code.
+ *
+ * Only called on the error path, immediately before throwing — the body is never read
+ * again, so consuming it here is safe (no clone needed). Never throws: any parse
+ * failure or missing fields falls back to the HTTP status line.
+ */
+export declare function parseS3Error(params: {
+    context: string;
+    response: Response;
+}): Promise<string>;

package/dist/api/error-response.js

@@ -0,0 +1,66 @@
+/**
+ * Extract a human-readable error message from a non-ok control-plane API Response.
+ *
+ * Sinatra's error helpers (api_error, api_reject, api_not_found, api_needs_upgrade)
+ * all serialize the user-facing string under a `message` key. Surfacing it lets the
+ * CLI show the real reason (e.g. "Deployment package is too large...") instead of a
+ * bare status code.
+ *
+ * Scoped to JSON `{ message }` bodies. S3 upload errors arrive as XML and need a
+ * separate parser.
+ *
+ * Only called on the error path, immediately before throwing — the body is never read
+ * again, so consuming it here is safe (no clone needed). Never throws: any parse
+ * failure or missing message falls back to the HTTP status line.
+ */ export async function parseControlPlaneApiError(params) {
+    const { context, response } = params;
+    const fallback = `Failed to ${context}: ${response.status} ${response.statusText}`;
+    try {
+        const body = await response.json();
+        if (typeof body.message === 'string' && body.message.trim().length > 0) {
+            return `Failed to ${context}: ${response.status} ${body.message.trim()}`;
+        }
+    } catch  {
+    // Non-JSON body, empty body, or no .json() — fall back to the status line.
+    }
+    return fallback;
+}
+/**
+ * Extract a human-readable error message from a non-ok S3 upload Response.
+ *
+ * S3 reports failures (e.g. SignatureDoesNotMatch, AccessDenied / expired signatures)
+ * as an XML document whose first `<Code>` and `<Message>` carry the reason — not the
+ * JSON shape {@link parseControlPlaneApiError} expects. The document also includes
+ * sibling tags (StringToSign, CanonicalRequest, RequestId), so we extract only those
+ * two so the CLI can show the real reason instead of a bare status code.
+ *
+ * Only called on the error path, immediately before throwing — the body is never read
+ * again, so consuming it here is safe (no clone needed). Never throws: any parse
+ * failure or missing fields falls back to the HTTP status line.
+ */ export async function parseS3Error(params) {
+    const { context, response } = params;
+    const fallback = `Failed to ${context}: ${response.status} ${response.statusText}`;
+    try {
+        const body = await response.text();
+        const code = extractXmlTag(body, 'Code');
+        const message = extractXmlTag(body, 'Message');
+        if (message) {
+            return `Failed to ${context}: ${response.status} ${code ? `${code}: ` : ''}${message}`;
+        }
+        if (code) {
+            return `Failed to ${context}: ${response.status} ${code}`;
+        }
+    } catch  {
+    // Non-XML body, empty body, or no .text() — fall back to the status line.
+    }
+    return fallback;
+}
+/**
+ * Pull the trimmed text content of a single non-nested XML tag (e.g. `<Code>`).
+ * Returns undefined when the tag is absent or empty. S3 error documents are flat,
+ * so a narrow regex is sufficient — no general XML parsing needed.
+ */ function extractXmlTag(xml, tag) {
+    const match = new RegExp(`<${tag}>([^<]*)</${tag}>`).exec(xml);
+    const value = match?.[1]?.trim();
+    return value && value.length > 0 ? value : undefined;
+}

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
  */
@@ -20,12 +30,23 @@ export declare class FigmaApiError extends Error {
  * requests to the Content API. The token contains the CMS ID and
  * user identifying information in its claims.
  *
- * Endpoint: GET https://api.figma.com/v1/cms/:id/token/
+ * Endpoint: POST https://api.figma.com/v1/cms/content-systems/:id/token/
  *
  * @param accessToken - OAuth access token for authentication
  * @param tenantId - The tenant/CMS ID
  * @returns ProjectToken with JWT and expiry information
  * @throws {FigmaApiError} If the API call fails
  */
-export declare function getProjectToken(accessToken: string, tenantId: string): Promise<ProjectToken>;
-//# sourceMappingURL=figma-api.d.ts.map
+export declare function getProjectToken(credential: AuthCredential, tenantId: string): Promise<ProjectToken>;
+export declare function getPayloadAdminToken(credential: AuthCredential, environmentId: 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>;