@zihin/agent-client 0.1.0

package/dist/http.js

@@ -0,0 +1,281 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_TOTAL_BYTES = exports.DEFAULT_MAX_EVENT_BYTES = exports.DEFAULT_MAX_RETRIES = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_BASE_URL = void 0;
+exports.resolveConfig = resolveConfig;
+exports.endpointLabel = endpointLabel;
+exports.buildHeaders = buildHeaders;
+exports.createDeadline = createDeadline;
+exports.requestBuffered = requestBuffered;
+exports.openStream = openStream;
+exports.parseBody = parseBody;
+const errors_1 = require("./errors");
+const security_1 = require("./security");
+exports.DEFAULT_BASE_URL = 'https://llm.zihin.ai';
+exports.DEFAULT_TIMEOUT_MS = 120_000;
+exports.DEFAULT_MAX_RETRIES = 2;
+exports.DEFAULT_MAX_EVENT_BYTES = 1 * 1024 * 1024; // 1MB por evento/linha SSE
+exports.DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024; // 64MB por stream
+/** Resolve o fetch no momento da chamada (honra injeção e mudanças de globalThis.fetch). */
+function resolveFetch(injected) {
+    const f = injected ?? globalThis.fetch;
+    if (typeof f !== 'function') {
+        throw new errors_1.ZihinAgentError('config', 'Global fetch is unavailable in this runtime.');
+    }
+    return f;
+}
+/** Valida a config e devolve valores efetivos. Lança ZihinAgentError('config') se inválida. */
+function resolveConfig(config) {
+    const keyCheck = (0, security_1.validateApiKeyFormat)(config.apiKey ?? '');
+    if (!keyCheck.valid) {
+        throw new errors_1.ZihinAgentError('config', keyCheck.error || 'Invalid API key.');
+    }
+    const urlCheck = (0, security_1.validateBaseUrl)(config.baseUrl ?? '', {
+        allowCustomDomains: config.allowCustomBaseUrl,
+        allowHttp: config.allowHttp,
+        allowLocalhost: config.allowHttp,
+    });
+    if (!urlCheck.valid) {
+        throw new errors_1.ZihinAgentError('config', urlCheck.error || 'Invalid base URL.');
+    }
+    // Preflight de runtime: sem fetch, dá um erro claro em vez de um TypeError cru rotulado de "network".
+    if (typeof (config.fetch ?? globalThis.fetch) !== 'function') {
+        throw new errors_1.ZihinAgentError('config', 'Global fetch is unavailable in this runtime. Use Node >=18 or pass a `fetch` implementation in the client config.');
+    }
+    return {
+        apiKey: config.apiKey.trim(),
+        baseUrl: urlCheck.sanitizedUrl || exports.DEFAULT_BASE_URL,
+        timeoutMs: config.timeoutMs ?? exports.DEFAULT_TIMEOUT_MS,
+        maxRetries: config.maxRetries ?? exports.DEFAULT_MAX_RETRIES,
+        maxStreamEventBytes: config.maxStreamEventBytes ?? exports.DEFAULT_MAX_EVENT_BYTES,
+        maxStreamTotalBytes: config.maxStreamTotalBytes ?? exports.DEFAULT_MAX_TOTAL_BYTES,
+        fetchImpl: config.fetch,
+        onRetry: config.onRetry,
+    };
+}
+/** Rótulo de endpoint para mensagens de erro/observabilidade: "POST host/path". */
+function endpointLabel(method, url) {
+    try {
+        const u = new URL(url);
+        return `${method} ${u.host}${u.pathname}`;
+    }
+    catch {
+        return method;
+    }
+}
+/** Lê o header Retry-After (segundos ou data HTTP) em ms, com teto. */
+function retryAfterMs(headers, capMs = 30_000) {
+    const raw = headers.get('retry-after');
+    if (!raw)
+        return undefined;
+    const secs = Number(raw);
+    if (Number.isFinite(secs))
+        return Math.min(Math.max(0, secs * 1000), capMs);
+    const when = Date.parse(raw);
+    if (Number.isFinite(when))
+        return Math.min(Math.max(0, when - Date.now()), capMs);
+    return undefined;
+}
+function buildHeaders(apiKey, extra = {}) {
+    return {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        'X-Api-Key': apiKey,
+        ...extra,
+    };
+}
+/** Espera `ms`, mas rejeita com 'aborted' imediatamente se o signal do chamador disparar. */
+function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new errors_1.ZihinAgentError('aborted', 'Request was aborted by the caller.'));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new errors_1.ZihinAgentError('aborted', 'Request was aborted by the caller.'));
+        };
+        const timer = setTimeout(() => {
+            if (signal)
+                signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        if (signal)
+            signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/** Backoff exponencial 1s→10s com jitter (metade fixa + metade aleatória), evita thundering herd. */
+function backoffMs(attempt) {
+    const base = Math.min(1000 * 2 ** attempt, 10_000);
+    return base / 2 + Math.random() * (base / 2);
+}
+/**
+ * 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.
+ */
+function createDeadline(timeoutMs, callerSignal) {
+    const controller = new AbortController();
+    let timedOut = false;
+    let abortedByCaller = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    const onAbort = () => {
+        abortedByCaller = true;
+        controller.abort();
+    };
+    if (callerSignal) {
+        if (callerSignal.aborted)
+            onAbort();
+        else
+            callerSignal.addEventListener('abort', onAbort, { once: true });
+    }
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            clearTimeout(timer);
+            if (callerSignal)
+                callerSignal.removeEventListener('abort', onAbort);
+        },
+        timedOut: () => timedOut,
+        abortedByCaller: () => abortedByCaller,
+    };
+}
+function shouldRetryStatus(status, policy) {
+    if (policy === 'idempotent')
+        return status >= 500 || status === 429;
+    return status === 429 || status === 503; // side-effecting: só "tente depois"
+}
+/**
+ * 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).
+ */
+async function requestBuffered(args) {
+    const endpoint = endpointLabel(args.method, args.url);
+    const doFetch = resolveFetch(args.fetchImpl);
+    let lastError = null;
+    for (let attempt = 0; attempt <= args.maxRetries; attempt++) {
+        const d = createDeadline(args.timeoutMs, args.callerSignal);
+        try {
+            const res = await doFetch(args.url, {
+                method: args.method,
+                headers: args.headers,
+                body: args.body,
+                signal: d.signal,
+                redirect: 'error', // 3xx para outro host vazaria a X-Api-Key
+                cache: 'no-store', // evita cache stale (ex.: polling em Next.js/edge)
+            });
+            if (shouldRetryStatus(res.status, args.policy) && attempt < args.maxRetries) {
+                const wait = retryAfterMs(res.headers) ?? backoffMs(attempt);
+                try {
+                    await res.body?.cancel();
+                }
+                catch {
+                    /* ignore */
+                }
+                d.dispose();
+                args.onRetry?.({ endpoint, attempt: attempt + 1, delayMs: wait, reason: 'status', status: res.status });
+                await delay(wait, args.callerSignal);
+                continue;
+            }
+            const text = await res.text(); // dentro do deadline
+            d.dispose();
+            return { status: res.status, ok: res.ok, text, endpoint, attempts: attempt + 1 };
+        }
+        catch (err) {
+            d.dispose();
+            const meta = { endpoint, attempts: attempt + 1 };
+            if (d.timedOut())
+                throw new errors_1.ZihinAgentError('timeout', `Request timed out after ${args.timeoutMs}ms.`, meta);
+            if (d.abortedByCaller())
+                throw new errors_1.ZihinAgentError('aborted', 'Request was aborted by the caller.', meta);
+            lastError = (0, errors_1.errorFromThrow)(err, args.timeoutMs, meta);
+            // S1: erro de rede só é retentável em método idempotente.
+            const canRetry = args.policy === 'idempotent' && lastError.retryable && attempt < args.maxRetries;
+            if (!canRetry)
+                throw lastError;
+            const wait = backoffMs(attempt);
+            args.onRetry?.({ endpoint, attempt: attempt + 1, delayMs: wait, reason: 'network' });
+            await delay(wait, args.callerSignal);
+        }
+    }
+    throw lastError ?? new errors_1.ZihinAgentError('unknown', 'Max retries exceeded.', { endpoint });
+}
+/**
+ * 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).
+ */
+async function openStream(args) {
+    const endpoint = endpointLabel('POST', args.url);
+    const doFetch = resolveFetch(args.fetchImpl);
+    for (let attempt = 0; attempt <= args.maxRetries; attempt++) {
+        const d = createDeadline(args.timeoutMs, args.callerSignal);
+        try {
+            const response = await doFetch(args.url, {
+                method: 'POST',
+                headers: { ...args.headers, Accept: 'text/event-stream' },
+                body: args.body,
+                signal: d.signal,
+                redirect: 'error',
+                cache: 'no-store',
+            });
+            if (shouldRetryStatus(response.status, 'side-effecting') && attempt < args.maxRetries) {
+                const wait = retryAfterMs(response.headers) ?? backoffMs(attempt);
+                try {
+                    await response.body?.cancel();
+                }
+                catch {
+                    /* ignore */
+                }
+                d.dispose();
+                args.onRetry?.({
+                    endpoint,
+                    attempt: attempt + 1,
+                    delayMs: wait,
+                    reason: 'status',
+                    status: response.status,
+                });
+                await delay(wait, args.callerSignal);
+                continue;
+            }
+            return { response, deadline: d, endpoint }; // NÃO dá dispose: o stream ainda vai ser lido
+        }
+        catch (err) {
+            d.dispose();
+            const meta = { endpoint, attempts: attempt + 1 };
+            if (d.timedOut())
+                throw new errors_1.ZihinAgentError('timeout', `Request timed out after ${args.timeoutMs}ms.`, meta);
+            if (d.abortedByCaller())
+                throw new errors_1.ZihinAgentError('aborted', 'Request was aborted by the caller.', meta);
+            // S1: POST não retenta em erro de rede.
+            throw (0, errors_1.errorFromThrow)(err, args.timeoutMs, meta);
+        }
+    }
+    throw new errors_1.ZihinAgentError('unknown', 'Max retries exceeded.', { endpoint });
+}
+/** Faz parse seguro de um corpo (JSON quando possível, senão {message}). */
+function parseBody(text) {
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { message: text };
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @zihin/agent-client — núcleo de invocação de agente Zihin.ai.
+ *
+ * Padrão híbrido (verificado contra o BE em 2026-06-28):
+ *   • Direto:   client.invokeAgent / client.streamAgent  → POST /api/v2/agents/:id/stream
+ *   • Triggers: client.createTrigger / dispatchAgent / getExecution  → async + callback
+ *   • Auxiliar: client.listAgents  → GET /api/v2/agents (dropdown)
+ *
+ * Zero dependência de plataforma (n8n / Paperclip). Segurança reusada de `security.ts`.
+ *
+ * @example
+ *   import { createClient } from '@zihin/agent-client';
+ *   const zihin = createClient({ apiKey: process.env.ZIHIN_API_KEY! });
+ *   const res = await zihin.invokeAgent({ agentId, message: 'Olá' });
+ *   console.log(res.content, res.usage, res.sessionId);
+ */
+export { ZihinAgentClient, createClient } from './client';
+export { ZihinAgentError, type ZihinErrorKind } from './errors';
+export type { AgentSummary } from './agents';
+export type { AgentResult, AgentStreamChunk, Attachment, AttachmentType, CreateTriggerParams, DeleteTriggerParams, DispatchAgentParams, DispatchResult, ExecutionStatus, FindOrCreateResult, GetExecutionParams, GetTriggerParams, InvokeAgentParams, InvokeOptions, ListTriggersParams, RetryInfo, Source, TriggerInfo, TriggerMode, TriggerRef, Usage, ZihinClientConfig, } from './types';
+export { validateApiKeyFormat, validateBaseUrl, validatePromptSize, sanitizeApiError, signRequest, DEFAULT_LIMITS, } from './security';

package/dist/index.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * @zihin/agent-client — núcleo de invocação de agente Zihin.ai.
+ *
+ * Padrão híbrido (verificado contra o BE em 2026-06-28):
+ *   • Direto:   client.invokeAgent / client.streamAgent  → POST /api/v2/agents/:id/stream
+ *   • Triggers: client.createTrigger / dispatchAgent / getExecution  → async + callback
+ *   • Auxiliar: client.listAgents  → GET /api/v2/agents (dropdown)
+ *
+ * Zero dependência de plataforma (n8n / Paperclip). Segurança reusada de `security.ts`.
+ *
+ * @example
+ *   import { createClient } from '@zihin/agent-client';
+ *   const zihin = createClient({ apiKey: process.env.ZIHIN_API_KEY! });
+ *   const res = await zihin.invokeAgent({ agentId, message: 'Olá' });
+ *   console.log(res.content, res.usage, res.sessionId);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LIMITS = exports.signRequest = exports.sanitizeApiError = exports.validatePromptSize = exports.validateBaseUrl = exports.validateApiKeyFormat = exports.ZihinAgentError = exports.createClient = exports.ZihinAgentClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "ZihinAgentClient", { enumerable: true, get: function () { return client_1.ZihinAgentClient; } });
+Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "ZihinAgentError", { enumerable: true, get: function () { return errors_1.ZihinAgentError; } });
+// Primitivas de segurança reutilizáveis pelos shells.
+var security_1 = require("./security");
+Object.defineProperty(exports, "validateApiKeyFormat", { enumerable: true, get: function () { return security_1.validateApiKeyFormat; } });
+Object.defineProperty(exports, "validateBaseUrl", { enumerable: true, get: function () { return security_1.validateBaseUrl; } });
+Object.defineProperty(exports, "validatePromptSize", { enumerable: true, get: function () { return security_1.validatePromptSize; } });
+Object.defineProperty(exports, "sanitizeApiError", { enumerable: true, get: function () { return security_1.sanitizeApiError; } });
+Object.defineProperty(exports, "signRequest", { enumerable: true, get: function () { return security_1.signRequest; } });
+Object.defineProperty(exports, "DEFAULT_LIMITS", { enumerable: true, get: function () { return security_1.DEFAULT_LIMITS; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAEH,mCAA0D;AAAjD,0GAAA,gBAAgB,OAAA;AAAE,sGAAA,YAAY,OAAA;AACvC,mCAAgE;AAAvD,yGAAA,eAAe,OAAA;AA2BxB,sDAAsD;AACtD,uCAOoB;AANnB,gHAAA,oBAAoB,OAAA;AACpB,2GAAA,eAAe,OAAA;AACf,8GAAA,kBAAkB,OAAA;AAClB,4GAAA,gBAAgB,OAAA;AAChB,uGAAA,WAAW,OAAA;AACX,0GAAA,cAAc,OAAA"}

package/dist/internal.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Helpers internos compartilhados (parsing defensivo de respostas do BE).
+ * Centralizados aqui para não divergir entre invoke/triggers/agents.
+ *
+ * @module internal
+ */
+import type { Usage } from './types';
+/** Tamanho em bytes UTF-8 de uma string, portável (sem depender de Node Buffer). */
+export declare function utf8Len(s: string): number;
+export declare function rec(x: unknown): Record<string, unknown>;
+export declare function str(x: unknown): string | undefined;
+export declare function num(x: unknown): number | undefined;
+export declare function parseUsage(usageRaw: unknown): Usage | undefined;

package/dist/internal.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Helpers internos compartilhados (parsing defensivo de respostas do BE).
+ * Centralizados aqui para não divergir entre invoke/triggers/agents.
+ *
+ * @module internal
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.utf8Len = utf8Len;
+exports.rec = rec;
+exports.str = str;
+exports.num = num;
+exports.parseUsage = parseUsage;
+// TextEncoder existe em Node, edge e browser (ao contrário de Buffer, que é só Node).
+const _utf8 = new TextEncoder();
+/** Tamanho em bytes UTF-8 de uma string, portável (sem depender de Node Buffer). */
+function utf8Len(s) {
+    return _utf8.encode(s).length;
+}
+function rec(x) {
+    return x && typeof x === 'object' ? x : {};
+}
+function str(x) {
+    return typeof x === 'string' ? x : undefined;
+}
+function num(x) {
+    return typeof x === 'number' ? x : undefined;
+}
+function parseUsage(usageRaw) {
+    const u = rec(usageRaw);
+    if (Object.keys(u).length === 0)
+        return undefined;
+    return {
+        inputTokens: num(u.input_tokens) ?? num(u.prompt_tokens),
+        outputTokens: num(u.output_tokens) ?? num(u.completion_tokens),
+        totalTokens: num(u.total_tokens),
+        costUsd: num(u.cost_usd),
+    };
+}
+//# sourceMappingURL=internal.js.map

package/dist/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAQH,0BAEC;AAED,kBAEC;AAED,kBAEC;AAED,kBAEC;AAED,gCASC;AA7BD,sFAAsF;AACtF,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC;AAEhC,oFAAoF;AACpF,SAAgB,OAAO,CAAC,CAAS;IAChC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AAC/B,CAAC;AAED,SAAgB,GAAG,CAAC,CAAU;IAC7B,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,CAA6B,CAAC,CAAC,CAAC,EAAE,CAAC;AACzE,CAAC;AAED,SAAgB,GAAG,CAAC,CAAU;IAC7B,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9C,CAAC;AAED,SAAgB,GAAG,CAAC,CAAU;IAC7B,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9C,CAAC;AAED,SAAgB,UAAU,CAAC,QAAiB;IAC3C,MAAM,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxB,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAClD,OAAO;QACN,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC;QACxD,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,iBAAiB,CAAC;QAC9D,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC;QAChC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;KACxB,CAAC;AACH,CAAC"}

package/dist/invoke.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Caminho A — invocação direta de agente (POST /api/v2/agents/:id/stream).
+ * `streamAgent` emite deltas ao vivo; `invokeAgent` buffeia o stream e consolida
+ * o evento `response` (content/sources/session_id/blocks) com o `metrics` (usage/model).
+ *
+ * @module invoke
+ */
+import { type ResolvedConfig } from './http';
+import type { AgentResult, AgentStreamChunk, InvokeAgentParams } from './types';
+/**
+ * Emite chunks normalizados do agente ao vivo. Para quem quer streaming (UI, logs).
+ * O deadline (timeout + abort do chamador) cobre toda a duração do stream e é liberado no fim.
+ */
+export declare function streamAgent(cfg: ResolvedConfig, params: InvokeAgentParams): AsyncGenerator<AgentStreamChunk>;
+/**
+ * Invoca o agente e retorna o resultado final consolidado. Buffeia o SSE até `response`+`metrics`.
+ */
+export declare function invokeAgent(cfg: ResolvedConfig, params: InvokeAgentParams): Promise<AgentResult>;