@zihin/agent-client 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+# @zihin/agent-client
+
+Núcleo de **invocação de agente** Zihin.ai — o padrão único que n8n, Paperclip e integrações
+futuras usam para acionar agentes hospedados na Zihin. Zero dependência de plataforma.
+
+> Contexto e decisões: `docs/issues/PLANO-padrao-agent-client.md` (issue #16). Contrato verificado
+> contra o BE (`zihin-agent-builder/server-llm`) em 2026-06-28.
+
+## A ideia
+
+Toda entrada externa na Zihin atravessa um **agente** (RBAC, quota, HITL, auditoria, memória) — não
+a call crua de LLM. Este pacote esconde os detalhes de transporte (SSE, triggers) atrás de uma API
+simples, e oferece **dois estilos** de invocação:
+
+| Estilo | Método | Quando usar |
+|---|---|---|
+| **Direto / imediato** | `invokeAgent` / `streamAgent` | espera a resposta (n8n, request/resposta). Zero setup. |
+| **Assíncrono / desacoplado** | `createTrigger` + `dispatchAgent` (+ `getExecution`) | dispara e recebe via callback (serverless, execução longa). |
+
+## Instalação
+
+```bash
+npm install @zihin/agent-client
+```
+
+Requer Node >= 18 (usa `fetch`/`ReadableStream` globais).
+
+## Uso — caminho direto
+
+```ts
+import { createClient } from '@zihin/agent-client';
+
+const zihin = createClient({ apiKey: process.env.ZIHIN_API_KEY! }); // zhn_live_*
+
+// Imediato — buffeia o SSE e consolida response + metrics
+const res = await zihin.invokeAgent({
+  agentId: 'uuid-do-agente',
+  message: 'Qual a previsão de vendas?',
+  sessionId: previousSessionId, // opcional, continua a conversa
+});
+console.log(res.content);     // texto final
+console.log(res.usage);       // { inputTokens, outputTokens, totalTokens, costUsd }
+console.log(res.sessionId);   // guarde para a próxima mensagem
+console.log(res.model);       // modelo efetivo
+
+// Ao vivo — deltas conforme o agente pensa/usa tools/responde
+for await (const chunk of zihin.streamAgent({ agentId, message: 'Olá' })) {
+  if (chunk.type === 'token') process.stdout.write(chunk.content);
+  if (chunk.type === 'tool') console.log('tool:', chunk.tool);
+}
+```
+
+## Uso — caminho assíncrono (triggers)
+
+```ts
+// 1x: provisiona (ou reaproveita) um webhook ligado ao agente.
+// PREFIRA findOrCreateTrigger — o BE não tem unicidade de nome, então createTrigger
+// repetido cria duplicatas. findOrCreate reusa por (agente + nome).
+const { triggerId, webhookUrl, created } = await zihin.findOrCreateTrigger({
+  agentId,
+  name: 'Integração X',
+  mode: 'async',
+  callbackUrl: 'https://minha-plataforma.com/webhook/zihin',
+});
+
+// N vezes: dispara (responde 202 na hora; resultado chega no callback)
+const { accepted, executionId } = await zihin.dispatchAgent({
+  triggerId,
+  payload: { message: 'Processa este pedido' },
+});
+
+// opcional: polling do resultado em vez de callback
+const exec = await zihin.getExecution({ triggerId, executionId });
+```
+
+> O modo `sync` do trigger (`mode: 'sync'`) responde 200 + JSON na hora (`dispatchResult.agentResponse`).
+
+### Ciclo de vida do trigger
+
+```ts
+await zihin.listTriggers({ agentId });        // lista (filtros: agentId/triggerType/enabledOnly)
+await zihin.getTrigger({ triggerId });        // detalhe (inclui webhookUrl)
+await zihin.deleteTrigger({ triggerId });     // remove (requer key admin/owner; editor → 403)
+```
+
+## Dropdown de agentes
+
+```ts
+const agents = await zihin.listAgents(); // GET /api/v2/agents
+// [{ id, name, commercialName, status, toolsCount, ... }]
+```
+
+## Permissões da API key
+
+- `invokeAgent` / `streamAgent` — qualquer role.
+- `createTrigger` / `getExecution` — exigem key **admin** ou **editor** (default é admin). Keys
+  `member` recebem `ZihinAgentError` com `kind: 'auth'`.
+
+## Erros
+
+Todos os erros são `ZihinAgentError` com `kind` (`config | auth | not_found | rate_limit | timeout |
+aborted | server | network | protocol | unknown`), `status`, `code`, `retryable` e — para depurar em
+produção externa — `endpoint` (`"POST host/path"`), `attempts` e **`requestId`** (handle do BE para o
+suporte correlacionar). Erros de rede carregam a causa-raiz (`ECONNREFUSED`/`ENOTFOUND`/TLS…) na
+mensagem. As mensagens redigem **só segredos** (key/Bearer/stack) — `request_id`/`trace_id` são
+preservados. Cancele com `AbortSignal` via `params.signal`.
+
+## Robustez (timeout / retry / limites)
+
+- **Timeout cobre tudo** — headers e o corpo/stream inteiro. `timeoutMs` (default 120s, igual ao cap
+  do BE) é o tempo máximo total da chamada; `AbortSignal` do chamador funciona durante todo o stream.
+- **Retry sem duplicar efeito** — GET (idempotente) retenta em rede/429/5xx; POST com efeito
+  (`invokeAgent`/`dispatchAgent`/`createTrigger`) retenta **só em 429/503** e **nunca em erro de
+  rede** (o request pode ter sido processado). Backoff exponencial 1s→10s com jitter.
+- **Anti-DoS de memória** — limites de stream `maxStreamEventBytes` (1MB) e `maxStreamTotalBytes`
+  (64MB); estourar aborta com `protocol`. Configuráveis no `createClient`.
+- **`includeRaw`** — por padrão `invokeAgent` não retém os eventos brutos (`raw: []`) para economizar
+  memória; passe `includeRaw: true` para recebê-los. `streamAgent` sempre entrega os chunks ao vivo.
+- **Segurança de transporte** — `redirect: 'error'` (um 3xx para outro host vazaria a key) e
+  `cache: 'no-store'` (evita polling stale em Next.js/edge) em toda requisição. `Retry-After` do
+  servidor é respeitado em 429/503.
+
+### Observabilidade e portabilidade
+
+- **Hooks** (opt-in, sem `console`): `onRetry(info)` (a cada retentativa, com `endpoint`/`attempt`/
+  `delayMs`/`reason`/`status`) e `onError(err)`.
+- **`fetch` injetável** — `fetch?` na config; por padrão usa `globalThis.fetch` (Node ≥18). Um
+  preflight dá erro `config` claro se não houver fetch.
+- **Portável** — sem `Buffer`; `node:crypto` só é carregado se você usar `signRequest`. Roda em Node;
+  para edge/serverless, injete `fetch` se necessário.
+
+```ts
+const zihin = createClient({
+  apiKey,
+  timeoutMs: 60_000,
+  maxRetries: 2,
+  maxStreamEventBytes: 2 * 1024 * 1024,
+  onRetry: (info) => myLogger.warn('zihin retry', info),
+  // fetch: customFetch,  // ambientes sem fetch global
+});
+```
+
+> SSRF: a validação de base/callback URL é por nome de host. Com `allowCustomBaseUrl: true` um host
+> que resolva para IP privado (DNS rebinding) passa — mantenha o whitelist em ambiente sensível.
+
+## Segurança
+
+Reusa as primitivas de `security.ts`: validação SSRF da base URL (whitelist Zihin por padrão; libere
+com `allowCustomBaseUrl`), limites de payload, sanitização de erro, validação de formato de key e HMAC
+opcional.
+
+## Dev
+
+```bash
+npm run build && npm test   # smoke test offline (mocka fetch), sem rede
+```

package/dist/agents.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Listagem de agentes do tenant (GET /api/v2/agents). Alimenta o dropdown do nó n8n (#17)
+ * e o select de `agentId` no Paperclip (#20). Aceita key `zhn_live_*` (agents:read em todos os roles).
+ *
+ * @module agents
+ */
+import { type ResolvedConfig } from './http';
+export interface AgentSummary {
+    id: string;
+    name?: string;
+    commercialName?: string;
+    bio?: string;
+    type?: string;
+    status?: string;
+    tags?: string[];
+    toolsCount?: number;
+}
+/** Lista os agentes acessíveis pelo tenant da key. */
+export declare function listAgents(cfg: ResolvedConfig, opts?: {
+    signal?: AbortSignal;
+}): Promise<AgentSummary[]>;

package/dist/agents.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Listagem de agentes do tenant (GET /api/v2/agents). Alimenta o dropdown do nó n8n (#17)
+ * e o select de `agentId` no Paperclip (#20). Aceita key `zhn_live_*` (agents:read em todos os roles).
+ *
+ * @module agents
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listAgents = listAgents;
+const errors_1 = require("./errors");
+const http_1 = require("./http");
+const internal_1 = require("./internal");
+/** Lista os agentes acessíveis pelo tenant da key. */
+async function listAgents(cfg, opts = {}) {
+    const res = await (0, http_1.requestBuffered)({
+        method: 'GET',
+        url: `${cfg.baseUrl}/api/v2/agents`,
+        headers: (0, http_1.buildHeaders)(cfg.apiKey),
+        timeoutMs: cfg.timeoutMs,
+        maxRetries: cfg.maxRetries,
+        policy: 'idempotent',
+        callerSignal: opts.signal,
+        fetchImpl: cfg.fetchImpl,
+        onRetry: cfg.onRetry,
+    });
+    if (!res.ok) {
+        throw (0, errors_1.errorFromResponse)(res.status, (0, http_1.parseBody)(res.text), { endpoint: res.endpoint, attempts: res.attempts });
+    }
+    let json;
+    try {
+        json = JSON.parse(res.text);
+    }
+    catch {
+        throw new errors_1.ZihinAgentError('protocol', 'Expected JSON from GET /api/v2/agents.');
+    }
+    const data = (0, internal_1.rec)(json).data;
+    const list = Array.isArray(data) ? data : [];
+    return list.map((item) => {
+        const a = (0, internal_1.rec)(item);
+        return {
+            id: (0, internal_1.str)(a.id) ?? '',
+            name: (0, internal_1.str)(a.name),
+            commercialName: (0, internal_1.str)(a.commercial_name),
+            bio: (0, internal_1.str)(a.bio),
+            type: (0, internal_1.str)(a.type),
+            status: (0, internal_1.str)(a.status),
+            tags: Array.isArray(a.tags) ? a.tags.filter((t) => typeof t === 'string') : undefined,
+            toolsCount: typeof a.tools_count === 'number' ? a.tools_count : undefined,
+        };
+    });
+}
+//# sourceMappingURL=agents.js.map

package/dist/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAkBH,gCAyCC;AAzDD,qCAA8D;AAC9D,iCAAuF;AACvF,yCAAsC;AAatC,sDAAsD;AAC/C,KAAK,UAAU,UAAU,CAC/B,GAAmB,EACnB,OAAiC,EAAE;IAEnC,MAAM,GAAG,GAAG,MAAM,IAAA,sBAAe,EAAC;QACjC,MAAM,EAAE,KAAK;QACb,GAAG,EAAE,GAAG,GAAG,CAAC,OAAO,gBAAgB;QACnC,OAAO,EAAE,IAAA,mBAAY,EAAC,GAAG,CAAC,MAAM,CAAC;QACjC,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,MAAM,EAAE,YAAY;QACpB,YAAY,EAAE,IAAI,CAAC,MAAM;QACzB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,OAAO,EAAE,GAAG,CAAC,OAAO;KACpB,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACb,MAAM,IAAA,0BAAiB,EAAC,GAAG,CAAC,MAAM,EAAE,IAAA,gBAAS,EAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC9G,CAAC;IAED,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACJ,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACR,MAAM,IAAI,wBAAe,CAAC,UAAU,EAAE,wCAAwC,CAAC,CAAC;IACjF,CAAC;IAED,MAAM,IAAI,GAAG,IAAA,cAAG,EAAC,IAAI,CAAC,CAAC,IAAI,CAAC;IAC5B,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,MAAM,CAAC,GAAG,IAAA,cAAG,EAAC,IAAI,CAAC,CAAC;QACpB,OAAO;YACN,EAAE,EAAE,IAAA,cAAG,EAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE;YACnB,IAAI,EAAE,IAAA,cAAG,EAAC,CAAC,CAAC,IAAI,CAAC;YACjB,cAAc,EAAE,IAAA,cAAG,EAAC,CAAC,CAAC,eAAe,CAAC;YACtC,GAAG,EAAE,IAAA,cAAG,EAAC,CAAC,CAAC,GAAG,CAAC;YACf,IAAI,EAAE,IAAA,cAAG,EAAC,CAAC,CAAC,IAAI,CAAC;YACjB,MAAM,EAAE,IAAA,cAAG,EAAC,CAAC,CAAC,MAAM,CAAC;YACrB,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAc,CAAC,CAAC,CAAC,SAAS;YACnG,UAAU,EAAE,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;SACzE,CAAC;IACH,CAAC,CAAC,CAAC;AACJ,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ZihinAgentClient — fachada do núcleo. Carrega a config uma vez (auth, baseUrl, timeout,
+ * retries) e expõe os dois caminhos do padrão híbrido:
+ *   • Direto:    invokeAgent / streamAgent  (POST /stream, SSE bufferizado)
+ *   • Triggers:  createTrigger / dispatchAgent / getExecution  (async + callback)
+ *   • Auxiliar:  listAgents  (dropdown de agentes)
+ *
+ * @module client
+ */
+import { type AgentSummary } from './agents';
+import type { AgentResult, AgentStreamChunk, CreateTriggerParams, DeleteTriggerParams, DispatchAgentParams, DispatchResult, ExecutionStatus, FindOrCreateResult, GetExecutionParams, GetTriggerParams, InvokeAgentParams, ListTriggersParams, TriggerInfo, TriggerRef, ZihinClientConfig } from './types';
+export declare class ZihinAgentClient {
+    private readonly cfg;
+    constructor(config: ZihinClientConfig);
+    /** Base URL efetiva (após validação SSRF). */
+    get baseUrl(): string;
+    /** Invoca o agente e retorna o resultado final consolidado (response + metrics). */
+    invokeAgent(params: InvokeAgentParams): Promise<AgentResult>;
+    /** Emite deltas ao vivo do agente (async iterator). */
+    streamAgent(params: InvokeAgentParams): AsyncGenerator<AgentStreamChunk>;
+    /** Provisiona (1x) um trigger de webhook ligado a um agente. */
+    createTrigger(params: CreateTriggerParams): Promise<TriggerRef>;
+    /** Reaproveita (por agente+nome) ou cria um trigger — evita duplicação. */
+    findOrCreateTrigger(params: CreateTriggerParams): Promise<FindOrCreateResult>;
+    /** Lista os triggers do tenant (filtros opcionais). */
+    listTriggers(params?: ListTriggersParams): Promise<TriggerInfo[]>;
+    /** Obtém um trigger pelo id (inclui webhookUrl). */
+    getTrigger(params: GetTriggerParams): Promise<TriggerInfo>;
+    /** Remove um trigger (requer key admin/owner). */
+    deleteTrigger(params: DeleteTriggerParams): Promise<{
+        deleted: boolean;
+    }>;
+    /** Dispara um trigger: 202 (async) ou JSON imediato (sync). */
+    dispatchAgent(params: DispatchAgentParams): Promise<DispatchResult>;
+    /** Consulta o resultado de uma execução disparada por trigger (polling). */
+    getExecution(params: GetExecutionParams): Promise<ExecutionStatus>;
+    /** Lista os agentes do tenant (dropdown). */
+    listAgents(opts?: {
+        signal?: AbortSignal;
+    }): Promise<AgentSummary[]>;
+}
+/** Açúcar: cria um cliente a partir da config. */
+export declare function createClient(config: ZihinClientConfig): ZihinAgentClient;

package/dist/client.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * ZihinAgentClient — fachada do núcleo. Carrega a config uma vez (auth, baseUrl, timeout,
+ * retries) e expõe os dois caminhos do padrão híbrido:
+ *   • Direto:    invokeAgent / streamAgent  (POST /stream, SSE bufferizado)
+ *   • Triggers:  createTrigger / dispatchAgent / getExecution  (async + callback)
+ *   • Auxiliar:  listAgents  (dropdown de agentes)
+ *
+ * @module client
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZihinAgentClient = void 0;
+exports.createClient = createClient;
+const agents_1 = require("./agents");
+const http_1 = require("./http");
+const invoke_1 = require("./invoke");
+const triggers_1 = require("./triggers");
+class ZihinAgentClient {
+    constructor(config) {
+        this.cfg = (0, http_1.resolveConfig)(config);
+    }
+    /** Base URL efetiva (após validação SSRF). */
+    get baseUrl() {
+        return this.cfg.baseUrl;
+    }
+    // ---- Caminho A: direto (SSE) ----
+    /** Invoca o agente e retorna o resultado final consolidado (response + metrics). */
+    invokeAgent(params) {
+        return (0, invoke_1.invokeAgent)(this.cfg, params);
+    }
+    /** Emite deltas ao vivo do agente (async iterator). */
+    streamAgent(params) {
+        return (0, invoke_1.streamAgent)(this.cfg, params);
+    }
+    // ---- Caminho B: triggers (async/callback) ----
+    /** Provisiona (1x) um trigger de webhook ligado a um agente. */
+    createTrigger(params) {
+        return (0, triggers_1.createTrigger)(this.cfg, params);
+    }
+    /** Reaproveita (por agente+nome) ou cria um trigger — evita duplicação. */
+    findOrCreateTrigger(params) {
+        return (0, triggers_1.findOrCreateTrigger)(this.cfg, params);
+    }
+    /** Lista os triggers do tenant (filtros opcionais). */
+    listTriggers(params = {}) {
+        return (0, triggers_1.listTriggers)(this.cfg, params);
+    }
+    /** Obtém um trigger pelo id (inclui webhookUrl). */
+    getTrigger(params) {
+        return (0, triggers_1.getTrigger)(this.cfg, params);
+    }
+    /** Remove um trigger (requer key admin/owner). */
+    deleteTrigger(params) {
+        return (0, triggers_1.deleteTrigger)(this.cfg, params);
+    }
+    /** Dispara um trigger: 202 (async) ou JSON imediato (sync). */
+    dispatchAgent(params) {
+        return (0, triggers_1.dispatchAgent)(this.cfg, params);
+    }
+    /** Consulta o resultado de uma execução disparada por trigger (polling). */
+    getExecution(params) {
+        return (0, triggers_1.getExecution)(this.cfg, params);
+    }
+    // ---- Auxiliar ----
+    /** Lista os agentes do tenant (dropdown). */
+    listAgents(opts = {}) {
+        return (0, agents_1.listAgents)(this.cfg, opts);
+    }
+}
+exports.ZihinAgentClient = ZihinAgentClient;
+/** Açúcar: cria um cliente a partir da config. */
+function createClient(config) {
+    return new ZihinAgentClient(config);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAsGH,oCAEC;AAtGD,qCAAyD;AACzD,iCAA4D;AAC5D,qCAAoD;AACpD,yCAQoB;AAmBpB,MAAa,gBAAgB;IAG5B,YAAY,MAAyB;QACpC,IAAI,CAAC,GAAG,GAAG,IAAA,oBAAa,EAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,8CAA8C;IAC9C,IAAI,OAAO;QACV,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;IACzB,CAAC;IAED,oCAAoC;IAEpC,oFAAoF;IACpF,WAAW,CAAC,MAAyB;QACpC,OAAO,IAAA,oBAAW,EAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,uDAAuD;IACvD,WAAW,CAAC,MAAyB;QACpC,OAAO,IAAA,oBAAW,EAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,iDAAiD;IAEjD,gEAAgE;IAChE,aAAa,CAAC,MAA2B;QACxC,OAAO,IAAA,wBAAa,EAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,2EAA2E;IAC3E,mBAAmB,CAAC,MAA2B;QAC9C,OAAO,IAAA,8BAAmB,EAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED,uDAAuD;IACvD,YAAY,CAAC,SAA6B,EAAE;QAC3C,OAAO,IAAA,uBAAY,EAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,oDAAoD;IACpD,UAAU,CAAC,MAAwB;QAClC,OAAO,IAAA,qBAAU,EAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAED,kDAAkD;IAClD,aAAa,CAAC,MAA2B;QACxC,OAAO,IAAA,wBAAa,EAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,+DAA+D;IAC/D,aAAa,CAAC,MAA2B;QACxC,OAAO,IAAA,wBAAa,EAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,4EAA4E;IAC5E,YAAY,CAAC,MAA0B;QACtC,OAAO,IAAA,uBAAY,EAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,qBAAqB;IAErB,6CAA6C;IAC7C,UAAU,CAAC,OAAiC,EAAE;QAC7C,OAAO,IAAA,mBAAU,EAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;CACD;AAnED,4CAmEC;AAED,kDAAkD;AAClD,SAAgB,YAAY,CAAC,MAAyB;IACrD,OAAO,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Erros do @zihin/agent-client — sanitizados (sem vazar key/Bearer/stack), mas COMPLETOS:
+ * carregam endpoint, nº de tentativas e request_id do BE para depuração em produção externa.
+ *
+ * @module errors
+ */
+export type ZihinErrorKind = 'config' | 'auth' | 'not_found' | 'rate_limit' | 'timeout' | 'aborted' | 'server' | 'network' | 'protocol' | 'unknown';
+/** Contexto opcional anexado a um erro para correlação/depuração. */
+export interface ErrorMeta {
+    /** Ex.: "POST llm.zihin.ai/api/v2/agents/abc/stream". */
+    endpoint?: string;
+    /** Número de tentativas feitas antes de falhar. */
+    attempts?: number;
+}
+export interface ZihinErrorOptions extends ErrorMeta {
+    status?: number;
+    code?: string;
+    retryable?: boolean;
+    /** request_id do BE (NÃO é segredo) — handle para o suporte correlacionar nos logs. */
+    requestId?: string;
+}
+export declare class ZihinAgentError extends Error {
+    readonly kind: ZihinErrorKind;
+    readonly status?: number;
+    readonly code?: string;
+    readonly retryable: boolean;
+    readonly requestId?: string;
+    readonly attempts?: number;
+    readonly endpoint?: string;
+    constructor(kind: ZihinErrorKind, message: string, opts?: ZihinErrorOptions);
+}
+/** Mapeia um status HTTP + corpo (já parseado) para um ZihinAgentError completo. */
+export declare function errorFromResponse(status: number, body: unknown, meta?: ErrorMeta): ZihinAgentError;
+/** Normaliza qualquer throw (network/abort/timeout) para ZihinAgentError, com a causa-raiz. */
+export declare function errorFromThrow(err: unknown, timeoutMs?: number, meta?: ErrorMeta): ZihinAgentError;

package/dist/errors.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Erros do @zihin/agent-client — sanitizados (sem vazar key/Bearer/stack), mas COMPLETOS:
+ * carregam endpoint, nº de tentativas e request_id do BE para depuração em produção externa.
+ *
+ * @module errors
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZihinAgentError = void 0;
+exports.errorFromResponse = errorFromResponse;
+exports.errorFromThrow = errorFromThrow;
+const internal_1 = require("./internal");
+const security_1 = require("./security");
+class ZihinAgentError extends Error {
+    constructor(kind, message, opts = {}) {
+        super(buildMessage(message, opts));
+        this.name = 'ZihinAgentError';
+        this.kind = kind;
+        this.status = opts.status;
+        this.code = opts.code;
+        this.requestId = opts.requestId;
+        this.attempts = opts.attempts;
+        this.endpoint = opts.endpoint;
+        this.retryable =
+            opts.retryable ?? (kind === 'rate_limit' || kind === 'server' || kind === 'network');
+        // Mantém a cadeia de protótipo correta ao transpilar para ES5/ES2021.
+        Object.setPrototypeOf(this, ZihinAgentError.prototype);
+    }
+}
+exports.ZihinAgentError = ZihinAgentError;
+/** Compõe uma mensagem completa: base + endpoint + tentativas + request_id. */
+function buildMessage(base, opts) {
+    let s = base;
+    if (opts.endpoint)
+        s += ` [${opts.endpoint}]`;
+    if (opts.attempts && opts.attempts > 1)
+        s += ` (after ${opts.attempts} attempts)`;
+    if (opts.requestId)
+        s += ` (request_id: ${opts.requestId})`;
+    return s;
+}
+function extractRequestId(body) {
+    const b = (0, internal_1.rec)(body);
+    return (0, internal_1.str)(b.request_id) ?? (0, internal_1.str)(b.requestId) ?? (0, internal_1.str)((0, internal_1.rec)(b.error).request_id);
+}
+/** Mapeia um status HTTP + corpo (já parseado) para um ZihinAgentError completo. */
+function errorFromResponse(status, body, meta = {}) {
+    const sanitized = (0, security_1.sanitizeApiError)(body);
+    const message = sanitized.message;
+    const code = sanitized.code;
+    const base = { status, code, requestId: extractRequestId(body), ...meta };
+    if (status === 401)
+        return new ZihinAgentError('auth', message || 'Authentication failed.', base);
+    if (status === 403)
+        return new ZihinAgentError('auth', message ||
+            'This API key lacks permission. Use an admin/editor key (member keys cannot create triggers or read telemetry).', base);
+    if (status === 404)
+        return new ZihinAgentError('not_found', message || 'Resource not found.', base);
+    if (status === 429)
+        return new ZihinAgentError('rate_limit', message || 'Rate limit exceeded.', { ...base, retryable: true });
+    if (status >= 500)
+        return new ZihinAgentError('server', message || `Server error (${status}).`, { ...base, retryable: true });
+    return new ZihinAgentError('unknown', message || `Request failed (${status}).`, base);
+}
+// Códigos de rede permanentes (não adianta retentar): DNS e TLS.
+const NON_RETRYABLE_NET = /^(ENOTFOUND|EAI_AGAIN|CERT_|ERR_TLS|UNABLE_TO_VERIFY|DEPTH_ZERO)/;
+/** Normaliza qualquer throw (network/abort/timeout) para ZihinAgentError, com a causa-raiz. */
+function errorFromThrow(err, timeoutMs, meta = {}) {
+    if (err instanceof ZihinAgentError)
+        return err;
+    const name = err?.name;
+    if (name === 'TimeoutError') {
+        return new ZihinAgentError('timeout', `Request timed out after ${timeoutMs ?? '?'}ms.`, {
+            ...meta,
+            retryable: false,
+        });
+    }
+    if (name === 'AbortError') {
+        return new ZihinAgentError('aborted', 'Request was aborted by the caller.', { ...meta, retryable: false });
+    }
+    // Erros de fetch escondem a causa-raiz em err.cause.code (ENOTFOUND/ECONNREFUSED/TLS...).
+    const cause = err?.cause;
+    const causeCode = cause?.code;
+    const sanitized = (0, security_1.sanitizeApiError)(err);
+    const detail = causeCode || sanitized.message || 'Network error';
+    const retryable = causeCode ? !NON_RETRYABLE_NET.test(causeCode) : true;
+    return new ZihinAgentError('network', `Network error: ${detail}`, { ...meta, retryable });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/http.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Transporte HTTP do núcleo: resolução/validação de base URL (SSRF), headers de auth,
+ * deadline via AbortController que cobre TODO o request (headers + corpo/stream),
+ * e retry com exponential backoff + jitter.
+ *
+ * Política de retry (evita duplicar efeito colateral):
+ *  - 'idempotent' (GET): retenta em erro de rede, 429 e 5xx.
+ *  - 'side-effecting' (POST: invoke/dispatch/create): retenta SÓ em 429/503 (servidor disse
+ *    "tente depois", sem ter processado). NUNCA em erro de rede — o request pode ter sido
+ *    recebido e processado mesmo com o socket caindo na volta.
+ *
+ * @module http
+ */
+import type { RetryInfo, ZihinClientConfig } from './types';
+export declare const DEFAULT_BASE_URL = "https://llm.zihin.ai";
+export declare const DEFAULT_TIMEOUT_MS = 120000;
+export declare const DEFAULT_MAX_RETRIES = 2;
+export declare const DEFAULT_MAX_EVENT_BYTES: number;
+export declare const DEFAULT_MAX_TOTAL_BYTES: number;
+export type RetryPolicy = 'idempotent' | 'side-effecting';
+export interface ResolvedConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeoutMs: number;
+    maxRetries: number;
+    maxStreamEventBytes: number;
+    maxStreamTotalBytes: number;
+    /** fetch injetado explicitamente; se ausente, usa `globalThis.fetch` no momento da chamada. */
+    fetchImpl?: typeof fetch;
+    onRetry?: (info: RetryInfo) => void;
+}
+/** Valida a config e devolve valores efetivos. Lança ZihinAgentError('config') se inválida. */
+export declare function resolveConfig(config: ZihinClientConfig): ResolvedConfig;
+/** Rótulo de endpoint para mensagens de erro/observabilidade: "POST host/path". */
+export declare function endpointLabel(method: string, url: string): string;
+export declare function buildHeaders(apiKey: string, extra?: Record<string, string>): Record<string, string>;
+export interface Deadline {
+    signal: AbortSignal;
+    dispose: () => void;
+    timedOut: () => boolean;
+    abortedByCaller: () => boolean;
+}
+/**
+ * Cria um deadline que aborta o request após `timeoutMs` (cobre headers E corpo/stream) e
+ * propaga o abort do chamador. Mantenha vivo até o corpo/stream terminar; chame dispose() ao fim.
+ */
+export declare function createDeadline(timeoutMs: number, callerSignal?: AbortSignal): Deadline;
+export interface BufferedResponse {
+    status: number;
+    ok: boolean;
+    text: string;
+    /** "POST host/path" — para o chamador anexar ao erro. */
+    endpoint: string;
+    /** Tentativas feitas (1 = sem retry). */
+    attempts: number;
+}
+export interface BufferedRequest {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+    timeoutMs: number;
+    maxRetries: number;
+    policy: RetryPolicy;
+    callerSignal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+    onRetry?: (info: RetryInfo) => void;
+}
+/**
+ * Executa um request lendo o corpo inteiro dentro do deadline (P1: timeout cobre o download).
+ * Retorna mesmo em não-2xx (o chamador converte via errorFromResponse).
+ */
+export declare function requestBuffered(args: BufferedRequest): Promise<BufferedResponse>;
+export interface StreamHandle {
+    response: Response;
+    /** Mantenha vivo durante a iteração do stream; dispose() ao terminar/abortar. */
+    deadline: Deadline;
+    /** "POST host/path" — para o chamador anexar ao erro no caminho !ok. */
+    endpoint: string;
+}
+export interface StreamRequest {
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+    timeoutMs: number;
+    maxRetries: number;
+    callerSignal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+    onRetry?: (info: RetryInfo) => void;
+}
+/**
+ * Abre um POST SSE. Retenta só pré-stream em 429/503 (POST side-effecting). Em sucesso/4xx
+ * devolve a Response COM o deadline ainda ativo — o consumidor do stream chama deadline.dispose()
+ * ao finalizar (P1: o timeout cobre toda a duração do stream, e o abort do chamador continua ligado).
+ */
+export declare function openStream(args: StreamRequest): Promise<StreamHandle>;
+/** Faz parse seguro de um corpo (JSON quando possível, senão {message}). */
+export declare function parseBody(text: string): unknown;