@peernova/cuneiform-sf 1.0.2 → 1.0.4-beta.8

package/lib/mcp/tools/tool-factory.js

@@ -0,0 +1,146 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+import { McpErrorCodes } from '../errors.js';
+/**
+ * Creates a typed MCP tool handler that narrows `unknown` input to type `T`.
+ *
+ * The McpServer SDK validates input via Zod schemas before calling handlers,
+ * so the cast from `unknown` to `T` is runtime-safe. This wrapper centralizes
+ * the single cast point instead of scattering `input as T` across 18 handlers.
+ *
+ * @template T The validated input type (inferred from the handler parameter)
+ * @param handler - Typed handler function accepting validated input
+ * @returns Untyped handler matching the ToolHandler signature
+ */
+export function typedHandler(handler) {
+    return (adapters, input) => handler(adapters, input);
+}
+/**
+ * Converts a ServiceResult to MCP CallToolResult format.
+ *
+ * Maps success/failure to MCP's content/isError structure.
+ * Preserves warnings and metadata in the response.
+ *
+ * @template T The type of the service result data
+ * @param result - ServiceResult from a service call
+ * @returns MCP-formatted CallToolResult
+ *
+ * @example
+ * ```typescript
+ * const serviceResult = await orgInfoService.getOrgIdentity();
+ * return serviceResultToMcp(serviceResult);
+ * ```
+ */
+export function serviceResultToMcp(result) {
+    if (result.success) {
+        const content = {
+            type: 'text',
+            text: JSON.stringify({
+                success: true,
+                data: result.data,
+                message: result.message,
+                warnings: result.warnings,
+                metadata: result.metadata,
+            }, null, 2),
+        };
+        return {
+            content: [content],
+            isError: false,
+        };
+    }
+    // Failure case
+    const errorContent = {
+        type: 'text',
+        text: JSON.stringify({
+            success: false,
+            errorCode: result.errorCode ?? McpErrorCodes.SERVICE_CALL_FAILED,
+            message: result.message ?? 'Service call failed',
+            data: result.data,
+            metadata: result.metadata,
+        }, null, 2),
+    };
+    return {
+        content: [errorContent],
+        isError: true,
+    };
+}
+/**
+ * Converts a ServiceResult to a paginated MCP CallToolResult.
+ *
+ * Includes `_pagination` metadata in the response envelope for
+ * cursor-based pagination through large result sets.
+ *
+ * @template T The type of the service result data
+ * @param result - ServiceResult from a service call
+ * @param pagination - Pagination metadata for the response
+ * @returns MCP-formatted CallToolResult with pagination envelope
+ */
+export function serviceResultToMcpPaginated(result, pagination) {
+    if (result.success) {
+        const content = {
+            type: 'text',
+            text: JSON.stringify({
+                success: true,
+                data: result.data,
+                _pagination: pagination,
+                message: result.message,
+                warnings: result.warnings,
+                metadata: result.metadata,
+            }, null, 2),
+        };
+        return {
+            content: [content],
+            isError: false,
+        };
+    }
+    // Failure case — no pagination on errors
+    return serviceResultToMcp(result);
+}
+/**
+ * Extracts a user-facing error message from a caught error and logs the
+ * full stack trace to stderr for post-mortem debugging.
+ *
+ * @param error - The caught error (may be Error or non-Error value)
+ * @param context - Tool/handler name for the log prefix
+ * @returns The error message string
+ */
+/* eslint-disable no-console -- MCP uses stderr for logging */
+export function extractErrorMessage(error, context) {
+    if (error instanceof Error) {
+        if (error.stack) {
+            console.error(`[MCP] ${context} error:\n${error.stack}`);
+        }
+        return error.message;
+    }
+    const message = String(error);
+    console.error(`[MCP] ${context} non-Error thrown: ${message}`);
+    return message;
+}
+/* eslint-enable no-console */
+/**
+ * Creates an MCP error response.
+ *
+ * @param errorCode - MCP error code
+ * @param message - Error message
+ * @returns MCP-formatted error CallToolResult
+ */
+export function createMcpError(errorCode, message) {
+    const errorContent = {
+        type: 'text',
+        text: JSON.stringify({
+            success: false,
+            errorCode,
+            message,
+        }, null, 2),
+    };
+    return {
+        content: [errorContent],
+        isError: true,
+    };
+}
+//# sourceMappingURL=tool-factory.js.map

package/lib/mcp/tools/tool-factory.js.map

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

package/lib/mcp/tools/user-tools.d.ts

@@ -0,0 +1,25 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { McpAdapters } from '../config/mcp-config.js';
+import type { UserDetailsInput, UserConfigureInput } from '../schemas/input-schemas.js';
+/**
+ * Handler for cuneiform_user_details tool invocation.
+ *
+ * Returns user identity, readiness, and org context directly from service data.
+ * Builds the MCP response inline rather than delegating to the command layer.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export declare function handleUserDetails(adapters: McpAdapters, params: UserDetailsInput): Promise<CallToolResult>;
+/**
+ * Handler for cuneiform_user_configure tool invocation.
+ *
+ * Includes a prerequisite guard that checks Cuneiform installation
+ * before attempting configuration.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export declare function handleUserConfigure(adapters: McpAdapters, params: UserConfigureInput): Promise<CallToolResult>;

package/lib/mcp/tools/user-tools.js

@@ -0,0 +1,167 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+import { UserConfigurationService } from '../../services/UserConfigurationService.js';
+import { OrgInfoService } from '../../services/OrgInfoService.js';
+import { UserReadinessService } from '../../services/UserReadinessService.js';
+import { McpErrorCodes } from '../errors.js';
+import { createMcpError, serviceResultToMcp, extractErrorMessage } from './tool-factory.js';
+/**
+ * Handler for cuneiform_user_details tool invocation.
+ *
+ * Returns user identity, readiness, and org context directly from service data.
+ * Builds the MCP response inline rather than delegating to the command layer.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- SDK requires params arg; UserDetailsInput is empty
+export async function handleUserDetails(adapters, params) {
+    try {
+        const { facade, soql: soqlAdapter } = adapters;
+        const userReadinessService = new UserReadinessService({ soqlAdapter });
+        const orgInfoService = new OrgInfoService({ connectionFacade: facade, soqlAdapter });
+        // Get current user ID from connection identity with validation
+        const identity = await facade.identity();
+        const userId = identity.user_id;
+        if (!userId) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, 'Session expired or identity unavailable. Re-authenticate with the target org.');
+        }
+        // Fetch org identity, user info, and readiness in parallel
+        const [orgIdentityResult, userInfoResult, readinessResult] = await Promise.all([
+            orgInfoService.getOrgIdentity(),
+            userReadinessService.getUserInfo(userId),
+            userReadinessService.checkReadiness(userId),
+        ]);
+        // Handle user info failure
+        if (!userInfoResult.success) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to get user info: ${userInfoResult.message ?? 'Unknown error'}`);
+        }
+        // Handle readiness check failure
+        if (!readinessResult.success) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to check readiness: ${readinessResult.message ?? 'Unknown error'}`);
+        }
+        // Build warnings for partial failures
+        const warnings = [];
+        if (!orgIdentityResult.success) {
+            warnings.push(`Org identity unavailable: ${orgIdentityResult.message ?? 'Unknown error'}`);
+        }
+        const orgIdentity = orgIdentityResult.success ? orgIdentityResult.data : undefined;
+        const userInfo = userInfoResult.data;
+        const readiness = readinessResult.data;
+        // Build MCP response directly from service data (no command-layer dependency)
+        const result = {
+            orgContext: {
+                orgName: orgIdentity?.organizationName ?? null,
+                orgId: orgIdentity?.organizationId ?? null,
+                instanceUrl: facade.instanceUrl ?? null,
+                isSandbox: orgIdentity?.isSandbox ?? null,
+            },
+            user: {
+                id: userInfo.id,
+                username: userInfo.username,
+                email: userInfo.email,
+                profileName: userInfo.profileName,
+                roleName: userInfo.roleName,
+            },
+            readiness: {
+                isReady: readiness.isReady,
+                isCuneiformInstalled: readiness.isCuneiformInstalled,
+                permissionSets: {
+                    hasAllRequired: readiness.permissionSets.hasAllRequired,
+                    missingRequired: readiness.permissionSets.missingRequired,
+                    assignments: readiness.permissionSets.assignments,
+                },
+                configProfile: {
+                    isConfigured: readiness.configProfile.isConfigured,
+                    profileLabel: readiness.configProfile.profileLabel ?? null,
+                    apiOnlyProfilingEnabled: readiness.configProfile.isConfigured
+                        ? readiness.configProfile.apiOnlyProfilingEnabled ?? null
+                        : null,
+                },
+            },
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+        return serviceResultToMcp({
+            success: true,
+            data: result,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        });
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to get user details: ${extractErrorMessage(error, 'handleUserDetails')}`);
+    }
+}
+/**
+ * Handler for cuneiform_user_configure tool invocation.
+ *
+ * Includes a prerequisite guard that checks Cuneiform installation
+ * before attempting configuration.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export async function handleUserConfigure(adapters, params) {
+    try {
+        const { facade, soql: soqlAdapter, rest: restAdapter } = adapters;
+        const userReadinessService = new UserReadinessService({ soqlAdapter });
+        // Get current user ID from connection identity with validation
+        const identity = await facade.identity();
+        const userId = identity.user_id;
+        if (!userId) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, 'Session expired or identity unavailable. Re-authenticate with the target org.');
+        }
+        // Prerequisite guard: check Cuneiform is installed before configuring
+        const readinessResult = await userReadinessService.checkReadiness(userId);
+        if (!readinessResult.success) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to check prerequisites: ${readinessResult.message ?? 'Unknown error'}`);
+        }
+        if (!readinessResult.data.isCuneiformInstalled) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, 'Cuneiform for Salesforce is not installed in this org. ' +
+                'Install the package from AppExchange before configuring user access. ' +
+                'See: https://peernova.link/cli/configure');
+        }
+        const userConfigService = new UserConfigurationService({
+            soqlAdapter,
+            restApiAdapter: restAdapter,
+            userReadinessService,
+        });
+        // Execute configuration (with dry-run by default)
+        const configResult = await userConfigService.configure(userId, {
+            dryRun: params.dryRun,
+        });
+        if (!configResult.success) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Configuration failed: ${configResult.message ?? 'Unknown error'}`);
+        }
+        // Map to command-level result for consistent response shape
+        const result = {
+            dryRun: params.dryRun,
+            actions: configResult.data.actions.map((action) => ({
+                type: action.type,
+                target: action.target,
+                targetLabel: action.targetLabel ?? action.target,
+                status: params.dryRun ? 'planned' : action.status,
+                message: action.message,
+            })),
+            summary: {
+                changesRequired: configResult.data.summary.changesRequired,
+                changesApplied: configResult.data.summary.changesApplied,
+                changesFailed: configResult.data.summary.changesFailed,
+            },
+        };
+        return serviceResultToMcp({
+            success: true,
+            data: result,
+        });
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to configure user: ${extractErrorMessage(error, 'handleUserConfigure')}`);
+    }
+}
+//# sourceMappingURL=user-tools.js.map

package/lib/mcp/tools/user-tools.js.map

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

package/lib/models/date-literal.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Date literal support for profiling definition creation.
+ *
+ * Replaces the year-range model with ISV-compatible date literal segmentation.
+ * Definitions become rolling windows that stay relevant without recreation.
+ *
+ * The 14 supported literals match the ISV DateLiteral.cls constants exactly.
+ * See docs/knowledge/salesforce/date-literals.md for full reference.
+ */
+/**
+ * The 14 date literals supported by the ISV DateLiteral.cls.
+ * These are the ONLY literals the CLI should generate — they correspond 1:1
+ * to the constants in the ISV product's DateLiteral class.
+ */
+export declare const SUPPORTED_DATE_LITERALS: readonly ["TODAY", "YESTERDAY", "THIS_WEEK", "LAST_WEEK", "THIS_MONTH", "LAST_MONTH", "THIS_QUARTER", "LAST_QUARTER", "THIS_YEAR", "LAST_YEAR", "N_YEARS_AGO:2", "N_YEARS_AGO:3", "LAST_N_YEARS:2", "LAST_N_YEARS:3"];
+/** Type representing any supported date literal value */
+export type SupportedDateLiteral = (typeof SUPPORTED_DATE_LITERALS)[number];
+/**
+ * Customer-facing labels for each date literal.
+ * Used in definition names, descriptions, and time category display.
+ */
+export declare const DATE_LITERAL_LABELS: Record<SupportedDateLiteral, string>;
+/**
+ * Date literal tier classification.
+ *
+ * Each tier determines the maximum allowed depth for cascading:
+ * - year: depth 0-3 (THIS_YEAR → LAST_YEAR → N_YEARS_AGO:2 → N_YEARS_AGO:3)
+ * - quarter: depth 0-1 (THIS_QUARTER → LAST_QUARTER)
+ * - month: depth 0-1 (THIS_MONTH → LAST_MONTH)
+ * - week: depth 0-1 (THIS_WEEK → LAST_WEEK)
+ * - day: depth 0-1 (TODAY → YESTERDAY)
+ * - span: depth 0 only (LAST_N_YEARS:2, LAST_N_YEARS:3 combine multiple years)
+ */
+export type DateLiteralTier = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'span';
+/** Maps each literal to its tier */
+export declare const LITERAL_TIERS: Record<SupportedDateLiteral, DateLiteralTier>;
+/**
+ * Maximum cascade depth per tier.
+ *
+ * Only year-tier literals support depth > 1. Quarter, month, week, and day tiers
+ * each represent a single atomic period with no comparable prior available via
+ * ISV-supported literals, so depth is capped at 1 for those tiers.
+ */
+export declare const TIER_MAX_DEPTH: Record<DateLiteralTier, number>;
+/**
+ * Depth cascade arrays per literal.
+ *
+ * Starting from a given literal at depth 0, each subsequent depth level
+ * adds the next literal in the cascade. Cascades always move backward in time.
+ *
+ * Example: THIS_YEAR with depth 3 → [THIS_YEAR, LAST_YEAR, N_YEARS_AGO:2]
+ */
+export declare const LITERAL_CASCADES: Record<SupportedDateLiteral, readonly SupportedDateLiteral[]>;
+/**
+ * A single entry in a resolved date literal range.
+ * Analogous to ComparativeYearEntry in the year-range model.
+ */
+export type DateLiteralEntry = {
+    /** The date literal value (e.g., 'THIS_YEAR', 'LAST_QUARTER') */
+    readonly literal: SupportedDateLiteral;
+    /** Customer-facing label (e.g., 'This Year', 'Last Quarter') */
+    readonly label: string;
+};
+/**
+ * A resolved date literal range for profiling definitions.
+ * Analogous to YearRange in the year-range model.
+ *
+ * Contains the ordered list of date literal entries derived from user input
+ * (--date-literal flag + --depth flag).
+ */
+export type DateLiteralRange = {
+    /** Ordered list of date literal entries (most recent first) */
+    readonly entries: readonly DateLiteralEntry[];
+    /** The date field to filter on (default: CreatedDate) */
+    readonly dateField: string;
+};
+/**
+ * Raw flag inputs for date literal range resolution.
+ */
+export type DateLiteralInput = {
+    /** The base date literal (e.g., 'THIS_YEAR') */
+    dateLiteral: string;
+    /** Number of periods to cascade (counting back from base) */
+    depth?: number;
+    /** The date field to filter on (default: CreatedDate) */
+    dateField?: string;
+};
+/**
+ * Validates a date literal value against the ISV-supported set.
+ *
+ * @param value - The date literal string to validate
+ * @returns undefined if valid, error message string if invalid
+ */
+export declare function validateDateLiteral(value: string): string | undefined;
+/**
+ * Resolves CLI flag inputs into a validated DateLiteralRange.
+ *
+ * @param input - Raw flag inputs
+ * @returns Resolved DateLiteralRange
+ * @throws Error if inputs are invalid
+ */
+export declare function resolveDateLiteralRange(input: DateLiteralInput): DateLiteralRange;
+/**
+ * Returns the customer-facing label for a date literal.
+ *
+ * @param literal - A supported date literal value
+ * @returns The label string, or the raw literal if not found
+ */
+export declare function getDateLiteralLabel(literal: string): string;
+/**
+ * Maps each date literal to its `$Constant.*` display value for the expression builder.
+ * These are the values that `fsc_expressionBuilder3` renders in the Value field.
+ */
+export declare const DATE_LITERAL_CONSTANTS: Record<SupportedDateLiteral, string>;
+/**
+ * Builds an ISV-compatible filterJson string for date literal filtering.
+ *
+ * Produces the full expression builder JSON schema that `fsc_expressionBuilder3` expects,
+ * including all 12 required fields per expression line. The `parameter` field uses `$Constant.*`
+ * display values and `parameterValue` / `dateLiteral` use the SOQL literal.
+ *
+ * The outer envelope (hasFilters, setA) is required by ProfilingDefinitionApiService.resolveFilterClause()
+ * to enable WHERE clause filtering. setA.json must be an object (not a string) — the API
+ * does JSON.serialize() on it.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate')
+ * @param dateLiteral - The date literal value (e.g., 'THIS_YEAR', 'N_YEARS_AGO:2')
+ * @param objectName - The Salesforce object API name (e.g., 'Account', 'Lead'). Defaults to empty string for backward compatibility.
+ * @param objectLabel - The Salesforce object label (e.g., 'Account', 'Lead'). Defaults to objectName.
+ * @returns JSON string compatible with GlobalProfilingService.createProfilingDefinition()
+ */
+export declare function buildDateLiteralFilterJson(dateField: string, dateLiteral: string, objectName?: string, objectLabel?: string): string;
+/**
+ * Builds an ISV-compatible filterJson string for date-literal comparative definitions.
+ * Creates SetA (primary period) and SetB (prior period), both using SOQL date literals.
+ *
+ * Used when method='comparative' with a date literal that has a prior period in its cascade.
+ * The prior literal is derived from LITERAL_CASCADES[setALiteral][1] by the caller.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate')
+ * @param setALiteral - The primary (current) date literal for SetA
+ * @param setBLiteral - The prior period date literal for SetB
+ * @param objectName - The Salesforce object API name
+ * @param objectLabel - The Salesforce object label
+ * @returns JSON string with hasFilters, setA, and setB
+ */
+export declare function buildComparativeDateLiteralFilterJson(dateField: string, setALiteral: SupportedDateLiteral, setBLiteral: SupportedDateLiteral, objectName?: string, objectLabel?: string): string;
+/**
+ * Maps a calendar year to the appropriate SOQL date literal based on distance from current year.
+ *
+ * @param year - The target calendar year
+ * @returns The date literal key (THIS_YEAR, LAST_YEAR, N_YEARS_AGO:2, N_YEARS_AGO:3) or undefined if out of range
+ */
+export declare function yearToDateLiteral(year: number): SupportedDateLiteral | undefined;
+/**
+ * Formats a year boundary as an ISO 8601 UTC midnight string.
+ * Used for explicit date range expressions in year-based comparisons.
+ */
+export declare function yearBoundaryISO(year: number): string;
+/**
+ * Formats a year boundary as a human-readable display string (M/d/yyyy, h:mm a).
+ * Used for the `parameter` display value in expression builder JSON.
+ */
+export declare function yearBoundaryDisplay(year: number): string;
+/**
+ * Builds an ISV-compatible filterJson string for a single year (SetA only, no SetB).
+ * Used for historical definitions scoped to a specific year via --year flag.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate')
+ * @param year - The target year
+ * @param objectName - The Salesforce object API name
+ * @param objectLabel - The Salesforce object label
+ * @returns JSON string with hasFilters and setA (no setB)
+ */
+export declare function buildHistoricalYearFilterJson(dateField: string, year: number, objectName?: string, objectLabel?: string): string;
+/**
+ * Builds an ISV-compatible filterJson string for year-based comparative definitions.
+ * Creates SetA (target year) and SetB (prior year or all prior years) using explicit
+ * date range expressions (>= start AND < end), not date literals.
+ *
+ * This approach supports arbitrary years with no lookback limitation.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate', 'LastModifiedDate')
+ * @param year - The target year for SetA
+ * @param usePrior - When true, SetB is all records before the target year. When false, SetB is the prior year.
+ * @param objectName - The Salesforce object API name
+ * @param objectLabel - The Salesforce object label
+ * @returns JSON string with hasFilters, setA, and setB
+ */
+export declare function buildComparativeYearFilterJson(dateField: string, year: number, usePrior: boolean, objectName?: string, objectLabel?: string): string;
+/**
+ * Builds an ISV-compatible filterJson string for the lifetime-vs-X comparative variant.
+ *
+ * SetA is unfiltered (empty expressions array — represents "all records / lifetime"); SetB carries the supplied
+ * secondary filter. This is the inverse of `buildComparativeYearFilterJson`, where SetA is the year-scoped set and
+ * SetB is the prior-year (or unbounded) set.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate', 'LastModifiedDate')
+ * @param secondary - The secondary filter spec applied to SetB. Accepts `{ kind: 'year', year }` for a year-bounded SetB,
+ * or `{ kind: 'dateLiteral', literal }` for a SOQL date-literal SetB.
+ * @param objectName - The Salesforce object API name
+ * @param objectLabel - The Salesforce object label (defaults to objectName)
+ * @returns JSON string with hasFilters, setA (empty), and setB (filtered)
+ */
+export declare function buildLifetimeComparativeFilterJson(dateField: string, secondary: {
+    kind: 'year';
+    year: number;
+} | {
+    kind: 'dateLiteral';
+    literal: SupportedDateLiteral;
+}, objectName?: string, objectLabel?: string): string;