@hartl-services/medusa-base 1.0.0 → 1.1.0

package/dist/email/types/template-data.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EmailRenderDataSchemas = exports.EmailPersistedDataSchemas = void 0;
+exports.EmailRenderDataSchemas = exports.EmailPersistedDataSchemas = exports.RefundSummarySchema = exports.ReturnReceivedSummarySchema = exports.ReturnSummarySchema = exports.ShipmentSummarySchema = exports.OrderSummarySchema = void 0;
 const zod_1 = require("@medusajs/framework/zod");
 const affiliate_1 = require("@hartl-services/medusa-food-supplements-contracts/schemas/affiliate");
 const NonEmptyStringSchema = zod_1.z.string().trim().min(1);
@@ -9,15 +9,146 @@ const DocumentsFactFingerprintSchema = zod_1.z
     .string()
     .regex(/^[a-f0-9]{64}$/)
     .optional();
+const AmountSchema = zod_1.z.string().regex(/^-?\d+(\.\d+)?$/);
+const OptionalTextSchema = zod_1.z.string().nullable();
+const OrderSummaryAddressSchema = zod_1.z
+    .object({
+    first_name: OptionalTextSchema,
+    last_name: OptionalTextSchema,
+    company: OptionalTextSchema,
+    address_1: OptionalTextSchema,
+    address_2: OptionalTextSchema,
+    postal_code: OptionalTextSchema,
+    city: OptionalTextSchema,
+    country_code: OptionalTextSchema,
+})
+    .strict();
+/**
+ * Snapshot of an order when it was placed. Amounts are Medusa's gross
+ * decimal strings: item and shipping rows before discounts, so
+ * `original_item_total + original_shipping_total - discount_total` is the
+ * `total`, which already contains `tax_total`.
+ */
+exports.OrderSummarySchema = zod_1.z
+    .object({
+    display_id: zod_1.z.number().int().nullable(),
+    /** The order's e-mail address; `null` when the order has none. */
+    email: OptionalTextSchema,
+    /** When the order was placed (ISO 8601). */
+    placed_at: zod_1.z.string().datetime(),
+    currency_code: NonEmptyStringSchema,
+    items: zod_1.z.array(zod_1.z
+        .object({
+        title: NonEmptyStringSchema,
+        variant_title: OptionalTextSchema,
+        quantity: zod_1.z.number().positive(),
+        original_total: AmountSchema,
+    })
+        .strict()),
+    shipping_method_names: zod_1.z.array(NonEmptyStringSchema),
+    original_item_total: AmountSchema,
+    original_shipping_total: AmountSchema,
+    discount_total: AmountSchema,
+    tax_total: AmountSchema,
+    total: AmountSchema,
+    billing_address: OrderSummaryAddressSchema.nullable(),
+    shipping_address: OrderSummaryAddressSchema.nullable(),
+})
+    .strict();
+/**
+ * Snapshot of one shipment when it was shipped: the parcel's items (title
+ * of the order line, shipped quantity), tracking numbers and links as
+ * entered at shipping, and whether more of the order is still to be shipped.
+ */
+exports.ShipmentSummarySchema = zod_1.z
+    .object({
+    display_id: zod_1.z.number().int().nullable(),
+    shipping_method_name: OptionalTextSchema,
+    tracking: zod_1.z.array(zod_1.z
+        .object({
+        number: OptionalTextSchema,
+        url: OptionalTextSchema,
+    })
+        .strict()),
+    items: zod_1.z.array(zod_1.z
+        .object({
+        title: NonEmptyStringSchema,
+        variant_title: OptionalTextSchema,
+        quantity: zod_1.z.number().positive(),
+    })
+        .strict()),
+    delivery_address: OrderSummaryAddressSchema.nullable(),
+    more_to_follow: zod_1.z.boolean(),
+})
+    .strict();
+/**
+ * Snapshot of a return when it was requested: the return and order numbers,
+ * the items to send back (title of the order line, quantity, reason label),
+ * the return shipping option and where to send the parcel.
+ */
+exports.ReturnSummarySchema = zod_1.z
+    .object({
+    display_id: zod_1.z.number().int().nullable(),
+    order_display_id: zod_1.z.number().int().nullable(),
+    shipping_method_name: OptionalTextSchema,
+    items: zod_1.z.array(zod_1.z
+        .object({
+        title: NonEmptyStringSchema,
+        variant_title: OptionalTextSchema,
+        quantity: zod_1.z.number().positive(),
+        reason: OptionalTextSchema,
+    })
+        .strict()),
+    return_address: OrderSummaryAddressSchema.nullable(),
+})
+    .strict();
+/**
+ * Snapshot of a return when it was completely received: the return and
+ * order numbers, when it arrived and the received items (title of the order
+ * line, received quantity and how much of it arrived damaged).
+ */
+exports.ReturnReceivedSummarySchema = zod_1.z
+    .object({
+    display_id: zod_1.z.number().int().nullable(),
+    order_display_id: zod_1.z.number().int().nullable(),
+    received_at: zod_1.z.string().datetime().nullable(),
+    items: zod_1.z.array(zod_1.z
+        .object({
+        title: NonEmptyStringSchema,
+        variant_title: OptionalTextSchema,
+        quantity: zod_1.z.number().positive(),
+        damaged_quantity: zod_1.z.number().nonnegative(),
+    })
+        .strict()),
+})
+    .strict();
+/**
+ * Snapshot of one refund when its Documents fact arrived: the order number,
+ * the refunded gross amount, when it was refunded and the refund reason
+ * chosen in the Admin.
+ */
+exports.RefundSummarySchema = zod_1.z
+    .object({
+    order_display_id: zod_1.z.number().int().nullable(),
+    amount: AmountSchema,
+    currency_code: NonEmptyStringSchema,
+    refunded_at: zod_1.z.string().datetime().nullable(),
+    reason: OptionalTextSchema,
+})
+    .strict();
 exports.EmailPersistedDataSchemas = {
     "order.received": zod_1.z
         .object({
         order_id: NonEmptyStringSchema,
+        // Optional: messages stored before the summary existed have none.
+        summary: exports.OrderSummarySchema.optional(),
     })
         .strict(),
     "order.received.admin": zod_1.z
         .object({
         order_id: NonEmptyStringSchema,
+        // Optional: messages stored before the summary existed have none.
+        summary: exports.OrderSummarySchema.optional(),
     })
         .strict(),
     "order.shipped": zod_1.z
@@ -25,24 +156,38 @@ exports.EmailPersistedDataSchemas = {
         order_id: NonEmptyStringSchema,
         fulfillment_id: NonEmptyStringSchema,
         documents_fact_fingerprint: DocumentsFactFingerprintSchema,
+        // Optional: messages stored before the snapshot existed have none.
+        shipment: exports.ShipmentSummarySchema.optional(),
+        /** The invoice PDF is attached (Documents chose this shipment). */
+        invoice_attached: zod_1.z.boolean().optional(),
     })
         .strict(),
     "order.canceled": zod_1.z
         .object({
         order_id: NonEmptyStringSchema,
         documents_fact_fingerprint: DocumentsFactFingerprintSchema,
+        // Optional: messages stored before the snapshot existed have none.
+        summary: exports.OrderSummarySchema.optional(),
+        /** When the order was canceled (ISO 8601). */
+        canceled_at: zod_1.z.string().datetime().optional(),
+        /** A cancellation document PDF is attached (from Documents). */
+        cancellation_attached: zod_1.z.boolean().optional(),
     })
         .strict(),
     "order.return_requested": zod_1.z
         .object({
         order_id: NonEmptyStringSchema,
         return_id: NonEmptyStringSchema,
+        // Optional: messages stored before the snapshot existed have none.
+        summary: exports.ReturnSummarySchema.optional(),
     })
         .strict(),
     "order.return_received": zod_1.z
         .object({
         order_id: NonEmptyStringSchema,
         return_id: NonEmptyStringSchema,
+        // Optional: messages stored before the snapshot existed have none.
+        summary: exports.ReturnReceivedSummarySchema.optional(),
     })
         .strict(),
     "order.refunded": zod_1.z
@@ -50,6 +195,10 @@ exports.EmailPersistedDataSchemas = {
         order_id: NonEmptyStringSchema,
         refund_id: NonEmptyStringSchema,
         documents_fact_fingerprint: DocumentsFactFingerprintSchema,
+        // Optional: messages stored before the snapshot existed have none.
+        summary: exports.RefundSummarySchema.optional(),
+        /** A cancellation document PDF is attached (from Documents). */
+        cancellation_attached: zod_1.z.boolean().optional(),
     })
         .strict(),
     "auth.password_reset": zod_1.z
@@ -71,8 +220,12 @@ exports.EmailRenderDataSchemas = {
     ...exports.EmailPersistedDataSchemas,
     "auth.password_reset": exports.EmailPersistedDataSchemas["auth.password_reset"].extend({
         reset_url: zod_1.z.string().url(),
+        /** How long the reset link is valid, from the token; `undefined` if unknown. */
+        valid_minutes: zod_1.z.number().int().positive().optional(),
     }),
     "user.invite": exports.EmailPersistedDataSchemas["user.invite"].extend({
         invite_url: zod_1.z.string().url(),
+        /** When the invite expires (ISO 8601), from the current invite. */
+        expires_at: zod_1.z.string().datetime().optional(),
     }),
 };

package/dist/public/descriptor.js

@@ -11,6 +11,7 @@ const SETTING_TYPES = new Set([
     "boolean",
     "secret",
     "select",
+    "image",
 ]);
 const ACTION_MODES = new Set(["sync", "background"]);
 const ADMIN_PAGE_PREFIX = "/settings/hartl-services/";
@@ -33,6 +34,7 @@ const defaultMatchesType = (setting) => {
         case "string":
             return hasText(value);
         case "url":
+        case "image":
             return typeof value === "string" && isHttpUrl(value);
         case "number":
             return typeof value === "number" && Number.isFinite(value);

package/dist/public/shop-master-data.d.ts

@@ -5,7 +5,7 @@ import type { PluginSettingsFallback } from "./types";
  * on the generic plugin page like any plugin's settings. It cannot be
  * switched off and declares no features.
  */
-export declare const shopMasterDataDescriptor: import("./types").PluginFeatureDescriptor<string, "legal_name" | "address_line1" | "address_line2" | "postal_code" | "city" | "country_code" | "vat_number" | "email" | "phone" | "website" | "iban" | "bic" | "company_register_number" | "company_register_court", never>;
+export declare const shopMasterDataDescriptor: import("./types").PluginFeatureDescriptor<string, "country_code" | "legal_name" | "address_line1" | "address_line2" | "postal_code" | "city" | "vat_number" | "email" | "phone" | "website" | "iban" | "bic" | "company_register_number" | "company_register_court", never>;
 /** Keys of the shop master data settings. */
 export type ShopMasterDataKey = "legal_name" | "address_line1" | "address_line2" | "postal_code" | "city" | "country_code" | "vat_number" | "email" | "phone" | "website" | "iban" | "bic" | "company_register_number" | "company_register_court";
 /** Every key that has a value (stored > fallback). All values are strings. */

package/dist/public/shop-master-data.js

@@ -12,7 +12,7 @@ const settings_1 = require("./settings");
 exports.shopMasterDataDescriptor = (0, descriptor_1.definePluginFeatures)({
     plugin_key: "shop",
     label: "Shop-Stammdaten",
-    description: "Firmenangaben des Shops für Rechnungen, Dokumente und Steuerprüfungen.",
+    description: "Firmenangaben des Shops für E-Mails, Rechnungen, Dokumente und Steuerprüfungen.",
     switchable: false,
     features: [],
     settings: [

package/dist/public/types.d.ts

@@ -30,7 +30,8 @@ export type PluginFeatureDefinition<K extends string = string> = {
     readonly default_enabled: boolean;
     readonly parent_key?: K;
 };
-export type PluginSettingType = "string" | "url" | "number" | "boolean" | "secret" | "select";
+/** `image`: public http(s) URL of an image the Admin uploads (PNG/JPEG). */
+export type PluginSettingType = "string" | "url" | "number" | "boolean" | "secret" | "select" | "image";
 /** One allowed value of a `"select"` setting. */
 export type PluginSettingOption = {
     readonly value: string;

package/dist/shop-config/build-food-shop-config.js

@@ -144,6 +144,8 @@ function buildFoodShopConfig(options, environment = process.env) {
                 email: {
                     jwtSecret: env.JWT_SECRET,
                     shop: {
+                        // The Admin dashboard mounts under admin.path ("/app").
+                        adminOrderUrl: ({ orderId }) => new URL(`/app/orders/${encodeURIComponent(orderId)}`, backendOrigin).toString(),
                         displayName: options.displayName,
                         affiliatePortalUrl: (0, config_1.shopUrl)(storefrontOrigin, `${storefrontPath}/partnerportal`),
                         // The Admin dashboard mounts "/invite" under admin.path ("/app").
@@ -155,9 +157,11 @@ function buildFoodShopConfig(options, environment = process.env) {
                         orderNotificationEmail: options.orderNotificationEmail,
                         // The e-mail module appends "#token=<token>".
                         passwordResetUrl: () => (0, config_1.shopUrl)(storefrontOrigin, `${storefrontPath}/reset-password`),
+                        timeZone: options.timeZone,
                     },
                 },
                 documents: {
+                    htmlFactory: options.documentHtmlFactory,
                     // Fallback only: the shop master data in the Admin ("Hartl Services
                     // Plugins" -> Shop-Stammdaten) wins per field.
                     merchant,

package/dist/shop-config/options.d.ts

@@ -1,4 +1,4 @@
-import type { DocumentMerchantOption } from "../documents/types";
+import type { DocumentHtmlFactory, DocumentMerchantOption } from "../documents/types";
 /**
  * The shop-specific facts of a food shop. Deployment values and secrets are
  * not options: they come from the environment (see the README).
@@ -16,8 +16,8 @@ export type FoodShopConfigOptions = Readonly<{
     orderNotificationEmail: string;
     /**
      * IANA time zone (e.g. "Europe/Vienna"): chooses the annual document-number
-     * period, matches the dates printed on documents, and schedules the
-     * affiliate consignment reminders.
+     * period, matches the dates printed on documents and e-mails, and
+     * schedules the affiliate consignment reminders.
      */
     timeZone: string;
     /**
@@ -26,6 +26,13 @@ export type FoodShopConfigOptions = Readonly<{
      * affiliate referral links to `/<code>`.
      */
     storefrontCountryCode: string;
+    /**
+     * Replaces the default document markup (documents `htmlFactory`), e.g.
+     * `createDefaultDocumentHtmlFactory({ timeZone, theme })` from
+     * `@hartl-services/medusa-base/config` with the shop's own CSS and
+     * watermark. Omit it for the plugin's default look.
+     */
+    documentHtmlFactory?: DocumentHtmlFactory;
     /**
      * Load `.env.<NODE_ENV>` from the working directory into `process.env`
      * like `medusa-config.ts` does by default. Pass `false` when the

package/dist/shop-config/options.js

@@ -63,6 +63,10 @@ function assertFoodShopConfigOptions(options) {
     requireEmail(candidate.orderNotificationEmail, "orderNotificationEmail");
     requireTimeZone(candidate.timeZone, "timeZone");
     requireCountryCode(candidate.storefrontCountryCode, "storefrontCountryCode");
+    if (candidate.documentHtmlFactory !== undefined &&
+        typeof candidate.documentHtmlFactory !== "function") {
+        fail("documentHtmlFactory", "a function");
+    }
     if (candidate.loadEnvFile !== undefined &&
         typeof candidate.loadEnvFile !== "boolean") {
         fail("loadEnvFile", "a boolean");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hartl-services/medusa-base",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Base plugin for Hartl Services Medusa shops: per-plugin feature toggles with a generic Admin settings page, a Store endpoint for storefronts, enforcement helpers, the complete-cart hook composition, the root redirect, cart-promotion link repair, the built-in E-Mail, Documents and S3 file storage modules, config helpers with the turnkey food-shop preset, and the Sentry logger wrapper and instrumentation.",
   "license": "MIT",
   "files": [
@@ -88,7 +88,7 @@
     "mime-types": "3.0.1",
     "nodemailer": "6.10.1",
     "ulid": "^2.4.0",
-    "@hartl-services/medusa-food-supplements-contracts": "^0.16.0"
+    "@hartl-services/medusa-food-supplements-contracts": "^0.17.0"
   },
   "devDependencies": {
     "@medusajs/admin-sdk": "2.19.0",