@agentforge-io/sdk-server 4.1.0 → 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/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.1.0",
+  "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",