@hartl-services/medusa-base 0.4.0 → 1.0.0

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

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFoodShopConfig = buildFoodShopConfig;
+exports.defineFoodShopConfig = defineFoodShopConfig;
+const logger_1 = require("@medusajs/framework/logger");
+const utils_1 = require("@medusajs/framework/utils");
+const config_1 = require("../public/config");
+const sentry_logger_1 = require("../public/sentry-logger");
+const options_1 = require("./options");
+/**
+ * Builds the plain `medusa-config.ts` input of a food shop: Medusa core
+ * settings, the Redis event bus, SMTP notifications, S3 file storage, tax and
+ * Stripe payment providers, and the Hartl Services plugins (the base plugin
+ * with its E-Mail, Documents and file storage modules plus five feature
+ * plugins). Deployment
+ * values are read and validated from `environment`; a missing or invalid one
+ * fails with its name.
+ */
+function buildFoodShopConfig(options, environment = process.env) {
+    (0, options_1.assertFoodShopConfigOptions)(options);
+    const { merchant } = options;
+    if (options.loadEnvFile !== false) {
+        (0, utils_1.loadEnv)(process.env.NODE_ENV || "development", process.cwd());
+    }
+    const phase = environment.MEDUSA_BUILD_PHASE === "true" ? "build" : "runtime";
+    const allowInsecure = (0, config_1.allowsInsecureLocalServices)(environment, phase);
+    const env = (0, config_1.requireEnvironment)(environment, [
+        "DATABASE_URL",
+        "STORE_CORS",
+        "ADMIN_CORS",
+        "AUTH_CORS",
+        "JWT_SECRET",
+        "COOKIE_SECRET",
+        "MEDUSA_BACKEND_URL",
+        "STOREFRONT_URL",
+        ...config_1.SMTP_ENVIRONMENT_VARIABLES,
+        "STRIPE_API_KEY",
+        "STRIPE_WEBHOOK_SECRET",
+        "S3_CACHE_STORAGE_BUCKET",
+        "S3_CACHE_STORAGE_REGION",
+        "DOCUMENT_PDF_EXECUTABLE",
+    ], phase, {
+        ...config_1.MEDUSA_BUILD_PLACEHOLDERS,
+        ...config_1.SMTP_BUILD_PLACEHOLDERS,
+        ...config_1.S3_BUILD_PLACEHOLDERS,
+        ...config_1.DOCUMENTS_BUILD_PLACEHOLDERS,
+    });
+    const storefrontOrigin = (0, config_1.resolvePublicOrigin)(env.STOREFRONT_URL, "STOREFRONT_URL", allowInsecure);
+    const backendOrigin = (0, config_1.resolvePublicOrigin)(env.MEDUSA_BACKEND_URL, "MEDUSA_BACKEND_URL", allowInsecure);
+    const redis = (0, config_1.resolveRedisEventBus)(environment, phase);
+    const stripe = (0, config_1.resolveStripe)(env);
+    const storefrontPath = `/${options.storefrontCountryCode}`;
+    // S3 file storage: the File Module provider plus the `files.gateway` option
+    // of the base plugin that serves its /files routes, both from one validated
+    // configuration.
+    const s3CacheStorage = (0, config_1.createS3CacheStorageConfig)({
+        cache: {
+            cleanupIntervalMs: (0, config_1.integerEnvironment)(environment, "S3_CACHE_STORAGE_CLEANUP_INTERVAL_MS", 1, 86_400_000) ?? 900_000,
+            dir: (0, config_1.optionalEnvironment)(environment, "S3_CACHE_STORAGE_CACHE_DIR") ??
+                "./.medusa-s3-cache",
+            expirationStrategy: (0, config_1.resolveExpirationStrategy)(environment, "absolute"),
+            ttlMs: (0, config_1.integerEnvironment)(environment, "S3_CACHE_STORAGE_TTL_MS", 0, 604_800_000) ?? 3_600_000,
+        },
+        gateway: {
+            baseUrl: `${backendOrigin}/files`,
+            privateDownloadDurationSeconds: (0, config_1.integerEnvironment)(environment, "FILE_GATEWAY_PRIVATE_DOWNLOAD_DURATION_SECONDS", 1, 604_800) ?? 3_600,
+            signingSecret: env.JWT_SECRET,
+        },
+        s3: {
+            bucket: env.S3_CACHE_STORAGE_BUCKET,
+            credentials: (0, config_1.resolveS3Credentials)(environment, phase),
+            endpoint: (0, config_1.optionalEnvironment)(environment, "S3_CACHE_STORAGE_ENDPOINT"),
+            forcePathStyle: (0, config_1.booleanEnvironment)(environment, "S3_CACHE_STORAGE_FORCE_PATH_STYLE", false),
+            region: env.S3_CACHE_STORAGE_REGION,
+            storagePrefix: (0, config_1.optionalEnvironment)(environment, "S3_CACHE_STORAGE_PREFIX"),
+        },
+    });
+    const modules = [
+        ...(redis
+            ? [
+                {
+                    key: utils_1.Modules.EVENT_BUS,
+                    resolve: "@medusajs/event-bus-redis",
+                    options: {
+                        redisUrl: redis.url,
+                        jobOptions: {
+                            attempts: 3,
+                            backoff: {
+                                delay: 1_000,
+                                type: "exponential",
+                            },
+                            removeOnComplete: true,
+                            removeOnFail: {
+                                age: 3_600,
+                                count: 1_000,
+                            },
+                        },
+                    },
+                },
+            ]
+            : []),
+        (0, config_1.createSmtpNotificationModuleConfig)((0, config_1.resolveSmtp)(env, allowInsecure)),
+        s3CacheStorage.fileModule,
+        {
+            resolve: "@medusajs/medusa/tax",
+            options: {
+                providers: [
+                    {
+                        resolve: "@hartl-services/medusa-tax-compliance/providers/tax-compliance",
+                    },
+                ],
+            },
+        },
+        {
+            resolve: "@medusajs/medusa/payment",
+            options: {
+                providers: [
+                    {
+                        resolve: "@medusajs/medusa/payment-stripe",
+                        id: "stripe",
+                        options: {
+                            apiKey: stripe.apiKey,
+                            webhookSecret: stripe.webhookSecret,
+                            // Capture immediately at checkout. Several enabled payment
+                            // methods (e.g. SEPA Direct Debit, iDEAL, Klarna) do not
+                            // support a separate manual-capture step, so authorize-only is
+                            // not an option while automaticPaymentMethods exposes them.
+                            capture: true,
+                            // Which methods appear (card, SEPA, wallets, ...) is controlled
+                            // in the Stripe Dashboard under Settings -> Payment methods.
+                            automaticPaymentMethods: true,
+                        },
+                    },
+                ],
+            },
+        },
+    ];
+    const plugins = [
+        {
+            // Always first: owns the plugin feature toggles the other plugins gate
+            // on, and carries E-Mail, Documents and the /files gateway.
+            resolve: "@hartl-services/medusa-base",
+            options: {
+                email: {
+                    jwtSecret: env.JWT_SECRET,
+                    shop: {
+                        displayName: options.displayName,
+                        affiliatePortalUrl: (0, config_1.shopUrl)(storefrontOrigin, `${storefrontPath}/partnerportal`),
+                        // The Admin dashboard mounts "/invite" under admin.path ("/app").
+                        inviteUrl: ({ token }) => {
+                            const url = new URL("/app/invite", backendOrigin);
+                            url.searchParams.set("token", token);
+                            return url.toString();
+                        },
+                        orderNotificationEmail: options.orderNotificationEmail,
+                        // The e-mail module appends "#token=<token>".
+                        passwordResetUrl: () => (0, config_1.shopUrl)(storefrontOrigin, `${storefrontPath}/reset-password`),
+                    },
+                },
+                documents: {
+                    // Fallback only: the shop master data in the Admin ("Hartl Services
+                    // Plugins" -> Shop-Stammdaten) wins per field.
+                    merchant,
+                    numbering: {
+                        // Chooses the annual document-number period; matches the date the
+                        // HTML factory prints.
+                        timeZone: options.timeZone,
+                    },
+                    pdf: {
+                        executablePath: env.DOCUMENT_PDF_EXECUTABLE,
+                    },
+                },
+                files: { gateway: s3CacheStorage.gateway },
+            },
+        },
+        {
+            resolve: "@hartl-services/medusa-tax-compliance",
+            options: { merchant },
+        },
+        {
+            resolve: "@hartl-services/medusa-free-shipping",
+            options: {},
+        },
+        {
+            resolve: "@hartl-services/medusa-batch-management",
+            options: {},
+        },
+        {
+            resolve: "@hartl-services/medusa-affiliate",
+            options: {
+                consignment_reminders: {
+                    due_day: 10,
+                    timezone: options.timeZone,
+                },
+                portal: {
+                    referral_base_url: (0, config_1.shopUrl)(storefrontOrigin, storefrontPath),
+                },
+            },
+        },
+        {
+            resolve: "@hartl-services/medusa-payload-sync",
+            // URL, API key and auth collection are Admin settings of the base
+            // plugin ("Hartl Services Plugins" -> Payload-CMS-Sync); until they are
+            // stored the plugin boots "nicht konfiguriert".
+            options: {},
+        },
+    ];
+    return {
+        admin: {
+            // Kept explicit: serving the Admin SPA at "/" instead breaks its own
+            // auth, since the SPA's client-side-routing fallback then catches real
+            // API routes like /auth/user/providers too. The invite URL depends on
+            // this path.
+            path: "/app",
+        },
+        // Medusa's own HTTP error-handler middleware fully "handles" every thrown
+        // route/workflow error via logger.error(...) before it can ever reach an
+        // uncaught-exception process hook, so Sentry's default Node integrations
+        // never see it. This bridges logger.error(...) itself so those errors
+        // still reach Sentry.
+        logger: (0, sentry_logger_1.withSentryErrorReporting)(logger_1.logger),
+        projectConfig: {
+            databaseUrl: env.DATABASE_URL,
+            http: {
+                storeCors: env.STORE_CORS,
+                adminCors: env.ADMIN_CORS,
+                authCors: env.AUTH_CORS,
+                jwtSecret: env.JWT_SECRET,
+                cookieSecret: env.COOKIE_SECRET,
+            },
+            // The storefront turns its customer JWT into a Medusa browser session
+            // at login, so its browser-side cart and payment calls carry the
+            // customer's identity. Kept at the JWT's own 24h lifetime (Medusa's
+            // default is 10h) so the two never disagree about whether the customer
+            // is logged in.
+            sessionOptions: {
+                ttl: 24 * 60 * 60 * 1000,
+            },
+        },
+        modules,
+        plugins,
+    };
+}
+/** `defineConfig(buildFoodShopConfig(options))` for `module.exports`. */
+function defineFoodShopConfig(options, environment = process.env) {
+    return (0, utils_1.defineConfig)(buildFoodShopConfig(options, environment));
+}

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

@@ -0,0 +1,41 @@
+import type { 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).
+ */
+export type FoodShopConfigOptions = Readonly<{
+    /**
+     * Fallback for the shop master data (Admin -> "Hartl Services Plugins" ->
+     * Shop-Stammdaten) that documents and tax compliance read per field. Its
+     * `legalName` is also the seeded store name.
+     */
+    merchant: DocumentMerchantOption;
+    /** Shop name in the branding of the default e-mail templates. */
+    displayName: string;
+    /** Receives the shop's order notification e-mails. */
+    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.
+     */
+    timeZone: string;
+    /**
+     * Country code of the storefront route segment (e.g. "de"): e-mail links
+     * point to `/<code>/partnerportal` and `/<code>/reset-password`, and
+     * affiliate referral links to `/<code>`.
+     */
+    storefrontCountryCode: string;
+    /**
+     * Load `.env.<NODE_ENV>` from the working directory into `process.env`
+     * like `medusa-config.ts` does by default. Pass `false` when the
+     * environment is already complete (tests, isolated child processes).
+     * Defaults to `true`.
+     */
+    loadEnvFile?: boolean;
+}>;
+/**
+ * Throws a `TypeError` naming the first invalid option, so a misconfigured
+ * shop fails at boot.
+ */
+export declare function assertFoodShopConfigOptions(options: unknown): asserts options is FoodShopConfigOptions;

package/dist/shop-config/options.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertFoodShopConfigOptions = assertFoodShopConfigOptions;
+const fail = (name, expectation) => {
+    throw new TypeError(`Food shop option "${name}" must be ${expectation}.`);
+};
+const requireText = (value, name) => {
+    if (typeof value !== "string" || value.trim() === "") {
+        return fail(name, "a non-empty string");
+    }
+    return value;
+};
+const requireCountryCode = (value, name) => {
+    if (typeof value !== "string" || !/^[a-z]{2}$/.test(value)) {
+        return fail(name, 'a 2-letter lowercase country code such as "de"');
+    }
+    return value;
+};
+const requireTimeZone = (value, name) => {
+    const timeZone = requireText(value, name);
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone });
+    }
+    catch {
+        return fail(name, 'a valid IANA time zone such as "Europe/Vienna"');
+    }
+    return timeZone;
+};
+const requireEmail = (value, name) => {
+    const email = requireText(value, name);
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+        return fail(name, "a valid e-mail address");
+    }
+    return email;
+};
+const requireObject = (value, name) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return fail(name, "an object");
+    }
+    return value;
+};
+/**
+ * Throws a `TypeError` naming the first invalid option, so a misconfigured
+ * shop fails at boot.
+ */
+function assertFoodShopConfigOptions(options) {
+    const candidate = requireObject(options, "options");
+    const merchant = requireObject(candidate.merchant, "merchant");
+    requireText(merchant.legalName, "merchant.legalName");
+    requireCountryCode(merchant.countryCode, "merchant.countryCode");
+    if (merchant.vatNumber !== undefined) {
+        requireText(merchant.vatNumber, "merchant.vatNumber");
+    }
+    const address = requireObject(merchant.registeredAddress, "merchant.registeredAddress");
+    requireText(address.address1, "merchant.registeredAddress.address1");
+    if (address.address2 !== undefined) {
+        requireText(address.address2, "merchant.registeredAddress.address2");
+    }
+    requireText(address.city, "merchant.registeredAddress.city");
+    requireText(address.postalCode, "merchant.registeredAddress.postalCode");
+    requireCountryCode(address.countryCode, "merchant.registeredAddress.countryCode");
+    requireText(candidate.displayName, "displayName");
+    requireEmail(candidate.orderNotificationEmail, "orderNotificationEmail");
+    requireTimeZone(candidate.timeZone, "timeZone");
+    requireCountryCode(candidate.storefrontCountryCode, "storefrontCountryCode");
+    if (candidate.loadEnvFile !== undefined &&
+        typeof candidate.loadEnvFile !== "boolean") {
+        fail("loadEnvFile", "a boolean");
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hartl-services/medusa-base",
-  "version": "0.4.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, and the Sentry logger wrapper.",
+  "version": "1.0.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": [
     ".medusa/server",
@@ -33,10 +33,36 @@
       "import": "./dist/public/sentry-logger.js",
       "require": "./dist/public/sentry-logger.js"
     },
+    "./config": {
+      "types": "./dist/public/config.d.ts",
+      "import": "./dist/public/config.js",
+      "require": "./dist/public/config.js"
+    },
+    "./types": {
+      "types": "./dist/public/shop-types.d.ts",
+      "import": "./dist/public/shop-types.js",
+      "require": "./dist/public/shop-types.js"
+    },
+    "./gateway": {
+      "types": "./dist/public/gateway.d.ts",
+      "import": "./dist/public/gateway.js",
+      "require": "./dist/public/gateway.js"
+    },
+    "./shop-config": {
+      "types": "./dist/public/shop-config.d.ts",
+      "import": "./dist/public/shop-config.js",
+      "require": "./dist/public/shop-config.js"
+    },
+    "./instrumentation": {
+      "types": "./dist/public/instrumentation.d.ts",
+      "import": "./dist/public/instrumentation.js",
+      "require": "./dist/public/instrumentation.js"
+    },
     "./admin-components": {
       "types": "./dist/admin-components/index.d.ts",
       "import": "./dist/admin-components/index.js"
     },
+    "./providers/*": "./.medusa/server/src/providers/*/index.js",
     "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
     "./.medusa/server/src/*": "./.medusa/server/src/*",
     "./admin": {
@@ -56,7 +82,13 @@
     "react-router-dom": "^7.18.2"
   },
   "dependencies": {
-    "@hartl-services/medusa-food-supplements-contracts": "^0.12.0"
+    "@aws-sdk/client-s3": "^3.948.0",
+    "@aws-sdk/lib-storage": "^3.954.0",
+    "jsonwebtoken": "9.0.3",
+    "mime-types": "3.0.1",
+    "nodemailer": "6.10.1",
+    "ulid": "^2.4.0",
+    "@hartl-services/medusa-food-supplements-contracts": "^0.16.0"
   },
   "devDependencies": {
     "@medusajs/admin-sdk": "2.19.0",
@@ -64,18 +96,26 @@
     "@medusajs/framework": "2.19.0",
     "@medusajs/js-sdk": "2.19.0",
     "@medusajs/medusa": "2.19.0",
+    "@medusajs/test-utils": "2.19.0",
     "@medusajs/ui": "4.2.1",
     "@sentry/node": "^10.74.0",
     "@swc/core": "^1.7.28",
     "@swc/jest": "^0.2.39",
     "@tanstack/react-query": "5.64.2",
     "@types/jest": "^29.5.14",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/mailparser": "3.4.6",
+    "@types/mime-types": "3.0.1",
     "@types/node": "^20.12.11",
+    "@types/nodemailer": "6.4.17",
     "@types/react": "^18.3.2",
     "@types/react-dom": "^18.2.25",
+    "@types/smtp-server": "3.5.10",
     "jest": "^29.7.0",
+    "mailparser": "3.7.2",
     "react": "^18.3.1",
     "react-router-dom": "7.18.2",
+    "smtp-server": "3.13.6",
     "typescript": "^5.6.2",
     "vite": "7.3.6",
     "yalc": "^1.0.0-pre.53"
@@ -91,8 +131,11 @@
   "scripts": {
     "build": "medusa plugin:build && tsc -p tsconfig.public.json && tsc -p tsconfig.admin-components.json",
     "dev": "medusa plugin:develop",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.type-tests.json --noEmit",
     "pretest:unit": "pnpm --filter @hartl-services/medusa-food-supplements-contracts build",
-    "test:unit": "jest"
+    "test:unit": "jest",
+    "pretest:contract": "pnpm --filter @hartl-services/medusa-food-supplements-contracts build",
+    "test:contract": "jest --config jest.contract.config.js --runInBand",
+    "test:integration:modules": "TEST_TYPE=integration:modules NODE_OPTIONS=--experimental-vm-modules jest --config jest.integration.config.js --silent=false --runInBand --forceExit"
   }
 }