EasyPost Node Client Library

When upgrading to version 9.0, several high-impact changes affect how data is received and how the HTTP transport layer operates.

Response Objects

Response objects are now plain JSON objects. This change affects how you parse and interact with the data returned from the API.

HTTP Transport

The HTTP transport layer has migrated to fetch. Ensure your environment supports fetch or provides a polyfill if running in older Node.js versions.

Type Optionality

Type optionality has been relaxed, meaning certain fields that were previously optional in TypeScript definitions may now be required to ensure type safety and alignment with the API.

retrieveStatelessRates Behavior

The retrieveStatelessRates method now returns the full response object rather than a subset of the data.

Type Declarations

Type declarations are now source-generated, which may affect how you extend or reference types in your own TypeScript code.

Upgrading to version 9.0 involves several high and medium impact changes, primarily due to a shift in how API responses are structured and how HTTP requests are handled.

Key Changes

• Response Objects: API responses are now plain JSON-compatible objects instead of model class instances. While helper methods like shipment.lowestRate() are preserved on these objects, instanceof model checks may no longer work as expected.
• HTTP Transport: The library has migrated from superagent to fetch. This requires Node 18+.
• Method Renaming: agent is now httpClient, and superagentMiddleware is replaced by httpMiddleware.
• API Call Aliases: The del alias for makeApiCall has been removed; use delete instead.
• Stateless Rates: retrieveStatelessRates now returns the full response object. You must access the rates via response.rates.

### 9.0 Migration Checklist
- Ensure runtime is Node 18+.
- Replace `superagentMiddleware` with `httpMiddleware`.
- Replace `agent` with `httpClient`.
- Replace `makeApiCall('del', ...)` with `makeApiCall('delete', ...)`.
- If you use `retrieveStatelessRates`, read rates from `response.rates`.
- If you import from internal `types/` paths, migrate to package-root imports.

### 9.0 HTTP Transport Migration Example
```javascript
// After
const client = new EasyPostClient('api_key', {
  httpMiddleware: (httpFn) => httpFn,
  httpClient: fetch,
});

9.0 retrieveStatelessRates Usage

// Before
const rates = await client.BetaRate.retrieveStatelessRates(params);

// After
const response = await client.BetaRate.retrieveStatelessRates(params);
const rates = response.rates;

Note that v6 is deprecated. This version introduced significant architectural changes to how objects are managed and how errors are handled.

Key Changes

• Node Requirement: Requires Node 12+.
• Service-Based Pattern: Instance methods like .save(), .delete(), and .buy() have been removed. You must now call these methods against a service (e.g., client.Parcel.create()) and pass the object ID where necessary.
• Async Methods: All functions attached to a service are now asynchronous and must be awaited.
• Error Handling: A new hierarchy of ~24 error types has been introduced, categorized into ApiError (for API-related issues like invalid_request_error or rate_limit_error) and EasyPostError (for library-level issues like invalid_parameter_error).
• Report Creation: The type parameter for Reports is now nested inside the params object.

// 6.0 New approach (create/update called against a service)
const client = new Easypost(process.env.EASYPOST_API_KEY);
const parcel = await client.Parcel.create({
  length: 20.2,
  width: 10.9,
  height: 5,
  weight: 65.9,
});

// 6.0 New approach (buy function called against the Shipment service)
const client = new Easypost(process.env.EASYPOST_API_KEY);
const shipment = await client.Shipment.retrieve('shp_123...');
const boughtShipment = client.Shipment.buy(shipment.id, shipment.lowestRate());

// 6.0 New approach (Report creation with nested type)
const report = await client.Report.create({ type: 'payment_log', more_params: 'here' });

When instantiating EasyPostClient, you can provide an options object to customize the client behavior. Supported options include:

• timeout: Time in milliseconds before a request fails.
• baseUrl: The base URL for API requests (useful for proxying).
• useProxy: If true, disables using the API key (useful when proxying from a frontend through a server).
• httpMiddleware: A function that wraps the underlying HTTP transport function.
• httpClient: The function used for HTTP requests. Defaults to built-in fetch (Node 18+).
• requestMiddleware: A function that takes a compatibility request object and returns it. Supports patterns using auth, query, and send.

const client = new EasyPostClient(process.env.EASYPOST_API_KEY, {
  timeout: 120000,
  baseUrl: 'https://api.easypost.com/v2/',
  useProxy: false,
  httpMiddleware: (f) => f,
  httpClient: fetch,
  requestMiddleware: (r) => r,
});