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

package/lib/adapters/rest/profiling-rest-client.d.ts

@@ -0,0 +1,137 @@
+import type { ServiceResult } from '../../models/service-result.js';
+import type { DateLiteralRange } from '../../models/date-literal.js';
+import type { IRestApiAdapter } from './rest-api-adapter.js';
+/**
+ * Standard response envelope from the ISV REST API.
+ */
+export type ProfilingRestResponse<T = unknown> = {
+    success: boolean;
+    results?: T;
+    result?: T;
+    summary?: Record<string, number>;
+    errors: string[];
+};
+/**
+ * Smart definition creation request payload.
+ */
+export type SmartCreateRequest = {
+    objects: Array<{
+        name: string;
+        label: string;
+    }>;
+    method: string;
+    options: {
+        category?: string;
+        timeCategory?: string;
+        segmentCategory?: string;
+        year?: number;
+        usePrior?: boolean;
+        noValueFrequency?: boolean;
+        namePrefix?: string;
+        nameSuffix?: string;
+        origin?: string;
+        recordType?: string;
+        description?: string;
+        dryRun?: boolean;
+        dateLiteralRange?: DateLiteralRange;
+        yearEntries?: Array<{
+            year: number;
+            unbounded: boolean;
+        }>;
+    };
+};
+/**
+ * Per-definition result from the smart creation endpoint.
+ */
+export type SmartCreateDefinitionResult = {
+    objectName: string;
+    definitionName: string;
+    definitionId?: string;
+    definitionKey?: string;
+    status: 'created' | 'skipped' | 'failed' | 'preview';
+    errorMessage?: string;
+    fieldCount?: number;
+    type?: string;
+    category?: string;
+    timeCategory?: string;
+    segmentCategory?: string;
+};
+/**
+ * Object filter request payload.
+ */
+export type FilterObjectsRequest = {
+    type?: string;
+    namespace?: string;
+    excludeSystemObjects?: boolean;
+    namePattern?: string;
+    nameOperator?: string;
+    classification?: string;
+    hasRecordTypes?: boolean;
+    withOwner?: boolean;
+    limit?: number;
+};
+/**
+ * Thin REST client for calling Cuneiform ISV profiling endpoints.
+ * Wraps the existing IRestApiAdapter.request<T>() method with typed payloads.
+ *
+ * @example
+ * ```typescript
+ * const client = new ProfilingRestClient(restAdapter);
+ * const result = await client.createSmart({
+ *   objects: [{ name: 'Account', label: 'Account' }],
+ *   method: 'metadata',
+ *   options: { dryRun: true }
+ * });
+ * ```
+ */
+export declare class ProfilingRestClient {
+    private readonly restAdapter;
+    constructor(restAdapter: IRestApiAdapter);
+    /**
+     * Calls the smart definition creation endpoint.
+     * Server handles naming, categorization, deduplication, and creation.
+     */
+    createSmart(request: SmartCreateRequest): Promise<ServiceResult<ProfilingRestResponse<SmartCreateDefinitionResult[]>>>;
+    /**
+     * Calls the object filtering endpoint.
+     * Server applies cost-optimized multi-criteria filter chain.
+     */
+    filterObjects(request: FilterObjectsRequest): Promise<ServiceResult<ProfilingRestResponse>>;
+    /**
+     * Calls the object describe endpoint.
+     */
+    describeObject(objectName: string, options?: {
+        includeRecordAge?: boolean;
+        includeFieldDistribution?: boolean;
+        withFields?: boolean;
+        withRelationships?: boolean;
+        withProfilingStatus?: boolean;
+    }): Promise<ServiceResult<ProfilingRestResponse>>;
+    /**
+     * Calls the data availability grid endpoint.
+     */
+    getDataAvailability(objects: string[], years: number[]): Promise<ServiceResult<ProfilingRestResponse>>;
+    /**
+     * Calls the user readiness endpoint.
+     */
+    checkUserReadiness(userId?: string): Promise<ServiceResult<ProfilingRestResponse>>;
+    /**
+     * Calls the org info endpoint.
+     */
+    getOrgInfo(): Promise<ServiceResult<ProfilingRestResponse>>;
+    /**
+     * Calls the user-configure endpoint (ConfigurationProfileResource).
+     * Separate REST resource at /v1/profiling/configuration/.
+     */
+    configureUser(options: {
+        userId?: string;
+        enableApiOnlyProfiling?: boolean;
+        enableRegistration?: boolean;
+        profileDeveloperName?: string;
+        dryRun?: boolean;
+    }): Promise<ServiceResult<ProfilingRestResponse>>;
+    /**
+     * Generic POST to a profiling REST action.
+     */
+    private post;
+}

package/lib/adapters/rest/profiling-rest-client.js

@@ -0,0 +1,115 @@
+/*
+ * 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';
+/**
+ * REST API base URL for Cuneiform profiling endpoints.
+ * All actions are routed via POST to this URL with the action as the last path segment.
+ */
+// Apex urlMapping is '/v1/profiling/*' — Salesforce auto-prepends namespace (pnova)
+const PROFILING_REST_BASE = '/services/apexrest/pnova/v1/profiling';
+/**
+ * Thin REST client for calling Cuneiform ISV profiling endpoints.
+ * Wraps the existing IRestApiAdapter.request<T>() method with typed payloads.
+ *
+ * @example
+ * ```typescript
+ * const client = new ProfilingRestClient(restAdapter);
+ * const result = await client.createSmart({
+ *   objects: [{ name: 'Account', label: 'Account' }],
+ *   method: 'metadata',
+ *   options: { dryRun: true }
+ * });
+ * ```
+ */
+export class ProfilingRestClient {
+    restAdapter;
+    constructor(restAdapter) {
+        this.restAdapter = restAdapter;
+    }
+    /**
+     * Calls the smart definition creation endpoint.
+     * Server handles naming, categorization, deduplication, and creation.
+     */
+    async createSmart(request) {
+        return this.post('create-smart', request);
+    }
+    /**
+     * Calls the object filtering endpoint.
+     * Server applies cost-optimized multi-criteria filter chain.
+     */
+    async filterObjects(request) {
+        return this.post('filter-objects', request);
+    }
+    /**
+     * Calls the object describe endpoint.
+     */
+    async describeObject(objectName, options) {
+        return this.post('describe-object', {
+            objectName,
+            ...options,
+        });
+    }
+    /**
+     * Calls the data availability grid endpoint.
+     */
+    async getDataAvailability(objects, years) {
+        return this.post('data-availability', { objects, years });
+    }
+    /**
+     * Calls the user readiness endpoint.
+     */
+    async checkUserReadiness(userId) {
+        return this.post('user-readiness', { userId });
+    }
+    /**
+     * Calls the org info endpoint.
+     */
+    async getOrgInfo() {
+        return this.post('org-info', {});
+    }
+    /**
+     * Calls the user-configure endpoint (ConfigurationProfileResource).
+     * Separate REST resource at /v1/profiling/configuration/.
+     */
+    async configureUser(options) {
+        const startTime = Date.now();
+        const result = await this.restAdapter.request({
+            url: '/services/apexrest/pnova/v1/profiling/configuration',
+            method: 'POST',
+            body: JSON.stringify(options),
+            headers: { 'content-type': 'application/json' },
+        });
+        if (!result.success) {
+            return createFailureResult(result.data, result.errorCode ?? 'REST_API_ERROR', result.message ?? 'REST API call to user-configure failed', { metadata: { duration: Date.now() - startTime } });
+        }
+        return createSuccessResult(result.data, {
+            message: 'User configuration completed via REST API',
+            metadata: { duration: Date.now() - startTime },
+        });
+    }
+    /**
+     * Generic POST to a profiling REST action.
+     */
+    async post(action, body) {
+        const startTime = Date.now();
+        const result = await this.restAdapter.request({
+            url: `${PROFILING_REST_BASE}/${action}`,
+            method: 'POST',
+            body: JSON.stringify(body),
+            headers: { 'content-type': 'application/json' },
+        });
+        if (!result.success) {
+            return createFailureResult(result.data, result.errorCode ?? 'REST_API_ERROR', result.message ?? `REST API call to ${action} failed`, { metadata: { duration: Date.now() - startTime } });
+        }
+        return createSuccessResult(result.data, {
+            message: `REST API call to ${action} succeeded`,
+            metadata: { duration: Date.now() - startTime },
+        });
+    }
+}
+//# sourceMappingURL=profiling-rest-client.js.map

package/lib/adapters/rest/profiling-rest-client.js.map

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

package/lib/adapters/rest/rest-api-adapter.d.ts

@@ -0,0 +1,389 @@
+import type { IConnectionFacade, DescribeSObjectResult, DescribeGlobalResult, HttpRequest } from '../connection-facade.js';
+import type { ServiceResult } from '../../models/service-result.js';
+import type { RestApiAdapterConfig } from './types.js';
+/**
+ * Result type for successful record insert operations.
+ */
+export type InsertRecordResult = {
+    /** The ID of the newly created record */
+    id: string;
+};
+/**
+ * Result type for successful record update operations.
+ */
+export type UpdateRecordResult = {
+    /** The ID of the updated record */
+    id: string;
+    /** Whether the update succeeded */
+    success: boolean;
+};
+/**
+ * Result type for successful record delete operations.
+ */
+export type DeleteRecordResult = {
+    /** The ID of the deleted record */
+    id: string;
+    /** Whether the delete succeeded */
+    success: boolean;
+};
+/**
+ * Interface for REST API operations.
+ *
+ * Provides methods for describing Salesforce objects with caching support,
+ * and writing sObject records.
+ */
+export type IRestApiAdapter = {
+    /**
+     * Describes a single Salesforce object.
+     *
+     * @param objectName - The API name of the object
+     * @returns ServiceResult containing the describe result
+     */
+    describeObject(objectName: string): Promise<ServiceResult<DescribeSObjectResult>>;
+    /**
+     * Retrieves global describe information for all accessible objects.
+     *
+     * @returns ServiceResult containing the global describe result
+     */
+    describeGlobal(): Promise<ServiceResult<DescribeGlobalResult>>;
+    /**
+     * Gets the record count for a Salesforce object.
+     *
+     * @param objectName - The API name of the object
+     * @returns ServiceResult containing the record count
+     */
+    getRecordCount(objectName: string): Promise<ServiceResult<number>>;
+    /**
+     * Gets record counts for multiple Salesforce objects using the bulk REST endpoint.
+     *
+     * Uses `GET /limits/recordCount?sObjects=...` for a single API call instead of
+     * N individual SOQL COUNT() queries. Falls back to per-object SOQL queries if
+     * the REST endpoint fails. Cached counts are resolved first; only uncached
+     * objects are included in the REST call.
+     *
+     * @param objectNames - Array of object API names
+     * @returns ServiceResult containing Map of object name to count
+     *
+     * @example
+     * ```typescript
+     * const result = await adapter.getRecordCounts(['Account', 'Contact', 'Lead']);
+     * if (result.success) {
+     *   for (const [name, count] of result.data) {
+     *     console.log(`${name}: ${count} records`);
+     *   }
+     * }
+     * ```
+     */
+    getRecordCounts(objectNames: string[]): Promise<ServiceResult<Map<string, number>>>;
+    /**
+     * Describes multiple Salesforce objects.
+     *
+     * @param objectNames - Array of object API names
+     * @returns ServiceResult containing a map of object names to describe results
+     */
+    describeObjects(objectNames: string[]): Promise<ServiceResult<Map<string, DescribeSObjectResult>>>;
+    /**
+     * Inserts a new record into a Salesforce object.
+     *
+     * Uses the REST API POST /sobjects/{objectName} endpoint.
+     *
+     * @param objectName - The API name of the object (e.g., 'Account', 'PermissionSetAssignment')
+     * @param record - The field values for the new record
+     * @returns ServiceResult containing the created record's ID
+     *
+     * @example
+     * ```typescript
+     * // Insert a PermissionSetAssignment record
+     * const result = await adapter.insertRecord('PermissionSetAssignment', {
+     *   AssigneeId: '005xx000001234567',
+     *   PermissionSetId: '0PS000000000001'
+     * });
+     * if (result.success) {
+     *   console.log(`Created record: ${result.data.id}`);
+     * }
+     * ```
+     */
+    insertRecord(objectName: string, record: Record<string, unknown>): Promise<ServiceResult<InsertRecordResult>>;
+    /**
+     * Updates an existing record in a Salesforce object.
+     *
+     * Uses the REST API PATCH /sobjects/{objectName}/{recordId} endpoint.
+     *
+     * @param objectName - The API name of the object (must use pnova__ namespace, e.g., 'pnova__Profiling_Definition__c')
+     * @param recordId - The ID of the record to update
+     * @param record - The field values to update
+     * @returns ServiceResult containing the update result with record ID and success status
+     *
+     * @example
+     * ```typescript
+     * // Update a Cuneiform record
+     * const result = await adapter.updateRecord('pnova__Profiling_Definition__c', '001xx000003DKMPAA4', {
+     *   pnova__Prop_Name__c: 'Updated Definition',
+     * });
+     * if (result.success) {
+     *   console.log(`Updated record: ${result.data.id}`);
+     * }
+     * ```
+     */
+    updateRecord(objectName: string, recordId: string, record: Record<string, unknown>): Promise<ServiceResult<UpdateRecordResult>>;
+    /**
+     * Deletes a record from a Salesforce object.
+     *
+     * Uses the REST API DELETE /sobjects/{objectName}/{recordId} endpoint.
+     *
+     * @param objectName - The API name of the object (must use pnova__ namespace, e.g., 'pnova__Profiling_Summary__c')
+     * @param recordId - The ID of the record to delete
+     * @returns ServiceResult containing the delete result with record ID and success status
+     *
+     * @example
+     * ```typescript
+     * // Delete a Cuneiform record
+     * const result = await adapter.deleteRecord('pnova__Profiling_Summary__c', '003xx000004TMJQAA4');
+     * if (result.success) {
+     *   console.log(`Deleted record: ${result.data.id}`);
+     * }
+     * ```
+     */
+    deleteRecord(objectName: string, recordId: string): Promise<ServiceResult<DeleteRecordResult>>;
+    /**
+     * Makes a generic HTTP request to a custom Salesforce REST endpoint.
+     *
+     * Supports custom Apex REST endpoints (e.g., `/services/apexrest/pnova/v1/...`)
+     * and any other Salesforce REST API path. Unlike the typed methods above,
+     * this provides a pass-through for arbitrary request/response shapes.
+     *
+     * @param request - The HTTP request configuration (url, method, body, headers)
+     * @returns ServiceResult containing the deserialized response of type T
+     *
+     * @example
+     * ```typescript
+     * // Call a custom Apex REST endpoint
+     * const result = await adapter.request<{ success: boolean; results: Array<{ id: string }> }>({
+     *   url: '/services/apexrest/pnova/v1/profiling/requests',
+     *   method: 'POST',
+     *   body: JSON.stringify({ id: definitionId }),
+     *   headers: { 'content-type': 'application/json' },
+     * });
+     * ```
+     */
+    request<T>(request: HttpRequest): Promise<ServiceResult<T>>;
+    /**
+     * Invalidates cached entries.
+     *
+     * @param pattern - Optional pattern to match keys (supports * wildcard). If not provided, clears all entries.
+     */
+    invalidateCache(pattern?: string): void;
+};
+/**
+ * Adapter for REST API operations against Salesforce.
+ *
+ * Provides caching for describe operations to reduce API calls.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new RestApiAdapter(connectionFacade);
+ *
+ * // Describe an object (cached)
+ * const result = await adapter.describeObject('Account');
+ *
+ * // Get global describe (cached)
+ * const global = await adapter.describeGlobal();
+ *
+ * // Describe multiple objects
+ * const describes = await adapter.describeObjects(['Account', 'Contact', 'Opportunity']);
+ *
+ * // Invalidate cache
+ * adapter.invalidateCache('describe:Account');  // Single object
+ * adapter.invalidateCache('describe:*');         // All describes
+ * adapter.invalidateCache();                     // Everything
+ * ```
+ */
+export declare class RestApiAdapter implements IRestApiAdapter {
+    private readonly connection;
+    private readonly logger?;
+    private readonly cache;
+    private readonly cacheEnabled;
+    private readonly lifecycle;
+    private readonly retryConfig?;
+    private readonly recordCountBatchSize;
+    /**
+     * Creates a new RestApiAdapter.
+     *
+     * @param connection - The connection facade to use for API calls
+     * @param config - Optional configuration
+     */
+    constructor(connection: IConnectionFacade, config?: RestApiAdapterConfig);
+    /**
+     * Validates that a write operation targets a permitted object.
+     *
+     * Only objects with the pnova__ namespace prefix are allowed for all write operations.
+     * A small set of standard objects (WRITE_ALLOWLIST) are allowed for specific operations.
+     *
+     * @param objectName - The API name of the target object
+     * @param operation - The write operation type
+     * @returns undefined if allowed, or an error code and message if blocked
+     */
+    private static validateWriteNamespace;
+    /**
+     * Describes a single Salesforce object.
+     *
+     * @param objectName - The API name of the object
+     * @returns ServiceResult containing the describe result
+     */
+    describeObject(objectName: string): Promise<ServiceResult<DescribeSObjectResult>>;
+    /**
+     * Retrieves global describe information for all accessible objects.
+     *
+     * @returns ServiceResult containing the global describe result
+     */
+    describeGlobal(): Promise<ServiceResult<DescribeGlobalResult>>;
+    /**
+     * Gets the record count for a Salesforce object.
+     *
+     * @param objectName - The API name of the object
+     * @returns ServiceResult containing the record count
+     */
+    getRecordCount(objectName: string): Promise<ServiceResult<number>>;
+    /**
+     * Describes multiple Salesforce objects.
+     *
+     * @param objectNames - Array of object API names
+     * @returns ServiceResult containing a map of object names to describe results
+     */
+    describeObjects(objectNames: string[]): Promise<ServiceResult<Map<string, DescribeSObjectResult>>>;
+    /**
+     * Gets record counts for multiple Salesforce objects using the bulk REST endpoint.
+     *
+     * Uses `GET /limits/recordCount?sObjects=A,B,C` for a single API call instead of
+     * N individual SOQL `SELECT COUNT()` queries. Falls back to per-object SOQL queries
+     * if the REST endpoint is unavailable or fails.
+     *
+     * Counts from the bulk response are cached individually so subsequent
+     * `getRecordCount()` calls benefit from the same cache.
+     *
+     * @param objectNames - Array of object API names
+     * @returns ServiceResult containing Map of object name to count
+     */
+    getRecordCounts(objectNames: string[]): Promise<ServiceResult<Map<string, number>>>;
+    /**
+     * Inserts a new record into a Salesforce object.
+     *
+     * Uses the REST API POST /sobjects/{objectName} endpoint to create a record.
+     * Does not use caching since write operations should always execute.
+     *
+     * @param objectName - The API name of the object (e.g., 'Account', 'PermissionSetAssignment')
+     * @param record - The field values for the new record
+     * @returns ServiceResult containing the created record's ID
+     *
+     * @example
+     * ```typescript
+     * const result = await adapter.insertRecord('PermissionSetAssignment', {
+     *   AssigneeId: '005xx000001234567',
+     *   PermissionSetId: '0PS000000000001'
+     * });
+     * ```
+     */
+    insertRecord(objectName: string, record: Record<string, unknown>): Promise<ServiceResult<InsertRecordResult>>;
+    /**
+     * Updates an existing record in a Salesforce object.
+     *
+     * Uses the REST API PATCH /sobjects/{objectName}/{recordId} endpoint to update a record.
+     * Does not use caching since write operations should always execute.
+     *
+     * @param objectName - The API name of the object (e.g., 'Account', 'Contact')
+     * @param recordId - The ID of the record to update
+     * @param record - The field values to update
+     * @returns ServiceResult containing the update result with record ID and success status
+     */
+    updateRecord(objectName: string, recordId: string, record: Record<string, unknown>): Promise<ServiceResult<UpdateRecordResult>>;
+    /**
+     * Deletes a record from a Salesforce object.
+     *
+     * Uses the REST API DELETE /sobjects/{objectName}/{recordId} endpoint to delete a record.
+     * Does not use caching since write operations should always execute.
+     *
+     * @param objectName - The API name of the object (e.g., 'Account', 'Contact')
+     * @param recordId - The ID of the record to delete
+     * @returns ServiceResult containing the delete result with record ID and success status
+     */
+    deleteRecord(objectName: string, recordId: string): Promise<ServiceResult<DeleteRecordResult>>;
+    /**
+     * Makes a generic HTTP request to a custom Salesforce REST endpoint.
+     *
+     * Supports custom Apex REST endpoints and any other Salesforce REST API path.
+     * Does not use caching since custom endpoints have unpredictable response shapes.
+     *
+     * The namespace guard is enforced for write operations (POST, PATCH, PUT, DELETE) that
+     * target sObject endpoints (`/sobjects/{objectName}`). Custom Apex REST endpoints
+     * (e.g., `/services/apexrest/pnova/v1/...`) and GET requests are not affected.
+     *
+     * @param httpRequest - The HTTP request configuration
+     * @returns ServiceResult containing the deserialized response of type T
+     */
+    request<T>(httpRequest: HttpRequest): Promise<ServiceResult<T>>;
+    /**
+     * Invalidates cached entries.
+     *
+     * @param pattern - Optional pattern to match keys (supports * wildcard). If not provided, clears all entries.
+     */
+    invalidateCache(pattern?: string): void;
+    /**
+     * Fetches record counts via the bulk REST endpoint `/limits/recordCount`.
+     *
+     * @param objectNames - Object API names to fetch counts for
+     * @param results - Map to populate with counts
+     * @returns true if the REST endpoint succeeded, false if it failed
+     */
+    private fetchRecordCountsViaRest;
+    /**
+     * Fallback: fetches record counts via individual SOQL COUNT() queries.
+     *
+     * @param objectNames - Object API names to fetch counts for
+     * @param results - Map to populate with counts
+     */
+    private fetchRecordCountsViaSoql;
+    /**
+     * Handles DML insert errors and maps them to appropriate error codes.
+     *
+     * @param error - The caught error
+     * @param startTime - The operation start time for duration calculation
+     * @param emptyResult - The empty result to return on failure
+     * @param context - Context for logging (object name)
+     * @returns ServiceResult with success=false and mapped error code
+     */
+    private handleInsertError;
+    /**
+     * Handles DML update errors and maps them to appropriate error codes.
+     *
+     * @param error - The caught error
+     * @param startTime - The operation start time for duration calculation
+     * @param emptyResult - The empty result to return on failure
+     * @param context - Context for logging (object name/record ID)
+     * @returns ServiceResult with success=false and mapped error code
+     */
+    private handleUpdateError;
+    /**
+     * Handles DML delete errors and maps them to appropriate error codes.
+     *
+     * @param error - The caught error
+     * @param startTime - The operation start time for duration calculation
+     * @param emptyResult - The empty result to return on failure
+     * @param context - Context for logging (object name/record ID)
+     * @returns ServiceResult with success=false and mapped error code
+     */
+    private handleDeleteError;
+    /**
+     * Handles errors and maps them to appropriate error codes.
+     *
+     * Accepts SfError, jsforce errors, or unknown error types. Extracts Salesforce
+     * error codes when available and maps them to adapter-specific error codes.
+     *
+     * @param error - The caught error (SfError, jsforce error, or unknown)
+     * @param startTime - The operation start time for duration calculation
+     * @param emptyResult - The empty result to return on failure
+     * @param context - Context for logging (e.g., "Account", "global describe")
+     * @param defaultErrorCode - The default error code if no SF error code is found
+     * @returns ServiceResult with success=false and mapped error code
+     */
+    private handleError;
+}