@adobe-commerce/aio-toolkit 1.2.5 → 1.2.7

package/README.md

@@ -312,7 +312,7 @@ OpenTelemetry integration for enterprise-grade observability with distributed tr
 - Access to current OpenTelemetry span via `ctx.telemetry` for custom instrumentation
 - `telemetry.instrument()` method for wrapping functions with automatic span creation
 - Conditional span access based on `ENABLE_TELEMETRY` flag
-- Multi-provider support (New Relic implemented, Grafana ready)
+- Multi-provider support (New Relic and Grafana LGTM implemented)
 - Graceful fallback when telemetry is not configured
 - Zero performance impact when disabled (opt-in via feature flags)
 
@@ -420,6 +420,195 @@ SELECT * FROM Log WHERE `x-adobe-commerce-request-id` = 'request-123' AND level
 SELECT count(*) FROM Log FACET `action.type` SINCE 1 hour ago
 ```
 
+---
+
+#### Grafana LGTM Telemetry
+
+The Grafana provider forwards traces, metrics, and logs to an OTLP/HTTP collector backed by the [Grafana LGTM](https://github.com/grafana/docker-otel-lgtm) all-in-one stack (**L**oki · **G**rafana · **T**empo · **M**imir). It works in two modes:
+
+| Mode | When | Collector URL |
+|---|---|---|
+| **Dev** | `GRAFANA_DEV=true` | `http://localhost:4318` (Docker image) |
+| **Deployed** | `GRAFANA_DEV` not set | `GRAFANA_ENDPOINT` (e.g. Cloudflare tunnel) |
+
+##### Dev mode — local Docker stack
+
+Start the LGTM stack with a single command:
+
+```bash
+docker run --rm -p 3000:3000 -p 4317:4317 -p 4318:4318 \
+  --name otel-lgtm \
+  grafana/otel-lgtm:latest
+```
+
+This exposes:
+
+| Port | Service |
+|---|---|
+| `3000` | Grafana UI — open `http://localhost:3000` (default credentials: `admin` / `admin`) |
+| `4317` | OTLP gRPC endpoint |
+| `4318` | OTLP HTTP endpoint (used by the toolkit) |
+
+Configure `app.config.yaml`:
+
+```yaml
+runtime-action:
+  function: actions/runtime-action/index.js
+  web: 'yes'
+  runtime: nodejs:22
+  inputs:
+    LOG_LEVEL: debug
+    ENABLE_TELEMETRY: true
+    GRAFANA_TELEMETRY: true
+    GRAFANA_DEV: true
+    GRAFANA_SERVICE_NAME: $GRAFANA_SERVICE_NAME
+  annotations:
+    require-adobe-auth: true
+    final: true
+```
+
+`.env`:
+
+```bash
+GRAFANA_SERVICE_NAME=my-app-builder-app
+```
+
+##### Deployed mode — Cloudflare tunnel
+
+Adobe I/O Runtime actions run in the cloud and cannot reach `localhost`. Expose your local LGTM stack via a [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/):
+
+```bash
+npx cloudflared tunnel --url http://localhost:4318
+# Outputs a URL like: https://abc123-def456.trycloudflare.com
+```
+
+Configure `app.config.yaml`:
+
+```yaml
+runtime-action:
+  function: actions/runtime-action/index.js
+  web: 'yes'
+  runtime: nodejs:22
+  inputs:
+    LOG_LEVEL: debug
+    ENABLE_TELEMETRY: true
+    GRAFANA_TELEMETRY: true
+    GRAFANA_ENDPOINT: $GRAFANA_ENDPOINT
+    GRAFANA_SERVICE_NAME: $GRAFANA_SERVICE_NAME
+  annotations:
+    require-adobe-auth: true
+    final: true
+```
+
+`.env`:
+
+```bash
+GRAFANA_ENDPOINT=https://abc123-def456.trycloudflare.com
+GRAFANA_SERVICE_NAME=my-app-builder-app
+```
+
+##### Usage example
+
+Telemetry is automatically initialized when you use framework action classes:
+
+```javascript
+/*
+ * <license header>
+ */
+
+const { RuntimeAction, RuntimeActionResponse, HttpMethod } = require('@adobe-commerce/aio-toolkit');
+const name = 'runtime-action';
+
+exports.main = RuntimeAction.execute(
+  name,
+  [HttpMethod.POST],
+  [],
+  ['Authorization'],
+  async (params, ctx) => {
+    const { logger, telemetry } = ctx;
+
+    logger.info({
+      message: `${name}-log`,
+      params: JSON.stringify(params),
+    });
+
+    const sampleInstrumental = telemetry.instrument(
+      `runtime.action.${name}.sampleInstrumental`,
+      async () => {
+        const span = telemetry.getCurrentSpan();
+
+        if (span) {
+          span.setAttribute('test', 'ABC');
+        }
+
+        logger.info({
+          message: `${name}-sampleInstrumental`,
+          test: 'ABC',
+        });
+
+        return 'Hello World';
+      }
+    );
+
+    const result = await sampleInstrumental();
+
+    return RuntimeActionResponse.success(result);
+  }
+);
+```
+
+##### Grafana Cloud
+
+Grafana Cloud provides a managed LGTM backend. It uses the same OTLP/HTTP protocol but requires
+HTTP Basic authentication with your stack's **Instance ID** and an **API key**.
+
+Find your OTLP endpoint and instance ID in **Grafana Cloud → Stack → OpenTelemetry**.
+
+Configure `app.config.yaml`:
+
+```yaml
+runtime-action:
+  inputs:
+    ENABLE_TELEMETRY: true
+    GRAFANA_TELEMETRY: true
+    GRAFANA_CLOUD: true
+    GRAFANA_ENDPOINT: $GRAFANA_ENDPOINT
+    GRAFANA_SERVICE_NAME: $GRAFANA_SERVICE_NAME
+    GRAFANA_INSTANCE_ID: $GRAFANA_INSTANCE_ID
+    GRAFANA_API_KEY: $GRAFANA_API_KEY
+```
+
+`.env`:
+
+```bash
+GRAFANA_ENDPOINT=https://otlp-gateway-prod-us-east-0.grafana.net/otlp
+GRAFANA_SERVICE_NAME=my-app-builder-app
+GRAFANA_INSTANCE_ID=123456
+GRAFANA_API_KEY=glc_xxx
+```
+
+##### Environment variable reference
+
+| Variable | Mode | Required | Default | Description |
+|---|---|---|---|---|
+| `ENABLE_TELEMETRY` | all | ✅ | — | Must be `true` to enable any telemetry |
+| `GRAFANA_TELEMETRY` | all | ✅ | — | Must be `true` to select the Grafana provider |
+| `GRAFANA_DEV` | dev | — | `false` | Set `true` to use `http://localhost:4318` |
+| `GRAFANA_CLOUD` | cloud | — | `false` | Set `true` to enable Grafana Cloud Basic auth |
+| `GRAFANA_ENDPOINT` | tunnel / cloud | ✅ | — | Collector base URL (not needed in dev mode) |
+| `GRAFANA_SERVICE_NAME` | tunnel / cloud | ✅ | `app-builder-app` | Service name tag (not needed in dev mode) |
+| `GRAFANA_INSTANCE_ID` | cloud | ✅ | — | Grafana Cloud stack instance ID |
+| `GRAFANA_API_KEY` | cloud | ✅ | — | Grafana Cloud API key / token |
+
+**Multi-provider fallback chain:**
+
+The toolkit tries providers in this order:
+1. **New Relic** — when `NEW_RELIC_TELEMETRY=true`
+2. **Grafana LGTM** — when `GRAFANA_TELEMETRY=true`
+3. **No telemetry** — original action runs uninstrumented
+
+---
+
 **Supported Action Classes:**
 
 Telemetry is automatically integrated with all framework action classes:
@@ -430,6 +619,97 @@ Telemetry is automatically integrated with all framework action classes:
 
 All action classes provide structured logging with automatic request ID and action type tracking.
 
+#### `LogSanitizer`
+
+Utility class that deep-clones a value and replaces sensitive field values with `"[REDACTED]"` before writing to logs. Used internally by all action classes and available for direct use.
+
+**Sensitive key detection (case-insensitive):**
+
+| Match type | Keys / patterns |
+|---|---|
+| Exact | `authorization`, `x-api-key`, `cookie`, `set-cookie` |
+| Suffix | `*_api_key`, `*_secret`, `*_token`, `*_password`, `*_key`, `*-token`, `*-secret`, `*-key` |
+
+**Constructor:**
+
+```typescript
+new LogSanitizer(
+  additionalSensitiveKeys?: ReadonlySet<string>, // extra keys to redact (lowercase)
+  maxDepth?: number                              // recursion limit, default 10
+)
+```
+
+**`LogSanitizer.parseSensitiveKeys(raw: unknown): ReadonlySet<string>`**
+
+Static helper that parses the `SENSITIVE_KEYS` runtime param into a `ReadonlySet<string>` suitable for the constructor. Accepts three input forms:
+
+| Input type | Example value | Result |
+|---|---|---|
+| Comma-separated string | `"x-merchant-token,internal_id"` | `Set { "x-merchant-token", "internal_id" }` |
+| Array | `["x-merchant-token", "INTERNAL_ID"]` | `Set { "x-merchant-token", "internal_id" }` |
+| Single string | `"x-merchant-token"` | `Set { "x-merchant-token" }` |
+| Anything else (incl. `undefined`) | — | `Set {}` (no-op) |
+
+All keys are lowercased; whitespace around commas and in array elements is trimmed; non-string array elements are silently dropped.
+
+**Automatic `SENSITIVE_KEYS` param support:**
+
+All action classes (`RuntimeAction`, `EventConsumerAction`, `OpenwhiskAction`) and `Telemetry.createLogger()` automatically call `parseSensitiveKeys(params.SENSITIVE_KEYS)` when initializing `LogSanitizer`. To extend sanitization with project-specific keys, add them to `app.config.yaml`:
+
+```yaml
+application:
+  actions:
+    my-action:
+      function: actions/my-action/index.js
+      inputs:
+        SENSITIVE_KEYS: "x-merchant-token,internal_order_id"
+```
+
+Or pass an array when testing:
+
+```typescript
+await myAction({ ...params, SENSITIVE_KEYS: ['x-merchant-token', 'internal_order_id'] });
+```
+
+**Usage:**
+
+```typescript
+const { LogSanitizer } = require('@adobe-commerce/aio-toolkit');
+
+const sanitizer = new LogSanitizer();
+
+// Sanitize HTTP headers before logging
+logger.debug({
+  message: 'Headers received',
+  headers: sanitizer.execute(params.__ow_headers || {}),
+});
+// authorization, x-api-key, cookie → "[REDACTED]"
+
+// Sanitize full action parameters (includes env-bound secrets)
+logger.debug({
+  message: 'Parameters received',
+  parameters: sanitizer.execute(params),
+});
+// MY_API_KEY, NEW_RELIC_LICENSE_KEY, GRAFANA_API_KEY → "[REDACTED]"
+
+// Extend with project-specific keys using parseSensitiveKeys
+const customSanitizer = new LogSanitizer(
+  LogSanitizer.parseSensitiveKeys(params.SENSITIVE_KEYS)
+);
+customSanitizer.execute(data);
+
+// Or construct a Set directly
+const fixedSanitizer = new LogSanitizer(new Set(['x-merchant-token', 'my_internal_secret']));
+fixedSanitizer.execute(data);
+```
+
+**Behaviour:**
+- Returns a deep copy — never mutates the input
+- Handles nested objects and arrays recursively (configurable depth limit)
+- Primitives (`string`, `number`, `boolean`, `null`, `undefined`) are returned as-is
+
+---
+
 #### `RuntimeApiGatewayService`
 Flexible Adobe I/O Runtime API Gateway client that accepts bearer tokens for authenticated requests.
 
@@ -1650,6 +1930,73 @@ if (stats.errors.length) {
 
 ---
 
+#### `AmazonSQSClient`
+Batched publisher and long-polling consumer for Amazon SQS standard and FIFO queues.
+
+**Installation**
+```bash
+npm install @aws-sdk/client-sqs
+```
+
+**Basic Usage**
+```typescript
+const { AmazonSQSClient } = require('@adobe-commerce/aio-toolkit');
+
+const client = new AmazonSQSClient({
+  region: 'us-east-1',
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  queueUrl: 'https://sqs.us-east-1.amazonaws.com/123456789/my-queue',
+});
+```
+
+**Publishing messages**
+```typescript
+const payloads = orders.map(o => JSON.stringify(o));
+const stats = await client.publish(payloads);
+
+console.log(`published=${stats.published} failed=${stats.failed}`);
+if (stats.errors.length) {
+  console.error('Failed payloads:', stats.errors);
+}
+```
+
+**Publishing to a FIFO queue**
+```typescript
+const fifoClient = new AmazonSQSClient({
+  region: 'us-east-1',
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  queueUrl: 'https://sqs.us-east-1.amazonaws.com/123456789/my-queue.fifo',
+  messageGroupId: 'order-processing',         // required for FIFO
+  messageDeduplicationId: 'unique-batch-id',  // optional — omit to use content-based dedup
+});
+
+const stats = await fifoClient.publish(payloads);
+```
+
+**Consuming messages**
+```typescript
+const stats = await client.consume(
+  { batchSize: 10, waitTimeSeconds: 20 }, // long polling
+  async (message) => {
+    const order = JSON.parse(message.body);
+    await processOrder(order);
+  }
+);
+
+console.log(`consumed=${stats.consumed} acked=${stats.acked} failed=${stats.failed}`);
+```
+
+**API Reference**
+
+| Method | Description | Returns |
+|---|---|---|
+| `publish(payloads)` | Sends each payload as an SQS message; FIFO queues include group/dedup IDs | `Promise<PublishStats>` |
+| `consume(options, handler)` | Long-polls the queue, invokes `handler` for each message, auto-deletes on success | `Promise<ConsumeStats>` |
+
+---
+
 #### `InfiniteLoopBreaker`
 Detect and prevent infinite loops in event-driven applications.
 
@@ -2118,6 +2465,108 @@ deployment:
 3. **CI/CD Integration**: Automate event configuration in deployment pipelines
 4. **Multi-Environment Setup**: Use different config files for dev/staging/production environments
 
+#### `aio-toolkit-cli-workflow`
+
+Command-line tool for orchestrating Adobe I/O CLI workflows in your App Builder projects. This CLI acts as a wrapper around the `aio` CLI to streamline environment setup, resets, and cron rule management via interactive prompts.
+
+> **Prerequisite:** The `aio` CLI must be installed. If it is missing, the command will detect this at startup and print installation instructions pointing to the [Adobe App Builder CLI install guide](https://developer.adobe.com/app-builder/docs/guides/runtime_guides/tools/cli-install).
+
+##### Commands
+
+###### `env:setup`
+Interactively configure the AIO Console environment (org → project → workspace).
+
+```bash
+npx aio-toolkit-cli-workflow env:setup
+
+# Skip the interactive prompt and use a specific workspace config file
+npx aio-toolkit-cli-workflow env:setup --config-file ./path/to/.aio
+```
+
+**Flow without `--config-file`:**
+1. Prompts "Do you have a workspace config file?" (yes/no).
+2. If **yes** — prompts for the file path and runs `aio app use <file>`.
+3. If **no** — runs `aio console org select` → `aio console project select` → `aio console workspace select` interactively.
+
+###### `env:reset`
+Fully reset the AIO CLI environment and re-authenticate.
+
+```bash
+# Reset for production (default)
+npx aio-toolkit-cli-workflow env:reset
+
+# Reset for staging
+npx aio-toolkit-cli-workflow env:reset --env stage
+```
+
+**Steps performed:**
+1. `aio auth logout`
+2. `aio config clear -f` (local) + `aio config clear -g -f` (global)
+3. `aio telemetry off`
+4. `aio config set cli.env <stage|prod>`
+5. `aio auth login`
+6. `aio telemetry on`
+
+After reset, verify with `aio config get cli.env` and `aio console where`.
+
+###### `cron:status`
+Display the status of all AIO Runtime cron rules in the current workspace.
+
+```bash
+# List all cron rules
+npx aio-toolkit-cli-workflow cron:status
+
+# Inspect a single rule by name
+npx aio-toolkit-cli-workflow cron:status --name myRuleName
+```
+
+**Output per rule:** rule name, status (active/inactive), action name, action path, publish status, trigger name, cron schedule, version.
+
+###### `cron:enable`
+Enable AIO Runtime cron rules interactively.
+
+```bash
+# Interactive rule selection
+npx aio-toolkit-cli-workflow cron:enable
+
+# Enable all rules without prompting
+npx aio-toolkit-cli-workflow cron:enable --all
+```
+
+###### `cron:disable`
+Disable AIO Runtime cron rules interactively.
+
+```bash
+# Interactive rule selection
+npx aio-toolkit-cli-workflow cron:disable
+
+# Disable all rules without prompting
+npx aio-toolkit-cli-workflow cron:disable --all
+```
+
+###### `cron:delete`
+Delete AIO Runtime cron rules and their associated triggers.
+
+```bash
+npx aio-toolkit-cli-workflow cron:delete
+```
+
+Confirms the workspace, lists all rules (with trigger names), and prompts for one or more rule numbers to delete. For each selected rule the associated trigger is deleted first (`aio rt trigger delete`) and then the rule (`aio rt rule delete`).
+
+###### `help`
+Displays help information for the CLI.
+
+```bash
+npx aio-toolkit-cli-workflow help
+```
+
+##### Use Cases
+
+1. **First-time setup**: Run `env:setup` to select org, project, and workspace in one step.
+2. **Environment switching**: Run `env:reset --env stage` or `env:reset --env prod` to cleanly switch AIO CLI environments.
+3. **Cron management**: Use `cron:status` to audit schedules, then `cron:enable` / `cron:disable` to control them without memorising `aio rt` commands.
+4. **Rule cleanup**: Use `cron:delete` to remove stale rules and their triggers together.
+
 ## Environment Variables
 
 Common environment variables used across components: