@donotdev/functions 0.0.3 → 0.0.5

package/src/firebase/crud/aggregate.ts

@@ -0,0 +1,361 @@
+// packages/functions/src/firebase/crud/aggregate.ts
+
+/**
+ * @fileoverview Generic function to aggregate entities with metrics and grouping.
+ * @description Provides a reusable implementation for computing aggregations on Firestore collections.
+ * Returns only computed metrics, never raw data - optimized for analytics dashboards.
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+
+import type { CallableRequest } from 'firebase-functions/v2/https';
+
+import * as v from 'valibot';
+
+import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
+
+import { isFieldVisible } from '../../shared/schema.js';
+import { DoNotDevError } from '../../shared/utils.js';
+import { createBaseFunction } from '../baseFunction.js';
+import { CRUD_CONFIG } from '../config/constants.js';
+
+/** Supported aggregation operations */
+export type AggregateOperation = 'count' | 'sum' | 'avg' | 'min' | 'max';
+
+/** Single metric definition */
+export interface MetricDefinition {
+  /** Field to aggregate ('*' for count all) */
+  field: string;
+  /** Aggregation operation */
+  operation: AggregateOperation;
+  /** Output name for this metric */
+  as: string;
+  /** Optional filter for this metric */
+  filter?: {
+    field: string;
+    operator: '==' | '!=' | '>' | '<' | '>=' | '<=';
+    value: any;
+  };
+}
+
+/** Group by definition */
+export interface GroupByDefinition {
+  /** Field to group by */
+  field: string;
+  /** Metrics to compute per group */
+  metrics: MetricDefinition[];
+}
+
+/** Aggregation configuration */
+export interface AggregateConfig {
+  /** Top-level metrics (computed on entire collection) */
+  metrics?: MetricDefinition[];
+  /** Group by configurations */
+  groupBy?: GroupByDefinition[];
+  /** Optional global filters */
+  where?: Array<[string, any, any]>;
+}
+
+/** Request schema for aggregate function */
+interface AggregateRequest {
+  /** Optional runtime filters (merged with config filters) */
+  where?: Array<[string, any, any]>;
+  /** Optional date range filter */
+  dateRange?: {
+    field: string;
+    start?: string;
+    end?: string;
+  };
+}
+
+/**
+ * Extracts visibility from a Valibot field schema
+ */
+function getFieldVisibilityFromSchema(
+  schema: any,
+  fieldName: string
+): string | undefined {
+  if (!schema?.entries?.[fieldName]) return undefined;
+  const field = schema.entries[fieldName];
+  return field?.visibility;
+}
+
+/**
+ * Checks if user can access a field for aggregation
+ */
+function canAggregateField(
+  fieldName: string,
+  schema: any,
+  isAdmin: boolean
+): boolean {
+  // '*' is always allowed (count all)
+  if (fieldName === '*') return true;
+
+  const visibility = getFieldVisibilityFromSchema(schema, fieldName);
+  return isFieldVisible(fieldName, visibility as any, isAdmin);
+}
+
+/**
+ * Computes a single metric on a dataset
+ */
+function computeMetric(docs: any[], metric: MetricDefinition): number | null {
+  // Apply metric-level filter if specified
+  let filtered = docs;
+  if (metric.filter) {
+    filtered = docs.filter((doc) => {
+      const value = doc[metric.filter!.field];
+      switch (metric.filter!.operator) {
+        case '==':
+          return value === metric.filter!.value;
+        case '!=':
+          return value !== metric.filter!.value;
+        case '>':
+          return value > metric.filter!.value;
+        case '<':
+          return value < metric.filter!.value;
+        case '>=':
+          return value >= metric.filter!.value;
+        case '<=':
+          return value <= metric.filter!.value;
+        default:
+          return true;
+      }
+    });
+  }
+
+  switch (metric.operation) {
+    case 'count':
+      return filtered.length;
+
+    case 'sum': {
+      return filtered.reduce((sum, doc) => {
+        const val = Number(doc[metric.field]) || 0;
+        return sum + val;
+      }, 0);
+    }
+
+    case 'avg': {
+      if (filtered.length === 0) return null;
+      const sum = filtered.reduce((s, doc) => {
+        const val = Number(doc[metric.field]) || 0;
+        return s + val;
+      }, 0);
+      return sum / filtered.length;
+    }
+
+    case 'min': {
+      if (filtered.length === 0) return null;
+      return filtered.reduce(
+        (min, doc) => {
+          const val = Number(doc[metric.field]);
+          if (isNaN(val)) return min;
+          return min === null ? val : Math.min(min, val);
+        },
+        null as number | null
+      );
+    }
+
+    case 'max': {
+      if (filtered.length === 0) return null;
+      return filtered.reduce(
+        (max, doc) => {
+          const val = Number(doc[metric.field]);
+          if (isNaN(val)) return max;
+          return max === null ? val : Math.max(max, val);
+        },
+        null as number | null
+      );
+    }
+
+    default:
+      return null;
+  }
+}
+
+/**
+ * Generic business logic for aggregating entities
+ */
+function aggregateEntitiesLogicFactory(
+  collection: string,
+  documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
+  config: AggregateConfig
+) {
+  return async function aggregateEntitiesLogic(
+    data: AggregateRequest,
+    context: { uid: string; request: CallableRequest<AggregateRequest> }
+  ) {
+    const db = getFirebaseAdminFirestore();
+    const user = context.request.auth;
+    const isAdmin = user?.token?.isAdmin === true;
+
+    // Validate that user can access the fields being aggregated
+    const allFields = new Set<string>();
+
+    config.metrics?.forEach((m) => allFields.add(m.field));
+    config.groupBy?.forEach((g) => {
+      allFields.add(g.field);
+      g.metrics.forEach((m) => allFields.add(m.field));
+    });
+
+    for (const field of allFields) {
+      if (!canAggregateField(field, documentSchema, isAdmin)) {
+        throw new DoNotDevError(
+          `Access denied: cannot aggregate field '${field}'`,
+          'permission-denied'
+        );
+      }
+    }
+
+    // Build query with filters
+    let query: FirebaseFirestore.Query = db.collection(collection);
+
+    // Apply config-level filters
+    const whereFilters = [...(config.where || []), ...(data.where || [])];
+    for (const [field, operator, value] of whereFilters) {
+      query = query.where(field, operator, value);
+    }
+
+    // Apply date range filter if specified
+    if (data.dateRange) {
+      const { field, start, end } = data.dateRange;
+      if (start) {
+        query = query.where(field, '>=', new Date(start));
+      }
+      if (end) {
+        query = query.where(field, '<=', new Date(end));
+      }
+    }
+
+    // Fetch all matching documents
+    const snapshot = await query.get();
+    const docs: Record<string, any>[] = snapshot.docs.map((doc) => ({
+      id: doc.id,
+      ...doc.data(),
+    }));
+
+    // Compute top-level metrics
+    const metrics: Record<string, number | null> = {};
+    if (config.metrics) {
+      for (const metric of config.metrics) {
+        metrics[metric.as] = computeMetric(docs, metric);
+      }
+    }
+
+    // Compute grouped metrics
+    const groups: Record<
+      string,
+      Record<string, Record<string, number | null>>
+    > = {};
+    if (config.groupBy) {
+      for (const groupConfig of config.groupBy) {
+        const groupedDocs = new Map<string, any[]>();
+
+        // Group documents by field value
+        for (const doc of docs) {
+          const groupValue = String(doc[groupConfig.field] ?? 'null');
+          if (!groupedDocs.has(groupValue)) {
+            groupedDocs.set(groupValue, []);
+          }
+          groupedDocs.get(groupValue)!.push(doc);
+        }
+
+        // Compute metrics for each group
+        const groupResults: Record<string, Record<string, number | null>> = {};
+        for (const [groupValue, groupDocs] of groupedDocs) {
+          groupResults[groupValue] = {};
+          for (const metric of groupConfig.metrics) {
+            groupResults[groupValue][metric.as] = computeMetric(
+              groupDocs,
+              metric
+            );
+          }
+        }
+
+        groups[groupConfig.field] = groupResults;
+      }
+    }
+
+    return {
+      metrics,
+      groups,
+      meta: {
+        collection,
+        totalDocs: docs.length,
+        computedAt: new Date().toISOString(),
+      },
+    };
+  };
+}
+
+/**
+ * Generic function to aggregate entities from any Firestore collection.
+ * Returns only computed metrics, never raw data.
+ *
+ * @param collection - The Firestore collection name
+ * @param documentSchema - The Valibot schema (used for visibility checks)
+ * @param config - Aggregation configuration (metrics, groupBy, filters)
+ * @returns Firebase callable function
+ *
+ * @example
+ * ```typescript
+ * // Define analytics for cars collection
+ * export const getCarsAnalytics = aggregateEntities('cars', carSchema, {
+ *   metrics: [
+ *     { field: '*', operation: 'count', as: 'total' },
+ *     { field: 'price', operation: 'sum', as: 'totalValue' },
+ *     { field: 'price', operation: 'avg', as: 'avgPrice' },
+ *   ],
+ *   groupBy: [
+ *     {
+ *       field: 'status',
+ *       metrics: [
+ *         { field: '*', operation: 'count', as: 'count' },
+ *         { field: 'price', operation: 'sum', as: 'value' },
+ *       ],
+ *     },
+ *   ],
+ * });
+ *
+ * // Returns:
+ * // {
+ * //   metrics: { total: 150, totalValue: 4500000, avgPrice: 30000 },
+ * //   groups: {
+ * //     status: {
+ * //       Available: { count: 80, value: 2400000 },
+ * //       Reserved: { count: 20, value: 600000 },
+ * //       Sold: { count: 50, value: 1500000 },
+ * //     }
+ * //   },
+ * //   meta: { collection: 'cars', totalDocs: 150, computedAt: '...' }
+ * // }
+ * ```
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export const aggregateEntities = (
+  collection: string,
+  documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
+  config: AggregateConfig
+) => {
+  const requestSchema = v.object({
+    where: v.optional(v.array(v.tuple([v.string(), v.any(), v.any()]))),
+    dateRange: v.optional(
+      v.object({
+        field: v.string(),
+        start: v.optional(v.string()),
+        end: v.optional(v.string()),
+      })
+    ),
+  });
+
+  return createBaseFunction(
+    CRUD_CONFIG,
+    requestSchema,
+    'aggregate_entities',
+    aggregateEntitiesLogicFactory(collection, documentSchema, config)
+  );
+};

package/src/firebase/crud/create.ts

@@ -12,6 +12,7 @@
 import * as v from 'valibot';
 
 import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
+import { DEFAULT_STATUS_VALUE } from '@donotdev/core/server';
 
 import {
   prepareForFirestore,
@@ -22,7 +23,15 @@ import { assertAdmin, validateDocument } from '../../shared/utils.js';
 import { createBaseFunction } from '../baseFunction.js';
 import { CRUD_CONFIG } from '../config/constants.js';
 
-import type { CallableRequest } from 'firebase-functions/v2/https';
+import type {
+  CallableFunction,
+  CallableRequest,
+} from 'firebase-functions/v2/https';
+
+export type CreateEntityRequest = {
+  payload: Record<string, any>;
+  idempotencyKey?: string;
+};
 
 /**
  * Generic business logic for creating entities
@@ -37,7 +46,7 @@ function createEntityLogicFactory(
   documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>
 ) {
   return async function createEntityLogic(
-    data: { payload: Record<string, any>; idempotencyKey?: string },
+    data: CreateEntityRequest,
     context: { uid: string; request: CallableRequest<any> }
   ) {
     const { payload, idempotencyKey } = data;
@@ -57,12 +66,21 @@ function createEntityLogicFactory(
       }
     }
 
+    // Determine status (default to draft if not provided)
+    const status = payload.status ?? DEFAULT_STATUS_VALUE;
+    const isDraft = status === 'draft';
+
     // Validate the document against the schema
-    validateDocument(payload, documentSchema);
+    // Skip validation for drafts - required fields can be incomplete
+    if (!isDraft) {
+      validateDocument(payload, documentSchema);
+    }
 
     // Prepare the document for Firestore and add metadata
+    // Always ensure status is set
     const documentData = {
       ...prepareForFirestore(payload),
+      status, // Ensure status is always present
       ...createMetadata(uid),
     };
 
@@ -110,7 +128,7 @@ export const createEntity = (
   collection: string,
   documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
   customSchema?: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>
-) => {
+): CallableFunction<CreateEntityRequest, Promise<any>> => {
   const requestSchema =
     customSchema ||
     v.object({

package/src/firebase/crud/delete.ts

@@ -20,7 +20,12 @@ import {
 import { createBaseFunction } from '../baseFunction.js';
 import { CRUD_CONFIG } from '../config/constants.js';
 
-import type { CallableRequest } from 'firebase-functions/v2/https';
+import type {
+  CallableFunction,
+  CallableRequest,
+} from 'firebase-functions/v2/https';
+
+export type DeleteEntityRequest = { id: string };
 
 /**
  * Generic business logic for deleting entities
@@ -32,7 +37,7 @@ import type { CallableRequest } from 'firebase-functions/v2/https';
  */
 function deleteEntityLogicFactory(collection: string) {
   return async function deleteEntityLogic(
-    data: { id: string },
+    data: DeleteEntityRequest,
     context: { uid: string; request: CallableRequest<any> }
   ) {
     const { id } = data;
@@ -73,7 +78,7 @@ function deleteEntityLogicFactory(collection: string) {
 export const deleteEntity = (
   collection: string,
   customSchema?: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>
-) => {
+): CallableFunction<DeleteEntityRequest, Promise<{ success: boolean }>> => {
   const requestSchema =
     customSchema ||
     v.object({

package/src/firebase/crud/get.ts

@@ -10,6 +10,7 @@
  */
 
 import * as v from 'valibot';
+import { HIDDEN_STATUSES } from '@donotdev/core/server';
 
 import { transformFirestoreData } from '../../shared/index.js';
 import { filterVisibleFields } from '../../shared/index.js';
@@ -19,7 +20,12 @@ import { DoNotDevError } from '../../shared/utils.js';
 import { createBaseFunction } from '../baseFunction.js';
 import { CRUD_CONFIG } from '../config/constants.js';
 
-import type { CallableRequest } from 'firebase-functions/v2/https';
+import type {
+  CallableFunction,
+  CallableRequest,
+} from 'firebase-functions/v2/https';
+
+export type GetEntityRequest = { id: string };
 
 /**
  * Generic business logic for getting entities
@@ -30,7 +36,7 @@ function getEntityLogicFactory(
   documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>
 ) {
   return async function getEntityLogic(
-    data: { id: string },
+    data: GetEntityRequest,
     context: { uid: string; request: CallableRequest<any> }
   ) {
     const { id } = data;
@@ -50,9 +56,15 @@ function getEntityLogicFactory(
     // Check if the user is an admin
     const isAdmin = context.request.auth?.token?.isAdmin === true;
 
+    // Hide drafts/deleted from non-admin users (security: hidden statuses never reach public)
+    const docData = doc.data();
+    if (!isAdmin && (HIDDEN_STATUSES as readonly string[]).includes(docData?.status)) {
+      throw new DoNotDevError('Entity not found', 'not-found');
+    }
+
     // Filter fields based on visibility and user role
     const filteredData = filterVisibleFields(
-      doc.data() || {},
+      docData || {},
       documentSchema,
       isAdmin
     );
@@ -76,7 +88,7 @@ export const getEntity = (
   collection: string,
   documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
   customSchema?: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>
-) => {
+): CallableFunction<GetEntityRequest, Promise<any>> => {
   const requestSchema =
     customSchema ||
     v.object({

package/src/firebase/crud/index.ts

@@ -9,6 +9,7 @@
  * @author AMBROISE PARK Consulting
  */
 
+export * from './aggregate.js';
 export * from './create.js';
 export * from './delete.js';
 export * from './get.js';

package/src/firebase/crud/list.ts

@@ -10,12 +10,13 @@
  */
 
 import { Query } from '@donotdev/firebase/server';
+import { HIDDEN_STATUSES } from '@donotdev/core/server';
 
 import type { CallableRequest } from 'firebase-functions/v2/https';
 
 import * as v from 'valibot';
 
-interface ListEntityRequest {
+export interface ListEntityRequest {
   where?: Array<[string, any, any]>;
   orderBy?: Array<[string, 'asc' | 'desc']>;
   limit?: number;
@@ -33,6 +34,8 @@ import { DoNotDevError } from '../../shared/utils.js';
 import { createBaseFunction } from '../baseFunction.js';
 import { CRUD_CONFIG } from '../config/constants.js';
 
+import type { CallableFunction } from 'firebase-functions/v2/https';
+
 /**
  * Generic business logic for listing entities
  * Base function handles: validation, auth, rate limiting, monitoring
@@ -47,10 +50,19 @@ function listEntitiesLogicFactory(
   ) {
     const { where = [], orderBy = [], limit = 50, startAfterId, search } = data;
 
+    // Check if the user is an admin (needed early for draft filtering)
+    const user = context.request.auth;
+    const isAdmin = user?.token?.isAdmin === true;
+
     // Start with a Query (not a CollectionReference)
     const db = getFirebaseAdminFirestore();
     let query: Query = db.collection(collection);
 
+    // Filter out hidden statuses for non-admin users (security: drafts/deleted never reach public)
+    if (!isAdmin) {
+      query = query.where('status', 'not-in', [...HIDDEN_STATUSES]);
+    }
+
     // Apply search if provided
     if (search) {
       const { field, query: searchQuery } = search;
@@ -89,10 +101,6 @@ function listEntitiesLogicFactory(
     // Execute the query
     const snapshot = await query.get();
 
-    // Check if the user is an admin
-    const user = context.request.auth;
-    const isAdmin = user?.token?.isAdmin === true;
-
     // Filter document fields based on visibility and user role
     const docs = snapshot.docs.map((doc: any) => ({
       id: doc.id,
@@ -120,7 +128,7 @@ export const listEntities = (
   collection: string,
   documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
   customSchema?: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>
-) => {
+): CallableFunction<ListEntityRequest, Promise<any>> => {
   const requestSchema =
     customSchema ||
     v.object({

package/src/firebase/crud/update.ts

@@ -12,6 +12,7 @@
 import * as v from 'valibot';
 
 import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
+import { DEFAULT_STATUS_VALUE } from '@donotdev/core/server';
 
 import {
   prepareForFirestore,
@@ -26,7 +27,16 @@ import {
 import { createBaseFunction } from '../baseFunction.js';
 import { CRUD_CONFIG } from '../config/constants.js';
 
-import type { CallableRequest } from 'firebase-functions/v2/https';
+import type {
+  CallableFunction,
+  CallableRequest,
+} from 'firebase-functions/v2/https';
+
+export type UpdateEntityRequest = {
+  id: string;
+  payload: Record<string, any>;
+  idempotencyKey?: string;
+};
 
 /**
  * Generic business logic for updating entities
@@ -37,7 +47,7 @@ function updateEntityLogicFactory(
   documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>
 ) {
   return async function updateEntityLogic(
-    data: { id: string; payload: Record<string, any>; idempotencyKey?: string },
+    data: UpdateEntityRequest,
     context: { uid: string; request: CallableRequest<any> }
   ) {
     const { id, payload, idempotencyKey } = data;
@@ -71,8 +81,15 @@ function updateEntityLogicFactory(
     const currentData = transformFirestoreData(doc.data());
     const mergedData = { ...currentData, ...payload };
 
+    // Determine resulting status (default to draft if not set)
+    const resultingStatus = mergedData.status ?? DEFAULT_STATUS_VALUE;
+    const isDraft = resultingStatus === 'draft';
+
     // Validate the merged document against the schema
-    validateDocument(mergedData, documentSchema);
+    // Skip validation for drafts - required fields can be incomplete
+    if (!isDraft) {
+      validateDocument(mergedData, documentSchema);
+    }
 
     // Prepare the update data for Firestore and add metadata
     const updateData = {
@@ -119,7 +136,7 @@ export const updateEntity = (
   collection: string,
   documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
   customSchema?: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>
-) => {
+): CallableFunction<UpdateEntityRequest, Promise<any>> => {
   const requestSchema =
     customSchema ||
     v.object({