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

package/dist/config/oauth.d.ts

@@ -1,19 +1,24 @@
 import type { OAuthConfig } from '../auth/types.js';
-export declare const URLS: Record<'prod' | 'staging', Pick<OAuthConfig, 'authorizationUrl' | 'refreshUrl' | 'tokenUrl'>>;
+export declare const DEFAULT_CALLBACK_PORTS: number[];
+export declare const DEFAULT_CALLBACK_PORT: number;
 /**
- * Figma OAuth2 configuration for public CLI client
+ * Get OAuth configuration for current environment.
  *
- * This is a PUBLIC OAuth client using PKCE (Proof Key for Code Exchange).
- * No client secret is used because CLIs cannot securely store secrets.
- * PKCE provides security through the code_verifier/code_challenge mechanism.
+ * `apiBaseUrl` (FIGMA_API_BASE_URL) and `authorizationUrl` (FIGMA_WEB_BASE_URL)
+ * are resolved by `getEnvConfig`; this function only layers on the OAuth-client
+ * specifics it owns:
+ *   FIGMA_CLIENT_ID    → clientId
+ *   FIGMA_REDIRECT_URI → redirectUri
  *
- * For production use, register a public OAuth app with Figma.
- * To register an OAuth app, visit: https://www.figma.com/developers/api#oauth2
+ * When FIGMA_INFRA_ENV=devbox, FIGMA_API_BASE_URL and FIGMA_WEB_BASE_URL are
+ * required (the devbox preset has empty URL defaults, to fail closed).
  */
-export declare const OAUTH_CONFIG: OAuthConfig;
+export declare function getOAuthConfig(): OAuthConfig;
+export declare const TOKEN_EXPIRY_BUFFER_SECONDS = 300;
 /**
- * Buffer time (in seconds) before token expiration to consider token as expired
- * This helps avoid using tokens that are about to expire
+ * Freshness buffer for project tokens. Figma's `pixie` issues 300-second project
+ * tokens, so reusing the 300-second OAuth buffer would treat every fresh token as
+ * already-expired and bypass the cache entirely. 30 seconds is well above the
+ * round-trip time for the calls these tokens authorize.
  */
-export declare const TOKEN_EXPIRY_BUFFER_SECONDS = 300;
-//# sourceMappingURL=oauth.d.ts.map
+export declare const PROJECT_TOKEN_EXPIRY_BUFFER_SECONDS = 30;

package/dist/config/oauth.js

@@ -1,43 +1,42 @@
-import { FIGMA_CLIENT_IDS } from '../constants.js';
-export const URLS = {
-    prod: {
-        authorizationUrl: 'https://www.figma.com/oauth',
-        refreshUrl: 'https://api.figma.com/v1/oauth/refresh',
-        tokenUrl: 'https://api.figma.com/v1/oauth/token'
-    },
-    staging: {
-        authorizationUrl: 'https://staging.figma.com/oauth',
-        refreshUrl: 'https://api.staging.figma.com/v1/oauth/refresh',
-        tokenUrl: 'https://api.staging.figma.com/v1/oauth/token'
-    }
-};
+import { getEnvConfig, getInfraEnvironment } from '../constants.js';
+export const DEFAULT_CALLBACK_PORTS = [
+    34462,
+    34463,
+    34464,
+    34465
+];
+export const DEFAULT_CALLBACK_PORT = DEFAULT_CALLBACK_PORTS[0];
 /**
- * Figma OAuth2 configuration for public CLI client
+ * Get OAuth configuration for current environment.
  *
- * This is a PUBLIC OAuth client using PKCE (Proof Key for Code Exchange).
- * No client secret is used because CLIs cannot securely store secrets.
- * PKCE provides security through the code_verifier/code_challenge mechanism.
+ * `apiBaseUrl` (FIGMA_API_BASE_URL) and `authorizationUrl` (FIGMA_WEB_BASE_URL)
+ * are resolved by `getEnvConfig`; this function only layers on the OAuth-client
+ * specifics it owns:
+ *   FIGMA_CLIENT_ID    → clientId
+ *   FIGMA_REDIRECT_URI → redirectUri
  *
- * For production use, register a public OAuth app with Figma.
- * To register an OAuth app, visit: https://www.figma.com/developers/api#oauth2
- */ export const OAUTH_CONFIG = {
-    // OAuth client ID (public client)
-    // Uses staging client ID by default since we use staging endpoints
-    clientId: process.env.FIGMA_CLIENT_ID || FIGMA_CLIENT_IDS.staging,
-    // No client secret - this is a public OAuth client using PKCE
-    // Public clients cannot securely store secrets in CLI environments
-    redirectUri: process.env.FIGMA_REDIRECT_URI || 'http://localhost:3000/callback',
-    // Only current_user:read scope is needed for basic user info
-    scopes: [
-        'current_user:read'
-    ],
-    // TODO: Dynamically choose between prod and staging based on environment
-    ...URLS.staging
-};
+ * When FIGMA_INFRA_ENV=devbox, FIGMA_API_BASE_URL and FIGMA_WEB_BASE_URL are
+ * required (the devbox preset has empty URL defaults, to fail closed).
+ */ export function getOAuthConfig() {
+    const { apiBaseUrl, authorizationUrl, clientId } = getEnvConfig();
+    if (getInfraEnvironment() === 'devbox' && (!apiBaseUrl || !authorizationUrl)) {
+        throw new Error('FIGMA_API_BASE_URL and FIGMA_WEB_BASE_URL must be set when FIGMA_INFRA_ENV=devbox');
+    }
+    return {
+        authorizationUrl,
+        clientId: process.env.FIGMA_CLIENT_ID || clientId,
+        redirectUri: process.env.FIGMA_REDIRECT_URI || `http://localhost:${DEFAULT_CALLBACK_PORT}/callback`,
+        refreshUrl: `${apiBaseUrl}/v1/oauth/refresh`,
+        scopes: [
+            'current_user:read'
+        ],
+        tokenUrl: `${apiBaseUrl}/v1/oauth/token`
+    };
+}
+export const TOKEN_EXPIRY_BUFFER_SECONDS = 300;
 /**
- * Buffer time (in seconds) before token expiration to consider token as expired
- * This helps avoid using tokens that are about to expire
- */ export const TOKEN_EXPIRY_BUFFER_SECONDS = 300 // 5 minutes
-;
-
-//# sourceMappingURL=oauth.js.map
+ * Freshness buffer for project tokens. Figma's `pixie` issues 300-second project
+ * tokens, so reusing the 300-second OAuth buffer would treat every fresh token as
+ * already-expired and bypass the cache entirely. 30 seconds is well above the
+ * round-trip time for the calls these tokens authorize.
+ */ export const PROJECT_TOKEN_EXPIRY_BUFFER_SECONDS = 30;

package/dist/constants.d.ts

@@ -1,27 +1,71 @@
-export declare const FIGMA_CLIENT_IDS: {
-    production: string;
-    staging: string;
-};
-export declare const JWKS_URI: {
-    production: string;
-    staging: string;
+/**
+ * Figma infrastructure environment (production, staging, or devbox).
+ * devbox is a local-dev mode that requires FIGMA_API_BASE_URL and
+ * FIGMA_WEB_BASE_URL env overrides to point at a Coder devbox.
+ */
+export type Environment = 'devbox' | 'production' | 'staging';
+type EnvironmentConfig = {
+    /** Figma API base URL. Override: FIGMA_API_BASE_URL */
+    apiBaseUrl: string;
+    /** OAuth authorization URL (CLI auth) */
+    authorizationUrl: string;
+    /** OAuth client ID. Override: FIGMA_CLIENT_ID or FIGMA_OAUTH_CLIENT_ID */
+    clientId: string;
+    /** Content API base URL. Override: FIGMA_CONTENT_API_URL */
+    contentApiUrl: string;
+    /** OIDC discovery endpoint */
+    identityMetadata: string;
+    /** JSON Web Key Set URL for token validation */
+    jwksUri: string;
 };
 /**
- * Figma environment (production or staging)
+ * User-facing error message when Content API returns 404 or 410.
+ * Used by the db adapter for consistent messaging at runtime.
  */
-export type Environment = 'production' | 'staging';
+export declare const CONTENT_SYSTEM_NOT_FOUND_MESSAGE = "Content system not found. Verify your Content System ID is correct, or contact your team admin for assistance.";
 /**
- * Get current Figma environment from environment variable
- * Defaults to 'staging' if not specified
- *
- * @returns Current environment
+ * Build a user-facing error message for CLI commands when a project is not found (404/410).
+ * Includes infra-env context and actionable suggestions.
+ */
+export declare function getProjectNotFoundMessage(params: {
+    environment: Environment;
+    projectId: string;
+}): string;
+/**
+ * Set infrastructure environment override (used by --infra-env CLI flag)
+ * Pass undefined to clear the override
  */
-export declare function getEnvironment(): Environment;
+export declare function setInfraEnvironment(env: Environment | undefined): void;
 /**
- * Get JWKS URI for a given environment
+ * Resolve the EnvironmentConfig for an infrastructure environment, applying the
+ * `process.env` overrides that the Make-preview sandbox (and devbox/staging)
+ * depend on. This is a FUNCTION, not a populated constant, because those env
+ * vars may be set after module load — resolving them lazily at call time keeps
+ * the values current (the empty `devbox` preset is filled here, not at import).
+ *
+ * This is the single place these `process.env` overrides are parsed; callers
+ * (including `getOAuthConfig`) read the resolved values from here rather than
+ * re-parsing the env vars themselves. Three overrides, each keyed off the axis
+ * it belongs to:
+ *
+ * - `apiBaseUrl` ← `FIGMA_API_BASE_URL` (Control Plane / token host).
+ *
+ * - `authorizationUrl` / `identityMetadata` ← `FIGMA_WEB_BASE_URL`. The
+ *   authorization code is minted by the SAME Figma host the editor runs on, so
+ *   the token exchange / OIDC discovery must hit THAT host. Without this the
+ *   plugin falls back to `www.figma.com`, the devbox-minted code is rejected
+ *   with `invalid_grant`, and the admin login loops forever.
+ *
+ * - `jwksUri` ← `FIGMA_CONTENT_API_URL` (the content backend that signs the
+ *   project token, independent of the OAuth host — see `deriveContentJwksUri`).
+ *
+ * In production the platform injects `FIGMA_WEB_BASE_URL=https://www.figma.com`
+ * and a `figmacontent.com` content URL, so the derived values equal the presets
+ * and behavior is unchanged.
  *
- * @param env - Environment (defaults to current environment)
- * @returns JWKS URI for the environment
+ * @param environment - the infrastructure environment to resolve; defaults to
+ *   the one reported by `getInfraEnvironment()`.
  */
-export declare function getJWKSUri(env?: Environment): string;
-//# sourceMappingURL=constants.d.ts.map
+export declare function getEnvConfig(environment?: Environment): EnvironmentConfig;
+export declare function getInfraEnvironment(): Environment;
+export {};

package/dist/constants.js

@@ -1,27 +1,165 @@
-export const FIGMA_CLIENT_IDS = {
-    production: '',
-    staging: 'wqAToBAp4UI9AZ5M6wTfT9'
-};
-export const JWKS_URI = {
-    production: 'https://static.figmacontent.com/.well_known/jwks.json',
-    staging: 'https://static.figmacontentstaging.com/.well_known/jwks.json'
+import { getEnvVarSync } from './utils/env-management.js';
+/**
+ * Environment-specific configuration for Figma integration.
+ * Selected via FIGMA_INFRA_ENV ('production' | 'staging'), defaults to 'production'.
+ */ const ENV_CONFIG = {
+    production: {
+        apiBaseUrl: 'https://api.figma.com',
+        authorizationUrl: 'https://www.figma.com/oauth',
+        clientId: 'lelKVTAzOekFnirnlAMbuD',
+        contentApiUrl: 'https://us-east-1.cms-tenants-001-production.figmacontent.com',
+        identityMetadata: 'https://www.figma.com/.well-known/openid-configuration',
+        jwksUri: 'https://static.figmacontent.com/.well_known/jwks.json'
+    },
+    staging: {
+        apiBaseUrl: 'https://api.staging.figma.com',
+        authorizationUrl: 'https://staging.figma.com/oauth',
+        clientId: 'wqAToBAp4UI9AZ5M6wTfT9',
+        contentApiUrl: 'https://us-east-1.cms-tenants-001-staging.figmacontentstaging.com',
+        identityMetadata: 'https://staging.figma.com/.well-known/openid-configuration',
+        jwksUri: 'https://static.figmacontentstaging.com/.well_known/jwks.json'
+    },
+    // Empty URLs are intentional: devbox mode requires FIGMA_API_BASE_URL and
+    // FIGMA_WEB_BASE_URL to be set, validated at getOAuthConfig() time.
+    // clientId defaults to the dev seed value in sinatra/db/seeds.rb.
+    devbox: {
+        apiBaseUrl: '',
+        authorizationUrl: '',
+        clientId: 'rNZBcf3xBDmI76mQ9603su',
+        contentApiUrl: '',
+        identityMetadata: '',
+        jwksUri: ''
+    }
 };
 /**
- * Get current Figma environment from environment variable
- * Defaults to 'staging' if not specified
+ * User-facing error message when Content API returns 404 or 410.
+ * Used by the db adapter for consistent messaging at runtime.
+ */ export const CONTENT_SYSTEM_NOT_FOUND_MESSAGE = 'Content system not found. Verify your Content System ID is correct, or contact your team admin for assistance.';
+/**
+ * Build a user-facing error message for CLI commands when a project is not found (404/410).
+ * Includes infra-env context and actionable suggestions.
+ */ export function getProjectNotFoundMessage(params) {
+    const { environment, projectId } = params;
+    return [
+        `Project not found on ${environment} (ID: ${projectId}).`,
+        '',
+        'Suggestions:',
+        '  • Verify your project ID is correct',
+        "  • Ensure you're logged into the correct Figma account",
+        '  • Contact your team admin for assistance'
+    ].join('\n');
+}
+let envOverride;
+/**
+ * Set infrastructure environment override (used by --infra-env CLI flag)
+ * Pass undefined to clear the override
+ */ export function setInfraEnvironment(env) {
+    envOverride = env;
+}
+/**
+ * Get current Figma infrastructure environment
+ * Priority: 1) setInfraEnvironment override, 2) FIGMA_INFRA_ENV env var, 3) .env file, 4) 'production' default
+ */ /**
+ * Derive the project-token JWKS URI from the content/CMS API domain
+ * (`FIGMA_CONTENT_API_URL`), or `undefined` when it is unset or malformed.
  *
- * @returns Current environment
- */ export function getEnvironment() {
-    return process.env.FIGMA_ENV === 'production' ? 'production' : 'staging';
+ * The project token is signed by the content backend, whose JWKS host tracks
+ * the content env — NOT the OAuth/infra env. A devbox or staging tenant runs
+ * on the staging content backend (`*.figmacontentstaging.com`) even when OAuth
+ * points at a devbox host, so its tokens are signed by the staging key and must
+ * validate against `static.figmacontentstaging.com`. Returning `undefined` lets
+ * the caller fall back to the per-env preset.
+ */ function deriveContentJwksUri() {
+    const contentApiUrl = process.env.FIGMA_CONTENT_API_URL;
+    if (!contentApiUrl) {
+        return undefined;
+    }
+    try {
+        const host = new URL(contentApiUrl).hostname;
+        const match = host.match(/(figmacontentstaging\.com|figmacontent\.com)$/);
+        if (match) {
+            return `https://static.${match[1]}/.well_known/jwks.json`;
+        }
+    } catch  {
+    // Malformed URL — fall through to the per-env preset.
+    }
+    return undefined;
 }
 /**
- * Get JWKS URI for a given environment
+ * Resolve the EnvironmentConfig for an infrastructure environment, applying the
+ * `process.env` overrides that the Make-preview sandbox (and devbox/staging)
+ * depend on. This is a FUNCTION, not a populated constant, because those env
+ * vars may be set after module load — resolving them lazily at call time keeps
+ * the values current (the empty `devbox` preset is filled here, not at import).
  *
- * @param env - Environment (defaults to current environment)
- * @returns JWKS URI for the environment
- */ export function getJWKSUri(env) {
-    const environment = env || getEnvironment();
-    return JWKS_URI[environment];
+ * This is the single place these `process.env` overrides are parsed; callers
+ * (including `getOAuthConfig`) read the resolved values from here rather than
+ * re-parsing the env vars themselves. Three overrides, each keyed off the axis
+ * it belongs to:
+ *
+ * - `apiBaseUrl` ← `FIGMA_API_BASE_URL` (Control Plane / token host).
+ *
+ * - `authorizationUrl` / `identityMetadata` ← `FIGMA_WEB_BASE_URL`. The
+ *   authorization code is minted by the SAME Figma host the editor runs on, so
+ *   the token exchange / OIDC discovery must hit THAT host. Without this the
+ *   plugin falls back to `www.figma.com`, the devbox-minted code is rejected
+ *   with `invalid_grant`, and the admin login loops forever.
+ *
+ * - `jwksUri` ← `FIGMA_CONTENT_API_URL` (the content backend that signs the
+ *   project token, independent of the OAuth host — see `deriveContentJwksUri`).
+ *
+ * In production the platform injects `FIGMA_WEB_BASE_URL=https://www.figma.com`
+ * and a `figmacontent.com` content URL, so the derived values equal the presets
+ * and behavior is unchanged.
+ *
+ * @param environment - the infrastructure environment to resolve; defaults to
+ *   the one reported by `getInfraEnvironment()`.
+ */ export function getEnvConfig(environment = getInfraEnvironment()) {
+    const config = {
+        ...ENV_CONFIG[environment]
+    };
+    const apiBaseUrl = process.env.FIGMA_API_BASE_URL?.replace(/\/+$/, '');
+    if (apiBaseUrl) {
+        config.apiBaseUrl = apiBaseUrl;
+    }
+    const webBaseUrl = process.env.FIGMA_WEB_BASE_URL?.replace(/\/+$/, '');
+    if (webBaseUrl) {
+        config.authorizationUrl = `${webBaseUrl}/oauth`;
+        config.identityMetadata = `${webBaseUrl}/.well-known/openid-configuration`;
+    }
+    const jwksUri = deriveContentJwksUri();
+    if (jwksUri) {
+        config.jwksUri = jwksUri;
+    }
+    return config;
+}
+export function getInfraEnvironment() {
+    if (envOverride) {
+        return envOverride;
+    }
+    // Check process.env first (case-insensitive)
+    const processEnv = process.env.FIGMA_INFRA_ENV?.toLowerCase();
+    if (processEnv === 'staging') {
+        return 'staging';
+    }
+    if (processEnv === 'devbox') {
+        return 'devbox';
+    }
+    // Fall back to .env file in cwd (check both new and old env var names)
+    const envFileValue = getEnvVarSync(process.cwd(), 'FIGMA_INFRA_ENV') ?? getEnvVarSync(process.cwd(), 'FIGMA_ENV');
+    if (envFileValue) {
+        const env = envFileValue.toLowerCase();
+        if (env === 'staging') {
+            return 'staging';
+        }
+        if (env === 'devbox') {
+            return 'devbox';
+        }
+        if (env !== 'production') {
+            // eslint-disable-next-line no-console
+            console.warn(`Warning: Invalid FIGMA_INFRA_ENV value "${envFileValue}" in .env file. Using production.`);
+        }
+        return 'production';
+    }
+    return 'production';
 }
-
-//# sourceMappingURL=constants.js.map