@donotdev/functions 0.0.8 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donotdev/functions",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "private": false,
   "description": "Backend functions for DoNotDev Framework - Firebase, Vercel, and platform-agnostic implementations for auth, billing, CRUD, and OAuth",
   "main": "./lib/firebase/index.js",
@@ -42,15 +42,15 @@
     "serve": "firebase emulators:start --only functions"
   },
   "dependencies": {
-    "@donotdev/core": "^0.0.18",
-    "@donotdev/firebase": "^0.0.7"
+    "@donotdev/core": "^0.0.19",
+    "@donotdev/firebase": "^0.0.8"
   },
   "peerDependencies": {
-    "@sentry/node": "^10.33.0",
+    "@sentry/node": "^10.38.0",
     "firebase-admin": "^13.6.0",
-    "firebase-functions": "^7.0.1",
-    "next": "^16.1.4",
-    "stripe": "^20.1.0",
+    "firebase-functions": "^7.0.5",
+    "next": "^16.1.6",
+    "stripe": "^20.3.0",
     "valibot": "^1.2.0"
   },
   "repository": {

package/src/firebase/crud/aggregate.ts

@@ -97,6 +97,34 @@ function canAggregateField(
   return isFieldVisible(fieldName, visibility as any, isAdmin);
 }
 
+/**
+ * Returns the effective (discounted) amount for a price field.
+ * Matches display/formula: amount * (1 - discountPercent/100). Plain numbers unchanged.
+ */
+function getPriceOrNumberValue(raw: unknown): number {
+  if (raw != null && typeof raw === 'object' && 'amount' in raw) {
+    const obj = raw as { amount?: unknown; discountPercent?: unknown };
+    const amount = Number(obj.amount);
+    if (!Number.isFinite(amount)) return NaN;
+    const discountPercent = Number(obj.discountPercent);
+    const pct = Number.isFinite(discountPercent)
+      ? Math.min(100, Math.max(0, discountPercent))
+      : 0;
+    return pct > 0 ? amount * (1 - pct / 100) : amount;
+  }
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : NaN;
+}
+
+/**
+ * Returns the numeric value of a field for aggregation.
+ * For structured price fields uses effective (discounted) price (expected revenue).
+ * Plain numbers are used as-is.
+ */
+function getNumericValue(doc: Record<string, any>, field: string): number {
+  return getPriceOrNumberValue(doc[field]);
+}
+
 /**
  * Computes a single metric on a dataset
  */
@@ -106,19 +134,25 @@ function computeMetric(docs: any[], metric: MetricDefinition): number | null {
   if (metric.filter) {
     filtered = docs.filter((doc) => {
       const value = doc[metric.filter!.field];
+      const comparable =
+        value != null && typeof value === 'object' && 'amount' in value
+          ? getPriceOrNumberValue(value)
+          : typeof value === 'number' || value == null
+            ? value
+            : Number(value);
       switch (metric.filter!.operator) {
         case '==':
           return value === metric.filter!.value;
         case '!=':
           return value !== metric.filter!.value;
         case '>':
-          return value > metric.filter!.value;
+          return comparable > metric.filter!.value;
         case '<':
-          return value < metric.filter!.value;
+          return comparable < metric.filter!.value;
         case '>=':
-          return value >= metric.filter!.value;
+          return comparable >= metric.filter!.value;
         case '<=':
-          return value <= metric.filter!.value;
+          return comparable <= metric.filter!.value;
         default:
           return true;
       }
@@ -131,16 +165,16 @@ function computeMetric(docs: any[], metric: MetricDefinition): number | null {
 
     case 'sum': {
       return filtered.reduce((sum, doc) => {
-        const val = Number(doc[metric.field]) || 0;
-        return sum + val;
+        const val = getNumericValue(doc, metric.field);
+        return sum + (Number.isFinite(val) ? val : 0);
       }, 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;
+        const val = getNumericValue(doc, metric.field);
+        return s + (Number.isFinite(val) ? val : 0);
       }, 0);
       return sum / filtered.length;
     }
@@ -149,8 +183,8 @@ function computeMetric(docs: any[], metric: MetricDefinition): number | null {
       if (filtered.length === 0) return null;
       return filtered.reduce(
         (min, doc) => {
-          const val = Number(doc[metric.field]);
-          if (isNaN(val)) return min;
+          const val = getNumericValue(doc, metric.field);
+          if (!Number.isFinite(val)) return min;
           return min === null ? val : Math.min(min, val);
         },
         null as number | null
@@ -161,8 +195,8 @@ function computeMetric(docs: any[], metric: MetricDefinition): number | null {
       if (filtered.length === 0) return null;
       return filtered.reduce(
         (max, doc) => {
-          const val = Number(doc[metric.field]);
-          if (isNaN(val)) return max;
+          const val = getNumericValue(doc, metric.field);
+          if (!Number.isFinite(val)) return max;
           return max === null ? val : Math.max(max, val);
         },
         null as number | null

package/src/firebase/crud/create.ts

@@ -12,7 +12,7 @@
 import * as v from 'valibot';
 
 import { DEFAULT_STATUS_VALUE } from '@donotdev/core/server';
-import type { UserRole } from '@donotdev/core/server';
+import type { UserRole, UniqueKeyDefinition } from '@donotdev/core/server';
 import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
 
 import {
@@ -20,7 +20,7 @@ import {
   transformFirestoreData,
 } from '../../shared/index.js';
 import { createMetadata } from '../../shared/index.js';
-import { validateDocument } from '../../shared/utils.js';
+import { DoNotDevError, validateDocument } from '../../shared/utils.js';
 import { createBaseFunction } from '../baseFunction.js';
 import { CRUD_CONFIG } from '../config/constants.js';
 
@@ -28,17 +28,123 @@ import type {
   CallableFunction,
   CallableRequest,
 } from 'firebase-functions/v2/https';
+import type { Query, DocumentData } from 'firebase-admin/firestore';
 
 export type CreateEntityRequest = {
   payload: Record<string, any>;
   idempotencyKey?: string;
 };
 
+/**
+ * Result of unique key check
+ */
+type UniqueKeyCheckResult =
+  | { found: false }
+  | { found: true; existingDoc: Record<string, any>; findOrCreate: boolean };
+
+/**
+ * Checks unique key constraints against existing documents
+ * Returns the first matching document if findOrCreate is enabled
+ *
+ * @param collection - Firestore collection name
+ * @param payload - Document data to check
+ * @param uniqueKeys - Unique key definitions from entity
+ * @param isDraft - Whether the document is a draft
+ * @returns Check result with existing document if found
+ */
+/**
+ * Normalize a value for case-insensitive comparison
+ * Lowercases strings, leaves other types unchanged
+ */
+function normalizeValue(value: unknown): unknown {
+  if (typeof value === 'string') {
+    return value.toLowerCase();
+  }
+  return value;
+}
+
+/**
+ * Normalize unique key fields in payload to lowercase (for strings)
+ * Returns a new object with normalized values for unique key fields
+ */
+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;
+}
+
+async function checkUniqueKeys(
+  collection: string,
+  payload: Record<string, any>,
+  uniqueKeys: UniqueKeyDefinition[],
+  isDraft: boolean
+): Promise<UniqueKeyCheckResult> {
+  const db = getFirebaseAdminFirestore();
+
+  for (const uniqueKey of uniqueKeys) {
+    // Skip validation for drafts if configured (default: true)
+    const skipForDrafts = uniqueKey.skipForDrafts !== false;
+    if (isDraft && skipForDrafts) 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 for all fields in this unique key
+    // Normalize values to lowercase for case-insensitive matching
+    let query: Query<DocumentData> = db.collection(collection);
+    for (const field of uniqueKey.fields) {
+      query = query.where(field, '==', normalizeValue(payload[field]));
+    }
+
+    const existing = await query.limit(1).get();
+
+    if (!existing.empty) {
+      const firstDoc = existing.docs[0]!;
+      const existingDoc = transformFirestoreData({
+        id: firstDoc.id,
+        ...firstDoc.data(),
+      });
+
+      if (uniqueKey.findOrCreate) {
+        // Return existing document for findOrCreate behavior
+        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: firstDoc.id,
+          },
+        }
+      );
+    }
+  }
+
+  return { found: false };
+}
+
 /**
  * Generic business logic for creating entities
  * Base function handles: validation, auth, rate limiting, monitoring
  *
- * @version 0.0.1
+ * @version 0.0.2
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
@@ -69,16 +175,44 @@ function createEntityLogicFactory(
     const status = payload.status ?? DEFAULT_STATUS_VALUE;
     const isDraft = status === 'draft';
 
+    // Check unique keys if schema has metadata with uniqueKeys
+    // This handles findOrCreate behavior and duplicate prevention
+    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
+      );
+
+      if (checkResult.found && checkResult.findOrCreate) {
+        // Return existing document instead of creating new one
+        return checkResult.existingDoc;
+      }
+      // If found but not findOrCreate, checkUniqueKeys already threw an error
+    }
+
+    // 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(payload, documentSchema);
+      validateDocument(normalizedPayload, documentSchema);
     }
 
     // Prepare the document for Firestore and add metadata
     // Always ensure status is set
     const documentData = {
-      ...prepareForFirestore(payload),
+      ...prepareForFirestore(normalizedPayload),
       status, // Ensure status is always present
       ...createMetadata(uid),
     };

package/src/firebase/crud/list.ts

@@ -128,10 +128,41 @@ function listEntitiesLogicFactory(
     const schemaHasEntries = !!(documentSchema as any)?.entries;
     console.log(`[listEntities] Schema has entries: ${schemaHasEntries}`);
 
+    // Helper: Check if value is a Picture object (has thumbUrl and fullUrl)
+    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) {
+        // Array of pictures - return just the first picture's thumbUrl
+        const firstPicture = value[0];
+        if (isPictureObject(firstPicture)) {
+          return firstPicture.thumbUrl || firstPicture.fullUrl || null;
+        }
+        // If first item is a string, return it as-is
+        if (typeof firstPicture === 'string') {
+          return firstPicture;
+        }
+      } else if (isPictureObject(value)) {
+        // Single picture object - return thumbUrl
+        return value.thumbUrl || value.fullUrl || null;
+      }
+      // Not a picture, return as-is
+      return value;
+    };
+
     // Filter document fields based on visibility and user role
     const docs = snapshot.docs.map((doc: any) => {
+      const rawData = doc.data() || {};
       const visibleData = filterVisibleFields(
-        doc.data() || {},
+        rawData,
         documentSchema,
         userRole
       );
@@ -141,24 +172,23 @@ function listEntitiesLogicFactory(
         const filtered: Record<string, any> = { id: doc.id };
         for (const field of listFields) {
           if (field in visibleData) {
-            filtered[field] = visibleData[field];
+            const value = visibleData[field];
+            // Optimize picture fields for list views (only need first thumbUrl)
+            filtered[field] = optimizePictureField(value);
           }
         }
         return filtered;
       }
 
       // No listFields restriction, return all visible fields
-      return {
-        id: doc.id,
-        ...visibleData,
-      };
+      // Still optimize picture fields for all list queries (datatables only need thumbUrl)
+      const optimizedData: Record<string, any> = { id: doc.id };
+      for (const [key, value] of Object.entries(visibleData)) {
+        optimizedData[key] = optimizePictureField(value);
+      }
+      return optimizedData;
     });
 
-    // DEBUG: Log filtered docs
-    console.log(
-      `[listEntities] Filtered docs count: ${docs.length}, first doc keys: ${docs[0] ? Object.keys(docs[0]).join(', ') : 'N/A'}`
-    );
-
     // Return the paginated result with metadata
     return {
       items: transformFirestoreData(docs),

package/src/firebase/crud/update.ts

@@ -12,7 +12,7 @@
 import * as v from 'valibot';
 
 import { DEFAULT_STATUS_VALUE } from '@donotdev/core/server';
-import type { UserRole } from '@donotdev/core/server';
+import type { UserRole, UniqueKeyDefinition } from '@donotdev/core/server';
 import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
 
 import {
@@ -28,6 +28,7 @@ import type {
   CallableFunction,
   CallableRequest,
 } from 'firebase-functions/v2/https';
+import type { Query, DocumentData } from 'firebase-admin/firestore';
 
 export type UpdateEntityRequest = {
   id: string;
@@ -35,9 +36,110 @@ export type UpdateEntityRequest = {
   idempotencyKey?: string;
 };
 
+/**
+ * Normalize a value for case-insensitive comparison
+ * Lowercases strings, leaves other types unchanged
+ */
+function normalizeValue(value: unknown): unknown {
+  if (typeof value === 'string') {
+    return value.toLowerCase();
+  }
+  return value;
+}
+
+/**
+ * Normalize unique key fields in payload to lowercase (for strings)
+ * Returns a new object with normalized values for unique key fields
+ */
+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;
+}
+
+/**
+ * Checks unique key constraints for updates
+ * Only checks if unique key fields are being modified
+ * Excludes the current document from conflict check
+ *
+ * @param collection - Firestore collection name
+ * @param currentDocId - ID of document being updated (excluded from check)
+ * @param mergedData - Merged document data (current + payload)
+ * @param payload - Update payload (only fields being changed)
+ * @param uniqueKeys - Unique key definitions from entity
+ * @param isDraft - Whether the resulting document is a draft
+ */
+async function checkUniqueKeysForUpdate(
+  collection: string,
+  currentDocId: string,
+  mergedData: Record<string, any>,
+  payload: Record<string, any>,
+  uniqueKeys: UniqueKeyDefinition[],
+  isDraft: boolean
+): Promise<void> {
+  const db = getFirebaseAdminFirestore();
+
+  for (const uniqueKey of uniqueKeys) {
+    // Skip validation for drafts if configured (default: true)
+    const skipForDrafts = uniqueKey.skipForDrafts !== false;
+    if (isDraft && skipForDrafts) continue;
+
+    // Check if any of the unique key fields are being updated
+    const isUpdatingUniqueKeyField = uniqueKey.fields.some(
+      (field) => field in payload
+    );
+    if (!isUpdatingUniqueKeyField) continue;
+
+    // Check if all fields in the unique key have values in merged data
+    const allFieldsHaveValues = uniqueKey.fields.every(
+      (field) => mergedData[field] != null && mergedData[field] !== ''
+    );
+    if (!allFieldsHaveValues) continue;
+
+    // Build query for all fields in this unique key
+    // Normalize values to lowercase for case-insensitive matching
+    let query: Query<DocumentData> = db.collection(collection);
+    for (const field of uniqueKey.fields) {
+      query = query.where(field, '==', normalizeValue(mergedData[field]));
+    }
+
+    const existing = await query.limit(2).get(); // Get 2 to check if another doc exists
+
+    // Check if any matching document is NOT the current document
+    const conflictingDoc = existing.docs.find((doc) => doc.id !== currentDocId);
+
+    if (conflictingDoc) {
+      const fieldNames = uniqueKey.fields.join(' + ');
+      throw new DoNotDevError(
+        uniqueKey.errorMessage || `Duplicate ${fieldNames}`,
+        'already-exists',
+        {
+          details: {
+            fields: uniqueKey.fields,
+            existingId: conflictingDoc.id,
+          },
+        }
+      );
+    }
+  }
+}
+
 /**
  * Generic business logic for updating entities
  * Base function handles: validation, auth, rate limiting, monitoring
+ *
+ * @version 0.0.2
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
  */
 function updateEntityLogicFactory(
   collection: string,
@@ -80,15 +182,39 @@ function updateEntityLogicFactory(
     const resultingStatus = mergedData.status ?? DEFAULT_STATUS_VALUE;
     const isDraft = resultingStatus === 'draft';
 
+    // Check unique keys if schema has metadata with uniqueKeys
+    // Only checks fields that are being updated
+    const schemaWithMeta = documentSchema as {
+      metadata?: { uniqueKeys?: UniqueKeyDefinition[] };
+    };
+    const uniqueKeys = schemaWithMeta.metadata?.uniqueKeys;
+
+    if (uniqueKeys && uniqueKeys.length > 0) {
+      await checkUniqueKeysForUpdate(
+        collection,
+        id,
+        mergedData,
+        payload,
+        uniqueKeys,
+        isDraft
+      );
+    }
+
     // Validate the merged document against the schema
     // Skip validation for drafts - required fields can be incomplete
     if (!isDraft) {
       validateDocument(mergedData, documentSchema);
     }
 
+    // Normalize unique key fields to lowercase for case-insensitive storage
+    const normalizedPayload =
+      uniqueKeys && uniqueKeys.length > 0
+        ? normalizePayloadForUniqueKeys(payload, uniqueKeys)
+        : payload;
+
     // Prepare the update data for Firestore and add metadata
     const updateData = {
-      ...prepareForFirestore(payload),
+      ...prepareForFirestore(normalizedPayload),
       ...updateMetadata(uid),
     };
 

package/src/shared/firebase.ts

@@ -158,7 +158,8 @@ export function transformFirestoreData<T = any>(
 }
 
 /**
- * Recursively prepares data for Firestore by converting ISO strings or Date objects to Timestamps.
+ * Recursively prepares data for Firestore by converting Date objects to ISO strings.
+ * ISO strings are kept as-is (no conversion needed).
  * @param data - The data to prepare
  * @param removeFields - Optional array of field names to remove
  * @returns The prepared data
@@ -189,14 +190,11 @@ export function prepareForFirestore<T = any>(
         continue;
       }
 
-      // Handle Date objects
+      // Handle Date objects - convert to ISO string
       if (value instanceof Date) {
-        prepared[key] = toTimestamp(value);
-      }
-      // Handle ISO strings that look like dates
-      else if (typeof value === 'string' && isISODateString(value)) {
-        prepared[key] = toTimestamp(value);
+        prepared[key] = value.toISOString();
       }
+      // ISO strings stay as strings - no conversion needed
       // Handle nested objects and arrays
       else {
         prepared[key] = prepareForFirestore(value, removeFields);
@@ -205,15 +203,12 @@ export function prepareForFirestore<T = any>(
     return prepared as T;
   }
 
-  // Handle Date objects at root level
+  // Handle Date objects at root level - convert to ISO string
   if (data instanceof Date) {
-    return toTimestamp(data) as unknown as T;
+    return data.toISOString() as unknown as T;
   }
 
-  // Handle ISO strings at root level
-  if (typeof data === 'string' && isISODateString(data)) {
-    return toTimestamp(data) as unknown as T;
-  }
+  // ISO strings stay as strings - no conversion needed
 
   // Return primitive values unchanged
   return data;