@dev.smartpricing/message-composer-layer 4.3.2-fix.1 → 4.4.1-next.0

package/README.md

@@ -1,75 +1,211 @@
-# Nuxt Minimal Starter
+# @dev.smartpricing/message-composer-layer
 
-Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more.
+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.
+
+## Host setup
+
+1. Install the layer and its peer:
+
+   ```bash
+   pnpm add @dev.smartpricing/message-composer-layer
+   pnpm add -D nuxt-ui-layer@github:smartpricing/smartness-nuxt-ui#v1.14.4   # peer, >= 1.3.0
+   ```
+
+   `nuxt-ui-layer` is extended by `@dev.smartpricing/platform-layer`, which this layer extends, so the host does not list it in `extends`.
+
+2. Extend it and set the API keys. `BACKEND_BASE_URL`, `PLATFORM_URL` and `CSRF_COOKIE_NAME` are declared by `@dev.smartpricing/platform-layer`, which this layer extends; set them once for both.
+
+   ```ts
+   // nuxt.config.ts
+   export default defineNuxtConfig({
+     extends: ['@dev.smartpricing/message-composer-layer'],
+     runtimeConfig: {
+       public: {
+         COMPOSER_API_URL: '', // NUXT_PUBLIC_COMPOSER_API_URL
+         BACKEND_BASE_URL: '', // NUXT_PUBLIC_BACKEND_BASE_URL
+         PLATFORM_URL: '', // NUXT_PUBLIC_PLATFORM_URL
+         CSRF_COOKIE_NAME: '', // NUXT_PUBLIC_CSRF_COOKIE_NAME: smt_csrf | smt_csrf_stage | smt_csrf_dev
+       },
+     },
+   })
+   ```
+
+3. Provide the composer context before any layer component renders (`app.vue` or a plugin). `product` is required; everything else has a default.
+
+   ```vue
+   <script setup lang="ts">
+   defineComposerContext({
+     product: ref('chat'), // 'connect' | 'chat' | 'pms' | 'pricing'
+     organization_id: useAuth().organizationId,
+     channels: ref(['whatsapp']),
+     mainLanguage: ref('it'),
+     metaWabaId: useAuth().wabaId, // required for the whatsapp channel
+     metaAccessToken: useAuth().metaToken, // required for the whatsapp channel
+   })
+
+   useNuxtApp().hook('composer:auth-error', () => {
+     // 401 from the composer API: the session is gone, decide what to do
+   })
+   </script>
+   ```
+
+   Auth is cookie-based through platform-layer. The full `ComposerContext` interface lives in `app/composables/composerContext.ts`; the design and the parent/layer contract are in [`docs/nuxt-layer-design.md`](../../docs/nuxt-layer-design.md).
+
+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.
+
+## Message Send Flow
+
+`MessageSendFlow` walks an operator from "which Message" to "here is what to send", in two steps inside a container the host owns (Smartchat: a modal):
+
+1. **Message**: pick a **Sendable** Message Group (at least one approved Message; groups with none are greyed out with a reason) and one of its approved languages.
+2. **Parameters**: one required input per operator parameter of the chosen Message, prefilled from the host, editable. `brand_*` keys are hidden and filled server-side. **Confirm** calls `POST /message-groups/:id/compile` once (`strict: true`, `strict_language: true`) and emits the **Sendable Message** the backend built.
+
+The preview follows every step in a right panel: the picked Message as the guest receives it (the WhatsApp bubble for `whatsapp_v1`, the compiled email for `email_v1`), with the typed values substituted live. Plan a container at least ~1100 px wide (Nuxt UI `max-w-6xl`); the panel is 400 px, the stepper 200 px.
+
+Back and Next move between steps, Cancel is always available, Confirm only on Parameters. The action bar renders under the steps, or wherever `actionsTo` points (a modal footer). The component has no outer padding: the host's container pads it. The component owns no overlay and no send, and it keeps its state after `compiled`: closing the container is the host's decision. There is no reset API; remount it (`:key`) to start over.
+
+The `/compile` contract (request, response with `message`, error codes) is documented in [`docs/compile-and-send.md`](../../docs/compile-and-send.md).
+
+### Mount
+
+```vue
+<script setup lang="ts">
+import type { SendableMessage } from '@dev.smartpricing/message-composer-utils/types'
+
+const open = ref(true)
+const groupId = ref<string>() // optional preselect, read back after a pick
+
+function onCompiled(message: SendableMessage) {
+  open.value = false
+  // hand `message` to your send pipeline, see "Smartchat glue" below
+}
+</script>
+
+<template>
+  <UModal v-model:open="open" title="New WhatsApp conversation">
+    <template #body>
+      <MessageSendFlow
+        v-model:message-group-id="groupId"
+        language="it"
+        :parameters="{ guest_name: 'Mario', guest_fullname: 'Mario Rossi' }"
+        actions-to="#send-flow-actions"
+        @compiled="onCompiled"
+        @cancel="open = false"
+        @error="(e) => console.warn(e.code, e.details)"
+      />
+    </template>
+    <template #footer>
+      <!-- Cancel, Back, Next and Confirm render here -->
+      <div id="send-flow-actions" class="w-full" />
+    </template>
+  </UModal>
+</template>
+```
 
-## Setup
+### Props
 
-Make sure to install dependencies:
+| Prop             | Type                     | Default         | Description                                                                                                                                                  |
+| ---------------- | ------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `messageGroupId` | `string` (`v-model`)     | `undefined`     | Two-way: preselect a group, read back what the operator picked. A preselected group that is not Sendable raises `NOT_SENDABLE` and leaves the picker usable. |
+| `renderType`     | `RenderType`             | `'whatsapp_v1'` | Channel of the Messages offered: `whatsapp_v1` or `email_v1`. Picker, languages, parameters, preview and the Sendable Message follow it.                     |
+| `language`       | `string`                 | `undefined`     | Preferred language (see the language rule).                                                                                                                  |
+| `parameters`     | `Record<string, string>` | `undefined`     | Editable prefill of the parameter inputs. Keys the chosen Message does not need are ignored.                                                                 |
+| `brandId`        | `string`                 | `undefined`     | Brand override forwarded to `/compile` as `brand_id`; defaults to the group's brand.                                                                         |
+| `actionsTo`      | `string \| HTMLElement`  | `undefined`     | Where the Cancel/Back/Next/Confirm bar renders, e.g. a `UModal` footer element. Unset, it renders under the steps.                                           |
 
-```bash
-# npm
-npm install
+### Emits
 
-# pnpm
-pnpm install
+| Event      | Payload                                                                  | When                                                                                                                                                                                      |
+| ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `compiled` | `SendableMessage`                                                        | Confirm succeeded. The Sendable Message is the `message` field of the `/compile` response, untouched: `WhatsappSendableMessage` for `whatsapp_v1`, `EmailSendableMessage` for `email_v1`. |
+| `cancel`   | none                                                                     | The operator pressed Cancel (on any step).                                                                                                                                                |
+| `error`    | `{ code: MessageSendFlowErrorCode, message: string, details?: unknown }` | Every failure the inline alert shows, so the host can log or surface it. `message` is the layer's translated text, the same string the alert shows.                                       |
 
-# yarn
-yarn install
+Types: `SendableMessage` from `@dev.smartpricing/message-composer-utils/types`; `MessageSendFlowError`, `MessageSendFlowErrorCode` and `MessageSendFlowEmits` from the layer's `app/composables/useMessageSendFlow.ts`.
 
-# bun
-bun install
-```
+### Error codes
 
-## Development Server
+| Code                     | Raised by | Meaning                                                                                                                             | `details`                     |
+| ------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `NOT_SENDABLE`           | layer     | The preselected or picked group has no approved Message. The picker stays usable; the alert clears once a Sendable group is picked. | none                          |
+| `MISSING_PARAMETERS`     | layer     | Confirm pressed with an empty required parameter (checked client-side before calling `/compile`).                                   | `{ missing: string[] }`       |
+| `MISSING_PARAMETERS`     | backend   | `/compile` reported a required key as absent.                                                                                       | the backend error body        |
+| `TEMPLATE_NOT_SUBMITTED` | backend   | The WhatsApp template was never submitted to Meta.                                                                                  | the backend error body        |
+| `TEMPLATE_NOT_APPROVED`  | backend   | The Message is not approved by Meta.                                                                                                | the backend error body        |
+| `COMPILE_FAILED`         | layer     | Any other `/compile` failure, or a response without `message`.                                                                      | the backend body or the error |
 
-Start the development server on `http://localhost:3000`:
+A 401 is not an `error` emit: it reaches the host through the `composer:auth-error` Nuxt hook like everywhere else in the layer.
 
-```bash
-# npm
-npm run dev
+### Language rule
 
-# pnpm
-pnpm dev
+The language selected in step 1 is the `language` prop when that Message is approved, otherwise the first approved Message in the group's `messages[]` order. It is recomputed whenever the group or the `language` prop changes. Non-approved languages stay visible as disabled radio cards showing their status; only approved ones can be picked.
 
-# yarn
-yarn dev
+### Reused blocks and their new props
 
-# bun
-bun run dev
-```
+- `MessageGroupSelect` (auto-import `CommonMessageGroupSelect`) gained `eligibility?: 'active' | 'sendable'`. `active` (default, the composer's own picker) selects groups whose every Message is approved; `sendable` selects groups with at least one approved Message. The disabled tooltip and the "hide inactive" filter follow the mode. The send flow uses `sendable`. Details in [`docs/message-group-select-migration.md`](../../docs/message-group-select-migration.md).
+- `WhatsappPreview` gained `parameters?: Record<string, string>`: non-empty values override the organization-level resolved values, keys not in the map keep the resolved mock, an empty string shows the raw `{{key}}` placeholder.
 
-## Production
+### Exported blocks
 
-Build the application for production:
+All of these are auto-imported in a host that extends the layer, so a different layout can be composed without forking:
 
-```bash
-# npm
-npm run build
+| Auto-import name                | File                                                 | Role                                                                                                                  |
+| ------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `MessageSendFlow`               | `app/components/MessageSendFlow/MessageSendFlow.vue` | The composed two-step flow.                                                                                           |
+| `MessageSendFlowLanguageSelect` | `app/components/MessageSendFlow/LanguageSelect.vue`  | Radio cards of a group's languages; props `languages`, `v-model` code.                                                |
+| `MessageSendFlowParametersForm` | `app/components/MessageSendFlow/ParametersForm.vue`  | One input per key; props `parameterKeys`, `placeholders`, `loading`, `v-model` values.                                |
+| `CommonMessageGroupSelect`      | `app/components/Common/MessageGroupSelect.vue`       | The picker, with `eligibility="sendable"`.                                                                            |
+| `WhatsappPreview`               | `app/components/Whatsapp/Preview.vue`                | The bubble, with the `parameters` override.                                                                           |
+| `MessageSendFlowEmailPreview`   | `app/components/MessageSendFlow/EmailPreview.vue`    | The compiled email (subject, HTML) for the typed values; props `messageGroupId`, `language`, `parameters`, `brandId`. |
+
+The data flow (group, language rule, parameters, one compile on Confirm, error mapping) is `useMessageSendFlow()` in `app/composables/useMessageSendFlow.ts`. Test ids for every control are in `messageSendFlowTestIds` (`app/utils/testIds.const.ts`).
+
+### Smartchat glue
 
-# pnpm
-pnpm build
+The emitted Sendable Message is the content object Smartchat already sends, so the glue is a two-field pick:
 
-# yarn
-yarn build
+```ts
+import type { SendableMessage } from '@dev.smartpricing/message-composer-utils/types'
 
-# bun
-bun run build
+function onCompiled(message: SendableMessage) {
+  sendMessage({
+    contentType: message.type, // 'WhatsappTemplateMessage' | 'HtmlMessage'
+    content: message,
+    language:
+      message.type === 'WhatsappTemplateMessage' ? message.meta.data.language.code : language,
+  })
+}
 ```
 
-Locally preview production build:
+For WhatsApp, `message.meta.data` is the Meta template object (`name`, `language`, `components` with the filled parameters) and `message.meta.template` is the raw translated template stored at submission, the one Smartchat renders in the bubble. For email, `message` is the `HtmlMessage` content compile-and-send publishes (`subject`, `text` and `rawHtml` both the compiled HTML, `skipTranslation: true`); it carries no language, so the host keeps the one the operator picked from its own state.
 
-```bash
-# npm
-npm run preview
+### Tracking
+
+With tracking enabled the flow reports `send_flow.confirm` (`message_name`, `message_category`, `language`, `parameters_count`), `send_flow.cancel` (`step`: `message` | `parameters`) and `send_flow.error` (`code`).
+
+### Dev harness
+
+`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, inline or modal container, remount, and a log of every emit.
 
-# pnpm
-pnpm preview
+## Development
 
-# yarn
-yarn preview
+Run from `apps/layer`:
 
-# bun
-bun run preview
+```bash
+pnpm typecheck            # nuxt typecheck
+pnpm lint                 # eslint app/ --fix
+pnpm test:e2e             # playwright
+pnpm translations:check   # every locale has every key
 ```
 
-Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
+There is no dev server in the layer itself: use `apps/frontend`, which extends `../layer`.
+
+## Release
+
+1. Bump `version` in `apps/layer/package.json` and `packages/message-composer-utils/package.json` together (semver: minor for a new component or prop, major for a change to the host contract).
+2. Build the tarball from `apps/layer` with `pnpm pack`; `build.sh` builds the Docker image of the standalone deployment, not the npm package.
+3. Publish both packages to the private registry.

package/app/api/client.ts

@@ -24,6 +24,11 @@ export const apiClient = createApiClient({
       (useRuntimeConfig().public.BACKEND_BASE_URL as string) ||
       (useRuntimeConfig().public.PLATFORM_URL as string),
     platformURL: useRuntimeConfig().public.PLATFORM_URL as string,
+    // The composer backend answers a dead access token with @fastify/jwt's flat
+    // body (`code: FST_JWT_*` at top level), never the platform's nested
+    // `error.code: session.*` that the default predicate looks for. Refresh on
+    // any 401, as Connect's client does; the retry decides.
+    shouldRefresh: (status) => status === 401,
     onRefreshFailed: () => {
       useNuxtApp().callHook('composer:auth-error', { statusCode: 401 })
     },
@@ -45,6 +50,13 @@ export const apiClient = createApiClient({
     }
   },
   onResponseError({ response, options }) {
+    // A 401 that reaches here survived the refresh attempt (or its retry): the
+    // session is dead. platform-layer only calls onRefreshFailed for its own
+    // `session.*` codes, so tell the host here for the composer's `FST_JWT_*`.
+    if (response.status === 401) {
+      useNuxtApp().callHook('composer:auth-error', { statusCode: 401 })
+      return
+    }
     if ((options as { _skipErrorToast?: boolean })._skipErrorToast) return
 
     const t = useNuxtApp().$i18n.t

package/app/api/compilation.ts

@@ -5,6 +5,7 @@ import type {
   GetResolvedParametersResponse,
   CompileMessageRequest,
   CompileEmailResponse,
+  CompileMessageResponse,
   PreviewMessageRequest,
 } from '@dev.smartpricing/message-composer-utils/types'
 import { apiClient } from './client'
@@ -26,11 +27,20 @@ export const compilationApi = {
       `/message-groups/${messageGroupId}/parameters/resolved?language=${language}`,
     ),
 
-  compileEmail: (messageGroupId: string, data: CompileMessageRequest) =>
-    apiClient<CompileEmailResponse>(`/message-groups/${messageGroupId}/compile`, {
+  /**
+   * WhatsApp responses carry `message`, the Sendable Message (docs/compile-and-send.md).
+   * `skipErrorToast` lets a caller with its own inline error surface silence the global toast.
+   */
+  compile: (
+    messageGroupId: string,
+    data: CompileMessageRequest,
+    options: { skipErrorToast?: boolean } = {},
+  ) =>
+    apiClient<CompileMessageResponse>(`/message-groups/${messageGroupId}/compile`, {
       method: 'POST',
       body: data,
-    }),
+      _skipErrorToast: options.skipErrorToast,
+    } as Record<string, unknown>),
 
   previewEmail: (data: PreviewMessageRequest) =>
     apiClient<CompileEmailResponse>('/message-groups/preview', {

package/app/api/dynamicValues.ts

@@ -1,8 +1,11 @@
-import type { DynamicValuesResponse } from '@dev.smartpricing/message-composer-utils/types'
+import type {
+  DynamicValuesResponse,
+  MessageGroupProduct,
+} from '@dev.smartpricing/message-composer-utils/types'
 import { apiClient } from './client'
 
 export const dynamicValuesApi = {
-  get: (product: string, language: string) => {
+  get: (product: MessageGroupProduct, language: string) => {
     const params = new URLSearchParams()
     params.set('product', product)
     params.set('language', language)

package/app/api/messageGroups.ts

@@ -1,27 +1,38 @@
 import type {
   MessageGroupFromDb,
+  PaginatedResponse,
   MessageGroupWithMessages,
   MessageGroupWithMessageSummary,
   MessageGroupValidationResponse,
   PostEntity,
   MessageGroup,
-  RenderType,
   DuplicateMessageGroupBody,
+  ListMessageGroupsQuery,
 } from '@dev.smartpricing/message-composer-utils/types'
 import { apiClient } from './client'
 
+/**
+ * Query params of `GET /message-groups`, straight from the shared schema
+ * (ADR 0007): snake_case, as on the wire. `visibility` other than `public`
+ * is admin-only (403 otherwise); every field is optional here, the server
+ * applies the defaults.
+ */
+export type ListMessageGroupsOptions = Partial<ListMessageGroupsQuery>
+
+function listQueryString(options: ListMessageGroupsOptions = {}): string {
+  const params = new URLSearchParams()
+  for (const [name, value] of Object.entries(options)) {
+    if (value !== undefined && value !== '') params.set(name, String(value))
+  }
+  return params.size ? `?${params.toString()}` : ''
+}
+
 export const messageGroupsApi = {
-  getAll: (options?: { renderType?: RenderType; tags?: string[]; tagsMode?: 'and' | 'or' }) => {
-    const params = new URLSearchParams()
-    if (options?.renderType) params.set('render_type', options.renderType)
-    if (options?.tags && options.tags.length > 0) {
-      options.tags.forEach((tag) => params.append('tags', tag))
-    }
-    if (options?.tagsMode) params.set('tags_mode', options.tagsMode)
-
-    const query = params.size ? `?${params.toString()}` : ''
-    return apiClient<MessageGroupWithMessageSummary[]>(`/message-groups${query}`)
-  },
+  /** One page of the server-side filtered list, in the Laravel envelope (ADR 0012). */
+  list: (options?: ListMessageGroupsOptions) =>
+    apiClient<PaginatedResponse<MessageGroupWithMessageSummary>>(
+      `/message-groups${listQueryString(options)}`,
+    ),
 
   getById: (id: string) => apiClient<MessageGroupWithMessages>(`/message-groups/${id}`),
 

package/app/components/Common/AppContextErrors.vue

@@ -0,0 +1,30 @@
+<script setup lang="ts">
+import { useAppContextStore } from '~/stores/appContext'
+
+/**
+ * Host-integration problems reported by the app-context store (missing
+ * Product, missing Meta config, ...). Shown persistently: the host has to fix
+ * its context, the user cannot.
+ */
+const { validationErrors } = storeToRefs(useAppContextStore())
+const messages = computed(() => Object.values(validationErrors.value))
+</script>
+
+<template>
+  <UAlert
+    v-if="messages.length"
+    color="error"
+    variant="subtle"
+    icon="i-lucide-alert-triangle"
+    :title="$t('common.context_error_title')"
+    class="rounded-none"
+  >
+    <template #description>
+      <ul class="list-disc pl-4 space-y-1">
+        <li v-for="message in messages" :key="message">
+          {{ message }}
+        </li>
+      </ul>
+    </template>
+  </UAlert>
+</template>

package/app/components/Common/HtmlPreviewIframe.vue

@@ -17,6 +17,8 @@ const props = withDefaults(
 
 const iframeRef = useTemplateRef<HTMLIFrameElement>('iframe')
 const measuredHeight = ref(0)
+// The first document comes from `srcdoc`; later ones are written in place (see the watch).
+const initialHtml = props.html
 
 const heightStyle = computed(() => {
   if (!measuredHeight.value) return `${props.minHeight}px`
@@ -44,10 +46,22 @@ function onLoad() {
   observeContent()
 }
 
+/**
+ * Replace the document in place instead of re-binding `srcdoc`: a `srcdoc`
+ * change is a navigation, which blanks the frame and drops the height for a
+ * few frames. Writing keeps the frame painted and the last measured height
+ * until the new content is measured.
+ */
 watch(
   () => props.html,
-  () => {
-    measuredHeight.value = 0
+  (html) => {
+    const doc = iframeRef.value?.contentDocument
+    if (!doc) return
+    doc.open()
+    doc.write(html)
+    doc.close()
+    fitToContent()
+    observeContent()
   },
 )
 
@@ -59,7 +73,7 @@ onBeforeUnmount(() => {
 <template>
   <iframe
     ref="iframe"
-    :srcdoc="html"
+    :srcdoc="initialHtml"
     :title="title"
     sandbox="allow-same-origin"
     :style="{ height: heightStyle }"