@memberjunction/skip-types 2.32.2 → 2.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/skip-types",
-  "version": "2.32.2",
+  "version": "2.33.0",
   "description": "MemberJunction: Skip AI Assistant - Types that are used between the MJAPI and the Skip API as well as the UI within MemberJunction Explorer",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,7 @@
     "typescript": "^5.4.5"
   },
   "dependencies": {
-    "@memberjunction/core-entities": "2.32.2",
-    "@memberjunction/data-context": "2.32.2"
+    "@memberjunction/core-entities": "2.33.0",
+    "@memberjunction/data-context": "2.33.0"
   }
 }

package/readme.md

@@ -1,7 +1,10 @@
-```markdown
-# @memberjunction/skip-types
+# MemberJunction Skip Types
 
-This library provides a set of types that are used to create consistency and coding simplicity for data interchange between the UI, Skip API and MJAPI
+Type definitions and interfaces for the Skip AI Assistant integration with MemberJunction. This package provides the contract between the MemberJunction API, Skip API, and the MemberJunction Explorer UI.
+
+## Overview
+
+The `@memberjunction/skip-types` package contains TypeScript type definitions, interfaces, and enums that facilitate communication between different components of the MemberJunction Skip AI assistant system. It ensures type safety and consistent data structures when interacting with the Skip API or rendering Skip-generated content in MemberJunction applications.
 
 ## Installation
 
@@ -9,10 +12,214 @@ This library provides a set of types that are used to create consistency and cod
 npm install @memberjunction/skip-types
 ```
 
+## Key Components
+
+### Request Types
+
+Types used for making requests to the Skip API:
+
+- `SkipAPIRequest` - Base interface for Skip API requests
+- `SkipAPIRequestContext` - Context information for Skip API requests
+- `SkipAPIRequestFilter` - Filter parameters for Skip requests
+- `SkipAPIRequestSort` - Sort parameters for Skip requests
+- `SkipAPIEntityQueryRequest` - Request for entity data queries
+- `SkipAPIDataContextItemRequest` - Request for data context items
+- `SkipAPIConversationRequest` - Request for conversation management
+- `SkipAPIFetchImageRequest` - Request for image fetching
+
+### Response Types
+
+Types used for handling responses from the Skip API:
+
+- `SkipAPIResponse` - Base interface for Skip API responses
+- `SkipAPIEntityQueryResponse` - Response with entity query results
+- `SkipAPIConversationResponse` - Response for conversation operations
+- `SkipAPIImageResponse` - Response for image operations
+- `SkipAPIErrorResponse` - Error response structure
+- `MJAPISkipResult` - Response format from MJAPI to the UI
+- `SkipResponsePhase` - Defines the different phases of Skip responses
+
+### Message and Conversation Types
+
+- `SkipMessage` - Individual message in a conversation with Skip
+- `SkipConversation` - Collection of messages forming a conversation
+- `SkipRequestPhase` - Defines the different phases of Skip requests
+- `SkipConversationDetail` - Detailed conversation information
+- `SkipConversationStatus` - Conversation status enum
+
+### Report Types
+
+Types for Skip-generated reports and visualizations:
+
+- `SkipHTMLReport` - HTML-based report generated by Skip
+- `SkipHTMLReportCallbacks` - Interface for callbacks from HTML reports
+- `SkipHTMLReportInitFunction` - Initialization function for HTML reports
+- `SkipReportAction` - Actions that can be performed on reports
+- `SkipReportEvent` - Events that can occur in reports
+- `SkipReportCallbackResponse` - Response from report callbacks
+- `SimpleDataContext` - Simplified data context for HTML reports
+
+### Learning Cycle Types
+
+- `SkipAPILearningCycleRequest` - Request for Skip to learn from conversation history
+- `SkipAPILearningCycleResponse` - Response from learning cycle processing
+- `SkipAPIAgentNote` - Notes that Skip can generate during learning
+- `SkipAPIAgentNoteType` - Types of notes Skip can generate
+- `SkipAPIAgentRequest` - Format for Skip's human-in-the-loop requests
+
+### Data Types
+
+- `SkipDataRequest` - Format for Skip to request additional data
+- `SkipDataRequestType` - Types of data requests Skip can make
+- `SkipSubProcessResponse` - Results from sandboxed script execution
+- `SkipEntityInfo` - Entity metadata information for Skip
+- `SkipEntityFieldInfo` - Field metadata for entities
+- `SkipEntityRelationshipInfo` - Relationship metadata for entities
+- `SkipDataContextItem` - Data context item structure
+- `SkipDataContextItemType` - Types of data context items
+- `SkipDataContextItemSource` - Source of data context items
+
+### Specialized Response Types
+
+- `SkipAPIAnalysisCompleteResponse` - Response for completed analysis
+- `SkipAPIClarifyingQuestionResponse` - Response when Skip needs clarification
+- `SkipAPIDataRequestResponse` - Response when Skip needs more data
+- `SkipAPIChatWithRecordResponse` - Response for chat-with-record feature
+
+## Usage Examples
+
+### Creating a Skip API Request
+
+```typescript
+import { 
+  SkipAPIRequest, 
+  SkipMessage, 
+  SkipRequestPhase 
+} from '@memberjunction/skip-types';
+
+// Create a new Skip API request
+const request: SkipAPIRequest = {
+  messages: [
+    {
+      role: "user",
+      content: "Show me sales by region from last quarter",
+      conversationDetailID: "12345"
+    }
+  ],
+  dataContext: myDataContext,
+  entities: myEntityMetadata,
+  queries: myStoredQueries,
+  conversationID: "conv-123",
+  organizationID: "org-456",
+  requestPhase: SkipRequestPhase.initial_request,
+  apiKeys: [
+    {
+      vendorDriverName: "AnthropicLLM",
+      apiKey: "YOUR_API_KEY"
+    }
+  ]
+};
+```
+
+### Handling Skip API Responses
+
+```typescript
+import { 
+  MJAPISkipResult, 
+  SkipAPIAnalysisCompleteResponse, 
+  SkipResponsePhase 
+} from '@memberjunction/skip-types';
+
+function handleSkipResponse(result: MJAPISkipResult) {
+  if (result.Success) {
+    if (result.ResponsePhase === SkipResponsePhase.analysis_complete) {
+      // Parse the result JSON into the appropriate type
+      const response = JSON.parse(result.Result) as SkipAPIAnalysisCompleteResponse;
+      
+      // Now you can access the analysis results
+      console.log("Report title:", response.reportTitle);
+      console.log("Analysis:", response.analysis);
+      
+      // Handle different result types
+      if (response.resultType === "data") {
+        // Handle table data from executionResults.tableData
+        displayTable(response.executionResults.tableData);
+      } else if (response.resultType === "plot") {
+        // Handle plot data from executionResults.plotData
+        renderPlot(response.executionResults.plotData);
+      } else if (response.resultType === "html") {
+        // Handle custom HTML report
+        renderHTML(response.executionResults.htmlReport);
+      }
+    } else if (result.ResponsePhase === SkipResponsePhase.clarifying_question) {
+      // Handle clarifying questions
+      const questionResponse = JSON.parse(result.Result) as SkipAPIClarifyingQuestionResponse;
+      promptUserForAnswer(questionResponse.question);
+    } else if (result.ResponsePhase === SkipResponsePhase.data_request) {
+      // Handle data requests
+      const dataRequest = JSON.parse(result.Result) as SkipAPIDataRequestResponse;
+      fetchAdditionalData(dataRequest.dataRequests);
+    }
+  } else {
+    console.error("Skip API request failed:", result.Status);
+  }
+}
+```
+
+### Working with Skip HTML Reports and Callbacks
+
+```typescript
+import { 
+  SkipHTMLReportInitFunction, 
+  SimpleDataContext, 
+  SkipHTMLReportCallbacks 
+} from '@memberjunction/skip-types';
+
+// Init function that would be called by the container application
+const initReport: SkipHTMLReportInitFunction = (
+  data: SimpleDataContext, 
+  userState?: any, 
+  callbacks?: SkipHTMLReportCallbacks
+) => {
+  // Initialize the report with the data
+  renderChart(data.data_item_1);
+  
+  // Set up event handlers that use callbacks
+  document.getElementById('refresh').addEventListener('click', () => {
+    callbacks?.RefreshData();
+  });
+  
+  document.getElementById('open-record').addEventListener('click', () => {
+    callbacks?.OpenEntityRecord('Customer', { ID: 123 });
+  });
+  
+  document.getElementById('drill-down').addEventListener('click', () => {
+    callbacks?.DrillDown('SalesRegion', 'Northeast');
+  });
+  
+  document.getElementById('export-data').addEventListener('click', () => {
+    callbacks?.ExportData('csv');
+  });
+  
+  // Update user state when something changes
+  const newState = { selectedRegion: 'North' };
+  callbacks?.UpdateUserState(newState);
+};
+
+// Register the init function globally so it can be called from the container
+window.initSkipReport = initReport;
+```
+
+## Dependencies
+
+This package relies on the following MemberJunction packages:
+- `@memberjunction/core-entities` - Core entity definitions
+- `@memberjunction/data-context` - Data context types and utilities
+
 ## Contributing
 
-Feel free to open issues or pull requests if you have suggestions or fixes.
+Contributions to extend or improve the type definitions are welcome. Please ensure that any additions maintain backward compatibility and follow the established naming conventions.
 
 ## License
 
-ISC License
+ISC