@donotdev/functions 0.0.10 → 0.0.12

package/src/supabase/crud/aggregate.ts

@@ -0,0 +1,169 @@
+// packages/functions/src/supabase/crud/aggregate.ts
+
+/**
+ * @fileoverview Generic handler to aggregate entities in Supabase.
+ * @description Provides aggregate operations (COUNT, SUM, AVG, MIN, MAX, GROUP BY) for PostgreSQL.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import * as v from 'valibot';
+
+import type { UserRole } from '@donotdev/core/server';
+
+import { defaultFieldMapper } from '@donotdev/supabase';
+
+import { DoNotDevError } from '../../shared/utils.js';
+import { createSupabaseHandler } from '../baseFunction.js';
+
+const mapper = defaultFieldMapper;
+
+export type AggregateEntityRequest = {
+  where?: Array<[string, any, any]>;
+  aggregate: {
+    field: string;
+    operation: 'count' | 'sum' | 'avg' | 'min' | 'max';
+  };
+  groupBy?: string[];
+};
+
+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]);
+    default:
+      return query.eq(column, value);
+  }
+}
+
+/**
+ * Create a Supabase Edge Function handler for aggregating entities.
+ *
+ * @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 createSupabaseAggregateEntities(
+  collection: string,
+  documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
+  requiredRole: UserRole
+) {
+  const requestSchema = v.object({
+    where: v.optional(v.array(v.tuple([v.string(), v.any(), v.any()]))),
+    aggregate: v.object({
+      field: v.string(),
+      operation: v.picklist(['count', 'sum', 'avg', 'min', 'max']),
+    }),
+    groupBy: v.optional(v.array(v.string())),
+  });
+
+  return createSupabaseHandler(
+    `aggregate_${collection}`,
+    requestSchema,
+    async (data: AggregateEntityRequest, ctx) => {
+      const { where = [], aggregate, groupBy } = data;
+      const { supabaseAdmin } = ctx;
+
+      const aggregateColumn = mapper.toBackendField(aggregate.field);
+      let query = supabaseAdmin.from(collection);
+
+      for (const [field, operator, value] of where) {
+        query = applyOperator(query, mapper.toBackendField(field), operator, value);
+      }
+
+      if (groupBy && groupBy.length > 0) {
+        const groupByColumns = groupBy.map((f) => mapper.toBackendField(f)).join(', ');
+        const selectFields = `${groupByColumns}, ${aggregate.operation}(${aggregateColumn})`;
+        query = query.select(selectFields);
+        for (const field of groupBy) {
+          query = query.group(mapper.toBackendField(field));
+        }
+      } else {
+        if (aggregate.operation === 'count') {
+          query = query.select('*', { count: 'exact', head: true });
+        } else {
+          query = query.select(aggregateColumn);
+        }
+      }
+
+      // Execute query
+      const { data: rows, error, count } = await query;
+
+      if (error) {
+        throw new DoNotDevError(`Failed to aggregate entities: ${error.message}`, 'internal');
+      }
+
+      // Process results
+      if (groupBy && groupBy.length > 0) {
+        const grouped: Record<string, number> = {};
+        for (const row of (rows || []) as any[]) {
+          const groupKey = groupBy
+            .map((f) => row[mapper.toBackendField(f)])
+            .join('|');
+          grouped[groupKey] = row[`${aggregate.operation}`] || 0;
+        }
+        return { value: grouped };
+      } else {
+        // Single aggregate value
+        if (aggregate.operation === 'count') {
+          return { value: count ?? 0 };
+        } else {
+          // Calculate aggregate from rows
+          const values = (rows || [] as any[])
+            .map((row) => row[aggregateColumn])
+            .filter((v) => v != null && !isNaN(Number(v)))
+            .map((v) => Number(v));
+
+          if (values.length === 0) {
+            return { value: 0 };
+          }
+
+          let result: number;
+          switch (aggregate.operation) {
+            case 'sum':
+              result = values.reduce((a, b) => a + b, 0);
+              break;
+            case 'avg':
+              result = values.reduce((a, b) => a + b, 0) / values.length;
+              break;
+            case 'min':
+              result = Math.min(...values);
+              break;
+            case 'max':
+              result = Math.max(...values);
+              break;
+            default:
+              result = 0;
+          }
+
+          return { value: result };
+        }
+      }
+    },
+    requiredRole
+  );
+}

package/src/supabase/crud/create.ts

@@ -0,0 +1,225 @@
+// packages/functions/src/supabase/crud/create.ts
+
+/**
+ * @fileoverview Generic handler to create an entity in Supabase.
+ * @description Provides a reusable implementation for creating documents in PostgreSQL with validation.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import * as v from 'valibot';
+
+import { DEFAULT_STATUS_VALUE } from '@donotdev/core/server';
+import type { UserRole, UniqueKeyDefinition } from '@donotdev/core/server';
+
+import { defaultFieldMapper } from '@donotdev/supabase';
+
+import { createMetadata } 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 CreateEntityRequest = {
+  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;
+}
+
+/**
+ * Normalize unique key fields in payload to lowercase (for strings)
+ */
+function normalizePayloadForUniqueKeys(
+  payload: Record<string, any>,
+  uniqueKeys: UniqueKeyDefinition[]
+): Record<string, any> {
+  const normalized = { ...payload };
+  for (const uniqueKey of uniqueKeys) {
+    for (const field of uniqueKey.fields) {
+      if (typeof normalized[field] === 'string') {
+        normalized[field] = normalized[field].toLowerCase();
+      }
+    }
+  }
+  return normalized;
+}
+
+/**
+ * Check unique key constraints against existing documents
+ */
+async function checkUniqueKeys(
+  collection: string,
+  payload: Record<string, any>,
+  uniqueKeys: UniqueKeyDefinition[],
+  isDraft: boolean,
+  supabaseAdmin: any
+): Promise<{ found: false } | { found: true; existingDoc: Record<string, any>; findOrCreate: boolean }> {
+  for (const uniqueKey of uniqueKeys) {
+    // Skip validation for drafts only if explicitly opted in
+    if (isDraft && uniqueKey.skipForDrafts === true) 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;
+
+    let query = supabaseAdmin.from(collection).select('*');
+    for (const field of uniqueKey.fields) {
+      query = query.eq(mapper.toBackendField(field), normalizeValue(payload[field]));
+    }
+
+    const { data: existing, error } = await query.limit(1);
+
+    if (!error && existing && existing.length > 0) {
+      const existingDoc = mapper.fromBackendRow(existing[0]) as Record<string, any>;
+
+      if (uniqueKey.findOrCreate) {
+        return { found: true, existingDoc, findOrCreate: true };
+      }
+
+      // Throw duplicate error
+      const fieldNames = uniqueKey.fields.join(' + ');
+      throw new DoNotDevError(
+        uniqueKey.errorMessage || `Duplicate ${fieldNames}`,
+        'already-exists',
+        {
+          details: {
+            fields: uniqueKey.fields,
+            existingId: existingDoc.id,
+          },
+        }
+      );
+    }
+  }
+
+  return { found: false };
+}
+
+/**
+ * Create a Supabase Edge Function handler for creating 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 createSupabaseCreateEntity(
+  collection: string,
+  documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
+  requiredRole: UserRole
+) {
+  const requestSchema = v.object({
+    payload: v.record(v.string(), v.any()),
+    idempotencyKey: v.optional(v.string()),
+  });
+
+  return createSupabaseHandler(
+    `create_${collection}`,
+    requestSchema,
+    async (data: CreateEntityRequest, ctx) => {
+      const { payload, idempotencyKey } = data;
+      const { uid, supabaseAdmin } = ctx;
+
+      // Idempotency check if key provided
+      if (idempotencyKey) {
+        const cachedResult = await checkIdempotency<any>(
+          supabaseAdmin,
+          idempotencyKey,
+          'create'
+        );
+        if (cachedResult) {
+          return cachedResult;
+        }
+      }
+
+      // Determine status (default to available if not provided)
+      const status = payload.status ?? DEFAULT_STATUS_VALUE;
+      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) {
+        const checkResult = await checkUniqueKeys(
+          collection,
+          payload,
+          uniqueKeys,
+          isDraft,
+          supabaseAdmin
+        );
+
+        if (checkResult.found && checkResult.findOrCreate) {
+          return checkResult.existingDoc;
+        }
+      }
+
+      // Normalize unique key fields to lowercase for case-insensitive storage
+      const normalizedPayload =
+        uniqueKeys && uniqueKeys.length > 0
+          ? normalizePayloadForUniqueKeys(payload, uniqueKeys)
+          : payload;
+
+      // Validate the document against the schema
+      // Skip validation for drafts - required fields can be incomplete
+      if (!isDraft) {
+        validateDocument(normalizedPayload, documentSchema);
+      }
+
+      const metadata = createMetadata(uid);
+      const snakeMetadata = mapper.toBackendKeys(metadata as Record<string, unknown>);
+
+      const { createdAt, updatedAt, created_at, updated_at, ...payloadWithoutTimestamps } = normalizedPayload;
+      const snakePayload = mapper.toBackendKeys(payloadWithoutTimestamps);
+
+      // Insert document (DB sets created_at/updated_at via triggers)
+      const { data: inserted, error } = await supabaseAdmin
+        .from(collection)
+        .insert({
+          ...snakePayload,
+          status,
+          ...snakeMetadata,
+        })
+        .select()
+        .single();
+
+      if (error) {
+        throw new DoNotDevError(`Failed to create entity: ${error.message}`, 'internal');
+      }
+
+      const result = mapper.fromBackendRow(inserted as Record<string, unknown>) as Record<string, any>;
+
+      // Store result for idempotency if key provided
+      if (idempotencyKey) {
+        await storeIdempotency(
+          supabaseAdmin,
+          idempotencyKey,
+          'create',
+          result,
+          uid
+        );
+      }
+
+      return result;
+    },
+    requiredRole
+  );
+}

package/src/supabase/crud/delete.ts

@@ -0,0 +1,154 @@
+// packages/functions/src/supabase/crud/delete.ts
+
+/**
+ * @fileoverview Generic handler to delete an entity from Supabase.
+ * @description Provides a reusable implementation for deleting documents from PostgreSQL.
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+import * as v from 'valibot';
+
+import type { UserRole } from '@donotdev/core/server';
+
+import { DoNotDevError } from '../../shared/utils.js';
+import { createSupabaseHandler } from '../baseFunction.js';
+
+export type DeleteEntityRequest = { id: string };
+
+/**
+ * Reference metadata for entity deletion checking
+ */
+export interface ReferenceMetadata {
+  /** Fields in THIS entity that reference OTHER entities */
+  outgoing?: Array<{
+    field: string;
+    targetCollection: string;
+    required?: boolean;
+  }>;
+  /** Fields in OTHER entities that reference THIS entity */
+  incoming?: Array<{
+    sourceCollection: string;
+    sourceField: string;
+    required?: boolean;
+  }>;
+}
+
+/**
+ * Find references to a document
+ *
+ * @param supabaseAdmin - Supabase admin client
+ * @param collection - Collection name
+ * @param docId - Document ID
+ * @param referenceMetadata - Reference metadata from entity
+ * @returns Array of reference information
+ */
+async function findReferences(
+  supabaseAdmin: any,
+  collection: string,
+  docId: string,
+  referenceMetadata?: ReferenceMetadata
+): Promise<Array<{ collection: string; field: string; count: number }>> {
+  const references: Array<{ collection: string; field: string; count: number }> = [];
+
+  if (!referenceMetadata) {
+    return references;
+  }
+
+  // Check incoming references (other entities reference this one)
+  if (referenceMetadata.incoming) {
+    for (const ref of referenceMetadata.incoming) {
+      const { count, error } = await supabaseAdmin
+        .from(ref.sourceCollection)
+        .select('*', { count: 'exact', head: true })
+        .eq(ref.sourceField, docId);
+
+      if (!error && count && count > 0) {
+        references.push({
+          collection: ref.sourceCollection,
+          field: ref.sourceField,
+          count,
+        });
+      }
+    }
+  }
+
+  // Check outgoing references (this entity references others)
+  // Note: Outgoing references don't prevent deletion, but we track them for info
+  if (referenceMetadata.outgoing) {
+    // For now, we only check incoming references as they prevent deletion
+    // Outgoing references are informational only
+  }
+
+  return references;
+}
+
+/**
+ * Create a Supabase Edge Function handler for deleting an entity.
+ *
+ * @param collection - The Supabase table name
+ * @param requiredRole - Minimum role required for this operation
+ * @param referenceMetadata - Optional reference metadata for deletion checking
+ * @returns A `(req: Request) => Promise<Response>` handler for Deno.serve
+ */
+export function createSupabaseDeleteEntity(
+  collection: string,
+  requiredRole: UserRole,
+  referenceMetadata?: ReferenceMetadata
+) {
+  const requestSchema = v.object({
+    id: v.pipe(v.string(), v.minLength(1)),
+  });
+
+  return createSupabaseHandler(
+    `delete_${collection}`,
+    requestSchema,
+    async (data: DeleteEntityRequest, ctx) => {
+      const { id } = data;
+      const { supabaseAdmin } = ctx;
+
+      // Check for references to this document
+      const references = await findReferences(
+        supabaseAdmin,
+        collection,
+        id,
+        referenceMetadata
+      );
+
+      // Prevent deletion if required references exist
+      const requiredReferences = references.filter((ref) => {
+        const metadata = referenceMetadata?.incoming?.find(
+          (r) => r.sourceCollection === ref.collection && r.sourceField === ref.field
+        );
+        return metadata?.required === true;
+      });
+
+      if (requiredReferences.length > 0) {
+        throw new DoNotDevError(
+          'Cannot delete: item is referenced by other entities',
+          'permission-denied',
+          {
+            details: {
+              references: requiredReferences,
+            },
+          }
+        );
+      }
+
+      // Delete document
+      const { error } = await supabaseAdmin
+        .from(collection)
+        .delete()
+        .eq('id', id);
+
+      if (error) {
+        throw new DoNotDevError(`Failed to delete entity: ${error.message}`, 'internal');
+      }
+
+      return { success: true };
+    },
+    requiredRole
+  );
+}

package/src/supabase/crud/get.ts

@@ -0,0 +1,89 @@
+// packages/functions/src/supabase/crud/get.ts
+
+/**
+ * @fileoverview Generic handler to retrieve a single entity from Supabase.
+ * @description Provides a reusable implementation for retrieving documents from PostgreSQL with visibility filtering.
+ *
+ * @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, UserRole } from '@donotdev/core/server';
+
+import { DoNotDevError } from '../../shared/utils.js';
+import { createSupabaseHandler } from '../baseFunction.js';
+
+export type GetEntityRequest = { id: string };
+
+/**
+ * Create a Supabase Edge Function handler for getting a single entity.
+ *
+ * @param collection - The Supabase table name
+ * @param documentSchema - The Valibot schema for document validation
+ * @param requiredRole - Minimum role required for this operation
+ * @param ownership - Optional ownership config for visibility: 'owner' field masking
+ * @returns A `(req: Request) => Promise<Response>` handler for Deno.serve
+ */
+export function createSupabaseGetEntity(
+  collection: string,
+  documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
+  requiredRole: UserRole,
+  ownership?: EntityOwnershipConfig
+) {
+  const requestSchema = v.object({
+    id: v.pipe(v.string(), v.minLength(1)),
+  });
+
+  return createSupabaseHandler(
+    `get_${collection}`,
+    requestSchema,
+    async (data: GetEntityRequest, ctx) => {
+      const { id } = data;
+      const { userRole, uid, supabaseAdmin } = ctx;
+
+      // Query the document
+      const { data: row, error } = await supabaseAdmin
+        .from(collection)
+        .select('*')
+        .eq('id', id)
+        .single();
+
+      if (error || !row) {
+        throw new DoNotDevError('Entity not found', 'not-found');
+      }
+
+      const isAdmin = hasRoleAccess(userRole, 'admin');
+
+      // Hide drafts/deleted from non-admin users (security: hidden statuses never reach public)
+      if (!isAdmin && (HIDDEN_STATUSES as readonly string[]).includes(row.status)) {
+        throw new DoNotDevError('Entity not found', 'not-found');
+      }
+
+      const visibilityOptions =
+        ownership && uid ? { documentData: row, uid, ownership } : undefined;
+
+      // Filter fields based on visibility and user role (and ownership for visibility: 'owner')
+      const filteredData = filterVisibleFields(
+        row,
+        documentSchema,
+        userRole,
+        visibilityOptions
+      );
+
+      // Supabase returns plain JSON (no Firestore Timestamp conversion needed)
+      return {
+        id: row.id,
+        ...filteredData,
+      };
+    },
+    requiredRole
+  );
+}

package/src/supabase/crud/index.ts

@@ -0,0 +1,24 @@
+// packages/functions/src/supabase/crud/index.ts
+
+/**
+ * @fileoverview Supabase CRUD handlers barrel export
+ * @description Exports all Supabase CRUD handler factories
+ *
+ * @version 0.0.1
+ * @since 0.5.0
+ * @author AMBROISE PARK Consulting
+ */
+
+export { createSupabaseGetEntity } from './get.js';
+export { createSupabaseCreateEntity } from './create.js';
+export { createSupabaseUpdateEntity } from './update.js';
+export { createSupabaseDeleteEntity } from './delete.js';
+export { createSupabaseListEntities } from './list.js';
+export { createSupabaseAggregateEntities } from './aggregate.js';
+
+export type { GetEntityRequest } from './get.js';
+export type { CreateEntityRequest } from './create.js';
+export type { UpdateEntityRequest } from './update.js';
+export type { DeleteEntityRequest, ReferenceMetadata } from './delete.js';
+export type { ListEntityRequest } from './list.js';
+export type { AggregateEntityRequest } from './aggregate.js';