@jarwizz/create-jarshop 0.1.1 → 0.1.2

package/dist/template/src/plugins/jarshop-checkout/legal.entity.ts

@@ -0,0 +1,39 @@
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  PrimaryGeneratedColumn,
+  Unique,
+  UpdateDateColumn,
+} from "typeorm";
+
+@Entity({ name: "jarshop_legal_configuration" })
+@Unique("UQ_jarshop_legal_channel_language", ["channelId", "languageCode"])
+export class JarShopLegalConfiguration {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Column({ type: "int" })
+  channelId!: number;
+
+  @Column({ type: "varchar", length: 10 })
+  languageCode!: string;
+
+  @Column({ type: "varchar", length: 64 })
+  termsVersion!: string;
+
+  @Column({ type: "varchar", length: 2048 })
+  termsUrl!: string;
+
+  @Column({ type: "varchar", length: 64 })
+  privacyVersion!: string;
+
+  @Column({ type: "varchar", length: 2048 })
+  privacyUrl!: string;
+
+  @CreateDateColumn()
+  createdAt!: Date;
+
+  @UpdateDateColumn()
+  updatedAt!: Date;
+}

package/dist/template/src/plugins/jarshop-checkout/order-consent.entity.ts

@@ -0,0 +1,32 @@
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  PrimaryGeneratedColumn,
+  Unique,
+} from "typeorm";
+
+@Entity({ name: "jarshop_order_consent" })
+export class JarShopOrderConsent {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Unique("UQ_jarshop_order_consent_order", ["orderId"])
+  @Column({ type: "int" })
+  orderId!: number;
+
+  @Column({ type: "varchar", length: 64 })
+  termsVersion!: string;
+
+  @Column({ type: "varchar", length: 2048 })
+  termsUrl!: string;
+
+  @Column({ type: "varchar", length: 2048 })
+  privacyUrl!: string;
+
+  @Column({ type: "timestamptz" })
+  acceptedAt!: Date;
+
+  @CreateDateColumn()
+  createdAt!: Date;
+}

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

@@ -0,0 +1,337 @@
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const fileTransport = "file";
+const defaultStorefrontUrl = "http://localhost:3001";
+const defaultOutputPath = "./static/email/jarshop-outbox";
+
+export type OrderEmailLanguageCode = "sk" | "en";
+
+export type OrderConfirmationEmail = {
+  recipient: string;
+  subject: string;
+  text: string;
+};
+
+export type OrderEmailTransport = {
+  readonly kind: "file" | "smtp";
+  deliver(input: {
+    deliveryId: number;
+    email: OrderConfirmationEmail;
+  }): Promise<void>;
+};
+
+export type SmtpOrderEmailTransportConfiguration = {
+  kind: "smtp";
+  host: string;
+  port: number;
+  secure: boolean;
+  from: string;
+  username: string;
+  password: string;
+};
+
+export type OrderEmailTransportConfiguration =
+  | {
+      kind: "file";
+      outputPath?: string;
+    }
+  | SmtpOrderEmailTransportConfiguration;
+
+type Environment = Readonly<Record<string, string | undefined>>;
+
+export type OrderConfirmationEmailInput = {
+  recipient: string;
+  languageCode: string;
+  orderCode: string;
+  currencyCode: string;
+  totalWithTax: number;
+  shippingWithTax: number;
+  paymentMethod: string;
+  shippingMethod: string;
+  confirmationUrl: string;
+  lines: ReadonlyArray<{
+    name: string;
+    quantity: number;
+    totalWithTax: number;
+  }>;
+};
+
+export const orderEmailDeliveryPolicy = {
+  maximumAttempts: 5,
+  leaseDurationMs: 2 * 60 * 1_000,
+  retryDelaysMs: [60_000, 5 * 60_000, 30 * 60_000, 2 * 60 * 60_000],
+} as const;
+
+export function scheduleOrderEmailRetry(input: {
+  attemptCount: number;
+  now: Date;
+}): { status: "pending"; nextAttemptAt: Date } | { status: "failed" } {
+  if (!Number.isInteger(input.attemptCount) || input.attemptCount < 1) {
+    throw new Error("order email attempt count must be a positive integer");
+  }
+  if (input.attemptCount >= orderEmailDeliveryPolicy.maximumAttempts) {
+    return { status: "failed" };
+  }
+  const delay = orderEmailDeliveryPolicy.retryDelaysMs[input.attemptCount - 1];
+  if (delay === undefined) {
+    throw new Error("order email retry delay is not configured");
+  }
+  return {
+    status: "pending",
+    nextAttemptAt: new Date(input.now.getTime() + delay),
+  };
+}
+
+export function registerUniqueScheduledTask<
+  Config extends { schedulerOptions: { tasks: Task[] } },
+  Task extends { id: string },
+>(config: Config, task: Task): Config {
+  if (
+    !config.schedulerOptions.tasks.some((candidate) => candidate.id === task.id)
+  ) {
+    config.schedulerOptions.tasks.push(task);
+  }
+  return config;
+}
+
+export function assertOrderEmailDeliveryConfiguration(): void {
+  readOrderEmailTransportConfiguration(process.env);
+  const storefrontUrl =
+    process.env.JARSHOP_STOREFRONT_URL ?? defaultStorefrontUrl;
+  const parsed = new URL(storefrontUrl);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("JARSHOP_STOREFRONT_URL must use HTTP or HTTPS");
+  }
+}
+
+export function readOrderEmailTransportConfiguration(
+  environment: Environment,
+): OrderEmailTransportConfiguration {
+  const appEnvironment = environment.APP_ENV;
+  const transport =
+    environment.JARSHOP_EMAIL_TRANSPORT ??
+    (appEnvironment === "dev" || appEnvironment === "test"
+      ? fileTransport
+      : undefined);
+
+  if (transport === undefined) {
+    throw new Error(
+      "JARSHOP_EMAIL_TRANSPORT must be explicitly set outside APP_ENV=dev or APP_ENV=test",
+    );
+  }
+  if (transport === fileTransport) {
+    if (appEnvironment !== "dev" && appEnvironment !== "test") {
+      throw new Error(
+        "file email transport is allowed only for APP_ENV=dev or APP_ENV=test",
+      );
+    }
+    return {
+      kind: fileTransport,
+      ...(environment.JARSHOP_EMAIL_FILE_TRANSPORT_PATH === undefined
+        ? {}
+        : { outputPath: environment.JARSHOP_EMAIL_FILE_TRANSPORT_PATH }),
+    };
+  }
+  if (transport !== "smtp") {
+    throw new Error("JARSHOP_EMAIL_TRANSPORT must be file or smtp");
+  }
+
+  return {
+    kind: "smtp",
+    host: requireEnvironmentValue(environment, "JARSHOP_EMAIL_SMTP_HOST"),
+    port: parseSmtpPort(
+      requireEnvironmentValue(environment, "JARSHOP_EMAIL_SMTP_PORT"),
+    ),
+    secure: parseSmtpSecure(
+      requireEnvironmentValue(environment, "JARSHOP_EMAIL_SMTP_SECURE"),
+    ),
+    from: requireEnvironmentValue(environment, "JARSHOP_EMAIL_SMTP_FROM"),
+    username: requireEnvironmentValue(
+      environment,
+      "JARSHOP_EMAIL_SMTP_USERNAME",
+    ),
+    password: requireEnvironmentValue(
+      environment,
+      "JARSHOP_EMAIL_SMTP_PASSWORD",
+    ),
+  };
+}
+
+export function createFileOrderEmailTransport(
+  input: {
+    outputPath?: string;
+  } = {},
+): OrderEmailTransport {
+  return {
+    kind: "file",
+    deliver: async ({ deliveryId, email }) => {
+      await writeSanitizedFileTransport({
+        deliveryId,
+        email,
+        outputPath: input.outputPath,
+      });
+    },
+  };
+}
+
+export function createSmtpOrderEmailTransport(
+  configuration: SmtpOrderEmailTransportConfiguration,
+  sendMail: (message: {
+    from: string;
+    to: string;
+    subject: string;
+    text: string;
+  }) => Promise<unknown>,
+): OrderEmailTransport {
+  return {
+    kind: "smtp",
+    deliver: async ({ email }) => {
+      await sendMail({
+        from: configuration.from,
+        to: email.recipient,
+        subject: email.subject,
+        text: email.text,
+      });
+    },
+  };
+}
+
+export function renderOrderConfirmationEmail(
+  input: OrderConfirmationEmailInput,
+): OrderConfirmationEmail {
+  const languageCode = toOrderEmailLanguageCode(input.languageCode);
+  const copy = emailCopy[languageCode];
+  const formatMoney = new Intl.NumberFormat(
+    languageCode === "sk" ? "sk-SK" : "en-GB",
+    { style: "currency", currency: input.currencyCode },
+  );
+  const money = (minorUnits: number) => formatMoney.format(minorUnits / 100);
+  const lines = input.lines.map(
+    (line) => `- ${line.quantity}× ${line.name}: ${money(line.totalWithTax)}`,
+  );
+
+  return {
+    recipient: input.recipient,
+    subject: `${copy.subject} #${input.orderCode}`,
+    text: [
+      `${copy.greeting} #${input.orderCode}.`,
+      "",
+      copy.items,
+      ...lines,
+      "",
+      `${copy.shipping}: ${input.shippingMethod || copy.notAvailable} (${money(input.shippingWithTax)})`,
+      `${copy.payment}: ${input.paymentMethod || copy.notAvailable}`,
+      `${copy.total}: ${money(input.totalWithTax)}`,
+      "",
+      `${copy.confirmation}: ${input.confirmationUrl}`,
+    ].join("\n"),
+  };
+}
+
+export async function writeSanitizedFileTransport(input: {
+  deliveryId: number;
+  email: OrderConfirmationEmail;
+  outputPath?: string;
+}): Promise<string> {
+  if (!Number.isSafeInteger(input.deliveryId) || input.deliveryId <= 0) {
+    throw new Error("order email delivery id must be a positive integer");
+  }
+  const outputPath = path.resolve(
+    input.outputPath ??
+      process.env.JARSHOP_EMAIL_FILE_TRANSPORT_PATH ??
+      defaultOutputPath,
+  );
+  await mkdir(outputPath, { recursive: true });
+  const filePath = path.join(
+    outputPath,
+    `${input.deliveryId}.order-confirmation.txt`,
+  );
+  const temporaryPath = `${filePath}.tmp`;
+  await writeFile(
+    temporaryPath,
+    sanitizeFileTransportEmail(input.email),
+    "utf8",
+  );
+  await rename(temporaryPath, filePath);
+  return filePath;
+}
+
+export function sanitizeFileTransportEmail(
+  email: OrderConfirmationEmail,
+): string {
+  return [
+    "To: [redacted]",
+    `Subject: ${email.subject}`,
+    "",
+    email.text.replace(/([?&]token=)[^\s]+/gu, "$1[redacted]"),
+  ].join("\n");
+}
+
+export function createOrderConfirmationUrl(
+  languageCode: OrderEmailLanguageCode,
+  token: string,
+): string {
+  const storefrontUrl =
+    process.env.JARSHOP_STOREFRONT_URL ?? defaultStorefrontUrl;
+  return new URL(
+    `/${languageCode}/checkout/success?token=${encodeURIComponent(token)}`,
+    storefrontUrl,
+  ).toString();
+}
+
+export function toOrderEmailLanguageCode(
+  languageCode: string,
+): OrderEmailLanguageCode {
+  return languageCode === "sk" ? "sk" : "en";
+}
+
+function requireEnvironmentValue(
+  environment: Environment,
+  name: string,
+): string {
+  const value = environment[name]?.trim();
+  if (value === undefined || value.length === 0) {
+    throw new Error(`${name} must be set when JARSHOP_EMAIL_TRANSPORT=smtp`);
+  }
+  return value;
+}
+
+function parseSmtpPort(value: string): number {
+  const port = Number(value);
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+    throw new Error(
+      "JARSHOP_EMAIL_SMTP_PORT must be an integer from 1 to 65535",
+    );
+  }
+  return port;
+}
+
+function parseSmtpSecure(value: string): boolean {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw new Error("JARSHOP_EMAIL_SMTP_SECURE must be true or false");
+}
+
+const emailCopy = {
+  sk: {
+    subject: "Potvrdenie objednávky",
+    greeting: "Ďakujeme za objednávku",
+    items: "Položky objednávky:",
+    shipping: "Doprava",
+    payment: "Platba",
+    total: "Celkom s DPH",
+    confirmation: "Potvrdenie objednávky",
+    notAvailable: "neuvedené",
+  },
+  en: {
+    subject: "Order confirmation",
+    greeting: "Thank you for your order",
+    items: "Order items:",
+    shipping: "Shipping",
+    payment: "Payment",
+    total: "Total including tax",
+    confirmation: "Order confirmation",
+    notAvailable: "not available",
+  },
+} as const;

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

@@ -0,0 +1,39 @@
+export type OrderEmailDeliveryStatusRecord = {
+  id: number;
+  orderId: number;
+  kind: "order-confirmation";
+  status: "pending" | "processing" | "sent" | "failed";
+  attemptCount: number;
+  nextAttemptAt: Date;
+  sentAt: Date | null;
+  lastErrorCode: string | null;
+};
+
+/**
+ * The admin read model is deliberately narrower than the outbox entity. It
+ * must never grow into a backdoor for recipients, encrypted content, worker
+ * leases, or checkout confirmation tokens.
+ */
+export function toOrderEmailDeliveryStatus(
+  delivery: OrderEmailDeliveryStatusRecord,
+) {
+  return {
+    deliveryId: delivery.id,
+    orderId: delivery.orderId,
+    kind: delivery.kind,
+    status: delivery.status,
+    attemptCount: delivery.attemptCount,
+    nextAttemptAt: delivery.nextAttemptAt,
+    sentAt: delivery.sentAt,
+    lastErrorCode: delivery.lastErrorCode,
+  };
+}
+
+export function isOrderAvailableInChannel(
+  orderChannelIds: readonly (number | string)[],
+  activeChannelId: number | string,
+): boolean {
+  return orderChannelIds.some(
+    (orderChannelId) => String(orderChannelId) === String(activeChannelId),
+  );
+}

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

@@ -0,0 +1,66 @@
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  Index,
+  PrimaryGeneratedColumn,
+  Unique,
+  UpdateDateColumn,
+} from "typeorm";
+
+export type OrderEmailDeliveryStatus =
+  "pending" | "processing" | "sent" | "failed";
+
+@Entity({ name: "jarshop_order_email_delivery" })
+@Unique("UQ_jarshop_order_email_delivery_order_kind", ["orderId", "kind"])
+@Index("IDX_jarshop_order_email_delivery_pending", ["status", "nextAttemptAt"])
+export class JarShopOrderEmailDelivery {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Column({ type: "int" })
+  orderId!: number;
+
+  @Column({ type: "varchar", length: 36 })
+  checkoutAttemptId!: string;
+
+  @Column({ type: "varchar", length: 64 })
+  kind!: "order-confirmation";
+
+  @Column({ type: "varchar", length: 10 })
+  languageCode!: string;
+
+  @Column({ type: "varchar", length: 16 })
+  status!: OrderEmailDeliveryStatus;
+
+  @Column({ type: "text" })
+  payloadCiphertext!: string;
+
+  @Column({ type: "int", default: 0 })
+  attemptCount!: number;
+
+  @Column({ type: "timestamptz" })
+  nextAttemptAt!: Date;
+
+  /**
+   * A temporary worker ownership fence. The token prevents a worker whose
+   * lease expired from completing a delivery claimed by a newer worker.
+   */
+  @Column({ type: "varchar", length: 36, nullable: true })
+  leaseToken!: string | null;
+
+  @Column({ type: "timestamptz", nullable: true })
+  leaseExpiresAt!: Date | null;
+
+  @Column({ type: "varchar", length: 64, nullable: true })
+  lastErrorCode!: string | null;
+
+  @Column({ type: "timestamptz", nullable: true })
+  sentAt!: Date | null;
+
+  @CreateDateColumn()
+  createdAt!: Date;
+
+  @UpdateDateColumn()
+  updatedAt!: Date;
+}

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

@@ -0,0 +1,108 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+
+const encryptionAlgorithm = "aes-256-gcm";
+const encryptionKeyBytes = 32;
+
+export type OrderEmailOutboxPayload = {
+  confirmationToken: string;
+};
+
+export function assertOrderEmailOutboxEncryptionConfiguration(): void {
+  parseOrderEmailEncryptionKey(process.env.JARSHOP_ORDER_EMAIL_ENCRYPTION_KEY);
+}
+
+export function createPendingOrderEmailDelivery(input: {
+  orderId: number;
+  checkoutAttemptId: string;
+  languageCode: string;
+  confirmationToken: string;
+  now?: Date;
+  encodedKey?: string;
+}) {
+  return {
+    orderId: input.orderId,
+    checkoutAttemptId: input.checkoutAttemptId,
+    kind: "order-confirmation" as const,
+    languageCode: input.languageCode,
+    status: "pending" as const,
+    payloadCiphertext: encryptOrderEmailOutboxPayload(
+      { confirmationToken: input.confirmationToken },
+      input.encodedKey,
+    ),
+    attemptCount: 0,
+    nextAttemptAt: input.now ?? new Date(),
+    leaseToken: null,
+    leaseExpiresAt: null,
+    lastErrorCode: null,
+    sentAt: null,
+  };
+}
+
+export function encryptOrderEmailOutboxPayload(
+  payload: OrderEmailOutboxPayload,
+  encodedKey = process.env.JARSHOP_ORDER_EMAIL_ENCRYPTION_KEY,
+): string {
+  const key = parseOrderEmailEncryptionKey(encodedKey);
+  const initializationVector = randomBytes(12);
+  const cipher = createCipheriv(encryptionAlgorithm, key, initializationVector);
+  const ciphertext = Buffer.concat([
+    cipher.update(JSON.stringify(payload), "utf8"),
+    cipher.final(),
+  ]);
+  const tag = cipher.getAuthTag();
+  return [
+    "v1",
+    initializationVector.toString("base64url"),
+    tag.toString("base64url"),
+    ciphertext.toString("base64url"),
+  ].join(".");
+}
+
+export function decryptOrderEmailOutboxPayload(
+  payloadCiphertext: string,
+  encodedKey = process.env.JARSHOP_ORDER_EMAIL_ENCRYPTION_KEY,
+): OrderEmailOutboxPayload {
+  const [version, initializationVector, tag, ciphertext, ...unexpected] =
+    payloadCiphertext.split(".");
+  if (
+    version !== "v1" ||
+    !initializationVector ||
+    !tag ||
+    !ciphertext ||
+    unexpected.length > 0
+  ) {
+    throw new Error("order email outbox payload has an unsupported format");
+  }
+  try {
+    const decipher = createDecipheriv(
+      encryptionAlgorithm,
+      parseOrderEmailEncryptionKey(encodedKey),
+      Buffer.from(initializationVector, "base64url"),
+    );
+    decipher.setAuthTag(Buffer.from(tag, "base64url"));
+    const decoded = Buffer.concat([
+      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 };
+  } catch {
+    throw new Error("order email outbox payload cannot be decrypted");
+  }
+}
+
+export function parseOrderEmailEncryptionKey(encodedKey: string | undefined) {
+  const key = encodedKey ? Buffer.from(encodedKey, "base64") : Buffer.alloc(0);
+  if (key.length !== encryptionKeyBytes) {
+    throw new Error(
+      "JARSHOP_ORDER_EMAIL_ENCRYPTION_KEY must be a base64-encoded 32-byte key",
+    );
+  }
+  return key;
+}

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

@@ -0,0 +1,35 @@
+import nodemailer from "nodemailer";
+import {
+  createFileOrderEmailTransport,
+  createSmtpOrderEmailTransport,
+  readOrderEmailTransportConfiguration,
+  type OrderEmailTransport,
+} from "./order-email-delivery-core.js";
+
+/**
+ * Builds the environment-selected delivery implementation without sending or
+ * probing the SMTP provider. The worker owns the first actual delivery call.
+ */
+export function createConfiguredOrderEmailTransport(
+  environment = process.env,
+): OrderEmailTransport {
+  const configuration = readOrderEmailTransportConfiguration(environment);
+  if (configuration.kind === "file") {
+    return createFileOrderEmailTransport({
+      outputPath: configuration.outputPath,
+    });
+  }
+
+  const client = nodemailer.createTransport({
+    host: configuration.host,
+    port: configuration.port,
+    secure: configuration.secure,
+    auth: {
+      user: configuration.username,
+      pass: configuration.password,
+    },
+  });
+  return createSmtpOrderEmailTransport(configuration, async (message) => {
+    await client.sendMail(message);
+  });
+}