@salesforce/b2c-tooling-sdk 0.2.0 → 0.3.0

package/dist/esm/operations/logs/index.js

@@ -0,0 +1,73 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Log operations for B2C Commerce instances.
+ *
+ * This module provides functions for listing, tailing, and analyzing log files
+ * on B2C Commerce instances via WebDAV.
+ *
+ * @module operations/logs
+ *
+ * @example
+ * List log files:
+ * ```typescript
+ * import { listLogFiles } from '@salesforce/b2c-tooling-sdk/operations/logs';
+ *
+ * const files = await listLogFiles(instance, {
+ *   prefixes: ['error', 'customerror'],
+ *   sortBy: 'date',
+ *   sortOrder: 'desc'
+ * });
+ *
+ * for (const file of files) {
+ *   console.log(`${file.name} (${file.size} bytes)`);
+ * }
+ * ```
+ *
+ * @example
+ * Tail logs in real-time:
+ * ```typescript
+ * import { tailLogs, createPathNormalizer } from '@salesforce/b2c-tooling-sdk/operations/logs';
+ *
+ * const normalizer = createPathNormalizer({ cartridgePath: './cartridges' });
+ *
+ * const { stop, done } = await tailLogs(instance, {
+ *   prefixes: ['error', 'customerror'],
+ *   pathNormalizer: normalizer,
+ *   onEntry: (entry) => {
+ *     console.log(`[${entry.file}] ${entry.level}: ${entry.message}`);
+ *   },
+ *   onError: (err) => console.error('Error:', err),
+ * });
+ *
+ * // Stop after 30 seconds
+ * setTimeout(() => stop(), 30000);
+ *
+ * await done;
+ * ```
+ *
+ * @example
+ * Get recent logs (one-shot):
+ * ```typescript
+ * import { getRecentLogs } from '@salesforce/b2c-tooling-sdk/operations/logs';
+ *
+ * const entries = await getRecentLogs(instance, {
+ *   prefixes: ['error'],
+ *   maxEntries: 50
+ * });
+ *
+ * for (const entry of entries) {
+ *   console.log(`[${entry.timestamp}] ${entry.message}`);
+ * }
+ * ```
+ */
+// List operations
+export { extractPrefix, listLogFiles } from './list.js';
+// Tail operations
+export { aggregateLogEntries, getRecentLogs, parseLogEntry, splitLines, tailLogs } from './tail.js';
+// Path normalization
+export { createPathNormalizer, discoverAndCreateNormalizer, extractPaths, } from './path-normalizer.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/operations/logs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/operations/logs/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAaH,kBAAkB;AAClB,OAAO,EAAC,aAAa,EAAE,YAAY,EAAC,MAAM,WAAW,CAAC;AAEtD,kBAAkB;AAClB,OAAO,EAAC,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAC,MAAM,WAAW,CAAC;AAElG,qBAAqB;AACrB,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,YAAY,GAEb,MAAM,sBAAsB,CAAC"}

package/dist/esm/operations/logs/list.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Log file listing operations.
+ */
+import type { B2CInstance } from '../../instance/index.js';
+import type { ListLogsOptions, LogFile } from './types.js';
+/**
+ * Extracts the log prefix from a filename.
+ *
+ * @param filename - Log file name (e.g., "error-blade1-20250125.log")
+ * @returns The prefix (e.g., "error") or "unknown"
+ *
+ * @example
+ * extractPrefix("error-blade1-20250125.log") // "error"
+ * extractPrefix("customerror-blade1-20250125.log") // "customerror"
+ * extractPrefix("custom-mylog-blade1-20250125.log") // "custom-mylog"
+ */
+export declare function extractPrefix(filename: string): string;
+/**
+ * Lists log files on a B2C Commerce instance.
+ *
+ * @param instance - B2C instance to list logs from
+ * @param options - Listing options (filters, sorting)
+ * @returns Array of log files
+ *
+ * @example
+ * ```typescript
+ * // List all error and customerror logs
+ * const logs = await listLogFiles(instance, {
+ *   prefixes: ['error', 'customerror'],
+ *   sortBy: 'date',
+ *   sortOrder: 'desc'
+ * });
+ * ```
+ */
+export declare function listLogFiles(instance: B2CInstance, options?: ListLogsOptions): Promise<LogFile[]>;

package/dist/esm/operations/logs/list.js

@@ -0,0 +1,144 @@
+import { getLogger } from '../../logging/logger.js';
+/**
+ * Known log file prefixes in B2C Commerce.
+ * Used to extract the prefix from log file names.
+ */
+const LOG_PREFIXES = [
+    // Custom logs (must check first due to "custom" prefix)
+    'customdebug',
+    'custominfo',
+    'customwarn',
+    'customerror',
+    'customfatal',
+    // System logs
+    'error',
+    'warn',
+    'info',
+    'debug',
+    'fatal',
+    'api',
+    'deprecation',
+    'jobs',
+    'staging',
+    'quota',
+    'sql',
+    'service',
+    'syslog',
+    'security',
+    'analytics',
+    'migration',
+    // Custom named logs (format: custom-<name>-...)
+    'custom',
+];
+/**
+ * Extracts the log prefix from a filename.
+ *
+ * @param filename - Log file name (e.g., "error-blade1-20250125.log")
+ * @returns The prefix (e.g., "error") or "unknown"
+ *
+ * @example
+ * extractPrefix("error-blade1-20250125.log") // "error"
+ * extractPrefix("customerror-blade1-20250125.log") // "customerror"
+ * extractPrefix("custom-mylog-blade1-20250125.log") // "custom-mylog"
+ */
+export function extractPrefix(filename) {
+    // Handle custom-<name> pattern (e.g., custom-mylog-blade1-...)
+    // Custom log names use word characters only (no dashes) to distinguish from hostname
+    const customMatch = filename.match(/^(custom-[a-zA-Z0-9_]+)-/);
+    if (customMatch) {
+        return customMatch[1];
+    }
+    // Check known prefixes (order matters - longer matches first)
+    for (const prefix of LOG_PREFIXES) {
+        if (filename.startsWith(`${prefix}-`) || filename.startsWith(`${prefix}_`)) {
+            return prefix;
+        }
+    }
+    // Fallback: extract first segment before dash or underscore
+    const match = filename.match(/^([a-zA-Z]+)[-_]/);
+    return match ? match[1] : 'unknown';
+}
+/**
+ * Lists log files on a B2C Commerce instance.
+ *
+ * @param instance - B2C instance to list logs from
+ * @param options - Listing options (filters, sorting)
+ * @returns Array of log files
+ *
+ * @example
+ * ```typescript
+ * // List all error and customerror logs
+ * const logs = await listLogFiles(instance, {
+ *   prefixes: ['error', 'customerror'],
+ *   sortBy: 'date',
+ *   sortOrder: 'desc'
+ * });
+ * ```
+ */
+export async function listLogFiles(instance, options = {}) {
+    const logger = getLogger();
+    const { prefixes, sortBy = 'date', sortOrder = 'desc' } = options;
+    logger.debug({ prefixes, sortBy, sortOrder }, 'Listing log files');
+    // Get all files from Logs directory
+    const entries = await instance.webdav.propfind('Logs', '1');
+    // Filter to only log files (not directories, not the Logs directory itself)
+    const logFiles = entries
+        .filter((entry) => {
+        // Skip directories
+        if (entry.isCollection)
+            return false;
+        // Skip if not a .log file
+        const name = entry.displayName || entry.href.split('/').pop() || '';
+        if (!name.endsWith('.log'))
+            return false;
+        return true;
+    })
+        .map((entry) => {
+        const name = entry.displayName || entry.href.split('/').pop() || '';
+        const prefix = extractPrefix(name);
+        return {
+            name,
+            prefix,
+            size: entry.contentLength || 0,
+            lastModified: entry.lastModified || new Date(0),
+            path: `Logs/${name}`,
+        };
+    });
+    // Filter by prefix if specified
+    let filtered = logFiles;
+    if (prefixes && prefixes.length > 0) {
+        const prefixSet = new Set(prefixes.map((p) => p.toLowerCase()));
+        filtered = logFiles.filter((file) => {
+            // Check exact prefix match
+            if (prefixSet.has(file.prefix.toLowerCase()))
+                return true;
+            // Also check if the prefix starts with any of the specified prefixes
+            // This handles cases like "custom-mylog" matching "custom"
+            for (const p of prefixSet) {
+                if (file.prefix.toLowerCase().startsWith(p))
+                    return true;
+            }
+            return false;
+        });
+    }
+    // Sort the results
+    filtered.sort((a, b) => {
+        let comparison = 0;
+        switch (sortBy) {
+            case 'name':
+                comparison = a.name.localeCompare(b.name);
+                break;
+            case 'size':
+                comparison = a.size - b.size;
+                break;
+            case 'date':
+            default:
+                comparison = a.lastModified.getTime() - b.lastModified.getTime();
+                break;
+        }
+        return sortOrder === 'desc' ? -comparison : comparison;
+    });
+    logger.debug({ count: filtered.length }, `Found ${filtered.length} log files`);
+    return filtered;
+}
+//# sourceMappingURL=list.js.map

package/dist/esm/operations/logs/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../../src/operations/logs/list.ts"],"names":[],"mappings":"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"}

package/dist/esm/operations/logs/path-normalizer.d.ts

@@ -0,0 +1,82 @@
+import { type CartridgeMapping } from '../code/cartridges.js';
+/**
+ * Options for creating a path normalizer.
+ */
+export interface PathNormalizerOptions {
+    /**
+     * Local path to the cartridges directory (simple mode).
+     * All cartridge references will be prefixed with this path.
+     * @example "./cartridges" or "/Users/dev/project/cartridges"
+     */
+    cartridgePath?: string;
+    /**
+     * Discovered cartridge mappings (precise mode).
+     * Each cartridge is mapped to its actual local path.
+     * Takes precedence over cartridgePath for known cartridges.
+     */
+    cartridges?: CartridgeMapping[];
+}
+/**
+ * Creates a path normalizer function for converting remote cartridge paths
+ * to local paths in log messages.
+ *
+ * Supports two modes:
+ * 1. **Cartridge mappings** (precise): Uses discovered cartridges to map each
+ *    cartridge name to its actual local path. Best for projects with cartridges
+ *    in different locations.
+ * 2. **Cartridge path** (simple): Prefixes all paths with a base directory.
+ *    Best when all cartridges are in a single directory.
+ *
+ * @param options - Normalizer options
+ * @returns Function that normalizes paths in a message string, or undefined if no options provided
+ *
+ * @example
+ * ```typescript
+ * // Using discovered cartridges (recommended)
+ * const cartridges = findCartridges('./my-project');
+ * const normalize = createPathNormalizer({ cartridges });
+ *
+ * // Using simple cartridge path
+ * const normalize = createPathNormalizer({ cartridgePath: './cartridges' });
+ *
+ * // Input: "(app_storefront/cartridge/controllers/Home.js:45)"
+ * // Output: "(./cartridges/app_storefront/cartridge/controllers/Home.js:45)"
+ * const normalized = normalize(logMessage);
+ * ```
+ */
+export declare function createPathNormalizer(options: PathNormalizerOptions): ((message: string) => string) | undefined;
+/**
+ * Discovers cartridges and creates a path normalizer automatically.
+ *
+ * This is a convenience function that combines `findCartridges` with
+ * `createPathNormalizer` for easy setup. Cartridge paths are converted
+ * to relative paths from the current working directory.
+ *
+ * @param directory - Directory to search for cartridges (defaults to cwd)
+ * @returns Path normalizer function, or undefined if no cartridges found
+ *
+ * @example
+ * ```typescript
+ * // Auto-discover cartridges from current directory
+ * const normalize = discoverAndCreateNormalizer();
+ *
+ * // Auto-discover from specific directory
+ * const normalize = discoverAndCreateNormalizer('./my-project');
+ * ```
+ */
+export declare function discoverAndCreateNormalizer(directory?: string): ((message: string) => string) | undefined;
+/**
+ * Extracts all cartridge paths from a message.
+ *
+ * Useful for testing or analysis of log messages.
+ *
+ * @param message - Log message to extract paths from
+ * @returns Array of extracted paths
+ *
+ * @example
+ * ```typescript
+ * const paths = extractPaths("Error at (app_storefront/cartridge/controllers/Home.js:45)");
+ * // Returns: ["app_storefront/cartridge/controllers/Home.js:45"]
+ * ```
+ */
+export declare function extractPaths(message: string): string[];

package/dist/esm/operations/logs/path-normalizer.js

@@ -0,0 +1,190 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Path normalization for B2C Commerce log files.
+ *
+ * Converts remote cartridge paths in log messages to local paths
+ * for IDE click-to-open functionality.
+ */
+import path from 'node:path';
+import { findCartridges } from '../code/cartridges.js';
+/**
+ * Patterns for matching cartridge paths in various contexts.
+ *
+ * B2C Commerce log files can contain paths in various formats:
+ * - In parentheses: (app_storefront/cartridge/controllers/Home.js:45)
+ * - In quotes: 'app_storefront/cartridge/controllers/Home.js:45'
+ * - In stack traces: at app_storefront/cartridge/controllers/Home.js:45
+ * - Plain paths: app_storefront/cartridge/controllers/Home.js:45
+ */
+const PATH_PATTERNS = [
+    // Parentheses: (cartridge_name/cartridge/path/file.js:line)
+    {
+        pattern: /\(([a-zA-Z0-9_-]+\/cartridge\/[^)]+)\)/g,
+        context: 'parentheses',
+        extractPath: (match) => match[1],
+        buildReplacement: (match, normalizedPath) => `(${normalizedPath})`,
+    },
+    // Single quotes: 'cartridge_name/cartridge/path/file.js:line'
+    {
+        pattern: /'([a-zA-Z0-9_-]+\/cartridge\/[^']+)'/g,
+        context: 'quotes',
+        extractPath: (match) => match[1],
+        buildReplacement: (match, normalizedPath) => `'${normalizedPath}'`,
+    },
+    // Double quotes: "cartridge_name/cartridge/path/file.js:line"
+    {
+        pattern: /"([a-zA-Z0-9_-]+\/cartridge\/[^"]+)"/g,
+        context: 'quotes',
+        extractPath: (match) => match[1],
+        buildReplacement: (match, normalizedPath) => `"${normalizedPath}"`,
+    },
+    // Stack trace: at cartridge_name/cartridge/path/file.js:line
+    {
+        pattern: /at\s+([a-zA-Z0-9_-]+\/cartridge\/[^\s]+)/g,
+        context: 'stacktrace',
+        extractPath: (match) => match[1],
+        buildReplacement: (match, normalizedPath) => `at ${normalizedPath}`,
+    },
+];
+/**
+ * Creates a path normalizer function for converting remote cartridge paths
+ * to local paths in log messages.
+ *
+ * Supports two modes:
+ * 1. **Cartridge mappings** (precise): Uses discovered cartridges to map each
+ *    cartridge name to its actual local path. Best for projects with cartridges
+ *    in different locations.
+ * 2. **Cartridge path** (simple): Prefixes all paths with a base directory.
+ *    Best when all cartridges are in a single directory.
+ *
+ * @param options - Normalizer options
+ * @returns Function that normalizes paths in a message string, or undefined if no options provided
+ *
+ * @example
+ * ```typescript
+ * // Using discovered cartridges (recommended)
+ * const cartridges = findCartridges('./my-project');
+ * const normalize = createPathNormalizer({ cartridges });
+ *
+ * // Using simple cartridge path
+ * const normalize = createPathNormalizer({ cartridgePath: './cartridges' });
+ *
+ * // Input: "(app_storefront/cartridge/controllers/Home.js:45)"
+ * // Output: "(./cartridges/app_storefront/cartridge/controllers/Home.js:45)"
+ * const normalized = normalize(logMessage);
+ * ```
+ */
+export function createPathNormalizer(options) {
+    const { cartridgePath, cartridges } = options;
+    // If no options provided, return undefined
+    if (!cartridgePath && (!cartridges || cartridges.length === 0)) {
+        return undefined;
+    }
+    // Build a map of cartridge names to their local paths
+    const cartridgeMap = new Map();
+    if (cartridges) {
+        for (const c of cartridges) {
+            cartridgeMap.set(c.name, c.src);
+        }
+    }
+    // Normalize the fallback cartridge path (remove trailing slash)
+    const normalizedCartridgePath = cartridgePath?.replace(/\/+$/, '');
+    return (message) => {
+        let result = message;
+        for (const { pattern, extractPath, buildReplacement } of PATH_PATTERNS) {
+            // Create a fresh regex for each message (stateful with /g flag)
+            const regex = new RegExp(pattern.source, pattern.flags);
+            result = result.replace(regex, (...args) => {
+                // The full match is the first arg, captured groups follow
+                const match = args;
+                const remotePath = extractPath(match);
+                // Extract cartridge name from the path (first segment before /cartridge/)
+                const cartridgeName = remotePath.split('/')[0];
+                const restOfPath = remotePath.substring(cartridgeName.length);
+                // Try to find the cartridge in our mappings
+                const localCartridgePath = cartridgeMap.get(cartridgeName);
+                let localPath;
+                if (localCartridgePath) {
+                    // Use the discovered cartridge's actual path
+                    localPath = `${localCartridgePath}${restOfPath}`;
+                }
+                else if (normalizedCartridgePath) {
+                    // Fall back to simple prefix mode
+                    localPath = `${normalizedCartridgePath}/${remotePath}`;
+                }
+                else {
+                    // No mapping and no fallback - return original
+                    return match[0];
+                }
+                return buildReplacement(match, localPath);
+            });
+        }
+        return result;
+    };
+}
+/**
+ * Discovers cartridges and creates a path normalizer automatically.
+ *
+ * This is a convenience function that combines `findCartridges` with
+ * `createPathNormalizer` for easy setup. Cartridge paths are converted
+ * to relative paths from the current working directory.
+ *
+ * @param directory - Directory to search for cartridges (defaults to cwd)
+ * @returns Path normalizer function, or undefined if no cartridges found
+ *
+ * @example
+ * ```typescript
+ * // Auto-discover cartridges from current directory
+ * const normalize = discoverAndCreateNormalizer();
+ *
+ * // Auto-discover from specific directory
+ * const normalize = discoverAndCreateNormalizer('./my-project');
+ * ```
+ */
+export function discoverAndCreateNormalizer(directory) {
+    const searchDir = directory ?? process.cwd();
+    const cwd = process.cwd();
+    const cartridges = findCartridges(searchDir);
+    if (cartridges.length === 0) {
+        return undefined;
+    }
+    // Convert absolute paths to relative paths from cwd
+    const relativeCartridges = cartridges.map((c) => ({
+        ...c,
+        src: './' + path.relative(cwd, c.src),
+    }));
+    return createPathNormalizer({ cartridges: relativeCartridges });
+}
+/**
+ * Extracts all cartridge paths from a message.
+ *
+ * Useful for testing or analysis of log messages.
+ *
+ * @param message - Log message to extract paths from
+ * @returns Array of extracted paths
+ *
+ * @example
+ * ```typescript
+ * const paths = extractPaths("Error at (app_storefront/cartridge/controllers/Home.js:45)");
+ * // Returns: ["app_storefront/cartridge/controllers/Home.js:45"]
+ * ```
+ */
+export function extractPaths(message) {
+    const paths = [];
+    for (const { pattern, extractPath } of PATH_PATTERNS) {
+        const regex = new RegExp(pattern.source, pattern.flags);
+        let match;
+        while ((match = regex.exec(message)) !== null) {
+            const path = extractPath(match);
+            if (!paths.includes(path)) {
+                paths.push(path);
+            }
+        }
+    }
+    return paths;
+}
+//# sourceMappingURL=path-normalizer.js.map

package/dist/esm/operations/logs/path-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-normalizer.js","sourceRoot":"","sources":["../../../../src/operations/logs/path-normalizer.ts"],"names":[],"mappings":"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"}

package/dist/esm/operations/logs/tail.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Log tailing operations for B2C Commerce.
+ */
+import type { B2CInstance } from '../../instance/index.js';
+import type { GetRecentLogsOptions, LogEntry, TailLogsOptions, TailLogsResult } from './types.js';
+/**
+ * Parses the first line of a log entry to extract timestamp, level, and message.
+ *
+ * Expected format: [timestamp GMT] LEVEL context - message
+ * Example: [2025-01-25 10:30:45.123 GMT] ERROR PipelineCallServlet|... - Error message
+ *
+ * The message field will contain:
+ * - The content portion from the first line (after LEVEL)
+ * - Plus any continuation lines (stack traces, etc.)
+ *
+ * @param firstLine - First line of the log entry
+ * @param file - File name the entry came from
+ * @param fullMessage - Complete raw message including all lines
+ * @param pathNormalizer - Optional function to normalize paths in the message
+ * @returns Parsed log entry
+ */
+export declare function parseLogEntry(firstLine: string, file: string, fullMessage: string, pathNormalizer?: (msg: string) => string): LogEntry;
+/**
+ * Splits content into lines, handling incomplete lines at boundaries.
+ * Uses TextDecoder with stream mode for proper UTF-8 multi-byte character handling.
+ *
+ * @param content - ArrayBuffer content
+ * @param decoder - TextDecoder instance (should be reused for streaming)
+ * @param isComplete - Whether this is the final chunk (flush decoder)
+ * @returns Array of complete lines (without trailing incomplete line)
+ */
+export declare function splitLines(content: ArrayBuffer, decoder: InstanceType<typeof TextDecoder>, isComplete?: boolean): string[];
+/**
+ * Aggregates lines into multi-line log entries.
+ *
+ * B2C log entries can span multiple lines. A new entry starts when a line
+ * begins with a timestamp pattern: [YYYY-MM-DD HH:MM:SS.mmm GMT]
+ *
+ * @param lines - Array of individual lines
+ * @param pendingLines - Lines carried over from previous chunk (incomplete entry)
+ * @returns Object with complete entries and any pending lines for next chunk
+ */
+export declare function aggregateLogEntries(lines: string[], pendingLines?: string[]): {
+    entries: string[][];
+    pending: string[];
+};
+/**
+ * Tails log files on a B2C Commerce instance.
+ *
+ * Continuously polls for new log content using HTTP Range requests for efficiency.
+ * Calls the onEntry callback for each new log line.
+ *
+ * @param instance - B2C instance to tail logs from
+ * @param options - Tailing options (filters, callbacks, polling interval)
+ * @returns Tail result with stop() control and done promise
+ *
+ * @example
+ * ```typescript
+ * const result = await tailLogs(instance, {
+ *   prefixes: ['error', 'customerror'],
+ *   onEntry: (entry) => console.log(`[${entry.file}] ${entry.message}`),
+ *   onError: (err) => console.error('Tail error:', err),
+ * });
+ *
+ * // Stop after 10 seconds
+ * setTimeout(() => result.stop(), 10000);
+ *
+ * // Wait for tailing to complete
+ * await result.done;
+ * ```
+ */
+export declare function tailLogs(instance: B2CInstance, options?: TailLogsOptions): Promise<TailLogsResult>;
+/**
+ * Gets recent log entries (one-shot retrieval).
+ *
+ * Useful for MCP server integration or programmatic access without continuous tailing.
+ * Reads the tail end of log files and returns parsed entries.
+ *
+ * @param instance - B2C instance to get logs from
+ * @param options - Retrieval options
+ * @returns Array of recent log entries
+ *
+ * @example
+ * ```typescript
+ * // Get the last 50 error entries
+ * const entries = await getRecentLogs(instance, {
+ *   prefixes: ['error'],
+ *   maxEntries: 50
+ * });
+ * ```
+ */
+export declare function getRecentLogs(instance: B2CInstance, options?: GetRecentLogsOptions): Promise<LogEntry[]>;