@qoretechnologies/reqraft 0.10.8 → 0.10.9-pr.74.g452d4d3

package/src/components/supportTicket/TicketMetaTags.stories.tsx

@@ -0,0 +1,71 @@
+import { StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import { StoryMeta } from '../../types';
+import { TTicketCategory, TTicketPriority, TTicketStatus } from './meta';
+import { TicketMetaTags } from './TicketMetaTags';
+
+const ticket = (
+  status: TTicketStatus,
+  priority: TTicketPriority,
+  category: TTicketCategory
+): { status: TTicketStatus; priority: TTicketPriority; category: TTicketCategory } => ({
+  status,
+  priority,
+  category,
+});
+
+const meta = {
+  component: TicketMetaTags,
+  title: 'Components/TicketMetaTags',
+  args: {
+    ticket: ticket('open', 'high', 'bug'),
+  },
+} as StoryMeta<typeof TicketMetaTags>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** The status / priority / category badge row — each value's label, intent and
+ *  icon come from the shared `supportTicket/meta` vocabularies. */
+export const Default: Story = {
+  async play({ canvasElement }) {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText('Open')).toBeInTheDocument();
+    await expect(canvas.getByText('High')).toBeInTheDocument();
+    await expect(canvas.getByText('Bug')).toBeInTheDocument();
+  },
+};
+
+/**
+ * The `awaiting_customer` status is the one value whose label is audience-specific.
+ * With no `viewerRole` (the staff / neutral default) it reads "Awaiting customer".
+ */
+export const StaffAwaitingLabel: Story = {
+  args: { ticket: ticket('awaiting_customer', 'normal', 'question') },
+  async play({ canvasElement }) {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText('Awaiting customer')).toBeInTheDocument();
+    await expect(canvas.queryByText('Awaiting your reply')).not.toBeInTheDocument();
+  },
+};
+
+/** The customer viewpoint re-labels the same status as "Awaiting your reply". */
+export const CustomerAwaitingLabel: Story = {
+  args: { viewerRole: 'customer', ticket: ticket('awaiting_customer', 'normal', 'question') },
+  async play({ canvasElement }) {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText('Awaiting your reply')).toBeInTheDocument();
+    await expect(canvas.queryByText('Awaiting customer')).not.toBeInTheDocument();
+  },
+};
+
+/** `hideCategory` drops the category tag — for dense list rows. */
+export const HideCategory: Story = {
+  args: { hideCategory: true },
+  async play({ canvasElement }) {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText('Open')).toBeInTheDocument();
+    await expect(canvas.getByText('High')).toBeInTheDocument();
+    await expect(canvas.queryByText('Bug')).not.toBeInTheDocument();
+  },
+};

package/src/components/supportTicket/TicketMetaTags.tsx

@@ -0,0 +1,58 @@
+import { ReqoreControlGroup, ReqoreTag } from '@qoretechnologies/reqore';
+import { TSizes } from '@qoretechnologies/reqore/dist/constants/sizes';
+import {
+  TICKET_CATEGORY_META,
+  TICKET_PRIORITY_META,
+  TICKET_STATUS_META,
+  ticketStatusLabel,
+  TTicketCategory,
+  TTicketPriority,
+  TTicketStatus,
+  TTicketViewerRole,
+} from './meta';
+
+export interface ITicketMetaTagsProps {
+  /** The three enum values to badge — a full ticket satisfies this structurally. */
+  ticket: {
+    status: TTicketStatus;
+    priority: TTicketPriority;
+    category: TTicketCategory;
+  };
+  /** Picks audience-specific labels (e.g. "Awaiting your reply" vs "Awaiting
+   *  customer"). Omit for the staff / neutral wording. */
+  viewerRole?: TTicketViewerRole;
+  size?: TSizes;
+  /** Hide the category tag (e.g. in a dense list row). */
+  hideCategory?: boolean;
+}
+
+/**
+ * The status / priority / category badge row for a ticket — the single place the
+ * three enum vocabularies (`../supportTicket/meta`) turn into Reqore tags, so the
+ * customer list, the staff queue, the detail header and the Qonsole card all read
+ * identically. Each tag's label, intent and icon come from the shared meta maps.
+ */
+export const TicketMetaTags = ({
+  ticket,
+  viewerRole,
+  size = 'small',
+  hideCategory,
+}: ITicketMetaTagsProps) => {
+  const status = TICKET_STATUS_META[ticket.status];
+  const priority = TICKET_PRIORITY_META[ticket.priority];
+  const category = TICKET_CATEGORY_META[ticket.category];
+
+  return (
+    <ReqoreControlGroup size={size} wrap>
+      <ReqoreTag
+        icon={status.icon}
+        intent={status.intent}
+        label={ticketStatusLabel(ticket.status, viewerRole)}
+        size={size}
+        effect={{ weight: 'bold' }}
+      />
+      <ReqoreTag icon={priority.icon} intent={priority.intent} label={priority.label} size={size} />
+      {!hideCategory && <ReqoreTag icon={category.icon} label={category.label} size={size} />}
+    </ReqoreControlGroup>
+  );
+};

package/src/components/supportTicket/TicketReplyBox.stories.tsx

@@ -0,0 +1,111 @@
+import { ReqoreButton } from '@qoretechnologies/reqore';
+import { StoryObj } from '@storybook/react-vite';
+import { expect, fn, screen, userEvent, waitFor, within } from 'storybook/test';
+import { StoryMeta } from '../../types';
+import { InterfaceReferenceTags } from './InterfaceReferenceTags';
+import { TicketReplyBox } from './TicketReplyBox';
+
+const meta = {
+  component: TicketReplyBox,
+  title: 'Components/TicketReplyBox',
+  args: {
+    onSend: fn(),
+  },
+} as StoryMeta<typeof TicketReplyBox>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * The customer composer: a textarea, an attach button (no extra menu → a plain
+ * button, not a dropdown), and Send. No internal-note toggle. Typing enables Send;
+ * clicking it calls `onSend` with the body and `internal: false`.
+ */
+export const Default: Story = {
+  async play({ canvasElement, args }) {
+    const canvas = within(canvasElement);
+    const textarea = canvasElement.querySelector('textarea');
+    await expect(textarea).not.toBeNull();
+    await expect(canvas.queryByText('Internal note')).not.toBeInTheDocument();
+
+    await userEvent.type(textarea!, 'Here is my reply');
+    await userEvent.click(canvas.getByText('Send reply'));
+    await waitFor(() =>
+      expect(args.onSend).toHaveBeenCalledWith(
+        'Here is my reply',
+        expect.objectContaining({ internal: false })
+      )
+    );
+  },
+};
+
+/**
+ * The staff composer (`allowInternalNote`): no toggle — the send button splits, so
+ * the primary action posts a public reply and the caret opens "Add internal note",
+ * which sends with `internal: true`.
+ */
+export const StaffWithInternalNote: Story = {
+  args: { allowInternalNote: true },
+  async play({ canvasElement, args }) {
+    const canvas = within(canvasElement);
+    // no toggle any more; the primary action is a plain "Send reply"
+    await expect(canvas.queryByText('Internal note')).not.toBeInTheDocument();
+    await expect(canvas.getByText('Send reply')).toBeInTheDocument();
+
+    const textarea = canvasElement.querySelector('textarea');
+    await userEvent.type(textarea!, 'internal context');
+
+    // "Add internal note" lives behind the split-send caret
+    const caret = canvasElement.querySelector('.ticket-send-more');
+    await expect(caret).not.toBeNull();
+    await userEvent.click(caret as Element);
+    await userEvent.click(await screen.findByText('Add internal note'));
+
+    await waitFor(() =>
+      expect(args.onSend).toHaveBeenCalledWith(
+        'internal context',
+        expect.objectContaining({ internal: true })
+      )
+    );
+  },
+};
+
+/** A closed ticket replaces the editor with a muted notice. */
+export const Closed: Story = {
+  args: { disabled: true },
+  async play({ canvasElement }) {
+    await expect(within(canvasElement).getByText(/ticket is closed/i)).toBeInTheDocument();
+    await expect(canvasElement.querySelector('textarea')).toBeNull();
+  },
+};
+
+/**
+ * The composer with app-injected affordances — how the qorus-ide customer view
+ * dresses it: `attachMenuItems` adds screenshot/capture to the attach dropdown,
+ * `footerActions` adds the reference-interfaces toggle, and `belowInput` hosts the
+ * reference display/picker (here the shared `InterfaceReferenceTags` stands in).
+ * The extra attach items receive `addFiles` so they can stage what they produce.
+ */
+export const WithSlots: Story = {
+  args: {
+    attachMenuItems: () => [
+      { label: 'Take screenshot', icon: 'CameraAiLine', onClick: fn() },
+      { label: 'Capture area', icon: 'CropLine', onClick: fn() },
+    ],
+    footerActions: (
+      <ReqoreButton icon='LinksLine' minimal flat badge={1} tooltip='Reference interfaces' />
+    ),
+    belowInput: (
+      <InterfaceReferenceTags
+        label='References'
+        references={[{ interface_kind: 'workflow', interface_name: 'order-sync:1.2' }]}
+      />
+    ),
+  },
+  async play({ canvasElement }) {
+    const canvas = within(canvasElement);
+    // the below-input slot (reference chips) and the footer toggle both render
+    await expect(canvas.getByText('References')).toBeInTheDocument();
+    await expect(canvas.getByText('order-sync:1.2')).toBeInTheDocument();
+  },
+};

package/src/components/supportTicket/TicketReplyBox.tsx

@@ -0,0 +1,251 @@
+import {
+  ReqoreButton,
+  ReqoreControlGroup,
+  ReqoreDropdown,
+  ReqoreMessage,
+  ReqoreTextarea,
+} from '@qoretechnologies/reqore';
+import { ComponentProps, ReactNode, useRef, useState } from 'react';
+import { AttachmentChips } from './AttachmentChips';
+import { fileToAttachment as defaultFileToAttachment } from './fileToAttachment';
+import { IAttachmentUpload } from './meta';
+
+/** The exact `items` shape ReqoreDropdown accepts — no import-path guessing. */
+type TAttachMenuItems = NonNullable<ComponentProps<typeof ReqoreDropdown>['items']>;
+
+export interface ITicketReplyBoxProps {
+  /** Send the composed message. `internal` is only ever true when
+   *  `allowInternalNote` is set (the staff surface). */
+  onSend: (
+    body: string,
+    options: { internal: boolean; attachments?: IAttachmentUpload[] }
+  ) => void | Promise<void>;
+  /** File → base64 upload conversion; defaults to the shared `fileToAttachment`. */
+  fileToAttachment?: (file: File) => Promise<IAttachmentUpload>;
+  /** the send round-trip is in flight */
+  sending?: boolean;
+  /** the ticket can't be replied to (e.g. closed) — renders a notice instead */
+  disabled?: boolean;
+  disabledReason?: string;
+  /** placeholder text. (A function is called with `false` — there is no live
+   *  internal-note mode any more; the mode is chosen at send time.) */
+  placeholder?: string | ((internal: boolean) => string);
+  /** send labels; a function is called with `false` for the primary "Send reply"
+   *  and `true` for the "Add internal note" split-menu item. Defaults to
+   *  "Send reply" / "Add internal note". */
+  sendLabel?: string | ((internal: boolean) => string);
+  /** Staff surface: split the send button so it also offers "Add internal note"
+   *  (customer composers omit it and just send a reply). */
+  allowInternalNote?: boolean;
+  /** Extra attach-menu entries beyond "Upload files" — e.g. the IDE's screenshot /
+   *  region capture, which need IDE-only capabilities. Receives the composer's
+   *  `addFiles` so an item can stage the file(s) it produces. With any entry the
+   *  attach control becomes a dropdown; otherwise it's a plain button. */
+  attachMenuItems?: (addFiles: (files: File[]) => void) => TAttachMenuItems;
+  /** Extra footer controls left of the send button — e.g. the IDE's
+   *  reference-interfaces toggle. */
+  footerActions?: ReactNode;
+  /** Rendered below the textarea — e.g. the IDE's interface-reference picker. */
+  belowInput?: ReactNode;
+}
+
+/** Image files pasted from the clipboard (a screenshot, a copied image) — the
+ *  generic bits, so pasting to attach works on every composer without an IDE dep. */
+const clipboardImages = (event: React.ClipboardEvent): File[] => {
+  const images: File[] = [];
+  for (const item of Array.from(event.clipboardData?.items ?? [])) {
+    if (item.kind === 'file' && item.type.startsWith('image/')) {
+      const file = item.getAsFile();
+      if (file) {
+        images.push(file);
+      }
+    }
+  }
+  return images;
+};
+
+/**
+ * The shared ticket reply composer core: a markdown textarea, staged file chips
+ * (with image thumbnails), an attach control, and a send button — presentational,
+ * with the parent owning the send round-trip and busy/disabled state. On the staff
+ * surface (`allowInternalNote`) the send button splits: the primary posts a public
+ * reply and a caret offers "Add internal note", so the mode is chosen at send time
+ * instead of held in a toggle that's easy to misread. A closed ticket renders a
+ * muted notice.
+ *
+ * App-specific affordances are injected through slots rather than baked in, so
+ * the IDE-only bits (screenshot / region capture, clipboard paste, the
+ * interface-reference picker — all of which need IDE helpers or the customer's
+ * instance) stay in qorus-ide: `attachMenuItems` adds to the attach menu,
+ * `belowInput` hosts the reference picker, `footerActions` adds footer buttons,
+ * and `onPaste` handles clipboard images.
+ */
+export const TicketReplyBox = ({
+  onSend,
+  fileToAttachment = defaultFileToAttachment,
+  sending,
+  disabled,
+  disabledReason = 'This ticket is closed. Open a new ticket to continue the conversation.',
+  placeholder = 'Write a reply…',
+  sendLabel,
+  allowInternalNote,
+  attachMenuItems,
+  footerActions,
+  belowInput,
+}: ITicketReplyBoxProps) => {
+  const [body, setBody] = useState('');
+  const [files, setFiles] = useState<File[]>([]);
+  const fileInput = useRef<HTMLInputElement>(null);
+
+  if (disabled) {
+    return (
+      <ReqoreMessage intent='muted' icon='LockLine' size='small' flat>
+        {disabledReason}
+      </ReqoreMessage>
+    );
+  }
+
+  const canSend = !!body.trim() && !sending;
+  const resolvedPlaceholder =
+    typeof placeholder === 'function' ? placeholder(false) : placeholder;
+  // Label for a given send mode: `false` = public reply, `true` = internal note.
+  const labelFor = (note: boolean): string =>
+    sendLabel !== undefined
+      ? typeof sendLabel === 'function'
+        ? sendLabel(note)
+        : sendLabel
+      : note
+        ? 'Add internal note'
+        : 'Send reply';
+
+  const addFiles = (incoming: File[]) => {
+    if (incoming.length) {
+      setFiles((prev) => [...prev, ...incoming]);
+    }
+  };
+
+  const handlePaste = (event: React.ClipboardEvent) => {
+    const images = clipboardImages(event);
+    if (images.length) {
+      event.preventDefault();
+      addFiles(images);
+    }
+  };
+
+  const extraAttachItems = attachMenuItems ? attachMenuItems(addFiles) : [];
+
+  const handleSend = async (internal: boolean) => {
+    if (!body.trim()) {
+      return;
+    }
+    const attachments = files.length
+      ? await Promise.all(files.map(fileToAttachment))
+      : undefined;
+    await onSend(body.trim(), { internal, attachments });
+    // only reached when onSend resolves — a thrown error keeps the draft + files
+    setBody('');
+    setFiles([]);
+  };
+
+  return (
+    <ReqoreControlGroup vertical fluid gapSize='small' onPaste={handlePaste}>
+      {/* Input + controls on one line: the textarea grows to fill, the controls
+          sit at its right and stay bottom-aligned as it scales with content. */}
+      <ReqoreControlGroup fluid verticalAlign='flex-end' gapSize='small'>
+        <ReqoreTextarea
+          value={body}
+          scaleWithContent
+          fluid
+          placeholder={resolvedPlaceholder}
+          disabled={sending}
+          onChange={(e: React.ChangeEvent<HTMLTextAreaElement>) => setBody(e.target.value)}
+        />
+        {extraAttachItems.length ? (
+          <ReqoreDropdown
+            icon='AttachmentLine'
+            minimal
+            flat
+            disabled={sending}
+            tooltip='Attach'
+            items={[
+              { label: 'Upload files', icon: 'Upload2Line', onClick: () => fileInput.current?.click() },
+              ...extraAttachItems,
+            ]}
+          />
+        ) : (
+          <ReqoreButton
+            icon='AttachmentLine'
+            minimal
+            flat
+            disabled={sending}
+            tooltip='Attach files'
+            onClick={() => fileInput.current?.click()}
+          />
+        )}
+        {footerActions}
+        {allowInternalNote ? (
+          <ReqoreControlGroup stack fixed>
+            <ReqoreButton
+              icon='SendPlane2Line'
+              intent='info'
+              disabled={!canSend}
+              loading={sending}
+              onClick={() => handleSend(false)}
+            >
+              {labelFor(false)}
+            </ReqoreButton>
+            <ReqoreDropdown
+              className='ticket-send-more'
+              icon='ArrowDownSLine'
+              intent='info'
+              disabled={!canSend}
+              tooltip='More send options'
+              items={[
+                {
+                  label: labelFor(false),
+                  icon: 'SendPlane2Line',
+                  onClick: () => handleSend(false),
+                },
+                {
+                  label: labelFor(true),
+                  icon: 'StickyNoteLine',
+                  intent: 'warning',
+                  onClick: () => handleSend(true),
+                },
+              ]}
+            />
+          </ReqoreControlGroup>
+        ) : (
+          <ReqoreButton
+            icon='SendPlane2Line'
+            intent='info'
+            disabled={!canSend}
+            loading={sending}
+            onClick={() => handleSend(false)}
+            fixed
+          >
+            {labelFor(false)}
+          </ReqoreButton>
+        )}
+      </ReqoreControlGroup>
+      <AttachmentChips
+        files={files}
+        onRemove={(index) => setFiles((prev) => prev.filter((_, j) => j !== index))}
+        disabled={sending}
+      />
+      {belowInput}
+      <input
+        ref={fileInput}
+        type='file'
+        multiple
+        style={{ display: 'none' }}
+        onChange={(e) => {
+          if (e.target.files) {
+            addFiles(Array.from(e.target.files));
+          }
+          e.target.value = '';
+        }}
+      />
+    </ReqoreControlGroup>
+  );
+};

package/src/components/supportTicket/fileToAttachment.ts

@@ -0,0 +1,24 @@
+import { IAttachmentUpload } from './meta';
+
+/**
+ * Read a picked `File` into the inline base64 upload shape the support API expects
+ * (the SaaS plane accepts attachments as base64 on the create/reply payload, with
+ * no separate multipart upload). Shared by every composer so the customer and
+ * staff surfaces encode files identically.
+ */
+export const fileToAttachment = (file: File): Promise<IAttachmentUpload> =>
+  new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onerror = () => reject(new Error(`Could not read ${file.name}`));
+    reader.onload = () => {
+      // reader.result is a data URL: "data:<type>;base64,<content>"
+      const result = String(reader.result);
+      const content = result.slice(result.indexOf(',') + 1);
+      resolve({
+        filename: file.name,
+        content_type: file.type || 'application/octet-stream',
+        content,
+      });
+    };
+    reader.readAsDataURL(file);
+  });

package/src/components/supportTicket/index.ts

@@ -0,0 +1,6 @@
+export * from './meta';
+export * from './AttachmentChips';
+export * from './TicketMetaTags';
+export * from './InterfaceReferenceTags';
+export * from './fileToAttachment';
+export * from './TicketReplyBox';

package/src/components/supportTicket/meta.ts

@@ -0,0 +1,135 @@
+import { TReqoreIntent } from '@qoretechnologies/reqore/dist/constants/theme';
+import { IReqoreIconName } from '@qoretechnologies/reqore/dist/types/icons';
+
+/*
+ * The single source of truth for the Qorus support-ticket presentation
+ * vocabulary — how each status / priority / category / audit-action value
+ * renders (label + Reqore intent + icon), plus the interface-kind icon map and
+ * the small enum helpers. Shared by every Qorus surface that shows a ticket
+ * (the qorus-ide customer view, the admin-portal staff queue, the Qonsole
+ * renderer) so the chips read identically everywhere and can't drift apart.
+ */
+
+export type TTicketStatus = 'new' | 'open' | 'awaiting_customer' | 'resolved' | 'closed';
+export type TTicketPriority = 'low' | 'normal' | 'high' | 'urgent';
+export type TTicketCategory = 'bug' | 'question' | 'billing' | 'feature' | 'other';
+export type TTicketAuditAction = 'replied' | 'noted' | 'status_changed' | 'assigned' | 'updated';
+
+/** A message author. Staff identities are masked from the customer by the backend. */
+export type TTicketMessageAuthor = 'customer' | 'staff' | 'system';
+
+/** Which side "you" sit on — decides self-alignment and audience-specific labels. */
+export type TTicketViewerRole = 'customer' | 'staff';
+
+export interface ITicketEnumMeta {
+  label: string;
+  intent: TReqoreIntent;
+  icon: IReqoreIconName;
+  /** Audience-specific label for the customer view; falls back to `label` (the
+   *  staff / neutral wording). Only a few values differ by audience. */
+  customerLabel?: string;
+}
+
+export const TICKET_STATUS_META: Record<TTicketStatus, ITicketEnumMeta> = {
+  new: { label: 'New', intent: 'info', icon: 'SparklingLine' },
+  open: { label: 'Open', intent: 'pending', icon: 'Chat3Line' },
+  awaiting_customer: {
+    label: 'Awaiting customer',
+    customerLabel: 'Awaiting your reply',
+    intent: 'warning',
+    icon: 'UserReceivedLine',
+  },
+  resolved: { label: 'Resolved', intent: 'success', icon: 'CheckLine' },
+  closed: { label: 'Closed', intent: 'muted', icon: 'CloseCircleLine' },
+};
+
+export const TICKET_PRIORITY_META: Record<TTicketPriority, ITicketEnumMeta> = {
+  low: { label: 'Low', intent: 'muted', icon: 'ArrowDownLine' },
+  normal: { label: 'Normal', intent: 'info', icon: 'SubtractLine' },
+  high: { label: 'High', intent: 'warning', icon: 'ArrowUpLine' },
+  urgent: { label: 'Urgent', intent: 'danger', icon: 'AlarmWarningLine' },
+};
+
+export const TICKET_CATEGORY_META: Record<TTicketCategory, ITicketEnumMeta> = {
+  bug: { label: 'Bug', intent: 'danger', icon: 'BugLine' },
+  question: { label: 'Question', intent: 'info', icon: 'QuestionLine' },
+  billing: { label: 'Billing', intent: 'warning', icon: 'BankCardLine' },
+  feature: { label: 'Feature request', intent: 'success', icon: 'LightbulbLine' },
+  other: { label: 'Other', intent: 'muted', icon: 'MoreLine' },
+};
+
+/** Staff-only audit trail vocabulary (used by the admin-portal staff surface).
+ *  These are exactly the actions the backend writes (qorus-api
+ *  `QorusSaasTicketStore::insertAudit`): a public reply, an internal note, a
+ *  status change, an assignment, or `updated` (a priority/category change). */
+export const TICKET_AUDIT_ACTION_META: Record<TTicketAuditAction, ITicketEnumMeta> = {
+  replied: { label: 'Replied', intent: 'success', icon: 'ReplyLine' },
+  noted: { label: 'Internal note', intent: 'info', icon: 'StickyNoteLine' },
+  status_changed: { label: 'Status changed', intent: 'warning', icon: 'ExchangeLine' },
+  assigned: { label: 'Assigned', intent: 'pending', icon: 'UserFollowLine' },
+  updated: { label: 'Updated', intent: 'muted', icon: 'Edit2Line' },
+};
+
+/** The status label for a given viewer — the customer sees "Awaiting your reply"
+ *  where staff see "Awaiting customer"; all other values are audience-neutral. */
+export const ticketStatusLabel = (
+  status: TTicketStatus,
+  viewerRole?: TTicketViewerRole
+): string => {
+  const meta = TICKET_STATUS_META[status];
+  return viewerRole === 'customer' && meta.customerLabel ? meta.customerLabel : meta.label;
+};
+
+/** A reply may be sent while a ticket is in any state except `closed`. */
+export const REPLYABLE_STATUSES: TTicketStatus[] = [
+  'new',
+  'open',
+  'awaiting_customer',
+  'resolved',
+];
+
+/** Whether a ticket can still be replied to (closed ⇒ no). */
+export const isTicketReplyable = (status: TTicketStatus): boolean => status !== 'closed';
+
+/** A file to upload with a ticket or reply — raw bytes as base64, inline on the
+ *  create/reply payload (the SaaS plane has no separate multipart upload). */
+export interface IAttachmentUpload {
+  filename: string;
+  content_type: string;
+  /** base64-encoded file content */
+  content: string;
+}
+
+/** A reference to a Qorus interface on the subscriber's instance, stored as a
+ *  `{kind, name}` snapshot (the interface itself lives on the instance, not the
+ *  SaaS plane). Attaches to a ticket (at creation) or a message (in a reply). */
+export interface IInterfaceReference {
+  /** interface type: workflow / service / job / fsm / connection / ... */
+  interface_kind: string;
+  /** interface name (may include a version) */
+  interface_name: string;
+  /** server-assigned reference UUID (present on read, absent when submitting) */
+  reference_id?: string;
+}
+
+// Built-in per-kind icons for referenced interfaces, kept in step with the
+// qorus-ide interface vocabulary. Used when a consumer doesn't pass its own
+// `resolveInterfaceIcon`, so the staff view and the Qonsole renderer show the
+// same chips as the customer view without each re-declaring the mapping.
+const DEFAULT_INTERFACE_ICONS: Record<string, IReqoreIconName> = {
+  workflow: 'GitBranchLine',
+  service: 'ServerLine',
+  job: 'CalendarLine',
+  fsm: 'DashboardLine',
+  connection: 'Plug2Line',
+  mapper: 'MindMap',
+  class: 'CodeSLine',
+  'value-map': 'BringToFront',
+  'ai-collection': 'FileMarkedLine',
+  'ai-endpoint': 'RobotLine',
+  'ai-guardrail': 'ShieldLine',
+};
+
+/** Default per-kind icon for a referenced interface, with a generic fallback. */
+export const defaultInterfaceIcon = (kind: string): IReqoreIconName =>
+  DEFAULT_INTERFACE_ICONS[kind] ?? 'CodeBoxLine';