@aui.io/aui-client 3.2.0 → 3.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.md +195 -239
  2. package/dist/cjs/ApolloClientWrapper.d.ts +3 -3
  3. package/dist/cjs/ApolloClientWrapper.js +2 -6
  4. package/dist/cjs/Client.js +2 -2
  5. package/dist/cjs/version.d.ts +1 -1
  6. package/dist/cjs/version.js +1 -1
  7. package/dist/esm/ApolloClientWrapper.d.mts +3 -3
  8. package/dist/esm/ApolloClientWrapper.mjs +2 -6
  9. package/dist/esm/Client.mjs +2 -2
  10. package/dist/esm/version.d.mts +1 -1
  11. package/dist/esm/version.mjs +1 -1
  12. package/package.json +1 -1
package/README.md CHANGED
@@ -1,9 +1,9 @@
1
1
  # @aui.io/aui-client
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/@aui.io/aui-client)](https://www.npmjs.com/package/@aui.io/aui-client)
4
- [![Built with Fern](https://img.shields.io/badge/Built%20with-Fern-brightgreen)](https://buildwithfern.com)
5
4
 
6
- > **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.
5
+ Official TypeScript/JavaScript SDK for the AUI Apollo API. Provides REST access to
6
+ messaging, projects, agents, and threads, plus a real-time WebSocket messaging session.
7
7
 
8
8
  ## Installation
9
9
 
@@ -11,347 +11,303 @@
11
11
  npm install @aui.io/aui-client
12
12
  ```
13
13
 
14
- ## Authentication
14
+ ## Clients
15
15
 
16
- 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).
16
+ The package exposes two clients, one per credential. Import and use the one that
17
+ matches your environment.
17
18
 
18
- | Client | Credential | Resources | Browser-safe |
19
+ | Client | Credential | Browser | Purpose |
19
20
  | --- | --- | --- | --- |
20
- | `ApolloMessagingClient` | Publishable key (`pk_network_…` / `pk_org_…`) | `messaging`, `channels`, WebSocket sessions | **Yes** |
21
- | `ApolloManagementClient` | Organization API key | `projects`, `agents`, `agentVersions`, `threads` | **No** — server-side only |
21
+ | `ApolloMessagingClient` | Publishable key (`pk_network_...`) | Yes | End-user messaging and channels |
22
+ | `ApolloManagementClient` | Organization API key | No — server only | Managing projects, agents, versions, and threads |
22
23
 
23
- - **`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 …`.
24
- - **`ApolloManagementClient`** sends the organization API key on every request as the `x-organization-api-key` header — there is no token exchange, caching, or refresh.
24
+ ---
25
25
 
26
- ```typescript
27
- import { ApolloMessagingClient, ApolloManagementClient } from '@aui.io/aui-client';
26
+ ## Messaging
28
27
 
29
- // Browser / widget / end-user (publishable key)
30
- const messaging = new ApolloMessagingClient({
31
- publishableKey: 'pk_network_xxxxxxxxxxxxxxxxxxxxxxxx',
32
- });
28
+ `ApolloMessagingClient` authenticates with a publishable key. It exchanges the key
29
+ for a short-lived access token and refreshes it as needed, so you never handle tokens
30
+ directly. The agent is derived from the key and is not passed in request bodies. The
31
+ client is safe to use in the browser.
32
+
33
+ ```ts
34
+ import { ApolloMessagingClient } from '@aui.io/aui-client';
33
35
 
34
- // Backend / CI (organization API key — never ship this to the browser)
35
- const management = new ApolloManagementClient({
36
- organizationApiKey: 'YOUR_ORG_API_KEY',
36
+ const client = new ApolloMessagingClient({
37
+ publishableKey: 'pk_network_xxxxxxxxxxxxxxxxxxxxxxxx',
37
38
  });
38
39
  ```
39
40
 
40
- ## Quick Start
41
+ ### Send a message
41
42
 
42
- Messaging (publishable key) — the agent is derived from the key, so you don't pass it:
43
-
44
- ```typescript
45
- import { ApolloMessagingClient } from '@aui.io/aui-client';
46
-
47
- const messaging = new ApolloMessagingClient({
48
- publishableKey: 'pk_network_xxxxxxxxxxxxxxxxxxxxxxxx',
49
- });
43
+ Omit `thread_id` to start a new thread, or pass it to continue one.
50
44
 
51
- // Send a message (creates a thread if thread_id is omitted)
52
- const response = await messaging.messaging.sendMessage({
53
- user_id: 'end-user-123',
54
- text: 'Hello from the SDK',
45
+ ```ts
46
+ const response = await client.messaging.sendMessage({
47
+ user_id: 'end-user-123',
48
+ text: 'What can you help me with?',
49
+ // thread_id: existingThreadId,
55
50
  });
56
51
 
57
- console.log('Thread:', response.thread_id);
52
+ console.log(response.thread_id);
58
53
  ```
59
54
 
60
- Management (organization API key, server-side only):
55
+ You can pass optional per-message values for the agent's configured context variables:
61
56
 
62
- ```typescript
63
- import { ApolloManagementClient } from '@aui.io/aui-client';
64
-
65
- const management = new ApolloManagementClient({
66
- organizationApiKey: 'YOUR_ORG_API_KEY',
57
+ ```ts
58
+ await client.messaging.sendMessage({
59
+ user_id: 'end-user-123',
60
+ text: 'Where is my order?',
61
+ agent_variables: {
62
+ static: { customer_name: 'Ada' },
63
+ dynamic: { order_id: 'ORD-1042' },
64
+ },
67
65
  });
68
-
69
- const projects = await management.projects.listProjects();
70
- const projectId = projects.results[0].id;
71
-
72
- const agents = await management.agents.listAgents(projectId, { filters: {} });
73
66
  ```
74
67
 
75
- ## Configuration
68
+ ### Stream a message
76
69
 
77
- Each client takes its credential:
70
+ `streamMessage` returns the reply as Server-Sent Events.
78
71
 
79
- ```typescript
80
- interface ApolloMessagingClient.Options {
81
- publishableKey: string; // pk_network_… or pk_org_…
82
- }
72
+ ```ts
73
+ const stream = await client.messaging.streamMessage({
74
+ user_id: 'end-user-123',
75
+ text: 'Tell me about my account',
76
+ });
83
77
 
84
- interface ApolloManagementClient.Options {
85
- organizationApiKey: string; // server-side only
78
+ for await (const event of stream) {
79
+ console.log(event);
86
80
  }
87
81
  ```
88
82
 
89
- ## REST API
90
-
91
- 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.
83
+ ### Welcome message and follow-up suggestions
92
84
 
93
- ### Messaging client (`ApolloMessagingClient`)
85
+ ```ts
86
+ const { welcome_message } = await client.messaging.getWelcomeMessage();
94
87
 
95
- #### Messaging — `messaging.messaging`
88
+ const { suggestions } = await client.messaging.generateFollowupSuggestions({
89
+ context: { topic: 'order tracking' },
90
+ });
91
+ ```
96
92
 
97
- Full method list:
93
+ ### Other messaging methods
98
94
 
99
95
  | Method | Description |
100
96
  | --- | --- |
101
- | `sendMessage(request)` | Send a message and get the full reply. Omit `thread_id` to start a new thread. |
102
- | `streamMessage(request)` | Same as `sendMessage`, but streams the reply token-by-token over Server-Sent Events. |
97
+ | `sendMessage(request)` | Send a message and return the reply. |
98
+ | `streamMessage(request)` | Send a message and stream the reply (SSE). |
103
99
  | `rerun(threadId, request)` | Re-run the latest turn of a thread. |
104
- | `listMessages(threadId)` | The thread transcript, scoped to the key's agent. |
105
- | `threadTrace(threadId)` | Reasoning trace for every interaction in a thread. |
106
- | `interactionTrace(interactionId)` | Reasoning trace for a single interaction. |
107
- | `getWelcomeMessage()` | The agent's welcome message (from its live version). |
108
- | `generateFollowupSuggestions(request)` | Suggested follow-up prompts from a context you provide. |
109
-
110
- ```typescript
111
- // Send a message. Omit thread_id to start a new thread. The agent rides the key,
112
- // so it isn't passed in the body.
113
- const res = await messaging.messaging.sendMessage({
114
- user_id: 'end-user-123',
115
- text: 'What can you help me with?',
116
- // thread_id: existingThreadId,
117
- // Optional per-message values for the agent's configured context variables:
118
- // agent_variables: { static: { customer_name: 'Ada' }, dynamic: { order_id: 'ORD-1042' } },
100
+ | `listMessages(threadId)` | Return the messages in a thread. |
101
+ | `threadTrace(threadId)` | Return the reasoning trace for each interaction in a thread. |
102
+ | `interactionTrace(interactionId)` | Return the reasoning trace for a single interaction. |
103
+ | `getWelcomeMessage()` | Return the agent's welcome message. |
104
+ | `generateFollowupSuggestions(request)` | Generate follow-up prompts from a context. |
105
+
106
+ ### Channels (SMS and WhatsApp)
107
+
108
+ Start an outbound thread on a channel with `channels.initiateThread`. Pass `'sms'`
109
+ or `'whatsapp'` as the channel.
110
+
111
+ ```ts
112
+ const thread = await client.channels.initiateThread('sms', {
113
+ phone_number: '+14155551234',
114
+ user_id: 'end-user-123',
115
+ text: 'Hi! Your order has shipped.',
116
+ // thread_id: existingThreadId,
119
117
  });
120
- console.log('Thread:', res.thread_id);
121
118
 
122
- // Stream the reply instead (Server-Sent Events)
123
- const stream = await messaging.messaging.streamMessage({ user_id: 'end-user-123', text: 'Tell me a story' });
124
- for await (const event of stream) {
125
- console.log(event);
126
- }
119
+ console.log(thread.thread_id);
120
+ ```
121
+
122
+ ### WebSocket sessions
127
123
 
128
- // Re-run the latest turn of a thread
129
- const rerun = await messaging.messaging.rerun(res.thread_id, { user_id: 'end-user-123' });
124
+ `connect()` opens a real-time messaging session. Authentication is handled for you,
125
+ and it works in both Node and the browser.
130
126
 
131
- // Read the transcript and traces
132
- const messages = await messaging.messaging.listMessages(res.thread_id);
133
- const traces = await messaging.messaging.threadTrace(res.thread_id);
134
- const one = await messaging.messaging.interactionTrace(interactionId);
127
+ ```ts
128
+ const socket = await client.connect();
129
+ await socket.waitForOpen();
135
130
 
136
- // Welcome message (from the agent's live version) — open a conversation UI before the first turn
137
- const { welcome_message } = await messaging.messaging.getWelcomeMessage();
131
+ socket.on('message', (message) => console.log(message));
132
+ socket.on('error', (error) => console.error(error));
133
+ socket.on('close', (event) => console.log('closed', event.code));
138
134
 
139
- // Follow-up suggestions generated from a context you provide
140
- const { suggestions } = await messaging.messaging.generateFollowupSuggestions({
141
- context: { topic: 'order tracking' },
135
+ socket.sendSubmitMessage({
136
+ type: 'message',
137
+ agent_id: agentId,
138
+ user_id: 'end-user-123',
139
+ text: 'Hello over WebSocket',
142
140
  });
141
+
142
+ socket.close();
143
143
  ```
144
144
 
145
- #### Channels — `messaging.channels`
145
+ The socket exposes `waitForOpen()`, `on(event, handler)` (events: `open`, `message`,
146
+ `error`, `close`), `sendSubmitMessage(request)`, `sendResume(request)`, and `close()`.
147
+ Note that `on()` registers a single handler per event; calling it again for the same
148
+ event replaces the previous handler. The socket type is exported as `SessionSocket`.
146
149
 
147
- | Method | Description |
148
- | --- | --- |
149
- | `initiateThread(channel, request)` | Send the opening message on an outbound channel (`'sms'` / `'whatsapp'`) and bind the recipient to a thread. |
150
-
151
- ```typescript
152
- // Start a channel-scoped thread (e.g. SMS opener). The agent rides the key, so it isn't
153
- // passed in the body. Use 'whatsapp' for WhatsApp.
154
- const sms = await messaging.channels.initiateThread('sms', {
155
- phone_number: '+14155551234',
156
- user_id: 'end-user-123',
157
- text: 'Hello from the SDK',
158
- // thread_id: existingThreadId, // omit to start a new thread
159
- });
160
- console.log('Thread:', sms.thread_id);
150
+ ### Resolved key context
151
+
152
+ After the first request, or after calling `getContext()`, the scope resolved from the
153
+ publishable key is available.
154
+
155
+ ```ts
156
+ const context = await client.getContext();
157
+ console.log(context.agentId, context.organizationId);
158
+
159
+ client.agentId; // set after the first token exchange
160
+ client.organizationId;
161
161
  ```
162
162
 
163
- ### Management client (`ApolloManagementClient`)
163
+ ---
164
+
165
+ ## Management
166
+
167
+ `ApolloManagementClient` authenticates with an organization API key, sent as the
168
+ `x-organization-api-key` header on every request. It is intended for backend services
169
+ and CI. Do not expose the organization API key in the browser.
170
+
171
+ ```ts
172
+ import { ApolloManagementClient } from '@aui.io/aui-client';
173
+
174
+ const client = new ApolloManagementClient({
175
+ organizationApiKey: process.env.AUI_ORG_API_KEY,
176
+ });
177
+ ```
164
178
 
165
- #### Projects — `management.projects`
179
+ ### Projects
166
180
 
167
181
  | Method | Description |
168
182
  | --- | --- |
169
- | `listProjects()` | List the org's projects (paginated). |
183
+ | `listProjects()` | List the organization's projects. |
170
184
  | `createProject(request)` | Create a project. |
171
185
  | `getProject(projectId)` | Fetch one project. |
172
186
  | `deleteProject(projectId)` | Delete a project. |
173
187
  | `getProjectUsage(projectId)` | Usage metrics aggregated across the project. |
174
188
 
175
- ```typescript
176
- const page = await management.projects.listProjects(); // { results, meta }
177
- const project = await management.projects.createProject({ name: 'My project' });
178
- const fetched = await management.projects.getProject(project.id);
179
- const usage = await management.projects.getProjectUsage(project.id);
180
- await management.projects.deleteProject(project.id);
189
+ ```ts
190
+ const page = await client.projects.listProjects();
191
+ const project = await client.projects.createProject({ name: 'My project' });
192
+ const usage = await client.projects.getProjectUsage(project.id);
181
193
  ```
182
194
 
183
- #### Agents — `management.agents`
195
+ ### Agents
184
196
 
185
197
  | Method | Description |
186
198
  | --- | --- |
187
- | `listAgents(projectId, { filters })` | List a project's agents (paginated). |
188
- | `createAgent(projectId, request)` | Create an agent (starts with no live version). |
189
- | `getAgent(agentId)` | Fetch one agent, incl. its live version. |
199
+ | `listAgents(projectId, { filters })` | List a project's agents. |
200
+ | `createAgent(projectId, request)` | Create an agent. |
201
+ | `getAgent(agentId)` | Fetch one agent. |
190
202
  | `updateAgent(agentId, request)` | Rename an agent. |
191
- | `deleteAgent(agentId)` | Delete an agent and all its versions. |
203
+ | `deleteAgent(agentId)` | Delete an agent and its versions. |
192
204
  | `getAgentUsage(agentId)` | Usage metrics for one agent. |
193
205
 
194
- ```typescript
195
- const page = await management.agents.listAgents(projectId, { filters: {} });
196
- const agent = await management.agents.createAgent(projectId, { name: 'Support bot' });
197
- const fetched = await management.agents.getAgent(agent.id); // fetched.live_version_id, …
198
- await management.agents.updateAgent(agent.id, { name: 'Support bot v2' });
199
- const usage = await management.agents.getAgentUsage(agent.id);
200
- await management.agents.deleteAgent(agent.id);
206
+ ```ts
207
+ const page = await client.agents.listAgents(projectId, { filters: {} });
208
+ const agent = await client.agents.createAgent(projectId, { name: 'Support bot' });
209
+ const usage = await client.agents.getAgentUsage(agent.id);
201
210
  ```
202
211
 
203
- #### Agent versions — `management.agentVersions`
212
+ ### Agent versions
204
213
 
205
214
  | Method | Description |
206
215
  | --- | --- |
207
216
  | `listVersions(agentId, { filters })` | List an agent's versions, newest first. |
208
- | `createVersion(agentId, request)` | Create a draft version (empty, from a template, or cloned). |
209
- | `updateVersion(agentId, versionId, request)` | Update a version's metadata (label, tags, notes). |
210
- | `pushVersion(agentId, versionId, request)` | Push a config bundle, committing a new revision. |
211
- | `pullVersion(agentId, versionId, request?)` | Download a version's config bundle. |
217
+ | `createVersion(agentId, request)` | Create a draft version. |
218
+ | `updateVersion(agentId, versionId, request)` | Update a version's metadata. |
219
+ | `pushVersion(agentId, versionId, request)` | Push a configuration bundle. |
220
+ | `pullVersion(agentId, versionId, request?)` | Download a version's configuration bundle. |
212
221
  | `publishVersion(agentId, versionId)` | Make a version the agent's live version. |
213
- | `archiveVersion(agentId, versionId)` | Archive (retire) a version. |
214
-
215
- ```typescript
216
- const versions = await management.agentVersions.listVersions(agentId, { filters: {} });
217
- const draft = await management.agentVersions.createVersion(agentId, {});
218
- await management.agentVersions.updateVersion(agentId, draft.id, { label: 'v1' });
219
- await management.agentVersions.pushVersion(agentId, draft.id, { /* config bundle */ });
220
- const bundle = await management.agentVersions.pullVersion(agentId, draft.id);
221
- await management.agentVersions.publishVersion(agentId, draft.id);
222
- await management.agentVersions.archiveVersion(agentId, draft.id);
222
+ | `archiveVersion(agentId, versionId)` | Archive a version. |
223
+
224
+ ```ts
225
+ const draft = await client.agentVersions.createVersion(agentId, {});
226
+ await client.agentVersions.pushVersion(agentId, draft.id, { /* config bundle */ });
227
+ await client.agentVersions.publishVersion(agentId, draft.id);
223
228
  ```
224
229
 
225
- #### Threads — `management.threads`
230
+ ### Threads
226
231
 
227
232
  | Method | Description |
228
233
  | --- | --- |
229
- | `listThreads({ filters })` | List the org's threads, newest first (paginated). |
234
+ | `listThreads({ filters })` | List the organization's threads, newest first. |
230
235
  | `getThread(threadId)` | Fetch one thread. |
231
236
  | `updateThread(threadId, request)` | Update a thread (currently `title`). |
232
- | `getThreadMessages(threadId)` | The thread's full transcript. |
233
- | `getThreadTrace(threadId)` | Reasoning trace for every interaction in the thread. |
234
- | `getInteractionTrace(interactionId)` | Reasoning trace for a single interaction. |
235
-
236
- `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.
237
-
238
- ```typescript
239
- const page = await management.threads.listThreads(
240
- { filters: { project_id: projectId } },
241
- { timeoutInSeconds: 120 }, // this endpoint can be slow; give it headroom
237
+ | `getThreadMessages(threadId)` | Return the thread's transcript. |
238
+ | `getThreadTrace(threadId)` | Return the reasoning trace for each interaction. |
239
+ | `getInteractionTrace(interactionId)` | Return the reasoning trace for a single interaction. |
240
+
241
+ `filters` supports `project_id`, `agent_id`, `user_id`, `external_id`, `created`
242
+ (range), `tool`, `rule`, and `param`. Prefer a filter such as `project_id` over an
243
+ empty object; the unfiltered list sorts every thread in the organization and can be slow.
244
+
245
+ ```ts
246
+ const page = await client.threads.listThreads(
247
+ { filters: { project_id: projectId } },
248
+ { timeoutInSeconds: 120 },
242
249
  );
243
- const thread = await management.threads.getThread(threadId);
244
- const updated = await management.threads.updateThread(threadId, { title: 'Renamed conversation' });
245
- const messages = await management.threads.getThreadMessages(threadId);
246
- const trace = await management.threads.getThreadTrace(threadId);
247
- const one = await management.threads.getInteractionTrace(interactionId);
250
+ const thread = await client.threads.getThread(threadId);
251
+ await client.threads.updateThread(threadId, { title: 'Renamed conversation' });
248
252
  ```
249
253
 
250
- ## WebSocket Messaging
251
-
252
- `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.
253
-
254
- ```typescript
255
- const messaging = new ApolloMessagingClient({ publishableKey: 'pk_network_…' });
256
- const socket = await messaging.connect();
257
- await socket.waitForOpen();
258
-
259
- socket.on('message', (msg) => {
260
- console.log('Agent:', msg);
261
- });
262
- socket.on('error', (err) => console.error('WS error:', err));
263
- socket.on('close', (event) => console.log('Closed:', event.code));
264
-
265
- // Send a turn (type is required on the WS submit frame)
266
- socket.sendSubmitMessage({
267
- type: 'message',
268
- agent_id: agentId,
269
- user_id: 'end-user-123',
270
- text: 'Hello over WebSocket',
271
- });
272
-
273
- // Resume a dropped stream
274
- socket.sendResume({ /* ResumeRequest */ });
275
-
276
- // When done
277
- socket.close();
278
- ```
279
-
280
- The socket (`SessionSocket`) exposes: `waitForOpen()`, `on(event, handler)` (events: `open`, `message`, `error`, `close`), `sendSubmitMessage(request)`, `sendResume(request)`, and `close()`.
281
-
282
- > **Notes**
283
- > - `socket.on(event, handler)` registers a **single** handler per event — calling it
284
- > again for the same event replaces the previous handler rather than adding one.
285
- > - The socket type is exported as `SessionSocket` (`import { SessionSocket } from '@aui.io/aui-client'`).
286
- > - Request timeouts are **per call** via `timeoutInSeconds` on a request's options; there
287
- > is no client-wide default timeout. Pass it on slow calls, e.g.
288
- > `management.threads.listThreads({ filters: {} }, { timeoutInSeconds: 120 })`.
289
-
290
- ## Key Context Helpers
254
+ ---
291
255
 
292
- On **`ApolloMessagingClient`**, after the first request (or an explicit `getContext()`), the scope resolved from the publishable key is available:
256
+ ## Pagination
293
257
 
294
- ```typescript
295
- const messaging = new ApolloMessagingClient({ publishableKey: 'pk_network_…' });
258
+ List endpoints return `{ results, meta }`. Use `meta.has_more` to detect further pages.
296
259
 
297
- console.log(messaging.keyType); // 'agent' | 'org' | 'unknown'
260
+ ## Timeouts
298
261
 
299
- const ctx = await messaging.getContext();
300
- console.log(ctx.agentId, ctx.organizationId, ctx.keyType);
262
+ There is no client-wide timeout. Set `timeoutInSeconds` per call when needed:
301
263
 
302
- messaging.agentId; // populated once a token has been exchanged
303
- messaging.organizationId;
264
+ ```ts
265
+ await client.threads.listThreads({ filters: {} }, { timeoutInSeconds: 120 });
304
266
  ```
305
267
 
306
- `ApolloManagementClient` proves only the organization (resolved server-side by the gateway), so it has no key-context helpers.
307
-
308
- ## Error Handling
268
+ ## Error handling
309
269
 
310
- `ApolloError` (the base API error) and `ApolloTimeoutError` are exported at the top
311
- level. The per-status errors (e.g. `UnprocessableEntityError`) live under the `Apollo`
312
- namespace.
270
+ `ApolloError` and `ApolloTimeoutError` are exported at the top level. Per-status errors,
271
+ such as `UnprocessableEntityError`, are available under the `Apollo` namespace.
313
272
 
314
- ```typescript
273
+ ```ts
315
274
  import { ApolloError, Apollo } from '@aui.io/aui-client';
316
275
 
317
276
  try {
318
- await management.agents.getAgent('missing-id');
277
+ await client.agents.getAgent('missing-id');
319
278
  } catch (error) {
320
- if (error instanceof Apollo.UnprocessableEntityError) {
321
- console.error('Validation failed:', error.body);
322
- } else if (error instanceof ApolloError) {
323
- console.error('API error:', error.statusCode, error.body);
324
- } else {
325
- console.error('Unexpected error:', error);
326
- }
279
+ if (error instanceof Apollo.UnprocessableEntityError) {
280
+ console.error(error.body);
281
+ } else if (error instanceof ApolloError) {
282
+ console.error(error.statusCode, error.body);
283
+ } else {
284
+ throw error;
285
+ }
327
286
  }
328
287
  ```
329
288
 
330
- ## TypeScript Support
289
+ ## TypeScript
331
290
 
332
- The SDK ships full type definitions. Models are namespaced under `Apollo`:
291
+ The package ships type definitions. Request and response models are available under the
292
+ `Apollo` namespace.
333
293
 
334
- ```typescript
294
+ ```ts
335
295
  import { Apollo } from '@aui.io/aui-client';
336
296
 
337
- const req: Apollo.SubmitMessageRequest = {
338
- type: 'message',
339
- agent_id: 'agent-123',
340
- user_id: 'end-user-123',
341
- text: 'Typed request',
297
+ const request: Apollo.SubmitMessageRequest = {
298
+ type: 'message',
299
+ agent_id: 'agent-123',
300
+ user_id: 'end-user-123',
301
+ text: 'Typed request',
342
302
  };
343
303
  ```
344
304
 
345
305
  ## Resources
346
306
 
347
- - **GitHub:** [aui-io/aui-client-typescript](https://github.com/aui-io/aui-client-typescript)
348
- - **npm:** [@aui.io/aui-client](https://www.npmjs.com/package/@aui.io/aui-client)
349
- - **Issues:** [GitHub Issues](https://github.com/aui-io/aui-client-typescript/issues)
307
+ - npm: [@aui.io/aui-client](https://www.npmjs.com/package/@aui.io/aui-client)
308
+ - GitHub: [aui-io/aui-client-typescript](https://github.com/aui-io/aui-client-typescript)
309
+ - Issues: [GitHub Issues](https://github.com/aui-io/aui-client-typescript/issues)
350
310
 
351
311
  ## License
352
312
 
353
- Proprietary software. Unauthorized copying or distribution is prohibited.
354
-
355
- ---
356
-
357
- **Built by the AUI team**
313
+ Proprietary. Unauthorized copying or distribution is prohibited.
package/dist/cjs/ApolloClientWrapper.d.ts CHANGED
@@ -9,7 +9,7 @@ import type { Agents } from "./api/resources/agents/client/Client.js";
9
9
  import type { AgentVersions } from "./api/resources/agentVersions/client/Client.js";
10
10
  import type { Threads } from "./api/resources/threads/client/Client.js";
11
11
  /** Publishable-key family, inferred from the key prefix. */
12
- export type PublishableKeyType = "agent" | "org" | "unknown";
12
+ export type PublishableKeyType = "agent" | "unknown";
13
13
  type AuthHeaders = Record<string, string | (() => Promise<string>) | null>;
14
14
  declare class BaseApolloClient {
15
15
  protected readonly _client: _GeneratedClient;
@@ -18,7 +18,7 @@ declare class BaseApolloClient {
18
18
  }
19
19
  export declare namespace ApolloMessagingClient {
20
20
  interface Options {
21
- /** Publishable key (pk_network_ / pk_org_). */
21
+ /** Publishable key (pk_network_...). */
22
22
  publishableKey: string;
23
23
  /** Internal: override the API host. Defaults to production. */
24
24
  baseUrl?: string;
@@ -37,7 +37,7 @@ export declare class ApolloMessagingClient extends BaseApolloClient {
37
37
  get messaging(): Messaging;
38
38
  /** Initiate channel-scoped threads (e.g. SMS). */
39
39
  get channels(): Channels;
40
- /** Publishable-key family (agent / org / unknown). */
40
+ /** Publishable-key family (agent / unknown). */
41
41
  get keyType(): PublishableKeyType;
42
42
  /** Agent resolved from an agent-scoped key. Populated after the first exchange. */
43
43
  get agentId(): string | undefined;
package/dist/cjs/ApolloClientWrapper.js CHANGED
@@ -159,7 +159,7 @@ class ApolloMessagingClient extends BaseApolloClient {
159
159
  get channels() {
160
160
  return this._client.channels;
161
161
  }
162
- /** Publishable-key family (agent / org / unknown). */
162
+ /** Publishable-key family (agent / unknown). */
163
163
  get keyType() {
164
164
  return this._pkAuth.keyType;
165
165
  }
@@ -238,11 +238,7 @@ function resolveEnv(baseUrl) {
238
238
  return { base, production: base.replace(/^http/i, "ws") };
239
239
  }
240
240
  function detectKeyType(publishableKey) {
241
- if (!publishableKey)
242
- return "unknown";
243
- if (publishableKey.startsWith("pk_network_"))
241
+ if (publishableKey === null || publishableKey === void 0 ? void 0 : publishableKey.startsWith("pk_network_"))
244
242
  return "agent";
245
- if (publishableKey.startsWith("pk_org_"))
246
- return "org";
247
243
  return "unknown";
248
244
  }
package/dist/cjs/Client.js CHANGED
@@ -62,8 +62,8 @@ class ApolloClient {
62
62
  "x-organization-api-key": _options === null || _options === void 0 ? void 0 : _options.organizationApiKey,
63
63
  "X-Fern-Language": "JavaScript",
64
64
  "X-Fern-SDK-Name": "@aui.io/aui-client",
65
- "X-Fern-SDK-Version": "3.2.0",
66
- "User-Agent": "@aui.io/aui-client/3.2.0",
65
+ "X-Fern-SDK-Version": "3.2.1",
66
+ "User-Agent": "@aui.io/aui-client/3.2.1",
67
67
  "X-Fern-Runtime": core.RUNTIME.type,
68
68
  "X-Fern-Runtime-Version": core.RUNTIME.version,
69
69
  }, _options === null || _options === void 0 ? void 0 : _options.headers) });
package/dist/cjs/version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const SDK_VERSION = "3.2.0";
1
+ export declare const SDK_VERSION = "3.2.1";
package/dist/cjs/version.js CHANGED
@@ -1,4 +1,4 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.SDK_VERSION = void 0;
4
- exports.SDK_VERSION = "3.2.0";
4
+ exports.SDK_VERSION = "3.2.1";
package/dist/esm/ApolloClientWrapper.d.mts CHANGED
@@ -9,7 +9,7 @@ import type { Agents } from "./api/resources/agents/client/Client.mjs";
9
9
  import type { AgentVersions } from "./api/resources/agentVersions/client/Client.mjs";
10
10
  import type { Threads } from "./api/resources/threads/client/Client.mjs";
11
11
  /** Publishable-key family, inferred from the key prefix. */
12
- export type PublishableKeyType = "agent" | "org" | "unknown";
12
+ export type PublishableKeyType = "agent" | "unknown";
13
13
  type AuthHeaders = Record<string, string | (() => Promise<string>) | null>;
14
14
  declare class BaseApolloClient {
15
15
  protected readonly _client: _GeneratedClient;
@@ -18,7 +18,7 @@ declare class BaseApolloClient {
18
18
  }
19
19
  export declare namespace ApolloMessagingClient {
20
20
  interface Options {
21
- /** Publishable key (pk_network_ / pk_org_). */
21
+ /** Publishable key (pk_network_...). */
22
22
  publishableKey: string;
23
23
  /** Internal: override the API host. Defaults to production. */
24
24
  baseUrl?: string;
@@ -37,7 +37,7 @@ export declare class ApolloMessagingClient extends BaseApolloClient {
37
37
  get messaging(): Messaging;
38
38
  /** Initiate channel-scoped threads (e.g. SMS). */
39
39
  get channels(): Channels;
40
- /** Publishable-key family (agent / org / unknown). */
40
+ /** Publishable-key family (agent / unknown). */
41
41
  get keyType(): PublishableKeyType;
42
42
  /** Agent resolved from an agent-scoped key. Populated after the first exchange. */
43
43
  get agentId(): string | undefined;
package/dist/esm/ApolloClientWrapper.mjs CHANGED
@@ -123,7 +123,7 @@ export class ApolloMessagingClient extends BaseApolloClient {
123
123
  get channels() {
124
124
  return this._client.channels;
125
125
  }
126
- /** Publishable-key family (agent / org / unknown). */
126
+ /** Publishable-key family (agent / unknown). */
127
127
  get keyType() {
128
128
  return this._pkAuth.keyType;
129
129
  }
@@ -200,11 +200,7 @@ function resolveEnv(baseUrl) {
200
200
  return { base, production: base.replace(/^http/i, "ws") };
201
201
  }
202
202
  function detectKeyType(publishableKey) {
203
- if (!publishableKey)
204
- return "unknown";
205
- if (publishableKey.startsWith("pk_network_"))
203
+ if (publishableKey === null || publishableKey === void 0 ? void 0 : publishableKey.startsWith("pk_network_"))
206
204
  return "agent";
207
- if (publishableKey.startsWith("pk_org_"))
208
- return "org";
209
205
  return "unknown";
210
206
  }
package/dist/esm/Client.mjs CHANGED
@@ -26,8 +26,8 @@ export class ApolloClient {
26
26
  "x-organization-api-key": _options === null || _options === void 0 ? void 0 : _options.organizationApiKey,
27
27
  "X-Fern-Language": "JavaScript",
28
28
  "X-Fern-SDK-Name": "@aui.io/aui-client",
29
- "X-Fern-SDK-Version": "3.2.0",
30
- "User-Agent": "@aui.io/aui-client/3.2.0",
29
+ "X-Fern-SDK-Version": "3.2.1",
30
+ "User-Agent": "@aui.io/aui-client/3.2.1",
31
31
  "X-Fern-Runtime": core.RUNTIME.type,
32
32
  "X-Fern-Runtime-Version": core.RUNTIME.version,
33
33
  }, _options === null || _options === void 0 ? void 0 : _options.headers) });
package/dist/esm/version.d.mts CHANGED
@@ -1 +1 @@
1
- export declare const SDK_VERSION = "3.2.0";
1
+ export declare const SDK_VERSION = "3.2.1";
package/dist/esm/version.mjs CHANGED
@@ -1 +1 @@
1
- export const SDK_VERSION = "3.2.0";
1
+ export const SDK_VERSION = "3.2.1";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aui.io/aui-client",
3
- "version": "3.2.0",
3
+ "version": "3.2.1",
4
4
  "private": false,
5
5
  "repository": "github:aui-io/aui-client-typescript",
6
6
  "type": "commonjs",