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

package/lib/operations/DefinitionUpdateOperation.js

@@ -0,0 +1,142 @@
+/*
+ * 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.
+ */
+/**
+ * Error codes specific to update operations.
+ */
+export const UpdateErrorCodes = {
+    /** Invalid options provided (missing ID or fields) */
+    INVALID_OPTIONS: 'UPDATE_INVALID_OPTIONS',
+    /** Update operation failed */
+    UPDATE_FAILED: 'UPDATE_FAILED',
+};
+/**
+ * Orchestrates the update of profiling definition metadata attributes.
+ *
+ * Follows the 4-layer architecture: Command → Operation → Service → API
+ * This operation layer handles business logic orchestration while delegating
+ * the actual update to ProfilingDefinitionService.
+ *
+ * @example
+ * ```typescript
+ * const operation = new DefinitionUpdateOperation(definitionService);
+ * const result = await operation.execute({
+ *   definitionId: 'a00000000000001AAA',
+ *   attributes: { name: 'New Name', category: 'Revenue' }
+ * });
+ * ```
+ */
+export class DefinitionUpdateOperation {
+    definitionService;
+    logger;
+    /**
+     * Creates a new DefinitionUpdateOperation.
+     *
+     * @param definitionService - The ProfilingDefinitionService instance for executing updates
+     * @param logger - Optional logger for debug output
+     */
+    constructor(definitionService, logger) {
+        this.definitionService = definitionService;
+        this.logger = logger;
+    }
+    /**
+     * Validates the update options.
+     *
+     * @param options - The update options to validate
+     * @returns Error message if invalid, undefined if valid
+     */
+    static validateOptions(options) {
+        if (!options.definitionId || options.definitionId.trim() === '') {
+            return 'Definition ID is required';
+        }
+        const { attributes } = options;
+        const hasAny = attributes.name !== undefined ||
+            attributes.category !== undefined ||
+            attributes.timeCategory !== undefined ||
+            attributes.segmentCategory !== undefined ||
+            attributes.description !== undefined;
+        if (!hasAny) {
+            return 'At least one attribute must be supplied (name, category, timeCategory, segmentCategory, description)';
+        }
+        return undefined;
+    }
+    /**
+     * Executes the update operation.
+     *
+     * Returns a ServiceResult with success=false and one of the following error codes on failure:
+     * - INVALID_OPTIONS: Missing ID or no attributes supplied
+     * - UPDATE_FAILED: When the underlying service update fails
+     *
+     * @param options - Update options
+     * @returns ServiceResult containing update results or error details
+     */
+    async execute(options) {
+        const startTime = Date.now();
+        // Validate options
+        const validationError = DefinitionUpdateOperation.validateOptions(options);
+        if (validationError) {
+            return {
+                success: false,
+                data: {
+                    definitionId: options.definitionId || '',
+                    updated: false,
+                    updatedAttributes: [],
+                },
+                errorCode: UpdateErrorCodes.INVALID_OPTIONS,
+                message: validationError,
+                metadata: { duration: Date.now() - startTime },
+            };
+        }
+        try {
+            this.logger?.log(`Updating definition ${options.definitionId} attributes`);
+            const updateResult = await this.definitionService.updateAttributes(options.definitionId, options.attributes);
+            const duration = Date.now() - startTime;
+            if (!updateResult.success) {
+                this.logger?.log(`Definition attribute update failed: ${updateResult.message ?? 'Unknown error'}`);
+                return {
+                    success: false,
+                    data: {
+                        definitionId: options.definitionId,
+                        updated: false,
+                        updatedAttributes: [],
+                    },
+                    errorCode: UpdateErrorCodes.UPDATE_FAILED,
+                    message: updateResult.message ?? 'Definition attribute update failed',
+                    metadata: { duration },
+                };
+            }
+            this.logger?.log(`Successfully updated definition ${options.definitionId}`);
+            return {
+                success: true,
+                data: {
+                    definitionId: options.definitionId,
+                    updated: true,
+                    updatedAttributes: updateResult.data.updatedAttributes,
+                },
+                message: `Successfully updated definition attributes: ${updateResult.data.updatedAttributes.join(', ')}`,
+                metadata: { duration },
+            };
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Definition attribute update failed: ${errorMessage}`);
+            return {
+                success: false,
+                data: {
+                    definitionId: options.definitionId,
+                    updated: false,
+                    updatedAttributes: [],
+                },
+                errorCode: UpdateErrorCodes.UPDATE_FAILED,
+                message: `Definition attribute update failed: ${errorMessage}`,
+                metadata: { duration },
+            };
+        }
+    }
+}
+//# sourceMappingURL=DefinitionUpdateOperation.js.map

package/lib/operations/DefinitionUpdateOperation.js.map

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

package/lib/operations/OrgDetailsOperation.d.ts

@@ -0,0 +1,253 @@
+import type { ServiceResult } from '../models/service-result.js';
+import { OrgInfoService, type OrgLimit, type OrgType } from '../services/OrgInfoService.js';
+/**
+ * Cloud item in the org details result.
+ */
+export type CloudItem = {
+    name: string;
+    type: 'license' | 'package';
+    installed: boolean;
+    totalLicenses?: number;
+    usedLicenses?: number;
+    namespace?: string;
+    version?: string;
+    status?: string;
+};
+/**
+ * Namespace detail item in the org details result.
+ */
+export type NamespaceDetailItem = {
+    prefix: string;
+    productName: string;
+    objectCount: number;
+    populatedCount: number;
+    emptyCount: number;
+};
+/**
+ * Business process item in the org details result.
+ */
+export type ProcessItem = {
+    name: string;
+    objectName: string;
+    isActive: boolean;
+    description?: string;
+    recordTypeCount: number;
+    recordTypeNames: string[];
+};
+/**
+ * A single limit item for grouped display.
+ */
+export type LimitItem = {
+    name: string;
+    label: string;
+    max: number;
+    used: number;
+    percentUsed: number;
+};
+/**
+ * A group of related limits with a category label.
+ */
+export type LimitGroup = {
+    key: string;
+    label: string;
+    limits: LimitItem[];
+};
+/**
+ * Result returned by OrgDetailsOperation and the org details command.
+ */
+export type OrgDetailsResult = {
+    /** Org identity information */
+    identity: {
+        orgId: string;
+        orgName: string;
+        orgType: OrgType;
+        edition: string;
+        namespace: string | null;
+        instanceUrl: string;
+        username: string;
+    };
+    /** Cuneiform for Salesforce installation status */
+    cuneiform: {
+        installed: boolean;
+        version: string | null;
+        licenseStatus: string;
+    };
+    /** Detected org features */
+    features: {
+        multiCurrency: boolean;
+        enhancedNotes: boolean;
+        stateCountryPicklists: boolean;
+        territoryManagement: boolean;
+        personAccounts: boolean;
+        digitalExperiences: boolean;
+        einsteinAI: boolean;
+    };
+    /** Detected Salesforce Clouds (includes uninstalled for JSON completeness) */
+    clouds: {
+        count: number;
+        details: CloudItem[];
+    };
+    /** Installed namespace summary */
+    namespaces: {
+        count: number;
+        details: NamespaceDetailItem[];
+    };
+    /** Business processes with record type associations */
+    processes: {
+        count: number;
+        details: ProcessItem[];
+    };
+    /** API limits (omitted if limits call failed) */
+    limits?: {
+        dailyApiRequests?: {
+            max: number;
+            used: number;
+            percentUsed: number;
+        };
+        dataStorageMB?: {
+            max: number;
+            used: number;
+            percentUsed: number;
+        };
+        fileStorageMB?: {
+            max: number;
+            used: number;
+            percentUsed: number;
+        };
+        dailyBulkApiRequests?: {
+            max: number;
+            used: number;
+            percentUsed: number;
+        };
+        dailyBulkV2QueryJobs?: {
+            max: number;
+            used: number;
+            percentUsed: number;
+        };
+        dailyAsyncApexExecutions?: {
+            max: number;
+            used: number;
+            percentUsed: number;
+        };
+        dailyStreamingApiEvents?: {
+            max: number;
+            used: number;
+            percentUsed: number;
+        };
+        /** All limits grouped by category for `limits-all` / `limits-<group>` display */
+        groups: LimitGroup[];
+    };
+    /** Non-fatal warnings collected during execution */
+    warnings?: string[];
+    /** R-11: Sections included in this result (self-describing for MCP consumers) */
+    sections: OrgDetailsSection[];
+};
+/**
+ * Error codes for OrgDetailsOperation failures.
+ */
+export declare const OrgDetailsErrorCodes: {
+    /** Failed to retrieve org identity — operation cannot continue */
+    readonly IDENTITY_FAILED: "ORG_DETAILS_IDENTITY_FAILED";
+};
+/**
+ * Valid section names for selective retrieval.
+ */
+export type OrgDetailsSection = 'identity' | 'cuneiform' | 'features' | 'clouds' | 'namespaces' | 'processes' | 'limits';
+/**
+ * Configuration for OrgDetailsOperation.
+ */
+export type OrgDetailsOperationConfig = {
+    /** Initialized OrgInfoService instance */
+    orgInfoService: OrgInfoService;
+    /** Connection instance URL for the identity section */
+    instanceUrl: string;
+    /** Optional list of sections to retrieve. When omitted, all sections are retrieved. */
+    sections?: string[];
+};
+/**
+ * Orchestrates retrieval and assembly of org details.
+ *
+ * Calls describeGlobal() once and passes the cached result to the three
+ * service methods that require it (features, clouds, namespaces), eliminating
+ * redundant API calls and enforcing the 4-layer architecture boundary.
+ *
+ * @example
+ * ```typescript
+ * const operation = new OrgDetailsOperation({ orgInfoService, instanceUrl });
+ * const result = await operation.execute();
+ * if (result.success) {
+ *   console.log(result.data.identity.orgName);
+ * }
+ * ```
+ */
+export declare class OrgDetailsOperation {
+    /**
+     * Limit group definitions mapping Salesforce limit names to display categories.
+     * Limits not matching any group are placed in 'other'.
+     */
+    private static readonly LIMIT_GROUP_DEFS;
+    /** All valid section names in display order. */
+    private static readonly ALL_SECTIONS;
+    private readonly orgInfoService;
+    private readonly instanceUrl;
+    private readonly sections;
+    constructor(config: OrgDetailsOperationConfig);
+    /**
+     * Groups all limits by category, producing LimitGroup arrays.
+     * Limits not matching any defined group are placed in 'other'.
+     */
+    static groupLimits(allLimits: Record<string, OrgLimit>): LimitGroup[];
+    /**
+     * Converts a Salesforce limit API name to a human-readable label.
+     * Inserts spaces before uppercase letters and handles common suffixes.
+     */
+    private static humanizeLimit;
+    /**
+     * Collects warnings from non-critical service failures and result warnings.
+     */
+    private static collectWarnings;
+    /**
+     * Formats an OrgLimit for result output.
+     */
+    private static formatLimit;
+    /**
+     * Returns an empty OrgFeatures object for error fallback.
+     */
+    private static emptyFeatures;
+    /**
+     * Extracts data from service results, falling back to empty defaults on failure.
+     */
+    private static extractServiceData;
+    /**
+     * Returns an empty OrgDetailsResult for error fallback.
+     */
+    private static buildEmptyResult;
+    /**
+     * Returns stub success results for sections that are skipped.
+     */
+    private static skippedResults;
+    /**
+     * Executes the org details retrieval.
+     *
+     * Calls fetchDescribeGlobal() once, then fans out to all service methods
+     * in parallel. Identity failure is fatal; all other failures degrade
+     * gracefully to empty data with warnings.
+     *
+     * @returns ServiceResult containing the assembled OrgDetailsResult
+     */
+    execute(): Promise<ServiceResult<OrgDetailsResult>>;
+    /**
+     * Builds the OrgDetailsResult from resolved service data.
+     */
+    private buildResult;
+    /**
+     * Returns the list of sections included in this result.
+     */
+    private getIncludedSections;
+    /**
+     * Returns true if the given section should be retrieved.
+     * When no sections filter is set, all sections are included.
+     * For 'limits', also triggers on 'limits-all' and 'limits-<group>' variants.
+     */
+    private needsSection;
+}