@jarwizz/create-jarshop 0.1.1 → 0.1.3

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

@@ -0,0 +1,281 @@
+import { Inject, Injectable, OnApplicationBootstrap } from "@nestjs/common";
+import {
+  LanguageCode,
+  Order,
+  OrderService,
+  ProcessContext,
+  RequestContextService,
+  ScheduledTask,
+  TransactionalConnection,
+} from "@vendure/core";
+import { randomUUID } from "node:crypto";
+import { JarShopOrderEmailDelivery } from "./order-email-delivery.entity.js";
+import {
+  assertOrderEmailDeliveryConfiguration,
+  createOrderConfirmationUrl,
+  orderEmailDeliveryPolicy,
+  type OrderConfirmationEmail,
+  registerUniqueScheduledTask,
+  renderOrderConfirmationEmail,
+  scheduleOrderEmailRetry,
+  toOrderEmailLanguageCode,
+  type OrderEmailTransport,
+} from "./order-email-delivery-core.js";
+import { resolveLocalizedShippingMethodName } from "./shipping.js";
+import { createConfiguredOrderEmailTransport } from "./order-email-transport.js";
+import {
+  assertOrderEmailOutboxEncryptionConfiguration,
+  decryptOrderEmailOutboxPayload,
+} from "./order-email-outbox.js";
+
+type DeliveryResult =
+  | { outcome: "idle" }
+  | { outcome: "sent"; deliveryId: number }
+  | { outcome: "failed"; deliveryId: number; errorCode: string };
+
+type ClaimedDelivery = {
+  delivery: JarShopOrderEmailDelivery;
+  leaseToken: string;
+};
+
+class OrderEmailWorkerError extends Error {
+  constructor(readonly code: string) {
+    super(code);
+  }
+}
+
+@Injectable()
+export class JarShopOrderEmailWorker implements OnApplicationBootstrap {
+  private emailTransport: OrderEmailTransport | undefined;
+
+  constructor(
+    @Inject(TransactionalConnection)
+    private readonly connection: TransactionalConnection,
+    @Inject(OrderService)
+    private readonly orderService: OrderService,
+    @Inject(RequestContextService)
+    private readonly requestContextService: RequestContextService,
+    @Inject(ProcessContext)
+    private readonly processContext: ProcessContext,
+  ) {}
+
+  onApplicationBootstrap(): void {
+    if (!this.processContext.isServer && !this.processContext.isWorker) return;
+    assertOrderEmailOutboxEncryptionConfiguration();
+    assertOrderEmailDeliveryConfiguration();
+  }
+
+  async processNextDueDelivery(now = new Date()): Promise<DeliveryResult> {
+    const delivery = await this.claimNextDueDelivery(now);
+    if (!delivery) return { outcome: "idle" };
+
+    try {
+      const payload = decryptOrderEmailOutboxPayload(
+        delivery.delivery.payloadCiphertext,
+      );
+      const email = await this.renderOrderConfirmation(
+        delivery.delivery,
+        payload.confirmationToken,
+      );
+      await this.getEmailTransport().deliver({
+        deliveryId: delivery.delivery.id,
+        email,
+      });
+      await this.markSent(delivery.delivery.id, delivery.leaseToken, now);
+      return { outcome: "sent", deliveryId: delivery.delivery.id };
+    } catch (error) {
+      const errorCode = toOrderEmailWorkerErrorCode(error);
+      const outcome = await this.markFailure(
+        delivery.delivery.id,
+        delivery.leaseToken,
+        delivery.delivery.attemptCount,
+        errorCode,
+        now,
+      );
+      return outcome.status === "failed"
+        ? { outcome: "failed", deliveryId: delivery.delivery.id, errorCode }
+        : { outcome: "idle" };
+    }
+  }
+
+  private getEmailTransport(): OrderEmailTransport {
+    this.emailTransport ??= createConfiguredOrderEmailTransport();
+    return this.emailTransport;
+  }
+
+  private async claimNextDueDelivery(
+    now: Date,
+  ): Promise<ClaimedDelivery | null> {
+    return this.connection.rawConnection.transaction(async (manager) => {
+      const repository = manager.getRepository(JarShopOrderEmailDelivery);
+      const delivery = await repository
+        .createQueryBuilder("delivery")
+        .setLock("pessimistic_write")
+        .setOnLocked("skip_locked")
+        .where(
+          "(delivery.status = :pendingStatus AND delivery.nextAttemptAt <= :now) OR (delivery.status = :processingStatus AND (delivery.leaseExpiresAt IS NULL OR delivery.leaseExpiresAt <= :now))",
+          { pendingStatus: "pending", processingStatus: "processing", now },
+        )
+        .orderBy("delivery.nextAttemptAt", "ASC")
+        .addOrderBy("delivery.id", "ASC")
+        .getOne();
+      if (!delivery) return null;
+
+      const staleLease = delivery.status === "processing";
+      if (
+        staleLease &&
+        delivery.attemptCount >= orderEmailDeliveryPolicy.maximumAttempts
+      ) {
+        delivery.status = "failed";
+        delivery.leaseToken = null;
+        delivery.leaseExpiresAt = null;
+        delivery.lastErrorCode = "DELIVERY_LEASE_EXPIRED";
+        await repository.save(delivery);
+        return null;
+      }
+
+      delivery.status = "processing";
+      delivery.attemptCount += 1;
+      delivery.leaseToken = randomUUID();
+      delivery.leaseExpiresAt = new Date(
+        now.getTime() + orderEmailDeliveryPolicy.leaseDurationMs,
+      );
+      delivery.lastErrorCode = staleLease ? "DELIVERY_LEASE_EXPIRED" : null;
+      const claimed = await repository.save(delivery);
+      return { delivery: claimed, leaseToken: claimed.leaseToken! };
+    });
+  }
+
+  private async renderOrderConfirmation(
+    delivery: JarShopOrderEmailDelivery,
+    confirmationToken: string,
+  ): Promise<OrderConfirmationEmail> {
+    const sourceOrder = await this.connection.rawConnection
+      .getRepository(Order)
+      .findOne({ where: { id: delivery.orderId }, relations: ["channels"] });
+    const channel = sourceOrder?.channels[0];
+    if (!sourceOrder) throw new OrderEmailWorkerError("ORDER_NOT_FOUND");
+    if (!channel) throw new OrderEmailWorkerError("ORDER_CHANNEL_MISSING");
+
+    const languageCode = toOrderEmailLanguageCode(delivery.languageCode);
+    const ctx = await this.requestContextService.create({
+      apiType: "admin",
+      // The raw order relation contains the channel identity, not its default
+      // tax and shipping zones. Resolve it through Vendure's ChannelService so
+      // OrderService can hydrate the order without recalculating against an
+      // incomplete Channel entity.
+      channelOrToken: channel.token,
+      languageCode: languageCode === "sk" ? LanguageCode.sk : LanguageCode.en,
+    });
+    const order = await this.orderService.findOne(ctx, delivery.orderId, [
+      "customer",
+      "lines.productVariant",
+      "shippingLines.shippingMethod.translations",
+      "payments",
+    ]);
+    if (!order?.customer?.emailAddress) {
+      throw new OrderEmailWorkerError("ORDER_RECIPIENT_MISSING");
+    }
+
+    return renderOrderConfirmationEmail({
+      recipient: order.customer.emailAddress,
+      languageCode,
+      orderCode: order.code,
+      currencyCode: order.currencyCode,
+      totalWithTax: order.totalWithTax,
+      shippingWithTax: order.shippingWithTax,
+      paymentMethod: order.payments.map((payment) => payment.method).join(", "),
+      shippingMethod: order.shippingLines
+        .map((line) =>
+          resolveLocalizedShippingMethodName(line.shippingMethod, languageCode),
+        )
+        .filter(Boolean)
+        .join(", "),
+      confirmationUrl: createOrderConfirmationUrl(
+        languageCode,
+        confirmationToken,
+      ),
+      lines: order.lines.map((line) => ({
+        name: line.productVariant.name,
+        quantity: line.quantity,
+        totalWithTax: Math.round(line.proratedLinePriceWithTax),
+      })),
+    });
+  }
+
+  private async markSent(
+    deliveryId: number,
+    leaseToken: string,
+    now: Date,
+  ): Promise<void> {
+    const result = await this.connection.rawConnection
+      .getRepository(JarShopOrderEmailDelivery)
+      .update(
+        { id: deliveryId, status: "processing", leaseToken },
+        {
+          status: "sent",
+          sentAt: now,
+          leaseToken: null,
+          leaseExpiresAt: null,
+          lastErrorCode: null,
+        },
+      );
+    if (result.affected !== 1) {
+      throw new Error("order email delivery was not owned by this worker");
+    }
+  }
+
+  private async markFailure(
+    deliveryId: number,
+    leaseToken: string,
+    attemptCount: number,
+    errorCode: string,
+    now: Date,
+  ): Promise<ReturnType<typeof scheduleOrderEmailRetry>> {
+    const retry = scheduleOrderEmailRetry({ attemptCount, now });
+    const result = await this.connection.rawConnection
+      .getRepository(JarShopOrderEmailDelivery)
+      .update(
+        { id: deliveryId, status: "processing", leaseToken },
+        {
+          status: retry.status,
+          ...(retry.status === "pending"
+            ? { nextAttemptAt: retry.nextAttemptAt }
+            : {}),
+          leaseToken: null,
+          leaseExpiresAt: null,
+          lastErrorCode: errorCode,
+        },
+      );
+    if (result.affected !== 1) {
+      throw new Error(
+        "order email delivery was no longer owned by this worker",
+      );
+    }
+    return retry;
+  }
+}
+
+export const jarShopOrderEmailWorkerTask = new ScheduledTask({
+  id: "jarshop-order-email-outbox",
+  description: "Deliver one due JarShop order-confirmation email",
+  schedule: (cron) => cron.every(1).minutes(),
+  timeout: 30_000,
+  execute: async ({ injector }) => {
+    return injector.get(JarShopOrderEmailWorker).processNextDueDelivery();
+  },
+});
+
+export function registerJarShopOrderEmailWorkerTask<
+  Config extends { schedulerOptions: { tasks: ScheduledTask[] } },
+>(config: Config): Config {
+  return registerUniqueScheduledTask(config, jarShopOrderEmailWorkerTask);
+}
+
+function toOrderEmailWorkerErrorCode(error: unknown): string {
+  if (error instanceof OrderEmailWorkerError) return error.code;
+  if (error instanceof Error && error.message.includes("cannot be decrypted")) {
+    return "OUTBOX_PAYLOAD_UNREADABLE";
+  }
+  return "DELIVERY_FAILED";
+}

package/dist/template/src/plugins/jarshop-checkout/shipping.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compareCheckoutSnapshot,
+  resolveLocalizedShippingMethodName,
+} from "./shipping.js";
+
+describe("compareCheckoutSnapshot", () => {
+  it("accepts equivalent GraphQL ID string and number representations", () => {
+    expect(
+      compareCheckoutSnapshot(
+        {
+          currencyCode: "EUR",
+          subtotalWithTax: 1990,
+          lines: [{ lineId: 1, quantity: 1, linePriceWithTax: 1990 }],
+        },
+        {
+          currencyCode: "EUR",
+          subtotalWithTax: 1990,
+          lines: [{ lineId: "1", quantity: 1, linePriceWithTax: 1990 }],
+        },
+      ),
+    ).toEqual({ ok: true });
+  });
+});
+
+describe("resolveLocalizedShippingMethodName", () => {
+  it("uses the order language when a loaded shipping relation has no translated name", () => {
+    expect(
+      resolveLocalizedShippingMethodName(
+        {
+          translations: [
+            { languageCode: "en", name: "Personal pickup" },
+            { languageCode: "sk", name: "Osobný odber" },
+          ],
+        },
+        "sk",
+      ),
+    ).toBe("Osobný odber");
+  });
+});

package/dist/template/src/plugins/jarshop-checkout/shipping.ts

@@ -0,0 +1,162 @@
+export type ShippingMethodCode = "pickup" | "courier";
+
+type LocalizedShippingMethod = {
+  name?: string | null;
+  translations?: ReadonlyArray<{
+    languageCode: string;
+    name?: string | null;
+  }>;
+};
+
+/**
+ * Vendure translates `name` for a request context, but relation loading can
+ * leave it empty. Keep delivery communications localized by falling back to
+ * the explicitly loaded translation for the order's language.
+ */
+export function resolveLocalizedShippingMethodName(
+  shippingMethod: LocalizedShippingMethod | undefined,
+  languageCode: string,
+): string {
+  const translatedName = shippingMethod?.translations
+    ?.find((translation) => translation.languageCode === languageCode)
+    ?.name?.trim();
+  return translatedName || shippingMethod?.name?.trim() || "";
+}
+
+export interface CheckoutCartSnapshotLine {
+  // GraphQL ID input values can arrive as a JSON string or number, depending
+  // on the active Vendure ID strategy. Comparison is canonicalized below.
+  lineId: string | number;
+  quantity: number;
+  linePriceWithTax: number;
+}
+
+export interface CheckoutCartSnapshot {
+  currencyCode: string;
+  subtotalWithTax: number;
+  lines: CheckoutCartSnapshotLine[];
+}
+
+export type CheckoutSnapshotComparison =
+  | { readonly ok: true }
+  | {
+      readonly ok: false;
+      readonly errorCode: "PRICE_CHANGED" | "INSUFFICIENT_STOCK";
+      readonly affectedLineIds: readonly string[];
+    };
+
+export function compareCheckoutSnapshot(
+  expected: CheckoutCartSnapshot,
+  actual: CheckoutCartSnapshot,
+): CheckoutSnapshotComparison {
+  if (expected.currencyCode !== actual.currencyCode) {
+    return {
+      ok: false,
+      errorCode: "PRICE_CHANGED",
+      affectedLineIds: expected.lines.map((line) => String(line.lineId)),
+    };
+  }
+  const actualById = new Map(
+    actual.lines.map((line) => [String(line.lineId), line]),
+  );
+  if (
+    actual.lines.length !== expected.lines.length ||
+    actual.lines.some(
+      (line) =>
+        !expected.lines.some(
+          (item) => String(item.lineId) === String(line.lineId),
+        ),
+    )
+  ) {
+    return {
+      ok: false,
+      errorCode: "PRICE_CHANGED",
+      affectedLineIds: expected.lines.map((line) => String(line.lineId)),
+    };
+  }
+  const stockIssues = expected.lines.filter((line) => {
+    const actualLine = actualById.get(String(line.lineId));
+    return !actualLine || actualLine.quantity < line.quantity;
+  });
+  if (stockIssues.length) {
+    return {
+      ok: false,
+      errorCode: "INSUFFICIENT_STOCK",
+      affectedLineIds: stockIssues.map((line) => String(line.lineId)),
+    };
+  }
+  const priceChanged =
+    expected.subtotalWithTax !== actual.subtotalWithTax ||
+    expected.lines.some((line) => {
+      const actualLine = actualById.get(String(line.lineId));
+      return (
+        !actualLine || actualLine.linePriceWithTax !== line.linePriceWithTax
+      );
+    });
+  return priceChanged
+    ? {
+        ok: false,
+        errorCode: "PRICE_CHANGED",
+        affectedLineIds: expected.lines.map((line) => String(line.lineId)),
+      }
+    : { ok: true };
+}
+
+export interface ShippingAddressInput {
+  streetLine1: string;
+  streetLine2?: string;
+  city: string;
+  postalCode: string;
+  countryCode: string;
+  company?: string;
+}
+
+export type ShippingValidationResult =
+  | { readonly ok: true }
+  | {
+      readonly ok: false;
+      readonly errorCode: "VALIDATION_ERROR" | "SHIPPING_METHOD_INELIGIBLE";
+      readonly message: string;
+    };
+
+export function validateShippingSelection(input: {
+  shippingMethodCode: string;
+  shippingAddress?: ShippingAddressInput;
+}): ShippingValidationResult {
+  if (
+    input.shippingMethodCode !== "pickup" &&
+    input.shippingMethodCode !== "courier"
+  ) {
+    return {
+      ok: false,
+      errorCode: "SHIPPING_METHOD_INELIGIBLE",
+      message: "Selected shipping method is not available",
+    };
+  }
+
+  if (input.shippingMethodCode === "pickup") return { ok: true };
+
+  const address = input.shippingAddress;
+  if (!address) {
+    return {
+      ok: false,
+      errorCode: "VALIDATION_ERROR",
+      message: "A shipping address is required for courier delivery",
+    };
+  }
+
+  if (
+    !address.streetLine1.trim() ||
+    !address.city.trim() ||
+    !address.postalCode.trim() ||
+    address.countryCode !== "SK"
+  ) {
+    return {
+      ok: false,
+      errorCode: "VALIDATION_ERROR",
+      message: "Courier delivery requires a valid Slovak shipping address",
+    };
+  }
+
+  return { ok: true };
+}

package/dist/template/src/seed.ts

@@ -9,10 +9,17 @@ import {
   TaxRateService,
   ZoneService,
   ChannelService,
+  CountryService,
+  PaymentMethodService,
+  PaymentMethod,
+  ShippingMethod,
+  ShippingMethodService,
+  TransactionalConnection,
   bootstrap,
 } from "@vendure/core";
 import { GlobalFlag } from "@vendure/common/lib/generated-types";
 import { config } from "./vendure-config";
+import { JarShopLegalConfiguration } from "./plugins/jarshop-checkout/legal.entity.js";
 
 const productSlug = "jarshop-demo-product";
 
@@ -31,9 +38,13 @@ async function seed(): Promise<void> {
     const variantService = app.get(ProductVariantService);
     const stockLocationService = app.get(StockLocationService);
     const zoneService = app.get(ZoneService);
+    const countryService = app.get(CountryService);
     const taxCategoryService = app.get(TaxCategoryService);
     const taxRateService = app.get(TaxRateService);
     const channelService = app.get(ChannelService);
+    const paymentMethodService = app.get(PaymentMethodService);
+    const shippingMethodService = app.get(ShippingMethodService);
+    const connection = app.get(TransactionalConnection);
     const existing = await productService.findOneBySlug(ctx, productSlug);
 
     const stockLocation = await stockLocationService.defaultStockLocation(ctx);
@@ -42,6 +53,23 @@ async function seed(): Promise<void> {
     const taxZone =
       zones.items[0] ??
       (await zoneService.create(ctx, { name: "JarShop default tax zone" }));
+    const countries = await countryService.findAll(ctx);
+    const slovakia =
+      countries.items.find((country) => country.code === "SK") ??
+      (await countryService.create(ctx, {
+        code: "SK",
+        enabled: true,
+        translations: [
+          { languageCode: LanguageCode.sk, name: "Slovensko" },
+          { languageCode: LanguageCode.en, name: "Slovakia" },
+        ],
+      }));
+    if (!taxZone.members.some((country) => country.id === slovakia.id)) {
+      await zoneService.addMembersToZone(ctx, {
+        zoneId: taxZone.id,
+        memberIds: [slovakia.id],
+      });
+    }
     if (
       !channel.defaultTaxZone ||
       channel.defaultCurrencyCode !== CurrencyCode.EUR
@@ -58,6 +86,149 @@ async function seed(): Promise<void> {
         channelOrToken: channel.token,
       });
     }
+
+    const shippingMethods =
+      await shippingMethodService.getActiveShippingMethods(ctx);
+    const pickup =
+      shippingMethods.find((method) => method.code === "pickup") ??
+      (await shippingMethodService.create(ctx, {
+        code: "pickup",
+        fulfillmentHandler: "manual-fulfillment",
+        checker: {
+          code: "default-shipping-eligibility-checker",
+          arguments: [{ name: "orderMinimum", value: "0" }],
+        },
+        calculator: {
+          code: "default-shipping-calculator",
+          arguments: [
+            { name: "rate", value: "0" },
+            { name: "taxRate", value: "0" },
+            { name: "includesTax", value: "auto" },
+          ],
+        },
+        translations: [
+          {
+            languageCode: LanguageCode.sk,
+            name: "Osobný odber",
+            description: "",
+          },
+          {
+            languageCode: LanguageCode.en,
+            name: "Personal pickup",
+            description: "",
+          },
+        ],
+      }));
+    await channelService.assignToChannels(ctx, ShippingMethod, pickup.id, [
+      channel.id,
+    ]);
+    const courier =
+      shippingMethods.find((method) => method.code === "courier") ??
+      (await shippingMethodService.create(ctx, {
+        code: "courier",
+        fulfillmentHandler: "manual-fulfillment",
+        checker: {
+          code: "default-shipping-eligibility-checker",
+          arguments: [{ name: "orderMinimum", value: "0" }],
+        },
+        calculator: {
+          code: "default-shipping-calculator",
+          arguments: [
+            { name: "rate", value: "490" },
+            { name: "taxRate", value: "0" },
+            { name: "includesTax", value: "auto" },
+          ],
+        },
+        translations: [
+          {
+            languageCode: LanguageCode.sk,
+            name: "Kuriér",
+            description: "Doručenie kuriérom",
+          },
+          {
+            languageCode: LanguageCode.en,
+            name: "Courier",
+            description: "Courier delivery",
+          },
+        ],
+      }));
+    await channelService.assignToChannels(ctx, ShippingMethod, courier.id, [
+      channel.id,
+    ]);
+
+    const paymentMethods = await paymentMethodService.findAll(ctx);
+    const legacyDummy = paymentMethods.items.find(
+      (method) => method.code === "dummy-payment-method",
+    );
+    if (legacyDummy?.enabled) {
+      await paymentMethodService.update(ctx, {
+        id: legacyDummy.id,
+        enabled: false,
+      });
+    }
+    const existingCod = paymentMethods.items.find(
+      (method) => method.code === "cod",
+    );
+    const cod = existingCod
+      ? await paymentMethodService.update(ctx, {
+          id: existingCod.id,
+          enabled: true,
+          handler: {
+            code: "jarshop-cod-handler",
+            arguments: [],
+          },
+        })
+      : await paymentMethodService.create(ctx, {
+          code: "cod",
+          enabled: true,
+          handler: {
+            code: "jarshop-cod-handler",
+            arguments: [],
+          },
+          translations: [
+            {
+              languageCode: LanguageCode.sk,
+              name: "Dobierka",
+              description: "",
+            },
+            {
+              languageCode: LanguageCode.en,
+              name: "Cash on delivery",
+              description: "",
+            },
+          ],
+        });
+    await channelService.assignToChannels(ctx, PaymentMethod, cod.id, [
+      channel.id,
+    ]);
+
+    const legalRepository = connection.getRepository(
+      ctx,
+      JarShopLegalConfiguration,
+    );
+    for (const languageCode of [LanguageCode.sk, LanguageCode.en]) {
+      const existingLegal = await legalRepository.findOne({
+        where: { channelId: Number(channel.id), languageCode },
+      });
+      if (!existingLegal) {
+        await legalRepository.save(
+          legalRepository.create({
+            channelId: Number(channel.id),
+            languageCode,
+            termsVersion: "2026-08-01",
+            termsUrl:
+              languageCode === LanguageCode.sk
+                ? "https://example.com/sk/obchodne-podmienky"
+                : "https://example.com/en/terms",
+            privacyVersion: "2026-08-01",
+            privacyUrl:
+              languageCode === LanguageCode.sk
+                ? "https://example.com/sk/ochrana-sukromia"
+                : "https://example.com/en/privacy",
+          }),
+        );
+      }
+    }
     const taxCategories = await taxCategoryService.findAll(ctx);
     const taxCategory =
       taxCategories.items.find((item) => item.isDefault) ??