@aui.io/aui-client 3.1.2 → 3.2.0

package/README.md

@@ -13,46 +13,43 @@ npm install @aui.io/aui-client
 
 ## Authentication
 
-The SDK authenticates with a **publishable key** or an **organization API key** — you never manage bearer tokens yourself.
+There are two clients, one per credential flow — you never manage bearer tokens yourself. Each client exposes only the resources for its surface; pick the one that matches your environment (you can use both).
 
-- **Publishable key** (`pk_network_…` for a single agent, or `pk_org_…` for an organization): exchanged automatically at `POST /management/v1/auth/token` for a short-lived bearer token that is cached and refreshed transparently.
-- **Organization API key**: used directly as the bearer token.
+| Client | Credential | Resources | Browser-safe |
+| --- | --- | --- | --- |
+| `ApolloMessagingClient` | Publishable key (`pk_network_…` / `pk_org_…`) | `messaging`, `channels`, WebSocket sessions | **Yes** |
+| `ApolloManagementClient` | Organization API key | `projects`, `agents`, `agentVersions`, `threads` | **No** — server-side only |
 
-Pass exactly one of them:
+- **`ApolloMessagingClient`** exchanges the publishable key automatically at `POST /management/v1/auth/token` for a short-lived bearer token that is cached and refreshed transparently, and sent as `Authorization: Bearer …`.
+- **`ApolloManagementClient`** sends the organization API key on every request as the `x-organization-api-key` header — there is no token exchange, caching, or refresh.
 
 ```typescript
-import { ApolloClient } from '@aui.io/aui-client';
+import { ApolloMessagingClient, ApolloManagementClient } from '@aui.io/aui-client';
 
-// With a publishable key (recommended for client / agent-scoped use)
-const client = new ApolloClient({
+// Browser / widget / end-user (publishable key)
+const messaging = new ApolloMessagingClient({
     publishableKey: 'pk_network_xxxxxxxxxxxxxxxxxxxxxxxx',
 });
 
-// Or with an organization API key
-const orgClient = new ApolloClient({
+// Backend / CI (organization API key — never ship this to the browser)
+const management = new ApolloManagementClient({
     organizationApiKey: 'YOUR_ORG_API_KEY',
 });
 ```
 
 ## Quick Start
 
+Messaging (publishable key) — the agent is derived from the key, so you don't pass it:
+
 ```typescript
-import { ApolloClient } from '@aui.io/aui-client';
+import { ApolloMessagingClient } from '@aui.io/aui-client';
 
-const client = new ApolloClient({
+const messaging = new ApolloMessagingClient({
     publishableKey: 'pk_network_xxxxxxxxxxxxxxxxxxxxxxxx',
 });
 
-// List projects, then the agents in the first project
-const projects = await client.projects.listProjects();
-const projectId = projects.results[0].id;
-
-const agents = await client.agents.listAgents(projectId, { filters: {} });
-const agentId = agents.results[0].id;
-
 // Send a message (creates a thread if thread_id is omitted)
-const response = await client.messaging.sendMessage({
-    agent_id: agentId,
+const response = await messaging.messaging.sendMessage({
     user_id: 'end-user-123',
     text: 'Hello from the SDK',
 });
@@ -60,82 +57,203 @@ const response = await client.messaging.sendMessage({
 console.log('Thread:', response.thread_id);
 ```
 
+Management (organization API key, server-side only):
+
+```typescript
+import { ApolloManagementClient } from '@aui.io/aui-client';
+
+const management = new ApolloManagementClient({
+    organizationApiKey: 'YOUR_ORG_API_KEY',
+});
+
+const projects = await management.projects.listProjects();
+const projectId = projects.results[0].id;
+
+const agents = await management.agents.listAgents(projectId, { filters: {} });
+```
+
 ## Configuration
 
-The `ApolloClient` constructor accepts:
+Each client takes its credential:
 
 ```typescript
-interface ApolloClient.Options {
-    environment?: ApolloEnvironment;  // Defaults to ApolloEnvironment.Gcp
-    publishableKey?: string;          // pk_network_… or pk_org_…
-    organizationApiKey?: string;      // Organization API key
+interface ApolloMessagingClient.Options {
+    publishableKey: string;       // pk_network_… or pk_org_…
+}
+
+interface ApolloManagementClient.Options {
+    organizationApiKey: string;   // server-side only
 }
 ```
 
-### Environments
+## REST API
+
+Resources are split by surface: messaging resources live on `ApolloMessagingClient`, management resources on `ApolloManagementClient`. All list endpoints are paginated and return `{ results, meta }`, where `meta.has_more` indicates further pages.
+
+### Messaging client (`ApolloMessagingClient`)
+
+#### Messaging — `messaging.messaging`
+
+Full method list:
+
+| Method | Description |
+| --- | --- |
+| `sendMessage(request)` | Send a message and get the full reply. Omit `thread_id` to start a new thread. |
+| `streamMessage(request)` | Same as `sendMessage`, but streams the reply token-by-token over Server-Sent Events. |
+| `rerun(threadId, request)` | Re-run the latest turn of a thread. |
+| `listMessages(threadId)` | The thread transcript, scoped to the key's agent. |
+| `threadTrace(threadId)` | Reasoning trace for every interaction in a thread. |
+| `interactionTrace(interactionId)` | Reasoning trace for a single interaction. |
+| `getWelcomeMessage()` | The agent's welcome message (from its live version). |
+| `generateFollowupSuggestions(request)` | Suggested follow-up prompts from a context you provide. |
 
 ```typescript
-import { ApolloEnvironment } from '@aui.io/aui-client';
+// Send a message. Omit thread_id to start a new thread. The agent rides the key,
+// so it isn't passed in the body.
+const res = await messaging.messaging.sendMessage({
+    user_id: 'end-user-123',
+    text: 'What can you help me with?',
+    // thread_id: existingThreadId,
+    // Optional per-message values for the agent's configured context variables:
+    // agent_variables: { static: { customer_name: 'Ada' }, dynamic: { order_id: 'ORD-1042' } },
+});
+console.log('Thread:', res.thread_id);
 
-ApolloEnvironment.Gcp = {
-    base: 'https://api-v3.aui.io/apollo-api-v2',        // REST
-    production: 'wss://api-v3.aui.io/apollo-api-v2',    // WebSocket
-};
-```
+// Stream the reply instead (Server-Sent Events)
+const stream = await messaging.messaging.streamMessage({ user_id: 'end-user-123', text: 'Tell me a story' });
+for await (const event of stream) {
+    console.log(event);
+}
 
-`environment` defaults to `ApolloEnvironment.Gcp`, so most callers only need to pass a key.
+// Re-run the latest turn of a thread
+const rerun = await messaging.messaging.rerun(res.thread_id, { user_id: 'end-user-123' });
 
-## REST API
+// Read the transcript and traces
+const messages = await messaging.messaging.listMessages(res.thread_id);
+const traces = await messaging.messaging.threadTrace(res.thread_id);
+const one = await messaging.messaging.interactionTrace(interactionId);
+
+// Welcome message (from the agent's live version) — open a conversation UI before the first turn
+const { welcome_message } = await messaging.messaging.getWelcomeMessage();
 
-Resources are grouped on the client. All list endpoints are paginated and return `{ results, meta }`, where `meta.has_more` indicates further pages.
+// Follow-up suggestions generated from a context you provide
+const { suggestions } = await messaging.messaging.generateFollowupSuggestions({
+    context: { topic: 'order tracking' },
+});
+```
 
-### Projects — `client.projects`
+#### Channels — `messaging.channels`
+
+| Method | Description |
+| --- | --- |
+| `initiateThread(channel, request)` | Send the opening message on an outbound channel (`'sms'` / `'whatsapp'`) and bind the recipient to a thread. |
 
 ```typescript
-const page = await client.projects.listProjects();       // { results, meta }
-const project = await client.projects.getProject(projectId);
-const usage = await client.projects.getProjectUsage(projectId);
+// Start a channel-scoped thread (e.g. SMS opener). The agent rides the key, so it isn't
+// passed in the body. Use 'whatsapp' for WhatsApp.
+const sms = await messaging.channels.initiateThread('sms', {
+    phone_number: '+14155551234',
+    user_id: 'end-user-123',
+    text: 'Hello from the SDK',
+    // thread_id: existingThreadId, // omit to start a new thread
+});
+console.log('Thread:', sms.thread_id);
 ```
 
-### Agents — `client.agents`
+### Management client (`ApolloManagementClient`)
+
+#### Projects — `management.projects`
+
+| Method | Description |
+| --- | --- |
+| `listProjects()` | List the org's projects (paginated). |
+| `createProject(request)` | Create a project. |
+| `getProject(projectId)` | Fetch one project. |
+| `deleteProject(projectId)` | Delete a project. |
+| `getProjectUsage(projectId)` | Usage metrics aggregated across the project. |
 
 ```typescript
-const page = await client.agents.listAgents(projectId, { filters: {} });
-const agent = await client.agents.getAgent(agentId);      // agent.live_version_id, …
-const usage = await client.agents.getAgentUsage(agentId);
+const page = await management.projects.listProjects();       // { results, meta }
+const project = await management.projects.createProject({ name: 'My project' });
+const fetched = await management.projects.getProject(project.id);
+const usage = await management.projects.getProjectUsage(project.id);
+await management.projects.deleteProject(project.id);
 ```
 
-### Threads — `client.threads`
+#### Agents — `management.agents`
+
+| Method | Description |
+| --- | --- |
+| `listAgents(projectId, { filters })` | List a project's agents (paginated). |
+| `createAgent(projectId, request)` | Create an agent (starts with no live version). |
+| `getAgent(agentId)` | Fetch one agent, incl. its live version. |
+| `updateAgent(agentId, request)` | Rename an agent. |
+| `deleteAgent(agentId)` | Delete an agent and all its versions. |
+| `getAgentUsage(agentId)` | Usage metrics for one agent. |
 
 ```typescript
-const page = await client.threads.listThreads({ filters: {} });
-const thread = await client.threads.getThread(threadId);
-const messages = await client.threads.getThreadMessages(threadId);
-const trace = await client.threads.getThreadTrace(threadId);
+const page = await management.agents.listAgents(projectId, { filters: {} });
+const agent = await management.agents.createAgent(projectId, { name: 'Support bot' });
+const fetched = await management.agents.getAgent(agent.id);   // fetched.live_version_id, …
+await management.agents.updateAgent(agent.id, { name: 'Support bot v2' });
+const usage = await management.agents.getAgentUsage(agent.id);
+await management.agents.deleteAgent(agent.id);
 ```
 
-### Messaging — `client.messaging`
+#### Agent versions — `management.agentVersions`
+
+| Method | Description |
+| --- | --- |
+| `listVersions(agentId, { filters })` | List an agent's versions, newest first. |
+| `createVersion(agentId, request)` | Create a draft version (empty, from a template, or cloned). |
+| `updateVersion(agentId, versionId, request)` | Update a version's metadata (label, tags, notes). |
+| `pushVersion(agentId, versionId, request)` | Push a config bundle, committing a new revision. |
+| `pullVersion(agentId, versionId, request?)` | Download a version's config bundle. |
+| `publishVersion(agentId, versionId)` | Make a version the agent's live version. |
+| `archiveVersion(agentId, versionId)` | Archive (retire) a version. |
 
 ```typescript
-// Send a message. Omit thread_id to start a new thread.
-const res = await client.messaging.sendMessage({
-    agent_id: agentId,
-    user_id: 'end-user-123',
-    text: 'What can you help me with?',
-    // thread_id: existingThreadId,
-});
-console.log('Thread:', res.thread_id);
+const versions = await management.agentVersions.listVersions(agentId, { filters: {} });
+const draft = await management.agentVersions.createVersion(agentId, {});
+await management.agentVersions.updateVersion(agentId, draft.id, { label: 'v1' });
+await management.agentVersions.pushVersion(agentId, draft.id, { /* config bundle */ });
+const bundle = await management.agentVersions.pullVersion(agentId, draft.id);
+await management.agentVersions.publishVersion(agentId, draft.id);
+await management.agentVersions.archiveVersion(agentId, draft.id);
+```
+
+#### Threads — `management.threads`
 
-// List the messages in a thread
-const messages = await client.messaging.listMessages(res.thread_id);
+| Method | Description |
+| --- | --- |
+| `listThreads({ filters })` | List the org's threads, newest first (paginated). |
+| `getThread(threadId)` | Fetch one thread. |
+| `updateThread(threadId, request)` | Update a thread (currently `title`). |
+| `getThreadMessages(threadId)` | The thread's full transcript. |
+| `getThreadTrace(threadId)` | Reasoning trace for every interaction in the thread. |
+| `getInteractionTrace(interactionId)` | Reasoning trace for a single interaction. |
+
+`filters` supports `project_id`, `agent_id`, `user_id`, `external_id`, `created` (range), `tool`, `rule`, and `param`. Prefer a filter (e.g. `project_id`) over `{}` — the unfiltered list sorts every thread in the org and can be slow.
+
+```typescript
+const page = await management.threads.listThreads(
+    { filters: { project_id: projectId } },
+    { timeoutInSeconds: 120 }, // this endpoint can be slow; give it headroom
+);
+const thread = await management.threads.getThread(threadId);
+const updated = await management.threads.updateThread(threadId, { title: 'Renamed conversation' });
+const messages = await management.threads.getThreadMessages(threadId);
+const trace = await management.threads.getThreadTrace(threadId);
+const one = await management.threads.getInteractionTrace(interactionId);
 ```
 
 ## WebSocket Messaging
 
-`client.connect()` opens a real-time session. The bearer token is resolved and attached to the upgrade automatically.
+`connect()` opens a real-time session and is available on **`ApolloMessagingClient`** only (WebSocket messaging is publishable-key territory). The bearer token is attached to the upgrade automatically — it's passed as the first WebSocket subprotocol, which is the one credential channel browsers allow, so this works in the browser as well as in Node.
 
 ```typescript
-const socket = await client.connect();
+const messaging = new ApolloMessagingClient({ publishableKey: 'pk_network_…' });
+const socket = await messaging.connect();
 await socket.waitForOpen();
 
 socket.on('message', (msg) => {
@@ -152,32 +270,41 @@ socket.sendSubmitMessage({
     text: 'Hello over WebSocket',
 });
 
+// Resume a dropped stream
+socket.sendResume({ /* ResumeRequest */ });
+
 // When done
 socket.close();
 ```
 
+The socket (`SessionSocket`) exposes: `waitForOpen()`, `on(event, handler)` (events: `open`, `message`, `error`, `close`), `sendSubmitMessage(request)`, `sendResume(request)`, and `close()`.
+
 > **Notes**
 > - `socket.on(event, handler)` registers a **single** handler per event — calling it
 >   again for the same event replaces the previous handler rather than adding one.
 > - The socket type is exported as `SessionSocket` (`import { SessionSocket } from '@aui.io/aui-client'`).
 > - Request timeouts are **per call** via `timeoutInSeconds` on a request's options; there
 >   is no client-wide default timeout. Pass it on slow calls, e.g.
->   `client.threads.listThreads({ filters: {} }, { timeoutInSeconds: 120 })`.
+>   `management.threads.listThreads({ filters: {} }, { timeoutInSeconds: 120 })`.
 
 ## Key Context Helpers
 
-After the first request (or an explicit `getContext()`), scope resolved from the key is available:
+On **`ApolloMessagingClient`**, after the first request (or an explicit `getContext()`), the scope resolved from the publishable key is available:
 
 ```typescript
-console.log(client.keyType);        // 'agent' | 'org' | 'unknown'
+const messaging = new ApolloMessagingClient({ publishableKey: 'pk_network_…' });
+
+console.log(messaging.keyType);        // 'agent' | 'org' | 'unknown'
 
-const ctx = await client.getContext();
+const ctx = await messaging.getContext();
 console.log(ctx.agentId, ctx.organizationId, ctx.keyType);
 
-client.agentId;         // populated once a token has been exchanged
-client.organizationId;
+messaging.agentId;         // populated once a token has been exchanged
+messaging.organizationId;
 ```
 
+`ApolloManagementClient` proves only the organization (resolved server-side by the gateway), so it has no key-context helpers.
+
 ## Error Handling
 
 `ApolloError` (the base API error) and `ApolloTimeoutError` are exported at the top
@@ -188,7 +315,7 @@ namespace.
 import { ApolloError, Apollo } from '@aui.io/aui-client';
 
 try {
-    await client.agents.getAgent('missing-id');
+    await management.agents.getAgent('missing-id');
 } catch (error) {
     if (error instanceof Apollo.UnprocessableEntityError) {
         console.error('Validation failed:', error.body);
@@ -205,7 +332,7 @@ try {
 The SDK ships full type definitions. Models are namespaced under `Apollo`:
 
 ```typescript
-import { ApolloClient, Apollo } from '@aui.io/aui-client';
+import { Apollo } from '@aui.io/aui-client';
 
 const req: Apollo.SubmitMessageRequest = {
     type: 'message',

package/dist/cjs/ApolloClientWrapper.d.ts

@@ -2,30 +2,41 @@ import { ApolloClient as _GeneratedClient } from "./Client.js";
 import type { ApolloEnvironmentUrls } from "./environments.js";
 import { SessionSocket } from "./api/resources/session/client/Socket.js";
 import type { Session } from "./api/resources/session/client/Client.js";
+import type { Messaging } from "./api/resources/messaging/client/Client.js";
+import type { Channels } from "./api/resources/channels/client/Client.js";
+import type { Projects } from "./api/resources/projects/client/Client.js";
+import type { Agents } from "./api/resources/agents/client/Client.js";
+import type { AgentVersions } from "./api/resources/agentVersions/client/Client.js";
+import type { Threads } from "./api/resources/threads/client/Client.js";
 /** Publishable-key family, inferred from the key prefix. */
 export type PublishableKeyType = "agent" | "org" | "unknown";
-export declare namespace ApolloClient {
+type AuthHeaders = Record<string, string | (() => Promise<string>) | null>;
+declare class BaseApolloClient {
+    protected readonly _client: _GeneratedClient;
+    protected readonly _env: ApolloEnvironmentUrls;
+    constructor(env: ApolloEnvironmentUrls, authHeaders: AuthHeaders);
+}
+export declare namespace ApolloMessagingClient {
     interface Options {
-        /** Deployment environment. Defaults to ApolloEnvironment.Gcp. */
-        environment?: ApolloEnvironmentUrls;
-        /** Publishable key (pk_network_ or pk_org_); exchanged for a bearer token. */
-        publishableKey?: string;
-        /** Organization API key; used directly as the bearer token. */
-        organizationApiKey?: string;
+        /** Publishable key (pk_network_ / pk_org_). */
+        publishableKey: string;
+        /** Internal: override the API host. Defaults to production. */
+        baseUrl?: string;
     }
     interface ConnectArgs extends Session.ConnectArgs {
     }
 }
 /**
- * ApolloClient adds authentication on top of the generated client: it takes a
- * publishable key (or organization API key) and handles the token exchange/refresh
- * transparently. Every generated resource (agents, threads, messaging, …) is
- * inherited unchanged.
+ * Publishable-key client for end-user / widget messaging (browser-safe).
+ * Exposes the `messaging` audience only.
  */
-export declare class ApolloClient extends _GeneratedClient {
-    private readonly _tokenAuth;
-    private readonly _env;
-    constructor(options?: ApolloClient.Options);
+export declare class ApolloMessagingClient extends BaseApolloClient {
+    private readonly _pkAuth;
+    constructor(options: ApolloMessagingClient.Options);
+    /** Send / stream messages and read thread & interaction traces. */
+    get messaging(): Messaging;
+    /** Initiate channel-scoped threads (e.g. SMS). */
+    get channels(): Channels;
     /** Publishable-key family (agent / org / unknown). */
     get keyType(): PublishableKeyType;
     /** Agent resolved from an agent-scoped key. Populated after the first exchange. */
@@ -38,13 +49,30 @@ export declare class ApolloClient extends _GeneratedClient {
         organizationId?: string;
         keyType: PublishableKeyType;
     }>;
-    /**
-     * Open a messaging WebSocket session. The bearer token is passed as the first
-     * subprotocol (with `aui-websocket` second) — the gateway reads auth from
-     * Sec-WebSocket-Protocol, the only upgrade header a browser can set. The token is
-     * also sent as an Authorization header for Node. Built here (rather than via the
-     * generated session resource) so the generated code stays vanilla — Fern emits
-     * protocols: [] and forwards only per-call headers, neither of which the server accepts.
-     */
-    connect(args?: ApolloClient.ConnectArgs): Promise<SessionSocket>;
+    /** Open a messaging WebSocket session. */
+    connect(args?: ApolloMessagingClient.ConnectArgs): Promise<SessionSocket>;
+}
+export declare namespace ApolloManagementClient {
+    interface Options {
+        /** Organization API key. Server-side only. */
+        organizationApiKey: string;
+        /** Internal: override the API host. Defaults to production. */
+        baseUrl?: string;
+    }
+}
+/**
+ * Organization-API-key client for backend services and CI (server-side only).
+ * Exposes the `management` audience only.
+ */
+export declare class ApolloManagementClient extends BaseApolloClient {
+    constructor(options: ApolloManagementClient.Options);
+    /** Projects: listing, retrieval, and usage. */
+    get projects(): Projects;
+    /** Agents: listing, retrieval, and usage. */
+    get agents(): Agents;
+    /** Agent versions. */
+    get agentVersions(): AgentVersions;
+    /** Threads: listing, retrieval, updates, and traces. */
+    get threads(): Threads;
 }
+export {};