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

package/README.md

@@ -2,7 +2,7 @@
 
 The Message Composer as a [Nuxt layer](https://nuxt.com/docs/getting-started/layers). A host app extends it and gets the composer pages (message library, editor, preview, brands, images) plus embeddable components such as the **Message Send Flow**.
 
-The layer is published on the private Smartpricing npm registry together with `@dev.smartpricing/message-composer-utils` (shared types and helpers, subpath exports `/types` and `/utils`). Both packages share one version number.
+The layer is published on the private Smartpricing npm registry together with `@dev.smartpricing/message-composer-utils` (shared types, helpers and Zod schemas, subpath exports `/types`, `/utils` and `/schemas`). Both packages share one version number.
 
 ## Host setup
 
@@ -55,7 +55,7 @@ The layer is published on the private Smartpricing npm registry together with `@
 
 4. Tracking is opt-in: set `composer.tracking: true` in the host's `app.config.ts` to have the layer post its events to `POST /tracking/event`.
 
-The layer's pages are mounted at root (`/`, `/template/...`, `/preview/...`, `/brands`, `/images`). Remap them with `pages:extend` if the host already owns those routes.
+The layer's pages are mounted at root (`/`, `/template/...`, `/preview/...`, `/brands`, `/images`). Remap them with `pages:extend` if the host already owns those routes. The Automation pages (`/automations/...`) are mounted too and answer 404 until the Host turns them on: see "Automation pages" below.
 
 ## Organization and WABA
 
@@ -85,7 +85,7 @@ watch(
 )
 ```
 
-**WABA.** The Host does not supply the WABA: the WABAs follow the Organization and the backend resolves them (ADR [0015](../../docs/adr/0015-message-group-waba-fixed-at-first-submission.md)). WhatsApp is configured when the Host's `channels` include `whatsapp` and the Organization has at least one WABA. A Message Group is submitted to one WABA, chosen at its first submission and fixed from then on; with several WABAs the user picks one when requesting approval. `metaWabaId` in the context is optional and is only the preselection in that picker. A Host that sends from one WABA only also sets `metaWabaLocked: ref(true)`: a new Message Group is then submitted to `metaWabaId` without asking, as long as it is one of the Organization's WABAs.
+**WABA.** The Host does not supply the WABA: the WABAs follow the Organization and the backend resolves them (ADR [0015](../../docs/adr/0015-message-group-waba-fixed-at-first-submission.md)). WhatsApp is configured when the Host's `channels` include `whatsapp` and the Organization has at least one WABA. A Message Group is submitted to one WABA, chosen at its first submission and fixed from then on; with several WABAs the user picks one when requesting approval. `metaWabaId` in the context is optional and is only the preselection in that picker.
 
 ### Upgrading to 4.5.0
 
@@ -237,6 +237,135 @@ With tracking enabled the flow reports `send_flow.confirm` (`message_name`, `mes
 
 `apps/frontend` (this monorepo's standalone host) has a permanent `/debug/send-flow` page that plays the host: preselect, preferred language, prefill JSON, brand id, the flow's own Organization and WABA, inline or modal container, remount, and a log of every emit.
 
+## Automation pages
+
+Three pages list, create and edit the Automations of the Host's Product. The Automations live in the Automation Engine and the composer backend is the only way to them (ADR [0016](../../docs/adr/0016-automations-live-in-the-automation-engine.md)). The pages are off until a Host turns them on (ADR [0019](../../docs/adr/0019-automation-pages-off-until-a-host-turns-them-on.md)): an upgrade changes nothing for a Host that does not set the flag.
+
+1. Turn them on in the Host's `app.config.ts`, next to `composer.tracking`:
+
+   ```ts
+   export default defineAppConfig({
+     composer: { automations: true },
+   })
+   ```
+
+   The routes always exist. While the flag is off, a layer middleware on those pages answers 404. The flag is static: a Host that wants the pages for some Organizations only does it with its own guard.
+
+2. Provide the Automations context before an Automation page renders (`app.vue` or a plugin), as `defineComposerContext()` and apart from it:
+
+   ```vue
+   <script setup lang="ts">
+   const { countries, languages } = useBuiltInOptionLists()
+   const tags = ref<AutomationOption[]>([]) // fetched and kept current by the Host
+
+   defineAutomationsContext({
+     optionLists: computed(() => ({
+       countries: countries.value,
+       languages: languages.value,
+       tags: tags.value,
+     })),
+     currency: ref('EUR'),
+   })
+   </script>
+   ```
+
+### Routes
+
+| Route name          | Path               | Page                                                                                  |
+| ------------------- | ------------------ | ------------------------------------------------------------------------------------- |
+| `automations-list`  | `/automations`     | The Automations of the Host's Product. Clone and delete are actions here, not routes. |
+| `automation-create` | `/automations/new` | A new Automation.                                                                     |
+| `automation-edit`   | `/automations/:id` | An existing Automation; a clone opens here.                                           |
+
+Link to them by name. The paths are the Host's to remap in `pages:extend`, and the Automation pages may sit under a different prefix than the Message pages: every link between them and the Message editor is by route name.
+
+### `defineAutomationsContext(context)`
+
+`AutomationsContext` and `AutomationOption` live in `app/composables/automationsContext.ts`.
+
+| Key           | Type                                      | Description                                                                                                                                                                                                                                                   |
+| ------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `optionLists` | `Ref<Record<string, AutomationOption[]>>` | Required. The option lists, by the name the Automation Catalog gives them (the `option_list` of a Condition Field). An `AutomationOption` is `{ value: string \| number, label: string }`, label already translated. A list that is not there shows as empty. |
+| `currency`    | `Ref<string \| undefined>`                | Optional. ISO code of the currency `price` fields show; EUR when absent. Never a conversion.                                                                                                                                                                  |
+
+The Automation Catalog holds no option: every list is the Host's (ADR [0017](../../docs/adr/0017-automation-catalog-served-by-the-backend.md)). There are no loader callbacks: the Host fetches the lists and keeps the refs current. Countries and languages can come from `useBuiltInOptionLists()`.
+
+### What a page needs to work
+
+An Automation page checks three things inside the page, not in the layout, so a Host that replaces the layout keeps the check:
+
+1. **The Automations context**: `defineAutomationsContext()` was called.
+2. **An Automation Catalog for the Host's Product**: the backend serves one for the `product` of the composer context.
+3. **An Organization**: the layer resolved one (see "Organization and WABA").
+
+With the flag on and one of them missing, the page keeps its header and shows an error alert in place of its content. A failed Organization lookup or a failed catalog request shows the same alert with a retry.
+
+The layer ships **no permission check** on these pages: the Host guards them as it guards the Message pages.
+
+A Host sees only the Automations of its own Product. The Channels an Action can send over are the ones the catalog gives its Trigger, limited to the `channels` of the composer context, and WhatsApp only when the Organization has a WABA.
+
+### Public and stable
+
+This is the host contract for Automations:
+
+- the `composer.automations` flag;
+- the three route names: `automations-list`, `automation-create`, `automation-edit`;
+- `defineAutomationsContext()` and the shape of `AutomationsContext`;
+- `FiltersEditor` and `FiltersSummary`, with their props and emits;
+- the `fields` shape and the report: `FilterField`, `FilterOption`, `FiltersReport`;
+- `useBuiltInOptionLists()`;
+- the shared schemas in `@dev.smartpricing/message-composer-utils/schemas`: the Condition schemas (`conditionSchema`, `conditionOperatorSchema`, `conditionFieldTypeSchema`), the request and response schemas of the Automation routes and of the Automation Catalog, and with them the operator table `CONDITION_OPERATORS_BY_FIELD_TYPE` (in `/types`).
+
+The semver promise (ADRs [0018](../../docs/adr/0018-filter-components-speak-conditions-and-know-no-catalog.md) and [0019](../../docs/adr/0019-automation-pages-off-until-a-host-turns-them-on.md)):
+
+- **Major**: renaming or removing a route name; removing or renaming a prop of a filter component; changing the shape of the value (`Condition[]`); dropping a field type or an operator.
+- **Minor**: adding a prop, a field type or an operator.
+- **No promise**: the paths (the Host's to remap), everything else under `app/components/Filters/` and `app/utils/filters/`, and the test-id pattern. They can change in any release. The components and utils of the pages themselves (`app/components/Automations/`, `app/utils/automations/`) are not on the list above.
+
+The flag, the context and the shared schemas are host contract with no rule of their own in the ADRs: the general one applies (see "Release": a change to the host contract is a major).
+
+## Filter components
+
+Two props-only components edit and show a list of Conditions in the Automation Engine's shape (`{ field, operator, value? }`), on any page: they read neither the Automation Catalog nor the Host's context ([ADR 0018](../../docs/adr/0018-filter-components-speak-conditions-and-know-no-catalog.md)). The slideover, Save and Cancel around the editor belong to the page.
+
+```vue
+<script setup lang="ts">
+import type {
+  Condition,
+  FilterField,
+  FiltersReport,
+} from '@dev.smartpricing/message-composer-utils/types'
+
+const { countries } = useBuiltInOptionLists()
+
+const fields = computed<FilterField[]>(() => [
+  { key: 'guest.country', label: t('country'), type: 'multiselect', options: countries.value },
+  { key: 'totalPrice', label: t('total_price'), type: 'price' },
+])
+const conditions = ref<Condition[]>([])
+const report = ref<FiltersReport>()
+</script>
+
+<template>
+  <FiltersEditor v-model="conditions" :fields="fields" title="Audience" @report="report = $event" />
+  <FiltersSummary :model-value="conditions" :fields="fields" />
+</template>
+```
+
+| Auto-import name          | Props                                                                                                          | Emits                         |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `FiltersEditor`           | `v-model` (`Condition[]`), `fields`, `currency?`, `title?`, `subtitle?`, `testIdPrefix?`                       | `update:modelValue`, `report` |
+| `FiltersSummary`          | `modelValue` (`Condition[]`), `fields`, `currency?`, `preview?` (lines before "View more", 3), `testIdPrefix?` | `report`                      |
+| `useBuiltInOptionLists()` | returns `countries` and `languages`: option lists in the current language, values are lowercase ISO codes      | -                             |
+
+- **`fields`** is one reactive list of `{ key, label, type, options? }`, labels and options already resolved, in display order. `type` is one of `select`, `multiselect`, `number`, `price`, `date`, `text`; the operators of each are `CONDITION_OPERATORS_BY_FIELD_TYPE` in `message-composer-utils`. A field can be picked once.
+- **Values**: a `price` is stored in cents and shown in `currency` (EUR when absent, never converted); a `date` is `YYYY-MM-DD`. "Between" is a `gte` and an `lte` on the same field. There is no "not between": the Automation Engine holds all the Conditions of a list together, so no pair of them can say "outside this range". A stored `lte` below a `gte` on one field shows as one editable row and one unavailable row.
+- **Nothing is dropped.** A Condition on a field that is not in `fields`, with an operator or a value that does not fit the field's type, or one too many on a field, shows as an unavailable row: emitted as it came in until the user removes it. A selected option that is not in `options` shows as unavailable and is kept the same way. A row the user did not touch is emitted exactly as stored.
+- **`report`** (`FiltersReport`, emitted on mount and on every change): `unknownFields`, `unavailable` (each Condition with its reason, `unknown_field` or `not_editable`), `unavailableOptions`, and `halfFilled`, the rows with a field and no complete value. A half-filled row is never in the emitted value. The components block nothing: the caller decides what stops a save.
+- **Rows in progress** live in the editor only. It reads its rows again when the Conditions change from outside or when the keys or types in `fields` change, and rows in progress are then lost. Setting `v-model` to the value it already has does not reset them: to start over, remount the editor with a `key`.
+- **Stability**: the two components, the `fields` shape, the report (`FilterField`, `FilterOption` and `FiltersReport`, in `message-composer-utils/types`), `useBuiltInOptionLists()` and the Condition schemas are host contract, usable before the Automation pages are turned on. What is a major and what is a minor is in "Public and stable" above.
+- **Dev harness**: `/debug/filters` in `apps/frontend`.
+
 ## Development
 
 Run from `apps/layer`:

package/app/api/automations.ts

@@ -0,0 +1,74 @@
+import type {
+  Automation,
+  AutomationCatalogLanguage,
+  AutomationCatalogResponse,
+  AutomationDeleteResult,
+  CloneAutomationBody,
+  CreateAutomationBody,
+  MessageGroupProduct,
+  UpdateAutomationBody,
+} from '@dev.smartpricing/message-composer-utils/types'
+import { apiClient } from './client'
+
+/** Every request names its Organization and its Product (ADR 0014, ADR 0019). */
+export const automationsApi = {
+  getAll: (options: { organization_id: string; product: MessageGroupProduct }) =>
+    apiClient<Automation[]>(`/automations?${new URLSearchParams(options)}`),
+
+  getCatalog: (options: {
+    organization_id: string
+    product: MessageGroupProduct
+    language: AutomationCatalogLanguage
+  }) => apiClient<AutomationCatalogResponse>(`/automation-catalog?${new URLSearchParams(options)}`),
+
+  /** No error toast: the page says in place why it has no Automation to show. */
+  getById: (id: string, options: { product: MessageGroupProduct }) =>
+    apiClient<Automation>(
+      `/automations/${encodeURIComponent(id)}?${new URLSearchParams(options)}`,
+      {
+        _skipErrorToast: true,
+      } as Record<string, unknown>,
+    ),
+
+  /** No error toast: a refused save is shown in the form, by its caller. */
+  create: (body: CreateAutomationBody) =>
+    apiClient<Automation>('/automations', {
+      method: 'POST',
+      body,
+      _skipErrorToast: true,
+    } as Record<string, unknown>),
+
+  /** No error toast, as on a create: its caller tells a refused save from a half-saved one. */
+  update: (id: string, body: UpdateAutomationBody) =>
+    apiClient<Automation>(`/automations/${encodeURIComponent(id)}`, {
+      method: 'PUT',
+      body,
+      _skipErrorToast: true,
+    } as Record<string, unknown>),
+
+  /**
+   * The copy of an Automation, made by the backend from what is stored: with
+   * its own Message Groups and every Action inactive (ADR 0016).
+   */
+  clone: (id: string, body: CloneAutomationBody) =>
+    apiClient<Automation>(`/automations/${encodeURIComponent(id)}/clone`, {
+      method: 'POST',
+      body,
+    }),
+
+  /**
+   * Deletes the Automation and the Message Groups named, each a repeated
+   * `message_group_ids`. With none the answer is empty; with some it says
+   * which were deleted and which were kept (ADR 0016).
+   */
+  delete: (id: string, options: { product: MessageGroupProduct; message_group_ids: string[] }) => {
+    const query = new URLSearchParams({ product: options.product })
+    for (const messageGroupId of options.message_group_ids) {
+      query.append('message_group_ids', messageGroupId)
+    }
+    return apiClient<AutomationDeleteResult | undefined>(
+      `/automations/${encodeURIComponent(id)}?${query}`,
+      { method: 'DELETE' },
+    )
+  },
+}

package/app/api/index.ts

@@ -10,3 +10,4 @@ export * from './tracking'
 export * from './dynamicValues'
 export * from './brands'
 export * from './organization'
+export * from './automations'

package/app/api/messageGroups.ts

@@ -34,7 +34,11 @@ export const messageGroupsApi = {
       `/message-groups${listQueryString(options)}`,
     ),
 
-  getById: (id: string) => apiClient<MessageGroupWithMessages>(`/message-groups/${id}`),
+  /** `skipErrorToast` for a caller that expects some not to be found. */
+  getById: (id: string, options: { skipErrorToast?: boolean } = {}) =>
+    apiClient<MessageGroupWithMessages>(`/message-groups/${id}`, {
+      _skipErrorToast: options.skipErrorToast,
+    } as Record<string, unknown>),
 
   create: (data: PostEntity<MessageGroup>) =>
     apiClient<MessageGroupFromDb>('/message-groups', {

package/app/app.config.ts

@@ -0,0 +1,10 @@
+import type { AppConfigInput } from 'nuxt/schema'
+
+// Not through `defineAppConfig`: its input type asks every app config for
+// Nuxt UI's `ui`, which only the design system's own config sets.
+export default {
+  composer: {
+    tracking: false,
+    automations: false,
+  },
+} satisfies Pick<AppConfigInput, 'composer'>

package/app/components/Automations/ActionCard.vue

@@ -0,0 +1,163 @@
+<script setup lang="ts">
+import type {
+  AutomationChannel,
+  AutomationTrigger,
+} from '@dev.smartpricing/message-composer-utils/types'
+import {
+  dateReferenceLabel,
+  localSendingTime,
+  type AutomationFormAction,
+} from '../../utils/automations/form'
+import type {
+  AutomationUnavailableItem,
+  AutomationUnavailableKind,
+} from '../../utils/automations/unavailable'
+
+/** One Action of the form: what it sends and when, its Active switch and its buttons. */
+const props = defineProps<{
+  action: AutomationFormAction
+  trigger: AutomationTrigger
+  /** What the Action holds that is no longer available: each is a badge here. */
+  unavailable: AutomationUnavailableItem[]
+  /** A refused save pointed at this Action. */
+  invalid?: boolean
+  /** The Action is not edited or removed here: its Active switch still works. */
+  readOnly?: boolean
+}>()
+
+const emit = defineEmits<{
+  edit: []
+  remove: []
+  toggle: [active: boolean]
+}>()
+
+const { t } = useI18n()
+
+const CHANNEL_ICONS: Record<AutomationChannel, string> = {
+  email: 'ph:envelope-simple-bold',
+  whatsapp: 'ph:whatsapp-logo-bold',
+}
+
+const schedule = computed(() => {
+  // `moment` is the name the ported copy gives the Date Reference.
+  const moment = dateReferenceLabel(props.action, props.trigger)
+  const { days } = props.action
+  if (days === 0) return t('automations.immediately', { moment })
+  if (days === 1) return t('automations.oneDay', { moment })
+  return t('automations.nDays', { count: days, moment })
+})
+
+function unavailableOf(...kinds: AutomationUnavailableKind[]) {
+  return props.unavailable.find((item) => kinds.includes(item.kind))
+}
+
+const unusableChannel = computed(() => unavailableOf('channel'))
+const unlistedDateReference = computed(() => unavailableOf('date_reference'))
+const unapproved = computed(() => unavailableOf('message_group_inactive', 'message_group_active'))
+
+/**
+ * Why the Action cannot be turned on: its Channel cannot be used, or its
+ * Message Group is not approved. An Active one on an unapproved Message Group
+ * keeps a switch that works, so the user can turn it off.
+ */
+const cannotBeActive = computed(
+  () => unusableChannel.value ?? unavailableOf('message_group_inactive'),
+)
+</script>
+
+<template>
+  <UCard :class="{ 'ring-error': invalid }">
+    <div class="flex items-start gap-4">
+      <UAvatar :icon="CHANNEL_ICONS[action.channel]" size="xl" class="shrink-0" />
+
+      <div class="flex-1 min-w-0">
+        <div class="flex items-center gap-2">
+          <p class="label-md truncate">
+            {{ action.messageGroupName || t(`automations.channels.${action.channel}`) }}
+          </p>
+          <AutomationsUnavailableBadge v-if="unapproved" :item="unapproved" />
+          <AutomationsUnavailableBadge v-if="unusableChannel" :item="unusableChannel" />
+        </div>
+        <p class="mt-2 paragraph-sm text-muted">
+          {{ t('automations.action.itIsSent') }}
+          <span class="font-semibold text-default">{{ schedule }}</span>
+          <AutomationsUnavailableBadge
+            v-if="unlistedDateReference"
+            :item="unlistedDateReference"
+            class="ml-2"
+          />
+          <span class="mx-2">&bull;</span>
+          {{ t('automations.action.at') }}
+          <span class="font-semibold text-default">
+            {{ localSendingTime(action.sendingTimeUTC) }}
+          </span>
+          <template v-if="action.recurrence">
+            <span class="mx-2">&bull;</span>
+            <span class="font-semibold text-default">
+              {{ t(`automations.recurrence.${action.recurrence}`) }}
+            </span>
+          </template>
+          <template v-if="action.strictDelay">
+            <span class="mx-2">&bull;</span>
+            <UBadge :label="t('automations.strictDelay.label')" color="neutral" size="sm" />
+          </template>
+          <template v-if="action.preventDuplicates">
+            <span class="mx-2">&bull;</span>
+            <UBadge :label="t('automations.preventDuplicates.label')" color="neutral" size="sm" />
+          </template>
+        </p>
+      </div>
+    </div>
+
+    <template #footer>
+      <div class="flex items-center gap-1">
+        <!-- An Action on a Channel that cannot be used is kept as stored, and shown as not Active. -->
+        <UTooltip :text="cannotBeActive?.text" :disabled="!cannotBeActive">
+          <!-- A disabled switch takes no hover: the tooltip is on what wraps it. -->
+          <span class="inline-flex">
+            <USwitch
+              :model-value="action.status === 'active' && !unusableChannel"
+              :disabled="Boolean(cannotBeActive)"
+              size="sm"
+              color="secondary"
+              :label="t('automations.list.active')"
+              @update:model-value="emit('toggle', $event)"
+            />
+          </span>
+        </UTooltip>
+
+        <div class="ml-auto flex items-center gap-1">
+          <UButton
+            v-if="!readOnly"
+            color="error"
+            variant="ghost"
+            size="sm"
+            :label="t('common.actions.delete')"
+            @click="emit('remove')"
+          />
+          <USlideover
+            close-icon="ph:x"
+            :title="t('common.preview')"
+            :ui="{ content: 'max-w-2xl', body: 'p-0 sm:p-0' }"
+          >
+            <UButton color="primary" variant="outline" size="sm" :label="t('common.preview')" />
+
+            <template #body>
+              <CommonPreviewById
+                :id="action.messageGroupId"
+                class="w-full h-full min-h-[400px]"
+                show-subject
+              />
+            </template>
+          </USlideover>
+          <UButton
+            v-if="!readOnly"
+            size="sm"
+            :label="t('common.actions.edit')"
+            @click="emit('edit')"
+          />
+        </div>
+      </div>
+    </template>
+  </UCard>
+</template>