@bigfootds/bigfootds-service-utils 0.1.0 → 1.1.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 BigfootDS
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 BigfootDS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,14 +4,14 @@ Reusable service-side utilities for BigfootDS microservices.
 
 This package helps services apply the same request, error, and internal-caller conventions without copying helper code into each service. It is a package, not a service, and it does not own runtime data.
 
-## First-Pass Scope
+## To-Do List
 
-- request ID generation, validation, inbound resolution, active request metadata, and response-header wiring
-- standard JSON error helpers built from the global error catalogue in `@bigfootds/bigfootds-shared-data`
-- framework-neutral bearer service-token verification and service caller policy results
-- thin Express-style adapters for request IDs, service-token verification, and standard error responses
+- [x] Morgan logging helpers
+- [x] Profanity matching/normalisation helpers.
+- [ ] Broad validation helpers
+- [ ] Audit helpers
+- [ ] Admin/operator bulk helpers
 
-Deferred areas include broad validation helpers, audit helpers, Morgan logging helpers, admin/operator bulk helpers, and profanity matching/normalisation helpers.
 
 ## Public Package Safety
 
@@ -25,6 +25,8 @@ Service-token helpers accept token values at runtime from the consuming service.
 
 ## Installation
 
+Install using the organisatio-scoped name like below: 
+
 ```sh
 npm install @bigfootds/bigfootds-service-utils
 ```
@@ -120,6 +122,48 @@ app.post(
 app.use(standardErrorHandler());
 ```
 
+## Morgan Logging
+
+Use the BigfootDS Morgan logger to emit one-line request logs similar to the current microservice convention, with request ID support added:
+
+```ts
+import {
+	createBigfootDSMorganLogger,
+	requestIdMiddleware
+} from "@bigfootds/bigfootds-service-utils";
+
+app.use(requestIdMiddleware());
+app.use(createBigfootDSMorganLogger());
+```
+
+Logging is disabled by default when `NODE_ENV` is `test`. The default format is exported as `BIGFOOTDS_MORGAN_FORMAT` if a service needs to pass it to Morgan directly.
+
+## Profanity And Restricted Words
+
+Runtime profanity handling lives here, while the static word lists and metadata stay in `@bigfootds/bigfootds-shared-data`.
+
+```ts
+import {
+	chatProfanityHandler,
+	playerNameProfanityHandler
+} from "@bigfootds/bigfootds-service-utils";
+
+const chatHasProfanity = chatProfanityHandler.exists("I like big butts and I cannot lie");
+const nameResult = playerNameProfanityHandler.check("BigfootDS_Admin");
+```
+
+Use the lower-level helpers when a service needs direct list matching or normalisation:
+
+```ts
+import {
+	findProfanityListMatches,
+	normalizeModerationText
+} from "@bigfootds/bigfootds-service-utils";
+
+const normalised = normalizeModerationText("  BigfootDS\tAdmin  ");
+const matches = findProfanityListMatches(normalised);
+```
+
 ## Package Boundary
 
 `pkg-service-utils` depends on `@bigfootds/bigfootds-shared-data` for stable Project Definitions, error-code metadata, and shared response data shapes.

package/dist/index.d.ts

@@ -2,3 +2,5 @@ export * from "./requestIds";
 export * from "./errors";
 export * from "./serviceTokens";
 export * from "./express";
+export * from "./logging";
+export * from "./profanity";

package/dist/index.js

@@ -18,3 +18,5 @@ __exportStar(require("./requestIds"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./serviceTokens"), exports);
 __exportStar(require("./express"), exports);
+__exportStar(require("./logging"), exports);
+__exportStar(require("./profanity"), exports);

package/dist/logging.d.ts

@@ -0,0 +1,53 @@
+import morgan, { type Options as MorganOptions } from "morgan";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type HeaderRecord } from "./requestIds";
+/**
+ * Morgan token name for BigfootDS request IDs.
+ */
+export declare const MORGAN_REQUEST_ID_TOKEN_NAME = "bigfootds-request-id";
+/**
+ * Single-line Morgan format for BigfootDS microservice console logs.
+ */
+export declare const BIGFOOTDS_MORGAN_FORMAT: string;
+/**
+ * Minimal request shape used by the request ID Morgan token.
+ */
+export interface MorganRequestIdSource {
+    readonly headers?: HeaderRecord;
+    readonly bigfootds?: {
+        readonly requestId?: string;
+    };
+}
+/**
+ * Options for creating the BigfootDS Morgan request logger.
+ */
+export interface BigfootDSMorganOptions<Request extends IncomingMessage, Response extends ServerResponse> extends MorganOptions<Request, Response> {
+    /**
+     * Whether to create an active Morgan logger. Defaults to disabled in `NODE_ENV=test`.
+     */
+    readonly enabled?: boolean;
+    /**
+     * Morgan format string. Defaults to the BigfootDS single-line format.
+     */
+    readonly format?: string;
+    /**
+     * Whether to register BigfootDS custom Morgan tokens before creating the logger.
+     */
+    readonly registerTokens?: boolean;
+}
+/**
+ * Returns whether request logging should be active for an environment.
+ */
+export declare function shouldLogRequests(nodeEnv?: string | undefined): boolean;
+/**
+ * Gets the request ID value used by the BigfootDS Morgan token.
+ */
+export declare function getMorganRequestIdToken(request: MorganRequestIdSource): string;
+/**
+ * Registers BigfootDS custom Morgan tokens on a Morgan-compatible instance.
+ */
+export declare function registerBigfootDSMorganTokens(morganInstance?: typeof morgan): void;
+/**
+ * Creates a Morgan request logger configured for BigfootDS microservices.
+ */
+export declare function createBigfootDSMorganLogger<Request extends IncomingMessage = IncomingMessage, Response extends ServerResponse = ServerResponse>(options?: BigfootDSMorganOptions<Request, Response>): ReturnType<typeof morgan<Request, Response>>;

package/dist/logging.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BIGFOOTDS_MORGAN_FORMAT = exports.MORGAN_REQUEST_ID_TOKEN_NAME = void 0;
+exports.shouldLogRequests = shouldLogRequests;
+exports.getMorganRequestIdToken = getMorganRequestIdToken;
+exports.registerBigfootDSMorganTokens = registerBigfootDSMorganTokens;
+exports.createBigfootDSMorganLogger = createBigfootDSMorganLogger;
+const morgan_1 = __importDefault(require("morgan"));
+const requestIds_1 = require("./requestIds");
+/**
+ * Morgan token name for BigfootDS request IDs.
+ */
+exports.MORGAN_REQUEST_ID_TOKEN_NAME = "bigfootds-request-id";
+/**
+ * Single-line Morgan format for BigfootDS microservice console logs.
+ */
+exports.BIGFOOTDS_MORGAN_FORMAT = [
+    ":date[iso]",
+    "RequestId :bigfootds-request-id,",
+    "Method :method,",
+    "URL :url,",
+    "Status :status,",
+    "ResponseBytes :res[content-length],",
+    "ResponseTime :response-time ms,",
+    "Referrer :referrer,",
+    "UserAgent :user-agent"
+].join(" ");
+/**
+ * Returns whether request logging should be active for an environment.
+ */
+function shouldLogRequests(nodeEnv = process.env.NODE_ENV) {
+    return nodeEnv !== "test";
+}
+/**
+ * Gets the request ID value used by the BigfootDS Morgan token.
+ */
+function getMorganRequestIdToken(request) {
+    return request.bigfootds?.requestId
+        ?? (0, requestIds_1.getHeaderValue)(request.headers, requestIds_1.REQUEST_ID_HEADER_NAME)
+        ?? "-";
+}
+/**
+ * Registers BigfootDS custom Morgan tokens on a Morgan-compatible instance.
+ */
+function registerBigfootDSMorganTokens(morganInstance = morgan_1.default) {
+    morganInstance.token(exports.MORGAN_REQUEST_ID_TOKEN_NAME, (request) => {
+        return getMorganRequestIdToken(request);
+    });
+}
+/**
+ * Creates a Morgan request logger configured for BigfootDS microservices.
+ */
+function createBigfootDSMorganLogger(options = {}) {
+    const { enabled = shouldLogRequests(), format = exports.BIGFOOTDS_MORGAN_FORMAT, registerTokens = true, ...morganOptions } = options;
+    if (!enabled) {
+        return ((_request, _response, next) => {
+            next();
+        });
+    }
+    if (registerTokens) {
+        registerBigfootDSMorganTokens();
+    }
+    return (0, morgan_1.default)(format, morganOptions);
+}

package/dist/profanity.d.ts

@@ -0,0 +1,164 @@
+import { CensorType } from "@2toad/profanity";
+import { type ProfanityListDefinition, type ProfanityListId } from "@bigfootds/bigfootds-shared-data";
+export { CensorType, Profanity, ProfanityOptions, profaneWords, profanity } from "@2toad/profanity";
+/**
+ * Language codes that `@2toad/profanity` supports without BigfootDS custom datasets.
+ */
+export declare const supportedProfanityLanguages: readonly ["ar", "zh", "en", "fr", "de", "hi", "it", "ja", "ko", "pt", "ru", "es"];
+/**
+ * Union of language codes supported directly by the upstream profanity package.
+ */
+export type SupportedProfanityLanguage = typeof supportedProfanityLanguages[number];
+/**
+ * Metadata for a BigfootDS localisation target and its profanity support status.
+ */
+export interface TargetProfanityLanguage {
+    readonly name: string;
+    readonly locale: string;
+    readonly profanityLanguage?: SupportedProfanityLanguage;
+    readonly supportedByDefault: boolean;
+}
+/**
+ * BigfootDS localisation targets and their current profanity-detection coverage.
+ */
+export declare const targetProfanityLanguages: readonly TargetProfanityLanguage[];
+/**
+ * Default profanity language set used when callers do not provide a language option.
+ */
+export declare const defaultProfanityLanguages: readonly SupportedProfanityLanguage[];
+/**
+ * Shared language options accepted by profanity handlers.
+ */
+export interface ProfanityLanguageOptions {
+    readonly languages?: readonly SupportedProfanityLanguage[];
+}
+/**
+ * Options for censoring chat text.
+ */
+export interface ChatCensorOptions extends ProfanityLanguageOptions {
+    readonly censorType?: CensorType;
+}
+/**
+ * Options for checking player-facing names.
+ */
+export interface PlayerNameCheckOptions extends ProfanityLanguageOptions {
+    readonly includeReservedWords?: boolean;
+    readonly includeDevWords?: boolean;
+}
+/**
+ * Detailed outcome from checking a player/user-controlled name.
+ */
+export interface PlayerNameCheckResult {
+    readonly isAllowed: boolean;
+    readonly hasProfanity: boolean;
+    readonly hasReservedWord: boolean;
+    readonly hasDevWord: boolean;
+    readonly matches: {
+        readonly reservedWords: readonly string[];
+        readonly devWords: readonly string[];
+    };
+}
+/**
+ * Unicode normalisation forms supported by JavaScript.
+ */
+export type ModerationUnicodeNormalForm = "NFC" | "NFD" | "NFKC" | "NFKD";
+/**
+ * Text normalisation options for moderation and restricted-word checks.
+ */
+export interface NormalizeModerationTextOptions {
+    readonly unicodeForm?: ModerationUnicodeNormalForm;
+    readonly trim?: boolean;
+    readonly collapseWhitespace?: boolean;
+    readonly lowerCase?: boolean;
+    readonly locale?: string | readonly string[];
+}
+/**
+ * Matching mode for static profanity/restricted-word list checks.
+ */
+export type ProfanityMatchMode = "substring" | "whole_word";
+/**
+ * Options for static profanity/restricted-word list matching.
+ */
+export interface FindProfanityListMatchesOptions {
+    readonly listIds?: readonly ProfanityListId[];
+    readonly lists?: readonly ProfanityListDefinition[];
+    readonly mode?: ProfanityMatchMode;
+    readonly normalization?: NormalizeModerationTextOptions;
+}
+/**
+ * Static profanity/restricted-word match.
+ */
+export interface ProfanityListMatch {
+    readonly listId: ProfanityListId;
+    readonly listDisplayName: string;
+    readonly word: string;
+    readonly normalizedWord: string;
+    readonly index: number;
+    readonly mode: ProfanityMatchMode;
+}
+/**
+ * Result from checking a value against static BigfootDS profanity/restricted-word lists.
+ */
+export interface ProfanityListCheckResult {
+    readonly isAllowed: boolean;
+    readonly matches: readonly ProfanityListMatch[];
+}
+/**
+ * Checks whether a string is a language code supported directly by `@2toad/profanity`.
+ */
+export declare function isSupportedProfanityLanguage(language: string): language is SupportedProfanityLanguage;
+/**
+ * Resolves an application locale to an upstream profanity language when one is available.
+ */
+export declare function getSupportedProfanityLanguageForLocale(locale: string): SupportedProfanityLanguage | undefined;
+/**
+ * Normalises text for moderation-sensitive comparisons.
+ */
+export declare function normalizeModerationText(value: string, options?: NormalizeModerationTextOptions): string;
+/**
+ * Normalises a value before comparing it with BigfootDS reserved or developer word lists.
+ */
+export declare function normalizeRestrictedWord(value: string): string;
+/**
+ * Finds BigfootDS restricted words contained within a candidate value.
+ */
+export declare function findRestrictedWords(value: string, words: readonly string[]): string[];
+/**
+ * Finds static profanity/restricted-word list matches in a candidate value.
+ */
+export declare function findProfanityListMatches(value: string, options?: FindProfanityListMatchesOptions): readonly ProfanityListMatch[];
+/**
+ * Checks whether a value has any static profanity/restricted-word list matches.
+ */
+export declare function hasProfanityListMatch(value: string, options?: FindProfanityListMatchesOptions): boolean;
+/**
+ * Returns a pass/fail result plus static list matches.
+ */
+export declare function checkProfanityList(value: string, options?: FindProfanityListMatchesOptions): ProfanityListCheckResult;
+/**
+ * Profanity-only handler for chat and other free-text surfaces.
+ */
+export declare const chatProfanityHandler: {
+    exists(text: string, options?: ProfanityLanguageOptions): boolean;
+    censor(text: string, options?: ChatCensorOptions): string;
+};
+/**
+ * Handler for player/user-controlled names.
+ */
+export declare const playerNameProfanityHandler: {
+    check(value: string, options?: PlayerNameCheckOptions): PlayerNameCheckResult;
+    isAllowed(value: string, options?: PlayerNameCheckOptions): boolean;
+};
+/**
+ * Grouped handlers for consumers that prefer context-based property access.
+ */
+export declare const ProfanityHandlers: {
+    chat: {
+        exists(text: string, options?: ProfanityLanguageOptions): boolean;
+        censor(text: string, options?: ChatCensorOptions): string;
+    };
+    playerName: {
+        check(value: string, options?: PlayerNameCheckOptions): PlayerNameCheckResult;
+        isAllowed(value: string, options?: PlayerNameCheckOptions): boolean;
+    };
+};

package/dist/profanity.js

@@ -0,0 +1,258 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProfanityHandlers = exports.playerNameProfanityHandler = exports.chatProfanityHandler = exports.defaultProfanityLanguages = exports.targetProfanityLanguages = exports.supportedProfanityLanguages = exports.profanity = exports.profaneWords = exports.ProfanityOptions = exports.Profanity = exports.CensorType = void 0;
+exports.isSupportedProfanityLanguage = isSupportedProfanityLanguage;
+exports.getSupportedProfanityLanguageForLocale = getSupportedProfanityLanguageForLocale;
+exports.normalizeModerationText = normalizeModerationText;
+exports.normalizeRestrictedWord = normalizeRestrictedWord;
+exports.findRestrictedWords = findRestrictedWords;
+exports.findProfanityListMatches = findProfanityListMatches;
+exports.hasProfanityListMatch = hasProfanityListMatch;
+exports.checkProfanityList = checkProfanityList;
+const profanity_1 = require("@2toad/profanity");
+const bigfootds_shared_data_1 = require("@bigfootds/bigfootds-shared-data");
+var profanity_2 = require("@2toad/profanity");
+Object.defineProperty(exports, "CensorType", { enumerable: true, get: function () { return profanity_2.CensorType; } });
+Object.defineProperty(exports, "Profanity", { enumerable: true, get: function () { return profanity_2.Profanity; } });
+Object.defineProperty(exports, "ProfanityOptions", { enumerable: true, get: function () { return profanity_2.ProfanityOptions; } });
+Object.defineProperty(exports, "profaneWords", { enumerable: true, get: function () { return profanity_2.profaneWords; } });
+Object.defineProperty(exports, "profanity", { enumerable: true, get: function () { return profanity_2.profanity; } });
+/**
+ * Language codes that `@2toad/profanity` supports without BigfootDS custom datasets.
+ */
+exports.supportedProfanityLanguages = [
+    "ar",
+    "zh",
+    "en",
+    "fr",
+    "de",
+    "hi",
+    "it",
+    "ja",
+    "ko",
+    "pt",
+    "ru",
+    "es"
+];
+/**
+ * BigfootDS localisation targets and their current profanity-detection coverage.
+ */
+exports.targetProfanityLanguages = [
+    { name: "English", locale: "en", profanityLanguage: "en", supportedByDefault: true },
+    { name: "French", locale: "fr", profanityLanguage: "fr", supportedByDefault: true },
+    { name: "Italian", locale: "it", profanityLanguage: "it", supportedByDefault: true },
+    { name: "German", locale: "de", profanityLanguage: "de", supportedByDefault: true },
+    { name: "Spanish", locale: "es", profanityLanguage: "es", supportedByDefault: true },
+    { name: "Portuguese", locale: "pt", profanityLanguage: "pt", supportedByDefault: true },
+    { name: "Portuguese Brazilian", locale: "pt-BR", profanityLanguage: "pt", supportedByDefault: true },
+    { name: "Dutch", locale: "nl", supportedByDefault: false },
+    { name: "Turkish", locale: "tr", supportedByDefault: false },
+    { name: "Japanese", locale: "ja", profanityLanguage: "ja", supportedByDefault: true },
+    { name: "Korean", locale: "ko", profanityLanguage: "ko", supportedByDefault: true },
+    { name: "Mandarin Chinese", locale: "zh", profanityLanguage: "zh", supportedByDefault: true },
+    { name: "Russian", locale: "ru", profanityLanguage: "ru", supportedByDefault: true },
+    { name: "Ukrainian", locale: "uk", supportedByDefault: false },
+    { name: "Malay", locale: "ms", supportedByDefault: false },
+    { name: "Indonesian", locale: "id", supportedByDefault: false },
+    { name: "Vietnamese", locale: "vi", supportedByDefault: false },
+    { name: "Tagalog", locale: "tl", supportedByDefault: false },
+    { name: "Hindi", locale: "hi", profanityLanguage: "hi", supportedByDefault: true },
+    { name: "Urdu", locale: "ur", supportedByDefault: false },
+    { name: "Bengali", locale: "bn", supportedByDefault: false },
+    { name: "Marathi", locale: "mr", supportedByDefault: false },
+    { name: "Telugu", locale: "te", supportedByDefault: false },
+    { name: "Tamil", locale: "ta", supportedByDefault: false },
+    { name: "Arabic", locale: "ar", profanityLanguage: "ar", supportedByDefault: true }
+];
+/**
+ * Default profanity language set used when callers do not provide a language option.
+ */
+exports.defaultProfanityLanguages = ["en"];
+const chatProfanity = new profanity_1.Profanity({
+    languages: [...exports.defaultProfanityLanguages],
+    wholeWord: true,
+    unicodeWordBoundaries: true
+});
+const playerNameProfanity = new profanity_1.Profanity({
+    languages: [...exports.defaultProfanityLanguages],
+    wholeWord: false,
+    unicodeWordBoundaries: true
+});
+/**
+ * Checks whether a string is a language code supported directly by `@2toad/profanity`.
+ */
+function isSupportedProfanityLanguage(language) {
+    return exports.supportedProfanityLanguages.includes(language);
+}
+/**
+ * Resolves an application locale to an upstream profanity language when one is available.
+ */
+function getSupportedProfanityLanguageForLocale(locale) {
+    const normalizedLocale = locale.trim().toLowerCase();
+    const exactMatch = exports.targetProfanityLanguages.find((language) => language.locale.toLowerCase() === normalizedLocale);
+    if (exactMatch) {
+        return exactMatch.profanityLanguage;
+    }
+    const baseLocale = normalizedLocale.split("-")[0];
+    if (isSupportedProfanityLanguage(baseLocale)) {
+        return baseLocale;
+    }
+    return undefined;
+}
+/**
+ * Normalises text for moderation-sensitive comparisons.
+ */
+function normalizeModerationText(value, options = {}) {
+    const { unicodeForm = "NFKC", trim = true, collapseWhitespace = true, lowerCase = true, locale } = options;
+    let normalized = value.normalize(unicodeForm);
+    if (trim) {
+        normalized = normalized.trim();
+    }
+    if (collapseWhitespace) {
+        normalized = normalized.replace(/\s+/g, " ");
+    }
+    if (lowerCase) {
+        normalized = normalized.toLocaleLowerCase(locale);
+    }
+    return normalized;
+}
+/**
+ * Normalises a value before comparing it with BigfootDS reserved or developer word lists.
+ */
+function normalizeRestrictedWord(value) {
+    return value.normalize("NFKC").trim().toLowerCase();
+}
+/**
+ * Finds BigfootDS restricted words contained within a candidate value.
+ */
+function findRestrictedWords(value, words) {
+    const normalizedValue = normalizeRestrictedWord(value);
+    if (!normalizedValue) {
+        return [];
+    }
+    return words.filter((word) => {
+        const normalizedWord = normalizeRestrictedWord(word);
+        return normalizedWord.length > 0 && normalizedValue.includes(normalizedWord);
+    });
+}
+/**
+ * Finds static profanity/restricted-word list matches in a candidate value.
+ */
+function findProfanityListMatches(value, options = {}) {
+    const normalizedValue = normalizeModerationText(value, options.normalization);
+    if (normalizedValue === "") {
+        return [];
+    }
+    const lists = resolveProfanityLists(options);
+    const matches = [];
+    for (const list of lists) {
+        const mode = options.mode ?? resolveDefaultMatchMode(list);
+        for (const word of list.words) {
+            const normalizedWord = normalizeModerationText(word, options.normalization);
+            if (normalizedWord === "") {
+                continue;
+            }
+            const index = mode === "whole_word"
+                ? findWholeWordIndex(normalizedValue, normalizedWord)
+                : normalizedValue.indexOf(normalizedWord);
+            if (index >= 0) {
+                matches.push({
+                    listId: list.id,
+                    listDisplayName: list.displayName,
+                    word,
+                    normalizedWord,
+                    index,
+                    mode
+                });
+            }
+        }
+    }
+    return matches;
+}
+/**
+ * Checks whether a value has any static profanity/restricted-word list matches.
+ */
+function hasProfanityListMatch(value, options = {}) {
+    return findProfanityListMatches(value, options).length > 0;
+}
+/**
+ * Returns a pass/fail result plus static list matches.
+ */
+function checkProfanityList(value, options = {}) {
+    const matches = findProfanityListMatches(value, options);
+    return {
+        isAllowed: matches.length === 0,
+        matches
+    };
+}
+/**
+ * Profanity-only handler for chat and other free-text surfaces.
+ */
+exports.chatProfanityHandler = {
+    exists(text, options = {}) {
+        return chatProfanity.exists(text, resolveLanguages(options.languages));
+    },
+    censor(text, options = {}) {
+        return chatProfanity.censor(text, options.censorType ?? profanity_1.CensorType.Word, resolveLanguages(options.languages));
+    }
+};
+/**
+ * Handler for player/user-controlled names.
+ */
+exports.playerNameProfanityHandler = {
+    check(value, options = {}) {
+        const hasProfanity = playerNameProfanity.exists(value, resolveLanguages(options.languages));
+        const reservedWords = options.includeReservedWords === false
+            ? []
+            : findRestrictedWords(value, bigfootds_shared_data_1.reservedWordsArray);
+        const devWords = options.includeDevWords === false
+            ? []
+            : findRestrictedWords(value, bigfootds_shared_data_1.devWordsArray);
+        return {
+            isAllowed: !hasProfanity && reservedWords.length === 0 && devWords.length === 0,
+            hasProfanity,
+            hasReservedWord: reservedWords.length > 0,
+            hasDevWord: devWords.length > 0,
+            matches: {
+                reservedWords,
+                devWords
+            }
+        };
+    },
+    isAllowed(value, options = {}) {
+        return exports.playerNameProfanityHandler.check(value, options).isAllowed;
+    }
+};
+/**
+ * Grouped handlers for consumers that prefer context-based property access.
+ */
+exports.ProfanityHandlers = {
+    chat: exports.chatProfanityHandler,
+    playerName: exports.playerNameProfanityHandler
+};
+function resolveLanguages(languages) {
+    return languages ? [...languages] : undefined;
+}
+function resolveProfanityLists(options) {
+    if (options.lists !== undefined) {
+        return options.lists;
+    }
+    if (options.listIds !== undefined) {
+        return options.listIds.map((listId) => bigfootds_shared_data_1.PROFANITY_LISTS_BY_ID[listId]);
+    }
+    return bigfootds_shared_data_1.PROFANITY_LISTS;
+}
+function resolveDefaultMatchMode(list) {
+    return list.matchingDefault === "substring_for_names" ? "substring" : "substring";
+}
+function findWholeWordIndex(value, word) {
+    const pattern = new RegExp(`(^|[^\\p{L}\\p{N}_])(${escapeRegExp(word)})(?=$|[^\\p{L}\\p{N}_])`, "u");
+    const match = pattern.exec(value);
+    if (match === null) {
+        return -1;
+    }
+    return match.index + (match[1]?.length ?? 0);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigfootds/bigfootds-service-utils",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "Reusable service-side utilities for BigfootDS microservices.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,6 +33,16 @@
       "require": "./dist/express.js",
       "default": "./dist/express.js"
     },
+    "./logging": {
+      "types": "./dist/logging.d.ts",
+      "require": "./dist/logging.js",
+      "default": "./dist/logging.js"
+    },
+    "./profanity": {
+      "types": "./dist/profanity.d.ts",
+      "require": "./dist/profanity.js",
+      "default": "./dist/profanity.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -53,9 +63,12 @@
   },
   "homepage": "https://github.com/BigfootDS/pkg-service-utils#readme",
   "dependencies": {
-    "@bigfootds/bigfootds-shared-data": "^2.1.0"
+    "@2toad/profanity": "^3.3.0",
+    "@bigfootds/bigfootds-shared-data": "^3.0.0",
+    "morgan": "^1.11.0"
   },
   "devDependencies": {
+    "@types/morgan": "^1.9.10",
     "@types/node": "^25.9.2",
     "typescript": "^6.0.3"
   }