@natyapp/meta 1.6.7 → 1.7.0

package/dist/utils/methodContext.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Utility for generating consistent method context strings for logging.
+ *
+ * @module methodContext
+ * @example
+ * ```typescript
+ * import { getMethodContext } from '../utils';
+ *
+ * logger.info("Operation started", {
+ *   operation: getMethodContext("WhatsappResponse", "send_text_message"),
+ *   // ... other metadata
+ * });
+ * // Logs: operation: "WhatsappResponse.send_text_message"
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMethodContext = void 0;
+/**
+ * Generates a standardized method context string for logging.
+ *
+ * @param className - The name of the class or module (e.g., "WhatsappResponse", "Webhooks")
+ * @param methodName - The name of the method (e.g., "send_text_message", "getSingle")
+ * @returns A formatted string in the format "ClassName.methodName"
+ *
+ * @throws {Error} If className or methodName is empty or whitespace-only
+ *
+ * @example
+ * ```typescript
+ * getMethodContext("WhatsappResponse", "send_text_message")
+ * // Returns: "WhatsappResponse.send_text_message"
+ *
+ * getMethodContext("Webhooks", "getSingle")
+ * // Returns: "Webhooks.getSingle"
+ * ```
+ */
+function getMethodContext(className, methodName) {
+    const trimmedClass = className === null || className === void 0 ? void 0 : className.trim();
+    const trimmedMethod = methodName === null || methodName === void 0 ? void 0 : methodName.trim();
+    if (!trimmedClass) {
+        throw new Error("className cannot be empty");
+    }
+    if (!trimmedMethod) {
+        throw new Error("methodName cannot be empty");
+    }
+    return `${trimmedClass}.${trimmedMethod}`;
+}
+exports.getMethodContext = getMethodContext;

package/dist/utils/parseError.d.ts

@@ -2,4 +2,16 @@ export declare const parseError: (err: any, fallbackMessage?: string) => {
     message: string;
     code: any;
 };
+/**
+ * Returns a parsed error as Either monad instead of throwing.
+ * Use this for functional error handling following SDK architecture.
+ * @param err - The error to parse
+ * @param contextMessage - Optional context to prepend to error message
+ * @returns Either with Error instance (not ErrorHandling)
+ */
+export declare const returnParsedError: (err: any, contextMessage?: string) => import("../errors/Either").isError<Error>;
+/**
+ * @deprecated Use returnParsedError instead to follow Either pattern.
+ * This function throws exceptions which violates SDK architecture.
+ */
 export declare const throwParsedError: (err: any, contextMessage?: string) => never;

package/dist/utils/parseError.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.throwParsedError = exports.parseError = void 0;
-const Errors_1 = require("../Errors");
+exports.throwParsedError = exports.returnParsedError = exports.parseError = void 0;
+const Either_1 = require("../errors/Either");
 const parseError = (err, fallbackMessage = "Erro inesperado") => {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
     const details = ((_d = (_c = (_b = (_a = err === null || err === void 0 ? void 0 : err.response) === null || _a === void 0 ? void 0 : _a.data) === null || _b === void 0 ? void 0 : _b.error) === null || _c === void 0 ? void 0 : _c.error_data) === null || _d === void 0 ? void 0 : _d.details) ||
@@ -19,8 +19,32 @@ const parseError = (err, fallbackMessage = "Erro inesperado") => {
     };
 };
 exports.parseError = parseError;
+/**
+ * Returns a parsed error as Either monad instead of throwing.
+ * Use this for functional error handling following SDK architecture.
+ * @param err - The error to parse
+ * @param contextMessage - Optional context to prepend to error message
+ * @returns Either with Error instance (not ErrorHandling)
+ */
+const returnParsedError = (err, contextMessage) => {
+    const { message, code } = (0, exports.parseError)(err);
+    const errorMsg = `${contextMessage ? contextMessage + ": " : ""}${message}`;
+    const error = new Error(errorMsg);
+    error.code = code; // Attach code as property
+    return (0, Either_1.throwError)(error);
+};
+exports.returnParsedError = returnParsedError;
+/**
+ * @deprecated Use returnParsedError instead to follow Either pattern.
+ * This function throws exceptions which violates SDK architecture.
+ */
 const throwParsedError = (err, contextMessage) => {
+    if (process.env.NODE_ENV !== "production") {
+        console.warn("[DEPRECATED] throwParsedError is deprecated. Use returnParsedError instead to follow Either pattern.");
+    }
     const { message, code } = (0, exports.parseError)(err);
-    throw (0, Errors_1.ErrorHandling)(`${contextMessage ? contextMessage + ": " : ""}${message}`, code);
+    const error = new Error(`${contextMessage ? contextMessage + ": " : ""}${message}`);
+    error.code = code;
+    throw error;
 };
 exports.throwParsedError = throwParsedError;

package/dist/utils/pinoAdapter.d.ts

@@ -0,0 +1,30 @@
+import type { ILogger } from "../interfaces/ILogger";
+/**
+ * Pino logger adapter
+ *
+ * Adapts a Pino logger instance to work with the SDK's ILogger interface.
+ * Note: Pino uses a different parameter order (meta, message) vs our interface (message, meta).
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino';
+ * import { createPinoAdapter } from '@natyapp/meta/utils/pinoAdapter';
+ * import NatyMeta from '@natyapp/meta';
+ *
+ * const pinoLogger = pino({
+ *   level: 'debug',
+ *   transport: {
+ *     target: 'pino-pretty',
+ *     options: { colorize: true }
+ *   }
+ * });
+ *
+ * const sdk = new NatyMeta({
+ *   logger: createPinoAdapter(pinoLogger)
+ * });
+ * ```
+ *
+ * @param pinoLogger - A Pino logger instance
+ * @returns An ILogger-compatible adapter
+ */
+export declare function createPinoAdapter(pinoLogger: any): ILogger;

package/dist/utils/pinoAdapter.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPinoAdapter = void 0;
+/**
+ * Pino logger adapter
+ *
+ * Adapts a Pino logger instance to work with the SDK's ILogger interface.
+ * Note: Pino uses a different parameter order (meta, message) vs our interface (message, meta).
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino';
+ * import { createPinoAdapter } from '@natyapp/meta/utils/pinoAdapter';
+ * import NatyMeta from '@natyapp/meta';
+ *
+ * const pinoLogger = pino({
+ *   level: 'debug',
+ *   transport: {
+ *     target: 'pino-pretty',
+ *     options: { colorize: true }
+ *   }
+ * });
+ *
+ * const sdk = new NatyMeta({
+ *   logger: createPinoAdapter(pinoLogger)
+ * });
+ * ```
+ *
+ * @param pinoLogger - A Pino logger instance
+ * @returns An ILogger-compatible adapter
+ */
+function createPinoAdapter(pinoLogger) {
+    return {
+        debug(message, meta) {
+            if (meta) {
+                pinoLogger.debug(meta, message);
+            }
+            else {
+                pinoLogger.debug(message);
+            }
+        },
+        info(message, meta) {
+            if (meta) {
+                pinoLogger.info(meta, message);
+            }
+            else {
+                pinoLogger.info(message);
+            }
+        },
+        warn(message, meta) {
+            if (meta) {
+                pinoLogger.warn(meta, message);
+            }
+            else {
+                pinoLogger.warn(message);
+            }
+        },
+        error(message, meta) {
+            if (meta) {
+                pinoLogger.error(meta, message);
+            }
+            else {
+                pinoLogger.error(message);
+            }
+        },
+    };
+}
+exports.createPinoAdapter = createPinoAdapter;

package/dist/utils/sanitize.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Utilities for sanitizing sensitive data in logs
+ */
+/**
+ * Sanitize phone number by masking the last 4 digits
+ * @param phoneNumber - Phone number in E.164 format (e.g., +5511987654321)
+ * @returns Masked phone number (e.g., +5511***4321)
+ *
+ * @example
+ * sanitizePhoneNumber("+5511987654321") // Returns: "+5511***4321"
+ * sanitizePhoneNumber("+1234567890") // Returns: "+123456***7890"
+ */
+export declare function sanitizePhoneNumber(phoneNumber: string | undefined | null): string;
+/**
+ * Sanitize access token by replacing with placeholder
+ * @param token - Access token or credential
+ * @returns Sanitized placeholder
+ */
+export declare function sanitizeToken(token: string | undefined | null): string;
+/**
+ * Sanitize metadata object by masking sensitive fields
+ * @param metadata - Metadata object to sanitize
+ * @param sensitiveFields - Array of field names to sanitize (default: common sensitive fields)
+ * @returns Sanitized metadata object
+ *
+ * @example
+ * sanitizeMetadata({
+ *   phone: "+5511987654321",
+ *   token: "abc123",
+ *   name: "John"
+ * })
+ * // Returns: { phone: "+5511***4321", token: "[REDACTED]", name: "John" }
+ */
+export declare function sanitizeMetadata(metadata: Record<string, any> | undefined | null, sensitiveFields?: string[]): Record<string, any>;
+/**
+ * Sanitize message body content for logging
+ * Returns type and size instead of actual content
+ */
+export declare function sanitizeMessageBody(body: string | undefined | null): {
+    type: string;
+    size: number;
+};

package/dist/utils/sanitize.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Utilities for sanitizing sensitive data in logs
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeMessageBody = exports.sanitizeMetadata = exports.sanitizeToken = exports.sanitizePhoneNumber = void 0;
+/**
+ * Sanitize phone number by masking the last 4 digits
+ * @param phoneNumber - Phone number in E.164 format (e.g., +5511987654321)
+ * @returns Masked phone number (e.g., +5511***4321)
+ *
+ * @example
+ * sanitizePhoneNumber("+5511987654321") // Returns: "+5511***4321"
+ * sanitizePhoneNumber("+1234567890") // Returns: "+123456***7890"
+ */
+function sanitizePhoneNumber(phoneNumber) {
+    if (!phoneNumber)
+        return "[NO_PHONE]";
+    // Remove non-digit characters except leading +
+    const cleaned = phoneNumber.toString().trim();
+    if (cleaned.length < 8) {
+        // Too short to mask meaningfully
+        return "***" + cleaned.slice(-2);
+    }
+    // Keep country code and first digits, mask middle, show last 4
+    const lastFour = cleaned.slice(-4);
+    const prefix = cleaned.slice(0, -7); // Keep country code + area
+    return `${prefix}***${lastFour}`;
+}
+exports.sanitizePhoneNumber = sanitizePhoneNumber;
+/**
+ * Sanitize access token by replacing with placeholder
+ * @param token - Access token or credential
+ * @returns Sanitized placeholder
+ */
+function sanitizeToken(token) {
+    if (!token)
+        return "[NO_TOKEN]";
+    return "[REDACTED]";
+}
+exports.sanitizeToken = sanitizeToken;
+/**
+ * Sanitize metadata object by masking sensitive fields
+ * @param metadata - Metadata object to sanitize
+ * @param sensitiveFields - Array of field names to sanitize (default: common sensitive fields)
+ * @returns Sanitized metadata object
+ *
+ * @example
+ * sanitizeMetadata({
+ *   phone: "+5511987654321",
+ *   token: "abc123",
+ *   name: "John"
+ * })
+ * // Returns: { phone: "+5511***4321", token: "[REDACTED]", name: "John" }
+ */
+function sanitizeMetadata(metadata, sensitiveFields = [
+    "phone",
+    "phoneNumber",
+    "phone_number",
+    "to",
+    "from",
+    "token",
+    "accessToken",
+    "access_token",
+    "systemUserAccessToken",
+    "password",
+    "secret",
+    "apiKey",
+    "api_key",
+]) {
+    if (!metadata || typeof metadata !== "object") {
+        return {};
+    }
+    const sanitized = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        const lowerKey = key.toLowerCase();
+        // Check if field should be sanitized
+        const shouldSanitize = sensitiveFields.some((field) => lowerKey.includes(field.toLowerCase()));
+        if (shouldSanitize) {
+            if (lowerKey.includes("phone") ||
+                lowerKey === "to" ||
+                lowerKey === "from") {
+                sanitized[key] = sanitizePhoneNumber(value);
+            }
+            else if (lowerKey.includes("token") ||
+                lowerKey.includes("password") ||
+                lowerKey.includes("secret") ||
+                lowerKey.includes("key")) {
+                sanitized[key] = sanitizeToken(value);
+            }
+            else {
+                sanitized[key] = "[REDACTED]";
+            }
+        }
+        else if (typeof value === "object" &&
+            value !== null &&
+            !Array.isArray(value)) {
+            // Recursively sanitize nested objects
+            sanitized[key] = sanitizeMetadata(value, sensitiveFields);
+        }
+        else {
+            sanitized[key] = value;
+        }
+    }
+    return sanitized;
+}
+exports.sanitizeMetadata = sanitizeMetadata;
+/**
+ * Sanitize message body content for logging
+ * Returns type and size instead of actual content
+ */
+function sanitizeMessageBody(body) {
+    if (!body)
+        return { type: "empty", size: 0 };
+    return {
+        type: typeof body,
+        size: body.length,
+    };
+}
+exports.sanitizeMessageBody = sanitizeMessageBody;

package/dist/utils/tryCatch.d.ts

@@ -1 +1,10 @@
-export declare const Try: (fn: any, ...args: any) => Promise<any>;
+import { Either } from "../errors/Either";
+export declare const Try: <TSuccess, TError = string>(fn: (...args: any[]) => Promise<Either<TError, TSuccess>>, ...args: any[]) => Promise<Either<TError, TSuccess>>;
+/**
+ * Synchronous version of Try wrapper for operations that throw synchronously.
+ * Catches any thrown error and converts to Either monad.
+ * @param fn - Synchronous function that may throw
+ * @param args - Arguments to pass to function
+ * @returns Either with error or success value
+ */
+export declare const TrySync: <TSuccess, TError = string>(fn: (...args: any[]) => TSuccess, ...args: any[]) => Either<TError, TSuccess>;

package/dist/utils/tryCatch.js

@@ -1,19 +1,54 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Try = void 0;
-const Either_1 = require("../Errors/Either");
-const ErrorHandling_1 = require("../Errors/ErrorHandling");
+exports.TrySync = exports.Try = void 0;
+const Either_1 = require("../errors/Either");
+const loggerContext_1 = require("./loggerContext");
+const parseError_1 = require("./parseError");
+const methodContext_1 = require("./methodContext");
 const Try = async (fn, ...args) => {
     var _a;
     try {
+        loggerContext_1.logger.debug("Try: Executing operation", {
+            operation: (0, methodContext_1.getMethodContext)("Try", fn.name || "anonymous"),
+            argsCount: args.length,
+        });
         const resolver = await fn.apply(null, args);
         if ((0, Either_1.isSuccess)(resolver))
             (0, Either_1.unwrapEither)(resolver);
         return resolver;
     }
     catch (err) {
-        const axiosError = { isError: (_a = err === null || err === void 0 ? void 0 : err.response) === null || _a === void 0 ? void 0 : _a.data };
-        return (0, ErrorHandling_1.ErrorHandling)(axiosError);
+        const errorDetails = (0, parseError_1.parseError)(err, "Operation failed");
+        loggerContext_1.logger.error("Try: Operation failed", {
+            operation: (0, methodContext_1.getMethodContext)("Try", fn.name || "anonymous"),
+            error: errorDetails.message,
+            code: errorDetails.code,
+        });
+        return (0, Either_1.throwError)(((_a = err === null || err === void 0 ? void 0 : err.response) === null || _a === void 0 ? void 0 : _a.data) || errorDetails.message);
     }
 };
 exports.Try = Try;
+/**
+ * Synchronous version of Try wrapper for operations that throw synchronously.
+ * Catches any thrown error and converts to Either monad.
+ * @param fn - Synchronous function that may throw
+ * @param args - Arguments to pass to function
+ * @returns Either with error or success value
+ */
+const TrySync = (fn, ...args) => {
+    var _a;
+    try {
+        const result = fn.apply(null, args);
+        return (0, Either_1.throwSuccess)(result);
+    }
+    catch (err) {
+        const errorDetails = (0, parseError_1.parseError)(err, "Operation failed");
+        loggerContext_1.logger.error("TrySync: Operation failed", {
+            operation: (0, methodContext_1.getMethodContext)("TrySync", fn.name || "anonymous"),
+            error: errorDetails.message,
+            code: errorDetails.code,
+        });
+        return (0, Either_1.throwError)(((_a = err === null || err === void 0 ? void 0 : err.response) === null || _a === void 0 ? void 0 : _a.data) || errorDetails.message);
+    }
+};
+exports.TrySync = TrySync;