# WooCommerce Order Sync

## Objective

Pull WooCommerce orders and customers into the app across stores you do not control.

A sync of orders and their customers from a connected store, tolerant of custom statuses, taxes, currencies, and plugins.

## 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. Treat the store's configuration as unknown at build time. Read the statuses, tax rows, currencies, and payment methods the store actually reports rather than hard-coding the defaults a stock install ships with.
2. Map any unrecognized order status onto a defined local fallback and keep the raw value alongside it. A plugin-defined status must never be read as complete by accident.
3. Verify every incoming webhook against the store's shared secret before acting on it, and key the resulting write on the store plus the order identifier so redelivery is harmless.
4. Hold a cursor for the sync and resume from it after an authentication failure or a rate limit. Do not restart the whole sync from the beginning after a transient failure; that reprocesses months of orders and buries the actual error.
5. Where the app also writes back to the store, stamp the origin of each write and ignore updates the app itself caused. This has the same shape as Shopify Order Import, so keep one shared import pipeline and vary only the provider adapter.

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

- Self-hosted stores run arbitrary plugins. An order may carry statuses, fee lines, tax rows, and meta fields the app has never seen, and none of them may abort the import.
- An unverified webhook is an untrusted request from the open internet. Reject anything whose signature does not match, and never fall back to trusting the payload because the signature header was absent.
- Redelivery is normal and must be safe. Two deliveries of the same order update must leave exactly one local record in the same final state.
- Products and customers get deleted after the order that references them. The order must remain importable from the values it captured at the time, with the missing reference marked rather than the row rejected.
- If the app writes status back into the store, the store's own webhook returns that change. Ignore echoes of the app's own writes, or the two systems will trade updates without end.
- Expired credentials and rate limits are temporary conditions. Pause the sync, retain the cursor, surface the reason where an operator will see it, and resume from that point rather than dropping the window.
- Stores in other locales report dates in the site's own time zone and decimals with a comma separator. Normalize both on the way in rather than assuming one format.
- A store that is offline or mid-upgrade returns an HTML error page instead of structured data. Treat an unparseable response as a retryable failure, never as an empty list of orders.

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

- [ ] Orders import from stores with custom statuses, tax rows, and plugin fields without failing.
- [ ] Unrecognized statuses map to a defined local state and the raw value is retained.
- [ ] Webhooks are signature-verified, and repeated delivery of the same event changes nothing after the first.
- [ ] Orders referencing deleted products or customers remain intact with the missing reference marked.
- [ ] The sync resumes from its last cursor after an authentication or rate-limit interruption, with the reason visible to an operator.
- [ ] Bidirectional updates terminate; no order oscillates between the app and the store.
- [ ] 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.