@neetru/sdk 3.0.0 → 3.0.2

package/CHANGELOG.md

@@ -5,6 +5,57 @@ 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).
 
+## [3.0.2] - 2026-06-02 — **fix: sentinels de escrita server-side (serverTimestamp + increment) — bug_05aedb8b**
+
+### Fixed / Added
+
+Fecha 3 lacunas do DB de documentos (`client.db.collection()`):
+
+- **`serverTimestamp()`** — sentinel de timestamp resolvido pelo **servidor**. Antes, `createdAt`/`updatedAt` de produto usavam o relógio do CLIENTE (spoofável + clock-skew). Agora:
+
+  ```ts
+  import { serverTimestamp } from '@neetru/sdk/db';
+  await orders.add({ total: 99, createdAt: serverTimestamp() });
+  ```
+
+  O marcador atravessa o transporte como `{ "__neetru__": "serverTimestamp" }` e o Core o resolve em `FieldValue.serverTimestamp()` no momento da escrita.
+
+- **`increment(n)`** — incremento **atômico** de campo numérico (antes `update()` era só merge/replace, sujeito a lost-update sob concorrência):
+
+  ```ts
+  import { increment } from '@neetru/sdk/db';
+  await counters.update('global', { hits: increment(1) });
+  await wallet.update(uid, { balance: increment(-50) });
+  ```
+
+  Resolvido server-side via `FieldValue.increment(n)`. Aplicação otimista local: `serverTimestamp()` → `Date.now()` aproximado; `increment(n)` → soma local sobre o valor atual (valor canônico vem do servidor no sync).
+
+- **Tipos alinhados ao runtime** — `add`/`set`/`update`/`batch` e `DbDocRef.set/update` agora aceitam `WithFieldSentinels<T>`: cada campo pode receber seu tipo OU um sentinel, sem erro de tipo. O `.d.ts` é gerado da mesma fonte do runtime (tsup), eliminando divergência declaração↔runtime.
+
+### Novos exports
+
+- De `@neetru/sdk` e `@neetru/sdk/db`: `serverTimestamp`, `increment`, `isFieldSentinel`, `isServerTimestampSentinel`, `isIncrementSentinel`, `NEETRU_SENTINEL_KEY`.
+- Tipos: `FieldSentinel`, `ServerTimestampSentinel`, `IncrementSentinel`, `WithFieldSentinels`.
+
+### Segurança
+
+- Sentinels só são resolvidos em campos **top-level** (espelha o Core). Marcador desconhecido, `operand` não-numérico, ou sentinel aninhado → o Core rejeita com `400 validation_failed` (fail-closed) e **nunca grava** o objeto cru.
+
+> Requer Core com o resolver de sentinels (`src/lib/datastore-sentinels.ts`) nos endpoints `/api/sdk/v1/datastore/*`. Ambos os repos mudam neste fix.
+
+## [3.0.1] - 2026-05-29 — **fix: sincronizar VERSION + docstrings + contract-staging códigos de erro**
+
+### Fixed
+
+- `src/index.ts` — `VERSION` constante sincronizada com `package.json` (`'3.0.0'` → `'3.0.1'`). Consumers que fazem `import { VERSION } from '@neetru/sdk'` recebiam `'3.0.0'` enquanto `npm list` mostrava `3.0.1` (LOW-NEW-SDK-01).
+- `src/telemetry.ts` — JSDoc na linha 6 corrigido: path legacy `/api/v1/sdk/telemetry/event` → canônico `/api/sdk/v1/telemetry/event`. O código sempre usou o path correto; apenas a documentação estava stale (LOW-NEW-SDK-02).
+- `src/__tests__/telemetry.test.ts` — comentário de cabeçalho atualizado para não dizer "(legado)" (LOW-NEW-SDK-02).
+- `src/__tests__/contract-staging.test.ts` — `'http_error'` removido de todos os arrays `toContain`. `NeetruErrorCode` não inclui `'http_error'`; respostas HTTP não mapeáveis caem em `'unknown'`. Substituído por `'unknown'` em todos os 7 sites (LOW-NEW-SDK-03).
+
+### Nota
+
+Este patch corresponde ao commit `4c40f01` (inline realtime-protocol types) que não atualizou `VERSION` nem o CHANGELOG.
+
 ## [3.0.0] - 2026-05-27 — **MAJOR: contract hardening + Universal runtime + paths canonical**
 
 > Major rewrite resolvendo 5 CRITICAL + 6 HIGH do review `CHEFE_SDK_REVIEW_2026-05-27`.

package/README.md

@@ -221,6 +221,31 @@ const neetru = createNeetruClient({
 - Zero dependências runtime (usa `fetch` global)
 - Bundle minzip <10KB (todos namespaces somados, tree-shake-friendly)
 
+## Testes de contrato (staging)
+
+O arquivo `src/__tests__/contract-staging.test.ts` contém testes que exercitam o HTTP real contra um ambiente de staging. Por default, todos os testes são skippados quando `NEETRU_STAGING_URL` não estiver definido.
+
+Para rodar:
+
+```bash
+NEETRU_STAGING_URL=https://api.staging.neetru.com \
+NEETRU_STAGING_API_KEY=nrt_<keyId>_<secret> \
+npx vitest run src/__tests__/contract-staging.test.ts
+```
+
+Variáveis de ambiente:
+
+| Variável | Obrigatória | Descrição |
+|---|---|---|
+| `NEETRU_STAGING_URL` | Sim | URL base da API de staging |
+| `NEETRU_STAGING_API_KEY` | Sim | API key no formato `nrt_<keyId>_<secret>` |
+| `NEETRU_STAGING_PRODUCT_ID` | Não | productId cadastrado no staging (default: `gestovendas`) |
+| `NEETRU_STAGING_TENANT_ID` | Não | tenantId válido no staging (default: `t-acme`) |
+
+Namespaces cobertos: `catalog.list`, `catalog.get`, `entitlements.check`, `entitlements.checkDetailed`, `usage.report`, `usage.check`, `telemetry.event`, `telemetry.log`, `auth.getUser`, `auth.signIn`.
+
+Os testes assertam apenas o shape/tipos da resposta, nunca valores exatos — staging pode ter dados variáveis mas o contrato de formato deve ser estável.
+
 ## Mais info
 
 - **Repo:** [github.com/Neetru/neetru-core](https://github.com/Neetru/neetru-core)

package/dist/auth.cjs

@@ -3337,6 +3337,43 @@ var TabCoordinator = class {
 
 // src/db/collection-ref.ts
 init_db_errors();
+
+// src/db/field-value.ts
+var NEETRU_SENTINEL_KEY = "__neetru__";
+function isFieldSentinel(v) {
+  return typeof v === "object" && v !== null && NEETRU_SENTINEL_KEY in v && typeof v[NEETRU_SENTINEL_KEY] === "string";
+}
+function isServerTimestampSentinel(v) {
+  return isFieldSentinel(v) && v.__neetru__ === "serverTimestamp";
+}
+function isIncrementSentinel(v) {
+  return isFieldSentinel(v) && v.__neetru__ === "increment" && typeof v.operand === "number" && Number.isFinite(v.operand);
+}
+function resolveSentinelLocally(value, baseValue) {
+  if (isServerTimestampSentinel(value)) {
+    return Date.now();
+  }
+  if (isIncrementSentinel(value)) {
+    const base = typeof baseValue === "number" && Number.isFinite(baseValue) ? baseValue : 0;
+    return base + value.operand;
+  }
+  return value;
+}
+function resolveSentinelsLocally(data, existing) {
+  let touched = false;
+  const out = {};
+  for (const [k, v] of Object.entries(data)) {
+    if (isFieldSentinel(v)) {
+      touched = true;
+      out[k] = resolveSentinelLocally(v, existing?.[k]);
+    } else {
+      out[k] = v;
+    }
+  }
+  return touched ? out : data;
+}
+
+// src/db/collection-ref.ts
 function isIndexedDBUnavailable() {
   return typeof indexedDB === "undefined" || typeof window === "undefined";
 }
@@ -3465,10 +3502,12 @@ var DbCollectionRefImpl = class {
     return this._buildListResult(q);
   }
   async add(data) {
+    const rawData = data;
+    const localData = resolveSentinelsLocally(rawData, void 0);
     const mutation = await this._queue.enqueue({
       collection: this._collection,
       op: "add",
-      payload: data,
+      payload: rawData,
       baseVersion: null,
       batchId: null
     });
@@ -3476,7 +3515,7 @@ var DbCollectionRefImpl = class {
     await this._store.putDoc({
       collection: this._collection,
       id: docId,
-      data,
+      data: localData,
       meta: {
         serverVersion: null,
         updatedAtServer: null,
@@ -3490,25 +3529,27 @@ var DbCollectionRefImpl = class {
     this._bus.emit([{
       type: "added",
       collection: this._collection,
-      doc: { id: docId, data }
+      doc: { id: docId, data: localData }
     }]);
     return { ok: true, id: docId };
   }
   async set(id, data) {
     assertValidId(id);
     const existing = await this._store.getDoc(this._collection, id);
+    const rawData = data;
+    const localData = resolveSentinelsLocally(rawData, void 0);
     const mutation = await this._queue.enqueue({
       collection: this._collection,
       docId: id,
       op: "set",
-      payload: data,
+      payload: rawData,
       baseVersion: existing?.meta.serverVersion ?? null,
       batchId: null
     });
     await this._store.putDoc({
       collection: this._collection,
       id,
-      data,
+      data: localData,
       meta: {
         serverVersion: existing?.meta.serverVersion ?? null,
         updatedAtServer: existing?.meta.updatedAtServer ?? null,
@@ -3522,19 +3563,22 @@ var DbCollectionRefImpl = class {
     this._bus.emit([{
       type: existing && !existing.meta.deleted ? "modified" : "added",
       collection: this._collection,
-      doc: { id, data }
+      doc: { id, data: localData }
     }]);
     return { ok: true };
   }
   async update(id, data) {
     assertValidId(id);
     const existing = await this._store.getDoc(this._collection, id);
-    const mergedData = existing?.meta.deleted ? { ...data } : { ...existing?.data ?? {}, ...data };
+    const rawData = data;
+    const existingBase = existing?.meta.deleted ? void 0 : existing?.data;
+    const localData = resolveSentinelsLocally(rawData, existingBase);
+    const mergedData = existing?.meta.deleted ? { ...localData } : { ...existing?.data ?? {}, ...localData };
     const mutation = await this._queue.enqueue({
       collection: this._collection,
       docId: id,
       op: "update",
-      payload: data,
+      payload: rawData,
       baseVersion: existing?.meta.serverVersion ?? null,
       batchId: null
     });
@@ -3591,6 +3635,7 @@ var DbCollectionRefImpl = class {
       const collection = this._collection;
       if (op.kind === "add") {
         const data = op.data;
+        const localData = resolveSentinelsLocally(data, void 0);
         const mutation = await this._queue.enqueue({
           collection,
           op: "add",
@@ -3602,7 +3647,7 @@ var DbCollectionRefImpl = class {
         await this._store.putDoc({
           collection,
           id: docId,
-          data,
+          data: localData,
           meta: {
             serverVersion: null,
             updatedAtServer: null,
@@ -3613,11 +3658,12 @@ var DbCollectionRefImpl = class {
             ownerId: null
           }
         });
-        busChanges.push({ type: "added", collection, doc: { id: docId, data } });
+        busChanges.push({ type: "added", collection, doc: { id: docId, data: localData } });
       } else if (op.kind === "set") {
         const id = op.id;
         const data = op.data;
         const existing = await this._store.getDoc(collection, id);
+        const localData = resolveSentinelsLocally(data, void 0);
         const mutation = await this._queue.enqueue({
           collection,
           docId: id,
@@ -3629,7 +3675,7 @@ var DbCollectionRefImpl = class {
         await this._store.putDoc({
           collection,
           id,
-          data,
+          data: localData,
           meta: {
             serverVersion: existing?.meta.serverVersion ?? null,
             updatedAtServer: existing?.meta.updatedAtServer ?? null,
@@ -3643,13 +3689,15 @@ var DbCollectionRefImpl = class {
         busChanges.push({
           type: existing && !existing.meta.deleted ? "modified" : "added",
           collection,
-          doc: { id, data }
+          doc: { id, data: localData }
         });
       } else if (op.kind === "update") {
         const id = op.id;
         const data = op.data;
         const existing = await this._store.getDoc(collection, id);
-        const merged = { ...existing?.data ?? {}, ...data };
+        const existingBase = existing?.meta.deleted ? void 0 : existing?.data;
+        const localData = resolveSentinelsLocally(data, existingBase);
+        const merged = { ...existing?.data ?? {}, ...localData };
         const mutation = await this._queue.enqueue({
           collection,
           docId: id,