@aligent/nx-appbuilder 0.2.0

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/actions/utils/http.ts.template

@@ -0,0 +1,18 @@
+/**
+ * Helper constant for HTTP status codes
+ *
+ * Caution: 500 errors will cause an action to be retried for 24 hours with exponential backoff
+ *
+ * https://developer.adobe.com/events/docs/support/faq/#what-happens-if-my-webhook-is-down-why-is-my-event-registration-marked-as-unstable
+ */
+export const STATUS_CODES = {
+    OK: 200,
+    Created: 201,
+    Accepted: 202,
+    NoContent: 204,
+    BadRequest: 400,
+    Unauthorized: 401,
+    InternalServerError: 500,
+} as const;
+
+export type StatusCode = (typeof STATUS_CODES)[keyof typeof STATUS_CODES];

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/actions/utils/runtime.ts.template

@@ -0,0 +1,47 @@
+/**
+ * Request parameters set by the OpenWhisk framework.
+ * https://developer.adobe.com/runtime/docs/guides/reference/environment_variables/
+ */
+export interface RequestParameters {
+    __ow_method: string;
+    __ow_headers: {
+        authorization?: string;
+        [key: string]: string | number | undefined;
+    };
+    __ow_path: string;
+    __ow_body: string;
+    __ow_query: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Environment variables set by the OpenWhisk framework.
+ * https://developer.adobe.com/runtime/docs/guides/reference/environment_variables/
+ */
+export interface EnvironmentVariables {
+    __OW_ACTION_NAME: string;
+    __OW_ACTION_VERSION: string;
+    __OW_ACTIVATION_ID: string;
+    __OW_ALLOW_CONCURRENT: string;
+    __OW_API_HOST: string;
+    __OW_CLOUD: string;
+    __OW_NAMESPACE: string;
+    __OW_REGION: string;
+    __OW_TRANSACTION_ID: string;
+}
+
+interface SuccessResponse<B> {
+    statusCode: number;
+    body: B;
+}
+
+interface ErrorResponse {
+    error: {
+        statusCode: number;
+        body: {
+            error: string;
+        };
+    };
+}
+
+export type Response<B> = Promise<SuccessResponse<B> | ErrorResponse>;

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/actions/utils/utils.ts.template

@@ -0,0 +1,187 @@
+import type { Paths, SetRequiredDeep, SimplifyDeep, UnionToIntersection } from 'type-fest';
+import { RequestParameters } from './runtime.ts';
+
+/**
+ *
+ * Returns a log ready string of the action input parameters.
+ * The `Authorization` header content will be replaced by '<hidden>'.
+ *
+ * @param {object} params action input parameters.
+ *
+ * @returns {string} A sanitized string containing the input parameters
+ *
+ */
+export function stringParameters<T extends RequestParameters>(params: T): string {
+    // hide authorization token without overriding params
+    let headers = params.__ow_headers || {};
+    if (headers.authorization) {
+        headers = { ...headers, authorization: '<hidden>' };
+    }
+    return JSON.stringify({ ...params, __ow_headers: headers });
+}
+
+/**
+ * Type guard to check if a value is a classic object (i.e. indexable by string keys).
+ *
+ * @param {unknown} value value to check.
+ * @returns {boolean} true if the value is an object, false otherwise.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && value.constructor === Object;
+}
+
+/**
+ * Safely retrieves a value from an object using a dot-notation path.
+ * Returns undefined if the full path does not exist.
+ *
+ * @param {Record<string, unknown>} obj object to check.
+ * @param {string} path dot-notation path to the value.
+ * @returns {unknown} the value at the path or undefined if the path does not exist.
+ */
+function getValueByPath(obj: Record<string, unknown>, path: string): unknown {
+    const keys = path.split('.');
+    let currentValue: unknown = obj;
+
+    for (const key of keys) {
+        if (!isRecord(currentValue)) {
+            return undefined;
+        }
+        currentValue = currentValue[key];
+    }
+
+    return currentValue;
+}
+
+/**
+ * Returns the list of missing keys from an object based on required paths.
+ * A key is missing if its value at the specified path is undefined or ''.
+ *
+ * @param {Record<string, unknown>} obj object to check.
+ * @param {string[]} required list of required keys (can use dot notation for nesting).
+ * @returns {string[]} Array of missing keys.
+ */
+function getMissingKeys(obj: Record<string, unknown>, required: string[]): string[] {
+    return required.filter(requiredPath => {
+        const value = getValueByPath(obj, requiredPath);
+        return value === undefined || value === '';
+    });
+}
+
+type BuildObject<P extends string> = P extends `${infer U}.${infer Rest}`
+    ? { [key in U]: BuildObject<Rest> }
+    : { [key in P]: unknown };
+
+export type ObjectFromPaths<P extends string[]> = SimplifyDeep<
+    UnionToIntersection<BuildObject<P[number]>>
+>;
+
+/**
+ *
+ * Returns the list of missing keys giving an object and its required keys.
+ * A parameter is missing if its value is undefined or ''.
+ * A value of 0 or null is not considered as missing.
+ *
+ * @param {object} params action input parameters.
+ * @param {array} requiredHeaders list of required input headers.
+ * @param {array} requiredParams list of required input parameters.
+ *        Each element can be multi level deep using a '.' separator e.g. 'myRequiredObj.myRequiredKey'.
+ *
+ * @returns {object} Returns an object with the following properties:
+ *        - success: boolean
+ *        - data: The input parameters with the required keys set
+ *        - error: A string describing the missing inputs if any
+ *
+ */
+export function checkMissingRequestInputs<
+    const T extends Partial<RequestParameters>,
+    const P extends Array<Paths<T> | Paths<T>>,
+    const H extends Array<Paths<T> | Paths<T['__ow_headers']>>,
+>(params: T, requiredParams: P, requiredHeaders: H) {
+    let errorMessage: string | null = null;
+
+    // check for missing headers, including those added by OpenWhisk
+    const missingHeaders = getMissingKeys({ ...params.__ow_headers }, requiredHeaders);
+    if (missingHeaders.length > 0) {
+        errorMessage = `missing header(s) '${missingHeaders}'`;
+    }
+
+    // check for missing parameters
+    const missingParams = getMissingKeys(params, requiredParams);
+    if (missingParams.length > 0) {
+        if (errorMessage) {
+            errorMessage += ' and ';
+        } else {
+            errorMessage = '';
+        }
+        errorMessage += `missing parameter(s) '${missingParams}'`;
+    }
+
+    if (errorMessage) {
+        return {
+            success: false as const,
+            error: errorMessage,
+        };
+    }
+
+    return {
+        success: true as const,
+        data: params as SetRequiredDeep<T, [...P][number]> & {
+            __ow_headers: {
+                [key in H[number]]: string;
+            };
+        },
+    };
+}
+
+/**
+ *
+ * Extracts the bearer token string from the Authorization header in the request parameters.
+ *
+ * @param {object} params action input parameters.
+ *
+ * @returns {string|undefined} the token string or undefined if not set in request headers.
+ *
+ */
+export function getBearerToken<T extends Pick<RequestParameters, '__ow_headers'>>(
+    params: T
+): string | undefined {
+    const bearerPrefix = 'Bearer ';
+    if (
+        typeof params.__ow_headers?.authorization === 'string' &&
+        params.__ow_headers.authorization.startsWith(bearerPrefix)
+    ) {
+        return params.__ow_headers.authorization.substring(bearerPrefix.length);
+    }
+    return undefined;
+}
+
+/**
+ *
+ * Returns an error response object and attempts to log.info the status code and error message
+ *
+ * @param {number} statusCode the error status code.
+ *        e.g. 400
+ * @param {string} message the error message.
+ *        e.g. 'missing xyz parameter'
+ * @param {*} [logger] an optional logger instance object with an `info` method
+ *        e.g. `new require('@adobe/aio-sdk').Core.Logger('name')`
+ *
+ * @returns {object} the error object, ready to be returned from the action main's function.
+ *
+ */
+export function errorResponse(
+    statusCode: number,
+    message: string,
+    logger?: { info: (message: string) => unknown }
+): object {
+    logger?.info(`${statusCode}: ${message}`);
+
+    return {
+        error: {
+            statusCode,
+            body: {
+                error: message,
+            },
+        },
+    };
+}

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/ext.config.yaml.template

@@ -0,0 +1,20 @@
+operations:
+    view:
+        - type: web
+          impl: index.html
+actions: actions
+web: web-src
+runtimeManifest:
+    packages:
+        admin-ui-sdk:
+            license: Apache-2.0
+            actions:
+                registration:
+                    function: actions/registration/index.ts
+                    web: 'yes'
+                    runtime: 'nodejs:22'
+                    inputs:
+                        LOG_LEVEL: debug
+                    annotations:
+                        require-adobe-auth: true
+                        final: true

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/.gitignore.template

@@ -0,0 +1,2 @@
+# Automatically generated by Aio CLI
+config.json

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/index.html.template

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, shrink-to-fit=no">
+  <meta name="theme-color" content="#333333">
+  <meta http-equiv="X-UA-Compatible" content="ie=edge">
+  <title><%= displayName %></title>
+</head>
+<body>
+  <noscript>You need to enable JavaScript to run this app.</noscript>
+  <div id="root"></div>
+  <script src="src/index.tsx" async type="module"></script>
+</body>
+</html>

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/src/components/App.tsx.template

@@ -0,0 +1,37 @@
+import { Content, Heading, lightTheme, Provider, View } from '@adobe/react-spectrum';
+import { Route, Routes, useNavigate } from 'react-router';
+
+import { PageContextProvider } from '@/web/context/PageContextProvider.tsx';
+
+function App() {
+    const navigate = useNavigate();
+
+    return (
+        <PageContextProvider title="<%= displayName %>">
+            <Provider
+                theme={lightTheme}
+                colorScheme={'light'}
+                router={{
+                    navigate,
+                }}
+            >
+                <View padding="size-300">
+                    <Routes>
+                        <Route path="/" element={<LandingPage />} />
+                    </Routes>
+                </View>
+            </Provider>
+        </PageContextProvider>
+    );
+}
+
+function LandingPage() {
+    return (
+        <>
+            <Heading level={1}><%= displayName %></Heading>
+            <Content><%= description %></Content>
+        </>
+    );
+}
+
+export default App;

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/src/components/ExtensionRegistration.tsx.template

@@ -0,0 +1,15 @@
+import { register } from '@adobe/uix-guest';
+import { useEffect, type ReactNode } from 'react';
+
+import { EXTENSION_ID } from '@/web/constants/extension.ts';
+
+export default function ExtensionRegistration({ children }: { children: ReactNode }) {
+    useEffect(() => {
+        register({
+            id: EXTENSION_ID,
+            methods: {},
+        }).catch(console.error);
+    }, []);
+
+    return <>{children}</>;
+}

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/src/config.json.d.ts.template

@@ -0,0 +1,4 @@
+// config.json is generated at build time by the Adobe App Builder CLI.
+// This declaration provides types for TypeScript when the file is absent (e.g. CI type checks).
+declare const config: Record<string, string>;
+export default config;

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/src/constants/extension.ts.template

@@ -0,0 +1 @@
+export const EXTENSION_ID = '<%= extensionId %>';

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/src/context/AdobeRuntimeContextProvider.tsx.template

@@ -0,0 +1,65 @@
+import { attach } from '@adobe/uix-guest';
+import { createContext, useContext, useEffect, useState, type ReactNode } from 'react';
+
+import { EXTENSION_ID } from '@/web/constants/extension.ts';
+
+interface ImsContext {
+    token?: string | undefined;
+    org?: string | undefined;
+}
+
+interface AdobeRuntimeContextType {
+    loading: boolean;
+    error: Error | null;
+    ims: ImsContext;
+}
+
+const AdobeRuntimeContext = createContext<AdobeRuntimeContextType>({
+    loading: true,
+    error: null,
+    ims: {},
+});
+
+/**
+ * Retrieves IMS credentials from the Commerce Admin shared context via attach().
+ *
+ * register() is handled separately by the ExtensionRegistration component.
+ * This provider only calls attach() to access the shared context (imsToken, imsOrgId).
+ */
+export const AdobeRuntimeContextProvider = ({ children }: { children: ReactNode }) => {
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState<Error | null>(null);
+    const [ims, setIms] = useState<ImsContext>({});
+
+    useEffect(() => {
+        const init = async () => {
+            try {
+                const guestConnection = await attach({ id: EXTENSION_ID });
+                const token = guestConnection.sharedContext.get('imsToken') as string | undefined;
+                const org = guestConnection.sharedContext.get('imsOrgId') as string | undefined;
+
+                setIms({ token, org });
+            } catch (err) {
+                console.error('Failed to retrieve Admin UI SDK shared context', err);
+                setError(err instanceof Error ? err : new Error(String(err)));
+            } finally {
+                setLoading(false);
+            }
+        };
+
+        init();
+    }, []);
+
+    return <AdobeRuntimeContext value={{ loading, error, ims }}>{children}</AdobeRuntimeContext>;
+};
+
+/**
+ * React hook to access IMS credentials from the Commerce Admin context.
+ */
+export const useAdobeRuntimeContext = () => {
+    const context = useContext(AdobeRuntimeContext);
+    if (!context) {
+        throw new Error('AdobeRuntimeContext not found');
+    }
+    return context;
+};

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/src/context/PageContextProvider.tsx.template

@@ -0,0 +1,78 @@
+import page from '@adobe/exc-app/page';
+import topbar from '@adobe/exc-app/topbar';
+import { createContext, useContext, useEffect, type ReactNode } from 'react';
+
+import { useAdobeRuntimeContext } from '@/web/context/AdobeRuntimeContextProvider';
+
+interface PageContextType {
+    title: string;
+    shortTitle: string;
+}
+
+export const PageContext = createContext<PageContextType>({
+    title: 'Adobe App Builder',
+    shortTitle: 'AAB',
+});
+
+/**
+ * Format a short title from the full title.
+ *
+ * If the title is less than 3 words, use the first 5 characters.
+ * If the title is 3 or more words, make an acronym from the first 5 words.
+ */
+function formatShortTitle(title: string) {
+    return title.split(' ').length >= 3
+        ? title.split(' ').slice(0, 5).join('').toUpperCase()
+        : title.slice(0, 5);
+}
+
+/**
+ * Provides page properties to the application.
+ *
+ * If wrapped with AdobeRuntimeContextProvider, updates the topbar and page
+ * title once the Adobe runtime is ready.
+ */
+export const PageContextProvider = ({
+    children,
+    title,
+    shortTitle,
+}: {
+    children: ReactNode;
+    title?: string;
+    shortTitle?: string;
+}) => {
+    const formattedTitle = title?.trim() || 'Adobe App Builder';
+    const formattedShortTitle = shortTitle?.trim() || formatShortTitle(formattedTitle);
+
+    const { loading, error } = useAdobeRuntimeContext();
+    useEffect(() => {
+        document.title = formattedTitle;
+
+        if (loading || error) {
+            return;
+        }
+
+        // topbar/page APIs are only available when running inside the Experience Cloud Shell.
+        // In the Commerce Admin iframe they are not available, so we catch and ignore.
+        try {
+            topbar.solution = {
+                icon: 'AdobeExperienceCloud',
+                title: formattedTitle,
+                shortTitle: formattedShortTitle,
+            };
+            page.title = formattedTitle;
+        } catch {
+            // Not running in Experience Cloud Shell — topbar APIs unavailable.
+        }
+    }, [loading, error, formattedTitle, formattedShortTitle]);
+
+    return (
+        <PageContext value={{ title: formattedTitle, shortTitle: formattedShortTitle }}>
+            {children}
+        </PageContext>
+    );
+};
+
+export const usePageContext = () => {
+    return useContext(PageContext);
+};

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/src/hooks/useAppBuilderAction.ts.template

@@ -0,0 +1,41 @@
+import { useEffect, useRef } from 'react';
+
+import {
+    useLazyAppBuilderAction,
+    type UseLazyAppBuilderActionOptions,
+} from '@/web/hooks/useLazyAppBuilderAction';
+
+/**
+ * React hook that invokes an App Builder action immediately on mount.
+ *
+ * Use this when you need to fetch data as soon as the component renders.
+ * For manual invocation, use `useLazyAppBuilderAction` directly.
+ *
+ * @example
+ * ```tsx
+ * const { response, loading } = useAppBuilderAction<ConfigData>({
+ *     name: 'my-package/get-config',
+ *     method: 'GET',
+ * });
+ *
+ * if (loading) return <Spinner />;
+ * return <ConfigForm initialValues={response} />;
+ * ```
+ */
+export function useAppBuilderAction<T = unknown>(options: UseLazyAppBuilderActionOptions) {
+    const hasInvokedRef = useRef(false);
+
+    const { response, loading: isInvoking, error, invoke } = useLazyAppBuilderAction<T>(options);
+
+    useEffect(() => {
+        if (hasInvokedRef.current) {
+            return;
+        }
+        hasInvokedRef.current = true;
+        invoke();
+    }, [invoke]);
+
+    const loading = isInvoking || (!response && !error);
+
+    return { response, loading, error };
+}

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/src/hooks/useLazyAppBuilderAction.ts.template

@@ -0,0 +1,116 @@
+import { useCallback, useState } from 'react';
+
+import ActionRegistry from '@/web/config.json';
+import { type ActionName } from '@/web/types/ActionName.ts';
+
+/**
+ * Payload options that can be passed when invoking an action.
+ * These values merge with and override the options set during hook initialization.
+ */
+export interface ActionPayload {
+    /** URL search parameters to append to the action URL */
+    searchParams?: Record<string, string>;
+
+    /** Request body for non-GET/HEAD requests */
+    body?: object;
+
+    /** Custom headers to include in the request */
+    headers?: Record<string, string>;
+}
+
+/**
+ * Configuration options for the useLazyAppBuilderAction / useAppBuilderAction hooks.
+ */
+export type UseLazyAppBuilderActionOptions = ActionPayload & {
+    /** The name of the action to invoke. Must be a key from the action registry in `config.json`. */
+    name: ActionName;
+
+    /**
+     * HTTP method to use for the request.
+     * @default 'GET'
+     */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+
+    /** Adobe IMS authentication credentials */
+    ims?: {
+        token?: string | undefined;
+        org?: string | undefined;
+    };
+};
+
+/**
+ * React hook for invoking App Builder actions with built-in state management.
+ *
+ * Returns `{ invoke, response, loading, error }`. Call `invoke()` to fire the
+ * request manually. For automatic invocation on mount, use `useAppBuilderAction`.
+ *
+ * @example
+ * ```tsx
+ * const { invoke, response, loading, error } = useLazyAppBuilderAction<MyData>({
+ *     name: 'my-package/my-action',
+ *     method: 'POST',
+ *     ims: { token, org },
+ * });
+ *
+ * await invoke({ body: { id: '123' } });
+ * ```
+ */
+export function useLazyAppBuilderAction<T = unknown>(options: UseLazyAppBuilderActionOptions) {
+    const [response, setResponse] = useState<T | null>(null);
+    const [loading, setLoading] = useState<boolean>(false);
+    const [error, setError] = useState<string | null>(null);
+
+    const invoke = useCallback(
+        async (invokeOptions?: ActionPayload) => {
+            setLoading(true);
+            setError(null);
+            setResponse(null);
+
+            try {
+                const actionUrl = ActionRegistry[options.name];
+                if (!actionUrl) {
+                    throw new Error(`Action "${options.name}" not found in config.json`);
+                }
+
+                const headers = new Headers({
+                    'content-type': 'application/json',
+                    ...(options.ims?.org && { 'x-gw-ims-org-id': options.ims.org }),
+                    ...(options.ims?.token && { Authorization: `Bearer ${options.ims.token}` }),
+                    ...options.headers,
+                    ...invokeOptions?.headers,
+                });
+
+                const url = new URL(actionUrl);
+                const allSearchParams = { ...options.searchParams, ...invokeOptions?.searchParams };
+                for (const [k, v] of Object.entries(allSearchParams)) {
+                    if (v != null) url.searchParams.set(k, v);
+                }
+
+                const fetchOptions: RequestInit = {
+                    method: options.method || 'GET',
+                    headers,
+                };
+
+                if (fetchOptions.method !== 'GET' && fetchOptions.method !== 'HEAD') {
+                    const body = invokeOptions?.body || options.body;
+                    if (body) fetchOptions.body = JSON.stringify(body);
+                }
+
+                const response = await fetch(url.toString(), fetchOptions);
+                if (!response.ok) {
+                    throw new Error(`Error: ${response.status} ${response.statusText}`);
+                }
+
+                const data = await response.json();
+                setResponse(data);
+            } catch (err) {
+                setError(err instanceof Error ? err.message : String(err));
+            } finally {
+                setLoading(false);
+            }
+        },
+        [options]
+    );
+
+    return { response, loading, error, invoke };
+}

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/src/index.css.template

@@ -0,0 +1,4 @@
+html,
+body {
+  margin: 0;
+}

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/src/index.tsx.template

@@ -0,0 +1,20 @@
+import { createRoot } from 'react-dom/client';
+import { HashRouter } from 'react-router';
+
+import App from '@/web/components/App.tsx';
+import ExtensionRegistration from '@/web/components/ExtensionRegistration.tsx';
+import { AdobeRuntimeContextProvider } from '@/web/context/AdobeRuntimeContextProvider.tsx';
+
+import './index.css';
+
+const root = createRoot(document.getElementById('root')!);
+
+root.render(
+    <HashRouter>
+        <ExtensionRegistration>
+            <AdobeRuntimeContextProvider>
+                <App />
+            </AdobeRuntimeContextProvider>
+        </ExtensionRegistration>
+    </HashRouter>
+);