@donotdev/functions 0.0.10 → 0.0.11

package/src/supabase/crud/list.ts

@@ -0,0 +1,357 @@
+// packages/functions/src/supabase/crud/list.ts
+
+/**
+ * @fileoverview Generic handler to list entities from Supabase with pagination, filtering, and sorting.
+ * @description Provides a reusable implementation for listing documents from PostgreSQL with advanced query capabilities.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import * as v from 'valibot';
+
+import {
+  filterVisibleFields,
+  hasRoleAccess,
+  HIDDEN_STATUSES,
+} from '@donotdev/core/server';
+import type {
+  EntityOwnershipConfig,
+  EntityOwnershipPublicCondition,
+  UserRole,
+} from '@donotdev/core/server';
+
+import { defaultFieldMapper } from '@donotdev/supabase';
+
+import { DoNotDevError } from '../../shared/utils.js';
+import { createSupabaseHandler } from '../baseFunction.js';
+
+/** Field mapper: app (camelCase) ↔ backend (snake_case). Single boundary for list handler. */
+const mapper = defaultFieldMapper;
+
+/** Ensure we only pass strings to the mapper (entity listFields/ownership can be mis-typed at runtime). */
+function toBackendColumn(field: unknown): string {
+  return mapper.toBackendField(typeof field === 'string' ? field : String(field));
+}
+
+export interface ListEntityRequest {
+  where?: Array<[string, any, any]>;
+  orderBy?: Array<[string, 'asc' | 'desc']>;
+  limit?: number;
+  startAfterId?: string; // Offset-based pagination (legacy)
+  startAfterCursor?: string; // Keyset pagination (cursor-based)
+  search?: {
+    field: string;
+    query: string;
+  };
+}
+
+/**
+ * Encode cursor for keyset pagination
+ */
+function encodeCursor(id: string, orderBy: Record<string, any>): string {
+  const cursor = { id, orderBy };
+  return Buffer.from(JSON.stringify(cursor)).toString('base64');
+}
+
+/**
+ * Decode cursor for keyset pagination
+ */
+function decodeCursor(cursor: string): { id: string; orderBy: Record<string, any> } {
+  try {
+    return JSON.parse(Buffer.from(cursor, 'base64').toString());
+  } catch (error) {
+    throw new DoNotDevError('Invalid cursor format', 'invalid-argument');
+  }
+}
+
+/** Apply operator; column must already be backend (snake_case) name. */
+function applyOperator(
+  query: any,
+  column: string,
+  operator: string,
+  value: any
+): any {
+  switch (operator) {
+    case '==':
+      return query.eq(column, value);
+    case '!=':
+      return query.neq(column, value);
+    case '>':
+      return query.gt(column, value);
+    case '>=':
+      return query.gte(column, value);
+    case '<':
+      return query.lt(column, value);
+    case '<=':
+      return query.lte(column, value);
+    case 'in':
+      return query.in(column, Array.isArray(value) ? value : [value]);
+    case 'not-in':
+      return query.not(column, 'in', Array.isArray(value) ? value : [value]);
+    case 'array-contains':
+      return query.contains(column, [value]);
+    case 'array-contains-any':
+      return query.contains(column, Array.isArray(value) ? value : [value]);
+    default:
+      return query.eq(column, value);
+  }
+}
+
+function applyPublicCondition(
+  query: any,
+  publicCondition: EntityOwnershipPublicCondition[]
+): any {
+  let q = query;
+  for (const c of publicCondition) {
+    q = applyOperator(q, toBackendColumn(c.field), c.op, c.value);
+  }
+  return q;
+}
+
+/**
+ * Create a Supabase Edge Function handler for listing entities.
+ *
+ * @param collection - The Supabase table name
+ * @param documentSchema - The Valibot schema for document validation
+ * @param requiredRole - Minimum role required for this operation
+ * @param listFields - Optional array of field names to include (plus id)
+ * @param ownership - Optional ownership config for list constraints and visibility: 'owner' masking
+ * @param isListCard - When true and ownership is set, applies public condition; when false, applies "mine" filter
+ * @returns A `(req: Request) => Promise<Response>` handler for Deno.serve
+ */
+export function createSupabaseListEntities(
+  collection: string,
+  documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
+  requiredRole: UserRole,
+  listFields?: string[],
+  ownership?: EntityOwnershipConfig,
+  isListCard?: boolean
+) {
+  const requestSchema = v.object({
+    where: v.optional(v.array(v.tuple([v.string(), v.any(), v.any()]))),
+    orderBy: v.optional(
+      v.array(v.tuple([v.pipe(v.string(), v.minLength(1)), v.picklist(['asc', 'desc'])]))
+    ),
+    limit: v.optional(v.pipe(v.number(), v.minValue(1))),
+    startAfterId: v.optional(v.string()), // Offset-based (legacy)
+    startAfterCursor: v.optional(v.string()), // Keyset pagination
+    search: v.optional(
+      v.object({
+        field: v.string(),
+        query: v.string(),
+      })
+    ),
+  });
+
+  return createSupabaseHandler(
+    isListCard ? `listCard_${collection}` : `list_${collection}`,
+    requestSchema,
+    async (data: ListEntityRequest, ctx) => {
+      const { where = [], orderBy = [], limit = 50, startAfterId, startAfterCursor, search } = data;
+      const { userRole, uid, supabaseAdmin } = ctx;
+
+      const isAdmin = hasRoleAccess(userRole, 'admin');
+
+      // Build query - select fields (listFields + id + status, or *). Only use string entries (entity may be mis-typed).
+      const safeListFields = listFields?.filter((f): f is string => typeof f === 'string');
+      const selectFields = safeListFields && safeListFields.length > 0
+        ? safeListFields.map((f) => toBackendColumn(f)).join(', ') + ', id, status'
+        : '*';
+      
+      let query = supabaseAdmin.from(collection).select(selectFields, { count: 'exact' });
+
+      // Filter out hidden statuses for non-admin users
+      if (!isAdmin) {
+        query = query.not('status', 'in', [...HIDDEN_STATUSES]);
+      }
+
+      // Ownership: when set and not admin, listCard = public condition, list = mine filter
+      if (ownership && !isAdmin) {
+        if (
+          isListCard &&
+          ownership.publicCondition &&
+          ownership.publicCondition.length > 0
+        ) {
+          query = applyPublicCondition(query, ownership.publicCondition);
+        } else if (!isListCard && ownership.ownerFields.length > 0) {
+          const firstOwnerField = ownership.ownerFields[0];
+          query = query.eq(toBackendColumn(firstOwnerField), uid);
+        }
+      }
+
+      if (search) {
+        query = query.ilike(toBackendColumn(search.field), `%${search.query}%`);
+      }
+
+      for (const [field, operator, value] of where) {
+        query = applyOperator(query, toBackendColumn(field), operator, value);
+      }
+
+      const hasIdInOrderBy = orderBy.some(([field]) => toBackendColumn(field) === 'id');
+      for (const [field, direction] of orderBy) {
+        query = query.order(toBackendColumn(field), { ascending: direction === 'asc' });
+      }
+      // Add id as tiebreaker if not already in orderBy
+      if (!hasIdInOrderBy && orderBy.length > 0) {
+        query = query.order('id', { ascending: true });
+      }
+
+      // Pagination: keyset (cursor-based) or offset-based (legacy)
+      let useKeysetPagination = false;
+      if (startAfterCursor) {
+        // Keyset pagination (preferred)
+        useKeysetPagination = true;
+        try {
+          const cursor = decodeCursor(startAfterCursor);
+          
+          if (orderBy.length === 0) {
+            query = query.gt('id', cursor.id);
+          } else {
+            const firstOrderFieldApp = orderBy[0][0];
+            const firstOrderDirection = orderBy[0][1];
+            const orderColumnBackend = toBackendColumn(firstOrderFieldApp);
+            const cursorValue = cursor.orderBy[firstOrderFieldApp];
+            if (firstOrderDirection === 'asc') {
+              query = query.gte(orderColumnBackend, cursorValue);
+            } else {
+              query = query.lte(orderColumnBackend, cursorValue);
+            }
+          }
+        } catch (error) {
+          throw new DoNotDevError('Invalid cursor format', 'invalid-argument');
+        }
+        // Apply limit (will filter cursor item after fetch)
+        query = query.limit(limit + 1); // Fetch one extra to check hasMore
+      } else if (startAfterId) {
+        // Offset-based pagination (legacy)
+        const offset = parseInt(startAfterId, 10);
+        if (isNaN(offset)) {
+          throw new DoNotDevError('Invalid startAfterId', 'invalid-argument');
+        }
+        query = query.range(offset, offset + limit - 1);
+      } else {
+        // First page
+        query = query.range(0, limit - 1);
+      }
+
+      // Execute query
+      const { data: rows, error, count } = await query;
+
+      if (error) {
+        throw new DoNotDevError(`Failed to list entities: ${error.message}`, 'internal');
+      }
+
+      let items = (rows || []) as Record<string, any>[];
+      
+      // Filter out cursor item for keyset pagination
+      if (useKeysetPagination && startAfterCursor && items.length > 0) {
+        try {
+          const cursor = decodeCursor(startAfterCursor);
+          items = items.filter((item) => {
+            if (orderBy.length === 0) {
+              return item.id !== cursor.id;
+            }
+            const firstOrderFieldApp = orderBy[0][0];
+            const cursorValue = cursor.orderBy[firstOrderFieldApp];
+            const itemValue = item[mapper.toBackendField(firstOrderFieldApp)];
+            return !(item.id === cursor.id && itemValue === cursorValue);
+          });
+        } catch {
+          // If cursor decode fails, continue with all items
+        }
+      }
+
+      // Helper: Check if value is a Picture object
+      const isPictureObject = (value: any): boolean => {
+        return (
+          typeof value === 'object' &&
+          value !== null &&
+          'thumbUrl' in value &&
+          'fullUrl' in value
+        );
+      };
+
+      // Helper: Optimize picture fields for listCard (only return first picture's thumbUrl)
+      const optimizePictureField = (value: any): any => {
+        if (Array.isArray(value) && value.length > 0) {
+          const firstPicture = value[0];
+          if (isPictureObject(firstPicture)) {
+            return firstPicture.thumbUrl || firstPicture.fullUrl || null;
+          }
+          if (typeof firstPicture === 'string') {
+            return firstPicture;
+          }
+        } else if (isPictureObject(value)) {
+          return value.thumbUrl || value.fullUrl || null;
+        }
+        return value;
+      };
+
+      const visibilityOptions = ownership && uid ? { uid, ownership } : undefined;
+
+      // Filter document fields based on visibility and user role
+      const filteredItems = items.map((row) => {
+        const camelRow = mapper.fromBackendRow(row) as Record<string, any>;
+        const visibleData = filterVisibleFields(
+          camelRow,
+          documentSchema,
+          userRole,
+          visibilityOptions
+            ? { ...visibilityOptions, documentData: camelRow }
+            : undefined
+        );
+
+        // If listFields specified, filter to only those fields (plus id always)
+        if (safeListFields && safeListFields.length > 0) {
+          const filtered: Record<string, any> = { id: camelRow.id };
+          for (const field of safeListFields) {
+            if (field in visibleData) {
+              const value = visibleData[field];
+              filtered[field] = optimizePictureField(value);
+            }
+          }
+          return filtered;
+        }
+
+        // No listFields restriction, return all visible fields (optimize pictures)
+        const optimizedData: Record<string, any> = { id: camelRow.id };
+        for (const [key, value] of Object.entries(visibleData)) {
+          optimizedData[key] = optimizePictureField(value);
+        }
+        return optimizedData;
+      });
+
+      const hasMore = items.length === limit;
+      
+      // Generate cursor for keyset pagination or offset for legacy
+      let lastVisible: string | null = null;
+      if (hasMore && filteredItems.length > 0) {
+        const lastItem = filteredItems[filteredItems.length - 1];
+        if (useKeysetPagination && orderBy.length > 0) {
+          // Create cursor from last item's orderBy field + id
+          const firstOrderField = orderBy[0][0];
+          const orderByValue: Record<string, any> = {};
+          orderByValue[firstOrderField] = lastItem[firstOrderField];
+          lastVisible = encodeCursor(lastItem.id, orderByValue);
+        } else if (useKeysetPagination) {
+          // No orderBy: just use id
+          lastVisible = encodeCursor(lastItem.id, {});
+        } else {
+          // Offset-based: return offset + count
+          const offset = startAfterId ? parseInt(startAfterId, 10) : 0;
+          lastVisible = String(offset + items.length);
+        }
+      }
+
+      return {
+        items: filteredItems,
+        lastVisible,
+        count: count ?? undefined,
+        hasMore,
+      };
+    },
+    requiredRole
+  );
+}

package/src/supabase/crud/update.ts

@@ -0,0 +1,199 @@
+// packages/functions/src/supabase/crud/update.ts
+
+/**
+ * @fileoverview Generic handler to update an entity in Supabase.
+ * @description Provides a reusable implementation for updating documents in PostgreSQL with validation.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import * as v from 'valibot';
+
+import type { UserRole, UniqueKeyDefinition } from '@donotdev/core/server';
+
+import { defaultFieldMapper } from '@donotdev/supabase';
+
+import { updateMetadata } from '../../shared/index.js';
+import { DoNotDevError, validateDocument } from '../../shared/utils.js';
+import { createSupabaseHandler } from '../baseFunction.js';
+import {
+  checkIdempotency,
+  storeIdempotency,
+} from '../utils/idempotency.js';
+
+const mapper = defaultFieldMapper;
+
+export type UpdateEntityRequest = {
+  id: string;
+  payload: Record<string, any>;
+  idempotencyKey?: string;
+};
+
+/**
+ * Normalize a value for case-insensitive comparison
+ */
+function normalizeValue(value: unknown): unknown {
+  if (typeof value === 'string') {
+    return value.toLowerCase();
+  }
+  return value;
+}
+
+/**
+ * Check unique key constraints for modified fields only
+ */
+async function checkUniqueKeys(
+  collection: string,
+  id: string,
+  payload: Record<string, any>,
+  uniqueKeys: UniqueKeyDefinition[],
+  isDraft: boolean,
+  supabaseAdmin: any
+): Promise<void> {
+  for (const uniqueKey of uniqueKeys) {
+    if (isDraft && uniqueKey.skipForDrafts === true) continue;
+
+    // Only check fields that are being modified
+    const modifiedFields = uniqueKey.fields.filter((field) => field in payload);
+    if (modifiedFields.length === 0) continue;
+
+    // Check if all fields in the unique key have values
+    const allFieldsHaveValues = uniqueKey.fields.every(
+      (field) => payload[field] != null && payload[field] !== ''
+    );
+    if (!allFieldsHaveValues) continue;
+
+    // Build query excluding current document
+    let query = supabaseAdmin.from(collection).select('*');
+    for (const field of uniqueKey.fields) {
+      query = query.eq(mapper.toBackendField(field), normalizeValue(payload[field]));
+    }
+    query = query.neq('id', id);
+
+    const { data: existing, error } = await query.limit(1);
+
+    if (!error && existing && existing.length > 0) {
+      const fieldNames = uniqueKey.fields.join(' + ');
+      throw new DoNotDevError(
+        uniqueKey.errorMessage || `Duplicate ${fieldNames}`,
+        'already-exists',
+        {
+          details: {
+            fields: uniqueKey.fields,
+            existingId: existing[0].id,
+          },
+        }
+      );
+    }
+  }
+}
+
+/**
+ * Create a Supabase Edge Function handler for updating an entity.
+ *
+ * @param collection - The Supabase table name
+ * @param documentSchema - The Valibot schema for document validation
+ * @param requiredRole - Minimum role required for this operation
+ * @returns A `(req: Request) => Promise<Response>` handler for Deno.serve
+ */
+export function createSupabaseUpdateEntity(
+  collection: string,
+  documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
+  requiredRole: UserRole
+) {
+  const requestSchema = v.object({
+    id: v.pipe(v.string(), v.minLength(1)),
+    payload: v.record(v.string(), v.any()),
+    idempotencyKey: v.optional(v.string()),
+  });
+
+  return createSupabaseHandler(
+    `update_${collection}`,
+    requestSchema,
+    async (data: UpdateEntityRequest, ctx) => {
+      const { id, payload, idempotencyKey } = data;
+      const { uid, supabaseAdmin } = ctx;
+
+      // Idempotency check if key provided
+      if (idempotencyKey) {
+        const cachedResult = await checkIdempotency<any>(
+          supabaseAdmin,
+          idempotencyKey,
+          'update'
+        );
+        if (cachedResult) {
+          return cachedResult;
+        }
+      }
+
+      // Fetch existing document
+      const { data: existing, error: fetchError } = await supabaseAdmin
+        .from(collection)
+        .select('*')
+        .eq('id', id)
+        .single();
+
+      if (fetchError || !existing) {
+        throw new DoNotDevError('Entity not found', 'not-found');
+      }
+
+      const merged = { ...(mapper.fromBackendRow(existing) as Record<string, any>), ...payload };
+      const status = merged.status ?? existing.status;
+      const isDraft = status === 'draft';
+
+      // Check unique keys if schema has metadata with uniqueKeys
+      const schemaWithMeta = documentSchema as {
+        metadata?: { uniqueKeys?: UniqueKeyDefinition[] };
+      };
+      const uniqueKeys = schemaWithMeta.metadata?.uniqueKeys;
+
+      if (uniqueKeys && uniqueKeys.length > 0) {
+        await checkUniqueKeys(collection, id, merged, uniqueKeys, isDraft, supabaseAdmin);
+      }
+
+      // Validate merged document (skip for drafts)
+      if (!isDraft) {
+        validateDocument(merged, documentSchema);
+      }
+
+      const metadata = updateMetadata(uid);
+      const snakeMetadata = mapper.toBackendKeys(metadata as Record<string, unknown>);
+
+      const { createdAt, updatedAt, created_at, updated_at, id: _id, ...payloadWithoutTimestamps } = payload;
+      const snakePayload = mapper.toBackendKeys(payloadWithoutTimestamps);
+
+      // Update document (DB sets updated_at via trigger)
+      const { data: updated, error } = await supabaseAdmin
+        .from(collection)
+        .update({
+          ...snakePayload,
+          ...snakeMetadata,
+        })
+        .eq('id', id)
+        .select()
+        .single();
+
+      if (error) {
+        throw new DoNotDevError(`Failed to update entity: ${error.message}`, 'internal');
+      }
+
+      const result = mapper.fromBackendRow(updated) as Record<string, any>;
+
+      // Store result for idempotency if key provided
+      if (idempotencyKey) {
+        await storeIdempotency(
+          supabaseAdmin,
+          idempotencyKey,
+          'update',
+          result,
+          uid
+        );
+      }
+
+      return result;
+    },
+    requiredRole
+  );
+}

package/src/supabase/helpers/authProvider.ts

@@ -0,0 +1,45 @@
+// packages/functions/src/supabase/helpers/authProvider.ts
+
+/**
+ * @fileoverview Supabase Auth Provider for shared billing logic
+ * @description Maps Supabase Admin auth to the shared `AuthProvider` interface,
+ * bridging `app_metadata` ↔ `customClaims`.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import type { AuthProvider } from '../../shared/billing/helpers/updateUserSubscription.js';
+
+import type { SupabaseClient } from '@supabase/supabase-js';
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+/**
+ * Create an AuthProvider backed by Supabase Admin.
+ * `app_metadata` is used as the equivalent of Firebase custom claims.
+ *
+ * @param supabaseAdmin - Supabase client created with the service role key
+ * @returns AuthProvider compatible with shared billing helpers
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ */
+export function createSupabaseAuthProvider(supabaseAdmin: SupabaseClient): AuthProvider {
+  return {
+    async getUser(userId: string) {
+      const { data, error } = await supabaseAdmin.auth.admin.getUserById(userId);
+      if (error) throw error;
+      return { customClaims: data.user?.app_metadata ?? {} };
+    },
+    async setCustomUserClaims(userId: string, claims: Record<string, unknown>) {
+      const { error } = await supabaseAdmin.auth.admin.updateUserById(userId, {
+        app_metadata: claims,
+      });
+      if (error) throw error;
+    },
+  };
+}

package/src/supabase/index.ts

@@ -0,0 +1,73 @@
+// packages/functions/src/supabase/index.ts
+
+/**
+ * @fileoverview Supabase Edge Functions barrel exports
+ * @description All Supabase Edge Function handlers for auth and billing.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+// Base
+export { createSupabaseHandler } from './baseFunction.js';
+export type { SupabaseHandlerContext } from './baseFunction.js';
+
+// Helpers
+export { createSupabaseAuthProvider } from './helpers/authProvider.js';
+
+// Auth
+export { createDeleteAccount } from './auth/deleteAccount.js';
+export { createSetCustomClaims } from './auth/setCustomClaims.js';
+export { createGetCustomClaims } from './auth/getCustomClaims.js';
+export { createRemoveCustomClaims } from './auth/removeCustomClaims.js';
+export { createGetUserAuthStatus } from './auth/getUserAuthStatus.js';
+
+// Billing
+export { createCheckoutSession } from './billing/createCheckoutSession.js';
+export { createCancelSubscription } from './billing/cancelSubscription.js';
+export { createChangePlan } from './billing/changePlan.js';
+export { createCustomerPortal } from './billing/createCustomerPortal.js';
+export { createRefreshSubscriptionStatus } from './billing/refreshSubscriptionStatus.js';
+
+// CRUD
+export {
+  createSupabaseGetEntity,
+  createSupabaseCreateEntity,
+  createSupabaseUpdateEntity,
+  createSupabaseDeleteEntity,
+  createSupabaseListEntities,
+  createSupabaseAggregateEntities,
+} from './crud/index.js';
+export { createSupabaseCrudFunctions } from './registerCrudFunctions.js';
+export type {
+  GetEntityRequest,
+  CreateEntityRequest,
+  UpdateEntityRequest,
+  DeleteEntityRequest,
+  ListEntityRequest,
+  AggregateEntityRequest,
+  ReferenceMetadata,
+} from './crud/index.js';
+
+// Utils
+export {
+  checkIdempotency,
+  storeIdempotency,
+  cleanupExpiredIdempotency,
+} from './utils/idempotency.js';
+export {
+  checkRateLimitWithPostgres,
+  DEFAULT_RATE_LIMITS,
+} from './utils/rateLimiter.js';
+export type {
+  RateLimitConfig,
+  RateLimitResult,
+} from './utils/rateLimiter.js';
+export {
+  recordOperationMetrics,
+  getFailureRate,
+  getOperationCounts,
+  getSlowOperations,
+} from './utils/monitoring.js';
+export type { OperationMetrics } from './utils/monitoring.js';