@adobe-commerce/aio-toolkit 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.1] - 2026-03-28
+
+### 🐛 Bug Fixes
+
+- **Fixed `ERESOLVE` installation failures introduced in v1.1.0**
+  - `v1.1.0` moved `cloudevents`, `dotenv`, `node-fetch`, and `openwhisk` to `peerDependencies` to avoid duplicate module installs
+  - This caused hard `ERESOLVE` errors for any client that had one of those packages installed at a different major version (e.g. `cloudevents@4.x` vs the required `>=8.0.0`)
+  - Root cause: `peerDependenciesMeta.optional: true` only suppresses the "not installed" warning — it does **not** suppress `ERESOLVE` when the package IS installed at an incompatible version
+  - Fix: moved these four packages back to `dependencies` where they belong
+
+### 🔧 Dependency Changes
+
+| Package | v1.1.0 | v1.1.1 | Reason |
+|---|---|---|---|
+| `cloudevents` | `peerDependencies` (optional) | `dependencies` | Clients have v4.x — incompatible with `>=8.0.0` range; duplicate copies harmless (stateless) |
+| `dotenv` | `peerDependencies` (optional) | `dependencies` | Stateless — just sets `process.env`; two copies are harmless |
+| `node-fetch` | `peerDependencies` (optional) | `dependencies` | Stateless HTTP function — no singleton, no shared state |
+| `openwhisk` | `peerDependencies` (optional) | `dependencies` | Creates client instances per call — no global singleton |
+
+### 📝 Peer Dependency Philosophy
+
+Only packages that maintain **shared singleton state** between the toolkit and the client application belong in `peerDependencies`. Stateless utilities where duplicate copies are functionally harmless must stay in `dependencies` to avoid blocking installation.
+
+Packages that remain in `peerDependencies` as **required** peers (all five are unconditionally imported at package load time):
+
+| Package | Why it must be a peer dep |
+|---|---|
+| `@adobe/aio-sdk` | Singleton services — logger, config, state shared across the app |
+| `graphql` | Schema registry singleton — two copies cause `instanceof` and type failures |
+| `@adobe/aio-lib-ims` | Token cache and auth context must be a single shared instance |
+| `@adobe/aio-lib-telemetry` | Single telemetry pipeline — two copies split traces and logs |
+| `@opentelemetry/resources` | Resource object tied to the telemetry pipeline instance |
+
+### 💡 Migration Guide
+
+```bash
+# Upgrade from v1.1.0 — no code changes required
+npm install @adobe-commerce/aio-toolkit@1.1.1
+```
+
+---
+
 ## [1.1.0] - 2026-03-27
 
 ### ⚠️ Breaking Changes

package/README.md

@@ -7,9 +7,16 @@ A comprehensive TypeScript toolkit for Adobe App Builder applications providing
 ## Installation
 
 ```bash
-npm install @adobe-commerce/aio-toolkit
+npm install @adobe-commerce/aio-toolkit \
+  @adobe/aio-sdk \
+  @adobe/aio-lib-ims \
+  @adobe/aio-lib-telemetry \
+  @opentelemetry/resources \
+  graphql
 ```
 
+> **App Builder projects** already include `@adobe/aio-sdk`, `@adobe/aio-lib-ims`, and `graphql` — you only need to add the missing ones. See [Dependency Resolution](#dependency-resolution) for details.
+
 ## Usage
 
 The toolkit is organized into five main modules:
@@ -1744,6 +1751,105 @@ COMMERCE_ACCESS_TOKEN=commerce-access-token
 COMMERCE_ACCESS_TOKEN_SECRET=commerce-access-token-secret
 ```
 
+## Dependency Resolution
+
+This toolkit carefully manages its dependency tree to avoid conflicts with packages already installed in your App Builder project.
+
+### How dependencies are split
+
+#### `dependencies` — bundled with the toolkit
+
+Packages installed directly by the toolkit that are either unique to it, or are stateless utilities where having two copies causes no functional harm:
+
+| Package | Reason |
+|---|---|
+| `@adobe-commerce/aio-services-kit` | Companion package — not used by client projects directly |
+| `cloudevents` | Stateless event constructor — duplicate copies are harmless |
+| `dotenv` | Stateless — only sets `process.env`; two copies are harmless |
+| `got` | Internal HTTP client for Commerce API — not exposed externally |
+| `node-fetch` | Stateless HTTP function — no shared state |
+| `oauth-1.0a` | Internal OAuth 1.0a request signing — not exposed externally |
+| `openwhisk` | Creates client instances per call — no global singleton |
+| `uuid` | Pure stateless function — no conflict possible |
+| `yaml` | Stateless YAML parser — no shared state |
+
+#### `peerDependencies` — must use your project's copy
+
+Packages that maintain **singleton state or shared registries** — if two copies exist (one in the toolkit, one in your project), they behave as separate instances which breaks shared behaviour:
+
+| Package | Why it must be shared |
+|---|---|
+| `@adobe/aio-sdk` | Singleton services — logger, config, state are shared across the app |
+| `graphql` | Schema registry is a singleton — `instanceof GraphQLSchema` and type checks fail with two copies |
+| `@adobe/aio-lib-ims` | Token cache and auth context must be the same shared instance |
+| `@adobe/aio-lib-telemetry` | Single telemetry pipeline — two copies split traces and logs |
+| `@opentelemetry/resources` | Resource object tied to the telemetry pipeline instance |
+
+All five are **required** — they are unconditionally imported when the package loads (`export * from './framework'` and `export * from './commerce'` in the root `index.ts`). If any is missing, the entire package will fail to load with a `Cannot find module` error.
+
+### Installing peer dependencies
+
+Install the toolkit and all required peer dependencies in one command:
+
+```bash
+npm install @adobe-commerce/aio-toolkit \
+  @adobe/aio-sdk \
+  @adobe/aio-lib-ims \
+  @adobe/aio-lib-telemetry \
+  @opentelemetry/resources \
+  graphql
+```
+
+Or individually if you prefer to control versions:
+
+```bash
+npm install @adobe-commerce/aio-toolkit
+
+# Required peer dependencies
+npm install @adobe/aio-sdk@^5.0.0
+npm install @adobe/aio-lib-ims@^7.0.0
+npm install @adobe/aio-lib-telemetry@^1.0.0
+npm install @opentelemetry/resources@^2.0.0
+npm install graphql@^16.0.0
+```
+
+> **Note for App Builder projects:** `@adobe/aio-sdk`, `graphql`, and `@adobe/aio-lib-ims` are almost always already present in a standard App Builder project. Run `npm list @adobe/aio-sdk graphql @adobe/aio-lib-ims` to check before installing.
+
+### Resolving `ERESOLVE` errors
+
+If you see an `ERESOLVE` error when installing, it means one of the required peer dependencies is installed in your project at a version outside the supported range.
+
+**Check which peer dep is conflicting:**
+
+```bash
+npm install @adobe-commerce/aio-toolkit 2>&1 | grep "Found:"
+```
+
+**Upgrade the conflicting package to a compatible version:**
+
+```bash
+# @adobe/aio-sdk must be >=5.0.0
+npm install @adobe/aio-sdk@latest
+
+# graphql must be >=14.0.0
+npm install graphql@latest
+
+# @adobe/aio-lib-ims must be >=7.0.0
+npm install @adobe/aio-lib-ims@latest
+
+# @adobe/aio-lib-telemetry must be >=1.0.0
+npm install @adobe/aio-lib-telemetry@latest
+
+# @opentelemetry/resources must be >=2.0.0
+npm install @opentelemetry/resources@latest
+```
+
+If upgrading is not immediately possible, you can bypass the check with `--legacy-peer-deps` (not recommended for production):
+
+```bash
+npm install @adobe-commerce/aio-toolkit --legacy-peer-deps
+```
+
 ## License
 
 See the LICENSE file (in package) for license rights and limitations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe-commerce/aio-toolkit",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "A comprehensive TypeScript toolkit for Adobe App Builder applications providing standardized Adobe Commerce integrations, I/O Events orchestration, file storage utilities, authentication helpers, and robust backend development tools with 100% test coverage.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -60,8 +60,12 @@
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
     "@adobe-commerce/aio-services-kit": "^1.0.0",
+    "cloudevents": "^8.0.2",
+    "dotenv": "^17.3.1",
     "got": "^11.8.6",
+    "node-fetch": "^2.7.0",
     "oauth-1.0a": "^2.2.6",
+    "openwhisk": "^3.21.8",
     "uuid": "^10.0.0",
     "yaml": "^2.0.0"
   },
@@ -85,8 +89,6 @@
     "@types/uuid": "^10.0.0",
     "@typescript-eslint/eslint-plugin": "^6.13.0",
     "@typescript-eslint/parser": "^6.13.0",
-    "cloudevents": "^8.0.2",
-    "dotenv": "^17.3.1",
     "eslint": "^8.55.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-prettier": "^5.0.1",
@@ -94,8 +96,6 @@
     "husky": "^9.1.7",
     "jest": "^30.1.3",
     "lint-staged": "^16.1.6",
-    "node-fetch": "^2.7.0",
-    "openwhisk": "^3.21.8",
     "prettier": "^3.1.0",
     "ts-jest": "^29.4.1",
     "tsup": "^8.5.0",
@@ -106,36 +106,9 @@
     "@adobe/aio-lib-telemetry": ">=1.0.0",
     "@adobe/aio-sdk": ">=5.0.0",
     "@opentelemetry/resources": ">=2.0.0",
-    "cloudevents": ">=8.0.0",
-    "dotenv": ">=16.0.0",
-    "graphql": ">=16.0.0",
-    "node-fetch": ">=2.6.0",
-    "openwhisk": ">=3.0.0",
+    "graphql": ">=14.0.0",
     "typescript": ">=4.9.0"
   },
-  "peerDependenciesMeta": {
-    "@adobe/aio-lib-ims": {
-      "optional": true
-    },
-    "@adobe/aio-lib-telemetry": {
-      "optional": true
-    },
-    "@opentelemetry/resources": {
-      "optional": true
-    },
-    "cloudevents": {
-      "optional": true
-    },
-    "dotenv": {
-      "optional": true
-    },
-    "node-fetch": {
-      "optional": true
-    },
-    "openwhisk": {
-      "optional": true
-    }
-  },
   "engines": {
     "node": ">=18.0.0"
   },