feat(llmo-akamai): CUSTOM-default OAE onboarding (PUT deploy + caching/scope gates)

[ABHA61]

What

Reworks the Akamai "Optimize at Edge" (BYOCDN) onboarding for CUSTOM-default properties.

Rule builder (llmo-akamai-utils.js)

• Wildcard the UA match values (*GPTBot*) so they match real agent strings, not only an exact GPTBot.
• Add a Caching behavior (Honor origin Cache-Control + Expires) to the OAE rule only when the property's default rule has none; cacheId is always present.
• Append the managed "Optimize at Edge" wrapper last so its origin + cacheId win (Akamai evaluates siblings top-down, last match wins).
• OAE origin host comes from env.EDGE_OPTIMIZE_EDGE_DOMAIN (dev/stage/live.edgeoptimize.net; defaults to live); matchSan (*.edgeoptimize.net) covers all three.

Controller (llmo-akamai.js)

• deploy/plan: JSON-Patch → full-tree PUT (updateRuleTree, pinned ruleFormat; plan uses the client's dryRun).
• Scope gate: reject a non-CUSTOM default origin (400) before creating a version (no orphan version).
• Optional baseVersion (copy from a specific version; rejects 0); caller email in the activation note.
• Activation resilience: the PAPI activation POST frequently exceeds the client request timeout on large trees (and a retry then returns 422 already-activated) — in both cases Akamai has already queued the activation, so activate recovers by reporting the in-flight/active activation for the same version+network instead of a false failure.

Why

Validated end-to-end on tokowaka-aem.stage.adobe.com: an OAE-rule Caching behavior on a property that (correctly) defaults HTML to no-store overrides it and makes the optimized path cacheable, so Akamai replays a stale/passthrough copy to bots (v40 = 0/20 optimized at IAD). Conditional caching + full-tree PUT + the CUSTOM scope gate + append-last ordering fix it — AI bots receive x-edgeoptimize-request-id + no-store, humans pass through.

Design

High-Level Design: Optimize at Edge — Akamai BYOCDN Automation (HLD)

Depends on

adobe/spacecat-shared#1825 (merged, released as @adobe/spacecat-shared-akamai-client@1.2.0) — defaultRuleHasCaching, getDefaultOriginSsl, updateRuleTree({ dryRun }). package.json now pins the published 1.2.0.

Testing

Controller + utils unit tests green, lint clean, OpenAPI updated + valid.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

This PR will trigger a minor release when merged.

[MysticatBot]

Hey @ABHA61,

Verdict: Request changes - gist tarball dependency must be swapped before merge; baseVersion validation gap should be fixed.
Complexity: HIGH - medium diff with supply-chain pin, API surface changes, and multiple behavioral shifts.
Changes: Reworks Akamai OAE onboarding to use full-tree PUT with CUSTOM-default scope gate, conditional caching, activation recovery, and optional baseVersion (7 files).
Note: CI checks are currently failing - resolve before merge.

Must fix before merge

1. [Critical] Supply chain risk - Gist tarball dependency - package.json:86

   @adobe/spacecat-shared-akamai-client resolves from a personal Gist URL rather than the npm registry. The Gist owner can modify or delete the content; there is no independent provenance verification that the tarball matches the source in spacecat-shared PR 1825. The PR description acknowledges this is temporary, but this must NOT be merged in this state. Gate merge on the upstream package publishing.

2. [Important] baseVersion validation accepts 0 - src/controllers/llmo/llmo-akamai.js:592

   DECIMAL_INT_RE is /^[0-9]+$/ which matches "0". After Number("0"), the code passes version 0 to client.getRuleTree(propertyId, 0, ...). PAPI property versions start at 1, so this produces an opaque 404/500 rather than the intended clean 400. Fix: add if (Number(rawBaseVersion) < 1) return badRequest(...) after the regex check, mirroring the activate handler pattern.

3. [Important] Activation recovery fires on any exception - src/controllers/llmo/llmo-akamai.js:780

   The recovery block fires on any exception from client.activate, not only timeouts or 422. If the POST fails for a genuine permission error (403) or rate-limit (429), recovery still queries latestActivation and could match an unrelated earlier activation for the same version+network (e.g. submitted manually in Property Manager), returning false recovered: true. Consider narrowing to specific error signatures (timeout string match + 422 status) or adding a recency/timestamp check on the recovered activation.

4. [Important] Stale OpenAPI description for insertIndex - docs/openapi/llmo-api.yaml:6489

   The spec still reads "Defaults to 0 (before everything)" but the code now defaults to LAST (children.length) when no index is provided. This actively misleads consumers who rely on the spec. Fix: update to reflect the new default (appends after all existing children).

Non-blocking (4): minor issues and suggestions

• nit: Wildcard-wrapping heuristic (String(ua).includes('*')) leaves values like GPTBot* (trailing only) untouched rather than ensuring both leading and trailing wildcards - src/controllers/llmo/llmo-akamai-utils.js:104
• suggestion: buildRuleTreePatch is now dead code in the controller (import removed) but still exported and tested - mark deprecated or remove in a follow-up
• nit: behaviorCaching hardcodes defaultTtl: '1d' - document this choice so operators know AI-bot responses may be edge-cached up to a day when origin omits Cache-Control - src/controllers/llmo/llmo-akamai-utils.js:200
• suggestion: Recovery catch logs at warn level when both the activation POST and the recovery probe fail - this double-failure warrants error for alerting visibility - src/controllers/llmo/llmo-akamai.js:810

---

_{Skill: pr-review | Model: us.anthropic.claude-opus-4-6-v1[1m] | Duration: 0m 4s | Cost: $9.10 | Commit: 2f194a3aa5f03512e835b09b8945e388f7a11928
If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[ABHA61]

Follow-up commits: reject baseVersion 0, more robust activation recovery, and docs/OpenAPI sync. Tests green, lint clean.

[MysticatBot]

Hey @ABHA61,

⚠ Degraded review - no spec document was found for this change (searched the PR links, the touched repos' docs, the architecture/guidelines docs, and linked Jira). This review covers code-level quality but could not validate the change against an agreed design, so confidence is reduced. Add a spec link (PR template section 4) and re-request review for a full-confidence pass.

Verdict: Request changes - gist tarball dependency must be resolved before merge; the PR is no longer in draft.
Complexity: HIGH - large diff with supply-chain pin and API surface changes.
Changes: Reworks Akamai OAE onboarding to use full-tree PUT with CUSTOM-default scope gate, conditional caching, activation recovery with recency window, and optional baseVersion (7 files).
Note: Recommend a human read before merge - this change modifies a shared contract (docs/openapi/llmo-api.yaml). The bot review is a complement to, not a replacement for, a human read here.

Must fix before merge

1. [Critical] Gist tarball dependency still in place on an open (non-draft) PR - package.json:86 (details inline)

Non-blocking (1): minor issues and suggestions

• suggestion: Recovery tests rely on wall-clock proximity to Date.now() rather than a fake clock; boundary behavior (4:59 vs 5:01) is not directly exercisable without sinon.useFakeTimers - src/controllers/llmo/llmo-akamai.js:51

Previously flagged, now resolved

• baseVersion validation now rejects < 1 with a clean 400 (mirrors activate handler) + regression test
• Activation recovery narrowed with isRecentlySubmitted (5-min recency window); double-failure upgraded to log.error + tests for stale/recent/placeholder/different-version/double-failure
• OpenAPI insertIndex description updated to document the append-last default
• defaultTtl: '1d' documented as the origin-omits-Cache-Control fallback

---

_{Skill: pr-review | Model: us.anthropic.claude-opus-4-6-v1[1m] | Duration: 2m 27s | Cost: $6.97 | Commit: 2c67abdf46a7c630f56986daaf621e283b161378
If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[MysticatBot]

issue (blocking): Supply chain risk - gist tarball dependency.

@adobe/spacecat-shared-akamai-client resolves from a personal Gist URL rather than the npm registry. The prior review flagged this as Critical; the author acknowledged it as a pre-merge blocker ("will swap once #1825 releases"). However, the PR has since moved from draft to open without resolving it - the structural safeguard preventing an accidental merge is gone.

The Gist owner can modify or delete the content at any time. There is no provenance verification, no CI, and no audit trail on the tarball. If this merges as-is, production builds fetch from a personal Gist URL.

Engagement with pushback: The author's commitment to fix before merge is understood and reasonable, but the PR is now in a mergeable state without a branch-protection rule or CI check preventing it. Either (a) move the PR back to draft until the swap is done, (b) add a CI check that fails on non-registry dependency URLs, or (c) swap to the published package now that spacecat-shared#1825 is available.

[MysticatBot]

Hey @ABHA61,

⚠ Degraded review - no spec document was found for this change (searched the PR links, the touched repos' docs, the architecture/guidelines docs, and linked Jira). This review covers code-level quality but could not validate the change against an agreed design, so confidence is reduced. Add a spec link (PR template section 4) and re-request review for a full-confidence pass.

Verdict: Request changes - gist tarball dependency must be resolved before merge; the PR is no longer in draft.
Complexity: HIGH - large diff with supply-chain pin and API surface changes.
Changes: Reworks Akamai OAE onboarding to use full-tree PUT with CUSTOM-default scope gate, conditional caching, activation recovery without recency gating, and optional baseVersion (7 files).
Note: Recommend a human read before merge - this change modifies a shared contract (docs/openapi/llmo-api.yaml). The bot review is a complement to, not a replacement for, a human read here.

Must fix before merge

1. [Critical] Gist tarball dependency still pinned on a non-draft PR - package.json:86 (details inline)

Non-blocking (0): no minor issues or suggestions

No non-blocking findings on this increment.

Previously flagged, now resolved

• baseVersion validation now rejects < 1 with a clean 400 + regression test
• Activation recovery refined: recency window removed in favor of version+network+status match; rationale documented in code comments and tests updated
• OpenAPI insertIndex description updated to document the append-last default

---

_{Skill: pr-review | Model: us.anthropic.claude-opus-4-6-v1[1m] | Duration: 1m 18s | Cost: $4.72 | Commit: a1ed81f7b210f207f5a45c718b8892ff3a29c468
If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[MysticatBot]

issue (blocking): Supply chain risk - gist tarball dependency remains unresolved.

@adobe/spacecat-shared-akamai-client still resolves from a personal Gist URL rather than the npm registry. The PR is no longer in draft, so no structural safeguard prevents an accidental merge.

The incremental code change (recency-window removal) is well-reasoned and the test coverage is adequate - this remains the sole blocker. Once spacecat-shared#1825 publishes and the dependency is swapped to the registry version, the PR is ready to merge.

[MysticatBot]

Hey @ABHA61,

Verdict: Approve - all prior blockers resolved, code is well-structured with comprehensive test coverage.
Complexity: HIGH - large diff with dependency upgrade, API surface changes, and multiple behavioral shifts.
Changes: Reworks Akamai OAE onboarding to use full-tree PUT with CUSTOM-default scope gate, conditional caching, activation recovery, and optional baseVersion (7 files).
Note: Recommend a human read before merge - this change modifies a shared contract (docs/openapi/llmo-api.yaml). The bot review is a complement to, not a replacement for, a human read here.

Non-blocking (6): minor issues and suggestions

• suggestion: OpenAPI response schema for baseVersion still reads "The latest version the new version was created from" but it may now be an explicit caller-supplied version - update to "The version the new version was created from" - docs/openapi/llmo-api.yaml
• suggestion: buildRuleTreePatch JSDoc still says "0 = before everything = default" but the default is now LAST (append) - stale comment in dead code - src/controllers/llmo/llmo-akamai-utils.js:493
• nit: Recovery logic does not explicitly assert recovered.network === network - the latestActivation call is already scoped by network, but an explicit check would make the contract visible - src/controllers/llmo/llmo-akamai.js:789
• suggestion: Add a direct unit test for buildRoutingRule with cfg.addCaching = true to verify the Caching behavior is positioned before cacheId - currently only tested through the integration-level controller test - test/controllers/llmo/llmo-akamai-utils.test.js
• suggestion: Add a test for the scope gate when getDefaultOriginSsl returns null/undefined (tree with no origin behavior) to exercise the "an unknown mode" error path - test/controllers/llmo/llmo-akamai.test.js
• nit: Wildcard wrapping produces ** for an empty-string UA value - not exploitable since the defaults list is service-controlled, but a .filter(ua => String(ua).trim()) before .map(...) would harden it - src/controllers/llmo/llmo-akamai-utils.js:99

Previously flagged, now resolved

• Gist tarball dependency swapped to @adobe/spacecat-shared-akamai-client@1.2.0 from npm registry
• baseVersion validation now rejects < 1 with a clean 400 + regression test
• Activation recovery narrowed with version+network+status match; double-failure upgraded to log.error + tests for stale/recent/placeholder/different-version/double-failure
• OpenAPI insertIndex description updated to document the append-last default

---

_{Skill: pr-review | Model: us.anthropic.claude-opus-4-6-v1[1m] | Duration: 1m 16s | Cost: $7.68 | Commit: 68885463d989fe27be25ec5805550b9198561c51
If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[solaris007]

🎉 This PR is included in version 1.669.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀