# Salesforce Lead Creation

## Objective

Push qualified leads into Salesforce with the fields and ownership sales needs to follow up.

A push of qualified app leads into a configurable Salesforce object with mapped fields, ownership, and a visible sync status.

## 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. Let an admin choose which object a lead becomes — a Lead, a Contact, or a custom object — because organizations model this differently and hardcoding one of them makes the feature unusable for half of them.
2. Read the target object's field definitions from the connected org at configuration time, including which fields are required and which picklist values are valid, and build the mapping from that rather than from assumptions.
3. Defer duplicate prevention to the org's configured matching and duplicate rules where they exist, and handle the resulting duplicate response as an expected outcome that links to the existing record, not as an error.
4. Set an owner using a rule the admin configures — a named user, a queue, or round-robin over a group — and fall back to a defined default when the mapped owner is inactive. An unowned lead is a lead nobody follows up.
5. Do not surface raw provider errors to end users. Log the full detail for operators, and show the person who submitted the form a plain confirmation that their submission was received.

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

- Organizations use Leads, Contacts, and custom objects in incompatible ways, and some do not use Leads at all. The target object and its field mapping must be configuration, or the integration only fits the org it was written against.
- Required fields and picklists vary by org and by record type, and an unknown picklist value is rejected outright. Read the schema from the connected org and validate the mapping against it before saving, not on the first live lead.
- Creating without consulting the org's matching rules floods the pipeline with duplicates. When the org reports a duplicate, treat that as success, link the app record to the existing one, and record why no new record was created.
- Sessions expire and orgs enforce hard API request limits that the app can exhaust in a backfill. Refresh proactively, back off and requeue on limits, and mark the connection broken when reauthorization is genuinely required.
- Provider error text names internal fields, validation rules, and org configuration that no end user should see. Keep it in operator-facing logs, and give the submitter a plain outcome with a reference an operator can look up.
- An owner mapping can point at a user who has been deactivated or a queue that has been removed. Detect it, assign the configured fallback, and flag the mapping for correction rather than failing the create.
- Validation rules and required-field configuration change without warning after the mapping was built. A rejected lead must be retained locally in a failed state with the reason attached, and must be replayable once the mapping is fixed.
- When the org is unreachable, the app must still accept and store the lead. Queue the push, show it as pending on the record, and never lose the submission to the outage.

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

- [ ] The destination object and field mapping are configurable per connected org.
- [ ] The mapping is validated against the org's current fields, required flags, and picklist values before it can be saved.
- [ ] The org's duplicate rules are respected and a duplicate response links to the existing record instead of erroring.
- [ ] Every created record has an owner, with a defined fallback when the mapped owner is inactive.
- [ ] Expired sessions refresh and API limits produce backoff, not lost leads.
- [ ] End users see a plain outcome while operators get the full provider error and a reference.
- [ ] Rejected leads are retained locally with a reason and can be replayed.
- [ ] 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.