@scout9/app 1.0.0-alpha.0.1.91 → 1.0.0-alpha.0.1.93

package/src/runtime/client/workflow.js

@@ -6,15 +6,17 @@ 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'})
+  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')
     .max(15, 'Cannot have more than 15 entity paths'),
-  entity: zId('Workflow Folder', z.string()),
+  entity: zId('Workflow Folder', z.string())
 });
 
 /**
@@ -29,11 +31,12 @@ export const WorkflowsConfigurationSchema = z.array(WorkflowConfigurationSchema)
 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'})),
-  initialContexts: z.array(z.string(), {description: 'Initial contexts to load when starting the conversation'}).optional(),
+  initialContexts: z.array(z.string(), {description: 'Initial contexts to load when starting the conversation'})
+    .optional(),
   environment: z.enum(['phone', 'email', 'web']),
   environmentProps: 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(),
+    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(),
@@ -42,16 +45,16 @@ export const ConversationSchema = z.object({
   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(),
+  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()
+  current: z.string().nullable(),
+  flow: z.array(z.string()),
+  initial: z.string().nullable()
 });
 
 /**
@@ -74,7 +77,7 @@ export const WorkflowEventSchema = z.object({
   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
@@ -102,29 +105,36 @@ export const ForwardSchema = z.union([
     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
+ * @typedef {import('zod').infer<typeof InstructionObjectSchema>} 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(),
+export const InstructionObjectSchema = z.object({
+  id: zId('Instruction ID')
+    .describe('Unique ID for the instruction, this is used to remove the instruction later')
+    .optional(),
+  persist: z.boolean()
+    .describe(
+      'if true, the instruction persists the conversation, if false the instruction will only last for 1 auto reply')
+    .default(true)
+    .optional(),
+  content: z.string()
 });
 
 /**
  * @typedef {import('zod').infer<typeof WorkflowResponseMessageApiRequest>} IWorkflowResponseMessageApiRequest
  */
-export const WorkflowResponseMessageApiRequest =  z.object({
+export const WorkflowResponseMessageApiRequest = z.object({
   uri: z.string(),
   data: z.any().optional(),
   headers: z.object({
-    [z.string()]: z.string(),
+    [z.string()]: z.string()
   }).optional(),
-  method: z.enum(["GET", "POST", "PUT"]).optional()
+  method: z.enum(['GET', 'POST', 'PUT']).optional()
 });
 
 /**
@@ -168,19 +178,67 @@ export const WorkflowResponseMessageApiResponse = z.union([
 
 /**
  * The workflow response object slot
- * @typedef {import('zod').infer<typeof WorkflowResponseSlotSchema>} IWorkflowResponseSlot
+ * @typedef {import('zod').infer<typeof InstructionSchema>} IInstruction
+ */
+export const InstructionSchema = z.union([z.string(), InstructionObjectSchema, z.array(z.string()), z.array(
+  InstructionObjectSchema)]);
+
+/**
+ * Base follow up schema to follow up with the client
+ * @typedef {import('zod').infer<typeof FollowupBaseSchema>} IFollowupBase
+ */
+export const FollowupBaseSchema = z.object({
+  scheduled: z.number(),
+  cancelIf: ConversationContext.optional(),
+  overrideLock: z.boolean({description: 'This will still run even if the conversation is locked, defaults to false'}).optional()
+});
+
+/**
+ * Data used to automatically follow up with the client in the future
+ * @typedef {import('zod').infer<typeof FollowupSchema>} IFollowup
+ */
+export const FollowupSchema = z.union([
+  FollowupBaseSchema.extend({
+    message: z.string({description: 'Manual message sent to client'}),
+  }),
+  FollowupBaseSchema.extend({
+    instructions: InstructionSchema
+  })
+]);
+
+/**
+ * The workflow response object slot
+ * @typedef {import('zod').infer<typeof WorkflowResponseSlotBaseSchema>} IWorkflowResponseSlotBase
  */
-export const WorkflowResponseSlotSchema = z.object({
+export const WorkflowResponseSlotBaseSchema = 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(),
+  forwardNote: z.string({description: 'Note to provide to the agent, recommend using forward object api instead'})
+    .optional(),
+  instructions: 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(),
+  followup: FollowupSchema.optional()
+});
+
+/**
+ * The workflow response object slot
+ * @typedef {import('zod').infer<typeof WorkflowResponseSlotSchema>} IWorkflowResponseSlot
+ */
+export const WorkflowResponseSlotSchema = WorkflowResponseSlotBaseSchema.extend({
+  anticipate: z.union([
+    z.object({
+      did: z.string({definition: 'The prompt to check if true or false'}),
+      yes: WorkflowResponseSlotBaseSchema,
+      no: WorkflowResponseSlotBaseSchema
+    }),
+    z.array(WorkflowResponseSlotBaseSchema.extend({
+      keywords: z.array(z.string()).min(1).max(20)
+    }))
+  ]).optional()
 });
 
 /**
@@ -199,5 +257,5 @@ export const WorkflowFunctionSchema = z.function()
   .args(WorkflowEventSchema)
   .returns(z.union([
     z.promise(WorkflowResponseSchema),
-    WorkflowResponseSchema,
+    WorkflowResponseSchema
   ]));

package/src/runtime/index.js

@@ -1,2 +1,3 @@
 export * from './entry.js';
 export * from './client/index.js';
+export * from './macros/index.js';

package/src/runtime/macros/builder.js

@@ -0,0 +1,43 @@
+/**
+ * Builder Macros
+ * used to build and guide a application logic in relation to the Scout9 conversation state.
+ */
+import { Configuration, Scout9Api } from '@scout9/admin';
+import MacroGlobals from './globals.js';
+
+function handleAxiosResponse(res) {
+  if (res.status === 200) {
+    return res.data;
+  } else {
+    throw new Error(`${res.status} ${res.statusText}`)
+  }
+}
+
+/**
+ * The `did` macro takes a given prompt and infers a binary `true` or `false` result in relation to the prompt's subject actor and the prompt's inquiry.
+ * @param {string} prompt
+ * @return {Promise<boolean>}
+ */
+export async function did(prompt) {
+  const convoId = MacroGlobals.$convo();
+  const {value} = (await (new Scout9Api(new Configuration({apiKey: process.env.SCOUT9_API_KEY}))).did({prompt, convoId})
+    .then(handleAxiosResponse));
+  return value;
+}
+
+
+/**
+ * The `context` macro, similar to the `did` macro, takes a natural statement and checks the entire conversation state and extracts or infers a metadata composition result.
+ * @param {string} prompt
+ * @param {import('@scout9/admin').CaptureContextRequestExamples} [examples]
+ * @return {Promise<import('@scout9/admin').CaptureContext200Response>}
+ */
+export async function context(prompt, examples) {
+  const convoId = MacroGlobals.$convo();
+  return (await (new Scout9Api(new Configuration({apiKey: process.env.SCOUT9_API_KEY}))).captureContext({
+    prompt,
+    examples,
+    convoId
+  })
+    .then(handleAxiosResponse));
+}

package/src/runtime/macros/event.js

@@ -0,0 +1,234 @@
+import { WorkflowResponseSlotBaseSchema, WorkflowResponseSlotSchema } from '../client/workflow.js';
+import { MacroUtils } from './utils.js';
+
+
+
+function EventMacros() {
+
+  let slots = [];
+
+  return {
+
+    /**
+     * Sets context into the conversation context for later use
+     * @param {Record<string, any>} updates
+     * @return {this}
+     */
+    upsert(updates) {
+      const slot = {contextUpsert: updates}
+      slots.push(WorkflowResponseSlotSchema.parse(slot));
+      return this;
+    },
+
+    /**
+     * Similar to `instruction` except that it requires a schedule time parameter that determines when to follow up (and is not an event output macro). This will fire another run job with a new insert system context message, if `options.literal` is set to true, it will be an appended agent message prior to running the workflow app.
+     *
+     * @param {string} instruction
+     *
+     * @overload
+     * @param {Date | string} options
+     *
+     * @overload
+     * @param {Object} options
+     * @param {Date | string} options.scheduled
+     * @param {Record<string, any>} [options.cancelIf]
+     * @param {boolean} [options.literal]
+     * @param {boolean} [options.overrideLock]
+     *
+     * @return {this}
+     */
+    followup(instruction, options) {
+      let slot;
+      if (!options) {
+        throw new Error('Missing second argument in followup(instruction, options) \'options\' argument needs to be included')
+      }
+      // Check if it's date value
+      const {success, ...rest} = MacroUtils.scheduledToUnixSafe(options);
+      if (!success) {
+        if (!('scheduled' in options)) {
+          throw new Error('.scheduled was not included in options and needs to be required');
+        }
+        if (typeof options !== 'object') {
+          throw new Error('second argument options in followup is not an object type');
+        }
+
+        // Advance object
+        slot = {
+          followup: {
+            scheduled: MacroUtils.scheduledToUnix(options.scheduled)
+          }
+        }
+        if (options.literal) {
+          slot.followup.message = instruction;
+        } else {
+          slot.followup.instructions = instruction;
+        }
+        if (typeof options.overrideLock === 'boolean') {
+          slot.followup.overrideLock = options.overrideLock;
+        }
+        if (options.cancelIf) {
+          slot.followup.cancelIf = options.cancelIf;
+        }
+
+      } else {
+        // Simple follow up
+        slot = {
+          followup: {
+            instructions: instruction,
+            scheduled: rest.data
+          }
+        }
+
+      }
+      slots.push(WorkflowResponseSlotSchema.parse(slot));
+      return this;
+    },
+
+    /**
+     * Similar to `instruct` except that it requires a schedule time parameter that determines when to follow up (and is not an event output macro). This will fire another run job with a new insert system context message, if `options.literal` is set to true, it will be an appended agent message prior to running the workflow app.
+     * @overload
+     * @param {string} instruction - The instruction to be anticipated as a string. When this is a string, `yes` and `no` must be provided as objects.
+     * @param {object} yes - The object to process if the instruction is a string and the condition is met.
+     * @param {object} no - The object to process if the instruction is a string and the condition is not met.
+     *
+     * @overload
+     * @param {(Array<import('zod').infer<typeof import('../runtime/client/workflow.js').WorkflowResponseSlotBaseSchema> & {keywords: string[]}>)} instruction
+     *
+     * @return {EventMacros}
+     */
+    anticipate(instruction, yes, no) {
+      const slot = {
+        anticipate: []
+      }
+      if (Array.isArray(instruction)) {
+        for (const _slot of instruction) {
+          if (!Array.isArray(_slot.keywords) || _slot.keywords.length < 1) {
+            throw new Error(`Anticipate field .keywords should be an array of string, with more than one value`);
+          }
+          slot.anticipate.push(_slot);
+        }
+      } else if (typeof instruction === 'string') {
+        if (!yes) {
+          throw new Error('Missing "yes" option for anticipate');
+        }
+        if (!no) {
+          throw new Error('Missing "no" option for anticipate');
+        }
+        slot.anticipate = {
+          did: instruction,
+          yes: WorkflowResponseSlotBaseSchema.parse(yes),
+          no: WorkflowResponseSlotBaseSchema.parse(no)
+        }
+      } else {
+        throw new Error(`Instruction is not of type "string" or "array"`);
+      }
+      slots.push(WorkflowResponseSlotSchema.parse(slot));
+      return this;
+    },
+
+    /**
+     *
+     * @param {string} instruction
+     * @param {Object} [options]
+     * @param {string} [options.id] - Unique ID for the instruction, this is used to remove the instruction later
+     * @param {string} [options.persist] - if true, the instruction persists the conversation, if false the instruction will only last for 1 auto reply
+     * @return {EventMacros}
+     */
+    instruct(instruction, options = {}) {
+      const slot = {};
+      if (Object.keys(options).length > 0) {
+        const instructionObj = {
+          content: instruction,
+        }
+        if (options.id) {
+          instructionObj.id = options.id
+        }
+        if (typeof options.persist === 'boolean') {
+          instructionObj.persist = options.persist
+        }
+        slot.instructions = instructionObj;
+      } else {
+        slot.instructions = instruction;
+      }
+      slots.push(WorkflowResponseSlotSchema.parse(slot));
+      return this;
+    },
+    /**
+     * If a manual message must be sent, you can use the `reply` macro
+     * @param {string} message - the message to manually send to the user
+     * @param {Object} [options]
+     * @param {Date | string} [options.scheduled] - this will schedule the date to a specific provided date
+     * @param {string} [options.delay] - delays the message return in seconds
+     * @return {this}
+     */
+    reply(message, options = {}) {
+      const slot = {
+        message
+      };
+      if (Object.keys(options).length) {
+        if ('scheduled' in options) {
+          slot.scheduled = MacroUtils.scheduledToUnix(options.scheduled);
+        }
+        if ('delay' in options) {
+          const delay = options.delay;
+          if (typeof delay !== 'number') {
+            throw new Error('.delay is not of type "number"');
+          }
+          slot.secondsDelay = delay;
+        }
+      }
+      slots.push(WorkflowResponseSlotSchema.parse(slot));
+      return this;
+    },
+    /**
+     * This macro ends the conversation and forwards it the owner of the persona to manually handle the flow. If your app returns undefined or no event, then a default forward is generated.
+     * @param {string} message - the message to forward to owner of persona
+     * @param {Object} [options]
+     * @param {'after-reply' | 'immediately'} [options.mode] - sets forward mode, defaults to "immediately"
+     * @param {string} [options.to] - another phone or email to forward to instead of owner
+     * @return {this}
+     */
+    forward(message, options = {}) {
+      let slot;
+      if (options && Object.keys(options).length) {
+        slot = {
+          forward: {
+            note: message
+          },
+          forwardNote: message
+        }
+        if (options.to) {
+          slot.forward.to = options.to;
+        }
+        if (options.mode) {
+          slot.forward.mode = options.mode;
+        }
+      } else {
+        slot = {
+          forward: true,
+          forwardNote: message
+        }
+      }
+      slots.push(WorkflowResponseSlotSchema.parse(slot));
+      return this;
+    },
+    /**
+     *
+     * @return {Array<(import('zod').infer<typeof import('../runtime/client/workflow.js').WorkflowResponseSlotSchema>)>}
+     */
+    toJSON(flush = true) {
+      if (flush) {
+        const copy = [...slots];
+        slots =[];
+        return copy;
+      } else {
+        return slots;
+      }
+    },
+  };
+}
+
+const eventMacros = EventMacros();
+export const instruct = eventMacros.instruct.bind(eventMacros);
+export const forward = eventMacros.forward.bind(eventMacros);
+export const reply = eventMacros.reply.bind(eventMacros);

package/src/runtime/macros/globals.js

@@ -0,0 +1,14 @@
+
+
+export default class MacroGlobals {
+
+  static $convo() {
+    const $convo = globalThis?.SCOUT9?.$convo;
+    if (!$convo) {
+      throw new Error(`$convo not found in runtime context, ${MacroGlobals.#hint}`);
+    }
+    return $convo;
+  }
+
+  static #hint = `make sure the context is properly instantiated before running workflow.`;
+}

package/src/runtime/macros/index.js

@@ -0,0 +1,3 @@
+export * from './event.js';
+export * from './builder.js';
+export * from './schemas.js';

package/src/runtime/macros/schemas.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+
+export const ContextExampleWithTrainingDataSchema = z.object({
+  input: z.string(),
+  output: z.array(z.record(z.any())),
+});
+
+export const ContextExampleSchema = z.union([
+  z.array(ContextExampleWithTrainingDataSchema),
+  z.array(z.record(z.any())),
+]);
+

package/src/runtime/macros/utils.js

@@ -0,0 +1,31 @@
+function MacroUtilsFactory() {
+
+  return  {
+    dateToUnix(date) { return parseInt((date.getTime() / 1000).toFixed(0))},
+    scheduledToUnixSafe(scheduled) {
+      if (scheduled instanceof Date) {
+        return {data: this.dateToUnix(scheduled), success: true}
+      } else if (typeof scheduled === 'string') {
+        const timestamp = Date.parse(scheduled);
+        if (isNaN(timestamp) === false) {
+          return {data: this.dateToUnix(new Date(timestamp)), success: true };
+        } else {
+          return {error: '.scheduled is an invalid date string', success: false};
+        }
+      } else {
+        return {error: `.scheduled was neither a Date or ISO string`, success: false};
+      }
+    },
+    scheduledToUnix(scheduled) {
+      const {success, ...rest} = this.scheduledToUnixSafe(scheduled);
+      if (success) {
+        return rest.data;
+      } else  {
+        throw new Error(rest.error);
+      }
+    }
+  }
+
+}
+
+export const MacroUtils = MacroUtilsFactory();