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

package/README.md

@@ -1,75 +1,257 @@
-# 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**.
 
-## Setup
+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.
 
-Make sure to install dependencies:
+## Host setup
 
-```bash
-# npm
-npm install
+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'
+     channels: ref(['whatsapp']),
+     mainLanguage: ref('it'),
+     // organization_id: useAuth().organizationId, // only when the Host works on one Organization
+   })
+
+   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).
+
+   See "Organization and WABA" below for what `organization_id` and `metaWabaId` do.
+
+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.
+
+## Organization and WABA
 
-# pnpm
-pnpm install
+No request depends on an ambient Organization: every request names the one it is for (ADR [0014](../../docs/adr/0014-organization-explicit-on-every-request.md)). The Host no longer has to know it.
 
-# yarn
-yarn install
+**Organization.** `organization_id` is optional in the context.
 
-# bun
-bun install
+- **Given**: the layer works on that Organization and shows no selector. Passing the key is what counts, not its value: it may arrive late (a ref filled after the first render), and until then the layer waits (`status` is `resolving`) and sends no resource request, so a Host does not need to hold the composer back until its Tenant is loaded. A Host that passes the key and never fills it leaves the composer waiting.
+- **Omitted** (the key is not passed at all): the layer asks the backend which Organizations the user can reach (`GET /organizations`). With one, it uses it and looks as before. With several, the Message Group, Brands and images pages show an **Organization selector** in their header: it filters what is listed and decides where new resources are created. The choice is remembered in the browser's local storage and checked against the reachable list on load. There is no "all Organizations" view.
+
+On an editor or preview page the Organization is always the one of the Message Group on screen, whatever the selector says, so a link to a Message Group of any Organization the user can reach works.
+
+**Effective Organization.** `useEffectiveOrganization()` (auto-imported) is the Host's read-only view of the Organization the layer is working on: `organizationId` (`null` until resolved) and `status` (`resolving` | `resolved` | `failed` | `none`). Use it for anything the Host supplies per Organization, such as `organizationData` (the test-email sender addresses and accommodation name):
+
+```ts
+const organizationData = ref<OrganizationData>({ senderEmails: [] })
+defineComposerContext({ product: ref('chat'), organizationData })
+
+// After `defineComposerContext()`: the composable reads the context.
+const { organizationId } = useEffectiveOrganization()
+watch(
+  organizationId,
+  async (id) => {
+    organizationData.value = id ? await loadSenders(id) : { senderEmails: [] }
+  },
+  { immediate: true },
+)
 ```
 
-## Development Server
+**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.
 
-Start the development server on `http://localhost:3000`:
+### Upgrading to 4.5.0
 
-```bash
-# npm
-npm run dev
+Nothing is required: a Host that keeps passing `organization_id` and `metaWabaId` behaves as before.
+
+- **Removed** from `ComposerContext` and from `AppContextConfig` in utils (no code read them): `authenticationToken`, `strategy`, `metaAccessToken`, `dinamicValues`. Remove them from the `defineComposerContext()` call. The utils types `AppContextState` and `ContextSource` are gone too.
+- **Changed**: `metaWabaId` no longer decides where a WhatsApp submission goes and is no longer required for the WhatsApp channel; it preselects the WABA when the user has to pick one.
+- **Deprecated**, removed in 5.0.0: the `sm-organization-id` and `x-meta-waba-id` request headers. The layer no longer sends them; the backend still accepts them from Hosts on an older layer.
+- **New**: `organization_id` is optional, the Organization selector, `useEffectiveOrganization()`, and the `organizationId` and `wabaId` props of the Message Send Flow.
+
+## 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 flow works on one Organization and never shows a selector: the `organizationId` prop when the Host gives one (Smartchat: the conversation's), otherwise the one the layer resolved, which is also the one the page's selector is on. With `organizationId` the flow lists and compiles that Organization's Sendable Message Groups whatever the rest of the page is working on. With `wabaId` it offers only the WhatsApp Message Groups on the WABA the Host sends from.
 
-# pnpm
-pnpm dev
+The `/compile` contract (request, response with `message`, error codes) is documented in [`docs/compile-and-send.md`](../../docs/compile-and-send.md).
 
-# yarn
-yarn dev
+### Mount
 
-# bun
-bun run dev
+```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"
+        :organization-id="conversation.organizationId"
+        :waba-id="conversation.wabaId"
+        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>
 ```
 
-## Production
+### Props
 
-Build the application for production:
+| 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.                                                                         |
+| `organizationId` | `string`                 | `undefined`     | The Organization the flow works on. Unset, the one the layer resolved. A preselected group of another Organization raises `NOT_OFFERED`.                     |
+| `wabaId`         | `string`                 | `undefined`     | The WABA the Host sends from: with `whatsapp_v1`, only Message Groups on it are offered. Unset, the groups of every WABA. Ignored for `email_v1`.            |
+| `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 run build
+### Emits
+
+| 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.                                       |
+
+Types: `SendableMessage` from `@dev.smartpricing/message-composer-utils/types`; `MessageSendFlowError`, `MessageSendFlowErrorCode` and `MessageSendFlowEmits` from the layer's `app/composables/useMessageSendFlow.ts`.
+
+### Error codes
+
+| 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                          |
+| `NOT_OFFERED`            | layer     | The preselected group belongs to another Organization than `organizationId`, or is not on `wabaId`. The picker stays usable.        | 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 |
+
+A 401 is not an `error` emit: it reaches the host through the `composer:auth-error` Nuxt hook like everywhere else in the layer.
+
+### Language rule
+
+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.
+
+### Reused blocks and their new props
+
+- `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`. It also takes `organizationId` (list that Organization instead of the resolved one) and `wabaId` (with `renderType="whatsapp_v1"`, only the groups on that WABA). 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.
 
-# pnpm
-pnpm build
+### Exported blocks
 
-# yarn
-yarn build
+All of these are auto-imported in a host that extends the layer, so a different layout can be composed without forking:
 
-# bun
-bun 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
+
+The emitted Sendable Message is the content object Smartchat already sends, so the glue is a two-field pick:
+
+```ts
+import type { SendableMessage } from '@dev.smartpricing/message-composer-utils/types'
+
+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
 
-# pnpm
-pnpm preview
+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`).
 
-# yarn
-yarn preview
+### Dev harness
 
-# bun
-bun run preview
+`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.
+
+## Development
+
+Run from `apps/layer`:
+
+```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/brands.ts

@@ -14,19 +14,27 @@ import { apiClient } from './client'
 export type BrandWithProperties = BrandFromDb & { properties: BrandProperty[] }
 export type BrandCreateResponse = BrandFromDb & { brand_count: number }
 export type BrandDeleteResponse = { brand_count: number }
+export type BrandPreviewRequest = {
+  message: PostEntity<EmailMessage>
+  parameters?: Record<string, unknown>
+  brand?: BrandCascadeData | undefined
+}
 
 export const brandsApi = {
-  getAll: (options?: { sort_by?: 'created_at' | 'name'; direction?: 'asc' | 'desc' }) => {
-    const params = new URLSearchParams()
-    if (options?.sort_by) params.set('sort_by', options.sort_by)
-    if (options?.direction) params.set('direction', options.direction)
-    const query = params.size ? `?${params.toString()}` : ''
-    return apiClient<BrandWithProperties[]>(`/brands${query}`)
+  getAll: (options: {
+    organization_id: string
+    sort_by?: 'created_at' | 'name'
+    direction?: 'asc' | 'desc'
+  }) => {
+    const params = new URLSearchParams({ organization_id: options.organization_id })
+    if (options.sort_by) params.set('sort_by', options.sort_by)
+    if (options.direction) params.set('direction', options.direction)
+    return apiClient<BrandWithProperties[]>(`/brands?${params.toString()}`)
   },
 
   getById: (id: string) => apiClient<BrandWithProperties>(`/brands/${id}`),
 
-  create: (data: BrandCreateBody) =>
+  create: (data: BrandCreateBody & { organization_id: string }) =>
     apiClient<BrandCreateResponse>('/brands', {
       method: 'POST',
       body: data,
@@ -43,11 +51,7 @@ export const brandsApi = {
 
   delete: (id: string) => apiClient<BrandDeleteResponse>(`/brands/${id}`, { method: 'DELETE' }),
 
-  preview: (data: {
-    message: PostEntity<EmailMessage>
-    parameters?: Record<string, unknown>
-    brand?: BrandCascadeData | undefined
-  }) =>
+  preview: (data: BrandPreviewRequest & { organization_id: string }) =>
     apiClient<CompileEmailResponse>('/message-groups/preview', {
       method: 'POST',
       body: data,
@@ -55,5 +59,8 @@ export const brandsApi = {
 }
 
 export const propertiesApi = {
-  getAll: () => apiClient<Property[]>('/properties'),
+  getAll: (organizationId: string) =>
+    apiClient<Property[]>(
+      `/properties?${new URLSearchParams({ organization_id: organizationId })}`,
+    ),
 }

package/app/api/client.ts

@@ -24,19 +24,21 @@ 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 })
     },
   },
+  // No Organization header: every request names its Organization itself, in
+  // the query, in the body or through the resource it acts on (ADR 0014).
+  // No WABA header either: a submission names its WABA in the body (ADR 0015).
   onRequest({ options }) {
     const store = useAppContextStore()
 
-    if (store.organization_id) {
-      options.headers.set('sm-organization-id', store.organization_id)
-    }
-    if (store.metaWabaId) {
-      options.headers.set('x-meta-waba-id', store.metaWabaId)
-    }
     if (store.product) {
       options.headers.set('sm-product', store.product)
     }
@@ -45,6 +47,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,11 +1,15 @@
-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, organizationId: string) => {
     const params = new URLSearchParams()
     params.set('product', product)
     params.set('language', language)
+    params.set('organization_id', organizationId)
     return apiClient<DynamicValuesResponse>(`/dynamic-values?${params.toString()}`)
   },
 }

package/app/api/media.ts

@@ -2,12 +2,15 @@ import type { MediaFromDb } from '@dev.smartpricing/message-composer-utils/types
 import { apiClient } from './client'
 
 export const mediaApi = {
-  list: () => apiClient<MediaFromDb[]>('/media'),
+  list: (organizationId: string) =>
+    apiClient<MediaFromDb[]>(`/media?${new URLSearchParams({ organization_id: organizationId })}`),
 
-  upload: (file: File) => {
+  upload: (file: File, organizationId: string) => {
     const formData = new FormData()
-    formData.append('file', file)
+    // Before the file: the backend reads only the fields that precede it.
+    formData.append('organization_id', organizationId)
     formData.append('fileName', file.name)
+    formData.append('file', file)
     return apiClient<MediaFromDb>('/media/upload', {
       method: 'POST',
       body: formData,

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}`),
 
@@ -40,10 +51,14 @@ export const messageGroupsApi = {
   delete: (id: string) => apiClient(`/message-groups/${id}`, { method: 'DELETE' }),
 
   publish: (id: string) =>
-    apiClient<MessageGroupFromDb>(`/message-groups/${id}/publish`, { method: 'PUT' }),
+    apiClient<MessageGroupFromDb>(`/message-groups/${id}/publish`, {
+      method: 'PUT',
+    }),
 
   unpublish: (id: string) =>
-    apiClient<MessageGroupFromDb>(`/message-groups/${id}/unpublish`, { method: 'PUT' }),
+    apiClient<MessageGroupFromDb>(`/message-groups/${id}/unpublish`, {
+      method: 'PUT',
+    }),
 
   validate: (id: string) =>
     apiClient<MessageGroupValidationResponse>(`/message-groups/${id}/validate`),

package/app/api/meta.ts

@@ -1,22 +1,44 @@
 import type {
+  OrganizationWaba,
   SubmissionJob,
   SubmissionJobResponse,
+  SubmitToWabaBody,
 } from '@dev.smartpricing/message-composer-utils/types'
 import { apiClient } from './client'
 
+const submitBody = (wabaId?: string): SubmitToWabaBody => (wabaId ? { waba_id: wabaId } : {})
+
 export const metaApi = {
-  submitGroup: (messageGroupId: string) =>
+  /**
+   * The WABAs of an Organization, empty when it has none (ADR 0015). No error
+   * toast: a failed lookup leaves the WhatsApp configuration unknown, and the
+   * submission itself reports what is wrong.
+   */
+  getWabas: (organizationId: string) => {
+    const params = new URLSearchParams()
+    params.set('organization_id', organizationId)
+    return apiClient<OrganizationWaba[]>(`/integrations/meta/wabas?${params.toString()}`, {
+      _skipErrorToast: true,
+    } as Record<string, unknown>)
+  },
+
+  /**
+   * `wabaId` names the WABA of a first submission, when the user had to pick
+   * one. Left out, the backend uses the Message Group's WABA or the
+   * Organization's only one.
+   */
+  submitGroup: (messageGroupId: string, wabaId?: string) =>
     apiClient<SubmissionJobResponse>(`/integrations/meta/submit-group/${messageGroupId}`, {
       method: 'POST',
-      body: {},
+      body: submitBody(wabaId),
     }),
 
-  submitMessage: (messageId: string) =>
+  submitMessage: (messageId: string, wabaId?: string) =>
     apiClient<{ success: boolean; templateId?: string }>(
       `/integrations/meta/submit-message/${messageId}`,
       {
         method: 'POST',
-        body: {},
+        body: submitBody(wabaId),
       },
     ),
 

package/app/api/organization.ts

@@ -1,5 +1,14 @@
+import type { ReachableOrganization } from '@dev.smartpricing/message-composer-utils/types'
 import { apiClient } from './client'
 
 export const organizationApi = {
-  getData: () => apiClient<Record<string, string>>('/organization/data'),
+  /**
+   * The user's Reachable Organizations: the answer is what resolves the
+   * Effective Organization. No error toast, the Organization gate renders
+   * the failure.
+   */
+  getReachable: () =>
+    apiClient<ReachableOrganization[]>('/organizations', {
+      _skipErrorToast: true,
+    } as Record<string, unknown>),
 }

package/app/api/tracking.ts

@@ -1,9 +1,9 @@
 import { apiClient } from './client'
 
 export const trackingApi = {
-  event: (eventName: string, properties?: Record<string, unknown>) =>
+  event: (eventName: string, organizationId: string, properties?: Record<string, unknown>) =>
     apiClient<{ success: boolean }>('/tracking/event', {
       method: 'POST',
-      body: { eventName, properties },
+      body: { eventName, properties, organization_id: organizationId },
     }),
 }