@jarwizz/create-jarshop 0.1.3 → 0.1.5

package/dist/template/src/plugins/jarshop-checkout/order-email-outbox.ts

@@ -3,10 +3,75 @@ import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 const encryptionAlgorithm = "aes-256-gcm";
 const encryptionKeyBytes = 32;
 
-export type OrderEmailOutboxPayload = {
+export type LegacyOrderConfirmationOutboxPayload = {
   confirmationToken: string;
 };
 
+export type OrderEmailLineSnapshot = {
+  name: string;
+  quantity: number;
+  totalWithTax: number;
+};
+
+export type OrderConfirmationEmailSnapshot = {
+  recipient: string;
+  languageCode: string;
+  orderCode: string;
+  currencyCode: string;
+  totalWithTax: number;
+  shippingWithTax: number;
+  paymentMethod: string;
+  shippingMethod: string;
+  confirmationToken: string;
+  lines: readonly OrderEmailLineSnapshot[];
+};
+
+export type FulfillmentLifecycleEmailKind =
+  | "pickup-ready"
+  | "pickup-picked-up"
+  | "shipment-shipped"
+  | "shipment-delivered";
+
+export type FulfillmentLifecycleEmailSnapshot = {
+  recipient: string;
+  languageCode: string;
+  orderCode: string;
+  currencyCode: string;
+  totalWithTax: number;
+  shippingWithTax: number;
+  shippingMethodCode: string;
+  fulfillmentId: string;
+  trackingCode: string;
+  lines: readonly OrderEmailLineSnapshot[];
+};
+
+export type OrderCancellationEmailSnapshot = {
+  recipient: string;
+  languageCode: string;
+  orderCode: string;
+  currencyCode: string;
+  totalWithTax: number;
+  shippingWithTax: number;
+  historyEntryId: string;
+  shippingCancelled: boolean;
+  lines: readonly OrderEmailLineSnapshot[];
+};
+
+export type OrderEmailOutboxPayload =
+  | LegacyOrderConfirmationOutboxPayload
+  | {
+      kind: "order-confirmation";
+      snapshot: OrderConfirmationEmailSnapshot;
+    }
+  | {
+      kind: FulfillmentLifecycleEmailKind;
+      snapshot: FulfillmentLifecycleEmailSnapshot;
+    }
+  | {
+      kind: "order-cancelled";
+      snapshot: OrderCancellationEmailSnapshot;
+    };
+
 export function assertOrderEmailOutboxEncryptionConfiguration(): void {
   parseOrderEmailEncryptionKey(process.env.JARSHOP_ORDER_EMAIL_ENCRYPTION_KEY);
 }
@@ -14,19 +79,19 @@ export function assertOrderEmailOutboxEncryptionConfiguration(): void {
 export function createPendingOrderEmailDelivery(input: {
   orderId: number;
   checkoutAttemptId: string;
-  languageCode: string;
-  confirmationToken: string;
+  snapshot: OrderConfirmationEmailSnapshot;
   now?: Date;
   encodedKey?: string;
 }) {
   return {
     orderId: input.orderId,
+    eventKey: createOrderConfirmationEventKey(input.orderId),
     checkoutAttemptId: input.checkoutAttemptId,
     kind: "order-confirmation" as const,
-    languageCode: input.languageCode,
+    languageCode: input.snapshot.languageCode,
     status: "pending" as const,
     payloadCiphertext: encryptOrderEmailOutboxPayload(
-      { confirmationToken: input.confirmationToken },
+      { kind: "order-confirmation", snapshot: input.snapshot },
       input.encodedKey,
     ),
     attemptCount: 0,
@@ -38,11 +103,45 @@ export function createPendingOrderEmailDelivery(input: {
   };
 }
 
+export function createOrderConfirmationEventKey(orderId: number): string {
+  if (!Number.isSafeInteger(orderId) || orderId <= 0) {
+    throw new Error("order email event order id must be a positive integer");
+  }
+  return `order:${orderId}:order-confirmation`;
+}
+
+export function createPendingFulfillmentEmailDelivery(input: {
+  orderId: number;
+  kind: FulfillmentLifecycleEmailKind;
+  snapshot: FulfillmentLifecycleEmailSnapshot;
+  now?: Date;
+  encodedKey?: string;
+}) {
+  return createPendingLifecycleEmailDelivery({
+    ...input,
+    eventKey: `order:${input.orderId}:fulfillment:${requireEventSourceId(input.snapshot.fulfillmentId)}:${input.kind}`,
+  });
+}
+
+export function createPendingCancellationEmailDelivery(input: {
+  orderId: number;
+  snapshot: OrderCancellationEmailSnapshot;
+  now?: Date;
+  encodedKey?: string;
+}) {
+  return createPendingLifecycleEmailDelivery({
+    ...input,
+    kind: "order-cancelled" as const,
+    eventKey: `order-history:${requireEventSourceId(input.snapshot.historyEntryId)}:order-cancelled`,
+  });
+}
+
 export function encryptOrderEmailOutboxPayload(
   payload: OrderEmailOutboxPayload,
   encodedKey = process.env.JARSHOP_ORDER_EMAIL_ENCRYPTION_KEY,
 ): string {
   const key = parseOrderEmailEncryptionKey(encodedKey);
+  const version = "snapshot" in payload ? "v2" : "v1";
   const initializationVector = randomBytes(12);
   const cipher = createCipheriv(encryptionAlgorithm, key, initializationVector);
   const ciphertext = Buffer.concat([
@@ -51,7 +150,7 @@ export function encryptOrderEmailOutboxPayload(
   ]);
   const tag = cipher.getAuthTag();
   return [
-    "v1",
+    version,
     initializationVector.toString("base64url"),
     tag.toString("base64url"),
     ciphertext.toString("base64url"),
@@ -65,7 +164,7 @@ export function decryptOrderEmailOutboxPayload(
   const [version, initializationVector, tag, ciphertext, ...unexpected] =
     payloadCiphertext.split(".");
   if (
-    version !== "v1" ||
+    (version !== "v1" && version !== "v2") ||
     !initializationVector ||
     !tag ||
     !ciphertext ||
@@ -84,19 +183,213 @@ export function decryptOrderEmailOutboxPayload(
       decipher.update(Buffer.from(ciphertext, "base64url")),
       decipher.final(),
     ]).toString("utf8");
-    const payload = JSON.parse(decoded) as Partial<OrderEmailOutboxPayload>;
-    if (
-      typeof payload.confirmationToken !== "string" ||
-      !payload.confirmationToken
-    ) {
-      throw new Error("missing confirmation token");
-    }
-    return { confirmationToken: payload.confirmationToken };
+    return version === "v1"
+      ? parseLegacyOrderConfirmationPayload(JSON.parse(decoded))
+      : parseOrderConfirmationSnapshotPayload(JSON.parse(decoded));
   } catch {
     throw new Error("order email outbox payload cannot be decrypted");
   }
 }
 
+export function isSnapshotOrderEmailOutboxPayload(
+  payload: OrderEmailOutboxPayload,
+): payload is Extract<OrderEmailOutboxPayload, { kind: "order-confirmation" }> {
+  return "kind" in payload && payload.kind === "order-confirmation";
+}
+
+export function isLegacyOrderConfirmationOutboxPayload(
+  payload: OrderEmailOutboxPayload,
+): payload is LegacyOrderConfirmationOutboxPayload {
+  return "confirmationToken" in payload;
+}
+
+function parseLegacyOrderConfirmationPayload(
+  value: unknown,
+): LegacyOrderConfirmationOutboxPayload {
+  const payload = asRecord(value);
+  return { confirmationToken: requireString(payload, "confirmationToken") };
+}
+
+function parseOrderConfirmationSnapshotPayload(
+  value: unknown,
+): Exclude<OrderEmailOutboxPayload, LegacyOrderConfirmationOutboxPayload> {
+  const payload = asRecord(value);
+  const kind = requireString(payload, "kind");
+  const snapshot = asRecord(payload.snapshot);
+  if (kind === "order-confirmation") {
+    return {
+      kind,
+      snapshot: parseOrderConfirmationSnapshot(snapshot),
+    };
+  }
+  if (isFulfillmentLifecycleEmailKind(kind)) {
+    return {
+      kind,
+      snapshot: parseFulfillmentLifecycleSnapshot(snapshot),
+    };
+  }
+  if (kind === "order-cancelled") {
+    return {
+      kind,
+      snapshot: parseOrderCancellationSnapshot(snapshot),
+    };
+  }
+  throw new Error("unsupported order email kind");
+}
+
+function parseOrderConfirmationSnapshot(
+  snapshot: Record<string, unknown>,
+): OrderConfirmationEmailSnapshot {
+  const lines = snapshot.lines;
+  if (!Array.isArray(lines)) throw new Error("missing order email lines");
+  return {
+    recipient: requireString(snapshot, "recipient"),
+    languageCode: requireString(snapshot, "languageCode"),
+    orderCode: requireString(snapshot, "orderCode"),
+    currencyCode: requireString(snapshot, "currencyCode"),
+    totalWithTax: requireInteger(snapshot, "totalWithTax"),
+    shippingWithTax: requireInteger(snapshot, "shippingWithTax"),
+    paymentMethod: requireString(snapshot, "paymentMethod", true),
+    shippingMethod: requireString(snapshot, "shippingMethod", true),
+    confirmationToken: requireString(snapshot, "confirmationToken"),
+    lines: parseOrderEmailLines(lines),
+  };
+}
+
+function parseFulfillmentLifecycleSnapshot(
+  snapshot: Record<string, unknown>,
+): FulfillmentLifecycleEmailSnapshot {
+  return {
+    ...parseLifecycleOrderSnapshot(snapshot),
+    shippingMethodCode: requireString(snapshot, "shippingMethodCode"),
+    fulfillmentId: requireString(snapshot, "fulfillmentId"),
+    trackingCode: requireString(snapshot, "trackingCode", true),
+  };
+}
+
+function parseOrderCancellationSnapshot(
+  snapshot: Record<string, unknown>,
+): OrderCancellationEmailSnapshot {
+  const shippingCancelled = snapshot.shippingCancelled;
+  if (typeof shippingCancelled !== "boolean") {
+    throw new Error("invalid order email shippingCancelled");
+  }
+  return {
+    ...parseLifecycleOrderSnapshot(snapshot),
+    historyEntryId: requireString(snapshot, "historyEntryId"),
+    shippingCancelled,
+  };
+}
+
+function parseLifecycleOrderSnapshot(snapshot: Record<string, unknown>) {
+  const lines = snapshot.lines;
+  if (!Array.isArray(lines)) throw new Error("missing order email lines");
+  return {
+    recipient: requireString(snapshot, "recipient"),
+    languageCode: requireString(snapshot, "languageCode"),
+    orderCode: requireString(snapshot, "orderCode"),
+    currencyCode: requireString(snapshot, "currencyCode"),
+    totalWithTax: requireInteger(snapshot, "totalWithTax"),
+    shippingWithTax: requireInteger(snapshot, "shippingWithTax"),
+    lines: parseOrderEmailLines(lines),
+  };
+}
+
+function parseOrderEmailLines(lines: unknown[]): OrderEmailLineSnapshot[] {
+  return lines.map((line) => {
+    const item = asRecord(line);
+    return {
+      name: requireString(item, "name"),
+      quantity: requireInteger(item, "quantity"),
+      totalWithTax: requireInteger(item, "totalWithTax"),
+    };
+  });
+}
+
+function isFulfillmentLifecycleEmailKind(
+  kind: string,
+): kind is FulfillmentLifecycleEmailKind {
+  return [
+    "pickup-ready",
+    "pickup-picked-up",
+    "shipment-shipped",
+    "shipment-delivered",
+  ].includes(kind);
+}
+
+function createPendingLifecycleEmailDelivery<
+  Kind extends Exclude<
+    OrderEmailOutboxPayload,
+    LegacyOrderConfirmationOutboxPayload | { kind: "order-confirmation" }
+  >["kind"],
+>(input: {
+  orderId: number;
+  eventKey: string;
+  kind: Kind;
+  snapshot: Extract<OrderEmailOutboxPayload, { kind: Kind }>["snapshot"];
+  now?: Date;
+  encodedKey?: string;
+}) {
+  if (!Number.isSafeInteger(input.orderId) || input.orderId <= 0) {
+    throw new Error("order email event order id must be a positive integer");
+  }
+  return {
+    orderId: input.orderId,
+    eventKey: input.eventKey,
+    checkoutAttemptId: null,
+    kind: input.kind,
+    languageCode: input.snapshot.languageCode,
+    status: "pending" as const,
+    payloadCiphertext: encryptOrderEmailOutboxPayload(
+      { kind: input.kind, snapshot: input.snapshot } as Exclude<
+        OrderEmailOutboxPayload,
+        LegacyOrderConfirmationOutboxPayload
+      >,
+      input.encodedKey,
+    ),
+    attemptCount: 0,
+    nextAttemptAt: input.now ?? new Date(),
+    leaseToken: null,
+    leaseExpiresAt: null,
+    lastErrorCode: null,
+    sentAt: null,
+  };
+}
+
+function requireEventSourceId(sourceId: string): string {
+  if (!sourceId.trim() || sourceId.length > 128 || /[:\s]/u.test(sourceId)) {
+    throw new Error("order email event source id is invalid");
+  }
+  return sourceId;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("order email payload must be an object");
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireString(
+  value: Record<string, unknown>,
+  key: string,
+  allowEmpty = false,
+): string {
+  const field = value[key];
+  if (typeof field !== "string" || (!allowEmpty && field.length === 0)) {
+    throw new Error(`invalid order email ${key}`);
+  }
+  return field;
+}
+
+function requireInteger(value: Record<string, unknown>, key: string): number {
+  const field = value[key];
+  if (!Number.isSafeInteger(field)) {
+    throw new Error(`invalid order email ${key}`);
+  }
+  return field as number;
+}
+
 export function parseOrderEmailEncryptionKey(encodedKey: string | undefined) {
   const key = encodedKey ? Buffer.from(encodedKey, "base64") : Buffer.alloc(0);
   if (key.length !== encryptionKeyBytes) {

package/dist/template/src/plugins/jarshop-checkout/order-email-worker.ts

@@ -9,6 +9,9 @@ import {
   TransactionalConnection,
 } from "@vendure/core";
 import { randomUUID } from "node:crypto";
+import { In } from "typeorm";
+import { JarShopEmailBrandConfiguration } from "./order-email-configuration.entity.js";
+import { isLifecycleEmailEnabled } from "./order-email-configuration.js";
 import { JarShopOrderEmailDelivery } from "./order-email-delivery.entity.js";
 import {
   assertOrderEmailDeliveryConfiguration,
@@ -17,6 +20,7 @@ import {
   type OrderConfirmationEmail,
   registerUniqueScheduledTask,
   renderOrderConfirmationEmail,
+  renderOrderLifecycleEmail,
   scheduleOrderEmailRetry,
   toOrderEmailLanguageCode,
   type OrderEmailTransport,
@@ -26,6 +30,10 @@ import { createConfiguredOrderEmailTransport } from "./order-email-transport.js"
 import {
   assertOrderEmailOutboxEncryptionConfiguration,
   decryptOrderEmailOutboxPayload,
+  isLegacyOrderConfirmationOutboxPayload,
+  isSnapshotOrderEmailOutboxPayload,
+  type LegacyOrderConfirmationOutboxPayload,
+  type OrderConfirmationEmailSnapshot,
 } from "./order-email-outbox.js";
 
 type DeliveryResult =
@@ -73,10 +81,40 @@ export class JarShopOrderEmailWorker implements OnApplicationBootstrap {
       const payload = decryptOrderEmailOutboxPayload(
         delivery.delivery.payloadCiphertext,
       );
-      const email = await this.renderOrderConfirmation(
-        delivery.delivery,
-        payload.confirmationToken,
-      );
+      let email: OrderConfirmationEmail;
+      if (isSnapshotOrderEmailOutboxPayload(payload)) {
+        email = this.renderSnapshotOrderConfirmation(
+          payload.snapshot,
+          await this.getBrandConfiguration(delivery.delivery.orderId),
+        );
+      } else if (isLegacyOrderConfirmationOutboxPayload(payload)) {
+        email = await this.renderLegacyOrderConfirmation(
+          delivery.delivery,
+          payload,
+        );
+      } else {
+        const brandConfiguration = await this.getBrandConfiguration(
+          delivery.delivery.orderId,
+        );
+        if (
+          !brandConfiguration ||
+          !isLifecycleEmailEnabled(brandConfiguration, payload.kind)
+        ) {
+          throw new OrderEmailWorkerError("EMAIL_KIND_NOT_ENABLED");
+        }
+        email =
+          payload.kind === "order-cancelled"
+            ? renderOrderLifecycleEmail({
+                kind: payload.kind,
+                snapshot: payload.snapshot,
+                brandConfiguration,
+              })
+            : renderOrderLifecycleEmail({
+                kind: payload.kind,
+                snapshot: payload.snapshot,
+                brandConfiguration,
+              });
+      }
       await this.getEmailTransport().deliver({
         deliveryId: delivery.delivery.id,
         email,
@@ -146,9 +184,23 @@ export class JarShopOrderEmailWorker implements OnApplicationBootstrap {
     });
   }
 
-  private async renderOrderConfirmation(
+  private renderSnapshotOrderConfirmation(
+    snapshot: OrderConfirmationEmailSnapshot,
+    brandConfiguration: JarShopEmailBrandConfiguration | undefined,
+  ): OrderConfirmationEmail {
+    return renderOrderConfirmationEmail({
+      ...snapshot,
+      ...(brandConfiguration ? { brandConfiguration } : {}),
+      confirmationUrl: createOrderConfirmationUrl(
+        toOrderEmailLanguageCode(snapshot.languageCode),
+        snapshot.confirmationToken,
+      ),
+    });
+  }
+
+  private async renderLegacyOrderConfirmation(
     delivery: JarShopOrderEmailDelivery,
-    confirmationToken: string,
+    payload: LegacyOrderConfirmationOutboxPayload,
   ): Promise<OrderConfirmationEmail> {
     const sourceOrder = await this.connection.rawConnection
       .getRepository(Order)
@@ -177,6 +229,9 @@ export class JarShopOrderEmailWorker implements OnApplicationBootstrap {
       throw new OrderEmailWorkerError("ORDER_RECIPIENT_MISSING");
     }
 
+    const brandConfiguration = await this.getBrandConfiguration(
+      delivery.orderId,
+    );
     return renderOrderConfirmationEmail({
       recipient: order.customer.emailAddress,
       languageCode,
@@ -193,16 +248,39 @@ export class JarShopOrderEmailWorker implements OnApplicationBootstrap {
         .join(", "),
       confirmationUrl: createOrderConfirmationUrl(
         languageCode,
-        confirmationToken,
+        payload.confirmationToken,
       ),
       lines: order.lines.map((line) => ({
         name: line.productVariant.name,
         quantity: line.quantity,
         totalWithTax: Math.round(line.proratedLinePriceWithTax),
       })),
+      ...(brandConfiguration ? { brandConfiguration } : {}),
     });
   }
 
+  private async getBrandConfiguration(
+    orderId: number,
+  ): Promise<JarShopEmailBrandConfiguration | undefined> {
+    const sourceOrder = await this.connection.rawConnection
+      .getRepository(Order)
+      .findOne({ where: { id: orderId }, relations: ["channels"] });
+    if (!sourceOrder) throw new OrderEmailWorkerError("ORDER_NOT_FOUND");
+    const configurations = await this.connection.rawConnection
+      .getRepository(JarShopEmailBrandConfiguration)
+      .find({
+        where: {
+          channelId: In(
+            sourceOrder.channels.map((channel) => Number(channel.id)),
+          ),
+        },
+      });
+    if (configurations.length > 1) {
+      throw new OrderEmailWorkerError("EMAIL_BRAND_CHANNEL_AMBIGUOUS");
+    }
+    return configurations[0];
+  }
+
   private async markSent(
     deliveryId: number,
     leaseToken: string,
@@ -258,7 +336,7 @@ export class JarShopOrderEmailWorker implements OnApplicationBootstrap {
 
 export const jarShopOrderEmailWorkerTask = new ScheduledTask({
   id: "jarshop-order-email-outbox",
-  description: "Deliver one due JarShop order-confirmation email",
+  description: "Deliver one due JarShop order lifecycle email",
   schedule: (cron) => cron.every(1).minutes(),
   timeout: 30_000,
   execute: async ({ injector }) => {

package/dist/template/src/plugins/jarshop-checkout/order-lifecycle-core.ts

@@ -0,0 +1,131 @@
+import type { FulfillmentLifecycleEmailKind } from "./order-email-outbox.js";
+
+type FulfillmentCoverage = {
+  orderLineId: string | number;
+  quantity: number;
+  state: string;
+};
+
+export function validateFulfillmentTransition(input: {
+  toState: string;
+  shippingMethodCodes: readonly string[];
+  paymentStates: readonly string[];
+}): string | undefined {
+  const pickupOrder =
+    input.shippingMethodCodes.length > 0 &&
+    input.shippingMethodCodes.every((code) => code === "pickup");
+  const pickupState =
+    input.toState === "ReadyForPickup" || input.toState === "PickedUp";
+
+  if (pickupState && !pickupOrder) {
+    return "Pickup states are available only for pickup orders";
+  }
+  if (
+    pickupOrder &&
+    (input.toState === "Shipped" || input.toState === "Delivered")
+  ) {
+    return "Pickup orders must use ReadyForPickup and PickedUp";
+  }
+  if (
+    input.toState === "PickedUp" &&
+    (input.paymentStates.length === 0 ||
+      input.paymentStates.some((state) => state !== "Settled"))
+  ) {
+    return "Pickup cannot be completed before payment is settled";
+  }
+  return undefined;
+}
+
+export function getCourierOrderAlignmentState(
+  orderLines: ReadonlyArray<{ orderLineId: string | number; quantity: number }>,
+  fulfillmentLines: readonly FulfillmentCoverage[],
+):
+  | "PartiallyShipped"
+  | "Shipped"
+  | "PartiallyDelivered"
+  | "Delivered"
+  | undefined {
+  const delivered = coverageByOrderLine(
+    fulfillmentLines.filter((line) => line.state === "Delivered"),
+  );
+  const shipped = coverageByOrderLine(
+    fulfillmentLines.filter(
+      (line) => line.state === "Shipped" || line.state === "Delivered",
+    ),
+  );
+  const allDelivered = hasCompleteCoverage(orderLines, delivered);
+  const anyDelivered = hasAnyCoverage(delivered);
+  const allShipped = hasCompleteCoverage(orderLines, shipped);
+  const anyShipped = hasAnyCoverage(shipped);
+
+  if (allDelivered) return "Delivered";
+  if (anyDelivered) return "PartiallyDelivered";
+  if (allShipped) return "Shipped";
+  if (anyShipped) return "PartiallyShipped";
+  return undefined;
+}
+
+export function resolveShippingMethodCodeForOrderLines(
+  shippingLines: ReadonlyArray<{
+    code: string;
+    orderLineIds: readonly (string | number)[];
+  }>,
+  fulfillmentOrderLineIds: readonly (string | number)[],
+): string {
+  const fulfillmentLineIds = new Set(fulfillmentOrderLineIds.map(String));
+  const matchingCodes = [
+    ...new Set(
+      shippingLines
+        .filter((shippingLine) =>
+          shippingLine.orderLineIds.some((orderLineId) =>
+            fulfillmentLineIds.has(String(orderLineId)),
+          ),
+        )
+        .map((shippingLine) => shippingLine.code),
+    ),
+  ];
+  if (matchingCodes.length === 1) return matchingCodes[0];
+  if (matchingCodes.length === 0 && shippingLines.length === 1) {
+    return shippingLines[0].code;
+  }
+  throw new Error("fulfillment shipping method could not be resolved");
+}
+
+export function toFulfillmentLifecycleEmailKind(
+  shippingMethodCode: string,
+  state: string,
+): FulfillmentLifecycleEmailKind | undefined {
+  if (shippingMethodCode === "pickup") {
+    if (state === "ReadyForPickup") return "pickup-ready";
+    if (state === "PickedUp") return "pickup-picked-up";
+    return undefined;
+  }
+  if (state === "Shipped") return "shipment-shipped";
+  if (state === "Delivered") return "shipment-delivered";
+  return undefined;
+}
+
+function coverageByOrderLine(lines: readonly FulfillmentCoverage[]) {
+  const coverage = new Map<string, number>();
+  for (const line of lines) {
+    const orderLineId = String(line.orderLineId);
+    coverage.set(orderLineId, (coverage.get(orderLineId) ?? 0) + line.quantity);
+  }
+  return coverage;
+}
+
+function hasCompleteCoverage(
+  orderLines: ReadonlyArray<{ orderLineId: string | number; quantity: number }>,
+  coverage: ReadonlyMap<string, number>,
+): boolean {
+  return (
+    orderLines.length > 0 &&
+    orderLines.every(
+      (line) => (coverage.get(String(line.orderLineId)) ?? 0) >= line.quantity,
+    )
+  );
+}
+
+function hasAnyCoverage(coverage: ReadonlyMap<string, number>): boolean {
+  return [...coverage.values()].some((quantity) => quantity > 0);
+}