# Zendesk Ticket Creation

## Objective

Turn an in-app support request into a Zendesk ticket with the context agents need.

An in-app support form that files a Zendesk ticket carrying the requester, the surrounding product context, and any attachments.

## 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. Find the points where a user currently has to leave the app to ask for help, and put the request form there, prefilled with what an agent would otherwise have to ask for: account, plan, workspace, current screen, app version, and any recent error reference.
2. Set the requester from the authenticated session alone. Never let a submitted email address decide whose ticket this is, or one user can attach themselves to another person's support history.
3. Map the app's request types onto priority, type, tags, brand, and custom fields through operator-editable configuration. Embedding field identifiers in code guarantees a silent break the first time someone reconfigures the helpdesk.
4. Generate a request identifier before submission and carry it on every attempt, so a retry after a timeout is matched against the ticket that may already exist rather than opening a second one.
5. If Help Scout or Freshdesk briefs are also applied to this app, build one provider-agnostic submission path owning the form, context capture, attachments, and deduplication, and let each provider brief supply only its mapping and delivery. Do not build three parallel support forms.

## 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

- Matching an existing requester by email must be exact, and a match must never surface another user's ticket history back into the app.
- Attachments must be transferred server-side from storage the app controls. A guessable temporary URL handed to the provider is a public URL to a customer's private file.
- Size limits and rejected file types must be checked before submission, so the user is told immediately instead of after a ticket half-exists.
- A submission that times out mid-flight may still have succeeded. Deduplicate on the request identifier rather than assuming failure and retrying blind.
- The created ticket reference must be stored against the app record, so status can be shown later and a follow-up attaches to the same thread instead of starting a new one.
- When the provider is down the request must still be accepted, queued, and delivered later, with the user told it was received. Failing a help request is worst at the exact moment the user is already stuck.
- Provider error detail belongs in the app's logs. Show the user a plain outcome and a reference they can quote, not a raw message from someone else's API.
- Automatically captured context must exclude session tokens, API keys, and full request payloads, which would otherwise sit in a helpdesk searchable by every agent.

## 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

- [ ] Support requests can be raised without leaving the app and arrive with account and screen context attached.
- [ ] The requester is derived from the session and never from user-supplied input.
- [ ] Priority, type, tags, brand, and custom fields are mapped through operator-editable configuration.
- [ ] A submission retried after a timeout produces exactly one ticket.
- [ ] Attachments transfer server-side and are never exposed at a publicly reachable URL.
- [ ] The ticket reference is stored against the app record for later status and replies.
- [ ] Provider downtime results in a queued request and a clear confirmation, not a failed submission.
- [ ] 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.