hobots 1.10.0 → 2.0.1

package/README.md

@@ -113,7 +113,7 @@ try {
   await processarNota(nota);
 } catch (error) {
   Hobots.captureException(error, {
-    level: 'error',
+    type: 'error',
     tags: { cliente: 'acme' },
     fingerprint: ['sefaz-timeout'], // agrupa manualmente; sem isso o servidor agrupa pelo stack
   });
@@ -123,9 +123,9 @@ try {
 Hobots.captureMessage('Lote processado com sucesso', 'success');
 ```
 
-Ambas retornam o `event_id` (ou `undefined` se não inicializado). O hint aceita `level`, `tags`, `extra` e `fingerprint`. Erros **não tratados** são capturados e flushados automaticamente antes do processo sair — desligue com `captureUnhandled: false`. Os eventos aparecem agrupados em issues no módulo **Issues** do app.
+Ambas retornam o `event_id` (ou `undefined` se não inicializado). O hint aceita `type`, `tags`, `extra` e `fingerprint`. Erros **não tratados** são capturados e flushados automaticamente antes do processo sair — desligue com `captureUnhandled: false`. Os eventos aparecem agrupados em issues no módulo **Issues** do app.
 
-`Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'success'`. Use `'success'` para reportar itens concluídos com êxito — contam como eventos, mas **não** viram issue nem disparam alertas.
+`EventType = 'fatal' | 'error' | 'warning' | 'success'`. Não há `'info'`/`'debug'`: narração não abre issue — para isso existem o log da execução e as breadcrumbs. Use `'success'` para reportar itens concluídos com êxito — contam como eventos, mas **não** viram issue nem disparam alertas.
 
 ### Breadcrumbs
 

package/dist/index.cjs

@@ -161,7 +161,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "1.10.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "2.0.1" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -291,34 +291,34 @@ function safeString(value) {
   }
   return String(value);
 }
-function eventFromException(error, level = "error") {
-  let type;
+function eventFromException(error, type = "error") {
+  let exceptionType;
   let value;
   let frames = [];
   if (error instanceof Error) {
-    type = error.name || "Error";
+    exceptionType = error.name || "Error";
     value = scrubSecrets(error.message);
     frames = parseStacktrace(error.stack);
   } else {
-    type = "NonError";
+    exceptionType = "NonError";
     value = scrubSecrets(safeString(error));
   }
   return {
     event_id: uuid4(),
     timestamp: nowISO(),
-    level,
+    type,
     exception: {
-      type,
+      type: exceptionType,
       value,
       ...frames.length > 0 ? { stacktrace: { frames } } : {}
     }
   };
 }
-function eventFromMessage(message, level = "info") {
+function eventFromMessage(message, type = "warning") {
   return {
     event_id: uuid4(),
     timestamp: nowISO(),
-    level,
+    type,
     message: scrubSecrets(message)
   };
 }
@@ -354,7 +354,8 @@ var Transport = class {
       return;
     }
     if (this.buffer.length >= this.maxQueueSize) {
-      this.buffer.shift();
+      const dropIndex = this.buffer.findIndex((queued) => queued.type !== "heartbeat");
+      this.buffer.splice(dropIndex === -1 ? 0 : dropIndex, 1);
       this.logger.warn("fila cheia, item mais antigo descartado");
     }
     this.buffer.push(item);
@@ -445,6 +446,8 @@ function runtimeContexts() {
 }
 var Client = class {
   logger;
+  /** Eco de lifecycle (Transaction.emit) e afins só imprimem no terminal com debug ligado. */
+  debug;
   // campos privados + getters de protótipo: o clientSecret não aparece em
   // JSON.stringify/serialização enumerável do Client (ex.: um objeto capturado
   // que referencie o client), mas client.options/config seguem funcionando
@@ -453,7 +456,8 @@ var Client = class {
   transport;
   constructor(options, config = resolveConfig(options)) {
     this.#options = options;
-    this.logger = makeLogger(!!options.debug);
+    this.debug = !!options.debug;
+    this.logger = makeLogger(this.debug);
     this.#config = config;
     this.transport = new Transport({
       endpoint: this.#config.ingestEndpoint,
@@ -477,10 +481,10 @@ var Client = class {
     return `Client { baseUrl: '${this.#config.baseUrl}' }`;
   }
   captureException(error, hint, scope2) {
-    return this.captureEvent(eventFromException(error, hint?.level ?? "error"), hint, scope2);
+    return this.captureEvent(eventFromException(error, hint?.type ?? "error"), hint, scope2);
   }
-  captureMessage(message, level, hint, scope2) {
-    return this.captureEvent(eventFromMessage(message, level), hint, scope2);
+  captureMessage(message, type, hint, scope2) {
+    return this.captureEvent(eventFromMessage(message, type), hint, scope2);
   }
   captureEvent(event, hint, scope2) {
     const sampleRate = this.options.sampleRate ?? 1;
@@ -502,7 +506,7 @@ var Client = class {
     const extra = { ...scope2.extra, ...event.extra, ...hint?.extra };
     return {
       ...event,
-      level: hint?.level ?? event.level ?? scope2.level ?? "error",
+      type: hint?.type ?? event.type ?? scope2.type ?? "error",
       release: event.release ?? this.options.release,
       environment: event.environment ?? this.options.environment ?? "production",
       tags: Object.keys(tags).length > 0 ? tags : void 0,
@@ -540,6 +544,8 @@ var Client = class {
 
 // src/heartbeat.ts
 var DEFAULT_INTERVAL_MS = 3e4;
+var MIN_REPORTED_INTERVAL_MS = 1e3;
+var MAX_REPORTED_INTERVAL_MS = 9e5;
 var Heartbeat = class {
   constructor(client2, options = {}, instanceId) {
     this.client = client2;
@@ -556,12 +562,22 @@ var Heartbeat = class {
   start() {
     if (this.timer) return;
     this.beat();
-    this.timer = setInterval(() => this.beat(), this.intervalMs);
+    this.schedule();
+  }
+  /** Jitter de ±10%: uma frota iniciada junto não sincroniza todos os beats no mesmo segundo. */
+  schedule() {
+    this.timer = setTimeout(
+      () => {
+        this.beat();
+        this.schedule();
+      },
+      this.intervalMs * (0.9 + Math.random() * 0.2)
+    );
     unrefTimer(this.timer);
   }
   stop() {
     if (this.timer) {
-      clearInterval(this.timer);
+      clearTimeout(this.timer);
       this.timer = void 0;
     }
   }
@@ -569,7 +585,7 @@ var Heartbeat = class {
     this.client.sendHeartbeat({
       instance_id: this.instanceId,
       name: this.name,
-      interval_ms: this.intervalMs,
+      interval_ms: Math.min(Math.max(this.intervalMs, MIN_REPORTED_INTERVAL_MS), MAX_REPORTED_INTERVAL_MS),
       timestamp: nowISO(),
       metadata: this.metadata
     });
@@ -608,7 +624,7 @@ function installGlobalHandlers(client2, getScope) {
     process.on(
       "uncaughtException",
       markInternal((error) => {
-        client2.captureException(error, { level: "fatal", tags: { mechanism: "uncaughtException" } }, getScope());
+        client2.captureException(error, { type: "fatal", tags: { mechanism: "uncaughtException" } }, getScope());
         void client2.flush(2e3).then(async () => {
           if (externalListenerCount("uncaughtException") === 0) {
             await awaitEmergencyTasks(EMERGENCY_REPORT_CAP_MS);
@@ -621,7 +637,7 @@ function installGlobalHandlers(client2, getScope) {
     process.on(
       "unhandledRejection",
       markInternal((reason) => {
-        client2.captureException(reason, { level: "error", tags: { mechanism: "unhandledRejection" } }, getScope());
+        client2.captureException(reason, { type: "error", tags: { mechanism: "unhandledRejection" } }, getScope());
         void client2.flush(2e3);
       })
     );
@@ -652,7 +668,7 @@ var Scope = class _Scope {
   user;
   contexts = {};
   extra = {};
-  level;
+  type;
   fingerprint;
   breadcrumbs = [];
   setTag(key, value) {
@@ -683,8 +699,8 @@ var Scope = class _Scope {
     Object.assign(this.extra, extras);
     return this;
   }
-  setLevel(level) {
-    this.level = level;
+  setType(type) {
+    this.type = type;
     return this;
   }
   setFingerprint(fingerprint) {
@@ -708,7 +724,7 @@ var Scope = class _Scope {
     next.user = this.user ? { ...this.user } : void 0;
     next.contexts = Object.fromEntries(Object.entries(this.contexts).map(([k, v]) => [k, { ...v }]));
     next.extra = { ...this.extra };
-    next.level = this.level;
+    next.type = this.type;
     next.fingerprint = this.fingerprint ? [...this.fingerprint] : void 0;
     next.breadcrumbs = [...this.breadcrumbs];
     return next;
@@ -816,15 +832,18 @@ var Transaction = class {
   // antes do RunReporter conectar) — replay no setLifecycleSink
   lifecycleBacklog = [];
   /**
-   * Ecoa no terminal o início/fim de uma step ou transaction (sempre, independente de
-   * sampling ou do debug) e espelha a linha no sink de lifecycle, se conectado — é
-   * assim que os eventos de performance também aparecem nos logs da run no app.
+   * Registra o início/fim de uma step ou transaction: espelha a linha no sink de
+   * lifecycle, se conectado (é assim que os eventos de performance aparecem nos
+   * logs da run no app), e ecoa no terminal apenas com `debug: true` — o SDK não
+   * escreve no stdout do processo do usuário sem permissão.
    */
   emit(kind, phase, label, startTs, endTs, status) {
     const durationMs = startTs && endTs ? new Date(endTs).getTime() - new Date(startTs).getTime() : void 0;
-    const tag = colorize(`[hobots:${kind}] ${phase.toUpperCase()}`, phase === "finish" ? colorForStatus(status ?? "ok") : "cyan");
     const suffix = durationMs != null ? ` (${durationMs}ms)` : "";
-    console.log(`${tag} ${label}${suffix}`);
+    if (this.client?.debug) {
+      const tag = colorize(`[hobots:${kind}] ${phase.toUpperCase()}`, phase === "finish" ? colorForStatus(status ?? "ok") : "cyan");
+      console.log(`${tag} ${label}${suffix}`);
+    }
     const level = phase === "finish" ? levelForStatus(status ?? "ok") : "info";
     const message = `[${kind}] ${phase.toUpperCase()} ${label}${suffix}`;
     if (this.lifecycleSink) this.lifecycleSink(level, message);
@@ -1871,13 +1890,17 @@ var TaskAgent = class {
     try {
       const response = await this.api.poll(
         {
-          agent: {
+          instance: {
             // identidade canônica do agente no painel — o mesmo instanceId do
             // heartbeat da Telemetria, então os dois canais convergem em um agente
             instance_id: this.instanceId,
             version: SDK_VERSION,
             host: hostname(),
-            tasks: [...this.registry.keys()]
+            tasks: [...this.registry.keys()],
+            // o servidor calcula a tolerância de offline (3×) a partir disto em
+            // agentes poll-only — sem o campo, um poll lento flaparia offline/online.
+            // Clampado à faixa aceita pelo schema do poll (1s..15min).
+            poll_interval_ms: Math.min(Math.max(this.pollIntervalMs, 1e3), 9e5)
           },
           max: Math.min(MAX_CONCURRENCY, this.concurrency - this.activeRuns.size),
           tasks: [...this.registry.keys()]
@@ -2061,10 +2084,10 @@ function init(options) {
 function getClient() {
   return client;
 }
-function toRunLogLevel(level) {
-  return level === "fatal" ? "error" : level;
+function toRunLogLevel(type) {
+  return type === "fatal" ? "error" : type;
 }
-function forwardAttachment(attachment, message, level) {
+function forwardAttachment(attachment, message, type) {
   const attach = currentRunAttach();
   if (!attach) {
     client?.logger.warn("attachment descartado \u2014 s\xF3 \xE9 suportado dentro de uma execu\xE7\xE3o de task (register/start)");
@@ -2073,7 +2096,7 @@ function forwardAttachment(attachment, message, level) {
   const withMeta = typeof attachment === "object" && "image" in attachment ? attachment : { image: attachment };
   void attach(withMeta.image, {
     message,
-    level: toRunLogLevel(level),
+    level: toRunLogLevel(type),
     caption: withMeta.caption,
     contentType: withMeta.contentType
   });
@@ -2081,15 +2104,15 @@ function forwardAttachment(attachment, message, level) {
 function captureException(error, hint) {
   if (hint?.attachment) {
     const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
-    forwardAttachment(hint.attachment, message, hint.level ?? "error");
+    forwardAttachment(hint.attachment, message, hint.type ?? "error");
   }
   return client?.captureException(error, hint, scope);
 }
-function captureMessage(message, level = "info", hint) {
+function captureMessage(message, type = "warning", hint) {
   if (hint?.attachment) {
-    forwardAttachment(hint.attachment, message, hint.level ?? level);
+    forwardAttachment(hint.attachment, message, hint.type ?? type);
   }
-  return client?.captureMessage(message, level, hint, scope);
+  return client?.captureMessage(message, type, hint, scope);
 }
 function addBreadcrumb(crumb) {
   scope.addBreadcrumb(crumb, client?.options.maxBreadcrumbs ?? DEFAULT_MAX_BREADCRUMBS);