@ponceca/firestore-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ponceca
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,692 @@
+# @ponceca/firestore-sdk
+
+SDK JavaScript/TypeScript 100% compatible con Firebase Firestore v9+ (API modular).
+
+**Migrar desde Firebase es tan simple como cambiar el import.**
+
+## Instalación
+
+```bash
+npm install @ponceca/firestore-sdk
+```
+
+## Importación “igual” al SDK oficial (estilo Firebase)
+
+Ahora puedes importar igual que Firebase:
+
+- `@ponceca/firestore-sdk/app` (equivalente a `firebase/app`)
+- `@ponceca/firestore-sdk/firestore` (equivalente a `firebase/firestore`)
+
+## Configuración - Idéntica a Firebase
+
+### Opción 1: Conectar al Emulador (Recomendado para desarrollo)
+
+```typescript
+import { initializeApp } from '@ponceca/firestore-sdk/app';
+import { 
+  getFirestore, 
+  connectFirestoreEmulator 
+} from '@ponceca/firestore-sdk/firestore';
+
+// Inicializar app (igual que Firebase)
+const app = initializeApp({
+  projectId: 'my-project',
+});
+
+// Obtener Firestore
+const db = getFirestore(app);
+
+// Conectar al servidor local (igual que Firebase emulator)
+connectFirestoreEmulator(db, 'localhost', 3000);
+```
+
+### Opción 2: Configuración en initializeFirestore
+
+```typescript
+import { initializeApp } from '@ponceca/firestore-sdk/app';
+import { initializeFirestore } from '@ponceca/firestore-sdk/firestore';
+
+const app = initializeApp({
+  projectId: 'my-project',
+});
+
+// Configuración avanzada
+const db = initializeFirestore(app, {
+  host: 'localhost:3000',
+  ssl: false,
+});
+```
+
+### Perfil recomendado para producción (balanceado)
+
+```typescript
+import { initializeApp } from '@ponceca/firestore-sdk/app';
+import { initializeFirestore } from '@ponceca/firestore-sdk/firestore';
+
+const app = initializeApp({
+  projectId: 'my-project',
+});
+
+const db = initializeFirestore(app, {
+  host: 'api.my-firestore-clone.com',
+  ssl: true,
+  timeout: 12000,
+  maxRetries: 2,
+  retryInitialDelayMs: 150,
+  retryMaxDelayMs: 2000,
+});
+```
+
+### Opción 3: Configuración con baseUrl (Conveniente)
+
+```typescript
+import { initializeApp } from '@ponceca/firestore-sdk/app';
+
+const app = initializeApp({
+  projectId: 'my-project',
+  baseUrl: 'http://localhost:3000', // Auto-configura host y ssl
+});
+
+const db = getFirestore(app);
+```
+
+## Migrar desde Firebase
+
+```diff
+- import { initializeApp } from 'firebase/app';
+- import { getFirestore, doc, setDoc } from 'firebase/firestore';
++ import { initializeApp } from '@ponceca/firestore-sdk/app';
++ import { getFirestore, doc, setDoc } from '@ponceca/firestore-sdk/firestore';
+
+const app = initializeApp({ projectId: 'my-project' });
+const db = getFirestore(app);
+
++ // Conectar a tu servidor (en desarrollo)
++ connectFirestoreEmulator(db, 'localhost', 3000);
+
+// ¡El resto del código es IDÉNTICO!
+await setDoc(doc(db, 'users', 'user1'), { name: 'Juan' });
+```
+
+## Uso Básico
+
+```typescript
+import { initializeApp } from '@ponceca/firestore-sdk/app';
+import {
+  getFirestore,
+  connectFirestoreEmulator,
+  collection,
+  doc,
+  getDoc,
+  setDoc,
+  updateDoc,
+  deleteDoc,
+  addDoc,
+  query,
+  where,
+  orderBy,
+  limit,
+  getDocs,
+  onSnapshot,
+  serverTimestamp,
+} from '@ponceca/firestore-sdk/firestore';
+
+// 1. Inicializar app
+const app = initializeApp({
+  projectId: 'my-project',
+});
+
+// 2. Obtener instancia de Firestore
+const db = getFirestore(app);
+
+// 3. Conectar al servidor (desarrollo local)
+connectFirestoreEmulator(db, 'localhost', 3000);
+
+// 4. Crear referencia a documento
+const userRef = doc(db, 'users', 'user123');
+
+// 5. Escribir documento
+await setDoc(userRef, {
+  name: 'Juan García',
+  email: 'juan@example.com',
+  age: 25,
+  createdAt: serverTimestamp(),
+});
+
+// 6. Leer documento
+const snapshot = await getDoc(userRef);
+if (snapshot.exists()) {
+  console.log('Usuario:', snapshot.data());
+}
+
+// 7. Actualizar documento
+await updateDoc(userRef, {
+  age: 26,
+  'address.city': 'Madrid', // Actualización anidada
+});
+
+// 8. Eliminar documento
+await deleteDoc(userRef);
+
+// 9. Añadir documento con ID automático
+const newDocRef = await addDoc(collection(db, 'posts'), {
+  title: 'Mi primer post',
+  content: 'Hola mundo!',
+  createdAt: serverTimestamp(),
+});
+console.log('Nuevo ID:', newDocRef.id);
+```
+
+## Autenticación
+
+El SDK soporta múltiples formas de autenticación, idéntico a Firebase:
+
+### Opción 1: Token Manual (Simple)
+
+```typescript
+import { 
+  getFirestore, 
+  setAuthToken,
+  getAuthToken 
+} from '@ponceca/firestore-sdk/firestore';
+
+const db = getFirestore(app);
+
+// Establecer token JWT
+const token = await myAuthService.getToken();
+setAuthToken(db, token);
+
+// Verificar token actual
+console.log('Token:', getAuthToken(db));
+
+// Logout - eliminar token
+setAuthToken(db, null);
+```
+
+### Opción 2: AuthTokenProvider (Automático - Recomendado)
+
+Igual que Firebase Auth se integra automáticamente con Firestore:
+
+```typescript
+import { 
+  initializeFirestore,
+  type AuthTokenProvider 
+} from '@ponceca/firestore-sdk/firestore';
+
+// Crear un provider que obtiene tokens automáticamente
+const authProvider: AuthTokenProvider = {
+  // Obtiene el token actual (llamado en cada request)
+  async getToken() {
+    const user = myAuthService.currentUser;
+    return user ? await user.getIdToken() : null;
+  },
+  
+  // Opcional: escucha cambios de auth
+  onAuthStateChanged(callback) {
+    return myAuthService.onAuthStateChanged((user) => {
+      callback(user ? user.token : null);
+    });
+  }
+};
+
+// Configurar Firestore con el provider
+const db = initializeFirestore(app, {
+  host: 'localhost:3000',
+  ssl: false,
+  authTokenProvider: authProvider
+});
+
+// Ahora cada request obtiene el token automáticamente
+await setDoc(doc(db, 'users', 'user1'), { name: 'Juan' }); // Token incluido!
+```
+
+### Opción 3: Integración con Firebase Auth
+
+```typescript
+import { getAuth, onAuthStateChanged } from 'firebase/auth';
+import { initializeFirestore, type AuthTokenProvider } from '@ponceca/firestore-sdk/firestore';
+
+const firebaseAuth = getAuth();
+
+// Provider que usa Firebase Auth
+const firebaseAuthProvider: AuthTokenProvider = {
+  async getToken() {
+    const user = firebaseAuth.currentUser;
+    return user ? await user.getIdToken() : null;
+  },
+  onAuthStateChanged(callback) {
+    return onAuthStateChanged(firebaseAuth, async (user) => {
+      callback(user ? await user.getIdToken() : null);
+    });
+  }
+};
+
+const db = initializeFirestore(app, {
+  host: 'localhost:3000',
+  authTokenProvider: firebaseAuthProvider
+});
+```
+
+### Opción 4: Mock Token para Testing
+
+```typescript
+connectFirestoreEmulator(db, 'localhost', 3000, {
+  mockUserToken: { 
+    sub: 'user123', 
+    email: 'test@example.com',
+    // Simular claims personalizados
+    admin: true 
+  }
+});
+```
+
+## Queries
+
+```typescript
+// Query con filtros
+const q = query(
+  collection(db, 'users'),
+  where('age', '>=', 18),
+  where('status', '==', 'active'),
+  orderBy('age', 'desc'),
+  limit(10)
+);
+
+const querySnapshot = await getDocs(q);
+querySnapshot.forEach((doc) => {
+  console.log(doc.id, '=>', doc.data());
+});
+
+// Operadores disponibles
+where('field', '==', value);   // Igual
+where('field', '!=', value);   // No igual
+where('field', '<', value);    // Menor que
+where('field', '<=', value);   // Menor o igual
+where('field', '>', value);    // Mayor que
+where('field', '>=', value);   // Mayor o igual
+where('field', 'in', [values]);           // En array
+where('field', 'not-in', [values]);       // No en array
+where('field', 'array-contains', value);  // Array contiene
+where('field', 'array-contains-any', [values]); // Array contiene cualquiera
+```
+
+### Modo flexible (opt-in)
+
+En Firestore original, si usas un filtro de rango (ej: `where('price', '>=', 600)`),
+el primer `orderBy` debe ser sobre ese mismo campo. En PostgreSQL no es necesario.
+
+Si quieres permitir queries más flexibles, activa el flag `allowFlexibleQueries`:
+
+```typescript
+const db = initializeFirestore(app, {
+  host: 'localhost:3000',
+  ssl: false,
+  allowFlexibleQueries: true,
+});
+
+// Ahora es válido:
+const q = query(
+  collection(db, 'products'),
+  where('price', '>=', 600),
+  orderBy('rating', 'desc')  // Ordenar por campo diferente al del filtro de rango
+);
+```
+
+📖 Ver [documentación completa del modo flexible](docs/FLEXIBLE_QUERIES.md) con más ejemplos y casos de uso.
+
+## Real-time Listeners
+
+```typescript
+// Escuchar cambios en documento
+const unsubscribe = onSnapshot(userRef, (snapshot) => {
+  if (snapshot.exists()) {
+    console.log('Datos actualizados:', snapshot.data());
+  }
+});
+
+// Escuchar cambios en query
+const q = query(collection(db, 'messages'), orderBy('timestamp', 'desc'), limit(50));
+const unsubscribeQuery = onSnapshot(q, (snapshot) => {
+  snapshot.docChanges().forEach((change) => {
+    if (change.type === 'added') {
+      console.log('Nuevo mensaje:', change.doc.data());
+    }
+    if (change.type === 'modified') {
+      console.log('Mensaje modificado:', change.doc.data());
+    }
+    if (change.type === 'removed') {
+      console.log('Mensaje eliminado:', change.doc.id);
+    }
+  });
+});
+
+// Cancelar suscripción
+unsubscribe();
+unsubscribeQuery();
+```
+
+## Field Values Especiales
+
+```typescript
+import {
+  serverTimestamp,
+  increment,
+  arrayUnion,
+  arrayRemove,
+  deleteField,
+} from '@ponceca/firestore-sdk/firestore';
+
+// Timestamp del servidor
+await setDoc(ref, { createdAt: serverTimestamp() });
+
+// Incrementar valor numérico
+await updateDoc(ref, { views: increment(1) });
+
+// Añadir elementos a array (sin duplicados)
+await updateDoc(ref, { tags: arrayUnion('new-tag') });
+
+// Eliminar elementos de array
+await updateDoc(ref, { tags: arrayRemove('old-tag') });
+
+// Eliminar campo
+await updateDoc(ref, { oldField: deleteField() });
+```
+
+## Batch Writes
+
+```typescript
+import { writeBatch } from '@ponceca/firestore-sdk/firestore';
+
+const batch = writeBatch(db);
+
+batch.set(doc(db, 'cities', 'NYC'), { name: 'New York' });
+batch.update(doc(db, 'cities', 'LA'), { population: 4000000 });
+batch.delete(doc(db, 'cities', 'OLD'));
+
+await batch.commit();
+```
+
+## Transacciones
+
+```typescript
+import { runTransaction } from '@ponceca/firestore-sdk/firestore';
+
+const newBalance = await runTransaction(db, async (transaction) => {
+  const accountRef = doc(db, 'accounts', 'account1');
+  const accountDoc = await transaction.get(accountRef);
+
+  if (!accountDoc.exists()) {
+    throw new Error('Account does not exist');
+  }
+
+  const currentBalance = accountDoc.data()!.balance;
+  const newBalance = currentBalance - 100;
+
+  if (newBalance < 0) {
+    throw new Error('Insufficient funds');
+  }
+
+  transaction.update(accountRef, { balance: newBalance });
+  return newBalance;
+});
+```
+
+## Subcolecciones
+
+```typescript
+// Crear referencia a subcolección
+const postsRef = collection(db, 'users', 'user123', 'posts');
+
+// O desde documento
+const userRef = doc(db, 'users', 'user123');
+const postsRef2 = collection(userRef, 'posts');
+
+// Añadir documento a subcolección
+await addDoc(postsRef, {
+  title: 'Mi post',
+  content: 'Contenido...',
+});
+
+// Query en subcolección
+const recentPosts = await getDocs(
+  query(postsRef, orderBy('createdAt', 'desc'), limit(5))
+);
+```
+
+## Tipos TypeScript
+
+El SDK incluye tipos completos para TypeScript:
+
+```typescript
+import type {
+  DocumentData,
+  DocumentReference,
+  CollectionReference,
+  Query,
+  DocumentSnapshot,
+  QuerySnapshot,
+  Firestore,
+  FieldValue,
+} from '@ponceca/firestore-sdk/firestore';
+
+// Tipos personalizados
+interface User {
+  name: string;
+  email: string;
+  age: number;
+}
+
+const userRef = doc(db, 'users', 'user123') as DocumentReference<User>;
+const snapshot = await getDoc(userRef);
+
+if (snapshot.exists()) {
+  const user: User = snapshot.data()!;
+  console.log(user.name); // TypeScript conoce el tipo
+}
+```
+
+## Compatibilidad con Firebase
+
+Este SDK es un drop-in replacement para Firebase Firestore v9. Para migrar:
+
+```typescript
+// Antes (Firebase)
+import { initializeApp } from 'firebase/app';
+import { getFirestore, doc, getDoc } from 'firebase/firestore';
+
+// Después (Este SDK)
+import { initializeApp } from '@ponceca/firestore-sdk/app';
+import { getFirestore, doc, getDoc } from '@ponceca/firestore-sdk/firestore';
+```
+
+## Queries Avanzadas
+
+```typescript
+import { and, or, collectionGroup } from '@ponceca/firestore-sdk/firestore';
+
+// Filtros compuestos con AND/OR
+const q = query(
+  collection(db, 'products'),
+  and(
+    where('category', '==', 'electronics'),
+    or(
+      where('price', '<', 100),
+      where('onSale', '==', true)
+    )
+  )
+);
+
+// Collection Group Query (buscar en todas las subcolecciones con mismo ID)
+const allComments = query(
+  collectionGroup(db, 'comments'),
+  where('author', '==', 'john'),
+  orderBy('createdAt', 'desc'),
+  limit(10)
+);
+```
+
+## Agregaciones
+
+```typescript
+import { getCountFromServer, getAggregateFromServer, count, sum, average } from '@ponceca/firestore-sdk/firestore';
+
+// Contar documentos
+const countSnapshot = await getCountFromServer(query(collection(db, 'users')));
+console.log('Total users:', countSnapshot.data().count);
+
+// Múltiples agregaciones
+const snapshot = await getAggregateFromServer(
+  query(collection(db, 'orders'), where('status', '==', 'completed')),
+  {
+    totalOrders: count(),
+    totalRevenue: sum('amount'),
+    avgOrderValue: average('amount')
+  }
+);
+
+console.log('Total orders:', snapshot.data().totalOrders);
+console.log('Total revenue:', snapshot.data().totalRevenue);
+console.log('Average order:', snapshot.data().avgOrderValue);
+```
+
+## Tipos Especiales
+
+```typescript
+import { Timestamp, GeoPoint, Bytes, FieldPath, documentId, vector } from '@ponceca/firestore-sdk/firestore';
+
+// Timestamp
+const ts = Timestamp.now();
+const tsFromDate = Timestamp.fromDate(new Date());
+console.log(ts.toDate());
+
+// GeoPoint
+const location = new GeoPoint(37.7749, -122.4194);
+console.log(location.latitude, location.longitude);
+
+// Bytes
+const bytes = Bytes.fromBase64String('SGVsbG8gV29ybGQ=');
+console.log(bytes.toUint8Array());
+
+// FieldPath para campos anidados
+const path = new FieldPath('user', 'address', 'city');
+
+// documentId() para filtrar por ID de documento
+const q = query(
+  collection(db, 'users'),
+  where(documentId(), 'in', ['user1', 'user2', 'user3'])
+);
+
+// Vector para embeddings/ML
+const embedding = vector([0.1, 0.2, 0.3, 0.4]);
+await setDoc(docRef, { embedding });
+```
+
+## Utilidades
+
+```typescript
+import { refEqual, queryEqual, snapshotEqual, onSnapshotsInSync } from '@ponceca/firestore-sdk/firestore';
+
+// Comparar referencias
+const ref1 = doc(db, 'users', '123');
+const ref2 = doc(db, 'users', '123');
+console.log(refEqual(ref1, ref2)); // true
+
+// Comparar queries
+const q1 = query(collection(db, 'users'), where('age', '>=', 18));
+const q2 = query(collection(db, 'users'), where('age', '>=', 18));
+console.log(queryEqual(q1, q2)); // true
+
+// Notificación cuando todos los listeners están sincronizados
+const unsubSync = onSnapshotsInSync(db, () => {
+  console.log('All snapshots are in sync');
+});
+```
+
+## API Reference
+
+### App
+
+- `initializeApp(options, name?)` - Inicializa la app
+- `getApp(name?)` - Obtiene app existente
+- `getApps()` - Lista todas las apps
+- `deleteApp(app)` - Elimina una app
+
+### Firestore
+
+- `getFirestore(app?)` - Obtiene instancia de Firestore
+- `initializeFirestore(app, settings)` - Inicializa con configuración
+- `terminate(firestore)` - Termina instancia
+
+### Referencias
+
+- `doc(firestore, path, ...segments)` - Referencia a documento
+- `collection(firestore, path, ...segments)` - Referencia a colección
+- `collectionGroup(firestore, collectionId)` - Query sobre grupo de colecciones
+
+### CRUD
+
+- `getDoc(ref)` - Lee documento
+- `setDoc(ref, data, options?)` - Escribe documento
+- `updateDoc(ref, data)` - Actualiza campos
+- `deleteDoc(ref)` - Elimina documento
+- `addDoc(collectionRef, data)` - Añade con ID auto
+
+### Queries
+
+- `query(ref, ...constraints)` - Crea query
+- `where(field, op, value)` - Filtro
+- `orderBy(field, direction?)` - Ordenar
+- `limit(n)` - Limitar resultados
+- `limitToLast(n)` - Últimos N
+- `startAt(...values)` - Cursor inicio inclusivo
+- `startAfter(...values)` - Cursor inicio exclusivo
+- `endAt(...values)` - Cursor fin inclusivo
+- `endBefore(...values)` - Cursor fin exclusivo
+- `and(...constraints)` - Filtro AND compuesto
+- `or(...constraints)` - Filtro OR compuesto
+- `getDocs(query)` - Ejecuta query
+
+### Real-time
+
+- `onSnapshot(ref, onNext, onError?)` - Suscribe a cambios
+- `onSnapshotsInSync(firestore, callback)` - Sincronización de listeners
+
+### Agregaciones
+
+- `getCountFromServer(query)` - Cuenta documentos
+- `getAggregateFromServer(query, spec)` - Múltiples agregaciones
+- `count()` - Campo de conteo
+- `sum(field)` - Campo de suma
+- `average(field)` - Campo de promedio
+
+### Field Values
+
+- `serverTimestamp()` - Timestamp del servidor
+- `increment(n)` - Incrementar número
+- `arrayUnion(...values)` - Añadir a array
+- `arrayRemove(...values)` - Eliminar de array
+- `deleteField()` - Eliminar campo
+
+### Tipos Especiales
+
+- `Timestamp` - Clase para timestamps
+- `GeoPoint` - Clase para coordenadas
+- `Bytes` - Clase para datos binarios
+- `FieldPath` - Clase para paths de campos
+- `VectorValue` / `vector()` - Para embeddings/ML
+- `documentId()` - Referencia al ID de documento
+
+### Batch & Transactions
+
+- `writeBatch(firestore)` - Crea batch
+- `runTransaction(firestore, fn, options?)` - Ejecuta transacción
+
+### Utilidades
+
+- `refEqual(ref1, ref2)` - Compara referencias
+- `queryEqual(q1, q2)` - Compara queries
+- `snapshotEqual(s1, s2)` - Compara snapshots
+
+## Licencia
+
+MIT