@engramind/client 0.0.0-stage → 0.1.1

package/dist/server.d.ts

@@ -0,0 +1,225 @@
+import { a as EngramindMethod, E as EngramindClient } from './client-Q0QFU2A6.js';
+export { C as CallOptions, b as CategoryInput, c as ChannelQuery, d as EngramindClientOptions, M as MemoryQuery, Q as Query, e as buildUrl, f as createEngramindClient, g as debugUrl } from './client-Q0QFU2A6.js';
+import { L as LiveEvent, W as WebhookEvent } from './events-DYEjIvxs.js';
+export { C as ConsumptionEvent, a as ConsumptionGrouperOptions, E as EngramindError, b as EngramindErrorBody, c as WebhookEventType, d as clientStatus, e as createConsumptionGrouper, f as engramindCodeOf, i as isConsumedEvent, g as isMemoryChange, m as mergeConsumption, n as notConfiguredError, p as proxyMaskedError, t as toEngramindError, h as toLiveEvent, u as unreachableError } from './events-DYEjIvxs.js';
+import { h as ContextView } from './types-BnU5iHwB.js';
+
+/**
+ * Rotas do proxy da lib: o caminho do REST do Engramind sem o `/v1` (`channels/eng%2Fglobal/archive`).
+ * `app` é o que o token de app pode fazer (matriz do guia `tokens-e-escopos`); `manager` acrescenta o que
+ * o gestor da rede usa nas telas (apps, criar/editar/excluir canais, configurações por canal).
+ */
+type ProxyMode = "app" | "manager";
+interface ProxyRoute {
+    method: EngramindMethod;
+    /** Segmentos; `:nome` casa um segmento qualquer. */
+    pattern: string;
+    modes: readonly ProxyMode[];
+    /** Operação do Engramind (auditoria do app e testes). */
+    operation: string;
+}
+declare const PROXY_ROUTES: readonly ProxyRoute[];
+interface RouteMatch {
+    route: ProxyRoute;
+    params: Record<string, string>;
+    /** Caminho do Engramind (`/v1/...`) com os segmentos recodificados. */
+    path: string;
+}
+/** Casa método + segmentos (já decodificados) com uma rota permitida no modo. */
+declare function matchProxyRoute(method: string, segments: readonly string[], mode: ProxyMode): RouteMatch | null;
+
+/**
+ * Proxy HTTP pronto para os componentes da lib: o app monta numa rota (ex.: catch-all do Next.js
+ * `app/api/engramind/[...path]/route.ts`) **atrás do próprio login** — a lib não verifica usuário. Repassa
+ * só as rotas do modo (`app`: as do token de app; `manager`: também as do gestor), com o token do
+ * servidor; a resposta é `{ success: true, data }` ou `{ success: false, error, code, details }` e nunca
+ * traz o token configurado. No modo app, `issue_token` só emite `kind: agent`.
+ */
+interface ProxyMutation {
+    operation: string;
+    method: EngramindMethod;
+    params: Record<string, string>;
+    /** Corpo enviado (o app decide o que audita; segredos de token emitido não passam por aqui). */
+    body: unknown;
+    result: unknown;
+}
+interface EngramindProxyOptions {
+    /** Cliente do Engramind (ou uma função que o monta a cada requisição, ex.: lendo a configuração). */
+    client: EngramindClient | (() => EngramindClient | null | Promise<EngramindClient | null>);
+    mode?: ProxyMode;
+    /** Prefixo da rota no app (ex.: `/api/engramind`); o resto do caminho é a rota do Engramind. */
+    basePath: string;
+    /** Depois de cada mutação bem-sucedida (auditoria do app). */
+    onMutation?: (mutation: ProxyMutation) => void | Promise<void>;
+    /**
+     * Token de agente emitido ou rotacionado: o segredo aparece só nesta resposta. O app pode gravá-lo onde
+     * quiser (ex.: cofre do servidor); o diálogo da lib também o mostra uma única vez.
+     */
+    onTokenIssued?: (secret: string, token: {
+        id: string;
+        agent: string | null;
+        app: string | null;
+        kind: string;
+        operation: "issue_token" | "rotate_token";
+    }) => void | Promise<void>;
+    onError?: (error: unknown, route: ProxyRoute | null) => void;
+}
+declare function errorResponse(error: unknown): Response;
+/** Segmentos depois do `basePath`, decodificados (`channels/eng%2Fglobal` → `["channels", "eng/global"]`). */
+declare function proxySegments(pathname: string, basePath: string): string[] | null;
+declare function createEngramindProxy(options: EngramindProxyOptions): (request: Request) => Promise<Response>;
+
+/**
+ * Barramento dos eventos ao vivo (webhook → SSE). O padrão vive **no processo**: só os navegadores
+ * ligados à instância que recebeu o webhook são avisados. Com várias instâncias, passe um `Broadcaster`
+ * (ex.: Redis pub/sub, Postgres `NOTIFY`, Pusher) que entregue o evento a todas.
+ */
+type LiveListener = (event: LiveEvent) => void;
+interface Broadcaster {
+    publish(event: LiveEvent): void | Promise<void>;
+    subscribe(listener: LiveListener): () => void;
+}
+interface EventBus {
+    publish(event: LiveEvent): Promise<void>;
+    subscribe(listener: LiveListener): () => void;
+    /** Navegadores ligados nesta instância. */
+    readonly size: number;
+}
+declare function createEventBus(options?: {
+    broadcaster?: Broadcaster;
+    onError?: (error: unknown) => void;
+}): EventBus;
+
+/**
+ * Contexto das memórias por agente (`get_context`) com cache por `version` (`If-None-Match` → `304`).
+ * Os eventos `memory.*`, `channel.updated` e `subscription.updated` marcam os canais como sujos;
+ * **`memory.consumed` não** (só avisa que memórias foram entregues). Se o Engramind cair, devolve o
+ * último bloco (`stale: true`). Guarde o bloco na parte estável do prompt.
+ */
+interface ContextEntry {
+    content: string;
+    version: string;
+    counts: ContextView["counts"];
+    format: string;
+    fetchedAt: number;
+    dirty: boolean;
+}
+/** Onde o bloco fica (padrão: memória do processo). Troque por Redis/banco para várias instâncias. */
+interface ContextStore {
+    get(key: string): ContextEntry | null | Promise<ContextEntry | null>;
+    set(key: string, entry: ContextEntry): void | Promise<void>;
+    /** Chaves guardadas (para marcar os canais sujos). */
+    keys(): string[] | Promise<string[]>;
+}
+declare function createMemoryContextStore(): ContextStore;
+interface ContextResult {
+    block: string;
+    version: string | null;
+    /** `live` (lido agora ou `304`), `cache` (Engramind indisponível: último bloco) ou `none`. */
+    source: "live" | "cache" | "none";
+    stale: boolean;
+    counts: ContextView["counts"] | null;
+    error: string | null;
+}
+interface ContextCacheOptions {
+    /** Cliente com o token **do agente** (o contexto é o do agente). */
+    client: (agent: string) => EngramindClient | null | Promise<EngramindClient | null>;
+    store?: ContextStore;
+    format?: string;
+    /**
+     * `always` (padrão): toda chamada revalida com `If-None-Match` (o `304` custa poucos bytes).
+     * `on-dirty`: só chama o Engramind quando um evento sujou um canal do bloco ou depois de `maxAgeMs`.
+     */
+    revalidate?: "always" | "on-dirty";
+    maxAgeMs?: number;
+    onError?: (error: unknown, agent: string) => void;
+}
+declare const contextKey: (agent: string, channels: readonly string[], format: string) => string;
+/** O evento muda o contexto do canal? (`memory.consumed` não muda.) */
+declare function invalidatesContext(event: Pick<WebhookEvent, "type">): boolean;
+declare function createContextCache(options: ContextCacheOptions): {
+    /** Webhook recebido: suja o contexto dos canais afetados (nunca por `memory.consumed`). */
+    handleEvent(event: Pick<WebhookEvent, "type" | "channel">): void;
+    getContext(agent: string, input?: {
+        channels?: readonly string[];
+        focus?: string;
+    }): Promise<ContextResult>;
+    /** Bloco guardado (sem chamar o Engramind). */
+    peek: (agent: string, channels?: readonly string[]) => Promise<ContextEntry | null>;
+};
+type ContextCache = ReturnType<typeof createContextCache>;
+
+/**
+ * Webhook do Engramind (`POST <webhook_url>`): valida `Engramind-Signature` (`t=<unix>,v1=<hex>`,
+ * HMAC-SHA256 do segredo sobre `t + "." + corpo bruto`, janela de 300 s, comparação em tempo constante),
+ * descarta o `id` repetido (as retentativas repetem o corpo), marca o contexto do canal como sujo (menos
+ * `memory.consumed`) e republica no SSE só ids, slugs e tipos. Assinatura inválida: `401` sem corpo.
+ */
+declare const WEBHOOK_TOLERANCE_SECONDS = 300;
+declare function parseSignatureHeader(header: string | null): {
+    t: number;
+    v1: string[];
+} | null;
+declare function signWebhook(secret: string, timestamp: number, body: string): string;
+declare function verifyWebhookSignature(header: string | null, body: string, secret: string, options?: {
+    now?: number;
+    toleranceSeconds?: number;
+}): boolean;
+/** Registro dos `id` já processados (retentativas do Engramind). */
+interface DedupeStore {
+    /** `true` se o `id` já foi visto (e o marca como visto). */
+    seen(id: string): boolean | Promise<boolean>;
+}
+/** Padrão em memória: lembra os últimos `max` ids por `ttlMs` (24 h). */
+declare function createMemoryDedupe(options?: {
+    ttlMs?: number;
+    max?: number;
+}): DedupeStore;
+interface WebhookHandlerOptions {
+    /** Segredo do webhook do app (o mesmo gravado no Engramind por `update_app_webhook`). */
+    secret: string | (() => string | null | Promise<string | null>);
+    bus?: EventBus;
+    dedupe?: DedupeStore;
+    /** Contexto em cache dos agentes do app: marca os canais sujos. */
+    context?: ContextCache;
+    /** Depois de validar (ex.: auditoria, outro tempo real do app). Uma falha não muda a resposta. */
+    onEvent?: (event: WebhookEvent) => void | Promise<void>;
+    onError?: (error: unknown) => void;
+    toleranceSeconds?: number;
+}
+declare function createWebhookHandler(options: WebhookHandlerOptions): (request: Request) => Promise<Response>;
+
+/**
+ * Endpoint SSE dos componentes (`EventSource`): repassa os eventos do barramento como
+ * `event: engramind` com só ids, slugs e tipos, e um comentário de vida a cada `heartbeatMs`. O app monta
+ * **atrás do próprio login**; ao cair, o navegador reconecta e relê as telas.
+ */
+interface SseOptions {
+    bus: EventBus;
+    heartbeatMs?: number;
+    /** Filtra o que cada navegador recebe (ex.: por app ou canal). */
+    filter?: (event: LiveEvent, request: Request) => boolean;
+}
+declare const formatSse: (event: string, data: unknown) => string;
+declare function createSseHandler(options: SseOptions): (request: Request) => Response;
+
+/**
+ * Configuração de MCP pronta para registrar o Engramind num agente: `POST /mcp` com o token **do agente**
+ * e o cabeçalho `Engramind-Channels` (canais do projeto). `tools/list` já mostra só o que o token pode
+ * usar; repasse ao agente só as ferramentas que a sua política permite.
+ */
+interface EngramindMcpConfig {
+    type: "http";
+    url: string;
+    headers: Record<string, string>;
+}
+declare function engramindMcpConfig(input: {
+    baseUrl: string;
+    agentToken: string;
+    channels?: readonly string[];
+}): EngramindMcpConfig;
+/** Ferramentas de leitura e de escrita do MCP do Engramind (para filtrar o `tools/list`). */
+declare const MCP_READ_TOOLS: readonly ["get_context", "search_memories", "get_memory", "get_hints", "list_memories", "list_categories"];
+declare const MCP_WRITE_TOOLS: readonly ["create_memory", "update_memory"];
+
+export { type Broadcaster, type ContextCache, type ContextCacheOptions, type ContextEntry, type ContextResult, type ContextStore, type DedupeStore, EngramindClient, type EngramindMcpConfig, EngramindMethod, type EngramindProxyOptions, type EventBus, LiveEvent, type LiveListener, MCP_READ_TOOLS, MCP_WRITE_TOOLS, PROXY_ROUTES, type ProxyMode, type ProxyMutation, type ProxyRoute, type RouteMatch, type SseOptions, WEBHOOK_TOLERANCE_SECONDS, WebhookEvent, type WebhookHandlerOptions, contextKey, createContextCache, createEngramindProxy, createEventBus, createMemoryContextStore, createMemoryDedupe, createSseHandler, createWebhookHandler, engramindMcpConfig, errorResponse, formatSse, invalidatesContext, matchProxyRoute, parseSignatureHeader, proxySegments, signWebhook, verifyWebhookSignature };