feat(sdk): trade intelligence in the OpenAPI spec and TypeScript SDK

chatgpt-app-submission.json

@@ -4,7 +4,7 @@
   "app_info": {
     "display_name": "Terminal49",
     "subtitle": "Track shipping containers",
-    "description": "Terminal49 helps users find and monitor ocean shipments and containers, filter and count their container worklists (by status, terminal, carrier, holds, last free day, arrival, or company), inspect routes and transport events, check supported shipping lines, and create new tracking requests through ChatGPT.",
+    "description": "Terminal49 helps users find and monitor ocean shipments and containers, filter and count their container worklists (by status, terminal, carrier, holds, last free day, arrival, or company), inspect routes and transport events, check supported shipping lines, create new tracking requests, and, where trade intelligence is enabled, research US ocean import markets (importers, products, origins, ports, and carriers) through ChatGPT.",
     "category": "BUSINESS"
   },
   "tools": {
@@ -175,6 +175,90 @@
         "open_world_justification": "Reads the connected Terminal49 account only and does not change any external system.",
         "destructive_justification": "Does not delete, overwrite, revoke access, or perform irreversible actions."
       }
+    },
+    "search_importers": {
+      "annotations": {
+        "readOnlyHint": true,
+        "openWorldHint": false,
+        "destructiveHint": false
+      },
+      "justifications": {
+        "read_only_justification": "Searches US import market data for importers by name or product without modifying records.",
+        "open_world_justification": "Reads Terminal49's own trade intelligence data; does not publish content or change public or third-party systems.",
+        "destructive_justification": "Does not delete, overwrite, revoke access, or perform irreversible actions."
+      }
+    },
+    "get_importer_profile": {
+      "annotations": {
+        "readOnlyHint": true,
+        "openWorldHint": false,
+        "destructiveHint": false
+      },
+      "justifications": {
+        "read_only_justification": "Reads one importer's US import history from market data without modifying records.",
+        "open_world_justification": "Reads Terminal49's own trade intelligence data; does not publish content or change public or third-party systems.",
+        "destructive_justification": "Does not delete, overwrite, revoke access, or perform irreversible actions."
+      }
+    },
+    "search_commodities": {
+      "annotations": {
+        "readOnlyHint": true,
+        "openWorldHint": false,
+        "destructiveHint": false
+      },
+      "justifications": {
+        "read_only_justification": "Looks up product codes in US import market data without modifying records.",
+        "open_world_justification": "Reads Terminal49's own trade intelligence data; does not publish content or change public or third-party systems.",
+        "destructive_justification": "Does not delete, overwrite, revoke access, or perform irreversible actions."
+      }
+    },
+    "rank_importers": {
+      "annotations": {
+        "readOnlyHint": true,
+        "openWorldHint": false,
+        "destructiveHint": false
+      },
+      "justifications": {
+        "read_only_justification": "Ranks importers in US import market data without modifying records.",
+        "open_world_justification": "Reads Terminal49's own trade intelligence data; does not publish content or change public or third-party systems.",
+        "destructive_justification": "Does not delete, overwrite, revoke access, or perform irreversible actions."
+      }
+    },
+    "get_trade_trends": {
+      "annotations": {
+        "readOnlyHint": true,
+        "openWorldHint": false,
+        "destructiveHint": false
+      },
+      "justifications": {
+        "read_only_justification": "Reads US import volume time series without modifying records.",
+        "open_world_justification": "Reads Terminal49's own trade intelligence data; does not publish content or change public or third-party systems.",
+        "destructive_justification": "Does not delete, overwrite, revoke access, or perform irreversible actions."
+      }
+    },
+    "get_trade_breakdown": {
+      "annotations": {
+        "readOnlyHint": true,
+        "openWorldHint": false,
+        "destructiveHint": false
+      },
+      "justifications": {
+        "read_only_justification": "Reads US import volume totals by dimension without modifying records.",
+        "open_world_justification": "Reads Terminal49's own trade intelligence data; does not publish content or change public or third-party systems.",
+        "destructive_justification": "Does not delete, overwrite, revoke access, or perform irreversible actions."
+      }
+    },
+    "get_trade_data_coverage": {
+      "annotations": {
+        "readOnlyHint": true,
+        "openWorldHint": false,
+        "destructiveHint": false
+      },
+      "justifications": {
+        "read_only_justification": "Reads the coverage dates of the US import market data without modifying records.",
+        "open_world_justification": "Reads Terminal49's own trade intelligence data; does not publish content or change public or third-party systems.",
+        "destructive_justification": "Does not delete, overwrite, revoke access, or perform irreversible actions."
+      }
     }
   },
   "test_cases": [

claude-connector-submission.json

@@ -10,7 +10,7 @@
   "listing": {
     "name": "Terminal49",
     "tagline": "Track ocean shipments",
-    "description": "Terminal49 helps users find and monitor ocean shipments and containers, filter and count their container worklists (by status, terminal, carrier, holds, last free day, arrival, or company), inspect routes and transport events, check supported shipping lines, and create new tracking requests.",
+    "description": "Terminal49 helps users find and monitor ocean shipments and containers, filter and count their container worklists (by status, terminal, carrier, holds, last free day, arrival, or company), inspect routes and transport events, check supported shipping lines, create new tracking requests, and, where trade intelligence is enabled, research US ocean import markets (importers, products, origins, ports, and carriers).",
     "categories": [
       "Business"
     ],
@@ -25,14 +25,21 @@
       "get_container",
       "get_container_route",
       "get_container_transport_events",
+      "get_importer_profile",
       "get_shipment_details",
       "get_supported_shipping_lines",
+      "get_trade_breakdown",
+      "get_trade_data_coverage",
+      "get_trade_trends",
       "list_containers",
       "list_parties",
       "list_shipments",
       "list_tracking_requests",
+      "rank_importers",
+      "search_commodities",
       "search_container",
       "search_docs",
+      "search_importers",
       "summarize_containers",
       "track_container",
       "whoami"
@@ -50,7 +57,8 @@
       "Filter and count container worklists by status, terminal, carrier, holds, last free day, or company",
       "Inspect routes and transport events",
       "Check supported shipping lines",
-      "Create new tracking requests"
+      "Create new tracking requests",
+      "Research US ocean import markets: importers, products, origin countries, ports, and carriers"
     ]
   }
 }

docs/api-docs/api-reference/trade-intelligence/get-an-import-breakdown.mdx

@@ -0,0 +1,7 @@
+---
+title: "Get an import breakdown"
+description: "Get nested totals with subtotals at every level of a dimension hierarchy such as region, country, and port, or HS chapter and heading."
+og:title: Import Breakdown | Terminal49 API Documentation
+og:description: Break US ocean imports down by region, country, port, carrier, or HS code with Terminal49's trade intelligence API.
+openapi: post /trade_intel/breakdown
+---

docs/api-docs/api-reference/trade-intelligence/get-an-importer-profile.mdx

@@ -0,0 +1,7 @@
+---
+title: "Get an importer profile"
+description: "Get one importer's monthly container history, ports of discharge, origin countries, carriers, destination states, and HS4 commodities from US import bill-of-lading records."
+og:title: Importer Profile | Terminal49 API Documentation
+og:description: Pull an importer's monthly ocean import history and trade lanes with Terminal49's trade intelligence API.
+openapi: post /trade_intel/companies/profile
+---

docs/api-docs/api-reference/trade-intelligence/get-import-trends.mdx

@@ -0,0 +1,7 @@
+---
+title: "Get import trends"
+description: "Get monthly, quarterly, or yearly series of containers, TEUs, or estimated value, split by up to two dimensions and filtered by company, commodity, lane, or carrier."
+og:title: Import Trends | Terminal49 API Documentation
+og:description: Chart US ocean import trends by commodity, origin, port, carrier, or company with Terminal49's trade intelligence API.
+openapi: post /trade_intel/trends
+---

docs/api-docs/api-reference/trade-intelligence/get-trade-intelligence-coverage.mdx

@@ -0,0 +1,7 @@
+---
+title: "Get trade intelligence coverage"
+description: "Return the window, history start, partial month, and build time of Terminal49 trade intelligence, built from US import bill-of-lading records."
+og:title: Trade Intelligence Coverage | Terminal49 API Documentation
+og:description: Check the coverage window and freshness of Terminal49 trade intelligence before quoting import volumes.
+openapi: get /trade_intel/meta
+---

docs/api-docs/api-reference/trade-intelligence/look-up-a-bill-of-lading.mdx

@@ -0,0 +1,7 @@
+---
+title: "Look up a bill of lading"
+description: "Get the import record for a master or house bill of lading from US Customs manifests: containers, consignee, shipper, notify party, and commodity lines."
+og:title: Bill of Lading Import Record | Terminal49 API Documentation
+og:description: Look up a bill of lading's containers, parties, and commodity lines with Terminal49's trade intelligence API.
+openapi: post /trade_intel/bills_of_lading/lookup
+---

docs/api-docs/api-reference/trade-intelligence/look-up-a-containers-import-record.mdx

@@ -0,0 +1,7 @@
+---
+title: "Look up a container's import record"
+description: "Get the most recent US import of a container from US Customs manifests: bills of lading, carrier, vessel, ports, destination, parties, and commodity lines."
+og:title: Container Import Record | Terminal49 API Documentation
+og:description: Look up a container's most recent US import, its bills of lading, parties, and commodities with Terminal49's trade intelligence API.
+openapi: post /trade_intel/containers/lookup
+---

docs/api-docs/api-reference/trade-intelligence/rank-importers.mdx

@@ -0,0 +1,7 @@
+---
+title: "Rank importers"
+description: "Rank US importers by physical containers for an HS4 heading, port of discharge, or origin country over full calendar months."
+og:title: Top US Importers | Terminal49 API Documentation
+og:description: Rank the largest US importers of a commodity, through a port, or from a country with Terminal49's trade intelligence API.
+openapi: post /trade_intel/importers/top
+---

docs/api-docs/api-reference/trade-intelligence/search-commodities.mdx

@@ -0,0 +1,7 @@
+---
+title: "Search commodities"
+description: "Resolve a product description or HS code prefix to 4-digit HS headings with common goods, estimated import value, and importer counts."
+og:title: Search Commodities | Terminal49 API Documentation
+og:description: Find the HS4 heading for a product and see what is declared under it with Terminal49's trade intelligence API.
+openapi: post /trade_intel/commodities/search
+---

docs/api-docs/api-reference/trade-intelligence/search-importers.mdx

@@ -0,0 +1,7 @@
+---
+title: "Search importers"
+description: "Find US importers by name or by what they import, with 12-month container volumes, TEUs, estimated value, and top ports, origins, carriers, and commodities."
+og:title: Search US Importers | Terminal49 API Documentation
+og:description: Search US importers by company name or product using Terminal49's trade intelligence API, built from US Customs manifests.
+openapi: post /trade_intel/companies/search
+---

docs/api-docs/in-depth-guides/mcp.mdx

@@ -170,7 +170,7 @@ Once configured, verify everything works:
   <Step title="Ask Claude to list tools">
     > "List the tools available in the Terminal49 MCP server."
 
-    Claude should respond with a list of 14 tools including `search_container`, `track_container`, and list tools.
+    Claude should respond with a list of 21 tools including `search_container`, `track_container`, the list tools, and the trade intelligence tools.
   </Step>
   <Step title="Search for a test container">
     > "Using the Terminal49 MCP server, search for container TCLU1234567 and summarize its status."

docs/docs.json

@@ -260,6 +260,21 @@
               "api-docs/api-reference/account/get-the-current-credential"
             ]
           },
+          {
+            "group": "Trade Intelligence",
+            "icon": "chart-line",
+            "pages": [
+              "api-docs/api-reference/trade-intelligence/get-trade-intelligence-coverage",
+              "api-docs/api-reference/trade-intelligence/search-importers",
+              "api-docs/api-reference/trade-intelligence/get-an-importer-profile",
+              "api-docs/api-reference/trade-intelligence/search-commodities",
+              "api-docs/api-reference/trade-intelligence/rank-importers",
+              "api-docs/api-reference/trade-intelligence/get-import-trends",
+              "api-docs/api-reference/trade-intelligence/get-an-import-breakdown",
+              "api-docs/api-reference/trade-intelligence/look-up-a-containers-import-record",
+              "api-docs/api-reference/trade-intelligence/look-up-a-bill-of-lading"
+            ]
+          },
           {
             "group": "Shipping Lines",
             "icon": "ship",
@@ -440,18 +455,39 @@
                   "sdk/reference/client/managers/classes/ShipmentManager",
                   "sdk/reference/client/managers/classes/ShippingLineManager",
                   "sdk/reference/client/managers/classes/TrackingRequestManager",
+                  "sdk/reference/client/managers/classes/TradeIntelManager",
                   "sdk/reference/client/managers/interfaces/ContainerAddPartyRoleParams",
                   "sdk/reference/client/managers/interfaces/CreateDocumentParams",
                   "sdk/reference/client/managers/interfaces/CreateTrackingRequestFromInferOptions",
                   "sdk/reference/client/managers/interfaces/DocumentListFilters",
                   "sdk/reference/client/managers/interfaces/ShipmentAddPartyRoleParams",
                   "sdk/reference/client/managers/interfaces/TrackingRequestListFilters",
                   "sdk/reference/client/managers/interfaces/UpdateDocumentParams",
+                  "sdk/reference/client/managers/interfaces/TradeIntelBillOfLadingLookupOptions",
                   "sdk/reference/client/managers/type-aliases/ContainerUpdateAttributes",
                   "sdk/reference/client/managers/type-aliases/DocumentRotation",
                   "sdk/reference/client/managers/type-aliases/ShipmentUpdateAttributes",
                   "sdk/reference/client/managers/type-aliases/TrackingRequestType",
-                  "sdk/reference/client/managers/type-aliases/TrackingRequestUpdateAttributes"
+                  "sdk/reference/client/managers/type-aliases/TrackingRequestUpdateAttributes",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelBillOfLadingLookup",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelBreakdown",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelBreakdownRequest",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelCommoditySearchRequest",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelCommoditySearchResponse",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelCompanyProfile",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelCompanyProfileRequest",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelCompanySearchRequest",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelCompanySearchResponse",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelCompanySearchResult",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelContainerLookup",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelDimension",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelFilters",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelMeasure",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelMeta",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelTopImporters",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelTopImportersRequest",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelTrends",
+                  "sdk/reference/client/managers/type-aliases/TradeIntelTrendsRequest"
                 ]
               },
               {