@embrace-io/react-native/lib/src/api/log.js

A React Native wrapper for the Embrace SDK

"use strict";
/**
 * Log API
 *
 * Provides methods for sending log messages to the Embrace backend. Unlike breadcrumbs,
 * log messages trigger an immediate network request and can be used for real-time alerting.
 * Use logs sparingly to avoid impacting app performance or battery life.
 *
 * @see {@link https://embrace.io/docs/react-native/integration/log-message-api | Log Message API Documentation}
 */
Object.defineProperty(exports, "__esModule", { value: true });
exports.logMessage = exports.logHandledError = exports.logError = exports.logWarning = exports.logInfo = void 0;
const promiseHandler_1 = require("../utils/promiseHandler");
const log_1 = require("../utils/log");
const EmbraceManagerModule_1 = require("../EmbraceManagerModule");
/**
 * Logs a message with the specified severity, optional properties, and optional stack trace.
 *
 * This is the most flexible logging method. For convenience, prefer using
 * {@link logInfo}, {@link logWarning}, or {@link logError} for common cases.
 *
 * @param message - The log message string. Keep this short yet informative.
 * @param severity - The severity level: `"info"`, `"warning"`, or `"error"`. Defaults to `"error"`.
 * @param properties - Optional key-value pairs for categorizing and filtering logs in the dashboard.
 * @param includeStacktrace - Whether to capture and attach a stack trace. Defaults to `true`.
 *   Note: stack traces are never included for `"info"` severity regardless of this setting.
 * @returns A promise that resolves to `true` if the log was successfully sent, `false` otherwise
 *
 * @example
 * ```typescript
 * import { logMessage } from '@embrace-io/react-native';
 *
 * logMessage('Loading not finished in time.', 'error', {
 *   screen: 'checkout',
 *   itemCount: '5',
 * });
 * ```
 */
const logMessage = (message, severity = "error", 
// Android Native method is handling the null case
// iOS Native method is waiting for a non-nullable object
properties = {}, includeStacktrace = true) => {
    const stackTrace = 
    // `"info"` are not supposed to send stack traces
    // this is also restricted in the Native layers
    includeStacktrace && severity !== "info" ? (0, log_1.generateStackTrace)() : "";
    if (properties === null) {
        console.warn("[Embrace] `properties` is null. It should be an object of type `Properties`. Native layer will ignore this value.");
    }
    return (0, promiseHandler_1.safePromise)(EmbraceManagerModule_1.EmbraceManagerModule.logMessageWithSeverityAndProperties(message, severity, properties, stackTrace, includeStacktrace), "logMessage", false);
};
exports.logMessage = logMessage;
/**
 * Logs an informational message.
 *
 * Info-level logs never include stack traces.
 *
 * @param message - The informational message to log
 * @returns A promise that resolves to `true` if the log was successfully sent, `false` otherwise
 *
 * @example
 * ```typescript
 * import { logInfo } from '@embrace-io/react-native';
 *
 * logInfo('User completed onboarding flow');
 * ```
 */
const logInfo = (message) => {
    // `"info"` logs are not supposed to send stack traces as per Product decision
    // this is also restricted in the Native layers
    return logMessage(message, "info", undefined, false);
};
exports.logInfo = logInfo;
/**
 * Logs a warning message with an optional stack trace.
 *
 * @param message - The warning message to log
 * @param includeStacktrace - Whether to capture and attach a stack trace. Defaults to `true`.
 * @returns A promise that resolves to `true` if the log was successfully sent, `false` otherwise
 *
 * @example
 * ```typescript
 * import { logWarning } from '@embrace-io/react-native';
 *
 * logWarning('API response took longer than expected');
 * ```
 */
const logWarning = (message, includeStacktrace = true) => {
    return logMessage(message, "warning", undefined, includeStacktrace);
};
exports.logWarning = logWarning;
/**
 * Logs an error message with an optional stack trace.
 *
 * @param message - The error message to log
 * @param includeStacktrace - Whether to capture and attach a stack trace. Defaults to `true`.
 * @returns A promise that resolves to `true` if the log was successfully sent, `false` otherwise
 *
 * @example
 * ```typescript
 * import { logError } from '@embrace-io/react-native';
 *
 * logError('Failed to load user profile');
 * ```
 */
const logError = (message, includeStacktrace = true) => {
    return logMessage(message, "error", undefined, includeStacktrace);
};
exports.logError = logError;
/**
 * Logs a handled error (caught exception) along with its stack trace.
 *
 * Use this to report errors that your app caught and handled gracefully but that
 * you still want visibility into. The full stack trace from the Error object is
 * automatically included.
 *
 * @param error - The caught Error object to log. Must be an instance of Error.
 * @param properties - Optional key-value pairs for additional context
 * @returns A promise that resolves to `true` if the error was logged, `false` if the
 *   argument was not an Error instance or the log failed
 *
 * @example
 * ```typescript
 * import { logHandledError } from '@embrace-io/react-native';
 *
 * try {
 *   await riskyOperation();
 * } catch (error) {
 *   logHandledError(error, { operation: 'riskyOperation' });
 * }
 * ```
 */
const logHandledError = (error, properties = {}) => {
    if (error instanceof Error) {
        const { stack, message } = error;
        return (0, promiseHandler_1.safePromise)(EmbraceManagerModule_1.EmbraceManagerModule.logHandledError(message, stack, properties), "logHandledError", false);
    }
    return Promise.resolve(false);
};
exports.logHandledError = logHandledError;