@seeka-labs/cli-apps 3.8.10 → 3.9.1

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

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