@zihin/agent-client 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Tipos do contrato externo Zihin — fonte de verdade verificada contra o BE
+ * (zihin-agent-builder/server-llm, 2026-06-28).
+ *
+ * @module types
+ */
+import type { ZihinAgentError } from './errors';
+export interface ZihinClientConfig {
+    /** API key `zhn_live_*` (tenant embutido). Para triggers/telemetria use role admin/editor. */
+    apiKey: string;
+    /** Base URL. Default: https://llm.zihin.ai */
+    baseUrl?: string;
+    /** Timeout por request (ms). Default: 120000 (= limite do /stream no BE). */
+    timeoutMs?: number;
+    /** Máximo de retentativas em 5xx/429/erro de rede. Default: 2. */
+    maxRetries?: number;
+    /** Permite base URL fora da whitelist Zihin (default false → SSRF guard). */
+    allowCustomBaseUrl?: boolean;
+    /** Permite http:// (apenas dev/local). Default false. */
+    allowHttp?: boolean;
+    /** Teto de bytes por evento/linha SSE (anti-DoS de memória). Default: 1MB. */
+    maxStreamEventBytes?: number;
+    /** Teto de bytes do stream inteiro (anti-DoS de memória). Default: 64MB. */
+    maxStreamTotalBytes?: number;
+    /**
+     * Implementação de `fetch` a usar. Default: `globalThis.fetch`. Injete em runtimes onde o
+     * fetch não é global (Node <18 com polyfill, testes, proxies).
+     */
+    fetch?: typeof fetch;
+    /**
+     * Observabilidade (opt-in, sem console): chamado antes de cada retentativa.
+     * Para logar backoff/timeouts/falhas transitórias em produção externa.
+     */
+    onRetry?: (info: RetryInfo) => void;
+    /** Observabilidade: chamado quando uma operação falha em definitivo (após retries). */
+    onError?: (error: ZihinAgentError) => void;
+}
+export interface RetryInfo {
+    /** "POST llm.zihin.ai/api/v2/agents/abc/stream". */
+    endpoint: string;
+    /** Número da tentativa que acabou de falhar (1 = primeira). */
+    attempt: number;
+    /** Atraso até a próxima tentativa, em ms. */
+    delayMs: number;
+    /** Motivo do retry. */
+    reason: 'status' | 'network';
+    /** Status HTTP, quando `reason === 'status'`. */
+    status?: number;
+}
+export type AttachmentType = 'image' | 'audio' | 'document';
+export interface Attachment {
+    url: string;
+    type: AttachmentType;
+}
+export interface InvokeOptions {
+    temperature?: number;
+    maxTokens?: number;
+    /** Timeout específico desta chamada (ms); sobrepõe o do cliente. */
+    timeoutMs?: number;
+    /** Just-in-time tool loading (Sprint 33). */
+    jitMode?: boolean;
+}
+export interface InvokeAgentParams {
+    /** UUID do agente (path :agent_id). */
+    agentId: string;
+    /** Mensagem ao agente. `message` OU `attachments` é obrigatório. */
+    message?: string;
+    /** Anexos multimodais. `message` OU `attachments` é obrigatório. */
+    attachments?: Attachment[];
+    /** Continuidade de conversa (Supabase agent_sessions). */
+    sessionId?: string;
+    options?: InvokeOptions;
+    metadata?: {
+        traceId?: string;
+        correlationId?: string;
+        [k: string]: unknown;
+    };
+    /** Cancelamento externo. */
+    signal?: AbortSignal;
+    /**
+     * Retém todos os eventos SSE brutos em `AgentResult.raw`. Default: false (economiza memória
+     * em runs longos). `streamAgent` sempre entrega os chunks ao vivo, independente disto.
+     */
+    includeRaw?: boolean;
+}
+export interface Usage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    costUsd?: number;
+}
+export interface Source {
+    title?: string;
+    url?: string;
+    [k: string]: unknown;
+}
+/**
+ * Resultado final de `invokeAgent`: consolida o evento SSE `response`
+ * (content/sources/session_id/blocks) com o evento `metrics` (usage/model).
+ */
+export interface AgentResult {
+    content: string;
+    sessionId?: string;
+    model?: string;
+    usage?: Usage;
+    sources?: Source[];
+    /** Cards/blocos estruturados (SPEC B). */
+    blocks?: Array<{
+        type: string;
+        [k: string]: unknown;
+    }>;
+    iterations?: number;
+    executionTimeMs?: number;
+    /** Eventos SSE brutos coletados (para depuração / casos avançados). */
+    raw: AgentStreamChunk[];
+}
+/**
+ * Chunk normalizado emitido por `streamAgent`. Mapeia os tipos de evento SSE do BE:
+ * metadata, status, attachments, phase, thinking, tool, action_proposed, token,
+ * warning, response, metrics.
+ */
+export type AgentStreamChunk = {
+    type: 'metadata';
+    requestId?: string;
+    agentId?: string;
+    sessionId?: string;
+    data: unknown;
+} | {
+    type: 'status';
+    phase?: string;
+    data: unknown;
+} | {
+    type: 'attachments';
+    data: unknown;
+} | {
+    type: 'phase';
+    phase?: string;
+    data: unknown;
+} | {
+    type: 'thinking';
+    thought?: string;
+    data: unknown;
+} | {
+    type: 'tool';
+    tool?: string;
+    callId?: string;
+    success?: boolean;
+    data: unknown;
+} | {
+    type: 'action_proposed';
+    data: unknown;
+} | {
+    type: 'token';
+    content: string;
+    data: unknown;
+} | {
+    type: 'warning';
+    message?: string;
+    data: unknown;
+} | {
+    type: 'response';
+    content: string;
+    sessionId?: string;
+    sources?: Source[];
+    blocks?: Array<{
+        type: string;
+        [k: string]: unknown;
+    }>;
+    data: unknown;
+} | {
+    type: 'metrics';
+    usage?: Usage;
+    model?: string;
+    iterations?: number;
+    executionTimeMs?: number;
+    data: unknown;
+} | {
+    type: 'unknown';
+    event: string;
+    data: unknown;
+};
+export type TriggerMode = 'sync' | 'async';
+export interface CreateTriggerParams {
+    agentId: string;
+    /** Nome legível do trigger. */
+    name: string;
+    /** `async` → 202 + callback; `sync` → 200 + JSON na hora. Default: async. */
+    mode?: TriggerMode;
+    /** URL que o BE chama com o resultado (obrigatório no modo async). */
+    callbackUrl?: string;
+    /** Método HTTP do callback. Default: POST. */
+    callbackMethod?: 'POST' | 'PUT';
+    /** Campo do payload de disparo de onde sai a mensagem do agente. Default: "message". */
+    queryField?: string;
+    /** Auth de disparo aceita. Default: api_key. */
+    dispatchAuth?: 'api_key' | 'signature' | 'none';
+    signal?: AbortSignal;
+}
+export interface TriggerRef {
+    triggerId: string;
+    /** URL completa de disparo: POST {webhookUrl}. */
+    webhookUrl: string;
+}
+/** Resultado de findOrCreateTrigger: o ref + se foi recém-criado ou reaproveitado. */
+export interface FindOrCreateResult extends TriggerRef {
+    created: boolean;
+}
+/** Trigger como listado/obtido do BE. */
+export interface TriggerInfo {
+    id: string;
+    agentId?: string;
+    name?: string;
+    description?: string;
+    triggerType?: string;
+    enabled?: boolean;
+    triggerCount?: number;
+    lastError?: string;
+    /** Presente para triggers do tipo webhook. */
+    webhookUrl?: string;
+}
+export interface ListTriggersParams {
+    /** Filtra por agente. */
+    agentId?: string;
+    /** Filtra por tipo (webhook | db_event | email | schedule). */
+    triggerType?: string;
+    /** Apenas habilitados. */
+    enabledOnly?: boolean;
+    signal?: AbortSignal;
+}
+export interface GetTriggerParams {
+    triggerId: string;
+    signal?: AbortSignal;
+}
+export interface DeleteTriggerParams {
+    triggerId: string;
+    signal?: AbortSignal;
+}
+export interface DispatchAgentParams {
+    triggerId: string;
+    /** Payload entregue ao trigger (a mensagem sai do `queryField` configurado). */
+    payload: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+export interface DispatchResult {
+    /** true quando o BE retorna 202 (async) ou 200 (sync). */
+    accepted: boolean;
+    triggerId?: string;
+    executionId?: string;
+    /** Presente quando o trigger é `sync`: resposta imediata do agente. */
+    agentResponse?: string;
+    usage?: Usage;
+    raw: unknown;
+}
+export interface ExecutionStatus {
+    executionId: string;
+    status: string;
+    startedAt?: string;
+    finishedAt?: string;
+    executionTimeMs?: number;
+    usage?: Usage;
+    result?: string;
+    raw: unknown;
+}
+export interface GetExecutionParams {
+    triggerId: string;
+    executionId: string;
+    signal?: AbortSignal;
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Tipos do contrato externo Zihin — fonte de verdade verificada contra o BE
+ * (zihin-agent-builder/server-llm, 2026-06-28).
+ *
+ * @module types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@zihin/agent-client",
+  "version": "0.1.0",
+  "description": "Núcleo de invocação de agentes Zihin.ai — padrão único para n8n, Paperclip e integrações futuras. Stream direto (SSE bufferizado) + triggers assíncronos com callback.",
+  "keywords": [
+    "zihin",
+    "agent",
+    "ai",
+    "llm",
+    "sse",
+    "agent-client"
+  ],
+  "license": "MIT",
+  "homepage": "https://zihin.ai",
+  "author": {
+    "name": "Zihin AI Inc.",
+    "email": "support@zihin.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zihin-ai/zihin-integrations.git",
+    "directory": "packages/agent-client"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "node test/smoke.js",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": ">=18",
+    "typescript": "^5.4.0"
+  }
+}