@flamingo-stack/openframe-frontend-core 0.0.214 → 0.0.215-snapshot.20260529010429

package/src/components/tickets/help-center-card.tsx

@@ -55,6 +55,10 @@ export interface HelpCenterCardProps {
   onClose: TicketDetailDrawerProps['onClose']
   onReopen: TicketDetailDrawerProps['onReopen']
   onActionCollapsed: () => void
+  /** Persisted reply-failure banner — forwarded to the drawer. Parent
+   *  (`HelpCenterList`) reads via `actions.replyErrorFor(external_id)`. */
+  replyError?: TicketDetailDrawerProps['replyError']
+  onClearReplyError?: TicketDetailDrawerProps['onClearReplyError']
 }
 
 export function HelpCenterCard({
@@ -67,6 +71,8 @@ export function HelpCenterCard({
   onClose,
   onReopen,
   onActionCollapsed,
+  replyError,
+  onClearReplyError,
 }: HelpCenterCardProps) {
   const optimistic = isOptimistic(ticket)
   const rawStatus = (ticket.status ?? 'OPEN').toUpperCase()
@@ -177,6 +183,8 @@ export function HelpCenterCard({
             onClose={onClose}
             onReopen={onReopen}
             onActionCollapsed={onActionCollapsed}
+            replyError={replyError}
+            onClearReplyError={onClearReplyError}
           />
         </div>
       )}

package/src/components/tickets/help-center-list.tsx

@@ -285,6 +285,8 @@ function HelpCenterListAuthed({
                   onClose={actions.closeTicket}
                   onReopen={actions.reopenTicket}
                   onActionCollapsed={() => setExpandedTicketId(null)}
+                  replyError={actions.replyErrorFor(ticket.external_id)}
+                  onClearReplyError={() => actions.clearReplyError(ticket.external_id)}
                 />
               ))}
             </div>

package/src/components/tickets/hooks/use-ticket-actions.ts

@@ -44,6 +44,17 @@ import {
 
 const TICKET_ACTION_ENDPOINT = '/api/chat/agent/ticket-action'
 
+/** Codes that populate the inline reply-failure banner above the drawer
+ *  composer. Other codes (system-down, ticket-gone, rate-limit) are
+ *  full-row / full-system signals covered by the toast + supportSystemDown
+ *  handling — surfacing them in the inline banner too would be redundant. */
+const REPLY_BANNER_CODES: ReadonlySet<TicketActionErrorCode> = new Set<TicketActionErrorCode>([
+  'HUBSPOT_5XX',
+  'HUBSPOT_400_VALIDATION',
+  'HUBSPOT_404_THREAD',
+  'HUBSPOT_REPLY_UNKNOWN',
+])
+
 /** 3 attempts × backoff (cumulative ~21s wall-clock). After this we
  *  drop the optimistic row and ask the user to reload. */
 const MIRROR_SYNC_BACKOFF_MS = [3_000, 6_000, 12_000] as const
@@ -125,6 +136,14 @@ export interface UseTicketActionsReturn {
   isSubmittingForm: boolean
   /** Per-row in-flight set (read-only). UI uses `isRowBusy(localId)`. */
   isRowBusy: (localId: string) => boolean
+  /** Most recent reply failure for a given ticket id (`external_id`).
+   *  Drives the inline "couldn't send" banner above the composer in
+   *  `<TicketDetailDrawer>`. Cleared on the next successful send OR
+   *  via `clearReplyError(ticketId)`. */
+  replyErrorFor: (ticketExternalId: string) => MappedTicketActionError | null
+  /** Clear the persisted reply-failure banner for a ticket (e.g. when
+   *  the user dismisses it or starts a new draft). */
+  clearReplyError: (ticketExternalId: string) => void
 }
 
 export function useTicketActions(options: UseTicketActionsOptions): UseTicketActionsReturn {
@@ -151,6 +170,37 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
   }, [])
   const isRowBusy = useCallback((id: string) => busyRows.has(id), [busyRows])
 
+  // Persisted reply-failure banner state — keyed by the ticket's
+  // HubSpot `external_id`. The drawer reads `replyErrorFor(externalId)`
+  // and renders an inline "couldn't send — retry" banner above the
+  // composer. Cleared automatically on the next successful send and
+  // explicitly by the dismiss-X / "Retry" actions in the banner UI.
+  // Distinct from the transient toast — the banner persists so the
+  // user can locate their failed draft after dismissing the toast.
+  const [replyErrorByTicket, setReplyErrorByTicket] = useState<
+    Map<string, MappedTicketActionError>
+  >(() => new Map())
+  const setReplyError = useCallback(
+    (externalId: string, mapped: MappedTicketActionError | null) => {
+      setReplyErrorByTicket((prev) => {
+        const next = new Map(prev)
+        if (mapped) next.set(externalId, mapped)
+        else next.delete(externalId)
+        return next
+      })
+    },
+    [],
+  )
+  const replyErrorFor = useCallback(
+    (externalId: string): MappedTicketActionError | null =>
+      replyErrorByTicket.get(externalId) ?? null,
+    [replyErrorByTicket],
+  )
+  const clearReplyError = useCallback(
+    (externalId: string) => setReplyError(externalId, null),
+    [setReplyError],
+  )
+
   // Mirror-sync watcher controllers tracked by placeholder id so we can
   // abort prior watchers when a new submit lands AND so unmount cleans
   // them up without leaking setState calls. Single source of truth for
@@ -262,9 +312,15 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
     [queryClient, removeOptimistic, toast],
   )
 
+  // Last `surfaceError` mapping — sendMessage reads this immediately
+  // after the catch returns so it can decide whether to populate the
+  // inline reply banner. Cleared on every read by the consumer to
+  // prevent a stale failure from leaking into the next attempt.
+  const lastUpdateErrorRef = useRef<MappedTicketActionError | null>(null)
   const surfaceError = useCallback(
     (err: unknown, action: string): MappedTicketActionError => {
       const mapped = mapTicketActionError(err)
+      lastUpdateErrorRef.current = mapped
       if (mapped.supportSystemDown) onSupportSystemDown()
       toast({
         title: `Could not ${action}`,
@@ -302,6 +358,10 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
         // seconds via the mirror refetch. Drawer uses live chat
         // identity for own-replies during this window anyway.
         customer_name: null,
+        // No assignee until the real ticket lands. Drawer renders
+        // "Unassigned" for this brief window.
+        assigned_to: null,
+        assignedOwner: null,
         hubspot_updated_at: new Date().toISOString(),
         _optimistic: true,
       }
@@ -393,12 +453,18 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
   )
 
   const sendMessage = useCallback(
-    (ticket: TicketRef, text: string, attachments: ChatAttachment[]) => {
+    async (ticket: TicketRef, text: string, attachments: ChatAttachment[]) => {
       const trimmed = text.trim()
       const hasText = trimmed.length > 0
       const hasFiles = attachments.length > 0
-      if (!hasText && !hasFiles) return Promise.resolve(false)
-      return updateTicket(
+      if (!hasText && !hasFiles) return false
+      // Clear any stale mapped error from a prior non-sendMessage action
+      // (closeTicket / reopenTicket) so the post-call read only picks up
+      // an error THIS sendMessage produced. Without this clear, a prior
+      // close-failure's mapped error could leak into the banner via the
+      // post-call `lastUpdateErrorRef.current` read.
+      lastUpdateErrorRef.current = null
+      const ok = await updateTicket(
         ticket,
         {
           ...(hasText ? { content_addendum: trimmed } : {}),
@@ -407,8 +473,33 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
         TOAST_COPY.comment_success,
         'send message',
       )
+      // Banner-state coupling: SUCCESS clears any stale failure banner
+      // for this ticket; FAILURE populates the banner ONLY for the
+      // reply-specific code subset (HUBSPOT_5XX / 400 / 404 / UNKNOWN).
+      // Other codes (TICKET_NOT_FOUND, HUBSPOT_DISCONNECTED, RATE_LIMITED)
+      // are full-row / full-system signals already covered by the
+      // existing toast + supportSystemDown handling — surfacing them in
+      // the inline banner too would be redundant.
+      if (ok) {
+        clearReplyError(ticket.external_id)
+      } else {
+        // Line 466's `.current = null` narrows the property to literal
+        // `null`. `tsc -p tsconfig.declarations.json` (declarations
+        // build, distinct from the `tsc --noEmit` pre-step) doesn't
+        // widen that narrowing across the `await updateTicket(...)`,
+        // so the read here is typed `never`. The runtime type IS
+        // `MappedTicketActionError | null` per the useRef declaration;
+        // the assertion just tells TS to honor it instead of the stale
+        // narrowing.
+        const mapped = lastUpdateErrorRef.current as MappedTicketActionError | null
+        if (mapped && REPLY_BANNER_CODES.has(mapped.code)) {
+          setReplyError(ticket.external_id, mapped)
+        }
+        lastUpdateErrorRef.current = null
+      }
+      return ok
     },
-    [updateTicket],
+    [updateTicket, clearReplyError, setReplyError],
   )
 
   const closeTicket = useCallback(
@@ -439,8 +530,19 @@ export function useTicketActions(options: UseTicketActionsOptions): UseTicketAct
       reopenTicket,
       isSubmittingForm,
       isRowBusy,
+      replyErrorFor,
+      clearReplyError,
     }),
-    [submitTicket, sendMessage, closeTicket, reopenTicket, isSubmittingForm, isRowBusy],
+    [
+      submitTicket,
+      sendMessage,
+      closeTicket,
+      reopenTicket,
+      isSubmittingForm,
+      isRowBusy,
+      replyErrorFor,
+      clearReplyError,
+    ],
   )
 }
 
@@ -512,6 +614,38 @@ export function mapTicketActionError(err: unknown): MappedTicketActionError {
           supportSystemDown: false,
           removeRowFromCache: false,
         }
+      case 'HUBSPOT_5XX':
+        return {
+          code: err.code,
+          message:
+            "We couldn't reach the support system. Your reply wasn't sent — please retry in a moment.",
+          supportSystemDown: false,
+          removeRowFromCache: false,
+        }
+      case 'HUBSPOT_400_VALIDATION':
+        return {
+          code: err.code,
+          message:
+            'Your reply was rejected. Please rephrase or remove unsupported content and try again.',
+          supportSystemDown: false,
+          removeRowFromCache: false,
+        }
+      case 'HUBSPOT_404_THREAD':
+        return {
+          code: err.code,
+          message:
+            'This conversation is no longer accepting replies. Open a new ticket to continue.',
+          supportSystemDown: false,
+          removeRowFromCache: false,
+        }
+      case 'HUBSPOT_REPLY_UNKNOWN':
+        return {
+          code: err.code,
+          message:
+            "Your reply didn't go through. Please retry.",
+          supportSystemDown: false,
+          removeRowFromCache: false,
+        }
       default:
         return {
           code: 'UNKNOWN',

package/src/components/tickets/ticket-detail-drawer.tsx

@@ -46,12 +46,17 @@ import {
   ConversationCardRowSkeletonList,
 } from './../shared/dev-section/dev-card-row'
 import type { TicketAttachment } from './../ui/ticket-attachments-list'
+import { SquareAvatar } from './../ui/square-avatar'
 import { useTicketEngagements } from './hooks/use-ticket-engagements'
 import type {
   TicketEngagementFile,
 } from './hooks/use-ticket-engagements'
 import { TicketLinkedDeliveryCard } from './ticket-linked-delivery-card'
-import type { AnyTicket } from './types'
+import type {
+  AnyTicket,
+  TicketAssignedOwner,
+  MappedTicketActionError,
+} from './types'
 import { isOptimistic, TICKET_TEXT_MAX_CHARS } from './types'
 
 /** Identity bundle threaded through the action callbacks: local mirror
@@ -76,6 +81,15 @@ export interface TicketDetailDrawerProps {
   /** Called after a successful close/reopen so the parent can collapse
    *  the drawer (status flipped — current action set is now stale). */
   onActionCollapsed: () => void
+  /** Persisted reply-failure surface — when non-null the drawer renders
+   *  an inline banner above the composer with the mapped copy + a
+   *  dismiss control. Distinct from the transient toast; the banner
+   *  stays visible so the customer can locate the failed draft after
+   *  the toast disappears. Cleared on the next successful send. */
+  replyError?: MappedTicketActionError | null
+  /** Dismiss-X handler for the banner. Parent calls
+   *  `actions.clearReplyError(ticket.external_id)`. */
+  onClearReplyError?: () => void
 }
 
 export function TicketDetailDrawer({
@@ -86,10 +100,19 @@ export function TicketDetailDrawer({
   onClose,
   onReopen,
   onActionCollapsed,
+  replyError,
+  onClearReplyError,
 }: TicketDetailDrawerProps) {
   const isClosed = (ticket.status ?? '').toUpperCase() === 'CLOSED'
   return (
     <div className="bg-ods-card border-t border-ods-border px-4 py-4 flex flex-col gap-4">
+      {/* Assignee header — surfaces who's looking at this ticket on the
+          support side. Populated server-side via `attachOwnerProfiles`;
+          falls back to "Unassigned" when no agent is assigned OR when
+          the owner couldn't be resolved (deleted between ticket update
+          + next owners reconcile). */}
+      <AssignedAgentRow assignedOwner={ticket.assignedOwner} />
+
       {/* Linked ClickUp delivery — rendered only when the server's
           `attachClickupTasks` step populated `ticket.clickup`. Customer
           tickets with no linked task skip this entirely. The card itself
@@ -107,6 +130,19 @@ export function TicketDetailDrawer({
       </div>
 
       <div className="border-t border-ods-border pt-4">
+        {/* Reply-failure banner — populated by `useTicketActions` when
+            the last sendMessage attempt for THIS ticket failed with a
+            reply-specific code. Rendered above the composer/reopen so
+            the customer sees it in context of their failed draft. Open
+            (composer) actions still allow Retry; the closed (reopen)
+            state still shows the banner because the user might have
+            tried to reply to a then-closing ticket. */}
+        {replyError && (
+          <ReplyFailureBanner
+            error={replyError}
+            onDismiss={onClearReplyError ?? (() => undefined)}
+          />
+        )}
         {isClosed ? (
           <ReopenAction
             ticketRef={{ id: ticket.id, external_id: ticket.external_id }}
@@ -562,3 +598,95 @@ function OpenActions({
     </div>
   )
 }
+
+/**
+ * Persistent banner above the drawer composer/actions when the most
+ * recent customer reply failed with a reply-specific code (HUBSPOT_5XX
+ * / 400 / 404 / UNKNOWN). The transient toast already fired at the
+ * moment of failure; this banner stays until the next successful send
+ * OR the user dismisses it explicitly. Wording is sourced from
+ * `mapTicketActionError` so a future copy update lives in one place.
+ *
+ * 404_THREAD is the only terminal code in the set — the banner copy
+ * reads "open a new ticket" and Retry would just re-fail. We still
+ * render a Dismiss control instead of hiding Retry so the visual shape
+ * is uniform; the parent's composer continues to function for any
+ * non-thread-deletion reply path.
+ */
+function ReplyFailureBanner({
+  error,
+  onDismiss,
+}: {
+  error: MappedTicketActionError
+  onDismiss: () => void
+}) {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className="mb-3 flex items-start gap-3 rounded-md border border-ods-attention-red-error bg-ods-attention-red-error-secondary px-3 py-2 text-sm text-ods-attention-red-error"
+    >
+      <span className="font-medium leading-snug">{error.message}</span>
+      <Button
+        type="button"
+        variant="transparent"
+        onClick={onDismiss}
+        aria-label="Dismiss reply failure"
+        className="ml-auto px-2 py-0.5 text-xs font-medium uppercase tracking-wider text-ods-attention-red-error hover:bg-ods-attention-red-error/10 border-transparent"
+      >
+        Dismiss
+      </Button>
+    </div>
+  )
+}
+
+/**
+ * Compact "Assigned to" row at the top of the drawer. Surfaces the
+ * support-side agent — name + avatar — so the customer knows who's
+ * looking at their ticket. Renders "Unassigned" when the ticket has no
+ * `hubspot_owner_id` OR when the owner couldn't be resolved against
+ * the mirror (deleted between ticket update + next reconcile).
+ *
+ * Avatar comes from the canonical `<SquareAvatar variant="round">` so
+ * it picks up the initials-fallback + image-proxy behavior used
+ * everywhere else in the lib (matches the dev-section message-bubble
+ * avatars). No bespoke avatar markup.
+ */
+function AssignedAgentRow({
+  assignedOwner,
+}: {
+  assignedOwner: TicketAssignedOwner | null
+}) {
+  // Display label precedence:
+  //   1. `name` from the mirror (employee match OR HubSpot's first+last)
+  //   2. `email` local-part — covers HubSpot owners that exist but have
+  //      no name (rare but real; the ticket IS assigned and rendering
+  //      "Unassigned" would be misleading)
+  //   3. "Unassigned" — only when the ticket has no `assigned_to` OR
+  //      the owner couldn't be resolved against the mirror at all
+  const trimmedName = assignedOwner?.name?.trim() || null
+  const emailFallback = assignedOwner?.email?.trim() || null
+  const displayLabel =
+    trimmedName ?? (emailFallback ? emailFallback.split('@')[0] : null)
+  return (
+    <div className="flex items-center gap-2 text-xs">
+      <span className="text-ods-text-secondary uppercase tracking-wider font-medium">
+        Assigned to
+      </span>
+      {displayLabel ? (
+        <span className="flex items-center gap-1.5 text-ods-text-primary font-medium">
+          <SquareAvatar
+            size="sm"
+            variant="round"
+            src={assignedOwner?.avatarUrl ?? undefined}
+            alt={displayLabel}
+            fallback={displayLabel}
+          />
+          {displayLabel}
+        </span>
+      ) : (
+        <span className="text-ods-text-secondary italic">Unassigned</span>
+      )}
+    </div>
+  )
+}

package/src/components/tickets/types.ts

@@ -51,9 +51,30 @@ export interface TicketData {
    *  Channels, so this is the only reliable source for "what's the
    *  customer's name." */
   customer_name: string | null
+  /** HubSpot owner id of the agent assigned to this ticket. Carried as
+   *  raw id for debugging; rendering goes through `assignedOwner`. Null
+   *  when unassigned. */
+  assigned_to: string | null
+  /** Resolved assigned-owner profile — name + email + avatar. Populated
+   *  server-side via `attachOwnerProfiles` which joins through the
+   *  `hubspot_owners` mirror to `profiles` by email. Drives the
+   *  "Assigned to" attribution in the drawer header. Null when
+   *  unassigned OR the owner couldn't be resolved (rare — only when
+   *  the agent was deleted from HubSpot between the ticket update and
+   *  the next owners reconcile). */
+  assignedOwner: TicketAssignedOwner | null
   hubspot_updated_at: string
 }
 
+/** Resolved profile of a ticket's assigned agent — surfaced in the
+ *  drawer header. Subset of the server's `MirroredOwnerProfile`
+ *  trimmed to just the rendering fields. */
+export interface TicketAssignedOwner {
+  name: string | null
+  email: string | null
+  avatarUrl: string | null
+}
+
 /** Compact projection of a linked ClickUp task — matches the server's
  *  `ClickupSummary` and aligns with `DeliveryItem` so the linked-card
  *  on a ticket can render through the same `DeliveryRow` primitive used
@@ -122,6 +143,13 @@ export function isOptimistic(t: AnyTicket): t is OptimisticTicket {
  * Stable server-side error codes the ticket-action helpers route
  * through `mapTicketActionError`. Anything else is treated as a generic
  * server error.
+ *
+ * Reply-specific codes (`HUBSPOT_5XX` / `HUBSPOT_400_VALIDATION` /
+ * `HUBSPOT_404_THREAD` / `HUBSPOT_REPLY_UNKNOWN`) drive the drawer
+ * banner that appears above the composer when a customer reply fails.
+ * Distinct from `HUBSPOT_DISCONNECTED` (whole-system) and
+ * `TICKET_NOT_FOUND` (terminal-row) — the reply codes are per-attempt
+ * + retryable except for `HUBSPOT_404_THREAD`.
  */
 export type TicketActionErrorCode =
   | 'PROPOSAL_NOT_CLAIMABLE'
@@ -130,6 +158,10 @@ export type TicketActionErrorCode =
   | 'HUBSPOT_DISCONNECTED'
   | 'RATE_LIMITED'
   | 'INVALID_TOOL_ARGS'
+  | 'HUBSPOT_5XX'
+  | 'HUBSPOT_400_VALIDATION'
+  | 'HUBSPOT_404_THREAD'
+  | 'HUBSPOT_REPLY_UNKNOWN'
   | 'UNKNOWN'
 
 export interface MappedTicketActionError {