@combeenation/custom-code-sdk 0.0.1-alpha6 → 0.0.1-alpha7

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 
+declare type AppLanguage = 'en' | 'de';
+
 export declare class Button {
     #private;
     readonly id: CtrlId;
@@ -14,13 +16,20 @@ declare type CallbackUnsubscribeOption = {
     unsubscribe: () => void;
 };
 
-declare type CfgrClient = NonNullable<typeof client>;
-
-declare interface CfgrClientApi_v1 {
-    finishConfiguration: (input?: string) => Promise<FinishResult>;
-    onAnyCmpValueChanged<TInput extends ValueComponent_2>(listener: CmpValuesChangedListener<TInput['name']>, components: TInput[], lazy?: boolean): Promise<void>;
-    getCmpValue<T extends CmpValue_2>(cmpName: CmpName_2): Promise<T | undefined>;
-    onCmpValueChanged<TValue extends CmpValue_2>(cmpName: CmpName_2, listener: CmpValueChangedListener_2<TValue>, condition?: CmpValueChangedCondition_2<TValue>, callImmediately?: boolean): Promise<void>;
+export declare namespace CbnSdk {
+    export {
+        configuratorIsInIFrame,
+        finishConfiguration,
+        fireAnalyticsEvent,
+        getParentPageUrl,
+        navigateToLogin,
+        onAnyCmpValueChanged,
+        redirectParentPage,
+        sendCustomMsgToParentPage,
+        setConfiguratorIFrameSize,
+        shareConfiguration,
+        version
+    }
 }
 
 export declare class Checkbox {
@@ -31,52 +40,27 @@ export declare class Checkbox {
     setVisible(visible: boolean): Promise<void>;
 }
 
-export declare type CheckoutProductCustomFields = {
-    /**
-     * Unique identifier
-     */
-    id: string;
-    /**
-     * Label which the user will also see in the cart (if it is visible)
-     */
-    label: string;
-    /**
-     * Value of the custom field
-     */
-    value: string;
-    /**
-     * Position in the cart
-     */
-    position: number;
-    /**
-     * If it should be visible in the cart
-     */
-    isVisible: boolean;
-};
-
-declare const client: CfgrClientApi_v1 | undefined;
-
 declare type CmpName = string;
 
-declare type CmpName_2 = string;
-
+/**
+ * All possible typings for component values.
+ *
+ * Rule of thumb with this type: Limit usages to the bare minimum only when actually needed.
+ * Ideally, this type should not be used in the consuming app (cfgr editor etc.) at all but only in the API layer which
+ * does all the parsing & conversion of cmp values to raw wire format and vice versa.
+ *
+ * Why?
+ * This is practically an `unknown` ATM (see comment above {@link ZCmpValue}) and dealing with `unknown` in code is very
+ * cumbersome and leads to hard to maintain code.
+ */
 declare type CmpValue = z.infer<typeof ZCmpValue>;
 
-declare type CmpValue_2 = z.infer<typeof ZCmpValue_2>;
-
-declare interface CmpValueChangedCondition<T extends CmpValue = CmpValue> {
+/** Interface for value changed condition function */
+export declare interface CmpValueChangedCondition<T extends CmpValue = CmpValue> {
     (param: T | undefined): Promise<boolean>;
 }
 
-declare interface CmpValueChangedCondition_2<T extends CmpValue_2 = CmpValue_2> {
-    (param: T | undefined): Promise<boolean>;
-}
-
-declare interface CmpValueChangedListener<T extends CmpValue = CmpValue> {
-    (param: T | undefined): void;
-}
-
-declare interface CmpValueChangedListener_2<T extends CmpValue_2 = CmpValue_2> {
+export declare interface CmpValueChangedListener<T extends CmpValue = CmpValue> {
     (param: T | undefined): void;
 }
 
@@ -84,7 +68,11 @@ declare type CmpValueChangedMap<TName extends string = string> = {
     [K in TName]: boolean;
 };
 
-declare interface CmpValuesChangedListener<TName extends string = string> {
+export declare interface CmpValuesChangedListener<TName extends string = string> {
+    /**
+     * Returns an object where each key represents the given components, and the corresponding boolean value
+     * indicates whether that component has changed or not
+     */
     (changedCmps: CmpValueChangedMap<TName>): void;
 }
 
@@ -96,6 +84,11 @@ export declare class Collapsible {
     setVisible(visible: boolean): Promise<void>;
 }
 
+/**
+ * Checks if the configurator is embedded inside an IFrame.
+ */
+export declare const configuratorIsInIFrame: () => boolean;
+
 declare type CtrlId = z.infer<typeof ZCtrlId>;
 
 export declare class CustomControl {
@@ -104,9 +97,9 @@ export declare class CustomControl {
     constructor(id: CtrlId);
     /**
      * Things to mention when writing docs:
-     *   - Given `el` is only disconnected when ctrl is hidden
-     *     -> Event listener on that element shall only be installed once in custom code
-     *     Explicitly mention that this is only the case for `customCtrl.renderFn` and not for `otherCtrls.onRendered`.
+     *   - The `renderFn` is always meant to actively render/set the content/innerHTML of the given `element`.
+     *     ATM, system does sometimes pass a "pre-rendered" `element` but that will change in the future when introducing
+     *     some dedicated ctrl property like "Custom control controlled/custom control rendered/...".
      *   - Assigning a new fn does not trigger a re-render
      *   - Explain, when this fn is being called (automatically on show, manually on `.render()`)
      *   - Explain, why this should be used instead of a pattern like the following:
@@ -137,26 +130,78 @@ export declare class Dataview {
     setVisible(visible: boolean): Promise<void>;
 }
 
-export declare type DiyShopCheckoutJson = Shopware6CheckoutJson;
+/**
+ * Creates a finish of the current configuration by running all the Configurator's finish actions and optionally passes
+ * the resulting data to the parent page.
+ */
+export declare const finishConfiguration: (options: (FinishConfigurationBaseOptions & {
+    sendDataToParentPage: false;
+}) | (FinishConfigurationBaseOptions & {
+    /**
+     * If `true`, the data returned by `transformParentPageData` will be passed to the function
+     * `window.Combeenation.onConfigurationFinished(data)` on the parent page (or one of its older aliases like
+     * `Combeenation.onCheckout` etc.).
+     */
+    sendDataToParentPage: true;
+    /**
+     * Allows transformation of the data that is passed to the parent page after the configuration is finished.
+     *
+     * @example
+     * ```ts
+     * const checkoutData: Shopware6CheckoutJson = { ... };
+     *
+     * finishConfiguration({
+     *   transformParentPageData: () => {
+     *     return {
+     *       id: cfgnId, // E.g. from Hive's `configuration.id`
+     *       authentication: authToken, // E.g. from Hive's `configuration.authToken`
+     *       checkoutParameters: JSON.stringify(checkoutData),
+     *       queryParameters: Object.fromEntries(new URLSearchParams(window.location.search)),
+     *       checkoutParametersHash: '123', // Not actually used ATM, will be provided by the server in the future
+     *     } satisfies ParentPageCheckoutData;
+     *   },
+     * });
+     * ```
+     *
+     * FYI, this is mandatory ATM and does not get any input values which means that the consumer is required to
+     * build the return value himself. In the future we'll change this to be optional and provide the data generated
+     * on the server as input to the transformation function.
+     */
+    transformParentPageData: () => ParentPageCheckoutData & {
+        [key: string]: SerializableJsonValue;
+    };
+})) => Promise<void>;
 
-export declare const finishConfiguration: CfgrClient['finishConfiguration'];
+declare type FinishConfigurationBaseOptions = {
+    input?: string;
+};
 
 /**
- * Why we need this?
+ * Pushes the given data into the Google Tag Manager data layer on the parent page.
  *
- * Our custom code SDK is using the `ConfiguratorClient` as its main gateway to communicate with cmps. It comes with the
- * `ConfiguratorClient` built in and only knows about the API of the version is was built with.
+ * If the Configurator is not embedded in an IFrame, the event is pushed directly into the data layer of the current
+ * window.
  *
- * Therefore, we'll always have to support older versions of the public API for custom code as well at "system runtime".
+ * If embedded in an IFrame, this requires the Configurator plugin to be installed correctly on the parent page.\
+ * See embedding instructions for details.
  *
- * Custom code shall always access the `ConfiguratorClient` via some well defined "gateway fn" like
- * `window.Cbn.getCustomCodeSdkBridge().createCfgrClient` which is responsible for returning the correct versioned API
- * e.g. by "hotpatching" the returned runtime object based on the requested version.
+ * @param event Key for event identification
  */
-declare type FinishResult = {
-    newEditCfgnUrl: string;
-    actionResults: {};
-};
+export declare const fireAnalyticsEvent: (event: string, eventData?: object | string) => Promise<ParentPageComResult<void>>;
+
+export declare type FlexShopFinishJson = Shopware6FinishJson;
+
+/**
+ * Retrieve the parent page's URI.
+ *
+ * Requires the Configurator plugin to be installed correctly on the parent page.\
+ * See embedding instructions for details.
+ *
+ * @returns `undefined` if we're not inside an IFrame or the parent page does not respond to our request.
+ */
+export declare const getParentPageUrl: () => Promise<ParentPageComResult<{
+    url: string;
+}>>;
 
 export declare class Input {
     #private;
@@ -166,7 +211,59 @@ export declare class Input {
     setVisible(visible: boolean): Promise<void>;
 }
 
-export declare const onAnyCmpValueChanged: CfgrClient['onAnyCmpValueChanged'];
+declare type JsonArray = Array<SerializableJsonValue>;
+
+declare type JsonObject = {
+    [key: string]: SerializableJsonValue;
+};
+
+declare type JsonPrimitive = string | number | boolean | null;
+
+/**
+ * Navigates to the login page of the Configurator.
+ *
+ * @param options.hideBackNavigation Defaults to `false`.\
+ *                                   E.g. can be used if the Configurator immediately redirects to the login and
+ *                                   shouldn't be accessible without a successful login.
+ * @param options.language Defaults to the browser language.
+ */
+export declare const navigateToLogin: (options?: {
+    hideBackNavigation?: boolean;
+    language?: AppLanguage;
+}) => void;
+
+/**
+ * @param listener Called whenever the value of at least 1 component has changed.\
+ *                 Returns an object that indicates which components have actually changed.
+ * @param components Only call the listener if one of the given cmps have changed
+ * @param lazy `false` [default]: Immediately fetch the values of all changed components.\
+ *             `true`: Trigger the listener but don't fetch values until specifically requested.
+ *                     This could reduce data traffic when only some components are required in the listener, due to
+ *                     conditions or similar.
+ *
+ * @example
+ * [SCENARIO 1] where `lazy: true` could be benefical
+ * ```typescript
+ * CmpUtils.onAnyCmpValueChanged(() => {
+ *   const useBigData = CmpSimpleBool.getValue();
+ *   if(useBigData) {
+ *     // only now the data will be retrieved from the server
+ *     const bigData = await CmpBigData.getValue();
+ *   }
+ *
+ * }, [CmpBigData, CmpSimpleBool, CmpSimpleText], true);
+ * ```
+ *
+ * [SCENARIO 2] where `lazy: false` could be benefical
+ * ```typescript
+ * CmpUtils.onAnyCmpValueChanged(() => {
+ *   // The data for both values has been fetched in the background, so no further server request is necessary
+ *   const bigData1 = await CmpBigData1.getValue();
+ *   const bigData2 = await CmpBigData2.getValue();
+ * }, [CmpBigData1, CmpBigData2]);
+ * ```
+ */
+export declare const onAnyCmpValueChanged: <TInput extends ValueComponent>(listener: CmpValuesChangedListener<TInput["name"]>, components: TInput[], lazy?: boolean) => Promise<void>;
 
 declare type OnClickCallback = () => void;
 
@@ -180,7 +277,144 @@ export declare class Panel {
     setVisible(visible: boolean): Promise<void>;
 }
 
-export declare type ShopifyCheckoutJson = {
+export declare type ParentPageCheckoutData = {
+    /** Cfgn id */
+    id: string;
+    /** Contains the value of the `data` passed to Hive's `OnFinish.CheckoutLegacy(data, key)` as stringified JSON */
+    checkoutParameters: string;
+    /** SHA256 hash of `checkoutParameters` built with the secret `key` passed to `OnFinish.CheckoutLegacy(data, key)` */
+    checkoutParametersHash: string;
+    /** Contains all query parameters which are added to the current cfgr URL */
+    queryParameters: {
+        [key: string]: string;
+    };
+    /** Cfgn auth token */
+    authentication: string;
+};
+
+declare type ParentPageComErrorPayload<T> = [T] extends [void] ? {} : {
+    [K in keyof T]: undefined;
+};
+
+/**
+ * Given `T` must be an object and all its properties are directly spread into the resulting object.
+ *
+ * @example
+ * ```ts
+ * ParentPageComResult<void>
+ * // -> { success: true; } | { success: false; error: Error };
+ *
+ * ParentPageComResult<{ url: string }>
+ * // -> { success: true; url: string; } | { success: false; error: Error; url: undefined; };
+ *
+ * // Not allowed:
+ * ParentPageComResult<number> // `number` is not an object
+ * ParentPageComResult<string[]> // `string[]` is not an object
+ * ParentPageComResult<{ success: string }> // Property `success` is not allowed
+ * ParentPageComResult<{ error: string, name: string }> // Property `error` is not allowed
+ * ```
+ */
+declare type ParentPageComResult<T extends Record<string, unknown> | void> = ({
+    success: true;
+    error: undefined;
+} & ([T] extends [void] ? {} : T)) | ({
+    success: false;
+    error: Error;
+} & ParentPageComErrorPayload<T>);
+
+export declare type ProductCustomFields = {
+    /**
+     * Unique identifier
+     */
+    id: string;
+    /**
+     * Label which the user will also see in the cart (if it is visible)
+     */
+    label: string;
+    /**
+     * Value of the custom field
+     */
+    value: string;
+    /**
+     * Position in the cart
+     */
+    position: number;
+    /**
+     * If it should be visible in the cart
+     */
+    isVisible: boolean;
+};
+
+/**
+ * Sets `window.location.href` to the given `url` on the parent page.
+ *
+ * Requires the Configurator plugin to be installed correctly on the parent page.\
+ * See embedding instructions for details.
+ */
+export declare const redirectParentPage: (url: string) => Promise<ParentPageComResult<void>>;
+
+/**
+ * Send a custom message to the parent page via the "CustomMessage".\
+ * The parent page can handle those messages by implementing the function `Combeenation.on{msgName}`.
+ *
+ * Requires the Configurator plugin to be installed correctly on the parent page.\
+ * See embedding instructions for details.
+ */
+export declare const sendCustomMsgToParentPage: (msgName: string, data?: object) => Promise<ParentPageComResult<void>>;
+
+/** A JSON-serializable value safe to use as a `postMessage` payload etc. */
+declare type SerializableJsonValue = JsonPrimitive | JsonObject | JsonArray;
+
+/**
+ * Changes the width and/or height of the IFrame and/or scroll position of the parent page window.
+ *
+ * Requires the Configurator plugin to be installed correctly on the parent page.\
+ * See embedding instructions for details.
+ *
+ * @param width     If not given or 0, the width is not changed
+ * @param height    If not given or 0, the height is not changed
+ * @param scrollToX New horizontal scroll position of the parent page window
+ * @param scrollToY New vertical scroll position of the parent page window
+ */
+export declare const setConfiguratorIFrameSize: (data: {
+    width?: string;
+    height?: string;
+    scrollToX?: number;
+    scrollToY?: number;
+}) => Promise<ParentPageComResult<void>>;
+
+/**
+ * Creates a copy of the current configuration and opens a share window for the given platform with the resulting share
+ * URL
+ */
+export declare const shareConfiguration: (data: {
+    /** If `Custom`, no share window will be opened */
+    platform: "Facebook" | "Pinterest" | "Twitter" | "LinkedIn" | "WhatsApp" | "Custom" | "NativeShare";
+    ogTitle?: string;
+    ogAuthor?: string;
+    ogDescription?: string;
+    /**
+     * URL to an image which will be used as share preview image when supported by the platform.
+     *
+     * It's recommended to use the URL of a file uploaded via upload tooling of the configurator.
+     */
+    imageUrl?: string;
+    /**
+     * URL of the parent page where the configurator is embedded.
+     *
+     * Will be integrated into the resulting share URL, so that the share redirects to the parent page, not the standalone
+     * configurator.
+     */
+    embedUrl?: string;
+}) => Promise<{
+    /**
+     * Url which is enhanced for sharing on social media by providing required "Open Graph" tags.
+     */
+    shareUrl: string;
+    shareConfigurationId: string;
+}>;
+
+export declare type ShopifyFinishJson = {
     products: {
         main: {
             /**
@@ -204,7 +438,7 @@ export declare type ShopifyCheckoutJson = {
              * New description of your product
              */
             productText?: string;
-            customFields?: CheckoutProductCustomFields[];
+            customFields?: ProductCustomFields[];
             /**
              * Weight of the main product
              */
@@ -229,7 +463,7 @@ export declare type ShopifyCheckoutJson = {
     }[];
 };
 
-export declare type Shopware6CheckoutJson = {
+export declare type Shopware6FinishJson = {
     products: {
         main: {
             /**
@@ -253,7 +487,7 @@ export declare type Shopware6CheckoutJson = {
              * New description of your product
              */
             productText?: string;
-            customFields?: CheckoutProductCustomFields[];
+            customFields?: ProductCustomFields[];
         };
         /**
          * Additional predefined Shopware products which will be added to the cart (no custom price/image/title)
@@ -306,39 +540,10 @@ export declare class ValueComponent<TName extends CmpName = CmpName, TValue exte
     onValueChanged(listener: CmpValueChangedListener<TValue>, callImmediately?: boolean, condition?: CmpValueChangedCondition<TValue>): void;
 }
 
-/**
- * Represents a component of type `Value`
- */
-declare class ValueComponent_2<TName extends CmpName_2 = CmpName_2, TValue extends CmpValue_2 = CmpValue_2, TInput extends CmpValue_2 = TValue> {
-    readonly name: TName;
-    readonly zodType: z.ZodType<CmpValue_2>;
-    constructor(name: TName, zodType: z.ZodType<CmpValue_2>);
-    /**
-     * Function for receiving the value of a component.
-     */
-    getValue(): Promise<TValue | undefined>;
-    /**
-     * Sends the ChangeConfigurationValue request to the server
-     */
-    setInput(value: TInput | undefined): Promise<void>;
-    /**
-     * @param listener        Called whenever the value of the given cmp has changed
-     * @param callImmediately `True:` The listener is immediately called with the current value of the cmp at the
-     *                        time, the listener is added\
-     *                        `False:` The listener will be called for the first time when the value of the cmp
-     *                        actually changes
-     * @param condition       A predicate function which is given the new cmp value.\
-     *                        The function can decide on whether the listener is called or not by returning true or false.
-     */
-    onValueChanged(listener: CmpValueChangedListener_2<TValue>, callImmediately?: boolean, condition?: CmpValueChangedCondition_2<TValue>): void;
-}
-
-export declare const version = "@VERSION@";
+export declare const version: string;
 
 declare const ZCmpValue: z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, "many">, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>, z.ZodUnknown]>;
 
-declare const ZCmpValue_2: z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, "many">, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>, z.ZodUnknown]>;
-
 declare const ZCtrlId: z.ZodString;
 
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combeenation/custom-code-sdk",
-  "version": "0.0.1-alpha6",
+  "version": "0.0.1-alpha7",
   "description": "Combeenation custom code SDK package",
   "keywords": [],
   "homepage": "",
@@ -13,10 +13,9 @@
     "dist"
   ],
   "scripts": {
-    "build": "npm run build:be-lib-types && npm run lint && vite build",
-    "build:be-lib-types": "npm run build:types --workspace=@repo/be-lib",
+    "build": "npm run build:dependency-types && npm run lint && vite build",
     "build:clean": "npm install && rimraf dist && npm run build",
-    "dev": "vite build --watch",
+    "build:dependency-types": "npm run build:types --workspace=@repo/std-lib && npm run build:types --workspace=@repo/be-lib && npm run build:types --workspace=@combeenation/configurator-client",
     "lint": "eslint src/**/*.ts*",
     "pack": "npm run build:clean && npm pack",
     "pub:alpha": "npm run build:clean && npm publish --tag alpha",