@payloadcms/figma 0.0.1-alpha.63 → 0.0.1-alpha.65

package/dist/oauth/utilities/establishSession.js

@@ -0,0 +1,82 @@
+import { APIError, generateCookie } from 'payload';
+import { getProjectToken, getUserInfo } from '../../api/figma-api.js';
+import { createCookieOptions } from './createCookieOptions.js';
+import { getCookieExpiration } from './getCookieExpiration.js';
+/**
+ * Given a valid OAuth access_token: fetch user info (non-fatal), mint a
+ * project token, and write the main + refresh + user-info cookies to
+ * `req.responseHeaders`. Throws `APIError` if the project token mint fails.
+ */ export const establishSession = async ({ accessToken, collection, collectionOptions, contentSystemId, debugLogger, pluginOptions, refreshTokenExpiresIn, req, strategy })=>{
+    const oauthCredential = {
+        type: 'oauth',
+        token: accessToken
+    };
+    // Non-fatal: user just won't have handle/image on first request.
+    let figmaUserInfo = null;
+    try {
+        figmaUserInfo = await getUserInfo(oauthCredential);
+        debugLogger.info({
+            figmaUserInfo,
+            msg: 'Fetched Figma user info'
+        });
+    } catch (err) {
+        debugLogger.error({
+            err,
+            msg: 'Failed to fetch Figma user info'
+        });
+    }
+    const projectToken = await getProjectToken(oauthCredential, contentSystemId);
+    if (!projectToken.token) {
+        const errMsg = 'No project token returned from Figma API';
+        req.payload.logger.error({
+            msg: errMsg
+        });
+        throw new APIError(errMsg);
+    }
+    const cookieOptions = createCookieOptions({
+        collection,
+        headers: req.headers,
+        pluginOptions
+    });
+    if (!req.responseHeaders) {
+        req.responseHeaders = new Headers();
+    }
+    // The -refresh cookie holds the OAuth access_token so refreshTokens can
+    // re-mint project_tokens from it on JWT expiry.
+    if (!collectionOptions.usePayloadJWT) {
+        const refreshCookie = generateCookie({
+            ...cookieOptions,
+            name: `${strategy.cookieName}-refresh`,
+            expires: getCookieExpiration(cookieOptions?.expires ?? refreshTokenExpiresIn ?? 31_556_952),
+            returnCookieAsObject: false,
+            value: accessToken
+        });
+        req.responseHeaders.append('Set-Cookie', refreshCookie);
+    }
+    const tokenExpires = cookieOptions?.expires ? getCookieExpiration(cookieOptions.expires) : new Date(projectToken.expiresAt);
+    const tokenCookie = generateCookie({
+        ...cookieOptions,
+        name: strategy.cookieName,
+        expires: tokenExpires,
+        returnCookieAsObject: false,
+        value: projectToken.token
+    });
+    req.responseHeaders.append('Set-Cookie', tokenCookie);
+    // Short-lived handoff cookie consumed by defaultVerify on the next request.
+    if (figmaUserInfo) {
+        const userInfoValue = Buffer.from(JSON.stringify({
+            handle: figmaUserInfo.handle,
+            img_url: figmaUserInfo.img_url
+        })).toString('base64');
+        const userInfoCookie = generateCookie({
+            ...cookieOptions,
+            name: pluginOptions?.userInfoCookieName ?? 'figma-user-info',
+            expires: new Date(Date.now() + 60_000),
+            returnCookieAsObject: false,
+            value: userInfoValue
+        });
+        req.responseHeaders.append('Set-Cookie', userInfoCookie);
+    }
+};
+
+//# sourceMappingURL=establishSession.js.map

package/dist/oauth/utilities/exchangeCodeForAccessToken.d.ts

@@ -0,0 +1,24 @@
+import type { Strategy } from '../strategy/index.js';
+interface Args {
+    /** Authorization code received from the IdP redirect. */
+    code: string;
+    /** PKCE verifier; omit for non-PKCE flows. */
+    codeVerifier?: string;
+    /** Must match the redirect_uri the authorization request used. */
+    redirectUri: string;
+    strategy: Strategy;
+}
+export interface TokenEndpointResponse {
+    access_token?: null | string;
+    error?: string;
+    error_description?: string;
+    expires_in?: number;
+}
+/**
+ * POSTs an authorization code to the IdP's `token_endpoint` and returns the
+ * raw response body. Callers handle error/missing-token logging in their own
+ * style — this helper only owns the request shape.
+ */
+export declare const exchangeCodeForAccessToken: ({ code, codeVerifier, redirectUri, strategy, }: Args) => Promise<TokenEndpointResponse>;
+export {};
+//# sourceMappingURL=exchangeCodeForAccessToken.d.ts.map

package/dist/oauth/utilities/exchangeCodeForAccessToken.js

@@ -0,0 +1,28 @@
+/**
+ * POSTs an authorization code to the IdP's `token_endpoint` and returns the
+ * raw response body. Callers handle error/missing-token logging in their own
+ * style — this helper only owns the request shape.
+ */ export const exchangeCodeForAccessToken = async ({ code, codeVerifier, redirectUri, strategy })=>{
+    const body = {
+        client_id: strategy.clientID,
+        code,
+        grant_type: 'authorization_code',
+        redirect_uri: redirectUri
+    };
+    if (codeVerifier) {
+        body.code_verifier = codeVerifier;
+    }
+    if (strategy.collectionOptions.clientSecret) {
+        body.client_secret = strategy.collectionOptions.clientSecret;
+    }
+    const res = await fetch(strategy.meta.token_endpoint, {
+        body: new URLSearchParams(body),
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded'
+        },
+        method: 'POST'
+    });
+    return await res.json();
+};
+
+//# sourceMappingURL=exchangeCodeForAccessToken.js.map

package/dist/oauth/utilities/isAbsoluteURL.d.ts

@@ -0,0 +1,2 @@
+export declare const isAbsoluteURL: (url: string) => boolean;
+//# sourceMappingURL=isAbsoluteURL.d.ts.map

package/dist/oauth/utilities/isAbsoluteURL.js

@@ -0,0 +1,3 @@
+export const isAbsoluteURL = (url)=>/^[a-z][a-z\d+.-]*:/.test(url);
+
+//# sourceMappingURL=isAbsoluteURL.js.map

package/dist/plugin/build-config.js

@@ -104,6 +104,66 @@ function missingOAuthCredential(name) {
 function messageOf(error) {
     return error instanceof Error ? error.message : 'Unknown error';
 }
+/**
+ * Creates storage configuration for upload collections
+ */ function createStorageConfig(url, contentSystemId) {
+    const storageConfig = process.env.FIGMA_CONTENT_API_ACCESS_KEY ? {
+        baseUrl: url,
+        contentApiKey: process.env.FIGMA_CONTENT_API_ACCESS_KEY
+    } : process.env.FIGMA_DEV_JWT === 'true' ? {
+        auth: {
+            mode: 'devJwt'
+        },
+        baseUrl: url,
+        contentSystemId
+    } : {
+        auth: {
+            mode: 'tokenStore',
+            tokenStore: getTokenStore()
+        },
+        baseUrl: url,
+        contentSystemId
+    };
+    const adapter = contentApiStorageAdapter(storageConfig);
+    const storageClient = createStorageClient(storageConfig);
+    return {
+        adapter,
+        storageClient
+    };
+}
+/**
+ * Plugin that applies cloud storage configuration to all upload-enabled collections.
+ * Runs at the end of the plugin chain so it sees collections added by user plugins too.
+ */ function createStoragePlugin(url, contentSystemId) {
+    return (incomingConfig)=>{
+        const uploadCollections = (incomingConfig.collections || []).filter((c)=>c.upload);
+        if (uploadCollections.length === 0) {
+            return incomingConfig;
+        }
+        const { adapter, storageClient } = createStorageConfig(url, contentSystemId);
+        const collectionsMap = uploadCollections.reduce((acc, c)=>{
+            acc[c.slug] = {
+                adapter,
+                disableLocalStorage: true
+            };
+            return acc;
+        }, {});
+        initClientUploads({
+            clientHandler: '@payloadcms/figma/client#ContentApiClientUploadHandler',
+            collections: collectionsMap,
+            config: incomingConfig,
+            enabled: true,
+            serverHandler: getGenerateSignedURLHandler({
+                client: storageClient
+            }),
+            serverHandlerPath: '/content-api-storage-signed-url'
+        });
+        const storagePlugin = cloudStoragePlugin({
+            collections: collectionsMap
+        });
+        return storagePlugin(incomingConfig);
+    };
+}
 export async function buildFigmaConfig(config) {
     const envConfig = getEnvConfig();
     // Resolve contentSystemId: config first, env var, then local store fallback (dev)
@@ -160,6 +220,7 @@ export async function buildFigmaConfig(config) {
                 mode: 'apiKey'
             },
             contentSystemId,
+            environmentName: process.env.FIGMA_ENVIRONMENT_NAME,
             url
         });
     } else if (process.env.FIGMA_DEV_JWT === 'true') {
@@ -168,6 +229,7 @@ export async function buildFigmaConfig(config) {
                 mode: 'devJwt'
             },
             contentSystemId,
+            environmentName: process.env.FIGMA_ENVIRONMENT_NAME,
             url
         });
     } else {
@@ -177,53 +239,10 @@ export async function buildFigmaConfig(config) {
                 tokenStore: getTokenStore()
             },
             contentSystemId,
+            environmentName: process.env.FIGMA_ENVIRONMENT_NAME,
             url
         });
     }
-    // Build storage plugin if there are upload collections and storage is not disabled
-    const uploadCollections = (config.collections || []).filter((c)=>c.upload);
-    let storagePlugin;
-    if (uploadCollections.length > 0 && config.figma.storage !== false) {
-        const storageConfig = process.env.FIGMA_CONTENT_API_ACCESS_KEY ? {
-            baseUrl: url,
-            contentApiKey: process.env.FIGMA_CONTENT_API_ACCESS_KEY
-        } : process.env.FIGMA_DEV_JWT === 'true' ? {
-            auth: {
-                mode: 'devJwt'
-            },
-            baseUrl: url,
-            contentSystemId
-        } : {
-            auth: {
-                mode: 'tokenStore',
-                tokenStore: getTokenStore()
-            },
-            baseUrl: url,
-            contentSystemId
-        };
-        const adapter = contentApiStorageAdapter(storageConfig);
-        const storageClient = createStorageClient(storageConfig);
-        const collectionsMap = uploadCollections.reduce((acc, c)=>{
-            acc[c.slug] = {
-                adapter,
-                disableLocalStorage: true
-            };
-            return acc;
-        }, {});
-        initClientUploads({
-            clientHandler: '@payloadcms/figma/client#ContentApiClientUploadHandler',
-            collections: collectionsMap,
-            config: config,
-            enabled: true,
-            serverHandler: getGenerateSignedURLHandler({
-                client: storageClient
-            }),
-            serverHandlerPath: '/content-api-storage-signed-url'
-        });
-        storagePlugin = cloudStoragePlugin({
-            collections: collectionsMap
-        });
-    }
     // Build complete config with Figma platform defaults
     const configWithFigmaDefaults = {
         ...config,
@@ -257,8 +276,8 @@ export async function buildFigmaConfig(config) {
         // Add oauth to plugins if not already present
         plugins: [
             ...config.plugins ?? [],
-            ...storagePlugin ? [
-                storagePlugin
+            ...config.figma.storage !== false ? [
+                createStoragePlugin(url, contentSystemId)
             ] : [],
             oAuth2Plugin({
                 collections: [

package/dist/types.d.ts

@@ -11,11 +11,13 @@ export interface Args extends arg.Spec {
     '--list': BooleanConstructor;
     '--logout': BooleanConstructor;
     '--name': StringConstructor;
+    '--template': StringConstructor;
     '--yes': BooleanConstructor;
     '-e': string;
     '-f': string;
     '-h': string;
     '-n': string;
+    '-t': string;
     '-y': string;
 }
 export type CliArgs = arg.Result<Args>;

package/dist/utils/download-template.d.ts

@@ -5,11 +5,19 @@ export declare class TemplateDownloadError extends Error {
     cause?: Error | undefined;
     constructor(message: string, cause?: Error | undefined);
 }
+export type TemplateSource = {
+    owner: string;
+    ref: string;
+    repo: string;
+    templatePath: string;
+};
+export declare const DEFAULT_TEMPLATE_SOURCE: TemplateSource;
 /**
  * Download Payload template from GitHub with retry logic
  *
  * @param projectDir - Directory to extract template into
+ * @param source - Optional override of repo / ref / template path
  * @throws TemplateDownloadError if download fails
  */
-export declare function downloadTemplateFromGitHub(projectDir: string): Promise<void>;
+export declare function downloadTemplateFromGitHub(projectDir: string, source?: Partial<TemplateSource>): Promise<void>;
 //# sourceMappingURL=download-template.d.ts.map

package/dist/utils/download-template.js

@@ -11,23 +11,30 @@ import { x } from 'tar';
         this.name = 'TemplateDownloadError';
     }
 }
-const BRANCH_OR_TAG = 'v3.79.1';
-/** GitHub strips the 'v' prefix in tarball directory names */ const TARBALL_PREFIX = `payload-${BRANCH_OR_TAG.replace(/^v/, '')}`;
-const TEMPLATE_NAME = 'blank';
+export const DEFAULT_TEMPLATE_SOURCE = {
+    owner: 'payloadcms',
+    ref: 'v3.84.1',
+    repo: 'payload',
+    templatePath: 'blank'
+};
 const MAX_RETRIES = 3;
-const INITIAL_RETRY_DELAY = 1000 // 1 second
-;
+const INITIAL_RETRY_DELAY = 1000;
 /**
  * Download Payload template from GitHub with retry logic
  *
  * @param projectDir - Directory to extract template into
+ * @param source - Optional override of repo / ref / template path
  * @throws TemplateDownloadError if download fails
- */ export async function downloadTemplateFromGitHub(projectDir) {
+ */ export async function downloadTemplateFromGitHub(projectDir, source) {
+    const resolved = {
+        ...DEFAULT_TEMPLATE_SOURCE,
+        ...source
+    };
     let lastError;
     for(let attempt = 1; attempt <= MAX_RETRIES; attempt++){
         try {
-            await downloadTemplateAttempt(projectDir);
-            return; // Success
+            await downloadTemplateAttempt(projectDir, resolved);
+            return;
         } catch (error) {
             lastError = error instanceof Error ? error : new Error('Unknown error');
             if (attempt < MAX_RETRIES) {
@@ -37,31 +44,29 @@ const INITIAL_RETRY_DELAY = 1000 // 1 second
             }
         }
     }
-    // All retries failed
     throw new TemplateDownloadError(`Failed to download template after ${MAX_RETRIES} attempts`, lastError);
 }
-/**
- * Single attempt to download template (extracted for retry logic)
- */ async function downloadTemplateAttempt(projectDir) {
-    const url = `https://codeload.github.com/payloadcms/payload/tar.gz/${BRANCH_OR_TAG}`;
-    const filter = `${TARBALL_PREFIX}/templates/${TEMPLATE_NAME}/`;
+async function downloadTemplateAttempt(projectDir, source) {
+    const url = `https://codeload.github.com/${source.owner}/${source.repo}/tar.gz/${source.ref}`;
+    // GitHub strips the leading 'v' and replaces '/' with '-' when naming the tarball root dir
+    const refSlug = source.ref.replace(/^v/, '').replace(/\//g, '-');
+    const tarballPrefix = `${source.repo}-${refSlug}`;
+    const filter = `${tarballPrefix}/templates/${source.templatePath}/`;
+    const strip = 2 + source.templatePath.split('/').length;
     try {
-        // Ensure target directory exists
         await fs.mkdir(projectDir, {
             recursive: true
         });
         await pipeline(await downloadTarStream(url), x({
             cwd: projectDir,
             filter: (p)=>p.includes(filter),
-            strip: 2 + TEMPLATE_NAME.split('/').length
+            strip
         }));
     } catch (error) {
         throw new TemplateDownloadError('Failed to download template from GitHub', error instanceof Error ? error : undefined);
     }
 }
-/**
- * Download tar stream from URL
- */ async function downloadTarStream(url) {
+async function downloadTarStream(url) {
     const res = await fetch(url);
     if (!res.ok) {
         throw new Error(`HTTP ${res.status}: ${res.statusText}`);

package/dist/utils/messages.js

@@ -14,6 +14,7 @@ export function helpMessage() {
       ${pc.cyan('logout')}           Clear all stored tokens
       ${pc.cyan('list-tokens')}      Show stored token information
       ${pc.cyan('init')}             Initialize a Figma CMS project
+      ${pc.cyan('bootstrap')}        Print bootstrap info (tenant IDs, OAuth creds) for a project
       ${pc.cyan('debug')}            Show debug info for troubleshooting
       ${pc.cyan('env')}              Switch active environment
       ${pc.cyan('deploy')}           Deploy your project to Figma
@@ -38,6 +39,14 @@ export function helpMessage() {
       ${pc.cyan('@payloadcms/figma init --id <id> --env staging')}    Initialize for specific environment
       ${pc.dim('--name, -n <name>')}                     Set project directory name (skips prompt)
       ${pc.dim('--force')}                               Force reconfiguration of existing project
+      ${pc.dim('--no-skill')}                            Skip installing the Payload skill into .claude/skills/payload/
+      ${pc.dim('--template, -t <spec>')}                  Override scaffold template (e.g. v3.80.0:website, owner/repo#ref:path)
+
+  ${pc.bold('BOOTSTRAP COMMAND')}
+
+      ${pc.cyan('@payloadcms/figma bootstrap --id <cms-resource-id>')}   Print bootstrap info
+      ${pc.dim('--env <environment>')}                   Filter to a single environment
+      ${pc.dim('--json')}                                 Output JSON instead of styled note
 
   ${pc.bold('ENV COMMAND')}
 

package/dist/utils/parse-template-spec.d.ts

@@ -0,0 +1,12 @@
+import type { TemplateSource } from './download-template.js';
+export declare class TemplateSpecParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a --template spec string into a partial TemplateSource override.
+ *
+ * Format: [<owner>/<repo>#]<ref>:<template-path>
+ * Shorthand: a bare token with no `#` and no `:` is treated as the template path.
+ */
+export declare function parseTemplateSpec(spec: string): Partial<TemplateSource>;
+//# sourceMappingURL=parse-template-spec.d.ts.map

package/dist/utils/parse-template-spec.js

@@ -0,0 +1,62 @@
+export class TemplateSpecParseError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'TemplateSpecParseError';
+    }
+}
+/**
+ * Parse a --template spec string into a partial TemplateSource override.
+ *
+ * Format: [<owner>/<repo>#]<ref>:<template-path>
+ * Shorthand: a bare token with no `#` and no `:` is treated as the template path.
+ */ export function parseTemplateSpec(spec) {
+    const trimmed = spec.trim();
+    if (!trimmed) {
+        throw new TemplateSpecParseError('Template spec is empty');
+    }
+    let rest = trimmed;
+    const result = {};
+    const hashIndex = rest.indexOf('#');
+    if (hashIndex !== -1) {
+        const repoPart = rest.slice(0, hashIndex);
+        rest = rest.slice(hashIndex + 1);
+        const slashCount = (repoPart.match(/\//g) ?? []).length;
+        if (slashCount !== 1) {
+            throw new TemplateSpecParseError(`Expected "<owner>/<repo>" before "#", got "${repoPart}"`);
+        }
+        const [owner, repo] = repoPart.split('/');
+        if (!owner || !repo) {
+            throw new TemplateSpecParseError(`Invalid owner/repo: "${repoPart}"`);
+        }
+        result.owner = owner;
+        result.repo = repo;
+    } else {
+        // Check for slash only in the portion before the first colon (the ref part).
+        // Slashes after the colon are valid multi-segment template paths.
+        const beforeColon = rest.includes(':') ? rest.slice(0, rest.indexOf(':')) : rest;
+        if (beforeColon.includes('/')) {
+            throw new TemplateSpecParseError(`"<owner>/<repo>" must be followed by "#<ref>" (got "${trimmed}")`);
+        }
+    }
+    const colonIndex = rest.indexOf(':');
+    if (colonIndex !== -1) {
+        const ref = rest.slice(0, colonIndex);
+        const templatePath = rest.slice(colonIndex + 1);
+        if (!ref) {
+            throw new TemplateSpecParseError('Ref before ":" is empty');
+        }
+        if (!templatePath) {
+            throw new TemplateSpecParseError('Template path after ":" is empty');
+        }
+        result.ref = ref;
+        result.templatePath = templatePath;
+        return result;
+    }
+    if (hashIndex !== -1) {
+        throw new TemplateSpecParseError('Spec with "<owner>/<repo>#<ref>" must include ":<template-path>"');
+    }
+    result.templatePath = rest;
+    return result;
+}
+
+//# sourceMappingURL=parse-template-spec.js.map