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

package/lib/adapters/connection-facade.d.ts

@@ -0,0 +1,458 @@
+import type { Connection } from '@salesforce/core';
+/**
+ * Query result structure from Salesforce.
+ *
+ * @template T The type of records in the result
+ */
+export type QueryResult<T> = {
+    /** Whether the query is complete (no more records) */
+    done: boolean;
+    /** Total number of records matching the query */
+    totalSize: number;
+    /** Array of records returned */
+    records: T[];
+    /** Locator for next batch if done is false */
+    nextRecordsUrl?: string;
+};
+/**
+ * Picklist entry for picklist fields.
+ */
+export type PicklistEntry = {
+    /** API value */
+    value: string;
+    /** Display label */
+    label: string;
+    /** Whether this is the default value */
+    defaultValue: boolean;
+    /** Whether this value is active */
+    active: boolean;
+};
+/**
+ * Child relationship for describe results.
+ */
+export type ChildRelationship = {
+    /** Relationship name */
+    relationshipName: string;
+    /** Child object API name */
+    childSObject: string;
+    /** Field on child that references this object */
+    field: string;
+    /** Whether cascade delete is enabled */
+    cascadeDelete: boolean;
+};
+/**
+ * Record type info for describe results.
+ */
+export type RecordTypeInfo = {
+    /** Record type ID */
+    recordTypeId: string;
+    /** Record type name */
+    name: string;
+    /** Developer name (may not be present in all versions) */
+    developerName?: string;
+    /** Whether this is the default record type */
+    defaultRecordTypeMapping: boolean;
+    /** Whether this is available */
+    available: boolean;
+    /** Whether this is the master record type */
+    master: boolean;
+};
+/**
+ * Describe result for a field.
+ */
+export type DescribeFieldResult = {
+    /** API name of the field */
+    name: string;
+    /** User-friendly label */
+    label: string;
+    /** Field data type */
+    type: string;
+    /** Maximum length for text fields */
+    length?: number;
+    /** Precision for numeric fields */
+    precision?: number;
+    /** Scale for decimal fields */
+    scale?: number;
+    /** Whether this is a custom field */
+    custom: boolean;
+    /** Whether the field can be null */
+    nillable: boolean;
+    /** Whether the field is unique */
+    unique: boolean;
+    /** Whether this is an external ID field */
+    externalId: boolean;
+    /** Whether the field is a formula */
+    calculated: boolean;
+    /** Whether the field can be created */
+    createable: boolean;
+    /** Whether the field can be updated */
+    updateable: boolean;
+    /** Whether the field can be used in filters */
+    filterable: boolean;
+    /** Whether the field can be used in sorts */
+    sortable: boolean;
+    /** Default value if any */
+    defaultValue?: unknown;
+    /** Picklist values if picklist type */
+    picklistValues?: PicklistEntry[];
+    /** Reference to object(s) for lookup fields */
+    referenceTo?: string[];
+    /** Relationship name for lookup fields */
+    relationshipName?: string;
+};
+/**
+ * Describe result for a Salesforce object.
+ */
+export type DescribeSObjectResult = {
+    /** API name of the object */
+    name: string;
+    /** User-friendly label */
+    label: string;
+    /** Plural label */
+    labelPlural: string;
+    /** Whether this is a custom object */
+    custom: boolean;
+    /** Whether records can be created */
+    createable: boolean;
+    /** Whether records can be updated */
+    updateable: boolean;
+    /** Whether records can be deleted */
+    deletable: boolean;
+    /** Whether the object can be queried */
+    queryable: boolean;
+    /** Whether the object is searchable */
+    searchable: boolean;
+    /** Field metadata */
+    fields: DescribeFieldResult[];
+    /** Child relationships */
+    childRelationships?: ChildRelationship[];
+    /** Record type infos */
+    recordTypeInfos?: RecordTypeInfo[];
+};
+/**
+ * Summary object info from global describe.
+ */
+export type DescribeGlobalSObjectResult = {
+    /** API name of the object */
+    name: string;
+    /** User-friendly label */
+    label: string;
+    /** Plural label */
+    labelPlural: string;
+    /** Key prefix (3 character ID prefix) */
+    keyPrefix: string | null;
+    /** Whether this is a custom object */
+    custom: boolean;
+    /** Whether records can be created */
+    createable: boolean;
+    /** Whether records can be updated */
+    updateable: boolean;
+    /** Whether records can be deleted */
+    deletable: boolean;
+    /** Whether the object can be queried */
+    queryable: boolean;
+    /** Whether the object is searchable */
+    searchable: boolean;
+    /** Whether this is a Custom Setting (hierarchy or list type) */
+    customSetting?: boolean;
+};
+/**
+ * Global describe result containing all accessible objects.
+ */
+export type DescribeGlobalResult = {
+    /** Maximum batch size for queries */
+    maxBatchSize: number;
+    /** Array of object metadata summaries */
+    sobjects: DescribeGlobalSObjectResult[];
+};
+/**
+ * Result of executing anonymous Apex.
+ */
+export type ExecuteAnonymousResult = {
+    /** Whether execution was successful */
+    success: boolean;
+    /** Whether code was compiled successfully */
+    compiled: boolean;
+    /** Compilation problem description if compilation failed */
+    compileProblem?: string;
+    /** Line number of compilation error */
+    line?: number;
+    /** Column number of compilation error */
+    column?: number;
+    /** Exception message if runtime exception occurred */
+    exceptionMessage?: string;
+    /** Exception stack trace */
+    exceptionStackTrace?: string;
+};
+/**
+ * HTTP request configuration for custom API calls.
+ */
+export type HttpRequest = {
+    /** Request URL (relative to instance URL) */
+    url: string;
+    /** HTTP method */
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Request body for POST/PUT/PATCH */
+    body?: unknown;
+    /** Custom headers */
+    headers?: Record<string, string>;
+};
+/**
+ * Query builder for SObject find operations.
+ *
+ * Provides a fluent interface for building and executing queries.
+ * Use the `limit()` method to constrain results, then `execute()` to run.
+ *
+ * @template T The SObject record type being queried
+ *
+ * @example
+ * ```typescript
+ * const accounts = await facade
+ *   .sobject<Account>('Account')
+ *   .find({ Type: 'Customer' }, ['Id', 'Name'])
+ *   .limit(100)
+ *   .execute();
+ * ```
+ */
+export type ISObjectQueryBuilder<T> = {
+    /**
+     * Limits the number of records returned.
+     *
+     * @param count - Maximum number of records to return
+     * @returns The query builder for method chaining
+     */
+    limit(count: number): ISObjectQueryBuilder<T>;
+    /**
+     * Executes the query and returns matching records.
+     *
+     * @returns Promise resolving to an array of matching records
+     */
+    execute(): Promise<T[]>;
+};
+/**
+ * SObject API for record operations on a specific Salesforce object.
+ *
+ * Provides methods to describe object metadata and query records.
+ *
+ * @template T The SObject record type
+ *
+ * @example
+ * ```typescript
+ * const accountApi = facade.sobject<Account>('Account');
+ * const metadata = await accountApi.describe();
+ * const records = await accountApi.find({ Type: 'Customer' }).execute();
+ * ```
+ */
+export type ISObjectApi<T> = {
+    /**
+     * Retrieves describe metadata for this SObject.
+     *
+     * @returns Promise resolving to the object's describe result
+     */
+    describe(): Promise<DescribeSObjectResult>;
+    /**
+     * Finds records matching the specified conditions.
+     *
+     * @param conditions - Field conditions to match (field name to value)
+     * @param fields - Optional list of fields to retrieve (defaults to all)
+     * @returns Query builder for further refinement and execution
+     */
+    find(conditions: Record<string, unknown>, fields?: string[]): ISObjectQueryBuilder<T>;
+};
+/**
+ * Tooling API interface for metadata and development operations.
+ *
+ * Provides access to Salesforce Tooling API for querying metadata objects,
+ * executing anonymous Apex, and CRUD operations on Tooling API entities.
+ *
+ * @example
+ * ```typescript
+ * // Query ApexClass metadata
+ * const result = await facade.tooling.query<ApexClass>(
+ *   "SELECT Id, Name FROM ApexClass WHERE Name LIKE 'Test%'"
+ * );
+ *
+ * // Execute anonymous Apex
+ * const execResult = await facade.tooling.executeAnonymous(
+ *   'System.debug("Hello");'
+ * );
+ * ```
+ */
+export type IToolingApi = {
+    /**
+     * Executes a Tooling API SOQL query.
+     *
+     * @template T The expected record type in results
+     * @param soql - The SOQL query string
+     * @returns Promise resolving to query results with records
+     */
+    query<T>(soql: string): Promise<QueryResult<T>>;
+    /**
+     * Retrieves additional results for a paginated query.
+     *
+     * @template T The expected record type in results
+     * @param locator - The nextRecordsUrl from a previous query result
+     * @returns Promise resolving to the next batch of results
+     */
+    queryMore<T>(locator: string): Promise<QueryResult<T>>;
+    /**
+     * Executes anonymous Apex code.
+     *
+     * @param apex - The Apex code to execute
+     * @returns Promise resolving to execution result with success/failure info
+     */
+    executeAnonymous(apex: string): Promise<ExecuteAnonymousResult>;
+    /**
+     * Creates a Tooling API record (e.g., TraceFlag, DebugLevel).
+     *
+     * @param type - The Tooling API object type name
+     * @param record - The record data to create
+     * @returns Promise resolving to creation result with id and success flag
+     */
+    create(type: string, record: Record<string, unknown>): Promise<{
+        id: string;
+        success: boolean;
+    }>;
+    /**
+     * Deletes a Tooling API record.
+     *
+     * @param type - The Tooling API object type name
+     * @param id - The record ID to delete
+     * @returns Promise resolving to deletion result with id and success flag
+     */
+    destroy(type: string, id: string): Promise<{
+        id: string;
+        success: boolean;
+    }>;
+};
+/**
+ * Facade type for Salesforce Connection.
+ *
+ * This type wraps the @salesforce/core Connection class to provide
+ * a testable, minimal surface for adapter implementations. The Connection
+ * class has 400+ methods; this facade exposes only what adapters need.
+ *
+ * @example
+ * ```typescript
+ * // In production, wrap the actual connection
+ * const facade = createConnectionFacade(connection);
+ *
+ * // In tests, use a mock
+ * const mockFacade = createMockConnectionFacade();
+ * ```
+ */
+export type IConnectionFacade = {
+    /** Access Tooling API methods */
+    tooling: IToolingApi;
+    /** Get the API version being used */
+    version: string;
+    /** Get the access token for authentication */
+    accessToken?: string;
+    /** Get the instance URL for the Salesforce org */
+    instanceUrl?: string;
+    /** Execute a SOQL query */
+    query<T>(soql: string): Promise<QueryResult<T>>;
+    /** Query for additional results using nextRecordsUrl locator */
+    queryMore<T>(locator: string): Promise<QueryResult<T>>;
+    /** Get SObject API for a specific object */
+    sobject<T>(name: string): ISObjectApi<T>;
+    /** Make a custom HTTP request to the Salesforce API */
+    request<T>(request: HttpRequest | string): Promise<T>;
+    /** Get the current user's identity information */
+    identity(): Promise<{
+        user_id: string;
+        organization_id: string;
+        username: string;
+    }>;
+};
+/**
+ * Validation result for connection state.
+ */
+export type ConnectionValidationResult = {
+    /** Whether the connection is valid */
+    valid: boolean;
+    /** Error code if invalid */
+    errorCode?: string;
+    /** Error message if invalid */
+    errorMessage?: string;
+};
+/**
+ * Validates that a connection has required properties for API calls.
+ *
+ * This checks that the connection has:
+ * - An access token (authentication)
+ * - An instance URL (target org)
+ * - A version (API version)
+ *
+ * @param connection - The connection to validate
+ * @returns Validation result indicating if connection is ready for use
+ *
+ * @example
+ * ```typescript
+ * const result = validateConnection(connection);
+ * if (!result.valid) {
+ *   throw new Error(`${result.errorCode}: ${result.errorMessage}`);
+ * }
+ * ```
+ */
+export declare function validateConnection(connection: Connection): ConnectionValidationResult;
+/**
+ * Creates a connection facade wrapper around a Salesforce Connection.
+ *
+ * @param connection - The @salesforce/core Connection instance
+ * @param options - Optional configuration
+ * @param options.skipValidation Skip connection validation (default: false)
+ * @returns An IConnectionFacade wrapping the connection
+ * @throws Error if connection validation fails and skipValidation is false
+ *
+ * @example
+ * ```typescript
+ * import { Connection } from '@salesforce/core';
+ *
+ * const org = await Org.create({ aliasOrUsername: 'myOrg' });
+ * const connection = org.getConnection();
+ * const facade = createConnectionFacade(connection);
+ *
+ * const result = await facade.query<Account>('SELECT Id, Name FROM Account LIMIT 10');
+ * ```
+ */
+export declare function createConnectionFacade(connection: Connection, options?: {
+    skipValidation?: boolean;
+}): IConnectionFacade;
+/**
+ * Configuration options for debug connection facade.
+ */
+export type DebugConnectionFacadeOptions = {
+    /** Enable debug logging for all API calls (default: false) */
+    debug?: boolean;
+};
+/**
+ * Creates a debug-wrapped connection facade that logs all API calls.
+ *
+ * When debug is enabled, wraps the facade to log:
+ * - SOQL queries (truncated to 100 chars)
+ * - Query results (record counts, timing)
+ * - REST API calls (describe, request, identity)
+ * - Tooling API calls (query, executeAnonymous)
+ * - Errors when operations fail
+ *
+ * When debug is disabled (default), returns the original facade unchanged
+ * with zero overhead.
+ *
+ * @param facade - The connection facade to wrap
+ * @param options - Configuration options
+ * @returns The facade, wrapped with logging if debug=true
+ *
+ * @example
+ * ```typescript
+ * // Without logging (production)
+ * const facade = createDebugConnectionFacade(baseFacade);
+ *
+ * // With logging (debug mode)
+ * const facade = createDebugConnectionFacade(baseFacade, { debug: true });
+ * // Calls will log:
+ * // [DEBUG] [ADAPTER] SOQL: query → SELECT Id FROM Account...
+ * // [DEBUG] [ADAPTER] SOQL: complete → 100 records, 150ms
+ * ```
+ */
+export declare function createDebugConnectionFacade(facade: IConnectionFacade, options?: DebugConnectionFacadeOptions): IConnectionFacade;