@seeka-labs/cli-apps 3.7.0 → 3.8.2

package/README.md

@@ -0,0 +1,286 @@
+# @seeka-labs/cli-apps
+
+The official Seeka Apps CLI for scaffolding and managing Seeka applications.
+
+## Installation
+
+```bash
+# Using npm
+npm install -g @seeka-labs/cli-apps
+
+# Using yarn
+yarn global add @seeka-labs/cli-apps
+
+# Or run directly with npx
+npx @seeka-labs/cli-apps@latest
+```
+
+## Quick Start
+
+The fastest way to get started is to run the CLI without any arguments to enter **interactive mode**:
+
+```bash
+npx @seeka-labs/cli-apps@latest
+```
+
+This will guide you through the setup process with prompts for all required information.
+
+## Commands
+
+### `init` - Initialize a New Seeka App
+
+Creates a new Seeka app with the specified template and configuration.
+
+#### Usage
+
+```bash
+# Interactive mode (recommended for first-time users)
+npx @seeka-labs/cli-apps@latest
+
+# Using command-line arguments
+npx @seeka-labs/cli-apps@latest init <org> <name> [options]
+
+# Using a configuration file
+npx @seeka-labs/cli-apps@latest init <config-file.json>
+```
+
+#### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `<configFileOrOrg>` | Path to JSON config file, or name of your organization (alphanumeric and hyphens only) |
+| `[name]` | Name of your app (alphanumeric and hyphens only) |
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--template <template>` | App template: `azure-function`, `aws-lambda`, or `netlify-function` |
+| `--developer <developer>` | App developer name or company |
+| `--email <email>` | App developer email |
+| `--outName [outName]` | Directory name of the app (a new directory will be created with this name) |
+| `--outDir [outDir]` | Output directory to create the app in (defaults to current working directory) |
+| `--npmUsername [username]` | Private NPM registry username for browser plugin dependencies |
+| `--npmPassword [password]` | Private NPM registry password for browser plugin dependencies |
+| `--noDependencies` | Skip installing dependencies |
+| `--skipSubDir` | Use sub directory for app files instead of root folder |
+| `--force` | Force creation of app in non-empty directory |
+| `--env [env...]` | Set environment variables (format: `--env KEY1=VALUE1 KEY2=VALUE2`) |
+
+#### Examples
+
+```bash
+# Create a new Azure Function app
+npx @seeka-labs/cli-apps@latest init my-org my-app \
+  --template azure-function \
+  --developer "My Company" \
+  --email "dev@mycompany.com"
+
+# Create app with environment variables
+npx @seeka-labs/cli-apps@latest init my-org my-app \
+  --template azure-function \
+  --developer "My Company" \
+  --email "dev@mycompany.com" \
+  --env "SEEKA_APP_ID=your-app-id" "SEEKA_APP_SECRET=your-secret"
+
+# Create app without installing dependencies
+npx @seeka-labs/cli-apps@latest init my-org my-app \
+  --template azure-function \
+  --developer "My Company" \
+  --email "dev@mycompany.com" \
+  --noDependencies
+
+# Create app from a configuration file
+npx @seeka-labs/cli-apps@latest init ./my-app-config.json
+```
+
+---
+
+### `ai context` - Install AI Context Files
+
+Installs AI context files to help AI assistants understand your Seeka app structure and provide better assistance.
+
+#### Usage
+
+```bash
+# Install AI context to current directory
+npx @seeka-labs/cli-apps@latest ai context
+
+# Install AI context to a specific directory
+npx @seeka-labs/cli-apps@latest ai context --target /path/to/project
+```
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--target <directory>` | Target directory (defaults to current directory) |
+
+#### What It Does
+
+- Downloads the Seeka AI context package
+- Extracts it to `.seeka/ai/context/` in your project
+- Provides documentation, architecture guides, and reference materials for AI assistants
+- Replaces any existing AI context if present
+
+#### Output Structure
+
+```
+.seeka/
+└── ai/
+    └── context/
+        ├── README.md
+        ├── architecture/
+        │   └── overview.md
+        ├── guides/
+        │   ├── getting-started.md
+        │   ├── common-patterns.md
+        │   ├── data-flow.md
+        │   └── testing.md
+        ├── reference/
+        │   ├── cli-commands.md
+        │   ├── config-schema.md
+        │   └── sdk-api.md
+        └── meta.json
+```
+
+---
+
+## Interactive Mode
+
+When you run the CLI without any arguments, it enters interactive mode:
+
+```bash
+npx @seeka-labs/cli-apps@latest
+```
+
+### Available Actions
+
+1. **Initialize a new Seeka app** - Guides you through creating a new app with prompts for:
+   - Organization name
+   - App name
+   - Template selection (azure-function, aws-lambda, netlify-function)
+   - Seeka App ID and Secret
+   - Developer name and email
+   - Output directory options
+   - Dependency installation preferences
+   - NPM registry credentials (for browser plugin)
+   - Additional options (force, skipSubDir)
+
+2. **Install AI context files** - Downloads and installs AI context to help AI assistants understand your project
+
+---
+
+## Configuration File
+
+You can use a JSON configuration file instead of command-line arguments:
+
+```json
+{
+  "orgName": "my-org",
+  "appName": "my-app",
+  "template": "azure-function",
+  "developerName": "My Company",
+  "developerEmail": "dev@mycompany.com",
+  "outputDirectory": "./",
+  "installDependencies": true,
+  "force": false,
+  "skipSubDir": false,
+  "environmentVariables": {
+    "SEEKA_APP_ID": "your-app-id",
+    "SEEKA_APP_SECRET": "your-secret"
+  },
+  "npmUsername": "your-npm-username",
+  "npmPassword": "your-npm-password"
+}
+```
+
+Then run:
+
+```bash
+npx @seeka-labs/cli-apps@latest init ./my-config.json
+```
+
+---
+
+## Templates
+
+### Azure Function (`azure-function`)
+
+Creates a Seeka app designed to run on Azure Functions. Includes:
+- Azure Functions project structure
+- Server-side webhook handlers
+- Local development setup with Azurite
+- GitHub Actions deployment workflow
+- GitLab CI/CD pipeline
+
+### AWS Lambda (`aws-lambda`)
+
+Creates a Seeka app designed to run on AWS Lambda. *(Coming soon)*
+
+### Netlify Function (`netlify-function`)
+
+Creates a Seeka app designed to run on Netlify Functions. *(Coming soon)*
+
+---
+
+## Project Structure
+
+After running `init`, your project will have the following structure:
+
+```
+seeka-app-{name}/
+├── .seeka/
+│   ├── init.app.seeka.cli.config.json    # CLI configuration
+│   ├── init.app.secrets.seeka.cli.config.json  # Environment variables
+│   └── ai/
+│       └── context/                       # AI context files
+├── app/
+│   ├── lib/                               # Shared library code
+│   ├── server/                            # Server-side code (Azure Functions)
+│   ├── browser/                           # Browser plugin code (optional)
+│   └── ui/                                # UI components (optional)
+├── .github/
+│   └── workflows/                         # GitHub Actions workflows
+├── .gitlab-ci.yml                         # GitLab CI/CD pipeline
+├── package.json
+├── .yarnrc.yml
+└── README.md
+```
+
+---
+
+## Environment Variables
+
+The following environment variables are commonly used in Seeka apps:
+
+| Variable | Description |
+|----------|-------------|
+| `SEEKA_APP_ID` | Your Seeka App ID (from https://seeka.app/settings/developer/apps) |
+| `SEEKA_APP_SECRET` | Your Seeka App Secret |
+
+---
+
+## Requirements
+
+- Node.js 18 or later
+- npm, yarn, or pnpm
+
+---
+
+## Related Packages
+
+- [`@seeka-labs/cli-apps-azure`](https://www.npmjs.com/package/@seeka-labs/cli-apps-azure) - Azure-specific CLI for GitHub repository setup and environment management
+
+---
+
+## Support
+
+- [Seeka Developer Documentation](https://developers.seeka.co)
+- [Seeka Platform](https://seeka.app)
+
+---
+
+## License
+
+MIT

package/dist/ai-context/common/README.md

@@ -0,0 +1,110 @@
+# Seeka Apps - AI Context
+
+This directory contains comprehensive context for AI assistants to effectively build and extend Seeka apps.
+
+## Quick Start for AI
+
+When building or extending a Seeka app, follow this reading order:
+
+1. **Architecture Overview** → `architecture/overview.md` - Understand the high-level architecture
+2. **Current Template Structure** → `architecture/v3-structure.md` - Use this for new app implementations
+3. **Getting Started Guide** → `guides/getting-started.md` - How to extend a scaffolded app
+4. **Common Patterns** → `guides/common-patterns.md` - Patterns used across all apps
+5. **Examples** → `examples/` - Reference implementations for specific features
+
+## Directory Structure
+
+```
+ai-context/
+├── README.md                    # This file - entry point for AI
+├── architecture/
+│   ├── overview.md              # High-level Seeka app architecture
+│   ├── v1-structure.md          # V1 app template structure (legacy)
+│   ├── v2-structure.md          # V2 app template structure (legacy)
+│   └── v3-structure.md          # V3 app template structure (current)
+├── guides/
+│   ├── getting-started.md       # How to extend a scaffolded app
+│   ├── common-patterns.md       # Common patterns across apps
+│   ├── data-flow.md             # Data flow from Seeka core to destinations
+│   └── testing.md               # Testing conventions and best practices
+├── reference/
+│   ├── cli-commands.md          # CLI command reference
+│   ├── sdk-api.md               # SDK API documentation
+│   └── config-schema.md         # Configuration file schemas
+└── examples/
+    ├── v1/                      # V1 template example apps
+    │   └── _index.md            # Index of V1 examples
+    ├── v2/                      # V2 template example apps
+    │   └── _index.md            # Index of V2 examples
+    └── v3/                      # V3 template example apps
+        └── _index.md            # Index of V3 examples
+```
+
+## Version Information
+
+Seeka apps have evolved through three major template versions:
+
+| Version | Status | Use Case |
+|---------|--------|----------|
+| V1 | Legacy | Reference only - for feature/functionality patterns |
+| V2 | Legacy | Reference only - for feature/functionality patterns |
+| V3 | Current | Use for all new app implementations |
+
+**Important**: When building new apps, always use the V3 structure. V1 and V2 examples are provided for feature reference only - they demonstrate how specific functionality has been implemented in production apps.
+
+## How to Use This Context
+
+### For New App Development
+1. Start with `architecture/v3-structure.md` to understand the current template
+2. Review `guides/getting-started.md` for extension patterns
+3. Search examples across all versions for similar feature implementations
+
+### For Feature Implementation
+1. Check `examples/` directories for apps with similar functionality
+2. Each example includes an `_ai-summary.md` explaining key patterns
+3. Adapt patterns to V3 structure if referencing V1/V2 examples
+
+### For Debugging/Troubleshooting
+1. Review `guides/common-patterns.md` for expected behaviors
+2. Check `guides/data-flow.md` for data handling patterns
+3. Reference `guides/testing.md` for test strategies
+
+## App Templates
+
+Seeka apps can be scaffolded with different server templates:
+
+- **azurefunc** - Azure Functions (most common)
+- **netlifyfunc** - Netlify Functions
+- **awslambda** - AWS Lambda
+
+## App Components
+
+Apps may include one or more components:
+
+- **server** - Backend API and webhook handlers
+- **browser** - Browser plugin/extension
+- **ui** - User interface for app configuration
+
+## Tags Reference
+
+Example apps are tagged for easy discovery:
+
+- `conversion-api` - Conversion API integrations
+- `crm` - CRM platform integrations
+- `telemetry` - Analytics and telemetry
+- `ads-platform` - Advertising platform integrations
+- `data-sync` - Data synchronization patterns
+- `webhook` - Webhook handling patterns
+
+## Meta Information
+
+The `meta.json` file in the context root contains version information:
+```json
+{
+  "sdk": {
+    "version": "<sdk-version>"
+  }
+}
+```
+
+This indicates which version of the Seeka SDK was used to generate this context.

package/dist/ai-context/common/architecture/overview.md

@@ -0,0 +1,140 @@
+# Seeka Apps Architecture Overview
+
+## What is a Seeka App?
+
+A Seeka app is a Node.js application that extends the Seeka platform by:
+- Receiving data from Seeka's core platform via webhooks
+- Processing and transforming data
+- Pushing data to external platforms (ads platforms, CRMs, analytics tools, etc.)
+- Providing configuration UI for end users
+
+## High-Level Architecture
+
+```
+┌─────────────────┐     Webhook      ┌─────────────────┐     API Calls    ┌─────────────────┐
+│                 │ ──────────────▶  │                 │ ──────────────▶  │                 │
+│   Seeka Core    │                  │   Seeka App     │                  │ External Platform│
+│   Platform      │ ◀──────────────  │   (Your App)    │ ◀──────────────  │ (Ads, CRM, etc) │
+│                 │     Response     │                 │     Response     │                 │
+└─────────────────┘                  └─────────────────┘                  └─────────────────┘
+                                            │
+                                            │ Serves UI
+                                            ▼
+                                     ┌─────────────────┐
+                                     │   App Config    │
+                                     │   UI (Browser)  │
+                                     └─────────────────┘
+```
+
+## Core Concepts
+
+### 1. Webhooks
+Seeka core sends data to your app via HTTP webhooks. Your app must:
+- Expose a webhook endpoint
+- Validate incoming requests
+- Process the data appropriately
+- Return proper responses
+
+### 2. Installation Settings
+Each app installation (per customer) has its own settings:
+- API credentials for external platforms
+- Configuration options
+- Feature toggles
+
+### 3. Data Encryption
+Sensitive data (like API keys) is encrypted at rest using the `DATA_ENCRYPTION_KEY` environment variable.
+
+### 4. Jobs and Activities
+Apps can process data through:
+- **Synchronous processing**: Handle in the webhook request
+- **Asynchronous processing**: Queue jobs for background processing
+
+## App Components
+
+### Server Component
+The backend of your app, typically deployed as:
+- Azure Functions (most common)
+- AWS Lambda
+- Netlify Functions
+
+Responsibilities:
+- Handle webhooks from Seeka
+- Store and retrieve installation settings
+- Communicate with external APIs
+- Serve the configuration UI
+
+### Browser Component (Optional)
+A browser extension/plugin that:
+- Runs in the user's browser
+- Collects additional data
+- Communicates with the server component
+
+### UI Component (Optional)
+A web interface for:
+- App configuration
+- Viewing app status
+- Managing settings
+
+## Deployment Architecture
+
+### Azure Functions (Primary)
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Azure Function App                    │
+├─────────────────────────────────────────────────────────┤
+│  HTTP Triggers:                                          │
+│  - /api/seeka-app-webhook    (Seeka webhooks)           │
+│  - /api/health               (Health check)              │
+│  - /api/settings/*           (Settings API)              │
+│  - /api/ui/*                 (UI static files)           │
+│                                                          │
+│  Queue Triggers:                                         │
+│  - trackActivityQueue        (Background processing)     │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Data Flow
+
+### Inbound (Seeka → App)
+1. Seeka core triggers webhook with event data
+2. App validates the request signature
+3. App processes the event
+4. App returns acknowledgment
+
+### Outbound (App → External Platform)
+1. App receives data from Seeka
+2. App transforms data to target format
+3. App authenticates with external platform
+4. App sends data via platform API
+5. App handles response/errors
+
+## Security Model
+
+### Request Validation
+- All incoming webhooks are signed
+- Apps must validate signatures before processing
+
+### Data Encryption
+- Sensitive settings encrypted with AES
+- Encryption key stored in environment variables
+
+### Authentication
+- Apps authenticate with external platforms using stored credentials
+- Credentials are encrypted at rest
+
+## Environment Variables
+
+Common environment variables across all apps:
+
+| Variable | Description |
+|----------|-------------|
+| `SEEKA_APP_ID` | Your app's unique identifier |
+| `SEEKA_APP_SECRET` | Secret for validating webhooks |
+| `DATA_ENCRYPTION_KEY` | Key for encrypting sensitive data |
+| `AZURE_STORAGE_CONNECTION_STRING` | Storage connection (Azure) |
+
+## Next Steps
+
+- See `v3-structure.md` for the current template structure
+- See `../guides/getting-started.md` for extending your app
+- See `../guides/data-flow.md` for detailed data flow patterns