cmcts-c-agent-embedding 1.0.22 → 1.0.23-vpcp

package/.env.example

@@ -3,14 +3,14 @@
 # ==============================================
 
 # API Host URL (required)
-# This should be the URL where your Flowise instance is running
-# Example: https://your-flowise-instance.com
+# This should be the URL where your CAgent instance is running
+# Example: https://your-cagent-instance.com
 API_HOST=
 
-# Flowise API Key (required)
-# Generate this from your Flowise instance settings page
+# CAgent API Key (required)
+# Generate this from your CAgent instance settings page
 # Example: OxxGE-h_LaH7ZYorStjTOik1XY999RxxoHpCSYl8BXxc
-FLOWISE_API_KEY=
+CAGENT_API_KEY=
 
 # ==============================================
 # CHATFLOWS CONFIGURATION (required)
@@ -20,7 +20,7 @@ FLOWISE_API_KEY=
 #
 # Each entry consists of:
 # - identifier: Any name you choose (e.g., agent1, support, salesbot)
-# - chatflowId: The UUID of your Flowise chatflow
+# - chatflowId: The UUID of your CAgent chatflow
 # - allowedDomains: Comma-separated list of domains where this chat can be embedded
 #                   Note: Wildcard domains (*) are not supported for security reasons
 #
@@ -32,3 +32,9 @@ FLOWISE_API_KEY=
 # Add your chatflows below:
 chatflow_1=
 chatflow_2=
+
+# ==============================================
+# OPTIONAL CONFIGURATION
+# ==============================================
+
+

package/.idea/{Flowise-share-chatbox.iml → flowise-chatbox.iml}

@@ -8,6 +8,5 @@
     </content>
     <orderEntry type="inheritedJdk" />
     <orderEntry type="sourceFolder" forTests="false" />
-    <orderEntry type="module" module-name="Flowise-share-chatbox-main" />
   </component>
 </module>

package/.idea/modules.xml

@@ -2,8 +2,7 @@
 <project version="4">
   <component name="ProjectModuleManager">
     <modules>
-      <module fileurl="file://$PROJECT_DIR$/.idea/Flowise-share-chatbox.iml" filepath="$PROJECT_DIR$/.idea/Flowise-share-chatbox.iml" />
-      <module fileurl="file://$PROJECT_DIR$/../Flowise-share-chatbox-main/.idea/Flowise-share-chatbox-main.iml" filepath="$PROJECT_DIR$/../Flowise-share-chatbox-main/.idea/Flowise-share-chatbox-main.iml" />
+      <module fileurl="file://$PROJECT_DIR$/.idea/flowise-chatbox.iml" filepath="$PROJECT_DIR$/.idea/flowise-chatbox.iml" />
     </modules>
   </component>
 </project>

package/.idea/vcs.xml

@@ -1,7 +1,6 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="VcsDirectoryMappings">
-    <mapping directory="" vcs="Git" />
-    <mapping directory="$PROJECT_DIR$/../Flowise-share-chatbox-main" vcs="Git" />
-  </component>
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
 </project>

package/AGENTS.md

@@ -0,0 +1,166 @@
+# AGENTS.md - Coding Guidelines
+
+> **Purpose:** Guidelines for code quality, development process, and decision-making  
+> **Target Audience:** AI coding assistants and developers  
+> **Version:** 1.0
+
+---
+
+## Code Quality Standards
+
+### Core Principles
+
+#### No Unused Code
+- **Rule:** Don't write unused code
+- **Requirement:** Ensure everything written is utilized in the project
+- **Priority:** Critical
+
+#### Readability First
+- **Rule:** Prioritize readability for human understanding over execution efficiency
+- **Priority:** Critical
+
+#### Maintainability
+- **Rule:** Maintain long-term maintainability over short-term optimization
+- **Priority:** High
+
+#### Simplicity
+- **Rule:** Avoid unnecessary complexity
+- **Approach:** Implement simple solutions unless complexity is truly required
+- **Priority:** High
+
+#### Clean Code Philosophy
+- **Rule:** Follow Linus Torvalds' clean code principles
+- **Priority:** High
+- **Guidelines:**
+  1. Keep it simple
+  2. Make code readable like prose
+  3. Avoid premature optimization
+  4. Express intent clearly
+  5. Minimize abstraction layers
+
+---
+
+### Documentation Standards
+
+#### Comment Purpose
+- **Rule:** Comments must explain "what" (business logic/purpose) and "why" (reasoning/decisions), not "how"
+- **Priority:** High
+
+#### Avoid Over-Commenting
+- **Rule:** Avoid over-commenting
+- **Rationale:** Excessive comments indicate poor code quality
+- **Priority:** Medium
+
+#### Function Comments
+- **Rule:** Function comments must explain purpose and reasoning
+- **Placement:** Placed at function beginnings
+- **Priority:** Medium
+
+#### Self-Explanatory Code
+- **Rule:** Well-written code should be self-explanatory
+- **Method:** Through meaningful names and clear structure
+- **Priority:** High
+
+---
+
+## Development Process
+
+> **Description:** Follow these steps in order for effective development  
+> **Priority:** Critical
+
+| Step | Name | Action/Rationale | Importance |
+|------|------|------------------|------------|
+| 1 | Understand First | Use available tools to understand data structures before implementation | Critical |
+| 2 | Design Data Structures | Good data structures lead to good code | Critical |
+| 3 | Define Interfaces | Specify all input/output structures before writing logic | High |
+| 4 | Define Functions | Create all function signatures before implementation | High |
+| 5 | Implement Logic | Write implementation only after structures and definitions are complete | High |
+| 6 | Validate Code Quality | Always run lint and typecheck after writing code. Fix all linting errors and type errors before considering the task complete. Zero tolerance for lint and typecheck errors | Critical |
+
+---
+
+## Quality Guidelines
+
+#### Avoid Over-Engineering
+- **Rule:** Avoid over-engineering
+- **Focus:** Focus on minimal viable solutions meeting acceptance criteria
+- **Priority:** High
+
+#### Testing Approach
+- **Rule:** Only create automated tests if explicitly required
+- **Priority:** Medium
+
+#### Feature Scope
+- **Rule:** Never add functionality "just in case"
+- **Requirement:** Implement only what's needed now
+- **Priority:** High
+
+#### Code Validation
+- **Rule:** Always run lint and typecheck after code changes
+- **Requirement:** Must fix all linting and type checking errors before completion
+- **Process:** Run lint command, then typecheck command. Address all errors and warnings
+- **Tolerance:** Zero tolerance for lint or typecheck errors
+- **Priority:** Critical
+
+---
+
+## Decision Making Framework
+
+> **Description:** Apply these principles systematically for all decisions  
+> **Priority:** High
+
+| Step | Principle | Importance |
+|------|-----------|------------|
+| 1 | Gather Complete Information | Critical |
+| 2 | Multi-Perspective Analysis | High |
+| 3 | Consider All Stakeholders | High |
+| 4 | Evaluate Alternatives | High |
+| 5 | Assess Impact & Consequences | High |
+| 6 | Apply Ethical Framework | Medium |
+| 7 | Take Responsibility | High |
+| 8 | Learn & Adapt | High |
+
+---
+
+## Code Validation Workflow
+
+> **Description:** Mandatory validation process after writing or modifying code  
+> **Priority:** Critical
+
+#### Validation Commands
+- **Lint Fix Command:** `yarn run lint-fix`
+- **Type Check Command:** `yarn run type-check`
+- **Combined Command:** `yarn run lint-fix && yarn run type-check`
+
+#### Required Workflow
+| Step | Action | Description |
+|------|--------|-------------|
+| 1 | Write/Edit Code | Make your code changes |
+| 2 | Run Validation | Execute `yarn run lint-fix && yarn run type-check` |
+| 3 | Review Results | Check for any remaining errors |
+| 4 | Fix Errors | Address all lint and type errors |
+| 5 | Repeat | Run validation again until all errors are resolved |
+
+#### Rules
+- **Rule:** Always run validation commands after every code change
+- **Requirement:** Must run both lint-fix and type-check before considering task complete
+- **Tolerance:** Zero errors allowed - all lint and type errors must be fixed
+- **Priority:** Critical
+
+---
+
+## Package Manager
+
+#### Required Package Manager
+- **Rule:** Use `yarn` as the package manager for this project
+- **Requirement:** All package installations and script executions must use `yarn`
+- **Prohibited:** Do NOT use `npm`, `pnpm`, or `bun`
+- **Priority:** Critical
+
+#### Examples
+| Action | Correct | Incorrect |
+|--------|---------|-----------|
+| Install dependencies | `yarn install` | `npm install`, `pnpm install` |
+| Add package | `yarn add <package>` | `npm install <package>` |
+| Run script | `yarn run <script>` | `npm run <script>` |
+| Remove package | `yarn remove <package>` | `npm uninstall <package>` |

package/CLAUDE.md

@@ -0,0 +1,77 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+CAgent Embed is a JavaScript library for embedding a chatbot widget on websites. It connects to a CAgent (Flowise-based) backend and provides both popup and fullpage chat interfaces. The project also includes a proxy server for secure deployment.
+
+## Commands
+
+```bash
+# Install dependencies
+yarn install --frozen-lockfile
+
+# Development (starts dev server on localhost:5678 with hot reload)
+yarn dev
+
+# Production build (outputs to dist/web.js)
+yarn build
+
+# Type checking
+yarn type-check
+
+# Linting
+yarn lint
+yarn lint-fix
+
+# Start proxy server (for production deployment, runs on port 3001)
+yarn start
+
+# Build and publish to npm
+yarn build-and-publish
+```
+
+## Architecture
+
+### Entry Points
+- `src/web.ts` - Main entry point, registers web components and exposes `Chatbot` API on window
+- `src/register.tsx` - Registers custom elements `<cagent-chatbot>` (popup) and `<cagent-fullchatbot>` (fullpage)
+- `src/window.ts` - Exposes `Chatbot.init()`, `Chatbot.initFull()`, and `Chatbot.destroy()` methods
+
+### Core Components
+- `src/components/Bot.tsx` - Main chat component handling messages, streaming, TTS/STT, file uploads, and all chat logic
+- `src/features/bubble/components/Bubble.tsx` - Popup bubble UI wrapper
+- `src/features/full/components/Full.tsx` - Fullpage chat UI wrapper
+
+### Key Utilities
+- `src/queries/sendMessageQuery.ts` - API communication with CAgent backend
+- `src/utils/audioRecording.ts` - Audio recording for speech-to-text
+- `src/utils/transcriptApi.ts` - Audio transcription API
+- `src/utils/security.ts` - Security utilities
+
+### Proxy Server
+- `server.js` - Express proxy server that:
+  - Hides CAgent API host and chatflow IDs from client
+  - Implements domain-based access control
+  - Handles API key authentication server-side
+  - Requires `.env` configuration with `API_HOST`, `CAGENT_API_KEY`, and chatflow mappings
+
+## Tech Stack
+
+- **Framework**: SolidJS with solid-element for web components
+- **Build**: Rollup with Babel, TypeScript, PostCSS/Tailwind
+- **Styling**: Tailwind CSS (processed at build time, injected inline)
+- **Streaming**: Microsoft fetch-event-source for SSE streaming responses
+- **Path alias**: `@/*` maps to `src/*`
+
+## Configuration
+
+Environment variables (`.env`):
+```
+API_HOST=https://your-cagent-instance.com
+CAGENT_API_KEY=your-api-key
+chatflow_1=<chatflowId>,<allowedDomain1>,<allowedDomain2>
+```
+
+For local development, update `public/index.html` to test the chatbot widget.