@aui.io/aui-client 1.2.39 → 1.2.41

package/README.md

@@ -274,7 +274,8 @@ const messageResponse = await client.controllerApi.sendMessage({
     task_id: string,              // Task identifier
     text?: string,                // Message text (optional in v1.2.36+)
     is_external_api?: boolean,    // Optional: mark as external API call
-    include_trace_info?: boolean, // Optional: include trace/debug info in response (NEW in v1.2.35)
+    include_business_trace?: boolean, // Optional: include NLU/understanding + business decisions in trace_info (NEW in v1.2.37; replaces include_trace_info)
+    include_context_trace?: boolean,  // Optional: include context section + call_integration decisions in trace_info (NEW in v1.2.37; replaces include_trace_info)
     context?: {                   // Optional: additional context
         url?: string,
         lead_details?: Record<string, any>,
@@ -339,12 +340,14 @@ const traceInfo = await client.controllerApi.getTraceInfo('your-task-id', 'your-
 **Example:**
 
 ```typescript
-// First, send a message with trace info enabled
+// First, send a message with trace info enabled.
+// Note: `include_trace_info` was replaced in v1.2.39 by two granular flags.
 const message = await client.controllerApi.sendMessage({
     task_id: 'your-task-id',
     text: 'What products do you recommend?',
     is_external_api: true,
-    include_trace_info: true
+    include_business_trace: true,
+    include_context_trace: true
 });
 
 // Then retrieve the full trace info for that message
@@ -383,6 +386,53 @@ response.suggestions?.forEach((suggestion, index) => {
 });
 ```
 
+#### `startTextConversation(request)` - Start Text Conversation (NEW)
+Start a phone-channel conversation (SMS or WhatsApp) with an initial outbound message.
+
+The SDK creates a task on the AUI backend and then proxies to the `third-party-auth` service so the first message is delivered to the recipient over the chosen channel. Subsequent inbound replies from the user feed back into the same task and can be observed via the standard message / WebSocket APIs.
+
+```typescript
+const response = await client.controllerApi.startTextConversation({
+    phoneNumber: string,        // Recipient phone number in E.164 format (e.g., '+19999999999')
+    channel: 'sms' | 'whatsapp',// Outbound channel
+    message?: string            // Optional initial message to send (e.g., 'Hello!')
+});
+
+// Returns: TextConversationInitiateResponse
+// {
+//     status: boolean,                  // true on success
+//     data: Record<string, string>,     // backend payload (e.g., task / message identifiers)
+//     message: string,                  // human-readable status message
+//     statusCode: number                // HTTP-style status code
+// }
+```
+
+**Parameters:**
+
+- `phoneNumber` *(required)* — Must include the country code in E.164 format. Example: `+15551234567`. Numbers without a country code are rejected by the upstream third-party-auth service.
+- `channel` *(required)* — Either `'sms'` or `'whatsapp'`. Determines which provider sends the initial message.
+- `message` *(optional)* — The first outbound message body. If omitted, the conversation is created but no initial message is sent.
+
+**Example:**
+
+```typescript
+const response = await client.controllerApi.startTextConversation({
+    phoneNumber: '+19999999999',
+    channel: 'sms',
+    message: 'Hello!'
+});
+
+console.log('Status:     ', response.status);      // true
+console.log('Status Code:', response.statusCode);  // e.g. 200
+console.log('Message:    ', response.message);     // e.g. 'Conversation initiated'
+console.log('Data:       ', response.data);        // e.g. { task_id: '...', ... }
+```
+
+> ℹ️ **Tip:** During development you can default to a sandbox number with an env var, e.g.
+> `phoneNumber: process.env.TEST_PHONE_NUMBER ?? '+15551234567'`. The placeholder
+> `+15551234567` is rejected by the upstream provider — use a real, reachable E.164
+> number to validate end-to-end delivery.
+
 ---
 
 ### WebSocket API
@@ -643,12 +693,14 @@ const client = new ApolloClient({
 
 async function debugAgentResponse(taskId: string) {
     try {
-        // Send a message with trace info enabled
+        // Send a message with trace info enabled.
+        // `include_trace_info` was replaced with the two flags below in v1.2.37.
         const message = await client.controllerApi.sendMessage({
             task_id: taskId,
             text: 'What products do you recommend?',
             is_external_api: true,
-            include_trace_info: true
+            include_business_trace: true,
+            include_context_trace: true
         });
 
         console.log('Agent Response:', message.text);
@@ -707,6 +759,63 @@ getSuggestedQuestions('task-123', 'user-456');
 //   3. "Can I schedule a test drive?"
 ```
 
+### Start a Text Conversation - SMS / WhatsApp (NEW)
+
+Reach a user over their phone channel (SMS or WhatsApp) with an initial outbound message. Internally, the SDK creates a task and dispatches the first message through Apollo's `third-party-auth` service — replies from the user thread back into the same task so you can keep using the existing message APIs and WebSocket events.
+
+```typescript
+import { ApolloClient, Apollo } from '@aui.io/aui-client';
+
+const client = new ApolloClient({
+    networkApiKey: 'API_KEY_YOUR_KEY_HERE'
+});
+
+async function startTextConversation(
+    phoneNumber: string,
+    channel: 'sms' | 'whatsapp',
+    message: string
+) {
+    try {
+        const response: Apollo.TextConversationInitiateResponse =
+            await client.controllerApi.startTextConversation({
+                phoneNumber,   // E.164 format, e.g. '+19999999999'
+                channel,       // 'sms' or 'whatsapp'
+                message        // initial message body, e.g. 'Hello!'
+            });
+
+        console.log('✅ Conversation initiated');
+        console.log('   Status:     ', response.status);
+        console.log('   Status Code:', response.statusCode);
+        console.log('   Message:    ', response.message);
+        console.log('   Data:       ', response.data);
+
+        return response;
+    } catch (error: any) {
+        console.error('❌ Error starting text conversation:', error.message);
+        if (error.body) {
+            console.error('   Body:', error.body);
+        }
+        throw error;
+    }
+}
+
+// SMS
+startTextConversation('+19999999999', 'sms', 'Hello!');
+
+// WhatsApp
+startTextConversation('+971501234567', 'whatsapp', 'Hi from AUI!');
+```
+
+**UI mapping:** This is the API behind the "Start Text Conversation" panel — phone number + channel selector (SMS / WhatsApp) + initial message — wired directly to `client.controllerApi.startTextConversation({ phoneNumber, channel, message })`.
+
+**Common errors:**
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| `500` from upstream `third-party-auth` | Invalid or unreachable phone number (e.g., placeholder `+15551234567`) | Use a real E.164 number, including the country code |
+| `422 Unprocessable Entity` | `phoneNumber` or `channel` missing / wrong shape | Ensure `channel` is exactly `'sms'` or `'whatsapp'` and `phoneNumber` starts with `+` |
+| `401 / 403` | Missing or invalid `networkApiKey` | Pass `networkApiKey` to `ApolloClient` (or the `x-network-api-key` header) |
+
 ## 🔧 Advanced Configuration
 
 ### Custom Timeout and Retries
@@ -788,6 +897,7 @@ import {
     CreateExternalTaskRequest,
     SubmitExternalMessageRequest,
     UserMessagePayload,
+    TextConversationInitiateRequest,
     // Response types
     CreateExternalTaskResponse,
     ExternalTaskMessage,
@@ -795,6 +905,7 @@ import {
     StreamingUpdatePayload,
     FinalMessagePayload,
     ErrorMessagePayload,
+    TextConversationInitiateResponse,
     // Error types
     ApolloError,
     UnprocessableEntityError

package/dist/cjs/Client.js

@@ -45,8 +45,8 @@ class ApolloClient {
                 "x-network-api-key": _options === null || _options === void 0 ? void 0 : _options.networkApiKey,
                 "X-Fern-Language": "JavaScript",
                 "X-Fern-SDK-Name": "@aui.io/aui-client",
-                "X-Fern-SDK-Version": "1.2.39",
-                "User-Agent": "@aui.io/aui-client/1.2.39",
+                "X-Fern-SDK-Version": "1.2.41",
+                "User-Agent": "@aui.io/aui-client/1.2.41",
                 "X-Fern-Runtime": core.RUNTIME.type,
                 "X-Fern-Runtime-Version": core.RUNTIME.version,
             }, _options === null || _options === void 0 ? void 0 : _options.headers) });

package/dist/cjs/api/types/TaskParameter.d.ts

@@ -10,6 +10,7 @@ export interface TaskParameter {
     is_anchor?: boolean;
     is_value_filled?: boolean;
     is_visible?: boolean;
+    is_exist_param?: boolean;
     param_type?: Apollo.ParameterType;
     code?: string;
 }

package/dist/cjs/api/types/TraceEntity.d.ts

@@ -1,9 +1,12 @@
 import type * as Apollo from "../index.js";
 export interface TraceEntity {
     entity: string;
-    identifier?: string;
+    identifier?: TraceEntity.Identifier;
     reference?: string;
     source: Apollo.TraceEntitySource;
     params?: Record<string, unknown>;
     sub_entities?: Apollo.TraceSubEntity[];
 }
+export declare namespace TraceEntity {
+    type Identifier = string | number;
+}

package/dist/cjs/api/types/TraceReferencedEntity.d.ts

@@ -1,6 +1,9 @@
 export interface TraceReferencedEntity {
     entity: string;
-    identifier?: string;
+    identifier?: TraceReferencedEntity.Identifier;
     reference?: string;
     is_visible: boolean;
 }
+export declare namespace TraceReferencedEntity {
+    type Identifier = string | number;
+}

package/dist/cjs/api/types/TraceSelfReviewEntity.d.ts

@@ -1,9 +1,12 @@
 import type * as Apollo from "../index.js";
 export interface TraceSelfReviewEntity {
     entity: string;
-    identifier?: string;
+    identifier?: TraceSelfReviewEntity.Identifier;
     reference?: string;
     sub_entities?: Apollo.TracSelfReviewSubEntity[];
     self_review?: Apollo.TraceSelfReviewSection;
     is_visible: boolean;
 }
+export declare namespace TraceSelfReviewEntity {
+    type Identifier = string | number;
+}

package/dist/cjs/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.2.39";
+export declare const SDK_VERSION = "1.2.41";

package/dist/cjs/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_VERSION = void 0;
-exports.SDK_VERSION = "1.2.39";
+exports.SDK_VERSION = "1.2.41";

package/dist/esm/Client.mjs

@@ -9,8 +9,8 @@ export class ApolloClient {
                 "x-network-api-key": _options === null || _options === void 0 ? void 0 : _options.networkApiKey,
                 "X-Fern-Language": "JavaScript",
                 "X-Fern-SDK-Name": "@aui.io/aui-client",
-                "X-Fern-SDK-Version": "1.2.39",
-                "User-Agent": "@aui.io/aui-client/1.2.39",
+                "X-Fern-SDK-Version": "1.2.41",
+                "User-Agent": "@aui.io/aui-client/1.2.41",
                 "X-Fern-Runtime": core.RUNTIME.type,
                 "X-Fern-Runtime-Version": core.RUNTIME.version,
             }, _options === null || _options === void 0 ? void 0 : _options.headers) });

package/dist/esm/api/types/TaskParameter.d.mts

@@ -10,6 +10,7 @@ export interface TaskParameter {
     is_anchor?: boolean;
     is_value_filled?: boolean;
     is_visible?: boolean;
+    is_exist_param?: boolean;
     param_type?: Apollo.ParameterType;
     code?: string;
 }

package/dist/esm/api/types/TraceEntity.d.mts

@@ -1,9 +1,12 @@
 import type * as Apollo from "../index.mjs";
 export interface TraceEntity {
     entity: string;
-    identifier?: string;
+    identifier?: TraceEntity.Identifier;
     reference?: string;
     source: Apollo.TraceEntitySource;
     params?: Record<string, unknown>;
     sub_entities?: Apollo.TraceSubEntity[];
 }
+export declare namespace TraceEntity {
+    type Identifier = string | number;
+}

package/dist/esm/api/types/TraceReferencedEntity.d.mts

@@ -1,6 +1,9 @@
 export interface TraceReferencedEntity {
     entity: string;
-    identifier?: string;
+    identifier?: TraceReferencedEntity.Identifier;
     reference?: string;
     is_visible: boolean;
 }
+export declare namespace TraceReferencedEntity {
+    type Identifier = string | number;
+}

package/dist/esm/api/types/TraceSelfReviewEntity.d.mts

@@ -1,9 +1,12 @@
 import type * as Apollo from "../index.mjs";
 export interface TraceSelfReviewEntity {
     entity: string;
-    identifier?: string;
+    identifier?: TraceSelfReviewEntity.Identifier;
     reference?: string;
     sub_entities?: Apollo.TracSelfReviewSubEntity[];
     self_review?: Apollo.TraceSelfReviewSection;
     is_visible: boolean;
 }
+export declare namespace TraceSelfReviewEntity {
+    type Identifier = string | number;
+}

package/dist/esm/version.d.mts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.2.39";
+export declare const SDK_VERSION = "1.2.41";

package/dist/esm/version.mjs

@@ -1 +1 @@
-export const SDK_VERSION = "1.2.39";
+export const SDK_VERSION = "1.2.41";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@aui.io/aui-client",
-    "version": "1.2.39",
+    "version": "1.2.41",
     "private": false,
     "repository": "github:aui-io/aui-client-typescript",
     "type": "commonjs",