release: 3.0.0 — restore npm semver continuity from 2.x

[chrisli30]

Summary

Stable 3.0.0 release of @avaprotocol/sdk-js + @avaprotocol/types, ending the 4.0.0-dev.X pre-release line.

Package	Before	After
@avaprotocol/sdk-js	4.0.0-dev.3	3.0.0
@avaprotocol/types	4.0.0-dev.0	3.0.0
sdk-js → types dep	4.0.0-dev.0	^3.0.0

Why 3.0.0 (not 4.0.0)

The pre-release dev iterations (4.0.0-dev.0 → 4.0.0-dev.3) used a major version that matched the internal codebase generation tag (src/v4/ directory). Publishing the stable as 3.0.0 instead restores npm semver continuity from 2.17.0 — consumers see the expected single-major bump rather than a skipped major.

The src/v4/ internal directory name is preserved as a codebase generation tag — the prior gRPC iteration was internally "v3" but published as the 2.x npm line, and the REST rewrite is "v4" internally regardless of its npm version. Renaming the internal directories would be cosmetic churn with no consumer-visible benefit; the npm version is what consumers see.

The 4.0.0-dev.X versions remain on npm under the dev dist-tag for anyone who pinned them during the rewrite; they're functionally equivalent to 3.0.0 minus the Position D auth changes shipped in #214.

What's in this PR

• packages/types/package.json: 4.0.0-dev.0 → 3.0.0
• packages/sdk-js/package.json: 4.0.0-dev.3 → 3.0.0 (+ types dep bumped to ^3.0.0)
• CHANGELOG entries for both packages explaining the cutover, the breaking changes vs 2.x, and the npm-continuity rationale
• README "Versioning notes" callout at the top of both READMEs flagging the rewrite + pointing at CHANGELOG for the detail
• Stale // As of 4.0.0-dev.3 code comment in packages/sdk-js/src/v4/protocols/index.ts updated to 3.0.0

What is NOT in this PR

• README content past the version-note callout still describes the 2.x gRPC client. Rewriting it for the 3.x REST client is a follow-up doc PR — out of scope for the version cutover.
• No changeset markdown file. Changesets supports patch/minor/major bumps from the current version (4.0.0-dev.3 → 4.0.0, 4.1.0, or 5.0.0). Going backwards to 3.0.0 requires manual version setting. Future releases go through changesets normally.

Prerequisite: merge #216 first

The publish scripts on main are broken in two ways that #216 (chore/publish-script-tag-detection) fixes:

1. No --tag flag → would publish any version as latest (correct for 3.0.0 stable by coincidence, but would silently clobber latest=2.17.0 with any future pre-release).
2. Pre-publish step runs yarn protoc-gen (v2.x gRPC leftover), aborts the script before publish.

Recommended sequence:

1. Merge chore: publish scripts pick npm dist-tag from semver pre-release #216
2. Merge this PR
3. From a freshly-pulled main: yarn publish (now safe — picks latest automatically for stable 3.0.0)
4. Tag the release on GitHub: gh release create v3.0.0 --title "v3.0.0" --notes-from-tag

Or, if you want to publish manually before #216 lands:

cd packages/types && npm publish --access public
cd ../sdk-js   && npm publish --access public

Stable 3.0.0 has no pre-release suffix, so npm's default latest tag is correct — the --tag bug only bites pre-releases.

Test plan

• yarn install — lockfile clean
• yarn workspace @avaprotocol/types build — clean
• yarn workspace @avaprotocol/sdk-js build — clean
• yarn test tests/v4/smoke.test.ts — 12/12 pass
• npx tsc --noEmit -p . — no new errors (pre-existing estimateFees + smoke.test cast errors unchanged)
• After merge + yarn publish: verify npm view @avaprotocol/sdk-js dist-tags shows latest: 3.0.0

🤖 Generated with Claude Code

[claude]

Code Review — release/3.0.0

Overview

This is a release-prep PR that promotes both packages from 4.0.0-dev.X pre-releases to the stable 3.0.0 line. The changes are small (50 additions, 5 deletions across 7 files) and largely documentation. The version rationale is well-argued and the CHANGELOG entries are thorough.

---

Issues

1. Self-contradicting README paragraphs (both READMEs)

README.md (root) and packages/sdk-js/README.md both now read:

`ava-sdk-js` is the official TypeScript SDK for Ava Protocol's AVS.

> **3.0.0 is a REST-only rewrite.** ... The sections below still describe the 2.x gRPC client ...

`ava-sdk-js` is a simple, type-safe wrapper around **gRPC** ...

The blockquote warns readers that the following content is outdated, but the paragraph immediately after still reads as a definitive first-person description, not a marked-as-stale section. A developer speed-reading for the first time will hit is a simple, type-safe wrapper around gRPC right after the notice and reasonably conclude the notice is wrong.

Minimal fix — prefix the outdated paragraph so the intent is clear:

-`@avaprotocol/sdk-js` is a simple, type-safe wrapper around gRPC ...
+> **[2.x — archived]** `@avaprotocol/sdk-js` was a simple, type-safe wrapper around gRPC ...

Or wrap the whole stale section in a <details> block. The Features bullets are equally outdated (Leverages gRPC for fast, efficient communication). This is called out as a follow-up doc PR, which is fine, but a small inline signal that the paragraph is stale would prevent developer confusion in the interim.

2. Version-pinned comment in source code

packages/sdk-js/src/v4/protocols/index.ts now reads:

// As of 3.0.0 the actual address/ABI/topic data lives in the
// standalone `@avaprotocol/protocols` package ...

Per the project's CLAUDE.md conventions, comments should only explain the why when non-obvious. A version anchor (As of 3.0.0) belongs in CHANGELOG.md — in source it silently becomes stale at 3.0.1. Suggest dropping the As of 3.0.0 prefix and keeping only the factual description, or removing the comment entirely since the re-export is self-documenting.

---

Nits

• packages/sdk-js/package.json description still says TypeScript SDK for Ava Protocol's AVS REST API (v4). The (v4) suffix refers to the internal directory tag; as the PR explains that's intentional, but it will confuse consumers who see v4 on a 3.0.0 package. Worth dropping (v4) or rewording.

• @avaprotocol/types dep range ^3.0.0 is the right choice — lets patch/minor types updates flow through without a manual SDK bump.

• No yarn.lock change — workspace-protocol resolution means the lockfile does not need to change here; the test plan's yarn install — lockfile clean check confirms this.

---

Positives

• CHANGELOG entries for both packages are detailed and honest about the breaking change surface and the version-skip rationale — exactly what consumers need.
• The PR description is excellent: merge order, manual publish fallback, and the dev dist-tag note for anyone who pinned 4.0.0-dev.X are all documented.
• Referencing chore: publish scripts pick npm dist-tag from semver pre-release #216 as a prerequisite is correctly called out rather than buried.

---

Summary

Blocking: The README contradiction (issue 1) is worth a one-line fix per file before merge — it avoids a confusing first impression for 3.0.0 adopters. Everything else is minor.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR cuts a stable 3.0.0 release for @avaprotocol/sdk-js and @avaprotocol/types, ending the 4.0.0-dev.X pre-release line while keeping the internal src/v4/ generation tag unchanged.

Changes:

• Bumps @avaprotocol/sdk-js and @avaprotocol/types versions to 3.0.0, and updates sdk-js → types dependency to ^3.0.0.
• Adds 3.0.0 release notes to both package CHANGELOGs explaining the REST cutover and versioning rationale.
• Adds top-of-README “versioning notes” callouts and updates a stale 4.0.0-dev.3 inline code comment to 3.0.0.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
README.md	Adds a top-level callout about the 3.0.0 REST rewrite and semver continuity rationale.
packages/types/package.json	Sets @avaprotocol/types version to 3.0.0.
packages/types/CHANGELOG.md	Adds 3.0.0 entry describing OpenAPI-derived REST types and rationale.
packages/sdk-js/src/v4/protocols/index.ts	Updates stale version reference in comment (4.0.0-dev.3 → 3.0.0).
packages/sdk-js/README.md	Adds a top-of-file callout about 3.0.0 REST rewrite and semver continuity rationale.
packages/sdk-js/package.json	Sets @avaprotocol/sdk-js version to 3.0.0 and bumps @avaprotocol/types dependency to ^3.0.0.
packages/sdk-js/CHANGELOG.md	Adds 3.0.0 entry describing the REST client cutover, breaking changes, and versioning rationale.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.