@agentforge-io/sdk-server 4.2.0 → 4.3.0

package/dist/resources/connectors.d.ts

@@ -263,6 +263,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

@@ -301,5 +301,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/package.json

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