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

package/lib/services/ProfilingDefinitionService.js

@@ -0,0 +1,1029 @@
+/*
+ * 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 { createSuccessResult, createFailureResult } from '../models/service-result.js';
+import { ServiceErrorCodes } from '../adapters/errors.js';
+import { CuneiformQueryBuilder } from '../adapters/soql/cuneiform-query-builder.js';
+import { validateSalesforceId, validateObjectName, validatePagination, validateRequiredString } from './validation.js';
+import { MAX_PAGINATION_LIMIT } from './constants.js';
+/**
+ * Default pagination limit for listDefinitions.
+ * Distinct from the general DEFAULT_PAGINATION_LIMIT (50) used by getDefinitions.
+ */
+const LIST_DEFAULT_LIMIT = 25;
+/** Empty/zero ListSummary used for failure-path returns. */
+const EMPTY_LIST_SUMMARY = {
+    activeCount: 0,
+    inactiveCount: 0,
+    profiledCount: 0,
+    notProfiledCount: 0,
+};
+/**
+ * Maps a listDefinitions sort field to the corresponding Salesforce field API name.
+ */
+const SORT_FIELD_MAP = {
+    key: 'Name',
+    name: 'pnova__Prop_Name__c',
+    objectName: 'pnova__Prop_SObjectApiName__c',
+    lastProfiledDate: 'pnova__PFx_LastDateProfiled__c',
+};
+/**
+ * SOQL field list for Profiling_Definition__c queries.
+ * Field names match actual Salesforce schema.
+ */
+// Query building, validation, and constants extracted to DefinitionQueryBuilder
+import { DefinitionQueryBuilder, DEFINITION_FIELDS } from './DefinitionQueryBuilder.js';
+/**
+ * Domain service for querying Cuneiform profiling definitions.
+ *
+ * Provides methods to retrieve profiling definitions from the
+ * Profiling_Definition__c custom object with filtering and pagination.
+ *
+ * @design
+ * **Read-Only Service**: This service only queries definitions; it does not
+ * create or update them. Definition management is handled through the
+ * Cuneiform UI or separate admin operations.
+ *
+ * @design
+ * **Field Mapping**: Maps Salesforce custom field names (e.g., `Definition_Key__c`)
+ * to TypeScript-friendly camelCase (e.g., `key`). This isolates consumers from
+ * Salesforce naming conventions and enables cleaner TypeScript interfaces.
+ *
+ * @design
+ * **Validation Strategy**: Validates filter parameters (type, status, objectName)
+ * before building SOQL to fail fast with clear error messages rather than
+ * letting Salesforce return cryptic query errors.
+ *
+ * @example
+ * ```typescript
+ * const service = new ProfilingDefinitionService({ soqlAdapter });
+ * const result = await service.getDefinitions({ objectName: 'Account', isActive: true });
+ * if (result.success) {
+ *   result.data.forEach(def => console.log(def.name));
+ * }
+ * ```
+ */
+// NOTE: GlobalProfilingServiceResponse type and DEFINITION_RESPONSE_MARKER removed
+// during REST API migration (CLI-1150). Apex routing now uses REST endpoints.
+/**
+ * Base path for Cuneiform profiling REST API endpoints.
+ */
+// Apex urlMapping is '/v1/profiling/*' — Salesforce auto-prepends namespace (pnova),
+// so the actual URL is /services/apexrest/pnova/v1/profiling/*
+const PROFILING_DEFINITION_REST_BASE = '/services/apexrest/pnova/v1/profiling';
+export class ProfilingDefinitionService {
+    soqlAdapter;
+    restAdapter;
+    logger;
+    constructor(config) {
+        this.soqlAdapter = config.soqlAdapter;
+        this.restAdapter = config.restAdapter;
+        this.logger = config.logger;
+    }
+    /**
+     * Derives the definition type from boolean flags.
+     *
+     * Logic:
+     * - comparative: isFilteredSetB is true (comparing two data sets)
+     * - metadata: isMetadataOnly is true (metadata-only profiling)
+     * - historical: default (standard profiling)
+     *
+     * @param isFilteredSetB - Whether Set B is filtered
+     * @param isMetadataOnly - Whether metadata-only profiling
+     * @returns The derived definition type
+     */
+    static deriveDefinitionType(isFilteredSetB, isMetadataOnly) {
+        if (isFilteredSetB) {
+            return 'comparative';
+        }
+        if (isMetadataOnly) {
+            return 'metadata';
+        }
+        return 'historical';
+    }
+    /**
+     * Maps a raw Salesforce Profiling_Definition__c record to a ProfilingDefinition.
+     *
+     * @param record - The raw SOQL query result record
+     * @returns Mapped ProfilingDefinition with camelCase field names
+     */
+    static mapToProfilingDefinition(record) {
+        const isFilteredSetB = record.pnova__Prop_IsFiltered_SetB__c ?? false;
+        const isMetadataOnly = record.pnova__PropFx_IsMetadataProfilingOnly__c ?? false;
+        return {
+            id: record.Id,
+            key: record.Name,
+            name: record.pnova__Prop_Name__c,
+            objectName: record.pnova__Prop_SObjectApiName__c,
+            objectLabel: record.pnova__Prop_SObjectLabel__c ?? undefined,
+            type: ProfilingDefinitionService.deriveDefinitionType(isFilteredSetB, isMetadataOnly),
+            status: record.pnova__Agg_Status__c ?? 'NOT PROFILED',
+            category: record.pnova__Prop_Category__c ?? undefined,
+            description: record.pnova__Prop_Description__c ?? undefined,
+            isActive: record.pnova__Prop_IsActive__c ?? false,
+            isFilteredSetA: record.pnova__Prop_IsFiltered_SetA__c ?? false,
+            isFilteredSetB,
+            isMetadataOnly,
+            isProfilingAllRecords: record.pnova__PropFx_IsProfilingAllRecords__c ?? false,
+            hasRelatedSummaries: record.pnova__PFx_HasRelatedSummaries__c ?? false,
+            lastProfiledDate: record.pnova__PFx_LastDateProfiled__c ?? undefined,
+            timeCategory: record.pnova__Prop_TimeCategory__c ?? undefined,
+            segmentCategory: record.pnova__Prop_SegmentCategory__c ?? undefined,
+            createdDate: record.CreatedDate ?? undefined,
+            lastModifiedDate: record.LastModifiedDate ?? undefined,
+        };
+    }
+    /**
+     * Builds a complete SOQL query string for Profiling_Definition__c using CuneiformQueryBuilder.
+     *
+     * Type filtering is pushed to SOQL using the underlying boolean fields:
+     * - comparative: isFilteredSetB = true
+     * - metadata: isMetadataOnly = true AND isFilteredSetB = false
+     * - historical: isMetadataOnly = false AND isFilteredSetB = false
+     *
+     * @param options - The filter and pagination options
+     * @returns Complete SOQL query string
+     */
+    // Static query building methods delegated to DefinitionQueryBuilder
+    static buildSoqlQuery(options) {
+        return DefinitionQueryBuilder.buildSoqlQuery(options);
+    }
+    static validateType(type) {
+        return DefinitionQueryBuilder.validateType(type);
+    }
+    static validateStatus(status) {
+        return DefinitionQueryBuilder.validateStatus(status);
+    }
+    static buildCreateDefinitionRequestBody(input) {
+        return DefinitionQueryBuilder.buildCreateDefinitionRequestBody(input);
+    }
+    static buildListWhereConditions(filter) {
+        return DefinitionQueryBuilder.buildListWhereConditions(filter);
+    }
+    static applyWhereConditions(builder, conditions) {
+        DefinitionQueryBuilder.applyWhereConditions(builder, conditions);
+    }
+    /**
+     * Folds aggregate rows from the GROUP BY query into a totalCount and named
+     * bucket counts. Status taxonomy preserves the prior in-memory display logic:
+     * profiledCount covers SUCCESS and COMPLETE w/ FAILURES; notProfiledCount
+     * covers NOT PROFILED and ERROR; IN PROGRESS and null statuses contribute to
+     * totalCount and the active/inactive split but are excluded from
+     * profiled/notProfiled.
+     */
+    static foldAggregateRows(rows) {
+        const summary = { activeCount: 0, inactiveCount: 0, profiledCount: 0, notProfiledCount: 0 };
+        let totalCount = 0;
+        for (const row of rows) {
+            const cnt = row.cnt;
+            totalCount += cnt;
+            if (row.pnova__Prop_IsActive__c) {
+                summary.activeCount += cnt;
+            }
+            else {
+                summary.inactiveCount += cnt;
+            }
+            const status = row.pnova__Agg_Status__c;
+            if (status === 'SUCCESS' || status === 'COMPLETE w/ FAILURES') {
+                summary.profiledCount += cnt;
+            }
+            else if (status === 'NOT PROFILED' || status === 'ERROR') {
+                summary.notProfiledCount += cnt;
+            }
+        }
+        return { totalCount, summary };
+    }
+    /**
+     * Retrieves profiling definitions with optional filtering and pagination.
+     *
+     * Note: Type filtering is applied client-side after the query since the type
+     * is derived from boolean flags (Prop_IsFiltered_SetB__c, PropFx_IsMetadataProfilingOnly__c).
+     *
+     * @param options - Filter and pagination options
+     * @returns ServiceResult containing an array of ProfilingDefinition records
+     */
+    async getDefinitions(options = {}) {
+        const startTime = Date.now();
+        const emptyResult = [];
+        // Validate type filter if provided
+        if (options.type !== undefined) {
+            const typeError = ProfilingDefinitionService.validateType(options.type);
+            if (typeError) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_QUERY_FAILED, typeError, {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+        }
+        // Validate status filter if provided
+        if (options.status !== undefined) {
+            const statusError = ProfilingDefinitionService.validateStatus(options.status);
+            if (statusError) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_QUERY_FAILED, statusError, {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+        }
+        // Validate objectNames filter if provided (takes precedence over objectName)
+        if (options.objectNames !== undefined) {
+            for (const name of options.objectNames) {
+                const objectNameError = validateObjectName(name);
+                if (objectNameError) {
+                    return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_INVALID_OBJECT_NAME, objectNameError, {
+                        metadata: { duration: Date.now() - startTime },
+                    });
+                }
+            }
+        }
+        // Validate objectName filter if provided
+        if (options.objectName !== undefined) {
+            const objectNameError = validateObjectName(options.objectName);
+            if (objectNameError) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_INVALID_OBJECT_NAME, objectNameError, {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+        }
+        // Validate pagination
+        const paginationError = validatePagination(options.limit, options.offset, MAX_PAGINATION_LIMIT);
+        if (paginationError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.INVALID_PAGINATION, paginationError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        try {
+            const soql = ProfilingDefinitionService.buildSoqlQuery(options);
+            this.logger?.log(`Querying profiling definitions: ${soql}`);
+            const queryResult = await this.soqlAdapter.query(soql);
+            if (!queryResult.success) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_QUERY_FAILED, queryResult.message ?? 'Profiling definition query failed', { metadata: { duration: Date.now() - startTime } });
+            }
+            const definitions = queryResult.data.records.map((record) => ProfilingDefinitionService.mapToProfilingDefinition(record));
+            // Note: Type filtering is now done in SOQL via underlying boolean fields.
+            // No client-side filtering needed since SOQL already applied the filter.
+            const duration = Date.now() - startTime;
+            this.logger?.log(`Found ${String(definitions.length)} profiling definitions`);
+            return createSuccessResult(definitions, {
+                message: `Found ${String(definitions.length)} profiling definitions`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Profiling definition query failed: ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_QUERY_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Retrieves all profiling definitions matching the given filters, with automatic pagination.
+     *
+     * Fetches pages of MAX_PAGINATION_LIMIT (200) until a short page is returned.
+     * The limit and offset options are ignored — pagination is handled internally.
+     *
+     * @param options - Filter options (limit/offset are overridden)
+     * @returns ServiceResult containing all matching ProfilingDefinition records
+     */
+    async getAllDefinitions(options = {}) {
+        const startTime = Date.now();
+        // Phase 1: standard query using the fully-qualified namespace prefix LIKE pattern.
+        const phase1 = await this.fetchAllPages(options);
+        if (!phase1.success)
+            return phase1;
+        if (phase1.data.length > 0) {
+            this.logger?.log(`Fetched ${phase1.data.length} total definitions across pagination`);
+            return createSuccessResult(phase1.data, {
+                ...(phase1.warnings ? { warnings: phase1.warnings } : {}),
+                message: `Found ${phase1.data.length} definitions`,
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        // Phase 2 fallback: fires only when Phase 1 returned 0, the requested namespace is
+        // 'pnova', and the org itself owns that namespace. In such orgs, objects may be stored
+        // without the namespace prefix, so the standard LIKE returns nothing. The wider '%__c'
+        // pattern catches them; client-side filtering removes false positives from other packages.
+        if (options.namespace?.kind === 'managed' && options.namespace.namespaces.includes('pnova')) {
+            const orgNamespace = await this.getOrgNamespace();
+            if (orgNamespace === 'pnova') {
+                const phase2 = await this.fetchAllPages({ ...options, orgNamespace });
+                if (!phase2.success)
+                    return phase2;
+                const namespaces = options.namespace.namespaces;
+                const filtered = phase2.data.filter((def) => namespaces.some((ns) => DefinitionQueryBuilder.isObjectInNamespace(def.objectName, ns, orgNamespace)));
+                this.logger?.log(`Fetched ${filtered.length} total definitions across pagination`);
+                return createSuccessResult(filtered, {
+                    message: `Found ${filtered.length} definitions`,
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+        }
+        this.logger?.log('Fetched 0 total definitions across pagination');
+        return createSuccessResult([], {
+            message: 'Found 0 definitions',
+            metadata: { duration: Date.now() - startTime },
+        });
+    }
+    /**
+     * Lists profiling definitions with filtering, pagination, and sorting.
+     *
+     * Executes two SOQL queries:
+     *
+     * - An aggregate GROUP BY query over the full filter set (no pagination) that
+     * yields totalCount and per-status / per-active bucket counts in one round-trip.
+     * - A data query with SELECT, WHERE, ORDER BY, LIMIT, OFFSET for the page.
+     *
+     * @param options - Filter, pagination, and sort options
+     * @returns ServiceResult containing definitions, totalCount, and aggregate summary
+     */
+    async listDefinitions(options) {
+        const startTime = Date.now();
+        const emptyResult = {
+            definitions: [],
+            totalCount: 0,
+            summary: { ...EMPTY_LIST_SUMMARY },
+        };
+        // Validate pagination
+        const limit = options.pagination?.limit ?? LIST_DEFAULT_LIMIT;
+        const offset = options.pagination?.offset ?? 0;
+        const paginationError = validatePagination(limit, offset, MAX_PAGINATION_LIMIT);
+        if (paginationError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.INVALID_PAGINATION, paginationError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        // Validate objects filter if provided
+        if (options.filter?.objects !== undefined) {
+            for (const name of options.filter.objects) {
+                const objectNameError = validateObjectName(name);
+                if (objectNameError) {
+                    return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_INVALID_OBJECT_NAME, objectNameError, {
+                        metadata: { duration: Date.now() - startTime },
+                    });
+                }
+            }
+        }
+        // Namespace validation is now performed at the parser boundary
+        // (`parseNamespaceFilter` in services/namespace-filter.ts) — the typed
+        // NamespaceFilter discriminated union arriving here is already validated.
+        try {
+            // Build WHERE conditions (shared by both aggregate and data queries)
+            const whereBuilder = ProfilingDefinitionService.buildListWhereConditions(options.filter);
+            // 1. Aggregate GROUP BY query for totalCount AND summary buckets
+            const aggregateBuilder = new CuneiformQueryBuilder()
+                .select(['COUNT(Id) cnt', 'pnova__Agg_Status__c', 'pnova__Prop_IsActive__c'])
+                .from('pnova__Profiling_Definition__c');
+            ProfilingDefinitionService.applyWhereConditions(aggregateBuilder, whereBuilder);
+            aggregateBuilder.groupBy(['pnova__Agg_Status__c', 'pnova__Prop_IsActive__c']);
+            const aggregateSoql = aggregateBuilder.toSOQL();
+            this.logger?.log(`Aggregating profiling definitions: ${aggregateSoql}`);
+            const aggregateResult = await this.soqlAdapter.query(aggregateSoql);
+            if (!aggregateResult.success) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_QUERY_FAILED, aggregateResult.message ?? 'Profiling definition aggregate query failed', { metadata: { duration: Date.now() - startTime } });
+            }
+            const { totalCount, summary } = ProfilingDefinitionService.foldAggregateRows(aggregateResult.data.records);
+            // 2. Data query with pagination and sort
+            const dataBuilder = new CuneiformQueryBuilder()
+                .select(DEFINITION_FIELDS.split(', '))
+                .from('pnova__Profiling_Definition__c');
+            ProfilingDefinitionService.applyWhereConditions(dataBuilder, whereBuilder);
+            // Sort
+            const sortField = options.sort?.field ?? 'name';
+            const sortDirection = (options.sort?.direction ?? 'asc').toUpperCase();
+            const soqlSortField = SORT_FIELD_MAP[sortField] ?? 'pnova__Prop_Name__c';
+            if (sortField === 'lastProfiledDate') {
+                dataBuilder.orderBy(soqlSortField, sortDirection, 'NULLS LAST');
+            }
+            else {
+                dataBuilder.orderBy(soqlSortField, sortDirection);
+            }
+            dataBuilder.limit(limit);
+            dataBuilder.offset(offset);
+            const dataSoql = dataBuilder.toSOQL();
+            this.logger?.log(`Querying profiling definitions: ${dataSoql}`);
+            const queryResult = await this.soqlAdapter.query(dataSoql);
+            if (!queryResult.success) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_QUERY_FAILED, queryResult.message ?? 'Profiling definition query failed', { metadata: { duration: Date.now() - startTime } });
+            }
+            const definitions = queryResult.data.records.map((record) => ProfilingDefinitionService.mapToProfilingDefinition(record));
+            const duration = Date.now() - startTime;
+            this.logger?.log(`Listed ${String(definitions.length)} of ${String(totalCount)} profiling definitions`);
+            return createSuccessResult({ definitions, totalCount, summary }, {
+                message: `Listed ${String(definitions.length)} of ${String(totalCount)} profiling definitions`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Profiling definition list failed: ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_QUERY_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Retrieves a single profiling definition by its Salesforce ID.
+     *
+     * @param id - The Salesforce record ID (15 or 18 characters)
+     * @returns ServiceResult containing the ProfilingDefinition or null if not found
+     */
+    async getDefinitionById(id) {
+        const startTime = Date.now();
+        const emptyResult = null;
+        // Validate ID format
+        const idError = validateSalesforceId(id);
+        if (idError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_INVALID_ID, idError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        try {
+            const soql = new CuneiformQueryBuilder()
+                .select(DEFINITION_FIELDS.split(', '))
+                .from('pnova__Profiling_Definition__c')
+                .where('Id', '=', id)
+                .limit(1)
+                .toSOQL();
+            this.logger?.log(`Querying profiling definition by ID: ${id}`);
+            const queryResult = await this.soqlAdapter.query(soql);
+            if (!queryResult.success) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_QUERY_FAILED, queryResult.message ?? 'Profiling definition query failed', { metadata: { duration: Date.now() - startTime } });
+            }
+            const duration = Date.now() - startTime;
+            if (queryResult.data.records.length === 0) {
+                this.logger?.log(`Profiling definition not found: ${id}`);
+                return createSuccessResult(emptyResult, {
+                    message: `Profiling definition not found: ${id}`,
+                    warnings: [`No profiling definition found with ID: ${id}`],
+                    metadata: { duration },
+                });
+            }
+            const definition = ProfilingDefinitionService.mapToProfilingDefinition(queryResult.data.records[0]);
+            this.logger?.log(`Found profiling definition: ${definition.name}`);
+            return createSuccessResult(definition, {
+                message: `Found profiling definition: ${definition.name}`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Profiling definition query failed: ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_QUERY_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Retrieves a single profiling definition by its definition key (e.g., "PD-0001").
+     *
+     * The key is stored in the standard Name field as an AutoNumber.
+     *
+     * @param key - The definition key (e.g., "PD-0001")
+     * @returns ServiceResult containing the ProfilingDefinition or null if not found
+     */
+    async getDefinitionByKey(key) {
+        const startTime = Date.now();
+        const emptyResult = null;
+        // Validate key is provided
+        const keyError = validateRequiredString(key, 'Definition key');
+        if (keyError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_QUERY_FAILED, keyError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        try {
+            // Name is the standard AutoNumber field (format: PD-{0000})
+            const soql = new CuneiformQueryBuilder()
+                .select(DEFINITION_FIELDS.split(', '))
+                .from('pnova__Profiling_Definition__c')
+                .where('Name', '=', key.trim())
+                .limit(1)
+                .toSOQL();
+            this.logger?.log(`Querying profiling definition by key: ${key}`);
+            const queryResult = await this.soqlAdapter.query(soql);
+            if (!queryResult.success) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_QUERY_FAILED, queryResult.message ?? 'Profiling definition query failed', { metadata: { duration: Date.now() - startTime } });
+            }
+            const duration = Date.now() - startTime;
+            if (queryResult.data.records.length === 0) {
+                this.logger?.log(`Profiling definition not found: ${key}`);
+                return createSuccessResult(emptyResult, {
+                    message: `Profiling definition not found: ${key}`,
+                    warnings: [`No profiling definition found with key: ${key}`],
+                    metadata: { duration },
+                });
+            }
+            const definition = ProfilingDefinitionService.mapToProfilingDefinition(queryResult.data.records[0]);
+            this.logger?.log(`Found profiling definition: ${definition.name} (key: ${key})`);
+            return createSuccessResult(definition, {
+                message: `Found profiling definition: ${definition.name}`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Profiling definition query failed: ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_QUERY_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Retrieves multiple profiling definitions by their human-readable keys in a single SOQL query.
+     *
+     * Replaces the N+1 pattern of calling getDefinitionByKey() per key with a single
+     * `WHERE Name IN (...)` query. Returns a Map keyed by the requested key values.
+     *
+     * @param keys - Array of definition keys (e.g., ['PD-0001', 'PD-0002'])
+     * @returns ServiceResult containing a Map of key → ProfilingDefinition (missing keys have null)
+     */
+    async getDefinitionsByKeys(keys) {
+        const startTime = Date.now();
+        const emptyResult = new Map();
+        if (keys.length === 0) {
+            return createSuccessResult(emptyResult, {
+                message: 'No keys provided',
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        try {
+            const trimmedKeys = keys.map((k) => k.trim());
+            const soql = new CuneiformQueryBuilder()
+                .select(DEFINITION_FIELDS.split(', '))
+                .from('pnova__Profiling_Definition__c')
+                .andWhereIn('Name', trimmedKeys)
+                .toSOQL();
+            this.logger?.log(`Querying profiling definitions by keys: ${trimmedKeys.join(', ')}`);
+            const queryResult = await this.soqlAdapter.query(soql);
+            if (!queryResult.success) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_QUERY_FAILED, queryResult.message ?? 'Profiling definition batch query failed', { metadata: { duration: Date.now() - startTime } });
+            }
+            const duration = Date.now() - startTime;
+            // Build result map: key → definition or null
+            const resultMap = new Map();
+            const recordsByKey = new Map();
+            for (const record of queryResult.data.records) {
+                recordsByKey.set(record.Name, record);
+            }
+            for (const key of trimmedKeys) {
+                const record = recordsByKey.get(key);
+                resultMap.set(key, record ? ProfilingDefinitionService.mapToProfilingDefinition(record) : null);
+            }
+            const foundCount = queryResult.data.records.length;
+            this.logger?.log(`Found ${foundCount}/${trimmedKeys.length} profiling definitions`);
+            return createSuccessResult(resultMap, {
+                message: `Found ${foundCount} of ${trimmedKeys.length} requested definitions`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Profiling definition batch query failed: ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_QUERY_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Retrieves profiling definitions filtered by type.
+     *
+     * Convenience method that delegates to getDefinitions() with the type filter.
+     *
+     * @param type - The definition type to filter by
+     * @param options - Additional filter and pagination options
+     * @returns ServiceResult containing an array of ProfilingDefinition records
+     */
+    async getDefinitionsByType(type, options = {}) {
+        return this.getDefinitions({ ...options, type });
+    }
+    /**
+     * Retrieves profiling definitions filtered by status.
+     *
+     * Convenience method that delegates to getDefinitions() with the status filter.
+     *
+     * @param status - The profiling status to filter by
+     * @param options - Additional filter and pagination options
+     * @returns ServiceResult containing an array of ProfilingDefinition records
+     */
+    async getDefinitionsByStatus(status, options = {}) {
+        return this.getDefinitions({ ...options, status });
+    }
+    /**
+     * Creates a new profiling definition via the Cuneiform REST API.
+     *
+     * Definition creation is routed through the REST endpoint which enforces
+     * server-side permission checks in GlobalProfilingService.
+     *
+     * @param input - The definition input containing name, objectName, and optional fields
+     * @returns ServiceResult containing the created ProfilingDefinition or null on failure
+     */
+    async createDefinition(input) {
+        const startTime = Date.now();
+        const emptyResult = null;
+        if (!this.restAdapter) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_CREATE_FAILED, 'restAdapter is required for create operations.', { metadata: { duration: Date.now() - startTime } });
+        }
+        return this.createDefinitionViaRest(input, startTime);
+    }
+    /**
+     * Creates multiple profiling definitions via the Cuneiform REST API.
+     *
+     * Each definition is created individually since the REST endpoint
+     * currently supports single creation per request.
+     *
+     * @param inputs - Array of definition inputs (1-10 items)
+     * @returns ServiceResult containing succeeded and failed arrays
+     */
+    async createDefinitions(inputs) {
+        const startTime = Date.now();
+        const emptyResult = { succeeded: [], failed: [] };
+        if (!this.restAdapter) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_CREATE_FAILED, 'restAdapter is required for create operations.', { metadata: { duration: Date.now() - startTime } });
+        }
+        return this.createDefinitionsViaRest(inputs, startTime);
+    }
+    /**
+     * Updates metadata attributes on a profiling definition.
+     *
+     * Writes only the supplied attributes; untouched columns are preserved.
+     * At least one attribute must be provided.
+     *
+     * @param definitionId - The Salesforce record ID of the definition to update
+     * @param attributes - Partial attribute set to write
+     * @returns ServiceResult containing the update result
+     */
+    async updateAttributes(definitionId, attributes) {
+        const startTime = Date.now();
+        const emptyResult = { id: definitionId, updated: false, updatedAttributes: [] };
+        // Validate definition ID
+        const idError = validateSalesforceId(definitionId);
+        if (idError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_INVALID_ID, idError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        // Check that REST adapter is configured
+        if (!this.restAdapter) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_UPDATE_FAILED, 'REST adapter required for update operations', { metadata: { duration: Date.now() - startTime } });
+        }
+        // Build the partial update payload — only supplied attributes
+        // eslint-disable-next-line camelcase -- Salesforce custom field API names require this casing
+        const payload = {};
+        const updatedAttributes = [];
+        if (attributes.name !== undefined) {
+            // eslint-disable-next-line camelcase -- Salesforce custom field API name
+            payload.pnova__Prop_Name__c = attributes.name;
+            updatedAttributes.push('name');
+        }
+        if (attributes.category !== undefined) {
+            // eslint-disable-next-line camelcase -- Salesforce custom field API name
+            payload.pnova__Prop_Category__c = attributes.category;
+            updatedAttributes.push('category');
+        }
+        if (attributes.timeCategory !== undefined) {
+            // eslint-disable-next-line camelcase -- Salesforce custom field API name
+            payload.pnova__Prop_TimeCategory__c = attributes.timeCategory;
+            updatedAttributes.push('timeCategory');
+        }
+        if (attributes.segmentCategory !== undefined) {
+            // eslint-disable-next-line camelcase -- Salesforce custom field API name
+            payload.pnova__Prop_SegmentCategory__c = attributes.segmentCategory;
+            updatedAttributes.push('segmentCategory');
+        }
+        if (attributes.description !== undefined) {
+            // eslint-disable-next-line camelcase -- Salesforce custom field API name
+            payload.pnova__Prop_Description__c = attributes.description;
+            updatedAttributes.push('description');
+        }
+        try {
+            this.logger?.log(`Updating definition ${definitionId}: ${updatedAttributes.join(', ')}`);
+            const updateResult = await this.restAdapter.updateRecord('pnova__Profiling_Definition__c', definitionId, payload);
+            const duration = Date.now() - startTime;
+            if (!updateResult.success) {
+                this.logger?.log(`Definition attribute update failed: ${updateResult.message ?? 'Unknown error'}`);
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_UPDATE_FAILED, updateResult.message ?? 'Definition attribute update failed', { metadata: { duration } });
+            }
+            this.logger?.log(`Definition ${definitionId} attributes updated successfully`);
+            return createSuccessResult({ id: definitionId, updated: true, updatedAttributes }, {
+                message: `Updated definition attributes: ${updatedAttributes.join(', ')}`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Definition attribute update failed: ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_UPDATE_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Deletes profiling definitions by their Salesforce IDs.
+     *
+     * Safety checks are applied before deletion:
+     * - Definition must exist
+     * - Definition must have no associated summaries (hasRelatedSummaries field)
+     *
+     * Definitions can be deleted regardless of profiling status when no
+     * associated summaries exist.
+     *
+     * Definitions that fail safety checks are skipped with reasons provided.
+     *
+     * @param ids - Array of Salesforce record IDs to delete (1-200 items)
+     * @param options - Optional progress callback and configuration
+     * @returns ServiceResult containing deletion counts and skip/failure details
+     */
+    async deleteDefinitions(ids, options) {
+        const startTime = Date.now();
+        const emptyResult = {
+            deleted: 0,
+            skipped: 0,
+            failed: 0,
+            skipReasons: [],
+            failures: [],
+        };
+        // Validate ids array is not empty
+        if (ids.length === 0) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_DELETE_FAILED, 'Definition IDs array cannot be empty', { metadata: { duration: Date.now() - startTime } });
+        }
+        // Validate REST adapter is available
+        if (!this.restAdapter) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_DELETE_FAILED, 'REST adapter required for delete operations', { metadata: { duration: Date.now() - startTime } });
+        }
+        // Validate all IDs have valid format
+        for (const id of ids) {
+            const idError = validateSalesforceId(id);
+            if (idError) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_INVALID_ID, `Invalid ID "${id}": ${idError}`, {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+        }
+        const result = {
+            deleted: 0,
+            skipped: 0,
+            failed: 0,
+            skipReasons: [],
+            failures: [],
+        };
+        const total = ids.length;
+        let current = 0;
+        // Process each ID sequentially - intentional for safe deletion with proper error handling
+        // Each operation depends on the previous (safety checks before delete)
+        // eslint-disable-next-line no-await-in-loop -- Sequential processing for safe deletion with individual error handling
+        for (const id of ids) {
+            current++;
+            try {
+                // Look up the definition
+                // eslint-disable-next-line no-await-in-loop -- Sequential: must verify existence before deletion
+                const lookupResult = await this.getDefinitionById(id);
+                if (!lookupResult.success) {
+                    result.failed++;
+                    result.failures.push({
+                        id,
+                        error: lookupResult.message ?? 'Failed to lookup definition',
+                    });
+                    options?.onProgress?.({ id, name: id, status: 'failed', reason: 'lookup_failed', current, total });
+                    continue;
+                }
+                // Check if definition exists
+                if (lookupResult.data === null) {
+                    result.skipped++;
+                    result.skipReasons.push({
+                        id,
+                        reason: 'not_found',
+                    });
+                    options?.onProgress?.({ id, name: id, status: 'skipped', reason: 'not_found', current, total });
+                    continue;
+                }
+                const definition = lookupResult.data;
+                const defMeta = {
+                    key: definition.key,
+                    objectName: definition.objectName,
+                    objectLabel: definition.objectLabel,
+                    category: definition.category,
+                    timeCategory: definition.timeCategory,
+                    segmentCategory: definition.segmentCategory,
+                    profilingStatus: definition.status,
+                };
+                // Safety check: Check for associated summaries
+                // Use hasRelatedSummaries field (formula field on the definition object)
+                const hasSummaries = definition.hasRelatedSummaries === true;
+                if (hasSummaries) {
+                    result.skipped++;
+                    result.skipReasons.push({
+                        id,
+                        name: definition.name,
+                        reason: 'has_summaries',
+                    });
+                    options?.onProgress?.({
+                        id,
+                        ...defMeta,
+                        name: definition.name,
+                        status: 'skipped',
+                        reason: 'has_summaries',
+                        current,
+                        total,
+                    });
+                    continue;
+                }
+                // All safety checks passed - delete the definition
+                // eslint-disable-next-line no-await-in-loop -- Sequential: dependent on prior safety checks passing
+                const deleteResult = await this.restAdapter.deleteRecord('pnova__Profiling_Definition__c', id);
+                if (!deleteResult.success) {
+                    const deleteError = deleteResult.message ?? 'Failed to delete definition';
+                    result.failed++;
+                    result.failures.push({
+                        id,
+                        name: definition.name,
+                        error: deleteError,
+                    });
+                    options?.onProgress?.({
+                        id,
+                        ...defMeta,
+                        name: definition.name,
+                        status: 'failed',
+                        reason: deleteError,
+                        current,
+                        total,
+                    });
+                    continue;
+                }
+                result.deleted++;
+                this.logger?.log(`Deleted profiling definition: ${id}`);
+                options?.onProgress?.({ id, ...defMeta, name: definition.name, status: 'deleted', current, total });
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                result.failed++;
+                result.failures.push({
+                    id,
+                    error: errorMessage,
+                });
+                options?.onProgress?.({ id, name: id, status: 'failed', reason: errorMessage, current, total });
+            }
+        }
+        const duration = Date.now() - startTime;
+        const totalProcessed = result.deleted + result.skipped + result.failed;
+        const summaryMessage = `Deleted ${result.deleted}/${totalProcessed} definitions (${result.skipped} skipped, ${result.failed} failed)`;
+        this.logger?.log(summaryMessage);
+        return createSuccessResult(result, {
+            message: summaryMessage,
+            warnings: result.skipped > 0 || result.failed > 0 ? [`${result.skipped} skipped, ${result.failed} failed`] : undefined,
+            metadata: { duration },
+        });
+    }
+    /**
+     * Paginates through all definition pages for the given options.
+     * Returns partial success with warnings if pagination fails mid-stream after
+     * collecting at least one page; returns failure if the first page fails.
+     */
+    async fetchAllPages(options) {
+        const allDefinitions = [];
+        let offset = 0;
+        const pageSize = MAX_PAGINATION_LIMIT;
+        // eslint-disable-next-line no-constant-condition -- Pagination loop exits on short page or failure
+        while (true) {
+            // eslint-disable-next-line no-await-in-loop -- Sequential pagination: each page depends on knowing if more exist
+            const pageResult = await this.getDefinitions({ ...options, limit: pageSize, offset });
+            if (!pageResult.success) {
+                if (allDefinitions.length > 0) {
+                    this.logger?.log(`Pagination failed at offset ${offset}, using ${allDefinitions.length} definitions fetched so far`);
+                    return createSuccessResult(allDefinitions, {
+                        warnings: [`Pagination incomplete: failed at offset ${offset}. Results may be partial.`],
+                    });
+                }
+                return pageResult;
+            }
+            allDefinitions.push(...pageResult.data);
+            if (pageResult.data.length < pageSize) {
+                break;
+            }
+            offset += pageSize;
+        }
+        return createSuccessResult(allDefinitions);
+    }
+    /**
+     * Resolves the org's own NamespacePrefix via a single SOQL query.
+     * Returns undefined if the org has no namespace or if the query fails.
+     */
+    async getOrgNamespace() {
+        try {
+            const result = await this.soqlAdapter.query('SELECT NamespacePrefix FROM Organization LIMIT 1');
+            if (result.success && result.data.records.length > 0) {
+                return result.data.records[0].NamespacePrefix ?? undefined;
+            }
+        }
+        catch {
+            // Silently fall through — callers use the standard LIKE filter only
+        }
+        return undefined;
+    }
+    // NOTE: createDefinitionViaApex and createDefinitionsViaApex removed during REST API migration (CLI-1150).
+    // These methods used anonymous Apex routing via GlobalProfilingService and have been replaced
+    // by createDefinitionViaRest and createDefinitionsViaRest.
+    /**
+     * Creates a single definition via the Cuneiform REST API.
+     */
+    async createDefinitionViaRest(input, startTime) {
+        const emptyResult = null;
+        // Validate objectName
+        const objectNameError = validateObjectName(input.objectName);
+        if (objectNameError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_INVALID_OBJECT_NAME, objectNameError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        try {
+            this.logger?.log(`Creating profiling definition for object: ${input.objectName}`);
+            const requestBody = ProfilingDefinitionService.buildCreateDefinitionRequestBody(input);
+            const restResult = await this.restAdapter.request({
+                url: `${PROFILING_DEFINITION_REST_BASE}/create-definition`,
+                method: 'POST',
+                body: requestBody,
+            });
+            if (!restResult.success) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_CREATE_FAILED, restResult.message ?? 'REST API call failed', { metadata: { duration: Date.now() - startTime } });
+            }
+            const response = restResult.data;
+            if (!response.success) {
+                const errorMsg = response.errors && response.errors.length > 0 ? response.errors.join('; ') : 'Definition creation failed';
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_CREATE_FAILED, errorMsg, {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+            if (!response.results || response.results.length === 0) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_CREATE_FAILED, 'No results returned from profiling definition REST API', { metadata: { duration: Date.now() - startTime } });
+            }
+            const createdId = response.results[0].id;
+            this.logger?.log(`Created profiling definition with ID: ${createdId}`);
+            // Query back the full definition record
+            const queryResult = await this.getDefinitionById(createdId);
+            if (!queryResult.success || queryResult.data === null) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_CREATE_FAILED, queryResult.message ?? 'Failed to retrieve created definition', { metadata: { duration: Date.now() - startTime } });
+            }
+            const duration = Date.now() - startTime;
+            this.logger?.log(`Created profiling definition: ${queryResult.data.name} (${queryResult.data.key})`);
+            return createSuccessResult(queryResult.data, {
+                message: `Created profiling definition: ${queryResult.data.name}`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Failed to create profiling definition: ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_CREATE_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Creates multiple definitions via the Cuneiform REST API.
+     *
+     * The REST endpoint supports single creation, so definitions are created sequentially.
+     */
+    async createDefinitionsViaRest(inputs, startTime) {
+        const emptyResult = { succeeded: [], failed: [] };
+        if (inputs.length === 0) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_CREATE_FAILED, 'Inputs array must contain at least one definition.', { metadata: { duration: Date.now() - startTime } });
+        }
+        try {
+            this.logger?.log(`Creating ${inputs.length} profiling definitions via REST API`);
+            const succeeded = [];
+            const failed = [];
+            /* eslint-disable no-await-in-loop -- Sequential creation to avoid overwhelming the org */
+            for (const input of inputs) {
+                const result = await this.createDefinitionViaRest(input, Date.now());
+                if (result.success && result.data) {
+                    succeeded.push(result.data);
+                }
+                else {
+                    failed.push({
+                        input,
+                        error: result.message ?? 'Creation failed',
+                        errorCode: result.errorCode ?? ServiceErrorCodes.DEFINITION_CREATE_FAILED,
+                    });
+                }
+            }
+            /* eslint-enable no-await-in-loop */
+            const duration = Date.now() - startTime;
+            this.logger?.log(`Created ${succeeded.length}/${inputs.length} definitions (${failed.length} failed)`);
+            return createSuccessResult({ succeeded, failed }, {
+                message: `Created ${succeeded.length}/${inputs.length} definitions`,
+                warnings: failed.length > 0 ? [`${failed.length} definition(s) failed to create`] : undefined,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Bulk create operation failed: ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.DEFINITION_CREATE_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+}
+//# sourceMappingURL=ProfilingDefinitionService.js.map