@memberjunction/server 3.3.0 → 4.0.0

package/dist/agents/skip-sdk.d.ts

@@ -1,58 +1,221 @@
+/**
+ * Skip TypeScript SDK
+ *
+ * A general-purpose SDK for calling the Skip SaaS API.
+ * This module provides a clean, reusable interface for integrating with Skip
+ * that can eventually be extracted into a standalone npm package.
+ */
 import { SkipAPIResponse, SkipMessage, SkipRequestPhase } from '@memberjunction/skip-types';
 import { DataContext } from '@memberjunction/data-context';
 import { UserInfo } from '@memberjunction/core';
 import mssql from 'mssql';
+/**
+ * Configuration options for Skip SDK
+ */
 export interface SkipSDKConfig {
+    /**
+     * Skip API base URL (e.g., 'https://skip.memberjunction.com')
+     */
     apiUrl?: string;
+    /**
+     * Skip API key for authentication
+     */
     apiKey?: string;
+    /**
+     * Organization ID
+     */
     organizationId?: string;
+    /**
+     * Optional organization context information
+     */
     organizationInfo?: string;
 }
+/**
+ * Options for making a Skip API call
+ */
 export interface SkipCallOptions {
+    /**
+     * Conversation messages (user/assistant)
+     */
     messages: SkipMessage[];
+    /**
+     * Conversation ID for tracking
+     */
     conversationId: string;
+    /**
+     * Data context to provide to Skip
+     */
     dataContext?: DataContext;
+    /**
+     * Request phase (initial_request, clarify_question_response, etc.)
+     */
     requestPhase?: SkipRequestPhase;
+    /**
+     * Context user for permissions and metadata
+     */
     contextUser: UserInfo;
+    /**
+     * Database connection for metadata queries
+     */
     dataSource: mssql.ConnectionPool;
+    /**
+     * Include entity metadata in request
+     */
     includeEntities?: boolean;
+    /**
+     * Include saved queries in request
+     */
     includeQueries?: boolean;
+    /**
+     * Include agent notes in request
+     */
     includeNotes?: boolean;
+    /**
+     * Include agent requests in request
+     */
     includeRequests?: boolean;
+    /**
+     * Force refresh of entity metadata cache
+     */
     forceEntityRefresh?: boolean;
+    /**
+     * Include callback API key and access token for Skip to call back to MJ
+     */
     includeCallbackAuth?: boolean;
+    /**
+     * Callback for streaming status updates during execution
+     */
     onStatusUpdate?: (message: string, responsePhase?: string) => void;
+    /**
+     * Optional payload data from a previous response (e.g., PRD in progress).
+     * This enables incremental artifact building where structured data accumulates
+     * throughout the conversation. When Skip returns a response with a payload,
+     * the client should pass that payload back in the next request.
+     */
     payload?: Record<string, any>;
 }
+/**
+ * Result from a Skip API call
+ */
 export interface SkipCallResult {
+    /**
+     * Whether the call was successful
+     */
     success: boolean;
+    /**
+     * The final Skip API response
+     */
     response?: SkipAPIResponse;
+    /**
+     * Response phase (analysis_complete, clarifying_question, status_update)
+     */
     responsePhase?: string;
+    /**
+     * Error message if failed
+     */
     error?: string;
+    /**
+     * All streaming responses received (including intermediate status updates)
+     */
     allResponses?: any[];
 }
+/**
+ * Skip TypeScript SDK
+ * Provides a clean interface for calling the Skip SaaS API
+ */
 export declare class SkipSDK {
     private config;
     private static __skipEntitiesCache$;
     private static __lastRefreshTime;
     constructor(config?: SkipSDKConfig);
+    /**
+     * Call the Skip chat API
+     */
     chat(options: SkipCallOptions): Promise<SkipCallResult>;
+    /**
+     * Build the Skip API request object
+     */
     private buildSkipRequest;
+    /**
+     * Build base request with metadata, API keys, and callback auth
+     */
     private buildBaseRequest;
+    /**
+     * Build entity metadata for Skip
+     * Copied from AskSkipResolver.BuildSkipEntities - uses cached metadata with refresh logic
+     */
     private buildEntities;
+    /**
+     * Build saved queries for Skip
+     */
     private buildQueries;
+    /**
+     * Recursively build category path for a query
+     */
     private buildQueryCategoryPath;
+    /**
+     * Build agent notes for Skip
+     */
     private buildAgentNotes;
+    /**
+     * Build artifacts for a conversation using optimized query
+     * Uses GetConversationArtifactsForAgent query which joins through ConversationDetailArtifact
+     * to get artifacts that were outputs from Skip agent's conversation details
+     */
     private buildArtifacts;
+    /**
+     * Build API keys for AI services
+     */
     private buildAPIKeys;
+    /**
+     * Build HTTP headers for Skip API requests
+     */
     private buildHeaders;
+    /**
+     * Refreshes the Skip entities cache
+     * Rebuilds the entity information that is provided to Skip
+     * Copied from AskSkipResolver.refreshSkipEntities
+     */
     private refreshSkipEntities;
+    /**
+     * Packs information about a single entity for Skip
+     * Includes fields, relationships, and sample data
+     * Copied from AskSkipResolver.PackSingleSkipEntityInfo
+     */
     private packSingleSkipEntityInfo;
+    /**
+     * Packs information about a single entity relationship
+     * These relationships help Skip understand the data model
+     * Copied from AskSkipResolver.PackSingleSkipEntityRelationship
+     */
     private packSingleSkipEntityRelationship;
+    /**
+     * Packs information about a single entity field
+     * Includes metadata and possible values
+     * Copied from AskSkipResolver.PackSingleSkipEntityField
+     */
     private packSingleSkipEntityField;
+    /**
+     * Packs possible values for an entity field
+     * These values help Skip understand the domain and valid values for fields
+     * Copied from AskSkipResolver.PackFieldPossibleValues
+     */
     private packFieldPossibleValues;
+    /**
+     * Gets distinct values for a field from the database
+     * Used to provide Skip with information about the possible values
+     * Copied from AskSkipResolver.GetFieldDistinctValues
+     */
     private getFieldDistinctValues;
+    /**
+     * Process messages: filter delegation messages and add metadata fields
+     * Messages coming in should already have conversationDetailID if they exist in the database
+     */
     private processMessages;
+    /**
+     * Check if a message is a delegation message that should be filtered out
+     * Uses flexible pattern matching to detect variations of delegation messages
+     */
     private isDelegationMessage;
 }
 //# sourceMappingURL=skip-sdk.d.ts.map

package/dist/agents/skip-sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skip-sdk.d.ts","sourceRoot":"","sources":["../../src/agents/skip-sdk.ts"],"names":[],"mappings":"AAQA,OAAO,EAEH,eAAe,EACf,WAAW,EAGX,gBAAgB,EAanB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAgG,MAAM,sBAAsB,CAAC;AAM9I,OAAO,KAAK,MAAM,OAAO,CAAC;AAQ1B,MAAM,WAAW,aAAa;IAI1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAKhB,MAAM,CAAC,EAAE,MAAM,CAAC;IAKhB,cAAc,CAAC,EAAE,MAAM,CAAC;IAKxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAKD,MAAM,WAAW,eAAe;IAI5B,QAAQ,EAAE,WAAW,EAAE,CAAC;IAKxB,cAAc,EAAE,MAAM,CAAC;IAKvB,WAAW,CAAC,EAAE,WAAW,CAAC;IAK1B,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAKhC,WAAW,EAAE,QAAQ,CAAC;IAKtB,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC;IAKjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAK1B,cAAc,CAAC,EAAE,OAAO,CAAC;IAKzB,YAAY,CAAC,EAAE,OAAO,CAAC;IAKvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAK1B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAK7B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAK9B,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAQnE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACjC;AAKD,MAAM,WAAW,cAAc;IAI3B,OAAO,EAAE,OAAO,CAAC;IAKjB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAK3B,aAAa,CAAC,EAAE,MAAM,CAAC;IAKvB,KAAK,CAAC,EAAE,MAAM,CAAC;IAKf,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC;CACxB;AAMD,qBAAa,OAAO;IAChB,OAAO,CAAC,MAAM,CAAgB;IAG9B,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAkH;IACrJ,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAa;gBAEjC,MAAM,CAAC,EAAE,aAAa;IAa5B,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;YAmF/C,gBAAgB;YA+DhB,gBAAgB;YAqDhB,aAAa;IAuB3B,OAAO,CAAC,YAAY;IA4DpB,OAAO,CAAC,sBAAsB;YAWhB,eAAe;YAYf,cAAc;IA8G5B,OAAO,CAAC,YAAY;IAgCpB,OAAO,CAAC,YAAY;YAYN,mBAAmB;YAoDnB,wBAAwB;IAkCtC,OAAO,CAAC,gCAAgC;YA4B1B,yBAAyB;YA4CzB,uBAAuB;YA+CvB,sBAAsB;IA2BpC,OAAO,CAAC,eAAe;IAqBvB,OAAO,CAAC,mBAAmB;CAW9B"}
+{"version":3,"file":"skip-sdk.d.ts","sourceRoot":"","sources":["../../src/agents/skip-sdk.ts"],"names":[],"mappings":"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"}

package/dist/agents/skip-sdk.js

@@ -1,3 +1,10 @@
+/**
+ * Skip TypeScript SDK
+ *
+ * A general-purpose SDK for calling the Skip SaaS API.
+ * This module provides a clean, reusable interface for integrating with Skip
+ * that can eventually be extracted into a standalone npm package.
+ */
 import { SkipResponsePhase } from '@memberjunction/skip-types';
 import { LogStatus, LogError, Metadata, RunQuery } from '@memberjunction/core';
 import { sendPostRequest } from '../util.js';
@@ -9,11 +16,16 @@ import mssql from 'mssql';
 import { registerAccessToken } from '../resolvers/GetDataResolver.js';
 import { BehaviorSubject } from 'rxjs';
 import { take } from 'rxjs/operators';
+/**
+ * Skip TypeScript SDK
+ * Provides a clean interface for calling the Skip SaaS API
+ */
 export class SkipSDK {
-    config;
-    static __skipEntitiesCache$ = new BehaviorSubject(null);
-    static __lastRefreshTime = 0;
+    // Static cache for Skip entities (shared across all instances)
+    static { this.__skipEntitiesCache$ = new BehaviorSubject(null); }
+    static { this.__lastRefreshTime = 0; }
     constructor(config) {
+        // Use provided config or fall back to MJ server config
         this.config = {
             apiUrl: config?.apiUrl || configInfo.askSkip?.chatURL,
             apiKey: config?.apiKey || configInfo.askSkip?.apiKey,
@@ -21,11 +33,20 @@ export class SkipSDK {
             organizationInfo: config?.organizationInfo || configInfo.askSkip?.organizationInfo
         };
     }
+    /**
+     * Call the Skip chat API
+     */
     async chat(options) {
         LogStatus(`[SkipSDK] Sending request to Skip API: ${this.config.apiUrl}`);
         try {
+            // Build the Skip API request
             const skipRequest = await this.buildSkipRequest(options);
-            const responses = await sendPostRequest(this.config.apiUrl, skipRequest, true, this.buildHeaders(), (streamMessage) => {
+            // Call Skip API with streaming support
+            const responses = await sendPostRequest(this.config.apiUrl, skipRequest, true, // useCompression
+            this.buildHeaders(), (streamMessage) => {
+                // Handle streaming status updates
+                // Queue messages come as flat objects: {responsePhase: 'queued'|'error', message: '...', error: '...'}
+                // Skip API messages come wrapped: {type: 'status_update', value: {responsePhase: '...', messages: [...]}}
                 if (streamMessage.type === 'status_update' && options.onStatusUpdate) {
                     const statusContent = streamMessage.value?.messages?.[0]?.content;
                     const responsePhase = streamMessage.value?.responsePhase;
@@ -34,6 +55,7 @@ export class SkipSDK {
                     }
                 }
                 else if (streamMessage.responsePhase === SkipResponsePhase.queued && options.onStatusUpdate) {
+                    // Handle queue progress messages
                     const statusContent = streamMessage.message;
                     const responsePhase = streamMessage.responsePhase;
                     if (statusContent) {
@@ -41,12 +63,15 @@ export class SkipSDK {
                     }
                 }
                 else if (streamMessage.responsePhase === 'error') {
+                    // Queue error messages - log but don't throw (final response will handle error)
+                    // Note: 'error' is not in SkipResponsePhase enum - it's a queue-specific error state
                     LogError(`[SkipSDK] Queue error: ${streamMessage.error || 'Unknown error'}`);
                     if (options.onStatusUpdate) {
                         options.onStatusUpdate(`Error: ${streamMessage.error || 'Request failed'}`, 'error');
                     }
                 }
             });
+            // The last response is the final one
             if (responses && responses.length > 0) {
                 const finalResponse = responses[responses.length - 1].value;
                 return {
@@ -65,6 +90,7 @@ export class SkipSDK {
         }
         catch (error) {
             LogError(`[SkipSDK] Error calling Skip API: ${error}`);
+            // Provide user-friendly error messages for common failures
             let userFriendlyError = String(error);
             const errorStr = String(error).toLowerCase();
             if (errorStr.includes('stream error') || errorStr.includes('aborted') || errorStr.includes('econnreset')) {
@@ -82,18 +108,25 @@ export class SkipSDK {
             };
         }
     }
+    /**
+     * Build the Skip API request object
+     */
     async buildSkipRequest(options) {
         const { messages, conversationId, dataContext, requestPhase = 'initial_request', contextUser, dataSource, includeEntities = true, includeQueries = true, includeNotes = true, includeRequests = false, forceEntityRefresh = false, includeCallbackAuth = true, payload } = options;
+        // Build base request with metadata
         const baseRequest = await this.buildBaseRequest(contextUser, dataSource, includeEntities, includeQueries, includeNotes, includeRequests, forceEntityRefresh, includeCallbackAuth, { conversationId, requestPhase });
+        // Build artifacts for this conversation
         const artifacts = await this.buildArtifacts(contextUser, dataSource, conversationId);
+        // Process messages: filter delegation messages and enrich with metadata
         const processedMessages = this.processMessages(messages);
+        // Construct the full Skip API request
         const request = {
             messages: processedMessages,
             conversationID: conversationId,
             dataContext: dataContext ? CopyScalarsAndArrays(dataContext) : undefined,
             requestPhase,
             artifacts,
-            payload,
+            payload, // Pass through payload for incremental artifact building (e.g., PRD in progress)
             entities: baseRequest.entities || [],
             queries: baseRequest.queries || [],
             notes: baseRequest.notes,
@@ -108,10 +141,15 @@ export class SkipSDK {
         };
         return request;
     }
+    /**
+     * Build base request with metadata, API keys, and callback auth
+     */
     async buildBaseRequest(contextUser, dataSource, includeEntities, includeQueries, includeNotes, includeRequests, forceEntityRefresh, includeCallbackAuth, additionalTokenInfo = {}) {
         const entities = includeEntities ? await this.buildEntities(dataSource, forceEntityRefresh) : [];
         const queries = includeQueries ? this.buildQueries() : [];
         const { notes, noteTypes } = includeNotes ? await this.buildAgentNotes(contextUser) : { notes: [], noteTypes: [] };
+        // Note: requests would be built here if includeRequests is true
+        // Setup access token for Skip callbacks if needed
         let accessToken;
         if (includeCallbackAuth) {
             const tokenInfo = {
@@ -121,7 +159,8 @@ export class SkipSDK {
                 userID: contextUser.ID,
                 ...additionalTokenInfo
             };
-            accessToken = registerAccessToken(undefined, 1000 * 60 * 10, tokenInfo);
+            accessToken = registerAccessToken(undefined, 1000 * 60 * 10, // 10 minutes
+            tokenInfo);
         }
         return {
             entities,
@@ -137,10 +176,15 @@ export class SkipSDK {
             callingServerAccessToken: accessToken ? accessToken.Token : undefined
         };
     }
+    /**
+     * Build entity metadata for Skip
+     * Copied from AskSkipResolver.BuildSkipEntities - uses cached metadata with refresh logic
+     */
     async buildEntities(dataSource, forceRefresh, refreshIntervalMinutes = 15) {
         try {
             const now = Date.now();
             const cacheExpired = (now - SkipSDK.__lastRefreshTime) > (refreshIntervalMinutes * 60 * 1000);
+            // If force refresh is requested OR cache expired OR cache is empty, refresh
             if (forceRefresh || cacheExpired || SkipSDK.__skipEntitiesCache$.value === null) {
                 LogStatus(`[SkipSDK] Refreshing Skip entities cache (force: ${forceRefresh}, expired: ${cacheExpired})`);
                 const newData = this.refreshSkipEntities(dataSource);
@@ -153,6 +197,9 @@ export class SkipSDK {
             return [];
         }
     }
+    /**
+     * Build saved queries for Skip
+     */
     buildQueries(status = 'Approved') {
         const md = new Metadata();
         const approvedQueries = md.Queries.filter((q) => q.Status === status);
@@ -208,6 +255,9 @@ export class SkipSDK {
             CacheValidationSQL: q.CacheValidationSQL
         }));
     }
+    /**
+     * Recursively build category path for a query
+     */
     buildQueryCategoryPath(md, categoryID) {
         const cat = md.QueryCategories.find((c) => c.ID === categoryID);
         if (!cat)
@@ -217,33 +267,53 @@ export class SkipSDK {
         const parentPath = this.buildQueryCategoryPath(md, cat.ParentID);
         return parentPath ? `${parentPath}/${cat.Name}` : cat.Name;
     }
+    /**
+     * Build agent notes for Skip
+     */
     async buildAgentNotes(contextUser) {
+        // TODO: Implement agent notes building
+        // This would query AIAgentNote entities and convert to SkipAPIAgentNote format
+        // For now, returning empty arrays
         return { notes: [], noteTypes: [] };
     }
+    /**
+     * Build artifacts for a conversation using optimized query
+     * Uses GetConversationArtifactsForAgent query which joins through ConversationDetailArtifact
+     * to get artifacts that were outputs from Skip agent's conversation details
+     */
     async buildArtifacts(contextUser, dataSource, conversationId) {
         try {
             const rq = new RunQuery();
+            // Ensure AIEngine is configured and get Skip agent ID
             await AIEngine.Instance.Config(false, contextUser);
             const skipAgent = AIEngine.Instance.GetAgentByName('Skip');
             const skipAgentId = skipAgent?.ID;
             if (!skipAgentId) {
                 LogError('[SkipSDK] Skip agent not found in AIEngine');
             }
+            // Use optimized query that replaces 4 RunView calls with 1 query
+            // This query includes Configuration field needed for component spec extraction
+            // Filter by Skip agent ID to only get artifacts created by Skip (not delegation agents)
             const result = await rq.RunQuery({
                 QueryName: 'GetConversationArtifactsForAgent',
                 CategoryPath: 'MJ/Conversations',
                 Parameters: {
                     ConversationID: conversationId,
-                    AgentID: skipAgentId
+                    AgentID: skipAgentId // Filter to only artifacts created by Skip agent
                 }
             }, contextUser);
             if (!result.Success || !result.Results || result.Results.length === 0) {
                 return [];
             }
+            // Query returns flat result set: one row per artifact version
+            // Group by ArtifactID to build SkipAPIArtifact objects with their versions
             const artifactMap = new Map();
+            // Process each row (represents one version)
             for (const row of result.Results) {
                 const artifactId = row.ArtifactID;
+                // Initialize artifact entry if not exists
                 if (!artifactMap.has(artifactId)) {
+                    // Map database sharingScope values to SkipAPIArtifact expected values
                     let sharingScope = 'None';
                     const dbSharingScope = (row.SharingScope || '').toLowerCase();
                     if (dbSharingScope === 'always' || dbSharingScope === 'everyone') {
@@ -278,11 +348,12 @@ export class SkipSDK {
                         versions: []
                     });
                 }
+                // Add this version to the artifact
                 const entry = artifactMap.get(artifactId);
                 entry.versions.push({
                     id: row.VersionID,
                     artifactId: artifactId,
-                    conversationDetailID: row.ConversationDetailID,
+                    conversationDetailID: row.ConversationDetailID, // Direct from join table!
                     version: row.Version,
                     configuration: row.Configuration || '',
                     content: row.Content || '',
@@ -291,6 +362,7 @@ export class SkipSDK {
                     updatedAt: new Date(row.VersionUpdatedAt)
                 });
             }
+            // Convert map to SkipAPIArtifact array
             const artifacts = Array.from(artifactMap.values()).map(entry => ({
                 ...entry.artifact,
                 artifactType: entry.artifactType,
@@ -303,6 +375,9 @@ export class SkipSDK {
             return [];
         }
     }
+    /**
+     * Build API keys for AI services
+     */
     buildAPIKeys() {
         return [
             {
@@ -331,20 +406,30 @@ export class SkipSDK {
             }
         ];
     }
+    /**
+     * Build HTTP headers for Skip API requests
+     */
     buildHeaders() {
         return {
             'x-api-key': this.config.apiKey || '',
             'Content-Type': 'application/json'
         };
     }
+    /**
+     * Refreshes the Skip entities cache
+     * Rebuilds the entity information that is provided to Skip
+     * Copied from AskSkipResolver.refreshSkipEntities
+     */
     async refreshSkipEntities(dataSource) {
         try {
             const md = new Metadata();
+            // Diagnostic logging
             LogStatus(`[SkipSDK.refreshSkipEntities] Total entities in metadata: ${md.Entities.length}`);
             LogStatus(`[SkipSDK.refreshSkipEntities] Config excludeSchemas: ${JSON.stringify(configInfo.askSkip?.entitiesToSend?.excludeSchemas)}`);
             LogStatus(`[SkipSDK.refreshSkipEntities] Config includeEntitiesFromExcludedSchemas: ${JSON.stringify(configInfo.askSkip?.entitiesToSend?.includeEntitiesFromExcludedSchemas)}`);
             const skipSpecialIncludeEntities = (configInfo.askSkip?.entitiesToSend?.includeEntitiesFromExcludedSchemas ?? [])
                 .map((e) => e.trim().toLowerCase());
+            // Get the list of entities
             const entities = md.Entities.filter((e) => {
                 if (!(configInfo.askSkip?.entitiesToSend?.excludeSchemas ?? []).includes(e.SchemaName) ||
                     skipSpecialIncludeEntities.includes(e.Name.trim().toLowerCase())) {
@@ -354,7 +439,7 @@ export class SkipSDK {
                         return !scopes || scopes.length === 0 || scopes.includes('all') || scopes.includes('ai') || skipSpecialIncludeEntities.includes(e.Name.trim().toLowerCase());
                     }
                     else {
-                        return true;
+                        return true; // no scope, so include it
                     }
                 }
                 return false;
@@ -363,9 +448,10 @@ export class SkipSDK {
             if (entities.length === 0) {
                 LogError(`[SkipSDK.refreshSkipEntities] WARNING: No entities passed filtering! This will result in empty Skip entities list.`);
             }
+            // Now we have our list of entities, pack em up
             const result = await Promise.all(entities.map((e) => this.packSingleSkipEntityInfo(e, dataSource)));
             LogStatus(`[SkipSDK.refreshSkipEntities] Successfully packed ${result.length} entities for Skip`);
-            SkipSDK.__lastRefreshTime = Date.now();
+            SkipSDK.__lastRefreshTime = Date.now(); // Update last refresh time
             return result;
         }
         catch (e) {
@@ -373,6 +459,11 @@ export class SkipSDK {
             return [];
         }
     }
+    /**
+     * Packs information about a single entity for Skip
+     * Includes fields, relationships, and sample data
+     * Copied from AskSkipResolver.PackSingleSkipEntityInfo
+     */
     async packSingleSkipEntityInfo(e, dataSource) {
         try {
             const ret = {
@@ -382,6 +473,7 @@ export class SkipSDK {
                 baseView: e.BaseView,
                 description: e.Description,
                 fields: await Promise.all(e.Fields.filter(f => {
+                    // we want to check the scopes for the field level and make sure it is either All or AI or has both
                     const scopes = f.ScopeDefault?.split(',').map((s) => s.trim().toLowerCase());
                     return !scopes || scopes.length === 0 || scopes.includes('all') || scopes.includes('ai');
                 }).map(f => {
@@ -398,6 +490,11 @@ export class SkipSDK {
             return null;
         }
     }
+    /**
+     * Packs information about a single entity relationship
+     * These relationships help Skip understand the data model
+     * Copied from AskSkipResolver.PackSingleSkipEntityRelationship
+     */
     packSingleSkipEntityRelationship(r) {
         try {
             return {
@@ -420,6 +517,11 @@ export class SkipSDK {
             return null;
         }
     }
+    /**
+     * Packs information about a single entity field
+     * Includes metadata and possible values
+     * Copied from AskSkipResolver.PackSingleSkipEntityField
+     */
     async packSingleSkipEntityField(f, dataSource) {
         try {
             return {
@@ -458,23 +560,34 @@ export class SkipSDK {
             return null;
         }
     }
+    /**
+     * Packs possible values for an entity field
+     * These values help Skip understand the domain and valid values for fields
+     * Copied from AskSkipResolver.PackFieldPossibleValues
+     */
     async packFieldPossibleValues(f, dataSource) {
         try {
             if (f.ValuesToPackWithSchema === 'None') {
-                return [];
+                return []; // don't pack anything
             }
             else if (f.ValuesToPackWithSchema === 'All') {
+                // wants ALL of the distinct values
                 return await this.getFieldDistinctValues(f, dataSource);
             }
             else if (f.ValuesToPackWithSchema === 'Auto') {
+                // default setting - pack based on the ValueListType
                 if (f.ValueListTypeEnum === 'List') {
+                    // simple list of values in the Entity Field Values table
                     return f.EntityFieldValues.map((v) => {
                         return { value: v.Value, displayValue: v.Value };
                     });
                 }
                 else if (f.ValueListTypeEnum === 'ListOrUserEntry') {
+                    // could be a user provided value, OR the values in the list of possible values.
+                    // get the distinct list of values from the DB and concat that with the f.EntityFieldValues array - deduped and return
                     const values = await this.getFieldDistinctValues(f, dataSource);
                     if (!values || values.length === 0) {
+                        // no result, just return the EntityFieldValues
                         return f.EntityFieldValues.map((v) => {
                             return { value: v.Value, displayValue: v.Value };
                         });
@@ -486,13 +599,18 @@ export class SkipSDK {
                     }
                 }
             }
-            return [];
+            return []; // if we get here, nothing to pack
         }
         catch (e) {
             LogError(`[SkipSDK] packFieldPossibleValues error: ${e}`);
             return [];
         }
     }
+    /**
+     * Gets distinct values for a field from the database
+     * Used to provide Skip with information about the possible values
+     * Copied from AskSkipResolver.GetFieldDistinctValues
+     */
     async getFieldDistinctValues(f, dataSource) {
         try {
             const sql = `SELECT DISTINCT ${f.Name} FROM ${f.SchemaName}.${f.BaseView}`;
@@ -515,10 +633,18 @@ export class SkipSDK {
             return [];
         }
     }
+    /**
+     * Process messages: filter delegation messages and add metadata fields
+     * Messages coming in should already have conversationDetailID if they exist in the database
+     */
     processMessages(messages) {
+        // Filter out delegation messages (administrative messages that shouldn't go to Skip)
         const filteredMessages = messages.filter(msg => !this.isDelegationMessage(msg.content));
+        // Enrich messages with default metadata if not already present
         return filteredMessages.map(msg => ({
             ...msg,
+            // Add default metadata fields if not already present
+            // Messages from DB already have conversationDetailID, temp messages get temp-X
             hiddenToUser: msg.hiddenToUser ?? false,
             userRating: msg.userRating ?? null,
             userFeedback: msg.userFeedback ?? null,
@@ -526,10 +652,15 @@ export class SkipSDK {
             summaryOfEarlierConveration: msg.summaryOfEarlierConveration ?? null
         }));
     }
+    /**
+     * Check if a message is a delegation message that should be filtered out
+     * Uses flexible pattern matching to detect variations of delegation messages
+     */
     isDelegationMessage(content) {
         if (!content)
             return false;
         const lowerContent = content.toLowerCase();
+        // Check for both "delegating" or "delegate" AND "skip" in any order
         const hasDelegatingOrDelegate = lowerContent.includes('delegating') || lowerContent.includes('delegate');
         const hasSkip = lowerContent.includes('skip');
         return hasDelegatingOrDelegate && hasSkip;