❌ NOT READY
SKU-8974 · ShipStation as the second Freight provider
PR #7114 · kmizzi/shipstation-freight @ e8d06d6 · 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
Why not ready: one open P1 UI bug (a second ShipStation account cannot be connected from the UI), and the money paths (quote, book, cancel, track, documents) have never run against a real freight provider.

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

Functional correctness
Connect, test, pick account, save: pass. "Connect another ShipStation account" opens the existing one (P1).
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. The "no freight account" alert is clipped (P2).
Error-free runtime
0 console errors across the flow
Backend integrity
API mocked in the harness; covered by 695 backend tests
Data states
Loading, empty select, blocked, populated seen. Load-error state not exercised.
Permissions / access
Not exercised in the browser (admin only)
Automated tests
695/695 backend after R4 · 21/21 vitest · bench in progress
Code review
59 files · 4 review rounds applied (18 findings) · R5 running
Interactive UI & design
URL-driven drawer, select, tooltips, catalog to settings routing
Performance sanity
N/A: harness has no server
Scorecard: 5 pass · 4 caveat · 2 fail · 1 N/A  |  Scenes: 7 (6 pass, 1 shows the bug)  |  Issues: 2 found, 0 fixed (report only)

Narrated walkthrough (75 s)

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 provider card now offers "Connect another ShipStation account".
assert: [data-testid=connection-quote-blocked-32] text matches NO_PROVIDER_ACCOUNT_MESSAGE · provider button = "Connect another ShipStation account" (but see P2: the alert text is clipped)
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.
assert: options = ["Main (Worldwide Express)","Backup (Unishippers)"] · PUT settings = {freight_provider_account_id:"fpa_8f2c1e"} · blocked alert gone after save
Connect another bug
FAIL 5. Connect another ShipStation account. Expected an empty Connect drawer for a second account. Observed: the drawer opens the existing "ShipStation — main" connection for editing. See P1 below.
assert: route after click = /settings/freight?connection=32 (expected ?connect=shipstation with a blank form)
Two accounts
PASS 6. Two ShipStation accounts (preset state). 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)"

Product bugs found (reported, not fixed)

P1 OPEN

"Connect another ShipStation account" edits the existing connection instead of creating a new one. Because of this, a second ShipStation account cannot be added from the UI. The catalog's Connect goes to the same ?connect=shipstation route and has the same problem. The backend allows it (FreightConnectionManager only refuses a second connection when allowsMultipleConnections() is false).

Cause: the watcher in frontend-vue-3/src/pages/settings/freight/index.vue (LIFECYCLE) rewrites ?connect=<provider> to ?connection=<first existing id> whenever a connection of that provider exists, without checking allows_multiple_connections. Suggested fix: only redirect when the provider does not allow multiple connections, and add a vitest for it.

Clicked "Connect another ShipStation account"
bug
Expected: a blank Connect drawer like this
expected
P2 OPEN

The connection card's warning alerts are clipped. The "No freight account is connected in ShipStation…" text loses its first and last lines, at both widths. Measured: alert 56px tall, content 80px at 1920; 46px vs 53px at 1280.

Cause: Vuetify's .v-alert has flex: 1 1 0% and overflow: hidden. Inside the card's d-flex flex-column it shrinks to share space with the <v-spacer>. The drawer already avoids this with class="flex-0-0". Add the same class to the three card alerts (last_test_error, quote_blocked_reason, account_warnings). The Warp alerts on the same card have the same problem.

1920: three columns
clipped 1920
1280: two columns
clipped 1280

Minor, not scored: the connected card prints the raw provider account id ("Freight provider account: fpa_8f2c1e") instead of its label ("Main (Worldwide Express)"). The card renders connection.settings values directly and does not look the value up in setting_options.

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 for a new accountFAIL (P1)

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 or the drawer. The card alerts are clipped (P2 above). 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
Freight + ShipStation + booking suites, after review round 4695 / 695 passed
Earlier full filtered backend run982 / 983 passed (1 skipped)
Frontend freight specs (vitest)21 / 21 passed; pnpm typecheck:changed clean
Full CI bench, run 44948712546IN PROGRESS

No vitest covers "Connect another" for a provider that allows multiple connections. That is why the P1 above got through.

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: in progress.

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                        | 949 ++++++++++++++++++++++++++++++++++++
 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              | 670 +++++++++++++++++++++++++
 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 |  55 ++-
 .../src/pages/settings/freight/components/FreightConnectionDrawer.vue       |  27 +-
 frontend-vue-3/src/pages/settings/freight/freightSettings.ts                |  20 +
 frontend-vue-3/src/pages/settings/freight/index.vue                         |  23 +-
 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, 3256 insertions(+), 56 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.