@veho/turvo-integration-sdk 0.1.0-beta.0

package/README.md

@@ -0,0 +1,473 @@
+# @veho/turvo-sdk
+
+TypeScript SDK for Turvo API integration. Provides clean abstractions for shipment tracking and management operations.
+
+## Installation
+
+```bash
+npm install @veho/turvo-sdk
+```
+
+## Prerequisites
+
+### AWS Secrets Manager Setup
+
+The SDK expects Turvo credentials in AWS Secrets Manager at `/turvo/api` (configurable):
+
+```json
+{
+  "apiKey": "your-turvo-api-key",
+  "username": "your-service-account-username",
+  "password": "your-service-account-password",
+  "urlBase": "https://api.turvo.com"
+}
+```
+
+### IAM Permissions
+
+Grant your Lambda/service permission to read the secret:
+
+```typescript
+import { TURVO_SECRET_PATH } from '@veho/turvo-sdk'
+import * as iam from 'aws-cdk-lib/aws-iam'
+
+myLambda.addToRolePolicy(new iam.PolicyStatement({
+  actions: ['secretsmanager:GetSecretValue'],
+  resources: [`arn:aws:secretsmanager:*:*:secret:${TURVO_SECRET_PATH}*`],
+}))
+```
+
+---
+
+## Use Cases
+
+### Use Case 1: Track Shipment Progress
+
+**When to use:** Monitor shipment status, ETA, GPS location, and stop progress.
+
+```typescript
+import { getShipmentTracking } from '@veho/turvo-sdk'
+
+// Get tracking data for a shipment
+const tracking = await getShipmentTracking('12345', {
+  includeGps: true  // Include GPS ping history (default: true)
+})
+
+console.log({
+  status: tracking.status,              // "En route"
+  isLate: tracking.isLate,              // false
+  lateBy: tracking.lateBy,              // null
+  currentLocation: tracking.currentLocation,  // "Biscoe, AR"
+  completedStops: tracking.completedStops,    // 2
+  totalStops: tracking.totalStops,            // 5
+  etaUtc: tracking.etaUtc,              // "2024-01-28T15:30:00Z"
+  milesRemaining: tracking.milesRemaining,    // 127
+
+  // GPS tracking (if available)
+  hasGpsTracking: tracking.hasGpsTracking,    // true
+  pingCount: tracking.pingCount,              // 45
+  lastPingAt: tracking.lastPingAt,            // "2024-01-28T14:22:00Z"
+
+  // Stops with details
+  stops: tracking.stops
+  // [
+  //   {
+  //     sequence: 1,
+  //     stopType: "Pickup",
+  //     isCompleted: true,
+  //     facilityCode: "PHL 01",
+  //     city: "Philadelphia",
+  //     state: "PA",
+  //     appointmentTimeUtc: "2024-01-28T08:00:00Z",
+  //     actualArrivalUtc: "2024-01-28T07:45:00Z",
+  //     actualDepartureUtc: "2024-01-28T09:15:00Z"
+  //   },
+  //   ...
+  // ]
+})
+```
+
+**Note:** GPS tracking (location updates) requires internal API access. Currently stubbed and returns `null`.
+
+---
+
+### Use Case 2: Create New Shipments
+
+**When to use:** Upload a new shipment to Turvo from your system.
+
+```typescript
+import { TurvoClient, TurvoPublicApi } from '@veho/turvo-sdk'
+
+const client = new TurvoClient()
+const publicApi = new TurvoPublicApi(client)
+
+// Create a complete shipment
+const result = await publicApi.uploadShipment({
+  shipment: {
+    id: 0,  // Will be assigned by Turvo
+    customId: 'VEHO-LOAD-98765',
+    ltlShipment: false,
+    startDate: {
+      date: '2024-01-28T08:00:00',
+      timeZone: 'America/New_York'
+    },
+    endDate: {
+      date: '2024-01-30T17:00:00',
+      timeZone: 'America/Los_Angeles',
+      flex: 0
+    },
+    status: {
+      code: { key: '2101', value: 'Tendered' }
+    },
+    equipment: [{
+      type: { key: 'VAN', value: 'Van' },
+      size: { key: '53', value: '53ft' }
+    }],
+    lane: {
+      start: 'Philadelphia, PA',
+      end: 'Los Angeles, CA'
+    },
+    globalRoute: [{
+      id: 0,
+      name: 'Pickup at PHL',
+      sequence: 1,
+      segmentSequence: 1,
+      state: 'OPEN',
+      stopType: { key: 'PICKUP', value: 'Pickup' },
+      schedulingType: { key: 'APPOINTMENT', value: 'Appointment' },
+      location: { id: 12345 },
+      appointment: {
+        date: '2024-01-28T08:00:00',
+        timeZone: 'America/New_York',
+        hasTime: true
+      }
+    }, {
+      id: 0,
+      name: 'Delivery at LAX',
+      sequence: 2,
+      segmentSequence: 2,
+      state: 'OPEN',
+      stopType: { key: 'DELIVERY', value: 'Delivery' },
+      schedulingType: { key: 'APPOINTMENT', value: 'Appointment' },
+      location: { id: 67890 },
+      appointment: {
+        date: '2024-01-30T17:00:00',
+        timeZone: 'America/Los_Angeles',
+        hasTime: true
+      }
+    }],
+    customerOrder: [{
+      customer: { id: 111, name: 'Acme Corp' },
+      customerOrderSourceId: 98765,
+      externalIds: [{
+        type: { key: '1401', value: 'Reference #' },
+        value: 'REF-98765',
+        copyToCarrierOrder: true
+      }]
+    }],
+    carrierOrder: [{
+      _operation: 0,
+      carrier: { id: 222, name: 'Swift Transport' },
+      carrierOrderSourceId: 55555
+    }]
+  },
+  vehoLoadId: 'LOAD-98765'  // For logging purposes
+})
+
+console.log(`Created shipment with ID: ${result.details.id}`)
+// Created shipment with ID: 12345
+```
+
+---
+
+### Use Case 3: Update Shipment Status
+
+**When to use:** Update status as shipment progresses through stops.
+
+```typescript
+import {
+  TurvoClient,
+  TurvoPublicApi,
+  TURVO_SHIPMENT_STATUS_AT_PICKUP,
+  TURVO_SHIPMENT_STATUS_PICKED_UP,
+  TURVO_SHIPMENT_STATUS_EN_ROUTE,
+  TURVO_SHIPMENT_STATUS_AT_DELIVERY,
+  TURVO_SHIPMENT_STATUS_DELIVERED
+} from '@veho/turvo-sdk'
+
+const client = new TurvoClient()
+const publicApi = new TurvoPublicApi(client)
+
+// Mark arrived at pickup
+await publicApi.updateShipmentStatus({
+  turvoShipmentId: 12345,
+  turvoStopId: 11111,  // First stop ID from globalRoute
+  turvoStatusCode: TURVO_SHIPMENT_STATUS_AT_PICKUP,
+  statusDate: '2024-01-28T07:45:00',
+  statusTimezone: 'America/New_York'
+})
+
+// Mark picked up
+await publicApi.updateShipmentStatus({
+  turvoShipmentId: 12345,
+  turvoStopId: 11111,
+  turvoStatusCode: TURVO_SHIPMENT_STATUS_PICKED_UP,
+  statusDate: '2024-01-28T09:15:00',
+  statusTimezone: 'America/New_York'
+})
+
+// Mark en route
+await publicApi.updateShipmentStatus({
+  turvoShipmentId: 12345,
+  turvoStopId: 22222,  // Second stop ID
+  turvoStatusCode: TURVO_SHIPMENT_STATUS_EN_ROUTE,
+  statusDate: '2024-01-28T09:30:00',
+  statusTimezone: 'America/New_York'
+})
+```
+
+---
+
+### Use Case 4: Tag Shipments
+
+**When to use:** Add metadata tags for filtering and organization.
+
+```typescript
+import { TurvoClient, TurvoPublicApi } from '@veho/turvo-sdk'
+
+const client = new TurvoClient()
+const publicApi = new TurvoPublicApi(client)
+
+// Add tags to categorize shipment
+await publicApi.associateTagsToShipment({
+  turvoShipmentId: 12345,
+  tags: ['urgent', 'fragile', 'high-value']
+})
+```
+
+---
+
+### Use Case 5: Cancel Shipments
+
+**When to use:** Mark shipment as cancelled in Turvo.
+
+```typescript
+import { TurvoClient, TurvoPublicApi } from '@veho/turvo-sdk'
+
+const client = new TurvoClient()
+const publicApi = new TurvoPublicApi(client)
+
+// Cancel a shipment
+await publicApi.cancelShipment({
+  turvoShipmentId: 12345
+})
+```
+
+---
+
+### Use Case 6: Query Shipments
+
+**When to use:** Fetch shipments by location and date range.
+
+```typescript
+import { TurvoClient, TurvoPublicApi } from '@veho/turvo-sdk'
+
+const client = new TurvoClient()
+const publicApi = new TurvoPublicApi(client)
+
+// Get shipments for a location
+let start = 0
+let moreAvailable = true
+
+while (moreAvailable) {
+  const result = await publicApi.filterShipments({
+    turvoLocationId: 12345,
+    pickupDateStart: '2024-01-01',
+    start
+  })
+
+  const shipments = result.details.shipments || []
+  console.log(`Retrieved ${shipments.length} shipments`)
+
+  shipments.forEach(shipment => {
+    console.log({
+      id: shipment.id,
+      customId: shipment.customId,
+      status: shipment.status.code.value,
+      customer: shipment.customerOrder[0]?.customer.name,
+      carrier: shipment.carrierOrder[0]?.carrier.name
+    })
+  })
+
+  // Check pagination
+  moreAvailable = result.details.pagination.moreAvailable
+  start += result.details.pagination.pageSize
+}
+```
+
+---
+
+## Configuration
+
+### Custom Secret Path
+
+Use a different AWS Secrets Manager path:
+
+```typescript
+const client = new TurvoClient('/custom/secret/path')
+```
+
+### Custom Secret Path for Tracking
+
+```typescript
+const tracking = await getShipmentTracking('12345', {
+  secretPath: '/custom/secret/path',
+  includeGps: true
+})
+```
+
+---
+
+## Available Status Constants
+
+```typescript
+import {
+  TURVO_SHIPMENT_STATUS_AT_PICKUP,
+  TURVO_SHIPMENT_STATUS_PICKED_UP,
+  TURVO_SHIPMENT_STATUS_EN_ROUTE,
+  TURVO_SHIPMENT_STATUS_AT_DELIVERY,
+  TURVO_SHIPMENT_STATUS_DELIVERED
+} from '@veho/turvo-sdk'
+```
+
+---
+
+## Error Handling
+
+```typescript
+import {
+  TurvoApiError,
+  TurvoNotFoundError,
+  TurvoAuthError,
+  TurvoRateLimitError
+} from '@veho/turvo-sdk'
+
+try {
+  const tracking = await getShipmentTracking('12345')
+} catch (error) {
+  if (error instanceof TurvoNotFoundError) {
+    console.error(`Shipment not found: ${error.shipmentId}`)
+  } else if (error instanceof TurvoAuthError) {
+    console.error('Authentication failed - check credentials')
+  } else if (error instanceof TurvoRateLimitError) {
+    console.error(`Rate limited. Retry after ${error.retryAfter}s`)
+  } else if (error instanceof TurvoApiError) {
+    console.error(`API error: ${error.errorCode} - ${error.errorMessage}`)
+  } else {
+    console.error('Unexpected error:', error)
+  }
+}
+```
+
+---
+
+## Type Definitions
+
+All types are fully exported:
+
+```typescript
+import type {
+  // Tracking types
+  ShipmentTracking,
+  Stop,
+  LocationUpdate,
+  GetTrackingOptions,
+
+  // Shipment types
+  TurvoShipment,
+  TurvoShipmentStatus,
+  TurvoGlobalRoute,
+  TurvoCustomerOrder,
+  TurvoCarrierOrder,
+
+  // API types
+  TurvoApiResult,
+  TurvoApiMethod,
+  TurvoCredentials,
+
+  // Error types
+  TurvoApiError,
+  TurvoNotFoundError,
+  TurvoAuthError
+} from '@veho/turvo-sdk'
+```
+
+---
+
+## Advanced Usage
+
+### Direct HTTP Client Access
+
+For operations not covered by the SDK:
+
+```typescript
+import { TurvoClient, TurvoApiMethod } from '@veho/turvo-sdk'
+
+const client = new TurvoClient()
+const httpClient = await client.getAuthenticatedClient()
+
+// Make custom API call
+const result = await httpClient.sendRequest(
+  '/custom/endpoint',
+  TurvoApiMethod.GET,
+  {
+    query: { param: 'value' },
+    headers: { 'Custom-Header': 'value' }
+  }
+)
+```
+
+### Get Raw Credentials
+
+```typescript
+const client = new TurvoClient()
+const credentials = await client.getCredentials()
+
+console.log({
+  apiKey: credentials.apiKey,
+  username: credentials.username,
+  urlBase: credentials.urlBase
+})
+```
+
+---
+
+## Rate Limiting & Retries
+
+The SDK automatically handles:
+- **Rate limiting:** 1 request per second (uses `p-throttle`)
+- **Retries:** Up to 2 retry attempts on transient failures (uses `p-retry`)
+- **Token caching:** OAuth tokens cached in memory to avoid repeated auth calls
+
+These are currently not configurable but use sensible defaults.
+
+---
+
+## Known Limitations
+
+1. **Internal API (GPS tracking):** Currently stubbed. `getShipmentTracking()` will return `hasGpsTracking: false` and `locationUpdates: null` until internal API is implemented.
+
+2. **Transformation logic:** `ShipmentTracking` response contains TODOs for computed fields like `lateBy`, `isLate`, `completedStops`. These will return placeholder values until transformation logic is completed.
+
+---
+
+## Requirements
+
+- Node.js >= 22.20.0
+- AWS credentials (for Secrets Manager access)
+
+---
+
+## License
+
+UNLICENSED - Internal Veho Technologies package

package/index.ts

@@ -0,0 +1 @@
+export * from './src'

package/lib/cjs/api/turvoInternalApi.d.ts

@@ -0,0 +1,23 @@
+import { TurvoClient } from '../client/turvoClient';
+import { LocationUpdate } from '../types/tracking';
+/**
+ * TurvoInternalApi provides access to undocumented Turvo internal APIs.
+ * ⚠️ WARNING: These APIs are not officially supported and may break without notice.
+ *
+ * Current status: STUB - All methods return null. Implementation pending.
+ */
+export declare class TurvoInternalApi {
+    private client;
+    constructor(client: TurvoClient);
+    /**
+     * GET /api/locationUpdates/
+     * Returns GPS ping history for a shipment
+     * ⚠️ Undocumented - may break
+     *
+     * @param _shipmentId - The shipment ID to fetch location updates for
+     * @returns Array of location updates, or null if not available
+     *
+     * TODO: Implement when internal API is ready
+     */
+    getLocationUpdates(shipmentId: string): Promise<LocationUpdate[] | null>;
+}

package/lib/cjs/api/turvoInternalApi.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TurvoInternalApi = void 0;
+/**
+ * TurvoInternalApi provides access to undocumented Turvo internal APIs.
+ * ⚠️ WARNING: These APIs are not officially supported and may break without notice.
+ *
+ * Current status: STUB - All methods return null. Implementation pending.
+ */
+class TurvoInternalApi {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * GET /api/locationUpdates/
+     * Returns GPS ping history for a shipment
+     * ⚠️ Undocumented - may break
+     *
+     * @param _shipmentId - The shipment ID to fetch location updates for
+     * @returns Array of location updates, or null if not available
+     *
+     * TODO: Implement when internal API is ready
+     */
+    async getLocationUpdates(shipmentId) {
+        // Stub implementation - will use this.client and shipmentId when ready
+        void this.client;
+        void shipmentId;
+        // TODO: Implement internal API call
+        // const httpClient = await this.client.getAuthenticatedClient()
+        // return httpClient.sendRequest('/api/locationUpdates/...', ...)
+        return null;
+    }
+}
+exports.TurvoInternalApi = TurvoInternalApi;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHVydm9JbnRlcm5hbEFwaS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9hcGkvdHVydm9JbnRlcm5hbEFwaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFHQTs7Ozs7R0FLRztBQUNILE1BQWEsZ0JBQWdCO0lBQ1A7SUFBcEIsWUFBb0IsTUFBbUI7UUFBbkIsV0FBTSxHQUFOLE1BQU0sQ0FBYTtJQUFHLENBQUM7SUFFM0M7Ozs7Ozs7OztPQVNHO0lBQ0gsS0FBSyxDQUFDLGtCQUFrQixDQUFDLFVBQWtCO1FBQ3pDLHVFQUF1RTtRQUN2RSxLQUFLLElBQUksQ0FBQyxNQUFNLENBQUE7UUFDaEIsS0FBSyxVQUFVLENBQUE7UUFDZixvQ0FBb0M7UUFDcEMsZ0VBQWdFO1FBQ2hFLGlFQUFpRTtRQUNqRSxPQUFPLElBQUksQ0FBQTtJQUNiLENBQUM7Q0FDRjtBQXRCRCw0Q0FzQkMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBUdXJ2b0NsaWVudCB9IGZyb20gJy4uL2NsaWVudC90dXJ2b0NsaWVudCdcbmltcG9ydCB7IExvY2F0aW9uVXBkYXRlIH0gZnJvbSAnLi4vdHlwZXMvdHJhY2tpbmcnXG5cbi8qKlxuICogVHVydm9JbnRlcm5hbEFwaSBwcm92aWRlcyBhY2Nlc3MgdG8gdW5kb2N1bWVudGVkIFR1cnZvIGludGVybmFsIEFQSXMuXG4gKiDimqDvuI8gV0FSTklORzogVGhlc2UgQVBJcyBhcmUgbm90IG9mZmljaWFsbHkgc3VwcG9ydGVkIGFuZCBtYXkgYnJlYWsgd2l0aG91dCBub3RpY2UuXG4gKlxuICogQ3VycmVudCBzdGF0dXM6IFNUVUIgLSBBbGwgbWV0aG9kcyByZXR1cm4gbnVsbC4gSW1wbGVtZW50YXRpb24gcGVuZGluZy5cbiAqL1xuZXhwb3J0IGNsYXNzIFR1cnZvSW50ZXJuYWxBcGkge1xuICBjb25zdHJ1Y3Rvcihwcml2YXRlIGNsaWVudDogVHVydm9DbGllbnQpIHt9XG5cbiAgLyoqXG4gICAqIEdFVCAvYXBpL2xvY2F0aW9uVXBkYXRlcy9cbiAgICogUmV0dXJucyBHUFMgcGluZyBoaXN0b3J5IGZvciBhIHNoaXBtZW50XG4gICAqIOKaoO+4jyBVbmRvY3VtZW50ZWQgLSBtYXkgYnJlYWtcbiAgICpcbiAgICogQHBhcmFtIF9zaGlwbWVudElkIC0gVGhlIHNoaXBtZW50IElEIHRvIGZldGNoIGxvY2F0aW9uIHVwZGF0ZXMgZm9yXG4gICAqIEByZXR1cm5zIEFycmF5IG9mIGxvY2F0aW9uIHVwZGF0ZXMsIG9yIG51bGwgaWYgbm90IGF2YWlsYWJsZVxuICAgKlxuICAgKiBUT0RPOiBJbXBsZW1lbnQgd2hlbiBpbnRlcm5hbCBBUEkgaXMgcmVhZHlcbiAgICovXG4gIGFzeW5jIGdldExvY2F0aW9uVXBkYXRlcyhzaGlwbWVudElkOiBzdHJpbmcpOiBQcm9taXNlPExvY2F0aW9uVXBkYXRlW10gfCBudWxsPiB7XG4gICAgLy8gU3R1YiBpbXBsZW1lbnRhdGlvbiAtIHdpbGwgdXNlIHRoaXMuY2xpZW50IGFuZCBzaGlwbWVudElkIHdoZW4gcmVhZHlcbiAgICB2b2lkIHRoaXMuY2xpZW50XG4gICAgdm9pZCBzaGlwbWVudElkXG4gICAgLy8gVE9ETzogSW1wbGVtZW50IGludGVybmFsIEFQSSBjYWxsXG4gICAgLy8gY29uc3QgaHR0cENsaWVudCA9IGF3YWl0IHRoaXMuY2xpZW50LmdldEF1dGhlbnRpY2F0ZWRDbGllbnQoKVxuICAgIC8vIHJldHVybiBodHRwQ2xpZW50LnNlbmRSZXF1ZXN0KCcvYXBpL2xvY2F0aW9uVXBkYXRlcy8uLi4nLCAuLi4pXG4gICAgcmV0dXJuIG51bGxcbiAgfVxufVxuIl19

package/lib/cjs/api/turvoPublicApi.d.ts

@@ -0,0 +1,99 @@
+import { TurvoClient } from '../client/turvoClient';
+import { TurvoApiResult, TurvoFilterShipmentsResultItem, TurvoPagedResult } from '../types/common';
+import { TurvoAssociateTagsApiResult, TurvoCancelShipmentApiResult, TurvoCreateShipmentApiResult, TurvoShipment, TurvoShipmentStatus, TurvoUpdateShipmentStatusApiResult } from '../types/shipment';
+/**
+ * Parameters for uploading a shipment to Turvo
+ */
+export interface UploadShipmentParams {
+    /** The formatted shipment to upload */
+    shipment: TurvoShipment;
+    /** The Load ID, solely for logging purposes */
+    vehoLoadId: string;
+}
+/**
+ * Parameters for associating tags to a shipment
+ */
+export interface AssociateTagsParams {
+    /** The shipment ID to associate tags with */
+    turvoShipmentId: number;
+    /** List of tag names to assign */
+    tags: string[];
+}
+/**
+ * Parameters for cancelling a shipment
+ */
+export interface CancelShipmentParams {
+    /** The Turvo system Shipment ID to cancel */
+    turvoShipmentId: number;
+}
+/**
+ * Parameters for updating shipment status
+ */
+export interface UpdateShipmentStatusParams {
+    /** The Turvo shipment ID */
+    turvoShipmentId: number;
+    /** The Turvo stop ID */
+    turvoStopId: number;
+    /** The status code to set */
+    turvoStatusCode: TurvoShipmentStatus;
+    /** The status date in ISO format */
+    statusDate: string;
+    /** The timezone for the status date */
+    statusTimezone: string;
+}
+/**
+ * Parameters for retrieving a shipment
+ */
+export interface GetShipmentParams {
+    /** The shipment ID to retrieve */
+    shipmentId: number;
+}
+/**
+ * Parameters for filtering shipments
+ */
+export interface FilterShipmentsParams {
+    /** Turvo location ID to filter by */
+    turvoLocationId: number;
+    /** Pickup date start filter (ISO format) */
+    pickupDateStart: string;
+    /** Optional pagination start offset */
+    start?: number;
+}
+/**
+ * TurvoPublicApi provides access to documented Turvo API endpoints.
+ * All shipment management operations (create, update, cancel, query) go through this class.
+ */
+export declare class TurvoPublicApi {
+    private client;
+    constructor(client: TurvoClient);
+    /**
+     * GET /v1/shipments/{id}
+     * Returns shipment details, stops, status
+     */
+    getShipment(params: GetShipmentParams): Promise<TurvoApiResult<TurvoShipment>>;
+    /**
+     * POST /v1/shipments
+     * Upload properly formatted shipment to Turvo
+     */
+    uploadShipment(params: UploadShipmentParams): Promise<TurvoApiResult<TurvoCreateShipmentApiResult>>;
+    /**
+     * PUT /v1/tags/attach/shipment/{id}
+     * Associate a list of tags with a shipment by ID
+     */
+    associateTagsToShipment(params: AssociateTagsParams): Promise<TurvoApiResult<TurvoAssociateTagsApiResult>>;
+    /**
+     * PUT /v1/shipments/status/{id}
+     * Set shipment status to Cancelled in Turvo
+     */
+    cancelShipment(params: CancelShipmentParams): Promise<TurvoApiResult<TurvoCancelShipmentApiResult>>;
+    /**
+     * PUT /v1/shipments/status/{id}
+     * Update shipment status at a specific stop
+     */
+    updateShipmentStatus(params: UpdateShipmentStatusParams): Promise<TurvoApiResult<TurvoUpdateShipmentStatusApiResult>>;
+    /**
+     * GET /v1/shipments/list
+     * Query shipments from Turvo with pagination support
+     */
+    filterShipments(params: FilterShipmentsParams): Promise<TurvoApiResult<TurvoPagedResult<'shipments', TurvoFilterShipmentsResultItem>>>;
+}