@ada-cx/messaging-bridge 1.3.3 → 1.4.0

package/dist-npm/contract/state-keys.d.ts

@@ -32,6 +32,10 @@ export declare const STATE: {
     readonly CHAT_IS_SENDING: "chat.isSending";
     readonly CHAT_MESSAGES: "chat.messages";
     readonly CHAT_COMPOSER_TEXT: "chat.composerText";
+    readonly CHAT_STAGED_ATTACHMENTS: "chat.stagedAttachments";
+    /** The newest entry of `chat.stagedAttachments`, for consumers written
+     * against the single-image contract. An app reading only this key cannot
+     * address the other staged images, and a send posts all of them. */
     readonly CHAT_STAGED_ATTACHMENT: "chat.stagedAttachment";
     readonly CHAT_ATTACHMENT_REJECTION: "chat.attachmentRejection";
     readonly CHAT_IMAGE_UPLOAD_VISIBLE: "chat.imageUploadVisible";

package/dist-npm/contract/types.d.ts

@@ -179,11 +179,19 @@ export interface StagedAttachment {
     /** Hosted URL, present once `status` is `ready`. */
     url?: string;
 }
-/** A pick the composer could not stage, kept apart from `chat.stagedAttachment`
- * so it never displaces a staged image. Replaced by the next pick. */
+/** A pick the composer could not stage, kept apart from
+ * `chat.stagedAttachments` so it never displaces a staged image.
+ *
+ * Replaced by the next *rejection*, and cleared on a conversation boundary
+ * (handoff, rollover, reset). A later successful pick leaves it standing: under
+ * `multiple` the app forwards each file as its own stage event, so clearing on
+ * a stage would swallow the refusal of a file picked alongside an accepted one.
+ * Render it as a transient notice keyed on `id`, not as persistent state. */
 export interface StagedAttachmentRejection {
     id: string;
-    error: "unsupported_type" | "too_large" | "unavailable" | "upload_failed";
+    /** `too_many` is new with multi-image staging: an exhaustive switch written
+     * against the single-image contract needs a case for it. */
+    error: "unsupported_type" | "too_large" | "too_many" | "unavailable" | "upload_failed";
 }
 export interface DownloadableMessage extends BaseMessage {
     type: "downloadable";
@@ -192,6 +200,10 @@ export interface DownloadableMessage extends BaseMessage {
     mimeType: string | null;
     /** Text sent with the file, when the chatter typed a message alongside it. */
     caption?: string;
+    /** Shared by every row of one multi-image send, so consecutive rows can be
+     * rendered as one group. Absent on a single image: treat that as a group of
+     * one rather than assuming the key is always there. */
+    attachmentGroupId?: string;
 }
 export interface AgentInfo {
     name: string;
@@ -484,10 +496,16 @@ export interface AppDisplayState {
         text: string;
         revision: number;
     } | null;
-    /** The image the chatter picked for the next bot send. Hosted as soon as it is
-     * picked; the composer shows it as a chip until the send consumes it. Absent on
-     * a core document that predates image attachments. Core keeps the storage key
-     * to itself. */
+    /** The images the chatter picked for the next bot send, in the order they are
+     * sent and rendered. Each is hosted as soon as it is picked; the composer shows
+     * them until the send consumes them. Absent on a core document that predates
+     * multi-image. Core keeps the storage key to itself. */
+    "chat.stagedAttachments"?: StagedAttachment[];
+    /** The NEWEST entry of `chat.stagedAttachments`, kept so an app written
+     * against the single-image contract keeps working — that contract replaced
+     * each pick with the next, so this key names what the chatter last chose.
+     * Prefer the list: this key cannot represent a second staged image, and a
+     * send posts every entry, including the ones it never showed. */
     "chat.stagedAttachment"?: StagedAttachment | null;
     /** The most recent pick that could not be staged, beside whatever is staged. */
     "chat.attachmentRejection"?: StagedAttachmentRejection | null;
@@ -788,9 +806,19 @@ export interface AppEvents {
     };
     "file.upload.cancel": undefined;
     "file.upload.errorDismiss": undefined;
-    /** Host the picked image for the next bot send. */
+    /**
+     * Host the picked image for the next bot send.
+     *
+     * `allowMultiple` is the app's opt-in to the staged LIST. Without it a pick
+     * replaces the previous one, which is what an app written against the
+     * single-image contract expects: such an app renders
+     * `chat.stagedAttachment`, can only remove what it renders, and would
+     * otherwise send an image the chatter believes they swapped out. Opt in only
+     * once the app reads `chat.stagedAttachments` and can remove any entry.
+     */
     "chat.attachment.stage": {
         file: File;
+        allowMultiple?: boolean;
     };
     /** Drop the staged image named by `id`; ignored once another pick replaced it. */
     "chat.attachment.remove": {

package/dist-npm/shared-utils/file-upload.d.ts

@@ -24,6 +24,22 @@ export type FileUploadErrorReason =
 /** Size cap of the bot image attachment: api's `MAX_FILE_SIZE_BYTES_FOR_STORAGE_UPLOAD`. */
 export declare const IMAGE_ATTACHMENT_MAX_MB = 50;
 export declare const IMAGE_ATTACHMENT_MAX_BYTES: number;
+/**
+ * How many images one send may carry.
+ *
+ * Not an api limit on this path. `MAX_DESCRIBED_IMAGE_ATTACHMENTS` is read in
+ * one api runtime site, `resolve_email_image_attachments_suffix`, which is the
+ * email channel; the bot path posts one `downloadable` per image and describes
+ * each through `resolve_uploaded_file_message_body`, which caps nothing. api
+ * also never reads `attachment_group_id` outside analytics, so it cannot batch
+ * a group into one describe budget. A fourth image would be hosted, rendered
+ * *and* described — in its own reasoner turn.
+ *
+ * So the cap is a product decision about that cost, not a ceiling api imposes:
+ * each extra image buys another bot turn and another describe call. Match it to
+ * `MAX_DESCRIBED_IMAGE_ATTACHMENTS` by coincidence of value only.
+ */
+export declare const IMAGE_ATTACHMENT_MAX_COUNT = 3;
 /** The image types api's attachments route accepts; HEIC/HEIF are transcoded to JPEG there. */
 export declare const IMAGE_ATTACHMENT_MIME_TYPES: readonly string[];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ada-cx/messaging-bridge",
-	"version": "1.3.3",
+	"version": "1.4.0",
 	"description": "Types, test mocks, and a thin CDN loader for building a custom app UI on Ada Messaging's bridge contract. The bridge runtime always loads from Ada's CDN.",
 	"type": "module",
 	"license": "ISC",