npm package: @ponceca/firestore-sdk
Description: SDK JavaScript/TypeScript compatible con Firebase Firestore v9
Author: ponceca
Latest version: 1.1.8

# @ponceca/firestore-sdk

SDK JavaScript/TypeScript 100% compatible con Firebase v9+ (API modular).

**Migrar desde Firebase es tan simple como cambiar el import.**

## Instalación

```bash
npm install @ponceca/firestore-sdk
```

## Quick Start

```typescript
import { initializeApp } from '@ponceca/firestore-sdk';
import { getFirestore, doc, setDoc, getDoc } from '@ponceca/firestore-sdk/firestore';
import { getAuth, signInWithCustomToken } from '@ponceca/firestore-sdk';
import { getStorage, ref, uploadBytesResumable } from '@ponceca/firestore-sdk/storage';

// 1. Inicializar
const app = initializeApp({
  projectId: 'mi-proyecto',
  baseUrl: 'http://localhost:3000',       // Firestore backend
  storageUrl: 'http://localhost:3002/api', // Storage backend
  storageBucket: 'default',
});

// 2. Firestore
const db = getFirestore(app);
await setDoc(doc(db, 'users', 'u1'), { name: 'Juan', age: 28 });
const snap = await getDoc(doc(db, 'users', 'u1'));
console.log(snap.data()); // { name: 'Juan', age: 28 }

// 3. Auth
const auth = getAuth(app);
const user = await signInWithCustomToken(auth, 'eyJhbGci...');
console.log(user.uid);

// 4. Storage
const storage = getStorage(app);
const task = uploadBytesResumable(ref(storage, 'uploads/file.pdf'), fileBlob);
```

## Sub-entry points

| Import | Equivale a Firebase |
|--------|-------------------|
| `@ponceca/firestore-sdk` | `firebase/app` + Auth |
| `@ponceca/firestore-sdk/app` | `firebase/app` |
| `@ponceca/firestore-sdk/firestore` | `firebase/firestore` |
| `@ponceca/firestore-sdk/auth` | `firebase/auth` |
| `@ponceca/firestore-sdk/storage` | `firebase/storage` |

## Migrar desde Firebase

```diff
- import { initializeApp } from 'firebase/app';
- import { getFirestore, doc, setDoc } from 'firebase/firestore';
+ import { initializeApp } from '@ponceca/firestore-sdk';
+ import { getFirestore, doc, setDoc } from '@ponceca/firestore-sdk/firestore';

const app = initializeApp({
  projectId: 'my-project',
+ baseUrl: 'http://localhost:3000',
});

// ¡El resto del código es IDÉNTICO!
const db = getFirestore(app);
await setDoc(doc(db, 'users', 'u1'), { name: 'Juan' });
```

## Configuración por Entorno

```typescript
// Desarrollo (usa defaults: localhost:3000)
initializeApp({ projectId: 'dev-project' });

// Producción
initializeApp({
  projectId: 'prod-project',
  apiKey: 'mi-api-key',
  baseUrl: 'https://firestore.midominio.com',
  storageUrl: 'https://storage.midominio.com/api',
  storageBucket: 'prod-bucket',
});
```

## Features

- ✅ **CRUD completo**: `getDoc`, `setDoc`, `updateDoc`, `deleteDoc`, `addDoc`
- ✅ **Queries**: `where`, `orderBy`, `limit`, `startAt/After`, `endAt/Before`, `and`, `or`
- ✅ **Real-time**: `onSnapshot` con `docChanges()`
- ✅ **Auth**: `signInWithCustomToken`, `signOut`, `onAuthStateChanged`, persistencia
- ✅ **Storage**: Upload resumable, `getDownloadURL`, `listAll`, metadata
- ✅ **Batch & Transactions**: Operaciones atómicas
- ✅ **Agregaciones**: `count()`, `sum()`, `average()`
- ✅ **Tipos especiales**: `Timestamp`, `GeoPoint`, `Bytes`, `VectorValue`
- ✅ **Búsqueda avanzada**: `fastSearch`, `whereFuzzy`, `whereSearch`
- ✅ **Field Values**: `serverTimestamp()`, `increment()`, `arrayUnion/Remove`

## Documentación Completa

📘 Ver [`sdk/DOCUMENTACION.md`](https://github.com/ponceca/firestore/blob/main/sdk/DOCUMENTACION.md) para la guía completa incluyendo: configuración del backend, variables de entorno, Angular SDK, seguridad JWT, y despliegue en producción.

## Para Angular

```bash
npm install @ponceca/firestore-sdk @ponceca/firestore-angular
```

Ver [@ponceca/firestore-angular](https://www.npmjs.com/package/@ponceca/firestore-angular) para la documentación del adapter Angular con Signals, Observables, Guards y SSR.

## Licencia

MIT — © 2026 ponceca