@scout9/app 1.0.0-alpha.0.6.4 → 1.0.0-alpha.0.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scout9/app",
-  "version": "1.0.0-alpha.0.6.4",
+  "version": "1.0.0-alpha.0.6.5",
   "description": "Build and deploy your Scout9 app for SMS auto replies",
   "publishConfig": {
     "access": "public"

package/src/public.d.ts

@@ -4,6 +4,8 @@
  * Application platform for managing auto reply workflows from personal communication methods
  */
 
+import { z } from 'zod';
+
 /**
  * @param {WorkflowEvent} event - every workflow receives an event object
  * @param {Object} options
@@ -530,6 +532,21 @@ export type FollowupWithInstructions = FollowupBase & { instructions: Instructio
 
 export type Followup = FollowupWithMessage | FollowupWithInstructions;
 
+/**
+ * Metadata to provide a atomic transaction on a entity context record
+ * @ingress auto/manual only
+ */
+export type EntityContextUpsert = {
+    entityType: string;
+    entityRecordId: string;
+    method: 'mutate' | 'delete'
+} & ({
+    method: 'delete'
+} | {
+    method: 'mutate';
+    fields: Record<string, string | number | boolean | null | '#remove' | '#delete'>;
+});
+
 export type Forward = boolean | string | {
     to?: string | undefined;
     mode?: ("after-reply" | "immediately") | undefined;
@@ -554,6 +571,9 @@ export type EntityToken = {
 export type Message = {
     /** Unique ID for the message */
     id: string;
+    /**
+     * @TODO role:agent is inaccurate it should be "persona"
+     */
     role: "agent" | "customer" | "system";
     content: string;
     /** Datetime ISO 8601 timestamp */
@@ -571,6 +591,10 @@ export type Message = {
     delayInSeconds?: (number | null) | undefined;
     /** Entities related to the message */
     entities?: EntityToken[] | null;
+    /** If set to true, the PMT will not transform, message will be sent as is */
+    ignoreTransform?: boolean;
+    /** Media urls to attach to the transported message */
+    mediaUrls?: string[];
 };
 
 export type PersonaConfiguration = AgentConfiguration;
@@ -666,27 +690,79 @@ export type AnticipateKeywords = WorkflowResponseSlotBase & {
 
 export type Anticipate = AnticipateDid | AnticipateKeywords[];
 
+export type DirectMessagePayload = {
+    /**
+     * The content
+     */
+    content: string;
+
+    /**
+     * If true, the PMT will transform the message into the owners own words. By default will send the message as is
+     */
+    transform?: boolean;
+
+    mediaUrls?: string[];
+};
+
+/**
+ * Workflow Response Slot, can use for both PMT workflow event and event macro runtimes
+ */
 export type WorkflowResponseSlotBase = {
     /** Forward input information of a conversation */
     forward?: Forward | undefined;
     /** Note to provide to the agent, recommend using forward object api instead */
     forwardNote?: string | undefined;
+
+    /** Instructions to send to the PMT on how to steer the conversation */
     instructions?: Instruction[] | undefined;
+
+    /** Remove instructions from memory (requires set instructions to have ids) */
     removeInstructions?: string[] | undefined;
-    message?: string | {content: string; transform?: boolean} | undefined;
+
+    /** If provided, sends a direct message to the user */
+    message?: string | DirectMessagePayload | undefined;
+
+    /** Delays in seconds of instructions (if provided) to PMT and direct message (if provided) to user */
     secondsDelay?: number | undefined;
+
+    /** unix time of when to send instructions or message */
     scheduled?: number | undefined;
+
+    /** Context to upsert to the conversation */
     contextUpsert?: {
         [x: string]: any;
     } | undefined;
+
+    /** If true, resets the conversations intent value to undefined or to its initial value */
     resetIntent?: boolean | undefined;
+
+    /** Information to follow up to the client */
     followup?: Followup | undefined;
 };
 
+/**
+ * Workflow Response Slot, only PMT workflow events
+ */
 export type WorkflowResponseSlot = WorkflowResponseSlotBase & {
+    /**
+     * The Anticipate API acts as a preflight to the users next response, for example:
+     *      - did the user agree to accept the concert tickets? Then proceed with asking for their email
+     *      - Did the user say any of these words: "cancel", "drop", or "remove"? Then cancel tickets
+     */
     anticipate?: Anticipate | undefined;
+
+
+    /**
+     * If provided, it will propagate entity context to your Scout9 entity context store
+     * @ingress auto/manual only
+     */
+    entityContextUpsert?: Array<EntityContextUpsert> | undefined;
 };
 
+/**
+ * The JSON anticipated response for a given workflow to drive the PMT runtime
+ * Can either be an EventMacro or WorkflowResponseSlot
+ */
 export type WorkflowResponse = EventMacros | WorkflowResponseSlot | (WorkflowResponseSlot | EventMacros)[];
 
 export type WorkflowFunction = (event: WorkflowEvent) => WorkflowResponse | Promise<WorkflowResponse>;

package/src/runtime/schemas/message.js

@@ -20,5 +20,7 @@ export const MessageSchema = z.object({
   intent: z.string({description: 'Detected intent'}).optional().nullable(),
   intentScore: z.number({description: 'Confidence score of the assigned intent'}).nullable().optional(),
   delayInSeconds: z.number({description: 'How long to delay the message manually in seconds'}).nullable().optional(),
-  entities: z.array(MessageEntitySchema).optional().nullable()
+  entities: z.array(MessageEntitySchema).optional().nullable(),
+  ignoreTransform: z.boolean({description: 'If set to true, the PMT will not transform, message will be sent as is'}).optional(),
+  mediaUrls: z.array(z.string(), {description: 'Media urls to attach to the transported message'}).optional().nullable()
 });

package/src/testing-tools/spirits.js

@@ -112,6 +112,7 @@
  * @property {Change<any>} context
  * @property {Change<import('@scout9/app').Message>} message
  * @property {Array<import('@scout9/app').Followup>} followup
+ * @property {Array<import('@scout9/app').EntityContextUpsert>} entityContextUpsert
  */
 export const Spirits = {
 
@@ -138,6 +139,7 @@ export const Spirits = {
     } = input;
     let {conversation, messages, context, message} = input;
     const followup = [];
+    const entityContextUpsert = [];
 
     // 0. Setup Helpers
     const updateConversation = (previousConversation, conversationUpdates) => {
@@ -398,6 +400,7 @@ export const Spirits = {
       contextUpsert,
       anticipate,
       followup: slotFollowup,
+      entityContextUpsert: slotEntityContextUpsert
     } of slots) {
 
       // Anticipate customer response
@@ -439,6 +442,10 @@ export const Spirits = {
         followup.push(slotFollowup);
       }
 
+      if (slotEntityContextUpsert && slotEntityContextUpsert.length) {
+        entityContextUpsert.push(...slotEntityContextUpsert);
+      }
+
       // Forward to agent or other agent
       if (forward) {
         conversation = lockConversation(conversation, 'App instructed forward');
@@ -680,7 +687,8 @@ export const Spirits = {
         before: contextBefore,
         after: context
       },
-      followup
+      followup,
+      entityContextUpsert
     };
   }
 };