@agentforge-io/sdk-server 4.2.0 → 4.4.0

package/dist/resources/connectors.d.ts

@@ -227,8 +227,9 @@ export declare class ConnectorsResource {
      * `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.
+     * accountLabel/connectedAt), PLUS `browsable` (AGF-074, computed
+     * server-side on top of the raw `ConnectorStatus` rows) — NOT the narrow
+     * `ConnectorStatus` the tenant-picker methods above use.
      *
      * Requires `appSecret` — throws early otherwise, same as
      * `authorizeForAppUser`.
@@ -263,6 +264,111 @@ export declare class ConnectorsResource {
     }): 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

@@ -259,8 +259,9 @@ class ConnectorsResource {
      * `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.
+     * accountLabel/connectedAt), PLUS `browsable` (AGF-074, computed
+     * server-side on top of the raw `ConnectorStatus` rows) — NOT the narrow
+     * `ConnectorStatus` the tenant-picker methods above use.
      *
      * Requires `appSecret` — throws early otherwise, same as
      * `authorizeForAppUser`.
@@ -301,5 +302,149 @@ class ConnectorsResource {
         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

@@ -330,6 +330,11 @@ export interface AppUserConnectorStatus {
     configured: boolean;
     /** Este externalUserId particular ya completó el OAuth/API-key setup. */
     connected: boolean;
+    /** ¿Tiene selector de recursos real implementado (nivel 2 del picker)?
+     *  `false` = se puede conectar pero `listResourcesForAppUser()` devuelve
+     *  `unsupported: true`. Mismo criterio (`SUPPORTED_CONNECTORS`) que
+     *  `ConnectorStatus.browsable` usa para el picker tenant-wide. */
+    browsable: boolean;
     accountLabel?: string;
     /** ISO 8601 — `Date` en el server, serializado a string sobre JSON. */
     connectedAt?: string;
@@ -338,12 +343,24 @@ export interface ConnectorResourceItem {
     id: string;
     name: string;
     description?: string;
+    /** Avatar/icon URL for the resource — populated for Slack DMs/people
+     *  (AGF-074 bug #2: the interlocutor's profile photo, from
+     *  `users.info`/`users.list`). Channels and other resource kinds leave
+     *  this `undefined`; render a generic icon (`#` for Slack channels)
+     *  as a fallback. */
+    imageUrl?: string;
 }
 export interface ListConnectorResourcesResult {
     items: ConnectorResourceItem[];
     /** true cuando el connector está conectado pero `browsable` es false —
      *  no es un error, la UI debe mostrar un estado "sin selector todavía". */
     unsupported?: true;
+    /** AGF-074 bug #3: true cuando el provider devolvió `missing_scope` para
+     *  un sub-recurso opcional (ej. Slack DMs vía `im`/`mpim`/`users.list`,
+     *  en un grant OAuth previo a que el connector declarara esos scopes).
+     *  `items` igual trae lo que SÍ se pudo listar (ej. los canales); la UI
+     *  debe ofrecer un CTA de reconectar en vez de tratarlo como error. */
+    needsReconnectForDms?: true;
 }
 export interface CreateClickupTaskInput {
     /** Id de la lista de ClickUp (`ConnectorResourceItem.id` del picker). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/sdk-server",
-  "version": "4.2.0",
+  "version": "4.4.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",