@scout9/app 1.0.0-alpha.0.1.86 → 1.0.0-alpha.0.1.88

package/src/runtime/client/workflow.js

@@ -2,11 +2,14 @@
 
 import { z } from 'zod';
 import { zId } from './utils.js';
-import { agentConfigurationSchema, customerSchema } from './agent.js';
+import { agentConfigurationSchema, customerSchema } from './users.js';
 import { MessageSchema } from './message.js';
 
 
 
+/**
+ * @typedef {import('zod').infer<typeof WorkflowConfigurationSchema>} IWorkflowConfiguration
+ */
 export const WorkflowConfigurationSchema = z.object({
   entities: z.array(zId('Workflow Folder', z.string()), {description: 'Workflow id association, used to handle route params'})
     .min(1, 'Must have at least 1 entity')
@@ -14,8 +17,15 @@ export const WorkflowConfigurationSchema = z.object({
   entity: zId('Workflow Folder', z.string()),
 });
 
+/**
+ * @typedef {import('zod').infer<typeof WorkflowsConfigurationSchema>} IWorkflowsConfiguration
+ */
 export const WorkflowsConfigurationSchema = z.array(WorkflowConfigurationSchema);
 
+
+/**
+ * @typedef {import('zod').infer<typeof ConversationSchema>} IConversation
+ */
 export const ConversationSchema = z.object({
   $agent: zId('Conversation Agent ID', z.string({description: 'Default agent assigned to the conversation(s)'})),
   $customer: zId('Conversation Customer ID', z.string({description: 'Customer this conversation is with'})),
@@ -25,20 +35,41 @@ export const ConversationSchema = z.object({
     subject: z.string({description: 'HTML Subject of the conversation'}).optional(),
     platformEmailThreadId: z.string({description: 'Used to sync email messages with the conversation'}).optional(),
   }).optional(),
+  locked: z.boolean({description: 'Whether the conversation is locked or not'}).optional().nullable(),
+  lockedReason: z.string({description: 'Why this conversation was locked'}).optional().nullable(),
+  lockAttempts: z.number({description: 'Number attempts made until conversation is locked'}).optional().nullable(),
+  forwardedTo: z.string({description: 'What personaId/phone/email was forwarded'}).optional().nullable(),
+  forwarded: z.string({description: 'Datetime ISO 8601 timestamp when persona was forwarded'}).optional().nullable(),
+  forwardNote: z.string().optional().nullable(),
+  intent: z.string({description: 'Detected intent of conversation'}).optional().nullable(),
+  intentScore: z.number({description: 'Confidence score of the assigned intent'}).optional().nullable(),
 });
 
+/**
+ * @typedef {import('zod').infer<typeof IntentWorkflowEventSchema>} IIntentWorkflowEvent
+ */
 export const IntentWorkflowEventSchema = z.object({
  current: z.string().nullable(),
  flow: z.array(z.string()),
  initial: z.string().nullable()
-})
+});
 
+/**
+ * @typedef {import('zod').infer<typeof WorkflowEventSchema>} IWorkflowEvent
+ */
 export const WorkflowEventSchema = z.object({
   messages: z.array(MessageSchema),
   conversation: ConversationSchema,
   context: z.any(),
   message: MessageSchema,
-  agent: agentConfigurationSchema,
+  agent: agentConfigurationSchema.omit({
+    transcripts: true,
+    audios: true,
+    includedLocations: true,
+    excludedLocations: true,
+    model: true,
+    context: true
+  }),
   customer: customerSchema,
   intent: IntentWorkflowEventSchema,
   stagnationCount: z.number(),
@@ -48,7 +79,10 @@ export const WorkflowEventSchema = z.object({
 const Primitive = z.union([z.string(), z.number(), z.boolean()]);
 // Assuming ConversationContext is already defined as a Zod schema
 
-// Lazy is used to handle recursive types.
+/**
+ * Lazy is used to handle recursive types.
+ * @typedef {import('zod').infer<typeof ConversationContext>} IConversation
+ */
 export const ConversationContext = z.lazy(() =>
   z.record(
     Primitive.or(ConversationContext)
@@ -57,15 +91,25 @@ export const ConversationContext = z.lazy(() =>
 
 const ContextSchema = z.record(Primitive.or(ConversationContext));
 
+/**
+ * Forward input information of a conversation
+ * @typedef {import('zod').infer<typeof ForwardSchema>} IForward
+ */
 export const ForwardSchema = z.union([
   z.boolean(),
   z.string(),
   z.object({
     to: z.string().optional(),
     mode: z.enum(['after-reply', 'immediately']).optional(),
+    note: z.string({description: 'Note to provide to the agent'}).optional()
   }),
-]);
+], {description: 'Forward input information of a conversation'});
+
 
+/**
+ * Instruction object schema used to send context to guide conversations
+ * @typedef {import('zod').infer<typeof InstructionSchema>} IInstruction
+ */
 export const InstructionSchema = z.object({
   id: zId('Instruction ID').describe('Unique ID for the instruction, this is used to remove the instruction later'),
   content: z.string(),
@@ -74,6 +118,7 @@ export const InstructionSchema = z.object({
 /**
  * If its a string, it will be sent as a static string.
  * If it's a object or WorkflowResponseMessageAPI - it will use
+ * @typedef {import('zod').infer<typeof WorkflowResponseMessage>} IWorkflowResponseMessage
  */
 export const WorkflowResponseMessage = z.union(
   z.string(),
@@ -84,6 +129,9 @@ export const WorkflowResponseMessage = z.union(
   WorkflowResponseMessageApiRequest
 );
 
+/**
+ * @typedef {import('zod').infer<typeof WorkflowResponseMessageApiRequest>} IWorkflowResponseMessageApiRequest
+ */
 export const WorkflowResponseMessageApiRequest =  z.object({
   uri: z.string(),
   data: z.any().optional(),
@@ -95,6 +143,7 @@ export const WorkflowResponseMessageApiRequest =  z.object({
 
 /**
  * The intended response provided by the WorkflowResponseMessageApiRequest
+ * @typedef {import('zod').infer<typeof WorkflowResponseMessageApiResponse>} IWorkflowResponseMessageApiResponse
  */
 export const WorkflowResponseMessageApiResponse = z.union([
   z.string(),
@@ -116,8 +165,13 @@ export const WorkflowResponseMessageApiResponse = z.union([
   })
 ]);
 
+/**
+ * The workflow response object slot
+ * @typedef {import('zod').infer<typeof WorkflowResponseSlotSchema>} IWorkflowResponseSlot
+ */
 export const WorkflowResponseSlotSchema = z.object({
   forward: ForwardSchema.optional(),
+  forwardNote: z.string({description: 'Note to provide to the agent, recommend using forward object api instead'}).optional(),
   instructions: z.union([z.string(), InstructionSchema, z.array(z.string()), z.array(InstructionSchema)]).optional(),
   removeInstructions: z.array(z.string()).optional(),
   message: z.string().optional(),
@@ -128,7 +182,21 @@ export const WorkflowResponseSlotSchema = z.object({
   resetIntent: z.boolean().optional(),
 });
 
+/**
+ * The workflow response to send in any given workflow
+ * @typedef {import('zod').infer<typeof WorkflowResponseSchema>} IWorkflowResponse
+ */
 export const WorkflowResponseSchema = z.union([
   WorkflowResponseSlotSchema,
   z.array(WorkflowResponseSlotSchema)
 ]);
+
+/**
+ * @typedef {import('zod').infer<typeof WorkflowFunctionSchema>} IWorkflowFunction
+ */
+export const WorkflowFunctionSchema = z.function()
+  .args(WorkflowEventSchema)
+  .returns(z.union([
+    z.promise(WorkflowResponseSchema),
+    WorkflowResponseSchema,
+  ]));

package/src/testing-tools/dev.js

@@ -15,22 +15,22 @@ import { Spirits } from './spirits.js';
 export class Scout9Test {
 
   /**
-   * @type {import('@scout9/app').Customer}
+   * @type {import('@scout9/app').ICustomer}
    */
   customer;
 
   /**
-   * @type {import('@scout9/app').Persona}
+   * @type {import('@scout9/app').IPersona}
    */
   persona;
 
   /**
-   * @type {import('@scout9/app').Conversation}
+   * @type {import('@scout9/app').IConversation}
    */
   conversation;
 
   /**
-   * @type {import('@scout9/app').Message[]}
+   * @type {import('@scout9/app').IMessage[]}
    */
   messages;
 
@@ -41,13 +41,13 @@ export class Scout9Test {
 
   /**
    * @private
-   * @type {import('scout9/app').Scout9ProjectBuildConfig | null}
+   * @type {import('scout9/app').IScout9ProjectBuildConfig | null}
    */
   _project = null;
 
   /**
    * @private
-   * @type {import('@scout9/app').WorkflowFunction | null}
+   * @type {import('@scout9/app').IWorkflowFunction | null}
    */
   _app = null;
 
@@ -86,16 +86,16 @@ export class Scout9Test {
   /**
    * Mimics a customer message to your app (useful for testing)
    * @param props - the Scout9Test properties
-   * @param {import('@scout9/app').Customer | undefined} [props.customer] - customer to use
+   * @param {import('@scout9/app').ICustomer | undefined} [props.customer] - customer to use
    * @param {any | undefined} [props.context] - prior conversation context
    * @param {string | undefined} [props.persona] id to use
-   * @param {import('@scout9/app').Conversation | undefined} [props.conversation] - existing conversation
+   * @param {import('@scout9/app').IConversation | undefined} [props.conversation] - existing conversation
    * @param {string | undefined} [props.cwd]
    * @param {string | undefined} [props.src]
    * @param {string | undefined} [props.mode]
    * @param {import('@scout9/admin').Scout9Api} [props.api]
-   * @param {import('@scout9/app').WorkflowFunction} [props.app]
-   * @param {import('scout9/app').Scout9ProjectBuildConfig} [props.project]
+   * @param {import('@scout9/app').IWorkflowFunction} [props.app]
+   * @param {import('scout9/app').IScout9ProjectBuildConfig} [props.project]
    */
   constructor(
     {
@@ -303,8 +303,8 @@ export class Scout9Test {
   /**
    * Runs your local app workflow
    * @param {string} message - the message to run through the workflow
-   * @param {Omit<Partial<import('@scout9/app').WorkflowEvent>, 'message'> | undefined} [event] - additional event data
-   * @returns {Promise<import('@scout9/app').WorkflowResponse>}
+   * @param {Omit<Partial<import('@scout9/app').IWorkflowEvent>, 'message'> | undefined} [event] - additional event data
+   * @returns {Promise<import('@scout9/app').IWorkflowResponse>}
    */
   async workflow(message, event = {}) {
     if (!this._app) {
@@ -324,7 +324,7 @@ export class Scout9Test {
    * @param {Object} [input] - Generation input, defaults to test registered data such as existing messages, context, and persona information.
    * @param {string} [input.personaId] - Persona ID to use, defaults to test registered persona id.
    * @param {Partial<import('@scout9/admin').ConversationCreateRequest>} [input.conversation] - Conversation overrides, defaults to test registered conversation data.
-   * @param {import('@scout9/app').Message[]} [input.messages] - Message overrides, defaults to test registered message data.
+   * @param {import('@scout9/app').IMessage[]} [input.messages] - Message overrides, defaults to test registered message data.
    * @param {any} [input.context] - Context overrides, defaults to test registered context data.
    * @returns {Promise<import('@scout9/admin').GenerateResponse>}
    */

package/src/testing-tools/mocks.js

@@ -1,7 +1,7 @@
 import moment from 'moment';
 
 /**
- * @returns {import('@scout9/app').Agent}
+ * @returns {import('@scout9/app').IAgent}
  */
 export const createMockAgent = (firstName = 'Carmela', lastName = 'Soprano') => {
   return {
@@ -12,7 +12,7 @@ export const createMockAgent = (firstName = 'Carmela', lastName = 'Soprano') =>
 }
 
 /**
- * @returns {import('@scout9/app').Customer}
+ * @returns {import('@scout9/app').ICustomer}
  */
 export const createMockCustomer = (firstName = 'Tony', lastName = 'Soprano') => {
   return {
@@ -28,7 +28,7 @@ export const createMockCustomer = (firstName = 'Tony', lastName = 'Soprano') =>
  * @param content
  * @param role
  * @param time
- * @returns {import('@scout9/app').Message}
+ * @returns {import('@scout9/app').IMessage}
  */
 export const createMockMessage = (content, role = 'customer', time  = moment().toISOString()) => {
   return {
@@ -42,7 +42,7 @@ export const createMockMessage = (content, role = 'customer', time  = moment().t
 }
 
 /**
- * @returns {import('@scout9/app').Conversation}
+ * @returns {import('@scout9/app').IConversation}
  */
 export const createMockConversation = (environment = 'phone', $agent = 'default', $customer = 'default') => {
   return {
@@ -54,8 +54,8 @@ export const createMockConversation = (environment = 'phone', $agent = 'default'
 
 /**
  * @param {string} message
- * @param {string | import('@scout9/app').WorkflowEvent['intent'] | null} intent
- * @returns {import('@scout9/app').WorkflowEvent}
+ * @param {string | import('@scout9/app').IWorkflowEvent['intent'] | null} intent
+ * @returns {import('@scout9/app').IWorkflowEvent}
  */
 export const createMockWorkflowEvent = (
   message,

package/src/testing-tools/spirits.js

@@ -14,35 +14,35 @@
 
 /**
  * @typedef {Object} ConversationData
- * @property {import('@scout9/app').Scout9ProjectBuildConfig} config - used to define generation and extract persona metadata
- * @property {import('@scout9/app').Conversation} conversation
- * @property {Array<import('@scout9/app').Message>} messages
- * @property {import('@scout9/app').Message} message - the message sent by the customer (should exist in messages)
- * @property {import('@scout9/app').Customer} customer
+ * @property {import('@scout9/app').IScout9ProjectBuildConfig} config - used to define generation and extract persona metadata
+ * @property {import('@scout9/app').IConversation} conversation
+ * @property {Array<import('@scout9/app').IMessage>} messages
+ * @property {import('@scout9/app').IMessage} message - the message sent by the customer (should exist in messages)
+ * @property {import('@scout9/app').ICustomer} customer
  * @property {any} context
  */
 
 /**
  * @typedef {Object} ParseOutput
- * @property {Array<import('@scout9/app').Message>} messages
- * @property {import('@scout9/app').Conversation} conversation
- * @property {import('@scout9/app').Message} message
+ * @property {Array<import('@scout9/app').IMessage>} messages
+ * @property {import('@scout9/app').IConversation} conversation
+ * @property {import('@scout9/app').IMessage} message
  * @property {any} context
  */
 
 /**
  * @typedef {Object} WorkflowOutput
- * @property {Array<import('@scout9/app').WorkflowResponseSlot>} slots
- * @property {Array<import('@scout9/app').Message>} messages
- * @property {import('@scout9/app').Conversation} conversation
+ * @property {Array<import('@scout9/app').IWorkflowResponseSlot>} slots
+ * @property {Array<import('@scout9/app').IMessage>} messages
+ * @property {import('@scout9/app').IConversation} conversation
  * @property {any} context
  */
 
 /**
  * @typedef {Object} GenerateOutput
  * @property {import('@scout9/admin').GenerateResponse | undefined} generate
- * @property {Array<import('@scout9/app').Message>} messages
- * @property {import('@scout9/app').Conversation} conversation
+ * @property {Array<import('@scout9/app').IMessage>} messages
+ * @property {import('@scout9/app').IConversation} conversation
  * @property {any} context
  */
 
@@ -55,8 +55,8 @@
 
 /**
  * @callback WorkflowFun
- * @param {import('@scout9/app').WorkflowEvent} event - conversation data
- * @returns {Promise<import('@scout9/app').WorkflowResponse>}
+ * @param {import('@scout9/app').IWorkflowEvent} event - conversation data
+ * @returns {Promise<import('@scout9/app').IWorkflowResponse>}
  */
 
 /**
@@ -67,7 +67,7 @@
 
 /**
  * @callback IdGeneratorFun
- * @param {import('@scout9/app').Message.role} prefix
+ * @param {import('@scout9/app').IMessage.role} prefix
  * @returns {string}
  */
 /**
@@ -90,10 +90,10 @@
 
 /**
  * @typedef {Object} ConversationEvent
- * @property {Change<import('@scout9/app').Conversation> & {forwardNote?: string; forward?: import('@scout9/app').WorkflowResponseSlot['forward']}} conversation
- * @property {Change<Array<import('@scout9/app').Message>>} messages
+ * @property {Change<import('@scout9/app').IConversation> & {forwardNote?: string; forward?: import('@scout9/app').WorkflowResponseSlot['forward']}} conversation
+ * @property {Change<Array<import('@scout9/app').IMessage>>} messages
  * @property {Change<Object>} context
- * @property {Change<import('@scout9/app').Message>} message
+ * @property {Change<import('@scout9/app').IMessage>} message
  */
 export const Spirits = {
 

package/src/utils/project-templates.js

@@ -7,7 +7,7 @@ function agentsTemplate(agents, exe = 'js') {
   return `
 /**
  * Required core entity type: Agents represents you and your team
- * @returns {Array<import('@scout9/app').Agent>}
+ * @returns {Array<import('@scout9/app').IAgent>}
  */
 export default function Agents() {
   return ${JSON.stringify(agents, null, 2)};
@@ -19,12 +19,13 @@ export default function Agents() {
  * @param {Scout9ProjectBuildConfig} config
  * @param {string} exe - file extension
  * @returns {string}
+ *
  */
 function rootTemplate(config, exe = 'js') {
   return `
 /**
  * Configuration for the Scout9 project.
- * @type {import('@scout9/app').Scout9ProjectConfig}
+ * @type {import('@scout9/app').IScout9ProjectConfig}
  */
 export default {
 
@@ -51,8 +52,8 @@ export default {
 function appTemplate() {
   return `
 /**
- * @param {import('@scout9/app').WorkflowEvent} event - every workflow receives an event object
- * @returns {Promise<import('@scout9/app').WorkflowResponse>} - every workflow must return a WorkflowResponse
+ * @param {import('@scout9/app').IWorkflowEvent} event - every workflow receives an event object
+ * @returns {Promise<import('@scout9/app').IWorkflowResponse>} - every workflow must return a WorkflowResponse
  */
 export default async function Scout9App(event) {
   return {