hobots 1.7.5 → 1.8.0

package/README.md

@@ -1,8 +1,8 @@
 # hobots
 
-SDK JavaScript/TypeScript da **Hobots** para instrumentar funcionários digitais (RPAs) e integrações.
+SDK JavaScript/TypeScript da **Hobots** para instrumentar agentes (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**).
 - **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, 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,31 +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).
-
-### Crons (check-ins)
-
-Monitora jobs agendados no módulo **Monitores** do app: check-in `in_progress` na entrada, `ok`/`error` na saída, com duração medida. O jeito recomendado é `withMonitor`, que faz o par e captura exceções:
-
-```js
-await Hobots.withMonitor(
-  'sync-notas',
-  () => executarSync(),
-  { schedule: '0 */2 * * *', timezone: 'America/Fortaleza' }
-);
-```
-
-O `schedule` (expressão cron) faz o servidor **criar/atualizar o monitor automaticamente** (upsert) e habilita a detecção de **execução perdida**. Para controle manual:
-
-```js
-const id = Hobots.checkIn({ monitorSlug: 'sync-notas', status: 'in_progress' });
-// … trabalho …
-Hobots.checkIn({ monitorSlug: 'sync-notas', status: 'ok', checkInId: id, durationMs: 1234 });
-```
+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).
 
 ### Heartbeat (uptime)
 
@@ -353,7 +333,7 @@ Para parar de aceitar execuções **sem** derrubar a telemetria, use `stop(timeo
 
 | Import | Conteúdo |
 | --- | --- |
-| `hobots` | Tudo: `init`, telemetria (captura, transactions, crons, heartbeat), tasks (`register`/`start`/`stop`), `close`, classes e tipos. |
+| `hobots` | Tudo: `init`, telemetria (captura, transactions, heartbeat), tasks (`register`/`start`/`stop`), `close`, classes e tipos. |
 | `hobots/protocol` | Tipos do wire format (telemetria e tasks). |
 
 Empacotado em **ESM e CommonJS** com **definições de tipos** (`.d.ts`) para todas as entradas.
@@ -364,11 +344,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/telemetry.md) — erros, breadcrumbs, escopo, transactions/etapas, 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,12 +33,11 @@ __export(src_exports, {
   Client: () => Client,
   DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
   Scope: () => Scope,
-  Span: () => Span,
+  Step: () => Step,
   Transaction: () => Transaction,
   addBreadcrumb: () => addBreadcrumb,
   captureException: () => captureException,
   captureMessage: () => captureMessage,
-  checkIn: () => checkIn,
   close: () => close,
   flush: () => flush,
   getClient: () => getClient,
@@ -53,7 +52,6 @@ __export(src_exports, {
   start: () => start,
   startTransaction: () => startTransaction,
   stop: () => stop,
-  withMonitor: () => withMonitor,
   withScope: () => withScope
 });
 module.exports = __toCommonJS(src_exports);
@@ -163,7 +161,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "1.7.5" : "0.0.0-dev";
+var SDK_VERSION = true ? "1.8.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -517,16 +515,6 @@ var Client = class {
       }
     });
   }
-  sendCheckIn(payload) {
-    this.transport.enqueue({
-      type: "check_in",
-      payload: {
-        ...payload,
-        release: payload.release ?? this.options.release,
-        environment: payload.environment ?? this.options.environment ?? "production"
-      }
-    });
-  }
   sendHeartbeat(payload) {
     this.transport.enqueue({
       type: "heartbeat",
@@ -719,10 +707,10 @@ 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)";
 }
 function levelForStatus(status) {
@@ -749,14 +737,14 @@ function colorForStatus(status) {
       return "green";
   }
 }
-var Span = class {
-  constructor(transaction, parentSpanId, op, description) {
+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;
@@ -769,17 +757,17 @@ 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",
+      "step",
       "finish",
-      spanLabel(this.op, this.description),
+      stepLabel(this.op, this.description),
       this.startTimestamp,
       this.endTimestamp,
       this.status
@@ -787,8 +775,8 @@ var Span = class {
   }
   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,
@@ -808,10 +796,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;
@@ -819,7 +807,7 @@ 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.
    */
@@ -840,15 +828,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;
@@ -865,7 +853,7 @@ 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",
@@ -883,7 +871,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
     };
@@ -891,34 +879,6 @@ var Transaction = class {
   }
 };
 
-// src/checkin.ts
-function sendCheckIn(client2, options) {
-  const checkInId = options.checkInId ?? uuid4();
-  client2.sendCheckIn({
-    check_in_id: checkInId,
-    monitor_slug: options.monitorSlug,
-    status: options.status,
-    duration_ms: options.durationMs,
-    schedule: options.schedule,
-    timezone: options.timezone
-  });
-  return checkInId;
-}
-async function withMonitorImpl(client2, captureError, monitorSlug, fn, options) {
-  const base = { monitorSlug, schedule: options?.schedule, timezone: options?.timezone };
-  const checkInId = sendCheckIn(client2, { ...base, status: "in_progress" });
-  const startedAt = Date.now();
-  try {
-    const result = await fn();
-    sendCheckIn(client2, { ...base, status: "ok", checkInId, durationMs: Date.now() - startedAt });
-    return result;
-  } catch (error) {
-    sendCheckIn(client2, { ...base, status: "error", checkInId, durationMs: Date.now() - startedAt });
-    captureError(error);
-    throw error;
-  }
-}
-
 // src/tasks/api.ts
 var POLL_TIMEOUT_MS = 3e4;
 var UPDATE_TIMEOUT_MS = 1e4;
@@ -1464,7 +1424,7 @@ var TaskAgent = class {
         {
           agent: {
             // identidade canônica do agente no painel — o mesmo instanceId do
-            // heartbeat do Monitor, então os dois canais convergem em um agente
+            // heartbeat da Telemetria, então os dois canais convergem em um agente
             instance_id: this.instanceId,
             version: SDK_VERSION,
             host: hostname(),
@@ -1666,19 +1626,6 @@ function startTransaction(name, op) {
   const sampled = rate >= 1 || Math.random() < rate;
   return new Transaction(client, name, op, sampled);
 }
-function checkIn(options) {
-  return client ? sendCheckIn(client, options) : void 0;
-}
-async function withMonitor(monitorSlug, fn, options) {
-  if (!client) return fn();
-  return withMonitorImpl(
-    client,
-    (error) => captureException(error, { tags: { monitor: monitorSlug } }),
-    monitorSlug,
-    fn,
-    options
-  );
-}
 function flush(timeoutMs) {
   return client ? client.flush(timeoutMs) : Promise.resolve(true);
 }