@aui.io/aui-client 3.1.2 → 3.2.1

package/README.md

@@ -1,9 +1,9 @@
 # @aui.io/aui-client
 
 [![npm version](https://img.shields.io/npm/v/@aui.io/aui-client)](https://www.npmjs.com/package/@aui.io/aui-client)
-[![Built with Fern](https://img.shields.io/badge/Built%20with-Fern-brightgreen)](https://buildwithfern.com)
 
-> **Official TypeScript/JavaScript SDK for the AUI Apollo API v2.** REST access to projects, agents, threads, and messaging, plus a real-time WebSocket messaging session.
+Official TypeScript/JavaScript SDK for the AUI Apollo API. Provides REST access to
+messaging, projects, agents, and threads, plus a real-time WebSocket messaging session.
 
 ## Installation
 
@@ -11,220 +11,303 @@
 npm install @aui.io/aui-client
 ```
 
-## Authentication
+## Clients
 
-The SDK authenticates with a **publishable key** or an **organization API key** — you never manage bearer tokens yourself.
+The package exposes two clients, one per credential. Import and use the one that
+matches your environment.
 
-- **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 | Browser | Purpose |
+| --- | --- | --- | --- |
+| `ApolloMessagingClient` | Publishable key (`pk_network_...`) | Yes | End-user messaging and channels |
+| `ApolloManagementClient` | Organization API key | No — server only | Managing projects, agents, versions, and threads |
 
-Pass exactly one of them:
+---
 
-```typescript
-import { ApolloClient } from '@aui.io/aui-client';
+## Messaging
 
-// With a publishable key (recommended for client / agent-scoped use)
-const client = new ApolloClient({
-    publishableKey: 'pk_network_xxxxxxxxxxxxxxxxxxxxxxxx',
-});
+`ApolloMessagingClient` authenticates with a publishable key. It exchanges the key
+for a short-lived access token and refreshes it as needed, so you never handle tokens
+directly. The agent is derived from the key and is not passed in request bodies. The
+client is safe to use in the browser.
 
-// Or with an organization API key
-const orgClient = new ApolloClient({
-    organizationApiKey: 'YOUR_ORG_API_KEY',
+```ts
+import { ApolloMessagingClient } from '@aui.io/aui-client';
+
+const client = new ApolloMessagingClient({
+  publishableKey: 'pk_network_xxxxxxxxxxxxxxxxxxxxxxxx',
 });
 ```
 
-## Quick Start
+### Send a message
 
-```typescript
-import { ApolloClient } from '@aui.io/aui-client';
+Omit `thread_id` to start a new thread, or pass it to continue one.
 
-const client = new ApolloClient({
-    publishableKey: 'pk_network_xxxxxxxxxxxxxxxxxxxxxxxx',
+```ts
+const response = await client.messaging.sendMessage({
+  user_id: 'end-user-123',
+  text: 'What can you help me with?',
+  // thread_id: existingThreadId,
 });
 
-// List projects, then the agents in the first project
-const projects = await client.projects.listProjects();
-const projectId = projects.results[0].id;
+console.log(response.thread_id);
+```
 
-const agents = await client.agents.listAgents(projectId, { filters: {} });
-const agentId = agents.results[0].id;
+You can pass optional per-message values for the agent's configured context variables:
 
-// Send a message (creates a thread if thread_id is omitted)
-const response = await client.messaging.sendMessage({
-    agent_id: agentId,
-    user_id: 'end-user-123',
-    text: 'Hello from the SDK',
+```ts
+await client.messaging.sendMessage({
+  user_id: 'end-user-123',
+  text: 'Where is my order?',
+  agent_variables: {
+    static: { customer_name: 'Ada' },
+    dynamic: { order_id: 'ORD-1042' },
+  },
 });
-
-console.log('Thread:', response.thread_id);
 ```
 
-## Configuration
+### Stream a message
 
-The `ApolloClient` constructor accepts:
+`streamMessage` returns the reply as Server-Sent Events.
 
-```typescript
-interface ApolloClient.Options {
-    environment?: ApolloEnvironment;  // Defaults to ApolloEnvironment.Gcp
-    publishableKey?: string;          // pk_network_… or pk_org_…
-    organizationApiKey?: string;      // Organization API key
+```ts
+const stream = await client.messaging.streamMessage({
+  user_id: 'end-user-123',
+  text: 'Tell me about my account',
+});
+
+for await (const event of stream) {
+  console.log(event);
 }
 ```
 
-### Environments
+### Welcome message and follow-up suggestions
 
-```typescript
-import { ApolloEnvironment } from '@aui.io/aui-client';
+```ts
+const { welcome_message } = await client.messaging.getWelcomeMessage();
 
-ApolloEnvironment.Gcp = {
-    base: 'https://api-v3.aui.io/apollo-api-v2',        // REST
-    production: 'wss://api-v3.aui.io/apollo-api-v2',    // WebSocket
-};
+const { suggestions } = await client.messaging.generateFollowupSuggestions({
+  context: { topic: 'order tracking' },
+});
 ```
 
-`environment` defaults to `ApolloEnvironment.Gcp`, so most callers only need to pass a key.
+### Other messaging methods
+
+| Method | Description |
+| --- | --- |
+| `sendMessage(request)` | Send a message and return the reply. |
+| `streamMessage(request)` | Send a message and stream the reply (SSE). |
+| `rerun(threadId, request)` | Re-run the latest turn of a thread. |
+| `listMessages(threadId)` | Return the messages in a thread. |
+| `threadTrace(threadId)` | Return the reasoning trace for each interaction in a thread. |
+| `interactionTrace(interactionId)` | Return the reasoning trace for a single interaction. |
+| `getWelcomeMessage()` | Return the agent's welcome message. |
+| `generateFollowupSuggestions(request)` | Generate follow-up prompts from a context. |
+
+### Channels (SMS and WhatsApp)
+
+Start an outbound thread on a channel with `channels.initiateThread`. Pass `'sms'`
+or `'whatsapp'` as the channel.
+
+```ts
+const thread = await client.channels.initiateThread('sms', {
+  phone_number: '+14155551234',
+  user_id: 'end-user-123',
+  text: 'Hi! Your order has shipped.',
+  // thread_id: existingThreadId,
+});
 
-## REST API
+console.log(thread.thread_id);
+```
 
-Resources are grouped on the client. All list endpoints are paginated and return `{ results, meta }`, where `meta.has_more` indicates further pages.
+### WebSocket sessions
 
-### Projects — `client.projects`
+`connect()` opens a real-time messaging session. Authentication is handled for you,
+and it works in both Node and the browser.
 
-```typescript
-const page = await client.projects.listProjects();       // { results, meta }
-const project = await client.projects.getProject(projectId);
-const usage = await client.projects.getProjectUsage(projectId);
-```
+```ts
+const socket = await client.connect();
+await socket.waitForOpen();
 
-### Agents — `client.agents`
+socket.on('message', (message) => console.log(message));
+socket.on('error', (error) => console.error(error));
+socket.on('close', (event) => console.log('closed', event.code));
 
-```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);
+socket.sendSubmitMessage({
+  type: 'message',
+  agent_id: agentId,
+  user_id: 'end-user-123',
+  text: 'Hello over WebSocket',
+});
+
+socket.close();
 ```
 
-### Threads — `client.threads`
+The socket exposes `waitForOpen()`, `on(event, handler)` (events: `open`, `message`,
+`error`, `close`), `sendSubmitMessage(request)`, `sendResume(request)`, and `close()`.
+Note that `on()` registers a single handler per event; calling it again for the same
+event replaces the previous handler. The socket type is exported as `SessionSocket`.
 
-```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);
-```
+### Resolved key context
 
-### Messaging — `client.messaging`
+After the first request, or after calling `getContext()`, the scope resolved from the
+publishable key is available.
 
-```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);
+```ts
+const context = await client.getContext();
+console.log(context.agentId, context.organizationId);
 
-// List the messages in a thread
-const messages = await client.messaging.listMessages(res.thread_id);
+client.agentId;        // set after the first token exchange
+client.organizationId;
 ```
 
-## WebSocket Messaging
+---
 
-`client.connect()` opens a real-time session. The bearer token is resolved and attached to the upgrade automatically.
+## Management
 
-```typescript
-const socket = await client.connect();
-await socket.waitForOpen();
+`ApolloManagementClient` authenticates with an organization API key, sent as the
+`x-organization-api-key` header on every request. It is intended for backend services
+and CI. Do not expose the organization API key in the browser.
 
-socket.on('message', (msg) => {
-    console.log('Agent:', msg);
-});
-socket.on('error', (err) => console.error('WS error:', err));
-socket.on('close', (event) => console.log('Closed:', event.code));
+```ts
+import { ApolloManagementClient } from '@aui.io/aui-client';
 
-// Send a turn (type is required on the WS submit frame)
-socket.sendSubmitMessage({
-    type: 'message',
-    agent_id: agentId,
-    user_id: 'end-user-123',
-    text: 'Hello over WebSocket',
+const client = new ApolloManagementClient({
+  organizationApiKey: process.env.AUI_ORG_API_KEY,
 });
+```
 
-// When done
-socket.close();
+### Projects
+
+| Method | Description |
+| --- | --- |
+| `listProjects()` | List the organization's projects. |
+| `createProject(request)` | Create a project. |
+| `getProject(projectId)` | Fetch one project. |
+| `deleteProject(projectId)` | Delete a project. |
+| `getProjectUsage(projectId)` | Usage metrics aggregated across the project. |
+
+```ts
+const page = await client.projects.listProjects();
+const project = await client.projects.createProject({ name: 'My project' });
+const usage = await client.projects.getProjectUsage(project.id);
+```
+
+### Agents
+
+| Method | Description |
+| --- | --- |
+| `listAgents(projectId, { filters })` | List a project's agents. |
+| `createAgent(projectId, request)` | Create an agent. |
+| `getAgent(agentId)` | Fetch one agent. |
+| `updateAgent(agentId, request)` | Rename an agent. |
+| `deleteAgent(agentId)` | Delete an agent and its versions. |
+| `getAgentUsage(agentId)` | Usage metrics for one agent. |
+
+```ts
+const page = await client.agents.listAgents(projectId, { filters: {} });
+const agent = await client.agents.createAgent(projectId, { name: 'Support bot' });
+const usage = await client.agents.getAgentUsage(agent.id);
+```
+
+### Agent versions
+
+| Method | Description |
+| --- | --- |
+| `listVersions(agentId, { filters })` | List an agent's versions, newest first. |
+| `createVersion(agentId, request)` | Create a draft version. |
+| `updateVersion(agentId, versionId, request)` | Update a version's metadata. |
+| `pushVersion(agentId, versionId, request)` | Push a configuration bundle. |
+| `pullVersion(agentId, versionId, request?)` | Download a version's configuration bundle. |
+| `publishVersion(agentId, versionId)` | Make a version the agent's live version. |
+| `archiveVersion(agentId, versionId)` | Archive a version. |
+
+```ts
+const draft = await client.agentVersions.createVersion(agentId, {});
+await client.agentVersions.pushVersion(agentId, draft.id, { /* config bundle */ });
+await client.agentVersions.publishVersion(agentId, draft.id);
+```
+
+### Threads
+
+| Method | Description |
+| --- | --- |
+| `listThreads({ filters })` | List the organization's threads, newest first. |
+| `getThread(threadId)` | Fetch one thread. |
+| `updateThread(threadId, request)` | Update a thread (currently `title`). |
+| `getThreadMessages(threadId)` | Return the thread's transcript. |
+| `getThreadTrace(threadId)` | Return the reasoning trace for each interaction. |
+| `getInteractionTrace(interactionId)` | Return the 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 such as `project_id` over an
+empty object; the unfiltered list sorts every thread in the organization and can be slow.
+
+```ts
+const page = await client.threads.listThreads(
+  { filters: { project_id: projectId } },
+  { timeoutInSeconds: 120 },
+);
+const thread = await client.threads.getThread(threadId);
+await client.threads.updateThread(threadId, { title: 'Renamed conversation' });
 ```
 
-> **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 })`.
+---
 
-## Key Context Helpers
+## Pagination
 
-After the first request (or an explicit `getContext()`), scope resolved from the key is available:
+List endpoints return `{ results, meta }`. Use `meta.has_more` to detect further pages.
 
-```typescript
-console.log(client.keyType);        // 'agent' | 'org' | 'unknown'
+## Timeouts
 
-const ctx = await client.getContext();
-console.log(ctx.agentId, ctx.organizationId, ctx.keyType);
+There is no client-wide timeout. Set `timeoutInSeconds` per call when needed:
 
-client.agentId;         // populated once a token has been exchanged
-client.organizationId;
+```ts
+await client.threads.listThreads({ filters: {} }, { timeoutInSeconds: 120 });
 ```
 
-## Error Handling
+## Error handling
 
-`ApolloError` (the base API error) and `ApolloTimeoutError` are exported at the top
-level. The per-status errors (e.g. `UnprocessableEntityError`) live under the `Apollo`
-namespace.
+`ApolloError` and `ApolloTimeoutError` are exported at the top level. Per-status errors,
+such as `UnprocessableEntityError`, are available under the `Apollo` namespace.
 
-```typescript
+```ts
 import { ApolloError, Apollo } from '@aui.io/aui-client';
 
 try {
-    await client.agents.getAgent('missing-id');
+  await client.agents.getAgent('missing-id');
 } catch (error) {
-    if (error instanceof Apollo.UnprocessableEntityError) {
-        console.error('Validation failed:', error.body);
-    } else if (error instanceof ApolloError) {
-        console.error('API error:', error.statusCode, error.body);
-    } else {
-        console.error('Unexpected error:', error);
-    }
+  if (error instanceof Apollo.UnprocessableEntityError) {
+    console.error(error.body);
+  } else if (error instanceof ApolloError) {
+    console.error(error.statusCode, error.body);
+  } else {
+    throw error;
+  }
 }
 ```
 
-## TypeScript Support
+## TypeScript
 
-The SDK ships full type definitions. Models are namespaced under `Apollo`:
+The package ships type definitions. Request and response models are available under the
+`Apollo` namespace.
 
-```typescript
-import { ApolloClient, Apollo } from '@aui.io/aui-client';
+```ts
+import { Apollo } from '@aui.io/aui-client';
 
-const req: Apollo.SubmitMessageRequest = {
-    type: 'message',
-    agent_id: 'agent-123',
-    user_id: 'end-user-123',
-    text: 'Typed request',
+const request: Apollo.SubmitMessageRequest = {
+  type: 'message',
+  agent_id: 'agent-123',
+  user_id: 'end-user-123',
+  text: 'Typed request',
 };
 ```
 
 ## Resources
 
-- **GitHub:** [aui-io/aui-client-typescript](https://github.com/aui-io/aui-client-typescript)
-- **npm:** [@aui.io/aui-client](https://www.npmjs.com/package/@aui.io/aui-client)
-- **Issues:** [GitHub Issues](https://github.com/aui-io/aui-client-typescript/issues)
+- npm: [@aui.io/aui-client](https://www.npmjs.com/package/@aui.io/aui-client)
+- GitHub: [aui-io/aui-client-typescript](https://github.com/aui-io/aui-client-typescript)
+- Issues: [GitHub Issues](https://github.com/aui-io/aui-client-typescript/issues)
 
 ## License
 
-Proprietary software. Unauthorized copying or distribution is prohibited.
-
----
-
-**Built by the AUI team**
+Proprietary. Unauthorized copying or distribution is prohibited.

package/dist/cjs/ApolloClientWrapper.d.ts

@@ -2,31 +2,42 @@ 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 {
+export type PublishableKeyType = "agent" | "unknown";
+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_...). */
+        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);
-    /** Publishable-key family (agent / org / unknown). */
+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 / unknown). */
     get keyType(): PublishableKeyType;
     /** Agent resolved from an agent-scoped key. Populated after the first exchange. */
     get agentId(): string | undefined;
@@ -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 {};