@cadraos/sdk 0.3.15 → 0.3.16-dev.1

package/dist/kanban/index.d.cts

@@ -1179,6 +1179,63 @@ interface ExecuteResponse {
     /** Initial status */
     status: ExecutionStatus;
 }
+/**
+ * Language code an agent message is stored and rendered in (e.g. `en`,
+ * `pt-br`). Each agent sets its own language list; see
+ * `AgentMessageList.languages`. Was `'en' | 'es' | 'id'` before p13.
+ */
+type AgentMessageLang = string;
+/**
+ * One saved agent message (e.g. `handoff.requested`), text per language.
+ */
+interface AgentMessage {
+    /** Lowercase dotted key, e.g. `chat.welcome` */
+    key: string;
+    /** Text per language code */
+    text: Partial<Record<AgentMessageLang, string>>;
+    /** `{word}` placeholder names found in any language */
+    placeholders: string[];
+}
+/**
+ * Response of `client.agents.messages.list()`
+ */
+interface AgentMessageList {
+    /** The resolved agent (a team uuid resolves to its lead agent) */
+    agentUuid: string;
+    /** The agent's saved messages, sorted by key */
+    messages: AgentMessage[];
+    /** Every key the platform knows about, for pickers (saved or not) */
+    knownKeys: string[];
+    /**
+     * The agent's message languages, in display order. Missing from older
+     * servers; fall back to the languages seen in `messages[].text`.
+     */
+    languages?: AgentMessageLang[];
+    /** The agent's default message language. Missing from older servers; treat as `en`. */
+    defaultLanguage?: AgentMessageLang;
+}
+/**
+ * Options for `client.agents.messages.render()`
+ */
+interface AgentMessageRenderOptions {
+    /**
+     * Requested language. Server falls back: exact, then base (`pt-br` to `pt`),
+     * then the agent's default language, then `en`, then the first non-empty text.
+     */
+    lang?: AgentMessageLang;
+    /** Values for `{word}` placeholders; unknown placeholders are left as-is */
+    vars?: Record<string, string | number>;
+}
+/**
+ * Response of `client.agents.messages.render()`
+ */
+interface AgentMessageRenderResult {
+    key: string;
+    /** The language actually rendered (after fallback) */
+    lang: AgentMessageLang;
+    /** Filled text, or `null` when the agent has no message for this key */
+    text: string | null;
+}
 
 /**
  * Image extraction utilities
@@ -3767,6 +3824,47 @@ interface StreamImagesResult {
     executionId: string;
 }
 
+/**
+ * Agent Messages Resource API (p13)
+ *
+ * Read-only access to an agent's saved messages (welcome, handoff, fallback
+ * copy, ...). Reached as `client.agents.messages`.
+ * - list(): the agent's saved messages, every known key, the agent's languages
+ * - render(): one message filled with vars, in a language (server falls back:
+ *   exact, base, agent default, en, first non-empty; `lang` says which was used)
+ */
+
+declare class AgentMessagesAPI extends BaseResourceAPI {
+    constructor(http: HttpClient);
+    /**
+     * List an agent's saved messages and the known keys
+     *
+     * @param agentUuid - Agent UUID (a team UUID resolves to its lead agent)
+     *
+     * @example
+     * ```typescript
+     * const { messages, knownKeys, languages, defaultLanguage } = await client.agents.messages.list('agent-uuid');
+     * ```
+     */
+    list(agentUuid: string): Promise<AgentMessageList>;
+    /**
+     * Render one message with placeholders filled
+     *
+     * Resolves with `text: null` when the agent has no message for the key.
+     * Throws `ValidationError` before any request when the key is not a
+     * lowercase dotted key (see `MESSAGE_KEY_PATTERN`).
+     *
+     * @example
+     * ```typescript
+     * const { text } = await client.agents.messages.render('agent-uuid', 'handoff.requested', {
+     *   lang: 'es',
+     *   vars: { agentName: 'Ana' },
+     * });
+     * ```
+     */
+    render(agentUuid: string, key: string, options?: AgentMessageRenderOptions): Promise<AgentMessageRenderResult>;
+}
+
 /**
  * Agents Resource API
  *
@@ -3782,6 +3880,8 @@ interface StreamImagesResult {
  */
 declare class AgentsAPI extends BaseResourceAPI {
     private readonly getStreamConfig;
+    /** Saved agent messages (p13): `list()` and `render()` */
+    readonly messages: AgentMessagesAPI;
     constructor(http: HttpClient, getStreamConfig: () => StreamConfig);
     /**
      * List all agents in the organization

package/dist/kanban/index.d.ts

@@ -1179,6 +1179,63 @@ interface ExecuteResponse {
     /** Initial status */
     status: ExecutionStatus;
 }
+/**
+ * Language code an agent message is stored and rendered in (e.g. `en`,
+ * `pt-br`). Each agent sets its own language list; see
+ * `AgentMessageList.languages`. Was `'en' | 'es' | 'id'` before p13.
+ */
+type AgentMessageLang = string;
+/**
+ * One saved agent message (e.g. `handoff.requested`), text per language.
+ */
+interface AgentMessage {
+    /** Lowercase dotted key, e.g. `chat.welcome` */
+    key: string;
+    /** Text per language code */
+    text: Partial<Record<AgentMessageLang, string>>;
+    /** `{word}` placeholder names found in any language */
+    placeholders: string[];
+}
+/**
+ * Response of `client.agents.messages.list()`
+ */
+interface AgentMessageList {
+    /** The resolved agent (a team uuid resolves to its lead agent) */
+    agentUuid: string;
+    /** The agent's saved messages, sorted by key */
+    messages: AgentMessage[];
+    /** Every key the platform knows about, for pickers (saved or not) */
+    knownKeys: string[];
+    /**
+     * The agent's message languages, in display order. Missing from older
+     * servers; fall back to the languages seen in `messages[].text`.
+     */
+    languages?: AgentMessageLang[];
+    /** The agent's default message language. Missing from older servers; treat as `en`. */
+    defaultLanguage?: AgentMessageLang;
+}
+/**
+ * Options for `client.agents.messages.render()`
+ */
+interface AgentMessageRenderOptions {
+    /**
+     * Requested language. Server falls back: exact, then base (`pt-br` to `pt`),
+     * then the agent's default language, then `en`, then the first non-empty text.
+     */
+    lang?: AgentMessageLang;
+    /** Values for `{word}` placeholders; unknown placeholders are left as-is */
+    vars?: Record<string, string | number>;
+}
+/**
+ * Response of `client.agents.messages.render()`
+ */
+interface AgentMessageRenderResult {
+    key: string;
+    /** The language actually rendered (after fallback) */
+    lang: AgentMessageLang;
+    /** Filled text, or `null` when the agent has no message for this key */
+    text: string | null;
+}
 
 /**
  * Image extraction utilities
@@ -3767,6 +3824,47 @@ interface StreamImagesResult {
     executionId: string;
 }
 
+/**
+ * Agent Messages Resource API (p13)
+ *
+ * Read-only access to an agent's saved messages (welcome, handoff, fallback
+ * copy, ...). Reached as `client.agents.messages`.
+ * - list(): the agent's saved messages, every known key, the agent's languages
+ * - render(): one message filled with vars, in a language (server falls back:
+ *   exact, base, agent default, en, first non-empty; `lang` says which was used)
+ */
+
+declare class AgentMessagesAPI extends BaseResourceAPI {
+    constructor(http: HttpClient);
+    /**
+     * List an agent's saved messages and the known keys
+     *
+     * @param agentUuid - Agent UUID (a team UUID resolves to its lead agent)
+     *
+     * @example
+     * ```typescript
+     * const { messages, knownKeys, languages, defaultLanguage } = await client.agents.messages.list('agent-uuid');
+     * ```
+     */
+    list(agentUuid: string): Promise<AgentMessageList>;
+    /**
+     * Render one message with placeholders filled
+     *
+     * Resolves with `text: null` when the agent has no message for the key.
+     * Throws `ValidationError` before any request when the key is not a
+     * lowercase dotted key (see `MESSAGE_KEY_PATTERN`).
+     *
+     * @example
+     * ```typescript
+     * const { text } = await client.agents.messages.render('agent-uuid', 'handoff.requested', {
+     *   lang: 'es',
+     *   vars: { agentName: 'Ana' },
+     * });
+     * ```
+     */
+    render(agentUuid: string, key: string, options?: AgentMessageRenderOptions): Promise<AgentMessageRenderResult>;
+}
+
 /**
  * Agents Resource API
  *
@@ -3782,6 +3880,8 @@ interface StreamImagesResult {
  */
 declare class AgentsAPI extends BaseResourceAPI {
     private readonly getStreamConfig;
+    /** Saved agent messages (p13): `list()` and `render()` */
+    readonly messages: AgentMessagesAPI;
     constructor(http: HttpClient, getStreamConfig: () => StreamConfig);
     /**
      * List all agents in the organization

package/dist/kanban/index.js

@@ -5410,13 +5410,69 @@ function executionCancelPath(executionId) {
   return `${EXECUTION_PATH}/${executionId}/cancel`;
 }
 
+// src/utils/message-key.ts
+var MESSAGE_KEY_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z0-9_]+)+$/;
+function isValidMessageKey(key) {
+  return MESSAGE_KEY_PATTERN.test(key);
+}
+
+// src/resources/agent-messages.ts
+var AgentMessagesAPI = class extends BaseResourceAPI {
+  constructor(http) {
+    super(http, "/api/v1/agents");
+  }
+  /**
+   * List an agent's saved messages and the known keys
+   *
+   * @param agentUuid - Agent UUID (a team UUID resolves to its lead agent)
+   *
+   * @example
+   * ```typescript
+   * const { messages, knownKeys, languages, defaultLanguage } = await client.agents.messages.list('agent-uuid');
+   * ```
+   */
+  async list(agentUuid) {
+    return this.httpGet(`/${agentUuid}/messages`);
+  }
+  /**
+   * Render one message with placeholders filled
+   *
+   * Resolves with `text: null` when the agent has no message for the key.
+   * Throws `ValidationError` before any request when the key is not a
+   * lowercase dotted key (see `MESSAGE_KEY_PATTERN`).
+   *
+   * @example
+   * ```typescript
+   * const { text } = await client.agents.messages.render('agent-uuid', 'handoff.requested', {
+   *   lang: 'es',
+   *   vars: { agentName: 'Ana' },
+   * });
+   * ```
+   */
+  async render(agentUuid, key, options = {}) {
+    if (!isValidMessageKey(key)) {
+      throw new ValidationError(`Invalid message key "${key}"`, [
+        { field: "key", message: "Must be a lowercase dotted key, e.g. chat.welcome" }
+      ]);
+    }
+    return this.httpPost(`/${agentUuid}/messages/render`, {
+      key,
+      ...options.lang ? { lang: options.lang } : {},
+      ...options.vars ? { vars: options.vars } : {}
+    });
+  }
+};
+
 // src/resources/agents.ts
 var AgentsAPI = class extends BaseResourceAPI {
   constructor(http, getStreamConfig) {
     super(http, "/api/v1/agents");
     this.getStreamConfig = getStreamConfig;
+    this.messages = new AgentMessagesAPI(http);
   }
   getStreamConfig;
+  /** Saved agent messages (p13): `list()` and `render()` */
+  messages;
   // ===== LIST Operations =====
   /**
    * List all agents in the organization