@seeka-labs/cli-apps 3.7.0 → 3.8.2

package/dist/ai-context/internal/examples/v3/google-ads/app/ui/src/vite-env.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="vite/client" />
+/// <reference types="vite-plugin-svgr/client" />
+interface ViteTypeOptions {
+    strictImportMetaEnv: unknown
+}
+
+interface ImportMetaEnv {
+    readonly VITE_BASE_URL: string
+}
+
+interface ImportMeta {
+    readonly env: ImportMetaEnv
+}

package/dist/ai-context/internal/examples/v3/google-ads/app/ui/tsconfig.json

@@ -0,0 +1,35 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "allowJs": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+
+    /* Paths */
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src", "vite.config.ts"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}

package/dist/ai-context/internal/examples/v3/google-ads/app/ui/tsconfig.node.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["vite.config.ts"]
+}

package/dist/ai-context/internal/examples/v3/google-ads/app/ui/vite.config.mts

@@ -0,0 +1,48 @@
+import react from '@vitejs/plugin-react';
+import fs from 'fs-extra';
+import path from 'path';
+import { defineConfig } from 'vite';
+import svgr from "vite-plugin-svgr";
+function getBase() {
+    if (!process.env["VITE_BASE_URL"]) {
+        throw new Error("VITE_BASE_URL environment variable is required");
+    }
+    return process.env["VITE_BASE_URL"];
+}
+
+const devMode = process.env.NODE_ENV === 'development';
+
+// https://vitejs.dev/config/
+export default defineConfig({
+    plugins: [
+        react(),
+        svgr(),
+        ...(!devMode ? [] : [
+            {
+                name: 'copy-ui-to-server',
+                writeBundle() {
+                    const dest = '../server/dist/src/ui/build'
+                    fs.removeSync(dest)
+                    fs.copySync('build', dest)
+                }
+            }
+        ])
+    ],
+    // get exposed to your app as import.meta.env.BASE_URL
+    base: getBase(),
+    build: {
+        outDir: 'build',
+        emptyOutDir: true,
+        sourcemap: devMode ? 'inline' : false,
+        minify: devMode ? false : 'esbuild',
+        watch: devMode ? {} : undefined,
+    },
+    server: {
+        port: 3000,
+    },
+    resolve: {
+        alias: {
+            '@': path.resolve(__dirname, './src'),
+        },
+    },
+})

package/dist/ai-context/internal/examples/v3/google-ads/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "seeka-app-root",
+  "private": true,
+  "workspaces": [
+    "app/*"
+  ],
+  "scripts": {
+    "start:server": "yarn clean && yarn dev:lib && yarn build:server && yarn start:server:parallel",
+    "start:server:parallel": "concurrently -k --names \"server:run,browser:plugin,server:watch,server:tunnel\" \"yarn dev:server\" \"yarn dev:browser\" \"yarn watch:server\" \"yarn tunnel\"",
+    "start:all": "yarn clean && yarn dev:lib && yarn build:server && yarn start:all:parallel",
+    "start:all:parallel": "concurrently -k --names \"ui,server:run,browser:plugin,server:watch,server:tunnel\" \"yarn dev:ui\" \"yarn dev:server\" \"yarn dev:browser\" \"yarn watch:server\" \"yarn tunnel\"",
+    "build": "yarn workspace @seeka-labs-apps/google-ads-lib run build && yarn workspace @seeka-labs-apps/google-ads-browser run build && yarn workspace @seeka-labs-apps/google-ads-ui run build && yarn workspace @seeka-labs-apps/google-ads-server run build",
+    "typecheck": "yarn workspaces foreach -pt --all run typecheck",
+    "dev:lib": "yarn workspace @seeka-labs-apps/google-ads-lib run dev",
+    "dev:browser": "yarn workspace @seeka-labs-apps/google-ads-browser run watch",
+    "lint": "yarn workspaces foreach --all -pt run lint",
+    "build:lib": "yarn workspace @seeka-labs-apps/google-ads-lib run build",
+    "build:browser": "yarn workspace @seeka-labs-apps/google-ads-browser run build",
+    "build:server": "yarn workspace @seeka-labs-apps/google-ads-server run build",
+    "build:ui:test": "VITE_BASE_URL=/app/ yarn workspace @seeka-labs-apps/google-ads-ui run build",
+    "dev": "yarn workspace @seeka-labs-apps/google-ads-lib run dev && yarn workspace @seeka-labs-apps/google-ads-server run build && yarn workspace @seeka-labs-apps/google-ads-browser run watch",
+    "dev:init": "yarn workspace @seeka-labs-apps/google-ads-server run dev:queue:create",
+    "dev:ui": "yarn workspace @seeka-labs-apps/google-ads-ui run build:dev",
+    "dev:server": "yarn workspace @seeka-labs-apps/google-ads-server run build && yarn workspace @seeka-labs-apps/google-ads-server run dev",
+    "watch:server": "yarn workspace @seeka-labs-apps/google-ads-server run build && yarn workspace @seeka-labs-apps/google-ads-server run watch",
+    "deploy": "yarn clean && VITE_RELEASE_TAG=localdevbuild VITE_BASE_URL=/google-ads-app/ VITE_URLS_SEEKA_API_CORE=https://api.seeka.services VITE_URLS_SEEKA_APP_CORE_ORIGIN=https://seeka.app yarn build && yarn workspace @seeka-labs-apps/google-ads-server run deploy",
+    "tunnel": "yarn workspace @seeka-labs-apps/google-ads-server run tunnel",
+    "bump:patch": "yarn git:isclean && yarn workspaces foreach --all version patch --deferred && yarn bump:apply && yarn git:push",
+    "bump:minor": "yarn git:isclean && yarn workspaces foreach --all version minor --deferred && yarn bump:apply && yarn git:push",
+    "bump:major": "yarn git:isclean && yarn workspaces foreach --all version major --deferred && yarn bump:apply && yarn git:push",
+    "bump:apply": "yarn version apply --all",
+    "clean:packages": "rm -r node_modules && rm -r **/**/node_modules",
+    "git:isclean": "bash -c 'if [ -n \"$(git status --porcelain)\" ]; then echo \"✖ Working directory not clean. Commit or stash your changes first.\"; exit 1; fi'",
+    "git:push": "git add -A && git commit -m \"v$(node -p \"require('./package.json').version\")\" && git tag -a v$(node -p \"require('./package.json').version\") -m \"v$(node -p \"require('./package.json').version\")\"",
+    "clean": "yarn workspaces foreach --all -pt --include '@seeka-labs-apps/google-ads-*' run clean",
+    "clean:all": "yarn clean && rimraf ./app/**/node_modules",
+    "dev:kill:windows": "taskkill /f /t /im node.exe",
+    "dev:kill:linux": "pkill -f \"node .*$(pwd)\""
+  },
+  "devDependencies": {
+    "concurrently": "^9",
+    "rimraf": "^6"
+  },
+  "packageManager": "yarn@4.11.0"
+}

package/dist/ai-context/internal/examples/v3/google-ads/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": false,
+    "esModuleInterop": true,
+    "sourceMap": true,
+    "module": "CommonJS",
+    "target": "ES6",
+    "resolveJsonModule": true,
+    "isolatedModules": false,
+    "baseUrl": "."
+  },
+  "references": [
+    { "path": "app/browser" },
+    { "path": "app/server" },
+    { "path": "app/ui" },
+    { "path": "app/lib" }
+  ],
+  "exclude": [
+    "node_modules",
+    "**/dist"
+  ]
+}

package/dist/ai-context/public/architecture/app-structure.md

@@ -0,0 +1,385 @@
+# Seeka App Template Structure
+
+This document describes the app template structure. **Use this structure for all app implementations.**
+
+## Overview
+
+Seeka 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 features:
+- **Dedicated `app/lib/` package** for shared code
+- **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
+│   │   ├── 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
+│   │   │       ├── 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/`)
+
+Business logic is organized in `src/app/`:
+
+| 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/`)
+
+A dedicated shared library package for code used across components.
+
+```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
+
+Seeka apps use these 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`
+
+Apps leverage SDK utilities for common operations:
+
+```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:
+
+| 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