@donotdev/functions 0.0.10 → 0.0.12

package/src/supabase/registerCrudFunctions.ts

@@ -0,0 +1,180 @@
+// packages/functions/src/supabase/registerCrudFunctions.ts
+
+/**
+ * @fileoverview Auto-register CRUD handlers from entities for Supabase Edge Functions
+ * @description Utility to automatically generate CRUD Edge Function handlers for all entities
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import { createSchemas, getListCardFieldNames } from '@donotdev/core/server';
+import type { Entity } from '@donotdev/core/server';
+
+import {
+  createSupabaseGetEntity,
+  createSupabaseCreateEntity,
+  createSupabaseUpdateEntity,
+  createSupabaseDeleteEntity,
+  createSupabaseListEntities,
+  createSupabaseAggregateEntities,
+} from './crud/index.js';
+
+type SupabaseHandler = (req: Request) => Promise<Response>;
+
+interface CrudHandlers {
+  handlers: Record<string, SupabaseHandler>;
+  serve: (req: Request) => Promise<Response>;
+}
+
+/**
+ * Create CRUD handlers for all entities (Supabase Edge Functions)
+ * Returns handlers object + serve dispatcher function
+ *
+ * @param entities - Object of { key: Entity } (from `import * as entities from 'entities'`)
+ * @returns Object with handlers and serve dispatcher
+ *
+ * @example
+ * ```typescript
+ * import * as entities from '../_shared/entities.ts';
+ * import { createSupabaseCrudFunctions } from '@donotdev/functions/supabase';
+ *
+ * const { serve } = createSupabaseCrudFunctions(entities);
+ * Deno.serve(serve);
+ * ```
+ */
+export function createSupabaseCrudFunctions(
+  entities: Record<string, Entity | unknown>
+): CrudHandlers {
+  const handlers: Record<string, SupabaseHandler> = {};
+
+  for (const [key, value] of Object.entries(entities)) {
+    if (!isEntity(value)) continue;
+
+    const entity = value as Entity;
+    const col = entity.collection;
+    const schemas = createSchemas(entity);
+    const access = entity.access;
+
+    handlers[`create_${col}`] = createSupabaseCreateEntity(
+      col,
+      schemas.create,
+      access.create
+    );
+    handlers[`get_${col}`] = createSupabaseGetEntity(
+      col,
+      schemas.get,
+      access.read,
+      entity.ownership
+    );
+    handlers[`list_${col}`] = createSupabaseListEntities(
+      col,
+      schemas.get,
+      access.read,
+      entity.listFields,
+      entity.ownership,
+      false
+    );
+    handlers[`listCard_${col}`] = createSupabaseListEntities(
+      col,
+      schemas.get,
+      access.read,
+      getListCardFieldNames(entity),
+      entity.ownership,
+      true
+    );
+    handlers[`update_${col}`] = createSupabaseUpdateEntity(
+      col,
+      schemas.update,
+      access.update
+    );
+    
+    // Extract reference metadata from entity if available
+    const schemaWithMeta = schemas.get as {
+      metadata?: {
+        references?: {
+          outgoing?: Array<{
+            field: string;
+            targetCollection: string;
+            required?: boolean;
+          }>;
+          incoming?: Array<{
+            sourceCollection: string;
+            sourceField: string;
+            required?: boolean;
+          }>;
+        };
+      };
+    };
+    const referenceMetadata = schemaWithMeta.metadata?.references;
+    
+    handlers[`delete_${col}`] = createSupabaseDeleteEntity(
+      col,
+      access.delete,
+      referenceMetadata
+    );
+    handlers[`aggregate_${col}`] = createSupabaseAggregateEntities(
+      col,
+      schemas.get,
+      access.read
+    );
+  }
+
+  /**
+   * Serve dispatcher: reads _functionName from request body, routes to correct handler
+   */
+  const serve = async (req: Request): Promise<Response> => {
+    try {
+      const body = await req.json().catch(() => ({}));
+      const functionName = (body as Record<string, unknown>)._functionName as string;
+
+      if (!functionName) {
+        return new Response(
+          JSON.stringify({ error: 'Missing _functionName in request body' }),
+          { status: 400, headers: { 'Content-Type': 'application/json' } }
+        );
+      }
+
+      const handler = handlers[functionName];
+      if (!handler) {
+        return new Response(
+          JSON.stringify({ error: `Unknown function: ${functionName}` }),
+          { status: 404, headers: { 'Content-Type': 'application/json' } }
+        );
+      }
+
+      // Remove _functionName from body before passing to handler
+      const { _functionName, ...handlerData } = body as Record<string, unknown>;
+      
+      // Create new request with cleaned body
+      const handlerReq = new Request(req.url, {
+        method: req.method,
+        headers: req.headers,
+        body: JSON.stringify(handlerData),
+      });
+
+      return handler(handlerReq);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Internal server error';
+      return new Response(
+        JSON.stringify({ error: message }),
+        { status: 500, headers: { 'Content-Type': 'application/json' } }
+      );
+    }
+  };
+
+  return { handlers, serve };
+}
+
+/**
+ * Type guard to check if a value is an Entity
+ */
+function isEntity(value: unknown): value is Entity {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'collection' in value &&
+    'fields' in value
+  );
+}

package/src/supabase/utils/idempotency.ts

@@ -0,0 +1,141 @@
+// packages/functions/src/supabase/utils/idempotency.ts
+
+/**
+ * @fileoverview Idempotency utilities for Supabase Edge Functions
+ * @description Provides idempotency checking and storage using Postgres table
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import type { SupabaseClient } from '@supabase/supabase-js';
+
+/**
+ * Default TTL for idempotency records (24 hours)
+ */
+const DEFAULT_TTL_HOURS = 24;
+
+/**
+ * TTL per operation type (hours)
+ */
+const OPERATION_TTL: Record<string, number> = {
+  create: 24,
+  update: 12,
+  delete: 1,
+  default: 24,
+};
+
+/**
+ * Check if an operation has already been processed (idempotency check)
+ *
+ * @param supabaseAdmin - Supabase admin client
+ * @param idempotencyKey - Client-provided idempotency key
+ * @param operation - Operation name (e.g., 'create', 'update')
+ * @returns Cached result if found, null otherwise
+ */
+export async function checkIdempotency<T>(
+  supabaseAdmin: SupabaseClient,
+  idempotencyKey: string,
+  operation: string
+): Promise<T | null> {
+  try {
+    const id = `${operation}_${idempotencyKey}`;
+
+    const { data, error } = await supabaseAdmin
+      .from('idempotency')
+      .select('result')
+      .eq('idempotency_key', idempotencyKey)
+      .eq('operation', operation)
+      .gt('expires_at', new Date().toISOString())
+      .single();
+
+    if (error || !data) {
+      return null;
+    }
+
+    return data.result as T;
+  } catch (error) {
+    // Fail open - allow the operation if idempotency check fails
+    console.error('[idempotency] Check failed:', error);
+    return null;
+  }
+}
+
+/**
+ * Store the result of an operation for idempotency
+ *
+ * @param supabaseAdmin - Supabase admin client
+ * @param idempotencyKey - Client-provided idempotency key
+ * @param operation - Operation name (e.g., 'create', 'update')
+ * @param result - Operation result to cache
+ * @param uid - User ID who processed the operation
+ * @param ttlHours - Optional TTL override (defaults to operation-specific TTL)
+ */
+export async function storeIdempotency<T>(
+  supabaseAdmin: SupabaseClient,
+  idempotencyKey: string,
+  operation: string,
+  result: T,
+  uid: string,
+  ttlHours?: number
+): Promise<void> {
+  try {
+    const id = `${operation}_${idempotencyKey}`;
+    const ttl = ttlHours ?? OPERATION_TTL[operation] ?? OPERATION_TTL.default;
+    const expiresAt = new Date();
+    expiresAt.setHours(expiresAt.getHours() + ttl);
+
+    const { error } = await supabaseAdmin
+      .from('idempotency')
+      .upsert(
+        {
+          id,
+          operation,
+          idempotency_key: idempotencyKey,
+          result: result as any,
+          processed_by: uid,
+          expires_at: expiresAt.toISOString(),
+        },
+        {
+          onConflict: 'idempotency_key',
+        }
+      );
+
+    if (error) {
+      console.error('[idempotency] Store failed:', error);
+      // Don't throw - idempotency storage failure shouldn't break the operation
+    }
+  } catch (error) {
+    console.error('[idempotency] Store failed:', error);
+    // Don't throw - idempotency storage failure shouldn't break the operation
+  }
+}
+
+/**
+ * Clean up expired idempotency records
+ *
+ * @param supabaseAdmin - Supabase admin client
+ * @returns Number of deleted records
+ */
+export async function cleanupExpiredIdempotency(
+  supabaseAdmin: SupabaseClient
+): Promise<number> {
+  try {
+    const { data, error } = await supabaseAdmin
+      .from('idempotency')
+      .delete()
+      .lt('expires_at', new Date().toISOString())
+      .select('id');
+
+    if (error) {
+      console.error('[idempotency] Cleanup failed:', error);
+      return 0;
+    }
+
+    return data?.length ?? 0;
+  } catch (error) {
+    console.error('[idempotency] Cleanup failed:', error);
+    return 0;
+  }
+}

package/src/supabase/utils/monitoring.ts

@@ -0,0 +1,187 @@
+// packages/functions/src/supabase/utils/monitoring.ts
+
+/**
+ * @fileoverview Monitoring and metrics utilities for Supabase Edge Functions
+ * @description Provides metrics collection and analytics queries using Postgres table
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import type { SupabaseClient } from '@supabase/supabase-js';
+
+/**
+ * Operation metrics data structure
+ */
+export interface OperationMetrics {
+  operation: string;
+  userId?: string;
+  status: 'success' | 'failed' | 'pending';
+  durationMs?: number;
+  metadata?: Record<string, any>;
+  errorCode?: string;
+  errorMessage?: string;
+}
+
+/**
+ * Record operation metrics for monitoring
+ *
+ * @param supabaseAdmin - Supabase admin client
+ * @param metrics - Operation metrics to record
+ */
+export async function recordOperationMetrics(
+  supabaseAdmin: SupabaseClient,
+  metrics: OperationMetrics
+): Promise<void> {
+  try {
+    const { error } = await supabaseAdmin.from('operation_metrics').insert({
+      operation: metrics.operation,
+      user_id: metrics.userId || null,
+      status: metrics.status,
+      duration_ms: metrics.durationMs || null,
+      metadata: metrics.metadata || null,
+      error_code: metrics.errorCode || null,
+      error_message: metrics.errorMessage || null,
+    });
+
+    if (error) {
+      console.error('[monitoring] Record failed:', error);
+      // Don't throw - metrics failure shouldn't break the operation
+    }
+  } catch (error) {
+    console.error('[monitoring] Record failed:', error);
+    // Don't throw - metrics failure shouldn't break the operation
+  }
+}
+
+/**
+ * Get failure rate for an operation
+ *
+ * @param supabaseAdmin - Supabase admin client
+ * @param operation - Operation name
+ * @param hours - Time window in hours (default: 24)
+ * @returns Failure rate (0-100)
+ */
+export async function getFailureRate(
+  supabaseAdmin: SupabaseClient,
+  operation: string,
+  hours: number = 24
+): Promise<number> {
+  try {
+    const cutoffTime = new Date();
+    cutoffTime.setHours(cutoffTime.getHours() - hours);
+
+    const { data, error } = await supabaseAdmin
+      .from('operation_metrics')
+      .select('status')
+      .eq('operation', operation)
+      .gte('timestamp', cutoffTime.toISOString());
+
+    if (error || !data || data.length === 0) {
+      return 0;
+    }
+
+    const failed = data.filter((m) => m.status === 'failed').length;
+    return (failed / data.length) * 100;
+  } catch (error) {
+    console.error('[monitoring] Get failure rate failed:', error);
+    return 0;
+  }
+}
+
+/**
+ * Get operation counts by user
+ *
+ * @param supabaseAdmin - Supabase admin client
+ * @param userId - User ID
+ * @param hours - Time window in hours (default: 24)
+ * @returns Record of operation names to counts
+ */
+export async function getOperationCounts(
+  supabaseAdmin: SupabaseClient,
+  userId: string,
+  hours: number = 24
+): Promise<Record<string, number>> {
+  try {
+    const cutoffTime = new Date();
+    cutoffTime.setHours(cutoffTime.getHours() - hours);
+
+    const { data, error } = await supabaseAdmin
+      .from('operation_metrics')
+      .select('operation')
+      .eq('user_id', userId)
+      .gte('timestamp', cutoffTime.toISOString());
+
+    if (error || !data) {
+      return {};
+    }
+
+    const counts: Record<string, number> = {};
+    for (const metric of data) {
+      counts[metric.operation] = (counts[metric.operation] || 0) + 1;
+    }
+
+    return counts;
+  } catch (error) {
+    console.error('[monitoring] Get operation counts failed:', error);
+    return {};
+  }
+}
+
+/**
+ * Get slow operations (above threshold)
+ *
+ * @param supabaseAdmin - Supabase admin client
+ * @param thresholdMs - Duration threshold in milliseconds
+ * @param hours - Time window in hours (default: 24)
+ * @returns Array of operations with average duration
+ */
+export async function getSlowOperations(
+  supabaseAdmin: SupabaseClient,
+  thresholdMs: number,
+  hours: number = 24
+): Promise<Array<{ operation: string; avgDuration: number; count: number }>> {
+  try {
+    const cutoffTime = new Date();
+    cutoffTime.setHours(cutoffTime.getHours() - hours);
+
+    const { data, error } = await supabaseAdmin
+      .from('operation_metrics')
+      .select('operation, duration_ms')
+      .gte('timestamp', cutoffTime.toISOString())
+      .not('duration_ms', 'is', null);
+
+    if (error || !data) {
+      return [];
+    }
+
+    // Group by operation and calculate average
+    const grouped: Record<string, { sum: number; count: number }> = {};
+    for (const metric of data) {
+      if (!metric.duration_ms) continue;
+      if (!grouped[metric.operation]) {
+        grouped[metric.operation] = { sum: 0, count: 0 };
+      }
+      grouped[metric.operation].sum += metric.duration_ms;
+      grouped[metric.operation].count += 1;
+    }
+
+    const results: Array<{ operation: string; avgDuration: number; count: number }> = [];
+    for (const [operation, stats] of Object.entries(grouped)) {
+      const avgDuration = stats.sum / stats.count;
+      if (avgDuration >= thresholdMs) {
+        results.push({
+          operation,
+          avgDuration: Math.round(avgDuration),
+          count: stats.count,
+        });
+      }
+    }
+
+    return results.sort((a, b) => b.avgDuration - a.avgDuration);
+  } catch (error) {
+    console.error('[monitoring] Get slow operations failed:', error);
+    return [];
+  }
+}