@whitewall/blip-sdk 0.0.190 → 0.0.192

package/src/utils/minifier.ts

@@ -0,0 +1,554 @@
+/**
+ * Round-trippable projection of a builder flow.
+ *
+ * Unlike the digest in `./builder.ts`, this keeps the `$`-prefixed keys and maps
+ * 1:1 onto the builder document: `minifyFlow` strips only the metadata the
+ * builder regenerates on its own, and `expandMinifiedFlow` rebuilds it, so a
+ * minified flow can be edited by hand and pushed back.
+ */
+import { z } from 'zod'
+import {
+    actionTypeSchema,
+    baseActionSchema,
+    type CONTENT_TYPES,
+    conditionOutputSchema,
+    defaultOutputSchema,
+    type Flow,
+    type InputState,
+    inputStateSchema,
+    type MIME_TYPES,
+    ROOT_STATE_ID,
+    type State,
+    stateSchema,
+} from '../types/flow.ts'
+import { isChatStateSendMessage } from './builder.ts'
+
+/**
+ * Everything `minifyFlow` removes, grouped by where it lives. Together these
+ * describe the same subset as `minifiedStateSchema`, so the two must be kept in
+ * sync. The lists deliberately differ from each other: a card only exists on a
+ * content action, and only a content action carries a generated `settings.id`.
+ */
+const STATE_NOISE = [
+    '$invalidContentActions',
+    '$invalidOutputs',
+    '$invalidCustomActions',
+    '$invalid',
+    'id',
+    'root',
+    '$tags',
+    '$inputSuggestions',
+    'isAiGenerated',
+    'deskStateVersion',
+] as const
+
+const CUSTOM_ACTION_LISTS = [
+    '$enteringCustomActions',
+    '$leavingCustomActions',
+    '$afterStateChangedActions',
+    '$localCustomActions',
+] as const
+const CUSTOM_ACTION_NOISE = ['$id', '$title', '$invalid', '$typeOfContent'] as const
+
+const CONTENT_ACTION_ITEM_NOISE = ['$invalid'] as const
+const CONTENT_ACTION_NOISE = ['$id', '$typeOfContent', '$cardContent', '$inputSchema'] as const
+const CONTENT_ACTION_SETTINGS_NOISE = ['id'] as const
+const CONTENT_INPUT_NOISE = ['$cardContent', '$invalid'] as const
+
+const CONDITION_OUTPUT_NOISE = [
+    '$id',
+    '$invalid',
+    '$isBuilderDefaultOutput',
+    '$connId',
+    '$isDeskOutput',
+    '$isDeskCustomOutput',
+    '$isDeskDefaultOutput',
+    '$contentId',
+] as const
+
+const DEFAULT_OUTPUT_NOISE = ['$invalid'] as const
+
+/**
+ * Pairs an incoming item with the one the builder already has, so its generated
+ * ids survive a push instead of being replaced on every write.
+ *
+ * A match is consumed, because two items in the same state can be identical and
+ * must not end up sharing an id.
+ */
+function createStaleMatcher<T>(candidates: ReadonlyArray<T> | undefined, key: (item: T) => string) {
+    const byKey = new Map<string, Array<T>>()
+
+    for (const candidate of candidates ?? []) {
+        const candidateKey = key(candidate)
+        const bucket = byKey.get(candidateKey)
+
+        if (bucket) {
+            bucket.push(candidate)
+        } else {
+            byKey.set(candidateKey, [candidate])
+        }
+    }
+
+    return (item: T): T | undefined => byKey.get(key(item))?.shift()
+}
+
+// The generated `settings.id` is left out of the key since a minified action
+// never carries one.
+const actionKey = ({ type, settings, conditions }: { type: string; settings: unknown; conditions?: unknown }) => {
+    const { id: _id, ...rest } = (settings ?? {}) as Record<string, unknown>
+    return JSON.stringify([type, rest, conditions])
+}
+
+const conditionOutputKey = ({ stateId, conditions }: { stateId: string; conditions?: unknown }) =>
+    JSON.stringify([stateId, conditions])
+
+// Only the part of the input a minified flow carries, so an unchanged input keeps
+// the card the builder drew for it.
+const inputKey = ({ $cardContent: _card, $invalid: _invalid, ...rest }: InputState) => JSON.stringify(rest)
+
+function stripKeys(target: unknown, keys: ReadonlyArray<string>): void {
+    if (!target || typeof target !== 'object') {
+        return
+    }
+
+    for (const key of keys) {
+        delete (target as Record<string, unknown>)[key]
+    }
+}
+
+/**
+ * Angular tags every item of an `ng-repeat`ed array with a `$$hashKey`, so the
+ * document the builder saves carries them on its condition outputs, on the
+ * conditions inside them and on its content actions. Nothing outside the editor
+ * reads them and the editor puts them back, but `minifiedStateSchema` is strict —
+ * so left in place they would report a freshly pulled flow as invalid.
+ *
+ * They are stripped wherever they appear rather than per location, because which
+ * arrays the editor happened to repeat over is not something to keep in sync here.
+ */
+function stripAngularKeys(target: unknown): void {
+    if (Array.isArray(target)) {
+        for (const item of target) {
+            stripAngularKeys(item)
+        }
+
+        return
+    }
+
+    if (target && typeof target === 'object') {
+        delete (target as Record<string, unknown>).$$hashKey
+
+        for (const value of Object.values(target)) {
+            stripAngularKeys(value)
+        }
+    }
+}
+
+const minifiedActionSchema = z.intersection(baseActionSchema.partial({ $id: true }), actionTypeSchema).check((ctx) => {
+    // expandMinifiedFlow derives $typeOfContent from the settings mime type, so
+    // a SendMessage without one cannot be pushed. Rejecting it here keeps
+    // validation and push in agreement instead of failing halfway through.
+    const action = ctx.value
+    if (action.type === 'SendMessage' && !action.settings.type) {
+        ctx.issues.push({
+            code: 'custom',
+            input: action,
+            path: ['settings', 'type'],
+            message: 'A SendMessage action requires a settings.type',
+        })
+    }
+
+    // The runtime deserializes the raw content as this media type and refuses to
+    // run the action without one, so a hand-written raw message that omits it
+    // would be accepted here and then fail in the conversation.
+    if (action.type === 'SendRawMessage' && !action.settings.type) {
+        ctx.issues.push({
+            code: 'custom',
+            input: action,
+            path: ['settings', 'type'],
+            message: 'A SendRawMessage action requires a settings.type',
+        })
+    }
+})
+
+const minifiedInputSchema = inputStateSchema.partial({ $cardContent: true, $invalid: true }).strict()
+
+const minifiedContentActionItemSchema = z
+    .object({
+        action: minifiedActionSchema.optional(),
+        input: minifiedInputSchema.optional(),
+    })
+    .strict()
+
+/**
+ * `stateSchema` minus the metadata `minifyFlow` strips. It is strict on purpose:
+ * minified flows are edited by hand, so an unknown key is almost always a typo
+ * that would otherwise be silently dropped on push.
+ */
+export const minifiedStateSchema = stateSchema
+    .extend({
+        $enteringCustomActions: z.array(minifiedActionSchema),
+        $leavingCustomActions: z.array(minifiedActionSchema),
+        $localCustomActions: z.array(minifiedActionSchema).optional(),
+        $afterStateChangedActions: z.array(minifiedActionSchema).optional(),
+        $contentActions: z.array(minifiedContentActionItemSchema),
+        $conditionOutputs: z.array(conditionOutputSchema.strict()),
+        $defaultOutput: defaultOutputSchema.strict(),
+    })
+    .partial({
+        $tags: true,
+        $inputSuggestions: true,
+        $invalidContentActions: true,
+        $invalidOutputs: true,
+        $invalidCustomActions: true,
+    })
+    .strict()
+
+/**
+ * A push replaces the whole flow, so a dangling output and a title collision are
+ * validation errors here instead of a broken canvas later.
+ */
+export const minifiedFlowSchema = z.record(z.string(), minifiedStateSchema).check((ctx) => {
+    const titles = new Map<string, string>()
+
+    const checkOutput = (output: { stateId: string; typeOfStateId?: string }, path: Array<string | number>) => {
+        // A variable output is only resolved at runtime.
+        if (output.typeOfStateId === 'variable' || output.stateId in ctx.value) {
+            return
+        }
+
+        ctx.issues.push({
+            code: 'custom',
+            input: output.stateId,
+            path: [...path, 'stateId'],
+            message: `Output points at '${output.stateId}', which is not a state in this flow`,
+        })
+    }
+
+    for (const [stateId, state] of Object.entries(ctx.value)) {
+        // The builder addresses a state by its title, so a duplicate hides one.
+        const title = state.$title.toLowerCase()
+        const duplicate = titles.get(title)
+
+        if (duplicate) {
+            ctx.issues.push({
+                code: 'custom',
+                input: state.$title,
+                path: [stateId, '$title'],
+                message: `Duplicate state title '${state.$title}', already used by '${duplicate}'`,
+            })
+        } else {
+            titles.set(title, stateId)
+        }
+
+        checkOutput(state.$defaultOutput, [stateId, '$defaultOutput'])
+
+        for (const [index, output] of state.$conditionOutputs.entries()) {
+            checkOutput(output, [stateId, '$conditionOutputs', index])
+        }
+    }
+})
+
+export type MinifiedState = z.infer<typeof minifiedStateSchema>
+export type MinifiedFlow = z.infer<typeof minifiedFlowSchema>
+
+/**
+ * Strips everything the builder can regenerate, so what is left is the part of
+ * the flow worth reading and editing.
+ *
+ * The result is round-trippable through `expandMinifiedFlow` with one
+ * exception: typing indicators are discarded rather than preserved, so a custom
+ * typing interval is replaced by the default on the way back. See
+ * `createChatStateContentAction`.
+ */
+export function minifyFlow(flow: Flow): MinifiedFlow {
+    const minified: MinifiedFlow = {}
+
+    for (const [stateId, state] of Object.entries(flow)) {
+        const minifiedState = structuredClone(state)
+
+        stripKeys(minifiedState, STATE_NOISE)
+        stripAngularKeys(minifiedState)
+        stripKeys(minifiedState.$defaultOutput, DEFAULT_OUTPUT_NOISE)
+
+        // Expansion writes `false` here for a state that has no plugin, so only a
+        // real configuration is worth carrying.
+        if (!minifiedState.$whiteWallIntegration) {
+            stripKeys(minifiedState, ['$whiteWallIntegration'])
+        }
+
+        for (const output of minifiedState.$conditionOutputs ?? []) {
+            stripKeys(output, CONDITION_OUTPUT_NOISE)
+        }
+
+        for (const list of CUSTOM_ACTION_LISTS) {
+            for (const action of minifiedState[list] ?? []) {
+                stripKeys(action, CUSTOM_ACTION_NOISE)
+            }
+        }
+
+        // The builder re-inserts a typing indicator before every message, so
+        // carrying them around would just add noise to the minified flow.
+        minifiedState.$contentActions = minifiedState.$contentActions
+            ?.filter((item) => !isChatStateSendMessage(item))
+            .map((item) => {
+                stripKeys(item, CONTENT_ACTION_ITEM_NOISE)
+                stripKeys(item.input, CONTENT_INPUT_NOISE)
+                stripKeys(item.action, CONTENT_ACTION_NOISE)
+                stripKeys(item.action?.settings, CONTENT_ACTION_SETTINGS_NOISE)
+                return item
+            })
+
+        minified[stateId] = minifiedState as unknown as MinifiedState
+    }
+
+    return minified
+}
+
+export function expandMinifiedFlow(minifiedFlow: MinifiedFlow, staleFlow?: Flow): Flow {
+    const flow: Flow = {}
+
+    for (const [stateId, minifiedState] of Object.entries(minifiedFlow)) {
+        try {
+            const staleState = staleFlow?.[stateId]
+            const state = structuredClone(minifiedState) as unknown as State
+
+            state.$invalidContentActions = false
+            state.$invalidOutputs = false
+            state.$invalidCustomActions = false
+            state.$invalid = false
+            state.id = stateId
+            // When the builder already knows the state, its answer wins; a state
+            // being pushed for the first time falls back to the id convention, so
+            // a flow pushed without a stale one still gets an entry point.
+            state.root = staleState ? staleState.root : stateId === ROOT_STATE_ID || undefined
+            state.$tags = staleState?.$tags ?? []
+            state.$inputSuggestions = staleState?.$inputSuggestions ?? []
+            state.isAiGenerated = staleState?.isAiGenerated ?? false
+            // A plugin's configuration is authored, not generated, so the minified
+            // flow is the source of truth for it. Falling back to the stale state
+            // keeps a plugin configured before this was carried through.
+            state.$whiteWallIntegration =
+                minifiedState.$whiteWallIntegration ?? staleState?.$whiteWallIntegration ?? false
+            state.deskStateVersion = staleState?.deskStateVersion ?? undefined
+            state.$defaultOutput.$invalid = false
+
+            // Reuse the ids the builder already knows so the canvas keeps its
+            // connections instead of redrawing them on every push.
+            const matchStaleConditionOutput = createStaleMatcher(staleState?.$conditionOutputs, conditionOutputKey)
+
+            for (const conditionOutput of state.$conditionOutputs ?? []) {
+                const staleConditionOutput = matchStaleConditionOutput(conditionOutput)
+
+                conditionOutput.$id = staleConditionOutput?.$id ?? crypto.randomUUID()
+                conditionOutput.$invalid = false
+                conditionOutput.$connId = staleConditionOutput?.$connId ?? undefined
+                conditionOutput.$isDeskOutput = staleConditionOutput?.$isDeskOutput ?? undefined
+                conditionOutput.$isDeskCustomOutput = staleConditionOutput?.$isDeskCustomOutput ?? undefined
+                conditionOutput.$isDeskDefaultOutput = staleConditionOutput?.$isDeskDefaultOutput ?? undefined
+                conditionOutput.$contentId = staleConditionOutput?.$contentId ?? undefined
+            }
+
+            for (const actionType of CUSTOM_ACTION_LISTS) {
+                const matchStaleAction = createStaleMatcher(staleState?.[actionType], actionKey)
+
+                for (const action of state[actionType] ?? []) {
+                    const staleAction = matchStaleAction(action)
+
+                    action.$id = staleAction?.$id ?? crypto.randomUUID()
+                    action.$invalid = false
+                    action.$title = staleAction?.$title ?? createActionTitle(action)
+                    action.$typeOfContent = staleAction?.$typeOfContent ?? undefined
+                }
+            }
+
+            const matchStaleContentAction = createStaleMatcher(
+                staleState?.$contentActions?.flatMap((candidate) => candidate.action ?? []),
+                actionKey,
+            )
+            const matchStaleInput = createStaleMatcher(
+                staleState?.$contentActions?.flatMap((candidate) => candidate.input ?? []),
+                inputKey,
+            )
+
+            for (const contentAction of state.$contentActions ?? []) {
+                contentAction.$invalid = false
+
+                if (contentAction.input) {
+                    const staleInput = matchStaleInput(contentAction.input)
+
+                    contentAction.input.$invalid = false
+                    contentAction.input.$cardContent = staleInput?.$cardContent ?? {
+                        document: {
+                            id: crypto.randomUUID(),
+                            type: 'text/plain',
+                            textContent: 'Entrada do usuário',
+                            content: 'Entrada do usuário',
+                        },
+                        editable: false,
+                        deletable: true,
+                        position: 'right',
+                        editing: false,
+                    }
+                }
+
+                if (contentAction.action) {
+                    const staleAction = matchStaleContentAction(contentAction.action)
+                    const staleSettings = staleAction?.settings as { id?: string } | undefined
+                    const settings = contentAction.action.settings as { id?: string; type?: string; content?: unknown }
+
+                    contentAction.action.$id = staleAction?.$id ?? crypto.randomUUID()
+                    settings.id = staleSettings?.id ?? crypto.randomUUID()
+                    // The label the builder wrote is at least as precise as a derived
+                    // one, but a GET can answer with an empty one.
+                    contentAction.action.$typeOfContent =
+                        staleAction?.$typeOfContent || getTypeOfContent(contentAction.action)
+                    contentAction.action.$cardContent = {
+                        deletable: true,
+                        editable: true,
+                        position: 'left',
+                        document: {
+                            id: staleAction?.$cardContent?.document.id ?? crypto.randomUUID(),
+                            type: settings.type as (typeof MIME_TYPES)[number],
+                            content: settings.content as string,
+                        },
+                    }
+                }
+            }
+
+            // Walk backwards so the chat states can be spliced in without shifting
+            // the indexes still to be visited.
+            for (let index = (state.$contentActions ?? []).length - 1; index >= 0; index--) {
+                if (state.$contentActions[index].action) {
+                    state.$contentActions.splice(index, 0, createChatStateContentAction())
+                }
+            }
+
+            flow[stateId] = state
+        } catch (err) {
+            if (err instanceof Error) {
+                throw new Error(`[State ${stateId}] ${err.message}`, { cause: err })
+            }
+
+            throw err
+        }
+    }
+
+    // Drops the keys explicitly set to undefined above.
+    return JSON.parse(JSON.stringify(flow))
+}
+
+/**
+ * Typing indicators are dropped by `minifyFlow` and rebuilt here from scratch,
+ * one before every message, rather than being carried through the minified flow.
+ *
+ * This is deliberate: they are pure presentation, they outnumber the messages
+ * they precede, and keeping them would double the size of the file a person or
+ * an LLM has to read and edit. The trade-off is that a typing interval tuned by
+ * hand in the builder does not survive a round trip and comes back as the
+ * default below.
+ */
+function createChatStateContentAction(): State['$contentActions'][number] {
+    const content = { state: 'composing', interval: 1000 }
+
+    return {
+        action: {
+            $id: crypto.randomUUID(),
+            $typeOfContent: 'chat-state',
+            type: 'SendMessage',
+            settings: {
+                id: crypto.randomUUID(),
+                type: 'application/vnd.lime.chatstate+json',
+                content,
+            },
+            $cardContent: {
+                document: {
+                    id: crypto.randomUUID(),
+                    type: 'application/vnd.lime.chatstate+json',
+                    content,
+                },
+                editable: true,
+                deletable: true,
+                position: 'left',
+            },
+        },
+        $invalid: false,
+    }
+}
+
+/** Derives the label the builder would have given an action it has never seen. */
+function getTypeOfContent(
+    action: NonNullable<State['$contentActions'][number]['action']>,
+): (typeof CONTENT_TYPES)[number] {
+    if (action.type === 'SendRawMessage') {
+        return 'raw-content'
+    }
+
+    const settings = action.settings as {
+        type?: (typeof MIME_TYPES)[number]
+        content?: { scope?: string; type?: string }
+    }
+
+    switch (settings.type) {
+        case 'text/plain':
+            return 'text'
+        case 'application/vnd.lime.media-link+json':
+            return getTypeOfMedia(settings.content?.type ?? '')
+        case 'application/vnd.lime.select+json':
+            return settings.content?.scope === 'immediate' ? 'select-immediate' : 'select'
+        case 'application/vnd.lime.chatstate+json':
+            return 'chat-state'
+        case 'application/vnd.lime.web-link+json':
+            return 'web-link'
+        default:
+            throw new Error(`Content action does not have a valid action property: ${JSON.stringify(action)}`)
+    }
+}
+
+function getTypeOfMedia(mimeType: string): (typeof CONTENT_TYPES)[number] {
+    if (mimeType.startsWith('audio/')) {
+        return 'media-audio'
+    }
+
+    if (mimeType.startsWith('video/')) {
+        return 'media-video'
+    }
+
+    return mimeType.startsWith('image/') ? 'media' : 'media-document'
+}
+
+function createActionTitle(action: State['$enteringCustomActions'][number]): string | undefined {
+    const sanitize = (value: string | number) => value.toString().replace(/[^a-zA-Z0-9.@]/g, '')
+
+    switch (action.type) {
+        case 'TrackEvent':
+            return `Track ${sanitize(action.settings.category)}`
+
+        case 'ExecuteScript':
+        case 'ExecuteScriptV2':
+            return `Process ${action.settings.outputVariable}`
+
+        case 'Redirect':
+            return `Redirect to ${sanitize(action.settings.address)}`
+
+        case 'MergeContact': {
+            const items = Object.keys(action.settings).filter((key) => key !== 'extras')
+            if (Object.keys(action.settings.extras ?? {}).length > 0) {
+                items.push('extras')
+            }
+            return `Set ${items.join(', ')}`
+        }
+
+        case 'ProcessHttp':
+            return `[${action.settings.method}] Process ${action.settings.responseBodyVariable ?? ''}`
+
+        case 'SetVariable':
+            return `Set ${action.settings.variable} to ${sanitize(action.settings.value ?? '')}`
+
+        case 'ProcessCommand':
+            return `[${action.settings.method.toUpperCase()}] Process ${action.settings.variable}`
+
+        default:
+            return undefined
+    }
+}

package/src/utils/whatsapp.ts

@@ -1,5 +1,12 @@
+import { Node, type PossiblyNode } from '../types/node.ts'
 import type { MessageTemplate, MessageTemplatePreview, MessageTemplateVariable } from '../types/whatsapp.ts'
 
+// A contact's identity is a GUID (BSUID) when they haven't shared their phone number with
+// the business, and a phone number when they have — a phone-shaped check tells them apart.
+export function isWhatsAppGuidIdentity(identity: PossiblyNode): boolean {
+    return !/^\d+$/.test(Node.from(identity).name)
+}
+
 type TemplateHeaderFormat = NonNullable<MessageTemplatePreview['headerFormat']>
 
 type TemplateHeaderComponent = {