@neetru/sdk 3.2.3 → 3.4.0

package/dist/db.cjs

@@ -20,12 +20,22 @@ var init_errors = __esm({
       code;
       status;
       requestId;
-      constructor(code, message, status, requestId) {
+      /**
+       * Motivo semântico opcional propagado pelo Core no corpo do erro (campo
+       * `reason` no TOPO do body, fora de `error`). Usado principalmente pelo 503
+       * de lease de DB, onde `reason` discrimina o estado do ambiente
+       * (`suspended` | `archived` | `revoked` | `provisioning` | `degraded` |
+       * `no_route` | `expired`). Camadas superiores (ex.: `db/sql`) mapeiam isso
+       * para um `NeetruDbErrorCode` mais específico (recuperável vs não).
+       */
+      reason;
+      constructor(code, message, status, requestId, reason) {
         super(message);
         this.name = "NeetruError";
         this.code = code;
         this.status = status;
         this.requestId = requestId;
+        this.reason = reason;
         Object.setPrototypeOf(this, _NeetruError.prototype);
       }
     };
@@ -231,16 +241,22 @@ async function httpRequest(config, opts) {
     const body = await safeJson(res);
     let code = statusToCode(res.status);
     let message = `HTTP ${res.status}`;
-    if (body && typeof body === "object" && "error" in body) {
+    let reason;
+    if (body && typeof body === "object") {
       const errField = body.error;
       if (typeof errField === "string") {
         message = errField;
       } else if (errField && typeof errField === "object") {
         if (typeof errField.code === "string") code = errField.code;
         if (typeof errField.message === "string") message = errField.message;
+        if (typeof errField.reason === "string") reason = errField.reason;
+      } else {
+        if (typeof body.code === "string") code = body.code;
+        if (typeof body.message === "string") message = body.message;
       }
+      if (typeof body.reason === "string") reason = body.reason;
     }
-    const err = new NeetruError(code, message, res.status, requestId);
+    const err = new NeetruError(code, message, res.status, requestId, reason);
     lastError = err;
     const isRetryable = RETRYABLE_CODES2.has(code);
     if (isRetryable && attempt < maxRetries) {
@@ -367,6 +383,7 @@ var init_resilient_pool = __esm({
 
 // src/db/sql/lease.ts
 function hasConnectionChanged(oldLease, newLease) {
+  if (!oldLease) return true;
   return oldLease.leaseId !== newLease.leaseId || oldLease.credentialVersion !== newLease.credentialVersion || oldLease.host !== newLease.host || oldLease.port !== newLease.port || oldLease.dbName !== newLease.dbName || oldLease.user !== newLease.user || oldLease.password !== newLease.password || oldLease.sslca !== newLease.sslca || oldLease.clientCert !== newLease.clientCert || oldLease.clientKey !== newLease.clientKey;
 }
 function mapPoolError(err) {
@@ -398,6 +415,10 @@ var init_lease = __esm({
     RENEWAL_THRESHOLD = 0.8;
     MIN_RENEWAL_DELAY_MS = 3e4;
     SqlLeaseManager = class {
+      /**
+       * Lease atual. `null` no modo LAZY antes da 1ª query (o 1º lease é adiado —
+       * ver `_ensureInitialLease`). Após a 1ª aquisição, sempre não-nulo.
+       */
       _lease;
       _pool;
       _orm;
@@ -409,6 +430,12 @@ var init_lease = __esm({
        * `_reactiveReLease`.
        */
       _reLeaseInFlight = null;
+      /**
+       * Promessa da aquisição do LEASE INICIAL em voo (modo lazy) — coalesce as
+       * N primeiras queries concorrentes num único fetch. `null` quando não há
+       * aquisição inicial pendente. Ver `_ensureInitialLease`.
+       */
+      _initInFlight = null;
       _deps;
       constructor(lease, pool, orm, deps) {
         this._lease = lease;
@@ -418,7 +445,7 @@ var init_lease = __esm({
           ...deps,
           now: deps.now ?? (() => Date.now())
         };
-        this._scheduleRenewal();
+        if (this._lease) this._scheduleRenewal();
       }
       // ─── Superfície pública (NeetruSqlClient) ──────────────────────────────────
       get orm() {
@@ -456,6 +483,7 @@ var init_lease = __esm({
        * usa `MIN_RENEWAL_DELAY_MS` como fallback seguro.
        */
       _calcRenewalDelayMs() {
+        if (!this._lease) return MIN_RENEWAL_DELAY_MS;
         const expiresAtMs = Date.parse(this._lease.expiresAt);
         if (!Number.isFinite(expiresAtMs)) return MIN_RENEWAL_DELAY_MS;
         const now = this._deps.now();
@@ -479,6 +507,8 @@ var init_lease = __esm({
       }
       async _doRenew() {
         if (this._closed) return;
+        const currentLease = this._lease;
+        if (!currentLease) return;
         try {
           const withDb = (o) => {
             if (this._deps.database !== void 0) o.database = this._deps.database;
@@ -486,7 +516,7 @@ var init_lease = __esm({
           };
           let newLease;
           try {
-            newLease = await this._deps.fetchLease(withDb({ leaseId: this._lease.leaseId }));
+            newLease = await this._deps.fetchLease(withDb({ leaseId: currentLease.leaseId }));
           } catch (renewErr) {
             newLease = await this._deps.fetchLease(withDb({}));
           }
@@ -546,6 +576,71 @@ var init_lease = __esm({
           this._reLeaseInFlight = null;
         }
       }
+      // ─── Lease INICIAL lazy (motor de ambientes suspenso) ──────────────────────
+      /**
+       * Adquire o LEASE INICIAL sob demanda (modo lazy). Chamado pelo pool "adiado"
+       * (`createDeferredPool`) na 1ª query/transação — nunca no boot do módulo.
+       *
+       * Fluxo:
+       *   1. Se já há lease (`_lease != null`), devolve o pool REAL interno vigente
+       *      (idempotente — chamadas após a 1ª aquisição são no-op de fetch).
+       *   2. Busca o 1º lease no Core (com `database` se houver — contrato C-H).
+       *   3. Cria o pool REAL e faz o swap no wrapper resiliente (`__neetruSwapInner`)
+       *      pra que as queries seguintes passem direto pelo pool real.
+       *   4. Agenda a renovação proativa (só a partir daqui — antes não havia lease).
+       *
+       * Coalesce concorrência: N primeiras queries compartilham UM único fetch
+       * (`_initInFlight`). Se a aquisição FALHA (ex.: ambiente suspenso →
+       * `db_suspended`, ou Core fora → `db_unavailable`), o erro propaga pra query
+       * que a disparou e `_initInFlight` é limpo — a PRÓXIMA query re-tenta (o
+       * ambiente pode ter voltado). NÃO derruba o processo nem o import do módulo.
+       */
+      async _ensureInitialLease() {
+        if (this._closed) {
+          throw new exports.NeetruDbError(
+            "db_unavailable",
+            "SqlLeaseManager foi fechado \u2014 aquisi\xE7\xE3o de lease inicial abortada."
+          );
+        }
+        if (this._lease) {
+          return isResilientPool(this._pool) ? this._pool.__neetruGetInner() : this._pool;
+        }
+        if (this._initInFlight !== null) return this._initInFlight;
+        const run = (async () => {
+          let lease;
+          try {
+            lease = this._deps.database !== void 0 ? await this._deps.fetchLease({ database: this._deps.database }) : await this._deps.fetchLease();
+          } catch (err) {
+            if (err instanceof exports.NeetruDbError) throw err;
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new exports.NeetruDbError("db_unavailable", `Falha ao obter lease inicial: ${msg}`);
+          }
+          let realPool;
+          try {
+            realPool = this._deps.createPool(lease);
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new exports.NeetruDbError("db_unavailable", `Falha ao abrir pool: ${msg}`);
+          }
+          if (isResilientPool(this._pool)) {
+            const old = this._pool.__neetruSwapInner(realPool);
+            void old.end().catch(() => {
+            });
+          } else {
+            this._pool = realPool;
+          }
+          this._lease = lease;
+          this._scheduleRenewal();
+          return realPool;
+        })();
+        this._initInFlight = run;
+        try {
+          return await run;
+        } catch (err) {
+          this._initInFlight = null;
+          throw err;
+        }
+      }
       /**
        * Hot-swap do pool: cria pool novo, atualiza ponteiros, drena pool antigo.
        *
@@ -629,10 +724,19 @@ function createHttpLeaseFetcher(config) {
         retries: 2
       });
     } catch (err) {
+      const verb = isRenewal ? "renovar" : "obter";
       const msg = err instanceof Error ? err.message : String(err);
+      const reason = err instanceof NeetruError ? err.reason : void 0;
+      if (reason === "suspended" || reason === "archived" || reason === "revoked") {
+        const human = reason === "suspended" ? "ambiente suspenso \u2014 a m\xE1quina que o servia parou; ser\xE1 religado quando o ambiente voltar" : reason === "archived" ? "ambiente arquivado \u2014 este banco foi arquivado e n\xE3o aceita mais conex\xF5es" : "lease revogado \u2014 as credenciais deste ambiente foram revogadas pelo Core";
+        throw new exports.NeetruDbError(
+          "db_suspended",
+          `Falha ao ${verb} lease SQL: ${human} (reason=${reason}).`
+        );
+      }
       throw new exports.NeetruDbError(
         "db_unavailable",
-        `Falha ao ${isRenewal ? "renovar" : "obter"} lease SQL: ${msg}`
+        `Falha ao ${verb} lease SQL: ${msg}`
       );
     }
     return parseLease(raw);
@@ -704,8 +808,64 @@ async function createDrizzleHandle(pool, schema) {
   );
   return drizzle(pool, { schema });
 }
+function createDeferredPool(poolPrototype, ensureRealPool) {
+  let real = null;
+  let inflight = null;
+  const getReal = () => {
+    if (real) return Promise.resolve(real);
+    if (!inflight) {
+      inflight = ensureRealPool().then((p) => {
+        real = p;
+        inflight = null;
+        return p;
+      }).catch((e) => {
+        inflight = null;
+        throw e;
+      });
+    }
+    return inflight;
+  };
+  const deferred = {
+    async query(...args) {
+      const p = await getReal();
+      return p.query(...args);
+    },
+    async connect(...args) {
+      const p = await getReal();
+      return p.connect(...args);
+    },
+    async end() {
+      if (real) await real.end();
+    }
+  };
+  if (poolPrototype) {
+    Object.setPrototypeOf(deferred, poolPrototype);
+  }
+  return deferred;
+}
 async function createSqlClientWithDeps(deps, options) {
   const depsWithDb = options?.database !== void 0 ? { ...deps, database: options.database } : deps;
+  if (depsWithDb.lazy) {
+    let managerRef = null;
+    const deferred = createDeferredPool(depsWithDb.poolPrototype ?? null, () => {
+      if (!managerRef) {
+        throw new exports.NeetruDbError("db_unavailable", "SQL client n\xE3o inicializado (manager ausente).");
+      }
+      return managerRef._ensureInitialLease();
+    });
+    const pool2 = createResilientPool(deferred);
+    let orm2;
+    try {
+      orm2 = depsWithDb.createDrizzle(pool2, depsWithDb.schema);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new exports.NeetruDbError("db_unavailable", `Falha ao criar handle Drizzle: ${msg}`);
+    }
+    const manager2 = new SqlLeaseManager(null, pool2, orm2, depsWithDb);
+    managerRef = manager2;
+    pool2.__neetruSetReLease(() => manager2._reactiveReLease());
+    return manager2;
+  }
   let lease;
   try {
     if (options?.database !== void 0) {
@@ -758,8 +918,8 @@ async function createSqlClientFromConfig(config, schema, options) {
       `[client.db.sql] requer pg + drizzle-orm como peerDependencies do servidor. Instale: npm install pg drizzle-orm. (${err.message})`
     );
   }
+  const Pool = pgMod.Pool ?? pgMod.default?.Pool;
   const createPool = (lease) => {
-    const Pool = pgMod.Pool ?? pgMod.default?.Pool;
     const ssl = lease.sslca ? {
       ca: lease.sslca,
       cert: lease.clientCert ?? void 0,
@@ -786,7 +946,14 @@ async function createSqlClientFromConfig(config, schema, options) {
       fetchLease,
       createPool,
       createDrizzle,
-      schema
+      schema,
+      // Lease inicial LAZY (motor de ambientes suspenso): `client.db.sql()` não
+      // pode explodir o `import` do módulo do produto quando o ambiente está
+      // suspenso/arquivado no boot. O 1º lease é adiado pra 1ª query.
+      lazy: true,
+      // Placeholder pré-1ª-query herda `pg.Pool.prototype` pra `instanceof Pool`
+      // valer no wrapper resiliente (transações Drizzle PASS-THROUGH seguras).
+      poolPrototype: Pool?.prototype ?? null
     },
     options
   );
@@ -795,6 +962,7 @@ var LEASE_ENDPOINT, LEASE_RENEW_ENDPOINT;
 var init_sql_client = __esm({
   "src/db/sql/sql-client.ts"() {
     init_db_errors();
+    init_errors();
     init_lease();
     init_resilient_pool();
     LEASE_ENDPOINT = "/api/sdk/v1/db/lease";
@@ -4233,7 +4401,23 @@ function buildTicketProvider(config, opts) {
 function getWebSocketRealtimeClient(gatewayUrl, ticketProvider, dbId, wsFactory) {
   return new NeetruRealtimeClient({ gatewayUrl, ticketProvider, dbId, webSocketFactory: wsFactory });
 }
+var _hasWarnedMissingDbId = false;
+function __resetDbIdWarningForTests() {
+  _hasWarnedMissingDbId = false;
+}
+function warnMissingDbIdOnce(config, dbOpts) {
+  if (_hasWarnedMissingDbId) return;
+  if (dbOpts.dbId) return;
+  if (config.env === "prod") return;
+  if (typeof window === "undefined") return;
+  if (typeof console === "undefined" || typeof console.warn !== "function") return;
+  _hasWarnedMissingDbId = true;
+  console.warn(
+    "[neetru/sdk] client.db sem `dbId` expl\xEDcito: escritas client-side (add/set/update/remove/list) caem no datastore gen\xE9rico do Core, escopado por tenant/produto (header x-neetru-tenant) \u2014 `dbId` s\xF3 nomeia o cache offline LOCAL (IndexedDB), n\xE3o roteia nem escopa nada no servidor. Veja o JSDoc de NeetruDbOptions.dbId."
+  );
+}
 function createNeetruDb(config, dbOpts = {}) {
+  warnMissingDbIdOnce(config, dbOpts);
   let resolvedTransport;
   if (dbOpts.transport !== void 0) {
     resolvedTransport = dbOpts.transport;
@@ -4409,6 +4593,7 @@ function createLazyCollectionRef(name, getDocsPromise) {
 }
 
 exports.NEETRU_SENTINEL_KEY = NEETRU_SENTINEL_KEY;
+exports.__resetDbIdWarningForTests = __resetDbIdWarningForTests;
 exports.createNeetruDb = createNeetruDb;
 exports.createRestSyncTransport = createRestSyncTransport;
 exports.getWebSocketRealtimeClient = getWebSocketRealtimeClient;