feat(facade): unified Tx3ClientBuilder for §3.3/§3.6 parity#29
Merged
Conversation
….6 parity
Adds Tx3ClientBuilder with the two seeding entry points (Protocol.client() for
the dynamic flow and Tx3ClientBuilder.fromParts(...) for the codegen flow),
the mandatory trp/trpEndpoint setters, optional withProfile / withParty /
withParties / withPartyUnchecked / withHeader / withEnvValue, and a single
build() terminal that throws MissingTrpEndpointError, UnknownProfileError, or
UnknownPartyError. New BuilderError class family under Tx3Error makes the
builder errors discriminable via instanceof.
Removes withProfile from the built Tx3Client (profile selection is builder-
only per §3.6) and makes tx(name) throw UnknownTxError at the call site
instead of deferring to resolve(). Late-binding withParty / withPartyUnchecked
/ withParties still available on the built client.
TxBuilder is now source-agnostic: it holds the TIR envelope, env, parties,
and args directly, so the dynamic and codegen flows drive an identical
resolve() path. Removes the client-side MissingParamsError pre-flight (TRP's
MissingTxArgError already covers this server-side); the class is kept exported
for forward compat.
Codegen template now wraps Tx3ClientBuilder.fromParts(...) instead of
re-implementing client state. The generated Client adds only the typed
per-tx params, per-tx methods, per-party setters (routing through
withPartyUnchecked), embedded TIR / profile constants, and a typed Profile
union when profiles are declared.
Top-level re-exports add Tx3ClientBuilder, Profile, BuilderError,
MissingTrpEndpointError.
Tests rewritten against the new builder API; 120/120 pass.
Spec: sdks/sdk-spec/api-surface/facade.md §3.3, §3.4, §3.6;
sdks/sdk-spec/codegen/generated-surface.md §C.3a–d.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Updates the quick-start example to use protocol.client()...build() instead of new Tx3Client(protocol, trp). Expands the concepts table with Tx3ClientBuilder, Profile, and BuilderError. Adds a fromParts walkthrough under "Skipping the runtime .tii (codegen flow)" and rewrites the CIP-30 example to drive the builder. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The e2e harness still constructed Tx3Client directly via the removed `new Tx3Client(protocol, trp).withProfile(...)` shape. Routes through `protocol.client().trpEndpoint(...).withProfile(...).withHeader(...).build()` instead; `dmtr-api-key` is now attached via the builder's `withHeader` setter rather than a separately-constructed TrpClient. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 24, 2026
scarmuega
added a commit
that referenced
this pull request
May 24, 2026
Aligns the web-sdk package version with the fleet's 0.12 release train (rust-sdk workspace is already at 0.12.0). The unified Tx3ClientBuilder landed in #29 and is a breaking change — per sdks/sdk-spec/release-policy.md any change to MAJOR or MINOR must be coordinated across all SDKs. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ports the unified-builder pattern from
rust-sdk(already oncodegen-v1beta0-4-g761a685) into web-sdk so the §3.3/§3.6 facade rows ofsdks/parity-matrix.mdflip ❌→✅.Tx3ClientBuilder(withProtocol.client()+fromParts(...)seeders,trp/trpEndpoint/withHeader/withProfile/withParty/withParties/withPartyUnchecked/withEnvValuesetters, singlebuild()terminal).Tx3Clientnow owns the deconstructed protocol parts;withProfileis builder-only (removed from the built client per §3.6);tx(name)throwsUnknownTxErrorat call site.TxBuilderis source-agnostic — both dynamic and codegen flows drive the sameresolve()path.BuilderErrorfamily +MissingTrpEndpointError;UnknownPartyErrorre-parented fromResolutionError→BuilderError(stillTx3Error-rooted, stillinstanceof-discriminable)..trix/client-lib/protocol.ts.hbs) now wrapsTx3ClientBuilder.fromParts(...); per-party setters route throughwithPartyUnchecked; profiles emitted as individualSdkProfileconsts with a typedProfilestring-union.Tx3ClientBuilder,Profile,BuilderError,MissingTrpEndpointError.Spec references:
sdks/sdk-spec/api-surface/facade.md§3.3, §3.4, §3.6;sdks/sdk-spec/codegen/generated-surface.md§C.3a–d.Breaking changes
new Tx3Client(protocol, trp)is gone — construct viaprotocol.client()...build()instead.Tx3Client.withProfile(name)removed — callwithProfileon the builder (switching profiles now requires a new client).tx(name)throwsUnknownTxErrorsynchronously instead of deferring toresolve().UnknownPartyError's parent class changed (ResolutionError→BuilderError); both still extendTx3Error.MissingParamsErrorpre-flight removed (TRP server still emitsMissingTxArgError).Test plan
npm run type-checkcleannpm run test:unit— 120/120 pass (12 new builder-pattern tests)tx3c codegenagainstsdk/tests/fixtures/transfer.tiirenders all expected symbols (Tx3ClientBuilder,fromParts,TransferParams,TRANSFER_TIR, per-partywithSender/withReceiver/withMiddleman)codegen-check.shwill fail in CI until this lands on npm — the script installstx3-sdk@latest, which is still v0.11.0 withoutTx3ClientBuilder. Expected for a template flip (same situation when rust-sdk landed this pattern).🤖 Generated with Claude Code