@seeka-labs/cli-apps 3.7.0 → 3.8.2

package/dist/ai-context/common/reference/sdk-api.md

@@ -0,0 +1,445 @@
+# SDK API Reference
+
+This document provides a reference for the Seeka SDK packages used in apps.
+
+## Packages Overview
+
+| Package | Description |
+|---------|-------------|
+| `@seeka-labs/sdk-apps-server` | Core SDK types, webhook validation, and utilities |
+| `@seeka-labs/sdk-apps-server-host` | Server hosting utilities for Azure Functions |
+
+## @seeka-labs/sdk-apps-server
+
+### Webhook Types
+
+```typescript
+import { SeekaWebhookCallType } from '@seeka-labs/sdk-apps-server';
+
+// Available webhook types
+SeekaWebhookCallType.Probe           // Health check probe
+SeekaWebhookCallType.AppInstalled    // App installation
+SeekaWebhookCallType.AppUninstalled  // App uninstallation
+SeekaWebhookCallType.ActivityAccepted // Activity data received
+SeekaWebhookCallType.IdentityChanged  // User identity updated
+SeekaWebhookCallType.BrowserSdkPlugin // Browser plugin request
+```
+
+### Webhook Payload Types
+
+```typescript
+import {
+    SeekaWebhookPayload,
+    SeekaAppInstalledWebhookPayload,
+    SeekaAppUninstalledWebhookPayload,
+    SeekaActivityAcceptedWebhookPayload,
+    SeekaIdentityChangedWebhookPayload
+} from '@seeka-labs/sdk-apps-server';
+```
+
+#### SeekaWebhookPayload (Base)
+
+```typescript
+interface SeekaWebhookPayload {
+    type: SeekaWebhookCallType;
+    isTest: boolean;
+    context?: {
+        applicationInstallId: string;
+        organisationId: string;
+        organisationBrandId: string;
+    };
+}
+```
+
+#### SeekaAppInstalledWebhookPayload
+
+```typescript
+interface SeekaAppInstalledWebhookPayload extends SeekaWebhookPayload {
+    type: 'AppInstalled';
+    content: {
+        grantedPermissions: string[];
+        installationSettings: Record<string, unknown>;
+    };
+}
+```
+
+#### SeekaActivityAcceptedWebhookPayload
+
+```typescript
+interface SeekaActivityAcceptedWebhookPayload extends SeekaWebhookPayload {
+    type: 'ActivityAccepted';
+    content: {
+        activity: {
+            activityId: string;
+            activityName: string;
+            activityNameCustom?: string;
+            timestamp: string;
+            properties?: Record<string, unknown>;
+        };
+        person?: {
+            personId: string;
+            email?: string;
+            emailHashed?: string;
+            phone?: string;
+            phoneHashed?: string;
+            firstName?: string;
+            lastName?: string;
+        };
+        source?: {
+            loc: string;
+            ref?: string;
+            userAgent?: string;
+            ip?: string;
+        };
+    };
+}
+```
+
+### Webhook Validation
+
+```typescript
+import { throwOnInvalidWebhookSignature } from '@seeka-labs/sdk-apps-server';
+
+// Validates webhook signature - throws if invalid
+throwOnInvalidWebhookSignature(
+    appSecret: string,      // SEEKA_APP_SECRET environment variable
+    headers: Headers,       // Request headers
+    bodyString: string      // Raw request body as string
+): void;
+```
+
+**Usage:**
+```typescript
+try {
+    throwOnInvalidWebhookSignature(
+        process.env.SEEKA_APP_SECRET!,
+        req.headers as Headers,
+        bodyStr
+    );
+    // Signature valid, proceed
+} catch {
+    // Invalid signature
+    return { status: 401, jsonBody: { error: 'Invalid signature' } };
+}
+```
+
+## @seeka-labs/sdk-apps-server-host
+
+### Installation Management
+
+#### createOrUpdateInstallation
+
+Creates or updates an installation record.
+
+```typescript
+import { createOrUpdateInstallation } from '@seeka-labs/sdk-apps-server-host';
+
+await createOrUpdateInstallation(
+    installation: InstallationContext,
+    logger: Logger
+): Promise<void>;
+```
+
+**Example:**
+```typescript
+await createOrUpdateInstallation({
+    applicationInstallId: payload.context.applicationInstallId,
+    organisationId: payload.context.organisationId,
+    organisationBrandId: payload.context.organisationBrandId,
+    installedAt: new Date().toISOString(),
+    installationState: {
+        grantedPermissions: payload.content.grantedPermissions,
+        installationSettings: payload.content.installationSettings
+    }
+}, logger);
+```
+
+#### getInstallation
+
+Gets an installation by ID. Throws if not found.
+
+```typescript
+import { getInstallation } from '@seeka-labs/sdk-apps-server-host';
+
+const installation = await getInstallation(
+    applicationInstallId: string,
+    decrypt: boolean,       // true to decrypt sensitive data
+    logger: Logger
+): Promise<InstallationContext>;
+```
+
+#### tryGetInstallation
+
+Gets an installation by ID. Returns null if not found.
+
+```typescript
+import { tryGetInstallation } from '@seeka-labs/sdk-apps-server-host';
+
+const installation = await tryGetInstallation(
+    applicationInstallId: string,
+    decrypt: boolean,
+    logger: Logger
+): Promise<InstallationContext | null>;
+```
+
+#### deleteInstallation
+
+Deletes an installation record.
+
+```typescript
+import { deleteInstallation } from '@seeka-labs/sdk-apps-server-host';
+
+await deleteInstallation(
+    applicationInstallId: string,
+    logger: Logger
+): Promise<void>;
+```
+
+### Background Jobs
+
+#### triggerBackgroundJob
+
+Queues a job for background processing.
+
+```typescript
+import { triggerBackgroundJob } from '@seeka-labs/sdk-apps-server-host';
+
+await triggerBackgroundJob<T>(
+    queueName: string,
+    item: T,
+    logger: Logger
+): Promise<void>;
+```
+
+**Example:**
+```typescript
+await triggerBackgroundJob(queueNames.trackActivity, {
+    payload: activity.content,
+    applicationInstallId: installation.applicationInstallId,
+    organisationId: installation.organisationId,
+    organisationBrandId: installation.organisationBrandId,
+    causationId: context.invocationId,
+    correlationId: context.invocationId
+}, logger);
+```
+
+### Logging
+
+#### webhookLogger
+
+Creates a logger configured for webhook handling.
+
+```typescript
+import { webhookLogger } from '@seeka-labs/sdk-apps-server-host';
+
+const logger = webhookLogger(
+    webhookPayload: SeekaWebhookPayload,
+    context: InvocationContext
+): Logger;
+```
+
+#### childLogger
+
+Creates a child logger with additional context.
+
+```typescript
+import { childLogger } from '@seeka-labs/sdk-apps-server-host';
+
+const logger = childLogger(
+    additionalMeta: Record<string, unknown> | null,
+    installation: InstallationContext | null,
+    parentLogger: Logger | null,
+    context: InvocationContext
+): Logger;
+```
+
+**Example:**
+```typescript
+let logger = webhookLogger(body, context);
+
+// Add installation context
+logger = childLogger({
+    'Activity_Id': activity.activityId
+}, installation, logger, context);
+```
+
+### Services
+
+#### startServices
+
+Initializes required services (storage, etc.). Call at the start of request handling.
+
+```typescript
+import { startServices } from '@seeka-labs/sdk-apps-server-host';
+
+await startServices(logger: Logger): Promise<void>;
+```
+
+### Browser Plugin
+
+#### getSeekaBrowserPlugin
+
+Loads and configures a browser plugin for serving to clients.
+
+```typescript
+import { getSeekaBrowserPlugin } from '@seeka-labs/sdk-apps-server-host';
+
+const plugin = await getSeekaBrowserPlugin<TConfig>(
+    pluginName: string,
+    pluginBasePath: string,
+    config: TConfig,
+    logger: Logger
+): Promise<BrowserPluginResponse>;
+```
+
+**Example:**
+```typescript
+const pluginConfig = {
+    appId: process.env.SEEKA_APP_ID,
+    appInstallId: installation.applicationInstallId,
+    appUrl: process.env.SELF_HOST_BASEURL
+};
+
+const browserPluginBasePath = path.resolve('./dist/src/browser');
+const plugin = await getSeekaBrowserPlugin(
+    'MyAppBrowserPlugin',
+    browserPluginBasePath,
+    pluginConfig,
+    logger
+);
+
+return {
+    status: 200,
+    body: JSON.stringify(plugin),
+    headers: { 'Content-Type': 'application/json' }
+};
+```
+
+## Type Definitions
+
+### InstallationContext
+
+```typescript
+interface InstallationContext {
+    applicationInstallId: string;
+    organisationId: string;
+    organisationBrandId: string;
+    installedAt: string;
+    installationState?: {
+        grantedPermissions: string[];
+        installationSettings: Record<string, unknown>;
+        // Custom state can be added here
+    };
+}
+```
+
+### Logger (Winston)
+
+The SDK uses Winston for logging:
+
+```typescript
+interface Logger {
+    debug(message: string, meta?: object): void;
+    verbose(message: string, meta?: object): void;
+    info(message: string, meta?: object): void;
+    warn(message: string, meta?: object): void;
+    error(message: string, meta?: object): void;
+    profile(id: string): void;
+}
+```
+
+## Common Patterns
+
+### Complete Webhook Handler
+
+```typescript
+import { app, HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';
+import {
+    SeekaWebhookCallType,
+    SeekaWebhookPayload,
+    throwOnInvalidWebhookSignature
+} from '@seeka-labs/sdk-apps-server';
+import {
+    tryGetInstallation,
+    createOrUpdateInstallation,
+    startServices,
+    webhookLogger,
+    childLogger
+} from '@seeka-labs/sdk-apps-server-host';
+
+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();
+    if (!bodyStr) {
+        return { status: 400, jsonBody: { error: 'Body missing' } };
+    }
+
+    const body = JSON.parse(bodyStr) as SeekaWebhookPayload;
+    let logger = webhookLogger(body, context);
+
+    // Handle probe
+    if (body.type === SeekaWebhookCallType.Probe) {
+        return { status: 204 };
+    }
+
+    // Validate signature
+    try {
+        throwOnInvalidWebhookSignature(
+            process.env.SEEKA_APP_SECRET!,
+            req.headers as Headers,
+            bodyStr
+        );
+    } catch {
+        return { status: 401, jsonBody: { error: 'Invalid signature' } };
+    }
+
+    // Skip test webhooks
+    if (body.isTest) {
+        return { status: 204 };
+    }
+
+    await startServices(logger);
+
+    // Get installation for non-install webhooks
+    let installation = null;
+    if (body.type !== SeekaWebhookCallType.AppInstalled) {
+        installation = await tryGetInstallation(
+            body.context!.applicationInstallId,
+            true,
+            logger
+        );
+        if (!installation) {
+            return { status: 422, jsonBody: { error: 'App not installed' } };
+        }
+        logger = childLogger(null, installation, logger, context);
+    }
+
+    // Handle webhook types
+    switch (body.type) {
+        case SeekaWebhookCallType.AppInstalled:
+            // Handle installation
+            break;
+        case SeekaWebhookCallType.ActivityAccepted:
+            // Handle activity
+            break;
+        // ... other types
+    }
+
+    return { status: 204 };
+}
+```
+
+## See Also
+
+- `../guides/getting-started.md` - Getting started guide
+- `../guides/data-flow.md` - Data flow patterns
+- `../architecture/v3-structure.md` - Template structure

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

@@ -0,0 +1,192 @@
+# V1 App Template Structure (Legacy)
+
+> **⚠️ Legacy Version**: V1 is no longer used for new apps. This documentation is provided for reference when examining existing V1 apps for feature implementation patterns.
+
+## Overview
+
+V1 apps were the first generation of Seeka apps. They are **single-package Azure Functions apps** (not monorepos) with all code in a flat `src/` directory structure.
+
+## Key Differences from V3
+
+| Aspect | V1 | V3 |
+|--------|----|----|
+| Structure | Single package, flat `src/` | Monorepo with `app/` workspaces |
+| Azure Functions | V4 programming model | V4 programming model |
+| Shared code | In `src/lib/` within same package | Separate `app/lib/` package |
+| Browser plugin | Nested in `src/browser/` (if present) | Separate `app/browser/` package |
+| UI component | Not present | Separate `app/ui/` package |
+| Build system | tsc | esbuild with optimizations |
+| Configuration | `host.json` at root | `host.json` in `app/server/` |
+
+## V1 Directory Structure
+
+V1 apps have two main variants:
+
+### Standard V1 (Azure Functions)
+
+Most V1 apps follow this structure:
+
+```
+your-app-name/
+├── src/
+│   ├── functions/                    # Azure Function handlers
+│   │   ├── seekaAppWebhook.ts        # Main Seeka webhook
+│   │   ├── healthCheck.ts            # Health check endpoint
+│   │   └── [platformWebhook].ts      # Platform-specific webhooks (optional)
+│   ├── lib/                          # Business logic and utilities
+│   │   ├── logging/
+│   │   │   └── index.ts              # Winston logging setup
+│   │   ├── services/
+│   │   │   └── index.ts              # Business logic services
+│   │   ├── state/
+│   │   │   ├── seeka/
+│   │   │   │   └── installations.ts  # Installation state management
+│   │   │   └── redis/
+│   │   │       └── index.ts          # Redis client setup
+│   │   ├── jobs/
+│   │   │   └── index.ts              # Background job definitions (optional)
+│   │   ├── models/
+│   │   │   └── index.ts              # TypeScript interfaces (optional)
+│   │   └── [platform-name]/          # Platform-specific API clients
+│   │       ├── api/
+│   │       │   └── index.ts
+│   │       └── [feature]/
+│   │           └── index.ts
+│   └── browser/                      # Browser plugin (optional, nested package)
+│       ├── src/
+│       │   ├── browser.ts
+│       │   └── plugin/
+│       │       └── index.ts
+│       ├── package.json
+│       ├── tsconfig.json
+│       └── README.md
+├── host.json                         # Azure Functions host configuration
+├── local.settings.json               # Local development settings (gitignored)
+├── package.json                      # Single package.json for entire app
+├── tsconfig.json
+└── README.md
+```
+
+### Express-based V1 (Alternative)
+
+Some V1 apps use Express instead of Azure Functions:
+
+```
+your-app-name/
+├── src/
+│   ├── app/
+│   │   └── index.ts                  # Express app setup
+│   ├── routes/                       # Express route handlers
+│   │   ├── seekaAppWebhook.ts
+│   │   └── [platformWebhook].ts
+│   ├── lib/                          # Same structure as above
+│   │   └── ...
+│   └── index.ts                      # Entry point
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Example V1 Apps by Category
+
+### Server-only Apps (No Browser Plugin)
+- **activecampaign** - CRM integration with ActiveCampaign
+- **nowbookit** - Booking platform integration
+- **klaviyo-events** (early version pattern)
+
+### Apps with Browser Plugin
+- **complianz** - Cookie consent management
+- **sevenrooms** - Restaurant reservation platform
+- **tradable-bits** - Fan engagement platform
+- **transcend** - Privacy/consent management
+
+### Express-based Apps
+- **ivvy** - Event venue management (uses Express routes)
+
+## Key V1 Patterns
+
+### Installation State Management
+
+V1 apps typically manage installation state in `src/lib/state/seeka/installations.ts`:
+
+```typescript
+// src/lib/state/seeka/installations.ts
+import { createClient } 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> => {
+    // Redis-based installation lookup
+};
+
+export const saveInstallation = async (installation: AppInstallContext): Promise<void> => {
+    // Redis-based installation storage
+};
+```
+
+### Platform API Clients
+
+V1 apps organize platform-specific code in `src/lib/[platform-name]/`:
+
+```typescript
+// src/lib/active-campaign/api/index.ts
+export class ActiveCampaignClient {
+    constructor(private apiUrl: string, private apiKey: string) {}
+
+    async createContact(contact: ContactData): Promise<Contact> {
+        // API implementation
+    }
+}
+```
+
+### Browser Plugin (Nested Package)
+
+When present, the browser plugin is a nested package within `src/browser/`:
+
+```typescript
+// src/browser/src/plugin/index.ts
+export class AppBrowserPlugin {
+    constructor(config: PluginConfig) {
+        // Initialize plugin
+    }
+
+    // Plugin methods for browser-side functionality
+}
+```
+
+## When to Reference V1 Apps
+
+V1 apps contain valuable implementation patterns for:
+
+- **External API integrations**: How specific platforms (ActiveCampaign, SevenRooms, etc.) were integrated
+- **Data transformation logic**: Converting Seeka activity data to platform-specific formats
+- **Webhook handling**: Receiving and processing webhooks from external platforms
+- **Queue-based processing**: Background job patterns for async operations
+- **Redis state management**: Installation and session state patterns
+
+## Adapting V1 Patterns to V3
+
+When using V1 code as reference for a new V3 app:
+
+1. **Move shared types** from `src/lib/models/` to `app/lib/src/models/`
+2. **Move validation logic** to `app/lib/src/validation/`
+3. **Move services** from `src/lib/services/` to `app/server/src/app/services/`
+4. **Move API routes** to `app/server/src/app/api/routes/`
+5. **Use SDK utilities** from `@seeka-labs/sdk-apps-server-host` instead of custom implementations
+6. **Replace custom logging** with the SDK's winston-based logging setup
+7. **Move browser plugin** from `src/browser/` to `app/browser/`
+
+## See Also
+
+- `v2-structure.md` - V2 legacy structure (monorepo introduction)
+- `v3-structure.md` - Current template structure (use for new apps)
+- `../examples/v1/` - V1 example apps for feature reference