chore: alpha to main

[dtfiedler]

OIDC npm publishing

Summary by CodeRabbit

• New Features
  • Optional HyperBeam integration for remote reads/compute (meta/now/compute) and CLI support for supplying gateway services; join/update gateway flows accept a services payload.
• Bug Fixes
  • Safer JSON parsing/validation for fetched messages and for CLI-provided services; improved error handling and fallbacks.
• Chores
  • Release bumped to 3.22.0-alpha.5; tooling and runtime version updates.
• Documentation
  • Added gateway services JSON Schema and example.
• Tests
  • E2E tests updated to use a remote CU endpoint and some suites skipped.

[coderabbitai[bot]]

Walkthrough

Adds HyperBeam client and JSON types, wires hyperbeamUrl and gateway services through ARIO/ANT/CLI/init flows, introduces gateway services schema and example, hardens Arweave JSON parsing, bumps version and dev-deps, and updates tests/tooling.

Changes

Cohort / File(s)	Summary
Version & Release package.json, src/version.ts, CHANGELOG.md	Bumped package/version to 3.22.0-alpha.5, updated release devDependencies, and added changelog entry.
Gateway Services Schema & Example schemas/gateway_services.schema.json, schemas/gateway_services.example.json	Added AO Gateway Services JSON Schema (AoGatewayService + bundlers) and an example config.
HyperBeam client & JSON types src/common/hyperbeam/hb.ts, src/types/common.ts	New HB class and HBConfig; added exported recursive JSONValue type.
ARIO / IO HyperBeam integration src/common/io.ts, src/types/io.ts	ARIO gains optional hb usage; balance/primary-name reads attempt HyperBeam then fallback; join/update gateway params accept services; emitted tags include Services; ANT init/read flows accept hyperbeamUrl.
ANT / AOProcess changes src/common/ant.ts, src/utils/ao.ts	ANTVersions/ANT init calls updated to use { process: AOProcess }; spawnANT/forkANT signatures accept and propagate hyperbeamUrl.
CLI: options, utils, commands src/cli/options.ts, src/cli/utils.ts, src/cli/cli.ts	Added services CLI option and servicesFromOptions validation; threaded hyperbeamUrl through ARIO/ANT initializers; removed hyperbeamUrl from one command's options list.
Arweave utils hardening src/utils/arweave.ts	Guarded message.Data presence and wrapped JSON.parse in try/catch in epoch fallback parsing.
E2E tests & examples tests/e2e/esm/index.test.ts, tests/e2e/web/src/App.tsx, tests/e2e/web/src/App.test.tsx	Switched CU_URL to https://cu.ardrive.io, skipped ANTRegistry/ANTVersions suites, wired shared AOProcess for ARIO/ANTRegistry, and removed testcontainer boilerplate.
Tooling & Examples .nvmrc, examples/vite/package.json, tests/e2e/web/package.json	Updated Node version to v24.11.0; bumped vite versions in examples/tests.

Sequence Diagram(s)

sequenceDiagram
    participant CLI as CLI
    participant Utils as CLI Utils
    participant ARIO as ARIOReadable
    participant HB as HyperBeam (HB)
    participant CU as Compute Unit (CU)
    participant ANT as ANT / ANTRegistry

    CLI->>Utils: gatewaySettingsFromOptions({ services?: string })
    Utils->>Utils: servicesFromOptions(parse & validate)
    alt valid
        Utils-->>CLI: AoUpdateGatewaySettingsParams { services }
    else invalid
        Utils-->>CLI: throw validation error
    end

    CLI->>ARIO: readARIOFromOptions({ hyperbeamUrl? })
    ARIO->>HB: lazy instantiate/checkHyperBeamCompatibility()
    alt HB compatible
        ARIO->>HB: compute(path, json)
        HB-->>ARIO: result
    else fallback
        ARIO->>CU: read via CU
        CU-->>ARIO: result
    end

    ARIO->>ANT: ANT.init({ process: AOProcess, hyperbeamUrl? })
    ANT->>HB: optional name-resolution / compute via HB

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Pay extra attention to:
  • src/common/hyperbeam/hb.ts — HTTP handling, timeouts, response validation and cached compatibility logic.
  • src/cli/utils.ts — servicesFromOptions parsing, validation limits, and error messages.
  • src/common/io.ts, src/common/ant.ts, src/utils/ao.ts — consistent propagation of hyperbeamUrl and updated ANTVersions/ANT init shapes.
  • Tests (tests/e2e/*) — remote CU usage, skipped suites, and shared AOProcess wiring.

Possibly related PRs

• ar-io/ar-io-sdk#563 — Direct overlap: adds HyperBeam client and integrates hyperbeamUrl across ARIO/CLI/ANT paths.
• ar-io/ar-io-sdk#565 — Related: guarded JSON parsing changes in arweave utilities (epoch message parsing).
• ar-io/ar-io-sdk#561 — Related: ANTVersions/ANT init and AOProcess usage changes affecting version/upgrade flows.

Suggested reviewers

• atticusofsparta
• arielmelendez

Poem

🐇 I hopped a beam to fetch the night,
Bundlers tucked in JSON light,
AOProcess carried through the fields,
HyperBeam hummed and balance yields,
A tiny rabbit cheers: "Alpha—bright!"

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description 'OIDC npm publishing' is vague and does not match the actual changeset, which includes HyperBeam integration, schema additions, and version updates. The description does not follow the required template structure or provide meaningful context.	Provide a detailed description following the template: explain HyperBeam integration, new gateway services schema, version bump to 3.22.0-alpha.5, and reference any related issues or PRs.
Title check	❓ Inconclusive	The title 'chore: alpha to main' is vague and generic, using non-descriptive terms that don't convey meaningful information about the substantial changes in this changeset.	Replace with a more specific title describing the main change, such as 'chore: release 3.22.0-alpha.5' or 'feat: add HyperBeam integration and gateway services schema'.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch alpha

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5df2339a0360ad3776a78220f163e9c2e3882547 and 0381fcf4b6ca39cbb99219432e857e69b3b3f65b.

⛔ Files ignored due to path filters (1)

• yarn.lock is excluded by !**/yarn.lock, !**/*.lock

📒 Files selected for processing (1)

• package.json (5 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: build / test (integration)
• GitHub Check: build / test (esm)

🔇 Additional comments (3)

package.json (3)

134-134: No issues found. axios 1.13.2 is secure with no breaking changes.

Axios v1.13.2 (released Nov 4, 2025) contains only bug fixes and performance improvements with no breaking changes. All known CVEs affecting axios (CVE-2025-27152, CVE-2025-58754) are fixed in 1.13.2. The dependency upgrade is safe.

---

106-106: Update Node version requirement to >=22 or verify esbuild 0.27.0 compatibility with Node >=18.

The esbuild 0.27.0 upgrade introduces a breaking change: the binary loader now uses Uint8Array.fromBase64 when available, which requires Node 25+ or an explicit --target=node22+ fallback. Your current package.json specifies engines.node: ">=18", but this is incompatible with esbuild 0.27.0 unless the older Node versions (18–24) have a graceful fallback path.

Recommended actions:

1. Bump minimum Node to >=22 (recommended LTS): Update "node": ">=22" in package.json engines. This ensures the build process runs on a Node version that safely handles the new binary loader behavior.
2. Or verify that your build environment is already on Node 25+ and update the constraint to match.
3. Or add --target=node22+ to your esbuild config if you need to support older Node versions (though this is not currently set in bundle.mjs).

The other breaking changes in 0.27.0 (class-field semantics, plugin metadata consistency, Go toolchain OS requirements) do not appear to impact your setup:

• No private class fields are used in your source code.
• You use esbuild-plugin-polyfill-node without custom onResolve callbacks.
• Your tsconfig is compatible with the new "define" semantics for esnext target.

---

124-124: Semantic-release ecosystem updates are compatible.

Verification confirms no breaking changes:

• semantic-release v25.0.1 is a patch release with no new breaking changes
• @semantic-release/npm v13.1.1 is a patch release with no documented breaking changes
• @semantic-release/exec v7.0.0 requires semantic-release >= v24.1.0, and the PR updates to v25.0.1, satisfying this requirement

The ecosystem updates work together without compatibility issues.

[!TIP]

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example:

"Create a concise high-level summary as a bullet-point list. Then include a Markdown table showing lines added and removed by each contributing author."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov-commenter]

Codecov Report

:x: Patch coverage is 16.73469% with 408 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 23.97%. Comparing base (6bdc3d0) to head (0381fcf). :warning: Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/common/hyperbeam/hb.ts	33.62%	154 Missing :warning:
src/common/io.ts	0.76%	130 Missing :warning:
src/cli/utils.ts	0.00%	67 Missing :warning:
src/utils/arweave.ts	3.44%	28 Missing :warning:
src/utils/ao.ts	8.33%	11 Missing :warning:
src/common/ant.ts	0.00%	10 Missing :warning:
src/cli/options.ts	0.00%	7 Missing :warning:
src/cli/cli.ts	0.00%	1 Missing :warning:

:x: Your project status has failed because the head coverage (23.97%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #569      +/-   ##
==========================================
+ Coverage   16.04%   23.97%   +7.92%     
==========================================
  Files          33       34       +1     
  Lines        9642    10095     +453     
  Branches       67       67              
==========================================
+ Hits         1547     2420     +873     
+ Misses       8093     7673     -420     
  Partials        2        2              

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• :package: JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[dtfiedler]

:tada: This PR is included in version 3.22.0-alpha.4 :tada:

The release is available on:

• npm package (@alpha dist-tag)
• GitHub release

Your semantic-release bot :package::rocket:

[dtfiedler]

:tada: This PR is included in version 3.22.0-alpha.5 :tada:

The release is available on:

• npm package (@alpha dist-tag)
• GitHub release

Your semantic-release bot :package::rocket: