mavenagi 1.2.4 → 1.2.5

package/Client.js

@@ -59,8 +59,8 @@ class MavenAGIClient {
                 "X-Agent-Id": _options === null || _options === void 0 ? void 0 : _options.agentId,
                 "X-Fern-Language": "JavaScript",
                 "X-Fern-SDK-Name": "mavenagi",
-                "X-Fern-SDK-Version": "1.2.4",
-                "User-Agent": "mavenagi/1.2.4",
+                "X-Fern-SDK-Version": "1.2.5",
+                "User-Agent": "mavenagi/1.2.5",
                 "X-Fern-Runtime": core.RUNTIME.type,
                 "X-Fern-Runtime-Version": core.RUNTIME.version,
             }, _options === null || _options === void 0 ? void 0 : _options.headers) });

package/README.md

@@ -102,6 +102,396 @@ try {
 }
 ```
 
+## Binary Response
+
+You can consume binary data from endpoints using the `BinaryResponse` type which lets you choose how to consume the data:
+
+```typescript
+const response = await client.conversation.export(...);
+const stream: ReadableStream<Uint8Array> = response.stream();
+// const arrayBuffer: ArrayBuffer = await response.arrayBuffer();
+// const blob: Blob = response.blob();
+// const bytes: Uint8Array = response.bytes();
+// You can only use the response body once, so you must choose one of the above methods.
+// If you want to check if the response body has been used, you can use the following property.
+const bodyUsed = response.bodyUsed;
+```
+
+<details>
+<summary>Save binary response to a file</summary>
+
+<blockquote>
+<details>
+<summary>Node.js</summary>
+
+<blockquote>
+<details>
+<summary>ReadableStream (most-efficient)</summary>
+
+```ts
+import { createWriteStream } from 'fs';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
+
+const response = await client.conversation.export(...);
+
+const stream = response.stream();
+const nodeStream = Readable.fromWeb(stream);
+const writeStream = createWriteStream('path/to/file');
+
+await pipeline(nodeStream, writeStream);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+import { writeFile } from 'fs/promises';
+
+const response = await client.conversation.export(...);
+
+const arrayBuffer = await response.arrayBuffer();
+await writeFile('path/to/file', Buffer.from(arrayBuffer));
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Blob</summary>
+
+```ts
+import { writeFile } from 'fs/promises';
+
+const response = await client.conversation.export(...);
+
+const blob = await response.blob();
+const arrayBuffer = await blob.arrayBuffer();
+await writeFile('output.bin', Buffer.from(arrayBuffer));
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+import { writeFile } from 'fs/promises';
+
+const response = await client.conversation.export(...);
+
+const bytes = await response.bytes();
+await writeFile('path/to/file', bytes);
+```
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bun</summary>
+
+<blockquote>
+<details>
+<summary>ReadableStream (most-efficient)</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const stream = response.stream();
+await Bun.write('path/to/file', stream);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const arrayBuffer = await response.arrayBuffer();
+await Bun.write('path/to/file', arrayBuffer);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Blob</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const blob = await response.blob();
+await Bun.write('path/to/file', blob);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const bytes = await response.bytes();
+await Bun.write('path/to/file', bytes);
+```
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Deno</summary>
+
+<blockquote>
+<details>
+<summary>ReadableStream (most-efficient)</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const stream = response.stream();
+const file = await Deno.open('path/to/file', { write: true, create: true });
+await stream.pipeTo(file.writable);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const arrayBuffer = await response.arrayBuffer();
+await Deno.writeFile('path/to/file', new Uint8Array(arrayBuffer));
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Blob</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const blob = await response.blob();
+const arrayBuffer = await blob.arrayBuffer();
+await Deno.writeFile('path/to/file', new Uint8Array(arrayBuffer));
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const bytes = await response.bytes();
+await Deno.writeFile('path/to/file', bytes);
+```
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Browser</summary>
+
+<blockquote>
+<details>
+<summary>Blob (most-efficient)</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const blob = await response.blob();
+const url = URL.createObjectURL(blob);
+
+// trigger download
+const a = document.createElement('a');
+a.href = url;
+a.download = 'filename';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ReadableStream</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const stream = response.stream();
+const reader = stream.getReader();
+const chunks = [];
+
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  chunks.push(value);
+}
+
+const blob = new Blob(chunks);
+const url = URL.createObjectURL(blob);
+
+// trigger download
+const a = document.createElement('a');
+a.href = url;
+a.download = 'filename';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const arrayBuffer = await response.arrayBuffer();
+const blob = new Blob([arrayBuffer]);
+const url = URL.createObjectURL(blob);
+
+// trigger download
+const a = document.createElement('a');
+a.href = url;
+a.download = 'filename';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const bytes = await response.bytes();
+const blob = new Blob([bytes]);
+const url = URL.createObjectURL(blob);
+
+// trigger download
+const a = document.createElement('a');
+a.href = url;
+a.download = 'filename';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+<details>
+<summary>Convert binary response to text</summary>
+
+<blockquote>
+<details>
+<summary>ReadableStream</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const stream = response.stream();
+const text = await new Response(stream).text();
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const arrayBuffer = await response.arrayBuffer();
+const text = new TextDecoder().decode(arrayBuffer);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Blob</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const blob = await response.blob();
+const text = await blob.text();
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+const response = await client.conversation.export(...);
+
+const bytes = await response.bytes();
+const text = new TextDecoder().decode(bytes);
+```
+
+</details>
+</blockquote>
+
+</details>
+
 ## Advanced
 
 ### Additional Headers

package/api/resources/actions/client/Client.d.ts

@@ -115,7 +115,17 @@ export declare class Actions {
      * @throws {@link MavenAGI.ServerError}
      *
      * @example
-     *     await client.actions.patch("actionReferenceId")
+     *     await client.actions.patch("get-balance", {
+     *         instructions: "Use this action when the user asks about their account balance or remaining credits.",
+     *         llmInclusionStatus: "WHEN_RELEVANT",
+     *         segmentId: {
+     *             referenceId: "premium-users",
+     *             appId: "my-billing-system",
+     *             organizationId: "acme",
+     *             agentId: "support",
+     *             type: "SEGMENT"
+     *         }
+     *     })
      */
     patch(actionReferenceId: string, request?: MavenAGI.ActionPatchRequest, requestOptions?: Actions.RequestOptions): core.HttpResponsePromise<MavenAGI.ActionResponse>;
     private __patch;

package/api/resources/actions/client/Client.js

@@ -375,7 +375,17 @@ class Actions {
      * @throws {@link MavenAGI.ServerError}
      *
      * @example
-     *     await client.actions.patch("actionReferenceId")
+     *     await client.actions.patch("get-balance", {
+     *         instructions: "Use this action when the user asks about their account balance or remaining credits.",
+     *         llmInclusionStatus: "WHEN_RELEVANT",
+     *         segmentId: {
+     *             referenceId: "premium-users",
+     *             appId: "my-billing-system",
+     *             organizationId: "acme",
+     *             agentId: "support",
+     *             type: "SEGMENT"
+     *         }
+     *     })
      */
     patch(actionReferenceId, request = {}, requestOptions) {
         return core.HttpResponsePromise.fromPromise(this.__patch(actionReferenceId, request, requestOptions));

package/api/resources/actions/client/requests/ActionPatchRequest.d.ts

@@ -1,7 +1,17 @@
 import * as MavenAGI from "../../../../index";
 /**
  * @example
- *     {}
+ *     {
+ *         instructions: "Use this action when the user asks about their account balance or remaining credits.",
+ *         llmInclusionStatus: "WHEN_RELEVANT",
+ *         segmentId: {
+ *             referenceId: "premium-users",
+ *             appId: "my-billing-system",
+ *             organizationId: "acme",
+ *             agentId: "support",
+ *             type: "SEGMENT"
+ *         }
+ *     }
  */
 export interface ActionPatchRequest {
     /** The App ID of the action to patch. If not provided the ID of the calling app will be used. */

package/api/resources/agents/client/Client.d.ts

@@ -128,9 +128,9 @@ export declare class Agents {
      * @throws {@link MavenAGI.ServerError}
      *
      * @example
-     *     await client.agents.patch("organizationReferenceId", "agentReferenceId", {})
+     *     await client.agents.patch("organizationReferenceId", "agentReferenceId")
      */
-    patch(organizationReferenceId: string, agentReferenceId: string, request: MavenAGI.AgentPatchRequest, requestOptions?: Agents.RequestOptions): core.HttpResponsePromise<MavenAGI.Agent>;
+    patch(organizationReferenceId: string, agentReferenceId: string, request?: MavenAGI.AgentPatchRequest, requestOptions?: Agents.RequestOptions): core.HttpResponsePromise<MavenAGI.Agent>;
     private __patch;
     /**
      * Delete an agent.

package/api/resources/agents/client/Client.js

@@ -460,13 +460,13 @@ class Agents {
      * @throws {@link MavenAGI.ServerError}
      *
      * @example
-     *     await client.agents.patch("organizationReferenceId", "agentReferenceId", {})
+     *     await client.agents.patch("organizationReferenceId", "agentReferenceId")
      */
-    patch(organizationReferenceId, agentReferenceId, request, requestOptions) {
+    patch(organizationReferenceId, agentReferenceId, request = {}, requestOptions) {
         return core.HttpResponsePromise.fromPromise(this.__patch(organizationReferenceId, agentReferenceId, request, requestOptions));
     }
-    __patch(organizationReferenceId, agentReferenceId, request, requestOptions) {
-        return __awaiter(this, void 0, void 0, function* () {
+    __patch(organizationReferenceId_1, agentReferenceId_1) {
+        return __awaiter(this, arguments, void 0, function* (organizationReferenceId, agentReferenceId, request = {}, requestOptions) {
             var _a, _b, _c, _d, _e, _f, _g, _h;
             let _headers = (0, headers_1.mergeHeaders)((_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, (0, headers_1.mergeOnlyDefinedHeaders)({
                 Authorization: yield this._getAuthorizationHeader(),
@@ -477,7 +477,7 @@ class Agents {
                 url: core.url.join((_h = (_g = (yield core.Supplier.get(this._options.baseUrl))) !== null && _g !== void 0 ? _g : (yield core.Supplier.get(this._options.environment))) !== null && _h !== void 0 ? _h : environments.MavenAGIEnvironment.Production, `/v1/organizations/${encodeURIComponent(organizationReferenceId)}/agents/${encodeURIComponent(agentReferenceId)}`),
                 method: "PATCH",
                 headers: _headers,
-                contentType: "application/json",
+                contentType: "application/merge-patch+json",
                 queryParameters: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams,
                 requestType: "json",
                 body: serializers.AgentPatchRequest.jsonOrThrow(request, { unrecognizedObjectKeys: "strip" }),

package/api/resources/agents/client/index.d.ts

@@ -1 +1,2 @@
 export {};
+export * from "./requests";

package/api/resources/agents/client/index.js

@@ -1,2 +1,17 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./requests"), exports);

package/api/resources/agents/client/requests/AgentPatchRequest.d.ts

@@ -0,0 +1,27 @@
+import * as MavenAGI from "../../../../index";
+/**
+ * @example
+ *     {}
+ */
+export interface AgentPatchRequest {
+    /** The name of the agent. */
+    name?: string;
+    /** The environment of the agent. */
+    environment?: MavenAGI.AgentEnvironment;
+    /** The agent's default timezone. This is used when a timezone is not set on a conversation. */
+    defaultTimezone?: string;
+    /** The PII categories that are enabled for the agent. */
+    enabledPiiCategories?: Set<MavenAGI.PiiCategory>;
+    /** The system fallback message. */
+    systemFallbackMessage?: string | null;
+    /** The overall persona of the agent. */
+    persona?: MavenAGI.LlmPersona;
+    /** Additional text directly appended to the prompt. */
+    additionalPromptText?: string | null;
+    /** LLM prompt for category generation. */
+    categoryGenerationPromptText?: string | null;
+    /** LLM prompt for generating a response when the user's question has been detected as unsafe. */
+    contentSafetyViolationResponsePromptText?: string | null;
+    /** Return the system fallback message on all questions that have no relevant knowledge bases or actions. */
+    rejectQuestionsWithoutKnowledge?: boolean;
+}

package/api/resources/agents/client/requests/index.d.ts

@@ -0,0 +1 @@
+export { type AgentPatchRequest } from "./AgentPatchRequest";

package/api/resources/agents/client/requests/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/api/resources/agents/types/Agent.d.ts

@@ -20,4 +20,12 @@ export interface Agent {
      * `UsUkPassportNumber`, `UsSocialSecurityNumber`.
      */
     enabledPiiCategories: Set<MavenAGI.PiiCategory>;
+    /**
+     * Text shown to end users when the system encounters an error while generating a bot response message.
+     *
+     * This text is also used when a content safety violation is detected, unless `contentSafetyViolationPromptText` is set.
+     */
+    systemFallbackMessage?: string;
+    /** Agent prompting settings. */
+    prompting: MavenAGI.AgentPrompting;
 }

package/api/resources/agents/types/AgentPrompting.d.ts

@@ -0,0 +1,23 @@
+import * as MavenAGI from "../../../index";
+export interface AgentPrompting {
+    /** The overall persona of the agent. */
+    persona: MavenAGI.LlmPersona;
+    /** Additional text directly appended to the prompt. This field is replaced by Knowledge Documents with `llmInclusionsStatus` set to `ALWAYS`. */
+    additionalPromptText?: string;
+    /**
+     * LLM prompt for category generation.
+     *
+     * Use this to specify a fixed set of categories that an LLM should choose from when analyzing a conversation.
+     * When not set uses a default prompt which gives the LLM flexibility to determine appropriate categories on its own.
+     */
+    categoryGenerationPromptText?: string;
+    /**
+     * LLM prompt for generating a response when the user's question has been detected as unsafe.
+     *
+     * Use this to provide custom LLM generated replies when dealing with content safety violations.
+     * When not set, the system fallback message will be used and replies will not be personalized by the LLM as it will not be involved.
+     */
+    contentSafetyViolationResponsePromptText?: string;
+    /** Return the system fallback message on all questions that have no relevant knowledge bases or actions. */
+    rejectQuestionsWithoutKnowledge: boolean;
+}

package/api/resources/agents/types/index.d.ts

@@ -2,8 +2,8 @@ export * from "./PiiCategory";
 export * from "./AgentEnvironment";
 export * from "./Agent";
 export * from "./CreateAgentRequest";
-export * from "./AgentPatchRequest";
 export * from "./AgentsSearchRequest";
 export * from "./AgentField";
 export * from "./AgentFilter";
 export * from "./AgentsSearchResponse";
+export * from "./AgentPrompting";

package/api/resources/agents/types/index.js

@@ -18,8 +18,8 @@ __exportStar(require("./PiiCategory"), exports);
 __exportStar(require("./AgentEnvironment"), exports);
 __exportStar(require("./Agent"), exports);
 __exportStar(require("./CreateAgentRequest"), exports);
-__exportStar(require("./AgentPatchRequest"), exports);
 __exportStar(require("./AgentsSearchRequest"), exports);
 __exportStar(require("./AgentField"), exports);
 __exportStar(require("./AgentFilter"), exports);
 __exportStar(require("./AgentsSearchResponse"), exports);
+__exportStar(require("./AgentPrompting"), exports);

package/api/resources/analytics/types/ConversationBarChartRequest.d.ts

@@ -3,6 +3,16 @@ export interface ConversationBarChartRequest extends MavenAGI.ConversationAnalyt
     /**
      * Determines how data is grouped along the x-axis. Each unique value forms a separate bar.
      * The name of the bar is derived from the grouping field's value or range.
+     *
+     * **Label Formats by Field:**
+     * - `Sources`: Document title (e.g., "Product Documentation")
+     * - `Actions`: "Action Name - App Name" (e.g., "Create Ticket - Freshdesk")
+     * - `IncompleteActions`: "Action Name - App Name" (e.g., "Search Documents - Zendesk")
+     * - `Users`: User identifier value (e.g., "user@example.com")
+     * - `InboxItems`: Inbox item title
+     * - `HumanAgents`: Human agent display name
+     * - `HumanAgentsWithInserts`: Human agent display name (for agents who made inserts)
+     * - Other fields: Field value as stored (e.g., "GOOD", "NEEDS_IMPROVEMENT" for Quality)
      */
     barDefinition: MavenAGI.ConversationGroupBy;
     /** Metric defining the y-axis values for the bar chart. */
@@ -10,6 +20,16 @@ export interface ConversationBarChartRequest extends MavenAGI.ConversationAnalyt
     /**
      * Optionally defines vertical grouping within each bar, producing multiple series.
      * If omitted, a single series is generated.
+     *
+     * **Series Name Formats by Field:**
+     * - `Sources`: Document title (e.g., "Product Documentation")
+     * - `Actions`: "Action Name - App Name" (e.g., "Create Ticket - Freshdesk")
+     * - `IncompleteActions`: "Action Name - App Name" (e.g., "Search Documents - Zendesk")
+     * - `Users`: User identifier value (e.g., "user@example.com")
+     * - `InboxItems`: Inbox item title
+     * - `HumanAgents`: Human agent display name
+     * - `HumanAgentsWithInserts`: Human agent display name (for agents who made inserts)
+     * - Other fields: Field value as stored (e.g., "GOOD", "NEEDS_IMPROVEMENT" for Quality)
      */
     verticalGrouping?: MavenAGI.ConversationGroupBy;
 }

package/api/resources/analytics/types/ConversationDateHistogramRequest.d.ts

@@ -2,7 +2,19 @@ import * as MavenAGI from "../../../index";
 export interface ConversationDateHistogramRequest extends MavenAGI.ConversationAnalyticsRequest {
     /** Time-based grouping interval (e.g., HOUR, DAY, WEEK) for the date histogram. */
     timeInterval: MavenAGI.TimeInterval;
-    /** Groups data before applying calculations, forming a separate time series for each group. */
+    /**
+     * Groups data before applying calculations, forming a separate time series for each group.
+     *
+     * **Series Name Formats by Field:**
+     * - `Sources`: Document title (e.g., "Product Documentation")
+     * - `Actions`: "Action Name - App Name" (e.g., "Create Ticket - Freshdesk")
+     * - `IncompleteActions`: "Action Name - App Name" (e.g., "Search Documents - Zendesk")
+     * - `Users`: User identifier value (e.g., "user@example.com")
+     * - `InboxItems`: Inbox item title
+     * - `HumanAgents`: Human agent display name
+     * - `HumanAgentsWithInserts`: Human agent display name (for agents who made inserts)
+     * - Other fields: Field value as stored (e.g., "GOOD", "NEEDS_IMPROVEMENT" for Quality)
+     */
     groupBy?: MavenAGI.ConversationGroupBy;
     /** Defines the y-axis values for the date histogram. */
     metric: MavenAGI.ConversationMetric;