@dev.smartpricing/message-composer-layer 4.5.1-next.2 → 5.0.0-automations.0

package/app/utils/automations/form.ts

@@ -0,0 +1,368 @@
+import type {
+  Automation,
+  AutomationAction,
+  AutomationActionConfig,
+  AutomationActionInput,
+  AutomationActionStatus,
+  AutomationChannel,
+  AutomationPartlySavedDetails,
+  AutomationSaveProblem,
+  AutomationTrigger,
+  Condition,
+  CreateAutomationBody,
+  DateReferenceDirection,
+  UpdateAutomationBody,
+} from '@dev.smartpricing/message-composer-utils/types'
+import { automationMetadataForm, metadataFormValue } from './metadata'
+
+/**
+ * The Automation form's own model and what it turns into on a save. The
+ * engine's shapes (a delay in signed seconds, `template` for a Message Group)
+ * stay in here.
+ */
+
+export const SECONDS_PER_DAY = 24 * 60 * 60
+
+export const DEFAULT_SENDING_TIME = '09:00:00Z'
+
+export const AUTOMATION_RECURRENCES = ['daily', 'monthly', 'yearly'] as const
+
+export type AutomationRecurrence = (typeof AUTOMATION_RECURRENCES)[number]
+
+export interface AutomationFormAction {
+  /**
+   * What the form tells its Actions apart by. It is the layer's alone: an
+   * Action that is not saved yet has no `id`, and this is never sent as one.
+   */
+  key: string
+  /** The id of the stored Action; none while the Action is not saved yet. */
+  id?: string
+  /**
+   * The `config` of the stored Action. The form shows only part of it: the
+   * rest goes back as it is on a save.
+   */
+  storedConfig?: AutomationActionConfig
+  status: AutomationActionStatus
+  channel: AutomationChannel
+  messageGroupId: string
+  messageGroupName: string
+  /** The key of the Date Reference the delay counts from. */
+  dateReference: string
+  direction: DateReferenceDirection
+  /** The delay, in whole days before or after the Date Reference. */
+  days: number
+  sendingTimeUTC: string
+  recurrence?: AutomationRecurrence
+  strictDelay: boolean
+  preventDuplicates: boolean
+}
+
+export interface AutomationFormState {
+  name: string
+  triggerType: string
+  conditions: Condition[]
+  actions: AutomationFormAction[]
+  /** The values the Automation asks for (`metadata.form`), by the key of their field. */
+  data: Record<string, string>
+}
+
+/**
+ * A copy the form can change freely. The form's state is plain data, and it
+ * can hold Vue proxies, which `structuredClone` refuses.
+ */
+export function cloneFormData<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T
+}
+
+/** A new Automation starts from its Trigger's default Conditions (ADR 0017). */
+export function newAutomationForm(trigger: AutomationTrigger): AutomationFormState {
+  return {
+    name: '',
+    triggerType: trigger.type,
+    conditions: cloneFormData(trigger.default_conditions),
+    actions: [],
+    data: {},
+  }
+}
+
+export function newAutomationFormAction(
+  trigger: AutomationTrigger,
+  channel: AutomationChannel,
+): AutomationFormAction {
+  const dateReference = trigger.date_references[0]
+
+  return {
+    key: crypto.randomUUID(),
+    status: 'active',
+    channel,
+    messageGroupId: '',
+    messageGroupName: '',
+    dateReference: dateReference?.key ?? '',
+    direction: dateReference?.directions[0]?.direction ?? 'after',
+    days: 0,
+    sendingTimeUTC: DEFAULT_SENDING_TIME,
+    strictDelay: false,
+    preventDuplicates: true,
+  }
+}
+
+/** The one Trigger the form edits: the Automation Engine can hold several, the pages write one. */
+function triggerTypeOf(automation: Automation): string {
+  return [automation.settings.trigger.type].flat()[0] ?? ''
+}
+
+/** What the form shows of an Action's `config`. */
+type AutomationFormSchedule = Omit<AutomationFormAction, 'key' | 'id' | 'storedConfig' | 'status'>
+
+function toFormSchedule(config: AutomationActionConfig): AutomationFormSchedule {
+  const delay = typeof config.delay === 'number' ? config.delay : 0
+  // The sign of the delay is its direction; `delayDirection` keeps it at 0.
+  const direction =
+    delay < 0 || (delay === 0 && config.delayDirection === 'before') ? 'before' : 'after'
+
+  return {
+    channel: config.channel as AutomationChannel,
+    messageGroupId: config.template,
+    messageGroupName: typeof config.templateName === 'string' ? config.templateName : '',
+    dateReference: typeof config.dateTimeReference === 'string' ? config.dateTimeReference : '',
+    direction,
+    days: Math.abs(delay) / SECONDS_PER_DAY,
+    sendingTimeUTC:
+      typeof config.sendingTimeUTC === 'string' ? config.sendingTimeUTC : DEFAULT_SENDING_TIME,
+    recurrence: AUTOMATION_RECURRENCES.find((recurrence) => recurrence === config.recurrence),
+    strictDelay: config.strictDelay === true,
+    preventDuplicates: config.preventDuplicates === true,
+  }
+}
+
+function toFormAction({ id, status, config }: AutomationAction): AutomationFormAction {
+  return { key: id, id, storedConfig: config, status, ...toFormSchedule(config) }
+}
+
+/** A stored Automation in the form. Its Conditions come as they are (ADR 0018). */
+export function toAutomationForm(automation: Automation): AutomationFormState {
+  return cloneFormData({
+    name: automation.name,
+    triggerType: triggerTypeOf(automation),
+    conditions: automation.settings.conditions as Condition[],
+    actions: automation.actions.map(toFormAction),
+    data: Object.fromEntries(
+      (automationMetadataForm(automation.metadata)?.fields ?? []).map(({ key }) => [
+        key,
+        metadataFormValue(automation.metadata, key),
+      ]),
+    ),
+  })
+}
+
+/** "before:checkinDate": a Date Reference and the direction of the delay, as one select value. */
+export function dateReferenceValue(reference: {
+  direction: DateReferenceDirection
+  dateReference: string
+}): string {
+  return `${reference.direction}:${reference.dateReference}`
+}
+
+export function parseDateReferenceValue(value: string): {
+  direction: DateReferenceDirection
+  dateReference: string
+} {
+  const separator = value.indexOf(':')
+  return {
+    direction: value.slice(0, separator) === 'before' ? 'before' : 'after',
+    dateReference: value.slice(separator + 1),
+  }
+}
+
+/** The label of an Action's Date Reference; its key when the Trigger no longer lists it. */
+export function dateReferenceLabel(action: AutomationFormAction, trigger: AutomationTrigger) {
+  return (
+    trigger.date_references
+      .find((reference) => reference.key === action.dateReference)
+      ?.directions.find((entry) => entry.direction === action.direction)?.label ??
+    action.dateReference
+  )
+}
+
+/** The sending time on the user's clock: the engine keeps it in UTC. */
+export function localSendingTime(sendingTimeUTC: string): string {
+  return new Date(`2000-01-01T${sendingTimeUTC}`).toLocaleTimeString([], {
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  })
+}
+
+function toActionConfig(action: AutomationFormSchedule): AutomationActionInput['config'] {
+  // The sign of the delay is its direction; `delayDirection` keeps it at 0.
+  const delay =
+    action.direction === 'before' ? -action.days * SECONDS_PER_DAY : action.days * SECONDS_PER_DAY
+
+  return {
+    template: action.messageGroupId,
+    templateName: action.messageGroupName,
+    channel: action.channel,
+    delay: delay || 0,
+    dateTimeReference: action.dateReference,
+    delayDirection: action.days === 0 ? action.direction : undefined,
+    sendingTimeUTC: action.sendingTimeUTC,
+    recurrence: action.recurrence,
+    strictDelay: action.strictDelay || undefined,
+    preventDuplicates: action.preventDuplicates,
+  }
+}
+
+/**
+ * A stored Action goes back with its `config` as stored, and over it only
+ * what the user changed: the form shows a default where the `config` has no
+ * value (no sending time, no name), and a default written back would change
+ * an Action the user did not touch.
+ */
+function toActionInput(action: AutomationFormAction): AutomationActionInput {
+  const config = toActionConfig(action)
+  const { storedConfig } = action
+  if (!storedConfig) return { status: action.status, config }
+
+  const unchanged = toActionConfig(toFormSchedule(storedConfig))
+  const changes = Object.fromEntries(
+    Object.entries(config).filter(([key, value]) => value !== unchanged[key]),
+  )
+  return {
+    status: action.status,
+    config: {
+      ...storedConfig,
+      channel: config.channel,
+      dateTimeReference: config.dateTimeReference,
+      ...changes,
+    },
+  }
+}
+
+/** A create without its scope: the mutation names the Organization and the Product. */
+export type NewAutomation = Omit<CreateAutomationBody, 'organization_id' | 'product'>
+
+/**
+ * The body of a create. No recipient, sender or trigger source: the backend
+ * writes them (ADR 0017).
+ */
+export function toCreateAutomationBody(form: AutomationFormState): NewAutomation {
+  return {
+    name: form.name.trim(),
+    settings: {
+      trigger: { type: form.triggerType },
+      conditions: form.conditions,
+    },
+    actions: form.actions.map(toActionInput),
+  }
+}
+
+/** An update without its Product: the mutation names it, and the Automation by its id. */
+export type AutomationChanges = Omit<UpdateAutomationBody, 'product'>
+
+/**
+ * The body of an update of `stored`: every Action the form holds, a stored
+ * one with its `id` and a new one without (ADR 0016). What `settings` holds
+ * that the form does not show goes back as stored. Of `metadata` only the
+ * asked-for values the user changed are sent: the backend merges them into
+ * the stored one, and keeps the rest.
+ */
+export function toUpdateAutomationBody(
+  form: AutomationFormState,
+  stored: Automation,
+): AutomationChanges {
+  const sameTrigger = triggerTypeOf(stored) === form.triggerType
+  const changedData = Object.entries(form.data).filter(
+    ([key, value]) => value !== metadataFormValue(stored.metadata, key),
+  )
+
+  return {
+    name: form.name.trim(),
+    ...(changedData.length > 0 && { metadata: Object.fromEntries(changedData) }),
+    settings: {
+      ...stored.settings,
+      trigger: { ...(sameTrigger && stored.settings.trigger), type: form.triggerType },
+      conditions: form.conditions,
+    },
+    actions: form.actions.map((action) => ({ ...toActionInput(action), id: action.id })),
+  }
+}
+
+/**
+ * The properties of `Automation setup`, as Smartconnect's pages send them.
+ * `trigger` is the form's, when the Automation Catalog still lists it.
+ */
+export function automationSetupProperties(
+  form: AutomationFormState,
+  trigger: AutomationTrigger | undefined,
+) {
+  const action = form.actions[0]
+  const dateReference = action?.dateReference ?? ''
+
+  return {
+    // The backend writes the sender: this is the template it will write.
+    automation_sender:
+      trigger?.channels.find((entry) => entry.channel === action?.channel)?.sender ?? '',
+    automation_name: form.name.trim(),
+    automation_trigger: form.triggerType,
+    automation_type: dateReference,
+    automation_rules_audience: form.conditions.length > 0 ? 'segmented' : 'all',
+    automation_subject: action?.messageGroupName ?? '',
+    automation_moment: dateReference,
+    automation_channel: action?.channel ?? '',
+    automation_status: action?.status ?? '',
+    automation_days: action?.days ?? 0,
+    created_by: 'user',
+  } as const
+}
+
+/**
+ * The `problems` of a refused save (422 `AUTOMATION_ACTIONS_INVALID`), or
+ * `undefined` for any other error. The entries are not checked one by one: a
+ * client skips a `target` or a `reason` it does not know.
+ */
+export function automationSaveProblems(error: unknown): AutomationSaveProblem[] | undefined {
+  const data = (error as { data?: { code?: unknown; details?: { problems?: unknown } } } | null)
+    ?.data
+  if (data?.code !== 'AUTOMATION_ACTIONS_INVALID') return undefined
+
+  const problems = data.details?.problems
+  return Array.isArray(problems) ? (problems as AutomationSaveProblem[]) : []
+}
+
+/**
+ * What the Automation Engine holds after an update that was saved only in
+ * part (502 `UPSTREAM_ERROR` with the current state, ADR 0016), or
+ * `undefined` for any other error.
+ */
+export function automationPartlySaved(error: unknown): AutomationPartlySavedDetails | undefined {
+  const data = (
+    error as {
+      data?: { code?: unknown; details?: Partial<AutomationPartlySavedDetails> }
+    } | null
+  )?.data
+  const details = data?.details
+  if (data?.code !== 'UPSTREAM_ERROR') return undefined
+  if (!details?.automation?.id || !Array.isArray(details.action_ids)) return undefined
+
+  return details as AutomationPartlySavedDetails
+}
+
+/**
+ * The form's Actions after an update that was saved only in part. Each
+ * Action of `sent`, the list that was submitted, takes the id and the stored
+ * `config` the Automation Engine now has for it, so that saving again creates
+ * nothing twice. What the user sees and typed is not touched.
+ */
+export function withPartlySavedActions(
+  actions: AutomationFormAction[],
+  sent: AutomationFormAction[],
+  { automation, action_ids }: AutomationPartlySavedDetails,
+): AutomationFormAction[] {
+  const idByKey = new Map(sent.map((action, position) => [action.key, action_ids[position]]))
+
+  return actions.map((action) => {
+    const id = idByKey.get(action.key)
+    const stored = automation.actions.find((candidate) => candidate.id === id)
+    return stored ? { ...action, id: stored.id, storedConfig: stored.config } : action
+  })
+}

package/app/utils/automations/metadata.ts

@@ -0,0 +1,71 @@
+import type { Automation } from '@dev.smartpricing/message-composer-utils/types'
+
+/**
+ * What the pages read of an Automation's `metadata`, the Automation Engine's
+ * free JSON: whether it is a System Automation, and the values it asks its
+ * user for.
+ */
+
+type AutomationMetadata = Automation['metadata']
+
+/**
+ * Whether the Automation is a System Automation: one its Host created, whose
+ * user can only activate its Actions and fill in what it asks for (ADR 0016).
+ * The one place in the layer that reads the marker.
+ */
+export function isSystemAutomation(automation: { metadata?: AutomationMetadata }): boolean {
+  return automation.metadata?.locked === true
+}
+
+/**
+ * One value an Automation asks its user for. Its label is the Host's text,
+ * or a key of the Host's translations, and whatever its stored `type` it is a line of text, as in Smartconnect.
+ */
+export interface AutomationMetadataFormField {
+  /** The metadata key the value is stored under. */
+  key: string
+  label: string
+  /** Shown on the field. Nothing stops a save over it, as in Smartconnect. */
+  required: boolean
+}
+
+export interface AutomationMetadataForm {
+  description?: string
+  fields: AutomationMetadataFormField[]
+}
+
+/**
+ * The stored `metadata.form`, or `undefined` when the Automation asks for
+ * nothing. Whoever seeded the Automation wrote it: what is not a field with a
+ * key is skipped, not refused.
+ */
+export function automationMetadataForm(
+  metadata: AutomationMetadata,
+): AutomationMetadataForm | undefined {
+  const form = metadata?.form as { description?: unknown; fields?: unknown } | null | undefined
+  if (typeof form !== 'object' || form === null || !Array.isArray(form.fields)) return undefined
+
+  const fields = form.fields.flatMap((field: unknown): AutomationMetadataFormField[] => {
+    const { key, label, required } = (field ?? {}) as Record<string, unknown>
+    if (typeof key !== 'string' || !key) return []
+    return [
+      {
+        key,
+        label: typeof label === 'string' ? label : key,
+        required: required === true,
+      },
+    ]
+  })
+  if (fields.length === 0) return undefined
+
+  return {
+    description: typeof form.description === 'string' ? form.description : undefined,
+    fields,
+  }
+}
+
+/** A stored value as the form's text input shows it; empty when there is none. */
+export function metadataFormValue(metadata: AutomationMetadata, key: string): string {
+  const value = metadata?.[key]
+  return value === undefined || value === null ? '' : String(value)
+}

package/app/utils/automations/unavailable.ts

@@ -0,0 +1,90 @@
+import type {
+  AutomationChannel,
+  AutomationTrigger,
+} from '@dev.smartpricing/message-composer-utils/types'
+import type { AutomationFormAction } from './form'
+
+/**
+ * What an Automation can hold that is no longer available, and which of it
+ * stops a save. Nothing is dropped or rewritten: a thing that only stays is
+ * "kept", and the user is told.
+ */
+
+export type AutomationUnavailableKind =
+  | 'trigger'
+  | 'date_reference'
+  | 'condition_unknown_field'
+  | 'condition_not_editable'
+  | 'option'
+  | 'channel'
+  | 'message_group_inactive'
+  | 'message_group_active'
+
+/** The kinds a save does not go through with. Every other one is kept. */
+const BLOCKING_KINDS: readonly AutomationUnavailableKind[] = [
+  'trigger',
+  'date_reference',
+  'condition_unknown_field',
+  'message_group_active',
+]
+
+export function unavailableBlocks(kind: AutomationUnavailableKind): boolean {
+  return BLOCKING_KINDS.includes(kind)
+}
+
+/** One unavailable thing, as the alert lists it and as its badge says it. */
+export interface AutomationUnavailableItem {
+  /** Tells the items of one list apart. */
+  key: string
+  kind: AutomationUnavailableKind
+  blocks: boolean
+  /** Where the thing is: "Trigger", `Message "Welcome"`. */
+  where: string
+  /** The full sentence: what is wrong and what to do. */
+  text: string
+  /** The id of the element the thing is at. */
+  target?: string
+  /** The thing is a Condition: showing it opens the filter editor. */
+  inFilters?: boolean
+}
+
+/** What tells whether an Action holds something unavailable. */
+export interface ActionAvailability {
+  trigger: AutomationTrigger
+  /** The Channels the Organization cannot use. */
+  unusableChannels: readonly AutomationChannel[]
+  /**
+   * Whether a Message Group is approved in every language, by its id in lower
+   * case. One that is not in there is not known yet, or could not be read:
+   * it is not taken for unapproved.
+   */
+  approvals: ReadonlyMap<string, boolean> | undefined
+}
+
+export function isDateReferenceListed(
+  action: AutomationFormAction,
+  trigger: AutomationTrigger,
+): boolean {
+  return trigger.date_references.some(({ key }) => key === action.dateReference)
+}
+
+/** The unavailable things one Action holds, in the order they are shown. */
+export function actionUnavailableKinds(
+  action: AutomationFormAction,
+  { trigger, unusableChannels, approvals }: ActionAvailability,
+): AutomationUnavailableKind[] {
+  const kinds: AutomationUnavailableKind[] = []
+
+  if (!isDateReferenceListed(action, trigger)) kinds.push('date_reference')
+
+  // An Action on a Channel that cannot be used is not sent and shows as not
+  // Active, with a switch that does not work: it is never asked to be turned off.
+  const unusableChannel = unusableChannels.includes(action.channel)
+  if (unusableChannel) kinds.push('channel')
+  if (approvals?.get(action.messageGroupId.toLowerCase()) === false) {
+    const active = action.status === 'active' && !unusableChannel
+    kinds.push(active ? 'message_group_active' : 'message_group_inactive')
+  }
+
+  return kinds
+}