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

package/lib/services/ProfilingSummaryService.d.ts

@@ -0,0 +1,292 @@
+import type { ISoqlQueryAdapter } from '../adapters/soql/soql-query-adapter.js';
+import type { IRestApiAdapter, DeleteRecordResult } from '../adapters/rest/rest-api-adapter.js';
+import type { ServiceResult } from '../models/service-result.js';
+import type { SummaryDeletionStatus } from '../models/status-types.js';
+import type { BulkSummaryResult } from '../models/summary-bulk-types.js';
+/**
+ * Terminal overall statuses for `pnova__Agg_OverallStatus__c` — used by purge SOQL filters.
+ *
+ * The ISV populates this field from Custom Labels with exactly 3 values:
+ * IN PROGRESS, COMPLETED, FAILED. Terminal = profiling work is done.
+ *
+ * NOTE: This is NOT the same as PFx_Status__c (which has SUCCESS, CANCELED, etc.).
+ * See docs/knowledge/cuneiform/profiling-request-status-reference.md Section 2.4.
+ */
+export declare const TERMINAL_SUMMARY_STATUSES: readonly ["COMPLETED", "FAILED"];
+/**
+ * Represents a profiling summary record for purge display.
+ * Contains summary-level aggregate fields rather than field-level statistics.
+ */
+export type PurgeSummaryRecord = {
+    /** The summary record ID */
+    id: string;
+    /** Summary key (auto-number, e.g., PS-0001) */
+    summaryKey: string;
+    /** The parent profiling definition ID */
+    definitionId: string;
+    /** The parent definition key (auto-number, e.g., PD-0001) */
+    definitionKey: string;
+    /** The Salesforce object API name */
+    objectName: string;
+    /** Total number of records profiled */
+    totalRecordsProfiled: number;
+    /** Number of fields profiled */
+    profiledFields: number;
+    /** Last profiled date (ISO 8601) */
+    lastProfiledDate: string | null;
+    /** Whether this is the latest summary for its definition */
+    isLatest: boolean;
+    /** Overall profiling status */
+    overallStatus: string;
+};
+/**
+ * Options for querying summaries for purge.
+ */
+export type GetSummariesForPurgeOptions = {
+    /** Definition IDs whose summaries to query */
+    definitionIds: string[];
+    /** Only include non-latest summaries (prune mode) */
+    pruneOnly?: boolean;
+};
+/**
+ * Progress event emitted during summary deletion.
+ */
+export type SummaryDeleteProgressEvent = {
+    /** The summary record ID */
+    id: string;
+    /** Summary key (auto-number) */
+    summaryKey: string;
+    /** Parent definition key */
+    definitionKey: string;
+    /** Object API name */
+    objectName: string;
+    /** Deletion status */
+    status: SummaryDeletionStatus;
+    /** Reason for skip or failure */
+    reason?: string;
+    /** Current index (1-based) */
+    current: number;
+    /** Total items to process */
+    total: number;
+};
+/**
+ * Result of a summary deletion batch.
+ */
+export type SummaryDeleteResult = {
+    /** Number successfully deleted */
+    deleted: number;
+    /** Number skipped */
+    skipped: number;
+    /** Number that failed */
+    failed: number;
+    /** Skip reasons */
+    skipReasons: Array<{
+        id: string;
+        summaryKey: string;
+        reason: string;
+    }>;
+    /** Failure details */
+    failures: Array<{
+        id: string;
+        summaryKey: string;
+        error: string;
+    }>;
+};
+/**
+ * Configuration for ProfilingSummaryService.
+ */
+export type IProfilingSummaryServiceConfig = {
+    /** SOQL query adapter for executing queries */
+    soqlAdapter: ISoqlQueryAdapter;
+    /** REST API adapter for delete operations (required for purge) */
+    restAdapter?: IRestApiAdapter;
+    /** Optional logger for debug output */
+    logger?: Console;
+};
+/**
+ * Represents a profiling summary record returned by the summary list tool.
+ * Contains summary-level aggregate fields for one profiling run.
+ */
+export type SummaryRecord = {
+    /** The summary record ID */
+    id: string;
+    /** Summary key (auto-number, e.g., PS-0001) */
+    summaryKey: string;
+    /** The parent profiling definition ID */
+    definitionId: string;
+    /** The parent definition key (auto-number, e.g., PD-0001) */
+    definitionKey: string;
+    /** The Salesforce object API name */
+    objectName: string;
+    /** Total number of records profiled */
+    totalRecordsProfiled: number;
+    /** Number of fields profiled */
+    profiledFields: number;
+    /** Date the summary record was created (ISO 8601) */
+    createdDate: string;
+    /** Whether this is the latest summary for its definition */
+    isLatest: boolean;
+    /** Overall profiling status */
+    overallStatus: string;
+};
+/**
+ * Options for retrieving profiling summaries.
+ */
+export type GetSummariesOptions = {
+    /** The parent profiling definition ID (required) */
+    definitionId: string;
+    /** Maximum number of records to return (default: 50, max: 200) */
+    limit?: number;
+    /** Number of records to skip for pagination */
+    offset?: number;
+};
+/**
+ * Domain service for querying Profiling_SObject_Results__c records.
+ *
+ * Provides methods to retrieve profiling summary data by definition ID
+ * or by individual summary ID, with support for pagination.
+ *
+ * @example
+ * ```typescript
+ * const service = new ProfilingSummaryService({ soqlAdapter });
+ * const result = await service.getSummaries({ definitionId: '001000000000001AAA' });
+ * if (result.success) {
+ *   result.data.forEach(s => console.log(`${s.fieldName}: ${s.populatedPercent}%`));
+ * }
+ * ```
+ */
+export declare class ProfilingSummaryService {
+    private readonly soqlAdapter;
+    private readonly restAdapter?;
+    private readonly logger?;
+    constructor(config: IProfilingSummaryServiceConfig);
+    /**
+     * Maps a raw Salesforce list query record to a SummaryRecord.
+     */
+    private static mapToSummaryRecord;
+    /**
+     * Maps a raw Salesforce purge query record to a PurgeSummaryRecord.
+     */
+    private static mapToPurgeSummaryRecord;
+    /**
+     * Parses the bulk API response into a typed BulkSummaryResult.
+     *
+     * Shared by stopSummaries and reprofileSummaries to reduce duplication.
+     *
+     * @param response - The raw API response
+     * @param failureCode - The error code to use on complete failure
+     * @param startTime - Operation start time for duration calculation
+     * @returns ServiceResult with parsed BulkSummaryResult
+     */
+    private static parseBulkResponse;
+    /**
+     * Retrieves profiling summaries for a given definition ID.
+     *
+     * @param options - Query options including definitionId, limit, and offset
+     * @returns ServiceResult containing an array of SummaryRecord
+     */
+    getSummaries(options: GetSummariesOptions): Promise<ServiceResult<SummaryRecord[]>>;
+    /**
+     * Retrieves a single profiling summary by its ID.
+     *
+     * @param id - The Salesforce ID of the Profiling_SObject_Results__c record
+     * @returns ServiceResult containing the SummaryRecord or null if not found
+     */
+    getSummaryById(id: string): Promise<ServiceResult<SummaryRecord | null>>;
+    /**
+     * Retrieves profiling summaries eligible for purge, filtered by parent definition IDs.
+     *
+     * Queries summary-level aggregate fields for display in the purge confirmation table.
+     * Only returns summaries with terminal profiling statuses (COMPLETED, FAILED).
+     * When pruneOnly is true, additionally filters to non-latest summaries only.
+     *
+     * @param options - Query options including definitionIds and optional pruneOnly flag
+     * @returns ServiceResult containing an array of PurgeSummaryRecord
+     */
+    getSummariesForPurge(options: GetSummariesForPurgeOptions): Promise<ServiceResult<PurgeSummaryRecord[]>>;
+    /**
+     * Retrieves specific profiling summaries by their IDs.
+     *
+     * Queries summaries directly by ID with terminal status filter.
+     * More efficient than getSummariesForPurge when specific IDs are known,
+     * as it avoids fetching all definitions first.
+     *
+     * @param ids - Array of Salesforce summary record IDs
+     * @returns ServiceResult containing matching PurgeSummaryRecord array
+     */
+    getSummariesByIds(ids: string[]): Promise<ServiceResult<PurgeSummaryRecord[]>>;
+    /**
+     * Deletes a single profiling summary record.
+     *
+     * Requires the restAdapter to be configured.
+     *
+     * @param id - The Salesforce ID of the summary to delete
+     * @returns ServiceResult containing the delete result
+     */
+    deleteSummary(id: string): Promise<ServiceResult<DeleteRecordResult>>;
+    /**
+     * Deletes multiple profiling summaries sequentially.
+     *
+     * Processes one summary at a time for reliability and progress tracking.
+     * Continues on individual failures, reporting results per summary.
+     *
+     * @param summaries - The summary records to delete
+     * @param onProgress - Optional progress callback
+     * @returns ServiceResult containing deletion statistics
+     */
+    deleteSummaries(summaries: PurgeSummaryRecord[], onProgress?: (event: SummaryDeleteProgressEvent) => void): Promise<ServiceResult<SummaryDeleteResult>>;
+    /**
+     * Queries which Salesforce objects have successful metadata profiling results.
+     *
+     * Returns unique object API names from Profiling_SObject_Results__c where
+     * metadata-only profiling has been completed with records profiled.
+     *
+     * @returns ServiceResult containing an array of unique object API names
+     */
+    queryProfiledObjects(): Promise<ServiceResult<string[]>>;
+    /**
+     * Retrieves in-progress profiling summaries eligible for stopping.
+     *
+     * Queries summaries with IN_PROGRESS_SUMMARY_STATUSES (IN PROGRESS).
+     * Optionally filters by object name.
+     *
+     * @param options - Optional filter by object names
+     * @returns ServiceResult containing matching PurgeSummaryRecord array
+     */
+    getInProgressSummaries(options?: {
+        objectNames?: string[];
+    }): Promise<ServiceResult<PurgeSummaryRecord[]>>;
+    /**
+     * Retrieves failed or stopped profiling summaries eligible for re-profiling.
+     *
+     * Queries summaries with REPROFILABLE_SUMMARY_STATUSES (FAILED).
+     * Optionally filters by object name.
+     *
+     * @param options - Optional filter by object names
+     * @returns ServiceResult containing matching PurgeSummaryRecord array
+     */
+    getReprofilableSummaries(options?: {
+        objectNames?: string[];
+    }): Promise<ServiceResult<PurgeSummaryRecord[]>>;
+    /**
+     * Stops in-progress profiling summaries via the ISV REST API.
+     *
+     * Sends a PATCH request to `/services/apexrest/pnova/v1/profiling/summaries`
+     * with `{ summariesToStop: [...ids] }`. Deduplicates IDs before sending.
+     *
+     * @param summaryIds - Array of summary record IDs to stop
+     * @returns ServiceResult containing per-item results with summary counts
+     */
+    stopSummaries(summaryIds: string[]): Promise<ServiceResult<BulkSummaryResult>>;
+    /**
+     * Reprofiles failed or stopped profiling summaries via the ISV REST API.
+     *
+     * Sends a POST request to `/services/apexrest/pnova/v1/profiling/summaries/reprofile`
+     * with `{ summariesToReprofile: [...ids] }`. Deduplicates IDs before sending.
+     * Response includes a `requestId` per item on success (HTTP 201).
+     *
+     * @param summaryIds - Array of summary record IDs to reprofile
+     * @returns ServiceResult containing per-item results with summary counts
+     */
+    reprofileSummaries(summaryIds: string[]): Promise<ServiceResult<BulkSummaryResult>>;
+}