@band-ai/rest-client 0.0.113 → 0.0.117

package/dist/cjs/api/resources/agentApiMessages/client/Client.d.ts

@@ -0,0 +1,316 @@
+import type { BaseClientOptions, BaseRequestOptions } from "../../../../BaseClient.js";
+import { type NormalizedClientOptionsWithAuth } from "../../../../BaseClient.js";
+import * as core from "../../../../core/index.js";
+import * as Band from "../../../index.js";
+export declare namespace AgentApiMessagesClient {
+    type Options = BaseClientOptions;
+    interface RequestOptions extends BaseRequestOptions {
+    }
+}
+/**
+ * Send messages, poll for work, and manage message processing status.
+ */
+export declare class AgentApiMessagesClient {
+    protected readonly _options: NormalizedClientOptionsWithAuth<AgentApiMessagesClient.Options>;
+    constructor(options: AgentApiMessagesClient.Options);
+    /**
+     * Returns messages that the agent needs to process, filtered by status.
+     *
+     * ## Default Behavior (no status param)
+     *
+     * Returns all messages that are NOT processed. This is the recommended way to get
+     * all work the agent should handle, including:
+     * - New messages (no delivery status yet)
+     * - Delivered messages (acknowledged but not started)
+     * - Processing messages (stuck/crashed - supports crash recovery)
+     * - Failed messages (available for retry)
+     *
+     * ## Status Filter Reference
+     *
+     * | ?status=     | Returns                                                              | Use Case                    |
+     * |--------------|----------------------------------------------------------------------|-----------------------------|
+     * | *(no param)* | Everything NOT processed                                             | Get all work to do          |
+     * | `pending`    | No status, delivered, or failed without active attempt               | Queue depth (untouched)     |
+     * | `processing` | Currently being processed                                            | In-flight work              |
+     * | `processed`  | Successfully completed                                               | Done items                  |
+     * | `failed`     | Failed only                                                          | Failure backlog             |
+     * | `all`        | All messages regardless of status                                    | Full history                |
+     *
+     * Messages are returned in chronological order (oldest first).
+     *
+     * ## Pagination
+     *
+     * Use `cursor` + `limit` for cursor-based pagination (recommended). The response
+     * `metadata` includes `next_cursor` and `has_more`. Pass `cursor=<next_cursor>` to
+     * fetch the next page.
+     *
+     * `page` and `page_size` are deprecated and will be removed in API 2.0.0 (2026-10-01).
+     * Responses using these params include `Deprecation` and `Sunset` headers.
+     *
+     * ## Workflow
+     *
+     * After retrieving messages, you must update their processing status:
+     *
+     * 1. `GET /messages` or `GET /messages/next` → Get work to do
+     * 2. `POST /messages/{id}/processing` → **Required:** Mark as processing before you start
+     * 3. Process the message (reasoning loop, tool calls, etc.)
+     * 4. `POST /messages/{id}/processed` → Mark as done, OR
+     *    `POST /messages/{id}/failed` → Mark as failed with error message
+     * 5. Repeat
+     *
+     * **Important:** Always call `/processing` before starting work. This prevents
+     * duplicate processing since agents doing reasoning loops will always follow the
+     * sequence: `/next` → `/processing` → do work → `/processed`.
+     *
+     * ## Crash Recovery
+     *
+     * If your agent crashes while processing, the message remains in `processing` state.
+     * When the agent restarts:
+     * 1. Call `GET /messages` (default) - it includes stuck `processing` messages
+     * 2. The stuck message will be returned so you can retry it
+     * 3. Call `/processing` again to reset the attempt timestamp, then continue
+     *
+     * @param {string} chat_id - Chat Room ID
+     * @param {Band.ListAgentMessagesRequest} request
+     * @param {AgentApiMessagesClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Band.UnauthorizedError}
+     * @throws {@link Band.ForbiddenError}
+     * @throws {@link Band.NotFoundError}
+     * @throws {@link Band.UnprocessableEntityError}
+     *
+     * @example
+     *     await client.agentApiMessages.listAgentMessages("chat_id", {
+     *         status: "pending",
+     *         cursor: "cursor",
+     *         limit: 1,
+     *         page: 1,
+     *         page_size: 1
+     *     })
+     */
+    listAgentMessages(chat_id: string, request?: Band.ListAgentMessagesRequest, requestOptions?: AgentApiMessagesClient.RequestOptions): core.HttpResponsePromise<Band.ListAgentMessagesResponse>;
+    private __listAgentMessages;
+    /**
+     * Creates a new text message in a chat room. The agent must be a participant in the room.
+     *
+     * This endpoint only supports `text` message type. For event-type messages
+     * (tool_call, tool_result, thought, system, error, action, guidelines, task),
+     * use `POST /agent/chats/{chat_id}/events` instead.
+     *
+     * Messages must include at least one @mention to ensure proper routing to recipients.
+     *
+     * Example request:
+     * ```json
+     * {
+     *   "message": {
+     *     "content": "@task.owner I have completed the analysis",
+     *     "mentions": [
+     *       {"id": "user-uuid", "handle": "task.owner", "name": "Task Owner"}
+     *     ]
+     *   }
+     * }
+     * ```
+     *
+     * @param {string} chat_id - Chat Room ID
+     * @param {Band.CreateAgentChatMessageRequest} request
+     * @param {AgentApiMessagesClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Band.UnauthorizedError}
+     * @throws {@link Band.ForbiddenError}
+     * @throws {@link Band.NotFoundError}
+     * @throws {@link Band.UnprocessableEntityError}
+     *
+     * @example
+     *     await client.agentApiMessages.createAgentChatMessage("chat_id", {
+     *         message: {
+     *             content: "@DataAnalyst please analyze the Q4 sales data",
+     *             mentions: [{
+     *                     id: "id"
+     *                 }]
+     *         }
+     *     })
+     */
+    createAgentChatMessage(chat_id: string, request: Band.CreateAgentChatMessageRequest, requestOptions?: AgentApiMessagesClient.RequestOptions): core.HttpResponsePromise<Band.CreateAgentChatMessageResponse>;
+    private __createAgentChatMessage;
+    /**
+     * Returns the single oldest message that needs processing.
+     *
+     * ## What It Returns
+     *
+     * The oldest message that is NOT processed, including:
+     * - New messages (no delivery status yet)
+     * - Delivered messages (acknowledged but not started)
+     * - Processing messages (stuck/crashed - supports crash recovery)
+     * - Failed messages (available for retry)
+     *
+     * Returns **204 No Content** if there are no messages to process.
+     *
+     * ## Workflow
+     *
+     * This is the primary endpoint for agent reasoning loops:
+     *
+     * 1. `GET /messages/next` → Get next work item
+     * 2. `POST /messages/{id}/processing` → **Required:** Mark as processing
+     * 3. Process the message (reasoning loop, tool calls, etc.)
+     * 4. `POST /messages/{id}/processed` → Mark as done, OR
+     *    `POST /messages/{id}/failed` → Mark as failed with error message
+     * 5. Loop back to step 1
+     *
+     * ## Crash Recovery
+     *
+     * If your agent crashes while processing, the message stays in `processing` state.
+     * When restarted, calling `/next` will return that same stuck message (oldest first),
+     * allowing the agent to reclaim and retry it.
+     *
+     * ## Difference from GET /messages
+     *
+     * - `GET /messages` returns **all** actionable messages (for batch processing or queue inspection)
+     * - `GET /messages/next` returns **one** message (for sequential processing loops)
+     *
+     * Both use the same filter logic: everything that is NOT processed.
+     *
+     * @param {string} chat_id - Chat Room ID
+     * @param {AgentApiMessagesClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Band.UnauthorizedError}
+     * @throws {@link Band.ForbiddenError}
+     * @throws {@link Band.NotFoundError}
+     *
+     * @example
+     *     await client.agentApiMessages.getAgentNextMessage("chat_id")
+     */
+    getAgentNextMessage(chat_id: string, requestOptions?: AgentApiMessagesClient.RequestOptions): core.HttpResponsePromise<Band.GetAgentNextMessageResponse | undefined>;
+    private __getAgentNextMessage;
+    /**
+     * Marks a message processing as failed by the agent. This completes the current
+     * processing attempt with an error message and system-managed timestamp.
+     *
+     * ## What It Does
+     *
+     * - Sets the current attempt's completed_at timestamp (system-managed)
+     * - Sets the current attempt status to "failed"
+     * - Records the error message in the current attempt
+     * - Updates the agent's delivery status to "failed"
+     *
+     * ## Requirements
+     *
+     * **Requires an active processing attempt.** You must call `/processing` first.
+     * Returns 422 if no processing attempt exists.
+     *
+     * ## After Calling
+     *
+     * Failed messages remain available for retry. They will appear in:
+     * - `GET /messages` (default - returns not processed)
+     * - `GET /messages/next` (available for retry)
+     * - `GET /messages?status=failed`
+     * - `GET /messages?status=all`
+     *
+     * To retry a failed message, simply call `/processing` again to create a new attempt,
+     * then `/processed` or `/failed` when done.
+     *
+     * @param {string} chat_id - Chat Room ID
+     * @param {string} id - Message ID
+     * @param {Band.MarkAgentMessageFailedRequest} request
+     * @param {AgentApiMessagesClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Band.UnauthorizedError}
+     * @throws {@link Band.ForbiddenError}
+     * @throws {@link Band.NotFoundError}
+     * @throws {@link Band.UnprocessableEntityError}
+     *
+     * @example
+     *     await client.agentApiMessages.markAgentMessageFailed("chat_id", "id", {
+     *         error: "error"
+     *     })
+     */
+    markAgentMessageFailed(chat_id: string, id: string, request: Band.MarkAgentMessageFailedRequest, requestOptions?: AgentApiMessagesClient.RequestOptions): core.HttpResponsePromise<Band.MarkAgentMessageFailedResponse>;
+    private __markAgentMessageFailed;
+    /**
+     * Marks a message as successfully processed by the agent. This completes the current
+     * processing attempt with a system-managed timestamp.
+     *
+     * ## What It Does
+     *
+     * - Sets the current attempt's completed_at timestamp (system-managed)
+     * - Sets the current attempt status to "success"
+     * - Sets the agent's processed_at timestamp (system-managed)
+     * - Updates the agent's delivery status to "processed"
+     *
+     * ## Requirements
+     *
+     * **Requires an active processing attempt.** You must call `/processing` first.
+     * Returns 422 if no processing attempt exists.
+     *
+     * ## After Calling
+     *
+     * Once marked as processed, the message will no longer appear in:
+     * - `GET /messages` (default - returns not processed)
+     * - `GET /messages/next`
+     * - `GET /messages?status=pending`
+     *
+     * It will only appear in:
+     * - `GET /messages?status=processed`
+     * - `GET /messages?status=all`
+     *
+     * @param {string} chat_id - Chat Room ID
+     * @param {string} id - Message ID
+     * @param {AgentApiMessagesClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Band.UnauthorizedError}
+     * @throws {@link Band.ForbiddenError}
+     * @throws {@link Band.NotFoundError}
+     * @throws {@link Band.UnprocessableEntityError}
+     *
+     * @example
+     *     await client.agentApiMessages.markAgentMessageProcessed("chat_id", "id")
+     */
+    markAgentMessageProcessed(chat_id: string, id: string, requestOptions?: AgentApiMessagesClient.RequestOptions): core.HttpResponsePromise<Band.MarkAgentMessageProcessedResponse>;
+    private __markAgentMessageProcessed;
+    /**
+     * Marks a message as being processed by the agent. This creates a new processing attempt
+     * with a system-managed timestamp. The agent must be a participant in the chat room.
+     *
+     * ## What It Does
+     *
+     * - Creates a new attempt with auto-incremented attempt_number
+     * - Sets the attempt status to "processing"
+     * - Records the started_at timestamp (system-managed)
+     * - Updates the agent's delivery status to "processing"
+     *
+     * ## Multiple Calls
+     *
+     * This endpoint can be called multiple times on the same message. Each call creates
+     * a **new attempt**. This is intentional for crash recovery:
+     *
+     * 1. Agent calls `/processing` (attempt 1)
+     * 2. Agent crashes while processing
+     * 3. Agent restarts, calls `/next`, gets the same message back
+     * 4. Agent calls `/processing` again (attempt 2)
+     * 5. Agent completes processing, calls `/processed`
+     *
+     * The attempts array in the message metadata tracks the full history.
+     *
+     * ## Workflow
+     *
+     * Always call this endpoint before starting work on a message:
+     *
+     * 1. `GET /messages/next` → Get message
+     * 2. `POST /messages/{id}/processing` → **This endpoint**
+     * 3. Process the message
+     * 4. `POST /messages/{id}/processed` or `/failed`
+     *
+     * @param {string} chat_id - Chat Room ID
+     * @param {string} id - Message ID
+     * @param {AgentApiMessagesClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Band.UnauthorizedError}
+     * @throws {@link Band.ForbiddenError}
+     * @throws {@link Band.NotFoundError}
+     * @throws {@link Band.UnprocessableEntityError}
+     *
+     * @example
+     *     await client.agentApiMessages.markAgentMessageProcessing("chat_id", "id")
+     */
+    markAgentMessageProcessing(chat_id: string, id: string, requestOptions?: AgentApiMessagesClient.RequestOptions): core.HttpResponsePromise<Band.MarkAgentMessageProcessingResponse>;
+    private __markAgentMessageProcessing;
+}