diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c00587986..0f95f69f2 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -15,10 +15,16 @@ jobs: with: node-version: 26 registry-url: 'https://registry.npmjs.org' - - name: Publish Package + - name: Publish Stable Package + if: ${{ github.event_name == 'workflow_dispatch' || !github.event.release.prerelease }} run: EASYPOST_TEST_API_KEY=123 EASYPOST_PROD_API_KEY=123 just install install-styleguide publish env: NODE_AUTH_TOKEN: ${{ secrets.NPM_API_KEY }} + - name: Publish Release Candidate Package + if: ${{ github.event_name == 'release' && github.event.release.prerelease }} + run: EASYPOST_TEST_API_KEY=123 EASYPOST_PROD_API_KEY=123 just install install-styleguide publish-next + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_API_KEY }} - name: Upload assets to release uses: AButler/upload-release-assets@v3.0.1 with: diff --git a/CHANGELOG.md b/CHANGELOG.md index f877dd94b..776ade4ce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,9 @@ # CHANGELOG -## v9.0.0 (Unreleased) +## v9.0.0-rc.1 (2026-09-08) - Breaking: Node 18+ is now required (built-in `fetch`) -- Breaking: API resource responses are now plain JSON-compatible objects rather than model class instances +- Breaking: API resource responses are now plain JSON-compatible objects rather than model class instances (better serializer and SSR compatibility) - Breaking: HTTP transport migrated from `superagent` to fetch-compatible transport - `superagent` runtime dependency removed - Breaking: `superagentMiddleware` renamed to `httpMiddleware` @@ -11,9 +11,10 @@ - Breaking: `makeApiCall` now accepts `delete` (the `del` alias was removed) - `requestMiddleware` compatibility preserved using a fetch-era compatibility request object - Default `User-Agent` retains structured runtime metadata fields (`Nodejs/`, `OS/`, `OSVersion/`, `OSArch/`) via runtime-safe detection -- TypeScript declarations are now generated from source and published from `dist/types`. -- Internal root `types/` declaration sources and demo fixtures were removed from the repository. -- Calling `retrieveStatelessRates` now returns the entire response and not only the `rates` key, allowing errors and other useful information to be exposed. Note that you will now need to reference the `rates` key to get the returned rates +- Breaking: Project migrated from JavaScript to TypeScript. Type declarations are now generated from source and published from `dist/types`. Although efforts were made to retain existing types, some required or accidental type changes may still exist, so verify compatibility in your codebase. + - Breaking: For consistency with other EasyPost client libraries, parameters and model properties are now generally typed as optional. + - Breaking: Internal root `types/` declaration sources and demo fixtures were removed from the repository. +- Breaking: `retrieveStatelessRates` now returns the full response rather than only the `rates` key. Read rates from `response.rates`. ## v8.9.0 (2026-06-25) diff --git a/README.md b/README.md index 0b6088488..fe042bcc4 100644 --- a/README.md +++ b/README.md @@ -209,6 +209,7 @@ No consumer configuration changes are required when importing `@easypost/api` fr - Predefined packages (see [Carrier Metadata](https://docs.easypost.com/docs/carrier-metadata) in our docs for more details) - Carrier service levels (see [Carrier Metadata](https://docs.easypost.com/docs/carrier-metadata) in our docs for more details) - Carrier list (see [Carrier Types](https://docs.easypost.com/docs/carrier-types) in our docs for more details) +- We do not require parameters or properties comprehensively in this library. See our documentation for more details on what is required per request ### Testing diff --git a/UPGRADE_GUIDE.md b/UPGRADE_GUIDE.md index 1f94c7705..b65ab5c71 100644 --- a/UPGRADE_GUIDE.md +++ b/UPGRADE_GUIDE.md @@ -2,8 +2,8 @@ Use the following guide to assist in the upgrade process of the `easypost-node` library between major versions. -- [Upgrading from 7.x to 8.0](#upgrading-from-7x-to-80) - [Upgrading from 8.x to 9.0](#upgrading-from-8x-to-90) +- [Upgrading from 7.x to 8.0](#upgrading-from-7x-to-80) - [Upgrading from 6.x to 7.0](#upgrading-from-6x-to-70) - [Upgrading from 5.x to 6.0](#upgrading-from-5x-to-60) - [Upgrading from 4.x to 5.0](#upgrading-from-4x-to-50) @@ -16,17 +16,33 @@ Use the following guide to assist in the upgrade process of the `easypost-node` - [Response Objects Are Now Plain JSON Objects](#90-response-objects-are-now-plain-json-objects) - [HTTP Transport Migrated to Fetch](#90-http-transport-migrated-to-fetch) +### 9.0 Medium Impact Changes + +- [Type Optionality Was Relaxed](#90-type-optionality-was-relaxed) +- [retrieveStatelessRates Returns the Full Response](#90-retrievestatelessrates-returns-the-full-response) + ### 9.0 Low Impact Changes - [Type Declarations Are Source-Generated](#90-type-declarations-are-source-generated) +### 9.0 Migration Checklist + +Use this checklist before shipping your upgrade: + +- 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 Response Objects Are Now Plain JSON Objects Likelihood of Impact: **High** API responses are now returned as plain JSON-compatible objects instead of model class instances. -Instance helper methods such as `shipment.lowestRate()` remain available on returned objects: +Helper methods such as `shipment.lowestRate()` remain available on returned objects where applicable: ```javascript const shipment = await client.Shipment.create({ ... }); @@ -34,6 +50,7 @@ const boughtShipment = await client.Shipment.buy(shipment.id, shipment.lowestRat ``` This change improves compatibility with serializers and SSR frameworks that require plain objects. +Compatibility note: helper methods and `instanceof` model checks are preserved for returned objects. ### 9.0 HTTP Transport Migrated to Fetch @@ -52,7 +69,7 @@ What changed: - Node 18+ is now required (built-in `fetch`). - `superagentMiddleware` has been removed and replaced by `httpMiddleware`. - `agent` has been renamed to `httpClient`. -- `makeApiCall` now uses `delete` only (the `del` alias was removed). +- `makeApiCall` now accepts `delete` only (the `del` alias was removed). - Middleware relying on superagent-only request internals (private properties or plugin APIs) must be updated. - The default `User-Agent` retains the prior structured format (`Nodejs/`, `OS/`, `OSVersion/`, `OSArch/`) while collecting values in a runtime-safe way. @@ -71,12 +88,39 @@ const client = new EasyPostClient('api_key', { await client.makeApiCall('delete', '/trackers/trk_123'); ``` +### 9.0 Type Optionality Was Relaxed + +Likelihood of Impact: **Medium** + +For consistency with other EasyPost client libraries, many request parameters and model properties are now typed as optional. + +If your project depended on stricter compile-time requiredness from previous declarations, add local validation or runtime guards where needed. + +### 9.0 retrieveStatelessRates Returns the Full Response + +Likelihood of Impact: **Medium** + +`retrieveStatelessRates` now returns the full API response, not only the `rates` value. + +Before: + +```javascript +const rates = await client.BetaRate.retrieveStatelessRates(params); +``` + +After: + +```javascript +const response = await client.BetaRate.retrieveStatelessRates(params); +const rates = response.rates; +``` + ### 9.0 Type Declarations Are Source-Generated Likelihood of Impact: **Low** Type declarations are generated from source and published from `dist/types`. -Package-root imports are unchanged. If you were importing internal files from the old root `types/` folder, migrate to package-root imports. +Package-root imports are unchanged. If you were importing internal files from the root `types/` folder, migrate to package-root imports. ## Upgrading from 7.x to 8.0 diff --git a/package-lock.json b/package-lock.json index 414973890..25c6e6ec0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@easypost/api", - "version": "8.9.0", + "version": "9.0.0-rc.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@easypost/api", - "version": "8.9.0", + "version": "9.0.0-rc.1", "license": "MIT", "dependencies": { "uuid": "^11.1.0" diff --git a/package.json b/package.json index f32de1edb..f3b849495 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@easypost/api", "description": "EasyPost Node Client Library", - "version": "8.9.0", + "version": "9.0.0-rc.1", "author": "Easypost Engineering ", "homepage": "https://easypost.com", "exports": {