# Freshdesk Ticket Creation

## Objective

Send support issues to Freshdesk with the context an agent needs to resolve them.

A Freshdesk delivery path that maps in-app support requests onto the helpdesk's requester, group, product, and field structure.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Build an operator-editable mapping from the app's request types onto requester, group, product, source, status, priority, and any custom fields. Field identifiers change whenever the helpdesk is reconfigured, so read them from configuration rather than embedding them in code.
2. Look up the contact by the session's address before creating one, and store the returned contact identifier on the app's user record so every later ticket reuses it instead of spawning a fresh contact each time.
3. Validate attachments against the provider's size and type limits in the browser and again on the server, and tell the user exactly what was rejected before the ticket is submitted.
4. Carry a request identifier generated before the first attempt and check for an existing ticket bearing it before creating one, so a timeout that actually succeeded does not file a duplicate.
5. If Zendesk or Help Scout briefs are also applied to this app, one shared submission path owns the form, context capture, attachments, and deduplication. This brief owns only the Freshdesk mapping and delivery.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Creating a new contact on every submission is the default failure mode here. Resolve and store the contact identifier, and reconcile it when the provider merges two contacts behind the app's back.
- A group, product, or custom field that has been renamed or removed must fail into an operator alert with the ticket still queued, rather than being dropped or filed into whatever queue happens to accept it.
- Files over the size limit or of a rejected type must be reported before submission, with the option to send the ticket without them rather than losing the whole request.
- A submission retried after a timeout must be deduplicated on the request identifier, because the first attempt may have already filed the ticket.
- Raw provider errors stay in the app's logs. The user sees a plain result and a reference they can quote, and agents do not receive the app's stack traces either.
- When the provider is unavailable the request must be accepted and queued with the user told it was received. Failing a help request when the user is already stuck is the worst possible moment to fail.
- Automatically attached context must exclude credentials, tokens, and full request bodies, which would otherwise be readable by every agent on the account.
- The ticket identifier must be stored against the app record so status can be shown and replies threaded correctly.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Request types map onto requester, group, product, source, status, and custom fields through configuration rather than code.
- [ ] Repeat submissions from the same user reuse a single provider contact.
- [ ] Attachment limits are enforced before submission and every rejection is explained to the user.
- [ ] A submission retried after a timeout yields exactly one ticket.
- [ ] Provider errors are logged internally while the user sees a plain outcome and a reference.
- [ ] Provider downtime queues the request instead of failing the submission.
- [ ] The ticket reference is stored against the app record.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.