@agentforge-io/sdk-server 4.0.19 → 4.0.21

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import { AgentsResource } from './resources/agents';
+import { AppsResource } from './resources/apps';
 import { ChatResource } from './resources/chat';
 import { ConnectorsResource } from './resources/connectors';
 import { SecretsResource } from './resources/secrets';
@@ -10,6 +11,13 @@ export interface AgentForgeClientOptions {
     chatToken?: string;
     /** ak_live_... API key scoped to the tenant. */
     apiKey?: string;
+    /** sk_live_... secret of a platform App (AGF-070). Authenticates AS the
+     *  App (the guard resolves its `appId` + tenant). Additive alongside
+     *  `apiKey` — deprecating `apiKey` is deliberately out of scope (SDD §6
+     *  decision #4). On the wire it uses the same `Authorization: Bearer`
+     *  header as `apiKey`; the server's ApiKeyGuard accepts both `ak_live_`
+     *  and `sk_live_` prefixes. */
+    appSecret?: string;
     /** Override fetch (for testing or custom transports). */
     fetch?: typeof fetch;
     /** Default request timeout in ms. Applied to every HTTP call unless
@@ -37,15 +45,18 @@ export declare class AgentForgeClient {
     readonly baseURL: string;
     private readonly chatToken?;
     private readonly apiKey?;
+    private readonly appSecret?;
     private readonly fetchImpl;
     private readonly timeoutMs;
     readonly agents: AgentsResource;
+    readonly apps: AppsResource;
     readonly chat: ChatResource;
     readonly connectors: ConnectorsResource;
     readonly secrets: SecretsResource;
     readonly tools: ToolsResource;
     constructor(opts: AgentForgeClientOptions);
     authHeaders(): Record<string, string>;
+    getAppSecret(): string | undefined;
     getApiKey(): string | undefined;
     getChatToken(): string | undefined;
     /** Como `getApiKey()`, pero tira si el cliente no fue construido con una

package/dist/client.js

@@ -21,6 +21,7 @@ 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 apps_1 = require("./resources/apps");
 const chat_1 = require("./resources/chat");
 const connectors_1 = require("./resources/connectors");
 const secrets_1 = require("./resources/secrets");
@@ -30,28 +31,38 @@ class AgentForgeClient {
         if (!opts.baseURL) {
             throw new Error('AgentForgeClient: baseURL is required');
         }
-        if (!opts.chatToken && !opts.apiKey) {
-            throw new Error('AgentForgeClient: either chatToken or apiKey is required');
+        if (!opts.chatToken && !opts.apiKey && !opts.appSecret) {
+            throw new Error('AgentForgeClient: one of chatToken, apiKey, or appSecret is required');
         }
         this.baseURL = opts.baseURL.replace(/\/$/, '');
         this.chatToken = opts.chatToken;
         this.apiKey = opts.apiKey;
+        this.appSecret = opts.appSecret;
         this.fetchImpl = opts.fetch ?? fetch;
         this.timeoutMs = opts.timeoutMs ?? 30000;
         this.agents = new agents_1.AgentsResource(this);
+        this.apps = new apps_1.AppsResource(this);
         this.chat = new chat_1.ChatResource(this);
         this.connectors = new connectors_1.ConnectorsResource(this);
         this.secrets = new secrets_1.SecretsResource(this);
         this.tools = new tools_1.ToolsResource(this);
     }
-    // Auth headers derivados del modo. ChatToken gana si ambos están presentes.
+    // Auth headers derivados del modo. ChatToken gana si ambos están presentes;
+    // luego apiKey (ak_live_); luego appSecret (sk_live_) — ambos secrets viajan
+    // en el MISMO header `Authorization: Bearer` porque el ApiKeyGuard del server
+    // reconoce ambos prefijos.
     authHeaders() {
         if (this.chatToken)
             return { 'X-Chat-Token': this.chatToken };
         if (this.apiKey)
             return { Authorization: `Bearer ${this.apiKey}` };
+        if (this.appSecret)
+            return { Authorization: `Bearer ${this.appSecret}` };
         return {};
     }
+    getAppSecret() {
+        return this.appSecret;
+    }
     // Expone el modo auth para que resources puedan tomar decisiones (ej. chat
     // proxy necesita la ak_live_ explícita en x-api-key — no ChatToken).
     getApiKey() {

package/dist/index.d.ts

@@ -2,8 +2,9 @@ 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, RegisterToolInput, RegisterToolsInput, RegisterToolsResult, ToolCallbackPayload, ToolCallRecord, ToolPermission, ToolPermissionMode, TokenUsage, TenantSecretEntry, UpdateAgentInput, } from './types';
+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 { AgentsResource } from './resources/agents';
+export { AppsResource } from './resources/apps';
 export { ChatResource } from './resources/chat';
 export type { AnthropicClientOptions, StreamMessageInput } from './resources/chat';
 export { ConnectorsResource } from './resources/connectors';

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.ConnectorsResource = exports.ChatResource = 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.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;
 var client_1 = require("./client");
 Object.defineProperty(exports, "AgentForgeClient", { enumerable: true, get: function () { return client_1.AgentForgeClient; } });
 var errors_1 = require("./errors");
@@ -43,6 +43,8 @@ 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 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");

package/dist/resources/apps.d.ts

@@ -0,0 +1,45 @@
+import type { AgentForgeClient } from '../client';
+import type { PublicAppBranding, AppSelf, AppSelfConnectors } from '../types';
+export declare class AppsResource {
+    private readonly client;
+    constructor(client: AgentForgeClient);
+    /**
+     * `GET /apps/public/:publicKey` — UNAUTHENTICATED branding for a published
+     * App, looked up by its public key (`pk_live_...`). Returns only
+     * name/description/logo/cover — never any secret material or status.
+     *
+     * Resolves ONLY for a published, non-revoked App addressed by its
+     * `pk_live_` key; every other case (unknown key, `pk_test_`, draft,
+     * revoked, malformed) maps to a single opaque **404** →
+     * `AgentForgeNotFoundError`, so a caller cannot distinguish "doesn't
+     * exist" from "exists but not published".
+     *
+     * @example
+     *   const app = await af.apps.publicMetadata('pk_live_abc…');
+     *   renderHeader(app.name, app.logoUrl);
+     */
+    publicMetadata(publicKey: string): Promise<PublicAppBranding>;
+    /**
+     * `GET /apps/me` — metadata of the App this client authenticated AS (via
+     * `sk_live_` in `appSecret`). Returns branding + status + credential
+     * prefixes only — never the plaintext secret or its hash.
+     *
+     * Requires the client to have an `appSecret`. A `pk_test_`/draft App's
+     * `sk_live_` is rejected upstream (403 `not_published`); a client with no
+     * `appSecret` gets 401.
+     *
+     * @example
+     *   const me = await af.apps.me();
+     *   if (me.status !== 'published') warnAuthorTheirAppIsDraft();
+     */
+    me(): Promise<AppSelf>;
+    readonly connectors: {
+        /**
+         * `GET /apps/me/connectors` — connectors resolved for the App this client
+         * authenticated AS, with the same whitelist-vs-legacy `mode` the
+         * tenant-admin surface returns. Only `enabled` rows are actually usable
+         * by the App at runtime.
+         */
+        list: () => Promise<AppSelfConnectors>;
+    };
+}

package/dist/resources/apps.js

@@ -0,0 +1,75 @@
+"use strict";
+// apps resource (AGF-070 §6) — surfaces the platform "App" object to a
+// consuming client (ScrappyDoc, a widget, etc.) so it never has to hand-roll
+// a fetch against `/apps/*` (the SDK-first rule).
+//
+// A platform App bundles a `pk_live_`/`sk_live_` credential pair + branding +
+// a connector whitelist. This resource exposes three reads:
+//
+//   - `publicMetadata(publicKey)` — UNAUTHENTICATED branding lookup by
+//     `pk_live_...`. Backed by the existing public endpoint
+//     `GET /apps/public/:publicKey` (AGF-070f-pk). Used for the
+//     frontend/widget case where only the public key is known.
+//   - `me()` / `connectors.list()` — self-metadata for the App the client
+//     authenticated AS (via `sk_live_` in `appSecret`). Backed by
+//     `GET /apps/me` and `GET /apps/me/connectors` (AGF-070 §6 backend).
+//     The client's `appSecret` is sent automatically on the
+//     `Authorization: Bearer` header, so the server's `ApiKeyGuard` resolves
+//     the calling App and returns ONLY that App — no id/tenant param needed.
+//
+// Auth: `publicMetadata` is unauthenticated (the endpoint is `@Public()`).
+// `me()`/`connectors.list()` require the client to have been constructed with
+// `appSecret` (`sk_live_...`); without it the server answers 401.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppsResource = void 0;
+class AppsResource {
+    constructor(client) {
+        this.client = client;
+        this.connectors = {
+            /**
+             * `GET /apps/me/connectors` — connectors resolved for the App this client
+             * authenticated AS, with the same whitelist-vs-legacy `mode` the
+             * tenant-admin surface returns. Only `enabled` rows are actually usable
+             * by the App at runtime.
+             */
+            list: async () => {
+                return this.client.request('GET', '/apps/me/connectors');
+            },
+        };
+    }
+    /**
+     * `GET /apps/public/:publicKey` — UNAUTHENTICATED branding for a published
+     * App, looked up by its public key (`pk_live_...`). Returns only
+     * name/description/logo/cover — never any secret material or status.
+     *
+     * Resolves ONLY for a published, non-revoked App addressed by its
+     * `pk_live_` key; every other case (unknown key, `pk_test_`, draft,
+     * revoked, malformed) maps to a single opaque **404** →
+     * `AgentForgeNotFoundError`, so a caller cannot distinguish "doesn't
+     * exist" from "exists but not published".
+     *
+     * @example
+     *   const app = await af.apps.publicMetadata('pk_live_abc…');
+     *   renderHeader(app.name, app.logoUrl);
+     */
+    async publicMetadata(publicKey) {
+        return this.client.request('GET', `/apps/public/${encodeURIComponent(publicKey)}`);
+    }
+    /**
+     * `GET /apps/me` — metadata of the App this client authenticated AS (via
+     * `sk_live_` in `appSecret`). Returns branding + status + credential
+     * prefixes only — never the plaintext secret or its hash.
+     *
+     * Requires the client to have an `appSecret`. A `pk_test_`/draft App's
+     * `sk_live_` is rejected upstream (403 `not_published`); a client with no
+     * `appSecret` gets 401.
+     *
+     * @example
+     *   const me = await af.apps.me();
+     *   if (me.status !== 'published') warnAuthorTheirAppIsDraft();
+     */
+    async me() {
+        return this.client.request('GET', '/apps/me');
+    }
+}
+exports.AppsResource = AppsResource;

package/dist/types.d.ts

@@ -42,6 +42,48 @@ export interface AgentMe {
     updatedAt: string | Date;
     externalTools: ExternalToolSummary[];
 }
+export interface PublicAppBranding {
+    name: string;
+    description: string | null;
+    logoUrl: string | null;
+    coverUrl: string | null;
+}
+export interface AppSelf {
+    id: string;
+    name: string;
+    description: string | null;
+    logoUrl: string | null;
+    coverUrl: string | null;
+    content: string | null;
+    status: 'draft' | 'published';
+    publicKey: string;
+    apiSecretPrefix: string;
+    publicKeyTest: string | null;
+    apiSecretTestPrefix: string | null;
+    revokedAt: string | null;
+    lastUsedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AppSelfConnector {
+    connectorId: string;
+    name: string;
+    iconUrl?: string;
+    /** Available to this App via the tenant's connected connectors. */
+    available: boolean;
+    /** Enabled for this App (whitelist row `enabled`, or `available` when the
+     *  App has no whitelist rows and falls back to legacy allow-all). */
+    enabled: boolean;
+    /** The App has a per-tool permission override for this connector. */
+    hasOverride: boolean;
+}
+export interface AppSelfConnectors {
+    /** `'whitelist'` — the App has >=1 explicit row; only `enabled` counts.
+     *  `'legacy'` — zero rows, every tenant-connected connector is implicitly
+     *  available. */
+    mode: 'whitelist' | 'legacy';
+    connectors: AppSelfConnector[];
+}
 export interface RegisterToolInput {
     name: string;
     description: string;

package/package.json

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