npm - @botonic/nx-plugin - Versions diffs - 2.23.0 - Mend

@botonic/nx-plugin 2.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (206) hide show

package/src/generators/bot-app/files/README.md.template ADDED Viewed

@@ -0,0 +1,148 @@
+# <%= className %> Bot
+A modern Botonic bot application built with TypeScript, Vite, and React.
+## 🚀 Getting Started
+### Development
+```bash
+# Start webchat development server
+pnpm run serve:webchat
+# Start webviews development server
+pnpm run serve:webviews
+# Start Lambda development server
+pnpm run serve:lambda
+# Start all development servers
+pnpm run serve
+# Build for production
+pnpm run build
+# Build for Node.js (Lambda)
+pnpm run build:node
+# Run tests
+pnpm run test
+# Type checking
+pnpm run typecheck
+```
+## 📁 Project Structure
+```
+src/
+├── client/           # Client-side applications
+│   ├── webchat/     # Webchat interface
+│   └── webviews/    # Webview interfaces
+├── server/          # Server-side bot logic
+│   ├── bot/         # Bot configuration and actions
+│   └── lambda/      # AWS Lambda handler
+└── shared/          # Shared utilities and config
+```
+## 🔧 Configuration
+### Bot Configuration
+The main bot configuration is in `src/server/bot/index.ts`. This includes:
+- **Routes**: Define conversation flows
+- **Actions**: Handle user interactions
+- **Locales**: Multi-language support
+- **Plugins**: Extend bot functionality
+- **Theme**: Customize appearance
+### Environment Variables
+Copy the example environment file and customize for your setup:
+```bash
+# Copy example environment file
+cp .env.example .env.local
+# Edit with your values
+vim .env.local
+```
+> **Note**: `.env.local` is gitignored and should contain your personal/local values. Never commit this file.
+## 🎯 Development Targets
+### Webchat (`serve:webchat`)
+- Develops the webchat interface
+- Hot reload enabled
+- React-based UI
+### Webviews (`serve:webviews`)
+- Develops custom webview interfaces
+- Interactive forms and displays
+- React-based UI
+### Lambda (`serve:lambda`)
+- Local Lambda development with SAM
+- Simulates AWS Lambda environment
+- Automatic rebuild on changes
+## 🏗️ Build Process
+The project uses **Vite** for fast building and development:
+- **TypeScript**: Full type safety
+- **Project References**: Optimized compilation
+- **Tree Shaking**: Minimal bundle size
+- **Hot Module Replacement**: Fast development
+## 🔌 Adding Features
+### New Action
+1. Create action in `src/server/bot/actions/`
+2. Add route in `src/server/bot/routes.ts`
+3. Update locales if needed
+### New Plugin
+1. Install plugin: `pnpm install @botonic/plugin-xyz`
+2. Add to `src/server/bot/plugins.ts`
+3. Configure in bot config
+### New Webview
+1. Create component in `src/client/webviews/`
+2. Add routing if needed
+3. Style with CSS modules
+## 📚 Learn More
+- [Botonic Documentation](https://botonic.io/docs/)
+- [Vite Documentation](https://vitejs.dev/)
+- [TypeScript Project References](https://www.typescriptlang.org/docs/handbook/project-references.html)
+- [Nx Documentation](https://nx.dev/)
+## 🚀 Deployment
+### AWS Lambda
+```bash
+# Build for Lambda
+pnpm run build:node
+# Deploy with SAM
+cd src/server/lambda
+sam build
+sam deploy --guided
+```
+### Production Build
+```bash
+# Build all targets
+pnpm run build
+# The built files will be in:
+# - dist/client/webchat/   (webchat interface)
+# - dist/client/webviews/  (webview interfaces)
+# - dist/server/           (Lambda function)
+```

package/src/generators/bot-app/files/src/client/custom-messages/index.ts.template ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export const customMessages = {}
2	+

package/src/generators/bot-app/files/src/client/webchat/index.html.template ADDED Viewed

@@ -0,0 +1,35 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title><%= className %> Webchat</title>
+    <base href="/" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+  </head>
+  <body>
+    <div id="webchat-root"></div>
+    <script type="module" src="./index.tsx"></script>
+    <script type="text/javascript">
+      document.addEventListener('DOMContentLoaded', function () {
+        var container = document.getElementById('webchat-root')
+        if (container) {
+          var params = new URLSearchParams(window.location.search)
+          var appId = params.get('appId') || '%VITE_HUBTYPE_APP_ID%'
+          var storageKey = params.get('storageKey')
+          var webchatConfig = { appId: appId }
+          if (storageKey) {
+            webchatConfig.storage = { keyPrefix: storageKey }
+          }
+          window.botonic.render(container, webchatConfig, {
+            title: '<%= className %>',
+            placeholder: 'Type your message...',
+          })
+        }
+      })
+    </script>
+  </body>
+</html>

package/src/generators/bot-app/files/src/client/webchat/index.tsx.template ADDED Viewed

@@ -0,0 +1,107 @@
+import './styles.css'
+import type { WebchatConfig } from '@botonic/webchat-core'
+import type { WebchatTriggerProps } from '@botonic/webchat-react/trigger'
+import { WebchatTrigger } from '@botonic/webchat-react/trigger'
+import React from 'react'
+import { createRoot } from 'react-dom/client'
+import { customMessages } from '../custom-messages'
+interface WebchatOptions {
+  title: string
+  placeholder: string
+}
+declare global {
+  interface Window {
+    botonic: {
+      render: (
+        container: HTMLElement,
+        webchatConfig: WebchatConfig,
+        options: WebchatOptions
+      ) => void
+      // Ready state
+      ready: Promise<void>
+      isReady: () => boolean
+      // All other methods from PublicWebchatController will be available after ready
+      [key: string]: unknown
+    }
+  }
+}
+function App({
+  webchatConfig,
+  options,
+}: {
+  webchatConfig: WebchatConfig
+  options: WebchatOptions
+}) {
+  // Default avatar SVG
+  const defaultAvatarSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="17" height="18" viewBox="0 0 17 18" fill="none">
+    <circle cx="8.5" cy="9" r="8.5" fill="#24252C"/>
+    <path d="M5.9647 5.03898C5.9647 4.61514 5.80479 4.45386 5.36004 4.45386C4.90405 4.45386 4.74414 4.61639 4.74414 5.03898C4.74414 5.46281 4.90405 5.6241 5.36004 5.6241C5.80479 5.6241 5.9647 5.46281 5.9647 5.03898Z" fill="white"/>
+    <path d="M11.1872 4.45386C10.7312 4.45386 10.5713 4.61639 10.5713 5.03898C10.5713 5.46281 10.7312 5.6241 11.1872 5.6241C11.6307 5.6241 11.7919 5.46156 11.7919 5.03898C11.7906 4.61514 11.6307 4.45386 11.1872 4.45386Z" fill="white"/>
+    <path d="M10.99 6.47729H10.7063C10.4352 6.47729 10.3365 6.60233 10.2503 6.99995L9.32574 10.8498C9.15332 11.4975 8.95591 11.6726 8.40117 11.6726H8.13005C7.5878 11.6726 7.3779 11.4988 7.20548 10.8498L6.28092 6.99995C6.19471 6.60108 6.1085 6.47729 5.83737 6.47729H5.55376C5.30762 6.47729 5.19643 6.6636 5.29513 7.04996L6.37962 11.2112C6.56453 11.9339 6.93436 12.2953 7.56406 12.4315C7.72399 12.4691 7.8102 12.5566 7.8102 12.7304V14.5884C7.8102 14.7997 7.94638 14.9373 8.15504 14.9373H8.38993C8.58733 14.9373 8.73476 14.7997 8.73476 14.5884V12.7316C8.73476 12.5566 8.82097 12.4703 8.9809 12.4328C9.59686 12.2953 9.96793 11.9339 10.1641 11.2124L11.2486 7.05121C11.3473 6.66485 11.2361 6.47729 10.99 6.47729Z" fill="white"/>
+  </svg>`
+  const avatarConfig = {
+    bot: {
+      placement: 'bubble' as const,
+      svg: defaultAvatarSvg,
+      alt: options.title || '<%= className %>',
+      showName: true,
+      name: options.title || '<%= className %>',
+    },
+  }
+  // Handle webchat ready – full control over when/how to open
+  const handleReady = React.useCallback<
+    NonNullable<WebchatTriggerProps['onReady']>
+  >(controller => {
+    console.log('🚀 Webchat ready!')
+    // Developer decides: open, log, analytics, etc.
+    controller.open()
+  }, [])
+  return (
+    <WebchatTrigger
+      appId={webchatConfig.appId}
+      position='bottom-right'
+      onReady={handleReady}
+      webchatConfig={{
+        avatarConfig,
+        customMessages,
+        title: options.title || '<%= className %>',
+        placeholder: options.placeholder || 'Message...',
+      }}
+    />
+  )
+}
+// Higher-order render function that integrates with the existing botonic API
+function renderWebchat(
+  container: HTMLElement,
+  webchatConfig: WebchatConfig,
+  options: WebchatOptions
+) {
+  if (!container) {
+    console.error('Webchat container not found:', container)
+    return
+  }
+  const root = createRoot(container)
+  root.render(<App webchatConfig={webchatConfig} options={options} />)
+}
+// Expose render; index.html inline script calls it with appId from URL or %VITE_HUBTYPE_APP_ID% (Vite replaces that in HTML)
+if (typeof window !== 'undefined') {
+  if (!window.botonic) {
+    window.botonic = {} as Window['botonic']
+  }
+  window.botonic.render = renderWebchat
+  if (window.self !== window.top) {
+    document.documentElement.classList.add('embedded-in-frame')
+    document.body.classList.add('embedded-in-frame')
+  }
+}

package/src/generators/bot-app/files/src/client/webchat/styles.css.template ADDED Viewed

@@ -0,0 +1,17 @@
+/* Import library styles (standard CSS import pattern) */
+@import '@botonic/webchat-react/styles.css';
+/* Import app-specific token overrides */
+@import './webchat-tokens-overrides.css';
+/* Global styles for the <%= fileName %> app */
+body {
+  margin: 0;
+  padding: 0;
+  font-family: var(--font-family);
+}
+#webchat-root {
+  width: 100%;
+  height: 100vh;
+}

package/src/generators/bot-app/files/src/client/webchat/webchat-tokens-overrides.css.template ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ @layer overrides {
2	+ }

package/src/generators/bot-app/files/src/client/webviews/app.tsx.template ADDED Viewed

@@ -0,0 +1,8 @@
+export function App() {
+  return (
+    <div className='app'>
+      <h1>Welcome to <%= className %> Webviews</h1>
+      <p>This is a sample webview for your bot.</p>
+    </div>
+  )
+}

package/src/generators/bot-app/files/src/client/webviews/index.html.template ADDED Viewed

@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title><%= className %> Webview</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+    <style>
+      body {
+        margin: 0px;
+      }
+    </style>
+  </head>
+  <body>
+    <script>
+      ;(function (d, s, id) {
+        var js,
+          fjs = d.getElementsByTagName(s)[0]
+        if (d.getElementById(id)) {
+          return
+        }
+        js = d.createElement(s)
+        js.id = id
+        js.src = 'https://connect.facebook.net/en_US/messenger.Extensions.js'
+        fjs.parentNode.insertBefore(js, fjs)
+      })(document, 'script', 'Messenger')
+    </script>
+    <div id="webviews-root"></div>
+    <script type="module" src="./index.tsx"></script>
+  </body>
+</html>

package/src/generators/bot-app/files/src/client/webviews/index.tsx.template ADDED Viewed

@@ -0,0 +1,18 @@
+import { WebviewApp, WebviewDefinition } from '@botonic/webviews'
+import * as ReactDOM from 'react-dom/client'
+import { WEBVIEWS } from '../../shared/constants'
+export const webviews: WebviewDefinition[] = [
+  // Add your webviews here
+  // Example:
+  // {
+  //   path: WEBVIEWS.EXAMPLE,
+  //   component: ExampleWebview,
+  // },
+]
+const root = ReactDOM.createRoot(
+  document.getElementById('webviews-root') as HTMLElement
+)
+root.render(<WebviewApp webviews={webviews} />)

package/src/generators/bot-app/files/src/server/bot/actions/index.ts.template ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export * from './welcome'
2	+ export * from './not-found'

package/src/generators/bot-app/files/src/server/bot/actions/not-found.ts.template ADDED Viewed

@@ -0,0 +1,13 @@
+import { BotContext, BotServerMessageFactory } from '@botonic/shared'
+export async function NotFound({ sendMessage }: BotContext) {
+  const message = BotServerMessageFactory.createText({
+    text: 'Sorry, I didn\'t understand that.\n\nTry saying "hello" to get started!',
+  })
+  await sendMessage(message)
+  return {
+    status: 200,
+    response: 'OK',
+  }
+}

package/src/generators/bot-app/files/src/server/bot/actions/welcome.ts.template ADDED Viewed

@@ -0,0 +1,13 @@
+import { BotContext, BotServerMessageFactory } from '@botonic/shared'
+export async function Welcome({ sendMessage }: BotContext) {
+  const message = BotServerMessageFactory.createText({
+    text: `Hello! I'm <%= className %> 🤖\n\nWelcome to your new Botonic bot! You can start building your conversation flow by editing the routes and actions.`,
+  })
+  await sendMessage(message)
+  return {
+    status: 200,
+    response: 'OK',
+  }
+}

package/src/generators/bot-app/files/src/server/bot/index.ts.template ADDED Viewed

@@ -0,0 +1,43 @@
+// eslint-disable-next-line @nx/enforce-module-boundaries
+import { CoreBot } from '@botonic/core'
+import { BotContext, BotServerMessageFactory } from '@botonic/shared'
+import { plugins } from './plugins'
+import { routes } from './routes'
+const DefaultFallbackAction = async ({ sendMessage }: BotContext) => {
+  const message = BotServerMessageFactory.createText({
+    text: "I don't understand you",
+  })
+  await sendMessage(message)
+  return {
+    status: 200,
+    response: 'OK',
+  }
+}
+const defaultRoutes = (botContext: BotContext) => [
+  {
+    path: '404',
+    action: async () => await DefaultFallbackAction(botContext),
+  },
+]
+export class NodeApp {
+  readonly bot: CoreBot
+  constructor(options: any) {
+    const config = {
+      defaultRoutes,
+      ...options,
+    }
+    this.bot = new CoreBot(config)
+  }
+  input(args: any) {
+    return this.bot.input(args)
+  }
+}
+export const app = new NodeApp({ routes, plugins })

package/src/generators/bot-app/files/src/server/bot/plugins/ai-agents/index.ts.template ADDED Viewed

@@ -0,0 +1,30 @@
+import { AiAgentArgs, BotonicPluginAiAgents } from '@botonic/plugin-ai-agents'
+import { BotContext } from '@botonic/shared'
+import { customTools } from '../../tools'
+import { BotPlugins } from '../../types'
+// Only initialize AI agents plugin if Azure OpenAI credentials are configured
+const hasAiAgentsConfig = Boolean(
+  process.env.AZURE_OPENAI_API_KEY || process.env.OPENAI_API_KEY
+)
+export const aiAgentsPlugin = hasAiAgentsConfig
+  ? new BotonicPluginAiAgents({
+      customTools: customTools,
+    })
+  : null
+export async function getAiAgentResponse(
+  botContext: BotContext<BotPlugins>,
+  aiAgentArgs: AiAgentArgs
+) {
+  const aiAgentPlugin = botContext.plugins.aiAgents
+  if (!aiAgentPlugin) {
+    throw new Error(
+      'AI Agents plugin is not configured. Please set AZURE_OPENAI_API_KEY or OPENAI_API_KEY environment variable.'
+    )
+  }
+  const response = await aiAgentPlugin.getInference(botContext, aiAgentArgs)
+  return response
+}

package/src/generators/bot-app/files/src/server/bot/plugins/flow-builder/index.ts.template ADDED Viewed

@@ -0,0 +1,28 @@
+import { AiAgentArgs } from '@botonic/plugin-ai-agents'
+import {
+  BotonicPluginFlowBuilder,
+  BotonicPluginFlowBuilderOptions,
+  FlowBuilderJSONVersion,
+} from '@botonic/plugin-flow-builder'
+import { BotContext } from '@botonic/shared'
+import { trackEventToHubtypeAnalytics } from '../../tracking'
+import { isLambdaLocal } from '../../utils'
+import { getAiAgentResponse } from '../ai-agents'
+export const flowBuilderConfig: BotonicPluginFlowBuilderOptions = {
+  flowVersion: isLambdaLocal()
+    ? FlowBuilderJSONVersion.DRAFT
+    : FlowBuilderJSONVersion.LATEST,
+  trackEvent: async (botContext: BotContext, eventAction, args) => {
+    await trackEventToHubtypeAnalytics(botContext, eventAction, args)
+  },
+  getAiAgentResponse: async (
+    botContext: BotContext,
+    aiAgentArgs: AiAgentArgs
+  ) => {
+    return getAiAgentResponse(botContext, aiAgentArgs)
+  },
+}
+export const flowBuilderPlugin = new BotonicPluginFlowBuilder(flowBuilderConfig)

package/src/generators/bot-app/files/src/server/bot/plugins/index.ts.template ADDED Viewed

@@ -0,0 +1,11 @@
+import { BotonicPluginHubtypeAnalytics } from '@botonic/plugin-hubtype-analytics'
+import { aiAgentsPlugin } from './ai-agents'
+import { flowBuilderPlugin } from './flow-builder'
+export const plugins = {
+  flowBuilder: flowBuilderPlugin,
+  // AI Agents plugin is only loaded if AZURE_OPENAI_API_KEY or OPENAI_API_KEY is set
+  ...(aiAgentsPlugin && { aiAgents: aiAgentsPlugin }),
+  hubtypeAnalytics: new BotonicPluginHubtypeAnalytics(),
+}

package/src/generators/bot-app/files/src/server/bot/routes.ts.template ADDED Viewed

@@ -0,0 +1,23 @@
+import { FlowBuilderAction } from '@botonic/plugin-flow-builder'
+import { BotContext } from '@botonic/shared'
+import { Welcome, NotFound } from './actions'
+export const routes = (botContext: BotContext) => {
+  return [
+    {
+      text: /^(hi|hello|start|hola)$/i,
+      action: async () => await Welcome(botContext),
+    },
+    {
+      path: 'flow-builder',
+      text: /.*/,
+      payload: /.*/,
+      action: async () => await FlowBuilderAction.botonicInit(botContext),
+    },
+    {
+      path: 'not-found',
+      action: async () => await NotFound(botContext),
+    },
+  ]
+}

package/src/generators/bot-app/files/src/server/bot/tools/index.ts.template ADDED Viewed

@@ -0,0 +1,5 @@
+import { CustomTool } from '@botonic/plugin-ai-agents'
+// Define custom AI agent tools here
+export const customTools: CustomTool[] = []

package/src/generators/bot-app/files/src/server/bot/tracking.ts.template ADDED Viewed

@@ -0,0 +1,35 @@
+import {
+  BotonicPluginHubtypeAnalytics,
+  EventAction,
+  HtEventProps,
+} from '@botonic/plugin-hubtype-analytics'
+import { BotContext } from '@botonic/shared'
+import { BotPlugins } from './types'
+export async function trackEventToHubtypeAnalytics(
+  botContext: BotContext<BotPlugins>,
+  eventName: EventAction,
+  args: Omit<HtEventProps, 'action'>
+): Promise<void> {
+  const hubtypeAnalyticsPlugin = botContext.plugins.hubtypeAnalytics
+  const htEventProps = {
+    action: eventName,
+    ...args,
+  } as HtEventProps
+  if (
+    !hubtypeAnalyticsPlugin ||
+    !(hubtypeAnalyticsPlugin instanceof BotonicPluginHubtypeAnalytics)
+  ) {
+    console.log('Hubtype Analytics Plugin not found')
+    return
+  }
+  const response = await hubtypeAnalyticsPlugin.trackEvent(
+    botContext,
+    htEventProps
+  )
+  console.log('TrackEvent Response', response, args)
+  return
+}

package/src/generators/bot-app/files/src/server/bot/types.ts.template ADDED Viewed

@@ -0,0 +1,4 @@
+import { plugins } from './plugins'
+export type BotPlugins = typeof plugins

package/src/generators/bot-app/files/src/server/bot/utils.ts.template ADDED Viewed

@@ -0,0 +1,9 @@
+export function isLambdaLocal(): boolean {
+  // AWS SAM sets AWS_SAM_LOCAL when running locally
+  // Or if AWS_LAMBDA_FUNCTION_NAME doesn't exist (only exists in real AWS)
+  return !!process.env.AWS_SAM_LOCAL || !process.env.AWS_LAMBDA_FUNCTION_NAME
+}
+export const empty = (object: Record<string, any>): boolean =>
+  Object.keys(object).length === 0

package/src/generators/bot-app/files/src/server/lambda/handler.js.template ADDED Viewed

@@ -0,0 +1,24 @@
+'use strict'
+/*
+	In lambda functions, it only have access to all files the first time it's invoked,
+	and placed into memory, after that it only calls the function that have the information
+	loadded in memory. For this reason, we initialize the bot the first time, and then we
+	only execute the input function
+	https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html
+*/
+import { app } from './dist/index.js'
+export const botonic = async (event, aws_context) => {
+  const { user_input, context } = event
+  await app.bot.input({
+    input: user_input || {},
+    session: context || {},
+  })
+  return {
+    statusCode: 200,
+  }
+}

package/src/generators/bot-app/files/src/server/lambda/package.json ADDED Viewed

@@ -0,0 +1,20 @@
+{
+  "name": "lambda",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "handler.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "uuid": "^11.1.0",
+    "@openai/agents": "^0.1.11",
+    "openai": "^5.23.2",
+    "tslib": "^2.3.0",
+    "zod": "^3.25.76"
+  }
+}

package/src/generators/bot-app/files/src/server/lambda/template.yaml.template ADDED Viewed

@@ -0,0 +1,20 @@
+AWSTemplateFormatVersion: 2010-09-09
+Description: botonic-lambda
+Transform:
+  - AWS::Serverless-2016-10-31
+Resources:
+  BotonicV2LocalLambda:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: handler.botonic
+      Runtime: nodejs20.x
+      Timeout: 30
+      Architectures:
+        - x86_64
+      Environment:
+        Variables:
+          STATIC_URL: http://localhost:4202/webviews.html # TODO: This will change in prod for our static assets hosting provider
+          AZURE_OPENAI_API_KEY: 'fake'
+          AZURE_OPENAI_ENDPOINT: 'fake'