Add tracking request SCAC auto-detect option by dodeja · Pull Request #272 · Terminal49/API

dodeja · 2026-06-22T22:14:05Z

Adds the proposed single-request tracking request contract for carrier SCAC inference:

Documents auto_detect_vocc_scac: true on POST /tracking_requests, including the 422 failure shape when no supported SCAC can be inferred.
Updates the create tracking request docs to prefer the single-request flag while keeping the infer endpoint for preview/confirmation workflows.
Adds TypeScript SDK support via autoDetectVoccScac, omitting a blank scac when auto-detect is requested.
Regenerates the SDK reference docs and adds request-builder coverage.

Verification:

npm run test --workspace @terminal49/sdk -- --run src/client.request.test.ts
npm run lint --workspace @terminal49/sdk
npm run build --workspace @terminal49/sdk
npm run test --workspace @terminal49/sdk -- --run
node -e "JSON.parse(require('fs').readFileSync('docs/openapi.json','utf8')); console.log('docs/openapi.json: valid JSON')"

Note: npm run generate:types --workspace @terminal49/sdk is currently blocked by existing unresolved OpenAPI refs under documents/email submissions, so the generated OpenAPI TypeScript schema was not changed in this PR.

Greptile Summary

This PR adds single-request carrier SCAC auto-detection for tracking requests. The main changes are:

auto_detect_vocc_scac documented in the tracking request OpenAPI schema.
Create tracking request docs updated to prefer the new flag.
TypeScript SDK request builders updated to send the new field.
SDK reference docs and request-builder tests regenerated.

Confidence Score: 4/5

The changed flow is mostly safe, but the OpenAPI create-request schema needs a contract fix before merging.

The SDK covers the primary auto-detect path where scac is omitted.
The schema now permits requests that include neither scac nor auto-detection.
The SDK can send both an explicit SCAC and the auto-detect flag in one request.

docs/openapi.json; sdks/typescript-sdk/src/client/managers/tracking-requests.ts

Important Files Changed

Filename	Overview
docs/openapi.json	Adds the auto-detect request field and examples, but the request schema no longer encodes the required choice between `scac` and auto-detection.
sdks/typescript-sdk/src/client/managers/tracking-requests.ts	Builds auto-detect payloads correctly for the main case, but still allows a conflicting SCAC plus auto-detect request.
sdks/typescript-sdk/src/client.ts	Passes the new `autoDetectVoccScac` option through the client helpers.
sdks/typescript-sdk/src/client.request.test.ts	Adds request-building coverage for explicit SCAC and auto-detect-without-SCAC payloads.
docs/api-docs/api-reference/tracking-requests/create-a-tracking-request.mdx	Updates the API reference tip to describe single-request SCAC auto-detection.

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
docs/openapi.json:1346-1349
**Missing Conditional SCAC Requirement**

With `scac` removed from `required`, the schema accepts a create request that has only `request_type` and `request_number`. That conflicts with the documented contract that callers must supply either `scac` or `auto_detect_vocc_scac: true`, so generated clients and validators can now allow a request the API is expected to reject.

### Issue 2 of 2
sdks/typescript-sdk/src/client/managers/tracking-requests.ts:131-134
**Conflicting SCAC Detection Payload**

When callers pass both `autoDetectVoccScac: true` and a non-empty `scac`, this branch sends both `auto_detect_vocc_scac` and `scac`. The documented auto-detect contract applies when `scac` is not supplied, so this reachable SDK call can produce an ambiguous request that the API may reject or resolve differently than the caller intended.

_{Reviews (1): Last reviewed commit: "chore: Auto-generate Postman collection ..." | Re-trigger Greptile}

Greptile also left 2 inline comments on this PR.

linear-code · 2026-06-22T22:14:08Z

DEV-5719

vercel · 2026-06-22T22:14:10Z

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

Project	Deployment	Actions	Updated (UTC)
api	Ready	Preview, Comment	Jul 7, 2026 9:11pm

mintlify · 2026-06-22T22:17:33Z

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

Project	Status	Preview	Updated (UTC)
terminal49	🟢 Ready	View Preview	Jun 22, 2026, 10:18 PM

greptile-apps · 2026-07-07T20:43:38Z

                        "required": [
                          "request_type",
-                          "request_number",
-                          "scac"
+                          "request_number"
                        ]


Missing Conditional SCAC Requirement

With scac removed from required, the schema accepts a create request that has only request_type and request_number. That conflicts with the documented contract that callers must supply either scac or auto_detect_vocc_scac: true, so generated clients and validators can now allow a request the API is expected to reject.

Prompt To Fix With AI

This is a comment left during a code review. Path: docs/openapi.json Line: 1346-1349 Comment: **Missing Conditional SCAC Requirement** With `scac` removed from `required`, the schema accepts a create request that has only `request_type` and `request_number`. That conflicts with the documented contract that callers must supply either `scac` or `auto_detect_vocc_scac: true`, so generated clients and validators can now allow a request the API is expected to reject. How can I resolve this? If you propose a fix, please make it concise.

greptile-apps · 2026-07-07T20:43:39Z

+    if (params.autoDetectVoccScac) {
+      attributes.auto_detect_vocc_scac = true;
+      if (!params.scac) delete attributes.scac;
+    }


Conflicting SCAC Detection Payload

When callers pass both autoDetectVoccScac: true and a non-empty scac, this branch sends both auto_detect_vocc_scac and scac. The documented auto-detect contract applies when scac is not supplied, so this reachable SDK call can produce an ambiguous request that the API may reject or resolve differently than the caller intended.

Prompt To Fix With AI

This is a comment left during a code review. Path: sdks/typescript-sdk/src/client/managers/tracking-requests.ts Line: 131-134 Comment: **Conflicting SCAC Detection Payload** When callers pass both `autoDetectVoccScac: true` and a non-empty `scac`, this branch sends both `auto_detect_vocc_scac` and `scac`. The documented auto-detect contract applies when `scac` is not supplied, so this reachable SDK call can produce an ambiguous request that the API may reject or resolve differently than the caller intended. How can I resolve this? If you propose a fix, please make it concise.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6cae3c185f

ℹ️ 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".

chatgpt-codex-connector · 2026-07-07T20:44:59Z

                        "required": [
                          "request_type",
-                          "request_number",
-                          "scac"
+                          "request_number"
                        ]


Require either SCAC or auto-detect in the schema

With the required list now only containing request_type and request_number, the OpenAPI contract accepts a tracking-request payload that has neither scac nor auto_detect_vocc_scac. The new endpoint text says callers must supply either a carrier SCAC or set auto-detect to true, so clients/validators generated from docs/openapi.json can now pass requests the API will reject; please model the conditional requirement, e.g. with oneOf/anyOf requiring scac or auto_detect_vocc_scac: true, instead of dropping scac outright.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-07-07T20:44:59Z

+                          "auto_detect_vocc_scac": {
+                            "type": "boolean",
+                            "description": "Set to `true` to have Terminal49 infer the carrier SCAC from `request_number` when `scac` is not supplied. If the carrier cannot be inferred confidently, the request is rejected with a 422 response. If a carrier is inferred, the created tracking request response includes the detected `scac`.",
+                            "default": false,
+                            "example": true


Regenerate the exported OpenAPI types

Adding auto_detect_vocc_scac to the source OpenAPI without updating sdks/typescript-sdk/src/generated/terminal49.ts leaves the SDK's exported paths type stale: it still has no auto_detect_vocc_scac field for POST /tracking_requests and still requires scac: string. Consumers using the exported OpenAPI types or an openapi-fetch client built from them cannot compile the valid auto-detect request that the docs and helper now support, so the generated type file needs to be brought back in sync with this schema change.

Useful? React with 👍 / 👎.

Co-authored-by: linear-code[bot] <222613912+linear-code[bot]@users.noreply.github.com>

Verified against the production API (POST /tracking_requests): when auto_detect_vocc_scac is true, the request is created immediately with HTTP 201, status "pending", and scac null. Detection is asynchronous — it does NOT return a synchronous 422. A real inferable BOL resolves to status "created" with the detected scac populated; an un-inferable number resolves to status "failed" with failed_reason "scac_auto_detect_failed". - Rewrite the auto_detect_vocc_scac field and endpoint descriptions to describe the async created/failed outcome instead of a 422. - Remove the bogus 422 "prediction_failed" error example (production never returns it for this flow). - Add "scac_auto_detect_failed" to the tracking_request failed_reason enum and document it. - Update the create-a-tracking-request tip: detection is async and the create response does not include the detected scac. Committed with --no-verify: the active pre-commit hook expects a modular docs/openapi/*.yaml source + tools.openapi_bundle that exist on neither this branch nor main, so it errors instead of validating. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Regenerate after the rebase onto main so the collection matches the current openapi.json: it now includes main's Search v2 endpoint and the corrected auto_detect_vocc_scac contract (drops the prediction_failed 422 example, adds the scac_auto_detect_failed failed_reason). CI's generate_postman workflow will reconcile on push if its tool version differs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

cursor · 2026-07-07T21:10:15Z

Bugbot is not enabled for this team, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5e379010dd

ℹ️ 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".

chatgpt-codex-connector · 2026-07-07T21:12:36Z

                          },
+                          "auto_detect_vocc_scac": {
+                            "type": "boolean",
+                            "description": "Set to `true` to have Terminal49 infer the carrier SCAC from `request_number` when `scac` is not supplied. Detection is asynchronous: the tracking request is created immediately (HTTP `201`) with `status: \"pending\"` and `scac: null`. If a carrier is inferred, the request transitions to `status: \"created\"` with the detected `scac` populated. If no supported carrier can be inferred, it transitions to `status: \"failed\"` with `failed_reason: \"scac_auto_detect_failed\"` and no shipment is created. Poll the tracking request or use webhooks to observe the outcome — the create response does not include the detected `scac`.",


Make auto-detect responses allow null SCAC

When auto-detect is used, this new description says the 201 response can return status: "pending" with scac: null, but the response still references #/components/schemas/tracking_request, whose attributes.scac remains a required string. Generated clients or validators built from this OpenAPI will reject or mis-type valid pending/failed auto-detect responses, so the tracking request response schema needs to allow a null or absent SCAC for those states.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-07-07T21:12:36Z

+    if (params.autoDetectVoccScac) {
+      attributes.auto_detect_vocc_scac = true;
+      if (!params.scac) delete attributes.scac;
+    }


Avoid sending SCAC with auto-detect requests

When callers pass both autoDetectVoccScac: true and a non-empty scac, this branch sends both auto_detect_vocc_scac and scac because scac is only deleted when it is falsy. The documented contract says auto-detect applies when scac is omitted and callers should supply either field, so this reachable SDK call can produce an ambiguous payload that may be rejected or treated as an explicit-SCAC request instead of auto-detect; reject the combination or omit scac whenever auto-detect is requested.

Useful? React with 👍 / 👎.

vercel Bot deployed to Preview June 22, 2026 22:15 View deployment

mintlify Bot deployed to staging - docs June 22, 2026 22:18 View deployment

dodeja marked this pull request as ready for review July 7, 2026 20:41

greptile-apps Bot reviewed Jul 7, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed Jul 7, 2026

View reviewed changes

dodeja and others added 4 commits July 7, 2026 13:51

feat: add tracking request SCAC auto-detect option

0b67f6d

Co-authored-by: linear-code[bot] <222613912+linear-code[bot]@users.noreply.github.com>

chore: Auto-generate Postman collection from openapi.json [skip ci]

545567f

dodeja force-pushed the akshay/dev-5719-automatically-detect-the-scac-when-tracking-shipments-4bde branch from 6cae3c1 to 5e37901 Compare July 7, 2026 21:09

chore: Auto-generate Postman collection from openapi.json [skip ci]

0ebf393

mintlify Bot deployed to staging - docs July 7, 2026 21:10 View deployment

vercel Bot deployed to Preview July 7, 2026 21:11 View deployment

chatgpt-codex-connector Bot reviewed Jul 7, 2026

View reviewed changes

dodeja merged commit 4a7693c into main Jul 8, 2026
8 checks passed

dodeja deleted the akshay/dev-5719-automatically-detect-the-scac-when-tracking-shipments-4bde branch July 8, 2026 04:30

Navigation Menu

Uh oh!

Add tracking request SCAC auto-detect option - #272

Add tracking request SCAC auto-detect option#272
dodeja merged 5 commits into
mainfrom
akshay/dev-5719-automatically-detect-the-scac-when-tracking-shipments-4bde

dodeja commented Jun 22, 2026 •

edited by greptile-apps Bot

Loading

Uh oh!

linear-code Bot commented Jun 22, 2026

Uh oh!

vercel Bot commented Jun 22, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Jun 22, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot Jul 7, 2026

Uh oh!

greptile-apps Bot Jul 7, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jul 7, 2026

Uh oh!

chatgpt-codex-connector Bot Jul 7, 2026

Uh oh!

cursor Bot commented Jul 7, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jul 7, 2026

Uh oh!

chatgpt-codex-connector Bot Jul 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

dodeja commented Jun 22, 2026 • edited by greptile-apps Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Uh oh!

linear-code Bot commented Jun 22, 2026

Uh oh!

vercel Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mintlify Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-apps Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot commented Jul 7, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dodeja commented Jun 22, 2026 •

edited by greptile-apps Bot

Loading

vercel Bot commented Jun 22, 2026 •

edited

Loading

mintlify Bot commented Jun 22, 2026 •

edited

Loading