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

package/lib/services/ObjectDescribeService.js

@@ -0,0 +1,869 @@
+/*
+ * 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 { CuneiformQueryBuilder } from '../adapters/soql/cuneiform-query-builder.js';
+import { createSuccessResult, createFailureResult } from '../models/service-result.js';
+import { ServiceErrorCodes, AdapterErrorCodes } from '../adapters/errors.js';
+import { validateRequiredString, validateObjectName } from './validation.js';
+/**
+ * Service for retrieving comprehensive object metadata with field analysis and profiling status.
+ *
+ * This service combines REST API describe results with optional enrichment from:
+ * - RecordTypeService: Record type information
+ * - ProfilingDefinitionService: Existing profiling definitions
+ * - ProfilingSummaryService: Profiling summary statistics
+ *
+ * Object Rejection Rules:
+ * - Big Objects (__b suffix) are rejected with E4805
+ * - External Objects (__x suffix) are rejected with E4806
+ *
+ * @example
+ * ```typescript
+ * const service = new ObjectDescribeService({
+ *   restApiAdapter,
+ *   soqlAdapter,
+ *   recordTypeService,
+ *   profilingDefinitionService,
+ *   profilingSummaryService,
+ * });
+ *
+ * const result = await service.describeObject('Account');
+ * if (result.success) {
+ *   console.log(`${result.data.objectName}: ${result.data.fieldClassification.totalFields} fields`);
+ * }
+ * ```
+ */
+export class ObjectDescribeService {
+    /** Lookup table for field type to display category mapping */
+    static FIELD_TYPE_MAP = {
+        string: 'Text',
+        textarea: 'Text',
+        url: 'Text',
+        email: 'Text',
+        phone: 'Text',
+        picklist: 'Picklist',
+        multipicklist: 'Picklist',
+        reference: 'Lookup',
+        double: 'Number',
+        currency: 'Number',
+        percent: 'Number',
+        int: 'Number',
+        date: 'Date/DateTime',
+        datetime: 'Date/DateTime',
+        time: 'Date/DateTime',
+        boolean: 'Checkbox',
+        id: 'ID',
+        address: 'Address',
+        location: 'Geolocation',
+    };
+    restApiAdapter;
+    soqlAdapter;
+    recordTypeService;
+    profilingDefinitionService;
+    profilingSummaryService;
+    logger;
+    restClient;
+    constructor(config) {
+        this.restApiAdapter = config.restApiAdapter;
+        this.soqlAdapter = config.soqlAdapter;
+        this.recordTypeService = config.recordTypeService;
+        this.profilingDefinitionService = config.profilingDefinitionService;
+        this.profilingSummaryService = config.profilingSummaryService;
+        this.logger = config.logger;
+        this.restClient = config.restClient;
+    }
+    /**
+     * Calculates field type distribution from an array of fields.
+     *
+     * @param fields - Array of DescribeFieldResult from object describe
+     * @returns ServiceResult containing array of FieldTypeCount sorted by count descending
+     */
+    static getFieldTypeDistribution(fields) {
+        const startTime = Date.now();
+        const emptyResult = [];
+        if (!fields || fields.length === 0) {
+            return createSuccessResult(emptyResult, {
+                message: 'No fields to analyze',
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        const typeCounts = new Map();
+        for (const field of fields) {
+            const displayType = ObjectDescribeService.mapFieldToDisplayType(field);
+            typeCounts.set(displayType, (typeCounts.get(displayType) ?? 0) + 1);
+        }
+        const totalFields = fields.length;
+        const distribution = [];
+        for (const [type, count] of typeCounts) {
+            const percent = Math.round((count / totalFields) * 1000) / 10;
+            distribution.push({ type, count, percent });
+        }
+        distribution.sort((a, b) => b.count - a.count);
+        return createSuccessResult(distribution, {
+            message: `Analyzed ${totalFields} fields across ${distribution.length} types`,
+            metadata: { duration: Date.now() - startTime },
+        });
+    }
+    /**
+     * Calculates namespace breakdown from an array of fields.
+     *
+     * @param fields - Array of DescribeFieldResult from object describe
+     * @returns ServiceResult containing array of NamespaceCount sorted by fieldCount descending
+     */
+    static getNamespaceBreakdown(fields) {
+        const startTime = Date.now();
+        const emptyResult = [];
+        if (!fields || fields.length === 0) {
+            return createSuccessResult(emptyResult, {
+                message: 'No fields to analyze',
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        const namespaceCounts = new Map();
+        for (const field of fields) {
+            const namespace = ObjectDescribeService.extractNamespace(field.name);
+            namespaceCounts.set(namespace, (namespaceCounts.get(namespace) ?? 0) + 1);
+        }
+        const breakdown = [];
+        for (const [namespace, fieldCount] of namespaceCounts) {
+            breakdown.push({ namespace, fieldCount });
+        }
+        breakdown.sort((a, b) => b.fieldCount - a.fieldCount);
+        return createSuccessResult(breakdown, {
+            message: `Found ${breakdown.length} namespaces across ${fields.length} fields`,
+            metadata: { duration: Date.now() - startTime },
+        });
+    }
+    /**
+     * Extracts external references from childRelationships array.
+     *
+     * External references represent objects that have lookup/master-detail
+     * relationships pointing TO this object.
+     *
+     * @param describeResult - The describe result containing childRelationships
+     * @returns Array of external references sorted alphabetically by object name
+     */
+    static extractExternalReferences(describeResult) {
+        if (!describeResult.childRelationships || describeResult.childRelationships.length === 0) {
+            return [];
+        }
+        const references = describeResult.childRelationships.map((rel) => ({
+            objectName: rel.childSObject,
+            fieldName: rel.field,
+            relationshipName: rel.relationshipName || null,
+        }));
+        // Sort alphabetically by object name for consistent output
+        return references.sort((a, b) => a.objectName.localeCompare(b.objectName));
+    }
+    /**
+     * Extracts lookup fields from fields array with their target objects.
+     *
+     * @param fields - Array of field describe results
+     * @returns Array of lookup field info sorted alphabetically by field name
+     */
+    static extractLookupFields(fields) {
+        if (!fields || fields.length === 0) {
+            return [];
+        }
+        const lookups = [];
+        for (const field of fields) {
+            if (field.referenceTo && field.referenceTo.length > 0) {
+                lookups.push({
+                    fieldName: field.name,
+                    label: field.label,
+                    targetObjects: field.referenceTo,
+                    relationshipName: field.relationshipName ?? null,
+                });
+            }
+        }
+        // Sort alphabetically by field name for consistent output
+        return lookups.sort((a, b) => a.fieldName.localeCompare(b.fieldName));
+    }
+    /**
+     * Detects if PersonAccount is enabled for the Account object.
+     *
+     * PersonAccount is detected by checking for the presence of the IsPersonAccount field,
+     * which only exists when PersonAccount is enabled in the org.
+     *
+     * @param objectName - The object being described
+     * @param fields - The fields from the describe result
+     * @returns true if PersonAccount is enabled (only for Account object), undefined otherwise
+     */
+    static detectPersonAccount(objectName, fields) {
+        // PersonAccount detection only applies to Account object
+        if (objectName !== 'Account') {
+            return undefined;
+        }
+        // Check for IsPersonAccount field - this field only exists when PersonAccount is enabled
+        return fields.some((field) => field.name === 'IsPersonAccount');
+    }
+    /**
+     * Builds a relationship summary from describe result.
+     *
+     * @param describeResult - The describe result
+     * @returns RelationshipSummary with external references and lookup fields
+     */
+    static buildRelationshipSummary(describeResult) {
+        const externalRefs = ObjectDescribeService.extractExternalReferences(describeResult);
+        const lookupFields = ObjectDescribeService.extractLookupFields(describeResult.fields);
+        return {
+            referencedByCount: externalRefs.length,
+            referencedBy: externalRefs,
+            lookupFields,
+        };
+    }
+    // ── Server Response Mapping (ISV REST API → CLI types) ────────────
+    /** Builds RelationshipSummary from server childRelationships + fields. */
+    static mapServerRelationships(childRels, fields) {
+        const referencedBy = childRels
+            .filter((cr) => cr.relationshipName != null)
+            .map((cr) => ({
+            objectName: cr.childSObject ?? '',
+            fieldName: cr.field ?? '',
+            relationshipName: cr.relationshipName ?? null,
+        }));
+        const lookupFields = fields
+            .filter((f) => f.referenceTo && f.referenceTo.length > 0)
+            .map((f) => ({
+            fieldName: f.name,
+            label: f.label,
+            targetObjects: f.referenceTo ?? [],
+            relationshipName: f.relationshipName ?? null,
+        }));
+        return { referencedByCount: referencedBy.length, referencedBy, lookupFields };
+    }
+    /** Maps server profilingStatus block to CLI ProfilingStatus. */
+    static mapServerProfilingStatus(ps) {
+        return {
+            hasDefinitions: (ps.definitionCount ?? 0) > 0,
+            definitionCount: ps.definitionCount ?? 0,
+            // Server returns minimal definition info ({name}); cast is safe because
+            // the command layer only reads .name from these entries (describe.ts:552)
+            definitions: ps.definitions
+                ? ps.definitions.map((d) => ({ name: d.name ?? '' }))
+                : undefined,
+            summaryCount: ps.summaryCount ?? 0,
+        };
+    }
+    /** Maps server recordTypeInfos to CLI RecordTypeInfo[], filtering out Master. */
+    static mapServerRecordTypes(rts, objectName) {
+        return rts
+            .filter((rt) => !rt.master)
+            .map((rt) => ({
+            id: rt.recordTypeId ?? '',
+            name: rt.name ?? '',
+            developerName: rt.developerName ?? '',
+            sobjectType: objectName,
+            isPersonType: false,
+            isActive: rt.active ?? true,
+            isDefault: rt.defaultRecordTypeMapping ?? false,
+            formattedReference: `${objectName}.${rt.developerName ?? rt.name ?? ''}`,
+        }));
+    }
+    /**
+     * Maps a Salesforce field type to a display category.
+     *
+     * @param field - The field describe result
+     * @returns Display category string
+     */
+    static mapFieldToDisplayType(field) {
+        if (field.calculated) {
+            return 'Formula';
+        }
+        return ObjectDescribeService.FIELD_TYPE_MAP[field.type] ?? field.type;
+    }
+    /**
+     * Extracts the namespace from a field API name.
+     *
+     * @param fieldName - The field API name (e.g., 'Name', 'Custom__c', 'pnova__Field__c')
+     * @returns The namespace (e.g., 'pnova') or null for standard/unmanaged fields
+     */
+    static extractNamespace(fieldName) {
+        const parts = fieldName.split('__');
+        if (parts.length >= 3) {
+            return parts[0];
+        }
+        return null;
+    }
+    /**
+     * Checks if the object is a Big Object (ends with __b).
+     *
+     * @param objectName - The object API name
+     * @returns true if it's a Big Object
+     */
+    static isBigObject(objectName) {
+        return objectName.endsWith('__b');
+    }
+    /**
+     * Checks if the object is an External Object (ends with __x).
+     *
+     * @param objectName - The object API name
+     * @returns true if it's an External Object
+     */
+    static isExternalObject(objectName) {
+        return objectName.endsWith('__x');
+    }
+    /**
+     * Classifies fields from a describe result.
+     *
+     * @param fields - Array of field describe results
+     * @returns Field classification statistics
+     */
+    static classifyFields(fields) {
+        let customFields = 0;
+        let formulaFields = 0;
+        let lookupFields = 0;
+        let requiredFields = 0;
+        let picklistFields = 0;
+        for (const field of fields) {
+            if (field.custom) {
+                customFields++;
+            }
+            if (field.calculated) {
+                formulaFields++;
+            }
+            if (field.referenceTo && field.referenceTo.length > 0) {
+                lookupFields++;
+            }
+            // Required: createable, not nillable, and no default value
+            if (field.createable && !field.nillable && field.defaultValue === undefined) {
+                requiredFields++;
+            }
+            if (field.type === 'picklist' || field.type === 'multipicklist') {
+                picklistFields++;
+            }
+        }
+        return {
+            totalFields: fields.length,
+            customFields,
+            formulaFields,
+            lookupFields,
+            requiredFields,
+            picklistFields,
+        };
+    }
+    /**
+     * Maps a DescribeSObjectResult to our ObjectDescribeResult base structure.
+     *
+     * @param describeResult - The raw describe result from REST API
+     * @returns ObjectDescribeResult without enrichment
+     */
+    static mapToObjectDescribeResult(describeResult) {
+        const result = {
+            objectName: describeResult.name,
+            label: describeResult.label,
+            labelPlural: describeResult.labelPlural,
+            isCustom: describeResult.custom,
+            isQueryable: describeResult.queryable,
+            isCreateable: describeResult.createable,
+            isUpdateable: describeResult.updateable,
+            isDeletable: describeResult.deletable,
+            isSearchable: describeResult.searchable,
+            fieldClassification: ObjectDescribeService.classifyFields(describeResult.fields),
+            fields: describeResult.fields,
+            relationships: ObjectDescribeService.buildRelationshipSummary(describeResult),
+        };
+        // Add PersonAccount detection for Account object
+        const isPersonAccountEnabled = ObjectDescribeService.detectPersonAccount(describeResult.name, describeResult.fields);
+        if (isPersonAccountEnabled !== undefined) {
+            result.isPersonAccountEnabled = isPersonAccountEnabled;
+        }
+        return result;
+    }
+    /**
+     * Creates an empty result for failure cases.
+     *
+     * @param objectName - The object name for the empty result
+     * @returns Empty ObjectDescribeResult
+     */
+    static createEmptyResult(objectName) {
+        return {
+            objectName,
+            label: '',
+            labelPlural: '',
+            isCustom: false,
+            isQueryable: false,
+            isCreateable: false,
+            isUpdateable: false,
+            isDeletable: false,
+            isSearchable: false,
+            fieldClassification: {
+                totalFields: 0,
+                customFields: 0,
+                formulaFields: 0,
+                lookupFields: 0,
+                requiredFields: 0,
+                picklistFields: 0,
+            },
+            fields: [],
+        };
+    }
+    /**
+     * Extracts a meaningful message from an unknown error.
+     *
+     * Handles the edge case where Error instances have an empty message
+     * but a meaningful name property (e.g., sinon's rejects behavior).
+     *
+     * @param error - The error to extract a message from
+     * @returns A human-readable error message
+     */
+    static getErrorMessage(error) {
+        if (error instanceof Error) {
+            // Prefer message, fall back to name if message is empty
+            return error.message || error.name || 'Unknown error';
+        }
+        return String(error);
+    }
+    /**
+     * Applies RecordTypeId filter to a query builder.
+     * Single string uses `=`, array uses `IN`.
+     * The builder auto-promotes to first WHERE if no prior condition exists.
+     *
+     * @param builder - The query builder to modify
+     * @param recordTypeIds - Single ID, array of IDs, or undefined (no filter)
+     */
+    static applyRecordTypeFilter(builder, recordTypeIds) {
+        if (!recordTypeIds)
+            return;
+        if (typeof recordTypeIds === 'string') {
+            builder.andWhere('RecordTypeId', '=', recordTypeIds);
+        }
+        else if (recordTypeIds.length > 0) {
+            builder.andWhereIn('RecordTypeId', recordTypeIds);
+        }
+    }
+    /**
+     * Describes a Salesforce object with comprehensive metadata and optional enrichment.
+     *
+     * This method:
+     * 1. Validates the object name
+     * 2. Rejects Big Objects (__b) and External Objects (__x)
+     * 3. Retrieves describe metadata via REST API
+     * 4. Classifies fields (custom, formula, lookup, required, picklist)
+     * 5. Enriches with record types, record age, and profiling status (in parallel)
+     *
+     * @param objectName - The Salesforce object API name (e.g., 'Account', 'Custom_Object__c')
+     * @returns ServiceResult containing the ObjectDescribeResult
+     */
+    async describeObject(objectName) {
+        const startTime = Date.now();
+        const emptyResult = ObjectDescribeService.createEmptyResult(objectName ?? '');
+        // Validate required
+        const requiredError = validateRequiredString(objectName, 'Object name');
+        if (requiredError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_DESCRIBE_OBJECT_NAME_REQUIRED, requiredError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        // Validate format
+        const formatError = validateObjectName(objectName);
+        if (formatError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_DESCRIBE_INVALID_OBJECT_NAME, formatError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        // Reject Big Objects
+        if (ObjectDescribeService.isBigObject(objectName)) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_DESCRIBE_BIG_OBJECT_REJECTED, `Big Objects are not supported: ${objectName}`, { metadata: { duration: Date.now() - startTime } });
+        }
+        // Reject External Objects
+        if (ObjectDescribeService.isExternalObject(objectName)) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_DESCRIBE_EXTERNAL_OBJECT_REJECTED, `External Objects are not supported: ${objectName}`, { metadata: { duration: Date.now() - startTime } });
+        }
+        // REST API path: delegate to server when restClient is available
+        if (this.restClient) {
+            return this.describeObjectViaRest(objectName, startTime);
+        }
+        try {
+            this.logger?.log(`Describing object: ${objectName}`);
+            // Get base describe result
+            const describeResult = await this.restApiAdapter.describeObject(objectName);
+            if (!describeResult.success) {
+                // Map adapter error codes to service error codes
+                let serviceErrorCode = ServiceErrorCodes.OBJECT_DESCRIBE_FAILED;
+                if (describeResult.errorCode === AdapterErrorCodes.OBJECT_NOT_FOUND) {
+                    serviceErrorCode = ServiceErrorCodes.OBJECT_DESCRIBE_NOT_FOUND;
+                }
+                else if (describeResult.errorCode === AdapterErrorCodes.PERMISSION_DENIED) {
+                    serviceErrorCode = ServiceErrorCodes.OBJECT_DESCRIBE_PERMISSION_DENIED;
+                }
+                return createFailureResult(emptyResult, serviceErrorCode, describeResult.message ?? 'Object describe failed', {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+            // Map to our result structure
+            const result = ObjectDescribeService.mapToObjectDescribeResult(describeResult.data);
+            const warnings = [];
+            // Parallel enrichment with catch-per-promise for graceful degradation
+            // Note: Record age is NOT enriched here — the command calls getRecordAgeDistribution()
+            // separately, which provides a superset of the data (year-by-year distribution + oldest date).
+            // Enriching here would duplicate 2 SOQL queries per object with no benefit.
+            const enrichmentPromises = [
+                // Record type enrichment
+                this.enrichRecordTypes(objectName).catch((error) => {
+                    warnings.push(`Record type enrichment failed: ${ObjectDescribeService.getErrorMessage(error)}`);
+                    return undefined;
+                }),
+                // Profiling status enrichment
+                this.enrichProfilingStatus(objectName).catch((error) => {
+                    warnings.push(`Profiling status enrichment failed: ${ObjectDescribeService.getErrorMessage(error)}`);
+                    return undefined;
+                }),
+            ];
+            const [recordTypes, profilingStatus] = await Promise.all(enrichmentPromises);
+            // Apply enrichments
+            if (recordTypes !== undefined) {
+                result.recordTypes = recordTypes;
+            }
+            if (profilingStatus !== undefined) {
+                result.profilingStatus = profilingStatus;
+            }
+            const duration = Date.now() - startTime;
+            this.logger?.log(`Described ${objectName}: ${result.fieldClassification.totalFields} fields, ` +
+                `${result.fieldClassification.customFields} custom, ${result.fieldClassification.formulaFields} formula`);
+            return createSuccessResult(result, {
+                message: `Described ${objectName} with ${result.fieldClassification.totalFields} fields`,
+                warnings: warnings.length > 0 ? warnings : undefined,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Object describe failed for ${objectName}: ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_DESCRIBE_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Describes multiple Salesforce objects in parallel.
+     *
+     * @param objectNames - Array of Salesforce object API names to describe
+     * @returns ServiceResult containing array of ObjectDescribeResult (one per successful describe)
+     */
+    async describeMultiple(objectNames) {
+        const startTime = Date.now();
+        const emptyResult = [];
+        if (!objectNames || objectNames.length === 0) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.INVALID_OBJECT_NAMES, 'At least one object name is required', { metadata: { duration: Date.now() - startTime } });
+        }
+        const describePromises = objectNames.map(async (objectName) => {
+            const result = await this.describeObject(objectName);
+            return { objectName, result };
+        });
+        const results = await Promise.all(describePromises);
+        const successResults = [];
+        const failureWarnings = [];
+        for (const { objectName, result } of results) {
+            if (result.success) {
+                successResults.push(result.data);
+            }
+            else {
+                failureWarnings.push(`${objectName}: ${result.message ?? 'Describe failed'}`);
+            }
+        }
+        const duration = Date.now() - startTime;
+        if (successResults.length === 0) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_DESCRIBE_FAILED, `All object describes failed: ${failureWarnings.join('; ')}`, { metadata: { duration } });
+        }
+        return createSuccessResult(successResults, {
+            message: `Described ${successResults.length} of ${objectNames.length} objects`,
+            warnings: failureWarnings.length > 0 ? failureWarnings : undefined,
+            metadata: { duration },
+        });
+    }
+    /**
+     * Retrieves record age distribution for an object showing year-by-year record existence.
+     *
+     * @param objectName - The Salesforce object API name
+     * @param recordTypeIds - Optional RecordTypeId(s) to filter. Single string uses `=`, array uses `IN`.
+     * @returns ServiceResult containing RecordAgeDistribution with year-by-year status
+     */
+    async getRecordAgeDistribution(objectName, recordTypeIds) {
+        const startTime = Date.now();
+        const currentYear = new Date().getFullYear();
+        const years = [currentYear, currentYear - 1, currentYear - 2, currentYear - 3];
+        const emptyResult = {
+            years: years.map((year) => ({ year, hasRecords: false })),
+            oldestRecordDate: null,
+        };
+        const requiredError = validateRequiredString(objectName, 'Object name');
+        if (requiredError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_DESCRIBE_OBJECT_NAME_REQUIRED, requiredError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        const formatError = validateObjectName(objectName);
+        if (formatError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_DESCRIBE_INVALID_OBJECT_NAME, formatError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        try {
+            const yearCheckPromises = years.map(async (year) => {
+                const builder = CuneiformQueryBuilder.create()
+                    .select(['Id'])
+                    .from(objectName)
+                    .whereDatetime('CreatedDate', '>=', `${year}-01-01T00:00:00Z`)
+                    .andWhereDatetime('CreatedDate', '<', `${year + 1}-01-01T00:00:00Z`);
+                ObjectDescribeService.applyRecordTypeFilter(builder, recordTypeIds);
+                const query = builder.limit(1).toSOQL();
+                const result = await this.soqlAdapter.query(query);
+                return { year, hasRecords: result.success && result.data.records.length > 0 };
+            });
+            const oldestBuilder = CuneiformQueryBuilder.create().select(['CreatedDate']).from(objectName);
+            ObjectDescribeService.applyRecordTypeFilter(oldestBuilder, recordTypeIds);
+            const oldestRecordQuery = oldestBuilder.orderBy('CreatedDate', 'ASC').limit(1).toSOQL();
+            const oldestRecordPromise = this.soqlAdapter.query(oldestRecordQuery);
+            const [yearChecks, oldestResult] = await Promise.all([Promise.all(yearCheckPromises), oldestRecordPromise]);
+            const yearStatusMap = new Map(yearChecks.map((yc) => [yc.year, yc.hasRecords]));
+            const distribution = {
+                years: years.map((year) => ({ year, hasRecords: yearStatusMap.get(year) ?? false })),
+                oldestRecordDate: oldestResult.success && oldestResult.data.records.length > 0
+                    ? oldestResult.data.records[0].CreatedDate
+                    : null,
+            };
+            return createSuccessResult(distribution, {
+                message: `Retrieved record age distribution for ${objectName}`,
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Record age distribution failed for ${objectName}: ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_DESCRIBE_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Retrieves business processes for a specific object with their record type IDs.
+     *
+     * Only Opportunity, Case, and Lead support business processes. For other objects,
+     * returns an empty array without issuing any queries.
+     *
+     * @param objectName - The Salesforce object API name
+     * @param recordTypes - Record types already enriched (used to cross-reference BusinessProcessId)
+     * @returns ServiceResult containing array of ObjectBusinessProcessInfo
+     */
+    async getBusinessProcesses(objectName, recordTypes) {
+        const startTime = Date.now();
+        const emptyResult = [];
+        const requiredError = validateRequiredString(objectName, 'Object name');
+        if (requiredError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_DESCRIBE_OBJECT_NAME_REQUIRED, requiredError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        try {
+            const bpQuery = CuneiformQueryBuilder.create()
+                .select(['Id', 'Name', 'IsActive'])
+                .from('BusinessProcess')
+                .where('SobjectType', '=', objectName)
+                .orderBy('Name', 'ASC')
+                .toSOQL();
+            const bpResult = await this.soqlAdapter.query(bpQuery);
+            if (!bpResult.success) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_DESCRIBE_FAILED, bpResult.message ?? 'BusinessProcess query failed', { metadata: { duration: Date.now() - startTime } });
+            }
+            const bpRecords = bpResult.data.records;
+            if (bpRecords.length === 0) {
+                return createSuccessResult(emptyResult, {
+                    message: `No business processes for ${objectName}`,
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+            // Cross-reference record types by BusinessProcessId
+            const processes = bpRecords.map((bp) => {
+                const linkedRtIds = recordTypes.filter((rt) => rt.businessProcessId === bp.Id).map((rt) => rt.id);
+                return {
+                    id: bp.Id,
+                    name: bp.Name,
+                    isActive: bp.IsActive,
+                    recordTypeCount: linkedRtIds.length,
+                    recordTypeIds: linkedRtIds,
+                };
+            });
+            return createSuccessResult(processes, {
+                message: `Found ${processes.length} business processes for ${objectName}`,
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Business process query failed for ${objectName}: ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_DESCRIBE_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Delegates object describe to the ISV REST API.
+     *
+     * @param objectName - The Salesforce object API name to describe
+     * @param startTime - Timestamp for duration tracking
+     * @returns ServiceResult containing ObjectDescribeResult from REST endpoint
+     */
+    async describeObjectViaRest(objectName, startTime) {
+        this.logger?.log(`Delegating object describe to ISV REST API (describe-object): ${objectName}`);
+        const emptyResult = ObjectDescribeService.createEmptyResult(objectName);
+        const restResult = await this.restClient.describeObject(objectName, {
+            includeRecordAge: true,
+            includeFieldDistribution: true,
+            withFields: true,
+            withRelationships: true,
+            withProfilingStatus: true,
+        });
+        if (!restResult.success) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_DESCRIBE_FAILED, restResult.message ?? 'REST describe-object failed', { metadata: { duration: Date.now() - startTime } });
+        }
+        const response = restResult.data;
+        if (!response.success) {
+            const errorMsg = response.errors?.length ? response.errors[0] : 'Server-side describe failed';
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_DESCRIBE_FAILED, errorMsg, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        const server = response.result;
+        if (!server) {
+            return createSuccessResult(emptyResult, {
+                message: `Object ${objectName} described via REST API (empty result)`,
+                metadata: { duration: Date.now() - startTime, strategyUsed: 'rest-api' },
+            });
+        }
+        let result = {
+            objectName: server.objectName ?? objectName,
+            label: server.label ?? objectName,
+            labelPlural: server.labelPlural ?? objectName,
+            isCustom: server.isCustom ?? false,
+            isQueryable: server.isQueryable ?? true,
+            isCreateable: false,
+            isUpdateable: false,
+            isDeletable: false,
+            isSearchable: server.isSearchable ?? false,
+            fieldClassification: server.fieldClassification ?? {
+                totalFields: 0,
+                customFields: 0,
+                formulaFields: 0,
+                lookupFields: 0,
+                requiredFields: 0,
+                picklistFields: 0,
+            },
+            fields: server.fields ?? [],
+            recordTypes: server.recordTypeInfos
+                ? ObjectDescribeService.mapServerRecordTypes(server.recordTypeInfos, objectName)
+                : undefined,
+            relationships: server.childRelationships
+                ? ObjectDescribeService.mapServerRelationships(server.childRelationships, server.fields ?? [])
+                : undefined,
+            profilingStatus: server.profilingStatus
+                ? ObjectDescribeService.mapServerProfilingStatus(server.profilingStatus)
+                : undefined,
+            isPersonAccountEnabled: server.isPersonAccountEnabled,
+        };
+        result = {
+            ...result,
+            fields: await this.resolveFieldFallback(result.fields, result.fieldClassification.totalFields, objectName),
+        };
+        const duration = Date.now() - startTime;
+        this.logger?.log(`Described ${objectName} via REST: ${result.fieldClassification.totalFields} fields, ` +
+            `${result.fieldClassification.customFields} custom`);
+        return createSuccessResult(result, {
+            message: `Object ${objectName} described via REST API`,
+            metadata: { duration, strategyUsed: 'rest-api' },
+        });
+    }
+    /**
+     * Falls back to standard REST describe for fields when ISV REST API
+     * returns field counts but omits the individual field array.
+     *
+     * @returns The field array to use (original or fallback)
+     */
+    async resolveFieldFallback(fields, totalFields, objectName) {
+        if (fields.length > 0 || totalFields === 0)
+            return fields;
+        this.logger?.log(`ISV REST API returned no fields for ${objectName}; falling back to standard describe`);
+        const standardDescribe = await this.restApiAdapter.describeObject(objectName);
+        return standardDescribe.success ? standardDescribe.data.fields : fields;
+    }
+    /**
+     * Enriches record type information using RecordTypeService.
+     * Errors are propagated to the caller for centralized handling.
+     *
+     * @param objectName - The object API name
+     * @returns Array of RecordTypeInfo or undefined if not configured or query fails gracefully
+     * @throws Error if service call throws
+     */
+    async enrichRecordTypes(objectName) {
+        if (!this.recordTypeService) {
+            return undefined;
+        }
+        const result = await this.recordTypeService.getRecordTypes(objectName);
+        if (result.success) {
+            return result.data;
+        }
+        this.logger?.log(`Record type enrichment failed for ${objectName}: ${result.message ?? 'Unknown error'}`);
+        return undefined;
+    }
+    /**
+     * Enriches profiling status using ProfilingDefinitionService and ProfilingSummaryService.
+     * Errors are propagated to the caller for centralized handling.
+     *
+     * @param objectName - The object API name
+     * @returns ProfilingStatus or undefined if not configured or query fails gracefully
+     * @throws Error if service call throws
+     */
+    async enrichProfilingStatus(objectName) {
+        if (!this.profilingDefinitionService) {
+            return undefined;
+        }
+        const definitionsResult = await this.profilingDefinitionService.getDefinitions({ objectName });
+        if (!definitionsResult.success) {
+            this.logger?.log(`Profiling definition enrichment failed for ${objectName}: ${definitionsResult.message ?? 'Unknown error'}`);
+            return undefined;
+        }
+        const definitions = definitionsResult.data;
+        const status = {
+            hasDefinitions: definitions.length > 0,
+            definitionCount: definitions.length,
+            definitions: definitions.length > 0 ? definitions : undefined,
+        };
+        // If we have definitions and a summary service, get summary info
+        if (definitions.length > 0 && this.profilingSummaryService) {
+            let totalSummaryCount = 0;
+            let lastProfiledDate;
+            // Query summaries for each definition in parallel
+            const summaryPromises = definitions.map(async (def) => {
+                try {
+                    const summaryResult = await this.profilingSummaryService.getSummaries({
+                        definitionId: def.id,
+                        limit: 1,
+                    });
+                    if (summaryResult.success && summaryResult.data.length > 0) {
+                        return summaryResult.data[0];
+                    }
+                    return null;
+                }
+                catch {
+                    return null;
+                }
+            });
+            const summaries = await Promise.all(summaryPromises);
+            const validSummaries = summaries.filter((s) => s !== null);
+            if (validSummaries.length > 0) {
+                totalSummaryCount = validSummaries.length;
+                // Find the most recent summary by creation date
+                const sortedByDate = [...validSummaries].sort((a, b) => new Date(b.createdDate).getTime() - new Date(a.createdDate).getTime());
+                lastProfiledDate = sortedByDate[0].createdDate;
+            }
+            status.summaryCount = totalSummaryCount;
+            status.lastProfiledDate = lastProfiledDate;
+        }
+        return status;
+    }
+}
+//# sourceMappingURL=ObjectDescribeService.js.map