@agentforge-io/sdk-server 4.0.22 → 4.2.0

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { AgentForgeClient } from './client';
 export type { AgentForgeClientOptions, RequestOptions } from './client';
 export { AgentForgeError, AgentForgeAuthError, AgentForgeNotFoundError, AgentForgeNetworkError, } from './errors';
 export { TOOL_CALLBACK_HEADERS, ToolCallbackSignatureError, signToolCallbackPayload, verifyToolCallbackSignature, } from './webhooks';
-export type { AgentMe, AgentSummary, ApprovalCopyBundle, ChatStreamChunk, ChatStreamEvent, ChatTokenRecord, ConnectorDefaultsResult, ConnectorDefaultsSource, ConnectorResourceItem, ConnectorStatus, ConnectorToolInfo, ConversationHistory, ConversationStatus, CreateAgentInput, CreateClickupTaskInput, CreateClickupTaskResult, ExternalToolSummary, IssueChatTokenInput, ListAgentsResult, ListConnectorResourcesResult, McpServerConfig, MessageRecord, MessageRole, PublicAppBranding, AppSelf, AppSelfConnector, AppSelfConnectors, RegisterToolInput, RegisterToolsInput, RegisterToolsResult, ToolCallbackPayload, ToolCallRecord, ToolPermission, ToolPermissionMode, TokenUsage, TenantSecretEntry, UpdateAgentInput, } from './types';
+export type { AgentMe, AgentSummary, AppUserConnectorStatus, ApprovalCopyBundle, ChatStreamChunk, ChatStreamEvent, ChatTokenRecord, ConnectorDefaultsResult, ConnectorDefaultsSource, ConnectorResourceItem, ConnectorStatus, ConnectorToolInfo, ConversationHistory, ConversationStatus, CreateAgentInput, CreateClickupTaskInput, CreateClickupTaskResult, ExternalToolSummary, IssueChatTokenInput, ListAgentsResult, ListConnectorResourcesResult, McpServerConfig, MessageRecord, MessageRole, PublicAppBranding, AppSelf, AppSelfConnector, AppSelfConnectors, RegisterToolInput, RegisterToolsInput, RegisterToolsResult, ToolCallbackPayload, ToolCallRecord, ToolPermission, ToolPermissionMode, TokenUsage, TenantSecretEntry, UpdateAgentInput, } from './types';
 export { AgentsResource } from './resources/agents';
 export { AppsResource } from './resources/apps';
 export { ChatResource } from './resources/chat';

package/dist/resources/chat.d.ts

@@ -9,6 +9,20 @@ export interface StreamMessageInput {
     /** Si se omite, el server crea una conversación nueva. */
     conversationId?: string;
 }
+export interface StreamMessageForAppUserInput {
+    /** Which of the App's tenant agents to run. */
+    agentId: string;
+    /** The App's own identifier for its end user — NOT signed, rides as a
+     *  plain param inside the sk_live_-authenticated request (AGF-072 §4.4
+     *  rationale: the authenticated channel is the proof, not a per-user
+     *  signature). Threads into the conversation key
+     *  `app-user:${appId}:${externalUserId}` server-side; `appId` itself is
+     *  never a param, only ever resolved from the secret. */
+    externalUserId: string;
+    content: string;
+    /** Si se omite, el server crea una conversación nueva. */
+    conversationId?: string;
+}
 export declare class ChatResource {
     private readonly client;
     constructor(client: AgentForgeClient);
@@ -52,4 +66,37 @@ export declare class ChatResource {
      * no pertenece al ChatToken que llama.
      */
     getHistory(conversationId: string): Promise<ConversationHistory>;
+    /**
+     * AGF-073a — chat streaming AGENT-AWARE para el surface App-authenticated
+     * (`sk_live_`/`sk_test_`), server-to-server — `POST
+     * /api/v1/app-user-chat/conversations/stream` (o `.../conversations/:id/
+     * messages/stream` cuando `input.conversationId` viene seteado). Sibling
+     * ADITIVO de `streamMessage()`: NO usa ChatToken, requiere que el
+     * `AgentForgeClient` se haya construido con `appSecret`. `appId` lo
+     * resuelve el server exclusivamente del secret — nunca es un param acá
+     * tampoco (ver `APP_USER_CHAT_RUNTIME_SDD.md`).
+     *
+     * Mismo shape de eventos que `streamMessage()` — `ChatStreamEvent` con
+     * los mismos `kind`s (`conversation` | `chunk` | `stream_end` | `error`).
+     * Un consumidor no puede distinguir cuál de los dos métodos produjo el
+     * stream a partir de los eventos solos.
+     *
+     * @example
+     *   const af = new AgentForgeClient({ baseURL, appSecret: 'sk_live_...' });
+     *   for await (const ev of af.chat.streamMessageForAppUser({
+     *     agentId: 'agent-uuid',
+     *     externalUserId: 'scrappydoc-user-42',
+     *     content: 'hola',
+     *   })) {
+     *     if (ev.kind === 'conversation') conversationId = ev.conversationId;
+     *   }
+     */
+    streamMessageForAppUser(input: StreamMessageForAppUserInput): AsyncGenerator<ChatStreamEvent>;
+    /**
+     * AGF-073a companion to `streamMessageForAppUser` — historial completo de
+     * una conversación app-user, `GET /api/v1/app-user-chat/conversations/:id/
+     * messages?externalUserId=...`. `externalUserId` va como query param
+     * porque GET no lleva body; `appId` sigue resolviéndose del secret.
+     */
+    getHistoryForAppUser(conversationId: string, externalUserId: string): Promise<ConversationHistory>;
 }

package/dist/resources/chat.js

@@ -110,6 +110,86 @@ class ChatResource {
     async getHistory(conversationId) {
         return this.client.request('GET', `/api/v1/chat/conversations/${encodeURIComponent(conversationId)}/messages`);
     }
+    /**
+     * AGF-073a — chat streaming AGENT-AWARE para el surface App-authenticated
+     * (`sk_live_`/`sk_test_`), server-to-server — `POST
+     * /api/v1/app-user-chat/conversations/stream` (o `.../conversations/:id/
+     * messages/stream` cuando `input.conversationId` viene seteado). Sibling
+     * ADITIVO de `streamMessage()`: NO usa ChatToken, requiere que el
+     * `AgentForgeClient` se haya construido con `appSecret`. `appId` lo
+     * resuelve el server exclusivamente del secret — nunca es un param acá
+     * tampoco (ver `APP_USER_CHAT_RUNTIME_SDD.md`).
+     *
+     * Mismo shape de eventos que `streamMessage()` — `ChatStreamEvent` con
+     * los mismos `kind`s (`conversation` | `chunk` | `stream_end` | `error`).
+     * Un consumidor no puede distinguir cuál de los dos métodos produjo el
+     * stream a partir de los eventos solos.
+     *
+     * @example
+     *   const af = new AgentForgeClient({ baseURL, appSecret: 'sk_live_...' });
+     *   for await (const ev of af.chat.streamMessageForAppUser({
+     *     agentId: 'agent-uuid',
+     *     externalUserId: 'scrappydoc-user-42',
+     *     content: 'hola',
+     *   })) {
+     *     if (ev.kind === 'conversation') conversationId = ev.conversationId;
+     *   }
+     */
+    async *streamMessageForAppUser(input) {
+        if (!this.client.getAppSecret()) {
+            throw new Error('chat.streamMessageForAppUser requires appSecret (sk_live_/sk_test_) in ' +
+                'AgentForgeClient. This surface authenticates AS the App, not via chatToken.');
+        }
+        const path = input.conversationId
+            ? `/api/v1/app-user-chat/conversations/${encodeURIComponent(input.conversationId)}/messages/stream`
+            : '/api/v1/app-user-chat/conversations/stream';
+        const res = await this.client.requestStream('POST', path, {
+            agentId: input.agentId,
+            externalUserId: input.externalUserId,
+            content: input.content,
+        });
+        if (!res.body) {
+            throw new Error('chat.streamMessageForAppUser: response has no readable body');
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let idx;
+                while ((idx = buffer.indexOf('\n\n')) !== -1) {
+                    const frame = buffer.slice(0, idx);
+                    buffer = buffer.slice(idx + 2);
+                    const raw = parseRawSseFrame(frame);
+                    if (!raw)
+                        continue;
+                    const event = toChatStreamEvent(raw);
+                    if (event)
+                        yield event;
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    /**
+     * AGF-073a companion to `streamMessageForAppUser` — historial completo de
+     * una conversación app-user, `GET /api/v1/app-user-chat/conversations/:id/
+     * messages?externalUserId=...`. `externalUserId` va como query param
+     * porque GET no lleva body; `appId` sigue resolviéndose del secret.
+     */
+    async getHistoryForAppUser(conversationId, externalUserId) {
+        if (!this.client.getAppSecret()) {
+            throw new Error('chat.getHistoryForAppUser requires appSecret (sk_live_/sk_test_) in AgentForgeClient.');
+        }
+        return this.client.request('GET', `/api/v1/app-user-chat/conversations/${encodeURIComponent(conversationId)}/messages` +
+            `?externalUserId=${encodeURIComponent(externalUserId)}`);
+    }
 }
 exports.ChatResource = ChatResource;
 /** Frame SSE genérico: `event: <name>\ndata: <line>\ndata: <line>...`.

package/dist/resources/connectors.d.ts

@@ -1,5 +1,5 @@
 import type { AgentForgeClient } from '../client';
-import type { ConnectorDefaultsResult, ConnectorStatus, CreateClickupTaskInput, CreateClickupTaskResult, ListConnectorResourcesResult, ToolPermission } from '../types';
+import type { AppUserConnectorStatus, ConnectorDefaultsResult, ConnectorStatus, CreateClickupTaskInput, CreateClickupTaskResult, ListConnectorResourcesResult, ToolPermission } from '../types';
 export declare class ConnectorsResource {
     private readonly client;
     constructor(client: AgentForgeClient);
@@ -196,6 +196,73 @@ export declare class ConnectorsResource {
      * desconecta un canal del inbox omnicanal.
      */
     destroyInboxChannel(agentId: string, channelId: string): Promise<void>;
+    /**
+     * `POST /connectors/oauth/:id/authorize-for-app-user` — starts the
+     * connector OAuth flow on behalf of ONE end user of the `sk_live_`/
+     * `sk_test_` App (`appId` resolved from the secret, `externalUserId`
+     * explicit). App-user counterpart of `authorizeForTenant()` above — same
+     * response shape (`{ url }`, open it e.g. via `window.open` in the
+     * consumer app), same callback flow end-to-end on the platform.
+     *
+     * Requires the `AgentForgeClient` to have been constructed with
+     * `appSecret` — throws early otherwise (this surface authenticates AS the
+     * App, not via ak_live_/ChatToken).
+     *
+     * @example
+     *   const af = new AgentForgeClient({ baseURL, appSecret: 'sk_live_...' });
+     *   const { url } = await af.connectors.authorizeForAppUser('slack', {
+     *     externalUserId: 'scrappydoc-user-42',
+     *     postAuthRedirect: 'https://myapp.com/settings',
+     *   });
+     */
+    authorizeForAppUser(connectorId: string, input: {
+        externalUserId: string;
+        postAuthRedirect?: string;
+    }): Promise<{
+        url: string;
+    }>;
+    /**
+     * `GET /connectors/oauth/app-user/directory` — the given end user's
+     * connectors + connection status (App-user counterpart of
+     * `listConnected()`, which is the ak_live_ tenant-wide picker). Returns
+     * the SAME rich shape `listForTenant`/`listForUser` produce server-side
+     * (`AppUserConnectorStatus`: name/description/category/iconUrl/configured/
+     * accountLabel/connectedAt) — NOT the narrow `ConnectorStatus` the
+     * tenant-picker methods above use.
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     *
+     * @example
+     *   const { items } = await af.connectors.listConnectorsForAppUser({
+     *     externalUserId: 'scrappydoc-user-42',
+     *   });
+     *   const unconnected = items.filter((c) => c.configured && !c.connected);
+     */
+    listConnectorsForAppUser(input: {
+        externalUserId: string;
+    }): Promise<{
+        items: AppUserConnectorStatus[];
+    }>;
+    /**
+     * `DELETE /connectors/oauth/:id/app-user` — disconnects `connectorId` for
+     * the given end user. App-user counterpart of `disconnect()` above.
+     * Mirrors the platform's `disconnectForAppUser` 404-on-missing behavior
+     * (`ConnectorError('not_connected', ...)` → `AgentForgeNotFoundError`).
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     *
+     * @example
+     *   await af.connectors.disconnectForAppUser('google-drive', {
+     *     externalUserId: 'scrappydoc-user-42',
+     *   });
+     */
+    disconnectForAppUser(connectorId: string, input: {
+        externalUserId: string;
+    }): Promise<{
+        ok: true;
+    }>;
 }
 export interface InboxChannelView {
     id: string;

package/dist/resources/connectors.js

@@ -5,9 +5,13 @@
 // reales de uno conectado (canales de Slack, repos de GitHub, etc), y arranca
 // el OAuth authorize para uno que falte conectar.
 //
-// Auth: SIEMPRE ak_live_ tenant-wide — estos 3 endpoints usan `ApiKeyGuard`
-// en el server y rechazan ChatToken de plano, aunque el `AgentForgeClient`
-// también tenga uno configurado (ver `requestWithApiKey`).
+// Auth: la mayoría de los métodos son ak_live_ tenant-wide — usan
+// `ApiKeyGuard` en el server y rechazan ChatToken de plano, aunque el
+// `AgentForgeClient` también tenga uno configurado (ver `requestWithApiKey`).
+// EXCEPCIÓN (AGF-072, sección "App-user scope" al final del archivo): los
+// métodos `*ForAppUser` (Plane B — un end user del App conectando SU PROPIA
+// cuenta) usan `appSecret` (sk_live_/sk_test_) en vez de ak_live_, y por eso
+// llaman `this.client.request()` directo en lugar de `requestWithApiKey()`.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConnectorsResource = void 0;
 class ConnectorsResource {
@@ -203,5 +207,99 @@ class ConnectorsResource {
     async destroyInboxChannel(agentId, channelId) {
         await this.client.requestWithApiKey('DELETE', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/channels/${encodeURIComponent(channelId)}`);
     }
+    // ─── App-user scope (AGF-072, Option A — APP_END_USER_CONNECTIONS_SDD.md §4.4) ──
+    //
+    // The 3 methods below are Plane B: a specific END USER of an `sk_live_`/
+    // `sk_test_` App connecting THEIR OWN account (their Slack, their Gmail) —
+    // distinct from `*ForTenant` above (Plane A, the App's own tenant-wide
+    // credentials) and from the ak_live_-only picker methods at the top of this
+    // file. Auth is `appSecret` (sk_live_/sk_test_), NOT ak_live_ — these calls
+    // use `this.client.request()` directly (plain `authHeaders()`, which picks
+    // `appSecret` when set) instead of `requestWithApiKey()`, because that
+    // helper hardcodes `forceApiKey: true` and would reject an appSecret-only
+    // client. Same pattern as `ChatResource.streamMessageForAppUser`.
+    //
+    // `appId` is NEVER a param on any of these — the platform resolves it
+    // exclusively from the `sk_live_`/`sk_test_` secret server-side (SDD §4.4),
+    // so App Y's secret can never touch App X's grants no matter what
+    // `externalUserId` is passed. Only `externalUserId` (the App's own,
+    // unsigned identifier for its end user) travels as a param.
+    /**
+     * `POST /connectors/oauth/:id/authorize-for-app-user` — starts the
+     * connector OAuth flow on behalf of ONE end user of the `sk_live_`/
+     * `sk_test_` App (`appId` resolved from the secret, `externalUserId`
+     * explicit). App-user counterpart of `authorizeForTenant()` above — same
+     * response shape (`{ url }`, open it e.g. via `window.open` in the
+     * consumer app), same callback flow end-to-end on the platform.
+     *
+     * Requires the `AgentForgeClient` to have been constructed with
+     * `appSecret` — throws early otherwise (this surface authenticates AS the
+     * App, not via ak_live_/ChatToken).
+     *
+     * @example
+     *   const af = new AgentForgeClient({ baseURL, appSecret: 'sk_live_...' });
+     *   const { url } = await af.connectors.authorizeForAppUser('slack', {
+     *     externalUserId: 'scrappydoc-user-42',
+     *     postAuthRedirect: 'https://myapp.com/settings',
+     *   });
+     */
+    async authorizeForAppUser(connectorId, input) {
+        if (!this.client.getAppSecret()) {
+            throw new Error('connectors.authorizeForAppUser requires appSecret (sk_live_/sk_test_) in ' +
+                'AgentForgeClient. This surface authenticates AS the App, not via chatToken/apiKey.');
+        }
+        const params = new URLSearchParams({ externalUserId: input.externalUserId });
+        if (input.postAuthRedirect)
+            params.set('postAuthRedirect', input.postAuthRedirect);
+        return this.client.request('POST', `/connectors/oauth/${encodeURIComponent(connectorId)}/authorize-for-app-user?${params.toString()}`);
+    }
+    /**
+     * `GET /connectors/oauth/app-user/directory` — the given end user's
+     * connectors + connection status (App-user counterpart of
+     * `listConnected()`, which is the ak_live_ tenant-wide picker). Returns
+     * the SAME rich shape `listForTenant`/`listForUser` produce server-side
+     * (`AppUserConnectorStatus`: name/description/category/iconUrl/configured/
+     * accountLabel/connectedAt) — NOT the narrow `ConnectorStatus` the
+     * tenant-picker methods above use.
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     *
+     * @example
+     *   const { items } = await af.connectors.listConnectorsForAppUser({
+     *     externalUserId: 'scrappydoc-user-42',
+     *   });
+     *   const unconnected = items.filter((c) => c.configured && !c.connected);
+     */
+    async listConnectorsForAppUser(input) {
+        if (!this.client.getAppSecret()) {
+            throw new Error('connectors.listConnectorsForAppUser requires appSecret (sk_live_/sk_test_) in ' +
+                'AgentForgeClient. This surface authenticates AS the App, not via chatToken/apiKey.');
+        }
+        const params = new URLSearchParams({ externalUserId: input.externalUserId });
+        return this.client.request('GET', `/connectors/oauth/app-user/directory?${params.toString()}`);
+    }
+    /**
+     * `DELETE /connectors/oauth/:id/app-user` — disconnects `connectorId` for
+     * the given end user. App-user counterpart of `disconnect()` above.
+     * Mirrors the platform's `disconnectForAppUser` 404-on-missing behavior
+     * (`ConnectorError('not_connected', ...)` → `AgentForgeNotFoundError`).
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     *
+     * @example
+     *   await af.connectors.disconnectForAppUser('google-drive', {
+     *     externalUserId: 'scrappydoc-user-42',
+     *   });
+     */
+    async disconnectForAppUser(connectorId, input) {
+        if (!this.client.getAppSecret()) {
+            throw new Error('connectors.disconnectForAppUser requires appSecret (sk_live_/sk_test_) in ' +
+                'AgentForgeClient. This surface authenticates AS the App, not via chatToken/apiKey.');
+        }
+        const params = new URLSearchParams({ externalUserId: input.externalUserId });
+        return this.client.request('DELETE', `/connectors/oauth/${encodeURIComponent(connectorId)}/app-user?${params.toString()}`);
+    }
 }
 exports.ConnectorsResource = ConnectorsResource;

package/dist/types.d.ts

@@ -319,6 +319,21 @@ export interface ConnectorStatus {
      *  false = se puede conectar pero `listResources()` devuelve `unsupported`. */
     browsable: boolean;
 }
+export interface AppUserConnectorStatus {
+    connectorId: string;
+    name: string;
+    description: string;
+    category?: string;
+    iconUrl?: string;
+    /** El operador del tenant ya trajo credenciales para este provider. Si es
+     *  `false`, este end user no puede conectar todavía (falta setup admin). */
+    configured: boolean;
+    /** Este externalUserId particular ya completó el OAuth/API-key setup. */
+    connected: boolean;
+    accountLabel?: string;
+    /** ISO 8601 — `Date` en el server, serializado a string sobre JSON. */
+    connectedAt?: string;
+}
 export interface ConnectorResourceItem {
     id: string;
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/sdk-server",
-  "version": "4.0.22",
+  "version": "4.2.0",
   "description": "Server-side SDK for backend apps integrating with AgentForge platform. Auth via ChatToken or ak_live_ API key.",
   "license": "MIT",
   "main": "dist/index.js",