hobots 1.10.0 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +36 -13
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +7 -4
- package/dist/index.d.ts +7 -4
- package/dist/index.js +36 -13
- package/dist/index.js.map +1 -1
- package/dist/protocol.cjs.map +1 -1
- package/dist/protocol.d.cts +8 -3
- package/dist/protocol.d.ts +8 -3
- package/docs/api-reference.md +1 -1
- package/docs/concepts.md +2 -2
- package/docs/protocol.md +3 -3
- package/package.json +1 -1
package/dist/protocol.cjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/protocol.ts"],"sourcesContent":["/**\n * Tipos do protocolo do Hobots (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 de tasks (agente ↔ servidor) — reexportado aqui para o app\n// consumir tudo de `hobots/protocol`.\nexport type {\n RunStatus,\n RunUpdateStatus,\n RunLogLevel,\n RunLogEntry,\n
|
|
1
|
+
{"version":3,"sources":["../src/protocol.ts"],"sourcesContent":["/**\n * Tipos do protocolo do Hobots (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 de tasks (agente ↔ servidor) — reexportado aqui para o app\n// consumir tudo de `hobots/protocol`.\nexport type {\n RunStatus,\n RunUpdateStatus,\n RunLogLevel,\n RunLogEntry,\n InstanceInfo,\n PollRequest,\n RunDescriptor,\n PollResponse,\n RunError,\n RunUpdateRequest,\n RunUpdateResponse,\n RunItemStatus,\n RunItemInput,\n RunItemsCreateRequest,\n RunItemsCreateResponse,\n RunAttachmentContentType,\n RunAttachmentCreateRequest,\n RunAttachmentCreateResponse,\n RunAttachmentConfirmRequest,\n RunAttachmentConfirmResponse,\n} from './tasks/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 uma step (etapa). `warning` = terminou, mas merece atenção (não é falha). */\nexport type StepStatus = 'ok' | 'warning' | 'error' | 'cancelled';\n\nexport interface StepData {\n /** 16 hex */\n step_id: string;\n parent_step_id?: string;\n op?: string;\n description?: string;\n status?: StepStatus;\n /** ISO 8601 */\n start_timestamp: string;\n /** ISO 8601 (fim da step) */\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 steps: StepData[];\n tags?: Record<string, string>;\n release?: string;\n environment?: string;\n /** Correlaciona esta transaction a uma execução de task (ctx.tx dentro de um task handler) */\n run_id?: 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: '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
CHANGED
|
@@ -22,7 +22,7 @@ interface RunLogEntry {
|
|
|
22
22
|
*/
|
|
23
23
|
attachments?: string[];
|
|
24
24
|
}
|
|
25
|
-
interface
|
|
25
|
+
interface InstanceInfo {
|
|
26
26
|
/** Identidade canônica do agente — correlaciona com o heartbeat de telemetria */
|
|
27
27
|
instance_id: string;
|
|
28
28
|
name?: string;
|
|
@@ -32,10 +32,15 @@ interface AgentInfo {
|
|
|
32
32
|
host?: string;
|
|
33
33
|
/** Tasks registradas no agente */
|
|
34
34
|
tasks?: string[];
|
|
35
|
+
/**
|
|
36
|
+
* Intervalo de poll em ms — alimenta a tolerância de offline do servidor (3×) em
|
|
37
|
+
* agentes poll-only, que sem isso herdariam a tolerância do heartbeat (30s × 3).
|
|
38
|
+
*/
|
|
39
|
+
poll_interval_ms?: number;
|
|
35
40
|
}
|
|
36
41
|
/** POST /v1/tasks/poll */
|
|
37
42
|
interface PollRequest {
|
|
38
|
-
|
|
43
|
+
instance?: InstanceInfo;
|
|
39
44
|
/** Quantas runs reivindicar de uma vez (1..5). Default: 1 */
|
|
40
45
|
max?: number;
|
|
41
46
|
/** Só entrega runs destas tasks (nomes registrados no agente) */
|
|
@@ -256,4 +261,4 @@ interface Envelope {
|
|
|
256
261
|
items: EnvelopeItem[];
|
|
257
262
|
}
|
|
258
263
|
|
|
259
|
-
export type {
|
|
264
|
+
export type { Breadcrumb, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, InstanceInfo, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemStatus, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, StackFrame, StepData, StepStatus, TransactionPayload };
|
package/dist/protocol.d.ts
CHANGED
|
@@ -22,7 +22,7 @@ interface RunLogEntry {
|
|
|
22
22
|
*/
|
|
23
23
|
attachments?: string[];
|
|
24
24
|
}
|
|
25
|
-
interface
|
|
25
|
+
interface InstanceInfo {
|
|
26
26
|
/** Identidade canônica do agente — correlaciona com o heartbeat de telemetria */
|
|
27
27
|
instance_id: string;
|
|
28
28
|
name?: string;
|
|
@@ -32,10 +32,15 @@ interface AgentInfo {
|
|
|
32
32
|
host?: string;
|
|
33
33
|
/** Tasks registradas no agente */
|
|
34
34
|
tasks?: string[];
|
|
35
|
+
/**
|
|
36
|
+
* Intervalo de poll em ms — alimenta a tolerância de offline do servidor (3×) em
|
|
37
|
+
* agentes poll-only, que sem isso herdariam a tolerância do heartbeat (30s × 3).
|
|
38
|
+
*/
|
|
39
|
+
poll_interval_ms?: number;
|
|
35
40
|
}
|
|
36
41
|
/** POST /v1/tasks/poll */
|
|
37
42
|
interface PollRequest {
|
|
38
|
-
|
|
43
|
+
instance?: InstanceInfo;
|
|
39
44
|
/** Quantas runs reivindicar de uma vez (1..5). Default: 1 */
|
|
40
45
|
max?: number;
|
|
41
46
|
/** Só entrega runs destas tasks (nomes registrados no agente) */
|
|
@@ -256,4 +261,4 @@ interface Envelope {
|
|
|
256
261
|
items: EnvelopeItem[];
|
|
257
262
|
}
|
|
258
263
|
|
|
259
|
-
export type {
|
|
264
|
+
export type { Breadcrumb, Envelope, EnvelopeItem, EventPayload, EventUser, ExceptionData, HeartbeatPayload, InstanceInfo, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemStatus, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, Severity, StackFrame, StepData, StepStatus, TransactionPayload };
|
package/docs/api-reference.md
CHANGED
|
@@ -84,7 +84,7 @@ Habilitadas com `tasks: true` (ou `TasksOptions`) no `init()` único. Todas expo
|
|
|
84
84
|
- **`start()`** — começa o polling. **Mantém o processo vivo** até `stop()`/`close()` — o timer não é `unref`'d, ao contrário dos da telemetria. Lança se o `init()` não configurou `tasks` ou se nenhuma task foi registrada. Também instala os handlers de saída (SIGINT/SIGTERM/erro fatal) que reportam as runs ativas como `AgentTerminated`, a menos que `installExitHandlers: false`.
|
|
85
85
|
- **`stop(timeoutMs = 30_000)`** → `Promise<boolean>` — encerra o polling e aguarda as [runs](./concepts.md#run) ativas terminarem. Para **só as tasks**: a telemetria (heartbeat, captura de erros) continua funcionando. Devolve `false` se estourou o timeout — as runs que ainda estavam rodando são reportadas como `AgentTerminated`. Para encerrar tudo, use [`close()`](./concepts.md#fila-flush-e-close).
|
|
86
86
|
|
|
87
|
-
No poll, o agente se identifica com `
|
|
87
|
+
No poll, o agente se identifica com `InstanceInfo` (`hobots/protocol`): o campo `instance_id` (o `instanceId` do `init()`) é a identidade canônica do agente — a mesma do heartbeat de telemetria, então os dois canais convergem em um agente no painel.
|
|
88
88
|
|
|
89
89
|
---
|
|
90
90
|
|
package/docs/concepts.md
CHANGED
|
@@ -41,9 +41,9 @@ Cada API do SDK alimenta um módulo do app da Hobots (app.hobots.app). O mapa:
|
|
|
41
41
|
| No SDK | No app |
|
|
42
42
|
| --- | --- |
|
|
43
43
|
| **Agente** — dono do Client Secret (`hb_…`) que autentica tudo | **Configurações → Agentes** (é lá que você copia a credencial) |
|
|
44
|
-
| **Instância** — o par `(
|
|
44
|
+
| **Instância** — o par `(agent_id, instance_id)`; heartbeat e poll de tasks convergem nele | Módulo **Instâncias** (uptime, performance) |
|
|
45
45
|
| **[Evento](#evento)** agrupado em **issue** — `captureException` / `captureMessage` | Módulo **Issues** |
|
|
46
|
-
| **[Transaction](#transaction) / etapas** — `startTransaction` (e [`ctx.tx`](#transaction-de-run-ctxtx) dentro de uma run) | Performance no módulo **
|
|
46
|
+
| **[Transaction](#transaction) / etapas** — `startTransaction` (e [`ctx.tx`](#transaction-de-run-ctxtx) dentro de uma run) | Performance no módulo **Instâncias**; nas execuções, a aba de performance da solicitação |
|
|
47
47
|
| **Task / [run](#run)** — `register('task-slug', …)` casa com o `task_slug` do formulário | Módulo **Solicitações** (formulários em **Configurações → Formulários**) |
|
|
48
48
|
|
|
49
49
|
---
|
package/docs/protocol.md
CHANGED
|
@@ -54,8 +54,8 @@ Corpo `PollRequest`:
|
|
|
54
54
|
|
|
55
55
|
```jsonc
|
|
56
56
|
{
|
|
57
|
-
"
|
|
58
|
-
"instance_id": "vm-01", // identidade canônica
|
|
57
|
+
"instance": {
|
|
58
|
+
"instance_id": "vm-01", // identidade canônica da instância (obrigatória)
|
|
59
59
|
"name": "VM 01",
|
|
60
60
|
"version": "2.0.0",
|
|
61
61
|
"host": "vm-01",
|
|
@@ -68,7 +68,7 @@ Corpo `PollRequest`:
|
|
|
68
68
|
|
|
69
69
|
Resposta `PollResponse` = `{ runs: RunDescriptor[] }`, cada `{ id, task, params, form, source, created_at }`.
|
|
70
70
|
|
|
71
|
-
O `
|
|
71
|
+
O `instance.instance_id` é a **mesma identidade** do heartbeat de telemetria (`instance_id`): o servidor correlaciona os dois canais numa tabela `instances` por `(agent_id, instance_id)`. Com o `init()` único, os dois derivam do `instanceId` — o robô aparece como um agente só no painel automaticamente. O próprio poll marca a presença da instância (`last_poll_at`), por isso o heartbeat é opcional quando as tasks estão habilitadas.
|
|
72
72
|
|
|
73
73
|
**Backoff:** um request por poll; o loop decide o ritmo. HTTP 401 (key rejeitada) → retry lento a 30s com log throttled; outros erros → ladder `[1s, 4s, 16s]`.
|
|
74
74
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hobots",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "2.0.0",
|
|
4
4
|
"description": "SDK JavaScript da Hobots — telemetria (erros, transactions e heartbeats) e execução remota de tarefas sob demanda (tasks) para RPAs e integrações. Um único import e um único init().",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"sideEffects": false,
|