@seeka-labs/cli-apps 3.7.0 → 3.8.2

package/dist/ai-context/common/guides/common-patterns.md

@@ -0,0 +1,471 @@
+# Common Patterns in Seeka Apps
+
+This guide documents common implementation patterns used across Seeka apps.
+
+## External API Integration Patterns
+
+### Basic API Client Pattern
+
+```typescript
+// services/externalApiClient.ts
+import { Logger } from 'winston';
+
+export interface ApiClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeout?: number;
+}
+
+export class ExternalApiClient {
+    private config: ApiClientConfig;
+    private logger: Logger;
+
+    constructor(config: ApiClientConfig, logger: Logger) {
+        this.config = config;
+        this.logger = logger;
+    }
+
+    private async request<T>(
+        method: string,
+        endpoint: string,
+        body?: unknown
+    ): Promise<T> {
+        const url = `${this.config.baseUrl}${endpoint}`;
+
+        this.logger.debug('API request', { method, url });
+
+        const response = await fetch(url, {
+            method,
+            headers: {
+                'Authorization': `Bearer ${this.config.apiKey}`,
+                'Content-Type': 'application/json'
+            },
+            body: body ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(this.config.timeout || 30000)
+        });
+
+        if (!response.ok) {
+            const errorBody = await response.text();
+            this.logger.error('API error', {
+                status: response.status,
+                body: errorBody
+            });
+            throw new Error(`API error: ${response.status}`);
+        }
+
+        return response.json() as T;
+    }
+
+    async get<T>(endpoint: string): Promise<T> {
+        return this.request<T>('GET', endpoint);
+    }
+
+    async post<T>(endpoint: string, body: unknown): Promise<T> {
+        return this.request<T>('POST', endpoint, body);
+    }
+}
+```
+
+### OAuth Token Management
+
+```typescript
+// services/oauthTokenManager.ts
+import { Logger } from 'winston';
+import { getInstallation, updateInstallation } from '@seeka-labs/sdk-apps-server-host';
+
+interface TokenData {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+}
+
+export class OAuthTokenManager {
+    private installationId: string;
+    private logger: Logger;
+    private clientId: string;
+    private clientSecret: string;
+    private tokenUrl: string;
+
+    constructor(
+        installationId: string,
+        clientId: string,
+        clientSecret: string,
+        tokenUrl: string,
+        logger: Logger
+    ) {
+        this.installationId = installationId;
+        this.clientId = clientId;
+        this.clientSecret = clientSecret;
+        this.tokenUrl = tokenUrl;
+        this.logger = logger;
+    }
+
+    async getValidToken(): Promise<string> {
+        const installation = await getInstallation(this.installationId, true, this.logger);
+        const tokenData = installation.installationState?.tokenData as TokenData;
+
+        if (!tokenData) {
+            throw new Error('No token data found');
+        }
+
+        // Check if token is expired (with 5 min buffer)
+        if (Date.now() > tokenData.expiresAt - 300000) {
+            return this.refreshToken(tokenData.refreshToken);
+        }
+
+        return tokenData.accessToken;
+    }
+
+    private async refreshToken(refreshToken: string): Promise<string> {
+        this.logger.info('Refreshing OAuth token');
+
+        const response = await fetch(this.tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                grant_type: 'refresh_token',
+                refresh_token: refreshToken,
+                client_id: this.clientId,
+                client_secret: this.clientSecret
+            })
+        });
+
+        if (!response.ok) {
+            throw new Error('Failed to refresh token');
+        }
+
+        const data = await response.json();
+
+        // Update stored tokens
+        const installation = await getInstallation(this.installationId, true, this.logger);
+        installation.installationState = {
+            ...installation.installationState,
+            tokenData: {
+                accessToken: data.access_token,
+                refreshToken: data.refresh_token || refreshToken,
+                expiresAt: Date.now() + (data.expires_in * 1000)
+            }
+        };
+        await updateInstallation(installation, this.logger);
+
+        return data.access_token;
+    }
+}
+```
+
+## Data Transformation Patterns
+
+### Activity to Platform Event Mapping
+
+```typescript
+// services/dataMapper.ts
+import { SeekaActivityAcceptedWebhookPayload } from '@seeka-labs/sdk-apps-server';
+
+interface PlatformEvent {
+    event_name: string;
+    event_time: number;
+    user_data: {
+        em?: string[];  // hashed emails
+        ph?: string[];  // hashed phones
+    };
+    custom_data: Record<string, unknown>;
+}
+
+export const mapActivityToPlatformEvent = (
+    activity: SeekaActivityAcceptedWebhookPayload['content']
+): PlatformEvent => {
+    return {
+        event_name: mapActivityName(activity.activity.activityName),
+        event_time: Math.floor(new Date(activity.activity.timestamp).getTime() / 1000),
+        user_data: {
+            em: activity.person?.emailHashed ? [activity.person.emailHashed] : undefined,
+            ph: activity.person?.phoneHashed ? [activity.person.phoneHashed] : undefined
+        },
+        custom_data: {
+            currency: activity.activity.properties?.currency,
+            value: activity.activity.properties?.value,
+            content_ids: activity.activity.properties?.productIds
+        }
+    };
+};
+
+const mapActivityName = (seekaActivityName: string): string => {
+    const mapping: Record<string, string> = {
+        'PageView': 'ViewContent',
+        'Purchase': 'Purchase',
+        'AddToCart': 'AddToCart',
+        'Lead': 'Lead',
+        'SignUp': 'CompleteRegistration'
+    };
+    return mapping[seekaActivityName] || seekaActivityName;
+};
+```
+
+### Batch Processing Pattern
+
+```typescript
+// services/batchProcessor.ts
+import { Logger } from 'winston';
+
+interface BatchConfig {
+    maxBatchSize: number;
+    maxWaitMs: number;
+}
+
+export class BatchProcessor<T> {
+    private batch: T[] = [];
+    private timer: NodeJS.Timeout | null = null;
+    private config: BatchConfig;
+    private logger: Logger;
+    private processFn: (items: T[]) => Promise<void>;
+
+    constructor(
+        config: BatchConfig,
+        processFn: (items: T[]) => Promise<void>,
+        logger: Logger
+    ) {
+        this.config = config;
+        this.processFn = processFn;
+        this.logger = logger;
+    }
+
+    async add(item: T): Promise<void> {
+        this.batch.push(item);
+
+        if (this.batch.length >= this.config.maxBatchSize) {
+            await this.flush();
+        } else if (!this.timer) {
+            this.timer = setTimeout(() => this.flush(), this.config.maxWaitMs);
+        }
+    }
+
+    async flush(): Promise<void> {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+
+        if (this.batch.length === 0) return;
+
+        const items = [...this.batch];
+        this.batch = [];
+
+        this.logger.info('Processing batch', { count: items.length });
+        await this.processFn(items);
+    }
+}
+```
+
+## Error Handling Patterns
+
+### Retry with Exponential Backoff
+
+```typescript
+// utils/retry.ts
+import { Logger } from 'winston';
+
+interface RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+}
+
+export const withRetry = async <T>(
+    fn: () => Promise<T>,
+    config: RetryConfig,
+    logger: Logger
+): Promise<T> => {
+    let lastError: Error | null = null;
+
+    for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+        try {
+            return await fn();
+        } catch (error) {
+            lastError = error as Error;
+
+            if (attempt === config.maxRetries) {
+                logger.error('All retry attempts failed', {
+                    error: lastError.message,
+                    attempts: attempt + 1
+                });
+                throw lastError;
+            }
+
+            const delay = Math.min(
+                config.baseDelayMs * Math.pow(2, attempt),
+                config.maxDelayMs
+            );
+
+            logger.warn('Retrying after error', {
+                attempt: attempt + 1,
+                delay,
+                error: lastError.message
+            });
+
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+
+    throw lastError;
+};
+```
+
+### Error Classification
+
+```typescript
+// utils/errors.ts
+export class RetryableError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'RetryableError';
+    }
+}
+
+export class PermanentError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'PermanentError';
+    }
+}
+
+export const classifyApiError = (status: number, body: string): Error => {
+    // Rate limited - retry
+    if (status === 429) {
+        return new RetryableError('Rate limited');
+    }
+
+    // Server errors - retry
+    if (status >= 500) {
+        return new RetryableError(`Server error: ${status}`);
+    }
+
+    // Client errors - don't retry
+    if (status >= 400) {
+        return new PermanentError(`Client error: ${status} - ${body}`);
+    }
+
+    return new Error(`Unknown error: ${status}`);
+};
+```
+
+## Logging Patterns
+
+### Structured Logging
+
+```typescript
+// Always include context in logs
+logger.info('Processing activity', {
+    activityId: activity.activityId,
+    activityName: activity.activityName,
+    installationId: installation.applicationInstallId
+});
+
+// Log errors with full context
+logger.error('Failed to send event', {
+    error: error.message,
+    stack: error.stack,
+    activityId: activity.activityId,
+    endpoint: apiEndpoint
+});
+
+// Use log levels appropriately
+logger.debug('Detailed debug info');  // Development only
+logger.verbose('Verbose operation info');  // Detailed but not debug
+logger.info('Normal operation');  // Standard operations
+logger.warn('Warning condition');  // Potential issues
+logger.error('Error occurred');  // Actual errors
+```
+
+### Performance Logging
+
+```typescript
+// Use profiling for performance tracking
+logger.profile('external-api-call');
+await externalApi.sendEvent(data);
+logger.profile('external-api-call');  // Logs duration
+```
+
+## Queue Processing Patterns
+
+### Idempotent Processing
+
+```typescript
+// Ensure operations can be safely retried
+const processQueueItem = async (item: QueueItem, logger: Logger) => {
+    // Check if already processed
+    const existing = await checkIfProcessed(item.id);
+    if (existing) {
+        logger.info('Item already processed, skipping', { id: item.id });
+        return;
+    }
+
+    // Process the item
+    await doProcessing(item);
+
+    // Mark as processed
+    await markAsProcessed(item.id);
+};
+```
+
+### Dead Letter Handling
+
+```typescript
+// Handle items that fail repeatedly
+const processWithDeadLetter = async (
+    item: QueueItem,
+    logger: Logger
+): Promise<void> => {
+    try {
+        await processItem(item);
+    } catch (error) {
+        if (item.dequeueCount >= 5) {
+            logger.error('Moving to dead letter queue', {
+                id: item.id,
+                dequeueCount: item.dequeueCount,
+                error: error.message
+            });
+            await moveToDeadLetter(item, error);
+        } else {
+            throw error;  // Will be retried
+        }
+    }
+};
+```
+
+## Configuration Patterns
+
+### Environment-Based Configuration
+
+```typescript
+// config/index.ts
+export const config = {
+    seeka: {
+        appId: process.env.SEEKA_APP_ID!,
+        appSecret: process.env.SEEKA_APP_SECRET!
+    },
+    external: {
+        apiKey: process.env.EXTERNAL_API_KEY!,
+        baseUrl: process.env.EXTERNAL_API_URL || 'https://api.external.com'
+    },
+    features: {
+        enableBatching: process.env.ENABLE_BATCHING === 'true',
+        batchSize: parseInt(process.env.BATCH_SIZE || '100', 10)
+    }
+};
+
+// Validate required config on startup
+export const validateConfig = () => {
+    const required = ['SEEKA_APP_ID', 'SEEKA_APP_SECRET', 'EXTERNAL_API_KEY'];
+    const missing = required.filter(key => !process.env[key]);
+
+    if (missing.length > 0) {
+        throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
+    }
+};
+```
+
+## See Also
+
+- `getting-started.md` - Initial setup guide
+- `data-flow.md` - Data flow patterns
+- `../examples/` - Complete example implementations