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

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

package/src/types/condition.ts

@@ -0,0 +1,114 @@
+/**
+ * Conditions in the Automation Engine's shape, and the closed vocabulary the
+ * filter components and the backend share (ADR 0018). Nothing here knows
+ * about Automations: an audience page edits Conditions too.
+ */
+
+/** Every operator the Automation Engine accepts. */
+export const CONDITION_OPERATORS = [
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "in",
+  "not_in",
+  "contains",
+  "exclude",
+  "exists",
+] as const;
+
+export type ConditionOperator = (typeof CONDITION_OPERATORS)[number];
+
+export const CONDITION_FIELD_TYPES = [
+  "select",
+  "multiselect",
+  "number",
+  "price",
+  "date",
+  "text",
+] as const;
+
+export type ConditionFieldType = (typeof CONDITION_FIELD_TYPES)[number];
+
+/** One test on a Trigger Event's data. `exists` takes no value. */
+export interface Condition {
+  field: string;
+  operator: ConditionOperator;
+  value?: unknown;
+}
+
+/** The operators of the field types whose values have an order. */
+const ORDERED_VALUE_OPERATORS = [
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "exists",
+] as const satisfies readonly ConditionOperator[];
+
+/** The operators a Condition on a field of each type can use (ADR 0018). */
+export const CONDITION_OPERATORS_BY_FIELD_TYPE = {
+  select: ["eq", "neq", "exists"],
+  multiselect: ["in", "not_in", "exists"],
+  number: ORDERED_VALUE_OPERATORS,
+  price: ORDERED_VALUE_OPERATORS,
+  date: ORDERED_VALUE_OPERATORS,
+  text: ["eq", "neq", "contains", "exclude", "exists"],
+} as const satisfies Record<ConditionFieldType, readonly ConditionOperator[]>;
+
+export function operatorFitsFieldType(
+  operator: ConditionOperator,
+  fieldType: ConditionFieldType,
+): boolean {
+  const operators: readonly ConditionOperator[] =
+    CONDITION_OPERATORS_BY_FIELD_TYPE[fieldType];
+  return operators.includes(operator);
+}
+
+/**
+ * What a caller passes to the layer's filter components (`FiltersEditor`,
+ * `FiltersSummary`) and what they report back (ADR 0018).
+ */
+
+export type FilterOptionValue = string | number;
+
+export interface FilterOption {
+  value: FilterOptionValue;
+  label: string;
+}
+
+/** One field a Condition can test, label and options already resolved. */
+export interface FilterField {
+  /** The `field` of the Conditions on it. */
+  key: string;
+  label: string;
+  type: ConditionFieldType;
+  /** For `select` and `multiselect`. A list that is not there shows as empty. */
+  options?: FilterOption[];
+}
+
+/**
+ * Why a Condition shows as an unavailable row: its field is not in `fields`,
+ * or the editor cannot edit it (an operator or a value that does not fit the
+ * field's type, one Condition too many on a field).
+ */
+export type FilterUnavailableReason = "unknown_field" | "not_editable";
+
+/** What is wrong with a list of Conditions. The caller decides what blocks. */
+export interface FiltersReport {
+  /** The fields of the Conditions that are on none of `fields`, each once. */
+  unknownFields: string[];
+  /** Every Condition shown as an unavailable row, the unknown fields included. */
+  unavailable: { condition: Condition; reason: FilterUnavailableReason }[];
+  /** Every selected option value that is not in its field's `options`. */
+  unavailableOptions: { field: string; value: FilterOptionValue }[];
+  /**
+   * Rows with a field picked and no complete value. They are not in the
+   * emitted Conditions. Always 0 from `FiltersSummary`.
+   */
+  halfFilled: number;
+}

package/src/types/index.ts

@@ -15,3 +15,6 @@ export * from "./dynamic-values.js";
 export * from "./brand.js";
 export * from "./organization.js";
 export * from "./pagination.js";
+export * from "./automation.js";
+export * from "./condition.js";
+export * from "./automation-catalog.js";