@seeka-labs/cli-apps 3.7.0 → 3.8.2

package/dist/ai-context/common/guides/getting-started.md

@@ -0,0 +1,349 @@
+# Getting Started: Extending Your Seeka App
+
+This guide explains how to extend a scaffolded Seeka app to add custom functionality.
+
+## Prerequisites
+
+- A scaffolded Seeka app (created via `npx @seeka-labs/cli-apps init`)
+- Node.js 18+ installed
+- Yarn package manager
+- Azure Functions Core Tools (for local development)
+
+## Understanding the Scaffolded App
+
+After scaffolding, your app has these key areas to extend:
+
+| Area | Location | Purpose |
+|------|----------|---------|
+| Webhook handling | `app/server/src/functions/seekaAppWebhook.ts` | Process Seeka events |
+| Business logic | `app/server/src/app/services/` | External API integrations |
+| Data models | `app/lib/src/models/` | Shared TypeScript interfaces |
+| Settings validation | `app/lib/src/validation/` | Validate installation settings |
+| Background jobs | `app/server/src/app/jobs/` | Async processing |
+
+## Step 1: Define Your Data Models
+
+Start by defining the data structures your app will use.
+
+### Installation Settings
+
+Edit `app/lib/src/models/index.ts` to define settings users will configure:
+
+```typescript
+export interface YourAppInstallationSettings {
+    // Required settings
+    apiKey: string;
+    accountId: string;
+
+    // Optional settings
+    enableFeatureX?: boolean;
+    customMapping?: Record<string, string>;
+}
+```
+
+### Installation Context
+
+The installation context stores the full state:
+
+```typescript
+export interface YourAppInstallContext {
+    applicationInstallId: string;
+    organisationId: string;
+    organisationBrandId: string;
+    installedAt: string;
+    installationState?: {
+        grantedPermissions: string[];
+        installationSettings: YourAppInstallationSettings;
+    };
+}
+```
+
+## Step 2: Add Settings Validation
+
+Edit `app/lib/src/validation/index.ts` to validate settings on installation:
+
+```typescript
+import { Logger } from 'winston';
+import { YourAppInstallationSettings } from '../models';
+
+export const validateInstallationSettings = async (
+    settings: YourAppInstallationSettings,
+    logger: Logger
+): Promise<string | null> => {
+    // Return error message string if invalid, null if valid
+
+    if (!settings.apiKey) {
+        return 'API Key is required';
+    }
+
+    if (!settings.accountId) {
+        return 'Account ID is required';
+    }
+
+    // Optionally validate API key works
+    try {
+        const isValid = await testApiConnection(settings.apiKey, settings.accountId);
+        if (!isValid) {
+            return 'Invalid API credentials';
+        }
+    } catch (error) {
+        logger.error('Failed to validate API credentials', { error });
+        return 'Failed to validate API credentials';
+    }
+
+    return null; // Valid
+};
+```
+
+## Step 3: Create Your Service Layer
+
+Add services in `app/server/src/app/services/` for external integrations:
+
+```typescript
+// app/server/src/app/services/externalPlatform.ts
+import { Logger } from 'winston';
+
+export interface ExternalPlatformConfig {
+    apiKey: string;
+    accountId: string;
+}
+
+export class ExternalPlatformService {
+    private config: ExternalPlatformConfig;
+    private logger: Logger;
+
+    constructor(config: ExternalPlatformConfig, logger: Logger) {
+        this.config = config;
+        this.logger = logger;
+    }
+
+    async sendEvent(eventData: any): Promise<boolean> {
+        this.logger.debug('Sending event to external platform', { eventData });
+
+        try {
+            const response = await fetch('https://api.external-platform.com/events', {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.config.apiKey}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    account_id: this.config.accountId,
+                    ...eventData
+                })
+            });
+
+            if (!response.ok) {
+                this.logger.error('External API error', {
+                    status: response.status,
+                    body: await response.text()
+                });
+                return false;
+            }
+
+            return true;
+        } catch (error) {
+            this.logger.error('Failed to send event', { error });
+            throw error;
+        }
+    }
+}
+```
+
+## Step 4: Handle Activity Events
+
+The main place to add your logic is in the activity handler. Edit `app/server/src/app/services/activities.ts`:
+
+```typescript
+import { Logger } from 'winston';
+import { SeekaActivityAcceptedWebhookPayload } from '@seeka-labs/sdk-apps-server';
+import { YourAppInstallContext } from '@your-org/your-app-lib';
+import { ExternalPlatformService } from './externalPlatform';
+
+export const processActivity = async (
+    activity: SeekaActivityAcceptedWebhookPayload['content'],
+    installation: YourAppInstallContext,
+    logger: Logger
+): Promise<void> => {
+    const settings = installation.installationState?.installationSettings;
+    if (!settings) {
+        logger.warn('No installation settings found');
+        return;
+    }
+
+    // Initialize your service
+    const service = new ExternalPlatformService({
+        apiKey: settings.apiKey,
+        accountId: settings.accountId
+    }, logger);
+
+    // Transform Seeka activity to external format
+    const eventData = {
+        event_name: activity.activity.activityName,
+        event_id: activity.activity.activityId,
+        timestamp: activity.activity.timestamp,
+        user_data: {
+            email: activity.person?.email,
+            phone: activity.person?.phone
+        },
+        custom_data: activity.activity.properties
+    };
+
+    // Send to external platform
+    await service.sendEvent(eventData);
+
+    logger.info('Activity processed successfully', {
+        activityId: activity.activity.activityId
+    });
+};
+```
+
+## Step 5: Wire Up the Queue Handler
+
+Edit `app/server/src/functions/trackActivityQueueHandler.ts` to use your service:
+
+```typescript
+import { app, InvocationContext } from '@azure/functions';
+import { tryGetInstallation, startServices, childLogger } from '@seeka-labs/sdk-apps-server-host';
+import { TrackActivityQueueItem } from '../app/models';
+import { processActivity } from '../app/services/activities';
+import { queueNames } from '../app/jobs';
+
+app.storageQueue('trackActivityQueueHandler', {
+    queueName: queueNames.trackActivity,
+    connection: 'AzureWebJobsStorage',
+    handler: async (item: TrackActivityQueueItem, context: InvocationContext) => {
+        let logger = childLogger({}, null, null, context);
+
+        await startServices(logger);
+
+        const installation = await tryGetInstallation(
+            item.applicationInstallId,
+            true,
+            logger
+        );
+
+        if (!installation) {
+            logger.error('Installation not found', {
+                applicationInstallId: item.applicationInstallId
+            });
+            return;
+        }
+
+        logger = childLogger({}, installation, logger, context);
+
+        await processActivity(item.payload, installation, logger);
+    }
+});
+```
+
+## Step 6: Local Development
+
+### Set Up Environment
+
+1. Copy the template settings:
+   ```bash
+   cp app/server/local.settings.template.json app/server/local.settings.json
+   ```
+
+2. Fill in your environment variables in `local.settings.json`
+
+### Run Locally
+
+```bash
+# Install dependencies
+yarn install
+
+# Build all packages
+yarn build
+
+# Start the function app
+cd app/server
+yarn dev
+```
+
+### Test with ngrok
+
+```bash
+# Expose local server
+ngrok http 7071
+
+# Use the ngrok URL in Seeka app configuration
+```
+
+## Step 7: Add Tests
+
+Create tests in `app/server/src/app/services/__tests__/`:
+
+```typescript
+// externalPlatform.test.ts
+import { ExternalPlatformService } from '../externalPlatform';
+
+describe('ExternalPlatformService', () => {
+    it('should send event successfully', async () => {
+        // Mock fetch
+        global.fetch = jest.fn().mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({ success: true })
+        });
+
+        const service = new ExternalPlatformService({
+            apiKey: 'test-key',
+            accountId: 'test-account'
+        }, mockLogger);
+
+        const result = await service.sendEvent({ test: 'data' });
+
+        expect(result).toBe(true);
+        expect(fetch).toHaveBeenCalledWith(
+            'https://api.external-platform.com/events',
+            expect.objectContaining({
+                method: 'POST'
+            })
+        );
+    });
+});
+```
+
+## Common Extension Patterns
+
+### Adding a New Webhook Type Handler
+
+In `seekaAppWebhook.ts`, add a case to the switch statement:
+
+```typescript
+case SeekaWebhookCallType.YourNewType: {
+    const payload = body as YourNewTypePayload;
+    await handleYourNewType(payload, installation, logger);
+    break;
+}
+```
+
+### Adding a New API Endpoint
+
+Create a new route in `app/server/src/app/api/routes/`:
+
+```typescript
+// yourNewEndpoint.ts
+import { HttpRequest, HttpResponseInit } from '@azure/functions';
+import { Logger } from 'winston';
+
+export const yourNewEndpoint = async (
+    req: HttpRequest,
+    logger: Logger
+): Promise<HttpResponseInit> => {
+    // Your logic here
+    return {
+        status: 200,
+        jsonBody: { success: true }
+    };
+};
+```
+
+Then register it in `router.ts`.
+
+## Next Steps
+
+- See `common-patterns.md` for more implementation patterns
+- See `data-flow.md` for understanding data flow
+- See `../examples/` for complete example implementations