@agentforge-io/sdk-server 4.5.2 → 4.6.0

package/dist/client.d.ts

@@ -1,7 +1,9 @@
 import { AgentsResource } from './resources/agents';
+import { AnalyticsResource } from './resources/analytics';
 import { AppsResource } from './resources/apps';
 import { ChatResource } from './resources/chat';
 import { ConnectorsResource } from './resources/connectors';
+import { InboxResource } from './resources/inbox';
 import { ProvisioningResource } from './resources/provisioning';
 import { SecretsResource } from './resources/secrets';
 import { ToolsResource } from './resources/tools';
@@ -58,9 +60,11 @@ export declare class AgentForgeClient {
     private readonly fetchImpl;
     private readonly timeoutMs;
     readonly agents: AgentsResource;
+    readonly analytics: AnalyticsResource;
     readonly apps: AppsResource;
     readonly chat: ChatResource;
     readonly connectors: ConnectorsResource;
+    readonly inbox: InboxResource;
     readonly provisioning: ProvisioningResource;
     readonly secrets: SecretsResource;
     readonly tools: ToolsResource;

package/dist/client.js

@@ -21,9 +21,11 @@ exports.AgentForgeClient = void 0;
 // solo tiene ChatToken. Esas pasan `{ forceApiKey: true }` a `request()`.
 const errors_1 = require("./errors");
 const agents_1 = require("./resources/agents");
+const analytics_1 = require("./resources/analytics");
 const apps_1 = require("./resources/apps");
 const chat_1 = require("./resources/chat");
 const connectors_1 = require("./resources/connectors");
+const inbox_1 = require("./resources/inbox");
 const provisioning_1 = require("./resources/provisioning");
 const secrets_1 = require("./resources/secrets");
 const tools_1 = require("./resources/tools");
@@ -47,9 +49,11 @@ class AgentForgeClient {
         this.fetchImpl = opts.fetch ?? fetch;
         this.timeoutMs = opts.timeoutMs ?? 30000;
         this.agents = new agents_1.AgentsResource(this);
+        this.analytics = new analytics_1.AnalyticsResource(this);
         this.apps = new apps_1.AppsResource(this);
         this.chat = new chat_1.ChatResource(this);
         this.connectors = new connectors_1.ConnectorsResource(this);
+        this.inbox = new inbox_1.InboxResource(this);
         this.provisioning = new provisioning_1.ProvisioningResource(this);
         this.secrets = new secrets_1.SecretsResource(this);
         this.tools = new tools_1.ToolsResource(this);

package/dist/index.d.ts

@@ -4,11 +4,15 @@ export { AgentForgeError, AgentForgeAuthError, AgentForgeNotFoundError, AgentFor
 export { TOOL_CALLBACK_HEADERS, ToolCallbackSignatureError, signToolCallbackPayload, verifyToolCallbackSignature, } from './webhooks';
 export type { AgentMe, AgentSummary, AppUserConnectorStatus, ApprovalCopyBundle, ChannelContext, 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 { AnalyticsResource } from './resources/analytics';
+export type { AgentAttentionLogRow, SupportAnalyticsQuery, SupportKpiResponse, SupportKpiTotals, } from './resources/analytics';
 export { AppsResource } from './resources/apps';
 export { ChatResource } from './resources/chat';
 export type { AnthropicClientOptions, StreamMessageInput } from './resources/chat';
 export { ConnectorsResource } from './resources/connectors';
 export type { InboxChannelView } from './resources/connectors';
+export { InboxResource } from './resources/inbox';
+export type { InboxMessageView, InboxThreadCustomerProfileView, InboxThreadMode, InboxThreadView, } from './resources/inbox';
 export { ProvisioningResource } from './resources/provisioning';
 export type { ProvisionedTenant, ProvisionedApp, } from './resources/provisioning';
 export { SecretsResource } from './resources/secrets';

package/dist/index.js

@@ -28,7 +28,7 @@
 //   const payload = af.tools.verifyCallback({ rawBody, signatureHeader, secretPlaintext });
 //   await af.tools.respondToCallback({ resultUrl: payload.resultUrl, tenantId: payload.tenantId, secret, result });
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolsResource = exports.SecretsResource = exports.ProvisioningResource = exports.ConnectorsResource = exports.ChatResource = exports.AppsResource = exports.AgentsResource = exports.verifyToolCallbackSignature = exports.signToolCallbackPayload = exports.ToolCallbackSignatureError = exports.TOOL_CALLBACK_HEADERS = exports.AgentForgeNetworkError = exports.AgentForgeNotFoundError = exports.AgentForgeAuthError = exports.AgentForgeError = exports.AgentForgeClient = void 0;
+exports.ToolsResource = exports.SecretsResource = exports.ProvisioningResource = exports.InboxResource = exports.ConnectorsResource = exports.ChatResource = exports.AppsResource = exports.AnalyticsResource = exports.AgentsResource = exports.verifyToolCallbackSignature = exports.signToolCallbackPayload = exports.ToolCallbackSignatureError = exports.TOOL_CALLBACK_HEADERS = exports.AgentForgeNetworkError = exports.AgentForgeNotFoundError = exports.AgentForgeAuthError = exports.AgentForgeError = exports.AgentForgeClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "AgentForgeClient", { enumerable: true, get: function () { return client_1.AgentForgeClient; } });
 var errors_1 = require("./errors");
@@ -43,12 +43,16 @@ Object.defineProperty(exports, "signToolCallbackPayload", { enumerable: true, ge
 Object.defineProperty(exports, "verifyToolCallbackSignature", { enumerable: true, get: function () { return webhooks_1.verifyToolCallbackSignature; } });
 var agents_1 = require("./resources/agents");
 Object.defineProperty(exports, "AgentsResource", { enumerable: true, get: function () { return agents_1.AgentsResource; } });
+var analytics_1 = require("./resources/analytics");
+Object.defineProperty(exports, "AnalyticsResource", { enumerable: true, get: function () { return analytics_1.AnalyticsResource; } });
 var apps_1 = require("./resources/apps");
 Object.defineProperty(exports, "AppsResource", { enumerable: true, get: function () { return apps_1.AppsResource; } });
 var chat_1 = require("./resources/chat");
 Object.defineProperty(exports, "ChatResource", { enumerable: true, get: function () { return chat_1.ChatResource; } });
 var connectors_1 = require("./resources/connectors");
 Object.defineProperty(exports, "ConnectorsResource", { enumerable: true, get: function () { return connectors_1.ConnectorsResource; } });
+var inbox_1 = require("./resources/inbox");
+Object.defineProperty(exports, "InboxResource", { enumerable: true, get: function () { return inbox_1.InboxResource; } });
 var provisioning_1 = require("./resources/provisioning");
 Object.defineProperty(exports, "ProvisioningResource", { enumerable: true, get: function () { return provisioning_1.ProvisioningResource; } });
 var secrets_1 = require("./resources/secrets");

package/dist/resources/analytics.d.ts

@@ -0,0 +1,72 @@
+import type { AgentForgeClient } from '../client';
+export interface SupportKpiTotals {
+    receivedCount: number;
+    aiResponsesCount: number;
+    humanMessagesCount: number;
+    escalationsCount: number;
+    aiResolvedCount: number;
+    humanHandledCount: number;
+    assignmentsCount: number;
+    avgResolutionMs: number | null;
+    avgFrtMs: number | null;
+    avgTimeToAssignMs: number | null;
+}
+export interface SupportKpiResponse {
+    tenantId: string;
+    from: string;
+    to: string;
+    totals: SupportKpiTotals;
+    byDimension: Array<SupportKpiTotals & {
+        dimensionType: 'agent' | 'operator';
+        dimensionKey: string;
+    }>;
+}
+export interface AgentAttentionLogRow {
+    dimensionType: 'agent' | 'operator';
+    dimensionKey: string;
+    metricDate: string;
+    receivedCount: number;
+    aiResponsesCount: number;
+    humanMessagesCount: number;
+    escalationsCount: number;
+    aiResolvedCount: number;
+    humanHandledCount: number;
+    assignmentsCount: number;
+    avgResolutionMs: number | null;
+    avgFrtMs: number | null;
+    avgTimeToAssignMs: number | null;
+}
+export interface SupportAnalyticsQuery {
+    /** ISO date string. Required. */
+    from: string;
+    /** ISO date string. Required. */
+    to: string;
+    /** Narrow to one agent's rows (`byDimension`/`items` filtered to
+     *  `dimensionType: 'agent', dimensionKey: agentId`). */
+    agentId?: string;
+    /** Narrow to one operator's rows. */
+    operatorUserId?: string;
+}
+export declare class AnalyticsResource {
+    private readonly client;
+    constructor(client: AgentForgeClient);
+    /**
+     * `GET /apps/me/support-kpis` — totals + per-agent/operator breakdown for
+     * the calling App's tenant, over `[from, to]`.
+     *
+     * @example
+     *   const kpis = await af.analytics.getSupportKpis({
+     *     from: '2026-08-01T00:00:00.000Z',
+     *     to: '2026-08-13T00:00:00.000Z',
+     *   });
+     */
+    getSupportKpis(query: SupportAnalyticsQuery): Promise<SupportKpiResponse>;
+    /**
+     * `GET /apps/me/support-attention-log` — daily per-agent/operator rows
+     * over `[from, to]`. Same query params as `getSupportKpis`.
+     */
+    getAgentAttentionLog(query: SupportAnalyticsQuery): Promise<{
+        items: AgentAttentionLogRow[];
+    }>;
+    private toQueryString;
+}

package/dist/resources/analytics.js

@@ -0,0 +1,59 @@
+"use strict";
+// analytics resource (AGF-SD-3b, AGF-SUPPORT-DESK epic) — wraps
+// `AppSupportAnalyticsController` (`GET /apps/me/support-kpis`,
+// `GET /apps/me/support-attention-log`) on the platform: pre-aggregated
+// support KPIs (received/AI-responses/escalations/resolution-time/etc.)
+// for the calling App's tenant, tenant-wide with optional agent/operator
+// narrowing.
+//
+// Auth: `AppSupportAnalyticsController` accepts BOTH `sk_live_` (appSecret)
+// and `ak_live_` (apiKey) via `ApiKeyGuard`. This resource uses plain
+// `this.client.request()` (NOT `requestWithApiKey()` — that helper
+// hardcodes `ak_live_`-only via `forceApiKey: true` and throws early on an
+// appSecret-only client; see `connectors.ts`'s file header for the same
+// gotcha on the App-user scope methods there), so `authHeaders()` can pick
+// either credential for the `Authorization: Bearer` header. `tenantId` is
+// NEVER a param here (SDD §4.5) — the server resolves it exclusively from
+// the credential.
+//
+// `from`/`to` are REQUIRED on both methods — the platform rejects a
+// missing/malformed/inverted/too-wide range with 400 (no implicit default
+// window). This wrapper does no validation of its own; it forwards
+// whatever `Date` the caller passes as an ISO string and lets the server
+// be the single source of truth for what's a valid range.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalyticsResource = void 0;
+class AnalyticsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * `GET /apps/me/support-kpis` — totals + per-agent/operator breakdown for
+     * the calling App's tenant, over `[from, to]`.
+     *
+     * @example
+     *   const kpis = await af.analytics.getSupportKpis({
+     *     from: '2026-08-01T00:00:00.000Z',
+     *     to: '2026-08-13T00:00:00.000Z',
+     *   });
+     */
+    async getSupportKpis(query) {
+        return this.client.request('GET', `/apps/me/support-kpis${this.toQueryString(query)}`);
+    }
+    /**
+     * `GET /apps/me/support-attention-log` — daily per-agent/operator rows
+     * over `[from, to]`. Same query params as `getSupportKpis`.
+     */
+    async getAgentAttentionLog(query) {
+        return this.client.request('GET', `/apps/me/support-attention-log${this.toQueryString(query)}`);
+    }
+    toQueryString(query) {
+        const params = new URLSearchParams({ from: query.from, to: query.to });
+        if (query.agentId)
+            params.set('agentId', query.agentId);
+        if (query.operatorUserId)
+            params.set('operatorUserId', query.operatorUserId);
+        return `?${params.toString()}`;
+    }
+}
+exports.AnalyticsResource = AnalyticsResource;

package/dist/resources/inbox.d.ts

@@ -0,0 +1,113 @@
+import type { AgentForgeClient } from '../client';
+export declare class InboxResource {
+    private readonly client;
+    constructor(client: AgentForgeClient);
+    /**
+     * `GET /connectors/inbox/agents/:agentId/inbox/threads` — threads for this
+     * agent's support inbox. Optional `channelId` narrows to one channel.
+     *
+     * @example
+     *   const { items } = await af.inbox.listThreads(agentId);
+     */
+    listThreads(agentId: string, opts?: {
+        channelId?: string;
+    }): Promise<{
+        items: InboxThreadView[];
+    }>;
+    /**
+     * `GET /connectors/inbox/agents/:agentId/inbox/threads/:threadId` — a
+     * single thread.
+     */
+    getThread(agentId: string, threadId: string): Promise<InboxThreadView>;
+    /**
+     * `GET /connectors/inbox/agents/:agentId/inbox/threads/:threadId/messages`
+     * — full message history for a thread.
+     */
+    listMessages(agentId: string, threadId: string): Promise<{
+        items: InboxMessageView[];
+    }>;
+    /**
+     * `POST .../threads/:threadId/messages` — send a message as the operator.
+     * `pauseAgent` defaults `true` server-side (pass `false` to reply without
+     * taking the thread away from the agent). `operatorId` is the App's own
+     * opaque identifier for the acting human rep — see file header.
+     *
+     * @example
+     *   await af.inbox.sendOperatorMessage(agentId, threadId, {
+     *     text: 'Un momento, reviso tu caso.',
+     *     operatorId: 'scrappydoc-rep-42',
+     *   });
+     */
+    sendOperatorMessage(agentId: string, threadId: string, input: {
+        text: string;
+        pauseAgent?: boolean;
+        operatorId?: string;
+    }): Promise<void>;
+    /**
+     * `POST .../threads/:threadId/assign` — claim a thread for an operator.
+     * `operatorId` is required (the server rejects a missing one with 401).
+     */
+    assignThread(agentId: string, threadId: string, input: {
+        operatorId: string;
+    }): Promise<void>;
+    /**
+     * `DELETE .../threads/:threadId/assign` — release a thread claim
+     * (handback). `operatorId`, when given, must match the current assignee
+     * server-side.
+     */
+    handback(agentId: string, threadId: string, opts?: {
+        operatorId?: string;
+    }): Promise<void>;
+    /**
+     * `POST .../threads/:threadId/mode` — switch a thread between agent/human
+     * mode.
+     */
+    setThreadMode(agentId: string, threadId: string, mode: InboxThreadMode): Promise<void>;
+    /**
+     * `POST .../threads/:threadId/close` — close a human-mode thread.
+     */
+    closeThread(agentId: string, threadId: string, opts?: {
+        notes?: string;
+        operatorId?: string;
+    }): Promise<void>;
+}
+export type InboxThreadMode = 'agent' | 'human';
+export interface InboxThreadCustomerProfileView {
+    id: string;
+    displayName?: string;
+    username?: string;
+    avatarUrl?: string;
+    providerId?: string;
+    tags?: string[];
+    notes?: string;
+}
+export interface InboxThreadView {
+    id: string;
+    channelId: string;
+    externalId: string;
+    displayName?: string;
+    mode: InboxThreadMode;
+    unreadCount: number;
+    lastMessageAt?: string;
+    lastMessagePreview?: string;
+    assignedHumanUserId?: string;
+    closedAt?: string;
+    closeNotes?: string;
+    closedByUserId?: string;
+    customerProfileId?: string;
+    customerProfile?: InboxThreadCustomerProfileView;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface InboxMessageView {
+    id: string;
+    threadId: string;
+    direction: 'inbound' | 'outbound';
+    source: 'customer' | 'agent' | 'operator';
+    type: 'text' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'location' | 'unsupported';
+    body: string;
+    externalMessageId?: string;
+    payload?: Record<string, unknown>;
+    sentAt: string;
+    recordedAt: string;
+}

package/dist/resources/inbox.js

@@ -0,0 +1,118 @@
+"use strict";
+// inbox resource (AGF-SD-1, AGF-SUPPORT-DESK epic) — wraps
+// `AppInboxController` (`connectors/inbox/agents/:agentId/inbox/*`) on the
+// platform: list/read/reply/assign/handback/mode/close for an agent's
+// support inbox threads, authenticated as an App (`sk_live_`) or an
+// agent-scoped `ak_live_` — never a human dashboard session.
+//
+// Auth: `AppInboxController` accepts BOTH `sk_live_` (appSecret) and
+// `ak_live_` (apiKey) via `ApiKeyGuard` — unlike the tenant-admin-only
+// surfaces `ConnectorsResource` wraps with `requestWithApiKey()` (which
+// hardcodes `ak_live_` and throws early on an appSecret-only client, see
+// that file's header), inbox operator routes are meant to be called by an
+// App itself. So this resource uses plain `this.client.request()`, whose
+// `authHeaders()` picks `apiKey` OR `appSecret` for the `Authorization:
+// Bearer` header (chatToken, if present instead, is rejected server-side
+// with 401 since the route requires `auth.isApiKey`). Every method takes
+// `agentId` explicitly (unlike `af.agents.me()`) because the platform
+// route itself is per-agent and validates ownership server-side
+// (`assertOwnedAgent` — 404, not 403, on a foreign agent).
+//
+// Tenant isolation (SDD §4.5): `tenantId` is NEVER a param here — the
+// server resolves it exclusively from the `ak_live_`/`sk_live_` credential.
+//
+// Operator identity: the platform has no concept of an App's own
+// human-support-rep identity. `operatorId` (optional on most write methods)
+// is an opaque string the calling App mints for its own end of the
+// conversation — passed through verbatim as the platform's `actingUserId`/
+// `userId`. See `AppInboxController`'s file header on the platform for the
+// full rationale.
+//
+// NOT covered here (left for a future extension — see file bottom for
+// what's deliberately excluded and why):
+//   - `af.inbox.channels.get`/`update` — no App-scoped single-channel-read
+//     or update route exists on the platform today (`ApiKeyInboxController`
+//     only has list/create/delete). `list`/`create`/`destroy` already live
+//     on `af.connectors.*` (see `connectors.ts`) — not duplicated here.
+//   - operator online/offline status (`PUT teams/:teamId/operator/status`)
+//     — lives on `OperatorStatusController`, gated by the GLOBAL
+//     `JwtAuthGuard` (human dashboard session), not `ApiKeyGuard`. No
+//     `@Public()`, not reachable with `sk_live_`/`ak_live_` at all.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboxResource = void 0;
+class InboxResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * `GET /connectors/inbox/agents/:agentId/inbox/threads` — threads for this
+     * agent's support inbox. Optional `channelId` narrows to one channel.
+     *
+     * @example
+     *   const { items } = await af.inbox.listThreads(agentId);
+     */
+    async listThreads(agentId, opts) {
+        const qs = opts?.channelId
+            ? `?channelId=${encodeURIComponent(opts.channelId)}`
+            : '';
+        return this.client.request('GET', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads${qs}`);
+    }
+    /**
+     * `GET /connectors/inbox/agents/:agentId/inbox/threads/:threadId` — a
+     * single thread.
+     */
+    async getThread(agentId, threadId) {
+        return this.client.request('GET', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads/${encodeURIComponent(threadId)}`);
+    }
+    /**
+     * `GET /connectors/inbox/agents/:agentId/inbox/threads/:threadId/messages`
+     * — full message history for a thread.
+     */
+    async listMessages(agentId, threadId) {
+        return this.client.request('GET', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads/${encodeURIComponent(threadId)}/messages`);
+    }
+    /**
+     * `POST .../threads/:threadId/messages` — send a message as the operator.
+     * `pauseAgent` defaults `true` server-side (pass `false` to reply without
+     * taking the thread away from the agent). `operatorId` is the App's own
+     * opaque identifier for the acting human rep — see file header.
+     *
+     * @example
+     *   await af.inbox.sendOperatorMessage(agentId, threadId, {
+     *     text: 'Un momento, reviso tu caso.',
+     *     operatorId: 'scrappydoc-rep-42',
+     *   });
+     */
+    async sendOperatorMessage(agentId, threadId, input) {
+        await this.client.request('POST', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads/${encodeURIComponent(threadId)}/messages`, input);
+    }
+    /**
+     * `POST .../threads/:threadId/assign` — claim a thread for an operator.
+     * `operatorId` is required (the server rejects a missing one with 401).
+     */
+    async assignThread(agentId, threadId, input) {
+        await this.client.request('POST', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads/${encodeURIComponent(threadId)}/assign`, input);
+    }
+    /**
+     * `DELETE .../threads/:threadId/assign` — release a thread claim
+     * (handback). `operatorId`, when given, must match the current assignee
+     * server-side.
+     */
+    async handback(agentId, threadId, opts) {
+        await this.client.request('DELETE', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads/${encodeURIComponent(threadId)}/assign`, opts);
+    }
+    /**
+     * `POST .../threads/:threadId/mode` — switch a thread between agent/human
+     * mode.
+     */
+    async setThreadMode(agentId, threadId, mode) {
+        await this.client.request('POST', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads/${encodeURIComponent(threadId)}/mode`, { mode });
+    }
+    /**
+     * `POST .../threads/:threadId/close` — close a human-mode thread.
+     */
+    async closeThread(agentId, threadId, opts) {
+        await this.client.request('POST', `/connectors/inbox/agents/${encodeURIComponent(agentId)}/inbox/threads/${encodeURIComponent(threadId)}/close`, opts);
+    }
+}
+exports.InboxResource = InboxResource;

package/package.json

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