@dev.smartpricing/message-composer-utils 4.5.1-next.2 → 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;

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;
+}

package/src/types/automation.ts

@@ -0,0 +1,216 @@
+import type { AutomationChannel } from "./automation-catalog.js";
+import type { Condition, ConditionOperator } from "./condition.js";
+import type {
+  MessageGroupProduct,
+  MessageGroupValidationErrors,
+} from "./message.js";
+
+/**
+ * Automations as the composer's API serves them (ADR 0016). The envelope
+ * speaks the composer's names; `settings`, `metadata` and an Action's
+ * `config` keep the Automation Engine's shapes, open to keys it adds.
+ */
+
+export const AUTOMATION_ACTION_STATUSES = ["active", "inactive"] as const;
+
+export type AutomationActionStatus =
+  (typeof AUTOMATION_ACTION_STATUSES)[number];
+
+export interface AutomationCondition {
+  field: string;
+  operator: string;
+  value?: unknown;
+  [key: string]: unknown;
+}
+
+export interface AutomationSettings {
+  trigger: {
+    source?: string | string[];
+    type: string | string[];
+    [key: string]: unknown;
+  };
+  conditions: AutomationCondition[];
+  [key: string]: unknown;
+}
+
+/** The engine's Action config: `template` is the id of a Message Group. */
+export interface AutomationActionConfig {
+  template: string;
+  channel: string;
+  recipient: string;
+  delay: number;
+  [key: string]: unknown;
+}
+
+export interface AutomationAction {
+  id: string;
+  type: string;
+  status: AutomationActionStatus;
+  created_at: string;
+  updated_at: string;
+  config: AutomationActionConfig;
+}
+
+export interface Automation {
+  id: string;
+  organization_id: string;
+  product: MessageGroupProduct;
+  name: string;
+  created_at: string;
+  updated_at: string;
+  /** Derived: at least one Active Action. */
+  active: boolean;
+  settings: AutomationSettings;
+  metadata?: Record<string, unknown>;
+  actions: AutomationAction[];
+}
+
+/**
+ * An Action as a client submits it (ADR 0016). It has no `type`, recipient
+ * or sender to choose: the backend writes them at save (ADR 0017), and
+ * ignores a `recipient` or `sender` sent in `config`.
+ */
+export interface AutomationActionInput {
+  status: AutomationActionStatus;
+  config: {
+    /** The id of the Message Group the Action sends. */
+    template: string;
+    channel: AutomationChannel;
+    delay: number;
+    /** The key of the Action's Date Reference. */
+    dateTimeReference: string;
+    [key: string]: unknown;
+  };
+}
+
+/** One Trigger, with no `source`: the backend sets it from the Product. */
+export interface AutomationSettingsInput {
+  trigger: { type: string; [key: string]: unknown };
+  conditions: Condition[];
+  [key: string]: unknown;
+}
+
+/** Body of `POST /automations`: an Automation with its Actions. */
+export interface CreateAutomationBody {
+  organization_id: string;
+  product: MessageGroupProduct;
+  name: string;
+  settings: AutomationSettingsInput;
+  metadata?: Record<string, unknown>;
+  actions: AutomationActionInput[];
+}
+
+/**
+ * An Action in the full list an update submits (ADR 0016): without an `id`
+ * it is new, with one it is the stored Action of that id.
+ */
+export interface AutomationActionUpdateInput extends AutomationActionInput {
+  id?: string;
+}
+
+/**
+ * Body of `PUT /automations/:id`. It names no Organization: an Automation
+ * never changes it. `metadata` is merged into what is stored.
+ */
+export interface UpdateAutomationBody {
+  product: MessageGroupProduct;
+  name: string;
+  settings: AutomationSettingsInput;
+  metadata?: Record<string, unknown>;
+  /** Every Action the Automation keeps: a stored one left out is deleted. */
+  actions: AutomationActionUpdateInput[];
+}
+
+/**
+ * Body of `POST /automations/:id/clone` (ADR 0016). The copy is made from
+ * the Automation as stored, never from what a client holds: the request
+ * only names it.
+ */
+export interface CloneAutomationBody {
+  product: MessageGroupProduct;
+  name: string;
+}
+
+/**
+ * `details` of the 502 of an update that failed after its first write
+ * (ADR 0016): nothing is rolled back, so this is what a retry starts from.
+ */
+export interface AutomationPartlySavedDetails {
+  /** The Automation as it now stands in the Automation Engine. */
+  automation: Automation;
+  /**
+   * The id of each submitted Action, by position: `null` for a new Action
+   * that was not created. A retry that sends these ids creates nothing twice.
+   */
+  action_ids: Array<string | null>;
+}
+
+/**
+ * One thing that keeps an Automation from being saved. `target` names what
+ * it is about; an Action and a Condition are pointed at by `position`, their
+ * index in the submitted list, since a new Action has no id to be named by.
+ * A client skips a `target` or a `reason` it does not know.
+ */
+export type AutomationSaveProblem =
+  | { target: "trigger"; reason: "not_in_catalog"; type: string }
+  | {
+      target: "condition";
+      /** Index in `settings.conditions`. */
+      position: number;
+      reason: "field_not_in_catalog" | "operator_not_allowed";
+      field: string;
+      operator: ConditionOperator;
+    }
+  | ({ target: "action"; position: number } & (
+      | {
+          reason: "not_found" | "other_organization";
+          message_group_id: string;
+        }
+      | {
+          reason: "invalid";
+          message_group_id: string;
+          /** The errors of the Message Group validation. */
+          errors: MessageGroupValidationErrors;
+        }
+      | { reason: "date_reference_not_in_catalog"; date_reference: string }
+      | { reason: "channel_not_in_catalog"; channel: AutomationChannel }
+    ));
+
+export type AutomationActionProblem = Extract<
+  AutomationSaveProblem,
+  { target: "action" }
+>;
+
+export type AutomationConditionProblem = Extract<
+  AutomationSaveProblem,
+  { target: "condition" }
+>;
+
+/**
+ * `details` of the 422 `AUTOMATION_ACTIONS_INVALID`: everything that keeps
+ * an Automation from being saved, found before anything is written. One
+ * flat list: the Trigger first, then Conditions and Actions by position.
+ */
+export interface AutomationActionsInvalidDetails {
+  problems: AutomationSaveProblem[];
+}
+
+/** Why a selected Message Group is still there after its Automation went. */
+export const AUTOMATION_MESSAGE_GROUP_KEPT_REASONS = ["delete_failed"] as const;
+
+export type AutomationMessageGroupKeptReason =
+  (typeof AUTOMATION_MESSAGE_GROUP_KEPT_REASONS)[number];
+
+/**
+ * Answer of a `DELETE /automations/:id` that selected Message Groups
+ * (ADR 0016): the Automation is gone, and each selected Message Group is
+ * either `deleted` or `kept`. A client skips a `reason` it does not know.
+ */
+export interface AutomationDeleteResult {
+  deleted: Array<{ id: string; name: string }>;
+  kept: Array<{
+    id: string;
+    name: string;
+    reason: AutomationMessageGroupKeptReason;
+  }>;
+}