@adobe-commerce/aio-toolkit 1.0.18 → 1.1.1

package/CHANGELOG.md

@@ -5,6 +5,111 @@ 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
+
+- **Peer dependency restructuring to resolve duplicate module conflicts**
+  - The following packages have been moved from `dependencies` to `peerDependencies`:
+    - `@adobe/aio-sdk` (>=5.0.0) — required peer
+    - `graphql` (>=16.0.0) — required peer
+    - `@adobe/aio-lib-ims` (>=7.0.0) — optional peer
+    - `@adobe/aio-lib-telemetry` (>=1.0.0) — optional peer
+    - `cloudevents` (>=8.0.0) — optional peer
+    - `dotenv` (>=16.0.0) — optional peer
+    - `node-fetch` (>=2.6.0) — optional peer
+    - `openwhisk` (>=3.0.0) — optional peer
+    - `@opentelemetry/resources` (>=1.0.0) — optional peer
+  - App Builder projects already have these packages installed — no additional installs required for the vast majority of users
+  - If you get `Cannot find module` errors after upgrading, install the missing package directly in your project
+
+### 🐛 Bug Fixes
+
+- **Fixed missing `yaml` dependency**
+  - `yaml` was used at runtime in `OnboardConfig` (YAML config file parsing) but was not declared in `package.json`
+  - This was relying on a transitive install which is fragile and unreliable across package managers
+  - `yaml: ^2.0.0` is now a proper direct `dependency`
+
+### 🔧 Dependency Changes
+
+| Package | Before | After | Reason |
+|---|---|---|---|
+| `@adobe/aio-sdk` | `dependencies` | `peerDependencies` | Singleton services break with duplicate instances |
+| `@adobe/aio-lib-ims` | `dependencies` | `peerDependencies` (optional) | Shared auth token context |
+| `@adobe/aio-lib-telemetry` | `dependencies` | `peerDependencies` (optional) | Shared telemetry pipeline |
+| `graphql` | `dependencies` | `peerDependencies` | Schema singleton — two copies cause type incompatibility |
+| `cloudevents` | `dependencies` | `peerDependencies` (optional) | App Builder I/O Events projects always install this |
+| `dotenv` | `dependencies` | `peerDependencies` (optional) | Every App Builder project loads `.env` files |
+| `node-fetch` | `dependencies` | `peerDependencies` (optional) | Common fetch polyfill; v2/v3 split causes conflicts |
+| `openwhisk` | `dependencies` | `peerDependencies` (optional) | App Builder Runtime projects always install this |
+| `@opentelemetry/resources` | *(missing)* | `peerDependencies` (optional) | Runtime import in telemetry code; provided by `aio-lib-telemetry` |
+| `yaml` | *(missing)* | `dependencies` | Runtime import in `OnboardConfig` — was undeclared |
+| `got` | `dependencies` | `dependencies` | Internal HTTP client — kept as direct dep |
+| `oauth-1.0a` | `dependencies` | `dependencies` | Internal OAuth signing — kept as direct dep |
+| `uuid` | `dependencies` | `dependencies` | Stateless, no conflict risk — kept as direct dep |
+
+### 💡 Migration Guide
+
+Most App Builder projects already have all moved packages installed and **require no changes**:
+
+```bash
+# Standard upgrade — works for most users
+npm install @adobe-commerce/aio-toolkit@1.1.0
+```
+
+If you encounter `Cannot find module` errors for any of the optional peer dependencies, install them explicitly:
+
+```bash
+# Install only the ones you use
+npm install @adobe/aio-sdk graphql dotenv
+npm install cloudevents node-fetch openwhisk   # if used
+npm install @adobe/aio-lib-ims @adobe/aio-lib-telemetry  # if used
+```
+
+---
+
 ## [1.0.18] - 2026-03-03
 
 ### 🔒 Security Fixes

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.