fix(sdk)!: apply the review and live-test fixes from #433

docs/docs.json

@@ -417,12 +417,15 @@
                   "sdk/reference/client/classes/Terminal49Client",
                   "sdk/reference/client/interfaces/Terminal49ClientConfig",
                   "sdk/reference/client/interfaces/CustomFieldDefinitionListFilters",
+                  "sdk/reference/client/interfaces/CustomFieldDefinitionListOptions",
                   "sdk/reference/client/interfaces/CustomFieldListFilters",
                   "sdk/reference/client/interfaces/TriggerWebhookParams",
                   "sdk/reference/client/interfaces/VesselFuturePositionsParams",
                   "sdk/reference/client/interfaces/VesselFuturePositionsWithCoordsParams",
                   "sdk/reference/client/interfaces/WebhookNotificationGetOptions",
-                  "sdk/reference/client/interfaces/WebhookNotificationListOptions"
+                  "sdk/reference/client/interfaces/WebhookNotificationListOptions",
+                  "sdk/reference/client/type-aliases/PartyAttributes",
+                  "sdk/reference/client/type-aliases/WebhookEvent"
                 ]
               },
               {
@@ -437,13 +440,18 @@
                   "sdk/reference/client/managers/classes/ShipmentManager",
                   "sdk/reference/client/managers/classes/ShippingLineManager",
                   "sdk/reference/client/managers/classes/TrackingRequestManager",
+                  "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/type-aliases/ContainerUpdateAttributes",
                   "sdk/reference/client/managers/type-aliases/DocumentRotation",
-                  "sdk/reference/client/managers/type-aliases/TrackingRequestType"
+                  "sdk/reference/client/managers/type-aliases/ShipmentUpdateAttributes",
+                  "sdk/reference/client/managers/type-aliases/TrackingRequestType",
+                  "sdk/reference/client/managers/type-aliases/TrackingRequestUpdateAttributes"
                 ]
               },
               {
@@ -497,7 +505,11 @@
                   "sdk/reference/types/models/interfaces/Shipment",
                   "sdk/reference/types/models/interfaces/ShippingLine",
                   "sdk/reference/types/models/interfaces/TrackingRequest",
-                  "sdk/reference/types/models/interfaces/TrackingSlots"
+                  "sdk/reference/types/models/interfaces/TrackingSlots",
+                  "sdk/reference/types/models/interfaces/Vessel",
+                  "sdk/reference/types/models/interfaces/VesselPosition",
+                  "sdk/reference/types/models/interfaces/VesselWithFuturePositions",
+                  "sdk/reference/types/models/type-aliases/CustomFieldValue"
                 ]
               },
               {

docs/sdk/error-handling.mdx

@@ -16,8 +16,8 @@ The SDK throws typed errors you can catch and handle based on the error type.
 
 | Error | Cause |
 |-------|-------|
-| `AuthenticationError` | Invalid or missing API key |
-| `AuthorizationError` | Valid API key but insufficient permissions |
+| `AuthenticationError` | HTTP 401. The API key is invalid or missing, or the API refused the action for this key. `error.message` carries the API's detail. |
+| `AuthorizationError` | HTTP 403. The API key is valid but lacks permission for the request. |
 | `NotFoundError` | Resource doesn't exist or isn't accessible |
 | `ValidationError` | Invalid request parameters |
 | `RateLimitError` | Too many requests |
@@ -43,7 +43,7 @@ try {
   await client.containers.get('container-uuid');
 } catch (error) {
   if (error instanceof AuthenticationError) {
-    console.error('Invalid API key');
+    console.error(`Authentication failed: ${error.message}`);
   } else if (error instanceof NotFoundError) {
     console.error('Container not found');
   } else if (error instanceof RateLimitError) {

docs/sdk/methods.mdx

@@ -20,6 +20,12 @@ The SDK exposes a `Terminal49Client` with methods grouped by resource type. Each
 |--------|-------------|
 | `client.search(query)` | Search across shipments and containers by number, reference, or keyword |
 
+### Credential
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `client.me(options?)` | `GET /me` | Describe the credential behind the client: whether it is an API key or a signed-in user, the account it is scoped to, and which gated features it can use there. Works for free-plan API keys too. |
+
 ### Shipments
 
 | Method | Description |
@@ -41,7 +47,7 @@ The SDK exposes a `Terminal49Client` with methods grouped by resource type. Each
 
 | Method | Description |
 |--------|-------------|
-| `client.containers.get(id, include?, options?)` | Fetch a container by ID. `include` is an array of related resources. |
+| `client.containers.get(id, include?, options?)` | Fetch a container by ID. `include` is an array of related resources. `mapped` returns a `Container`. |
 | `client.containers.list(filters?, options?)` | List containers matching filter criteria. |
 | `client.containers.events(id, options?)` | Get transport events for a container. |
 | `client.containers.route(id, options?)` | Get the container's route from `GET /containers/{id}/map_geojson`. `raw` returns the GeoJSON FeatureCollection. `mapped` returns `{ ports, currentVessel, totalPorts }`, with ports in route order and their arrival and departure times. Requires the Routing Data feature. `client.containers.map` is deprecated. It returns the GeoJSON FeatureCollection without mapping, so `both` returns `{ raw, mapped }` with the FeatureCollection in each half. |
@@ -61,8 +67,9 @@ The SDK exposes a `Terminal49Client` with methods grouped by resource type. Each
 | Method | Description |
 |--------|-------------|
 | `client.trackingRequests.list(filters?, options?)` | List tracking requests. |
-| `client.trackingRequests.get(id, options?)` | Fetch a single tracking request. |
+| `client.trackingRequests.get(id, options?)` | Fetch a single tracking request. `options.include` accepts `tracked_object`, `customer`, and `user`. In `mapped` format, `shipment` comes from `tracked_object`. |
 | `client.trackingRequests.update(id, attrs, options?)` | Update tracking request attributes. |
+| `client.trackingRequests.cancel(id)` | Cancel a tracking request that is still `pending` or `awaiting_manifest`. Other statuses return 422. |
 | `client.trackingRequests.create(params)` | Create a tracking request with an explicit request type and SCAC. |
 | `client.trackingRequests.inferNumber(number)` | Detect whether a number is a container, booking, or bill of lading. |
 | `client.trackingRequests.createFromInfer(number, options?)` | Create a tracking request with automatic number type detection. |
@@ -75,16 +82,16 @@ The SDK exposes a `Terminal49Client` with methods grouped by resource type. Each
 
 | Method | Description |
 |--------|-------------|
-| `client.vessels.get(id, options?)` | Fetch a vessel by ID. |
-| `client.vessels.getByImo(imo, options?)` | Fetch a vessel by IMO number. |
-| `client.vessels.futurePositions(id, { portId, previousPortId }, options?)` | Get the vessel's estimated positions between the previous port and the destination port. Requires the Routing Data feature. |
-| `client.vessels.futurePositionsWithCoords(id, { portId, previousPortId, latitude, longitude }, options?)` | Get the vessel's estimated positions from a starting coordinate to the destination port. Requires the Routing Data feature. |
+| `client.vessels.get(id, options?)` | Fetch a vessel by ID. `mapped` returns a `Vessel`. |
+| `client.vessels.getByImo(imo, options?)` | Fetch a vessel by IMO number. `mapped` returns a `Vessel`. |
+| `client.vessels.futurePositions(id, { portId, previousPortId }, options?)` | Get the vessel's estimated positions between the previous port and the destination port. `mapped` returns a `VesselWithFuturePositions`. Requires the Routing Data feature. |
+| `client.vessels.futurePositionsWithCoords(id, { portId, previousPortId, latitude, longitude }, options?)` | Get the vessel's estimated positions from a starting coordinate to the destination port. `mapped` returns a `VesselWithFuturePositions`. Requires the Routing Data feature. |
 
 ### Shipping lines
 
 | Method | Description |
 |--------|-------------|
-| `client.shippingLines.list(search?, options?)` | List carriers. Use `search` to filter by name or SCAC. |
+| `client.shippingLines.list(search?, options?)` | List carriers. `search` keeps the carriers whose SCAC, alternative SCACs, name, or short name contain the text, ignoring case. The SDK filters the full list because the API has no search parameter. |
 | `client.shippingLines.get(id, options?)` | Fetch a carrier by ID. |
 
 ### Webhooks
@@ -106,7 +113,7 @@ The SDK exposes a `Terminal49Client` with methods grouped by resource type. Each
 |--------|----------|-------------|
 | `client.webhookNotifications.list(options?)` | `GET /webhook_notifications` | List webhook notifications. Supports pagination and `options.include`. |
 | `client.webhookNotifications.get(id, options?)` | `GET /webhook_notifications/{id}` | Fetch a webhook notification. Pass `options.include` to sideload relationships. |
-| `client.webhookNotifications.examples(event?, options?)` | `GET /webhook_notifications/examples` | Get example notification payloads. Set `event` to get the examples for one event. |
+| `client.webhookNotifications.examples(event, options?)` | `GET /webhook_notifications/examples` | Get the example notification payload for `event`. `event` is required. |
 
 ### Ports, terminals, and metro areas
 
@@ -129,17 +136,17 @@ The SDK exposes a `Terminal49Client` with methods grouped by resource type. Each
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `client.customFieldDefinitions.list(options?)` | `GET /custom_field_definitions` | List definitions. Filter with `options.filters` by `entityType`, `dataType`, or `displayName`. |
+| `client.customFieldDefinitions.list(options?)` | `GET /accounts/{account_id}/custom_field_definitions` | List your account's definitions. Filter with `options.filters` by `entityType`, `dataType`, or `displayName`. Set `scope: 'templates'` to list the Terminal49 templates from `GET /custom_field_definitions`. The list is not paginated. |
 | `client.customFieldDefinitions.get(id, options?)` | `GET /custom_field_definitions/{id}` | Fetch a definition. |
-| `client.customFieldDefinitions.create(payload, options?)` | `POST /custom_field_definitions` | Create a definition. `payload` is the JSON:API request body. |
+| `client.customFieldDefinitions.create(payload, options?)` | `POST /accounts/{account_id}/custom_field_definitions` | Create a definition for your account. `payload` is the JSON:API request body. Set `data.attributes.template_id` to copy a template. |
 | `client.customFieldDefinitions.update(id, payload, options?)` | `PATCH /custom_field_definitions/{id}` | Update a definition. `payload` is the JSON:API request body. |
 | `client.customFieldDefinitions.delete(id, options?)` | `DELETE /custom_field_definitions/{id}` | Delete a definition. |
 
 ### Custom field options
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `client.customFieldOptions.list(definitionId, options?)` | `GET /custom_field_definitions/{id}/options` | List the options of a definition. Supports pagination. |
+| `client.customFieldOptions.list(definitionId, options?)` | `GET /custom_field_definitions/{id}/options` | List every option of a definition. The list is not paginated. |
 | `client.customFieldOptions.get(definitionId, optionId, options?)` | `GET /custom_field_definitions/{id}/options/{option_id}` | Fetch an option. |
 | `client.customFieldOptions.create(definitionId, payload, options?)` | `POST /custom_field_definitions/{id}/options` | Create an option. `payload` is the JSON:API request body. |
 | `client.customFieldOptions.update(definitionId, optionId, payload, options?)` | `PATCH /custom_field_definitions/{id}/options/{option_id}` | Update an option. `payload` is the JSON:API request body. |
@@ -149,7 +156,7 @@ The SDK exposes a `Terminal49Client` with methods grouped by resource type. Each
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `client.customFields.list(options?)` | `GET /custom_fields` | List custom field values. Filter with `options.filters` by `entityType`, `entityId`, or `definitionId`. |
+| `client.customFields.list(options?)` | `GET /custom_fields` | List custom field values. Filter with `options.filters` by `entityType`, `entityId`, or `definitionId`. The list is not paginated. |
 | `client.customFields.get(id, options?)` | `GET /custom_fields/{id}` | Fetch a custom field value. |
 | `client.customFields.create(payload, options?)` | `POST /custom_fields` | Create a custom field value. `payload` is the JSON:API request body. |
 | `client.customFields.update(id, payload, options?)` | `PATCH /custom_fields/{id}` | Update a custom field value. `payload` is the JSON:API request body. |
@@ -162,7 +169,7 @@ The SDK exposes a `Terminal49Client` with methods grouped by resource type. Each
 | `client.documents.list(filters?, options?)` | `GET /documents` | List documents. Filter by `filename`, `reference`, or `documentTypes`, and set `sort` and `include`. |
 | `client.documents.get(id, options?)` | `GET /documents/{id}` | Fetch a document. Pass `options.include` to sideload relationships. |
 | `client.documents.create({ name, attachedDocument }, options?)` | `POST /documents` | Create a document from a direct-uploaded blob. `attachedDocument` is the signed blob ID. |
-| `client.documents.update(id, { documentTypeManual?, extractedDataManual? }, options?)` | `PATCH /documents/{id}` | Override the document type or the extracted data. Pass `extractedDataManual: null` to clear manually provided extracted data. |
+| `client.documents.update(id, { documentType?, classificationNotes?, extractedDataManual? }, options?)` | `PATCH /documents/{id}` | Override the document type with a code from `documents.types()`, the classification notes, or the extracted data. Pass `null` for `classificationNotes` or `extractedDataManual` to clear it. |
 | `client.documents.delete(id, options?)` | `DELETE /documents/{id}` | Delete a document. |
 | `client.documents.types(options?)` | `GET /documents/types` | List the document types Terminal49 can classify. |
 | `client.documents.downloadUrl(id, options?)` | `GET /documents/{id}/download_url` | Get a short-lived download URL for the document's file. |
@@ -269,7 +276,7 @@ const shipment = await client.shipments.get('shipment-id', true, {
 Supported formats:
 
 - `raw` (default) returns the JSON:API response
-- `mapped` returns simplified objects for methods that support mapping
+- `mapped` returns simplified objects for methods that support mapping. Other methods return the JSON:API response unchanged.
 - `both` returns `{ raw, mapped }`
 
 You can set a default format when initializing the client:

docs/sdk/reference/client/classes/AuthenticationError.mdx

@@ -5,7 +5,7 @@ description: "AuthenticationError class in the Terminal49 TypeScript SDK, thrown
 
 # Class: AuthenticationError
 
-Thrown when the API token is invalid or missing (HTTP 401).
+Thrown on HTTP 401: the API token is invalid or missing, or the API denied the action for this token.
 
 ## Extends