@neetru/sdk 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -5,6 +5,84 @@ All notable changes to `@neetru/sdk` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2026-05-25 — **feat(db-config): renomeia engine→transport com deprecation — bug_ed9da7fd [HIGH]**
+
+Fix do bug `bug_ed9da7fd11194eac87f0eb9c75e5fad9` (HIGH) — colisão de terminologia: `engine` no SDK
+configurava o transporte SDK↔Core (REST/Firestore/WebSocket), mas `engine` no admin database (CLI
+`neetru admin database create --engine=...`) configura o storage engine (firestore-instance,
+cloud-sql-postgres, vm-postgres-single…). Devs colocavam `firestore-instance` no SDK e quebravam.
+
+### Added
+
+- **`NeetruDbTransport`** — novo tipo público canônico para o campo de transporte SDK↔Core.
+  Valores: `'rest' | 'firestore' | 'nosql-vm'` (idênticos aos de `NeetruDbEngine`).
+
+- **`NeetruDbOptions.transport`** — novo campo canônico que substitui `engine`.
+  ```ts
+  // v2.3+ (preferido):
+  createNeetruClient({ db: { transport: 'rest' } });
+  createNeetruClient({ db: { transport: 'firestore' } });
+  createNeetruClient({ db: { transport: 'nosql-vm', realtimeGatewayUrl: '...' } });
+  ```
+
+### Deprecated
+
+- **`NeetruDbOptions.engine`** — depreciado em v2.3, será removido em v3.0.
+  Continua funcionando: se `transport` estiver ausente e `engine` presente, o valor de `engine`
+  é usado como transport com `console.warn` de deprecação.
+
+  ```ts
+  // v2.x (depreciado — emite console.warn):
+  createNeetruClient({ db: { engine: 'firestore' } });
+  // ⚠ [neetru/sdk] NeetruDbOptions.engine está depreciado...
+  ```
+
+- **`NeetruDbEngine`** — depreciado em v2.3, será removido em v3.0.
+  Agora é alias de `NeetruDbTransport`. Use `NeetruDbTransport` em código novo.
+
+### Behavior
+
+- `transport` e `engine` podem coexistir: `transport` sempre prevalece, sem warn.
+- Sem `transport` nem `engine`: default `'rest'`, sem warn (comportamento idêntico ao v2.x).
+- A relação 1:N entre storage engines e transports é documentada no JSDoc de `NeetruDbTransport`:
+  qualquer storage engine (cloud-sql-postgres, vm-postgres-single…) pode ser acessado com
+  `transport: 'rest'`; `transport: 'firestore'` e `transport: 'nosql-vm'` são para bancos
+  documentais com realtime nativo.
+
+### Tests
+
+- 5 testes novos em `src/__tests__/db-real.test.ts`:
+  `transport=firestore`, `transport=nosql-vm`, `transport=rest`, colisão `transport+engine`
+  (transport prevalece, sem warn), default sem campos (sem warn).
+- Testes de regressão: `engine=firestore` e `engine=nosql-vm` legados ainda passam + emitem warn.
+
+## [2.2.1] - 2026-05-25 — **fix(offline-docs): fallback MemoryStore em Node — bug_ba287a CRITICAL**
+
+Fix do bug `bug_ba287aefdf6c4327b026d588a239ad06` (CRITICAL) — `client.db.collection().set/add/update`
+lançava `ReferenceError: indexedDB is not defined` em Node.js (reportado por pdv-agiliza prod).
+
+### Fixed
+
+- **`createOfflineDocumentsNamespace` — auto-detect Node runtime e usa `MemoryStore`**.
+  A função agora verifica `typeof indexedDB === 'undefined' || typeof window === 'undefined'`
+  antes de instanciar `LocalStore` (que depende de `idb` / IndexedDB). Em Node/Bun/Edge Workers
+  sem IDB, cai automaticamente em `MemoryStore` — implementação in-process com a mesma API,
+  sem nenhuma flag explícita necessária. Ops de documentos (`set/add/update/remove/get/list`,
+  `batch`, `onSnapshot`, `onDoc`) funcionam normalmente em Node; dados não persistem entre
+  reinicializações do processo (comportamento esperado em SSR/server-side).
+
+### Added
+
+- **`src/db/offline/memory-store.ts`** — `MemoryStore`: implementação in-memory do contrato
+  público de `LocalStore`. Cobre todas as 5 stores (documents, mutations, query\_cache,
+  sync\_meta, conflict\_log) com Maps/Arrays em memória.
+
+### Tests
+
+- **`src/__tests__/offline-docs-node-compat.test.ts`** — 5 casos de regressão:
+  verifica que a stack offline não lança `ReferenceError` em ambiente sem IDB,
+  e que `set/add/update` + `get` roundtrips funcionam in-memory.
+
 ## [2.2.0] - 2026-05-25 — **auth.verifyToken — validação server-side de id_token via JWKS [feature]**
 
 Fix do bug `bug_a7ef1702680044e3994b74bdccecb2ab` — resolve P0-1 audit security pdv-agiliza.

package/dist/auth.cjs

@@ -1163,6 +1163,125 @@ var LocalStore = class {
   }
 };
 
+// src/db/offline/memory-store.ts
+var MemoryStore = class {
+  // store `documents` — key: `${collection}\0${id}`
+  _docs = /* @__PURE__ */ new Map();
+  // store `mutations` — key: mutationId
+  _mutations = /* @__PURE__ */ new Map();
+  // store `sync_meta` — key: string
+  _meta = /* @__PURE__ */ new Map();
+  // store `conflict_log` — autoIncrement int key
+  _conflicts = [];
+  _conflictSeq = 0;
+  // store `query_cache` — key: queryHash
+  _queryCache = /* @__PURE__ */ new Map();
+  // ─── Ciclo de vida (no-ops) ─────────────────────────────────────────────────
+  async open() {
+  }
+  async close() {
+    this._docs.clear();
+    this._mutations.clear();
+    this._meta.clear();
+    this._conflicts.splice(0);
+    this._conflictSeq = 0;
+    this._queryCache.clear();
+  }
+  // ─── Documents ─────────────────────────────────────────────────────────────
+  async getDoc(collection, id) {
+    const key = `${collection}\0${id}`;
+    return this._docs.get(key) ?? null;
+  }
+  async putDoc(doc) {
+    const key = `${doc.collection}\0${doc.id}`;
+    this._docs.set(key, doc);
+  }
+  async deleteDoc(collection, id) {
+    const key = `${collection}\0${id}`;
+    const existing = this._docs.get(key);
+    if (!existing) return;
+    this._docs.set(key, {
+      ...existing,
+      meta: {
+        ...existing.meta,
+        deleted: true,
+        updatedAtLocal: Date.now()
+      }
+    });
+  }
+  async listDocs(collection, query) {
+    const rawDocs = Array.from(this._docs.values()).filter(
+      (d) => d.collection === collection
+    );
+    return QueryEngine.evaluate(rawDocs, query);
+  }
+  // ─── Sync meta ──────────────────────────────────────────────────────────────
+  async getMeta(key) {
+    return this._meta.get(key) ?? null;
+  }
+  async setMeta(key, value) {
+    this._meta.set(key, value);
+  }
+  // ─── Conflict log ────────────────────────────────────────────────────────────
+  async appendConflict(record) {
+    const id = ++this._conflictSeq;
+    const full = { ...record, id };
+    this._conflicts.push(full);
+    return full;
+  }
+  async listConflicts(options) {
+    if (options?.delivered !== void 0) {
+      return this._conflicts.filter((r) => r.delivered === options.delivered);
+    }
+    return [...this._conflicts];
+  }
+  async markConflictDelivered(id) {
+    const entry = this._conflicts.find((r) => r.id === id);
+    if (entry) entry.delivered = true;
+  }
+  // ─── Mutations ───────────────────────────────────────────────────────────────
+  async putMutation(mutation) {
+    this._mutations.set(mutation.mutationId, { ...mutation });
+  }
+  async getMutation(mutationId) {
+    return this._mutations.get(mutationId) ?? null;
+  }
+  async listMutations(options) {
+    let all = Array.from(this._mutations.values());
+    if (options?.status !== void 0) {
+      all = all.filter((m) => m.status === options.status);
+    } else if (options?.collection !== void 0 && options.docId !== void 0) {
+      all = all.filter(
+        (m) => m.collection === options.collection && m.docId === options.docId
+      );
+    } else if (options?.collection !== void 0) {
+      all = all.filter((m) => m.collection === options.collection);
+    }
+    return all.sort((a, b) => a.seq - b.seq);
+  }
+  async deleteMutation(mutationId) {
+    this._mutations.delete(mutationId);
+  }
+  // ─── Collection discovery ────────────────────────────────────────────────────
+  async listCollections() {
+    const collections = /* @__PURE__ */ new Set();
+    for (const doc of this._docs.values()) {
+      collections.add(doc.collection);
+    }
+    return Array.from(collections);
+  }
+  // ─── Query cache ─────────────────────────────────────────────────────────────
+  async getQueryCache(queryHash) {
+    return this._queryCache.get(queryHash) ?? null;
+  }
+  async putQueryCache(entry) {
+    this._queryCache.set(entry.queryHash, { ...entry });
+  }
+  async deleteQueryCache(queryHash) {
+    this._queryCache.delete(queryHash);
+  }
+};
+
 // src/db/offline/mutation-queue.ts
 function generateUUIDv4() {
   if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
@@ -2709,6 +2828,9 @@ var TabCoordinator = class {
 };
 
 // src/db/collection-ref.ts
+function isIndexedDBUnavailable() {
+  return typeof indexedDB === "undefined" || typeof window === "undefined";
+}
 var COLL_RE = /^[a-z0-9][a-z0-9_-]{0,62}$/;
 function assertValidCollection(name) {
   if (!COLL_RE.test(name)) {
@@ -3250,7 +3372,7 @@ var NeetruDbDocumentsImpl = class {
   }
 };
 async function createOfflineDocumentsNamespace(opts) {
-  const store = new LocalStore(opts.dbName);
+  const store = isIndexedDBUnavailable() ? new MemoryStore() : new LocalStore(opts.dbName);
   await store.open();
   const queue = new MutationQueue(store);
   const resolver = new ConflictResolver();
@@ -4020,16 +4142,16 @@ var defaultWebSocketFactory = (url) => {
 // src/db/client-db.ts
 var DATASTORE_COLLECTION_ENDPOINT = (collection) => `/api/sdk/v1/datastore/${encodeURIComponent(collection)}`;
 var DATASTORE_DOC_ENDPOINT = (collection, docId) => `/api/sdk/v1/datastore/${encodeURIComponent(collection)}/${encodeURIComponent(docId)}`;
-function resolveTransport(engine, opts, config) {
+function resolveTransport(transport, opts, config) {
   if (opts._transport) {
     return opts._transport;
   }
-  if (engine === "firestore") {
+  if (transport === "firestore") {
     if (opts.firestoreTransport) {
       return opts.firestoreTransport;
     }
   }
-  if (engine === "nosql-vm" && opts.realtimeGatewayUrl) {
+  if (transport === "nosql-vm" && opts.realtimeGatewayUrl) {
     return createWebSocketSyncTransport(opts.realtimeGatewayUrl, config, opts);
   }
   return createRestSyncTransport(config);
@@ -4173,8 +4295,18 @@ function buildTicketProvider(config, opts) {
   };
 }
 function createNeetruDb(config, dbOpts = {}) {
-  const engine = dbOpts.engine ?? "rest";
-  const transport = resolveTransport(engine, dbOpts, config);
+  let resolvedTransport;
+  if (dbOpts.transport !== void 0) {
+    resolvedTransport = dbOpts.transport;
+  } else if (dbOpts.engine !== void 0) {
+    console.warn(
+      '[neetru/sdk] NeetruDbOptions.engine est\xE1 depreciado e ser\xE1 removido em v3.0. Use NeetruDbOptions.transport em vez de engine. Valores v\xE1lidos: "rest" | "firestore" | "nosql-vm". Nota: "engine" no SDK configura o TRANSPORTE (REST/Firestore/WebSocket), n\xE3o o storage engine do admin database (firestore-instance, cloud-sql-postgres, \u2026).'
+    );
+    resolvedTransport = dbOpts.engine;
+  } else {
+    resolvedTransport = "rest";
+  }
+  const transport = resolveTransport(resolvedTransport, dbOpts, config);
   const dbId = dbOpts.dbId ?? "default";
   const dbName = dbOpts.dbName ?? `neetru-db__${config.productId ?? "sdk"}__${dbId}__${config.env}`;
   let _docsPromise = null;