@seeka-labs/cli-apps 3.7.0 → 3.8.2

package/dist/ai-context/internal/examples/_index.md

@@ -0,0 +1,240 @@
+# Seeka Example Apps Index
+
+This index provides an overview of all available example apps that can be used as references when building Seeka apps.
+
+## Summary
+
+- **Total Examples**: 19
+- **Template Versions**: V3, V2, V1
+- **Last Updated**: 2026-01-16
+
+## Quick Reference by Category
+
+### By Template Type
+- **azurefunc**: google-ads, calendly, clarity, google-bigquery, klaviyo-events, navitas, trustarc, typeform, webhook, yeastar, activecampaign, complianz, ivvy, nowbookit, tradable-bits, transcend, sevenrooms, me-and-u-connect, me-and-u-manage
+
+### By Component
+- **browser**: google-ads, calendly, clarity, navitas, trustarc, typeform
+- **ui**: google-ads, calendly, typeform, webhook, yeastar
+- **server**: google-ads, calendly, clarity, google-bigquery, klaviyo-events, navitas, trustarc, typeform, webhook, yeastar, activecampaign, complianz, ivvy, nowbookit, tradable-bits, transcend, sevenrooms, me-and-u-connect, me-and-u-manage
+
+### By Tag
+- **CRM**: calendly, klaviyo-events, navitas, yeastar, activecampaign, sevenrooms
+- **hospitality**: ivvy, nowbookit, sevenrooms, me-and-u-connect, me-and-u-manage
+- **restaurants**: nowbookit, sevenrooms, me-and-u-connect, me-and-u-manage
+- **webhooks**: calendly, typeform, webhook
+- **browser plugin**: clarity, navitas, trustarc
+- **privacy**: trustarc, complianz, transcend
+- **consent management**: trustarc, complianz, transcend
+- **analytics**: clarity, google-bigquery
+- **data export**: google-bigquery, webhook
+- **email marketing**: klaviyo-events, activecampaign
+- **events**: klaviyo-events, ivvy
+- **marketing automation**: klaviyo-events, activecampaign
+- **GDPR**: trustarc, complianz
+- **compliance**: complianz, transcend
+- **venue management**: ivvy, me-and-u-manage
+
+---
+
+## Examples by Template Version
+
+### Template V3
+
+*1 example(s) available*
+
+#### google-ads
+
+- **Template**: azurefunc
+- **Components**: browser, ui, server
+- **Description**: Google Ads conversion tracking and offline conversion import app. Receives activity data from Seeka and pushes conversions to Google Ads via the Google Ads API.
+- **Tags**: conversion API, advertising, Google Ads, offline conversions
+- **Path**: `./v3/google-ads/`
+- **AI Summary**: `./v3/google-ads/_ai-summary.md`
+
+
+### Template V2
+
+*9 example(s) available*
+
+#### calendly
+
+- **Template**: azurefunc
+- **Components**: browser, ui, server
+- **Description**: Calendly integration app for tracking meeting bookings and scheduling events from Calendly.
+- **Tags**: scheduling, meetings, webhooks, CRM
+- **Path**: `./v2/calendly/`
+- **AI Summary**: `./v2/calendly/_ai-summary.md`
+
+#### clarity
+
+- **Template**: azurefunc
+- **Components**: browser, server
+- **Description**: Microsoft Clarity integration for session recording and heatmap analytics.
+- **Tags**: analytics, session recording, heatmaps, browser plugin
+- **Path**: `./v2/clarity/`
+- **AI Summary**: `./v2/clarity/_ai-summary.md`
+
+#### google-bigquery
+
+- **Template**: azurefunc
+- **Components**: server
+- **Description**: Google BigQuery integration for exporting Seeka activity data to BigQuery for advanced analytics and reporting.
+- **Tags**: data warehouse, analytics, BigQuery, data export
+- **Path**: `./v2/google-bigquery/`
+- **AI Summary**: `./v2/google-bigquery/_ai-summary.md`
+
+#### klaviyo-events
+
+- **Template**: azurefunc
+- **Components**: server
+- **Description**: Klaviyo integration for pushing activity events to Klaviyo for email marketing automation.
+- **Tags**: email marketing, CRM, events, marketing automation
+- **Path**: `./v2/klaviyo-events/`
+- **AI Summary**: `./v2/klaviyo-events/_ai-summary.md`
+
+#### navitas
+
+- **Template**: azurefunc
+- **Components**: browser, server
+- **Description**: Navitas education group integration for tracking student inquiries and conversions.
+- **Tags**: education, lead tracking, CRM, browser plugin
+- **Path**: `./v2/navitas/`
+- **AI Summary**: `./v2/navitas/_ai-summary.md`
+
+#### trustarc
+
+- **Template**: azurefunc
+- **Components**: browser, server
+- **Description**: TrustArc consent management integration for privacy compliance and consent tracking.
+- **Tags**: privacy, consent management, GDPR, browser plugin
+- **Path**: `./v2/trustarc/`
+- **AI Summary**: `./v2/trustarc/_ai-summary.md`
+
+#### typeform
+
+- **Template**: azurefunc
+- **Components**: browser, ui, server
+- **Description**: Typeform integration for tracking form submissions and survey responses.
+- **Tags**: forms, surveys, webhooks, lead capture
+- **Path**: `./v2/typeform/`
+- **AI Summary**: `./v2/typeform/_ai-summary.md`
+
+#### webhook
+
+- **Template**: azurefunc
+- **Components**: ui, server
+- **Description**: Generic webhook app for sending Seeka activity data to custom webhook endpoints.
+- **Tags**: webhooks, integration, custom endpoints, data export
+- **Path**: `./v2/webhook/`
+- **AI Summary**: `./v2/webhook/_ai-summary.md`
+
+#### yeastar
+
+- **Template**: azurefunc
+- **Components**: ui, server
+- **Description**: Yeastar PBX integration for tracking phone calls and call events.
+- **Tags**: telephony, call tracking, PBX, CRM
+- **Path**: `./v2/yeastar/`
+- **AI Summary**: `./v2/yeastar/_ai-summary.md`
+
+
+### Template V1
+
+*9 example(s) available*
+
+#### activecampaign
+
+- **Template**: azurefunc
+- **Components**: server
+- **Description**: ActiveCampaign CRM integration for syncing contacts and activity data.
+- **Tags**: CRM, email marketing, marketing automation, contacts
+- **Path**: `./v1/activecampaign/`
+- **AI Summary**: `./v1/activecampaign/_ai-summary.md`
+
+#### complianz
+
+- **Template**: azurefunc
+- **Components**: server
+- **Description**: Complianz consent management integration for GDPR and privacy compliance.
+- **Tags**: privacy, consent management, GDPR, compliance
+- **Path**: `./v1/complianz/`
+- **AI Summary**: `./v1/complianz/_ai-summary.md`
+
+#### ivvy
+
+- **Template**: azurefunc
+- **Components**: server
+- **Description**: iVvy venue management integration for tracking event bookings and inquiries.
+- **Tags**: events, venue management, bookings, hospitality
+- **Path**: `./v1/ivvy/`
+- **AI Summary**: `./v1/ivvy/_ai-summary.md`
+
+#### nowbookit
+
+- **Template**: azurefunc
+- **Components**: server
+- **Description**: Now Book It restaurant reservation integration for tracking bookings.
+- **Tags**: hospitality, reservations, restaurants, bookings
+- **Path**: `./v1/nowbookit/`
+- **AI Summary**: `./v1/nowbookit/_ai-summary.md`
+
+#### tradable-bits
+
+- **Template**: azurefunc
+- **Components**: server
+- **Description**: Tradable Bits fan engagement platform integration for entertainment and sports.
+- **Tags**: entertainment, fan engagement, sports, marketing
+- **Path**: `./v1/tradable-bits/`
+- **AI Summary**: `./v1/tradable-bits/_ai-summary.md`
+
+#### transcend
+
+- **Template**: azurefunc
+- **Components**: server
+- **Description**: Transcend data privacy platform integration for consent and data rights management.
+- **Tags**: privacy, consent management, data rights, compliance
+- **Path**: `./v1/transcend/`
+- **AI Summary**: `./v1/transcend/_ai-summary.md`
+
+#### sevenrooms
+
+- **Template**: azurefunc
+- **Components**: server
+- **Description**: SevenRooms hospitality CRM integration for restaurant reservations and guest management.
+- **Tags**: hospitality, CRM, reservations, restaurants
+- **Path**: `./v1/sevenrooms/`
+- **AI Summary**: `./v1/sevenrooms/_ai-summary.md`
+
+#### me-and-u-connect
+
+- **Template**: azurefunc
+- **Components**: server
+- **Description**: Me&u Connect integration for mobile ordering and payment tracking in hospitality.
+- **Tags**: hospitality, mobile ordering, payments, restaurants
+- **Path**: `./v1/me-and-u-connect/`
+- **AI Summary**: `./v1/me-and-u-connect/_ai-summary.md`
+
+#### me-and-u-manage
+
+- **Template**: azurefunc
+- **Components**: server
+- **Description**: Me&u Manage integration for venue management and order tracking.
+- **Tags**: hospitality, venue management, orders, restaurants
+- **Path**: `./v1/me-and-u-manage/`
+- **AI Summary**: `./v1/me-and-u-manage/_ai-summary.md`
+
+---
+
+## How to Use These Examples
+
+1. **Find a relevant example** using the categories above or by searching for specific tags.
+2. **Review the AI summary** (`_ai-summary.md`) in each example folder for a quick overview.
+3. **Examine the source code** to understand implementation patterns.
+4. **Copy and adapt** patterns that match your use case.
+
+### Recommended Starting Points
+
+- **New to Seeka Apps?** Start with a V3 template example like `google-ads`.
+- **Building a browser plugin?** Look at examples with the `browser` component.
+- **Integrating with external APIs?** Check examples tagged with `conversion API` or `webhooks`.

package/dist/ai-context/internal/examples/v1/_index.md

@@ -0,0 +1,53 @@
+# V1 Example Apps
+
+> **⚠️ Legacy Version**: V1 apps use an older structure. Reference these for feature implementation patterns, but use V3 structure for new apps.
+
+## Overview
+
+V1 example apps demonstrate feature implementations using the original Seeka app template structure.
+
+## Available Examples
+
+
+### activecampaign
+- **Template**: azurefunc
+- **Components**: server
+- **Description**: ActiveCampaign CRM integration for syncing contacts and activity data.
+- **Tags**: CRM, email marketing, marketing automation, contacts
+- **Path**: `./activecampaign/`
+
+
+<!-- Example entries will be added here by the import script:
+
+### google-ads-v1
+- **Template**: azurefunc
+- **Components**: server
+- **Description**: Google Ads conversion tracking integration
+- **Tags**: conversion-api, ads-platform
+- **Path**: `./google-ads-v1/`
+
+-->
+
+## When to Reference V1 Apps
+
+V1 apps are useful for understanding:
+
+- **Legacy integration patterns**: How older integrations were built
+- **Data transformation logic**: Business logic that may still be relevant
+- **External API patterns**: API integration approaches
+
+## Adapting V1 Code to V3
+
+When using V1 code as reference:
+
+1. Update to Azure Functions V4 programming model
+2. Move shared types to `app/lib/src/models/`
+3. Use SDK utilities from `@seeka-labs/sdk-apps-server-host`
+4. Add structured logging with Winston
+
+See `../../architecture/v1-structure.md` for detailed migration guidance.
+
+## See Also
+
+- `../v3/` - Current template examples (use for new apps)
+- `../../architecture/v1-structure.md` - V1 structure documentation

package/dist/ai-context/internal/examples/v1/activecampaign/.eslintrc.cjs

@@ -0,0 +1,10 @@
+/* eslint-env node */
+module.exports = {
+    extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
+    parser: '@typescript-eslint/parser',
+    plugins: ['@typescript-eslint'],
+    root: true,
+    rules: {
+        "@typescript-eslint/no-unused-vars": "warn"
+    }
+};

package/dist/ai-context/internal/examples/v1/activecampaign/README.md

@@ -0,0 +1,88 @@
+# Seeka app example - Azure functions
+
+## Development
+
+- See [Configure your environment](https://learn.microsoft.com/en-us/azure/azure-functions/create-first-function-vs-code-typescript?pivots=nodejs-model-v4#configure-your-environment) for dependencies
+- For emulating Azure storage queues, blobs and tables: `docker run --name azurite -p 10000:10000 -p 10001:10001 -p 10002:10002 --detach mcr.microsoft.com/azure-storage/azurite`
+- Set `AzureWebJobsStorage` setting in local.settings.json to `UseDevelopmentStorage=true`
+    - If not using WSL: 
+    `UseDevelopmentStorage=true`
+    - If using WSL: Ensure to replace DAN-LAPTOP with your hostname. Below connection string allows running Azurite on your host machine and lets WSL connect to it
+    `DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://DAN-LAPTOP.local:10000/devstoreaccount1;QueueEndpoint=http://DAN-LAPTOP.local:10001/devstoreaccount1;TableEndpoint=http://DAN-LAPTOP.local:10002/devstoreaccount1;`
+- Install Azure Storage explorer and create your queues (see `./src/lib/jobs/index.ts` for `queueNames`). Azure Storage explorer can be used to view your queue items.
+- `yarn install`
+- `yarn start`
+
+### Debugging
+Supports VSCode debugging via the debugger and utilisation of breakpoints. 
+This is only tested on Linux but may work on Windows. 
+If using Windows then use WSL with an Ubuntu distro for support of attaching the VS code debugger
+
+#### Live urls
+You can expose your app locally to the internet via Ngrok to test your app before deploying.
+
+##### Setup
+1. Sign up for a Ngrok account
+2. Get your auth token
+3. `yarn ngrok config add-authtoken [auth token here]` replacing `[auth token]` with the auth token retrieved from your Ngrok dashboard
+
+##### Running
+1. `yarn start` OR start debugging in VSCode
+2. In separate terminal window run `yarn tunnel` and observe the log entry that starts with `Live url exposed` for your Seeka app webhook URL that you can place in your Seeka app configuration.
+
+#### Invoking functions
+##### Development environment
+Scheduled / timer function: `curl -i -d '{"input": null}' -H "Content-Type: application/json" -X POST http://localhost:7072/admin/functions/pollingExample`
+
+##### Azure cloud
+Scheduled / timer function: `curl -i -d '{"input": null}' -H "Content-Type: application/json" -H "x-functions-key: <key from azure portal>" -X POST https://seeka-app-activecampaign.azurewebsites.net/admin/functions/pollingExample`
+
+See [this doc](https://learn.microsoft.com/en-us/azure/azure-functions/functions-manually-run-non-http?tabs=azure-portal#get-the-master-key) on how to get the functions (master) key
+
+#### Sample functions
+##### Seeka app webhook 
+`src/functions/seekaAppWebhook.ts`
+TODO
+
+##### Queue example 
+`src/functions/queueExample.ts`
+TODO
+
+##### Polling example 
+`src/functions/pollingExample.ts`
+TODO
+
+### Logging
+
+Winston included - TODO
+Seq included - TODO
+
+## Deployment
+This project comes ready to deploy for free to Azure functions with database backed by Redis hosted by Upstash and queues, blobs and tables backed by Azure Storage.
+
+### Gitlab
+TODO
+
+### Azure Function deploy
+1. Create Azure function app via the portal with below settings
+    - Function app name: seeka-app-activecampaign
+    - Code or container image: Code
+    - Runtime stack: Node.js
+    - Version: 18 LTS
+    - Region: Closest region to where your upstash "master / write" database is located
+    - Operating system: linux
+    - Hosting: Consumption
+    - Enable public access: On
+2. Set environment variables of the Azure web app - reference local.settings.json "Values" 
+2. `yarn deploy`
+
+## State management
+Installations and other state is stored in Redis. Another state provider can be used, see `src/lib/state/seeka/installations.ts` for the file that manages the state of the installations.
+
+### Upstash (optional)
+If you dont want to use Upstash for Redis then swap out the connection strings with your Redis instance. 
+- When choosing region - use US East (Ohio) - us-east-* as this is the same Azure region that the Azure functions run from
+
+## References
+- https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite
+- https://learn.microsoft.com/en-us/azure/storage/queues/storage-quickstart-queues-nodejs?tabs=connection-string%2Croles-azure-portal%2Cenvironment-variable-windows%2Csign-in-azure-cli

package/dist/ai-context/internal/examples/v1/activecampaign/_ai-summary.md

@@ -0,0 +1,43 @@
+# AI Summary for Seeka App: ActiveCampaign
+
+## Overview
+The Seeka app "activecampaign" is designed to integrate with ActiveCampaign CRM for syncing contacts and activity data. It leverages Azure Functions to handle webhooks and manage state with Redis, providing a seamless connection between Seeka and ActiveCampaign.
+
+## Purpose and Functionality
+- **Integration with ActiveCampaign CRM:** The app syncs contact and activity data between Seeka and ActiveCampaign.
+- **Webhook Handling:** Processes various webhook events such as app installation, uninstallation, and activity acceptance.
+- **State Management:** Uses Redis to manage installation states and other necessary data.
+
+## Key Implementation Patterns
+- **Azure Functions:** Utilized for serverless execution of webhook handlers and health checks.
+- **TypeScript:** The app is built using TypeScript, providing type safety and modern JavaScript features.
+- **Winston Logging:** Integrated for logging and debugging purposes, with support for Seq logging.
+
+## External APIs/Services Integrated
+- **ActiveCampaign API:** For managing contacts and pipelines within the ActiveCampaign CRM.
+- **Azure Storage:** Used for queue management and other storage needs.
+- **Redis via Upstash:** For state management and caching.
+- **Ngrok:** Allows local development by exposing the app to the internet for testing.
+
+## Important Data Transformations
+- **Contact and Activity Data:** Transforms Seeka identity data to ActiveCampaign contact format using utility functions.
+- **Webhook Payloads:** Parses and validates incoming webhook payloads to ensure they are processed correctly.
+
+## Notable Code Patterns
+- **Webhook Signature Validation:** Ensures security by validating webhook signatures before processing.
+- **Service Initialization:** Uses a `startServices` function to initialize necessary services before handling webhooks.
+- **Error Handling:** Implements try-catch blocks to handle errors gracefully and log them using Winston.
+- **State Management with Redis:** Provides a reusable pattern for managing application state in a distributed environment.
+
+## Deployment and Development
+- **Azure Functions Deployment:** The app is configured for deployment to Azure Functions, supporting both local and cloud environments.
+- **Local Development with Docker:** Uses Azurite for local emulation of Azure Storage services.
+- **VSCode Debugging:** Supports debugging with breakpoints, primarily tested on Linux with WSL support for Windows.
+
+## References
+- [Azure Functions Documentation](https://learn.microsoft.com/en-us/azure/azure-functions/)
+- [ActiveCampaign API Documentation](https://developers.activecampaign.com/)
+- [Ngrok Documentation](https://ngrok.com/docs)
+- [Redis with Upstash](https://upstash.com/)
+
+This summary provides an AI-friendly overview of the Seeka app's architecture, key features, and integration points, facilitating better understanding and interaction with the app's implementation.

package/dist/ai-context/internal/examples/v1/activecampaign/host.json

@@ -0,0 +1,20 @@
+{
+  "version": "2.0",
+  "logging": {
+    "applicationInsights": {
+      "samplingSettings": {
+        "isEnabled": true,
+        "excludedTypes": "Request"
+      }
+    }
+  },
+  "functionTimeout": "00:10:00",
+  "extensionBundle": {
+    "id": "Microsoft.Azure.Functions.ExtensionBundle",
+    "version": "[4.*, 5.0.0)"
+  },
+  "concurrency": {
+    "dynamicConcurrencyEnabled": true,
+    "snapshotPersistenceEnabled": true
+  }
+}

package/dist/ai-context/internal/examples/v1/activecampaign/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "seeka-app-activecampaign",
+  "version": "1.0.1",
+  "description": "Seeka app seeka-app-activecampaign",
+  "author": "Seeka company <support@seeka.co>",
+  "license": "MIT",
+  "main": "dist/src/functions/*.js",
+  "private": true,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "lint": "eslint",
+    "build": "tsc",
+    "watch": "tsc -w",
+    "clean": "yarn rimraf dist",
+    "prestart": "yarn clean && yarn build",
+    "start": "func start --port 7072",
+    "tunnel": "node scripts/ngrok.js seeka-app-activecampaign-localdev",
+    "deploy": "yarn clean && yarn build && func azure functionapp publish seeka-app-activecampaign --no-build --javascript"
+  },
+  "dependencies": {
+    "@azure/functions": "^4.6.0",
+    "@azure/storage-queue": "^12.25.0",
+    "@datalust/winston-seq": "^2.0.0",
+    "@seeka-labs/sdk-apps-server": "^1.1.26",
+    "axios": "^1.7.9",
+    "lodash": "^4.17.21",
+    "redis": "^4.7.0",
+    "winston": "^3.17.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/lodash": "^4.17.14",
+    "@typescript-eslint/eslint-plugin": "^8.20.0",
+    "@typescript-eslint/parser": "^8.20.0",
+    "azure-functions-core-tools": "^4.x",
+    "eslint": "^9",
+    "ngrok": "^5.0.0-beta.2",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.7.3"
+  }
+}

package/dist/ai-context/internal/examples/v1/activecampaign/src/functions/healthCheck.ts

@@ -0,0 +1,14 @@
+import { app, HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';
+
+app.http('healthCheck', {
+    methods: ['GET', 'HEAD'],
+    authLevel: 'anonymous',
+    route: 'health',
+    handler: healthCheck
+});
+
+export async function healthCheck(req: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
+    return {
+        status: 200
+    }
+}