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

package/src/schemas/index.ts

@@ -1,4 +1,5 @@
 export * from "./common.js";
+export * from "./pagination.js";
 export * from "./ai-integration.js";
 export * from "./brand.js";
 export * from "./dynamic-values.js";

package/src/schemas/message-group.ts

@@ -1,21 +1,46 @@
 import { z } from "zod";
 import {
   DuplicateMessageGroupBody,
+  ListMessageGroupsQuery,
   MessageGroupFromDb,
   MessageGroupWithMessageSummary,
   MESSAGE_GROUP_CATEGORIES,
+  MESSAGE_GROUP_LIST_SORT,
+  MESSAGE_GROUP_LIST_VISIBILITY,
+  MESSAGE_GROUP_PRODUCTS,
   MESSAGE_GROUP_VISIBILITY,
   MESSAGE_STATUS,
   MESSAGE_RENDER_TYPES,
+  SORT_ORDER,
 } from "../types/index.js";
 import { dbTimestampSchema } from "./common.js";
+import {
+  paginatedResponseSchema,
+  paginationQuerySchema,
+} from "./pagination.js";
 import { messageResponseSchema } from "./message.js";
 
-export const listMessageGroupsQuerySchema = z.object({
-  render_type: z.string().optional(),
-  tags: z.union([z.string(), z.array(z.string())]).optional(),
-  tags_mode: z.enum(["and", "or"]).default("and"),
-});
+/**
+ * GET /message-groups: server-side filter, sort and pagination (ADR 0012).
+ * `visibility` other than `public` is admin-only (403 otherwise, enforced by
+ * the route). An empty or whitespace `search` is treated as absent.
+ */
+export const listMessageGroupsQuerySchema = paginationQuerySchema.extend({
+  search: z
+    .string()
+    .trim()
+    .max(200)
+    .optional()
+    .transform((value) => (value === "" ? undefined : value)),
+  category: z.enum(MESSAGE_GROUP_CATEGORIES).optional(),
+  status: z.enum(MESSAGE_STATUS).optional(),
+  product: z.enum(MESSAGE_GROUP_PRODUCTS).optional(),
+  visibility: z.enum(MESSAGE_GROUP_LIST_VISIBILITY).default("public"),
+  render_type: z.enum(MESSAGE_RENDER_TYPES).optional(),
+  sort: z.enum(MESSAGE_GROUP_LIST_SORT).default("updated_at"),
+  order: z.enum(SORT_ORDER).default("desc"),
+}) satisfies z.ZodType<ListMessageGroupsQuery, unknown>;
+export type { ListMessageGroupsQuery };
 
 export const updateMessageGroupBodySchema = z.object({
   name: z
@@ -24,12 +49,14 @@ export const updateMessageGroupBodySchema = z.object({
       (name) => name.trim() !== "",
       "Name is required and cannot be empty",
     ),
+  product: z.enum(MESSAGE_GROUP_PRODUCTS).optional(),
   brand_id: z.string().nullable().optional(),
 });
 
 export const createMessageGroupBodySchema = z.object({
   name: z.string(),
   category: z.enum(MESSAGE_GROUP_CATEGORIES),
+  product: z.enum(MESSAGE_GROUP_PRODUCTS),
   visibility: z.enum(MESSAGE_GROUP_VISIBILITY).optional(),
   brand_id: z.string().nullable().optional(),
 });
@@ -38,6 +65,7 @@ export const duplicateMessageGroupBodySchema = z
   .object({
     name: z.string().optional(),
     visibility: z.enum(MESSAGE_GROUP_VISIBILITY).optional(),
+    product: z.enum(MESSAGE_GROUP_PRODUCTS).optional(),
     brand_id: z.string().nullable().optional(),
   })
   .optional() satisfies z.ZodType<DuplicateMessageGroupBody | undefined>;
@@ -47,6 +75,7 @@ export const messageGroupResponseSchema = z.object({
   id: z.uuid(),
   name: z.string(),
   category: z.enum(MESSAGE_GROUP_CATEGORIES),
+  product: z.enum(MESSAGE_GROUP_PRODUCTS),
   visibility: z.enum(MESSAGE_GROUP_VISIBILITY).nullable().optional(),
   brand_id: z.string().nullable().optional(),
   organization_id: z.string().nullable().optional(),
@@ -80,7 +109,8 @@ export const messageGroupWithMessageSummaryResponseSchema =
     ),
   }) satisfies z.ZodType<unknown, MessageGroupWithMessageSummary>;
 
-export const messageGroupSummaryListResponseSchema = z.array(
+/** Paginated envelope of list items (ADR 0012). */
+export const messageGroupSummaryListResponseSchema = paginatedResponseSchema(
   messageGroupWithMessageSummaryResponseSchema,
 );
 

package/src/schemas/onboarding.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import {
+  MESSAGE_GROUP_PRODUCTS,
   brandDefaultEmailSettingsSchema,
   brandDefaultButtonSettingsSchema,
   brandSocialsSchema,
@@ -21,6 +22,8 @@ export const onboardingBodySchema = z.object({
   userId: z
     .string({ error: "Both organizationId and userId are required" })
     .min(1, "Both organizationId and userId are required"),
+  // Required, no fallback to the sm-product header (ADR 0011)
+  product: z.enum(MESSAGE_GROUP_PRODUCTS),
   tags: z.array(z.string()).optional(),
 });
 

package/src/schemas/pagination.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import {
+  paginationQuerySchema,
+  paginatedResponseSchema,
+} from "./pagination.js";
+
+describe("paginationQuerySchema", () => {
+  it("defaults to page 1 and 25 per page", () => {
+    expect(paginationQuerySchema.parse({})).toEqual({ page: 1, per_page: 25 });
+  });
+
+  it("coerces query-string numbers", () => {
+    expect(paginationQuerySchema.parse({ page: "3", per_page: "50" })).toEqual({
+      page: 3,
+      per_page: 50,
+    });
+  });
+
+  it("accepts the bounds 1 and 100 for per_page", () => {
+    expect(paginationQuerySchema.parse({ per_page: "1" }).per_page).toBe(1);
+    expect(paginationQuerySchema.parse({ per_page: "100" }).per_page).toBe(100);
+  });
+
+  it("rejects page 0, per_page 0 and per_page 101", () => {
+    expect(paginationQuerySchema.safeParse({ page: "0" }).success).toBe(false);
+    expect(paginationQuerySchema.safeParse({ per_page: "0" }).success).toBe(
+      false,
+    );
+    expect(paginationQuerySchema.safeParse({ per_page: "101" }).success).toBe(
+      false,
+    );
+  });
+
+  it("rejects non-integer values", () => {
+    expect(paginationQuerySchema.safeParse({ page: "1.5" }).success).toBe(
+      false,
+    );
+    expect(paginationQuerySchema.safeParse({ page: "abc" }).success).toBe(
+      false,
+    );
+  });
+});
+
+describe("paginatedResponseSchema", () => {
+  const schema = paginatedResponseSchema(z.object({ id: z.string() }));
+
+  it("accepts the Laravel resource-collection envelope", () => {
+    const envelope = {
+      data: [{ id: "a" }],
+      links: { first: "/x?page=1", last: "/x?page=1", prev: null, next: null },
+      meta: {
+        current_page: 1,
+        from: 1,
+        last_page: 1,
+        path: "/x",
+        per_page: 25,
+        to: 1,
+        total: 1,
+      },
+    };
+    expect(schema.parse(envelope)).toEqual(envelope);
+  });
+
+  it("allows null from/to on an empty page and has no meta.links", () => {
+    const parsed = schema.parse({
+      data: [],
+      links: { first: "/x?page=1", last: "/x?page=1", prev: null, next: null },
+      meta: {
+        current_page: 1,
+        from: null,
+        last_page: 1,
+        path: "/x",
+        per_page: 25,
+        to: null,
+        total: 0,
+        links: [{ url: null, label: "x", active: false }],
+      },
+    });
+    expect(parsed.meta.from).toBeNull();
+    expect(parsed.meta.to).toBeNull();
+    expect("links" in parsed.meta).toBe(false);
+  });
+
+  it("validates items with the given schema", () => {
+    const result = schema.safeParse({
+      data: [{ id: 1 }],
+      links: { first: "/x?page=1", last: "/x?page=1", prev: null, next: null },
+      meta: {
+        current_page: 1,
+        from: 1,
+        last_page: 1,
+        path: "/x",
+        per_page: 25,
+        to: 1,
+        total: 1,
+      },
+    });
+    expect(result.success).toBe(false);
+  });
+});

package/src/schemas/pagination.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import type {
+  PaginationLinks,
+  PaginationMeta,
+  PaginationQuery,
+} from "../types/index.js";
+
+export const PAGINATION_DEFAULT_PER_PAGE = 25;
+export const PAGINATION_MAX_PER_PAGE = 100;
+
+/** Laravel-style offset pagination query params (ADR 0012). */
+export const paginationQuerySchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  per_page: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .max(PAGINATION_MAX_PER_PAGE)
+    .default(PAGINATION_DEFAULT_PER_PAGE),
+}) satisfies z.ZodType<PaginationQuery, unknown>;
+
+export const paginationLinksSchema = z.object({
+  first: z.string(),
+  last: z.string(),
+  prev: z.string().nullable(),
+  next: z.string().nullable(),
+}) satisfies z.ZodType<unknown, PaginationLinks>;
+
+export const paginationMetaSchema = z.object({
+  current_page: z.number().int(),
+  from: z.number().int().nullable(),
+  last_page: z.number().int(),
+  path: z.string(),
+  per_page: z.number().int(),
+  to: z.number().int().nullable(),
+  total: z.number().int(),
+}) satisfies z.ZodType<unknown, PaginationMeta>;
+
+/**
+ * Laravel API resource-collection envelope around `item`:
+ * `{ data, links: { first, last, prev, next }, meta: { … } }`, no `meta.links`.
+ */
+export function paginatedResponseSchema<T extends z.ZodType>(item: T) {
+  return z.object({
+    data: z.array(item),
+    links: paginationLinksSchema,
+    meta: paginationMetaSchema,
+  });
+}

package/src/types/api/apiMessages.ts

@@ -1,6 +1,7 @@
 import type {
   MessageFromDb,
   MessageGroupFromDb,
+  MessageGroupProduct,
   MessageGroupVisibility,
   MessageStatus,
   RenderType,
@@ -14,6 +15,8 @@ export type MessageGroupWithMessages = MessageGroupFromDb & {
 export interface DuplicateMessageGroupBody {
   name?: string;
   visibility?: MessageGroupVisibility;
+  /** Defaults to the source group's Product. */
+  product?: MessageGroupProduct;
   brand_id?: string | null;
 }
 

package/src/types/app.ts

@@ -1,3 +1,5 @@
+import type { MessageGroupProduct } from "./message.js";
+
 export const errorCodes = {
   INTERNAL_SERVER_ERROR: "INTERNAL_SERVER_ERROR",
   UNAUTHORIZED: "UNAUTHORIZED",
@@ -34,7 +36,8 @@ export interface AppError {
 export interface AppContextConfig {
   /** @deprecated No longer used — auth is cookie-based via platform layer */
   authenticationToken?: string;
-  product?: "connect" | "chat" | "pms" | "pricing" | "browser";
+  /** The Product the host app embeds the composer in (ADR 0011). Required. */
+  product: MessageGroupProduct;
   strategy?: "embed" | "native";
   channels?: Array<"email" | "whatsapp">;
   languages?: string[];
@@ -45,7 +48,9 @@ export interface AppContextConfig {
   default_tags?: string[];
 }
 
-export interface AppContextState extends AppContextConfig {
+export interface AppContextState extends Omit<AppContextConfig, "product"> {
+  /** Undefined when the host gave no Product; surfaced as a validation error. */
+  product?: MessageGroupProduct;
   initializationSource:
     | "query"
     | "postMessage"

package/src/types/index.ts

@@ -13,3 +13,4 @@ export * from "./submission-job.js";
 export * from "./kafka-events.js";
 export * from "./dynamic-values.js";
 export * from "./brand.js";
+export * from "./pagination.js";

package/src/types/kafka-events.ts

@@ -1,10 +1,16 @@
-import type { MessageStatus, MessageGroupCategory } from "./message.js";
+import type {
+  MessageStatus,
+  MessageGroupCategory,
+  MessageGroupProduct,
+} from "./message.js";
 
 export interface KafkaEventBase {
   event_id: string;
   event_type: string;
   timestamp: string;
   message_group_id: string;
+  /** Product of the Message Group the event is about (ADR 0011). */
+  product: MessageGroupProduct;
   organization_id?: string | null;
   user_id: string;
 }

package/src/types/message.ts

@@ -8,6 +8,7 @@ import type {
   ButtonBlockV1,
 } from "./whatsappblocks.v1.js";
 import type { EmailBlock, EmailGlobalSettings } from "./emailblocks.v1.js";
+import type { PaginationQuery, SortOrder } from "./pagination.js";
 import {
   brandDefaultEmailSettingsSchema,
   brandDefaultButtonSettingsSchema,
@@ -79,10 +80,55 @@ export type MessageGroupCategory = (typeof MESSAGE_GROUP_CATEGORIES)[number];
 export const MESSAGE_GROUP_VISIBILITY = ["public", "internal"] as const;
 export type MessageGroupVisibility = (typeof MESSAGE_GROUP_VISIBILITY)[number];
 
+/** `visibility` filter of the list route; `internal` and `all` are admin-only. */
+export const MESSAGE_GROUP_LIST_VISIBILITY = [
+  ...MESSAGE_GROUP_VISIBILITY,
+  "all",
+] as const;
+export type MessageGroupListVisibility =
+  (typeof MESSAGE_GROUP_LIST_VISIBILITY)[number];
+
+/** Sortable columns of the list route (ADR 0012); aggregates are not sortable. */
+export const MESSAGE_GROUP_LIST_SORT = [
+  "name",
+  "category",
+  "created_at",
+  "updated_at",
+] as const;
+export type MessageGroupListSort = (typeof MESSAGE_GROUP_LIST_SORT)[number];
+
+/**
+ * Parsed query of `GET /message-groups` (ADR 0012): what the route handler
+ * receives after defaults. The layer sends any subset of these as query params.
+ */
+export interface ListMessageGroupsQuery extends PaginationQuery {
+  search?: string;
+  category?: MessageGroupCategory;
+  status?: MessageStatus;
+  product?: MessageGroupProduct;
+  visibility: MessageGroupListVisibility;
+  render_type?: RenderType;
+  sort: MessageGroupListSort;
+  order: SortOrder;
+}
+
+/**
+ * The Smartness application a Message Group is authored for (ADR 0011).
+ * Anything outside this list is not a Product and is rejected on write.
+ */
+export const MESSAGE_GROUP_PRODUCTS = [
+  "connect",
+  "chat",
+  "pms",
+  "pricing",
+] as const;
+export type MessageGroupProduct = (typeof MESSAGE_GROUP_PRODUCTS)[number];
+
 export interface MessageGroup extends DbEntity {
   id: string;
   name: string;
   category: MessageGroupCategory;
+  product: MessageGroupProduct;
   visibility?: MessageGroupVisibility | null;
   brand_id?: string | null;
   organization_id?: string | null;
@@ -311,6 +357,40 @@ interface WhatsAppTemplateMessage extends WhatsAppMessageBase {
  */
 export type WhatsAppSendPayload = WhatsAppTemplateMessage;
 
+/**
+ * Sendable Message (WhatsApp): the content object a host hands to its own
+ * send pipeline. `meta.data` is the compiled Meta template object (name,
+ * language, components) and `meta.template` the translated Meta template the
+ * bubble is rendered from.
+ */
+export interface WhatsappSendableMessage {
+  type: "WhatsappTemplateMessage";
+  text: string;
+  meta: {
+    data: WhatsAppTemplateMessage["template"];
+    template: MetaTemplate;
+  };
+}
+
+/**
+ * Email Sendable Message: the content object the email compile-and-send path
+ * publishes (Smartchat `HtmlMessage`), returned by `/compile` as `message`.
+ */
+export interface EmailSendableMessage {
+  type: "HtmlMessage";
+  skipTranslation: true;
+  /** The compiled HTML, as the message API expects it in both fields. */
+  text: string;
+  rawHtml: string;
+  subject: string;
+}
+
+/**
+ * Sendable Message: what `/compile` returns as `message` and what
+ * compile-and-send publishes, one member per channel.
+ */
+export type SendableMessage = WhatsappSendableMessage | EmailSendableMessage;
+
 /**
  * Response for compile endpoint (WhatsApp)
  */
@@ -319,6 +399,8 @@ export interface CompileWhatsAppResponse {
   language: string;
   template_name: string;
   payload: Omit<WhatsAppTemplateMessage, "to">;
+  /** The Sendable Message, ready for the host's send pipeline. */
+  message: SendableMessage;
   parameters_used: string[];
   missingParameters?: string[];
 }
@@ -332,6 +414,8 @@ export interface CompileEmailResponse {
   subject: string;
   html: string;
   plaintext?: string;
+  /** The Sendable Message, ready for the host's send pipeline. */
+  message: EmailSendableMessage;
   parameters_used: string[];
   missingParameters?: string[];
 }

package/src/types/pagination.ts

@@ -0,0 +1,36 @@
+/**
+ * Laravel API resource-collection envelope for paginated lists (ADR 0012).
+ * Links are relative (path + query, no host); `meta.links` is omitted.
+ */
+export interface PaginationLinks {
+  first: string;
+  last: string;
+  prev: string | null;
+  next: string | null;
+}
+
+export interface PaginationMeta {
+  current_page: number;
+  /** 1-based index of the first item on this page; null on an empty page. */
+  from: number | null;
+  last_page: number;
+  path: string;
+  per_page: number;
+  /** 1-based index of the last item on this page; null on an empty page. */
+  to: number | null;
+  total: number;
+}
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  links: PaginationLinks;
+  meta: PaginationMeta;
+}
+
+export interface PaginationQuery {
+  page: number;
+  per_page: number;
+}
+
+export const SORT_ORDER = ["asc", "desc"] as const;
+export type SortOrder = (typeof SORT_ORDER)[number];