aov-agent 1.0.0 → 1.0.6

package/README.md

@@ -1 +1,313 @@
-`
+# AOV AI Agent
+
+A React-based AI chat assistant library for Shopify applications, providing a seamless AI-powered support experience.
+
+## 🏗️ Project Structure
+
+This project follows Avada's monorepo structure as defined in [CLAUDE.md](./CLAUDE.md):
+
+```
+aov-ai-agent/
+├── packages/
+│   └── ui/                  # Frontend React UI package
+│       ├── src/
+│       │   ├── components/  # Reusable React components
+│       │   ├── contexts/    # React contexts
+│       │   ├── hooks/       # Custom React hooks
+│       │   ├── services/    # API services
+│       │   ├── utils/       # Utility functions
+│       │   └── index.js     # Main export
+│       ├── .babelrc         # Babel config for UI
+│       ├── .gitignore       # UI specific ignores
+│       ├── package.json     # UI package metadata
+│       └── README.md        # UI package documentation
+├── dist/
+│   └── agent-ui/            # Compiled UI output
+├── types/                   # TypeScript type definitions
+├── .babelrc                 # Root Babel configuration
+├── package.json             # Root package configuration (monorepo)
+└── CLAUDE.md                # Coding standards and guidelines
+```
+
+## 📦 Installation
+
+```bash
+npm install aov-agent
+```
+
+Install peer dependencies:
+
+```bash
+npm install react react-dom react-redux @shopify/polaris @shopify/polaris-icons
+```
+
+## 🚀 Usage
+
+### Import UI Components
+
+```javascript
+// ✅ Import from agent-ui subpath
+import { Assistant } from "aov-agent/agent-ui";
+
+function App() {
+  return (
+    <Assistant
+      shop={{
+        id: "shop-123",
+        showAgentChat: true,
+      }}
+      apiUrl="/api/chat/message"
+    />
+  );
+}
+```
+
+### Required Peer Dependencies
+
+```json
+{
+  "react": "^18.2.0",
+  "react-dom": "^18.2.0",
+  "react-redux": "^9.2.0",
+  "@shopify/polaris": "^13.9.5",
+  "@shopify/polaris-icons": "^9.3.1"
+}
+```
+
+## ✨ Features
+
+- **AI-Powered Chat Interface**: Streaming chat with AI assistant
+- **Thread Management**: Create, edit, delete, and switch between chat threads
+- **AI Suggestions**: Contextual suggestions for quick actions
+- **Tool Execution**: Support for AI tool calls and results
+- **Markdown Support**: Rich text formatting with math equations (KaTeX)
+- **Resizable Modal**: Draggable and resizable chat window
+- **Shopify Polaris UI**: Built with Shopify's design system
+- **PropTypes Validation**: Runtime type checking for components
+- **SSE Streaming**: Real-time streaming responses
+
+## 🛠️ Development
+
+### Build
+
+```bash
+npm run build
+```
+
+Compiles source code from `packages/ui/src/` to `dist/agent-ui/` using Babel.
+
+### Watch Mode
+
+```bash
+npm run build:watch
+```
+
+Automatically rebuilds on file changes.
+
+## 📚 Documentation
+
+See [CLAUDE.md](./CLAUDE.md) for:
+
+- Coding standards and conventions
+- Project structure guidelines
+- React component patterns
+- API integration guidelines
+- Error handling best practices
+
+See [packages/ui/README.md](./packages/ui/README.md) for:
+
+- Detailed component documentation
+- Hook usage examples
+- Context API reference
+
+## 🏛️ Architecture
+
+### Components
+
+- **Assistant**: Main container with provider wrappers
+- **AssistantWidget**: Chat UI with thread list and composer
+- **ThreadProvider**: Manages thread state and streaming runtime
+- **ResizableModal**: Draggable modal container
+
+### Contexts
+
+- **AgentContext**: Agent visibility state
+- **SuggestionsContext**: AI suggestions management
+- **ThreadContext**: Thread list and CRUD operations
+
+### Hooks
+
+- **useFetchApi**: Data fetching with pagination
+- **useStreamApi**: SSE streaming API calls
+- **useThreadAutoScrollFix**: Auto-scroll behavior
+
+## 🎨 Tech Stack
+
+- React 18.2
+- Shopify Polaris 13.9
+- @assistant-ui/react
+- Redux for state management
+- KaTeX for math rendering
+- PropTypes for validation
+
+## 📝 Code Standards
+
+This project follows Avada's coding standards:
+
+- ✅ ES6+ features (import/export, async/await, arrow functions)
+- ✅ camelCase for functions/variables
+- ✅ PascalCase for components/classes
+- ✅ JSDoc documentation
+- ✅ PropTypes validation
+- ✅ Early returns (no nested conditions)
+- ✅ Structured error handling
+
+## 🤝 Contributing
+
+Follow the guidelines in [CLAUDE.md](./CLAUDE.md) for:
+
+- Naming conventions
+- Function design patterns
+- React component structure
+- Documentation requirements
+- Error handling patterns
+
+## 📦 Publishing to NPM
+
+This package is designed to be published to NPM for use in other projects.
+
+### Build and Publish
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Clean and build (works on Windows & Linux)
+npm run clean
+npm run build
+
+# 3. Verify build output
+# On Linux/Mac:
+ls -la dist/agent-ui/
+# On Windows:
+dir dist\agent-ui\
+
+# 4. Test locally (optional)
+npm link
+
+# 5. Publish to NPM
+npm publish
+```
+
+**Note:** The `clean` script uses `rimraf` which works cross-platform (Windows, Linux, Mac).
+
+### Package Structure
+
+When published, the package structure will be:
+
+```
+aov-agent/
+├── dist/
+│   └── agent-ui/           # UI components
+│       ├── components/
+│       ├── contexts/
+│       ├── hooks/
+│       ├── services/
+│       ├── utils/
+│       └── index.js
+└── package.json
+```
+
+### Import Paths
+
+```javascript
+// UI Components
+import { Assistant } from "aov-agent/agent-ui";
+
+// Future packages (coming soon)
+// import { ... } from 'aov-agent/assets';
+// import { ... } from 'aov-agent/functions';
+```
+
+## 📦 Monorepo Structure
+
+This is a monorepo containing multiple packages:
+
+- **`packages/app/`** - Next.js 15 application (Frontend + Backend API Routes + Firestore)
+- **`packages/ui/`** - AI Assistant UI components (published as `aov-agent/agent-ui`)
+
+Each package can be developed, built, and tested independently.
+
+### 🚀 Quick Start for Development
+
+```bash
+# Install all dependencies
+npm install
+
+# Run Next.js development server
+npm run dev
+
+# App: http://localhost:3000
+# API: http://localhost:3000/api
+```
+
+### Project Structure
+
+```
+/aov-ai-agent/
+├── packages/
+│   ├── app/           # Next.js 15 App (Frontend + Backend API)
+│   │   ├── app/       # App Router
+│   │   │   ├── api/   # API Routes (Firestore backend)
+│   │   │   ├── layout.tsx
+│   │   │   ├── page.tsx
+│   │   │   └── globals.css
+│   │   ├── components/ui/  # shadcn/ui components
+│   │   ├── lib/            # Utilities & Firestore client
+│   │   ├── repositories/   # Firestore repositories
+│   │   ├── services/       # Business logic
+│   │   └── package.json
+│   └── ui/            # AI Assistant UI Components (publishable)
+│       └── src/
+│           └── components/
+```
+
+### Stack
+
+- **Frontend**: Next.js 15 + React 19 + TypeScript
+- **Styling**: Tailwind CSS + shadcn/ui
+- **Backend**: Next.js API Routes
+- **Database**: Google Cloud Firestore
+- **Validation**: Zod
+- **Icons**: Lucide React
+
+### Setup Firebase
+
+Create `packages/app/.env.local`:
+
+```bash
+GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/serviceAccount.json
+FIREBASE_PROJECT_ID=your-project-id
+NODE_ENV=development
+```
+
+Download your Firebase service account key from [Firebase Console](https://console.firebase.google.com/) → Project Settings → Service Accounts.
+
+### API Endpoints
+
+- `GET /api/health` - Health check
+- `GET /api/todos` - Get all todos
+- `POST /api/todos` - Create todo
+- `GET /api/todos/:id` - Get single todo
+- `PATCH /api/todos/:id` - Update todo
+- `DELETE /api/todos/:id` - Delete todo
+
+## 📄 License
+
+ISC
+
+## 🔗 Links
+
+- Repository: https://gitlab.com/avada/aov-ai-agent
+- Issues: https://gitlab.com/avada/aov-ai-agent/issues
+- NPM: https://www.npmjs.com/package/aov-agent

package/dist/agent-ui/components/Assistant/AgentButton/AgentButton.js

@@ -0,0 +1,28 @@
+import React from "react";
+import PropTypes from "prop-types";
+import { Icon } from "@shopify/polaris";
+import { MagicIcon } from "@shopify/polaris-icons";
+import "./AgentButton.scss";
+
+/**
+ * AgentButton - Floating button to trigger AI assistant
+ *
+ * @param {Function} onClick - Click handler to open assistant
+ * @returns {React.ReactElement} Agent button component
+ */
+var AgentButton = function AgentButton(_ref) {
+  var onClick = _ref.onClick;
+  return /*#__PURE__*/React.createElement("button", {
+    type: "button",
+    onClick: onClick,
+    className: "aov-agent-button",
+    "aria-label": "Open AI Assistant"
+  }, /*#__PURE__*/React.createElement(Icon, {
+    source: MagicIcon,
+    tone: "magic"
+  }));
+};
+AgentButton.propTypes = {
+  onClick: PropTypes.func.isRequired
+};
+export default AgentButton;

package/dist/agent-ui/components/Assistant/AgentButton/AgentButton.scss

@@ -0,0 +1,40 @@
+.aov-agent-button {
+  position: fixed;
+  bottom: 20px;
+  left: 20px;
+  z-index: 380;
+  min-width: 40px;
+  min-height: 40px;
+  padding: 2px;
+  border: none;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  background: #fff;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08),
+              0 4px 12px rgba(0, 0, 0, 0.08);
+  transition: all 0.2s ease;
+
+  &:hover {
+    transform: translateY(-1px);
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12),
+                0 8px 16px rgba(0, 0, 0, 0.12);
+  }
+
+  &:active {
+    transform: translateY(0);
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.08);
+  }
+
+  &:focus {
+    outline: 2px solid #007bff;
+    outline-offset: 2px;
+  }
+
+  &:focus:not(:focus-visible) {
+    outline: none;
+  }
+}
+

package/dist/agent-ui/components/Assistant/Assistant.js

@@ -0,0 +1,68 @@
+import React, { useContext } from "react";
+import PropTypes from "prop-types";
+import { AgentProvider, AgentContext } from "../../contexts/AgentContext.js";
+import { SuggestionsProvider } from "../../contexts/SuggestionsContext.js";
+import AgentButton from "./AgentButton/AgentButton.js";
+import ThreadProvider from "./ThreadProvider.js";
+import AssistantWidget from "./AssistantWidget/AssistantWidget.js";
+import ResizableModal from "../ResizableModal/ResizableModal.js";
+import "./Assistant.scss";
+var AssistantCore = function AssistantCore() {
+  var _useContext = useContext(AgentContext),
+    openAgent = _useContext.openAgent,
+    setOpenAgent = _useContext.setOpenAgent;
+  return /*#__PURE__*/React.createElement("div", {
+    className: "aov-assistant-core"
+  }, /*#__PURE__*/React.createElement(AgentButton, {
+    onClick: function onClick() {
+      return setOpenAgent(true);
+    }
+  }), /*#__PURE__*/React.createElement(ResizableModal, {
+    open: openAgent,
+    onClose: function onClose() {
+      return setOpenAgent(false);
+    },
+    accessibilityLabel: "Mavi"
+  }, /*#__PURE__*/React.createElement(SuggestionsProvider, null, /*#__PURE__*/React.createElement(ThreadProvider, null, /*#__PURE__*/React.createElement(AssistantWidget, {
+    onClose: function onClose() {
+      return setOpenAgent(false);
+    }
+  })))));
+};
+
+/**
+ * Assistant - Main AI assistant component with chat interface
+ *
+ * @param {Object} shop - Shop data object
+ * @param {boolean} shop.showAgentChat - Whether to show the agent chat
+ * @param {string} shop.id - Shop identifier
+ * @param {string} apiUrl - API endpoint URL for chat
+ * @param {string} appName - Application name
+ * @param {Object} customToolRenderers - Custom renderers for tools
+ * @returns {React.ReactElement} Assistant component
+ */
+export var Assistant = function Assistant(_ref) {
+  var shop = _ref.shop,
+    apiUrl = _ref.apiUrl,
+    appName = _ref.appName,
+    customToolRenderers = _ref.customToolRenderers;
+  if (!shop.showAgentChat) return null;
+  return /*#__PURE__*/React.createElement(AgentProvider, {
+    contextValue: {
+      appName: appName,
+      shop: shop,
+      apiUrl: apiUrl,
+      customToolRenderers: customToolRenderers
+    }
+  }, /*#__PURE__*/React.createElement(AssistantCore, null));
+};
+Assistant.propTypes = {
+  shop: PropTypes.shape({
+    showAgentChat: PropTypes.bool,
+    id: PropTypes.string
+  }),
+  apiUrl: PropTypes.string,
+  appName: PropTypes.string,
+  customToolRenderers: PropTypes.object
+};
+export default Assistant;

package/dist/agent-ui/components/Assistant/Assistant.scss

@@ -0,0 +1,3 @@
+.aov-assistant-core {
+  position: relative;
+}

package/dist/agent-ui/components/Assistant/AssistantWidget/AssistantWidget.js

@@ -0,0 +1,193 @@
+var _excluded = ["shop"];
+function _slicedToArray(r, e) { return _arrayWithHoles(r) || _iterableToArrayLimit(r, e) || _unsupportedIterableToArray(r, e) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t["return"] && (u = t["return"](), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(r) { if (Array.isArray(r)) return r; }
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+function _objectWithoutProperties(e, t) { if (null == e) return {}; var o, r, i = _objectWithoutPropertiesLoose(e, t); if (Object.getOwnPropertySymbols) { var n = Object.getOwnPropertySymbols(e); for (r = 0; r < n.length; r++) o = n[r], -1 === t.indexOf(o) && {}.propertyIsEnumerable.call(e, o) && (i[o] = e[o]); } return i; }
+function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (-1 !== e.indexOf(n)) continue; t[n] = r[n]; } return t; }
+import React, { useCallback, useState, useContext, useMemo } from "react";
+import PropTypes from "prop-types";
+import { Box, Button, InlineStack, Popover, Spinner, Text } from "@shopify/polaris";
+import { ComposeIcon, XIcon } from "@shopify/polaris-icons";
+import { ThreadContext } from "../../../contexts/ThreadContext.js";
+import { Composer, Thread, ThreadWelcome } from "@assistant-ui/react-ui";
+import { MarkdownText } from "../Markdown/MarkdownText.js";
+import MathRenderer from "../Markdown/MathRenderer.js";
+import { useThreadAutoScrollFix } from "../ThreadProvider.js";
+import Suggestions from "../Suggestions/Suggestions.js";
+import "@assistant-ui/react-markdown/styles/dot.css";
+import ToolResult from "../ToolResult/ToolResult.js";
+import ListChat from "./components/ListChat.js";
+import "./AssistantWidget.scss";
+import Avatar from "../../../resources/assistant-avatar.svg";
+import { welcomeSuggestions } from "../../../const/option";
+import { AgentContext } from "../../../contexts/AgentContext.js";
+var AssistantText = /*#__PURE__*/React.memo(function AssistantText(props) {
+  try {
+    return /*#__PURE__*/React.createElement("div", {
+      className: "assistant-markdown-text"
+    }, /*#__PURE__*/React.createElement(MathRenderer, null, /*#__PURE__*/React.createElement(MarkdownText, props)));
+  } catch (err) {
+    console.error("Error rendering markdown text:", err);
+    return /*#__PURE__*/React.createElement("div", {
+      className: "assistant-markdown-text"
+    }, props.children);
+  }
+});
+var AssistantTool = /*#__PURE__*/React.memo(function AssistantTool(_ref) {
+  var shop = _ref.shop,
+    props = _objectWithoutProperties(_ref, _excluded);
+  try {
+    return /*#__PURE__*/React.createElement(ToolResult, _extends({}, props, {
+      shop: shop
+    }));
+  } catch (err) {
+    console.error("Error rendering tool result:", err);
+    return null;
+  }
+});
+var AssistantWidget = function AssistantWidget(_ref2) {
+  var onClose = _ref2.onClose;
+  var _useContext = useContext(AgentContext),
+    appName = _useContext.appName,
+    shop = _useContext.shop;
+  var _useContext2 = useContext(ThreadContext),
+    threads = _useContext2.threads,
+    loadingThreads = _useContext2.loadingThreads,
+    getThread = _useContext2.getThread,
+    loadingMessages = _useContext2.loadingMessages,
+    thread = _useContext2.thread,
+    _setThread = _useContext2.setThread,
+    resetThread = _useContext2.resetThread,
+    updateThread = _useContext2.updateThread,
+    deleteThread = _useContext2.deleteThread;
+  var _useThreadAutoScrollF = useThreadAutoScrollFix(),
+    autoScroll = _useThreadAutoScrollF.autoScroll,
+    handleScroll = _useThreadAutoScrollF.handleScroll;
+  var _useState = useState(false),
+    _useState2 = _slicedToArray(_useState, 2),
+    popoverActive = _useState2[0],
+    setPopoverActive = _useState2[1];
+  var togglePopoverActive = useCallback(function () {
+    return setPopoverActive(function (popoverActive) {
+      return !popoverActive;
+    });
+  }, []);
+  var activator = /*#__PURE__*/React.createElement(Box, {
+    width: "fit-content"
+  }, /*#__PURE__*/React.createElement(Button, {
+    onClick: togglePopoverActive,
+    disclosure: true,
+    variant: "monochromePlain"
+  }, /*#__PURE__*/React.createElement(Box, {
+    width: "fit-content",
+    minWidth: "60px"
+  }, /*#__PURE__*/React.createElement(Text, {
+    truncate: true
+  }, thread && "title" in thread ? thread.title : "New chat"))));
+  var assistantComponents = useMemo(function () {
+    return {
+      Text: AssistantText,
+      ToolFallback: function ToolFallback(props) {
+        return /*#__PURE__*/React.createElement(AssistantTool, _extends({
+          shop: shop
+        }, props));
+      }
+    };
+  }, [shop]);
+  return /*#__PURE__*/React.createElement("div", {
+    className: "AOV-Sidekick__Container"
+  }, /*#__PURE__*/React.createElement(Box, {
+    paddingBlockStart: "300",
+    paddingBlockEnd: "200",
+    paddingInlineStart: "200",
+    paddingInlineEnd: "300"
+  }, /*#__PURE__*/React.createElement(InlineStack, {
+    align: "space-between",
+    blockAlign: "center",
+    gap: "100",
+    wrap: false
+  }, loadingThreads ? /*#__PURE__*/React.createElement(Spinner, {
+    size: "small"
+  }) : /*#__PURE__*/React.createElement(Box, {
+    width: "calc(100% - 120px)"
+  }, /*#__PURE__*/React.createElement(Popover, {
+    active: popoverActive,
+    activator: activator,
+    onClose: togglePopoverActive,
+    preferredAlignment: "start"
+  }, /*#__PURE__*/React.createElement(ListChat, {
+    threads: threads,
+    setThread: function setThread(thread) {
+      _setThread(thread);
+      togglePopoverActive();
+      if ("id" in thread) {
+        getThread(thread.id);
+      }
+    },
+    updateThread: updateThread,
+    deleteThread: deleteThread
+  }))), /*#__PURE__*/React.createElement(Box, {
+    minWidth: "45px"
+  }, /*#__PURE__*/React.createElement(InlineStack, {
+    wrap: false,
+    blockAlign: "center",
+    gap: "100"
+  }, /*#__PURE__*/React.createElement(Button, {
+    icon: ComposeIcon,
+    variant: "monochromePlain",
+    onClick: function onClick() {
+      _setThread({});
+      resetThread();
+    }
+  }), /*#__PURE__*/React.createElement(Button, {
+    icon: XIcon,
+    variant: "monochromePlain",
+    onClick: onClose
+  }))))), /*#__PURE__*/React.createElement(Thread.Root, {
+    config: {
+      welcome: {
+        message: "Hi! I'm Mavi, AOV Free Gift Assistant. I'm here to help you."
+      },
+      assistantAvatar: {
+        src: Avatar,
+        alt: "Mavi"
+      },
+      assistantMessage: {
+        allowEdit: false,
+        components: assistantComponents
+      },
+      userMessage: {
+        allowEdit: false
+      }
+    }
+  }, /*#__PURE__*/React.createElement(Thread.Viewport, {
+    autoScroll: autoScroll,
+    onScroll: handleScroll
+  }, loadingMessages ? /*#__PURE__*/React.createElement("div", {
+    className: "AOV-Sidekick__Loading"
+  }, /*#__PURE__*/React.createElement(Spinner, {
+    size: "small"
+  })) : /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement(ThreadWelcome.Root, null, /*#__PURE__*/React.createElement(ThreadWelcome.Center, null, /*#__PURE__*/React.createElement(ThreadWelcome.Avatar, {
+    size: "large"
+  }), /*#__PURE__*/React.createElement(ThreadWelcome.Message, null)), /*#__PURE__*/React.createElement("div", {
+    className: "aui-thread-welcome-suggestion-container"
+  }, welcomeSuggestions(appName).map(function (prompt, index) {
+    return /*#__PURE__*/React.createElement(ThreadWelcome.Suggestion, {
+      key: index,
+      suggestion: {
+        prompt: prompt
+      }
+    });
+  }))), /*#__PURE__*/React.createElement(Thread.Messages, null))), /*#__PURE__*/React.createElement(Thread.ViewportFooter, null, /*#__PURE__*/React.createElement(Suggestions, null), /*#__PURE__*/React.createElement(Composer.Root, null, /*#__PURE__*/React.createElement(Composer.Input, {
+    autoFocus: true,
+    placeholder: "Ask anything ..."
+  }), /*#__PURE__*/React.createElement(Composer.Action, null)))));
+};
+AssistantWidget.propTypes = {
+  onClose: PropTypes.func.isRequired
+};
+export default AssistantWidget;