@botonic/plugin-flow-builder 0.56.0 → 0.57.0-alpha.0

package/src/api.ts

@@ -1,7 +1,12 @@
-import type { PluginPreRequest } from '@botonic/core'
+import type { BotContext } from '@botonic/core'
 import axios from 'axios'
 
-import { AI_AGENTS_FLOW_NAME, SEPARATOR, UUID_REGEXP } from './constants'
+import {
+  AI_AGENTS_FLOW_NAME,
+  PUSH_FLOW_PAYLOAD,
+  SEPARATOR,
+  UUID_REGEXP,
+} from './constants'
 import {
   type HtBotActionNode,
   type HtCaptureUserInputNode,
@@ -31,7 +36,7 @@ export class FlowBuilderApi {
   url: string
   flowUrl: string
   flow: HtFlowBuilderData
-  request: PluginPreRequest
+  botContext: BotContext
 
   private constructor() {}
 
@@ -39,12 +44,12 @@ export class FlowBuilderApi {
     const newApi = new FlowBuilderApi()
 
     newApi.url = options.url
-    newApi.request = options.request
+    newApi.botContext = options.botContext
     // TODO: Refactor later to combine logic from `FlowBuilderApi.create`, `resolveFlowUrl` and `getAccessToken` to be in one place
     if (process.env.NODE_ENV === ProcessEnvNodeEnvs.DEVELOPMENT) {
       await newApi.updateSessionWithUserInfo(options.accessToken)
     }
-    const updatedRequest = newApi.request
+    const updatedRequest = newApi.botContext
     newApi.flowUrl = options.flowUrl.replace(
       '{bot_id}',
       updatedRequest.session.bot.id
@@ -65,8 +70,8 @@ export class FlowBuilderApi {
     const response = await axios.get(url, {
       headers: { Authorization: `Bearer ${token}` },
     })
-    this.request.session.organization_id = response.data.organization_id
-    this.request.session.bot.id = response.data.bot_id
+    this.botContext.session.organization_id = response.data.organization_id
+    this.botContext.session.bot.id = response.data.bot_id
   }
 
   getNodeByFlowId(id: string): HtNodeWithContent {
@@ -260,23 +265,23 @@ export class FlowBuilderApi {
   }
 
   getCaptureUserInputId(): string | undefined {
-    return this.request.session.capture_user_input?.node_id
+    return this.botContext.session.capture_user_input?.node_id
   }
 
   setCaptureUserInputId(id: string): void {
-    if (this.request.session.capture_user_input) {
-      this.request.session.capture_user_input.node_id = id
+    if (this.botContext.session.capture_user_input) {
+      this.botContext.session.capture_user_input.node_id = id
     }
-    this.request.session.capture_user_input = { node_id: id }
+    this.botContext.session.capture_user_input = { node_id: id }
   }
 
   removeCaptureUserInputId(): void {
-    this.request.session.capture_user_input = undefined
+    this.botContext.session.capture_user_input = undefined
   }
 
   setUserExtraDataVariable(key: string, value: string): void {
-    if (this.request.session.user.extra_data) {
-      this.request.session.user.extra_data[key] = value
+    if (this.botContext.session.user.extra_data) {
+      this.botContext.session.user.extra_data[key] = value
     }
   }
 
@@ -289,18 +294,18 @@ export class FlowBuilderApi {
   }
 
   getSessionWhatsappRequestContactId(): string | undefined {
-    return this.request.session.whatsapp_request_contact?.id
+    return this.botContext.session.whatsapp_request_contact?.id
   }
 
   setWhatsappRequestContactId(id: string): void {
-    if (this.request.session.whatsapp_request_contact) {
-      this.request.session.whatsapp_request_contact.id = id
+    if (this.botContext.session.whatsapp_request_contact) {
+      this.botContext.session.whatsapp_request_contact.id = id
     }
-    this.request.session.whatsapp_request_contact = { id }
+    this.botContext.session.whatsapp_request_contact = { id }
   }
 
   removeWhatsappRequestContactId(): void {
-    this.request.session.whatsapp_request_contact = undefined
+    this.botContext.session.whatsapp_request_contact = undefined
   }
 
   getWhatsappRequestContactInfoNode():
@@ -320,9 +325,13 @@ export class FlowBuilderApi {
     const defaultLocaleCode = this.flow.default_locale_code
 
     return new FlowLocale(
-      this.request,
+      this.botContext,
       flowLocales,
       defaultLocaleCode
     ).resolve()
   }
+
+  isPushFlowPayload(payload?: string): boolean {
+    return payload?.startsWith(PUSH_FLOW_PAYLOAD) ?? false
+  }
 }

package/src/bot-context-manager.ts

@@ -0,0 +1,153 @@
+import {
+  type BotContext,
+  INPUT,
+  PROVIDER,
+  WhatsappInputOrigin,
+} from '@botonic/core'
+
+import type { FlowBuilderApi } from './api'
+import {
+  EMPTY_PAYLOAD,
+  ON_CLOSE_HANDOFF_PAYLOAD,
+  SEPARATOR,
+  SOURCE_INFO_SEPARATOR,
+} from './constants'
+import { FlowHandoff } from './content-fields'
+import {
+  type HtBotActionNode,
+  type HtHandoffNode,
+  HtNodeWithContentType,
+} from './content-fields/hubtype-fields'
+import { getNextPayloadByUserInput } from './user-input'
+import type { SmartIntentsInferenceConfig } from './user-input/smart-intent'
+import { inputHasTextOrTranscript } from './utils/input'
+
+export class BotContextManager {
+  constructor(
+    private readonly cmsApi: FlowBuilderApi,
+    private readonly smartIntentsConfig: SmartIntentsInferenceConfig
+  ) {}
+
+  async updateBeforeRoutes(botContext: BotContext): Promise<void> {
+    // When AI Agent is executed in Whatsapp, button payloads come as referral and must be converted to text being processed by the agent.
+    this.convertWhatsappAiAgentEmptyPayloads(botContext)
+
+    // If the payload is a push-flow payload, set first interaction to false
+    this.updateFirstInteractionOnPushFlowPayload(botContext)
+
+    this.resolveWhatsappContactRequestPayload(botContext)
+    this.resolveOnCloseHandoffPayload(botContext)
+
+    await this.resolvePayloadFromUserTextInput(botContext)
+
+    this.cmsApi.removeCaptureUserInputId()
+    this.removePayloadSourceSuffix(botContext)
+    this.resolveBotActionPayload(botContext)
+  }
+
+  private async updateFirstInteractionOnPushFlowPayload(
+    botContext: BotContext
+  ): Promise<void> {
+    if (this.cmsApi.isPushFlowPayload(botContext.input.payload)) {
+      botContext.session.is_first_interaction = false
+    }
+  }
+
+  private async resolvePayloadFromUserTextInput(
+    botContext: BotContext
+  ): Promise<void> {
+    const checkUserTextInput =
+      inputHasTextOrTranscript(botContext.input) && !botContext.input.payload
+
+    if (!checkUserTextInput) {
+      return
+    }
+
+    const resolvedLocale = this.cmsApi.getResolvedLocale()
+    const nextPayload = await getNextPayloadByUserInput(
+      this.cmsApi,
+      resolvedLocale,
+      botContext,
+      this.smartIntentsConfig
+    )
+    botContext.input.payload = nextPayload
+  }
+
+  private resolveWhatsappContactRequestPayload(botContext: BotContext): void {
+    if (
+      botContext.input.type !== INPUT.CONTACT ||
+      botContext.input.origin !== WhatsappInputOrigin.ContactRequest
+    ) {
+      return
+    }
+
+    const whatsappRequestContactInfoNode =
+      this.cmsApi.getWhatsappRequestContactInfoNode()
+
+    if (whatsappRequestContactInfoNode) {
+      botContext.input.payload = this.cmsApi.getPayload(
+        whatsappRequestContactInfoNode.content.button.target
+      )
+    }
+
+    this.cmsApi.removeWhatsappRequestContactId()
+  }
+
+  private resolveOnCloseHandoffPayload(botContext: BotContext): void {
+    if (botContext.input.payload?.startsWith(ON_CLOSE_HANDOFF_PAYLOAD)) {
+      const handoffNodeId = botContext.input.payload.split(SEPARATOR)[1]
+      const handoffNode = this.cmsApi.getNodeById<HtHandoffNode>(handoffNodeId)
+      if (handoffNode && handoffNode.type === HtNodeWithContentType.HANDOFF) {
+        const flowHandoff = FlowHandoff.fromHubtypeCMS(
+          handoffNode,
+          this.cmsApi.getResolvedLocale(),
+          this.cmsApi
+        )
+        botContext.input.payload = flowHandoff.resolveOnClosePayload(botContext)
+      }
+    }
+  }
+
+  private convertWhatsappAiAgentEmptyPayloads(botContext: BotContext): void {
+    if (botContext.session.user.provider === PROVIDER.WHATSAPP) {
+      const shouldUseReferral =
+        botContext.input.referral &&
+        botContext.input.payload?.startsWith(EMPTY_PAYLOAD)
+
+      if (shouldUseReferral) {
+        botContext.input.type = INPUT.TEXT
+        botContext.input.data = botContext.input.referral
+      }
+    }
+  }
+
+  private removePayloadSourceSuffix(botContext: BotContext): void {
+    if (botContext.input.payload) {
+      botContext.input.payload = this.removeSourceSuffix(
+        botContext.input.payload
+      )
+    }
+  }
+
+  private resolveBotActionPayload(botContext: BotContext): void {
+    if (
+      botContext.input.payload &&
+      this.cmsApi.isBotAction(botContext.input.payload)
+    ) {
+      const cmsBotAction = this.cmsApi.getNodeById<HtBotActionNode>(
+        botContext.input.payload
+      )
+
+      botContext.input.payload =
+        this.cmsApi.createPayloadWithParams(cmsBotAction)
+
+      // Re-execute convertWhatsappAiAgentEmptyPayloads function to handle
+      // the case that a BotAction has a payload equals to EMPTY_PAYLOAD
+      this.convertWhatsappAiAgentEmptyPayloads(botContext)
+    }
+  }
+
+  private removeSourceSuffix(payload: string): string {
+    return payload.split(SOURCE_INFO_SEPARATOR)[0]
+  }
+}

package/src/constants.ts

@@ -2,7 +2,6 @@ export const FLOW_BUILDER_API_URL_PROD =
   process.env.HUBTYPE_API_URL || 'https://api.hubtype.com'
 export const SEPARATOR = '|'
 export const SOURCE_INFO_SEPARATOR = `${SEPARATOR}source_`
-export const EMPTY_PAYLOAD = 'fb-empty-payload'
 export const VARIABLE_PATTERN_GLOBAL = /{([^{}]+)}/g
 export const ACCESS_TOKEN_VARIABLE_KEY = '_access_token'
 export const REG_EXP_PATTERN = /^\/(.*)\/([gimyus]*)$/
@@ -10,6 +9,8 @@ export const UUID_REGEXP =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
 /* ********** PAYLOADS ********** */
+export const EMPTY_PAYLOAD = 'fb-empty-payload'
+export const ON_CLOSE_HANDOFF_PAYLOAD = 'fb-on-close-handoff'
 export const AGENT_RATING_PAYLOAD = 'agent-rating'
 export const PUSH_FLOW_PAYLOAD = 'push-flow'
 

package/src/content-fields/contact-reasons-conditional-matcher.ts

@@ -0,0 +1,24 @@
+import type { HubtypeCaseContactReason } from '@botonic/core'
+
+import type { HtContactReasonBranch } from './hubtype-fields/contact-reasons-conditional'
+
+export function contactReasonMatchesBranch(
+  sessionContactReason: HubtypeCaseContactReason,
+  branch: HtContactReasonBranch
+): boolean {
+  return (
+    sessionContactReason.project_id === branch.project_id &&
+    sessionContactReason.name === branch.name
+  )
+}
+
+export function findMatchingContactReasonBranch(
+  sessionContactReasons: HubtypeCaseContactReason[],
+  contactReasonBranches: HtContactReasonBranch[]
+): HtContactReasonBranch | undefined {
+  return contactReasonBranches.find(branch =>
+    sessionContactReasons.some(sessionContactReason =>
+      contactReasonMatchesBranch(sessionContactReason, branch)
+    )
+  )
+}

package/src/content-fields/flow-contact-reasons-conditional.tsx

@@ -0,0 +1,60 @@
+import type { BotContext, HubtypeCaseContactReason } from '@botonic/core'
+import { findMatchingContactReasonBranch } from './contact-reasons-conditional-matcher'
+import { ContentFieldsBase } from './content-fields-base'
+import type { HtNodeLink } from './hubtype-fields/common'
+import type {
+  HtContactReasonBranch,
+  HtContactReasonsNode,
+} from './hubtype-fields/contact-reasons-conditional'
+
+export class FlowContactReasonsConditional extends ContentFieldsBase {
+  public contactReasons: HtContactReasonBranch[] = []
+  public defaultTarget?: HtNodeLink
+
+  static fromHubtypeCMS(
+    component: HtContactReasonsNode,
+    botContext: BotContext
+  ): FlowContactReasonsConditional {
+    const newContactReasonsConditional = new FlowContactReasonsConditional(
+      component.id
+    )
+    newContactReasonsConditional.contactReasons =
+      component.content.contact_reasons
+    newContactReasonsConditional.defaultTarget =
+      component.content.default_target
+    newContactReasonsConditional.setFollowUp(botContext)
+    return newContactReasonsConditional
+  }
+
+  private setFollowUp(botContext: BotContext): void {
+    const sessionContactReasons: HubtypeCaseContactReason[] | undefined =
+      botContext.session._hubtype_case_contact_reasons
+
+    if (sessionContactReasons) {
+      const matchingBranch = findMatchingContactReasonBranch(
+        sessionContactReasons,
+        this.contactReasons
+      )
+      if (matchingBranch?.target) {
+        this.followUp = matchingBranch.target
+      }
+    }
+
+    this.followUp ??= this.defaultTarget
+  }
+
+  async trackFlow(_botContext: BotContext): Promise<void> {
+    // await trackFlow(botContext)
+    return
+  }
+
+  async processContent(_botContext: BotContext): Promise<void> {
+    // await this.filterContent(botContext, this)
+    // await this.trackFlow(botContext)
+    return
+  }
+
+  toBotonic() {
+    return <></>
+  }
+}

package/src/content-fields/flow-handoff.tsx

@@ -6,17 +6,22 @@ import {
   isWebchat,
 } from '@botonic/core'
 import { WebchatSettings } from '@botonic/react'
-
 import type { FlowBuilderApi } from '../api'
+import { ON_CLOSE_HANDOFF_PAYLOAD, SEPARATOR } from '../constants'
 import { getCommonFlowContentEventArgsForContentId } from '../tracking'
 import { ContentFieldsBase } from './content-fields-base'
-import type { HtHandoffNode, HtQueueLocale } from './hubtype-fields'
+import type { HtHandoffNode, HtNodeLink, HtQueueLocale } from './hubtype-fields'
 
 export class FlowHandoff extends ContentFieldsBase {
   public queue?: HtQueueLocale
   public onFinishPayload?: string
   public handoffAutoAssign: boolean
   public hasQueuePositionChangedNotificationsEnabled: boolean
+  public hasDifferentiatedCloseTypes: boolean
+  public resolvedByAgent?: HtNodeLink
+  public discardedByAgent?: HtNodeLink
+  public discardedByUser?: HtNodeLink
+  public discardedBySystem?: HtNodeLink
   public isTestIntegration: boolean
 
   static fromHubtypeCMS(
@@ -30,14 +35,21 @@ export class FlowHandoff extends ContentFieldsBase {
       locale,
       cmsHandoff.content.queue
     )
+    newHandoff.hasDifferentiatedCloseTypes =
+      cmsHandoff.content.has_differentiated_close_types
+    newHandoff.resolvedByAgent = cmsHandoff.content.resolved_by_agent
+    newHandoff.discardedByAgent = cmsHandoff.content.discarded_by_agent
+    newHandoff.discardedByUser = cmsHandoff.content.discarded_by_user
+    newHandoff.discardedBySystem = cmsHandoff.content.discarded_by_system
+    newHandoff.handoffAutoAssign = cmsHandoff.content.has_auto_assign
+    newHandoff.hasQueuePositionChangedNotificationsEnabled =
+      cmsHandoff.content.has_queue_position_changed_notifications_enabled
+
     newHandoff.onFinishPayload = FlowHandoff.getOnFinishPayload(
       cmsHandoff,
       cmsApi
     )
-    newHandoff.handoffAutoAssign = cmsHandoff.content.has_auto_assign
-    newHandoff.hasQueuePositionChangedNotificationsEnabled =
-      cmsHandoff.content.has_queue_position_changed_notifications_enabled
-    newHandoff.followUp = cmsHandoff.follow_up
+    newHandoff.followUp = undefined
 
     return newHandoff
   }
@@ -46,13 +58,43 @@ export class FlowHandoff extends ContentFieldsBase {
     cmsHandoff: HtHandoffNode,
     cmsApi: FlowBuilderApi
   ): string | undefined {
-    if (cmsHandoff.target?.id) {
+    if (cmsHandoff.content.has_differentiated_close_types) {
+      return `${ON_CLOSE_HANDOFF_PAYLOAD}${SEPARATOR}${cmsHandoff.id}`
+    } else if (cmsHandoff.target?.id) {
       return cmsApi.getPayload(cmsHandoff.target)
     }
 
     return undefined
   }
 
+  resolveOnClosePayload(botContext: BotContext): string {
+    const contactReasons =
+      botContext.session._hubtype_case_contact_reasons || []
+
+    if (contactReasons.some(reason => reason.name === 'discarded')) {
+      if (this.discardedByAgent?.id) {
+        return this.discardedByAgent.id
+      }
+      console.error('No discarded by agent target found')
+    }
+    if (contactReasons.some(reason => reason.name === 'discarded_by_user')) {
+      if (this.discardedByUser?.id) {
+        return this.discardedByUser.id
+      }
+      console.error('No discarded by user target found')
+    }
+    if (contactReasons.some(reason => reason.name === 'discarded_by_system')) {
+      if (this.discardedBySystem?.id) {
+        return this.discardedBySystem.id
+      }
+      console.error('No discarded by system target found')
+    }
+    if (this.resolvedByAgent?.id) {
+      return this.resolvedByAgent.id
+    }
+    throw new Error('No resolved by agent target found')
+  }
+
   async doHandoff(botContext: BotContext): Promise<void> {
     const handOffBuilder = new HandOffBuilder(botContext.session)
     handOffBuilder.withAutoAssignOnWaiting(this.handoffAutoAssign)

package/src/content-fields/hubtype-fields/contact-reasons-conditional.ts

@@ -0,0 +1,18 @@
+import type { HtBaseNode, HtNodeLink } from './common'
+import type { HtNodeWithContentType } from './node-types'
+
+export interface HtContactReasonBranch {
+  id: string
+  name: string
+  project_id: string
+  project_name?: string
+  target?: HtNodeLink
+}
+
+export interface HtContactReasonsNode extends HtBaseNode {
+  type: HtNodeWithContentType.CONTACT_REASONS_CONDITION
+  content: {
+    contact_reasons: HtContactReasonBranch[]
+    default_target?: HtNodeLink
+  }
+}

package/src/content-fields/hubtype-fields/handoff.ts

@@ -1,4 +1,9 @@
-import type { HtBaseNode, HtPayloadLocale, HtQueueLocale } from './common'
+import type {
+  HtBaseNode,
+  HtNodeLink,
+  HtPayloadLocale,
+  HtQueueLocale,
+} from './common'
 import type { HtNodeWithContentType } from './node-types'
 
 export interface HtHandoffNode extends HtBaseNode {
@@ -8,5 +13,10 @@ export interface HtHandoffNode extends HtBaseNode {
     payload: HtPayloadLocale[]
     has_auto_assign: boolean
     has_queue_position_changed_notifications_enabled: boolean
+    has_differentiated_close_types: boolean
+    resolved_by_agent?: HtNodeLink
+    discarded_by_agent?: HtNodeLink
+    discarded_by_user?: HtNodeLink
+    discarded_by_system?: HtNodeLink
   }
 }

package/src/content-fields/hubtype-fields/node-types.ts

@@ -21,6 +21,7 @@ export enum HtNodeWithContentType {
   CAPTURE_USER_INPUT = 'capture-user-input',
   CUSTOM_CONDITION = 'custom-condition',
   DO_NOTHING = 'do-nothing',
+  CONTACT_REASONS_CONDITION = 'contact-reasons-condition',
 }
 
 export enum HtNodeWithoutContentType {

package/src/content-fields/hubtype-fields/nodes.ts

@@ -3,6 +3,7 @@ import type { HtAiAgentRouterNode } from './ai-agent-router'
 import type { HtBotActionNode } from './bot-action'
 import type { HtCaptureUserInputNode } from './capture-user-input'
 import type { HtCarouselNode } from './carousel'
+import type { HtContactReasonsNode } from './contact-reasons-conditional'
 import type { HtCustomConditionalV2Node } from './custom-conditional-v2'
 import type { HtDoNothingNode } from './do-nothing'
 // import { HtChannelConditionalNode } from './channel-conditional'
@@ -50,6 +51,7 @@ export type HtNodeWithContent =
   | HtCaptureUserInputNode
   | HtCustomConditionalV2Node
   | HtDoNothingNode
+  | HtContactReasonsNode
 // | HtChannelConditionalNode
 // | HtCountryConditionalNode
 // | HtCustomConditionalNode

package/src/content-fields/index.ts

@@ -5,6 +5,7 @@ import { FlowBotAction } from './flow-bot-action'
 import { FlowCaptureUserInput } from './flow-capture-user-input'
 import { FlowCarousel } from './flow-carousel'
 import { FlowChannelConditional } from './flow-channel-conditional'
+import { FlowContactReasonsConditional } from './flow-contact-reasons-conditional'
 import { FlowCountryConditional } from './flow-country-conditional'
 import { FlowCustomConditional } from './flow-custom-conditional'
 import { FlowDoNothing } from './flow-do-nothing'
@@ -34,6 +35,7 @@ export {
   FlowCaptureUserInput,
   FlowCarousel,
   FlowChannelConditional,
+  FlowContactReasonsConditional,
   FlowCountryConditional,
   FlowCustomConditional,
   FlowCustomConditionalV2,
@@ -75,3 +77,4 @@ export type FlowContent =
   | FlowAiAgentRouter
   | FlowCustomConditionalV2
   | FlowDoNothing
+  | FlowContactReasonsConditional

package/src/flow-factory.ts

@@ -7,6 +7,7 @@ import {
   FlowBotAction,
   FlowCarousel,
   FlowChannelConditional,
+  FlowContactReasonsConditional,
   type FlowContent,
   FlowCountryConditional,
   FlowCustomConditional,
@@ -122,6 +123,12 @@ export class FlowFactory {
       case HtNodeWithContentType.DO_NOTHING:
         return FlowDoNothing.fromHubtypeCMS(hubtypeContent)
 
+      case HtNodeWithContentType.CONTACT_REASONS_CONDITION:
+        return FlowContactReasonsConditional.fromHubtypeCMS(
+          hubtypeContent,
+          this.botContext
+        )
+
       default:
         return undefined
     }