@myparcel-dev/pdk-admin 1.13.0

package/src/stores/useQueryStore.ts

@@ -0,0 +1,184 @@
+import {computed, type ComputedRef, type Ref, ref, toValue, unref} from 'vue';
+import {defineStore} from 'pinia';
+import {type MaybeRef} from '@vueuse/core';
+import {type QueryClient, useQueryClient} from '@tanstack/vue-query';
+import {AdminContextKey, BackendEndpoint} from '@myparcel-dev/pdk-common';
+import {type OneOrMore, toArray} from '@myparcel-dev/ts-utils';
+import {getOrderId, validateId} from '../utils';
+import {globalLogger, MutationMode} from '../services';
+import {AdminInstanceContextKey, BACKEND_ENDPOINTS_ORDERS, BACKEND_ENDPOINTS_SHIPMENTS} from '../data';
+import {useInstanceContext} from '../composables';
+import {
+  type PlainModifier,
+  QUERY_KEY_ORDER,
+  QUERY_KEY_SHIPMENT,
+  useCreateWebhooksMutation,
+  useDeleteShipmentsMutation,
+  useDeleteWebhooksMutation,
+  useExportOrdersMutation,
+  useExportReturnMutation,
+  useFetchContextQuery,
+  useFetchOrdersQuery,
+  useFetchProductsQuery,
+  useFetchShipmentsQuery,
+  useFetchWebhooksQuery,
+  usePrintOrdersMutation,
+  usePrintShipmentsMutation,
+  useUpdateOrdersMutation,
+  useUpdateShipmentsMutation,
+} from '../actions';
+import {type RegisterQuery, type ResolvedQuery} from './types';
+import {createQueryCacheKey} from './createQueryCacheKey';
+
+// eslint-disable-next-line max-lines-per-function
+export const useQueryStore = defineStore('query', () => {
+  const queries = ref({} as Record<string, ResolvedQuery>);
+  const queryClient: Ref<QueryClient | undefined> = ref<QueryClient>();
+
+  const has = <E extends BackendEndpoint>(endpoint: E, modifier?: PlainModifier): boolean => {
+    const key = createQueryCacheKey(endpoint, modifier);
+
+    return queries.value[key] !== undefined;
+  };
+
+  const get = <E extends BackendEndpoint>(endpoint: E, modifier?: PlainModifier): ResolvedQuery<E> => {
+    const key = createQueryCacheKey(endpoint, modifier);
+
+    if (!has(endpoint, modifier)) {
+      throw new Error(`No query found for key ${key}`);
+    }
+
+    // @ts-expect-error todo
+    return queries.value[key];
+  };
+
+  /**
+   * Queries must be registered manually, because vue-query hooks can only be
+   * called from a component's setup() function.
+   */
+  const register: RegisterQuery = (endpoint, arg2, arg3) => {
+    if (!queryClient.value) {
+      queryClient.value = useQueryClient();
+    }
+
+    const hasModifier = typeof arg2 === 'string' || typeof arg2 === 'number';
+
+    const modifier = hasModifier ? arg2 : undefined;
+    const query = hasModifier ? arg3 : arg2;
+
+    if (has(endpoint, modifier)) {
+      return get(endpoint, modifier);
+    }
+
+    const key = createQueryCacheKey(endpoint, modifier);
+
+    globalLogger.debug(`Registering query ${key}`);
+
+    // @ts-expect-error todo
+    queries.value[key] = query;
+
+    return query;
+  };
+
+  const registerShipmentQueries = (
+    shipmentIds: MaybeRef<OneOrMore<number>>,
+    orderIds?: MaybeRef<OneOrMore<string>>,
+  ): void => {
+    toArray(validateId(unref(orderIds) ?? getOrderId(), true)).forEach((orderId) => {
+      toArray(unref(shipmentIds)).forEach((shipmentId) => {
+        register(BackendEndpoint.FetchShipments, shipmentId, useFetchShipmentsQuery(orderId, shipmentId));
+        register(BackendEndpoint.DeleteShipments, shipmentId, useDeleteShipmentsMutation(orderId, shipmentId));
+        register(BackendEndpoint.PrintShipments, shipmentId, usePrintShipmentsMutation(orderId, shipmentId));
+        register(BackendEndpoint.UpdateShipments, shipmentId, useUpdateShipmentsMutation(orderId, shipmentId));
+        register(BackendEndpoint.ExportReturn, shipmentId, useExportReturnMutation(orderId, shipmentId));
+      });
+    });
+
+    register(BackendEndpoint.PrintShipments, usePrintShipmentsMutation());
+  };
+
+  const computedWatchers: Record<string, ComputedRef<Record<BackendEndpoint, ResolvedQuery>>> = {};
+
+  const getMatchingQueries = (
+    key: string,
+    id: number | string,
+    list: readonly BackendEndpoint[],
+  ): ComputedRef<Record<BackendEndpoint, ResolvedQuery>> => {
+    const identifier = `${key}-${id}`;
+
+    if (!computedWatchers[identifier]) {
+      computedWatchers[identifier] = computed(() => {
+        return list.reduce((acc, endpoint) => {
+          if (has(endpoint, id)) {
+            acc[endpoint] = get(endpoint, id);
+          }
+
+          return acc;
+        }, {} as Record<BackendEndpoint, ResolvedQuery>);
+      });
+    }
+
+    return computedWatchers[identifier];
+  };
+
+  return {
+    get,
+    has,
+    register,
+
+    registerShipmentQueries,
+
+    /**
+     * Register queries needed to render any order related component.
+     */
+    registerOrderQueries: (orderId?: string | undefined, mode: MutationMode = MutationMode.Default) => {
+      const id = validateId(orderId ?? getOrderId(), true);
+
+      toArray(id).forEach((orderId) => {
+        const ordersQuery = register(BackendEndpoint.FetchOrders, orderId, useFetchOrdersQuery(orderId));
+        toValue(ordersQuery.data)?.shipments?.forEach((shipment) => registerShipmentQueries(shipment.id, orderId));
+        register(BackendEndpoint.FetchOrders, orderId, useFetchOrdersQuery(orderId));
+        register(BackendEndpoint.ExportOrders, orderId, useExportOrdersMutation(orderId, mode));
+        register(BackendEndpoint.PrintOrders, orderId, usePrintOrdersMutation(orderId));
+        register(BackendEndpoint.UpdateOrders, orderId, useUpdateOrdersMutation(orderId));
+      });
+
+      register(BackendEndpoint.PrintOrders, usePrintOrdersMutation());
+    },
+
+    registerProductQueries: (productId?: string | undefined) => {
+      const id = validateId(productId ?? useInstanceContext(AdminInstanceContextKey.ProductIdentifier), true);
+
+      toArray(id).forEach((productId) => {
+        register(BackendEndpoint.FetchProducts, productId, useFetchProductsQuery(productId));
+      });
+    },
+
+    /**
+     * Register context queries. Always includes global and dynamic context.
+     */
+    registerContextQueries: <C extends Exclude<AdminContextKey, AdminContextKey.Global | AdminContextKey.Dynamic>>(
+      ...keys: C[]
+    ) => {
+      [AdminContextKey.Global, AdminContextKey.Dynamic, ...keys].forEach((key) => {
+        register(BackendEndpoint.FetchContext, key, useFetchContextQuery(key));
+      });
+    },
+
+    getQueriesForShipment(id: number): ComputedRef<Record<BackendEndpoint, ResolvedQuery>> {
+      return getMatchingQueries(QUERY_KEY_SHIPMENT, id, BACKEND_ENDPOINTS_SHIPMENTS);
+    },
+
+    getQueriesForOrder(externalIdentifier: string): ComputedRef<Record<BackendEndpoint, ResolvedQuery>> {
+      return getMatchingQueries(QUERY_KEY_ORDER, externalIdentifier, BACKEND_ENDPOINTS_ORDERS);
+    },
+
+    registerWebhookQueries: () => {
+      const fetchWebhooks = register(BackendEndpoint.FetchWebhooks, useFetchWebhooksQuery());
+      const createWebhooks = register(BackendEndpoint.CreateWebhooks, useCreateWebhooksMutation());
+      const deleteWebhooks = register(BackendEndpoint.DeleteWebhooks, useDeleteWebhooksMutation());
+
+      return {fetchWebhooks, createWebhooks, deleteWebhooks};
+    },
+  };
+});

package/src/symbols.ts

@@ -0,0 +1,7 @@
+import {type InjectionKey} from 'vue';
+import {type AdminInstance} from './types';
+import {type PdkAdmin} from './pdk';
+
+export const INJECT_ADMIN_INSTANCE: InjectionKey<AdminInstance> = Symbol('instance');
+
+export const INJECT_GLOBAL_PDK_ADMIN: InjectionKey<PdkAdmin> = Symbol('admin');

package/src/testing.ts

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

package/src/types/actions/actions.types.ts

@@ -0,0 +1,42 @@
+import {type BackendEndpoint} from '@myparcel-dev/pdk-common';
+import {type ReverseMap} from '@myparcel-dev/ts-utils';
+import {type AdminAction} from '../../data';
+
+export type MaybeAdminAction = AdminAction | undefined;
+
+export type PrintAction = AdminAction.ShipmentsPrint | AdminAction.OrdersPrint;
+
+export type OrderAction =
+  | AdminAction.OrdersEdit
+  | AdminAction.OrdersExport
+  | AdminAction.OrdersExportPrint
+  | AdminAction.OrdersFetch
+  | AdminAction.OrdersPrint
+  | AdminAction.OrdersUpdate;
+
+export interface AdminActionEndpointMap extends Record<AdminAction, BackendEndpoint> {
+  [AdminAction.AccountDelete]: BackendEndpoint.DeleteAccount;
+  [AdminAction.AccountUpdate]: BackendEndpoint.UpdateAccount;
+  [AdminAction.ContextFetch]: BackendEndpoint.FetchContext;
+  [AdminAction.DownloadLogs]: BackendEndpoint.DownloadLogs;
+  [AdminAction.SwitchToAcceptanceApi]: BackendEndpoint.SwitchToAcceptanceApi;
+  [AdminAction.SwitchToProductionApi]: BackendEndpoint.SwitchToProductionApi;
+  [AdminAction.OrdersEdit]: BackendEndpoint.UpdateOrders;
+  [AdminAction.OrdersExportPrint]: BackendEndpoint.ExportOrders;
+  [AdminAction.OrdersExport]: BackendEndpoint.ExportOrders;
+  [AdminAction.OrdersFetch]: BackendEndpoint.FetchOrders;
+  [AdminAction.OrdersPrint]: BackendEndpoint.PrintOrders;
+  [AdminAction.OrdersUpdate]: BackendEndpoint.UpdateOrders;
+  [AdminAction.PluginSettingsUpdate]: BackendEndpoint.UpdatePluginSettings;
+  [AdminAction.ProductSettingsUpdate]: BackendEndpoint.UpdateProductSettings;
+  [AdminAction.ShipmentsDelete]: BackendEndpoint.DeleteShipments;
+  [AdminAction.ShipmentsExportReturn]: BackendEndpoint.ExportReturn;
+  [AdminAction.ShipmentsFetch]: BackendEndpoint.FetchShipments;
+  [AdminAction.ShipmentsPrint]: BackendEndpoint.PrintShipments;
+  [AdminAction.ShipmentsUpdate]: BackendEndpoint.UpdateShipments;
+  [AdminAction.WebhooksCreate]: BackendEndpoint.CreateWebhooks;
+  [AdminAction.WebhooksDelete]: BackendEndpoint.DeleteWebhooks;
+  [AdminAction.WebhooksFetch]: BackendEndpoint.FetchWebhooks;
+}
+
+export type EndpointAdminActionMap = ReverseMap<AdminActionEndpointMap>;

package/src/types/actions/endpoints.types.ts

@@ -0,0 +1,32 @@
+import {type BackendEndpoint} from '@myparcel-dev/pdk-common';
+
+/**
+ * All backend endpoints that are mutations.
+ */
+export type BackendMutationEndpoints =
+  | BackendEndpoint.CreateWebhooks
+  | BackendEndpoint.DownloadLogs
+  | BackendEndpoint.SwitchToAcceptanceApi
+  | BackendEndpoint.SwitchToProductionApi
+  | BackendEndpoint.DeleteAccount
+  | BackendEndpoint.DeleteShipments
+  | BackendEndpoint.DeleteWebhooks
+  | BackendEndpoint.ExportOrders
+  | BackendEndpoint.ExportReturn
+  | BackendEndpoint.PrintOrders
+  | BackendEndpoint.PrintShipments
+  | BackendEndpoint.UpdateAccount
+  | BackendEndpoint.UpdateOrders
+  | BackendEndpoint.UpdatePluginSettings
+  | BackendEndpoint.UpdateProductSettings
+  | BackendEndpoint.UpdateShipments;
+
+/**
+ * All backend endpoints that are queries.
+ */
+export type BackendQueryEndpoints =
+  | BackendEndpoint.FetchContext
+  | BackendEndpoint.FetchOrders
+  | BackendEndpoint.FetchProducts
+  | BackendEndpoint.FetchShipments
+  | BackendEndpoint.FetchWebhooks;

package/src/types/actions/index.ts

@@ -0,0 +1,4 @@
+export * from './actions.types';
+export * from './endpoints.types';
+export * from './parameters.types';
+export * from './response.types';

package/src/types/actions/parameters.types.ts

@@ -0,0 +1,80 @@
+import {
+  type AdminContextKey,
+  type BackendEndpoint,
+  type LabelFormat,
+  type LabelOutput,
+  type LabelPosition,
+} from '@myparcel-dev/pdk-common';
+import {type FormInstance} from '@myparcel-dev/vue-form-builder';
+import {type OneOrMore} from '@myparcel-dev/ts-utils';
+import {type OrderIds, type ShipmentIds} from '../common.types';
+import {type AdminAction} from '../../data';
+import {type AdminActionEndpointMap, type MaybeAdminAction} from './actions.types';
+
+type LabelParameters = {
+  output?: LabelOutput;
+  format?: LabelFormat;
+  position?: OneOrMore<LabelPosition>;
+};
+
+type OrderIdParameters = {
+  orderIds?: OrderIds;
+};
+
+interface ShipmentIdParameters {
+  shipmentIds?: ShipmentIds;
+}
+
+type FormParameters = {
+  form: FormInstance;
+};
+
+type OptionalFormParameters = {
+  form?: false | FormInstance;
+};
+
+type ProductIdParameters = {
+  productIds?: OneOrMore<string>;
+};
+
+type HooksParameters = {
+  hooks: OneOrMore<string>;
+};
+
+type ContextParameters = {
+  context?: OneOrMore<AdminContextKey>;
+};
+
+export interface EndpointMutationInputMap extends Record<BackendEndpoint, object> {
+  [BackendEndpoint.FetchContext]: ContextParameters;
+
+  [BackendEndpoint.UpdateAccount]: OptionalFormParameters;
+
+  [BackendEndpoint.ExportOrders]: OrderIdParameters & OptionalFormParameters;
+  [BackendEndpoint.FetchOrders]: OrderIdParameters;
+  [BackendEndpoint.PrintOrders]: OrderIdParameters & LabelParameters & OptionalFormParameters;
+  [BackendEndpoint.UpdateOrders]: OrderIdParameters & FormParameters;
+
+  [BackendEndpoint.DeleteShipments]: OrderIdParameters & ShipmentIdParameters;
+  [BackendEndpoint.ExportReturn]: OrderIdParameters & ShipmentIdParameters;
+  [BackendEndpoint.FetchShipments]: OrderIdParameters & ShipmentIdParameters;
+  [BackendEndpoint.UpdateShipments]: OrderIdParameters & ShipmentIdParameters;
+  [BackendEndpoint.PrintShipments]: OrderIdParameters & ShipmentIdParameters & OptionalFormParameters & LabelParameters;
+
+  [BackendEndpoint.FetchProducts]: ProductIdParameters;
+
+  [BackendEndpoint.UpdatePluginSettings]: FormParameters;
+  [BackendEndpoint.UpdateProductSettings]: ProductIdParameters & FormParameters;
+
+  [BackendEndpoint.CreateWebhooks]: HooksParameters;
+  [BackendEndpoint.DeleteWebhooks]: HooksParameters;
+  [BackendEndpoint.FetchWebhooks]: never;
+}
+
+export type ActionInput<E extends BackendEndpoint> = EndpointMutationInputMap[E];
+
+export type ActionParameters<A extends string | MaybeAdminAction> = A extends AdminAction
+  ? ActionInput<AdminActionEndpointMap[A]>
+  : object;
+
+export type MaybeActionParameters<A extends MaybeAdminAction> = ActionParameters<A> | void;

package/src/types/actions/response.types.ts

@@ -0,0 +1,12 @@
+import {type BackendEndpoint, type PdkEndpointResponse} from '@myparcel-dev/pdk-common';
+import {type BackendEndpointDefinition} from '../sdk.types';
+import {type AdminAction} from '../../data';
+import {type AdminActionEndpointMap, type MaybeAdminAction} from './actions.types';
+
+export type BackendEndpointResponse<E extends BackendEndpoint> = PdkEndpointResponse<E, BackendEndpointDefinition>;
+
+export type ActionResponse<A extends MaybeAdminAction> = A extends AdminAction
+  ? BackendEndpointResponse<AdminActionEndpointMap[A]>
+  : void;
+
+export type MaybeActionResponse<A extends MaybeAdminAction> = ActionResponse<A> | void;

package/src/types/actions.types.ts

@@ -0,0 +1,57 @@
+import {type MaybeRef} from '@vueuse/core';
+import {type Variant} from '@myparcel-dev/pdk-common';
+import {type OneOrMore, type PromiseOr} from '@myparcel-dev/ts-utils';
+import {type AdminAction, type AdminIcon} from '../data';
+import {type ActionContext, type ActionContextWithResponse, type QueryHandler} from '../actions';
+import {type Translation} from './language.types';
+import {
+  type ActionParameters,
+  type ActionResponse,
+  type AdminActionEndpointMap,
+  type MaybeAdminAction,
+} from './actions';
+
+interface BaseActionDefinition {
+  disabled?: MaybeRef<boolean>;
+  icon?: AdminIcon;
+  label?: Translation;
+  notifications?: OneOrMore<Variant>;
+  standalone?: boolean;
+  variant?: MaybeRef<Variant | undefined>;
+  afterHandle?(...args: unknown[]): PromiseOr<unknown>;
+  beforeHandle?(...args: unknown[]): PromiseOr<unknown>;
+  handler(...args: unknown[]): PromiseOr<unknown>;
+}
+
+export interface NamedActionDefinition<A extends AdminAction = AdminAction> extends BaseActionDefinition {
+  name: A;
+  afterHandle?(context: ActionContextWithResponse<A>): PromiseOr<ActionResponse<A>>;
+  beforeHandle?(context: ActionContext<A>): PromiseOr<ActionParameters<A>>;
+  handler: QueryHandler<AdminActionEndpointMap[A]>;
+}
+
+export interface GenericActionDefinition extends BaseActionDefinition {
+  name?: never;
+  id: string;
+  afterHandle?(context: ActionContextWithResponse): PromiseOr<void>;
+  beforeHandle?(context: ActionContext): PromiseOr<void>;
+  handler(context: ActionContext): PromiseOr<void>;
+}
+
+export type AnyActionDefinition<A extends MaybeAdminAction = MaybeAdminAction> = A extends AdminAction
+  ? NamedActionDefinition<A>
+  : GenericActionDefinition;
+
+export type ActionDefinition<A extends MaybeAdminAction = MaybeAdminAction> = AnyActionDefinition<A> & {
+  id: string;
+  parameters?: ActionParameters<A>;
+};
+
+/**
+ * The final action type that can be executed.
+ */
+export type ResolvedAction = BaseActionDefinition & {
+  id: string;
+  standalone?: boolean;
+  handler(parameters?: ActionParameters<AdminAction> | Record<string, unknown>): PromiseOr<void>;
+};

package/src/types/admin.types.ts

@@ -0,0 +1,47 @@
+import {type Component} from 'vue';
+import {type PdkLogger} from '../services';
+import {
+  type ADMIN_COMPONENT_PREFIX,
+  type AdminComponent,
+  type AdminView,
+  type optionalAdminActionContainerComponentNames,
+  type optionalAdminComponentNames,
+  type optionalAdminPlainWrapperComponentNames,
+  type requiredAdminComponentNames,
+} from '../data';
+import {type AdminContextObject, type AdminInstanceContext} from './context.types';
+import {type AdminConfiguration} from './configuration.types';
+
+export type RequiredAdminComponentName = (typeof requiredAdminComponentNames)[number];
+
+export type OptionalAdminComponentName =
+  | (typeof optionalAdminComponentNames)[number]
+  | (typeof optionalAdminPlainWrapperComponentNames)[number]
+  | (typeof optionalAdminActionContainerComponentNames)[number];
+
+export type PrefixedAdminComponent<A extends AdminComponent = AdminComponent> = `${typeof ADMIN_COMPONENT_PREFIX}${A}`;
+
+export type AdminComponentMap = Record<RequiredAdminComponentName, Component> &
+  Partial<Record<OptionalAdminComponentName, Component>>;
+
+/**
+ * Prefer using AdminComponentMap instead to reduce bundle size.
+ */
+export type PrefixedAdminComponentMap = Record<PrefixedAdminComponent<RequiredAdminComponentName>, Component> &
+  Partial<Record<PrefixedAdminComponent<OptionalAdminComponentName>, Component>>;
+
+export type ComponentImportFunction = () => Promise<{
+  default: Component;
+}>;
+
+export interface AdminAppConfig {
+  appName: string;
+  config: AdminConfiguration;
+  context: AdminContextObject;
+  logger: PdkLogger;
+  view?: AdminView;
+}
+
+export interface AdminInstance extends Omit<AdminAppConfig, 'context'> {
+  context: Partial<AdminInstanceContext>;
+}

package/src/types/common.types.ts

@@ -0,0 +1,66 @@
+import {type Component} from 'vue';
+import {type Variant} from '@myparcel-dev/pdk-common';
+import {type OneOrMore} from '@myparcel-dev/ts-utils';
+import {type NotificationCategory} from '../data';
+import {type Translation} from './language.types';
+
+export type NotificationId = number | string;
+
+export interface PdkNotification {
+  category?: NotificationCategory;
+  content?: OneOrMore<string>;
+  dismissible?: boolean;
+  /**
+   * ID of a notification. If not provided, a unique id will be generated. It may be a string, but make sure this string
+   * does not exist in NotificationCategory.
+   *
+   * @see NotificationCategory
+   */
+  id?: NotificationId;
+  /**
+   * Arbitrary tags that can be set to distinguish notifications from each other.
+   */
+  tags?: Record<string, string>;
+  timeout?: boolean | number;
+  title?: string;
+  variant: Variant;
+}
+
+export type ResolvedNotification = PdkNotification & {
+  id: NotificationId;
+  timeout: boolean | number;
+  dismissible: boolean;
+};
+
+export type NotificationFilter = (notification: ResolvedNotification) => boolean;
+
+export type OrderIds = OneOrMore<string>;
+
+export type ShipmentIds = OneOrMore<string | number>;
+
+export type ArrayItem<T> = T extends (infer U)[] ? U : T;
+
+export interface TabDefinition {
+  component: string | Component;
+  description?: Translation;
+  icon?: string;
+  label: Translation;
+  labelSuffix?: string;
+  name: string;
+  subtext?: Translation;
+}
+
+export type WebhookDefinition = {
+  connected: boolean;
+  hook: string;
+  url: null | string;
+};
+
+export type DefaultSlot = {
+  default(): never;
+};
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type PlainComponentProps = {};
+
+export type PlainComponentSlots = DefaultSlot;