mitra-interactions-sdk 1.0.60-beta.25 → 1.0.60-beta.27

package/README.md

@@ -246,7 +246,7 @@ const result2 = await listRecordsMitra({
 
 ## Agent Chat (copilot)
 
-Chat com o agente de IA embarcado. **REST-first**: credenciais e modelos vão pela **BFF no `baseURL` normal** (`/agentAiShortcut/*` — herdam `fetchWithRefresh` e CORS); chats e histórico via `{origin}/copilot/api/v1`. **Só o prompt é streaming** — um WebSocket por task em `wss://{origin}/copilot/ws/tasks/{taskId}?token=JWT`, aberto pela SDK quando a conversa começa (WS não passa por preflight de CORS).
+Chat com o agente de IA embarcado. **REST-first, tudo pela BFF no `baseURL` normal** (`/agentAiShortcut/*` — herda `fetchWithRefresh` e CORS): chats (`createChat`/`listChats`/`readChat`/`renameChat`/`deleteChat`), histórico (`listChatMessages`), credenciais e modelos. `projectId` obrigatório em todas (opcional na chamada se veio do `configureSdkMitra`). **Só o prompt é streaming** — um WebSocket por task em `wss://{origin}/copilot/ws/tasks/{taskId}?token=JWT`, aberto pela SDK quando a conversa começa (WS não passa por preflight de CORS).
 
 Precisa de `token` e `baseURL` configurados (o login já deixa pronto). O transporte do prompt aceita `transport: 'ws' | 'http'` — `'ws'` é o default; `'http'` é reservado pra ambientes serverless e hoje lança erro claro (o backend ainda não expõe prompt por HTTP).
 
@@ -265,21 +265,19 @@ const deleted  = await manageAgentChatMitra({ action: 'delete', taskId }); // ar
 ```
 
 - `action: 'list'` → `AgentChat[]` — `{ id, name, agentType, agentId, archived, createdAt, updatedAt }`. Filtros: `agentId?`, `archived?`, `search?`, `page?`, `size?`.
-- `action: 'rename'` → `{ taskId, name }` (PATCH `/tasks/{id}`)
-- `action: 'delete'` → `{ taskId, deleted }` (PATCH `/tasks/{id}/archive` — o histórico não é destruído)
+- `action: 'rename'` → `{ taskId, name }` (POST `/agentAiShortcut/renameChat`)
+- `action: 'delete'` → `{ taskId, deleted }` (POST `/agentAiShortcut/deleteChat` — arquiva, o histórico não é destruído)
 
 ### Abrir uma session — `getAgentTaskMitra`
 
-Retorna uma `AgentTaskSession` que encapsula o ciclo de vida do chat. A task é criada via REST (`POST /tasks`) no primeiro `send()`; o WS da task conecta em seguida. Abrir a mesma `taskId` duas vezes devolve a **mesma** instância (cache).
+Retorna uma `AgentTaskSession` que encapsula o ciclo de vida do chat. A task é criada via BFF (`POST /agentAiShortcut/createChat`) no primeiro `send()`; o WS da task conecta em seguida. Abrir a mesma `taskId` duas vezes devolve a **mesma** instância (cache).
 
 ```typescript
 import { getAgentTaskMitra } from 'mitra-interactions-sdk';
 
-// Chat novo — taskId é preenchido no primeiro send() (evento taskCreated)
-const session = getAgentTaskMitra({ create: true, agentType: 'ANTHROPIC_CLAUDE_OPUS', name: 'Meu chat' });
-
-// Chat com um agente business (system prompt + SFs do agente; token escopado)
-const sales = getAgentTaskMitra({ create: true, agentId: 'uuid-do-agente' });
+// Chat novo — SEMPRE com agentId (sessão sem agente não executa nada).
+// taskId é preenchido no primeiro send() (evento taskCreated)
+const session = getAgentTaskMitra({ create: true, agentId: 'uuid-do-agente', agentType: 'ANTHROPIC_CLAUDE_OPUS', name: 'Meu chat' });
 
 // Chat existente
 const existing = getAgentTaskMitra({ taskId: 'uuid-da-task' });
@@ -289,7 +287,7 @@ await existing.loadHistory({ limit: 50 });
 `getAgentTaskMitra({ create: true, agentType?, name?, agentId?, transport? })` ou `getAgentTaskMitra({ taskId, transport? })`.
 
 - `agentType` vem de `manageAgentCredentialMitra({ action: 'list_models' })` — ex.: `'ANTHROPIC_CLAUDE_OPUS'`, `'OPENAI_GPT5'`, `'GOOGLE_GEMINI_PRO'`. Default: `'ANTHROPIC_CLAUDE_OPUS'`.
-- **`agentId`**: id de um agente business (CRUD via `mitra-sdk`: `listAgentsMitra` e família). A sessão sobe com o system prompt do agente e um token escopado — as tools enxergam só as Server Functions dele. Sem `agentId`, é o chat de desenvolvimento.
+- **`agentId`**: id de um agente business (CRUD via `mitra-sdk`: `listAgentsMitra` e família). A sessão sobe com o system prompt do agente e um token escopado — as tools enxergam só as Server Functions dele. **Sem `agentId`: sessão business sem agente** — sem system prompt e sem acesso às Server Functions (as tools recusam); não há adoção automática de agente único. Na prática, sempre passe `agentId`.
 
 #### Propriedades (somente leitura)
 
@@ -318,7 +316,7 @@ await existing.loadHistory({ limit: 50 });
 `statusChange` · `historyLoaded` · `taskCreated` · `turnStart` · `delta` (`{ delta, kind: 'text' | 'thinking' }`) · `tool` (`{ tool, toolId?, input?, content?, phase: 'call' | 'result' }`) · `turnEnd` (`{ content }`) · `cancelled` · `queueChange` · `error` (`{ code?, error }`) · `raw` (eventos não mapeados do stream, ex.: `workspace`).
 
 ```typescript
-const session = getAgentTaskMitra({ create: true });
+const session = getAgentTaskMitra({ create: true, agentId: 'uuid-do-agente' });
 
 session.on('delta', ({ delta, kind }) => { if (kind === 'text') process.stdout.write(delta); });
 session.on('tool',  ({ tool, phase }) => console.log('🔧', phase, tool));

package/dist/index.d.mts

@@ -205,7 +205,7 @@ interface AgentChat {
     id: string;
     name: string | null;
     agentType: AgentType;
-    /** Agente business dono do chat (null = chat de desenvolvimento). */
+    /** Agente business dono do chat (null = sessão business sem agente — não executa nada). */
     agentId: string | null;
     archived: boolean;
     createdAt: string;
@@ -222,6 +222,8 @@ interface AgentMessage {
 type ChatManageAction = 'list' | 'rename' | 'delete';
 interface ManageAgentChatListOptions {
     action: 'list';
+    /** Obrigatório (opcional na chamada se configurado via configureSdkMitra). */
+    projectId?: number | string;
     /** Filtra os chats de um agente business específico. Omitido = todos os chats. */
     agentId?: string;
     /** Inclui só arquivados (true) ou só ativos (false, default). */
@@ -237,10 +239,14 @@ interface ManageAgentChatRenameOptions {
     action: 'rename';
     taskId: string;
     name: string;
+    /** Obrigatório (opcional na chamada se configurado via configureSdkMitra). */
+    projectId?: number | string;
 }
 interface ManageAgentChatDeleteOptions {
     action: 'delete';
     taskId: string;
+    /** Obrigatório (opcional na chamada se configurado via configureSdkMitra). */
+    projectId?: number | string;
 }
 type ManageAgentChatOptions = ManageAgentChatListOptions | ManageAgentChatRenameOptions | ManageAgentChatDeleteOptions;
 interface RenameAgentChatResult {
@@ -259,8 +265,10 @@ interface DeleteAgentChatResult {
  */
 type AgentTaskTransport = 'ws' | 'http';
 interface GetAgentTaskCreateOptions {
-    /** Cria chat novo. A task é criada via REST no primeiro send(). */
+    /** Cria chat novo. A task é criada via BFF no primeiro send(). */
     create: true;
+    /** Obrigatório (opcional na chamada se configurado via configureSdkMitra). */
+    projectId?: number | string;
     /** Tipo/modelo do agente (de list_models). Default: 'ANTHROPIC_CLAUDE_OPUS'. */
     agentType?: AgentType;
     /** Nome/título do chat. */
@@ -268,8 +276,10 @@ interface GetAgentTaskCreateOptions {
     /**
      * ID de um agente business (CRUD via mitra-sdk: listAgentsMitra e família).
      * Com agentId, a sessão sobe com o system prompt do agente e um token escopado —
-     * as tools enxergam só as Server Functions daquele agente. Sem agentId, é o
-     * chat de desenvolvimento de sempre.
+     * as tools enxergam só as Server Functions daquele agente.
+     * Sem agentId: sessão business SEM agente — sem system prompt e sem acesso às
+     * Server Functions (as tools recusam). Não há adoção automática de agente
+     * único; na prática, sempre passe agentId.
      */
     agentId?: string;
     /** Transporte do prompt (default 'ws'). */
@@ -278,6 +288,8 @@ interface GetAgentTaskCreateOptions {
 interface GetAgentTaskOpenOptions {
     /** Abre chat existente. */
     taskId: string;
+    /** Obrigatório (opcional na chamada se configurado via configureSdkMitra). */
+    projectId?: number | string;
     /** Transporte do prompt (default 'ws'). */
     transport?: AgentTaskTransport;
 }
@@ -513,36 +525,44 @@ declare function getConfig(): MitraConfig;
 declare function resolveProjectId(projectId?: number | string): number | string;
 
 /**
- * Mitra Interactions SDK - Autenticação (Router)
- *
- * Roteia chamadas de auth para a implementação correta com base no `authUrl`:
- * - URLs legadas (`coder.mitralab.io/sdk-auth/`, `agent.mitralab.io/sdk-auth/`) → auth-legacy.ts
- * - Qualquer outro authUrl → auth-new.ts (novo Mitra: Kong gateway + IAM service)
+ * Mitra Interactions SDK - Autenticação (Novo Mitra)
  *
- * A API pública é idêntica à legacy. Consumers não precisam alterar código.
+ * Implementação do auth para o novo Mitra (Kong gateway).
+ * - Email login/signup/refresh: via BFF (mitra-legacy-bff), POST {gateway}/auth/*.
+ *   O BFF resolve projectId->appId, chama o mitra-iam e já devolve o envelope
+ *   { token, baseURL, integrationURL } que a SDK consome.
+ * - SSO (Google): página atravessadora (sdk-auth.html) faz o start do OAuth e
+ *   devolve o `code` cru (popup via postMessage, redirect via #codeMitra). A SDK
+ *   troca o code por token no BFF (POST {gateway}/auth/{provider}), mesmo host do
+ *   /email/login. Provider-agnóstico: Microsoft entra só mudando a allowlist
+ *   quando o back liberar o endpoint. Suporta popup (desktop) e redirect (mobile).
  */
 
-declare function loginMitra(method: 'email' | 'google' | 'microsoft' | 'mitra', options?: LoginOptions): Promise<LoginResponse>;
-declare function loginWithGoogleMitra(options?: LoginOptions): Promise<LoginResponse>;
-declare function loginWithMicrosoftMitra(options?: LoginOptions): Promise<LoginResponse>;
-declare function refreshTokenSilently(authUrl: string, projectId: number | string): Promise<LoginResponse>;
 /**
- * Gera o JWT a partir do code do SSO (novo Mitra). O app lê codeMitra/stateMitra
- * do fragment (lógica de template) e chama aqui pra validar o nonce e trocar o
- * code por token no BFF. Exclusivo do novo mundo — no legacy o token já vem
- * pronto no fragment (tokenMitra).
+ * Gera o JWT a partir do `code` do SSO (retorno do redirect). Valida o `state`
+ * contra o nonce gerado no start (anti-CSRF), troca o code no BFF
+ * (POST {gateway}/auth/{provider}) e configura o SDK. Ler/limpar o fragment da
+ * URL é responsabilidade do app — aqui só se gera o token.
  */
 declare function exchangeSsoCodeMitra(options: {
     code: string;
     state: string;
 }): Promise<LoginResponse>;
+declare function loginWithGoogleMitra(options?: LoginOptions): Promise<LoginResponse>;
+declare function loginWithMicrosoftMitra(options?: LoginOptions): Promise<LoginResponse>;
+declare function loginMitra(method: 'email' | 'google' | 'microsoft' | 'mitra', options?: LoginOptions): Promise<LoginResponse>;
+declare function refreshTokenSilently(authUrl: string, _projectId: number | string): Promise<LoginResponse>;
 
 /**
- * Mitra Interactions SDK — Agent Chat (copilot novo mundo)
+ * Mitra Interactions SDK — Agent Chat (via BFF)
+ *
+ * REST-first, tudo pela BFF no baseURL normal (`/agentAiShortcut/*`) — herda
+ * fetchWithRefresh e o CORS do BFF. Envelope `{ status, result }`; listas vêm
+ * desembrulhadas do Page (result é o array direto).
  *
- * REST-first: chats (tasks), histórico, credenciais e modelos são HTTP no
- * gateway `{origin}/copilot/api/v1`. SÓ o prompt é streaming — WebSocket por
- * task em `{origin}/copilot/ws/tasks/{taskId}?token=JWT`.
+ * SÓ o prompt é streaming: WebSocket por task em
+ * `wss://{origin}/copilot/ws/tasks/{taskId}?token=JWT` (não passa por
+ * preflight de CORS).
  *
  * API pública:
  *   - manageAgentChatMitra({ action: 'list' | 'rename' | 'delete', ... })
@@ -550,10 +570,12 @@ declare function exchangeSsoCodeMitra(options: {
  */
 
 /**
- * Gerencia a coleção de chats do usuário — tudo HTTP:
- *   - list   → GET /copilot/api/v1/tasks (filtros: agentId, archived, search, page, size)
- *   - rename → PATCH /copilot/api/v1/tasks/{id}
- *   - delete → PATCH /copilot/api/v1/tasks/{id}/archive (arquiva; some da lista default)
+ * Gerencia a coleção de chats do usuário — tudo HTTP via BFF:
+ *   - list   → GET  /agentAiShortcut/listChats (filtros: agentId, archived, search, page, size)
+ *   - rename → POST /agentAiShortcut/renameChat
+ *   - delete → POST /agentAiShortcut/deleteChat (arquiva; some da lista default)
+ *
+ * `projectId` é obrigatório (opcional na chamada se configurado no configureSdkMitra).
  *
  * @example
  * const chats = await manageAgentChatMitra({ action: 'list' });
@@ -566,7 +588,7 @@ declare function manageAgentChatMitra(options: ManageAgentChatRenameOptions): Pr
 declare function manageAgentChatMitra(options: ManageAgentChatDeleteOptions): Promise<DeleteAgentChatResult>;
 /**
  * Abre um handle de chat (session). Use:
- *   - `{ create: true }` para iniciar um chat novo (a task é criada via REST no 1º send)
+ *   - `{ create: true }` para iniciar um chat novo (a task é criada via BFF no 1º send)
  *   - `{ taskId: 'X' }` para abrir um chat existente
  *
  * A session expõe histórico, streaming, fila, cancel e eventos. Se a

package/dist/index.d.ts

@@ -205,7 +205,7 @@ interface AgentChat {
     id: string;
     name: string | null;
     agentType: AgentType;
-    /** Agente business dono do chat (null = chat de desenvolvimento). */
+    /** Agente business dono do chat (null = sessão business sem agente — não executa nada). */
     agentId: string | null;
     archived: boolean;
     createdAt: string;
@@ -222,6 +222,8 @@ interface AgentMessage {
 type ChatManageAction = 'list' | 'rename' | 'delete';
 interface ManageAgentChatListOptions {
     action: 'list';
+    /** Obrigatório (opcional na chamada se configurado via configureSdkMitra). */
+    projectId?: number | string;
     /** Filtra os chats de um agente business específico. Omitido = todos os chats. */
     agentId?: string;
     /** Inclui só arquivados (true) ou só ativos (false, default). */
@@ -237,10 +239,14 @@ interface ManageAgentChatRenameOptions {
     action: 'rename';
     taskId: string;
     name: string;
+    /** Obrigatório (opcional na chamada se configurado via configureSdkMitra). */
+    projectId?: number | string;
 }
 interface ManageAgentChatDeleteOptions {
     action: 'delete';
     taskId: string;
+    /** Obrigatório (opcional na chamada se configurado via configureSdkMitra). */
+    projectId?: number | string;
 }
 type ManageAgentChatOptions = ManageAgentChatListOptions | ManageAgentChatRenameOptions | ManageAgentChatDeleteOptions;
 interface RenameAgentChatResult {
@@ -259,8 +265,10 @@ interface DeleteAgentChatResult {
  */
 type AgentTaskTransport = 'ws' | 'http';
 interface GetAgentTaskCreateOptions {
-    /** Cria chat novo. A task é criada via REST no primeiro send(). */
+    /** Cria chat novo. A task é criada via BFF no primeiro send(). */
     create: true;
+    /** Obrigatório (opcional na chamada se configurado via configureSdkMitra). */
+    projectId?: number | string;
     /** Tipo/modelo do agente (de list_models). Default: 'ANTHROPIC_CLAUDE_OPUS'. */
     agentType?: AgentType;
     /** Nome/título do chat. */
@@ -268,8 +276,10 @@ interface GetAgentTaskCreateOptions {
     /**
      * ID de um agente business (CRUD via mitra-sdk: listAgentsMitra e família).
      * Com agentId, a sessão sobe com o system prompt do agente e um token escopado —
-     * as tools enxergam só as Server Functions daquele agente. Sem agentId, é o
-     * chat de desenvolvimento de sempre.
+     * as tools enxergam só as Server Functions daquele agente.
+     * Sem agentId: sessão business SEM agente — sem system prompt e sem acesso às
+     * Server Functions (as tools recusam). Não há adoção automática de agente
+     * único; na prática, sempre passe agentId.
      */
     agentId?: string;
     /** Transporte do prompt (default 'ws'). */
@@ -278,6 +288,8 @@ interface GetAgentTaskCreateOptions {
 interface GetAgentTaskOpenOptions {
     /** Abre chat existente. */
     taskId: string;
+    /** Obrigatório (opcional na chamada se configurado via configureSdkMitra). */
+    projectId?: number | string;
     /** Transporte do prompt (default 'ws'). */
     transport?: AgentTaskTransport;
 }
@@ -513,36 +525,44 @@ declare function getConfig(): MitraConfig;
 declare function resolveProjectId(projectId?: number | string): number | string;
 
 /**
- * Mitra Interactions SDK - Autenticação (Router)
- *
- * Roteia chamadas de auth para a implementação correta com base no `authUrl`:
- * - URLs legadas (`coder.mitralab.io/sdk-auth/`, `agent.mitralab.io/sdk-auth/`) → auth-legacy.ts
- * - Qualquer outro authUrl → auth-new.ts (novo Mitra: Kong gateway + IAM service)
+ * Mitra Interactions SDK - Autenticação (Novo Mitra)
  *
- * A API pública é idêntica à legacy. Consumers não precisam alterar código.
+ * Implementação do auth para o novo Mitra (Kong gateway).
+ * - Email login/signup/refresh: via BFF (mitra-legacy-bff), POST {gateway}/auth/*.
+ *   O BFF resolve projectId->appId, chama o mitra-iam e já devolve o envelope
+ *   { token, baseURL, integrationURL } que a SDK consome.
+ * - SSO (Google): página atravessadora (sdk-auth.html) faz o start do OAuth e
+ *   devolve o `code` cru (popup via postMessage, redirect via #codeMitra). A SDK
+ *   troca o code por token no BFF (POST {gateway}/auth/{provider}), mesmo host do
+ *   /email/login. Provider-agnóstico: Microsoft entra só mudando a allowlist
+ *   quando o back liberar o endpoint. Suporta popup (desktop) e redirect (mobile).
  */
 
-declare function loginMitra(method: 'email' | 'google' | 'microsoft' | 'mitra', options?: LoginOptions): Promise<LoginResponse>;
-declare function loginWithGoogleMitra(options?: LoginOptions): Promise<LoginResponse>;
-declare function loginWithMicrosoftMitra(options?: LoginOptions): Promise<LoginResponse>;
-declare function refreshTokenSilently(authUrl: string, projectId: number | string): Promise<LoginResponse>;
 /**
- * Gera o JWT a partir do code do SSO (novo Mitra). O app lê codeMitra/stateMitra
- * do fragment (lógica de template) e chama aqui pra validar o nonce e trocar o
- * code por token no BFF. Exclusivo do novo mundo — no legacy o token já vem
- * pronto no fragment (tokenMitra).
+ * Gera o JWT a partir do `code` do SSO (retorno do redirect). Valida o `state`
+ * contra o nonce gerado no start (anti-CSRF), troca o code no BFF
+ * (POST {gateway}/auth/{provider}) e configura o SDK. Ler/limpar o fragment da
+ * URL é responsabilidade do app — aqui só se gera o token.
  */
 declare function exchangeSsoCodeMitra(options: {
     code: string;
     state: string;
 }): Promise<LoginResponse>;
+declare function loginWithGoogleMitra(options?: LoginOptions): Promise<LoginResponse>;
+declare function loginWithMicrosoftMitra(options?: LoginOptions): Promise<LoginResponse>;
+declare function loginMitra(method: 'email' | 'google' | 'microsoft' | 'mitra', options?: LoginOptions): Promise<LoginResponse>;
+declare function refreshTokenSilently(authUrl: string, _projectId: number | string): Promise<LoginResponse>;
 
 /**
- * Mitra Interactions SDK — Agent Chat (copilot novo mundo)
+ * Mitra Interactions SDK — Agent Chat (via BFF)
+ *
+ * REST-first, tudo pela BFF no baseURL normal (`/agentAiShortcut/*`) — herda
+ * fetchWithRefresh e o CORS do BFF. Envelope `{ status, result }`; listas vêm
+ * desembrulhadas do Page (result é o array direto).
  *
- * REST-first: chats (tasks), histórico, credenciais e modelos são HTTP no
- * gateway `{origin}/copilot/api/v1`. SÓ o prompt é streaming — WebSocket por
- * task em `{origin}/copilot/ws/tasks/{taskId}?token=JWT`.
+ * SÓ o prompt é streaming: WebSocket por task em
+ * `wss://{origin}/copilot/ws/tasks/{taskId}?token=JWT` (não passa por
+ * preflight de CORS).
  *
  * API pública:
  *   - manageAgentChatMitra({ action: 'list' | 'rename' | 'delete', ... })
@@ -550,10 +570,12 @@ declare function exchangeSsoCodeMitra(options: {
  */
 
 /**
- * Gerencia a coleção de chats do usuário — tudo HTTP:
- *   - list   → GET /copilot/api/v1/tasks (filtros: agentId, archived, search, page, size)
- *   - rename → PATCH /copilot/api/v1/tasks/{id}
- *   - delete → PATCH /copilot/api/v1/tasks/{id}/archive (arquiva; some da lista default)
+ * Gerencia a coleção de chats do usuário — tudo HTTP via BFF:
+ *   - list   → GET  /agentAiShortcut/listChats (filtros: agentId, archived, search, page, size)
+ *   - rename → POST /agentAiShortcut/renameChat
+ *   - delete → POST /agentAiShortcut/deleteChat (arquiva; some da lista default)
+ *
+ * `projectId` é obrigatório (opcional na chamada se configurado no configureSdkMitra).
  *
  * @example
  * const chats = await manageAgentChatMitra({ action: 'list' });
@@ -566,7 +588,7 @@ declare function manageAgentChatMitra(options: ManageAgentChatRenameOptions): Pr
 declare function manageAgentChatMitra(options: ManageAgentChatDeleteOptions): Promise<DeleteAgentChatResult>;
 /**
  * Abre um handle de chat (session). Use:
- *   - `{ create: true }` para iniciar um chat novo (a task é criada via REST no 1º send)
+ *   - `{ create: true }` para iniciar um chat novo (a task é criada via BFF no 1º send)
  *   - `{ taskId: 'X' }` para abrir um chat existente
  *
  * A session expõe histórico, streaming, fila, cancel e eventos. Se a