hobots 1.7.4 → 1.7.6

package/README.md

@@ -2,7 +2,7 @@
 
 SDK JavaScript/TypeScript da **Hobots** para instrumentar funcionários digitais (RPAs) e integrações.
 
-- **Telemetria** — o que o programa **emite** sozinho: erros com stack trace (módulo **Issues** do app), performance (transactions/spans) e heartbeats de uptime (módulo **Agentes**), check-ins de cron (módulo **Monitores**).
+- **Telemetria** — o que o programa **emite** sozinho: erros com stack trace (módulo **Issues** do app), performance (transactions/etapas) e heartbeats de uptime (módulo **Agentes**), check-ins de cron (módulo **Monitores**).
 - **Tasks** — execução **sob demanda**: o agente faz polling no app da Hobots, executa handlers registrados e reporta status e logs (módulo **Solicitações**).
 
 **Um único import e um único `init()`** cobrem as duas capabilities. Cliente HTTP puro, **sem dependências de runtime**. Requer **Node 18+** (usa o `fetch` global); a telemetria também roda no browser para captura de erros.
@@ -30,7 +30,7 @@ O SDK expõe **duas capabilities** autenticadas pelo **mesmo Client Secret do ag
 
 | Capability | Como habilita | Para quê | Ciclo de vida |
 | --- | --- | --- | --- |
-| **Telemetria** | sempre ativa no `init()` | O que o programa emite sozinho: erros, transactions/spans, crons, heartbeat. | Timers `unref`'d — **não** segura o processo. Chame `close()` no fim. |
+| **Telemetria** | sempre ativa no `init()` | O que o programa emite sozinho: erros, transactions/etapas, crons, heartbeat. | Timers `unref`'d — **não** segura o processo. Chame `close()` no fim. |
 | **Tasks** | `tasks: true` (ou opções) no `init()` | Execução remota sob demanda via polling. | `start()` **segura o processo vivo** até `stop()`/`close()`. |
 
 Você usa **uma, outra ou as duas**:
@@ -158,16 +158,16 @@ Hobots.withScope((scope) => {
 });
 ```
 
-### Performance: transactions e spans
+### Performance: transactions e etapas
 
 ```js
 const tx = Hobots.startTransaction('processar-lote', 'rpa.job');
 
-const span = tx.startChild('http.client', 'GET /api/notas');
+const step = tx.startChild('http.client', 'GET /api/notas');
 await api.buscarNotas();
-span.setData('notas', 42).finish();
+step.setData('notas', 42).finish();
 
-const filho = span.startChild('db.query', 'INSERT INTO notas'); // spans aninham
+const filho = step.startChild('db.query', 'INSERT INTO notas'); // etapas aninham
 await gravar();
 filho.finish();
 
@@ -175,11 +175,11 @@ tx.setStatus('ok');  // ou 'error'
 tx.finish();         // só aqui a transaction é enviada (respeitando tracesSampleRate)
 ```
 
-- `startChild(op?, description?)` existe em `Transaction` **e** `Span` (aninhamento arbitrário).
-- Métodos encadeáveis: `setStatus`, `setData` (span), `setTag`/`setName` (transaction).
-- `finish()` na transaction fecha os spans abertos e envia o payload; nada é enviado se ela não foi amostrada. A amostragem é decidida no `startTransaction()`.
+- `startChild(op?, description?)` existe em `Transaction` **e** `Step` (aninhamento arbitrário).
+- Métodos encadeáveis: `setStatus`, `setData` (step), `setTag`/`setName` (transaction).
+- `finish()` na transaction fecha as etapas abertas e envia o payload; nada é enviado se ela não foi amostrada. A amostragem é decidida no `startTransaction()`.
 
-Dentro de um handler de task, `startTransaction()` **retorna a transaction da própria run** (`ctx.tx`) em vez de criar uma segunda — cada execução tem exatamente **uma** transaction. Conceitos: [Transaction](./docs/concepts.md#transaction) · [Span](./docs/concepts.md#span).
+Dentro de um handler de task, `startTransaction()` **retorna a transaction da própria run** (`ctx.tx`) em vez de criar uma segunda — cada execução tem exatamente **uma** transaction. Conceitos: [Transaction](./docs/concepts.md#transaction) · [Step](./docs/concepts.md#step).
 
 ### Crons (check-ins)
 
@@ -364,11 +364,11 @@ Empacotado em **ESM e CommonJS** com **definições de tipos** (`.d.ts`) para to
 
 Guias detalhados acompanham o pacote em [`docs/`](./docs/README.md).
 
-Novo no vocabulário de observabilidade (transaction, span, breadcrumb, tag, context, extra, flush, close)? Comece por [Conceitos](./docs/concepts.md) — as outras páginas assumem esses termos.
+Novo no vocabulário de observabilidade (transaction, step, breadcrumb, tag, context, extra, flush, close)? Comece por [Conceitos](./docs/concepts.md) — as outras páginas assumem esses termos.
 
 - [Conceitos](./docs/concepts.md) — o que cada coisa é, por que existe e quando escolher uma em vez da outra.
 - [Getting started](./docs/getting-started.md) — instalação, Client Secret, primeiro `init`, telemetria e tasks.
-- [Telemetria](./docs/monitor.md) — erros, breadcrumbs, escopo, transactions/spans, crons, heartbeat.
+- [Telemetria](./docs/monitor.md) — erros, breadcrumbs, escopo, transactions/etapas, crons, heartbeat.
 - [Tasks](./docs/tasks.md) — handlers, `RunContext`, cancelamento, concorrência, idempotência.
 - [Referência de API](./docs/api-reference.md) — todas as funções e tabelas de opções com defaults.
 - [Protocolo & transporte](./docs/protocol.md) — o Client Secret, endpoints, envelope, retries.

package/dist/index.cjs

@@ -33,7 +33,7 @@ __export(src_exports, {
   Client: () => Client,
   DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
   Scope: () => Scope,
-  Span: () => Span,
+  Step: () => Step,
   Transaction: () => Transaction,
   addBreadcrumb: () => addBreadcrumb,
   captureException: () => captureException,
@@ -163,7 +163,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "1.7.2" : "0.0.0-dev";
+var SDK_VERSION = true ? "1.7.6" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -719,20 +719,44 @@ var Scope = class _Scope {
 };
 
 // src/transaction.ts
-function spanId() {
+function stepId() {
   return uuid4().slice(0, 16);
 }
-function spanLabel(op, description) {
+function stepLabel(op, description) {
   return [op, description].filter(Boolean).join(" \u2014 ") || "(sem nome)";
 }
-var Span = class {
-  constructor(transaction, parentSpanId, op, description) {
+function levelForStatus(status) {
+  switch (status) {
+    case "warning":
+      return "warning";
+    case "error":
+      return "error";
+    case "cancelled":
+      return "warning";
+    default:
+      return "success";
+  }
+}
+function colorForStatus(status) {
+  switch (status) {
+    case "warning":
+      return "yellow";
+    case "error":
+      return "red";
+    case "cancelled":
+      return "gray";
+    default:
+      return "green";
+  }
+}
+var Step = class {
+  constructor(transaction, parentStepId, op, description) {
     this.transaction = transaction;
-    this.parentSpanId = parentSpanId;
+    this.parentStepId = parentStepId;
     this.op = op;
     this.description = description;
   }
-  spanId = spanId();
+  stepId = stepId();
   startTimestamp = nowISO();
   status = "ok";
   endTimestamp;
@@ -745,19 +769,26 @@ var Span = class {
     this.data = { ...this.data, [key]: value };
     return this;
   }
-  /** Span aninhado (filho deste span). */
+  /** Step aninhada (filha desta step). */
   startChild(op, description) {
-    return this.transaction.createSpan(this.spanId, op, description);
+    return this.transaction.createStep(this.stepId, op, description);
   }
   finish() {
     if (this.endTimestamp) return;
     this.endTimestamp = nowISO();
-    this.transaction.emit("span", "finish", spanLabel(this.op, this.description), this.startTimestamp, this.endTimestamp);
+    this.transaction.emit(
+      "step",
+      "finish",
+      stepLabel(this.op, this.description),
+      this.startTimestamp,
+      this.endTimestamp,
+      this.status
+    );
   }
   toJSON() {
     return {
-      span_id: this.spanId,
-      parent_span_id: this.parentSpanId,
+      step_id: this.stepId,
+      parent_step_id: this.parentStepId,
       op: this.op,
       description: this.description,
       status: this.status,
@@ -777,10 +808,10 @@ var Transaction = class {
     this.emit("transaction", "start", op ? `${name} (${op})` : name);
   }
   eventId = uuid4();
-  spanId = spanId();
+  stepId = stepId();
   startTimestamp = nowISO();
   status = "ok";
-  spans = [];
+  steps = [];
   tags = {};
   finished = false;
   lifecycleSink;
@@ -788,16 +819,16 @@ var Transaction = class {
   // antes do RunReporter conectar) — replay no setLifecycleSink
   lifecycleBacklog = [];
   /**
-   * Ecoa no terminal o início/fim de um span ou transaction (sempre, independente de
+   * 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.
    */
-  emit(kind, phase, label, startTs, endTs) {
+  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" ? "green" : "cyan");
+    const tag = colorize(`[hobots:${kind}] ${phase.toUpperCase()}`, phase === "finish" ? colorForStatus(status ?? "ok") : "cyan");
     const suffix = durationMs != null ? ` (${durationMs}ms)` : "";
     console.log(`${tag} ${label}${suffix}`);
-    const level = phase === "finish" ? "success" : "info";
+    const level = phase === "finish" ? levelForStatus(status ?? "ok") : "info";
     const message = `[${kind}] ${phase.toUpperCase()} ${label}${suffix}`;
     if (this.lifecycleSink) this.lifecycleSink(level, message);
     else if (this.lifecycleBacklog.length < 100) this.lifecycleBacklog.push([level, message]);
@@ -809,15 +840,15 @@ var Transaction = class {
     this.lifecycleBacklog = [];
     for (const [level, message] of backlog) sink(level, message);
   }
-  createSpan(parentSpanId, op, description) {
-    const span = new Span(this, parentSpanId, op, description);
-    this.spans.push(span);
-    this.emit("span", "start", spanLabel(op, description));
-    return span;
+  createStep(parentStepId, op, description) {
+    const step = new Step(this, parentStepId, op, description);
+    this.steps.push(step);
+    this.emit("step", "start", stepLabel(op, description));
+    return step;
   }
-  /** Span direto da transaction. */
+  /** Step direta da transaction. */
   startChild(op, description) {
-    return this.createSpan(this.spanId, op, description);
+    return this.createStep(this.stepId, op, description);
   }
   setTag(key, value) {
     this.tags[key] = value;
@@ -834,14 +865,15 @@ var Transaction = class {
   finish() {
     if (this.finished) return;
     this.finished = true;
-    for (const span of this.spans) span.finish();
+    for (const step of this.steps) step.finish();
     const endTimestamp = nowISO();
     this.emit(
       "transaction",
       "finish",
       this.op ? `${this.name} (${this.op})` : this.name,
       this.startTimestamp,
-      endTimestamp
+      endTimestamp,
+      this.status
     );
     if (!this.sampled || !this.client) return;
     const payload = {
@@ -851,7 +883,7 @@ var Transaction = class {
       status: this.status,
       start_timestamp: this.startTimestamp,
       timestamp: endTimestamp,
-      spans: this.spans.map((span) => span.toJSON()),
+      steps: this.steps.map((step) => step.toJSON()),
       tags: Object.keys(this.tags).length > 0 ? this.tags : void 0,
       run_id: this.runId
     };