@hartl-services/medusa-base 2.5.0 → 2.6.1

package/dist/public/module-access.d.ts

@@ -1,3 +1,11 @@
 import type { MedusaContainer } from "@medusajs/framework/types";
 /** Resolves the base module or fails with a clear `UNEXPECTED_STATE`. */
 export declare const resolveBaseModule: <T>(container: MedusaContainer) => T;
+/**
+ * Whether the base module is registered, for a boot-time check that names the
+ * problem ("add @hartl-services/medusa-base to medusa-config") instead of
+ * failing at the first request.
+ */
+export declare const isBasePluginRegistered: (container: {
+    hasRegistration(name: string): boolean;
+}) => boolean;

package/dist/public/module-access.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveBaseModule = void 0;
+exports.isBasePluginRegistered = exports.resolveBaseModule = void 0;
 const utils_1 = require("@medusajs/framework/utils");
 const constants_1 = require("./constants");
 /** Resolves the base module or fails with a clear `UNEXPECTED_STATE`. */
@@ -11,3 +11,10 @@ const resolveBaseModule = (container) => {
     return container.resolve(constants_1.PLUGIN_FEATURES_MODULE);
 };
 exports.resolveBaseModule = resolveBaseModule;
+/**
+ * Whether the base module is registered, for a boot-time check that names the
+ * problem ("add @hartl-services/medusa-base to medusa-config") instead of
+ * failing at the first request.
+ */
+const isBasePluginRegistered = (container) => container.hasRegistration(constants_1.PLUGIN_FEATURES_MODULE);
+exports.isBasePluginRegistered = isBasePluginRegistered;

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

@@ -1,12 +1,14 @@
 import type { MedusaContainer } from "@medusajs/framework/types";
 /**
- * The base's own descriptor: the shop's master data (Firmenangaben), edited
- * on the generic plugin page like any plugin's settings. It cannot be
+ * The base's own descriptor: the shop's master data (Firmenangaben) and its
+ * appearance (logo and colors of the default e-mail and document layouts),
+ * edited 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, "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";
+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" | "logo" | "color_accent" | "color_text" | "color_muted" | "color_line" | "color_surface", never>;
+declare const SHOP_MASTER_DATA_KEYS: readonly ["legal_name", "address_line1", "address_line2", "postal_code", "city", "country_code", "vat_number", "email", "phone", "website", "iban", "bic", "company_register_number", "company_register_court"];
+/** Keys of the shop master data (company) settings. */
+export type ShopMasterDataKey = (typeof SHOP_MASTER_DATA_KEYS)[number];
 /** Every key that has a value (stored > fallback). All values are strings. */
 export type ShopMasterData = Partial<Record<ShopMasterDataKey, string>>;
 export type ResolvedShopMasterData = {
@@ -22,3 +24,18 @@ export type ResolvedShopMasterData = {
  * `UNEXPECTED_STATE`; read failures propagate.
  */
 export declare function getShopMasterData(container: MedusaContainer): Promise<ResolvedShopMasterData>;
+/** Colors of the default e-mail and document layouts; unset = their default. */
+export type ShopAppearanceColors = Partial<Record<"accent" | "text" | "muted" | "line" | "surface", string>>;
+export type ShopAppearance = {
+    /** Public http(s) URL of the logo, when one is set. */
+    logo?: string;
+    /** Lowercase `#rrggbb` values; only the colors that are set. */
+    colors: ShopAppearanceColors;
+};
+/**
+ * The shop's appearance (Erscheinungsbild) for server-side code, as stored
+ * in the Admin. A missing base plugin fails with `UNEXPECTED_STATE`; read
+ * failures propagate.
+ */
+export declare function getShopAppearance(container: MedusaContainer): Promise<ShopAppearance>;
+export {};

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

@@ -2,27 +2,33 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.shopMasterDataDescriptor = void 0;
 exports.getShopMasterData = getShopMasterData;
+exports.getShopAppearance = getShopAppearance;
 const descriptor_1 = require("./descriptor");
 const settings_1 = require("./settings");
+const COMPANY = "Firmendaten";
+const APPEARANCE = "Erscheinungsbild";
+const DEFAULT_COLOR_HINT = "Leer lassen für die Standardfarbe von E-Mails und Dokumenten.";
 /**
- * The base's own descriptor: the shop's master data (Firmenangaben), edited
- * on the generic plugin page like any plugin's settings. It cannot be
+ * The base's own descriptor: the shop's master data (Firmenangaben) and its
+ * appearance (logo and colors of the default e-mail and document layouts),
+ * edited on the generic plugin page like any plugin's settings. It cannot be
  * switched off and declares no features.
  */
 exports.shopMasterDataDescriptor = (0, descriptor_1.definePluginFeatures)({
     plugin_key: "shop",
     label: "Shop-Stammdaten",
-    description: "Firmenangaben des Shops für E-Mails, Rechnungen, Dokumente und Steuerprüfungen.",
+    description: "Firmenangaben des Shops für E-Mails, Rechnungen, Dokumente und Steuerprüfungen sowie Logo und Farben von E-Mails und Dokumenten.",
     switchable: false,
     features: [],
     settings: [
-        { key: "legal_name", label: "Firmenname", type: "string", required: true },
-        { key: "address_line1", label: "Adresse", type: "string", required: true },
-        { key: "address_line2", label: "Adresszusatz", type: "string" },
-        { key: "postal_code", label: "Postleitzahl", type: "string", required: true },
-        { key: "city", label: "Ort", type: "string", required: true },
+        { key: "legal_name", group: COMPANY, label: "Firmenname", type: "string", required: true },
+        { key: "address_line1", group: COMPANY, label: "Adresse", type: "string", required: true },
+        { key: "address_line2", group: COMPANY, label: "Adresszusatz", type: "string" },
+        { key: "postal_code", group: COMPANY, label: "Postleitzahl", type: "string", required: true },
+        { key: "city", group: COMPANY, label: "Ort", type: "string", required: true },
         {
             key: "country_code",
+            group: COMPANY,
             label: "Land",
             type: "select",
             required: true,
@@ -63,16 +69,74 @@ exports.shopMasterDataDescriptor = (0, descriptor_1.definePluginFeatures)({
                 { value: "cy", label: "Zypern" },
             ],
         },
-        { key: "vat_number", label: "UID-Nummer", type: "string", required: true },
-        { key: "email", label: "E-Mail", type: "string" },
-        { key: "phone", label: "Telefon", type: "string" },
-        { key: "website", label: "Website", type: "url" },
-        { key: "iban", label: "IBAN", type: "string" },
-        { key: "bic", label: "BIC", type: "string" },
-        { key: "company_register_number", label: "Firmenbuchnummer", type: "string" },
-        { key: "company_register_court", label: "Firmenbuchgericht", type: "string" },
+        { key: "vat_number", group: COMPANY, label: "UID-Nummer", type: "string", required: true },
+        { key: "email", group: COMPANY, label: "E-Mail", type: "string" },
+        { key: "phone", group: COMPANY, label: "Telefon", type: "string" },
+        { key: "website", group: COMPANY, label: "Website", type: "url" },
+        { key: "iban", group: COMPANY, label: "IBAN", type: "string" },
+        { key: "bic", group: COMPANY, label: "BIC", type: "string" },
+        { key: "company_register_number", group: COMPANY, label: "Firmenbuchnummer", type: "string" },
+        { key: "company_register_court", group: COMPANY, label: "Firmenbuchgericht", type: "string" },
+        {
+            key: "logo",
+            group: APPEARANCE,
+            label: "Logo",
+            description: "PNG oder JPG, erscheint oben in den E-Mails und auf Rechnungen und Lieferscheinen. Ohne Logo steht dort der Firmenname bzw. Shopname.",
+            type: "image",
+        },
+        {
+            key: "color_accent",
+            group: APPEARANCE,
+            label: "Akzentfarbe",
+            description: `Buttons, Überschriften und Links. ${DEFAULT_COLOR_HINT}`,
+            type: "color",
+        },
+        {
+            key: "color_text",
+            group: APPEARANCE,
+            label: "Textfarbe",
+            description: `Fließtext und Beträge. ${DEFAULT_COLOR_HINT}`,
+            type: "color",
+        },
+        {
+            key: "color_muted",
+            group: APPEARANCE,
+            label: "Nebentextfarbe",
+            description: `Beschriftungen, Hinweise und Fußzeilen. ${DEFAULT_COLOR_HINT}`,
+            type: "color",
+        },
+        {
+            key: "color_line",
+            group: APPEARANCE,
+            label: "Linienfarbe",
+            description: `Rahmen und Trennlinien. ${DEFAULT_COLOR_HINT}`,
+            type: "color",
+        },
+        {
+            key: "color_surface",
+            group: APPEARANCE,
+            label: "Flächenfarbe",
+            description: `Hinterlegte Flächen wie Infoboxen und Tabellenköpfe. ${DEFAULT_COLOR_HINT}`,
+            type: "color",
+        },
     ],
 });
+const SHOP_MASTER_DATA_KEYS = [
+    "legal_name",
+    "address_line1",
+    "address_line2",
+    "postal_code",
+    "city",
+    "country_code",
+    "vat_number",
+    "email",
+    "phone",
+    "website",
+    "iban",
+    "bic",
+    "company_register_number",
+    "company_register_court",
+];
 /**
  * The shop's master data for server-side code, exactly as stored in the
  * Admin: there is no config fallback. A missing base plugin fails with
@@ -81,7 +145,8 @@ exports.shopMasterDataDescriptor = (0, descriptor_1.definePluginFeatures)({
 async function getShopMasterData(container) {
     const resolved = await (0, settings_1.getPluginSettings)(container, exports.shopMasterDataDescriptor);
     const values = {};
-    for (const [key, value] of Object.entries(resolved.values)) {
+    for (const key of SHOP_MASTER_DATA_KEYS) {
+        const value = resolved.values[key];
         if (typeof value === "string") {
             values[key] = value;
         }
@@ -92,3 +157,29 @@ async function getShopMasterData(container) {
         missing: resolved.missing,
     };
 }
+const APPEARANCE_COLOR_KEYS = {
+    accent: "color_accent",
+    text: "color_text",
+    muted: "color_muted",
+    line: "color_line",
+    surface: "color_surface",
+};
+/**
+ * The shop's appearance (Erscheinungsbild) for server-side code, as stored
+ * in the Admin. A missing base plugin fails with `UNEXPECTED_STATE`; read
+ * failures propagate.
+ */
+async function getShopAppearance(container) {
+    const { values } = await (0, settings_1.getPluginSettings)(container, exports.shopMasterDataDescriptor);
+    const colors = {};
+    for (const [token, key] of Object.entries(APPEARANCE_COLOR_KEYS)) {
+        const value = values[key];
+        if (typeof value === "string") {
+            colors[token] = value;
+        }
+    }
+    return {
+        ...(typeof values.logo === "string" ? { logo: values.logo } : {}),
+        colors,
+    };
+}

package/dist/public/types.d.ts

@@ -30,8 +30,11 @@ export type PluginFeatureDefinition<K extends string = string> = {
     readonly default_enabled: boolean;
     readonly parent_key?: K;
 };
-/** `image`: public http(s) URL of an image the Admin uploads (PNG/JPEG). */
-export type PluginSettingType = "string" | "url" | "number" | "boolean" | "secret" | "select" | "image";
+/**
+ * `image`: public http(s) URL of an image the Admin uploads (PNG/JPEG).
+ * `color`: lowercase hex color `#rrggbb`.
+ */
+export type PluginSettingType = "string" | "url" | "number" | "boolean" | "secret" | "select" | "image" | "color";
 /** One allowed value of a `"select"` setting. */
 export type PluginSettingOption = {
     readonly value: string;
@@ -42,6 +45,11 @@ export type PluginSettingDefinition<S extends string = string> = {
     readonly key: S;
     readonly label: string;
     readonly description?: string;
+    /**
+     * Section heading the Admin shows above this setting; consecutive settings
+     * with the same group share one heading.
+     */
+    readonly group?: string;
     readonly type: PluginSettingType;
     /** `false` when omitted. */
     readonly required?: boolean;

package/dist/shared/lib/coerce.d.ts

@@ -0,0 +1,19 @@
+type RawRecord = Record<string, unknown>;
+/** Reads untyped data (query results, event payloads) defensively. */
+/** The object itself, else `{}`: safe to read properties from. */
+export declare const asRecord: (value: unknown) => RawRecord;
+/** The object itself, else `null` (arrays are not records). */
+export declare const asRecordOrNull: (value: unknown) => RawRecord | null;
+/** The trimmed string, `null` for a blank or non-string value. */
+export declare const asText: (value: unknown) => string | null;
+export declare const asArray: (value: unknown) => unknown[];
+/**
+ * The string as it is (not trimmed), `null` for a non-string value. A blank
+ * string is `null` unless `allowBlank` is set.
+ */
+export declare const asOptionalString: (value: unknown, { allowBlank }?: {
+    allowBlank?: boolean;
+}) => string | null;
+/** The number if it is finite, else `null` (no string or BigNumber parsing). */
+export declare const asFiniteNumber: (value: unknown) => number | null;
+export {};

package/dist/shared/lib/coerce.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asFiniteNumber = exports.asOptionalString = exports.asArray = exports.asText = exports.asRecordOrNull = exports.asRecord = void 0;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Reads untyped data (query results, event payloads) defensively. */
+/** The object itself, else `{}`: safe to read properties from. */
+const asRecord = (value) => isRecord(value) ? value : {};
+exports.asRecord = asRecord;
+/** The object itself, else `null` (arrays are not records). */
+const asRecordOrNull = (value) => isRecord(value) ? value : null;
+exports.asRecordOrNull = asRecordOrNull;
+/** The trimmed string, `null` for a blank or non-string value. */
+const asText = (value) => typeof value === "string" && value.trim() ? value.trim() : null;
+exports.asText = asText;
+const asArray = (value) => Array.isArray(value) ? value : [];
+exports.asArray = asArray;
+/**
+ * The string as it is (not trimmed), `null` for a non-string value. A blank
+ * string is `null` unless `allowBlank` is set.
+ */
+const asOptionalString = (value, { allowBlank = false } = {}) => typeof value === "string" && (allowBlank || value.trim()) ? value : null;
+exports.asOptionalString = asOptionalString;
+/** The number if it is finite, else `null` (no string or BigNumber parsing). */
+const asFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+exports.asFiniteNumber = asFiniteNumber;

package/dist/shared/lib/collections.d.ts

@@ -0,0 +1,3 @@
+/** Splits a list into consecutive slices of at most `size` items. */
+export declare const chunk: <Item>(items: readonly Item[], size: number) => Item[][];
+export declare const sleep: (milliseconds: number) => Promise<void>;

package/dist/shared/lib/collections.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = exports.chunk = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+/** Splits a list into consecutive slices of at most `size` items. */
+const chunk = (items, size) => {
+    if (!Number.isInteger(size) || size < 1) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "The chunk size must be a positive integer.");
+    }
+    const chunks = [];
+    for (let index = 0; index < items.length; index += size) {
+        chunks.push(items.slice(index, index + size));
+    }
+    return chunks;
+};
+exports.chunk = chunk;
+const sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+exports.sleep = sleep;

package/dist/shared/lib/dates.d.ts

@@ -0,0 +1,12 @@
+/** A valid `Date`; throws `INVALID_DATA` for an unparsable value. */
+export declare const toValidDate: (value: Date | string | number, message?: string) => Date;
+/** Midnight UTC of the value's UTC calendar day. */
+export declare const startOfUtcDate: (value: Date | string | number) => Date;
+/** `yyyy-mm-dd` of the value's UTC calendar day; throws for an invalid date. */
+export declare const toIsoDate: (value: Date | string | number) => string;
+/** ISO-8601 instant for an HTTP response; throws for an invalid date. */
+export declare const toWireDate: (value: Date | string) => string;
+/** Like `toWireDate`, `null` for `null` / `undefined`. */
+export declare const toOptionalWireDate: (value: Date | string | null | undefined) => string | null;
+/** Whether the value is an IANA time zone this runtime knows ("Europe/Vienna"). */
+export declare const isValidTimeZone: (value: unknown) => value is string;

package/dist/shared/lib/dates.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidTimeZone = exports.toOptionalWireDate = exports.toWireDate = exports.toIsoDate = exports.startOfUtcDate = exports.toValidDate = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+/** A valid `Date`; throws `INVALID_DATA` for an unparsable value. */
+const toValidDate = (value, message = "Invalid date.") => {
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, message);
+    }
+    return date;
+};
+exports.toValidDate = toValidDate;
+/** Midnight UTC of the value's UTC calendar day. */
+const startOfUtcDate = (value) => {
+    const date = (0, exports.toValidDate)(value);
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+};
+exports.startOfUtcDate = startOfUtcDate;
+/** `yyyy-mm-dd` of the value's UTC calendar day; throws for an invalid date. */
+const toIsoDate = (value) => (0, exports.toValidDate)(value).toISOString().slice(0, 10);
+exports.toIsoDate = toIsoDate;
+/** ISO-8601 instant for an HTTP response; throws for an invalid date. */
+const toWireDate = (value) => (0, exports.toValidDate)(value).toISOString();
+exports.toWireDate = toWireDate;
+/** Like `toWireDate`, `null` for `null` / `undefined`. */
+const toOptionalWireDate = (value) => (value == null ? null : (0, exports.toWireDate)(value));
+exports.toOptionalWireDate = toOptionalWireDate;
+/** Whether the value is an IANA time zone this runtime knows ("Europe/Vienna"). */
+const isValidTimeZone = (value) => {
+    if (typeof value !== "string" || !value.trim()) {
+        return false;
+    }
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: value });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+exports.isValidTimeZone = isValidTimeZone;

package/dist/shared/lib/errors.d.ts

@@ -0,0 +1,2 @@
+/** The message of anything that was thrown. */
+export declare const describeError: (error: unknown) => string;

package/dist/shared/lib/errors.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeError = void 0;
+/** The message of anything that was thrown. */
+const describeError = (error) => error instanceof Error
+    ? error.message
+    : typeof error?.message === "string"
+        ? error.message
+        : String(error);
+exports.describeError = describeError;

package/dist/shared/lib/hash.d.ts

@@ -0,0 +1,2 @@
+/** Lower-case hex SHA-256 of a string (UTF-8) or of bytes. */
+export declare const sha256Hex: (value: string | Uint8Array) => string;

package/dist/shared/lib/hash.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256Hex = void 0;
+const node_crypto_1 = require("node:crypto");
+/** Lower-case hex SHA-256 of a string (UTF-8) or of bytes. */
+const sha256Hex = (value) => (0, node_crypto_1.createHash)("sha256").update(value).digest("hex");
+exports.sha256Hex = sha256Hex;

package/dist/shared/lib/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./coerce";
+export * from "./collections";
+export * from "./dates";
+export * from "./errors";
+export * from "./hash";
+export * from "./logging";
+export * from "./money";
+export * from "./text";
+export * from "./transaction";
+export * from "./wire-response";

package/dist/shared/lib/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Generic server/isomorphic helpers shared by all plugins, exported as
+// `@hartl-services/medusa-base/lib`.
+__exportStar(require("./coerce"), exports);
+__exportStar(require("./collections"), exports);
+__exportStar(require("./dates"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./hash"), exports);
+__exportStar(require("./logging"), exports);
+__exportStar(require("./money"), exports);
+__exportStar(require("./text"), exports);
+__exportStar(require("./transaction"), exports);
+__exportStar(require("./wire-response"), exports);

package/dist/shared/lib/logging.d.ts

@@ -0,0 +1,26 @@
+export type OptionalLogger = {
+    warn(message: string): void;
+};
+/**
+ * The registered logger, or `undefined`. Accepts a container (`resolve`) or a
+ * module cradle (`cradle.logger`), the first constructor argument of a module
+ * service. Reading an unregistered key from an awilix cradle throws, and a
+ * missing logger must never stop a module from loading, so every read is
+ * guarded.
+ */
+export declare const resolveOptionalLogger: (source: unknown) => OptionalLogger | undefined;
+export type WarnOnce = {
+    /**
+     * Runs `warn` unless the last warning for `key` had the same `signature`.
+     * Returns whether it ran.
+     */
+    (key: string, signature: string, warn: () => void): boolean;
+    /** Re-arms one key, e.g. once the problem is fixed, or all keys. */
+    reset(key?: string): void;
+};
+/**
+ * One warning per key and signature per process (not per request): a state
+ * that persists is logged once, a changed state is logged again, and `reset`
+ * re-arms a key once the state is healthy.
+ */
+export declare const createWarnOnce: () => WarnOnce;

package/dist/shared/lib/logging.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWarnOnce = exports.resolveOptionalLogger = void 0;
+const LOGGER_KEY = "logger";
+const hasWarn = (value) => typeof value?.warn === "function";
+const attempt = (read) => {
+    try {
+        return read();
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The registered logger, or `undefined`. Accepts a container (`resolve`) or a
+ * module cradle (`cradle.logger`), the first constructor argument of a module
+ * service. Reading an unregistered key from an awilix cradle throws, and a
+ * missing logger must never stop a module from loading, so every read is
+ * guarded.
+ */
+const resolveOptionalLogger = (source) => {
+    const fromProperty = attempt(() => source?.logger);
+    if (hasWarn(fromProperty)) {
+        return fromProperty;
+    }
+    const fromContainer = attempt(() => {
+        const container = source;
+        return typeof container?.resolve === "function"
+            ? container.resolve(LOGGER_KEY)
+            : undefined;
+    });
+    return hasWarn(fromContainer) ? fromContainer : undefined;
+};
+exports.resolveOptionalLogger = resolveOptionalLogger;
+/**
+ * One warning per key and signature per process (not per request): a state
+ * that persists is logged once, a changed state is logged again, and `reset`
+ * re-arms a key once the state is healthy.
+ */
+const createWarnOnce = () => {
+    const lastSignatures = new Map();
+    const warnOnce = ((key, signature, warn) => {
+        if (lastSignatures.get(key) === signature) {
+            return false;
+        }
+        lastSignatures.set(key, signature);
+        warn();
+        return true;
+    });
+    warnOnce.reset = (key) => {
+        if (key === undefined) {
+            lastSignatures.clear();
+        }
+        else {
+            lastSignatures.delete(key);
+        }
+    };
+    return warnOnce;
+};
+exports.createWarnOnce = createWarnOnce;

package/dist/shared/lib/money.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Minor-unit digit count for a currency, e.g. EUR/USD = 2, JPY = 0, KWD = 3.
+ * Sourced from Medusa's static currency table; unknown currencies use 2.
+ */
+export declare const getCurrencyDecimalPlaces: (currencyCode: string) => number;
+/**
+ * A finite number from whatever Medusa returns for an amount or quantity:
+ * a number, a numeric string, a Medusa `BigNumber` (detected by shape, never
+ * by `instanceof`: two copies of `@medusajs/utils` may be installed), a
+ * bignumber.js value or a raw `{ value }` record. Anything else, blank
+ * strings, `NaN` and `Infinity` included, is `null`.
+ */
+export declare const toNumericAmount: (value: unknown) => number | null;

package/dist/shared/lib/money.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toNumericAmount = exports.getCurrencyDecimalPlaces = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+const DEFAULT_CURRENCY_DECIMAL_PLACES = 2;
+/**
+ * Minor-unit digit count for a currency, e.g. EUR/USD = 2, JPY = 0, KWD = 3.
+ * Sourced from Medusa's static currency table; unknown currencies use 2.
+ */
+const getCurrencyDecimalPlaces = (currencyCode) => utils_1.defaultCurrencies[currencyCode.toUpperCase()]?.decimal_digits ??
+    DEFAULT_CURRENCY_DECIMAL_PLACES;
+exports.getCurrencyDecimalPlaces = getCurrencyDecimalPlaces;
+const finiteOrNull = (value) => Number.isFinite(value) ? value : null;
+/**
+ * A finite number from whatever Medusa returns for an amount or quantity:
+ * a number, a numeric string, a Medusa `BigNumber` (detected by shape, never
+ * by `instanceof`: two copies of `@medusajs/utils` may be installed), a
+ * bignumber.js value or a raw `{ value }` record. Anything else, blank
+ * strings, `NaN` and `Infinity` included, is `null`.
+ */
+const toNumericAmount = (value) => {
+    if (typeof value === "number") {
+        return finiteOrNull(value);
+    }
+    if (typeof value === "string") {
+        return value.trim() ? finiteOrNull(Number(value)) : null;
+    }
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const candidate = value;
+    if (typeof candidate.numeric === "number") {
+        return finiteOrNull(candidate.numeric);
+    }
+    if (typeof candidate.toNumber === "function") {
+        return finiteOrNull(Number(candidate.toNumber.call(value)));
+    }
+    if (typeof candidate.raw_ === "object" && candidate.raw_ !== null) {
+        return toRawValue(candidate.raw_.value);
+    }
+    return toRawValue(candidate.value);
+};
+exports.toNumericAmount = toNumericAmount;
+const toRawValue = (value) => typeof value === "number" || typeof value === "string"
+    ? (0, exports.toNumericAmount)(value)
+    : null;

package/dist/shared/lib/text.d.ts

@@ -0,0 +1,19 @@
+/** Placeholder UID for development; never a real merchant UID. */
+export declare const VAT_NUMBER_PLACEHOLDER = "ATU00000000";
+/** A VAT number without whitespace, upper-case: " atu 1234 5678 " -> "ATU12345678". */
+export declare const normalizeVatNumber: (value: string) => string;
+/**
+ * Provider-agnostic e-mail normalization: only surrounding whitespace and
+ * casing change (plus tags and dots can name different mailboxes). `null` for
+ * a blank value or one without a local part, "@" or domain; callers decide
+ * whether that is an error.
+ */
+export declare const normalizeEmail: (value: string | null | undefined) => string | null;
+/** Escapes `\`, `%` and `_` so a value matches literally in `LIKE` / `ILIKE`. */
+export declare const escapeLikePattern: (value: string) => string;
+/** Escapes text for HTML content and double- or single-quoted attributes. */
+export declare const escapeHtml: (value: string | number | null | undefined) => string;
+/** Whether the value parses as an absolute `http:` or `https:` URL. */
+export declare const isHttpUrl: (value: string | null | undefined) => value is string;
+/** A string with at least one non-whitespace character. */
+export declare const isNonEmptyString: (value: unknown) => value is string;