@dev.smartpricing/message-composer-utils 4.5.1-next.3 → 5.0.0-automations.0

package/src/schemas/automation.ts

@@ -0,0 +1,230 @@
+import { z } from "zod";
+import {
+  AUTOMATION_ACTION_STATUSES,
+  AUTOMATION_CHANNELS,
+  AUTOMATION_MESSAGE_GROUP_KEPT_REASONS,
+  Automation,
+  AutomationAction,
+  AutomationActionInput,
+  AutomationActionsInvalidDetails,
+  AutomationDeleteResult,
+  AutomationPartlySavedDetails,
+  CloneAutomationBody,
+  CreateAutomationBody,
+  MESSAGE_GROUP_PRODUCTS,
+  UpdateAutomationBody,
+} from "../types/index.js";
+import { conditionOperatorSchema, conditionSchema } from "./condition.js";
+import { messageGroupValidationErrorsSchema } from "./message-group.js";
+
+/**
+ * GET /automations: the Automations of one Organization for one Product.
+ * Both are required: the Automation Engine lists one Organization at a time
+ * (ADR 0016, a deviation from ADR 0014) and the Product is never read from
+ * the `sm-product` header (ADR 0011).
+ */
+export const automationListQuerySchema = z.object({
+  organization_id: z.uuid(),
+  product: z.enum(MESSAGE_GROUP_PRODUCTS),
+});
+
+/** GET /automations/:id: an Automation of another Product is not found. */
+export const automationQuerySchema = z.object({
+  product: z.enum(MESSAGE_GROUP_PRODUCTS),
+});
+
+/**
+ * DELETE /automations/:id: the Message Groups to delete with the Automation,
+ * one repeated `message_group_ids` each (ADR 0016). A single one reaches the
+ * schema as a string; the route always reads a list. The Product is in the
+ * query too: a DELETE has no body to name it in.
+ */
+export const deleteAutomationQuerySchema = automationQuerySchema.extend({
+  message_group_ids: z
+    .union([z.uuid(), z.array(z.uuid())])
+    .optional()
+    .transform((ids) => (ids === undefined ? [] : [ids].flat())),
+});
+
+const messageGroupRef = { id: z.uuid(), name: z.string() };
+
+/** 200 of a DELETE /automations/:id that selected Message Groups. */
+export const automationDeleteResponseSchema = z.object({
+  deleted: z.array(z.object(messageGroupRef)),
+  kept: z.array(
+    z.object({
+      ...messageGroupRef,
+      reason: z.enum(AUTOMATION_MESSAGE_GROUP_KEPT_REASONS),
+    }),
+  ),
+}) satisfies z.ZodType<AutomationDeleteResult>;
+
+/** Automation ids are the engine's (`aut_<uuid>`), not UUIDs. */
+export const automationIdParamsSchema = z.object({
+  id: z.string().min(1),
+});
+
+export const automationActionStatusSchema = z.enum(AUTOMATION_ACTION_STATUSES);
+
+/**
+ * An Action as served: the engine's `config` as stored, loose because the
+ * engine owns its shape (ADR 0016).
+ */
+export const automationActionSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  status: automationActionStatusSchema,
+  created_at: z.string(),
+  updated_at: z.string(),
+  config: z.looseObject({
+    template: z.string(),
+    channel: z.string(),
+    recipient: z.string(),
+    delay: z.number(),
+  }),
+}) satisfies z.ZodType<AutomationAction>;
+
+/**
+ * An Automation with its Actions embedded (ADR 0016). `settings` and
+ * `metadata` keep the engine's shapes, loose so a key the engine adds is
+ * served, not stripped; `active` is derived by the backend.
+ */
+export const automationResponseSchema = z.object({
+  id: z.string(),
+  organization_id: z.uuid(),
+  product: z.enum(MESSAGE_GROUP_PRODUCTS),
+  name: z.string(),
+  created_at: z.string(),
+  updated_at: z.string(),
+  active: z.boolean(),
+  settings: z.looseObject({
+    trigger: z.looseObject({
+      source: z.union([z.string(), z.array(z.string())]).optional(),
+      type: z.union([z.string(), z.array(z.string())]),
+    }),
+    conditions: z.array(
+      z.looseObject({
+        field: z.string(),
+        operator: z.string(),
+        value: z.unknown().optional(),
+      }),
+    ),
+  }),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  actions: z.array(automationActionSchema),
+}) satisfies z.ZodType<Automation>;
+
+export const automationListResponseSchema = z.array(automationResponseSchema);
+
+/**
+ * An Action as submitted: `config` keeps the engine's shape, loose for the
+ * rest of the Schedule. The recipient and the sender are not the client's
+ * to choose (ADR 0017).
+ */
+export const automationActionInputSchema = z.object({
+  status: automationActionStatusSchema,
+  config: z.looseObject({
+    template: z.string().min(1),
+    channel: z.enum(AUTOMATION_CHANNELS),
+    delay: z.number(),
+    dateTimeReference: z.string().min(1),
+  }),
+}) satisfies z.ZodType<AutomationActionInput>;
+
+/**
+ * POST /automations: an Automation and its Actions in one request
+ * (ADR 0016). The Organization and the Product are explicit in the body
+ * (ADR 0014, ADR 0011).
+ */
+export const createAutomationBodySchema = z.object({
+  organization_id: z.uuid(),
+  product: z.enum(MESSAGE_GROUP_PRODUCTS),
+  name: z.string().trim().min(1),
+  settings: z.looseObject({
+    trigger: z.looseObject({ type: z.string().min(1) }),
+    conditions: z.array(conditionSchema),
+  }),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  actions: z.array(automationActionInputSchema).min(1),
+}) satisfies z.ZodType<CreateAutomationBody>;
+
+/**
+ * PUT /automations/:id: the full list of Actions, each stored one named by
+ * its `id` (ADR 0016). The Product is explicit (ADR 0011); the Organization
+ * is the stored one and is not sent.
+ */
+export const updateAutomationBodySchema = createAutomationBodySchema
+  .omit({ organization_id: true })
+  .extend({
+    actions: z
+      .array(
+        automationActionInputSchema.extend({
+          id: z.string().min(1).optional(),
+        }),
+      )
+      .min(1),
+  }) satisfies z.ZodType<UpdateAutomationBody>;
+
+/**
+ * POST /automations/:id/clone: the name of the copy, and the Product as on
+ * every write (ADR 0011). Everything else is read from the source.
+ */
+export const cloneAutomationBodySchema = createAutomationBodySchema.pick({
+  product: true,
+  name: true,
+}) satisfies z.ZodType<CloneAutomationBody>;
+
+/** `details` of the 502 of an update that was saved only in part. */
+export const automationPartlySavedDetailsSchema = z.object({
+  automation: automationResponseSchema,
+  action_ids: z.array(z.string().nullable()),
+}) satisfies z.ZodType<AutomationPartlySavedDetails>;
+
+const position = z.number().int().nonnegative();
+
+const actionProblem = { target: z.literal("action"), position };
+
+/**
+ * `details` of the 422 `AUTOMATION_ACTIONS_INVALID`: a flat list, each
+ * entry naming its `target`. A new kind of problem is a new entry shape,
+ * never a change to an existing one.
+ */
+export const automationActionsInvalidDetailsSchema = z.object({
+  problems: z.array(
+    z.union([
+      z.object({
+        target: z.literal("trigger"),
+        reason: z.literal("not_in_catalog"),
+        type: z.string(),
+      }),
+      z.object({
+        target: z.literal("condition"),
+        position,
+        reason: z.enum(["field_not_in_catalog", "operator_not_allowed"]),
+        field: z.string(),
+        operator: conditionOperatorSchema,
+      }),
+      z.object({
+        ...actionProblem,
+        reason: z.enum(["not_found", "other_organization"]),
+        message_group_id: z.string(),
+      }),
+      z.object({
+        ...actionProblem,
+        reason: z.literal("invalid"),
+        message_group_id: z.string(),
+        errors: messageGroupValidationErrorsSchema,
+      }),
+      z.object({
+        ...actionProblem,
+        reason: z.literal("date_reference_not_in_catalog"),
+        date_reference: z.string(),
+      }),
+      z.object({
+        ...actionProblem,
+        reason: z.literal("channel_not_in_catalog"),
+        channel: z.enum(AUTOMATION_CHANNELS),
+      }),
+    ]),
+  ),
+}) satisfies z.ZodType<AutomationActionsInvalidDetails>;

package/src/schemas/condition.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import {
+  CONDITION_OPERATORS_BY_FIELD_TYPE,
+  conditionFieldTypeSchema,
+  conditionOperatorSchema,
+  conditionSchema,
+  operatorFitsFieldType,
+} from "./condition.js";
+
+describe("conditionSchema", () => {
+  it.each([
+    "eq",
+    "neq",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "in",
+    "not_in",
+    "contains",
+    "exclude",
+    "exists",
+  ])("accepts the engine operator %s", (operator) => {
+    const condition = { field: "guest.language", operator, value: "it" };
+    expect(conditionSchema.parse(condition)).toEqual(condition);
+  });
+
+  it("knows eleven operators and no other", () => {
+    expect(conditionOperatorSchema.options).toHaveLength(11);
+    expect(
+      conditionSchema.safeParse({ field: "status", operator: "is", value: 1 })
+        .success,
+    ).toBe(false);
+  });
+
+  it("accepts a Condition with no value", () => {
+    const condition = { field: "totalPrice", operator: "exists" };
+    expect(conditionSchema.parse(condition)).toEqual(condition);
+  });
+
+  it("keeps the value as it is, whatever its type", () => {
+    const condition = {
+      field: "guest.marketingConsent",
+      operator: "in",
+      value: [1, 2],
+    };
+    expect(conditionSchema.parse(condition)).toEqual(condition);
+  });
+
+  it("rejects a Condition with no field", () => {
+    expect(
+      conditionSchema.safeParse({ field: "", operator: "eq", value: 1 })
+        .success,
+    ).toBe(false);
+    expect(
+      conditionSchema.safeParse({ operator: "eq", value: 1 }).success,
+    ).toBe(false);
+  });
+});
+
+describe("the field types and their operators (ADR 0018)", () => {
+  it("has six field types", () => {
+    expect([...conditionFieldTypeSchema.options].sort()).toEqual([
+      "date",
+      "multiselect",
+      "number",
+      "price",
+      "select",
+      "text",
+    ]);
+  });
+
+  it("gives each field type the operators of the ADR's table", () => {
+    const comparison = ["eq", "neq", "gt", "gte", "lt", "lte", "exists"];
+    expect(CONDITION_OPERATORS_BY_FIELD_TYPE).toEqual({
+      select: ["eq", "neq", "exists"],
+      multiselect: ["in", "not_in", "exists"],
+      number: comparison,
+      price: comparison,
+      date: comparison,
+      text: ["eq", "neq", "contains", "exclude", "exists"],
+    });
+  });
+
+  it("tells whether an operator fits a field type", () => {
+    expect(operatorFitsFieldType("gte", "price")).toBe(true);
+    expect(operatorFitsFieldType("in", "multiselect")).toBe(true);
+    expect(operatorFitsFieldType("in", "select")).toBe(false);
+    expect(operatorFitsFieldType("contains", "number")).toBe(false);
+    expect(operatorFitsFieldType("exists", "text")).toBe(true);
+  });
+});

package/src/schemas/condition.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import {
+  CONDITION_FIELD_TYPES,
+  CONDITION_OPERATORS,
+  Condition,
+} from "../types/index.js";
+
+export const conditionOperatorSchema = z.enum(CONDITION_OPERATORS);
+
+export const conditionFieldTypeSchema = z.enum(CONDITION_FIELD_TYPES);
+
+/**
+ * A Condition in the Automation Engine's shape (ADR 0018). The value is not
+ * checked: what fits depends on the field, which only a catalog knows.
+ */
+export const conditionSchema = z.object({
+  field: z.string().min(1),
+  operator: conditionOperatorSchema,
+  value: z.unknown().optional(),
+}) satisfies z.ZodType<Condition>;
+
+// The type-to-operator table sits with the vocabulary it is made of, so the
+// layer can read it without the schemas.
+export {
+  CONDITION_OPERATORS_BY_FIELD_TYPE,
+  operatorFitsFieldType,
+} from "../types/index.js";

package/src/schemas/index.ts

@@ -13,3 +13,6 @@ export * from "./message-compilation.js";
 export * from "./meta-integration.js";
 export * from "./onboarding.js";
 export * from "./tracking.js";
+export * from "./automation.js";
+export * from "./condition.js";
+export * from "./automation-catalog.js";

package/src/schemas/message-group.ts

@@ -3,6 +3,7 @@ import {
   DuplicateMessageGroupBody,
   ListMessageGroupsQuery,
   MessageGroupFromDb,
+  MessageGroupValidationErrors,
   MessageGroupWithMessageSummary,
   MESSAGE_GROUP_CATEGORIES,
   MESSAGE_GROUP_LIST_SORT,
@@ -123,17 +124,20 @@ export const messageGroupSummaryListResponseSchema = paginatedResponseSchema(
   messageGroupWithMessageSummaryResponseSchema,
 );
 
+/** The errors of the Message Group validation, by what they are about. */
+export const messageGroupValidationErrorsSchema = z.object({
+  status: z.array(z.string()),
+  languages: z.array(z.string()),
+  content: z.record(
+    z.string(),
+    z.object({
+      type: z.enum(MESSAGE_RENDER_TYPES),
+      errors: z.array(z.string()),
+    }),
+  ),
+}) satisfies z.ZodType<MessageGroupValidationErrors>;
+
 export const messageGroupValidationResponseSchema = z.object({
   valid: z.boolean(),
-  errors: z.object({
-    status: z.array(z.string()),
-    languages: z.array(z.string()),
-    content: z.record(
-      z.string(),
-      z.object({
-        type: z.string(),
-        errors: z.array(z.string()),
-      }),
-    ),
-  }),
+  errors: messageGroupValidationErrorsSchema,
 });

package/src/types/app.ts

@@ -21,6 +21,9 @@ export const errorCodes = {
   UNSUPPORTED_RENDER_TYPE: "UNSUPPORTED_RENDER_TYPE",
   NOT_IMPLEMENTED: "NOT_IMPLEMENTED",
   TRANSLATION_TOKEN_MISMATCH: "TRANSLATION_TOKEN_MISMATCH",
+  UPSTREAM_ERROR: "UPSTREAM_ERROR",
+  AUTOMATION_ACTIONS_INVALID: "AUTOMATION_ACTIONS_INVALID",
+  SYSTEM_AUTOMATION_NOT_DELETABLE: "SYSTEM_AUTOMATION_NOT_DELETABLE",
 } as const;
 
 type ErrorCode = keyof typeof errorCodes;
@@ -40,8 +43,9 @@ export interface AppContextConfig {
   languages?: string[];
   mainLanguage?: string;
   /**
-   * The WABA the Host works on: a new Message Group is submitted to it when
-   * it is one of the Organization's (ADR 0015).
+   * 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;
   organization_id?: string;

package/src/types/automation-catalog.ts

@@ -0,0 +1,79 @@
+import type { Condition, ConditionFieldType } from "./condition.js";
+
+/**
+ * The Automation Catalog (ADR 0017): what an Automation of a Product can be
+ * built from. The backend keeps one config per Product with a label per
+ * language and serves it resolved to the requested one.
+ */
+
+/** The languages a catalog holds a label in. */
+export const AUTOMATION_CATALOG_LANGUAGES = [
+  "en",
+  "it",
+  "de",
+  "es",
+  "fr",
+] as const;
+
+export type AutomationCatalogLanguage =
+  (typeof AUTOMATION_CATALOG_LANGUAGES)[number];
+
+export const AUTOMATION_CHANNELS = ["email", "whatsapp"] as const;
+
+export type AutomationChannel = (typeof AUTOMATION_CHANNELS)[number];
+
+export const DATE_REFERENCE_DIRECTIONS = ["after", "before"] as const;
+
+export type DateReferenceDirection = (typeof DATE_REFERENCE_DIRECTIONS)[number];
+
+/** A label in every language of the catalog, as the backend keeps it. */
+export type AutomationCatalogLabels = Record<AutomationCatalogLanguage, string>;
+
+/**
+ * The shapes below take the type of a label: a string as the route serves
+ * them, in one language, or `AutomationCatalogLabels` as the backend keeps
+ * them.
+ */
+
+export interface ConditionField<Label = string> {
+  /** Dot path into the Trigger Event's data. */
+  key: string;
+  label: Label;
+  type: ConditionFieldType;
+  /**
+   * The name of the option list the Host supplies for this field. The
+   * catalog holds no option of its own.
+   */
+  option_list?: string;
+}
+
+export interface DateReference<Label = string> {
+  key: string;
+  /** The directions a delay can count in, in display order. */
+  directions: { direction: DateReferenceDirection; label: Label }[];
+}
+
+/** A Channel a Trigger can send over, with whom its Actions send to and from. */
+export interface AutomationCatalogChannel {
+  channel: AutomationChannel;
+  recipient: string;
+  sender: string;
+}
+
+export interface AutomationTrigger<Label = string> {
+  type: string;
+  label: Label;
+  date_references: DateReference<Label>[];
+  condition_fields: ConditionField<Label>[];
+  default_conditions: Condition[];
+  channels: AutomationCatalogChannel[];
+}
+
+export interface AutomationCatalog<Label = string> {
+  triggers: AutomationTrigger<Label>[];
+}
+
+/** `catalog` is null for a Product that has no Automation Catalog. */
+export interface AutomationCatalogResponse {
+  catalog: AutomationCatalog | null;
+}