@hyperse-hub/hps-plugin-ticket
A Vendure plugin that adds a general-purpose ticketing system: customers open tickets with a type, title, description, optional attachment, and threaded messages. Staff assign tickets, move them through configurable states, and exchange messages with customers.
Unlike the assisted-order plugin, tickets are not bound to a Vendure Order; they are standalone entities per customer (with optional image asset).
Features
- Entities:
Ticket, Message (channel-aware tickets with many messages).
- Ticket types: Configurable string list exposed as GraphQL
TicketType enum (e.g. Contactus).
- Workflow: Separate shop and admin state lists (default and terminal states; no transitions after terminal). Admin state order can define transition ordering in your UI.
- Attachments:
CreateTicketInput supports optional file uploads; ticket can reference a single ticketAsset image.
- Security: Shop
createTicket expects recaptcha input (integrate with your storefront).
- GraphQL: Shared schema for listing tickets and messages, create/update ticket, state transitions, and
sendMessage.
- Admin-only mutations:
assignAdminToTicket, unassignAdminFromTicket, setCustomerToTicket (with extended inputs for customerId on create where applicable).
- Email: Handlers for assignee on assign, admin on create, admin on customer reply, customer on admin reply (React Email templates under
templates/).
- Admin UI: Dashboard menu entry at
/ticket (Hyperse Plugin Admin extension).
Requirements
- Vendure ≥ 3.0.0 (see
peerDependencies in package.json).
- Works with
@hyperse-hub/hps-plugin-core, hps-plugin-admin, and hps-plugin-email.
Installation
Configuration options (HpsPluginTicketOptions)
| Option | Description |
|---|
ticketTypes | Allowed ticket type identifiers; become the TicketType enum in GraphQL. |
ticketStates.shop | Shop-visible states; first = default, last = terminal. |
ticketStates.admin | Staff states; first = default, last = terminal. Order may matter for next/previous transitions in tooling. |
recipients | Notification recipients for new tickets (and related email flows). |
systemName | Display name for system-sent messages. |
Data model (summary)
Ticket: title, description, type, state, optional ticketAsset / ticketAssetId, Customer, assignees, channels, messages.
Message: Belongs to a ticket; includes content and sender metadata (MessageFrom: customer, assignee, system).
GraphQL (high level)
Types include Ticket, Message, TicketList, MessageList, TicketType, TicketState, and TransitionTicketToStateResult.
Queries: tickets, ticket.
Mutations: createTicket, updateTicket, transitionTicketToState, sendMessage; Admin additionally: assignAdminToTicket, unassignAdminFromTicket, setCustomerToTicket.
Shop createTicket uses CreateTicketInput with type, title, description, recaptcha, and optional file uploads. See src/api/generate-common-extension.ts for the canonical schema.
Comparison with @hyperse-hub/hps-plugin-assisted-order
| Ticket plugin | Assisted-order plugin |
|---|
| Scope | Standalone tickets per customer | Tickets tied to an Order / OrderLine |
| Order link | No | Yes |
| Extras | Optional image asset, reCAPTCHA on create | Assisted order link, isAdminOrderAssistedMode, token-active-order integration |
Scripts
yarn build — server + UI build
yarn serve — local dev server
yarn test — unit and e2e tests
yarn codegen — GraphQL codegen
yarn email-dev — preview email templates
License
MIT — see LICENSE.