@myparcel-dev/pdk-admin 1.13.0

package/src/services/createNotification.ts

@@ -0,0 +1,35 @@
+import {type Variant} from '@myparcel-dev/pdk-common';
+import {type PdkNotification} from '../types';
+import {NotificationCategory} from '../data';
+import {useLanguage} from '../composables';
+
+const PREFIX = 'notification_';
+
+export const createNotification = (
+  variant: Variant,
+  options?: Partial<PdkNotification> & {identifier?: string},
+): undefined | PdkNotification => {
+  const language = useLanguage();
+  const {identifier, ...rest} = options ?? {};
+
+  const notification: PdkNotification = {
+    timeout: true,
+    variant,
+    ...rest,
+  };
+
+  if (options?.content || options?.title) {
+    return notification;
+  }
+
+  const title = `${PREFIX}${identifier ?? options?.category ?? NotificationCategory.General}_${variant}`;
+  const contentKey = `${title}_body`;
+
+  const content = language.has(contentKey) ? language.translate(contentKey) : undefined;
+
+  if (!language.has(title) && !content) {
+    return undefined;
+  }
+
+  return {...notification, title, content};
+};

package/src/services/index.ts

@@ -0,0 +1,9 @@
+export * from './actions';
+export * from './addErrorToNotifications';
+export * from './context';
+export * from './createNotification';
+export * from './instantiateAction';
+export * from './instantiateActions';
+export * from './logger';
+export * from './mutations';
+export * from './print';

package/src/services/instantiateAction.ts

@@ -0,0 +1,11 @@
+import {type ActionDefinition, type ActionParameters, type AnyActionDefinition, type MaybeAdminAction} from '../types';
+import {getActionIdentifier} from './actions';
+
+export const instantiateAction = <A extends MaybeAdminAction>(
+  action: AnyActionDefinition<A>,
+  parameters?: ActionParameters<A>,
+): ActionDefinition<A> => ({
+  ...action,
+  id: getActionIdentifier(action),
+  parameters,
+});

package/src/services/instantiateActions.ts

@@ -0,0 +1,14 @@
+import {toArray} from '@myparcel-dev/ts-utils';
+import {type ActionDefinition, type ActionParameters, type AnyActionDefinition} from '../types';
+import {type AdminAction} from '../data';
+import {instantiateAction} from './instantiateAction';
+
+type InstantiateActions = {
+  (action: AnyActionDefinition, parameters?: ActionParameters<AdminAction>): ActionDefinition[];
+  // eslint-disable-next-line @typescript-eslint/unified-signatures
+  (actions: AnyActionDefinition[], parameters?: ActionParameters<AdminAction>): ActionDefinition[];
+};
+
+export const instantiateActions: InstantiateActions = (actions, parameters) => {
+  return toArray(actions).map((action) => instantiateAction(action, parameters));
+};

package/src/services/logger.spec.ts

@@ -0,0 +1,70 @@
+import {afterAll, afterEach, describe, expect, it, vi} from 'vitest';
+import {createLogger, globalLogger, LogLevel, type PdkLogger} from './logger';
+
+type ExtractRecord<T extends Record<any, any>, U> = {
+  [P in keyof T]: T[P] extends U ? P : never;
+};
+
+type ExtractRecordKeys<T extends Record<any, any>, U> = ExtractRecord<T, U>[keyof T];
+
+type PdkLoggerMethod = ExtractRecordKeys<PdkLogger, (...args: any[]) => void>;
+
+describe('logger', () => {
+  const spies = {
+    log: vi.spyOn(console, 'log'),
+    warn: vi.spyOn(console, 'warn'),
+    error: vi.spyOn(console, 'error'),
+  };
+
+  const logMethodsMap = [
+    ['debug', 'log'],
+    ['info', 'log'],
+    ['warn', 'warn'],
+    ['error', 'error'],
+  ] as [PdkLoggerMethod, keyof typeof spies][];
+
+  afterEach(() => {
+    Object.values(spies).forEach((spy) => spy.mockReset());
+  });
+
+  afterAll(() => {
+    Object.values(spies).forEach((spy) => spy.mockRestore());
+  });
+
+  describe('global', () => {
+    it.each(logMethodsMap)('can use %s', (method, consoleMethod) => {
+      globalLogger[method]('test');
+
+      expect(spies[consoleMethod]).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('scoped', () => {
+    it.each(logMethodsMap)('can use %s', (method, consoleMethod) => {
+      const logger = createLogger('test');
+
+      logger[method]('test');
+
+      expect(spies[consoleMethod]).toHaveBeenCalledTimes(1);
+    });
+
+    it.each([
+      {logLevel: LogLevel.Off, logs: 0, warns: 0, errors: 0},
+      {logLevel: LogLevel.Error, logs: 0, warns: 0, errors: 1},
+      {logLevel: LogLevel.Warn, logs: 0, warns: 1, errors: 1},
+      {logLevel: LogLevel.Info, logs: 1, warns: 1, errors: 1},
+      {logLevel: LogLevel.Debug, logs: 2, warns: 1, errors: 1},
+    ])('honors log level $logLevel', ({logLevel, logs, warns, errors}) => {
+      const logger = createLogger('test', logLevel);
+
+      logger.debug('debug');
+      logger.info('info');
+      logger.warn('warn');
+      logger.error('error');
+
+      expect(spies.log).toHaveBeenCalledTimes(logs);
+      expect(spies.warn).toHaveBeenCalledTimes(warns);
+      expect(spies.error).toHaveBeenCalledTimes(errors);
+    });
+  });
+});

package/src/services/logger.ts

@@ -0,0 +1,118 @@
+/* eslint-disable @typescript-eslint/no-explicit-any,no-console */
+
+export enum LogLevel {
+  Debug = 1,
+  Info = 2,
+  Warn = 3,
+  Error = 4,
+  Off = 5,
+}
+
+const logLevelNameMap: Partial<Record<LogLevel, string>> = {
+  [LogLevel.Error]: 'error',
+  [LogLevel.Warn]: 'warn',
+  [LogLevel.Info]: 'info',
+  [LogLevel.Debug]: 'debug',
+};
+
+const backgroundColors: Partial<Record<LogLevel, string>> = {
+  [LogLevel.Debug]: '#9E9E9E',
+  [LogLevel.Info]: '#2196F3',
+  [LogLevel.Warn]: '#FFB562',
+  [LogLevel.Error]: '#F87474',
+};
+
+export interface PdkLogger {
+  level: LogLevel;
+  scope: string | null;
+
+  debug(...messages: any[]): void;
+
+  error(...messages: any[]): void;
+
+  info(...messages: any[]): void;
+
+  log(level: LogLevel, ...messages: any[]): void;
+
+  setScope(scope: string | null): void;
+
+  warn(...messages: any[]): void;
+}
+
+export const globalLogger: PdkLogger = {
+  level: LogLevel.Debug,
+
+  scope: null,
+
+  log(level: LogLevel, ...messages: any[]): void {
+    if (level < this.level) {
+      return;
+    }
+
+    const scope = this.scope ?? 'PDK';
+
+    if (process.env.NODE_ENV === 'production') {
+      console.log(`[${scope}] ${level}`, ...messages);
+    } else {
+      const background = this.scope ? '#002621' : '#0F5C47';
+      const levelName = logLevelNameMap[level];
+      let method;
+
+      // define console method based on level
+      switch (level) {
+        case LogLevel.Error:
+          method = console.error;
+          break;
+
+        case LogLevel.Warn:
+          method = console.warn;
+          break;
+
+        default:
+          method = console.log;
+      }
+
+      method(
+        ...[
+          `%c${scope}%c${levelName?.toUpperCase()}`,
+          [`background: ${background}`, 'border-radius: 3px 0 0 3px', 'padding: 2px 4px', 'color: #ccc'].join(';'),
+          [
+            `background: ${backgroundColors[level]}`,
+            'border-radius: 0 3px 3px 0',
+            'padding: 2px 4px',
+            'color: #222',
+          ].join(';'),
+          ...messages,
+        ],
+      );
+    }
+  },
+
+  debug(...messages: any[]): void {
+    this.log(LogLevel.Debug, ...messages);
+  },
+
+  info(...messages: any[]): void {
+    this.log(LogLevel.Info, ...messages);
+  },
+
+  warn(...messages: any[]): void {
+    this.log(LogLevel.Warn, ...messages);
+  },
+
+  error(...messages: any[]): void {
+    this.log(LogLevel.Error, ...messages);
+  },
+
+  setScope(scope: string | null): void {
+    this.scope = scope;
+  },
+};
+
+export const createLogger = (scope: string | null = null, logLevel: LogLevel | null = null): PdkLogger => {
+  const loggerInstance = {...globalLogger};
+  loggerInstance.setScope(scope);
+  loggerInstance.level = logLevel ?? globalLogger.level;
+
+  return loggerInstance;
+};

package/src/services/mutations/getCallbackForMutationMode.ts

@@ -0,0 +1,18 @@
+import {useModalStore, useNotificationStore} from '../../stores';
+import {NotificationCategory} from '../../data';
+import {MutationMode} from './mutationMode';
+
+type Callback = (() => void) | undefined;
+
+export const getCallbackForMutationMode = (mode: MutationMode): Callback => {
+  switch (mode) {
+    case MutationMode.Modal:
+      return () => {
+        useModalStore().loading = true;
+        useNotificationStore().remove(NotificationCategory.Modal);
+      };
+
+    default:
+      return undefined;
+  }
+};

package/src/services/mutations/getModalMutationOptions.ts

@@ -0,0 +1,24 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import {type MutationOptions} from '@tanstack/vue-query';
+import {addErrorToNotifications} from '../addErrorToNotifications';
+import {useModalStore} from '../../stores';
+import {NotificationCategory} from '../../data';
+
+export const getModalMutationOptions = <
+  TData = unknown,
+  TError = unknown,
+  TVariables = void,
+  TContext = unknown,
+>(): MutationOptions<TData, TError, TVariables, TContext> => {
+  return {
+    onSuccess() {
+      useModalStore().close();
+    },
+    onSettled() {
+      useModalStore().loading = false;
+    },
+    onError(error) {
+      addErrorToNotifications(error, NotificationCategory.Modal);
+    },
+  };
+};

package/src/services/mutations/index.ts

@@ -0,0 +1,3 @@
+export * from './getCallbackForMutationMode';
+export * from './getModalMutationOptions';
+export * from './mutationMode';

package/src/services/mutations/mutationMode.ts

@@ -0,0 +1,4 @@
+export enum MutationMode {
+  Modal = 'modal',
+  Default = 'default',
+}

package/src/services/print/index.ts

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

package/src/services/print/openPdfInNewWindow.ts

@@ -0,0 +1,11 @@
+import {openUrlInNewTab} from '../../utils';
+
+/**
+ * Opens a new window with the given base64 encoded pdf.
+ */
+export const openPdfInNewWindow = async (pdf: string): Promise<void> => {
+  const blob = await (await fetch(`data:application/pdf;base64,${pdf}`)).blob();
+  const url = URL.createObjectURL(blob);
+
+  openUrlInNewTab(url);
+};

package/src/stores/createQueryCacheKey.ts

@@ -0,0 +1,6 @@
+import {type BackendEndpoint} from '@myparcel-dev/pdk-common';
+import {type PlainModifier} from '../actions';
+
+export const createQueryCacheKey = <E extends BackendEndpoint>(endpoint: E, modifier?: PlainModifier): string => {
+  return modifier ? `${endpoint}.${modifier}` : endpoint;
+};

package/src/stores/index.ts

@@ -0,0 +1,6 @@
+export * from './createQueryCacheKey';
+export * from './types';
+export * from './useActionStore';
+export * from './useModalStore';
+export * from './useNotificationStore';
+export * from './useQueryStore';

package/src/stores/types.ts

@@ -0,0 +1,35 @@
+import {type UseMutationReturnType, type UseQueryReturnType} from '@tanstack/vue-query';
+import {type AdminContextKey, type BackendEndpoint} from '@myparcel-dev/pdk-common';
+import {type ApiException} from '@myparcel-dev/sdk';
+import {
+  type ActionInput,
+  type AdminContext,
+  type BackendEndpointResponse,
+  type BackendMutationEndpoints,
+  type BackendQueryEndpoints,
+} from '../types';
+import {type QueryModifier} from '../actions';
+
+type EndpointQuery<E extends BackendEndpoint> = E extends BackendMutationEndpoints
+  ? UseMutationReturnType<BackendEndpointResponse<E>, ApiException, ActionInput<E>, unknown>
+  : E extends BackendQueryEndpoints
+  ? UseQueryReturnType<BackendEndpointResponse<E>, ApiException>
+  : never;
+
+export type ContextQuery<C extends AdminContextKey = AdminContextKey.Dynamic> = UseQueryReturnType<
+  AdminContext<C>,
+  ApiException
+>;
+
+export type ResolvedQuery<E extends BackendEndpoint = BackendEndpoint> = E extends BackendEndpoint
+  ? EndpointQuery<E>
+  : never;
+
+export type RegisterQuery = {
+  <E extends BackendEndpoint, Q extends ResolvedQuery<E> = ResolvedQuery<E>>(endpoint: E, query: Q, arg3?: never): Q;
+  <E extends BackendEndpoint, Q extends ResolvedQuery<E> = ResolvedQuery<E>>(
+    endpoint: E,
+    modifier: QueryModifier<E>,
+    query: Q,
+  ): Q;
+};

package/src/stores/useActionStore.ts

@@ -0,0 +1,94 @@
+import {ref} from 'vue';
+import {defineStore} from 'pinia';
+import {type OneOrMore, type PromiseOr, toArray} from '@myparcel-dev/ts-utils';
+import {type ActionParameters, type AnyActionDefinition, type ResolvedAction} from '../types';
+import {createAction, getActionIdentifier} from '../services';
+import {type AdminAction} from '../data';
+import {usePluginSettings} from '../composables';
+import {
+  modalCloseAction,
+  modalSubmitFormAction,
+  orderExportAction,
+  orderExportToShipmentsAction,
+  ordersEditAction,
+  ordersExportPrintShipmentsAction,
+  ordersFetchAction,
+  ordersPrintAction,
+  ordersUpdateAction,
+  orderViewInBackofficeAction,
+  shipmentsDeleteAction,
+  shipmentsExportReturnAction,
+  shipmentsPrintAction,
+  shipmentsUpdateAction,
+  webhooksCreateAction,
+  webhooksDeleteAction,
+  webhooksFetchAction,
+} from '../actions';
+
+// eslint-disable-next-line max-lines-per-function
+export const useActionStore = defineStore('actions', () => {
+  const actions = ref<ResolvedAction[]>([]);
+
+  const register = (action: OneOrMore<AnyActionDefinition>) => {
+    toArray(action)
+      .filter((action) => !get(getActionIdentifier(action)))
+      .forEach((action) => {
+        const resolvedAction = createAction(action);
+
+        // @ts-expect-error todo
+        actions.value.push(resolvedAction);
+      });
+  };
+
+  const get = (action: string | AdminAction): ResolvedAction | undefined => {
+    return actions.value.find((a) => a.id === action);
+  };
+
+  const dispatch = <A extends string | AdminAction>(action: A, parameters?: ActionParameters<A>): PromiseOr<void> => {
+    const resolvedAction = get(action);
+
+    if (!resolvedAction) {
+      throw new Error(`Action ${action} is not registered.`);
+    }
+
+    return resolvedAction.handler(parameters) as PromiseOr<void>;
+  };
+
+  return {
+    get,
+
+    register,
+
+    dispatch,
+
+    registerOrderActions: () => {
+      const pluginSettings = usePluginSettings();
+
+      register([
+        ordersEditAction,
+        ordersFetchAction,
+        ordersPrintAction,
+        ordersUpdateAction,
+        ...(pluginSettings.order.orderMode
+          ? [orderExportAction, orderViewInBackofficeAction]
+          : [
+              orderExportToShipmentsAction,
+              ordersExportPrintShipmentsAction,
+              shipmentsExportReturnAction,
+              shipmentsExportReturnAction,
+              shipmentsDeleteAction,
+              shipmentsUpdateAction,
+              shipmentsPrintAction,
+            ]),
+      ]);
+    },
+
+    registerModalActions: () => {
+      register([modalCloseAction, modalSubmitFormAction]);
+    },
+
+    registerWebhookActions: () => {
+      register([webhooksCreateAction, webhooksDeleteAction, webhooksFetchAction]);
+    },
+  };
+});

package/src/stores/useModalStore.ts

@@ -0,0 +1,65 @@
+import {ref, type Ref, type UnwrapNestedRefs} from 'vue';
+import {defineStore} from 'pinia';
+import {type AdminModalContext} from '../types';
+import {type AdminModalKey, NotificationCategory} from '../data';
+import {useLoading} from '../composables';
+import {useNotificationStore} from './useNotificationStore';
+
+type ModalOpenFn = <K extends AdminModalKey>(modal: K, context?: AdminModalContext<K>) => void;
+
+type ModalCloseFn = <K extends AdminModalKey>(modal: K) => void;
+
+type ModalStore = {
+  loading: Ref<boolean>;
+  opened: Ref<AdminModalKey | null>;
+  context: Ref<UnwrapNestedRefs<AdminModalContext>>;
+  onOpen(callback: ModalOpenFn): void;
+  onClose(callback: ModalCloseFn): void;
+  open<K extends AdminModalKey>(modal: K, newContext?: AdminModalContext<K>): void;
+  close(): void;
+};
+
+export const useModalStore = defineStore('modal', (): ModalStore => {
+  const {loading} = useLoading();
+
+  const opened = ref<AdminModalKey | null>(null);
+  const context = ref<AdminModalContext>(null);
+
+  const openHooks = ref<ModalOpenFn[]>([]);
+  const closeHooks = ref<ModalCloseFn[]>([]);
+
+  return {
+    loading,
+
+    opened,
+
+    context,
+
+    onOpen(callback) {
+      openHooks.value.push(callback);
+    },
+
+    onClose(callback) {
+      closeHooks.value.push(callback);
+    },
+
+    open(modal, newContext) {
+      // TODO: fix excessive depth error
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      context.value = newContext;
+      opened.value = modal;
+
+      openHooks.value.forEach((hook) => hook(modal, newContext));
+    },
+
+    close() {
+      useNotificationStore().remove(NotificationCategory.Modal);
+      const modal = opened.value as AdminModalKey;
+
+      opened.value = null;
+      context.value = null;
+      closeHooks.value.forEach((hook) => hook(modal));
+    },
+  };
+});

package/src/stores/useNotificationStore.ts

@@ -0,0 +1,65 @@
+import {ref} from 'vue';
+import {defineStore} from 'pinia';
+import {isEnumValue} from '@myparcel-dev/ts-utils';
+import {type NotificationId, type PdkNotification, type ResolvedNotification} from '../types';
+import {NotificationSource} from '../data';
+
+let autoId = 0;
+
+const DEFAULT_TIMEOUT = 5000;
+
+export const useNotificationStore = defineStore('notifications', () => {
+  const notifications = ref<ResolvedNotification[]>([]);
+
+  return {
+    notifications,
+
+    /**
+     * Add a notification to the store.
+     */
+    add(notification: PdkNotification, tags?: object | Record<string, string>) {
+      const resolvedNotification: ResolvedNotification = {
+        timeout: true,
+        dismissible: notification.timeout === false,
+        id: notification.id ?? autoId++,
+        ...notification,
+        tags: {
+          ...notification.tags,
+          ...tags,
+        },
+      };
+
+      const {id} = resolvedNotification;
+
+      if (notifications.value.some((notification) => notification.id === id)) {
+        return;
+      }
+
+      if (notification.timeout !== false) {
+        const timeout =
+          typeof resolvedNotification.timeout === 'number' ? resolvedNotification.timeout : DEFAULT_TIMEOUT;
+
+        setTimeout(() => {
+          this.remove(id);
+        }, timeout);
+      }
+
+      notifications.value.push(resolvedNotification);
+    },
+
+    /**
+     * Remove one or more notifications from the store by tag or id.
+     */
+    remove(input: NotificationId | NotificationSource) {
+      let filter: (notification: ResolvedNotification) => boolean;
+
+      if (isEnumValue(input, NotificationSource)) {
+        filter = (notification) => notification.tags?.source === input;
+      } else {
+        filter = (notification) => notification.id !== input;
+      }
+
+      notifications.value = notifications.value.filter(filter);
+    },
+  };
+});