@myparcel-dev/pdk-admin 1.13.0

package/src/types/form.types.ts

@@ -0,0 +1,65 @@
+import {type Keyable, type SortType} from '@myparcel-dev/pdk-common';
+import {type InteractiveElementInstance} from '@myparcel-dev/vue-form-builder';
+import {type AdminIcon} from '../data';
+import {type Translatable, type Translation} from './language.types';
+
+export type GlobalFieldProps = {
+  description?: Translation;
+  subtext?: Translation;
+  value?: unknown;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ElementInstance<Type = unknown, Props = any> = InteractiveElementInstance<
+  Type,
+  Props & GlobalFieldProps & Record<string, unknown>
+>;
+
+export type OptionsProp<T extends SelectOptionValue = SelectOptionValue> = {
+  options?: SelectOption<T>[];
+  sort?: SortType;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type PdkElementProps<ModelValue extends unknown = Keyable, Props = any> = {
+  element: ElementInstance<ModelValue, Props>;
+  modelValue: ModelValue;
+};
+
+export type PdkElementEmits<ModelValue extends unknown = Keyable> = (
+  event: 'update:modelValue',
+  value: ModelValue,
+) => void;
+
+export type RadioGroupOption<Value extends Keyable = Keyable> = SelectOption<Value> & {
+  image?: string;
+  icon?: AdminIcon;
+};
+
+interface BaseSelectOption<Value extends SelectOptionValue = SelectOptionValue> {
+  disabled?: boolean;
+  icon?: string | AdminIcon;
+  image?: string;
+  description?: Translatable;
+  value: Value;
+}
+
+export interface SelectOptionWithLabel<
+  Value extends SelectOptionValue = SelectOptionValue,
+  T extends Translation = Translation,
+> extends BaseSelectOption<Value> {
+  label: T;
+}
+
+export interface SelectOptionWithPlainLabel<
+  Value extends SelectOptionValue = SelectOptionValue,
+  T extends Translation = Translation,
+> extends BaseSelectOption<Value> {
+  plainLabel: T;
+}
+
+export type SelectOptionValue = Keyable | boolean;
+
+export type SelectOption<Value extends SelectOptionValue = SelectOptionValue> =
+  | SelectOptionWithLabel<Value>
+  | SelectOptionWithPlainLabel<Value>;

package/src/types/index.ts

@@ -0,0 +1,12 @@
+export * from './actions';
+export * from './actions.types';
+export * from './admin.types';
+export * from './common.types';
+export * from './components-form.types';
+export * from './components.types';
+export * from './configuration.types';
+export * from './context.types';
+export * from './endpoints.types';
+export * from './form.types';
+export * from './language.types';
+export * from './sdk.types';

package/src/types/language.types.ts

@@ -0,0 +1,12 @@
+import {type Keyable} from '@myparcel-dev/pdk-common';
+
+export interface NonTranslatable {
+  text: string;
+}
+
+export interface Translatable {
+  key: string;
+  args?: Record<Keyable, Keyable>;
+}
+
+export type Translation = string | Translatable | NonTranslatable;

package/src/types/sdk.types.ts

@@ -0,0 +1,213 @@
+import {
+  type AdminContextKey,
+  type BackendEndpoint,
+  type ExtractEndpointDefinition,
+  type LabelFormat,
+  type LabelOutput,
+  type LabelPosition,
+  type PdkEndpointDefinition,
+  type Plugin,
+  type Settings,
+  type Shipment,
+} from '@myparcel-dev/pdk-common';
+import {type RecursivePartial} from '@myparcel-dev/ts-utils';
+import {type AdminContextObject} from './context.types';
+import {type WebhookDefinition} from './common.types';
+
+export type PdfUrlResponse = {
+  url: string;
+};
+
+export type PdfDataResponse = {
+  data: string;
+};
+
+interface BasePrintDefinition extends PdkEndpointDefinition {
+  formattedResponse: PdfUrlResponse | PdfDataResponse;
+  parameters: {
+    orderIds: string;
+    shipmentIds?: string;
+    format?: LabelFormat;
+    output?: LabelOutput;
+    position?: LabelPosition;
+  };
+  response: (PdfUrlResponse | PdfDataResponse)[];
+}
+
+interface FetchContextDefinition extends PdkEndpointDefinition {
+  formattedResponse: AdminContextObject;
+  name: BackendEndpoint.FetchContext;
+  parameters: {
+    context: string;
+  };
+  response: [AdminContextObject];
+}
+
+interface DeleteAccountDefinition extends PdkEndpointDefinition {
+  name: BackendEndpoint.UpdateAccount;
+  body: undefined;
+  parameters: undefined;
+  response: [Pick<AdminContextObject, AdminContextKey.Dynamic | AdminContextKey.PluginSettingsView>];
+  formattedResponse: Pick<AdminContextObject, AdminContextKey.Dynamic | AdminContextKey.PluginSettingsView>;
+}
+
+interface UpdateAccountDefinition extends PdkEndpointDefinition {
+  body: Settings.ModelAccountSettings;
+  name: BackendEndpoint.UpdateAccount;
+  parameters: undefined;
+  response: [Pick<AdminContextObject, AdminContextKey.Dynamic | AdminContextKey.PluginSettingsView>];
+  formattedResponse: Pick<AdminContextObject, AdminContextKey.Dynamic | AdminContextKey.PluginSettingsView>;
+}
+
+interface FetchOrdersDefinition extends PdkEndpointDefinition {
+  formattedResponse: Plugin.ModelContextOrderDataContext;
+  name: BackendEndpoint.FetchOrders;
+  parameters: {
+    orderIds: string;
+  };
+  response: [Plugin.ModelContextOrderDataContext];
+}
+
+interface ExportOrdersDefinition extends PdkEndpointDefinition {
+  body?: RecursivePartial<Plugin.ModelContextOrderDataContext>[];
+  name: BackendEndpoint.ExportOrders;
+  parameters: {
+    orderIds: string;
+  };
+  response: Plugin.ModelContextOrderDataContext[];
+}
+
+interface UpdateOrdersDefinition extends PdkEndpointDefinition {
+  body?: RecursivePartial<Plugin.ModelContextOrderDataContext>[];
+  name: BackendEndpoint.UpdateOrders;
+  parameters: {
+    orderIds: string;
+  };
+  response: Plugin.ModelContextOrderDataContext[];
+}
+
+interface DeleteShipmentsDefinition extends PdkEndpointDefinition {
+  name: BackendEndpoint.DeleteShipments;
+  parameters: {
+    orderIds: string;
+    shipmentIds?: string;
+  };
+  response: Plugin.ModelContextOrderDataContext[];
+}
+
+interface UpdateShipmentsDefinition extends PdkEndpointDefinition {
+  body: RecursivePartial<Plugin.ModelContextOrderDataContext>[];
+  name: BackendEndpoint.UpdateShipments;
+  parameters: {
+    orderIds: string;
+    shipmentIds?: string;
+  };
+  response: Plugin.ModelContextOrderDataContext['shipments'];
+}
+
+interface FetchShipmentsDefinition extends PdkEndpointDefinition {
+  name: BackendEndpoint.FetchShipments;
+  parameters: {
+    orderIds: string;
+    shipmentIds?: string;
+  };
+  response: Shipment.ModelShipment[];
+  formattedResponse: Shipment.ModelShipment;
+}
+
+interface FetchProductsDefinition extends PdkEndpointDefinition {
+  formattedResponse: Plugin.ModelContextProductDataContext;
+  name: BackendEndpoint.FetchProducts;
+  parameters: {
+    productIds: string;
+  };
+  response: [Plugin.ModelContextProductDataContext];
+}
+
+interface UpdatePluginSettingsDefinition extends PdkEndpointDefinition {
+  body: Settings.ModelSettings;
+  name: BackendEndpoint.UpdatePluginSettings;
+  parameters: undefined;
+  response: Settings.ModelSettings[];
+}
+
+interface UpdateProductSettingsDefinition extends PdkEndpointDefinition {
+  body: Settings.ModelProductSettings;
+  name: BackendEndpoint.UpdateProductSettings;
+  parameters: {
+    productIds: string;
+  };
+  response: Settings.ModelProductSettings[];
+}
+
+interface PrintShipmentsDefinition extends BasePrintDefinition {
+  name: BackendEndpoint.PrintShipments;
+}
+
+interface PrintOrdersDefinition extends BasePrintDefinition {
+  name: BackendEndpoint.PrintOrders;
+}
+
+interface FetchWebhooksDefinition extends PdkEndpointDefinition {
+  name: BackendEndpoint.FetchWebhooks;
+  parameters: never;
+  response: WebhookDefinition[];
+}
+
+interface CreateWebhooksDefinition extends PdkEndpointDefinition {
+  name: BackendEndpoint.CreateWebhooks;
+  parameters: {
+    hooks: string;
+  };
+  response: WebhookDefinition[];
+}
+
+interface DeleteWebhooksDefinition extends PdkEndpointDefinition {
+  name: BackendEndpoint.DeleteWebhooks;
+  parameters: {
+    hooks: string;
+  };
+  response: WebhookDefinition[];
+}
+
+interface DebugDownloadLogsDefinition extends PdkEndpointDefinition {
+  name: BackendEndpoint.DownloadLogs;
+  response: Blob;
+}
+
+interface DebugSwitchToAcceptanceApiDefinition extends PdkEndpointDefinition {
+  name: BackendEndpoint.SwitchToAcceptanceApi;
+  response: void;
+}
+
+interface DebugSwitchToProductionApiDefinition extends PdkEndpointDefinition {
+  name: BackendEndpoint.SwitchToProductionApi;
+  response: void;
+}
+
+export type BackendEndpointDefinition =
+  | CreateWebhooksDefinition
+  | DebugDownloadLogsDefinition
+  | DebugSwitchToAcceptanceApiDefinition
+  | DebugSwitchToProductionApiDefinition
+  | DeleteAccountDefinition
+  | DeleteShipmentsDefinition
+  | DeleteWebhooksDefinition
+  | ExportOrdersDefinition
+  | FetchContextDefinition
+  | FetchOrdersDefinition
+  | FetchProductsDefinition
+  | FetchShipmentsDefinition
+  | FetchWebhooksDefinition
+  | PrintOrdersDefinition
+  | PrintShipmentsDefinition
+  | UpdateAccountDefinition
+  | UpdateOrdersDefinition
+  | UpdatePluginSettingsDefinition
+  | UpdateProductSettingsDefinition
+  | UpdateShipmentsDefinition;
+
+export type BackendEndpointOptions<N extends BackendEndpoint> = Omit<
+  ExtractEndpointDefinition<N, BackendEndpointDefinition>,
+  'name' | 'response'
+>;

package/src/utils/booleanToTriState.spec.ts

@@ -0,0 +1,13 @@
+import {describe, expect, it} from 'vitest';
+import {TriState} from '@myparcel-dev/pdk-common';
+import {booleanToTriState} from './booleanToTriState';
+
+describe('booleanToTriState', () => {
+  it.each([
+    [true, TriState.On],
+    [false, TriState.Off],
+    [undefined, TriState.Off],
+  ])('should return %s for %s', (value, expected) => {
+    expect(booleanToTriState(value)).toEqual(expected);
+  });
+});

package/src/utils/booleanToTriState.ts

@@ -0,0 +1,5 @@
+import {TriState} from '@myparcel-dev/pdk-common';
+
+export const booleanToTriState = (value?: boolean): TriState.On | TriState.Off => {
+  return value ? TriState.On : TriState.Off;
+};

package/src/utils/convertDotNotationToObject.ts

@@ -0,0 +1,15 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import {set} from 'lodash-unified';
+
+export const convertDotNotationToObject = (
+  object: Record<string, any>,
+  valueCallback: (value: any, key: string) => any = (value) => value,
+): Record<string, any> => {
+  const result: Record<string, any> = {};
+
+  Object.entries(object).forEach(([key, value]) => {
+    set(result, key, valueCallback(value, key));
+  });
+
+  return result;
+};

package/src/utils/createAssetUrl.ts

@@ -0,0 +1,9 @@
+export const createAssetUrl = (path?: string): string => {
+  path ??= '';
+
+  if (path.startsWith('/')) {
+    path = path.slice(1);
+  }
+
+  return `https://assets.myparcel.nl/${path}`;
+};

package/src/utils/createClasses.ts

@@ -0,0 +1,18 @@
+import {type MaybeRef} from '@vueuse/core';
+
+type ClassValue = MaybeRef<string | number | boolean | undefined>;
+
+type ClassDefinition = {
+  key: string | undefined;
+  value: ClassValue;
+};
+
+export const createClasses = (param: ClassDefinition[]): Record<string, ClassValue> => {
+  return param.reduce((acc, {key, value}) => {
+    if (key && value) {
+      acc[key] = value;
+    }
+
+    return acc;
+  }, {} as Record<string, ClassValue>);
+};

package/src/utils/createObjectWithKeys.ts

@@ -0,0 +1,10 @@
+import {type Keyable} from '@myparcel-dev/pdk-common';
+import {type ReadonlyOr} from '@myparcel-dev/ts-utils';
+
+export const createObjectWithKeys = <K extends ReadonlyOr<Keyable[]>, V>(
+  keys: K,
+  callback: (key: K[number]) => V = (key) => key as V,
+): Record<K[number], V> => {
+  // @ts-expect-error wonky type inference
+  return keys.reduce((acc, key) => ({...acc, [key]: callback(key)}), {}) as Record<K[number], V>;
+};

package/src/utils/decodeHtmlEntities.ts

@@ -0,0 +1,11 @@
+/**
+ * Decodes any HTML entities in given string into their original strings.
+ *
+ * @param {string} string
+ * @returns {string}
+ */
+export function decodeHtmlEntities(string: string): string {
+  const textarea = document.createElement('textarea');
+  textarea.innerHTML = string;
+  return textarea.value;
+}

package/src/utils/downloadBlob.ts

@@ -0,0 +1,9 @@
+import {downloadFileFromUrl} from './downloadFileFromUrl';
+
+export const downloadBlob = (blob: Blob, filename: string): void => {
+  const url = URL.createObjectURL(blob);
+
+  downloadFileFromUrl(url, filename);
+
+  URL.revokeObjectURL(url);
+};

package/src/utils/downloadFileFromUrl.spec.ts

@@ -0,0 +1,29 @@
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {mockLinkElement} from '../__tests__/utils/mockLinkElement';
+import {downloadFileFromUrl} from './downloadFileFromUrl';
+
+/**
+ * @vitest-environment happy-dom
+ */
+
+describe('downloadFileFromUrl', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('creates a link with correct href and download attributes, clicks it, and removes it', () => {
+    const url = 'https://example.com/file.zip';
+    const filename = 'file.zip';
+
+    const {createElementSpy, appendChildSpy, mockElement} = mockLinkElement();
+
+    downloadFileFromUrl(url, filename);
+
+    expect(createElementSpy).toHaveBeenCalledWith('a');
+    expect(mockElement.setAttribute).toHaveBeenCalledWith('href', url);
+    expect(mockElement.setAttribute).toHaveBeenCalledWith('download', filename);
+    expect(appendChildSpy).toHaveBeenCalledWith(mockElement);
+    expect(mockElement.click).toHaveBeenCalled();
+    expect(mockElement.remove).toHaveBeenCalled();
+  });
+});

package/src/utils/downloadFileFromUrl.ts

@@ -0,0 +1,5 @@
+import {fakeLinkClick} from './fakeLinkClick';
+
+export const downloadFileFromUrl = (url: string, filename: string): void => {
+  fakeLinkClick(url, {download: filename});
+};

package/src/utils/encodeArrayParameter.ts

@@ -0,0 +1,6 @@
+import {isDef} from '@vueuse/core';
+import {type OneOrMore, toArray} from '@myparcel-dev/ts-utils';
+
+export const encodeArrayParameter = (parameter?: null | OneOrMore<string | number | undefined>): string => {
+  return toArray(parameter).filter(isDef).join(';');
+};

package/src/utils/extendAdminInstance.ts

@@ -0,0 +1,10 @@
+import {inject, provide} from 'vue';
+import {merge} from 'lodash-unified';
+import {type AdminInstance} from '../types';
+import {INJECT_ADMIN_INSTANCE} from '../symbols';
+
+export const extendAdminInstance = (data: Partial<AdminInstance>): void => {
+  const instance = inject(INJECT_ADMIN_INSTANCE);
+
+  provide(INJECT_ADMIN_INSTANCE, merge({}, instance, data));
+};

package/src/utils/fakeLinkClick.ts

@@ -0,0 +1,17 @@
+/**
+ * Creates and clicks a link with the given URL. Avoids popup blockers by creating a hidden link element.
+ */
+export const fakeLinkClick = (url: string, attributes: Record<string, string>): void => {
+  const link = document.createElement('a');
+
+  link.href = url;
+
+  Object.entries(attributes).forEach(([key, value]) => {
+    link.setAttribute(key, value);
+  });
+
+  document.body.appendChild(link);
+
+  link.click();
+  link.remove();
+};

package/src/utils/forms/createFormElement.ts

@@ -0,0 +1,20 @@
+import {ref} from 'vue';
+import {type FormInstance, type InteractiveElementConfiguration} from '@myparcel-dev/vue-form-builder';
+import {type ElementInstance, type PdkElementProps} from '../../types';
+
+export const createFormElement = <Type = unknown>(
+  config?: Partial<InteractiveElementConfiguration<Type>>,
+  formName?: string,
+): ElementInstance<Type, PdkElementProps<Type>> => {
+  const form = {
+    name: formName ?? 'form',
+  } as unknown as FormInstance;
+
+  return {
+    component: 'input',
+    form,
+    name: 'element',
+    ref: ref(),
+    ...config,
+  } as unknown as ElementInstance<Type, PdkElementProps<Type>>;
+};

package/src/utils/forms/createShipmentFormName.ts

@@ -0,0 +1,9 @@
+import {AdminModalKey} from '../../data';
+
+export const createShipmentFormName = (orderId?: string): string => {
+  if (!orderId) {
+    orderId = 'bulk';
+  }
+
+  return `${AdminModalKey.ShipmentOptions}_${orderId}`;
+};

package/src/utils/forms/formToBody.ts

@@ -0,0 +1,16 @@
+import {type FormInstance} from '@myparcel-dev/vue-form-builder';
+import {isOfType} from '@myparcel-dev/ts-utils';
+import {convertDotNotationToObject} from '../convertDotNotationToObject';
+
+export const formToBody = <T extends Record<string, unknown> = Record<string, unknown>>(
+  form?: false | FormInstance | T,
+): T => {
+  if (!isOfType<FormInstance>(form, 'getValues')) {
+    return form ? form : ({} as T);
+  }
+
+  const formValues = form.getValues();
+  return convertDotNotationToObject(formValues, (value) => {
+    return typeof value === 'boolean' ? Number(value) : value;
+  }) as T;
+};

package/src/utils/forms/generateFieldId.ts

@@ -0,0 +1,17 @@
+import {unref} from 'vue';
+import {type MaybeRef} from '@vueuse/core';
+import {type InteractiveElementInstance, useElement} from '@myparcel-dev/vue-form-builder';
+import {type ElementInstance} from '../../types';
+import {type FORM_KEYS} from '../../forms';
+import {useAdminConfig} from '../../composables';
+
+export const generateFieldId = (element?: MaybeRef<ElementInstance>): string => {
+  const config = useAdminConfig();
+  const resolvedElement = unref(element) ?? useElement();
+
+  const formBaseName = resolvedElement.form.name.split('--')[0] as (typeof FORM_KEYS)[number];
+
+  const method = config.formConfigOverrides?.[formBaseName]?.generateFieldId ?? config.generateFieldId;
+
+  return method(resolvedElement as InteractiveElementInstance);
+};

package/src/utils/forms/index.ts

@@ -0,0 +1,4 @@
+export * from './createFormElement';
+export * from './createShipmentFormName';
+export * from './formToBody';
+export * from './generateFieldId';

package/src/utils/generateLabelFilename.spec.ts

@@ -0,0 +1,24 @@
+import {describe, expect, it} from 'vitest';
+import {generateLabelFilename} from './generateLabelFilename';
+
+describe('generating label filename', () => {
+  it('generates a filename for a single order', () => {
+    expect(generateLabelFilename({orderIds: '123'})).toEqual('myparcel-labels-123.pdf');
+  });
+
+  it('generates a filename for multiple orders', () => {
+    expect(generateLabelFilename({orderIds: ['123', '456']})).toEqual('myparcel-labels.pdf');
+  });
+
+  it('generates a filename for a single shipment', () => {
+    expect(generateLabelFilename({orderIds: '123', shipmentIds: 456})).toEqual('myparcel-labels-123-456.pdf');
+  });
+
+  it('generates a filename for multiple shipments', () => {
+    expect(generateLabelFilename({orderIds: '123', shipmentIds: [456, 789]})).toEqual('myparcel-labels-123.pdf');
+  });
+
+  it('generates a filename for multiple orders and shipments', () => {
+    expect(generateLabelFilename({orderIds: ['123', '456'], shipmentIds: [789, 101]})).toEqual('myparcel-labels.pdf');
+  });
+});

package/src/utils/generateLabelFilename.ts

@@ -0,0 +1,26 @@
+import {type BackendEndpoint} from '@myparcel-dev/pdk-common';
+import {isOfType, toArray} from '@myparcel-dev/ts-utils';
+import {type ActionInput} from '../types';
+
+export const generateLabelFilename = (
+  parameters: ActionInput<BackendEndpoint.PrintShipments | BackendEndpoint.PrintOrders>,
+): string => {
+  const prefix = 'myparcel-labels';
+  const suffix = '.pdf';
+
+  const orderIds = toArray(parameters.orderIds);
+
+  if (orderIds.length > 1) {
+    return `${prefix}${suffix}`;
+  }
+
+  if (isOfType<ActionInput<BackendEndpoint.PrintShipments>>(parameters, 'shipmentIds')) {
+    const shipmentIds = toArray(parameters.shipmentIds);
+
+    if (shipmentIds.length === 1) {
+      return `${prefix}-${orderIds[0]}-${shipmentIds[0]}${suffix}`;
+    }
+  }
+
+  return `${prefix}-${orderIds[0]}${suffix}`;
+};

package/src/utils/getOrderId.ts

@@ -0,0 +1,12 @@
+import {type OneOrMore} from '@myparcel-dev/ts-utils';
+import {type AdminInstance} from '../types';
+import {AdminInstanceContextKey} from '../data';
+import {useInstanceContext, useModalOrder} from '../composables';
+
+export const getOrderId = (instance?: AdminInstance): undefined | OneOrMore<string> => {
+  return (
+    useModalOrder() ??
+    instance?.context?.[AdminInstanceContextKey.OrderIdentifier] ??
+    useInstanceContext(AdminInstanceContextKey.OrderIdentifier)
+  );
+};

package/src/utils/getOrderShipmentIds.ts

@@ -0,0 +1,12 @@
+import {toValue} from 'vue';
+import {isDef} from '@vueuse/core';
+import {type OrderIds} from '../types';
+import {useOrdersData} from '../composables';
+
+export const getOrderShipmentIds = (orderIds: OrderIds): number[] => {
+  return useOrdersData(orderIds)
+    .map(({order}) => toValue(order)?.shipments)
+    .flat()
+    .filter(isDef)
+    .map((shipment) => shipment.id);
+};

package/src/utils/index.ts

@@ -0,0 +1,23 @@
+export * from './booleanToTriState';
+export * from './convertDotNotationToObject';
+export * from './createAssetUrl';
+export * from './createClasses';
+export * from './createObjectWithKeys';
+export * from './decodeHtmlEntities';
+export * from './encodeArrayParameter';
+export * from './extendAdminInstance';
+export * from './forms';
+export * from './generateLabelFilename';
+export * from './getOrderId';
+export * from './getOrderShipmentIds';
+export * from './openUrlInNewTab';
+export * from './prefixComponent';
+export * from './query';
+export * from './resolveCarrier';
+export * from './translations';
+export * from './triStateToBoolean';
+export * from './unprefixComponent';
+export * from './validateId';
+export {downloadFileFromUrl} from './downloadFileFromUrl';
+
+export {fakeLinkClick} from './fakeLinkClick';