hobots 1.3.6 → 1.5.1

package/dist/manager/protocol.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/manager/protocol.ts"],"sourcesContent":["/**\n * Tipos do protocolo do Hobots Manager (agente SDK ↔ servidor).\n *\n * Este arquivo é a fonte de verdade do wire format e não pode importar nada:\n * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`\n * contra estes tipos (reexportados por `hobots/protocol`; `hobots/manager/protocol` é alias transitório).\n */\n\n/** Ciclo de vida completo de uma run no servidor. */\nexport type ManagerRunStatus = 'pending' | 'claimed' | 'running' | 'succeeded' | 'failed' | 'canceled';\n\n/** Subconjunto que o agente pode enviar no PATCH. */\nexport type ManagerRunUpdateStatus = 'running' | 'succeeded' | 'failed';\n\nexport type RunLogLevel = 'debug' | 'info' | 'warning' | 'error';\n\nexport interface RunLogEntry {\n  /** ISO 8601 — relógio do agente, apenas para exibição */\n  ts: string;\n  level: RunLogLevel;\n  message: string;\n}\n\nexport interface ManagerAgentInfo {\n  /** Identidade canônica do agente — correlaciona com o heartbeat do Monitor */\n  instance_id: string;\n  name?: string;\n  /** Versão do SDK */\n  version?: string;\n  /** Hostname da máquina */\n  host?: string;\n  /** Tasks registradas no agente */\n  tasks?: string[];\n}\n\n/** POST /v1/manager/poll */\nexport interface ManagerPollRequest {\n  agent?: ManagerAgentInfo;\n  /** Quantas runs reivindicar de uma vez (1..5). Default: 1 */\n  max?: number;\n  /** Só entrega runs destas tasks (nomes registrados no agente) */\n  tasks?: string[];\n}\n\nexport interface ManagerRunDescriptor {\n  id: string;\n  task: string;\n  params: Record<string, unknown>;\n  form: { id: string; name: string } | null;\n  /** Origem da run: 'manual' | 'link' | 'schedule' (informativo) */\n  source: string;\n  /** ISO 8601 (relógio do servidor) */\n  created_at: string;\n}\n\nexport interface ManagerPollResponse {\n  runs: ManagerRunDescriptor[];\n}\n\nexport interface ManagerRunError {\n  /** ex.: nome da classe do erro */\n  type?: string;\n  message: string;\n  stack?: string;\n}\n\n/** PATCH /v1/manager/runs/{id} — 'running' pode repetir com logs incrementais */\nexport interface ManagerRunUpdateRequest {\n  status: ManagerRunUpdateStatus;\n  /** Apenas com status 'failed' */\n  error?: ManagerRunError;\n  /** Delta desde o último envio — o servidor concatena */\n  logs?: RunLogEntry[];\n}\n\nexport interface ManagerRunUpdateResponse {\n  ok: true;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/manager/protocol.ts"],"sourcesContent":["/**\n * Tipos do protocolo do Hobots Manager (agente SDK ↔ servidor).\n *\n * Este arquivo é a fonte de verdade do wire format e não pode importar nada:\n * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`\n * contra estes tipos (reexportados por `hobots/protocol`; `hobots/manager/protocol` é alias transitório).\n */\n\n/** Ciclo de vida completo de uma run no servidor. */\nexport type ManagerRunStatus = 'pending' | 'claimed' | 'running' | 'succeeded' | 'failed' | 'canceled';\n\n/** Subconjunto que o agente pode enviar no PATCH. */\nexport type ManagerRunUpdateStatus = 'running' | 'succeeded' | 'failed';\n\nexport type RunLogLevel = 'debug' | 'info' | 'warning' | 'error' | 'success';\n\nexport interface RunLogEntry {\n  /** ISO 8601 — relógio do agente, apenas para exibição */\n  ts: string;\n  level: RunLogLevel;\n  message: string;\n}\n\nexport interface ManagerAgentInfo {\n  /** Identidade canônica do agente — correlaciona com o heartbeat do Monitor */\n  instance_id: string;\n  name?: string;\n  /** Versão do SDK */\n  version?: string;\n  /** Hostname da máquina */\n  host?: string;\n  /** Tasks registradas no agente */\n  tasks?: string[];\n}\n\n/** POST /v1/manager/poll */\nexport interface ManagerPollRequest {\n  agent?: ManagerAgentInfo;\n  /** Quantas runs reivindicar de uma vez (1..5). Default: 1 */\n  max?: number;\n  /** Só entrega runs destas tasks (nomes registrados no agente) */\n  tasks?: string[];\n}\n\nexport interface ManagerRunDescriptor {\n  id: string;\n  task: string;\n  params: Record<string, unknown>;\n  form: { id: string; name: string } | null;\n  /** Origem da run: 'hobots' | 'link' | 'schedule' (informativo) */\n  source: string;\n  /** ISO 8601 (relógio do servidor) */\n  created_at: string;\n}\n\nexport interface ManagerPollResponse {\n  runs: ManagerRunDescriptor[];\n}\n\nexport interface ManagerRunError {\n  /** ex.: nome da classe do erro */\n  type?: string;\n  message: string;\n  stack?: string;\n}\n\n/** PATCH /v1/manager/runs/{id} — 'running' pode repetir com logs incrementais */\nexport interface ManagerRunUpdateRequest {\n  status: ManagerRunUpdateStatus;\n  /** Apenas com status 'failed' */\n  error?: ManagerRunError;\n  /** Delta desde o último envio — o servidor concatena */\n  logs?: RunLogEntry[];\n}\n\nexport interface ManagerRunUpdateResponse {\n  ok: true;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/manager/protocol.d.cts

@@ -9,7 +9,7 @@
 type ManagerRunStatus = 'pending' | 'claimed' | 'running' | 'succeeded' | 'failed' | 'canceled';
 /** Subconjunto que o agente pode enviar no PATCH. */
 type ManagerRunUpdateStatus = 'running' | 'succeeded' | 'failed';
-type RunLogLevel = 'debug' | 'info' | 'warning' | 'error';
+type RunLogLevel = 'debug' | 'info' | 'warning' | 'error' | 'success';
 interface RunLogEntry {
     /** ISO 8601 — relógio do agente, apenas para exibição */
     ts: string;
@@ -43,7 +43,7 @@ interface ManagerRunDescriptor {
         id: string;
         name: string;
     } | null;
-    /** Origem da run: 'manual' | 'link' | 'schedule' (informativo) */
+    /** Origem da run: 'hobots' | 'link' | 'schedule' (informativo) */
     source: string;
     /** ISO 8601 (relógio do servidor) */
     created_at: string;

package/dist/manager/protocol.d.ts

@@ -9,7 +9,7 @@
 type ManagerRunStatus = 'pending' | 'claimed' | 'running' | 'succeeded' | 'failed' | 'canceled';
 /** Subconjunto que o agente pode enviar no PATCH. */
 type ManagerRunUpdateStatus = 'running' | 'succeeded' | 'failed';
-type RunLogLevel = 'debug' | 'info' | 'warning' | 'error';
+type RunLogLevel = 'debug' | 'info' | 'warning' | 'error' | 'success';
 interface RunLogEntry {
     /** ISO 8601 — relógio do agente, apenas para exibição */
     ts: string;
@@ -43,7 +43,7 @@ interface ManagerRunDescriptor {
         id: string;
         name: string;
     } | null;
-    /** Origem da run: 'manual' | 'link' | 'schedule' (informativo) */
+    /** Origem da run: 'hobots' | 'link' | 'schedule' (informativo) */
     source: string;
     /** ISO 8601 (relógio do servidor) */
     created_at: string;

package/dist/protocol.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/protocol.ts"],"sourcesContent":["/**\n * Tipos do protocolo de ingestão do Hobots Monitor (SDK → servidor).\n *\n * Este arquivo é a fonte de verdade do wire format e só pode reexportar tipos:\n * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`\n * contra estes tipos (importados de `hobots/protocol`).\n */\n\n// Wire format do Manager (agente ↔ servidor) — reexportado aqui para o app\n// consumir tudo de `hobots/protocol`.\nexport type {\n  ManagerRunStatus,\n  ManagerRunUpdateStatus,\n  RunLogLevel,\n  RunLogEntry,\n  ManagerAgentInfo,\n  ManagerPollRequest,\n  ManagerRunDescriptor,\n  ManagerPollResponse,\n  ManagerRunError,\n  ManagerRunUpdateRequest,\n  ManagerRunUpdateResponse,\n} from './manager/protocol';\n\nexport type Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'success';\n\n/** Frames em ordem innermost-first (mesma ordem impressa pelo V8). */\nexport interface StackFrame {\n  function?: string;\n  filename?: string;\n  lineno?: number;\n  colno?: number;\n  in_app: boolean;\n}\n\nexport interface Breadcrumb {\n  /** ISO 8601 */\n  timestamp: string;\n  type?: string;\n  category?: string;\n  message?: string;\n  level?: Severity;\n  data?: Record<string, unknown>;\n}\n\nexport interface ExceptionData {\n  type: string;\n  value: string;\n  stacktrace?: { frames: StackFrame[] };\n}\n\nexport interface EventUser {\n  id?: string;\n  username?: string;\n  email?: string;\n}\n\nexport interface EventPayload {\n  /** uuid v4 sem hífens (32 hex), gerado pelo SDK */\n  event_id: string;\n  /** ISO 8601 */\n  timestamp: string;\n  level: Severity;\n  message?: string;\n  exception?: ExceptionData;\n  /** Override de agrupamento; quando ausente o servidor calcula pelo stack trace */\n  fingerprint?: string[];\n  breadcrumbs?: Breadcrumb[];\n  tags?: Record<string, string>;\n  user?: EventUser;\n  contexts?: Record<string, Record<string, unknown>>;\n  extra?: Record<string, unknown>;\n  release?: string;\n  environment?: string;\n}\n\nexport interface SpanData {\n  /** 16 hex */\n  span_id: string;\n  parent_span_id?: string;\n  op?: string;\n  description?: string;\n  status?: string;\n  /** ISO 8601 */\n  start_timestamp: string;\n  /** ISO 8601 (fim do span) */\n  timestamp: string;\n  data?: Record<string, unknown>;\n}\n\nexport interface TransactionPayload {\n  event_id: string;\n  name: string;\n  op?: string;\n  status: string;\n  start_timestamp: string;\n  timestamp: string;\n  spans: SpanData[];\n  tags?: Record<string, string>;\n  release?: string;\n  environment?: string;\n  /** Correlaciona esta transaction a uma execução do Manager (ctx.tx dentro de um task handler) */\n  run_id?: string;\n}\n\nexport type CheckInStatus = 'in_progress' | 'ok' | 'error';\n\nexport interface CheckInPayload {\n  /** Mesmo id no par in_progress → ok/error para casar início e fim */\n  check_in_id: string;\n  monitor_slug: string;\n  status: CheckInStatus;\n  duration_ms?: number;\n  /** Expressão cron — permite o servidor criar o monitor automaticamente (upsert) */\n  schedule?: string;\n  timezone?: string;\n  environment?: string;\n  release?: string;\n}\n\nexport interface HeartbeatPayload {\n  instance_id: string;\n  name?: string;\n  interval_ms: number;\n  /** ISO 8601 */\n  timestamp: string;\n  metadata?: Record<string, unknown>;\n  release?: string;\n}\n\nexport type EnvelopeItem =\n  | { type: 'event'; payload: EventPayload }\n  | { type: 'transaction'; payload: TransactionPayload }\n  | { type: 'check_in'; payload: CheckInPayload }\n  | { type: 'heartbeat'; payload: HeartbeatPayload };\n\nexport interface Envelope {\n  sdk: { name: string; version: string };\n  /** ISO 8601 */\n  sent_at: string;\n  items: EnvelopeItem[];\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/protocol.ts"],"sourcesContent":["/**\n * Tipos do protocolo de ingestão do Hobots Monitor (SDK → servidor).\n *\n * Este arquivo é a fonte de verdade do wire format e só pode reexportar tipos:\n * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`\n * contra estes tipos (importados de `hobots/protocol`).\n */\n\n// Wire format do Manager (agente ↔ servidor) — reexportado aqui para o app\n// consumir tudo de `hobots/protocol`.\nexport type {\n  ManagerRunStatus,\n  ManagerRunUpdateStatus,\n  RunLogLevel,\n  RunLogEntry,\n  ManagerAgentInfo,\n  ManagerPollRequest,\n  ManagerRunDescriptor,\n  ManagerPollResponse,\n  ManagerRunError,\n  ManagerRunUpdateRequest,\n  ManagerRunUpdateResponse,\n} from './manager/protocol';\n\nexport type Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'success';\n\n/** Frames em ordem innermost-first (mesma ordem impressa pelo V8). */\nexport interface StackFrame {\n  function?: string;\n  filename?: string;\n  lineno?: number;\n  colno?: number;\n  in_app: boolean;\n}\n\nexport interface Breadcrumb {\n  /** ISO 8601 */\n  timestamp: string;\n  type?: string;\n  category?: string;\n  message?: string;\n  level?: Severity;\n  data?: Record<string, unknown>;\n}\n\nexport interface ExceptionData {\n  type: string;\n  value: string;\n  stacktrace?: { frames: StackFrame[] };\n}\n\nexport interface EventUser {\n  id?: string;\n  username?: string;\n  email?: string;\n}\n\nexport interface EventPayload {\n  /** uuid v4 sem hífens (32 hex), gerado pelo SDK */\n  event_id: string;\n  /** ISO 8601 */\n  timestamp: string;\n  level: Severity;\n  message?: string;\n  exception?: ExceptionData;\n  /** Override de agrupamento; quando ausente o servidor calcula pelo stack trace */\n  fingerprint?: string[];\n  breadcrumbs?: Breadcrumb[];\n  tags?: Record<string, string>;\n  user?: EventUser;\n  contexts?: Record<string, Record<string, unknown>>;\n  extra?: Record<string, unknown>;\n  release?: string;\n  environment?: string;\n}\n\n/** Status de um span (etapa). `warning` = terminou, mas merece atenção (não é falha). */\nexport type SpanStatus = 'ok' | 'warning' | 'error' | 'cancelled';\n\nexport interface SpanData {\n  /** 16 hex */\n  span_id: string;\n  parent_span_id?: string;\n  op?: string;\n  description?: string;\n  status?: SpanStatus;\n  /** ISO 8601 */\n  start_timestamp: string;\n  /** ISO 8601 (fim do span) */\n  timestamp: string;\n  data?: Record<string, unknown>;\n}\n\nexport interface TransactionPayload {\n  event_id: string;\n  name: string;\n  op?: string;\n  status: string;\n  start_timestamp: string;\n  timestamp: string;\n  spans: SpanData[];\n  tags?: Record<string, string>;\n  release?: string;\n  environment?: string;\n  /** Correlaciona esta transaction a uma execução do Manager (ctx.tx dentro de um task handler) */\n  run_id?: string;\n}\n\nexport type CheckInStatus = 'in_progress' | 'ok' | 'error';\n\nexport interface CheckInPayload {\n  /** Mesmo id no par in_progress → ok/error para casar início e fim */\n  check_in_id: string;\n  monitor_slug: string;\n  status: CheckInStatus;\n  duration_ms?: number;\n  /** Expressão cron — permite o servidor criar o monitor automaticamente (upsert) */\n  schedule?: string;\n  timezone?: string;\n  environment?: string;\n  release?: string;\n}\n\nexport interface HeartbeatPayload {\n  instance_id: string;\n  name?: string;\n  interval_ms: number;\n  /** ISO 8601 */\n  timestamp: string;\n  metadata?: Record<string, unknown>;\n  release?: string;\n}\n\nexport type EnvelopeItem =\n  | { type: 'event'; payload: EventPayload }\n  | { type: 'transaction'; payload: TransactionPayload }\n  | { type: 'check_in'; payload: CheckInPayload }\n  | { type: 'heartbeat'; payload: HeartbeatPayload };\n\nexport interface Envelope {\n  sdk: { name: string; version: string };\n  /** ISO 8601 */\n  sent_at: string;\n  items: EnvelopeItem[];\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/protocol.d.cts

@@ -56,13 +56,15 @@ interface EventPayload {
     release?: string;
     environment?: string;
 }
+/** Status de um span (etapa). `warning` = terminou, mas merece atenção (não é falha). */
+type SpanStatus = 'ok' | 'warning' | 'error' | 'cancelled';
 interface SpanData {
     /** 16 hex */
     span_id: string;
     parent_span_id?: string;
     op?: string;
     description?: string;
-    status?: string;
+    status?: SpanStatus;
     /** ISO 8601 */
     start_timestamp: string;
     /** ISO 8601 (fim do span) */
@@ -128,4 +130,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export type { Breadcrumb, CheckInPayload, CheckInStatus, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, Severity, SpanData, StackFrame, TransactionPayload };
+export type { Breadcrumb, CheckInPayload, CheckInStatus, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, Severity, SpanData, SpanStatus, StackFrame, TransactionPayload };

package/dist/protocol.d.ts

@@ -56,13 +56,15 @@ interface EventPayload {
     release?: string;
     environment?: string;
 }
+/** Status de um span (etapa). `warning` = terminou, mas merece atenção (não é falha). */
+type SpanStatus = 'ok' | 'warning' | 'error' | 'cancelled';
 interface SpanData {
     /** 16 hex */
     span_id: string;
     parent_span_id?: string;
     op?: string;
     description?: string;
-    status?: string;
+    status?: SpanStatus;
     /** ISO 8601 */
     start_timestamp: string;
     /** ISO 8601 (fim do span) */
@@ -128,4 +130,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export type { Breadcrumb, CheckInPayload, CheckInStatus, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, Severity, SpanData, StackFrame, TransactionPayload };
+export type { Breadcrumb, CheckInPayload, CheckInStatus, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, Severity, SpanData, SpanStatus, StackFrame, TransactionPayload };

package/docs/concepts.md

@@ -243,6 +243,7 @@ span.setData('notas', 42).finish();
 O `op` é a categoria (útil para agrupar "todas as queries") e a `description` é o detalhe humano ("`INSERT INTO notas`"). `setData(chave, valor)` anexa dados àquele span específico — contagens, tamanhos, ids.
 
 - Métodos encadeáveis: `setStatus`, `setData`, `finish`.
+- **Status do span:** `'ok'` (default), `'warning'` (terminou, mas merece atenção — não é falha) ou `'error'` (falhou). No waterfall do app cada um tem sua cor: verde/neutro, âmbar e vermelho. Use `span.setStatus('warning')` para etapas que passaram com ressalva (ex.: retry que deu certo, resultado parcial).
 - Esquecer o `finish()` de um span **não perde o dado**: o `finish()` da transaction fecha os spans abertos, marcando o fim naquele instante.
 - Os spans são guardados numa lista plana ligada por `parent_span_id` — o aninhamento que você vê no app é reconstruído a partir dessas referências, não da ordem das chamadas.
 

package/docs/manager.md

@@ -92,6 +92,7 @@ Cada `startChild` vira uma barra no waterfall da aba de performance daquela exec
 - **Não chame `Hobots.startTransaction()` dentro de um handler.** Você criaria uma segunda transaction, sem correlação com a run, e ela não apareceria na execução.
 - `ctx.tx` **não respeita o `tracesSampleRate`** — toda run gera uma transaction. A amostragem vale só para as transactions que você abre com `startTransaction()`.
 - Span que você esquecer aberto é fechado no `finish()` da transaction, então o dado não se perde.
+- Marque etapas com ressalva usando `span.setStatus('warning')` (ex.: retry que deu certo, resultado parcial): elas aparecem em âmbar no waterfall, distintas de sucesso e de falha (`'error'`).
 
 ## Cancelamento cooperativo
 

package/docs/monitor.md

@@ -109,6 +109,7 @@ tx.finish(); // só aqui a transaction é enviada (respeitando tracesSampleRate)
 
 - `startChild(op?, description?)` existe tanto em `Transaction` quanto em `Span` (aninhamento arbitrário).
 - Métodos encadeáveis: `setStatus`, `setData` (span), `setTag`/`setName` (transaction).
+- Status de span: `'ok'` (default), `'warning'` (atenção, não é falha) ou `'error'` — cores distintas no waterfall.
 - `finish()` na transaction fecha spans abertos e envia o payload; nada é enviado se ela não foi amostrada. É **idempotente** — chamar duas vezes não envia duas.
 - A decisão de amostragem acontece no **`startTransaction()`**, não no `finish()`. Esquecer o `finish()` de um span não perde o dado: ele é fechado no instante em que a transaction fecha.
 - Uma transaction leva as tags do `init()` e as que você marcar com `tx.setTag()` — ela **não** herda as tags do scope.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hobots",
-  "version": "1.3.6",
+  "version": "1.5.1",
   "description": "SDK JavaScript da Hobots — captura de erros, transactions, check-ins de cron e heartbeats (Monitor) e execução remota de tarefas sob demanda (Manager) para RPAs e integrações. Um único import e um único init().",
   "type": "module",
   "sideEffects": false,