@seeka-labs/cli-apps 3.8.2 → 3.8.6

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

@@ -1,386 +0,0 @@
-# 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

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

@@ -1,53 +0,0 @@
-# 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/v2/_index.md

@@ -1,66 +0,0 @@
-# V2 Example Apps
-
-> **⚠️ Legacy Version**: V2 apps use an older Azure Functions model. Reference these for feature implementation patterns, but use V3 structure for new apps.
-
-## Overview
-
-V2 example apps demonstrate feature implementations using the monorepo structure with Azure Functions V3 programming model.
-
-## Available Examples
-
-
-### 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**: `./calendly/`
-
-
-<!-- Example entries will be added here by the import script:
-
-### meta-capi-v2
-- **Template**: azurefunc
-- **Components**: server, browser
-- **Description**: Meta Conversions API integration
-- **Tags**: conversion-api, ads-platform
-- **Path**: `./meta-capi-v2/`
-
--->
-
-## When to Reference V2 Apps
-
-V2 apps are useful for understanding:
-
-- **Monorepo patterns**: Workspace organization (similar to V3)
-- **Shared library usage**: How `app/lib` is structured
-- **UI component patterns**: React-based configuration UIs
-- **Browser plugin architecture**: Plugin structure and communication
-- **Complex integrations**: Multi-component app patterns
-
-## Key Differences from V3
-
-| Aspect | V2 | V3 |
-|--------|----|----|
-| Azure Functions | V3 programming model | V4 programming model |
-| Function exports | Default exports | Named exports with `app.http()` |
-| Bindings | `function.json` files | Code-based configuration |
-| Logging | Basic console/context | Winston structured logging |
-
-## Adapting V2 Code to V3
-
-When using V2 code as reference:
-
-1. Remove `function.json` files - V3 uses code-based configuration
-2. Update function signatures to return `HttpResponseInit`
-3. Convert default exports to named exports with `app.http()`
-4. Replace `context.log` with Winston logger
-5. Update SDK packages to latest versions
-
-See `../../architecture/v2-structure.md` for detailed migration guidance.
-
-## See Also
-
-- `../v3/` - Current template examples (use for new apps)
-- `../v1/` - V1 legacy examples
-- `../../architecture/v2-structure.md` - V2 structure documentation

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

@@ -1,105 +0,0 @@
-# V3 Example Apps
-
-> **✅ Current Version**: V3 is the current template version. Use these examples as the primary reference for new app development.
-
-## Overview
-
-V3 example apps demonstrate feature implementations using the current Seeka app template with Azure Functions V4 programming model.
-
-## Available Examples
-
-*No examples imported yet. Use the `ai:context:generate` script to import example apps.*
-
-<!-- Example entries will be added here by the import script:
-
-### google-ads-push
-- **Template**: azurefunc
-- **Components**: server
-- **Description**: Pushes conversion data to Google Ads Conversion API
-- **Tags**: conversion-api, ads-platform
-- **Path**: `./google-ads-push/`
-
-### tiktok-events
-- **Template**: azurefunc
-- **Components**: server, browser
-- **Description**: TikTok Events API integration with browser pixel
-- **Tags**: conversion-api, ads-platform
-- **Path**: `./tiktok-events/`
-
--->
-
-## V3 Template Features
-
-V3 apps include:
-
-- **Azure Functions V4**: Modern programming model with code-based configuration
-- **Monorepo structure**: Organized workspaces for server, lib, browser, and UI
-- **TypeScript strict mode**: Full type safety
-- **Winston logging**: Structured logging with context
-- **SDK integration**: Full use of `@seeka-labs/sdk-apps-server-host`
-
-## Example Structure
-
-Each V3 example includes:
-
-```
-example-name/
-├── _ai-summary.md          # AI-generated summary of the app
-├── README.md               # Human-readable documentation
-├── app/
-│   ├── server/
-│   │   └── src/
-│   │       ├── functions/  # Azure Function handlers
-│   │       └── app/
-│   │           └── services/  # Business logic
-│   ├── lib/
-│   │   └── src/
-│   │       ├── models/     # Shared types
-│   │       └── validation/ # Settings validation
-│   ├── browser/            # (if applicable)
-│   └── ui/                 # (if applicable)
-└── package.json
-```
-
-## Using V3 Examples
-
-### For New Feature Development
-
-1. Find an example with similar functionality
-2. Review the `_ai-summary.md` for key patterns
-3. Examine the service layer in `app/server/src/app/services/`
-4. Check the models in `app/lib/src/models/`
-5. Adapt the patterns to your app
-
-### For Understanding Patterns
-
-| Pattern | Where to Look |
-|---------|---------------|
-| Webhook handling | `app/server/src/functions/seekaAppWebhook.ts` |
-| External API calls | `app/server/src/app/services/` |
-| Data transformation | `app/server/src/app/services/` |
-| Settings validation | `app/lib/src/validation/` |
-| Queue processing | `app/server/src/functions/*QueueHandler.ts` |
-| Browser plugins | `app/browser/src/plugin/` |
-
-## Common Tags
-
-Examples are tagged for easy discovery:
-
-| Tag | Description |
-|-----|-------------|
-| `conversion-api` | Conversion API integrations (Meta, Google, TikTok) |
-| `ads-platform` | Advertising platform integrations |
-| `crm` | CRM platform integrations |
-| `telemetry` | Analytics and telemetry |
-| `data-sync` | Data synchronization patterns |
-| `webhook` | Webhook handling patterns |
-| `oauth` | OAuth authentication flows |
-| `batch` | Batch processing patterns |
-
-## See Also
-
-- `../v1/` - V1 legacy examples (for feature reference)
-- `../v2/` - V2 legacy examples (for feature reference)
-- `../../architecture/v3-structure.md` - V3 structure documentation
-- `../../guides/getting-started.md` - Getting started guide