@donotdev/functions 0.0.8 → 0.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donotdev/functions",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "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.23",
+    "@donotdev/firebase": "^0.0.10"
   },
   "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/config/constants.ts

@@ -30,15 +30,12 @@ export const FUNCTION_CONFIG = {
   cors: true, // Enable CORS by default for all functions (required for web apps)
 } as const;
 
-import { stripeSecretKey, stripeWebhookSecret } from './secrets.js';
-
 /** Stripe/billing functions */
 export const STRIPE_CONFIG = {
   ...BASE_CONFIG,
   memory: '512MiB' as const,
   timeoutSeconds: 30,
   cors: true,
-  secrets: [stripeSecretKey, stripeWebhookSecret],
 };
 
 /** Auth functions */

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/get.ts

@@ -16,7 +16,7 @@ import {
   hasRoleAccess,
   HIDDEN_STATUSES,
 } from '@donotdev/core/server';
-import type { UserRole } from '@donotdev/core/server';
+import type { EntityOwnershipConfig, UserRole } from '@donotdev/core/server';
 import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
 
 import { transformFirestoreData } from '../../shared/index.js';
@@ -37,14 +37,15 @@ export type GetEntityRequest = { id: string };
  */
 function getEntityLogicFactory(
   collection: string,
-  documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>
+  documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
+  ownership?: EntityOwnershipConfig
 ) {
   return async function getEntityLogic(
     data: GetEntityRequest,
     context: { uid: string; userRole: UserRole; request: CallableRequest<any> }
   ) {
     const { id } = data;
-    const { userRole } = context;
+    const { userRole, uid } = context;
 
     // Get the document reference
     const db = getFirebaseAdminFirestore();
@@ -69,11 +70,16 @@ function getEntityLogicFactory(
       throw new DoNotDevError('Entity not found', 'not-found');
     }
 
-    // Filter fields based on visibility and user role
+    const rawData = docData || {};
+    const visibilityOptions =
+      ownership && uid ? { documentData: rawData, uid, ownership } : undefined;
+
+    // Filter fields based on visibility and user role (and ownership for visibility: 'owner')
     const filteredData = filterVisibleFields(
-      docData || {},
+      rawData,
       documentSchema,
-      userRole
+      userRole,
+      visibilityOptions
     );
 
     // Transform the document data back to the application format
@@ -90,13 +96,15 @@ function getEntityLogicFactory(
  * @param documentSchema - The Valibot schema for document validation
  * @param requiredRole - Minimum role required for this operation
  * @param customSchema - Optional custom request schema
+ * @param ownership - Optional ownership config for visibility: 'owner' field masking
  * @returns Firebase callable function
  */
 export const getEntity = (
   collection: string,
   documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
   requiredRole: UserRole,
-  customSchema?: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>
+  customSchema?: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
+  ownership?: EntityOwnershipConfig
 ): CallableFunction<GetEntityRequest, Promise<any>> => {
   const requestSchema =
     customSchema ||
@@ -108,7 +116,7 @@ export const getEntity = (
     CRUD_READ_CONFIG,
     requestSchema,
     'get_entity',
-    getEntityLogicFactory(collection, documentSchema),
+    getEntityLogicFactory(collection, documentSchema, ownership),
     requiredRole
   );
 };

package/src/firebase/crud/list.ts

@@ -16,7 +16,11 @@ import {
   hasRoleAccess,
   HIDDEN_STATUSES,
 } from '@donotdev/core/server';
-import type { UserRole } from '@donotdev/core/server';
+import type {
+  EntityOwnershipConfig,
+  EntityOwnershipPublicCondition,
+  UserRole,
+} from '@donotdev/core/server';
 import { getFirebaseAdminFirestore, Query } from '@donotdev/firebase/server';
 
 import { transformFirestoreData } from '../../shared/index.js';
@@ -40,6 +44,20 @@ export interface ListEntityRequest {
   };
 }
 
+/**
+ * Apply public-condition where clauses to a query (for listCard when ownership is set).
+ */
+function applyPublicCondition(
+  query: Query,
+  publicCondition: EntityOwnershipPublicCondition[]
+): Query {
+  let q = query;
+  for (const c of publicCondition) {
+    q = q.where(c.field, c.op as any, c.value);
+  }
+  return q;
+}
+
 /**
  * Generic business logic for listing entities
  * Base function handles: validation, auth, rate limiting, monitoring
@@ -47,7 +65,9 @@ export interface ListEntityRequest {
 function listEntitiesLogicFactory(
   collection: string,
   documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
-  listFields?: string[]
+  listFields?: string[],
+  ownership?: EntityOwnershipConfig,
+  isListCard?: boolean
 ) {
   return async function listEntitiesLogic(
     data: ListEntityRequest,
@@ -58,7 +78,8 @@ function listEntitiesLogicFactory(
     }
   ) {
     const { where = [], orderBy = [], limit, startAfterId, search } = data;
-    const { userRole } = context;
+    // Extract uid and userRole once (reused for all document masking)
+    const { userRole, uid } = context;
 
     const isAdmin = hasRoleAccess(userRole, 'admin'); // Uses role hierarchy
 
@@ -71,6 +92,26 @@ function listEntitiesLogicFactory(
       query = query.where('status', 'not-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) {
+        // "Mine" filter: Firestore does not support OR across different fields in one query.
+        // Use first owner field only for single query; recommend ownerIds array-contains for multiple.
+        const firstOwnerField = ownership.ownerFields[0];
+        query = query.where(firstOwnerField, '==', uid);
+        if (ownership.ownerFields.length > 1) {
+          // Optional: run second query and merge (complex pagination). For now, single field only.
+          // Document ownerIds pattern for multiple stakeholders.
+        }
+      }
+    }
+
     // Apply search if provided
     if (search) {
       const { field, query: searchQuery } = search;
@@ -128,12 +169,48 @@ function listEntitiesLogicFactory(
     const schemaHasEntries = !!(documentSchema as any)?.entries;
     console.log(`[listEntities] Schema has entries: ${schemaHasEntries}`);
 
-    // Filter document fields based on visibility and user role
+    // 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;
+    };
+
+    const visibilityOptions = ownership && uid ? { uid, ownership } : undefined;
+
+    // Filter document fields based on visibility and user role (uid/userRole from context, once)
     const docs = snapshot.docs.map((doc: any) => {
+      const rawData = doc.data() || {};
       const visibleData = filterVisibleFields(
-        doc.data() || {},
+        rawData,
         documentSchema,
-        userRole
+        userRole,
+        visibilityOptions
+          ? { ...visibilityOptions, documentData: rawData }
+          : undefined
       );
 
       // If listFields specified, filter to only those fields (plus id always)
@@ -141,24 +218,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),
@@ -176,6 +252,8 @@ function listEntitiesLogicFactory(
  * @param requiredRole - Minimum role required for this operation
  * @param customSchema - Optional custom request schema
  * @param listFields - Optional array of field names to include (plus id). If not provided, all visible fields are returned.
+ * @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 Firebase callable function
  */
 export const listEntities = (
@@ -183,7 +261,9 @@ export const listEntities = (
   documentSchema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
   requiredRole: UserRole,
   customSchema?: v.BaseSchema<unknown, any, v.BaseIssue<unknown>>,
-  listFields?: string[]
+  listFields?: string[],
+  ownership?: EntityOwnershipConfig,
+  isListCard?: boolean
 ): CallableFunction<ListEntityRequest, Promise<any>> => {
   const requestSchema =
     customSchema ||
@@ -206,7 +286,13 @@ export const listEntities = (
     CRUD_READ_CONFIG,
     requestSchema,
     'list_entities',
-    listEntitiesLogicFactory(collection, documentSchema, listFields),
+    listEntitiesLogicFactory(
+      collection,
+      documentSchema,
+      listFields,
+      ownership,
+      isListCard
+    ),
     requiredRole
   );
 };

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/firebase/registerCrudFunctions.ts

@@ -67,14 +67,23 @@ export function createCrudFunctions(
       schemas.create,
       access.create
     );
-    functions[`${prefix}get_${col}`] = getEntity(col, schemas.get, access.read);
+    functions[`${prefix}get_${col}`] = getEntity(
+      col,
+      schemas.get,
+      access.read,
+      undefined,
+      entity.ownership
+    );
     // Use schemas.get for visibility filtering, entity.listFields for field selection
+    // When ownership is set: list = "mine" filter, listCard = public condition
     functions[`${prefix}list_${col}`] = listEntities(
       col,
       schemas.get,
       access.read,
       undefined,
-      entity.listFields
+      entity.listFields,
+      entity.ownership,
+      false
     );
     // Always create listCard - uses same schemas.get, field selection via listCardFields ?? listFields ?? undefined
     functions[`${prefix}listCard_${col}`] = listEntities(
@@ -82,7 +91,9 @@ export function createCrudFunctions(
       schemas.get,
       access.read,
       undefined,
-      entity.listCardFields ?? entity.listFields ?? undefined
+      entity.listCardFields ?? entity.listFields ?? undefined,
+      entity.ownership,
+      true
     );
     functions[`${prefix}update_${col}`] = updateEntity(
       col,

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;

package/src/shared/schema.ts

@@ -12,7 +12,7 @@
 import * as v from 'valibot';
 
 /** Visibility levels matching @donotdev/core */
-type Visibility = 'guest' | 'user' | 'admin' | 'technical' | 'hidden';
+type Visibility = 'guest' | 'user' | 'admin' | 'technical' | 'hidden' | 'owner';
 
 // Define a type for the custom visibility property we might add to Valibot schemas
 interface ValibotSchemaWithVisibility extends v.BaseSchema<
@@ -52,6 +52,7 @@ function getFieldVisibility(field: any): Visibility | undefined {
  * - 'admin': Visible only to admins
  * - 'technical': Visible to admins only (shown as read-only in edit forms)
  * - 'hidden': Never visible (passwords, tokens, API keys - only in DB)
+ * - 'owner': Visible only when uid matches one of entity.ownership.ownerFields (requires document context; here treated as not visible for aggregate)
  * - undefined: Defaults to 'user' behavior (visible to authenticated users)
  *
  * @param key - The name (key) of the field.
@@ -90,6 +91,11 @@ export function isFieldVisible(
     return isAdmin;
   }
 
+  // Owner: requires per-document check (documentData, uid, ownership); not available in aggregate context
+  if (visibility === 'owner') {
+    return false;
+  }
+
   // User fields (or undefined/default) are visible to authenticated users
   if (visibility === 'user' || visibility === undefined) {
     return isAuthenticated;