@seeka-labs/cli-apps 3.7.0 → 3.8.2

package/dist/ai-context/internal/architecture/v2-structure.md

@@ -0,0 +1,261 @@
+# V2 App Template Structure (Legacy)
+
+> **⚠️ Legacy Version**: V2 is no longer used for new apps. This documentation is provided for reference when examining existing V2 apps for feature implementation patterns.
+
+## Overview
+
+V2 apps introduced the **monorepo structure** with separate packages for server, UI, and browser components. V2 apps use Azure Functions V4 programming model (same as V3) but organize code differently.
+
+## Key Differences from V3
+
+| Aspect | V2 | V3 |
+|--------|----|----|
+| Shared library | Code in `app/server/src/lib/` | Separate `app/lib/` package |
+| Server structure | `src/functions/` + `src/lib/` | `src/functions/` + `src/app/` |
+| Business logic | Mixed in `src/lib/` | Organized in `src/app/` subdirs |
+| SDK usage | Custom implementations | Uses `@seeka-labs/sdk-apps-server-host` |
+| CLI config | Not present | `.seeka/` directory with config |
+
+## V2 Directory Structure
+
+```
+your-app-name/
+├── app/
+│   ├── browser/                          # Browser plugin (optional)
+│   │   ├── src/
+│   │   │   ├── browser.ts                # Browser entry point
+│   │   │   └── plugin/
+│   │   │       └── index.ts              # Plugin implementation
+│   │   ├── package.json
+│   │   ├── tsconfig.json
+│   │   └── README.md
+│   ├── server/                           # Azure Functions server
+│   │   ├── src/
+│   │   │   ├── functions/                # Azure Function handlers
+│   │   │   │   ├── seekaAppWebhook.ts    # Main Seeka webhook
+│   │   │   │   ├── healthCheck.ts        # Health check endpoint
+│   │   │   │   ├── ui.ts                 # UI static file serving
+│   │   │   │   ├── [platform]Webhook.ts  # Platform webhooks (optional)
+│   │   │   │   ├── [platform]Auth*.ts    # OAuth handlers (optional)
+│   │   │   │   └── *QueueHandler.ts      # Queue processors (optional)
+│   │   │   └── lib/                      # Business logic (V2 style)
+│   │   │       ├── logging/
+│   │   │       │   └── index.ts          # Winston logging setup
+│   │   │       ├── services/
+│   │   │       │   └── index.ts          # Business logic services
+│   │   │       ├── state/
+│   │   │       │   ├── seeka/
+│   │   │       │   │   └── installations.ts
+│   │   │       │   └── redis/
+│   │   │       │       └── index.ts
+│   │   │       ├── jobs/
+│   │   │       │   └── index.ts          # Background job definitions
+│   │   │       ├── models/
+│   │   │       │   └── index.ts          # TypeScript interfaces
+│   │   │       ├── browser/
+│   │   │       │   └── index.ts          # Browser plugin config
+│   │   │       ├── api/                  # REST API routes (optional)
+│   │   │       │   ├── auth.ts
+│   │   │       │   └── routes/
+│   │   │       │       └── *.ts
+│   │   │       └── [platform-name]/      # Platform-specific code
+│   │   │           └── *.ts
+│   │   ├── host.json                     # Azure Functions host config
+│   │   ├── local.settings.json           # Local dev settings (gitignored)
+│   │   ├── package.json
+│   │   ├── tsconfig.json
+│   │   └── README.md
+│   └── ui/                               # Configuration UI (optional)
+│       ├── src/
+│       │   ├── main.tsx                  # React entry point
+│       │   ├── App.tsx                   # Main App component
+│       │   ├── vite-env.d.ts
+│       │   └── seeka-labs-app-sdk-ui/    # Shared UI utilities
+│       │       ├── utils/
+│       │       └── shared/
+│       ├── public/
+│       │   └── manifest.json
+│       ├── scripts/
+│       │   └── copy-output.mjs
+│       ├── package.json
+│       ├── tsconfig.json
+│       ├── tsconfig.node.json
+│       ├── vite.config.ts
+│       └── README.md
+├── .vscode/                              # VS Code configuration (optional)
+│   ├── launch.json
+│   ├── settings.json
+│   ├── extensions.json
+│   └── tasks.json
+├── package.json                          # Root package.json (workspaces)
+├── tsconfig.json                         # Root TypeScript config
+└── README.md
+```
+
+## Example V2 Apps by Category
+
+### Full-featured Apps (Server + UI + Browser)
+- **calendly** - Calendar scheduling integration with OAuth
+- **typeform** - Form/survey integration with OAuth
+
+### Server + UI Apps (No Browser)
+- **webhook** - Generic inbound webhook handler
+- **yeastar** - Phone system CRM integration
+
+### Server-only Apps
+- **klaviyo-events** - Email marketing event tracking
+- **google-bigquery** - Data warehouse integration
+- **navitas** - Education platform integration
+
+### Browser-focused Apps
+- **clarity** - Microsoft Clarity analytics (browser + server)
+- **trustarc** - Privacy/consent management (browser + server)
+
+## Key V2 Patterns
+
+### Function Definition (V2 uses V4 programming model)
+
+V2 apps use the same Azure Functions V4 programming model as V3:
+
+```typescript
+// app/server/src/functions/seekaAppWebhook.ts
+import { app, HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';
+
+app.http('seekaAppWebhook', {
+    methods: ['POST'],
+    authLevel: 'anonymous',
+    route: 'api/webhook/seeka/app',
+    handler: seekaAppWebhook
+});
+
+export async function seekaAppWebhook(
+    req: HttpRequest,
+    context: InvocationContext
+): Promise<HttpResponseInit> {
+    const body = JSON.parse(await req.text());
+    // Process webhook...
+    return { status: 204 };
+}
+```
+
+### Queue Handler Pattern
+
+```typescript
+// app/server/src/functions/handleSeekaActivityQueueHandler.ts
+import { app, InvocationContext } from '@azure/functions';
+
+app.storageQueue('handleSeekaActivityQueueHandler', {
+    queueName: 'seeka-activity-queue',
+    connection: 'AzureWebJobsStorage',
+    handler: async (queueItem: unknown, context: InvocationContext) => {
+        // Process queued item
+    }
+});
+```
+
+### Installation State (V2 Custom Implementation)
+
+V2 apps typically have custom installation management in `src/lib/state/`:
+
+```typescript
+// app/server/src/lib/state/seeka/installations.ts
+import { getRedisClient } from '../redis';
+
+export interface AppInstallContext {
+    applicationInstallId: string;
+    organisationId: string;
+    organisationBrandId: string;
+    installedAt: string;
+    installationState?: {
+        grantedPermissions: string[];
+        installationSettings: AppInstallationSettings;
+    };
+}
+
+export const getInstallation = async (installId: string): Promise<AppInstallContext | null> => {
+    const redis = await getRedisClient();
+    const data = await redis.get(`installation:${installId}`);
+    return data ? JSON.parse(data) : null;
+};
+```
+
+### API Routes Pattern
+
+V2 apps with UI typically have API routes in `src/lib/api/`:
+
+```typescript
+// app/server/src/lib/api/routes/setTrackingSettings.ts
+import { HttpRequest, HttpResponseInit } from '@azure/functions';
+import { getInstallation, saveInstallation } from '../../state/seeka/installations';
+
+export const setTrackingSettings = async (
+    req: HttpRequest,
+    installId: string
+): Promise<HttpResponseInit> => {
+    const body = await req.json();
+    const installation = await getInstallation(installId);
+    // Update settings...
+    await saveInstallation(installation);
+    return { status: 200, jsonBody: { success: true } };
+};
+```
+
+### UI Component Pattern
+
+V2 UIs use React with Vite and shared UI utilities:
+
+```typescript
+// app/ui/src/App.tsx
+import { useTokens } from './seeka-labs-app-sdk-ui/shared/auth/useTokens';
+
+function App() {
+    const { accessToken, installationId } = useTokens();
+
+    // Render configuration UI
+}
+```
+
+## When to Reference V2 Apps
+
+V2 apps are excellent references for:
+
+- **Monorepo organization**: How to structure multi-package apps
+- **UI configuration patterns**: React-based settings UIs with Vite
+- **OAuth integration flows**: Platform authentication (Calendly, Typeform, Google)
+- **API route patterns**: REST endpoints for UI communication
+- **Browser plugin architecture**: Plugin structure and server communication
+- **Queue-based processing**: Async activity processing patterns
+
+## Adapting V2 Patterns to V3
+
+When using V2 code as reference for a new V3 app:
+
+1. **Create `app/lib/` package** for shared code instead of keeping it in `app/server/src/lib/`
+2. **Move models** from `app/server/src/lib/models/` to `app/lib/src/models/`
+3. **Move validation** to `app/lib/src/validation/`
+4. **Reorganize server code**:
+   - Move `src/lib/services/` to `src/app/services/`
+   - Move `src/lib/api/` to `src/app/api/`
+   - Move `src/lib/jobs/` to `src/app/jobs/`
+   - Move `src/lib/logging/` to `src/app/logging/`
+5. **Use SDK utilities** from `@seeka-labs/sdk-apps-server-host`:
+   - Replace custom `getInstallation`/`saveInstallation` with SDK functions
+   - Use SDK logging setup instead of custom winston config
+6. **Add `.seeka/` directory** with `init.app.seeka.cli.config.json`
+
+## Migration Checklist: V2 → V3
+
+- [ ] Create `app/lib/` package with `package.json` and `tsconfig.json`
+- [ ] Move shared models and validation to `app/lib/src/`
+- [ ] Reorganize `app/server/src/lib/` to `app/server/src/app/`
+- [ ] Update imports to use `app/lib` package
+- [ ] Replace custom installation management with SDK utilities
+- [ ] Add `.seeka/init.app.seeka.cli.config.json`
+- [ ] Update SDK packages to latest versions
+- [ ] Test all endpoints, queue handlers, and UI
+
+## See Also
+
+- `v1-structure.md` - V1 legacy structure (single package)
+- `v3-structure.md` - Current template structure (use for new apps)
+- `../examples/v2/` - V2 example apps for feature reference

package/dist/ai-context/internal/architecture/v3-structure.md

@@ -0,0 +1,386 @@
+# V3 App Template Structure (Current)
+
+This document describes the current V3 template structure. **Use this structure for all new app implementations.**
+
+## Overview
+
+V3 apps are **monorepos** with four potential packages:
+- `app/lib/` - Shared library (models, validation, utilities)
+- `app/server/` - Azure Functions backend
+- `app/browser/` - Browser plugin (optional)
+- `app/ui/` - React configuration UI (optional)
+
+Key V3 improvements over V2:
+- **Dedicated `app/lib/` package** for shared code (instead of `app/server/src/lib/`)
+- **Organized `src/app/` directory** in server for business logic
+- **SDK integration** via `@seeka-labs/sdk-apps-server-host`
+- **CLI configuration** in `.seeka/` directory
+
+## Directory Structure
+
+```
+your-app-name/
+├── .seeka/
+│   ├── init.app.seeka.cli.config.json    # CLI init configuration
+│   └── init.app.secrets.seeka.cli.config.json  # Secrets (gitignored)
+├── .github/
+│   └── workflows/
+│       └── deploy-azurefunc.yml          # GitHub Actions deployment
+├── app/
+│   ├── browser/                          # Browser plugin (optional)
+│   │   ├── src/
+│   │   │   ├── browser.ts                # Browser entry point
+│   │   │   └── plugin/
+│   │   │       └── index.ts              # Plugin implementation
+│   │   ├── scripts/
+│   │   │   └── esbuild/
+│   │   │       └── build-browser-plugin.mjs
+│   │   ├── package.json
+│   │   ├── tsconfig.json
+│   │   └── README.md
+│   ├── lib/                              # Shared library (V3 key feature)
+│   │   ├── src/
+│   │   │   ├── index.ts                  # Library exports
+│   │   │   ├── models/
+│   │   │   │   └── index.ts              # Shared models/types
+│   │   │   ├── validation/
+│   │   │   │   └── index.ts              # Settings validation
+│   │   │   └── utils/
+│   │   │       └── index.ts              # Shared utilities (optional)
+│   │   ├── package.json
+│   │   └── tsconfig.json
+│   ├── server/                           # Server component (Azure Functions)
+│   │   ├── src/
+│   │   │   ├── functions/                # Azure Function handlers
+│   │   │   │   ├── seekaAppWebhook.ts    # Main webhook handler
+│   │   │   │   ├── healthCheck.ts        # Health check endpoint
+│   │   │   │   ├── ui.ts                 # UI static file serving
+│   │   │   │   ├── *QueueHandler.ts      # Queue processors
+│   │   │   │   ├── [platform]AuthRedirect.ts   # OAuth redirect (optional)
+│   │   │   │   └── [platform]AuthCallback.ts   # OAuth callback (optional)
+│   │   │   └── app/                      # Application logic (V3 key feature)
+│   │   │       ├── api/
+│   │   │       │   ├── router.ts         # API routing
+│   │   │       │   └── routes/
+│   │   │       │       └── *.ts          # Individual API route handlers
+│   │   │       ├── jobs/
+│   │   │       │   └── index.ts          # Background job definitions
+│   │   │       ├── models/
+│   │   │       │   └── index.ts          # Server-specific models
+│   │   │       ├── services/
+│   │   │       │   ├── activities.ts     # Activity processing
+│   │   │       │   └── [platform]/       # Platform-specific services
+│   │   │       │       └── *.ts
+│   │   │       └── logging/
+│   │   │           └── index.ts          # Logging configuration
+│   │   ├── host.json                     # Azure Functions host config
+│   │   ├── local.settings.json           # Local dev settings (gitignored)
+│   │   ├── local.settings.template.json  # Template for local settings
+│   │   ├── package.json
+│   │   ├── tsconfig.json
+│   │   └── README.md
+│   └── ui/                               # Configuration UI (optional)
+│       ├── src/
+│       │   ├── main.tsx                  # React entry point
+│       │   ├── App.tsx                   # Main App component
+│       │   └── vite-env.d.ts
+│       ├── scripts/
+│       │   └── copy-output.mjs           # Build output copy script
+│       ├── package.json
+│       ├── tsconfig.json
+│       ├── tsconfig.node.json
+│       ├── vite.config.ts
+│       └── README.md
+├── .yarnrc.yml                           # Yarn configuration
+├── package.json                          # Root package.json (workspaces)
+├── tsconfig.json                         # Root TypeScript config
+├── AGENTS.md                             # AI context pointer file
+└── README.md
+```
+
+## Key Components
+
+### 1. Server Component (`app/server/`)
+
+The main backend, implemented as Azure Functions V4.
+
+#### Functions (`src/functions/`)
+
+| File | Purpose |
+|------|---------|
+| `seekaAppWebhook.ts` | Main webhook handler for all Seeka events |
+| `healthCheck.ts` | Health check endpoint for monitoring |
+| `ui.ts` | Serves the configuration UI static files |
+| `*QueueHandler.ts` | Queue processors for async operations |
+| `[platform]AuthRedirect.ts` | OAuth redirect handler (optional) |
+| `[platform]AuthCallback.ts` | OAuth callback handler (optional) |
+
+#### Application Logic (`src/app/`)
+
+V3 organizes business logic in `src/app/` (not `src/lib/` like V2):
+
+| Directory | Purpose |
+|-----------|---------|
+| `api/` | REST API routes for UI communication |
+| `api/router.ts` | Central API routing |
+| `api/routes/*.ts` | Individual route handlers |
+| `jobs/` | Background job queue definitions |
+| `models/` | Server-specific TypeScript interfaces |
+| `services/` | Business logic and external API integrations |
+| `services/[platform]/` | Platform-specific service modules |
+| `logging/` | Winston logging configuration |
+
+### 2. Shared Library (`app/lib/`) - V3 Key Feature
+
+V3 introduces a dedicated shared library package (unlike V2 which kept shared code in `app/server/src/lib/`).
+
+```typescript
+// src/index.ts - Exports
+export * from './models';
+export * from './validation';
+export * from './utils';  // Optional utilities
+```
+
+#### Models (`src/models/index.ts`)
+
+Define your app's TypeScript interfaces:
+
+```typescript
+export interface YourAppInstallContext {
+    applicationInstallId: string;
+    organisationId: string;
+    organisationBrandId: string;
+    installedAt: string;
+    installationState?: {
+        grantedPermissions: string[];
+        installationSettings: YourAppInstallationSettings;
+    };
+}
+
+export interface YourAppInstallationSettings {
+    apiKey?: string;
+    customerId?: string;
+    // Add your settings here
+}
+
+export interface YourAppBrowserSdkPluginConfig {
+    appId: string;
+    appInstallId: string;
+    appUrl: string;
+    // Browser plugin configuration
+}
+```
+
+#### Validation (`src/validation/index.ts`)
+
+Validate installation settings:
+
+```typescript
+import { Logger } from 'winston';
+
+export const validateInstallationSettings = async (
+    settings: YourAppInstallationSettings,
+    logger: Logger
+): Promise<string | null> => {
+    if (!settings.apiKey) {
+        return 'API Key is required';
+    }
+    return null; // null = valid
+};
+```
+
+### 3. Browser Plugin (`app/browser/`) - Optional
+
+For apps that need browser-side functionality (tracking, consent, etc.).
+
+```typescript
+// src/plugin/index.ts
+export class YourAppBrowserPlugin {
+    constructor(config: YourAppBrowserPluginConfig) {
+        // Initialize plugin with config from server
+    }
+
+    // Plugin methods for browser-side operations
+}
+```
+
+### 4. Configuration UI (`app/ui/`) - Optional
+
+React-based UI for app configuration, built with Vite. Used for:
+- OAuth connection flows
+- Settings configuration
+- Status display
+
+## Webhook Handler Pattern
+
+The main webhook handler (`seekaAppWebhook.ts`) follows this pattern:
+
+```typescript
+import { app, HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';
+import { SeekaWebhookCallType, throwOnInvalidWebhookSignature } from '@seeka-labs/sdk-apps-server';
+
+app.http('seekaAppWebhook', {
+    methods: ['POST'],
+    authLevel: 'anonymous',
+    route: 'api/webhook/seeka/app',
+    handler: seekaAppWebhook
+});
+
+export async function seekaAppWebhook(req: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
+    const bodyStr = await req.text();
+    const body = JSON.parse(bodyStr);
+
+    // 1. Handle probe requests
+    if (body.type === SeekaWebhookCallType.Probe) {
+        return { status: 204 };
+    }
+
+    // 2. Validate webhook signature
+    throwOnInvalidWebhookSignature(process.env.SEEKA_APP_SECRET, req.headers, bodyStr);
+
+    // 3. Handle by webhook type
+    switch (body.type) {
+        case SeekaWebhookCallType.AppInstalled:
+            // Handle installation
+            break;
+        case SeekaWebhookCallType.AppUninstalled:
+            // Handle uninstallation
+            break;
+        case SeekaWebhookCallType.ActivityAccepted:
+            // Handle activity data
+            break;
+        case SeekaWebhookCallType.IdentityChanged:
+            // Handle identity changes
+            break;
+        case SeekaWebhookCallType.BrowserSdkPlugin:
+            // Return browser plugin config
+            break;
+    }
+
+    return { status: 204 };
+}
+```
+
+## Background Job Pattern
+
+For async processing, use the queue pattern:
+
+```typescript
+// jobs/index.ts
+export const queueNames = {
+    trackActivity: 'track-activity-queue'
+};
+
+export const triggerBackgroundJob = async <T>(
+    queueName: string,
+    item: T,
+    logger: Logger
+) => {
+    // Queue the job
+};
+```
+
+```typescript
+// functions/trackActivityQueueHandler.ts
+app.storageQueue('trackActivityQueueHandler', {
+    queueName: queueNames.trackActivity,
+    connection: 'AzureWebJobsStorage',
+    handler: async (item, context) => {
+        // Process the queued item
+    }
+});
+```
+
+## SDK Dependencies
+
+V3 apps use these Seeka SDK packages:
+
+| Package | Purpose |
+|---------|---------|
+| `@seeka-labs/sdk-apps-server` | Core SDK types, webhook payloads, signature validation |
+| `@seeka-labs/sdk-apps-server-host` | Server hosting utilities (installation management, logging, browser plugin) |
+
+### Key SDK Utilities from `@seeka-labs/sdk-apps-server-host`
+
+V3 apps leverage SDK utilities instead of custom implementations (unlike V1/V2):
+
+```typescript
+import {
+    tryGetInstallation,
+    createOrUpdateInstallation,
+    deleteInstallation,
+    getSeekaBrowserPlugin,
+    startServices,
+    webhookLogger,
+    childLogger,
+} from '@seeka-labs/sdk-apps-server-host';
+
+// Installation management
+const installation = await tryGetInstallation(installId, false, logger);
+await createOrUpdateInstallation(installationData, logger);
+await deleteInstallation(installId, logger);
+
+// Logging
+const logger = webhookLogger(webhookBody, context);
+const childLog = childLogger(metadata, installation, logger, context);
+
+// Browser plugin
+const plugin = await getSeekaBrowserPlugin<PluginConfig>(
+    'PluginClassName',
+    browserPluginBasePath,
+    pluginConfig,
+    logger
+);
+
+// Service initialization
+await startServices(logger);
+```
+
+### Key SDK Types from `@seeka-labs/sdk-apps-server`
+
+```typescript
+import {
+    SeekaWebhookCallType,
+    SeekaWebhookPayload,
+    SeekaAppInstalledWebhookPayload,
+    SeekaAppUninstalledWebhookPayload,
+    SeekaActivityAcceptedWebhookPayload,
+    SeekaIdentityChangedWebhookPayload,
+    throwOnInvalidWebhookSignature,
+} from '@seeka-labs/sdk-apps-server';
+```
+
+## Environment Variables
+
+Required environment variables for V3 apps:
+
+| Variable | Description |
+|----------|-------------|
+| `SEEKA_APP_ID` | Your app's unique identifier |
+| `SEEKA_APP_SECRET` | Secret for webhook validation |
+| `DATA_ENCRYPTION_KEY` | 32-character key for encrypting sensitive data |
+| `AZURE_STORAGE_CONNECTION_STRING` | Azure Storage connection string |
+| `SELF_HOST_BASEURL` | Public URL of your deployed app |
+
+## Package.json Scripts
+
+Standard scripts in root `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "yarn workspaces foreach -A run build",
+    "build:server": "yarn workspace @your-org/your-app-server run build",
+    "build:ui": "yarn workspace @your-org/your-app-ui run build",
+    "build:browser": "yarn workspace @your-org/your-app-browser run build",
+    "dev": "yarn workspace @your-org/your-app-server run dev",
+    "test": "yarn workspaces foreach -A run test"
+  }
+}
+```
+
+## Next Steps
+
+- See `../guides/getting-started.md` for extending your app
+- See `../guides/common-patterns.md` for implementation patterns
+- See `../examples/v3/` for complete example implementations