fix(sdk): correct JSON:API mapper relationship/attr paths + restore shipping-line capability flags

[dodeja]

Summary

The mapped SDK responses silently dropped or nulled several real Terminal49 fields because the JSON:API mappers read relationship/attribute paths that don't exist in the payloads. This corrects every path against the real API response shapes (verified from existing fixtures and the generated OpenAPI schema):

• mapRoute route-leg port — read a non-existent port relationship on each route_location, so every leg's port was always null. Route legs expose their port via the location relationship (type port|terminal) per the OpenAPI schema. Now reads location.
• Port code vs locode — Port resources expose code (e.g. KRPUS), never locode, so the mapped locode fields were always undefined. mapShipment, mapTransportEvents, and the container inline transport-event location now read code (with a defensive ?? locode fallback).
• mapContainer status + facility — read a non-existent attrs.status (real attribute is current_status) and a non-existent destination_terminal relationship, while the real pickup_facility relationship was never read. Now maps current_status → status/currentStatus and surfaces pickup_facility as the destination terminal.
• attrCamel clobber — the raw camelCased attribute spread clobbered curated nested fields and emitted ~19 duplicate top-level scalars per container row. A new pure omitKeys helper (in jsonapi.ts) drops the curated-source keys from the spread so curated nests win and no duplicate scalars leak.
• Shipping-line capability flags — the shipping-line mapper dropped alternative_scacs and the three *_tracking_support booleans; they're restored as alternativeScacs, billOfLadingTrackingSupport, bookingNumberTrackingSupport, containerNumberTrackingSupport.

TDD

Golden-fixture tests were written first (red), then the mappers were fixed until green. New fixtures containers.route.json and containers.get.pickup.json are seeded from the real JSON:API shapes / OpenAPI route_location schema. The previously-skipped route test now runs (and its port lookup was corrected to use the real location relationship).

Issues

Closes DEV-10662

Green gate

npm run build --workspace @terminal49/sdk ✅
npm run build --workspace @terminal49/mcp ✅
npm run type-check --workspace @terminal49/sdk ✅
npm run type-check --workspace @terminal49/mcp ✅
npm test --workspace @terminal49/sdk ✅ 57 passed | 1 skipped
npm run test --workspace @terminal49/mcp ✅ 77 passed

SDK gained +6 passing mapping tests (baseline was 51 pass / 2 skip → now 57 pass / 1 skip). MCP unchanged (77 pass). oxlint + oxfmt --check clean.

Notes / follow-ups

• ContainerInclude in src/types/options.ts still advertises the wrong destination_terminal include value and omits pickup_facility. That type is owned by another PR, so this PR passes the container include as a string in tests and notes it here. A follow-up should update that enum to pickup_facility.

This is an AI-drafted PR for human review.

🤖 Generated with Claude Code

Greptile Summary

This PR corrects a batch of wrong JSON:API attribute/relationship paths across the SDK mappers — fixing silently-null port codes, current_status vs status, pickup_facility vs destination_terminal, and a raw-attribute spread that clobbered curated nested objects — and restores four missing shipping-line capability fields.

• mapContainer: current_status → status/currentStatus, pickup_facility relationship replaces the non-existent destination_terminal, and omitKeys prevents the camelCase attribute spread from clobbering curated nested objects (equipment, location, demurrage, terminals, rail).
• mapRoute: Route-leg port now read via the location relationship (type port|terminal), which is the actual JSON:API relationship name; the old port relationship never existed on route_location.
• mapShipment / mapTransportEvents: Port locode fields now read attributes.code (with a ?? locode defensive fallback) since Terminal49 port resources expose code, not locode.
• mapShippingLines: alternativeScacs, billOfLadingTrackingSupport, bookingNumberTrackingSupport, and containerNumberTrackingSupport restored. However, these fields are not yet declared on the ShippingLine TypeScript interface, so they are inaccessible to typed consumers.

Confidence Score: 3/5

The mapper fixes are mostly correct, but two gaps prevent a clean merge: mapTrackingRequest still reads container.attributes?.status (will always be undefined), and the four new shipping-line fields are not declared in the ShippingLine interface, making them invisible to typed consumers.

Most of the mapper corrections are accurate and well-tested. However, mapTrackingRequest repeats the exact same wrong attribute name (status instead of current_status) that this PR set out to fix in mapContainer, so tracking-request responses will continue to silently drop the container status. Separately, the restored shipping-line capability fields are added to the runtime object but omitted from the ShippingLine TypeScript interface, meaning SDK consumers using typed access cannot reach them without an extra cast.

sdks/typescript-sdk/src/client/mappers.ts — the mapTrackingRequest function and the ShippingLine interface in src/types/models.ts both need attention.

Important Files Changed

Filename	Overview
sdks/typescript-sdk/src/client/mappers.ts	Core mapper fixes for JSON:API path bugs. mapContainer correctly fixed; mapTrackingRequest still reads container.attributes?.status (should be current_status). New ShippingLine fields are missing from the interface type. Route location type (port vs terminal) is unchecked.
sdks/typescript-sdk/src/client/jsonapi.ts	New omitKeys helper is correct and well-guarded. No issues.
sdks/typescript-sdk/src/client.mapping.test.ts	Good golden-fixture tests for each fixed mapper path; route port test upgraded from skipped. No test coverage for the mapTrackingRequest container status regression.
sdks/typescript-sdk/src/fixtures/containers.get.pickup.json	New fixture correctly uses current_status, pickup_facility, and excludes a non-existent status attribute.
sdks/typescript-sdk/src/fixtures/containers.route.json	New route fixture uses location relationship (not port) on each route_location, matching the fixed mapper logic.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
subgraph mapContainer
A[container resource] -->|pickup_facility rel ✅| B[destinationTerminal]
A -->|current_status attr ✅| C[status / currentStatus]
A -->|omitKeys spread ✅| D[equipment / location / demurrage / rail nested objects]
end
subgraph mapRoute
E[route_location resource] -->|location rel ✅| F[port or terminal]
F -->|.code ✅| G[leg port.code]
end
subgraph mapShipment_mapTransportEvents
H[port resource] -->|.code ?? .locode ✅| I[locode field]
end
subgraph mapShippingLines
J[shipping_line resource] -->|alternative_scacs ✅| K[alternativeScacs]
J -->|tracking_support ✅| L[3 capability flags]
L -.->|not in ShippingLine type ❌| M[TypeScript interface gap]
end
subgraph mapTrackingRequest
N[container relationship] -->|.status ❌ should be current_status| O[nested container.status always undefined]
end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
subgraph mapContainer
A[container resource] -->|pickup_facility rel ✅| B[destinationTerminal]
A -->|current_status attr ✅| C[status / currentStatus]
A -->|omitKeys spread ✅| D[equipment / location / demurrage / rail nested objects]
end
subgraph mapRoute
E[route_location resource] -->|location rel ✅| F[port or terminal]
F -->|.code ✅| G[leg port.code]
end
subgraph mapShipment_mapTransportEvents
H[port resource] -->|.code ?? .locode ✅| I[locode field]
end
subgraph mapShippingLines
J[shipping_line resource] -->|alternative_scacs ✅| K[alternativeScacs]
J -->|tracking_support ✅| L[3 capability flags]
L -.->|not in ShippingLine type ❌| M[TypeScript interface gap]
end
subgraph mapTrackingRequest
N[container relationship] -->|.status ❌ should be current_status| O[nested container.status always undefined]
end

Loading

Comments Outside Diff (3)

1. sdks/typescript-sdk/src/client/mappers.ts, line 430 (link)

   Container status still read as status in mapTrackingRequest

   container.attributes?.status is the same wrong attribute name that mapContainer just fixed — the real field on a container resource is current_status. When a TrackingRequest includes a related container, the nested status field will always be undefined, silently dropping the container's current state from every tracking-request response.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: sdks/typescript-sdk/src/client/mappers.ts
   Line: 430
   Comment:
   **Container status still read as `status` in `mapTrackingRequest`**`container.attributes?.status` is the same wrong attribute name that `mapContainer` just fixed — the real field on a container resource is `current_status`. When a `TrackingRequest` includes a related container, the nested `status` field will always be `undefined`, silently dropping the container's current state from every tracking-request response.
   How can I resolve this? If you propose a fix, please make it concise.

   

2. sdks/typescript-sdk/src/client/mappers.ts, line 151-165 (link)

   New ShippingLine fields missing from the interface type

   alternativeScacs, billOfLadingTrackingSupport, bookingNumberTrackingSupport, and containerNumberTrackingSupport are written into the returned object but are not declared in the ShippingLine interface in src/types/models.ts. The as ShippingLine cast silences the TypeScript error, so SDK consumers who type their variable as ShippingLine cannot access these fields without another cast. The runtime data is present but the public contract doesn't expose it.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: sdks/typescript-sdk/src/client/mappers.ts
   Line: 151-165
   Comment:
   **New `ShippingLine` fields missing from the interface type**`alternativeScacs`, `billOfLadingTrackingSupport`, `bookingNumberTrackingSupport`, and `containerNumberTrackingSupport` are written into the returned object but are not declared in the `ShippingLine` interface in `src/types/models.ts`. The `as ShippingLine` cast silences the TypeScript error, so SDK consumers who type their variable as `ShippingLine` cannot access these fields without another cast. The runtime data is present but the public contract doesn't expose it.
   How can I resolve this? If you propose a fix, please make it concise.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

   

3. sdks/typescript-sdk/src/client/mappers.ts, line 91-106 (link)

   Terminal-type location will produce an undefined code in the port object

   The location relationship on a route_location can resolve to either a port or a terminal (as noted in the OpenAPI schema and the PR description). When the resolved resource is a terminal, port.attributes?.code will be undefined because terminals use firms_code, not code. The leg's port object would still be truthy (non-null), so callers cannot distinguish a proper port from a structurally empty one. A type-check on the resolved resource (resource.type === 'port') before constructing the object would prevent this.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: sdks/typescript-sdk/src/client/mappers.ts
   Line: 91-106
   Comment:
   **Terminal-type `location` will produce an undefined `code` in the port object**
   The `location` relationship on a `route_location` can resolve to either a `port` or a `terminal` (as noted in the OpenAPI schema and the PR description). When the resolved resource is a terminal, `port.attributes?.code` will be `undefined` because terminals use `firms_code`, not `code`. The leg's port object would still be truthy (non-null), so callers cannot distinguish a proper port from a structurally empty one. A type-check on the resolved resource (`resource.type === 'port'`) before constructing the object would prevent this.
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.
---### Issue 1 of 3
sdks/typescript-sdk/src/client/mappers.ts:430
**Container status still read as `status` in `mapTrackingRequest`**`container.attributes?.status` is the same wrong attribute name that `mapContainer` just fixed — the real field on a container resource is `current_status`. When a `TrackingRequest` includes a related container, the nested `status` field will always be `undefined`, silently dropping the container's current state from every tracking-request response.
```suggestion status: container.attributes?.current_status ?? container.attributes?.status,```### Issue 2 of 3
sdks/typescript-sdk/src/client/mappers.ts:151-165
**New `ShippingLine` fields missing from the interface type**`alternativeScacs`, `billOfLadingTrackingSupport`, `bookingNumberTrackingSupport`, and `containerNumberTrackingSupport` are written into the returned object but are not declared in the `ShippingLine` interface in `src/types/models.ts`. The `as ShippingLine` cast silences the TypeScript error, so SDK consumers who type their variable as `ShippingLine` cannot access these fields without another cast. The runtime data is present but the public contract doesn't expose it.
### Issue 3 of 3
sdks/typescript-sdk/src/client/mappers.ts:91-106
**Terminal-type `location` will produce an undefined `code` in the port object**
The `location` relationship on a `route_location` can resolve to either a `port` or a `terminal` (as noted in the OpenAPI schema and the PR description). When the resolved resource is a terminal, `port.attributes?.code` will be `undefined` because terminals use `firms_code`, not `code`. The leg's port object would still be truthy (non-null), so callers cannot distinguish a proper port from a structurally empty one. A type-check on the resolved resource (`resource.type === 'port'`) before constructing the object would prevent this.

_{Reviews (1): Last reviewed commit: "fix(sdk): correct JSON:API mapper relati..." | Re-trigger Greptile}

[linear-code]

DEV-10662

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api	Ready	Preview, Comment	Jul 1, 2026 8:42pm

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:e94b0b86d6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[dodeja]

Triaged the Codex review + known residual type-hygiene findings. Pushed 4356b03.

Addressed

• Container include type/defaults (Codex inline comment, mappers.ts L179):ContainerInclude now lists the real pickup_facility relationship and drops the non-existent destination_terminal (that relationship only exists on shipments per the generated OpenAPI schema). The mapper resolves destinationTerminal from pickup_facility, so I also added pickup_facility to the default includes in ContainerManager.get/list and Terminal49Client.getContainer, and updated the affected mock-fetch handler URLs/assertions. Type-safe array calls like listContainers({ include: ['shipment', 'pod_terminal', 'pickup_facility'] }, { format: 'mapped' }) now type-check, and the default-include path populates destinationTerminal instead of always null.
• SDK type-hygiene (restored fields): Added explicit typed fields to the public interfaces so they're no longer reachable only via the index signature/casts — ShippingLine.{alternativeScacs, billOfLadingTrackingSupport, bookingNumberTrackingSupport, containerNumberTrackingSupport} and Container.currentStatus. Dropped the as ShippingLine cast in mapShippingLines in favour of a typed map return + type-predicate filter. Regenerated docs/sdk/reference for the changed public types.

Skipped

• MCP guidance docs / MCP tool z.enum(['shipment','pod_terminal','transport_events']) include schema: out of scope for this SDK-mapper PR; MCP passes plain string arrays to the SDK and is unaffected by the type change. No behavior bug.
• getDemurrage helper still uses include: ['pod_terminal']: it only reads raw attributes, never the mapped destinationTerminal relationship, so adding pickup_facility there would be noise.

Green gate: SDK build + type-check + 57 pass/1 skip; MCP build + type-check + 77 pass. oxfmt --check clean on the changed files.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
terminal49	🟢 Ready	View Preview	Jun 26, 2026, 10:35 AM

[dodeja]

Rebased onto current main (was 4 commits behind — main had picked up docs/workflow changes since this branch was opened) and re-verified.

Rebase conflicts resolved in sdks/typescript-sdk/src/client/managers/containers.ts and src/types/options.ts: main had refactored ContainerManager.list() onto the shared buildContainerListQuery/applyTypedPagination helpers after this branch forked. Kept that shared-helper structure and folded in this PR's pickup_facility default-include change by adding it to DEFAULT_CONTAINER_INCLUDES, so get() and list() both request pickup_facility by default as intended. The ContainerInclude conflict was comment-only (kept the explanatory comment).

Review feedback: The one substantive automated finding (Codex, P2, mappers.ts L179 — destinationTerminal resolves from pickup_facility but the typed ContainerInclude union/default-includes didn't request it) was already fixed on this branch in 4356b03 before this pass, and confirmed still correct post-rebase. No new inline comments since.

Checks:npm run build/test/lint --workspace @terminal49/sdk all green (67 passed/1 skipped, tsc clean, oxlint + oxfmt --check clean). Force-pushed the rebase with --force-with-lease.