@beabee/beabee-common 0.21.1-alpha.1 → 0.44.2

package/src/utils/callouts.ts

@@ -0,0 +1,291 @@
+import {
+  CalloutComponentBaseType,
+  CalloutComponentType,
+  calloutComponentInputSelectableTypes,
+  calloutComponentInputTextTypes,
+  calloutComponentInputTypes,
+  calloutComponentNestableTypes,
+} from '../data/index.js';
+import type {
+  CalloutComponentBaseMap,
+  CalloutComponentBaseSchema,
+  CalloutComponentMap,
+  CalloutComponentSchema,
+  CalloutResponseAnswer,
+  CalloutResponseAnswerAddress,
+  CalloutResponseAnswerFileUpload,
+  CalloutResponseAnswersSlide,
+  FilterArgs,
+  FormioFile,
+  SetCalloutFormSchema,
+} from '../types/index.js';
+
+function convertValuesToOptions(
+  values: { value: string; label: string }[]
+): string[] {
+  return values.map(({ value }) => value);
+}
+
+function convertComponentToFilter(
+  component: CalloutComponentSchema & { fullKey: string }
+): FilterArgs & { label: string } {
+  const baseItem = {
+    label: component.label || component.fullKey,
+    nullable: true,
+  };
+
+  if (
+    isCalloutComponentOfType(component, CalloutComponentType.INPUT_CHECKBOX)
+  ) {
+    return { ...baseItem, type: 'boolean', nullable: false };
+  }
+
+  if (isCalloutComponentOfType(component, CalloutComponentType.INPUT_NUMBER)) {
+    return { ...baseItem, type: 'number' };
+  }
+
+  if (isCalloutComponentOfType(component, CalloutComponentType.INPUT_SELECT)) {
+    return {
+      ...baseItem,
+      type: 'enum',
+      options: convertValuesToOptions(component.data.values),
+    };
+  }
+
+  if (
+    isCalloutComponentOfBaseType(
+      component,
+      CalloutComponentBaseType.INPUT_SELECTABLE
+    )
+  ) {
+    return {
+      ...baseItem,
+      type:
+        component.type === CalloutComponentType.INPUT_SELECTABLE_RADIO
+          ? 'enum'
+          : 'array',
+      options: convertValuesToOptions(component.values),
+    };
+  }
+
+  if (
+    isCalloutComponentOfType(component, CalloutComponentType.INPUT_TEXT_AREA)
+  ) {
+    return { ...baseItem, type: 'blob' };
+  }
+
+  return { ...baseItem, type: 'text' };
+}
+
+function getSelectableLabelFromValue(
+  component: CalloutComponentSchema,
+  value: string
+): string {
+  if (
+    isCalloutComponentOfBaseType(
+      component,
+      CalloutComponentBaseType.INPUT_SELECTABLE
+    )
+  ) {
+    return component.values.find((v) => v.value === value)?.label || value;
+  }
+
+  if (isCalloutComponentOfType(component, CalloutComponentType.INPUT_SELECT)) {
+    return component.data.values.find((v) => v.value === value)?.label || value;
+  }
+
+  return value;
+}
+
+/**
+ * Check if a component is a specific component type
+ *
+ * @param component The component to check
+ * @param type The type of component to check
+ * @returns Ensure that the component is of the specific type
+ */
+export function isCalloutComponentOfType<T extends CalloutComponentType>(
+  component: CalloutComponentBaseSchema,
+  type: T
+): component is CalloutComponentMap[T] {
+  return 'type' in component && component.type === type;
+}
+
+/**
+ * Check if a component is a specific base component type
+ *
+ * @param component The component to check
+ * @param type The type of component to check
+ * @returns Ensure that the component is of the specific base type
+ */
+export function isCalloutComponentOfBaseType<
+  T extends CalloutComponentBaseType,
+>(
+  component: CalloutComponentBaseSchema,
+  type: T
+): component is CalloutComponentBaseMap[T] {
+  if (!('type' in component)) {
+    return false;
+  }
+
+  // `content` has only one schema
+  if (type === CalloutComponentBaseType.CONTENT) {
+    return isCalloutComponentOfType(component, CalloutComponentType.CONTENT);
+  }
+
+  if (type === CalloutComponentBaseType.INPUT) {
+    return (calloutComponentInputTypes as string[]).includes(component.type);
+  }
+
+  if (type === CalloutComponentBaseType.INPUT_TEXT) {
+    return (calloutComponentInputTextTypes as string[]).includes(
+      component.type
+    );
+  }
+
+  if (type === CalloutComponentBaseType.INPUT_SELECTABLE) {
+    return (calloutComponentInputSelectableTypes as string[]).includes(
+      component.type
+    );
+  }
+
+  if (type === CalloutComponentBaseType.NESTABLE) {
+    return (calloutComponentNestableTypes as string[]).includes(component.type);
+  }
+
+  return false;
+}
+
+export function flattenComponents(
+  components: CalloutComponentSchema[]
+): CalloutComponentSchema[] {
+  return components.flatMap((component) =>
+    isCalloutComponentOfBaseType(component, CalloutComponentBaseType.NESTABLE)
+      ? [component, ...flattenComponents(component.components)]
+      : [component]
+  );
+}
+
+export function filterComponents(
+  components: CalloutComponentSchema[],
+  filterFn: (component: CalloutComponentSchema) => boolean
+): CalloutComponentSchema[] {
+  return components.filter(filterFn).map((component) => {
+    return {
+      ...component,
+      ...(isCalloutComponentOfBaseType(
+        component,
+        CalloutComponentBaseType.NESTABLE
+      ) && {
+        components: filterComponents(component.components, filterFn),
+      }),
+    };
+  });
+}
+
+export function getCalloutComponents(
+  formSchema: SetCalloutFormSchema
+): (CalloutComponentSchema & { slideId: string; fullKey: string })[] {
+  return formSchema.slides.flatMap((slide) =>
+    flattenComponents(slide.components).map((component) => ({
+      ...component,
+      slideId: slide.id,
+      fullKey: `${slide.id}.${component.key}`,
+    }))
+  );
+}
+
+export function getCalloutFilters(
+  formSchema: SetCalloutFormSchema
+): Record<string, FilterArgs & { label: string }> {
+  const items = getCalloutComponents(formSchema)
+    .filter((c) => c.input)
+    .map((c) => [`answers.${c.fullKey}`, convertComponentToFilter(c)]);
+
+  return Object.fromEntries(items);
+}
+
+export function isAddressAnswer(
+  answer: CalloutResponseAnswer
+): answer is CalloutResponseAnswerAddress {
+  return !!answer && typeof answer === 'object' && 'geometry' in answer;
+}
+
+export function isFileUploadAnswer(
+  answer: CalloutResponseAnswer | undefined
+): answer is CalloutResponseAnswerFileUpload {
+  return !!answer && typeof answer === 'object' && 'url' in answer;
+}
+
+export function isFormioFileAnswer(
+  answer: CalloutResponseAnswer | undefined
+): answer is CalloutResponseAnswerFileUpload & FormioFile {
+  return (
+    !!answer &&
+    typeof answer === 'object' &&
+    'url' in answer &&
+    'storage' in answer &&
+    'name' in answer &&
+    'size' in answer
+    // Not defined on old files
+    // "hash" in answer &&
+    // "originalName" in answer
+  );
+}
+
+export function stringifyAnswer(
+  component: CalloutComponentSchema,
+  answer: CalloutResponseAnswer | CalloutResponseAnswer[] | undefined
+): string {
+  if (Array.isArray(answer)) {
+    return answer.map((a) => stringifyAnswer(component, a)).join(', ');
+  } else if (!answer) {
+    return '';
+  } else if (isAddressAnswer(answer)) {
+    return JSON.stringify(answer);
+  } else if (isFileUploadAnswer(answer)) {
+    return answer.url;
+  } else if (typeof answer === 'object') {
+    // Checkboxes
+    return Object.entries(answer)
+      .filter(([, selected]) => selected)
+      .map(([value]) => getSelectableLabelFromValue(component, value))
+      .join(', ');
+  } else if (typeof answer === 'string') {
+    return getSelectableLabelFromValue(component, answer);
+  } else {
+    return answer.toString();
+  }
+}
+
+/**
+ * Retrieves the value at a given path of a nested object, similar to lodash's `get` function.
+ *
+ * @param {object} obj - The object to query.
+ * @param {string} path - The path of the property to get, using dot notation (e.g., "a.b.c").
+ * @returns {unknown} - Returns the resolved value, or `undefined` if the path does not exist.
+ *
+ * @example
+ * // Example with a generic object:
+ * const data = { a: { b: { c: 42 } } };
+ * const value = getByPath(data, 'a.b.c');
+ * // value === 42
+ *
+ * // Example with a callout response object:
+ * const calloutResponse = {
+ *   answers: {
+ *     'slide1.input1': 'some answer',
+ *     'slide2.input2': 123
+ *   }
+ * };
+ * const answer = getByPath(calloutResponse, 'answers.slide1.input1');
+ * // answer === 'some answer'
+ */
+export function getByPath<T = unknown, R = unknown>(
+  obj: T,
+  path: string
+): R | undefined {
+  return path
+    .split('.')
+    .reduce<any>((acc, key) => (acc && key in acc ? acc[key] : undefined), obj);
+}

package/src/utils/conversions.ts

@@ -0,0 +1,40 @@
+import { isPhoneNumber } from './validations.js';
+
+/**
+ * Convert the value to a valid phone number
+ * @param value The value to convert
+ * @returns The valid phone number or null if the value is not a valid phone number
+ */
+export const toPhoneNumber = (value: unknown): string | false => {
+  if (typeof value !== 'string' || !value.length) {
+    return false;
+  }
+  const result = value.replace(/(?!^\+)\D/g, '');
+  if (!isPhoneNumber(result)) {
+    return false;
+  }
+  return result;
+};
+
+/**
+ * Convert the value to a valid bytes number.
+ * Note: This method ignores the text case of the unit, so b is always the same as B which means Byte and makes no different between Bytes and bits.
+ * This method can be used to convert `fileMinSize` and `fileMaxSize` of a callout file component to bytes.
+ * @param value E.g. "0KB", "1GB"
+ * @returns The valid bytes number or null if the value is not a valid bytes number.
+ */
+export const toBytes = (value: unknown): number | null => {
+  if (typeof value !== 'string' || !value.length) {
+    return null;
+  }
+  const lowerCase = value.toLowerCase();
+  const units = ['b', 'kb', 'mb', 'gb', 'tb', 'pb', 'eb', 'zb', 'yb'];
+  const [, num, unit] = lowerCase.match(/(\d+)(\w+)/)!;
+  const unitIndex = units.indexOf(unit.toLowerCase());
+
+  if (unitIndex === -1) {
+    return null;
+  }
+
+  return Number(num) * Math.pow(1024, unitIndex);
+};

package/src/utils/date.ts

@@ -0,0 +1,106 @@
+import {
+  add,
+  isValid,
+  parseISO,
+  startOfDay,
+  startOfHour,
+  startOfMinute,
+  startOfMonth,
+  startOfSecond,
+  startOfYear,
+} from 'date-fns';
+
+import type { DateUnit, Duration, UnitMatches } from '../types/index.js';
+
+// Must be ordered from highest resolution to lowest (seconds to years)
+export const dateUnits = ['s', 'm', 'h', 'd', 'M', 'y'] as const;
+
+export const dateUnitMap: Record<DateUnit, keyof Duration> = {
+  y: 'years',
+  M: 'months',
+  d: 'days',
+  h: 'hours',
+  m: 'minutes',
+  s: 'seconds',
+};
+
+const startOf: Record<DateUnit, (d: Date) => Date> = {
+  y: startOfYear,
+  M: startOfMonth,
+  d: startOfDay,
+  h: startOfHour,
+  m: startOfMinute,
+  s: startOfSecond,
+};
+
+const relativeDate = /^\$now(?<units>\(((y|M|d|h|m|s):(-?\d+),?)+\))?$/;
+const relativeUnit = /(y|M|d|h|m|s):(-?\d+)/g;
+
+// Matches the different parts of an ISO 8601 date. Note we don't validate the
+// pattern properly as that is handled by parseISO, we just want to know which
+// parts of the date were specified
+const absoluteDate =
+  /^(?<y>\d{4,})(-(?<M>\d\d)(-(?<d>\d\d)([T ](?<h>\d\d)(:(?<m>\d\d)(:(?<s>\d\d))?)?)?)?)?/;
+
+// Convert relative dates and returns the minimum date unit specified
+export function parseDate(
+  value: string,
+  now: Date = new Date()
+): [Date, DateUnit] {
+  let date: Date;
+  let units: DateUnit[];
+
+  const relativeMatch = relativeDate.exec(value);
+  if (relativeMatch) {
+    date = now;
+    const unitsGroup = relativeMatch.groups?.units;
+    if (unitsGroup) {
+      const unitMatches = unitsGroup.matchAll(relativeUnit) as UnitMatches;
+      units = [];
+      for (const [_, unit, delta] of unitMatches) {
+        date = add(date, { [dateUnitMap[unit]]: Number(delta) });
+        units.push(unit);
+      }
+    } else {
+      units = ['d'];
+    }
+  } else {
+    date = parseISO(value);
+    units = Object.entries(absoluteDate.exec(value)?.groups || {})
+      .filter(([_, n]) => !!n)
+      .map(([unit]) => unit) as DateUnit[];
+  }
+
+  const minUnit = getMinDateUnit(units) || 's';
+  return [startOf[minUnit](date), minUnit];
+}
+
+export function getMinDateUnit(units: [DateUnit, ...DateUnit[]]): DateUnit;
+export function getMinDateUnit(units: DateUnit[]): DateUnit | undefined;
+export function getMinDateUnit(units: DateUnit[]): DateUnit | undefined {
+  return dateUnits.find((unit) => units.includes(unit));
+}
+
+export function isValidDate(s: string | Date): boolean {
+  if (typeof s === 'string') {
+    return relativeDate.test(s) || isValid(parseISO(s));
+  }
+  return isValid(s);
+}
+
+export function isDateBetween(
+  date: string | Date,
+  start?: string | Date | null,
+  end?: string | Date | null
+): boolean {
+  let valid = isValidDate(date);
+  if (start) {
+    start = typeof start === 'string' ? parseISO(start) : start;
+    valid = valid && date >= start!;
+  }
+  if (end) {
+    end = typeof end === 'string' ? parseISO(end) : end;
+    valid = valid && date <= end!;
+  }
+  return valid;
+}

package/src/utils/debounce.ts

@@ -0,0 +1,77 @@
+/**
+ * Creates a debounced function that delays invoking the provided function
+ * until after the specified wait time has elapsed since the last time it was invoked.
+ *
+ * @param fn - The function to debounce
+ * @param wait - The number of milliseconds to delay
+ * @returns A debounced version of the function with a cancel method
+ */
+export function debounce<T extends (...args: any[]) => any>(
+  fn: T,
+  wait: number
+): ((...args: Parameters<T>) => void) & { cancel: () => void } {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  const debounced = function (...args: Parameters<T>) {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+    }
+
+    timeoutId = setTimeout(() => {
+      fn(...args);
+    }, wait);
+  };
+
+  debounced.cancel = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  };
+
+  return debounced;
+}
+
+/**
+ * Creates a throttled function that invokes the provided function at most once
+ * per specified wait time period.
+ *
+ * @param fn - The function to throttle
+ * @param wait - The number of milliseconds to wait between invocations
+ * @returns A throttled version of the function with a cancel method
+ */
+export function throttle<T extends (...args: any[]) => any>(
+  fn: T,
+  wait: number
+): ((...args: Parameters<T>) => void) & { cancel: () => void } {
+  let lastCallTime = 0;
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  const throttled = function (...args: Parameters<T>) {
+    const now = Date.now();
+    const timeSinceLastCall = now - lastCallTime;
+
+    if (timeSinceLastCall >= wait) {
+      lastCallTime = now;
+      fn(...args);
+    } else {
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+      }
+
+      timeoutId = setTimeout(() => {
+        lastCallTime = Date.now();
+        fn(...args);
+      }, wait - timeSinceLastCall);
+    }
+  };
+
+  throttled.cancel = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  };
+
+  return throttled;
+}

package/src/utils/file.ts

@@ -0,0 +1,79 @@
+import {
+  ALLOWED_DOCUMENT_EXTENSIONS,
+  ALLOWED_DOCUMENT_MIME_TYPES,
+  ALLOWED_IMAGE_EXTENSIONS,
+  ALLOWED_IMAGE_MIME_TYPES,
+} from '../constants.js';
+
+/**
+ * Check if a MIME type is a supported document type.
+ * Example: "application/pdf"
+ * @param mimetype MIME type to check
+ * @returns True if it's a supported document type
+ */
+export const isSupportedDocumentType = (mimetype?: string): boolean => {
+  if (!mimetype) return false;
+  return ALLOWED_DOCUMENT_MIME_TYPES.includes(mimetype.toLowerCase().trim());
+};
+
+/**
+ * Check if an extension is a supported document extension.
+ * Example: "pdf"
+ * @param extension Extension to check
+ * @returns True if it's a supported document extension
+ */
+export const isSupportedDocumentExtension = (extension?: string): boolean => {
+  if (!extension) return false;
+  return ALLOWED_DOCUMENT_EXTENSIONS.includes(extension.toLowerCase().trim());
+};
+
+/**
+ * Check if a MIME type is a supported image type.
+ * Example: "image/jpeg", "image/png", "image/webp", "image/avif"
+ * @param mimetype MIME type to check
+ * @returns True if it's a supported image type
+ */
+export const isSupportedImageType = (mimetype?: string): boolean => {
+  if (!mimetype) return false;
+  return ALLOWED_IMAGE_MIME_TYPES.includes(mimetype.toLowerCase().trim());
+};
+
+/**
+ * Check if an extension is a supported image extension.
+ * Example: "jpg", "png", "webp", "avif"
+ * @param extension Extension to check
+ * @returns True if it's a supported image extension
+ */
+export const isSupportedImageExtension = (extension?: string): boolean => {
+  if (!extension) return false;
+  return ALLOWED_IMAGE_EXTENSIONS.includes(extension.toLowerCase().trim());
+};
+
+/**
+ * Converts byte size to a human-readable string representation
+ *
+ * This function takes a size in bytes and converts it to a human-readable
+ * format with appropriate units (B, KB, MB, GB, TB). The result is formatted
+ * with two decimal places.
+ *
+ * @param bytes - The file size in bytes to convert
+ * @returns A formatted string with size and unit (e.g., "15.50 MB")
+ *
+ * @example
+ * ```ts
+ * bytesToHumanReadable(1500000); // "1.43 MB"
+ * bytesToHumanReadable(1024);    // "1.00 KB"
+ * ```
+ */
+export const bytesToHumanReadable = (bytes: number): string => {
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let index = 0;
+  let value = bytes;
+
+  while (value >= 1024 && index < units.length - 1) {
+    value /= 1024;
+    index++;
+  }
+
+  return `${value.toFixed(2)} ${units[index]}`;
+};

package/src/utils/index.ts

@@ -0,0 +1,11 @@
+// Auto-generated by `@beabee/dev-cli generate-index`. Do not edit by hand.
+export * from './callouts.js';
+export * from './conversions.js';
+export * from './date.js';
+export * from './debounce.js';
+export * from './file.js';
+export * from './payments.js';
+export * from './rules.js';
+export * from './slug.js';
+export * from './url.js';
+export * from './validations.js';

package/src/utils/payments.ts

@@ -0,0 +1,51 @@
+import { ContributionPeriod, PaymentMethod } from '../data/index.js';
+import type { Feeable, StripeFeeCountry } from '../types/index.js';
+
+const stripeFees = {
+  gb: {
+    [PaymentMethod.StripeCard]: (amount: number) => 0.2 + 0.015 * amount,
+    [PaymentMethod.StripeSEPA]: () => 0.3,
+    [PaymentMethod.StripeBACS]: (amount: number) =>
+      Math.min(2, Math.max(0.2, 0.01 * amount)),
+    [PaymentMethod.StripePayPal]: (amount: number) => 0.1 + 0.02 * amount,
+    [PaymentMethod.StripeIdeal]: () => 0.3, // Becomes a SEPA so same fee
+  },
+  eu: {
+    [PaymentMethod.StripeCard]: (amount: number) => 0.25 + 0.015 * amount,
+    [PaymentMethod.StripeSEPA]: () => 0.35,
+    [PaymentMethod.StripeBACS]: () => 0, // Not available
+    [PaymentMethod.StripePayPal]: (amount: number) => 0.1 + 0.02 * amount,
+    [PaymentMethod.StripeIdeal]: () => 0.35, // Becomes a SEPA so same fee
+  },
+  ca: {
+    [PaymentMethod.StripeCard]: (amount: number) => 0.3 + 0.029 * amount,
+    [PaymentMethod.StripeSEPA]: () => 0, // Not available
+    [PaymentMethod.StripeBACS]: () => 0, // Not available
+    [PaymentMethod.StripePayPal]: () => 0, // Not available
+    [PaymentMethod.StripeIdeal]: () => 0, // Not available
+  },
+} as const;
+
+const gcFee = (amount: number) => 0.2 + amount * 0.01;
+
+export function calcPaymentFee(
+  feeable: Feeable,
+  country: StripeFeeCountry
+): number {
+  const feeFn =
+    feeable.paymentMethod === PaymentMethod.GoCardlessDirectDebit
+      ? gcFee
+      : stripeFees[country][feeable.paymentMethod];
+
+  if (!feeFn) {
+    const error = new Error(
+      `No fee function found for "${feeable.paymentMethod}" in "${country}". Please check that the payment methods have been configured correctly.`
+    );
+    console.error(error);
+    return 0;
+  }
+
+  return feeable.period === ContributionPeriod.Annually
+    ? 0
+    : feeFn(feeable.amount);
+}