@myparcel-dev/pdk-admin 1.13.0

package/src/pdk/instance/plugins/createRegisterComponentsPlugin.ts

@@ -0,0 +1,87 @@
+import {type App, type Component, markRaw} from 'vue';
+import {mergeWith} from 'lodash-unified';
+import {type FormConfiguration, MyParcelFormBuilderPlugin} from '@myparcel-dev/vue-form-builder';
+import {prefixComponent, unprefixComponent} from '../../../utils';
+import {type AdminComponentMap, type PrefixedAdminComponent} from '../../../types';
+import {
+  AdminComponent,
+  optionalAdminActionContainerComponentNames,
+  optionalAdminComponentNames,
+  optionalAdminPlainWrapperComponentNames,
+  requiredAdminComponentNames,
+} from '../../../data';
+import {useLanguage} from '../../../composables';
+import {PlainElement} from '../../../components';
+import {type PdkAppPlugin} from './plugins.types';
+
+const getOptionalComponents = (app: App): Record<string, Component | AdminComponent> => {
+  const isNotRegistered = (component: PrefixedAdminComponent): boolean => app.component(component) === undefined;
+
+  const createComponentMap = (
+    componentNames: readonly AdminComponent[],
+    fallback: Component | AdminComponent,
+  ): Record<string, Component | AdminComponent> => {
+    return componentNames
+      .map(prefixComponent)
+      .filter(isNotRegistered)
+      .reduce((acc, componentName) => ({...acc, [componentName]: fallback}), {});
+  };
+
+  return {
+    ...createComponentMap(optionalAdminComponentNames, PlainElement),
+    ...createComponentMap(optionalAdminPlainWrapperComponentNames, PlainElement),
+    ...createComponentMap(optionalAdminActionContainerComponentNames, AdminComponent.Box),
+  };
+};
+
+/**
+ * Registers all replaceable vue components. They must all be provided, for tree shaking purposes.
+ */
+export const createRegisterComponentsPlugin: PdkAppPlugin = ({config, logger}) => {
+  return {
+    install(app) {
+      const componentsFromConfig: Required<AdminComponentMap> = Object.entries(config.components).reduce(
+        (acc, [name, component]) => ({
+          ...acc,
+          [unprefixComponent(name)]: component,
+        }),
+        {} as Required<AdminComponentMap>,
+      );
+
+      const requiredComponents = {
+        ...requiredAdminComponentNames.reduce((acc, name) => ({...acc, [name]: null}), {}),
+        ...componentsFromConfig,
+      };
+
+      Object.entries(requiredComponents).forEach(([componentName, component]) => {
+        if (!component) {
+          logger.error(
+            `Missing component: "${componentName}". You must provide your own, or use one provided by one of the @myparcel-dev/pdk-admin-preset-* packages.`,
+          );
+          return;
+        }
+
+        app.component(prefixComponent(componentName), markRaw(component));
+      });
+
+      Object.entries(getOptionalComponents(app)).forEach(([componentName, component]) => {
+        const componentToRegister = typeof component === 'string' ? componentsFromConfig[component] : component;
+
+        app.component(prefixComponent(componentName), markRaw(componentToRegister));
+      });
+
+      const {translate} = useLanguage();
+
+      const defaultConfig: Partial<FormConfiguration> = {
+        renderLabel: translate,
+        field: {
+          wrapper: componentsFromConfig[AdminComponent.FormGroup],
+        },
+      };
+
+      app.use(MyParcelFormBuilderPlugin, mergeWith(defaultConfig, config.formConfig));
+
+      logger.debug('Installed components plugin.');
+    },
+  };
+};

package/src/pdk/instance/plugins/createStorePlugin.ts

@@ -0,0 +1,23 @@
+import {createPinia, type Pinia} from 'pinia';
+import {type PdkAppPlugin} from './plugins.types';
+
+let store: Pinia;
+let initialized = false;
+
+export const createStorePlugin: PdkAppPlugin = ({config, logger}) => {
+  store ??= createPinia();
+
+  logger.debug('Preparing store plugin');
+
+  store.use((storeContext) => {
+    if (initialized || !config.onCreateStore) {
+      return;
+    }
+
+    initialized = true;
+    logger.debug('Calling store renderer hook');
+    config.onCreateStore(storeContext);
+  });
+
+  return store;
+};

package/src/pdk/instance/plugins/createVueQueryPlugin.ts

@@ -0,0 +1,48 @@
+import {type QueryClient, VueQueryPlugin} from '@tanstack/vue-query';
+import {AdminContextKey, BackendEndpoint} from '@myparcel-dev/pdk-common';
+import {createQueryClient} from '../createQueryClient';
+import {createInstanceContext} from '../createInstanceContext';
+import {fillShipmentsQueryData} from '../../fillShipmentsQueryData';
+import {type PdkAppPlugin} from './plugins.types';
+
+let queryClient: QueryClient;
+
+/**
+ * Instantiate vue query client if it does not exist yet and provide it to the app.
+ */
+export const createVueQueryPlugin: PdkAppPlugin = ({context, logger}) => {
+  return {
+    install: (app) => {
+      logger.debug('Installing vue-query plugin');
+
+      queryClient ??= createQueryClient();
+
+      // Fill the query client with the context data
+      Object.entries(context).forEach(([contextKey, value]) => {
+        if (!value) {
+          return;
+        }
+
+        queryClient.setQueryData([BackendEndpoint.FetchContext, contextKey], value);
+      });
+
+      const instanceContext = createInstanceContext(context);
+      queryClient.setQueryData([BackendEndpoint.FetchContext, AdminContextKey.Instance], instanceContext);
+
+      // Add each order and its shipments to the query client
+      if (context.orderData) {
+        context.orderData.forEach((order) => {
+          fillShipmentsQueryData(queryClient, order.shipments, order);
+        });
+      }
+
+      if (context.productData) {
+        context.productData.forEach((product) => {
+          queryClient.setQueryData([BackendEndpoint.FetchProducts, {id: product.externalIdentifier}], product);
+        });
+      }
+
+      app.use(VueQueryPlugin, {queryClient});
+    },
+  };
+};

package/src/pdk/instance/plugins/index.ts

@@ -0,0 +1,6 @@
+export * from './createContextPlugin';
+export * from './createLoggerPlugin';
+export * from './createRegisterComponentsPlugin';
+export * from './createStorePlugin';
+export * from './createVueQueryPlugin';
+export * from './plugins.types';

package/src/pdk/instance/plugins/plugins.types.ts

@@ -0,0 +1,4 @@
+import {type Plugin} from 'vue';
+import {type AdminAppConfig} from '../../../types';
+
+export type PdkAppPlugin = (appConfig: AdminAppConfig) => Plugin;

package/src/pdk/renderMap.ts

@@ -0,0 +1,27 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+import {type Component} from 'vue';
+import {type ComponentImportFunction} from '../types';
+import {AdminView} from '../data';
+
+/**
+ * Maps components to render methods.
+ */
+const renderMap = Object.freeze<Record<AdminView, ComponentImportFunction>>({
+  [AdminView.ChildProductSettings]: async () => import('../views/ChildProductSettings.vue'),
+  [AdminView.Modals]: async () => import('../views/Modals.vue'),
+  [AdminView.Notifications]: async () => import('../views/Notifications.vue'),
+  [AdminView.OrderBox]: async () => import('../views/OrderBox.vue'),
+  [AdminView.OrderListItem]: async () => import('../views/OrderListItem.vue'),
+  [AdminView.PluginSettings]: async () => import('../views/PluginSettings.vue'),
+  [AdminView.ProductSettings]: async () => import('../views/ProductSettings.vue'),
+});
+
+export const renderViewComponent = async (componentName: AdminView): Promise<Component> => {
+  const renderMethod = renderMap[componentName];
+
+  if (!renderMethod) {
+    throw new Error(`No render method found for component "${componentName}"`);
+  }
+
+  return (await renderMethod()).default;
+};

package/src/pdk/sendBootEvent.ts

@@ -0,0 +1,12 @@
+import {type AdminContextObject} from '../types';
+import {type PdkAdmin} from './PdkAdmin';
+
+export const sendBootEvent = (pdkAdmin: PdkAdmin, context: AdminContextObject): void => {
+  const globalContext = context.global;
+
+  if (!globalContext) {
+    throw new Error('Global context not found');
+  }
+
+  document.dispatchEvent(new CustomEvent(globalContext.eventPong, {detail: pdkAdmin}));
+};

package/src/pdk/setupAdminApp.ts

@@ -0,0 +1,20 @@
+import {type App} from 'vue';
+import {type AdminAppConfig} from '../types';
+import {testIdDirective} from './testIdDirective';
+import {
+  createContextPlugin,
+  createLoggerPlugin,
+  createRegisterComponentsPlugin,
+  createStorePlugin,
+  createVueQueryPlugin,
+} from './instance';
+
+export const setupAdminApp = (app: App<Element>, appConfig: AdminAppConfig): void => {
+  app.use(createStorePlugin(appConfig));
+  app.use(createVueQueryPlugin(appConfig));
+  app.use(createContextPlugin(appConfig));
+  app.use(createRegisterComponentsPlugin(appConfig));
+  app.use(createLoggerPlugin(appConfig));
+
+  app.directive('test', testIdDirective);
+};

package/src/pdk/testIdDirective.spec.ts

@@ -0,0 +1,42 @@
+import {describe, expect, it} from 'vitest';
+import {shallowMount} from '@vue/test-utils';
+import {testIdDirective} from './testIdDirective';
+
+/**
+ * @vitest-environment happy-dom
+ */
+
+const mountWrapper = (template: string) => {
+  return shallowMount(
+    {
+      template,
+    },
+    {global: {directives: {test: testIdDirective}}},
+  );
+};
+
+describe('testIdDirective', () => {
+  it('handles plain string', () => {
+    const wrapper = mountWrapper(`<div v-test="'test'"></div>`);
+
+    expect(wrapper.find('div').attributes('data-test-id')).toBe('test');
+  });
+
+  it('handles string array', () => {
+    const wrapper = mountWrapper(`<div v-test="['test', 'test2']"></div>`);
+
+    expect(wrapper.find('div').attributes('data-test-id')).toBe('test--test2');
+  });
+
+  it('handles string + element', () => {
+    const wrapper = mountWrapper(`<div v-test="['test', {name: 'test2'}]"></div>`);
+
+    expect(wrapper.find('div').attributes('data-test-id')).toBe('test--test2');
+  });
+
+  it('handles undefined', () => {
+    const wrapper = mountWrapper(`<div v-test="['test', undefined]"></div>`);
+
+    expect(wrapper.find('div').attributes('data-test-id')).toBe('test');
+  });
+});

package/src/pdk/testIdDirective.ts

@@ -0,0 +1,28 @@
+import {type Directive} from 'vue';
+import {isDefined} from '@vueuse/core';
+import {type FieldInstance} from '@myparcel-dev/vue-form-builder';
+
+const SEPARATOR = '--';
+
+type TestIdBinding = string | string[] | [string, FieldInstance];
+
+export const testIdDirective: Directive<Element, TestIdBinding> = (el, binding) => {
+  if (import.meta.env.MODE !== 'test') {
+    return;
+  }
+
+  let testId: string;
+
+  if (Array.isArray(binding.value)) {
+    const filtered = binding.value.filter(isDefined);
+
+    const bindings =
+      typeof filtered[1] === 'string' ? (filtered as string[]) : [filtered[0], filtered[1]?.name as string];
+
+    testId = bindings.filter(isDefined).join(SEPARATOR);
+  } else {
+    testId = binding.value;
+  }
+
+  el.setAttribute('data-test-id', testId);
+};

package/src/sdk/PdkFetchClient.ts

@@ -0,0 +1,70 @@
+import {isOfType} from '@myparcel-dev/ts-utils';
+import {
+  type AbstractEndpoint,
+  ApiException,
+  type EndpointResponse,
+  type EndpointResponseBody,
+  type EndpointResponseProperty,
+  type ErrorResponse,
+  FetchClient,
+  type Options,
+  type ResponseWrapper,
+} from '@myparcel-dev/sdk';
+import {type PdkNotification} from '../types';
+import {useNotificationStore} from '../stores';
+
+type EndpointResponseBodyWithNotifications = {
+  notifications: PdkNotification[];
+};
+
+type PdkEndpointResponseBody<E extends AbstractEndpoint> = EndpointResponseBody<E> &
+  EndpointResponseBodyWithNotifications;
+
+export class PdkFetchClient extends FetchClient {
+  /**
+   * Prepare and execute the final request and handle the response.
+   */
+  public async doRequest<E extends AbstractEndpoint>(endpoint: E, options: Options<E>): Promise<EndpointResponse<E>> {
+    const newOptions = this.normalizeOptions(endpoint, {...options, ...this.options});
+    this.validateHeaders(endpoint, newOptions);
+
+    const response = (await this.request(endpoint, newOptions)) as ResponseWrapper<PdkEndpointResponseBody<E>>;
+
+    if (isOfType<ErrorResponse>(response, 'errors')) {
+      if (isOfType<EndpointResponseBodyWithNotifications>(response, 'notifications')) {
+        const notificationStore = useNotificationStore();
+
+        response.notifications.forEach((notification) => {
+          notificationStore.add(notification);
+        });
+      }
+
+      throw new ApiException(response);
+    }
+
+    if (isOfType<ResponseWrapper>(response, 'data')) {
+      const property = endpoint.getResponseProperty() as EndpointResponseProperty<E>;
+
+      if (isOfType<EndpointResponseBodyWithNotifications>(response.data, 'notifications')) {
+        const notificationStore = useNotificationStore();
+
+        response.data.notifications.forEach((notification) => {
+          notificationStore.add(notification);
+        });
+      }
+
+      return response.data[property];
+    }
+
+    return response;
+  }
+
+  /**
+   * If the url already contains a query string, append the parameters with an ampersand instead.
+   */
+  protected createUrl<E extends AbstractEndpoint>(endpoint: E, options: Options<E>): string {
+    const url = super.createUrl(endpoint, options);
+
+    return url.replace(/\?([^?]*)(\?)/, '?$1&');
+  }
+}

package/src/sdk/composables/api/index.ts

@@ -0,0 +1 @@
+export * from './useFetchCarrier';

package/src/sdk/composables/api/useFetchCarrier.ts

@@ -0,0 +1,23 @@
+/* eslint-disable @typescript-eslint/explicit-module-boundary-types */
+import {useQuery, useQueryClient} from '@tanstack/vue-query';
+import {type EndpointResponse, type GetCarrier} from '@myparcel-dev/sdk';
+import {type CarrierName} from '@myparcel-dev/constants';
+import {useMyParcelApi} from '../useMyParcelApi';
+
+export const useFetchCarrier = (carrier?: CarrierName) => {
+  const queryClient = useQueryClient();
+  const queryKey = ['carriers', {name: carrier}] as const;
+
+  return useQuery<EndpointResponse<GetCarrier>[number]>(
+    queryKey,
+    async () => {
+      const sdk = useMyParcelApi();
+      const carriers = await sdk.getCarrier(carrier ? {path: {carrier}} : undefined);
+
+      return carriers[0];
+    },
+    {
+      ...queryClient.defaultQueryOptions(),
+    },
+  );
+};

package/src/sdk/composables/index.ts

@@ -0,0 +1,3 @@
+export * from './api';
+export * from './useMyParcelApi';
+export * from './usePdkAdminApi';

package/src/sdk/composables/useMyParcelApi.ts

@@ -0,0 +1,18 @@
+import {createMyParcelSdk, FetchClient, GetCarrier, GetCarriers, type MyParcelSdk} from '@myparcel-dev/sdk';
+
+let sdk: ReturnType<typeof useMyParcelApi>;
+
+/**
+ * @returns {MyParcelSdk<GetCarrier | GetCarriers>}
+ */
+export const useMyParcelApi = (): MyParcelSdk<GetCarrier | GetCarriers> => {
+  if (sdk) {
+    return sdk;
+  }
+
+  const client = new FetchClient();
+
+  sdk = createMyParcelSdk(client, [new GetCarriers(), new GetCarrier()]);
+
+  return sdk;
+};

package/src/sdk/composables/usePdkAdminApi.ts

@@ -0,0 +1,34 @@
+import {createGlobalState} from '@vueuse/core';
+import {type BackendEndpoint} from '@myparcel-dev/pdk-common';
+import {createMyParcelSdk, type HttpMethod, type MyParcelSdk} from '@myparcel-dev/sdk';
+import {AbstractPdkEndpoint} from '../endpoints';
+import {PdkFetchClient} from '../PdkFetchClient';
+import {useGlobalContext} from '../../composables';
+
+/**
+ * Do requests to the PDK admin Api.
+ */
+export const usePdkAdminApi = createGlobalState((): MyParcelSdk<AbstractPdkEndpoint> => {
+  const globalContext = useGlobalContext();
+
+  const client = new PdkFetchClient({
+    baseUrl: globalContext.baseUrl,
+  });
+
+  const pdkEndpoints = Object.entries(globalContext.endpoints).map(([endpointName, options]) => {
+    class PdkEndpoint extends AbstractPdkEndpoint {
+      public readonly method = options.method.toUpperCase() as HttpMethod;
+      public readonly name = endpointName as BackendEndpoint;
+      public readonly path = options.path;
+      public readonly property = options.property;
+      public readonly responseProperty = options.responseProperty ?? options.property;
+    }
+
+    return new PdkEndpoint({
+      headers: options.headers,
+      parameters: options.parameters,
+    });
+  });
+
+  return createMyParcelSdk(client, pdkEndpoints) as MyParcelSdk<AbstractPdkEndpoint>;
+});

package/src/sdk/endpoints/abstractPdkEndpoint.ts

@@ -0,0 +1,10 @@
+import {type BackendEndpoint, type ExtractEndpointDefinition} from '@myparcel-dev/pdk-common';
+import {AbstractEndpoint} from '@myparcel-dev/sdk';
+import {type BackendEndpointDefinition} from '../../types';
+
+export abstract class AbstractPdkEndpoint<N extends BackendEndpoint = BackendEndpoint> extends AbstractEndpoint<
+  ExtractEndpointDefinition<N, BackendEndpointDefinition>
+> {
+  public declare readonly name: N | `${N}}`;
+  public declare readonly path: string;
+}

package/src/sdk/endpoints/index.ts

@@ -0,0 +1 @@
+export * from './abstractPdkEndpoint';

package/src/sdk/index.ts

@@ -0,0 +1,3 @@
+export * from './PdkFetchClient';
+export * from './composables';
+export * from './endpoints';

package/src/services/actions/createAction.ts

@@ -0,0 +1,24 @@
+import {type ActionParameters, type AnyActionDefinition, type MaybeAdminAction, type ResolvedAction} from '../../types';
+import {type AdminAction} from '../../data';
+import {type ActionContext, executeAction} from '../../actions';
+import {getActionIdentifier} from './getActionIdentifier';
+import {createActionContext} from './createActionContext';
+
+type CreateAction = (action: AnyActionDefinition) => ResolvedAction;
+
+export const createAction: CreateAction = (action) => {
+  const context = createActionContext(action as AnyActionDefinition<AdminAction>);
+
+  return {
+    id: getActionIdentifier(action),
+    icon: action.icon,
+    label: action.label,
+    variant: action.variant,
+    disabled: action.disabled,
+    standalone: action.standalone,
+
+    handler: async <A extends MaybeAdminAction>(parameters: ActionParameters<A>) => {
+      await executeAction({...context, parameters} as ActionContext<A>);
+    },
+  };
+};

package/src/services/actions/createActionContext.ts

@@ -0,0 +1,49 @@
+import {Variant} from '@myparcel-dev/pdk-common';
+import {toArray} from '@myparcel-dev/ts-utils';
+import {createLogger} from '../logger';
+import {createNotification} from '../createNotification';
+import {
+  type ActionParameters,
+  type AdminInstance,
+  type AnyActionDefinition,
+  type MaybeAdminAction,
+  type PdkNotification,
+} from '../../types';
+import {NotificationCategory} from '../../data';
+import {useAdminInstance} from '../../composables';
+import {type ActionContext} from '../../actions';
+import {getActionIdentifier} from './getActionIdentifier';
+
+export const createActionContext = <A extends MaybeAdminAction>(
+  action: AnyActionDefinition<A>,
+  parameters?: ActionParameters<A>,
+  existingInstance?: AdminInstance,
+): ActionContext<A> => {
+  const identifier = getActionIdentifier(action);
+  const logger = createLogger(identifier);
+
+  return {
+    // @ts-expect-error todo
+    action,
+
+    // @ts-expect-error todo
+    parameters: parameters ?? {},
+
+    instance: {
+      ...(existingInstance ?? useAdminInstance()),
+      logger,
+    },
+
+    notifications: toArray(action.notifications ?? [Variant.Error]).reduce(
+      (acc, variant) => ({
+        ...acc,
+        [variant]: createNotification(variant, {
+          tags: {
+            action: identifier,
+          },
+        }),
+      }),
+      {} as Record<Variant, PdkNotification>,
+    ),
+  };
+};

package/src/services/actions/downloadFile.ts

@@ -0,0 +1,16 @@
+import {downloadFileFromUrl} from '../../utils';
+
+/**
+ * Try to get a file from an url. An error means the file is not ready yet. Retry until it is.
+ */
+export async function downloadFile(url: string, filename: string): Promise<void> {
+  try {
+    downloadFileFromUrl(url, filename);
+  } catch (e) {
+    await new Promise((resolve) => {
+      setTimeout(resolve, 100);
+    });
+
+    return downloadFile(url, filename);
+  }
+}

package/src/services/actions/getActionIdentifier.ts

@@ -0,0 +1,7 @@
+import {isOfType} from '@myparcel-dev/ts-utils';
+import {type AnyActionDefinition} from '../../types';
+import {type AdminAction} from '../../data';
+
+export const getActionIdentifier = (action: AnyActionDefinition): string => {
+  return isOfType<AnyActionDefinition<AdminAction>>(action, 'name') ? action.name : action.id;
+};

package/src/services/actions/index.ts

@@ -0,0 +1,4 @@
+export * from './createAction';
+export * from './createActionContext';
+export * from './downloadFile';
+export * from './getActionIdentifier';

package/src/services/addErrorToNotifications.ts

@@ -0,0 +1,35 @@
+import {Variant} from '@myparcel-dev/pdk-common';
+import {isOfType} from '@myparcel-dev/ts-utils';
+import {type ApiException} from '@myparcel-dev/sdk';
+import {type PdkNotification} from '../types';
+import {useNotificationStore} from '../stores';
+import {type NotificationCategory} from '../data';
+import {createNotification} from './createNotification';
+
+export const addErrorToNotifications = (
+  error: unknown,
+  category: NotificationCategory,
+  timeout: boolean | number = false,
+): void => {
+  const store = useNotificationStore();
+  const options: Partial<PdkNotification> = {category, timeout};
+
+  if (isOfType<Error>(error, 'message')) {
+    options.title = error.message;
+
+    options.content = error.stack;
+  }
+
+  // Override stacktrace if the error is an ApiException
+  if (isOfType<ApiException>(error, 'data')) {
+    options.content = error.data.errors.map((error) => `${error.title} (code: ${error.code})`);
+  }
+
+  const notification = createNotification(Variant.Error, options);
+
+  if (!notification) {
+    return;
+  }
+
+  store.add(notification);
+};

package/src/services/context/getElementContext.ts

@@ -0,0 +1,17 @@
+import {globalLogger} from '../logger';
+import {type AdminContextObject} from '../../types';
+
+export const getElementContext = (selector: string): AdminContextObject => {
+  const element = document.querySelector(selector);
+  const context = element?.getAttribute('data-pdk-context');
+  const parsedContext = context ? JSON.parse(context) : null;
+
+  if (parsedContext && Object.keys(parsedContext).length) {
+    globalLogger.debug(`Found context in ${selector}`, parsedContext);
+    element?.removeAttribute('data-pdk-context');
+    return parsedContext;
+  }
+
+  globalLogger.info(`No context found in ${selector}`);
+  return {} as AdminContextObject;
+};

package/src/services/context/index.ts

@@ -0,0 +1 @@
+export * from './getElementContext';