@carlonicora/nextjs-jsonapi 5.2.0 → 5.3.0

package/src/features/email-automation/contexts/EmailAutomationContext.tsx

@@ -0,0 +1,175 @@
+"use client";
+
+import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { v4 } from "uuid";
+import { EmailAutomationInterface } from "../data/EmailAutomationInterface";
+import { EmailAutomationService } from "../data/EmailAutomationService";
+import { EmailAutomationStepInput, EmailAutomationStepInterface } from "../data/EmailAutomationStepInterface";
+import { EmailAutomationStepService } from "../data/EmailAutomationStepService";
+import { EmailAutomationTriggerInterface } from "../data/EmailAutomationTriggerInterface";
+
+/** A new step: the provider always sets `automationId` and, when absent, a fresh `id`. */
+export type EmailAutomationStepCreateInput = Omit<EmailAutomationStepInput, "id" | "automationId"> & {
+  id?: string;
+  automationId?: string;
+};
+/** A step update: the provider always sets `automationId`. */
+export type EmailAutomationStepUpdateInput = Omit<EmailAutomationStepInput, "automationId"> & { automationId?: string };
+
+export interface EmailAutomationContextType {
+  automation: EmailAutomationInterface | undefined;
+  steps: EmailAutomationStepInterface[];
+  reload: () => Promise<void>;
+  selectedStepId: string | null;
+  select: (id: string | null) => void;
+  createStep: (input: EmailAutomationStepCreateInput) => Promise<EmailAutomationStepInterface>;
+  updateStep: (input: EmailAutomationStepUpdateInput) => Promise<EmailAutomationStepInterface>;
+  deleteStep: (id: string) => Promise<void>;
+  setNext: (stepId: string, nextStepId: string | null) => Promise<void>;
+  updatePosition: (stepId: string, x: number, y: number) => Promise<void>;
+  tidy: () => Promise<void>;
+  triggers: EmailAutomationTriggerInterface[];
+}
+
+const EmailAutomationContext = createContext<EmailAutomationContextType | undefined>(undefined);
+
+export type EmailAutomationProviderProps = {
+  automationId: string;
+  children: ReactNode;
+};
+
+export const EmailAutomationProvider = ({ automationId, children }: EmailAutomationProviderProps) => {
+  const [automation, setAutomation] = useState<EmailAutomationInterface | undefined>(undefined);
+  const [steps, setSteps] = useState<EmailAutomationStepInterface[]>([]);
+  const [triggers, setTriggers] = useState<EmailAutomationTriggerInterface[]>([]);
+  const [selectedStepId, setSelectedStepId] = useState<string | null>(null);
+
+  const reload = useCallback(async () => {
+    const [loadedAutomation, loadedSteps] = await Promise.all([
+      EmailAutomationService.findOne({ id: automationId }),
+      EmailAutomationStepService.findByAutomation({ automationId }),
+    ]);
+    setAutomation(loadedAutomation);
+    setSteps(loadedSteps);
+  }, [automationId]);
+
+  useEffect(() => {
+    void reload();
+  }, [reload]);
+
+  useEffect(() => {
+    let active = true;
+    EmailAutomationService.findTriggers()
+      .then((list) => {
+        if (active) setTriggers(list);
+      })
+      .catch(() => {});
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  const select = useCallback((id: string | null) => setSelectedStepId(id), []);
+
+  const createStep = useCallback(
+    async (input: EmailAutomationStepCreateInput) => {
+      const saved = await EmailAutomationStepService.create({ ...input, id: input.id ?? v4(), automationId });
+      await reload();
+      return saved;
+    },
+    [automationId, reload],
+  );
+
+  const updateStep = useCallback(
+    async (input: EmailAutomationStepUpdateInput) => {
+      const saved = await EmailAutomationStepService.update({ ...input, automationId });
+      await reload();
+      return saved;
+    },
+    [automationId, reload],
+  );
+
+  const deleteStep = useCallback(
+    async (id: string) => {
+      await EmailAutomationStepService.delete({ id });
+      if (selectedStepId === id) setSelectedStepId(null);
+      await reload();
+    },
+    [reload, selectedStepId],
+  );
+
+  const setNext = useCallback(
+    async (stepId: string, nextStepId: string | null) => {
+      if (nextStepId) await EmailAutomationStepService.setNext({ stepId, nextStepId });
+      else await EmailAutomationStepService.clearNext({ stepId });
+      await reload();
+    },
+    [reload],
+  );
+
+  // PATCH with the step's current attributes plus the new position: the step
+  // input type requires subject and body, and sending them unchanged is a no-op.
+  const updatePosition = useCallback(
+    async (stepId: string, x: number, y: number) => {
+      const step = steps.find((candidate) => candidate.id === stepId);
+      if (!step) return;
+      await EmailAutomationStepService.update({
+        id: step.id,
+        automationId,
+        subject: step.subject,
+        body: step.body,
+        delayHours: step.delayHours,
+        positionX: x,
+        positionY: y,
+      });
+      await reload();
+    },
+    [automationId, reload, steps],
+  );
+
+  const tidy = useCallback(async () => {
+    await EmailAutomationService.tidy({ id: automationId });
+    await reload();
+  }, [automationId, reload]);
+
+  const value = useMemo<EmailAutomationContextType>(
+    () => ({
+      automation,
+      steps,
+      reload,
+      selectedStepId,
+      select,
+      createStep,
+      updateStep,
+      deleteStep,
+      setNext,
+      updatePosition,
+      tidy,
+      triggers,
+    }),
+    [
+      automation,
+      steps,
+      reload,
+      selectedStepId,
+      select,
+      createStep,
+      updateStep,
+      deleteStep,
+      setNext,
+      updatePosition,
+      tidy,
+      triggers,
+    ],
+  );
+
+  return <EmailAutomationContext.Provider value={value}>{children}</EmailAutomationContext.Provider>;
+};
+
+export const useEmailAutomation = (): EmailAutomationContextType => {
+  const context = useContext(EmailAutomationContext);
+  if (context === undefined) {
+    throw new Error("useEmailAutomation must be used within an EmailAutomationProvider");
+  }
+  return context;
+};

package/src/features/email-automation/data/EmailAutomation.ts

@@ -0,0 +1,87 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { EmailAutomationInput, EmailAutomationInterface } from "./EmailAutomationInterface";
+
+export class EmailAutomation extends AbstractApiData implements EmailAutomationInterface {
+  private _name?: string;
+  private _trigger?: string;
+  private _exitTrigger?: string;
+  private _replyTo?: string;
+  private _isActive: boolean = false;
+  private _stepCount?: number;
+  private _activeCount?: number;
+  private _completedCount?: number;
+  private _unsubscribedCount?: number;
+
+  get name(): string {
+    return this._name ?? "";
+  }
+
+  get trigger(): string | undefined {
+    return this._trigger;
+  }
+
+  get exitTrigger(): string | undefined {
+    return this._exitTrigger;
+  }
+
+  get replyTo(): string | undefined {
+    return this._replyTo;
+  }
+
+  get isActive(): boolean {
+    return this._isActive;
+  }
+
+  get stepCount(): number {
+    return this._stepCount ?? 0;
+  }
+
+  get activeCount(): number {
+    return this._activeCount ?? 0;
+  }
+
+  get completedCount(): number {
+    return this._completedCount ?? 0;
+  }
+
+  get unsubscribedCount(): number {
+    return this._unsubscribedCount ?? 0;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    this._name = data.jsonApi.attributes.name;
+    this._trigger = data.jsonApi.attributes.trigger ?? undefined;
+    this._exitTrigger = data.jsonApi.attributes.exitTrigger ?? undefined;
+    this._replyTo = data.jsonApi.attributes.replyTo ?? undefined;
+    this._isActive = data.jsonApi.attributes.isActive === true;
+    this._stepCount = data.jsonApi.attributes.stepCount;
+    this._activeCount = data.jsonApi.attributes.activeCount;
+    this._completedCount = data.jsonApi.attributes.completedCount;
+    this._unsubscribedCount = data.jsonApi.attributes.unsubscribedCount;
+
+    return this;
+  }
+
+  createJsonApi(data: EmailAutomationInput) {
+    const response: any = {
+      data: {
+        type: Modules.EmailAutomation.name,
+        id: data.id,
+        attributes: {},
+        meta: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.name !== undefined) response.data.attributes.name = data.name;
+    if (data.trigger !== undefined) response.data.attributes.trigger = data.trigger;
+    if (data.exitTrigger !== undefined) response.data.attributes.exitTrigger = data.exitTrigger;
+    if (data.replyTo !== undefined) response.data.attributes.replyTo = data.replyTo;
+    if (data.isActive !== undefined) response.data.attributes.isActive = data.isActive;
+
+    return response;
+  }
+}

package/src/features/email-automation/data/EmailAutomationEnrollment.ts

@@ -0,0 +1,105 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import {
+  EmailAutomationEnrollmentInterface,
+  EmailAutomationEnrollmentStatus,
+} from "./EmailAutomationEnrollmentInterface";
+import { EmailAutomationInterface } from "./EmailAutomationInterface";
+
+/** JSON:API type of the POST email-automations/unsubscribe/:token request body (not a module: nothing is stored). */
+export const EMAIL_AUTOMATION_UNSUBSCRIBE_TYPE = "email-automation-unsubscribes";
+
+export class EmailAutomationEnrollment extends AbstractApiData implements EmailAutomationEnrollmentInterface {
+  private _email?: string;
+  private _name?: string;
+  private _status: EmailAutomationEnrollmentStatus = "active";
+  private _enrolledAt?: Date;
+  private _nextSendAt?: Date;
+  private _finishedAt?: Date;
+  private _attempts?: number;
+  private _lastError?: string;
+  private _currentStepSubject?: string;
+  private _sentCount?: number;
+  private _automation?: EmailAutomationInterface;
+
+  get email(): string {
+    return this._email ?? "";
+  }
+
+  get name(): string | undefined {
+    return this._name;
+  }
+
+  get status(): EmailAutomationEnrollmentStatus {
+    return this._status;
+  }
+
+  get enrolledAt(): Date {
+    return this._enrolledAt ?? new Date(0);
+  }
+
+  get nextSendAt(): Date | undefined {
+    return this._nextSendAt;
+  }
+
+  get finishedAt(): Date | undefined {
+    return this._finishedAt;
+  }
+
+  get attempts(): number {
+    return this._attempts ?? 0;
+  }
+
+  get lastError(): string | undefined {
+    return this._lastError;
+  }
+
+  get currentStepSubject(): string | undefined {
+    return this._currentStepSubject;
+  }
+
+  get sentCount(): number {
+    return this._sentCount ?? 0;
+  }
+
+  get automation(): EmailAutomationInterface | undefined {
+    return this._automation;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes;
+    this._email = attributes.email;
+    this._name = attributes.name ?? undefined;
+    this._status = attributes.status ?? "active";
+    this._enrolledAt = attributes.enrolledAt ? new Date(attributes.enrolledAt) : undefined;
+    this._nextSendAt = attributes.nextSendAt ? new Date(attributes.nextSendAt) : undefined;
+    this._finishedAt = attributes.finishedAt ? new Date(attributes.finishedAt) : undefined;
+    this._attempts = attributes.attempts;
+    this._lastError = attributes.lastError ?? undefined;
+    this._currentStepSubject = attributes.currentStepSubject ?? undefined;
+    this._sentCount = attributes.sentCount;
+
+    this._automation = this._readIncluded(data, "automation", Modules.EmailAutomation) as EmailAutomationInterface;
+
+    return this;
+  }
+
+  createJsonApi(_data?: any): any {
+    throw new Error("EmailAutomationEnrollment is created by the API and cannot be created from the client");
+  }
+
+  /**
+   * Body of POST email-automations/unsubscribe/:token.
+   */
+  createUnsubscribeJsonApi(params: { scope: "automation" | "all" }) {
+    return {
+      data: {
+        type: EMAIL_AUTOMATION_UNSUBSCRIBE_TYPE,
+        attributes: {
+          scope: params.scope,
+        },
+      },
+    };
+  }
+}

package/src/features/email-automation/data/EmailAutomationEnrollmentInterface.ts

@@ -0,0 +1,18 @@
+import { ApiDataInterface } from "../../../core";
+import { EmailAutomationInterface } from "./EmailAutomationInterface";
+
+export type EmailAutomationEnrollmentStatus = "active" | "completed" | "unsubscribed" | "exited" | "failed";
+
+export interface EmailAutomationEnrollmentInterface extends ApiDataInterface {
+  get email(): string;
+  get name(): string | undefined;
+  get status(): EmailAutomationEnrollmentStatus;
+  get enrolledAt(): Date;
+  get nextSendAt(): Date | undefined;
+  get finishedAt(): Date | undefined;
+  get attempts(): number;
+  get lastError(): string | undefined;
+  get currentStepSubject(): string | undefined;
+  get sentCount(): number;
+  get automation(): EmailAutomationInterface | undefined;
+}

package/src/features/email-automation/data/EmailAutomationEnrollmentService.ts

@@ -0,0 +1,31 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { EmailAutomationEnrollment } from "./EmailAutomationEnrollment";
+import { EmailAutomationEnrollmentInterface } from "./EmailAutomationEnrollmentInterface";
+
+export class EmailAutomationEnrollmentService extends AbstractService {
+  /**
+   * POST email-automations/unsubscribe/:token (public). The scope travels both as
+   * a query parameter and in the body, as the API reads either.
+   */
+  static async unsubscribe(params: {
+    token: string;
+    scope: "automation" | "all";
+  }): Promise<EmailAutomationEnrollmentInterface> {
+    const enrollment = new EmailAutomationEnrollment();
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.EmailAutomation,
+      childEndpoint: "unsubscribe",
+      childId: params.token,
+    });
+
+    endpoint.addAdditionalParam("scope", params.scope);
+
+    return this.callApi<EmailAutomationEnrollmentInterface>({
+      type: Modules.EmailAutomationEnrollment,
+      method: HttpMethod.POST,
+      endpoint: endpoint.generate(),
+      input: enrollment.createUnsubscribeJsonApi({ scope: params.scope }),
+      overridesJsonApiCreation: true,
+    });
+  }
+}

package/src/features/email-automation/data/EmailAutomationInterface.ts

@@ -0,0 +1,22 @@
+import { ApiDataInterface } from "../../../core";
+
+export type EmailAutomationInput = {
+  id: string;
+  name: string;
+  trigger?: string;
+  exitTrigger?: string;
+  replyTo?: string;
+  isActive?: boolean;
+};
+
+export interface EmailAutomationInterface extends ApiDataInterface {
+  get name(): string;
+  get trigger(): string | undefined;
+  get exitTrigger(): string | undefined;
+  get replyTo(): string | undefined;
+  get isActive(): boolean;
+  get stepCount(): number;
+  get activeCount(): number;
+  get completedCount(): number;
+  get unsubscribedCount(): number;
+}

package/src/features/email-automation/data/EmailAutomationService.ts

@@ -0,0 +1,106 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef, PreviousRef } from "../../../core";
+import { EmailAutomationEnrollmentInterface } from "./EmailAutomationEnrollmentInterface";
+import { EmailAutomationInput, EmailAutomationInterface } from "./EmailAutomationInterface";
+import { EmailAutomationTriggerInterface } from "./EmailAutomationTriggerInterface";
+
+export class EmailAutomationService extends AbstractService {
+  static async findMany(params: { next?: NextRef; previous?: PreviousRef } = {}): Promise<EmailAutomationInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.EmailAutomation });
+
+    if (Modules.EmailAutomation.inclusions?.lists?.fields)
+      endpoint.limitToFields(Modules.EmailAutomation.inclusions.lists.fields);
+    if (Modules.EmailAutomation.inclusions?.lists?.types)
+      endpoint.limitToType(Modules.EmailAutomation.inclusions.lists.types);
+
+    return this.callApi<EmailAutomationInterface[]>({
+      type: Modules.EmailAutomation,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params.next,
+      previous: params.previous,
+    });
+  }
+
+  static async findOne(params: { id: string }): Promise<EmailAutomationInterface> {
+    return this.callApi<EmailAutomationInterface>({
+      type: Modules.EmailAutomation,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: Modules.EmailAutomation, id: params.id }).generate(),
+    });
+  }
+
+  static async create(params: EmailAutomationInput): Promise<EmailAutomationInterface> {
+    return this.callApi<EmailAutomationInterface>({
+      type: Modules.EmailAutomation,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.EmailAutomation }).generate(),
+      input: params,
+    });
+  }
+
+  static async update(params: EmailAutomationInput): Promise<EmailAutomationInterface> {
+    return this.callApi<EmailAutomationInterface>({
+      type: Modules.EmailAutomation,
+      method: HttpMethod.PATCH,
+      endpoint: new EndpointCreator({ endpoint: Modules.EmailAutomation, id: params.id }).generate(),
+      input: params,
+    });
+  }
+
+  static async delete(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.EmailAutomation,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({ endpoint: Modules.EmailAutomation, id: params.id }).generate(),
+    });
+  }
+
+  /**
+   * GET email-automations/triggers: the triggers the app declared to the API.
+   */
+  static async findTriggers(): Promise<EmailAutomationTriggerInterface[]> {
+    return this.callApi<EmailAutomationTriggerInterface[]>({
+      type: Modules.EmailAutomationTrigger,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: Modules.EmailAutomation, id: "triggers" }).generate(),
+    });
+  }
+
+  /**
+   * POST email-automations/:id/tidy: clears every manual step position. Replies 204.
+   */
+  static async tidy(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.EmailAutomation,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.EmailAutomation,
+        id: params.id,
+        childEndpoint: "tidy",
+      }).generate(),
+    });
+  }
+
+  static async findEnrollments(params: {
+    automationId: string;
+    status?: string;
+    next?: NextRef;
+    previous?: PreviousRef;
+  }): Promise<EmailAutomationEnrollmentInterface[]> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.EmailAutomation,
+      id: params.automationId,
+      childEndpoint: Modules.EmailAutomationEnrollment,
+    });
+
+    if (params.status) endpoint.addAdditionalParam("status", params.status);
+
+    return this.callApi<EmailAutomationEnrollmentInterface[]>({
+      type: Modules.EmailAutomationEnrollment,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params.next,
+      previous: params.previous,
+    });
+  }
+}

package/src/features/email-automation/data/EmailAutomationStep.ts

@@ -0,0 +1,104 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { EmailAutomationInterface } from "./EmailAutomationInterface";
+import { EmailAutomationStepInput, EmailAutomationStepInterface } from "./EmailAutomationStepInterface";
+
+export class EmailAutomationStep extends AbstractApiData implements EmailAutomationStepInterface {
+  private _subject?: string;
+  private _body?: string;
+  private _delayHours?: number;
+  private _positionX?: number;
+  private _positionY?: number;
+  private _sentCount?: number;
+  private _automation?: EmailAutomationInterface;
+  private _next?: EmailAutomationStepInterface;
+
+  get subject(): string {
+    return this._subject ?? "";
+  }
+
+  get body(): string {
+    return this._body ?? "";
+  }
+
+  get delayHours(): number {
+    return this._delayHours ?? 0;
+  }
+
+  get positionX(): number | undefined {
+    return this._positionX;
+  }
+
+  get positionY(): number | undefined {
+    return this._positionY;
+  }
+
+  get sentCount(): number {
+    return this._sentCount ?? 0;
+  }
+
+  get automation(): EmailAutomationInterface | undefined {
+    return this._automation;
+  }
+
+  get next(): EmailAutomationStepInterface | undefined {
+    return this._next;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    this._subject = data.jsonApi.attributes.subject;
+    this._body = data.jsonApi.attributes.body;
+    this._delayHours = data.jsonApi.attributes.delayHours;
+    this._positionX = data.jsonApi.attributes.positionX ?? undefined;
+    this._positionY = data.jsonApi.attributes.positionY ?? undefined;
+    this._sentCount = data.jsonApi.attributes.sentCount;
+
+    this._automation = this._readIncluded(data, "automation", Modules.EmailAutomation) as EmailAutomationInterface;
+    this._next = this._readIncluded(data, "next", Modules.EmailAutomationStep) as EmailAutomationStepInterface;
+
+    return this;
+  }
+
+  createJsonApi(data: EmailAutomationStepInput) {
+    const response: any = {
+      data: {
+        type: Modules.EmailAutomationStep.name,
+        id: data.id,
+        attributes: {},
+        meta: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.subject !== undefined) response.data.attributes.subject = data.subject;
+    if (data.body !== undefined) response.data.attributes.body = data.body;
+    if (data.delayHours !== undefined) response.data.attributes.delayHours = data.delayHours;
+    if (data.positionX !== undefined) response.data.attributes.positionX = data.positionX;
+    if (data.positionY !== undefined) response.data.attributes.positionY = data.positionY;
+
+    if (data.automationId) {
+      response.data.relationships.automation = {
+        data: {
+          type: Modules.EmailAutomation.name,
+          id: data.automationId,
+        },
+      };
+    }
+
+    return response;
+  }
+
+  /**
+   * Body of POST email-automation-steps/:stepId/next: the step the chain continues to.
+   */
+  createNextJsonApi(params: { nextStepId: string }) {
+    return {
+      data: {
+        type: Modules.EmailAutomationStep.name,
+        id: params.nextStepId,
+      },
+    };
+  }
+}

package/src/features/email-automation/data/EmailAutomationStepInterface.ts

@@ -0,0 +1,23 @@
+import { ApiDataInterface } from "../../../core";
+import { EmailAutomationInterface } from "./EmailAutomationInterface";
+
+export type EmailAutomationStepInput = {
+  id: string;
+  automationId: string;
+  subject: string;
+  body: string;
+  delayHours?: number;
+  positionX?: number;
+  positionY?: number;
+};
+
+export interface EmailAutomationStepInterface extends ApiDataInterface {
+  get subject(): string;
+  get body(): string;
+  get delayHours(): number;
+  get positionX(): number | undefined;
+  get positionY(): number | undefined;
+  get sentCount(): number;
+  get automation(): EmailAutomationInterface | undefined;
+  get next(): EmailAutomationStepInterface | undefined;
+}