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

package/src/schemas/organization.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect } from "vitest";
+import {
+  organizationBodySchema,
+  organizationFilterQuerySchema,
+  organizationLookupQuerySchema,
+} from "./organization.js";
+import { listBrandsQuerySchema } from "./brand.js";
+import { dynamicValuesQuerySchema } from "./dynamic-values.js";
+import { trackingBodySchema } from "./tracking.js";
+import {
+  createMessageGroupBodySchema,
+  duplicateMessageGroupBodySchema,
+  listMessageGroupsQuerySchema,
+} from "./message-group.js";
+
+const ORGANIZATION = "3f0c1a52-8f0e-4c53-9d58-0f6f6f1f2a77";
+const NOT_UUIDS = ["", "42", "hotel-uno", `${ORGANIZATION}x`, 42, null];
+
+describe("organizationFilterQuerySchema", () => {
+  it("accepts a UUID", () => {
+    expect(
+      organizationFilterQuerySchema.parse({ organization_id: ORGANIZATION }),
+    ).toEqual({ organization_id: ORGANIZATION });
+  });
+
+  it("is optional: a list without it spans the Reachable Organizations", () => {
+    expect(organizationFilterQuerySchema.parse({})).toEqual({});
+  });
+
+  it.each(NOT_UUIDS)("rejects %j", (organization_id) => {
+    expect(
+      organizationFilterQuerySchema.safeParse({ organization_id }).success,
+    ).toBe(false);
+  });
+});
+
+describe("organizationBodySchema", () => {
+  it("accepts a UUID", () => {
+    expect(
+      organizationBodySchema.parse({ organization_id: ORGANIZATION }),
+    ).toEqual({ organization_id: ORGANIZATION });
+  });
+
+  it.each(NOT_UUIDS)("rejects %j", (organization_id) => {
+    expect(organizationBodySchema.safeParse({ organization_id }).success).toBe(
+      false,
+    );
+  });
+});
+
+describe("Message Group schemas carry the Organization", () => {
+  it("the list query keeps a UUID filter and rejects anything else", () => {
+    expect(
+      listMessageGroupsQuerySchema.parse({ organization_id: ORGANIZATION })
+        .organization_id,
+    ).toBe(ORGANIZATION);
+    expect(
+      listMessageGroupsQuerySchema.safeParse({ organization_id: "hotel-uno" })
+        .success,
+    ).toBe(false);
+  });
+
+  it("the create body keeps a UUID Organization and rejects anything else", () => {
+    const body = { name: "Welcome", category: "utility", product: "chat" };
+    expect(
+      createMessageGroupBodySchema.parse({
+        ...body,
+        organization_id: ORGANIZATION,
+      }).organization_id,
+    ).toBe(ORGANIZATION);
+    expect(
+      createMessageGroupBodySchema.safeParse({
+        ...body,
+        organization_id: "hotel-uno",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("the duplicate body keeps a UUID Organization and rejects anything else", () => {
+    expect(
+      duplicateMessageGroupBodySchema.parse({ organization_id: ORGANIZATION }),
+    ).toEqual({ organization_id: ORGANIZATION });
+    expect(
+      duplicateMessageGroupBodySchema.safeParse({
+        organization_id: "hotel-uno",
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("organizationLookupQuerySchema", () => {
+  it("accepts a UUID", () => {
+    expect(
+      organizationLookupQuerySchema.parse({ organization_id: ORGANIZATION }),
+    ).toEqual({ organization_id: ORGANIZATION });
+  });
+
+  it.each(NOT_UUIDS)("rejects %j", (organization_id) => {
+    expect(
+      organizationLookupQuerySchema.safeParse({ organization_id }).success,
+    ).toBe(false);
+  });
+});
+
+describe("Brand, dynamic values and tracking schemas carry the Organization", () => {
+  it("the Brand list query keeps a UUID filter and rejects anything else", () => {
+    expect(
+      listBrandsQuerySchema.parse({ organization_id: ORGANIZATION })
+        .organization_id,
+    ).toBe(ORGANIZATION);
+    expect(
+      listBrandsQuerySchema.safeParse({ organization_id: "hotel-uno" }).success,
+    ).toBe(false);
+  });
+
+  it("the dynamic values query keeps a UUID Organization and rejects anything else", () => {
+    const query = { product: "connect" };
+    expect(
+      dynamicValuesQuerySchema.parse({
+        ...query,
+        organization_id: ORGANIZATION,
+      }).organization_id,
+    ).toBe(ORGANIZATION);
+    expect(
+      dynamicValuesQuerySchema.safeParse({
+        ...query,
+        organization_id: "hotel-uno",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("the tracking body keeps a UUID Organization and rejects anything else", () => {
+    const body = { eventName: "brand_created" };
+    expect(
+      trackingBodySchema.parse({ ...body, organization_id: ORGANIZATION })
+        .organization_id,
+    ).toBe(ORGANIZATION);
+    expect(
+      trackingBodySchema.safeParse({ ...body, organization_id: "hotel-uno" })
+        .success,
+    ).toBe(false);
+  });
+});

package/src/schemas/organization.ts

@@ -1,4 +1,43 @@
 import { z } from "zod";
+import { ReachableOrganization } from "../types/index.js";
+
+export const reachableOrganizationSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+}) satisfies z.ZodType<ReachableOrganization>;
+
+/** GET /organizations: the user's Reachable Organizations (ADR 0014). */
+export const reachableOrganizationListResponseSchema = z.array(
+  reachableOrganizationSchema,
+);
+
+/**
+ * Optional Organization filter of a list route (ADR 0014). Without it the
+ * list spans the user's Reachable Organizations; a value that is not
+ * reachable yields no data.
+ */
+export const organizationFilterQuerySchema = z.object({
+  organization_id: z.uuid().optional(),
+});
+
+/**
+ * Organization a resource is created in (ADR 0014). Optional only while the
+ * deprecated `sm-organization-id` header is accepted in its place: a request
+ * with neither is rejected by the route.
+ */
+export const organizationBodySchema = z.object({
+  organization_id: z.uuid().optional(),
+});
+
+/**
+ * Organization of a lookup route: one that reads Organization-scoped data
+ * without listing or creating a resource (ADR 0014). Optional only while the
+ * deprecated `sm-organization-id` header is accepted in its place: a request
+ * with neither is rejected by the route.
+ */
+export const organizationLookupQuerySchema = z.object({
+  organization_id: z.uuid().optional(),
+});
 
 /**
  * GET /organization/data passes through OrganizationData from Smartconnect —

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/schemas/tracking.ts

@@ -1,6 +1,8 @@
 import { z } from "zod";
+import { organizationBodySchema } from "./organization.js";
 
 export const trackingBodySchema = z.object({
   eventName: z.string().min(1, "eventName is required"),
   properties: z.record(z.string(), z.unknown()).optional(),
+  ...organizationBodySchema.shape,
 });

package/src/types/api/apiMessages.ts

@@ -1,6 +1,7 @@
 import type {
   MessageFromDb,
   MessageGroupFromDb,
+  MessageGroupProduct,
   MessageGroupVisibility,
   MessageStatus,
   RenderType,
@@ -12,8 +13,12 @@ export type MessageGroupWithMessages = MessageGroupFromDb & {
 };
 
 export interface DuplicateMessageGroupBody {
+  /** Organization the copy is created in (ADR 0014). */
+  organization_id?: string;
   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",
@@ -32,37 +34,21 @@ 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";
-  strategy?: "embed" | "native";
+  /** The Product the host app embeds the composer in (ADR 0011). Required. */
+  product: MessageGroupProduct;
   channels?: Array<"email" | "whatsapp">;
   languages?: string[];
   mainLanguage?: string;
+  /**
+   * The WABA the Host works on. Only a preselection when the user picks the
+   * WABA of a Message Group, valid if it is one of the Organization's
+   * (ADR 0015).
+   */
   metaWabaId?: string;
-  metaAccessToken?: string;
   organization_id?: string;
   default_tags?: string[];
 }
 
-export interface AppContextState extends AppContextConfig {
-  initializationSource:
-    | "query"
-    | "postMessage"
-    | "cookies"
-    | "injection"
-    | null;
-}
-
-export interface ContextSource {
-  name: string;
-  priority: number;
-  extract: () => Promise<Partial<AppContextConfig>>;
-  watch?: (
-    callback: (context: Partial<AppContextConfig>) => void,
-  ) => () => void;
-}
-
 export type ParentNotificationType =
   | "TEMPLATE_SAVED_DRAFT"
   | "TEMPLATE_SAVED"

package/src/types/index.ts

@@ -13,3 +13,5 @@ export * from "./submission-job.js";
 export * from "./kafka-events.js";
 export * from "./dynamic-values.js";
 export * from "./brand.js";
+export * from "./organization.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,13 +80,67 @@ 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 {
+  /** Narrows the list to one Reachable Organization (ADR 0014). */
+  organization_id?: string;
+  search?: string;
+  category?: MessageGroupCategory;
+  status?: MessageStatus;
+  product?: MessageGroupProduct;
+  visibility: MessageGroupListVisibility;
+  render_type?: RenderType;
+  /** Narrows the list to the Message Groups on one WABA (ADR 0015). */
+  waba_id?: string;
+  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;
+  /**
+   * The WABA the Message Group is submitted to: set at its first submission
+   * and fixed from then on, absent until then (ADR 0015).
+   */
+  waba_id?: string | null;
   user_id: string;
 }
 
@@ -154,6 +209,8 @@ export const brandCascadeDataSchema = z.object({
  * Request body for previewing a message with inline data (no DB lookups).
  */
 export const previewMessageRequestSchema = z.object({
+  /** Organization the preview is compiled for (ADR 0014). */
+  organization_id: z.uuid().optional(),
   message: z
     .object({
       render_type: z.literal("email_v1"),
@@ -203,6 +260,9 @@ export interface CompileAndSendRequest extends CompileMessageRequest {
  * Request body for testing email rendering
  */
 export interface TestEmailRequest {
+  /** Organization the test email is sent for (ADR 0014) */
+  organization_id?: string;
+
   /** Email message configuration */
   message: PostEntity<EmailMessage>;
 
@@ -311,6 +371,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 +413,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 +428,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/organization.ts

@@ -0,0 +1,19 @@
+/**
+ * An Organization the logged-in user has a role on, directly or through one of
+ * its properties (Reachable Organization, ADR 0014).
+ */
+export interface ReachableOrganization {
+  id: string;
+  name: string;
+}
+
+/**
+ * A WABA of an Organization. An Organization has none, one or several
+ * (ADR 0015). `phone_numbers` are the numbers connected to it, possibly none:
+ * a WABA is a valid submission target before its first number.
+ */
+export interface OrganizationWaba {
+  id: string;
+  name: string;
+  phone_numbers: 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];

package/src/types/submission-job.ts

@@ -29,3 +29,8 @@ export interface SubmissionJobResponse {
   status: "queued";
   message: string;
 }
+
+/** Body of the public submit routes: the WABA to submit to (ADR 0015). */
+export interface SubmitToWabaBody {
+  waba_id?: string;
+}