archastro.platform.channels.api_chat_channel

  1# Copyright (c) 2026 ArchAstro Inc. All Rights Reserved.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 25ed606eeb04
  4
  5from collections.abc import Callable
  6from datetime import datetime
  7from typing import TYPE_CHECKING, Any, Literal, Required, TypedDict
  8
  9if TYPE_CHECKING:
 10    from archastro.phx_channel.socket import Socket
 11
 12
 13class ApiChatForkThreadInput(TypedDict, total=False):
 14    "Fork a sub-thread from an existing message"
 15
 16    message_id: Required[str]
 17    title: str
 18
 19
 20class ApiChatMarkThreadReadInput(TypedDict):
 21    "Mark a thread as read up to a given message"
 22
 23    message_id: str
 24
 25
 26class ApiChatLoadMoreMessagesInput(TypedDict, total=False):
 27    "Load additional messages with cursor-based pagination"
 28
 29    after_cursor: str
 30    before_cursor: str
 31    include_metadata: bool
 32    limit: int
 33
 34
 35class ApiChatPostMessageInput(TypedDict, total=False):
 36    "Post a new message with optional uploads and reply-to"
 37
 38    content: Required[str]
 39    idempotency_key: str
 40    reply_to: str
 41    uploads: list[dict[str, Any]]
 42
 43
 44class ApiChatPostSimpleMessageInput(TypedDict, total=False):
 45    "Post a simple text message"
 46
 47    content: str
 48    idempotency_key: str
 49    reply_to: str
 50
 51
 52class ApiChatEditMessageInput(TypedDict):
 53    "Edit an existing message's content"
 54
 55    content: str
 56    message_id: str
 57
 58
 59class ApiChatDeleteMessageInput(TypedDict):
 60    "Delete a message"
 61
 62    message_id: str
 63
 64
 65class ApiChatAddReactionInput(TypedDict):
 66    "Add an emoji reaction to a message"
 67
 68    emoji: str
 69    message_id: str
 70
 71
 72class ApiChatRemoveReactionInput(TypedDict):
 73    "Remove an emoji reaction from a message"
 74
 75    emoji: str
 76    message_id: str
 77
 78
 79class ApiChatTypingInput(TypedDict):
 80    "Signal that the current user has started or stopped typing in the thread"
 81
 82    is_typing: bool
 83
 84
 85class MessageAddedPayloadMessageActorsItemProfilePicture(TypedDict, total=False):
 86    file: str | None
 87    "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file."
 88    height: int | None
 89    "Height of the image in pixels. `null` if not known."
 90    media: str | None
 91    "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity."
 92    mime_type: str | None
 93    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.'
 94    refresh_url: str | None
 95    "Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing."
 96    url: str | None
 97    "Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires."
 98    width: int | None
 99    "Width of the image in pixels. `null` if not known."
100
101
102class MessageAddedPayloadMessageActorsItem(TypedDict, total=False):
103    alias: str | None
104    "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured."
105    id: str | None
106    'Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.'
107    name: str | None
108    "Display name of the actor shown in the UI. `null` if no name is set."
109    profile_picture: MessageAddedPayloadMessageActorsItemProfilePicture | None
110    "Profile picture for the actor. `null` if the actor has no profile picture."
111
112
113class MessageAddedPayloadMessageAttachmentsItemImageSource(TypedDict, total=False):
114    file: str | None
115    "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file."
116    height: int | None
117    "Height of the image in pixels. `null` if not known."
118    media: str | None
119    "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity."
120    mime_type: str | None
121    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.'
122    refresh_url: str | None
123    "Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing."
124    url: str | None
125    "Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires."
126    width: int | None
127    "Width of the image in pixels. `null` if not known."
128
129
130class MessageAddedPayloadMessageAttachmentsItemVariantsItemImageSource(TypedDict, total=False):
131    file: str | None
132    "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file."
133    height: int | None
134    "Height of the image in pixels. `null` if not known."
135    media: str | None
136    "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity."
137    mime_type: str | None
138    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.'
139    refresh_url: str | None
140    "Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing."
141    url: str | None
142    "Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires."
143    width: int | None
144    "Width of the image in pixels. `null` if not known."
145
146
147class MessageAddedPayloadMessageAttachmentsItemVariantsItem(TypedDict, total=False):
148    content_type: str | None
149    'MIME type of this variant\'s file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.'
150    created_at: datetime | None
151    "When this variant was created (ISO 8601)."
152    file: str | None
153    "ID of the underlying storage file that backs this variant (`fil_...`)."
154    filename: str | None
155    "Original filename of the uploaded file for this variant. `null` if the file is not loaded."
156    height: int | None
157    "Height of this variant in pixels. `null` if not recorded."
158    id: Required[str]
159    "Media variant ID (`mvr_...`)."
160    image_source: MessageAddedPayloadMessageAttachmentsItemVariantsItemImageSource | None
161    "Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types."
162    updated_at: datetime | None
163    "When this variant was last updated (ISO 8601)."
164    url: str | None
165    "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable."
166    variant_key: str | None
167    'Identifier for this variant\'s processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).'
168    width: int | None
169    "Width of this variant in pixels. `null` if not recorded."
170
171
172class MessageAddedPayloadMessageAttachmentsItem(TypedDict, total=False):
173    content_type: str | None
174    'MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.'
175    description: str | None
176    "Short description. The page meta-description for `scraped_link`, the artifact description for `artifact`, and the task description for `task` types. `null` on other types."
177    filename: str | None
178    'Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.'
179    height: int | None
180    "Height in pixels of the media item. Present on `media` type only. `null` otherwise."
181    id: Required[str]
182    "Unique identifier for this attachment within the message."
183    image_height: int | None
184    "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise."
185    image_source: MessageAddedPayloadMessageAttachmentsItemImageSource | None
186    "Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise."
187    image_url: str | None
188    "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise."
189    image_width: int | None
190    "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise."
191    media_type: str | None
192    'The media category, e.g. `"video"` or `"audio"`. Present on `media` type only. `null` otherwise.'
193    name: str | None
194    "Display name of the media item. Present on `media` type only. `null` otherwise."
195    object: dict[str, Any] | None
196    "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. `null` on other types."
197    title: str | None
198    "Display title. The page title for `scraped_link`, the artifact name for `artifact`, and the task title for `task` types. `null` on other types."
199    type: Required[str]
200    'The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, or `"action"`. Determines which additional fields are present.'
201    url: str | None
202    "URL to access the resource. A signed download URL for `file` and `artifact` types; the original URL for `scraped_link`; a media playback URL for `media`. `null` on `task` and `action` types."
203    variants: list[MessageAddedPayloadMessageAttachmentsItemVariantsItem] | None
204    "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise."
205    version: int | None
206    "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise."
207    width: int | None
208    "Width in pixels of the media item. Present on `media` type only. `null` otherwise."
209
210
211class MessageAddedPayloadMessageReactionsItem(TypedDict, total=False):
212    payload: dict[str, Any] | None
213    'Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `" "`).'
214    type: Required[str]
215    'Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.'
216    user: str | None
217    "Public ID of the user who added the reaction (`usr_...`)."
218
219
220class MessageAddedPayloadMessage(TypedDict, total=False):
221    actors: list[MessageAddedPayloadMessageActorsItem] | None
222    "Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry."
223    agent: str | None
224    "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users."
225    agent_mode: Literal["cli", "embedded"] | None
226    "Local agent execution mode for this message. One of `cli`, `embedded`, or `null` when the message was not created by a local agent execution path."
227    attachments: list[MessageAddedPayloadMessageAttachmentsItem] | None
228    "Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments."
229    branched_thread: str | None
230    "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread."
231    content: str | None
232    "Text content of the message. `null` for messages that contain only attachments."
233    created_at: datetime | None
234    "When the message was posted (ISO 8601)."
235    has_replies: bool | None
236    "Whether this message has at least one reply. Only present when explicitly requested or computed by the server."
237    id: Required[str]
238    "Message ID (`msg_...`)."
239    idempotency_key: str | None
240    "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one."
241    legacy_agent: str | None
242    "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users."
243    metadata: dict[str, Any] | None
244    "Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set."
245    org: str | None
246    "ID of the organization that owns this message (`org_...`)."
247    reactions: list[MessageAddedPayloadMessageReactionsItem] | None
248    "Emoji and other reactions added to this message by users. Empty array if no reactions have been added or the association is not preloaded."
249    rendering_mode: str | None
250    'Display hint for how the message should be rendered. One of `"reply"`, `"direct"`, or `"inline"`. `null` for user-authored messages, which are always rendered as standard replies.'
251    replies: list[dict[str, Any]] | None
252    "Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message."
253    replies_after_cursor: str | None
254    "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response."
255    replies_before_cursor: str | None
256    "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response."
257    reply_count: int | None
258    "Total number of direct replies to this message. Only present when explicitly requested or computed by the server."
259    reply_to: dict[str, Any] | None
260    "The parent message this message is a reply to, expanded as a full message object when loaded. `null` if this is a top-level message or the association is not preloaded."
261    sandbox: str | None
262    "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages."
263    team: str | None
264    "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped."
265    thread: str | None
266    "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread."
267    user: str | None
268    "The human user who sent this message. Returns a public ID string (`usr_...`) when the association is not preloaded, or an expanded user object when it is. `null` for messages sent by agents."
269
270
271class MessageAddedPayload(TypedDict, total=False):
272    "Broadcast when a new message is added to a thread"
273
274    after_cursor: str | None
275    before_cursor: str | None
276    message: MessageAddedPayloadMessage | None
277    "A chat message posted in a thread, including its content, author, attachments, reactions, and optional reply metadata."
278    thread_id: str | None
279
280
281class MessageUpdatedPayloadMessageActorsItemProfilePicture(TypedDict, total=False):
282    file: str | None
283    "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file."
284    height: int | None
285    "Height of the image in pixels. `null` if not known."
286    media: str | None
287    "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity."
288    mime_type: str | None
289    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.'
290    refresh_url: str | None
291    "Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing."
292    url: str | None
293    "Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires."
294    width: int | None
295    "Width of the image in pixels. `null` if not known."
296
297
298class MessageUpdatedPayloadMessageActorsItem(TypedDict, total=False):
299    alias: str | None
300    "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured."
301    id: str | None
302    'Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.'
303    name: str | None
304    "Display name of the actor shown in the UI. `null` if no name is set."
305    profile_picture: MessageUpdatedPayloadMessageActorsItemProfilePicture | None
306    "Profile picture for the actor. `null` if the actor has no profile picture."
307
308
309class MessageUpdatedPayloadMessageAttachmentsItemImageSource(TypedDict, total=False):
310    file: str | None
311    "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file."
312    height: int | None
313    "Height of the image in pixels. `null` if not known."
314    media: str | None
315    "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity."
316    mime_type: str | None
317    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.'
318    refresh_url: str | None
319    "Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing."
320    url: str | None
321    "Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires."
322    width: int | None
323    "Width of the image in pixels. `null` if not known."
324
325
326class MessageUpdatedPayloadMessageAttachmentsItemVariantsItemImageSource(TypedDict, total=False):
327    file: str | None
328    "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file."
329    height: int | None
330    "Height of the image in pixels. `null` if not known."
331    media: str | None
332    "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity."
333    mime_type: str | None
334    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.'
335    refresh_url: str | None
336    "Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing."
337    url: str | None
338    "Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires."
339    width: int | None
340    "Width of the image in pixels. `null` if not known."
341
342
343class MessageUpdatedPayloadMessageAttachmentsItemVariantsItem(TypedDict, total=False):
344    content_type: str | None
345    'MIME type of this variant\'s file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.'
346    created_at: datetime | None
347    "When this variant was created (ISO 8601)."
348    file: str | None
349    "ID of the underlying storage file that backs this variant (`fil_...`)."
350    filename: str | None
351    "Original filename of the uploaded file for this variant. `null` if the file is not loaded."
352    height: int | None
353    "Height of this variant in pixels. `null` if not recorded."
354    id: Required[str]
355    "Media variant ID (`mvr_...`)."
356    image_source: MessageUpdatedPayloadMessageAttachmentsItemVariantsItemImageSource | None
357    "Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types."
358    updated_at: datetime | None
359    "When this variant was last updated (ISO 8601)."
360    url: str | None
361    "Signed download URL for this variant, resolved at request time. `null` if the file is unavailable."
362    variant_key: str | None
363    'Identifier for this variant\'s processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).'
364    width: int | None
365    "Width of this variant in pixels. `null` if not recorded."
366
367
368class MessageUpdatedPayloadMessageAttachmentsItem(TypedDict, total=False):
369    content_type: str | None
370    'MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.'
371    description: str | None
372    "Short description. The page meta-description for `scraped_link`, the artifact description for `artifact`, and the task description for `task` types. `null` on other types."
373    filename: str | None
374    'Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.'
375    height: int | None
376    "Height in pixels of the media item. Present on `media` type only. `null` otherwise."
377    id: Required[str]
378    "Unique identifier for this attachment within the message."
379    image_height: int | None
380    "Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise."
381    image_source: MessageUpdatedPayloadMessageAttachmentsItemImageSource | None
382    "Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise."
383    image_url: str | None
384    "URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise."
385    image_width: int | None
386    "Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise."
387    media_type: str | None
388    'The media category, e.g. `"video"` or `"audio"`. Present on `media` type only. `null` otherwise.'
389    name: str | None
390    "Display name of the media item. Present on `media` type only. `null` otherwise."
391    object: dict[str, Any] | None
392    "The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. `null` on other types."
393    title: str | None
394    "Display title. The page title for `scraped_link`, the artifact name for `artifact`, and the task title for `task` types. `null` on other types."
395    type: Required[str]
396    'The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, or `"action"`. Determines which additional fields are present.'
397    url: str | None
398    "URL to access the resource. A signed download URL for `file` and `artifact` types; the original URL for `scraped_link`; a media playback URL for `media`. `null` on `task` and `action` types."
399    variants: list[MessageUpdatedPayloadMessageAttachmentsItemVariantsItem] | None
400    "Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise."
401    version: int | None
402    "Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise."
403    width: int | None
404    "Width in pixels of the media item. Present on `media` type only. `null` otherwise."
405
406
407class MessageUpdatedPayloadMessageReactionsItem(TypedDict, total=False):
408    payload: dict[str, Any] | None
409    'Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `" "`).'
410    type: Required[str]
411    'Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.'
412    user: str | None
413    "Public ID of the user who added the reaction (`usr_...`)."
414
415
416class MessageUpdatedPayloadMessage(TypedDict, total=False):
417    actors: list[MessageUpdatedPayloadMessageActorsItem] | None
418    "Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry."
419    agent: str | None
420    "ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users."
421    agent_mode: Literal["cli", "embedded"] | None
422    "Local agent execution mode for this message. One of `cli`, `embedded`, or `null` when the message was not created by a local agent execution path."
423    attachments: list[MessageUpdatedPayloadMessageAttachmentsItem] | None
424    "Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments."
425    branched_thread: str | None
426    "ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread."
427    content: str | None
428    "Text content of the message. `null` for messages that contain only attachments."
429    created_at: datetime | None
430    "When the message was posted (ISO 8601)."
431    has_replies: bool | None
432    "Whether this message has at least one reply. Only present when explicitly requested or computed by the server."
433    id: Required[str]
434    "Message ID (`msg_...`)."
435    idempotency_key: str | None
436    "Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one."
437    legacy_agent: str | None
438    "Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users."
439    metadata: dict[str, Any] | None
440    "Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set."
441    org: str | None
442    "ID of the organization that owns this message (`org_...`)."
443    reactions: list[MessageUpdatedPayloadMessageReactionsItem] | None
444    "Emoji and other reactions added to this message by users. Empty array if no reactions have been added or the association is not preloaded."
445    rendering_mode: str | None
446    'Display hint for how the message should be rendered. One of `"reply"`, `"direct"`, or `"inline"`. `null` for user-authored messages, which are always rendered as standard replies.'
447    replies: list[dict[str, Any]] | None
448    "Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message."
449    replies_after_cursor: str | None
450    "Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response."
451    replies_before_cursor: str | None
452    "Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response."
453    reply_count: int | None
454    "Total number of direct replies to this message. Only present when explicitly requested or computed by the server."
455    reply_to: dict[str, Any] | None
456    "The parent message this message is a reply to, expanded as a full message object when loaded. `null` if this is a top-level message or the association is not preloaded."
457    sandbox: str | None
458    "ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages."
459    team: str | None
460    "ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped."
461    thread: str | None
462    "ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread."
463    user: str | None
464    "The human user who sent this message. Returns a public ID string (`usr_...`) when the association is not preloaded, or an expanded user object when it is. `null` for messages sent by agents."
465
466
467class MessageUpdatedPayload(TypedDict, total=False):
468    "Broadcast when a message is updated or removed"
469
470    message: MessageUpdatedPayloadMessage | None
471    "A chat message posted in a thread, including its content, author, attachments, reactions, and optional reply metadata."
472    thread_id: str | None
473
474
475class ThreadEventPayload(TypedDict, total=False):
476    "Broadcast thread-level events (agent updates, read state, unread counts)"
477
478    payload: dict[str, Any] | None
479    thread_id: str | None
480    type: str | None
481
482
483class SystemEventPayload(TypedDict, total=False):
484    "Broadcast system-wide events"
485
486    event: dict[str, Any] | None
487
488
489class TypingPayloadActorProfilePicture(TypedDict, total=False):
490    file: str | None
491    "ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file."
492    height: int | None
493    "Height of the image in pixels. `null` if not known."
494    media: str | None
495    "ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity."
496    mime_type: str | None
497    'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.'
498    refresh_url: str | None
499    "Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing."
500    url: str | None
501    "Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires."
502    width: int | None
503    "Width of the image in pixels. `null` if not known."
504
505
506class TypingPayloadActor(TypedDict, total=False):
507    alias: str | None
508    "Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured."
509    id: str | None
510    'Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.'
511    name: str | None
512    "Display name of the actor shown in the UI. `null` if no name is set."
513    profile_picture: TypingPayloadActorProfilePicture | None
514    "Profile picture for the actor. `null` if the actor has no profile picture."
515
516
517class TypingPayload(TypedDict, total=False):
518    "Broadcast when a participant (human or agent) starts or stops typing. Ephemeral; never persisted."
519
520    actor: TypingPayloadActor | None
521    "The entity that authored a message, either a human user or an agent."
522    is_typing: bool | None
523    thread_id: str | None
524
525
526# Channel for real-time chat messaging.
527# Supports team-scoped and user-scoped threads with keyed, transient, and direct
528# thread access patterns.
529class ApiChatChannel:
530    def __init__(self, channel, join_response=None):
531        self._channel = channel
532        self.join_response = join_response
533
534    # Join a team-scoped thread by ID
535    @staticmethod
536    def topic_team_thread(team_id: str, thread_id: str) -> str:
537        return f"api:chat:team:{team_id}:thread:{thread_id}"
538
539    # Join a team-scoped thread by ID
540    @classmethod
541    async def join_team_thread(
542        cls,
543        socket: "Socket",
544        team_id: str,
545        thread_id: str,
546        *,
547        after_cursor: str | None = None,
548        before_cursor: str | None = None,
549        include_metadata: bool | None = None,
550        limit: int | None = None,
551    ) -> "ApiChatChannel":
552        topic = cls.topic_team_thread(team_id, thread_id)
553        channel = socket.channel(topic)
554        payload: dict[str, object] = {}
555        if after_cursor is not None:
556            payload["after_cursor"] = after_cursor
557        if before_cursor is not None:
558            payload["before_cursor"] = before_cursor
559        if include_metadata is not None:
560            payload["include_metadata"] = include_metadata
561        if limit is not None:
562            payload["limit"] = limit
563        join_response = await channel.join(payload)
564        return cls(channel, join_response)
565
566    # Join or create a team-scoped keyed thread
567    @staticmethod
568    def topic_team_keyed(team_id: str, key: str) -> str:
569        return f"api:chat:team:{team_id}:key:{key}"
570
571    # Join or create a team-scoped keyed thread
572    @classmethod
573    async def join_team_keyed(
574        cls,
575        socket: "Socket",
576        team_id: str,
577        key: str,
578        *,
579        after_cursor: str | None = None,
580        before_cursor: str | None = None,
581        include_metadata: bool | None = None,
582        limit: int | None = None,
583    ) -> "ApiChatChannel":
584        topic = cls.topic_team_keyed(team_id, key)
585        channel = socket.channel(topic)
586        payload: dict[str, object] = {}
587        if after_cursor is not None:
588            payload["after_cursor"] = after_cursor
589        if before_cursor is not None:
590            payload["before_cursor"] = before_cursor
591        if include_metadata is not None:
592            payload["include_metadata"] = include_metadata
593        if limit is not None:
594            payload["limit"] = limit
595        join_response = await channel.join(payload)
596        return cls(channel, join_response)
597
598    # Join a team-scoped transient (ephemeral) thread
599    @staticmethod
600    def topic_team_transient(team_id: str, key: str) -> str:
601        return f"api:chat:team:{team_id}:transient:{key}"
602
603    # Join a team-scoped transient (ephemeral) thread
604    @classmethod
605    async def join_team_transient(
606        cls,
607        socket: "Socket",
608        team_id: str,
609        key: str,
610        *,
611        after_cursor: str | None = None,
612        before_cursor: str | None = None,
613        include_metadata: bool | None = None,
614        limit: int | None = None,
615    ) -> "ApiChatChannel":
616        topic = cls.topic_team_transient(team_id, key)
617        channel = socket.channel(topic)
618        payload: dict[str, object] = {}
619        if after_cursor is not None:
620            payload["after_cursor"] = after_cursor
621        if before_cursor is not None:
622            payload["before_cursor"] = before_cursor
623        if include_metadata is not None:
624            payload["include_metadata"] = include_metadata
625        if limit is not None:
626            payload["limit"] = limit
627        join_response = await channel.join(payload)
628        return cls(channel, join_response)
629
630    # Join a user-scoped thread by ID
631    @staticmethod
632    def topic_user_thread(thread_id: str) -> str:
633        return f"api:chat:user:thread:{thread_id}"
634
635    # Join a user-scoped thread by ID
636    @classmethod
637    async def join_user_thread(
638        cls,
639        socket: "Socket",
640        thread_id: str,
641        *,
642        after_cursor: str | None = None,
643        before_cursor: str | None = None,
644        include_metadata: bool | None = None,
645        limit: int | None = None,
646    ) -> "ApiChatChannel":
647        topic = cls.topic_user_thread(thread_id)
648        channel = socket.channel(topic)
649        payload: dict[str, object] = {}
650        if after_cursor is not None:
651            payload["after_cursor"] = after_cursor
652        if before_cursor is not None:
653            payload["before_cursor"] = before_cursor
654        if include_metadata is not None:
655            payload["include_metadata"] = include_metadata
656        if limit is not None:
657            payload["limit"] = limit
658        join_response = await channel.join(payload)
659        return cls(channel, join_response)
660
661    # Join or create a user-scoped keyed thread
662    @staticmethod
663    def topic_user_keyed(key: str) -> str:
664        return f"api:chat:user:key:{key}"
665
666    # Join or create a user-scoped keyed thread
667    @classmethod
668    async def join_user_keyed(
669        cls,
670        socket: "Socket",
671        key: str,
672        *,
673        after_cursor: str | None = None,
674        before_cursor: str | None = None,
675        include_metadata: bool | None = None,
676        limit: int | None = None,
677    ) -> "ApiChatChannel":
678        topic = cls.topic_user_keyed(key)
679        channel = socket.channel(topic)
680        payload: dict[str, object] = {}
681        if after_cursor is not None:
682            payload["after_cursor"] = after_cursor
683        if before_cursor is not None:
684            payload["before_cursor"] = before_cursor
685        if include_metadata is not None:
686            payload["include_metadata"] = include_metadata
687        if limit is not None:
688            payload["limit"] = limit
689        join_response = await channel.join(payload)
690        return cls(channel, join_response)
691
692    # Join a user-scoped transient (ephemeral) thread
693    @staticmethod
694    def topic_user_transient(key: str) -> str:
695        return f"api:chat:user:transient:{key}"
696
697    # Join a user-scoped transient (ephemeral) thread
698    @classmethod
699    async def join_user_transient(
700        cls,
701        socket: "Socket",
702        key: str,
703        *,
704        after_cursor: str | None = None,
705        before_cursor: str | None = None,
706        include_metadata: bool | None = None,
707        limit: int | None = None,
708    ) -> "ApiChatChannel":
709        topic = cls.topic_user_transient(key)
710        channel = socket.channel(topic)
711        payload: dict[str, object] = {}
712        if after_cursor is not None:
713            payload["after_cursor"] = after_cursor
714        if before_cursor is not None:
715            payload["before_cursor"] = before_cursor
716        if include_metadata is not None:
717            payload["include_metadata"] = include_metadata
718        if limit is not None:
719            payload["limit"] = limit
720        join_response = await channel.join(payload)
721        return cls(channel, join_response)
722
723    # Leave the underlying channel.
724    async def leave(self):
725        await self._channel.leave()
726
727    # Fork a sub-thread from an existing message
728    async def api_chat_fork_thread(self, payload: ApiChatForkThreadInput) -> dict[str, Any]:
729        return await self._channel.push("api:chat:fork_thread", payload)
730
731    # Mark a thread as read up to a given message
732    async def api_chat_mark_thread_read(
733        self, payload: ApiChatMarkThreadReadInput
734    ) -> dict[str, Any]:
735        return await self._channel.push("api:chat:mark_thread_read", payload)
736
737    # List all messages in the current thread
738    async def api_chat_list_messages(self, payload: dict) -> dict[str, Any]:
739        return await self._channel.push("api:chat:list_messages", payload)
740
741    # Load additional messages with cursor-based pagination
742    async def api_chat_load_more_messages(
743        self, payload: ApiChatLoadMoreMessagesInput
744    ) -> dict[str, Any]:
745        return await self._channel.push("api:chat:load_more_messages", payload)
746
747    # Post a new message with optional uploads and reply-to
748    async def api_chat_post_message(self, payload: ApiChatPostMessageInput) -> dict[str, Any]:
749        return await self._channel.push("api:chat:post_message", payload)
750
751    # Post a simple text message
752    async def api_chat_post_simple_message(
753        self, payload: ApiChatPostSimpleMessageInput
754    ) -> dict[str, Any]:
755        return await self._channel.push("api:chat:post_simple_message", payload)
756
757    # Edit an existing message's content
758    async def api_chat_edit_message(self, payload: ApiChatEditMessageInput) -> dict[str, Any]:
759        return await self._channel.push("api:chat:edit_message", payload)
760
761    # Delete a message
762    async def api_chat_delete_message(self, payload: ApiChatDeleteMessageInput) -> dict[str, Any]:
763        return await self._channel.push("api:chat:delete_message", payload)
764
765    # Add an emoji reaction to a message
766    async def api_chat_add_reaction(self, payload: ApiChatAddReactionInput) -> dict[str, Any]:
767        return await self._channel.push("api:chat:add_reaction", payload)
768
769    # Remove an emoji reaction from a message
770    async def api_chat_remove_reaction(self, payload: ApiChatRemoveReactionInput) -> dict[str, Any]:
771        return await self._channel.push("api:chat:remove_reaction", payload)
772
773    # Signal that the current user has started or stopped typing in the thread
774    async def api_chat_typing(self, payload: ApiChatTypingInput) -> dict[str, Any]:
775        return await self._channel.push("api:chat:typing", payload)
776
777    # Broadcast when a new message is added to a thread
778    def on_message_added(
779        self, callback: Callable[[MessageAddedPayload], None]
780    ) -> Callable[[], None]:
781        return self._channel.on("message_added", callback)
782
783    # Broadcast when a message is updated or removed
784    def on_message_updated(
785        self, callback: Callable[[MessageUpdatedPayload], None]
786    ) -> Callable[[], None]:
787        return self._channel.on("message_updated", callback)
788
789    # Broadcast thread-level events (agent updates, read state, unread counts)
790    def on_thread_event(self, callback: Callable[[ThreadEventPayload], None]) -> Callable[[], None]:
791        return self._channel.on("thread_event", callback)
792
793    # Broadcast system-wide events
794    def on_system_event(self, callback: Callable[[SystemEventPayload], None]) -> Callable[[], None]:
795        return self._channel.on("system_event", callback)
796
797    # Broadcast when a participant (human or agent) starts or stops typing. Ephemeral; never persisted.
798    def on_typing(self, callback: Callable[[TypingPayload], None]) -> Callable[[], None]:
799        return self._channel.on("typing", callback)