hobots 1.1.0 → 1.2.0

package/README.md

@@ -26,7 +26,7 @@ Também funciona em CommonJS: `const Hobots = require('hobots')`.
 
 ## Um SDK, duas capabilities, um `init()`
 
-O SDK expõe **duas capabilities** autenticadas pela **mesma DSN única do projeto**, configuradas em um único `init()`:
+O SDK expõe **duas capabilities** autenticadas pelo **mesmo Client Secret do projeto**, configuradas em um único `init()`:
 
 | Capability | Como habilita | Para quê | Ciclo de vida |
 | --- | --- | --- | --- |
@@ -35,13 +35,14 @@ O SDK expõe **duas capabilities** autenticadas pela **mesma DSN única do proje
 
 Você usa **uma, outra ou as duas**:
 
-- Só saber se o robô quebrou, quanto demora e se está vivo? → `init({ dsn, heartbeat: true })`.
-- Disparar o robô sob demanda a partir de um formulário no app? → `init({ dsn, manager: true })` + `register()` + `start()`.
+- Só saber se o robô quebrou, quanto demora e se está vivo? → `init({ clientSecret, heartbeat: true })`.
+- Disparar o robô sob demanda a partir de um formulário no app? → `init({ clientSecret, manager: true })` + `register()` + `start()`.
 - Ambos? Passe `heartbeat` e `manager` no mesmo `init()` — o `instanceId` é a identidade única, e os dois canais convergem em **um agente** no painel.
 
 ```js
 Hobots.init({
-  dsn: 'https://<secretKey>@<host>/<projectSlug>',
+  clientSecret: 'hb_<64 hex>',
+  // baseUrl: 'http://localhost:3002', // só em desenvolvimento
   instanceId: 'vm-cliente-01',
   heartbeat: true,                              // Monitor: "estou vivo" a cada 30s
   manager: { pollIntervalMs: 5_000 },           // Manager: execução sob demanda
@@ -57,15 +58,15 @@ Hobots.start(); // inicia o polling do Manager (segura o processo vivo)
 
 ---
 
-## O DSN
+## O Client Secret
 
-Cada projeto tem **uma única DSN** — a mesma credencial autentica o Monitor **e** o Manager:
+Cada projeto tem **um único Client Secret** — a mesma credencial autentica o Monitor **e** o Manager:
 
 ```
-https://<secretKey>@<host>/<projectSlug>
+hb_<64 hex>
 ```
 
-A `secretKey` (64 hex) é **secreta**: vai embutida na DSN só por conveniência — nas requisições viaja sempre no header `Authorization: Bearer`, nunca na URL. O `projectSlug` do path é informativo; a identidade do projeto vem da chave. Copie a DSN pronta no app, em **Configurações → Agentes** — os snippets de integração já vêm prontos.
+(Chaves antigas, 64 hex puros, continuam válidas no servidor.) A credencial é **secreta** e viaja sempre no header `Authorization: Bearer` — nunca na URL. Copie o Client Secret no app, em **Configurações → Projetos** — os snippets de integração já vêm prontos. O SDK fala com `https://app.hobots.app` por padrão; só sobrescreva `baseUrl` em desenvolvimento (ex.: `http://localhost:3002`).
 
 ---
 
@@ -79,7 +80,8 @@ Inicialize **uma vez**, o mais cedo possível no processo. Cria o cliente, insta
 
 ```js
 Hobots.init({
-  dsn: 'https://<secretKey>@<host>/<projectSlug>',
+  clientSecret: 'hb_<64 hex>',
+  // baseUrl: 'http://localhost:3002', // só em desenvolvimento
   environment: 'production',
   release: 'robo-nfe@1.4.2',
   instanceId: 'vm-cliente-01',
@@ -90,7 +92,8 @@ Hobots.init({
 
 | Opção | Tipo | Default | Descrição |
 | --- | --- | --- | --- |
-| `dsn` | `string` | **obrigatório** | a DSN única do projeto: `https://<secretKey>@host/<projectSlug>` |
+| `clientSecret` | `string` | **obrigatório** | o Client Secret do projeto (`hb_<64 hex>`), copiado em **Configurações → Projetos** |
+| `baseUrl` | `string` | `'https://app.hobots.app'` | host do app da Hobots — só sobrescreva em desenvolvimento (ex.: `http://localhost:3002`) |
 | `environment` | `string` | `'production'` | ambiente lógico |
 | `release` | `string` | — | versão do programa, ex. `robo-nfe@1.4.2` |
 | `instanceId` | `string` | **obrigatório** | identidade única da instância — heartbeat do Monitor e agente do Manager convergem nela |
@@ -203,7 +206,7 @@ Bate "estou vivo" periodicamente; o servidor acusa o robô **offline** quando os
 
 ```js
 Hobots.init({
-  dsn,
+  clientSecret,
   heartbeat: { intervalMs: 30_000, name: 'Robô NFe — VM 01' },
 });
 ```
@@ -223,13 +226,14 @@ Chame `close` antes do processo sair. Os timers do Monitor são `unref`'d — el
 
 ## Manager
 
-Capability de **execução remota sob demanda**, habilitada com `manager: true` (ou opções) no `init()`. O agente faz polling no app, executa os handlers registrados quando aparece trabalho e reporta status e logs incrementais. Mesma DSN, mesmo `debug` e o `instanceId` como identidade — nenhum handler global extra é instalado.
+Capability de **execução remota sob demanda**, habilitada com `manager: true` (ou opções) no `init()`. O agente faz polling no app, executa os handlers registrados quando aparece trabalho e reporta status e logs incrementais. Mesmo Client Secret, mesmo `debug` e o `instanceId` como identidade — nenhum handler global extra é instalado.
 
 ### Ciclo de vida
 
 ```js
 Hobots.init({
-  dsn: 'https://<secretKey>@<host>/<projectSlug>',
+  clientSecret: 'hb_<64 hex>',
+  // baseUrl: 'http://localhost:3002', // só em desenvolvimento
   instanceId: 'vm-cliente-01',
   manager: true, // ou { pollIntervalMs, concurrency, ... }
 });
@@ -260,7 +264,7 @@ process.on('SIGINT', () => {
 | `taskTimeoutMs` | `number` | — | timeout client-side por run (não mata o handler; servidor é o backstop) |
 | `logFlushIntervalMs` | `number` | `2000` | intervalo do envio incremental de logs |
 
-A DSN, o `debug` e a identidade do agente (`instanceId`) vêm do `init()` — o heartbeat do Monitor e o agente do Manager convergem em **um agente** no painel automaticamente.
+O Client Secret, o `debug` e a identidade do agente (`instanceId`) vêm do `init()` — o heartbeat do Monitor e o agente do Manager convergem em **um agente** no painel automaticamente.
 
 ### O handler e o `RunContext`
 
@@ -354,7 +358,7 @@ A 2.0 unifica o Manager no import raiz — `hobots/manager` **foi removido**:
 
 -Monitor.init({ dsn, serverName: 'vm-01', heartbeat: true });
 -Manager.init({ dsn, agentName: 'vm-01' });
-+Hobots.init({ dsn, instanceId: 'vm-01', heartbeat: true, manager: true });
++Hobots.init({ clientSecret, instanceId: 'vm-01', heartbeat: true, manager: true });
 
 -Manager.register('minha-task', handler);
 -Manager.start();
@@ -366,8 +370,9 @@ A 2.0 unifica o Manager no import raiz — `hobots/manager` **foi removido**:
 +await Hobots.close(15_000);
 ```
 
+- A `dsn` (mecanismo antigo, `https://<secretKey>@host/<slug>`) não existe mais — passe `clientSecret` (e `baseUrl` só em desenvolvimento). Copie o Client Secret em **Configurações → Projetos**.
 - `agentName` e `serverName` não existem mais — a identidade do agente é o `instanceId` (obrigatório, sem fallback).
-- As opções do Manager (`pollIntervalMs`, `concurrency`, `taskTimeoutMs`, `logFlushIntervalMs`) vão no campo `manager` do `init()`; `dsn` e `debug` não se repetem.
+- As opções do Manager (`pollIntervalMs`, `concurrency`, `taskTimeoutMs`, `logFlushIntervalMs`) vão no campo `manager` do `init()`; `clientSecret` e `debug` não se repetem.
 - Tipos (`ManagerTaskHandler`, `RunContext`, `ManagerOptions`) e classes (`ManagerAgent`, `ManagerApi`) agora vêm de `hobots`; o wire format vem de `hobots/protocol`.
 
 ---
@@ -376,11 +381,11 @@ A 2.0 unifica o Manager no import raiz — `hobots/manager` **foi removido**:
 
 Guias detalhados acompanham o pacote em [`docs/`](./docs/README.md):
 
-- [Getting started](./docs/getting-started.md) — instalação, DSN, primeiro `init`, Monitor vs Hobots.
+- [Getting started](./docs/getting-started.md) — instalação, Client Secret, primeiro `init`, Monitor vs Hobots.
 - [Monitor](./docs/monitor.md) — erros, breadcrumbs, escopo, transactions/spans, crons, heartbeat.
 - [Manager](./docs/manager.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) — a DSN única, endpoints, envelope, retries.
+- [Protocolo & transporte](./docs/protocol.md) — o Client Secret, endpoints, envelope, retries.
 
 ---
 

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   Client: () => Client,
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
   ManagerAgent: () => ManagerAgent,
   ManagerApi: () => ManagerApi,
   ManagerApiError: () => ManagerApiError,
@@ -35,8 +36,8 @@ __export(src_exports, {
   flush: () => flush,
   getClient: () => getClient,
   init: () => init,
-  parseDsn: () => parseDsn,
   register: () => register,
+  resolveConfig: () => resolveConfig,
   setContext: () => setContext,
   setExtra: () => setExtra,
   setTag: () => setTag,
@@ -50,29 +51,24 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/dsn.ts
-function parseDsnUrl(dsn, prefix) {
-  let url;
+// src/config.ts
+var DEFAULT_BASE_URL = "https://app.hobots.app";
+function resolveConfig(options, prefix = "[hobots]") {
+  const key = options.clientSecret?.trim();
+  if (!key) {
+    throw new Error(`${prefix} clientSecret ausente \u2014 copie o Client Secret do projeto em Configura\xE7\xF5es \u2192 Projetos`);
+  }
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
   try {
-    url = new URL(dsn);
+    new URL(baseUrl);
   } catch {
-    throw new Error(`${prefix} DSN inv\xE1lido: "${dsn}"`);
+    throw new Error(`${prefix} baseUrl inv\xE1lida: "${baseUrl}" \u2014 esperado ex.: https://app.hobots.app`);
   }
-  const key = url.username;
-  const path = url.pathname.replace(/^\/+/, "");
-  if (!key || !path) {
-    throw new Error(`${prefix} DSN inv\xE1lido: "${dsn}" \u2014 esperado https://<key>@host/<projeto>`);
-  }
-  return { key, path, origin: `${url.protocol}//${url.host}` };
-}
-function parseDsn(dsn) {
-  const { key, path, origin } = parseDsnUrl(dsn, "[hobots]");
   return {
     key,
-    projectSlug: path,
-    origin,
-    ingestEndpoint: `${origin}/api/ingest`,
-    managerBaseUrl: `${origin}/api/manager`
+    baseUrl,
+    ingestEndpoint: `${baseUrl}/api/ingest`,
+    managerBaseUrl: `${baseUrl}/api/manager`
   };
 }
 
@@ -308,16 +304,16 @@ function runtimeContexts() {
 }
 var Client = class {
   options;
-  dsn;
+  config;
   logger;
   transport;
   constructor(options) {
     this.options = options;
     this.logger = makeLogger(!!options.debug);
-    this.dsn = parseDsn(options.dsn);
+    this.config = resolveConfig(options);
     this.transport = new Transport({
-      endpoint: this.dsn.ingestEndpoint,
-      key: this.dsn.key,
+      endpoint: this.config.ingestEndpoint,
+      key: this.config.key,
       logger: this.logger,
       flushIntervalMs: options.flushIntervalMs,
       maxBatchSize: options.maxBatchSize
@@ -891,14 +887,14 @@ var ManagerAgent = class {
     this.options = options;
     this.registry = registry2;
     this.logger = makeLogger(options.debug ?? false, "[hobots-manager]");
-    const dsn = parseDsn(options.dsn);
-    this.api = new ManagerApi({ baseUrl: dsn.managerBaseUrl, key: dsn.key, logger: this.logger });
+    const config = resolveConfig(options, "[hobots-manager]");
+    this.api = new ManagerApi({ baseUrl: config.managerBaseUrl, key: config.key, logger: this.logger });
     this.pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
     this.concurrency = Math.min(MAX_CONCURRENCY, Math.max(1, options.concurrency ?? 1));
     this.instanceId = options.instanceId;
     this.taskTimeoutMs = options.taskTimeoutMs;
     this.logFlushIntervalMs = options.logFlushIntervalMs;
-    this.logger.debug("agente configurado", { baseUrl: dsn.managerBaseUrl, projectSlug: dsn.projectSlug });
+    this.logger.debug("agente configurado", { baseUrl: config.managerBaseUrl });
   }
   logger;
   api;
@@ -995,7 +991,7 @@ var ManagerAgent = class {
     if (error instanceof ManagerApiError && error.status === 401) {
       this.consecutiveAuthFailures++;
       if (this.consecutiveAuthFailures === 1 || this.consecutiveAuthFailures % 10 === 0) {
-        this.logger.error("chave rejeitada (401) \u2014 verifique a DSN do projeto em Configura\xE7\xF5es \u2192 Agentes");
+        this.logger.error("chave rejeitada (401) \u2014 verifique o Client Secret do projeto em Configura\xE7\xF5es \u2192 Projetos");
       }
       return Math.max(this.pollIntervalMs, AUTH_FAILURE_INTERVAL_MS);
     }
@@ -1109,11 +1105,11 @@ function init(options) {
   if (options.manager) {
     const managerOptions = options.manager === true ? {} : options.manager;
     agent = new ManagerAgent(
-      { ...managerOptions, dsn: options.dsn, instanceId: options.instanceId, debug: options.debug },
+      { ...managerOptions, clientSecret: options.clientSecret, baseUrl: options.baseUrl, instanceId: options.instanceId, debug: options.debug },
       registry
     );
   }
-  client.logger.debug("inicializado", { endpoint: client.dsn.ingestEndpoint });
+  client.logger.debug("inicializado", { endpoint: client.config.ingestEndpoint });
 }
 function getClient() {
   return client;