@scout9/app 1.0.0-alpha.0.1.9 → 1.0.0-alpha.0.1.90

package/src/runtime/client/{agent.js → users.js}

@@ -2,8 +2,14 @@ import { z } from 'zod';
 import { zId } from './utils.js';
 import { MessageSchema } from './message.js';
 
+/**
+ * @typedef {import('zod').infer<typeof customerValueSchema>} ICustomerValue
+ */
 export const customerValueSchema = z.union([z.boolean(), z.number(), z.string()]);
 
+/**
+ * @typedef {import('zod').infer<typeof customerSchema>} ICustomer
+ */
 export const customerSchema = z.object({
   firstName: z.string().optional(),
   lastName: z.string().optional(),
@@ -24,8 +30,16 @@ export const customerSchema = z.object({
   stripeDev: z.string().nullable().optional()
 }).catchall(customerValueSchema);
 
-export const agentConfigurationSchema = z.object({
-  id: zId('Agent ID', z.string({description: 'Unique ID for agent'})),
+/**
+ * @typedef {import('zod').infer<typeof agentBaseConfigurationSchema>} IAgentBase
+ */
+export const agentBaseConfigurationSchema = z.object({
+  deployed: z.object({
+    web: z.string({description: 'Web URL for agent'}).optional(),
+    phone: z.string({description: 'Phone number for agent'}).optional(),
+    email: z.string({description: 'Email address for agent'}).optional()
+  }).optional(),
+  img: z.string().nullable().optional(),
   firstName: z.string({description: 'Agent first name'}).optional(),
   lastName: z.string({description: 'Agent last name'}).optional(),
   inactive: z.boolean({description: 'Agent is inactive'}).optional(),
@@ -40,6 +54,24 @@ export const agentConfigurationSchema = z.object({
   excludedLocations: z.array(z.string({description: 'Locations the agent is excluded from'})).optional(),
   model: z.enum(['Scout9', 'bard', 'openai']).optional().default('openai'),
   transcripts: z.array(z.array(MessageSchema)).optional(),
-  audioRef: z.array(z.any()).optional()
+  audios: z.array(z.any()).optional()
+});
+
+/**
+ * @typedef {import('zod').infer<typeof agentBaseConfigurationSchema>} IAgent
+ * @typedef {import('zod').infer<typeof agentBaseConfigurationSchema>} IPersona
+ */
+export const agentConfigurationSchema = agentBaseConfigurationSchema.extend({
+  id: zId('Agent ID', {description: 'Unique ID for agent'}),
 });
+
+/**
+ * @typedef {import('zod').infer<typeof agentsConfigurationSchema>} IAgentsConfiguration
+ */
 export const agentsConfigurationSchema = z.array(agentConfigurationSchema);
+
+/**
+ * @typedef {import('zod').infer<typeof agentsBaseConfigurationSchema>} IAgentsBaseConfiguration
+ */
+export const agentsBaseConfigurationSchema = z.array(agentBaseConfigurationSchema);
+

package/src/runtime/client/utils.js

@@ -1,11 +1,12 @@
-import { ZodString } from 'zod';
+import { z } from 'zod';
 
-export function zId(name, strType) {
-  if (strType instanceof ZodString) {
-    return strType.regex(/^[A-Za-z0-9\-_\[\]]+$/, {
-      message: `Invalid ${name} ID: ID must not contain spaces and should only contain alphanumeric characters, dashes, or underscores.`
-    });
-  } else {
-    throw new Error(`Invalid zId type: ${strType}`);
-  }
+/**
+ * @param {string} name
+ * @param {Object} [props]
+ * @returns {import('zod').ZodString}
+ */
+export function zId(name, props = {}) {
+  return z.string(props).regex(/^[A-Za-z0-9\-_\[\]]+$/, {
+    message: `Invalid ${name} ID: ID must not contain spaces and should only contain alphanumeric characters, dashes, or underscores.`
+  });
 }

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,22 +35,54 @@ 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()
 });
 
-export const WorkflowEventSchema = {
+/**
+ * @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: z.string(),
-}
+  intent: IntentWorkflowEventSchema,
+  stagnationCount: z.number(),
+  note: z.string({description: 'Any developer notes to provide'}).optional()
+})
 
 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)
@@ -49,32 +91,112 @@ 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', z.string()).description('Unique ID for the instruction, this is used to remove the instruction later'),
+  id: zId('Instruction ID').describe('Unique ID for the instruction, this is used to remove the instruction later'),
   content: z.string(),
 });
+
+/**
+ * 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(),
+
+  /**
+   * An api call that should be called later, must return a string or {message: string}
+   */
+  WorkflowResponseMessageApiRequest
+);
+
+/**
+ * @typedef {import('zod').infer<typeof WorkflowResponseMessageApiRequest>} IWorkflowResponseMessageApiRequest
+ */
+export const WorkflowResponseMessageApiRequest =  z.object({
+  uri: z.string(),
+  data: z.any().optional(),
+  headers: z.object({
+    [z.string()]: z.string(),
+  }).optional(),
+  method: z.enum(["GET", "POST", "PUT"]).optional()
+});
+
+/**
+ * The intended response provided by the WorkflowResponseMessageApiRequest
+ * @typedef {import('zod').infer<typeof WorkflowResponseMessageApiResponse>} IWorkflowResponseMessageApiResponse
+ */
+export const WorkflowResponseMessageApiResponse = z.union([
+  z.string(),
+  z.object({
+    message: z.string()
+  }),
+  z.object({
+    text: z.string()
+  }),
+  z.object({
+    data: z.object({
+      message: z.string()
+    })
+  }),
+  z.object({
+    data: z.object({
+      text: z.string()
+    })
+  })
+]);
+
+/**
+ * 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(),
+  // message: WorkflowResponseMessage.optional(),
   secondsDelay: z.number().optional(),
   scheduled: z.number().optional(),
   contextUpsert: ConversationContext.optional(),
   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/runtime/entry.js

@@ -63,12 +63,12 @@ function customRequire(folder, moduleName) {
 
 export async function runInVM(
   event,
-  {folder, filePath, fileName}
+  {src, filePath, fileName}
 ) {
   // Prepare the script context
   const scriptExports = {};
   const context = vm.createContext({
-    require: (moduleName) => customRequire(folder, moduleName),
+    require: (moduleName) => customRequire(src, moduleName),
     console,
     module: { exports: scriptExports },
     exports: scriptExports,

package/src/testing-tools/dev.js

@@ -0,0 +1,373 @@
+import { Configuration, Scout9Api } from '@scout9/admin';
+import {grey, italic, bgWhite, black} from 'kleur/colors';
+import { createMockConversation, createMockWorkflowEvent } from './mocks.js';
+import { loadConfig } from '../core/config/index.js';
+import { requireProjectFile } from '../utils/index.js';
+import { globSync } from 'glob';
+
+export * from './spirits.js';
+
+import { Spirits } from './spirits.js';
+
+/**
+ * Testing tool kit, used to handle Scout9 operations such as parsing, workflow, and generating responses
+ */
+export class Scout9Test {
+
+  /**
+   * @type {import('../runtime/client/users.js').ICustomer}
+   */
+  customer;
+
+  /**
+   * @type {import('../runtime/client/users.js').IPersona}
+   */
+  persona;
+
+  /**
+   * @type {import('../runtime/client/workflow.js').IConversation}
+   */
+  conversation;
+
+  /**
+   * @type {import('../runtime/client/message.js').IMessage[]}
+   */
+  messages;
+
+  /**
+   * @type {any}
+   */
+  context;
+
+  /**
+   * @private
+   * @type {import('../runtime/client/config.js').IScout9ProjectBuildConfig | null}
+   */
+  _project = null;
+
+  /**
+   * @private
+   * @type {import('../runtime/client/workflow.js').IWorkflowFunction | null}
+   */
+  _app = null;
+
+  /**
+   * @private
+   * @type {import('@scout9/admin').Scout9Api | null}
+   */
+  _api = null;
+
+  /**
+   * @private
+   */
+  _cwd;
+
+  /**
+   * @private
+   */
+  _src;
+
+  /**
+   * @private
+   */
+  _mode;
+
+  /**
+   * @private
+   */
+  _loaded;
+
+  /**
+   * @private
+   */
+  _personaId;
+
+
+  /**
+   * Mimics a customer message to your app (useful for testing)
+   * @param props - the Scout9Test properties
+   * @param {import('../runtime/client/users.js').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('../runtime/client/workflow.js').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('../runtime/client/workflow.js').IWorkflowFunction} [props.app]
+   * @param {import('../runtime/client/config.js').IScout9ProjectBuildConfig} [props.project]
+   */
+  constructor(
+    {
+      persona,
+      customer,
+      context,
+      conversation = createMockConversation(),
+      cwd = process.cwd(),
+      src = 'src',
+      mode = 'production',
+      api,
+      app,
+      project
+    } = {
+      cwd: process.cwd(),
+      src: 'src',
+      mode: 'production'
+    }
+  ) {
+    this.messages = [];
+    this._cwd = cwd;
+    this._src = src;
+    this._mode = mode;
+    this.context = context || {};
+    this.conversation = conversation;
+    if (api) {
+      this._api = api;
+    }
+    if (app) {
+      this._app = app;
+    }
+    if (project) {
+      this._project = project;
+    }
+    if (!customer) {
+      customer = {
+        id: 'mock_customer_' + Math.random().toString(36).slice(2, 11),
+        name: 'Mock Customer',
+        firstName: 'Mock',
+        lastName: 'Customer'
+      };
+      this.conversation.$customer = customer.id;
+    } else {
+      this.conversation.$customer = customer.id;
+    }
+    this.customer = customer;
+    this.context.customer = customer;
+    this._personaId = persona;
+  }
+
+  /**
+   * Loads the test environment
+   * @param {boolean} [override] - defaults to false, if true, it will override the current loaded state such as the scout9 api, workflow function, and project config
+   * @returns {Promise<void>}
+   */
+  async load(override = false) {
+
+    // Load app (if not already loaded or override true)
+    if (override || !this._app) {
+      this._app = await this._loadApp();
+    }
+
+    // Load app configuration (if not already loaded or override true)
+    if (override || !this._project) {
+      this._project = await loadConfig({cwd: this._cwd, src: this._src, mode: this._mode})
+    }
+
+    if (override || !this._api) {
+      this._api = new Scout9Api(new Configuration({apiKey: process.env.SCOUT9_API_KEY}));
+    }
+
+    if (!this._personaId) {
+      this._personaId = (this._project.persona || this._project.agents)?.[0]?.id;
+      if (!this._personaId) {
+        throw new Error(`No persona found in config, please specify a persona id`);
+      }
+    }
+    this.conversation.$agent = this._personaId;
+    this.persona = (this._project.persona || this._project.agents).find(p => p.id === this._personaId);
+    if (!this.persona) {
+      throw new Error(`Could not find persona with id: ${this._personaId}, ensure your project is sync'd by running "scout9 sync" or you are using the correct persona id`);
+    }
+    this.context.agent = this.persona;
+    this._loaded = true;
+  }
+
+  /**
+   * Teardown the test environment
+   */
+  teardown() {
+    this._loaded = false;
+    this._api = null;
+    this._project = null;
+    this._app = null;
+  }
+
+  /**
+   * Send a message as a customer to your app
+   * @param {string} message - message to send
+   * @param {import('@scout9/app/testing-tools').StatusCallback | boolean} [progress] - progress callback, if true, will log progress, can override with your own callback. If not provided, no logs will be added.
+   * @returns {Promise<ConversationEvent>}
+   */
+  async send(message, progress = false) {
+    if (!this._loaded) {
+      await this.load();
+    }
+
+    const defaultProgressLogger = (message, level = 'info', type = '') => {
+      const typeStdout = type ? italic(bgWhite(' ' + black(type) + ' ')) : '';
+      const messageStdout = grey(message);
+      (console.hasOwnProperty(level) ? console[level] : console.log)(`\t${typeStdout ? typeStdout + ' ' : ''}${messageStdout}`);
+    }
+
+    // If custom logger provided, use it, otherwise use default logger
+    let progressInput = typeof progress === 'function' ? progress : defaultProgressLogger;
+
+    // If progress turned off, use a no-op function
+    if (typeof progress === 'boolean') {
+      if (!!progress) {
+        progressInput = defaultProgressLogger; // use default logger
+      } else {
+        progressInput = () => {}; // use no-op
+      }
+    }
+
+    const _message = {
+      id: 'user_mock_' + Math.random().toString(36).slice(2, 11),
+      role: 'customer',
+      content: message,
+      time: new Date().toISOString()
+    };
+    this.messages.push(_message);
+    const result = await Spirits.customer({
+      customer: this.customer,
+      config: this._project,
+      parser: async (_msg, _lng) => {
+        // @TODO can't do this for HUGE data sets
+        const detectableEntities = this._project.entities.filter(e => e.training?.length > 0 && e.definitions?.length > 0);
+        return this._api.parse({
+          message: _msg,
+          language: _lng,
+          entities: detectableEntities
+        }).then((_res => _res.data));
+      },
+      workflow: async (event) => {
+        return this._app(event);
+      },
+      generator: (request) => {
+        return this._api.generate(request).then((_res => _res.data));
+      },
+      idGenerator: (prefix) => prefix + '_' + Math.random().toString(36).slice(2, 11),
+      progress: progressInput,
+      message: _message,
+      context: this.context,
+      messages: this.messages,
+      conversation: this.conversation
+    });
+
+    this.context = result.context.after;
+    this.messages = result.messages.after;
+    this.conversation = result.conversation.after;
+
+    if (!!result.conversation.forward) {
+      // @TODO migrate this
+      if (typeof result.conversation.forward === 'string') {
+        this.conversation.forwardedTo = result.conversation.forward;
+      } else if (result.conversation.forward === true) {
+        this.conversation.forwardedTo = this.persona.forwardPhone || this.persona.forwardEmail || 'No Forward';
+      } else if (!!result.conversation.forward?.to) {
+        this.conversation.forwardedTo = result.conversation.forward.to;
+      } else {
+        console.error(`Invalid forward result`, result.conversation.forward);
+        this.conversation.forwardedTo = 'Invalid Forward';
+      }
+      this.conversation.forwarded = new Date().toString();
+      this.conversation.forwardNote = result.conversation.forwardNote || '';
+      this.conversation.locked = true;
+      this.conversation.lockedReason = result.conversation.forwardNote ?? ('Forwarded to ' + this.conversation.forwardedTo);
+    }
+
+    if (!result.messages.after.find(m => m.id === result.message.after.id)) {
+      console.error(`Message not found in result.messages.after`, result.message.after.id);
+    }
+
+    return result;
+  }
+
+  /**
+   * Parse user message
+   * @param {string} message - message string to parse
+   * @param {string} [language] - language to parse in, defaults to "en" for english
+   * @returns {Promise<import('@scout9/admin').ParseResponse>}
+   */
+  async parse(message, language = 'en') {
+    if (!this._project) {
+      throw new Error(`Config is not defined`);
+    }
+    return this._api.parse({
+      message,
+      language,
+      entities: this._project.entities
+    }).then((_res => _res.data));
+  }
+
+  /**
+   * Runs your local app workflow
+   * @param {string} message - the message to run through the workflow
+   * @param {Omit<Partial<import('../runtime/client/workflow.js').IWorkflowEvent>, 'message'> | undefined} [event] - additional event data
+   * @returns {Promise<import('../runtime/client/workflow.js').IWorkflowResponse>}
+   */
+  async workflow(message, event = {}) {
+    if (!this._app) {
+      throw new Error(`Workflow function is not loaded or found - make sure to run ".load()" before calling ".workflow()"`);
+    }
+    if (event.hasOwnProperty('message')) {
+      console.warn(`WARNING: inserting a "event.message" will overwrite your "message" argument`);
+    }
+    return this._app({
+      ...createMockWorkflowEvent(message),
+      ...event
+    });
+  }
+
+  /**
+   * Generate a response to the user from the given or registered persona's voice in relation to the current conversation's context.
+   * @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('../runtime/client/message.js').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>}
+   */
+  async generate({personaId = this._personaId, conversation = {}, messages = this.messages, context = this.context}) {
+    if (!this._api) {
+      throw new Error(`Scout9 API is not loaded or found - make sure to run ".load()" before calling ".generate()"`);
+    }
+    if (!this._project) {
+      throw new Error(`Config is not defined - make sure to run ".load()" before calling ".generate()"`);
+    }
+    const persona = (this._project.persona || this._project.agents).find(p => p.id === personaId);
+    if (!persona) {
+      throw new Error(`Could not find persona with id: ${personaId}, ensure your project is sync'd by running "scout9 sync"`);
+    }
+    return this._api.generate({
+      convo: {
+        $customer: this.customer.id,
+        environment: this.conversation.environment,
+        initialContexts: this.conversation.initialContexts || [],
+        ...conversation,
+        $agent: persona
+      },
+      messages,
+      context,
+      persona,
+      llm: this._project.llm,
+      pmt: this._project.pmt
+    }).then((_res => _res.data));
+  }
+
+  /**
+   * @private
+   */
+  async _loadApp() {
+    const paths = globSync(`${this._src}/app.{ts,cjs,mjs,js}`, {cwd: this._cwd, absolute: true});
+    if (paths.length === 0) {
+      throw new Error(`Missing main project entry file ${this._src}/app.{js|ts|cjs|mjs}`);
+    } else if (paths.length > 1) {
+      throw new Error(`Multiple main project entry files found ${this._src}/app.{js|ts|cjs|mjs}`);
+    }
+    const [appFilePath] = paths;
+    return requireProjectFile(appFilePath)
+      .then(mod => mod.default);
+  }
+
+}

package/src/testing-tools/index.js

@@ -1 +1,2 @@
 export * from './mocks.js';
+export * from './dev.js';