feat/fedex customer references full support

[ChrisNolan]

This change expands FedEx shipment customerReferences support from a single hardcoded invoice reference to full multi-type handling.

What changed

• Added FedEx customer reference builders in provider utils and wired them into shipment request creation.
• Implemented reference mapping for:
  • CUSTOMER_REFERENCE (from shipment reference)
  • INVOICE_NUMBER (from customs invoice, with options fallback)
  • DEPARTMENT_NUMBER (from options)
  • P_O_NUMBER (from options)
  • RMA_ASSOCIATION (from options)
• Applied FedEx length constraints per reference type (including conservative CUSTOMER_REFERENCE limit for Ground compatibility).
• Removed incorrect PO mapping from package reference values.

What is now available (was not before)

• FedEx requests now send multiple valid customer reference types in the correct shipment sections (commercial invoice and package line items), instead of only a hardcoded invoice reference.
• API callers can now populate FedEx-specific references via shipment options (for example fedex_po_number, fedex_department_number, fedex_rma_association) and have them forwarded to FedEx correctly.
• Added focused unit coverage for reference construction/collection plus regression validation in FedEx shipment tests.

[vercel]

@ChrisNolan is attempting to deploy a commit to the karrio Team on Vercel.

A member of the Team first needs to authorize it.

[andersonvom]

This is great! I was about to put together a PR to address this very issue, but you beat me to it 🥳

[zebradots]

Also about to submit a PR for this same functionality, but glad to see it's already been done!

[danh91]

Reviewed — looks good, approving. Thanks @ChrisNolan — this fixes the long-standing REF-field gap (#1082) and the test coverage is excellent.

We're going to apply some cleanups in the release branch (2026.1.32) to bring it in line with karrio conventions, and I'll leave inline notes on the specific spots. In short: build the customerReferences lists inline in the request tree (the lib.identity(...) / comprehension idiom UPS and FedEx already use) instead of a collect_customer_references helper that returns a keyed dict and gets called twice, and declare the new reference inputs as proper OptionEnums in units.py rather than raw payload.options lookups. Same behavior, your fixtures still pass.

Merging so it ships in 2026.1.32.

[danh91]

Cleanup applied in the 2026.1.32 release branch (patch/2026.1.32): build_customer_reference and collect_customer_references were removed from here.

Why: karrio builds the request tree inline at the call site (see UPS ReferenceNumber and the rest of FedEx's create.py). A helper that returns a {commercial_invoice, package} dict — and is called twice per shipment (once per key) — adds indirection without reuse value, and indexing it by string key is the opposite of inline-tree construction. The per-type length limits are now applied inline via lib.text(value, max=30|20).

[danh91]

In the release branch both collect_customer_references(...)["..."] calls are now built inline in the request tree as [_ref for _ref in [fedex.CustomerReferenceType(...), ...] if _ref.value] — computed once per site, and each site shows exactly which references it includes.

Also: fedex_department_number, fedex_po_number and fedex_rma_association are now declared as OptionEnums in units.py (with i18n), so they're read via options.<name>.state and surface in the schema — instead of raw payload.options.get("fedex_x") or .get("x") lookups with dual key spellings.

[danh91]

Removed in the release branch along with the helpers it covered. These also used mock.MagicMock() for payload/customs/options, whereas karrio tests drive gateway.mapper and assert the serialized request. Coverage is now a request-level test (test_shipment.py::test_create_shipment_request_with_customer_references) plus the canonical full-dict tests, which already assert INVOICE_NUMBER + CUSTOMER_REFERENCE output. Thanks for the thorough original coverage — much appreciated.