Add simplified interact() API.

[djscruggs]

What

Adds the simplified, single-call CHAPI interact() API — both the spec (docs/specs/interact-api.md) and an initial implementation.

await navigator.chapi.interact({interactionUrl, signal, recommendedHandlerOrigins});

• Always generates a request (no type param); translates into the existing get() flow, carrying interactionUrl in the protocols map under the well-known interact meta-protocol key: web: {protocols: {interact: interactionUrl}}. No mediator/RPC changes.
• interactionUrl is treated as opaque — the polyfill does not fetch, parse, or encode it. The full protocols object is fetched from that URL over TLS by the selected handler, giving source authentication and disconnected-system (QR) support.
• Resolves to an empty object {} on completion; rejects AbortError on user cancel or signal abort; otherwise surfaces the same errors as get().
• Exposed two ways, sharing one implementation: navigator.chapi.interact() and the chapi object on the value returned by load()/loadOnce().
• Purely additive — no behavior change to get()/store()/load()/loadOnce().

Structure (functional core / imperative shell)

• lib/interactRequest.js — pure createInteractRequest() builder (validates https:, builds the request); no navigator/network, independently unit-tested.
• lib/interact.js — interact() shell built around an injected credentials container + secure-context assertion; maps result/abort to the resolution contract.
• lib/index.js — wires chapi onto the returned polyfill and navigator.chapi.

Why

Addresses #50. The current API requires relying parties to compose a full web/VerifiablePresentation request object. A single interactionUrl-based entry point is much simpler for coordinator websites, and the URL indirection authenticates the protocols source over TLS.

Testing

• npm run test:node — node --test unit tests for the pure builder (9) and the shell (9): request shape, opaque pass-through, validation, abort/cancel mapping, secure-context.
• npm test runs the Node tests and the cross-browser Playwright suite (Chromium/Firefox/WebKit). Added test/interact.spec.js (wiring smoke tests) and a navigator.chapi assertion to the existing load smoke test.
• Full suite green locally (17 passed, 1 pre-existing WebKit skip); lint clean.

Open questions (for review)

Left open in the spec and called out inline: final method name; {} vs undefined resolution payload; first-call performance; whether abort must actively tear down the in-flight RPC vs. abandon it; and whether a null get() result (no credential selected) should map to AbortError (current behavior) or resolve empty. The interact protocols-key and dropping type were resolved during review.

Addresses #50.

🤖 Generated with Claude Code

[dlongley]

Let's leave type off for now and just generate a request. That might actually cover all the use cases.

[djscruggs]

Done — pushed a commit dropping type; interact() now always generates a request. Updated the summary, the API shape, the translation section, and removed the type: 'store' open question.

Follow-up that this raises (open question 3 in the spec): which protocols key should interactionUrl ride under? Since protocols is a protocolName → URL map and a URL-type handler only receives a protocol it advertised in acceptedProtocols, the choice affects which handlers interact() can reach. Two paths:

1. Hardcode a key (e.g. vcapi or OID4VCI) — simplest, but locks interact() to one exchange protocol.
2. Pass the protocol name through as an optional param (interact({interactionUrl, protocol})) — keeps the polyfill protocol-agnostic and lets the caller match their handler, at the cost of one more param.

Either way this is purely additive to the polyfill — interact() is new, so there's no back-compat risk to get()/store(). The compatibility that does matter is with deployed URL-type handlers: only a handler that advertised the chosen protocol in acceptedProtocols will receive the URL. An optional protocol param is also safe to add in a later release (it defaults), so hardcoding now doesn't paint us into a corner — though changing a hardcoded default later would be breaking for anyone relying on it.

I lean toward (2) to keep the polyfill a dumb broker, but do you have a target protocol in mind? That decides the request shape before I implement.

[dlongley]

It needs to use interact and just put the interactionUrl there as the value. The rest of the protocols are all hidden behind the interaction URL and not a concern for CHAPI. The interact protocol is a sort of "meta" protocol that allows for chaining together protocols objects.

[djscruggs]

Got it — using interact as the protocols key, with interactionUrl as the value: web: { protocols: { interact: interactionUrl } }. That makes the meta-protocol explicit and keeps CHAPI out of the underlying-protocol business — the polyfill just hands over one opaque URL under one well-known key, no protocol param needed. Will update the spec to set the key, close open question 3, and note that the polyfill treats interactionUrl as opaque (encoding is the caller's concern), then start the implementation.

[djscruggs]

Pushed a2917bc addressing all six review comments:

• Off navigator, onto globalThis. Removed the navigator.chapi assignment. Added an install option to load()/loadOnce() (default true, preserving the current global-install behavior): true installs globally and also sets globalThis.chapi; false attaches nothing and just returns the polyfill. README now recommends globalThis.chapi = (await loadOnce()).chapi.
• signal?.throwIfAborted() for the already-aborted pre-check; kept the mid-flight abort listener.
• Validation: error.cause + clearer message on URL parse failure, a distinct wrong-protocol message, and recommendedHandlerOrigins validated as an array of URL strings (URL.parse, verified available in all CI engines).

Spec, README, and CHANGELOG updated to match. Tests: 21 node + 20 browser (1 pre-existing WebKit skip), lint clean. Added coverage for install: false, the distinct error messages, and the non-URL-origin rejection.

Ready for another look.

[djscruggs]

Pushed 1d313e6 for the latest round:

• load() option parsing restructured so each option is validated independently: a string is still the legacy mediator-URL form; otherwise options must be an object, mediatorOrigin is validated (throws if not a string), and install is read independently. Fixes the fall-through where a non-string mediatorOrigin could skip the throw. install: true now shown in the default parameter.
• CHANGELOG Oxford comma applied.

All tests green (21 node + 20 browser, 1 pre-existing WebKit skip), lint clean.

[TallTed]

English looks good. I cannot judge the code.