feat: consume discovery_url from SignerSession exchange as gateway token default

[eliteprox]

Summary

Consume the new optional discovery_url field from PymtHouse SignerSession exchange responses and use it as the default orchestrator discovery endpoint when building gateway tokens or returning exchange envelopes — mirroring how signer_url is already handled today.

Blocked by / pairs with: pymthouse/pymthouse#190

Motivation

Integrators using @pymthouse/builder-sdk to exchange pmth_* API keys for signer sessions often also need a discovery URL for livepeer-gateway (--discovery / gateway token discovery field). Today callers must hardcode or pass discovery explicitly in buildGatewayToken({ discovery: "…" }).

Once PymtHouse returns a platform-default (and optionally app-scoped) discovery_url on exchange, the SDK should:

1. Parse and forward it on exchange response types.
2. Use it as a fallback when the caller did not supply discovery to buildGatewayToken / mintGatewayToken.

Current behavior

• deviceExchangeResponseFromSignerSessionBody reads signer_url, validates with assertDirectSignerBaseUrl, and attaches it to DeviceExchangeResponse (src/signer/device-exchange.ts).
• signerUrlFromExchangeResponse helper in src/signer/direct-signer.ts.
• buildGatewayToken only sets bundle.discovery when input.discovery is explicitly provided (src/signer/gateway-token.ts).
• mintGatewayToken passes through options.discovery unchanged; no exchange-derived default.

Proposed changes

1. Exchange response types

Add optional discovery_url to:

• DeviceExchangeResponse (src/signer/types.ts)
• SignerSession-shaped types in src/types.ts if applicable

Parse in deviceExchangeResponseFromSignerSessionBody (and any parallel parsers in device-exchange.ts / api-key-exchange.ts), similar to signer_url.

Validate as absolute http(s) URL (new helper, e.g. assertDiscoveryUrl — no dashboard-proxy rejection needed unlike signer_url).

2. Helper

Add discoveryUrlFromExchangeResponse alongside signerUrlFromExchangeResponse in src/signer/direct-signer.ts (or a small shared module).

3. Gateway token defaulting

When assembling gateway tokens from an exchange:

discovery: options.discovery ?? discoveryUrlFromExchangeResponse(session)

Apply in mintGatewayToken (apiKey source path) and facade handlers in api-key-exchange.ts.

Precedence: explicit caller discovery > exchange discovery_url > omit (current behavior).

4. Docs + tests

• README — document exchange discovery_url and defaulting behavior
• Tests mirroring signer_url coverage in api-key-exchange, device-exchange, gateway-token, direct-signer tests

Acceptance criteria

• discovery_url parsed from PymtHouse signer-session JSON into DeviceExchangeResponse
• Invalid/missing discovery_url does not fail exchange (field remains optional)
• buildGatewayToken / mintGatewayToken default discovery from exchange when not explicitly provided
• Explicit discovery option still wins over exchange default
• README + CHANGELOG updated
• Tests added/updated

References

• PymtHouse issue: feat: include discovery_url in SignerSession (api-key/signer-session exchange) pymthouse#190
• signer_url pattern: src/signer/direct-signer.ts, src/signer/device-exchange.ts
• Gateway token bundle: src/signer/gateway-token.ts (GatewayTokenBundle.discovery)