@nitrogenbuilder/connector-payload 0.1.0

package/dist/endpoints/helpers.d.ts

@@ -0,0 +1,64 @@
+import type { Payload, PayloadRequest } from 'payload';
+import type { JsonObject, NitrogenPageDoc, NitrogenTemplateDoc, NitrogenSettingsGlobal, MediaDoc } from '../types';
+export declare function formatDate(date: string | Date): string;
+export declare function buildDynamicData(doc: NitrogenPageDoc | NitrogenTemplateDoc, globalSettings?: NitrogenSettingsGlobal): JsonObject;
+export declare function buildPageResponse(doc: NitrogenPageDoc | NitrogenTemplateDoc, settings: NitrogenSettingsGlobal, dynamicData: JsonObject): {
+    id: string | number;
+    token: string;
+    title: string;
+    author: string | number;
+    slug: string;
+    permalink: string;
+    relative_permalink: string;
+    content: string;
+    dynamic_data: JsonObject;
+    settings: JsonObject;
+    nitrogen_settings: {
+        variables?: Array<{
+            name: string;
+            value?: string;
+        }>;
+        urlMaps: never[];
+        wysiwygColors: {};
+    };
+};
+export declare function buildListItemResponse(doc: NitrogenPageDoc | NitrogenTemplateDoc, settings: NitrogenSettingsGlobal): {
+    id: string | number;
+    title: string;
+    slug: string;
+    permalink: string;
+    relative_permalink: string;
+    content: string;
+    settings: JsonObject;
+    nitrogen_settings: {
+        variables?: Array<{
+            name: string;
+            value?: string;
+        }>;
+        urlMaps: never[];
+        wysiwygColors: {};
+    };
+};
+export declare function buildMediaItemResponse(doc: MediaDoc): {
+    id: string | number;
+    filename: string;
+    mimeType: string;
+    alt: string;
+    url: string;
+    filesize: number;
+    width: number;
+    height: number;
+    createdAt: string;
+    sizes: {
+        [key: string]: import("../types").MediaSize | undefined;
+        thumbnail?: import("../types").MediaSize;
+        medium?: import("../types").MediaSize;
+        large?: import("../types").MediaSize;
+    };
+    name: string;
+    mime: string;
+    ext: string;
+    size: number;
+};
+export declare function getNitrogenSettings(payload: Payload): Promise<NitrogenSettingsGlobal>;
+export declare function requireAuth(req: PayloadRequest): Response | null;

package/dist/endpoints/helpers.js

@@ -0,0 +1,104 @@
+export function formatDate(date) {
+    const d = new Date(date);
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
+}
+export function buildDynamicData(doc, globalSettings) {
+    const dynamicData = {
+        Post: {
+            post_title: doc.title || '',
+            post_content: '',
+            post_excerpt: '',
+            post_date: formatDate(doc.createdAt),
+            post_date_gmt: formatDate(doc.createdAt),
+            post_modified: formatDate(doc.updatedAt),
+            post_modified_gmt: formatDate(doc.updatedAt),
+            author_id: doc.author && typeof doc.author === 'object' ? String(doc.author.id) : String(doc.author || ''),
+            author: doc.author && typeof doc.author === 'object'
+                ? doc.author.name || doc.author.email || ''
+                : '',
+        },
+    };
+    if (globalSettings?.nitrogenConfig?.variables) {
+        const vars = {};
+        for (const item of globalSettings.nitrogenConfig.variables) {
+            if (item.name) {
+                vars[item.name] = item.value ?? '';
+            }
+        }
+        dynamicData['Global Variables'] = vars;
+    }
+    return dynamicData;
+}
+export function buildPageResponse(doc, settings, dynamicData) {
+    const pageSettings = 'pageSettings' in doc ? doc.pageSettings : undefined;
+    const templateSettings = 'templateSettings' in doc ? doc.templateSettings : undefined;
+    return {
+        id: doc.id,
+        token: settings.licenseKey || '',
+        title: doc.title,
+        author: doc.author && typeof doc.author === 'object' ? doc.author.id : (doc.author || ''),
+        slug: doc.slug,
+        permalink: `${settings.frontendUrl || ''}/${doc.slug}`,
+        relative_permalink: `/${doc.slug}`,
+        content: doc.nitrogenData ? JSON.stringify(doc.nitrogenData) : '[]',
+        dynamic_data: dynamicData,
+        settings: pageSettings || templateSettings || {
+            'Page Settings': {},
+        },
+        nitrogen_settings: {
+            urlMaps: [],
+            wysiwygColors: {},
+            ...(settings.nitrogenConfig || {}),
+        },
+    };
+}
+export function buildListItemResponse(doc, settings) {
+    const pageSettings = 'pageSettings' in doc ? doc.pageSettings : undefined;
+    const templateSettings = 'templateSettings' in doc ? doc.templateSettings : undefined;
+    return {
+        id: doc.id,
+        title: doc.title,
+        slug: doc.slug,
+        permalink: `${settings.frontendUrl || ''}/${doc.slug}`,
+        relative_permalink: `/${doc.slug}`,
+        content: doc.nitrogenData ? JSON.stringify(doc.nitrogenData) : '[]',
+        settings: pageSettings || templateSettings || {},
+        nitrogen_settings: {
+            urlMaps: [],
+            wysiwygColors: {},
+            ...(settings.nitrogenConfig || {}),
+        },
+    };
+}
+export function buildMediaItemResponse(doc) {
+    const filename = doc.filename || '';
+    const ext = filename.includes('.') ? `.${filename.split('.').pop()}` : '';
+    return {
+        // Payload-native fields (used by provider renderFiles/renderSelectedFile)
+        id: doc.id,
+        filename,
+        mimeType: doc.mimeType || '',
+        alt: doc.alt || '',
+        url: doc.url || '',
+        filesize: doc.filesize || 0,
+        width: doc.width || 0,
+        height: doc.height || 0,
+        createdAt: doc.createdAt,
+        sizes: doc.sizes || {},
+        // CtrlFile-compatible aliases
+        name: filename,
+        mime: doc.mimeType || '',
+        ext,
+        size: doc.filesize ? Math.round((doc.filesize / 1024) * 10) / 10 : 0,
+    };
+}
+export async function getNitrogenSettings(payload) {
+    return payload.findGlobal({ slug: 'nitrogen-settings' });
+}
+export function requireAuth(req) {
+    if (!req.user) {
+        return Response.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+    return null;
+}

package/dist/endpoints/media.d.ts

@@ -0,0 +1,2 @@
+import type { Endpoint } from 'payload';
+export declare const mediaEndpoints: Endpoint[];

package/dist/endpoints/media.js

@@ -0,0 +1,93 @@
+import { buildMediaItemResponse, requireAuth } from './helpers';
+export const mediaEndpoints = [
+    // GET /api/nitrogen/v1/media — List media items
+    {
+        path: '/nitrogen/v1/media',
+        method: 'get',
+        handler: async (req) => {
+            const { payload } = req;
+            const url = new URL(req.url || '', 'http://localhost');
+            // Parse Payload-style query params: where[mimeType][in][0]=image/jpg
+            const mimeTypes = [];
+            for (const [key, value] of url.searchParams.entries()) {
+                if (/^where\[mimeType\]\[in\]\[\d+\]$/.test(key)) {
+                    mimeTypes.push(value);
+                }
+            }
+            // Parse search: where[filename][contains]=search
+            const search = url.searchParams.get('where[filename][contains]') || '';
+            // Parse page number
+            const page = parseInt(url.searchParams.get('page') || '1', 10);
+            const where = {};
+            if (mimeTypes.length > 0) {
+                where.mimeType = { in: mimeTypes };
+            }
+            if (search) {
+                where.filename = { contains: search };
+            }
+            const result = await payload.find({
+                collection: 'media',
+                where,
+                page,
+                limit: 20,
+                sort: '-createdAt',
+            });
+            const docs = result.docs.map((doc) => buildMediaItemResponse(doc));
+            return Response.json({
+                docs,
+                totalPages: result.totalPages,
+            });
+        },
+    },
+    // PATCH /api/nitrogen/v1/media/:id — Update media alt text
+    {
+        path: '/nitrogen/v1/media/:id',
+        method: 'patch',
+        handler: async (req) => {
+            const authError = requireAuth(req);
+            if (authError)
+                return authError;
+            const { payload, routeParams } = req;
+            const id = routeParams?.id;
+            const body = (await req.json?.());
+            await payload.update({
+                collection: 'media',
+                id,
+                data: { alt: body?.alt || '' },
+            });
+            return Response.json({ success: true });
+        },
+    },
+    // POST /api/nitrogen/v1/media — Upload a media file
+    {
+        path: '/nitrogen/v1/media',
+        method: 'post',
+        handler: async (req) => {
+            const authError = requireAuth(req);
+            if (authError)
+                return authError;
+            const { payload } = req;
+            const formData = await req.formData?.();
+            if (!formData) {
+                return Response.json({ error: 'No form data provided' }, { status: 400 });
+            }
+            // Accept 'file' (singular — sent by Payload provider one at a time)
+            const file = formData.get('file');
+            if (!file) {
+                return Response.json({ error: 'No file provided' }, { status: 400 });
+            }
+            const buffer = Buffer.from(await file.arrayBuffer());
+            const doc = await payload.create({
+                collection: 'media',
+                data: { alt: '' },
+                file: {
+                    data: buffer,
+                    name: file.name,
+                    mimetype: file.type,
+                    size: file.size,
+                },
+            });
+            return Response.json({ doc: buildMediaItemResponse(doc) });
+        },
+    },
+];

package/dist/endpoints/menu.d.ts

@@ -0,0 +1,2 @@
+import type { Endpoint } from 'payload';
+export declare const menuEndpoints: Endpoint[];

package/dist/endpoints/menu.js

@@ -0,0 +1,19 @@
+export const menuEndpoints = [
+    // POST /api/nitrogen/v1/menu — Get menu items (stub)
+    // WordPress nav menus are WP-specific. Returns empty array.
+    // Implement with a NavigationMenus collection if menus are needed.
+    {
+        path: '/nitrogen/v1/menu',
+        method: 'post',
+        handler: async () => {
+            return Response.json({ items: [] });
+        },
+    },
+    {
+        path: '/nitrogen/v1/menu',
+        method: 'get',
+        handler: async () => {
+            return Response.json({ items: [] });
+        },
+    },
+];

package/dist/endpoints/nitrogen-settings.d.ts

@@ -0,0 +1,2 @@
+import type { Endpoint } from 'payload';
+export declare const nitrogenSettingsEndpoints: Endpoint[];

package/dist/endpoints/nitrogen-settings.js

@@ -0,0 +1,22 @@
+import { requireAuth } from './helpers';
+export const nitrogenSettingsEndpoints = [
+    // PUT /api/nitrogen/v1/nitrogen-settings — Save Nitrogen settings
+    {
+        path: '/nitrogen/v1/nitrogen-settings',
+        method: 'put',
+        handler: async (req) => {
+            const authError = requireAuth(req);
+            if (authError)
+                return authError;
+            const { payload } = req;
+            const body = await req.json?.();
+            const updated = await payload.updateGlobal({
+                slug: 'nitrogen-settings',
+                data: {
+                    nitrogenConfig: body,
+                },
+            });
+            return Response.json(updated.nitrogenConfig || {});
+        },
+    },
+];

package/dist/endpoints/templates.d.ts

@@ -0,0 +1,2 @@
+import type { Endpoint } from 'payload';
+export declare const templatesEndpoints: Endpoint[];

package/dist/endpoints/templates.js

@@ -0,0 +1,114 @@
+import { getNitrogenSettings, buildDynamicData, buildPageResponse, buildListItemResponse, requireAuth, } from './helpers';
+export const templatesEndpoints = [
+    // GET /api/nitrogen/v1/templates — List templates
+    {
+        path: '/nitrogen/v1/nitrogen-templates',
+        method: 'get',
+        handler: async (req) => {
+            const { payload } = req;
+            const settings = await getNitrogenSettings(payload);
+            const url = new URL(req.url || '', 'http://localhost');
+            const templateType = url.searchParams.get('templateType');
+            const where = {
+                status: { equals: 'published' },
+            };
+            if (templateType) {
+                where.associatedCollection = { equals: templateType };
+            }
+            const result = await payload.find({
+                collection: 'nitrogen-templates',
+                where,
+                limit: 0,
+                depth: 1,
+            });
+            const items = result.docs.map((doc) => ({
+                ...buildListItemResponse(doc, settings),
+                postType: doc.associatedCollection || '',
+            }));
+            return Response.json(items);
+        },
+    },
+    // GET /api/nitrogen/v1/templates/:id — Get a single template
+    {
+        path: '/nitrogen/v1/nitrogen-templates/:id',
+        method: 'get',
+        handler: async (req) => {
+            const { payload, routeParams } = req;
+            const id = routeParams?.id;
+            try {
+                const doc = await payload.findByID({
+                    collection: 'nitrogen-templates',
+                    id,
+                    depth: 1,
+                });
+                const settings = await getNitrogenSettings(payload);
+                // Build dynamic data from the first document of the associated collection
+                // so the template preview has real data to bind to
+                let dynamicData = buildDynamicData(doc, settings);
+                const associatedCollection = doc.associatedCollection;
+                if (associatedCollection &&
+                    associatedCollection !== 'header' &&
+                    associatedCollection !== 'footer') {
+                    try {
+                        const associated = await payload.find({
+                            collection: associatedCollection,
+                            limit: 1,
+                            depth: 1,
+                        });
+                        if (associated.docs.length) {
+                            dynamicData = buildDynamicData(associated.docs[0], settings);
+                        }
+                    }
+                    catch {
+                        // Collection may not exist — use template's own data
+                    }
+                }
+                const response = buildPageResponse(doc, settings, dynamicData);
+                return Response.json({
+                    ...response,
+                    postType: associatedCollection || '',
+                });
+            }
+            catch {
+                return Response.json({ error: 'Not found' }, { status: 404 });
+            }
+        },
+    },
+    // PATCH /api/nitrogen/v1/templates/:id — Update a template
+    {
+        path: '/nitrogen/v1/nitrogen-templates/:id',
+        method: 'patch',
+        handler: async (req) => {
+            const authError = requireAuth(req);
+            if (authError)
+                return authError;
+            const { payload, routeParams } = req;
+            const id = routeParams?.id;
+            const body = (await req.json?.());
+            const data = body?.data || body;
+            if (!data?.title) {
+                return Response.json({ error: 'Title is required' }, { status: 400 });
+            }
+            const updateData = { title: data.title };
+            if (data.author) {
+                updateData.author = data.author;
+            }
+            if ('data' in data && data.data !== undefined) {
+                updateData.nitrogenData =
+                    typeof data.data === 'string' ? JSON.parse(data.data) : data.data;
+            }
+            if (data.templateType !== undefined) {
+                updateData.associatedCollection = data.templateType;
+            }
+            if (data.settings !== undefined) {
+                updateData.templateSettings = data.settings;
+            }
+            await payload.update({
+                collection: 'nitrogen-templates',
+                id,
+                data: updateData,
+            });
+            return Response.json({ success: true });
+        },
+    },
+];

package/dist/frontend/NitrogenPageClient.d.ts

@@ -0,0 +1,16 @@
+import type { BuilderModule } from "@nitrogenbuilder/types";
+export interface NitrogenPageClientProps {
+    pageId: string;
+    pageData: BuilderModule[];
+    dynamicData: Record<string, unknown>;
+    isBuilder?: boolean;
+    collection?: string;
+}
+/**
+ * Client component that renders Nitrogen pages using React.
+ *
+ * Uses `useNitrogenData` hook for live preview updates in builder mode,
+ * and `NitrogenRenderer` for React-based rendering of the component tree.
+ */
+export declare function NitrogenPageClient({ pageId, pageData, dynamicData: initialDynamicData, isBuilder, collection, }: NitrogenPageClientProps): import("react/jsx-runtime").JSX.Element;
+export default NitrogenPageClient;

package/dist/frontend/NitrogenPageClient.js

@@ -0,0 +1,55 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect } from "react";
+import { NitrogenRenderer, useNitrogenData, } from "@nitrogenbuilder/client-react";
+import { Nitrogen } from "@nitrogenbuilder/client-core";
+/**
+ * Client component that renders Nitrogen pages using React.
+ *
+ * Uses `useNitrogenData` hook for live preview updates in builder mode,
+ * and `NitrogenRenderer` for React-based rendering of the component tree.
+ */
+export function NitrogenPageClient({ pageId, pageData, dynamicData: initialDynamicData, isBuilder = false, collection, }) {
+    // Use the hook for live preview updates
+    const page = useNitrogenData({
+        type: "page",
+        id: pageId,
+        data: pageData,
+        dynamicData: initialDynamicData,
+    });
+    // Set up builder mode scripts when in preview
+    useEffect(() => {
+        if (!isBuilder)
+            return;
+        // Load Nitrogen client bridge (handles editor ↔ iframe communication)
+        const clientBridgeScript = document.createElement("script");
+        clientBridgeScript.src =
+            "https://cdn.jsdelivr.net/npm/@nitrogenbuilder/client@0.3/nitrogen-client.js";
+        document.body.appendChild(clientBridgeScript);
+        // Once the bridge receives the 'init' message from the editor,
+        // dispatch the component definitions so they appear in the sidebar.
+        function onBridgeReady() {
+            const allModules = Nitrogen.modules;
+            if (!allModules.size)
+                return;
+            const modules = {};
+            allModules.forEach((mod, name) => {
+                modules[name] = mod;
+            });
+            window.dispatchEvent(new CustomEvent("nitrogen-modules", {
+                detail: { modules },
+            }));
+        }
+        // nitrogen-client.js dispatches 'nitrogen-initialized' after the editor
+        // sends its init postMessage.
+        window.addEventListener("nitrogen-initialized", onBridgeReady);
+        return () => {
+            window.removeEventListener("nitrogen-initialized", onBridgeReady);
+            if (clientBridgeScript.parentNode) {
+                clientBridgeScript.parentNode.removeChild(clientBridgeScript);
+            }
+        };
+    }, [isBuilder]);
+    return (_jsx("div", { "data-nitrogen-location": "page", "data-page-id": pageId, "data-collection": collection, children: _jsx(NitrogenRenderer, { page: page?.data ?? [], dynamicData: page?.dynamicData ?? initialDynamicData, requestedData: {} }) }));
+}
+export default NitrogenPageClient;

package/dist/frontend/NitrogenWrapper.d.ts

@@ -0,0 +1,45 @@
+import React from 'react';
+import type { BuilderModule } from '@nitrogenbuilder/types';
+export interface NitrogenWrapperProps {
+    /**
+     * The page document from Payload. Must have `id` and optionally `nitrogenData`.
+     */
+    page: {
+        id: string | number;
+        nitrogenData?: BuilderModule[] | null;
+        [key: string]: unknown;
+    };
+    /**
+     * Next.js searchParams (awaited). Used to detect builder mode.
+     */
+    searchParams: Record<string, string | string[] | undefined>;
+    /**
+     * The Payload collection this page belongs to.
+     */
+    collection: string;
+    /**
+     * Regular page content to render when not in Nitrogen mode.
+     */
+    children: React.ReactNode;
+}
+/**
+ * Server component that wraps your page content and automatically handles
+ * Nitrogen builder mode and Nitrogen-rendered pages.
+ *
+ * Usage:
+ * ```tsx
+ * import { NitrogenWrapper } from 'nitrogen-connector-payload/frontend'
+ *
+ * export default async function Page({ params, searchParams }) {
+ *   const page = await queryPage(...)
+ *
+ *   return (
+ *     <NitrogenWrapper page={page} searchParams={await searchParams} collection="pages">
+ *       <YourRegularPageContent page={page} />
+ *     </NitrogenWrapper>
+ *   )
+ * }
+ * ```
+ */
+export declare function NitrogenWrapper({ page, searchParams, collection, children, }: NitrogenWrapperProps): Promise<import("react/jsx-runtime").JSX.Element>;
+export default NitrogenWrapper;

package/dist/frontend/NitrogenWrapper.js

@@ -0,0 +1,38 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { getPayload } from 'payload';
+import { NitrogenPageClient } from './NitrogenPageClient';
+import { buildDynamicData, getNitrogenSettings } from '../endpoints/helpers';
+/**
+ * Server component that wraps your page content and automatically handles
+ * Nitrogen builder mode and Nitrogen-rendered pages.
+ *
+ * Usage:
+ * ```tsx
+ * import { NitrogenWrapper } from 'nitrogen-connector-payload/frontend'
+ *
+ * export default async function Page({ params, searchParams }) {
+ *   const page = await queryPage(...)
+ *
+ *   return (
+ *     <NitrogenWrapper page={page} searchParams={await searchParams} collection="pages">
+ *       <YourRegularPageContent page={page} />
+ *     </NitrogenWrapper>
+ *   )
+ * }
+ * ```
+ */
+export async function NitrogenWrapper({ page, searchParams, collection, children, }) {
+    const isBuilder = searchParams['nitrogen-builder'] !== undefined;
+    const hasNitrogenData = Array.isArray(page.nitrogenData) && page.nitrogenData.length > 0;
+    // If not in builder mode and no Nitrogen data, render regular content
+    if (!isBuilder && !hasNitrogenData) {
+        return _jsx(_Fragment, { children: children });
+    }
+    // Fetch Nitrogen settings and build dynamic data
+    const payloadConfig = (await import('@payload-config')).default;
+    const payload = await getPayload({ config: payloadConfig });
+    const settings = await getNitrogenSettings(payload);
+    const dynamicData = buildDynamicData(page, settings);
+    return (_jsx(NitrogenPageClient, { pageId: String(page.id), pageData: page.nitrogenData || [], dynamicData: dynamicData, isBuilder: isBuilder, collection: collection }));
+}
+export default NitrogenWrapper;

package/dist/frontend/index.d.ts

@@ -0,0 +1,7 @@
+export { NitrogenWrapper } from "./NitrogenWrapper";
+export type { NitrogenWrapperProps } from "./NitrogenWrapper";
+export { NitrogenPageClient } from "./NitrogenPageClient";
+export type { NitrogenPageClientProps } from "./NitrogenPageClient";
+export { buildDynamicData, getNitrogenSettings } from "../endpoints/helpers";
+export { nitrogen } from "@nitrogenbuilder/client-core";
+export type { ComponentSettings, ComponentSettingsToProps, } from "@nitrogenbuilder/types";

package/dist/frontend/index.js

@@ -0,0 +1,8 @@
+// Main export - use NitrogenWrapper for simplest integration
+export { NitrogenWrapper } from "./NitrogenWrapper";
+// Lower-level exports for custom implementations
+export { NitrogenPageClient } from "./NitrogenPageClient";
+// Helper exports for data fetching (server-safe)
+export { buildDynamicData, getNitrogenSettings } from "../endpoints/helpers";
+// Re-export nitrogen singleton for registering custom components
+export { nitrogen } from "@nitrogenbuilder/client-core";

package/dist/globals/NitrogenSettings.d.ts

@@ -0,0 +1,2 @@
+import type { GlobalConfig } from 'payload';
+export declare const NitrogenSettings: GlobalConfig;

package/dist/globals/NitrogenSettings.js

@@ -0,0 +1,41 @@
+export const NitrogenSettings = {
+    slug: 'nitrogen-settings',
+    access: {
+        read: ({ req }) => !!req.user,
+        update: ({ req }) => !!req.user,
+    },
+    fields: [
+        {
+            name: 'licenseKey',
+            type: 'text',
+            admin: { description: 'Nitrogen license key' },
+        },
+        {
+            name: 'connectorToken',
+            type: 'text',
+            admin: { description: 'Connector token for server communication' },
+        },
+        {
+            name: 'instanceUrl',
+            type: 'text',
+            admin: { description: 'Nitrogen instance URL' },
+        },
+        {
+            name: 'frontendUrl',
+            type: 'text',
+            admin: { description: 'Production frontend URL' },
+        },
+        {
+            name: 'developmentUrl',
+            type: 'text',
+            admin: { description: 'Local development URL' },
+        },
+        {
+            name: 'nitrogenConfig',
+            type: 'json',
+            admin: {
+                description: 'Full Nitrogen configuration JSON (colors, variables, CSS injection, URL maps, etc.)',
+            },
+        },
+    ],
+};