{"id":29720323,"url":"https://github.com/sankaiai/iheard.ai","last_synced_at":"2026-05-18T03:33:18.870Z","repository":{"id":304600996,"uuid":"1019268392","full_name":"SankaiAI/iHeard.ai","owner":"SankaiAI","description":"A free AI Sales Agent Chatbot designed for Shopify stores","archived":false,"fork":false,"pushed_at":"2025-07-21T17:57:21.000Z","size":683,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-21T19:38:39.198Z","etag":null,"topics":["ai","chatbot","shopify-app"],"latest_commit_sha":null,"homepage":"https://i-heard-ai.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SankaiAI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-14T04:29:17.000Z","updated_at":"2025-07-21T03:50:12.000Z","dependencies_parsed_at":"2025-07-14T07:38:44.624Z","dependency_job_id":"a34b848f-7739-47fd-bbd6-6dc4f2241ac8","html_url":"https://github.com/SankaiAI/iHeard.ai","commit_stats":null,"previous_names":["sankaiai/iheard.ai","sankaiai/ihear.ai"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/SankaiAI/iHeard.ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SankaiAI%2FiHeard.ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SankaiAI%2FiHeard.ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SankaiAI%2FiHeard.ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SankaiAI%2FiHeard.ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SankaiAI","download_url":"https://codeload.github.com/SankaiAI/iHeard.ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SankaiAI%2FiHeard.ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274231260,"owners_count":25245659,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","chatbot","shopify-app"],"created_at":"2025-07-24T13:11:18.061Z","updated_at":"2026-05-18T03:33:17.377Z","avatar_url":"https://github.com/SankaiAI.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"public/High-Resolution-Color-Logo-Blue-on-Transparent-Background.png\" alt=\"iHeard.ai Logo\" width=\"300\"\u003e\n\u003c/div\u003e\n\n# 🤖 iHeard.ai - AI Sales Assistant for Shopify\n\nAn intelligent AI-powered sales assistant widget for Shopify stores that helps customers find products, answer questions, and provide personalized recommendations.\n\n## 📋 Features\n\n- **🎯 Smart Product Recommendations** - AI-powered product suggestions based on customer queries\n- **💬 Real-time Chat Interface** - Floating chat widget with customizable positioning\n- **🎨 Fully Customizable** - Admin panel to configure colors, text, position, and behavior\n- **📱 Mobile Responsive** - Optimized for all device sizes\n- **🔌 N8N Integration** - Optional integration with N8N workflows for advanced AI processing\n- **⚡ Real-time Updates** - Settings changes reflect immediately on the storefront\n- **🛡️ Secure** - Built with Shopify's security best practices\n\n## 🏗️ Architecture\n\n- **Frontend**: Remix with TypeScript and Shopify Polaris UI\n- **Backend**: Node.js with Prisma ORM and SQLite database\n- **Theme Extension**: Liquid template with vanilla JavaScript\n- **AI Integration**: N8N webhooks with fallback processing\n- **Authentication**: Shopify OAuth with session management\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js 18+ and npm\n- Shopify Partner account\n- Shopify CLI 3.0+\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/SankaiAI/iheard.ai.git\n   cd iheard.ai\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Set up environment variables**\n   ```bash\n   cp .env.example .env\n   # Edit .env with your Shopify app credentials\n   ```\n   \n   **Required values for `.env`:**\n   - `SHOPIFY_API_KEY`: Get from Shopify Partner Dashboard \u003e Apps \u003e [Your App] \u003e App setup (Client ID)\n   - `SHOPIFY_SALES_ASSISTANT_WIDGET_ID`: Generate a UUID at [uuidgenerator.net](https://www.uuidgenerator.net/)\n   \n   **Optional N8N Integration:**\n   - `N8N_WEBHOOK_URL`: Your N8N webhook URL for AI processing\n   - `N8N_API_KEY`: N8N API key (if authentication required)\n   \n   See `SETUP.md` for detailed instructions on obtaining these values.\n   See `N8N_SETUP.md` for complete N8N workflow setup.\n\n4. **Configure Shopify app**\n   ```bash\n   cp shopify.app.example.toml shopify.app.toml\n   # Edit shopify.app.toml with your app details\n   ```\n\n5. **Set up the database**\n   ```bash\n   npx prisma generate\n   npx prisma migrate dev\n   ```\n\n6. **Start development server**\n   ```bash\n   shopify app dev\n   ```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\nCreate a `.env` file with the following variables:\n\n```env\nSHOPIFY_API_KEY=your_shopify_api_key_here\nSHOPIFY_SALES_ASSISTANT_WIDGET_ID=your_widget_id_here\n```\n\n### Shopify App Configuration\n\nUpdate `shopify.app.toml` with your app details:\n\n```toml\nclient_id = \"your_shopify_app_client_id\"\nname = \"ihear.ai\"\napplication_url = \"https://your-tunnel-url.trycloudflare.com\"\n```\n\n## 📁 Project Structure\n\n```\nihear-ai/\n├── app/                          # Remix application\n│   ├── routes/                   # App routes\n│   │   ├── app.settings.tsx      # Admin settings page\n│   │   ├── api.widget-settings.tsx # Widget settings API\n│   │   └── apps.sales-assistant-api.tsx # AI chat API\n│   ├── db.server.ts              # Database connection\n│   └── shopify.server.ts         # Shopify authentication\n├── extensions/                   # Shopify theme extensions\n│   └── sales-assistant-widget/   # AI widget extension\n│       ├── blocks/               # Theme blocks\n│       │   └── ai_sales_assistant.liquid # Main widget\n│       ├── assets/               # Static assets\n│       ├── locales/              # Translations\n│       └── snippets/             # Reusable snippets\n├── prisma/                       # Database schema and migrations\n│   ├── schema.prisma             # Database schema\n│   └── migrations/               # Database migrations\n└── services/                     # External services\n    └── n8n.service.ts            # N8N integration\n```\n\n## 🎛️ Admin Panel Features\n\n### Widget Configuration\n- **Enable/Disable** - Toggle widget on/off across the store\n- **Position Settings** - 6 positioning options (corners and center sides)\n- **Customization** - Button text, chat title, welcome message, placeholder text\n- **Color Picker** - Fully functional color customization\n- **Live Preview** - See changes in real-time\n\n### AI Workflow Configuration\n- **Default Workflow** - Use the developer's pre-configured AI assistant with product recommendations\n- **Custom N8N Workflow** - Configure your own N8N webhook URL for custom AI processing\n- **Dynamic Switching** - Easily switch between default and custom workflows\n- **Fallback Protection** - Automatic fallback to local processing if webhooks fail\n\n### Settings Auto-Sync\n- Changes in admin panel update the storefront within 5 seconds\n- Database persistence ensures settings survive server restarts\n- Fallback to default settings if API is unavailable\n\n## 🔧 Development\n\n### Database Management\n\n```bash\n# Generate Prisma client\nnpx prisma generate\n\n# Create and apply migrations\nnpx prisma migrate dev --name description\n\n# Reset database (development only)\nnpx prisma migrate reset\n\n# View database in browser\nnpx prisma studio\n```\n\n### Local Development Workflow\n\n⚠️ **Important for Local Development**: Every time you restart `shopify app dev`, you must update the **App Proxy URL** in your Shopify Partner Dashboard because the tunnel URL changes.\n\n**Quick Steps:**\n1. Check your new tunnel URL in `shopify.app.toml` → `application_url`\n2. Update the proxy URL in Partner Dashboard → Apps → [Your App] → App setup → App proxy\n3. Set proxy URL to: `https://NEW-TUNNEL-URL.trycloudflare.com/api/widget-settings`\n\n**Why this matters:**\n- The widget needs to fetch settings from your app's API\n- Tunnel URLs change on each restart for security\n- Without updating the proxy URL, you'll get \"Failed to fetch\" errors\n\nSee `SETUP.md` for detailed instructions on app proxy configuration.\n\n### Theme Extension Development\n\nThe widget is built as a Shopify theme extension block that can be added to any theme template. It automatically:\n\n- Fetches configuration from the admin panel\n- Applies custom styling and positioning\n- Handles real-time chat interactions\n- Integrates with the AI backend\n\n### API Endpoints\n\n- `GET /api/widget-settings` - Fetch widget configuration\n- `POST /apps/sales-assistant-api` - Process AI chat messages\n\n## 🤖 AI Integration\n\n### Two Workflow Options\n\n**1. Default Developer Workflow**\n- Pre-configured AI assistant with product recommendations\n- Works out-of-the-box with no additional setup\n- Integrated with your store's product catalog\n- Handles common customer queries automatically\n\n**2. Custom N8N Workflow**\n- Configure your own N8N webhook URL through the admin panel\n- Advanced AI processing with full customization\n- Integrate with external AI services (OpenAI, Claude, etc.)\n- Custom business logic and integrations\n\n### Configuration\n\n**Admin Panel Configuration:**\n1. Go to **App Settings** → **AI Workflow Configuration**\n2. Choose between \"Use Developer's Default Workflow\" or \"Use My Custom N8N Workflow\"\n3. If using custom: Enter your N8N webhook URL (must be HTTPS)\n4. Save settings - changes take effect immediately\n\n**Environment Configuration (Optional):**\n- Set `N8N_WEBHOOK_URL` in `.env` for a global default\n- Individual stores can override this with their own webhook URLs\n- Supports both shared and per-store N8N configurations\n\n### Fallback Processing\n\nThe app provides robust fallback protection:\n- If custom webhook fails → Falls back to local processing\n- If network issues occur → Provides helpful default responses\n- Ensures chat widget always works regardless of external dependencies\n\n## 🚀 Deployment\n\n### Development Deployment\n\nThe app runs in development mode with Shopify CLI:\n\n```bash\nshopify app dev\n```\n\n### Production Deployment\n\nFor production deployment, you'll need to:\n\n1. Set up a production server (Railway, Heroku, etc.)\n2. Configure production environment variables\n3. Set up a production database\n4. Deploy using Shopify CLI\n\n```bash\nshopify app deploy\n```\n\n## 🔒 Security Considerations\n\n- **API Keys**: Never commit `.env` or `shopify.app.toml` files\n- **Database**: SQLite is suitable for development; use PostgreSQL for production\n- **CORS**: Widget API includes proper CORS headers for cross-origin requests\n- **Authentication**: All admin routes require Shopify OAuth authentication\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🆘 Support\n\n- **Documentation**: [Shopify App Development](https://shopify.dev/docs/apps)\n- **Issues**: Open an issue on GitHub\n- **Discussions**: Use GitHub Discussions for questions and ideas\n\n## 🙏 Acknowledgments\n\n- Built with [Shopify CLI](https://shopify.dev/docs/apps/tools/cli)\n- UI components from [Shopify Polaris](https://polaris.shopify.com/)\n- Database ORM by [Prisma](https://www.prisma.io/)\n- Web framework by [Remix](https://remix.run/)\n\n---\n\n**Made with ❤️ for the Shopify ecosystem**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsankaiai%2Fiheard.ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsankaiai%2Fiheard.ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsankaiai%2Fiheard.ai/lists"}