@agentforge-io/sdk-server 4.1.0 → 4.3.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,178 @@ 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;
+    }>;
+    /**
+     * `GET /app-user/connector-resources/:connectorId?externalUserId=...` —
+     * real resource browsing (Slack channels, GitHub repos, ClickUp lists…)
+     * scoped to ONE end user's OWN grant. App-user counterpart of
+     * `listResources()` above — same return shape, same `unsupported: true`
+     * behavior for connectors without a resource selector implemented yet.
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     *
+     * @example
+     *   const { items } = await af.connectors.listResourcesForAppUser('slack', {
+     *     externalUserId: 'scrappydoc-user-42',
+     *   });
+     */
+    listResourcesForAppUser(connectorId: string, input: {
+        externalUserId: string;
+    }): Promise<ListConnectorResourcesResult>;
+    /**
+     * `GET /app-user/connector-resources/:connectorId/defaults?externalUserId=...`
+     * — tool permissions for this connector, resolved with the App's own
+     * override always live (tier 0, `af_app_connectors`) since `appId` comes
+     * from the secret. App-user counterpart of `getDefaults()` above.
+     * `externalUserId` doesn't affect resolution (defaults are per-App, not
+     * per-end-user) — still required because the platform route always reads
+     * it off the scope helper shared by this controller's other routes.
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     */
+    getDefaultsForAppUser(connectorId: string, input: {
+        externalUserId: string;
+    }): Promise<ConnectorDefaultsResult>;
+    /**
+     * `PUT /app-user/connector-resources/:connectorId/defaults?externalUserId=...`
+     * — overwrites the connector's tool permissions. App-user counterpart of
+     * `updateDefaults()` above. NOTE (mirrors the platform controller's own
+     * doc comment): this write lands on the tenant-level row
+     * (`af_connector_tool_defaults`), same as the ak_live_ route — there's no
+     * App-scoped-only override write today. `externalUserId` travels as a
+     * query param (matching `getDefaultsForAppUser`); the platform route also
+     * accepts it in the body but query is canonical for this SDK's GET/PUT
+     * pair.
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     */
+    updateDefaultsForAppUser(connectorId: string, permissions: ToolPermission[], input: {
+        externalUserId: string;
+    }): Promise<{
+        ok: true;
+    }>;
+    /**
+     * `POST /app-user/connector-resources/clickup/tasks` — creates a REAL
+     * ClickUp task using the end user's OWN grant. App-user counterpart of
+     * `createClickupTask()` above. Unlike the GET/PUT methods above,
+     * `externalUserId` travels in the BODY here — the platform route reads it
+     * off `body.externalUserId` for this action endpoint (not a query param).
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     */
+    createClickupTaskForAppUser(input: CreateClickupTaskInput & {
+        externalUserId: string;
+    }): Promise<CreateClickupTaskResult>;
+    /**
+     * `POST /app-user/connector-resources/slack/messages` — posts a REAL
+     * Slack message using the end user's OWN grant. App-user counterpart of
+     * `postSlackMessage()` above. `externalUserId` travels in the BODY, same
+     * as `createClickupTaskForAppUser` (the platform route reads
+     * `body.externalUserId` for both action endpoints).
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     */
+    postSlackMessageForAppUser(input: {
+        channelId: string;
+        text: string;
+        externalUserId: string;
+    }): Promise<{
+        ok: true;
+        ts?: string;
+        permalink?: string;
+    }>;
+    /**
+     * `POST /app-user/connector-resources/:connectorId/api-key` — guarda un
+     * API key pegado por el end user, para SU PROPIO grant (no el tenant del
+     * App). App-user counterpart of `saveApiKeyForTenant()` above, para
+     * connectors que NO usan OAuth (Granola, Mapbox). `externalUserId` viaja
+     * en el BODY, mismo patrón que `createClickupTaskForAppUser`/
+     * `postSlackMessageForAppUser`.
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     *
+     * @example
+     *   await af.connectors.saveApiKeyForAppUser('granola', 'grn_xxxxx', {
+     *     externalUserId: 'scrappydoc-user-42',
+     *   });
+     */
+    saveApiKeyForAppUser(connectorId: string, apiKey: string, input: {
+        externalUserId: string;
+    }): Promise<{
+        connectorId: string;
+    }>;
 }
 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,243 @@ 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()}`);
+    }
+    // ─── App-user resource picker (AGF-072d — app-user twin of the picker
+    // methods at the top of this file) ──────────────────────────────────────
+    //
+    // Mirrors listResources/getDefaults/updateDefaults/createClickupTask/
+    // postSlackMessage above, scoped to (appId-from-secret, externalUserId)
+    // instead of the ak_live_ tenant. Hits `AppUserResourcePickerController`
+    // (`/app-user/connector-resources/*`) — a DISTINCT base path from the
+    // tenant picker's `/connector-resources/*`, not just a query-param
+    // variant. Same auth rule as the 3 methods above: requires `appSecret`,
+    // uses `this.client.request()` directly (not `requestWithApiKey()`).
+    //
+    // NOT mirrored here:
+    //  - list-connected (`GET /app-user/connector-resources`): its
+    //    `{connectorId,connected,browsable}[]` shape is a narrower duplicate
+    //    of what `listConnectorsForAppUser()` above already returns (the
+    //    richer `AppUserConnectorStatus[]` from
+    //    `/connectors/oauth/app-user/directory`). Adding a second, thinner
+    //    "list connected" would just invite callers to pick the wrong one.
+    //  - disconnect (`DELETE /app-user/connector-resources/:connectorId`):
+    //    redundant with `disconnectForAppUser()` above
+    //    (`/connectors/oauth/:id/app-user`) — same ConnectorAuth row, same
+    //    method name would collide. Use the existing one.
+    /**
+     * `GET /app-user/connector-resources/:connectorId?externalUserId=...` —
+     * real resource browsing (Slack channels, GitHub repos, ClickUp lists…)
+     * scoped to ONE end user's OWN grant. App-user counterpart of
+     * `listResources()` above — same return shape, same `unsupported: true`
+     * behavior for connectors without a resource selector implemented yet.
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     *
+     * @example
+     *   const { items } = await af.connectors.listResourcesForAppUser('slack', {
+     *     externalUserId: 'scrappydoc-user-42',
+     *   });
+     */
+    async listResourcesForAppUser(connectorId, input) {
+        if (!this.client.getAppSecret()) {
+            throw new Error('connectors.listResourcesForAppUser 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', `/app-user/connector-resources/${encodeURIComponent(connectorId)}?${params.toString()}`);
+    }
+    /**
+     * `GET /app-user/connector-resources/:connectorId/defaults?externalUserId=...`
+     * — tool permissions for this connector, resolved with the App's own
+     * override always live (tier 0, `af_app_connectors`) since `appId` comes
+     * from the secret. App-user counterpart of `getDefaults()` above.
+     * `externalUserId` doesn't affect resolution (defaults are per-App, not
+     * per-end-user) — still required because the platform route always reads
+     * it off the scope helper shared by this controller's other routes.
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     */
+    async getDefaultsForAppUser(connectorId, input) {
+        if (!this.client.getAppSecret()) {
+            throw new Error('connectors.getDefaultsForAppUser 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', `/app-user/connector-resources/${encodeURIComponent(connectorId)}/defaults?${params.toString()}`);
+    }
+    /**
+     * `PUT /app-user/connector-resources/:connectorId/defaults?externalUserId=...`
+     * — overwrites the connector's tool permissions. App-user counterpart of
+     * `updateDefaults()` above. NOTE (mirrors the platform controller's own
+     * doc comment): this write lands on the tenant-level row
+     * (`af_connector_tool_defaults`), same as the ak_live_ route — there's no
+     * App-scoped-only override write today. `externalUserId` travels as a
+     * query param (matching `getDefaultsForAppUser`); the platform route also
+     * accepts it in the body but query is canonical for this SDK's GET/PUT
+     * pair.
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     */
+    async updateDefaultsForAppUser(connectorId, permissions, input) {
+        if (!this.client.getAppSecret()) {
+            throw new Error('connectors.updateDefaultsForAppUser 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('PUT', `/app-user/connector-resources/${encodeURIComponent(connectorId)}/defaults?${params.toString()}`, { permissions });
+    }
+    /**
+     * `POST /app-user/connector-resources/clickup/tasks` — creates a REAL
+     * ClickUp task using the end user's OWN grant. App-user counterpart of
+     * `createClickupTask()` above. Unlike the GET/PUT methods above,
+     * `externalUserId` travels in the BODY here — the platform route reads it
+     * off `body.externalUserId` for this action endpoint (not a query param).
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     */
+    async createClickupTaskForAppUser(input) {
+        if (!this.client.getAppSecret()) {
+            throw new Error('connectors.createClickupTaskForAppUser requires appSecret (sk_live_/sk_test_) in ' +
+                'AgentForgeClient. This surface authenticates AS the App, not via chatToken/apiKey.');
+        }
+        return this.client.request('POST', '/app-user/connector-resources/clickup/tasks', input);
+    }
+    /**
+     * `POST /app-user/connector-resources/slack/messages` — posts a REAL
+     * Slack message using the end user's OWN grant. App-user counterpart of
+     * `postSlackMessage()` above. `externalUserId` travels in the BODY, same
+     * as `createClickupTaskForAppUser` (the platform route reads
+     * `body.externalUserId` for both action endpoints).
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     */
+    async postSlackMessageForAppUser(input) {
+        if (!this.client.getAppSecret()) {
+            throw new Error('connectors.postSlackMessageForAppUser requires appSecret (sk_live_/sk_test_) in ' +
+                'AgentForgeClient. This surface authenticates AS the App, not via chatToken/apiKey.');
+        }
+        return this.client.request('POST', '/app-user/connector-resources/slack/messages', input);
+    }
+    /**
+     * `POST /app-user/connector-resources/:connectorId/api-key` — guarda un
+     * API key pegado por el end user, para SU PROPIO grant (no el tenant del
+     * App). App-user counterpart of `saveApiKeyForTenant()` above, para
+     * connectors que NO usan OAuth (Granola, Mapbox). `externalUserId` viaja
+     * en el BODY, mismo patrón que `createClickupTaskForAppUser`/
+     * `postSlackMessageForAppUser`.
+     *
+     * Requires `appSecret` — throws early otherwise, same as
+     * `authorizeForAppUser`.
+     *
+     * @example
+     *   await af.connectors.saveApiKeyForAppUser('granola', 'grn_xxxxx', {
+     *     externalUserId: 'scrappydoc-user-42',
+     *   });
+     */
+    async saveApiKeyForAppUser(connectorId, apiKey, input) {
+        if (!this.client.getAppSecret()) {
+            throw new Error('connectors.saveApiKeyForAppUser requires appSecret (sk_live_/sk_test_) in ' +
+                'AgentForgeClient. This surface authenticates AS the App, not via chatToken/apiKey.');
+        }
+        return this.client.request('POST', `/app-user/connector-resources/${encodeURIComponent(connectorId)}/api-key`, { apiKey, externalUserId: input.externalUserId });
+    }
 }
 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.3.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",