@qoretechnologies/reqraft 0.10.27-pr.74.gc5f6ca3 → 0.10.27

package/src/components/supportTicket/attachmentAccess.ts

@@ -0,0 +1,97 @@
+/*
+ * Authed attachment byte-fetching, shared by every ticket surface.
+ *
+ * Attachment bytes can't go through the JSON fetch helpers, so each app grew its
+ * own raw-`fetch` copy: qorus-ide in `views/support/api.ts`, admin-portal in
+ * `pages/SupportTickets/helpers.ts`. The two were the same function down to the
+ * error text ("Could not download the attachment") and the anchor-click dance —
+ * they differed only in how the URL is built, which auth header is sent, and
+ * which Error subclass is thrown.
+ *
+ * Those three differences are the parameters below. Everything else — the
+ * non-OK check, `URL.createObjectURL`, the temporary anchor, revoking the object
+ * URL — lives here once.
+ */
+
+export interface ITicketAttachmentAccessConfig {
+  /** Absolute URL for one attachment's bytes. */
+  attachmentUrl: (ticketId: string, attachmentId: string) => string;
+  /**
+   * Headers for the byte request — typically auth. A function rather than a
+   * value because tokens are resolved per request, not at wire-up time.
+   */
+  headers?: () => Record<string, string>;
+  /**
+   * Error to throw on a non-OK response. Defaults to a plain `Error`; apps with
+   * their own API error type (carrying the status) pass a factory.
+   */
+  onError?: (message: string, status: number) => Error;
+}
+
+export interface ITicketAttachmentAccess {
+  /** Raw bytes. `failure` is the message used if the response isn't OK. */
+  fetchBlob: (ticketId: string, attachmentId: string, failure?: string) => Promise<Blob>;
+  /**
+   * An object URL for the bytes — for inline thumbnails and the lightbox.
+   *
+   * The caller owns the returned URL and must `URL.revokeObjectURL` it when the
+   * element goes away; this cannot do it for them without breaking the img.
+   */
+  fetchBlobUrl: (ticketId: string, attachmentId: string) => Promise<string>;
+  /** Save the attachment to disk under its original filename. */
+  download: (ticketId: string, attachmentId: string, filename: string) => Promise<void>;
+}
+
+const DEFAULT_DOWNLOAD_FAILURE = 'Could not download the attachment';
+const DEFAULT_LOAD_FAILURE = 'Could not load the attachment';
+
+/**
+ * Save a blob to disk under `filename`, via a temporary anchor.
+ *
+ * Exported because it is the half of `download` that has nothing to do with
+ * tickets — a surface that already holds the bytes shouldn't have to re-fetch
+ * them just to reuse the save behaviour.
+ */
+export const saveBlobAs = (blob: Blob, filename: string): void => {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+
+  anchor.href = url;
+  anchor.download = filename;
+  document.body.appendChild(anchor);
+  anchor.click();
+  anchor.remove();
+  // Safari needs the URL alive until the click is processed; a task boundary is
+  // enough and avoids leaking the blob for the life of the document.
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+};
+
+export const createTicketAttachmentAccess = ({
+  attachmentUrl,
+  headers,
+  onError,
+}: ITicketAttachmentAccessConfig): ITicketAttachmentAccess => {
+  const fetchBlob = async (
+    ticketId: string,
+    attachmentId: string,
+    failure: string = DEFAULT_LOAD_FAILURE
+  ): Promise<Blob> => {
+    const response = await fetch(attachmentUrl(ticketId, attachmentId), {
+      headers: headers?.() ?? {},
+    });
+
+    if (!response.ok) {
+      throw onError ? onError(failure, response.status) : new Error(failure);
+    }
+
+    return response.blob();
+  };
+
+  return {
+    fetchBlob,
+    fetchBlobUrl: async (ticketId, attachmentId) =>
+      URL.createObjectURL(await fetchBlob(ticketId, attachmentId, DEFAULT_LOAD_FAILURE)),
+    download: async (ticketId, attachmentId, filename) =>
+      saveBlobAs(await fetchBlob(ticketId, attachmentId, DEFAULT_DOWNLOAD_FAILURE), filename),
+  };
+};

package/src/components/supportTicket/index.ts

@@ -1,4 +1,6 @@
 export * from './meta';
+export * from './ticketModel';
+export * from './attachmentAccess';
 export * from './AttachmentChips';
 export * from './TicketMetaTags';
 export * from './TicketHeader';

package/src/components/supportTicket/meta.ts

@@ -143,3 +143,43 @@ const DEFAULT_INTERFACE_ICONS: Record<string, IReqoreIconName> = {
 /** Default per-kind icon for a referenced interface, with a generic fallback. */
 export const defaultInterfaceIcon = (kind: string): IReqoreIconName =>
   DEFAULT_INTERFACE_ICONS[kind] ?? 'CodeBoxLine';
+
+// The reading name for each interface kind. The kind id (`value-map`, `ai-collection`)
+// is a wire value — it's what a host fetches with and what gets stored on the reference
+// — so it must never be what the user reads. These are plural because they name a
+// category the user picks from, not a single interface. `fsm` maps to "Qogs" like every
+// other user-facing surface; the id stays `fsm` wherever a host still uses it.
+const DEFAULT_INTERFACE_KIND_LABELS: Record<string, string> = {
+  workflow: 'Workflows',
+  service: 'Services',
+  job: 'Jobs',
+  fsm: 'Qogs',
+  qog: 'Qogs',
+  connection: 'Connections',
+  mapper: 'Mappers',
+  class: 'Classes',
+  'value-map': 'Value maps',
+  'ai-collection': 'AI collections',
+  'ai-endpoint': 'AI endpoints',
+  'ai-guardrail': 'AI guardrails',
+};
+
+/**
+ * Default reading name for an interface kind — "Value maps" for `value-map`. An
+ * unknown kind is humanised generically (separators to spaces, sentence case, a
+ * plural `s`) so a kind this map hasn't caught up with still reads as a word
+ * rather than an identifier. Consumers with their own vocabulary override the
+ * whole thing via the picker's `resolveKindLabel`.
+ */
+export const defaultInterfaceKindLabel = (kind: string): string => {
+  const known = DEFAULT_INTERFACE_KIND_LABELS[kind];
+
+  if (known) {
+    return known;
+  }
+
+  const words = kind.replace(/[-_]+/g, ' ').trim();
+  const sentenceCase = words.charAt(0).toUpperCase() + words.slice(1);
+
+  return sentenceCase.endsWith('s') ? sentenceCase : `${sentenceCase}s`;
+};

package/src/components/supportTicket/ticketModel.ts

@@ -0,0 +1,131 @@
+import type { IInterfaceReference, TTicketCategory, TTicketMessageAuthor, TTicketPriority, TTicketStatus } from './meta';
+
+/*
+ * The support-ticket wire model, shared by every surface that speaks it.
+ *
+ * These shapes mirror the `SupportTicket` / `SupportMessage` schemas served by
+ * the SaaS plane — `/qorus-saas/support/*` for the customer (qorus-api
+ * `QorusSaasSupportRestClass`) and `/qorus-saas-admin/support/*` for staff
+ * (`QorusSaasAdminRestHandler`). Both planes serve the SAME ticket row; the
+ * staff plane simply projects more of it.
+ *
+ * They live here because they were previously declared twice — once in
+ * qorus-ide's `views/support/types.ts` and once in admin-portal's
+ * `types/supportTickets.ts` — and had already started to drift. The enum
+ * vocabularies (`meta.ts`) were shared from the start; the record shapes that
+ * carry them were not, which is the wrong way round: a field added to the wire
+ * schema had to be remembered in two repos, and nothing failed if it wasn't.
+ *
+ * The split below is deliberate. `ITicket` is what BOTH planes return;
+ * `IStaffTicket` is the extra projection only the admin plane serves.
+ * That keeps "customer must never see the assignee" a property of the type
+ * rather than a convention, while still giving one place to add a field.
+ */
+
+/** Attachment metadata as embedded in a message (no content). */
+export interface ITicketAttachment {
+  attachment_id: string;
+  filename: string;
+  content_type: string;
+  size_bytes: number;
+}
+
+/**
+ * Attachment metadata from the ticket-level list endpoint.
+ *
+ * Richer than the per-message copy: it carries the provenance the embedded
+ * metadata omits — who uploaded the file, when, and which reply it came from
+ * (null for a file attached when the ticket was filed). A staff uploader arrives
+ * already masked by the server, so this never exposes a real staff identity.
+ */
+export interface ITicketAttachmentDetail extends ITicketAttachment {
+  message_id?: string | null;
+  uploaded_by?: string;
+  uploader_type?: 'customer' | 'staff';
+  created?: string;
+}
+
+/** One message in a ticket thread. */
+export interface ITicketMessage {
+  message_id: string;
+  ticket_id: string;
+  author_type: TTicketMessageAuthor;
+  /** author identity; staff identities are masked from the customer */
+  author_id: string;
+  /** message body (markdown) */
+  body: string;
+  /** staff-only internal note — never present in the customer thread */
+  internal: boolean;
+  created: string;
+  /** files attached to this message */
+  attachments?: ITicketAttachment[];
+  /** interfaces referenced in this message, as `{kind, name}` snapshots */
+  referenced_interfaces?: IInterfaceReference[];
+}
+
+/**
+ * One support ticket, in the projection BOTH planes serve.
+ *
+ * Staff-only fields are not optional-here-required-there; they live in
+ * `IStaffTicket` so a customer surface cannot read them by accident.
+ */
+export interface ITicket {
+  /** external ticket UUID, used in URLs */
+  ticket_id: string;
+  /** human-visible ticket number */
+  ticket_number: number;
+  subject: string;
+  /** initial description (markdown) */
+  description: string;
+  status: TTicketStatus;
+  priority: TTicketPriority;
+  category: TTicketCategory;
+  subscription_code: string;
+  /** account name (email) of the filer */
+  created_by: string;
+  /** parent ticket UUID, when this continues a closed ticket */
+  parent_ticket_id?: string;
+  /** first staff-reply timestamp */
+  first_response_at?: string;
+  resolved_at?: string;
+  closed_at?: string;
+  /** most-recent-message timestamp */
+  last_message_at: string;
+  created: string;
+  modified?: string;
+  /** interfaces this ticket references (ticket-level), as `{kind, name}` snapshots */
+  referenced_interfaces?: IInterfaceReference[];
+}
+
+/** The extra projection the admin plane adds on top of {@link ITicket}. */
+export interface IStaffTicket extends ITicket {
+  /** owner scope key (staff view) */
+  scope_key: string;
+  /** organization / account */
+  scope_type: string;
+  account_id: number;
+  groupid?: number;
+  /** the staff assignee */
+  assignee?: string;
+}
+
+/** The offset pagination every support list endpoint returns. */
+export interface ITicketPagedResult {
+  limit: number;
+  offset: number;
+}
+
+/**
+ * A ticket-list response. Generic over the ticket projection so the staff plane
+ * gets `IStaffTicket[]` without redeclaring the envelope; each plane extends this
+ * with the scope fields it actually serves.
+ */
+export interface ITicketListResult<T extends ITicket = ITicket> extends ITicketPagedResult {
+  tickets: T[];
+}
+
+/** A message-list response for one ticket. */
+export interface ITicketMessageListResult extends ITicketPagedResult {
+  ticket_id: string;
+  messages: ITicketMessage[];
+}