👀 READY WITH CAVEATS: not verified for live freight
SKU-8974 · ShipStation as the second Freight provider
PR #7114 · kmizzi/shipstation-freight @ df7cecf · 2026-11-21 · UI verified in a component harness (real pages, mocked API)
PRD coverage: 13 of 14 Implementation Plan items built · live verification (Phase 4) blocked
The connection UI is proven, and the 3 bugs this run found are fixed in df7cecf and re-verified. CI bench is green. Review loop converged at R5. Still open: the money paths (quote, book, cancel, track, documents) have never run against a real freight provider, so this is not ready for live freight.

⚠ What I could NOT verify. Not safe to call it ready for live freight.

Functional correctness
Connect, test, pick account, save, connect a second account: all pass after df7cecf
Live provider paths
Quote, book, cancel, track, documents: NOT VERIFIED (no provider in ShipStation)
Edge cases & validation
7 cases: blank/space key, 200-char name, <script>/unicode, double-click, masked key
Visual integrity
1920 + 1280 captured. Alert clipping fixed (96/96px, 76/76px).
Error-free runtime
0 console errors across the flow
Backend integrity
API mocked in the harness; covered by backend suites + green CI bench
Data states
Loading, empty select, blocked, populated seen. Load-error state not exercised.
Permissions / access
Not exercised in the browser (admin only)
Automated tests
CI bench green · 48/48 ShipStation · 24/24 vitest
Code review
59 files · 5 review rounds, 19 findings applied, converged
Interactive UI & design
URL-driven drawer, select, connect-another, catalog to settings routing
Performance sanity
N/A: harness has no server
Scorecard: 7 pass · 4 caveat · 0 fail · 1 N/A  |  Scenes: 7 (7 pass)  |  Issues: 3 found, 3 fixed in df7cecf & re-verified

Narrated walkthrough (76 s, re-recorded on df7cecf)

Recorded headless at 1920×1080 against the component harness. Voice: en-US-AndrewNeural.

Functional correctness: scene by scene

Catalog Freight category
PASS 1. Catalog. The Freight category lists Warp Freight and ShipStation Freight, with the ShipStation logo, "Supports multiple instances", and the description from the tenant migration. Connect routes to Settings → Freight.
assert: route after Connect = /settings/freight?connect=shipstation · image /images/shipping_providers/shipstation_square.png loaded
Connect drawer
PASS 2. Connect drawer. The drawer shows the V2 API key field (masked), the connection name, and the "Freight provider account" select, disabled with "Connect, then test to load the choices". "Test and connect" stays disabled until a key is typed.
assert: select disabled = true · payload = {provider:"shipstation", name, credentials:{api_key:<redacted>}, settings:{freight_provider_account_id:null}}
Blocked card
PASS 3. No freight provider in ShipStation. This is the state of SKU.io's own paid account today. The card shows the quote_blocked_reason: "No freight account is connected in ShipStation. In ShipStation, open Freight → Connect your account (Worldwide Express or Unishippers), then test again." The whole message is visible. The provider card now offers "Connect another ShipStation account".
assert: [data-testid=connection-quote-blocked-32] text matches NO_PROVIDER_ACCOUNT_MESSAGE · alert clientHeight/scrollHeight = 96/96 (not clipped) · provider button = "Connect another ShipStation account"
Pick account
PASS 4. Test, pick, save. Test connection loads the accounts, so the card switches to "Pick the freight provider account…". In Edit, the select lists "Main (Worldwide Express)" and "Backup (Unishippers)". Saving Main clears the block, and the card names the account: "Freight provider account: Main (Worldwide Express)".
assert: options = ["Main (Worldwide Express)","Backup (Unishippers)"] · PUT settings = {freight_provider_account_id:"fpa_8f2c1e"} · blocked alert gone after save · card text contains "Main (Worldwide Express)", not the id
Connect another bug
PASS 5. Connect another ShipStation account. It opens an empty "Connect ShipStation" drawer. A second key and the name "ShipStation — east warehouse", then Test and connect, adds a second ShipStation connection.
assert: route = /settings/freight?connect=shipstation · drawer title "Connect ShipStation" · key input empty · POST {provider:"shipstation", name:"ShipStation — east warehouse", credentials:{api_key:<redacted>}} · cards = [21, 32, 33]
Two accounts
PASS 6. Two ShipStation accounts (same session, right after scene 5). Each card shows its own state: "main" is ready with its provider account, "east warehouse" is blocked with no freight provider.
assert: 3 connection cards · connection-quote-blocked-33 present · none on 32
Edit drawer
PASS 7. Edit drawer. The saved key is never sent back, only a "Saved …k3Qx" hint and "leave blank to keep". The chosen account stays selected.
assert: chip-credential-set-api_key visible · select value = "Main (Worldwide Express)"

Issues found & fixed (fixed by the coordinator in df7cecf, re-verified here)

P1 FIXED & RE-VERIFIED

"Connect another ShipStation account" edited the existing connection instead of creating a new one, so a second account could not be added from the UI. The catalog's Connect went through the same route and had the same problem. Fix: the new helper existingConnectionForConnect only redirects to an existing connection when the provider does not allow multiple connections. It has a vitest spec.

Before (e8d06d6): the drawer edits "ShipStation — main"
before
After (df7cecf): an empty "Connect ShipStation" drawer
after
P2 FIXED & RE-VERIFIED

The connection card's warning alerts were clipped (Vuetify's .v-alert has flex: 1 1 0% inside the card's flex column). Fix: flex-0-0 on the three card alerts. Measured before: 56px shown of 80px content at 1920, 46 of 53 at 1280. After: 96/96 and 76/76.

Before, 1920
before
After, 1920
after
Minor FIXED & RE-VERIFIED

The card printed the raw provider account id ("Freight provider account: fpa_8f2c1e"). It now shows the option label: "Main (Worldwide Express)" (scenes 4 and 6).

Edge cases & validation

CaseInputExpectedObservedStatus
Blank key(empty)"Test and connect" disableddisabled = truePASS
Whitespace key5 spacesstill disabled (trimmed)disabled = truePASS
Key maskingtyped keypassword input; never echoed on edittype=password; edit shows "Saved …k3Qx" onlyPASS
Long name200 × "X"capped at 60value length 60PASS
Special characters<script>alert(1)</script> "Ünïcode" ☃rendered as textshown literally; 0 <script> nodes in the cardPASS
Rapid clicksdouble-click + 3rd click on "Test and connect"one connectionexactly 1 card addedPASS
No provider accounts yetnew connectionselect disabled with guidance; card explains the block"Connect, then test to load the choices"; NO_PROVIDER message on cardPASS

Server-side validation (key tested before save, a freight_provider_account_id must be one of the stored options, wrong-key message) is covered by the backend suites, not this harness.

Interactive UI & design

BehaviorActionAsserted resultStatus
Catalog to settings linkConnect ShipStation Freightroute /settings/freight?connect=shipstation, drawer openPASS
URL-driven drawerEdit on a cardroute ?connection=32, drawer titled with the connection namePASS
Select settingopen, pick, clear icon2 options listed; value saved; clearablePASS
Cancel / closeCancel in drawerdrawer closes, query clearedPASS
Connect anotherprovider-card buttonblank drawer; saving adds a second accountPASS (fixed in df7cecf)

Design: cards elevation-0 border rounded, bg-grey-lighten-4 drawer section titles, small buttons, tonal chips, the same as the Warp cards. No tables on these screens, so sorting and pagination are N/A.

Visual integrity: two viewports

Catalog 1920 × 1080
Catalog 1280 × 800
Connect drawer 1920
Connect drawer 1280

No truncation or collisions on the catalog, drawer or cards. The card alert clipping found in the first run is fixed (see Issues). The grey band under the page is a harness artifact (no app bar), not product UI.

Error-free runtime

Console errors over the whole flow: 0 (after a harness favicon was added). There are no network calls to judge, because the API is mocked in-process.

Backend integrity

Not exercised from the browser, because the harness mocks the API. Backend behaviour is proven by the suites below and by the live API probes.

Data states

Loading skeletons (start of scene 2), empty select (scene 2), blocked with no provider (scene 3), pick-an-account (scene 4), populated and ready (scenes 4, 6). Not exercised: the page's load-error state.

Permissions / access

Only an admin user was used. The page gates edits on integrations.update and disconnects on integrations.delete, the same as the Warp cards. This was not exercised for a non-admin in this run.

Performance sanity

N/A. The static harness has no server latency to measure.

Live API probes (2026-11-21, redacted)

AccountCallResult
SKU.io paid ShipStation (dev@sku.io, own V2 key)GET /v2/carriers200
sameGET /v2/freight/provider_accounts200 {"freight_provider_accounts": []} (no provider connected)
sameGET /v2/freight/shipments200 {"shipments": [], "total": 0, "page": 1, "page_size": 25, "pages": 0}
Trial merchant keyPOST /v2/freight/quotes400 passed request validation and stopped at "freight_provider_account_id must be a valid provider account id". The live API requires dimension_unit/weight_unit even though the docs do not.
ShipStation API sandbox (TEST_ key), LTL test carriersquote: TEST200 $2,198.48 (canned)
samequote: WARN200 $382.47
samequote: FAIL400 "Carrier Error: Missing Ship From Address."

The sandbox LTL carriers use the older v-beta/ltl surface, not the V2 /freight endpoints the driver calls, so they show the shapes but do not prove the driver end to end. No keys appear on this page.

Automated tests

SuiteResult
Full CI bench, run 44948712546 (e8d06d6 with master merged)PASSED
After df7cecf: ShipStation driver, flow and connection tests48 / 48 passed
After df7cecf: frontend freight vitest24 / 24 passed; pnpm typecheck:changed clean
Freight + ShipStation + booking suites, after review round 4695 / 695 passed
Earlier full filtered backend run982 / 983 passed (1 skipped)
Frontend freight specs before df7cecf (vitest)21 / 21 passed

df7cecf adds a vitest for "Connect another" on a provider that allows multiple connections (the gap that let the P1 through). The CI bench ran on e8d06d6. The df7cecf delta is covered by the 48 + 24 targeted runs above.

Code review: the diff

Review loop. Codex is unavailable (quota until 11-25), so independent reviewer agents ran instead. R1: 8 findings applied · R2: 4 applied · R3: 3 applied · R4: 3 applied · R5: 1 found and fixed in df7cecf (a 4xx on the round-trip proof lookup leaked raw provider text). The loop has converged.

What changed. A ShipStation case on FreightProviderEnum with a select-type setting (freight provider account) and multiple connections allowed. A Saloon connector and a ShipStationFreightDriver for provider accounts, quotes, booking, shipment list and lookup, tracking, documents and cancel, with error mapping. setting_options and quote_blocked_reason on the connection resource. The catalog row through a tenant migration. Drawer support for select settings. Fixtures and feature tests.

 Modules/Freight/Config/config.php                                           |  24 +
 Modules/Freight/Contracts/FreightProviderDriver.php                         |   9 +-
 Modules/Freight/Data/FreightAccountStatusData.php                           |   4 +
 Modules/Freight/Data/FreightBookingAttemptData.php                          |  36 ++
 Modules/Freight/Data/FreightBookingRequestData.php                          |   7 +
 Modules/Freight/Data/FreightCapabilitiesData.php                            |   2 +
 Modules/Freight/Database/Factories/FreightIntegrationInstanceFactory.php    |  30 +-
 Modules/Freight/Drivers/ShipStationFreightDriver.php                        | 958 ++++++++++++++++++++++++++++++++++++
 Modules/Freight/Drivers/WarpFreightDriver.php                               |   4 +-
 Modules/Freight/Enums/FreightProviderEnum.php                               |  62 ++-
 Modules/Freight/Http/Controllers/FreightConnectionController.php            |   1 +
 .../Integrations/ShipStation/Requests/ShipStationCancelShipmentRequest.php  |  21 +
 .../Integrations/ShipStation/Requests/ShipStationCreateShipmentRequest.php  |  33 ++
 .../Integrations/ShipStation/Requests/ShipStationGetShipmentRequest.php     |  21 +
 .../ShipStation/Requests/ShipStationListProviderAccountsRequest.php         |  19 +
 .../Integrations/ShipStation/Requests/ShipStationListShipmentsRequest.php   |  31 ++
 .../Http/Integrations/ShipStation/Requests/ShipStationQuoteRequest.php      |  33 ++
 .../ShipStation/Requests/ShipStationShipmentDocumentsRequest.php            |  21 +
 .../Integrations/ShipStation/Requests/ShipStationTrackShipmentRequest.php   |  21 +
 Modules/Freight/Http/Integrations/ShipStation/ShipStationConnector.php      |  55 +++
 Modules/Freight/Http/Requests/SaveFreightConnectionRequest.php              |  41 +-
 Modules/Freight/Http/Resources/FreightConnectionResource.php                |   2 +
 Modules/Freight/Managers/FreightBookingManager.php                          |  28 +-
 Modules/Freight/Managers/FreightConnectionManager.php                       |  45 +-
 Modules/Freight/Repositories/FreightConnectionRepository.php                |  15 +-
 Modules/Freight/Repositories/FreightShipmentRepository.php                  |  15 +
 Modules/Freight/Tests/Feature/FreightBookingTest.php                        |   5 +-
 Modules/Freight/Tests/Feature/FreightIntegrationCatalogTest.php             |   4 +-
 Modules/Freight/Tests/Feature/ShipStationFreightDriverTest.php              | 693 ++++++++++++++++++++++++++
 Modules/Freight/Tests/Feature/ShipStationFreightFlowTest.php                | 370 ++++++++++++++
 Modules/Freight/Tests/Fixtures/shipstation/book.json                        |  23 +
 Modules/Freight/Tests/Fixtures/shipstation/cancel_refused.json              |  11 +
 Modules/Freight/Tests/Fixtures/shipstation/documents.json                   |   6 +
 Modules/Freight/Tests/Fixtures/shipstation/invalid_provider_account.json    |  12 +
 Modules/Freight/Tests/Fixtures/shipstation/provider_accounts.json           |  14 +
 Modules/Freight/Tests/Fixtures/shipstation/provider_accounts_empty.json     |   3 +
 Modules/Freight/Tests/Fixtures/shipstation/quotes.json                      |  36 ++
 Modules/Freight/Tests/Fixtures/shipstation/quotes_empty.json                |   3 +
 Modules/Freight/Tests/Fixtures/shipstation/shipments.json                   |  46 ++
 Modules/Freight/Tests/Fixtures/shipstation/tracking_delivered.json          |  14 +
 Modules/Freight/Tests/Fixtures/shipstation/tracking_in_transit.json         |  13 +
 Modules/Freight/Tests/Fixtures/shipstation/unauthorized.json                |  11 +
 Modules/Freight/Tests/Fixtures/shipstation/validation_error.json            |  12 +
 Modules/Freight/Tests/FreightTestCase.php                                   |  30 +-
 app/Models/Integration.php                                                  |   5 +
 app/Support/FeatureCatalog.php                                              |   2 +-
 .../tenant/2026_11_21_210000_seed_shipstation_freight_integration.php       |  36 ++
 database/seeders/ImmutableData/IntegrationsSeeder.php                       |  12 +-
 docs/plans/shipstation-freight-driver.md                                    | 279 +++++++++++
 docs/postman/postman-orders.json                                            |  16 +-
 frontend-vue-3/src/pages/integrations/constants.ts                          |   3 +
 frontend-vue-3/src/pages/settings/freight/__tests__/freightSettings.spec.ts |  73 ++-
 .../src/pages/settings/freight/components/FreightConnectionDrawer.vue       |  27 +-
 frontend-vue-3/src/pages/settings/freight/freightSettings.ts                |  35 ++
 frontend-vue-3/src/pages/settings/freight/index.vue                         |  35 +-
 frontend-vue-3/src/test/integrations/freightCatalog.spec.ts                 |   5 +
 frontend-vue-3/src/types/freight.ts                                         |  13 +
 resources/mcp/api-index.json                                                |   2 +-
 tests/Feature/IntegrationSyncSurfaceTest.php                                |   2 +-
 59 files changed, 3329 insertions(+), 60 deletions(-)

Full diff (text, 243 KB) · PR files on GitHub

Generated by /present · component harness (real Vue pages, mocked API) + playwright-cli + backend/frontend suites · 2026-11-21
Hosted on Cloudflare Pages: static files, no app behind it.