@whitewall/blip-sdk 0.0.173 → 0.0.175

package/src/types/flow.ts

@@ -1,254 +1,393 @@
-import type { MessageTypesContent } from './message.ts'
+import { z } from 'zod'
 
-type SendMessageActionSettings = {
-    $invalid?: boolean
-    id: string
-    type: keyof MessageTypesContent
-    content: MessageTypesContent[keyof MessageTypesContent]
-}
+const VALIDATION_RULES = ['text', 'number', 'date', 'regex', 'type'] as const
+export const CONTENT_TYPES = [
+    'text',
+    'select-immediate',
+    'select',
+    'media',
+    'media-audio',
+    'media-video',
+    'media-document',
+    'chat-state',
+    'web-link',
+    'raw-content',
+    '',
+] as const
+export const MIME_TYPES = [
+    'text/plain',
+    'application/vnd.lime.media-link+json',
+    'application/vnd.lime.select+json',
+    'application/vnd.lime.chatstate+json',
+    'application/vnd.lime.web-link+json',
+] as const
+const HTTP_METHODS = ['POST', 'GET', 'PUT', 'DELETE'] as const
+const COMPARISON_OPERATORS = [
+    'equals',
+    'notEquals',
+    'contains',
+    'startsWith',
+    'endsWith',
+    'greaterThan',
+    'lessThan',
+    'greaterThanOrEquals',
+    'lessThanOrEquals',
+    'matches',
+    'approximateTo',
+    'exists',
+    'notExists',
+] as const
+const SELECT_SCOPES = ['immediate', 'persistent'] as const
+const LINK_TARGETS = ['blank', 'self', 'selfCompact', 'selfTall'] as const
+const COMMAND_METHODS = ['get', 'set', 'merge', 'delete'] as const
+const CONDITION_SOURCES = ['input', 'context'] as const
+const LOGICAL_OPERATORS = ['or', 'and'] as const
+const TYPE_OF_STATE_ID = ['state', 'variable'] as const
 
-type ProcessHttpActionSettings = {
-    $invalid?: boolean
-    method: 'POST' | 'GET' | 'PUT' | 'DELETE'
-    // The URL to be called, you can use variables in the URL, for example: https://api.example.com/{{contact.email}}
-    uri: string
-    // The headers to be sent in the request. You can use variables in the headers, for example: Authorization: Bearer {{config.token}}
-    headers: Record<string, string>
-    // The body of the request. You can use variables in the body, for example: { "email": "{{contact.email}}" }
-    body: string
-    responseBodyVariable: string
-    responseStatusVariable: string
-}
+const createVariableNameSchema = (description: string) => z.string().describe(description)
 
-type TrackEventActionSettings = {
-    $invalid?: boolean
-    category: string
-    action: string
-    extras: Record<string, string>
-}
+const plainTextSchema = z.string()
 
-type MergeContactActionSettings = {
-    $invalid?: boolean
-    name: string
-    email: string
-    city: string
-    extras: Record<string, string>
-}
+const mediaLinkSchema = z.object({
+    title: z.string().optional(),
+    text: z.string().optional(),
+    // Mime type of the linked content.
+    type: z.string().describe('Mime type of the content'),
+    uri: z.string(),
+})
 
-type ExecuteScriptActionSettings = {
-    $invalid?: boolean
-    function: 'run'
-    // It should be a valid ES5 code
-    source: string
-    // The input variables that will be passed to the function, you must not use the {{ variableName }} syntax or @ syntax here, just the variable name
-    // Can be a context variable or any other special variable
-    inputVariables: Array<string>
-    // The context variable name to store the returned result of the function
-    outputVariable: string
-}
+const selectSchema = z.object({
+    text: z.string(),
+    scope: z.enum(SELECT_SCOPES).nullish(),
+    // Builder accepts both simple string options and object options.
+    options: z.array(z.string()).or(
+        z.array(
+            z.object({
+                text: z.string(),
+            }),
+        ),
+    ),
+})
 
-type SendRawMessageActionSettings = {
-    $invalid?: boolean
-    type: 'application/json'
-    // Useful to send raw content to the user, like raw whatsapp messages
-    // Example: {"recipient_type": "individual","type": "interactive","interactive": {"type": "button","body": {"text": "..."},"action": {"buttons": [...]}}}
-    rawContent: string
-}
+const chatstateSchema = z.object({
+    state: z.string(),
+    interval: z.union([z.number(), z.string()]).optional(),
+})
 
-type SetVariableActionSettings = {
-    $invalid?: boolean
-    variable: string
-    value: string
-    // Expiration time of the variable in seconds, if unsure, don't set it
-    expiration?: number
-}
+const webLinkSchema = z.object({
+    title: z.string().nullish(),
+    text: z.string(),
+    target: z.enum(LINK_TARGETS).nullish(),
+    uri: z.string(),
+})
 
-type TypeOfStateId = 'state' | 'variable'
-
-export type Condition = {
-    source: 'input' | 'context'
-    // The variable name of the conversation context to be evaluated, if the 'source' value is 'context'
-    variable?: string
-    // The type of the comparison. Optional. The default value is 'equals'
-    comparison:
-        | 'equals'
-        | 'notEquals'
-        | 'contains'
-        | 'startsWith'
-        | 'endsWith'
-        | 'greaterThan'
-        | 'lessThan'
-        | 'greaterThanOrEquals'
-        | 'lessThanOrEquals'
-        | 'matches'
-        | 'approximateTo'
-        | 'exists'
-        | 'notExists'
-    // The operator for comparison with the provided values. The default value is 'or'
-    operator?: 'or' | 'and'
-    values: Array<string>
-}
+const flowMessageContentSchema = plainTextSchema
+    .or(mediaLinkSchema)
+    .or(selectSchema)
+    .or(webLinkSchema)
+    .or(chatstateSchema)
 
-export type Action = {
-    $id: string
-    // The type of content should only exists if the action is of type SendMessage or SendRawMessage
-    // It should match the content type of the action settings
-    $typeOfContent?: // if don`t exists is set with empty string in GET
-        | ''
-        // type = text/plain
-        | 'text'
-        // type = application/vnd.lime.select+json
-        // content.scope = immediate
-        | 'select-immediate'
-        // content.scope = persistent
-        | 'select'
-        // type = application/vnd.lime.media-link+json
-        // content.type = image/png, image/jpeg, image/gif
-        | 'media'
-        // content.type = audio/mpeg, audio/wav, audio/ogg
-        | 'media-audio'
-        // content.type = video/mp4
-        | 'media-video'
-        // content.type = application/pdf
-        | 'media-document'
-        // type = application/vnd.lime.chatstate+json
-        | 'chat-state'
-        // type = application/vnd.lime.web-link+json
-        | 'web-link'
-        // type = application/json
-        // Should be used only for SendRawMessage action
-        | 'raw-content'
-    // The type of the action to be executed
-    type: // Send a message to the user
-        | 'SendMessage'
-        // Send a raw message to the user, useful to send whatsapp content
-        | 'SendRawMessage'
-        // Track an event in the conversation
-        | 'TrackEvent'
-        // Process an HTTP request
-        | 'ProcessHttp'
-        // Update the contact information of the user
-        | 'MergeContact'
-        // Execute a ES5 script
-        | 'ExecuteScript'
-        // Set a variable in the context
-        | 'SetVariable'
-        | 'ForwardToDesk'
-        | 'LeavingFromDesk'
-    $title?: string
-    $invalid?: boolean
-    // The matching settings of the action type
-    settings:
-        | SendMessageActionSettings
-        | SendRawMessageActionSettings
-        | TrackEventActionSettings
-        | ProcessHttpActionSettings
-        | MergeContactActionSettings
-        | ExecuteScriptActionSettings
-        | SetVariableActionSettings
-        | Record<string, never>
-    // Must always be set if the action is of type SendMessage or SendRawMessage
-    // If other action type, it must be null
-    $cardContent?: {
-        document: {
-            id: string
-            // Should always be the same of settings.type
-            type: keyof MessageTypesContent | 'application/json'
-            // The content of the message, it should be the same of settings.content
-            content: MessageTypesContent[keyof MessageTypesContent] | string
-            textContent?: string
-        }
-        editable: boolean
-        deletable: boolean
-        position: 'left'
-    }
-    conditions?: Array<Condition>
-}
+const processHttpActionSettingsSchema = z.object({
+    $invalid: z.boolean().optional(),
+    method: z.enum(HTTP_METHODS),
+    // The URL to be called. Variables can be interpolated, for example:
+    // https://api.example.com/{{contact.email}}
+    uri: z.string(),
+    // The headers to be sent in the request. Variables can be interpolated too.
+    headers: z.record(z.string(), z.string()).nullish(),
+    // The body of the request. Variables can be interpolated in the body too.
+    body: z.string(),
+    // Context variable used to store the response body.
+    responseBodyVariable: createVariableNameSchema('Response body variable name'),
+    // Context variable used to store the response status.
+    responseStatusVariable: createVariableNameSchema('Response status variable name'),
+})
 
-type InputState = {
-    // Always same values, except for the document.id
-    $cardContent: {
-        document: {
-            id: string
-            type: 'text/plain'
-            content?: 'Entrada do usuário'
-            // Should always be the same of the variable name
-            textContent?: string
-        }
-        editable: boolean
-        editing: boolean
-        deletable: boolean
-        position: 'right'
-    }
-    $invalid: boolean
-    bypass: boolean
-    validation?: {
-        // Gets or sets the validation rule to be used
-        rule: 'text' | 'number' | 'date' | 'regex' | 'type'
-        // The regular expression to be used in case of the 'rule' value is regex'
-        regex?: string
-        // The type to be used in case of the 'rule' value is 'type'
-        type?: string
-        // The error message text to be returned to the user in case of the input value is not valid accordingly to the defined rule
-        error: string
-    }
-    // Input expiration time in minutes. If not set, the input will never expire. If unsure, don't set it
-    expiration?: string
-    variable?: string
-    conditions?: Array<Condition>
-}
+const trackEventActionSettingsSchema = z.object({
+    $invalid: z.boolean().optional(),
+    category: z.string(),
+    action: z.string(),
+    extras: z.record(z.string(), z.string()).nullish(),
+})
 
-type Output = {
-    // Id of the state to redirect
-    stateId: string
-    typeOfStateId?: TypeOfStateId
-    $id?: string
-    conditions: Array<Condition>
-    $invalid?: boolean
-    $isDeskOutput?: boolean
-    $isDeskDefaultOutput?: boolean
-}
+const mergeContactActionSettingsSchema = z.object({
+    $invalid: z.boolean().optional(),
+    name: z.string().nullish(),
+    email: z.string().nullish(),
+    city: z.string().nullish(),
+    extras: z.record(z.string(), z.string()).nullish(),
+})
 
-export type State = {
-    $contentActions: Array<{
-        // The actions that would be executed after entering actions
-        // All the actions here should be of type SendMessage
-        // This is the only place that can have the SendMessage action
-        action?: Action
-        // If the state should have a user input, it should be defined here
-        input?: InputState
-    }>
-    $conditionOutputs: Array<Output>
-    // The actions that would be executed after entering the state
-    $enteringCustomActions: Array<Action>
-    // The actions that would be executed after leaving the state, before the output conditions
-    $leavingCustomActions: Array<Action>
-    $localCustomActions: Array<Action>
-    $inputSuggestions: []
-    $defaultOutput: Output
-    isAiGenerated?: boolean
-    deskStateVersion?: string
-    $afterStateChangedActions?: Array<Action>
-    $tags: Array<{
-        id: string
-        label: string
-        // Hexadecimal color code of the tag, with # prefix
-        background: string
-        canChangeBackground: boolean
-    }>
-    id?: string
-    // Only the special state with id "onbarding" has root as boolean
-    root?: boolean
-    $title: string
-    $position?: {
-        top: string
-        left: string
-    }
-    $invalidContentActions: boolean
-    $invalidOutputs: boolean
-    $invalidCustomActions: boolean
-    $invalid?: boolean
-}
+const executeScriptActionSettingsSchema = z.object({
+    $invalid: z.boolean().optional(),
+    // Builder executes a function called "run".
+    function: z.literal('run').optional(),
+    // Must be valid ES5 source code.
+    source: z.string(),
+    // Variables are passed to the function in this declared order. Do not use
+    // the {{ variableName }} syntax here, only the plain variable name.
+    inputVariables: z.array(createVariableNameSchema('Variable name')),
+    // Context variable used to store the returned result.
+    outputVariable: createVariableNameSchema('Output variable name'),
+})
+
+const sendMessageActionSettingsSchema = z.object({
+    $invalid: z.boolean().optional(),
+    type: z.enum(MIME_TYPES).optional(),
+    content: flowMessageContentSchema,
+    // Message id generated by the builder.
+    id: z.string().optional(),
+    metadata: z.record(z.string(), z.string()).optional(),
+})
+
+const sendRawMessageActionSettingsSchema = z.object({
+    $invalid: z.boolean().optional(),
+    type: z.literal('application/json').optional(),
+    // Useful to send raw channel payloads, such as WhatsApp interactive content.
+    rawContent: z.string(),
+})
+
+const setVariableActionSettingsSchema = z.object({
+    $invalid: z.boolean().optional(),
+    variable: createVariableNameSchema('Name of the variable to be set in the context'),
+    value: z.union([z.string(), z.number()]).optional(),
+    // Expiration time in seconds.
+    expiration: z.number().nullish(),
+})
+
+const processCommandActionSettingsSchema = z.object({
+    $invalid: z.boolean().optional(),
+    to: z.string(),
+    method: z.enum(COMMAND_METHODS),
+    uri: z.string(),
+    variable: createVariableNameSchema('Variable name'),
+    from: z.string().optional(),
+})
+
+const forwardToDeskActionSettingsSchema = z.object({
+    $invalid: z.boolean().optional(),
+})
+
+const leavingFromDeskActionSettingsSchema = z.object({
+    $invalid: z.boolean().optional(),
+})
+
+const redirectActionSettingsSchema = z.object({
+    $invalid: z.boolean().optional(),
+    address: z.string(),
+    context: z.object({
+        type: z.literal('text/plain'),
+        value: z.string(),
+    }),
+})
+
+export const conditionSchema = z.object({
+    source: z.enum(CONDITION_SOURCES),
+    // Used only when source is "context".
+    variable: createVariableNameSchema('Context variable name').nullish(),
+    comparison: z.enum(COMPARISON_OPERATORS),
+    operator: z.enum(LOGICAL_OPERATORS).optional(),
+    values: z.array(z.string()),
+})
+
+const baseActionSchema = z.object({
+    $id: z.string(),
+    // Should only exist for SendMessage and SendRawMessage actions. When it is
+    // omitted, GET responses usually return an empty string.
+    $typeOfContent: z.enum(CONTENT_TYPES).optional(),
+    $title: z.string().optional(),
+    $invalid: z.boolean().optional(),
+    // The action runs only when its conditions are met.
+    conditions: z.array(conditionSchema).optional(),
+    $cardContent: z
+        .object({
+            editable: z.boolean(),
+            deletable: z.boolean(),
+            position: z.literal('left'),
+            document: z.object({
+                id: z.string(),
+                // Must match the type defined in the action settings.
+                type: z.enum(MIME_TYPES).or(z.literal('application/json')),
+                // Must match the content defined in the action settings.
+                content: flowMessageContentSchema.or(z.string()),
+                textContent: z.string().optional(),
+            }),
+        })
+        .nullish(),
+    // When true, execution continues even if the action fails.
+    continueOnError: z.boolean().optional(),
+})
+
+const actionTypeSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('SendMessage'),
+        settings: sendMessageActionSettingsSchema,
+    }),
+    z.object({
+        type: z.literal('SendRawMessage'),
+        settings: sendRawMessageActionSettingsSchema,
+    }),
+    z.object({
+        type: z.literal('TrackEvent'),
+        settings: trackEventActionSettingsSchema,
+    }),
+    z.object({
+        type: z.literal('ProcessHttp'),
+        settings: processHttpActionSettingsSchema,
+    }),
+    z.object({
+        type: z.literal('MergeContact'),
+        settings: mergeContactActionSettingsSchema,
+    }),
+    z.object({
+        type: z.literal('ExecuteScript'),
+        settings: executeScriptActionSettingsSchema,
+    }),
+    z.object({
+        type: z.literal('ExecuteScriptV2'),
+        settings: executeScriptActionSettingsSchema,
+    }),
+    z.object({
+        type: z.literal('SetVariable'),
+        settings: setVariableActionSettingsSchema,
+    }),
+    z.object({
+        type: z.literal('ProcessCommand'),
+        settings: processCommandActionSettingsSchema,
+    }),
+    z.object({
+        type: z.literal('ForwardToDesk'),
+        settings: forwardToDeskActionSettingsSchema,
+    }),
+    z.object({
+        type: z.literal('LeavingFromDesk'),
+        settings: leavingFromDeskActionSettingsSchema,
+    }),
+    z.object({
+        type: z.literal('Redirect'),
+        settings: redirectActionSettingsSchema,
+    }),
+])
+
+export const actionSchema = z.intersection(baseActionSchema, actionTypeSchema)
+
+const inputValidationSchema = z.object({
+    // Validation rule applied to the captured input.
+    rule: z.enum(VALIDATION_RULES),
+    regex: z.string().nullish(),
+    type: z.string().nullish(),
+    // Message shown when validation fails.
+    error: z.string(),
+})
+
+export const inputStateSchema = z.object({
+    // Builder card metadata shown in the editor. The values are usually fixed
+    // except for the nested document id.
+    $cardContent: z.object({
+        document: z.object({
+            id: z.string(),
+            type: z.literal('text/plain'),
+            // Builder commonly renders "Entrada do usuario" here.
+            content: z.string().optional(),
+            // Should usually match the variable name where the input is stored.
+            textContent: z.string().optional(),
+        }),
+        editable: z.boolean(),
+        editing: z.boolean(),
+        deletable: z.boolean(),
+        position: z.literal('right'),
+    }),
+    $invalid: z.boolean(),
+    // When true, the input step is skipped.
+    bypass: z.boolean(),
+    validation: inputValidationSchema.nullish(),
+    // Input expiration time in minutes.
+    expiration: z.string().nullish(),
+    variable: createVariableNameSchema('Input variable name').nullish(),
+    conditions: z.array(conditionSchema).optional(),
+})
+
+const baseOutputSchema = z.object({
+    // Id of the target state, or a variable id when typeOfStateId is "variable".
+    stateId: z.string(),
+    typeOfStateId: z.enum(TYPE_OF_STATE_ID).optional(),
+})
+
+export const conditionOutputSchema = baseOutputSchema.extend({
+    $id: z.string().optional(),
+    $invalid: z.boolean().optional(),
+    $connId: z.string().optional(),
+    $contentId: z.string().optional(),
+    $isDeskOutput: z.boolean().optional(),
+    $isDeskCustomOutput: z.boolean().optional(),
+    $isDeskDefaultOutput: z.boolean().optional(),
+    conditions: z.array(conditionSchema),
+})
+
+export const defaultOutputSchema = baseOutputSchema.extend({
+    $invalid: z.boolean().optional(),
+})
+
+export const contentActionItemSchema = z.object({
+    // Actions executed after entering actions. In practice, this is where
+    // builder stores SendMessage cards.
+    action: actionSchema.optional(),
+    // If the state expects user input, it should be defined here.
+    input: inputStateSchema.optional(),
+    $invalid: z.boolean().optional(),
+})
+
+export const stateSchema = z.object({
+    $contentActions: z.array(contentActionItemSchema),
+    $conditionOutputs: z.array(conditionOutputSchema),
+    // Actions executed when entering the state.
+    $enteringCustomActions: z.array(actionSchema),
+    // Actions executed when leaving the state, before output evaluation.
+    $leavingCustomActions: z.array(actionSchema),
+    $localCustomActions: z.array(actionSchema).optional(),
+    $inputSuggestions: z.array(z.string()),
+    // Output used when none of the conditional outputs are matched.
+    $defaultOutput: defaultOutputSchema,
+    isAiGenerated: z.boolean().optional(),
+    deskStateVersion: z.string().optional(),
+    $afterStateChangedActions: z.array(actionSchema).optional(),
+    $tags: z.array(
+        z.object({
+            id: z.string(),
+            label: z.string(),
+            // Hexadecimal color code including the "#" prefix.
+            background: z.string(),
+            canChangeBackground: z.boolean(),
+        }),
+    ),
+    id: z.string().optional(),
+    // Only the special state with id "onboarding" is usually marked as root.
+    root: z.boolean().optional(),
+    $title: z.string(),
+    $position: z
+        .object({
+            top: z.string(),
+            left: z.string(),
+        })
+        .optional(),
+    $invalidContentActions: z.boolean(),
+    $invalidOutputs: z.boolean(),
+    $invalidCustomActions: z.boolean(),
+    $invalid: z.boolean().optional(),
+    $whiteWallIntegration: z.unknown().optional(),
+})
+
+export const flowSchema = z.record(z.string(), stateSchema)
+
+export type Condition = z.infer<typeof conditionSchema>
+export type Action = z.infer<typeof actionSchema>
+export type InputState = z.infer<typeof inputStateSchema>
+export type ConditionOutput = z.infer<typeof conditionOutputSchema>
+export type DefaultOutput = z.infer<typeof defaultOutputSchema>
+export type ContentActionItem = z.infer<typeof contentActionItemSchema>
+export type State = z.infer<typeof stateSchema>
+export type Flow = z.infer<typeof flowSchema>
+export type BuilderFlow = Flow
 
 export type BuilderConfiguration = {
     'builder:minimumIntentScore'?: string
@@ -256,9 +395,7 @@ export type BuilderConfiguration = {
     'builder:#localTimeZone'?: string
 } & Record<string, string | number>
 
-export type BuilderFlow = Record<'onboarding' | 'fallback' | string, State>
-
-// The history index is a number from 1 to 10, representing the last 10 publications
+// The history index is a number from 1 to 10, representing the last 10 publications.
 export type HistoryIndex = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10
 
 export type Publication = {
@@ -267,7 +404,7 @@ export type Publication = {
 }
 
 export type BuilderLatestPublications = {
-    // The last publication its a rotate of 10
+    // The publication index rotates from 1 to 10.
     lastInsertedIndex: HistoryIndex
     isMoreOptionsActive: string
     publications: Array<Publication & { publishedAt: string; index: HistoryIndex }>
@@ -280,21 +417,25 @@ export type BuilderLatestPublication = {
 }
 
 type RecursivelyRemoveDollar<T> = T extends object
-    ? T extends Array<infer U>
-        ? Array<RecursivelyRemoveDollar<U>>
-        : { [K in keyof T as K extends `$${string}` ? never : K]: RecursivelyRemoveDollar<T[K]> }
+    ? T extends Array<infer Item>
+        ? Array<RecursivelyRemoveDollar<Item>>
+        : { [Key in keyof T as Key extends `$${string}` ? never : Key]: RecursivelyRemoveDollar<T[Key]> }
     : T
 
+type TypeOfStateId = (typeof TYPE_OF_STATE_ID)[number]
+
 export type StateApplication = {
     id: string
     root?: boolean
     name: string
+    deskStateVersion?: string
     inputActions: RecursivelyRemoveDollar<Array<Action>>
     input: RecursivelyRemoveDollar<InputState>
     outputActions: RecursivelyRemoveDollar<Array<Action>>
     afterStateChangedActions: RecursivelyRemoveDollar<Array<Action>>
     outputs: Array<{
         stateId: string
+        typeOfStateId?: TypeOfStateId
         conditions?: RecursivelyRemoveDollar<Array<Condition>>
     }>
 }