@agentforge-io/sdk-server 4.0.21 → 4.1.0

package/dist/client.d.ts

@@ -2,6 +2,7 @@ import { AgentsResource } from './resources/agents';
 import { AppsResource } from './resources/apps';
 import { ChatResource } from './resources/chat';
 import { ConnectorsResource } from './resources/connectors';
+import { ProvisioningResource } from './resources/provisioning';
 import { SecretsResource } from './resources/secrets';
 import { ToolsResource } from './resources/tools';
 export interface AgentForgeClientOptions {
@@ -18,6 +19,13 @@ export interface AgentForgeClientOptions {
      *  header as `apiKey`; the server's ApiKeyGuard accepts both `ak_live_`
      *  and `sk_live_` prefixes. */
     appSecret?: string;
+    /** Machine-to-machine host provisioning secret (`HOST_PROVISIONING_SECRET`).
+     *  UNLIKE the other three, this is NOT a per-tenant/App credential — it's the
+     *  shared secret a trusted host (ScrappyDoc) uses to provision tenants/Apps
+     *  via `af.provisioning.*` (`POST /platform/host-tenants` / `host-apps`). It
+     *  travels on the `x-provisioning-secret` header, never `Authorization`. A
+     *  client built with only this can ONLY call the provisioning surface. */
+    provisioningSecret?: string;
     /** Override fetch (for testing or custom transports). */
     fetch?: typeof fetch;
     /** Default request timeout in ms. Applied to every HTTP call unless
@@ -46,17 +54,23 @@ export declare class AgentForgeClient {
     private readonly chatToken?;
     private readonly apiKey?;
     private readonly appSecret?;
+    private readonly provisioningSecret?;
     private readonly fetchImpl;
     private readonly timeoutMs;
     readonly agents: AgentsResource;
     readonly apps: AppsResource;
     readonly chat: ChatResource;
     readonly connectors: ConnectorsResource;
+    readonly provisioning: ProvisioningResource;
     readonly secrets: SecretsResource;
     readonly tools: ToolsResource;
     constructor(opts: AgentForgeClientOptions);
     authHeaders(): Record<string, string>;
     getAppSecret(): string | undefined;
+    /** The `x-provisioning-secret` header value, or throws if the client wasn't
+     *  built with one — used by `ProvisioningResource`, whose every call needs
+     *  it (there is no other auth for the provisioning surface). */
+    requireProvisioningSecret(): string;
     getApiKey(): string | undefined;
     getChatToken(): string | undefined;
     /** Como `getApiKey()`, pero tira si el cliente no fue construido con una

package/dist/client.js

@@ -24,6 +24,7 @@ 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 provisioning_1 = require("./resources/provisioning");
 const secrets_1 = require("./resources/secrets");
 const tools_1 = require("./resources/tools");
 class AgentForgeClient {
@@ -31,19 +32,25 @@ class AgentForgeClient {
         if (!opts.baseURL) {
             throw new Error('AgentForgeClient: baseURL is required');
         }
-        if (!opts.chatToken && !opts.apiKey && !opts.appSecret) {
-            throw new Error('AgentForgeClient: one of chatToken, apiKey, or appSecret is required');
+        if (!opts.chatToken &&
+            !opts.apiKey &&
+            !opts.appSecret &&
+            !opts.provisioningSecret) {
+            throw new Error('AgentForgeClient: one of chatToken, apiKey, appSecret, or ' +
+                'provisioningSecret is required');
         }
         this.baseURL = opts.baseURL.replace(/\/$/, '');
         this.chatToken = opts.chatToken;
         this.apiKey = opts.apiKey;
         this.appSecret = opts.appSecret;
+        this.provisioningSecret = opts.provisioningSecret;
         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.provisioning = new provisioning_1.ProvisioningResource(this);
         this.secrets = new secrets_1.SecretsResource(this);
         this.tools = new tools_1.ToolsResource(this);
     }
@@ -63,6 +70,16 @@ class AgentForgeClient {
     getAppSecret() {
         return this.appSecret;
     }
+    /** The `x-provisioning-secret` header value, or throws if the client wasn't
+     *  built with one — used by `ProvisioningResource`, whose every call needs
+     *  it (there is no other auth for the provisioning surface). */
+    requireProvisioningSecret() {
+        if (!this.provisioningSecret) {
+            throw new Error('AgentForgeClient: this call requires a provisioningSecret ' +
+                '(HOST_PROVISIONING_SECRET), but the client was constructed without one.');
+        }
+        return this.provisioningSecret;
+    }
     // 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

@@ -9,6 +9,8 @@ export { ChatResource } from './resources/chat';
 export type { AnthropicClientOptions, StreamMessageInput } from './resources/chat';
 export { ConnectorsResource } from './resources/connectors';
 export type { InboxChannelView } from './resources/connectors';
+export { ProvisioningResource } from './resources/provisioning';
+export type { ProvisionedTenant, ProvisionedApp, } from './resources/provisioning';
 export { SecretsResource } from './resources/secrets';
 export { ToolsResource } from './resources/tools';
 export type { RespondToCallbackInput, VerifyCallbackInput } from './resources/tools';

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.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.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");
@@ -49,6 +49,8 @@ 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 provisioning_1 = require("./resources/provisioning");
+Object.defineProperty(exports, "ProvisioningResource", { enumerable: true, get: function () { return provisioning_1.ProvisioningResource; } });
 var secrets_1 = require("./resources/secrets");
 Object.defineProperty(exports, "SecretsResource", { enumerable: true, get: function () { return secrets_1.SecretsResource; } });
 var tools_1 = require("./resources/tools");

package/dist/resources/chat.d.ts

@@ -9,6 +9,20 @@ export interface StreamMessageInput {
     /** Si se omite, el server crea una conversación nueva. */
     conversationId?: string;
 }
+export interface StreamMessageForAppUserInput {
+    /** Which of the App's tenant agents to run. */
+    agentId: string;
+    /** The App's own identifier for its end user — NOT signed, rides as a
+     *  plain param inside the sk_live_-authenticated request (AGF-072 §4.4
+     *  rationale: the authenticated channel is the proof, not a per-user
+     *  signature). Threads into the conversation key
+     *  `app-user:${appId}:${externalUserId}` server-side; `appId` itself is
+     *  never a param, only ever resolved from the secret. */
+    externalUserId: string;
+    content: string;
+    /** Si se omite, el server crea una conversación nueva. */
+    conversationId?: string;
+}
 export declare class ChatResource {
     private readonly client;
     constructor(client: AgentForgeClient);
@@ -52,4 +66,37 @@ export declare class ChatResource {
      * no pertenece al ChatToken que llama.
      */
     getHistory(conversationId: string): Promise<ConversationHistory>;
+    /**
+     * AGF-073a — chat streaming AGENT-AWARE para el surface App-authenticated
+     * (`sk_live_`/`sk_test_`), server-to-server — `POST
+     * /api/v1/app-user-chat/conversations/stream` (o `.../conversations/:id/
+     * messages/stream` cuando `input.conversationId` viene seteado). Sibling
+     * ADITIVO de `streamMessage()`: NO usa ChatToken, requiere que el
+     * `AgentForgeClient` se haya construido con `appSecret`. `appId` lo
+     * resuelve el server exclusivamente del secret — nunca es un param acá
+     * tampoco (ver `APP_USER_CHAT_RUNTIME_SDD.md`).
+     *
+     * Mismo shape de eventos que `streamMessage()` — `ChatStreamEvent` con
+     * los mismos `kind`s (`conversation` | `chunk` | `stream_end` | `error`).
+     * Un consumidor no puede distinguir cuál de los dos métodos produjo el
+     * stream a partir de los eventos solos.
+     *
+     * @example
+     *   const af = new AgentForgeClient({ baseURL, appSecret: 'sk_live_...' });
+     *   for await (const ev of af.chat.streamMessageForAppUser({
+     *     agentId: 'agent-uuid',
+     *     externalUserId: 'scrappydoc-user-42',
+     *     content: 'hola',
+     *   })) {
+     *     if (ev.kind === 'conversation') conversationId = ev.conversationId;
+     *   }
+     */
+    streamMessageForAppUser(input: StreamMessageForAppUserInput): AsyncGenerator<ChatStreamEvent>;
+    /**
+     * AGF-073a companion to `streamMessageForAppUser` — historial completo de
+     * una conversación app-user, `GET /api/v1/app-user-chat/conversations/:id/
+     * messages?externalUserId=...`. `externalUserId` va como query param
+     * porque GET no lleva body; `appId` sigue resolviéndose del secret.
+     */
+    getHistoryForAppUser(conversationId: string, externalUserId: string): Promise<ConversationHistory>;
 }

package/dist/resources/chat.js

@@ -110,6 +110,86 @@ class ChatResource {
     async getHistory(conversationId) {
         return this.client.request('GET', `/api/v1/chat/conversations/${encodeURIComponent(conversationId)}/messages`);
     }
+    /**
+     * AGF-073a — chat streaming AGENT-AWARE para el surface App-authenticated
+     * (`sk_live_`/`sk_test_`), server-to-server — `POST
+     * /api/v1/app-user-chat/conversations/stream` (o `.../conversations/:id/
+     * messages/stream` cuando `input.conversationId` viene seteado). Sibling
+     * ADITIVO de `streamMessage()`: NO usa ChatToken, requiere que el
+     * `AgentForgeClient` se haya construido con `appSecret`. `appId` lo
+     * resuelve el server exclusivamente del secret — nunca es un param acá
+     * tampoco (ver `APP_USER_CHAT_RUNTIME_SDD.md`).
+     *
+     * Mismo shape de eventos que `streamMessage()` — `ChatStreamEvent` con
+     * los mismos `kind`s (`conversation` | `chunk` | `stream_end` | `error`).
+     * Un consumidor no puede distinguir cuál de los dos métodos produjo el
+     * stream a partir de los eventos solos.
+     *
+     * @example
+     *   const af = new AgentForgeClient({ baseURL, appSecret: 'sk_live_...' });
+     *   for await (const ev of af.chat.streamMessageForAppUser({
+     *     agentId: 'agent-uuid',
+     *     externalUserId: 'scrappydoc-user-42',
+     *     content: 'hola',
+     *   })) {
+     *     if (ev.kind === 'conversation') conversationId = ev.conversationId;
+     *   }
+     */
+    async *streamMessageForAppUser(input) {
+        if (!this.client.getAppSecret()) {
+            throw new Error('chat.streamMessageForAppUser requires appSecret (sk_live_/sk_test_) in ' +
+                'AgentForgeClient. This surface authenticates AS the App, not via chatToken.');
+        }
+        const path = input.conversationId
+            ? `/api/v1/app-user-chat/conversations/${encodeURIComponent(input.conversationId)}/messages/stream`
+            : '/api/v1/app-user-chat/conversations/stream';
+        const res = await this.client.requestStream('POST', path, {
+            agentId: input.agentId,
+            externalUserId: input.externalUserId,
+            content: input.content,
+        });
+        if (!res.body) {
+            throw new Error('chat.streamMessageForAppUser: response has no readable body');
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let idx;
+                while ((idx = buffer.indexOf('\n\n')) !== -1) {
+                    const frame = buffer.slice(0, idx);
+                    buffer = buffer.slice(idx + 2);
+                    const raw = parseRawSseFrame(frame);
+                    if (!raw)
+                        continue;
+                    const event = toChatStreamEvent(raw);
+                    if (event)
+                        yield event;
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    /**
+     * AGF-073a companion to `streamMessageForAppUser` — historial completo de
+     * una conversación app-user, `GET /api/v1/app-user-chat/conversations/:id/
+     * messages?externalUserId=...`. `externalUserId` va como query param
+     * porque GET no lleva body; `appId` sigue resolviéndose del secret.
+     */
+    async getHistoryForAppUser(conversationId, externalUserId) {
+        if (!this.client.getAppSecret()) {
+            throw new Error('chat.getHistoryForAppUser requires appSecret (sk_live_/sk_test_) in AgentForgeClient.');
+        }
+        return this.client.request('GET', `/api/v1/app-user-chat/conversations/${encodeURIComponent(conversationId)}/messages` +
+            `?externalUserId=${encodeURIComponent(externalUserId)}`);
+    }
 }
 exports.ChatResource = ChatResource;
 /** Frame SSE genérico: `event: <name>\ndata: <line>\ndata: <line>...`.

package/dist/resources/provisioning.d.ts

@@ -0,0 +1,52 @@
+import type { AgentForgeClient } from '../client';
+/** `POST /platform/host-tenants` result — a fresh tenant + its first ak_live_. */
+export interface ProvisionedTenant {
+    tenantId: string;
+    apiKey: string;
+}
+/** `POST /platform/host-apps` result — a published platform App's identity +
+ *  one-time-reveal sk_live_. */
+export interface ProvisionedApp {
+    appId: string;
+    publicKey: string;
+    appSecret: string;
+}
+export declare class ProvisioningResource {
+    private readonly client;
+    constructor(client: AgentForgeClient);
+    private headers;
+    /**
+     * `POST /platform/host-tenants` — create a new tenant and its first
+     * `ak_live_` key on behalf of a trusted host app. Idempotency is the
+     * caller's concern (the host caches the returned `{tenantId, apiKey}`); the
+     * server mints a fresh tenant on every call.
+     *
+     * @param input.name    display name (e.g. the host workspace's name)
+     * @param input.hostApp short host id (e.g. "scrappydoc") — determines the
+     *                       service account that owns the tenant
+     * @param input.hostRef  host reference (e.g. the workspaceId) — traceability
+     */
+    tenant(input: {
+        name: string;
+        hostApp: string;
+        hostRef?: string;
+    }): Promise<ProvisionedTenant>;
+    /**
+     * `POST /platform/host-apps` (AGF-071a) — mint (or re-provision) a PUBLISHED
+     * platform App for an EXISTING tenant. Idempotent by `(tenantId, hostApp,
+     * hostRef)`: a re-provision returns the SAME `appId` with a freshly rotated
+     * `sk_live_` (the one-time-reveal secret may have been lost), never a
+     * duplicate App.
+     *
+     * @param input.tenantId the tenant the App belongs to (host provisions it
+     *                        first via `tenant()`)
+     * @param input.hostApp   short host id (e.g. "scrappydoc")
+     * @param input.hostRef   host reference (e.g. the workspaceId) — part of the
+     *                        idempotency key; defaults server-side to `tenantId`
+     */
+    app(input: {
+        tenantId: string;
+        hostApp: string;
+        hostRef?: string;
+    }): Promise<ProvisionedApp>;
+}

package/dist/resources/provisioning.js

@@ -0,0 +1,55 @@
+"use strict";
+// provisioning resource (AGF-071c) — machine-to-machine host provisioning of
+// tenants and Apps. Lets a trusted host (ScrappyDoc) create a tenant + its
+// ak_live_, and mint a platform App (pk_live_/sk_live_) for that tenant, WITHOUT
+// hand-rolling a fetch — the SDK-first rule applies to provisioning too.
+//
+// Auth: UNLIKE every other resource, these calls don't use a per-tenant/App
+// credential. They authenticate with the shared `HOST_PROVISIONING_SECRET` on
+// the `x-provisioning-secret` header (the client must be built with
+// `provisioningSecret`). The server gates both endpoints with
+// `HostProvisioningGuard`, not `ApiKeyGuard`.
+//
+// These endpoints are `@Public()` on the server (the guard is the secret), so
+// a client built with ONLY `{ baseURL, provisioningSecret }` can call them.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProvisioningResource = void 0;
+class ProvisioningResource {
+    constructor(client) {
+        this.client = client;
+    }
+    headers() {
+        return { 'x-provisioning-secret': this.client.requireProvisioningSecret() };
+    }
+    /**
+     * `POST /platform/host-tenants` — create a new tenant and its first
+     * `ak_live_` key on behalf of a trusted host app. Idempotency is the
+     * caller's concern (the host caches the returned `{tenantId, apiKey}`); the
+     * server mints a fresh tenant on every call.
+     *
+     * @param input.name    display name (e.g. the host workspace's name)
+     * @param input.hostApp short host id (e.g. "scrappydoc") — determines the
+     *                       service account that owns the tenant
+     * @param input.hostRef  host reference (e.g. the workspaceId) — traceability
+     */
+    async tenant(input) {
+        return this.client.request('POST', '/platform/host-tenants', { name: input.name, hostApp: input.hostApp, hostRef: input.hostRef }, { headers: this.headers() });
+    }
+    /**
+     * `POST /platform/host-apps` (AGF-071a) — mint (or re-provision) a PUBLISHED
+     * platform App for an EXISTING tenant. Idempotent by `(tenantId, hostApp,
+     * hostRef)`: a re-provision returns the SAME `appId` with a freshly rotated
+     * `sk_live_` (the one-time-reveal secret may have been lost), never a
+     * duplicate App.
+     *
+     * @param input.tenantId the tenant the App belongs to (host provisions it
+     *                        first via `tenant()`)
+     * @param input.hostApp   short host id (e.g. "scrappydoc")
+     * @param input.hostRef   host reference (e.g. the workspaceId) — part of the
+     *                        idempotency key; defaults server-side to `tenantId`
+     */
+    async app(input) {
+        return this.client.request('POST', '/platform/host-apps', { tenantId: input.tenantId, hostApp: input.hostApp, hostRef: input.hostRef }, { headers: this.headers() });
+    }
+}
+exports.ProvisioningResource = ProvisioningResource;

package/package.json

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