feat(pymthouse): builder-sdk 0.6.0 and RFC 8693 API key exchange

[eliteprox]

Summary

• Bump @pymthouse/builder-sdk to the published builder-sdk 0.6.0 contract.
• Switch API-key → signer exchange to the app-scoped RFC 8693 endpoint (POST /api/v1/apps/{clientId}/oidc/token), replacing the old signer-session path.
• Treat composite app_<24hex>_pmth_… keys as DMZ Bearer credentials; update adapter/client tests and PymtHouse docs accordingly.

Test plan

• Confirm CI installs resolve @pymthouse/builder-sdk
• Run pymthouse-adapter / pymthouse-client unit tests.
• Exercise Get API Key / validate signer path with a composite key and with OIDC token exchange.
• Smoke developer-api UI key creation against preview PymtHouse.

Summary by CodeRabbit

• Improvements

  • Updated PymtHouse billing authentication to support app-scoped API key exchanges using the RFC 8693 token-exchange flow.
  • Added support for both composite app_*_* and legacy pmth_* presented API keys.
  • Improved signer routing and authorization handling for composite keys.
  • Updated Developer API screens with clearer guidance for creating, presenting, and exchanging PymtHouse keys.

• Documentation

  • Revised integration guidance, endpoint details, key formats, routing expectations, and verification steps.
  • Updated examples and SDK references for the latest PymtHouse integration behavior.

[github-actions]

⚠️ This PR is large (202 lines changed). Consider splitting it into smaller PRs for easier review.

[Copilot]

Pull request overview

This PR updates NaaP’s PymtHouse integration to the @pymthouse/builder-sdk 0.6.0 contract and switches API-key → signer authentication over to the app-scoped RFC 8693 token exchange endpoint (POST /api/v1/apps/{clientId}/oidc/token). It also updates UI copy and documentation to reflect that newly issued presented keys can be composite (app_<24hex>_<secret>) in addition to bare pmth_*.

Changes:

• Bump @pymthouse/builder-sdk from 0.5.0 → 0.6.0 across app + developer-api plugin, and update package-lock.json accordingly.
• Replace the prior signer-session exchange call pattern with RFC 8693 form-encoded token exchange and update parsing/tests.
• Update Developer API UI + docs to describe composite key behavior and how signing/exchange works.

Reviewed changes

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

Show a summary per file

File	Description
plugins/developer-api/frontend/src/pages/DeveloperView.tsx	Recognize composite app_*_* keys and update UI messaging for PymtHouse key behavior.
plugins/developer-api/frontend/package.json	Bump @pymthouse/builder-sdk to 0.6.0.
plugins/developer-api/backend/package.json	Bump @pymthouse/builder-sdk to 0.6.0.
package-lock.json	Lockfile update for @pymthouse/builder-sdk@0.6.0.
docs/pymthouse-integration.md	Refresh integration docs for composite keys + new /oidc/token exchange.
apps/web-next/src/lib/pymthouse-signer-exchange-config.ts	Update comments to reflect app-scoped RFC 8693 token exchange endpoint.
apps/web-next/src/lib/pymthouse-client.ts	Implement RFC 8693 form POST to /api/v1/apps/{clientId}/oidc/token and update error text.
apps/web-next/src/lib/pymthouse-client.test.ts	Update unit tests to assert form-encoded RFC 8693 request + new path.
apps/web-next/src/lib/billing/pymthouse-adapter.ts	Treat composite keys as direct Bearer to signer DMZ; use token exchange for bare pmth_*.
apps/web-next/src/lib/billing/pymthouse-adapter.test.ts	Update adapter tests to use composite app_<24hex>_... keys and new behaviors.
apps/web-next/package.json	Bump @pymthouse/builder-sdk to 0.6.0.

Comments suppressed due to low confidence (1)

apps/web-next/src/lib/pymthouse-client.ts:452

• The fallback error code 'signer_session_exchange_failed' is now misleading since this path is an RFC 8693 token exchange (/oidc/token). Updating the code string makes logs/telemetry easier to interpret and avoids consumers keying off an outdated name.

    throw new PmtHouseError(description, {
      status: response.status,
      code: typeof body.error === 'string' ? body.error : 'signer_session_exchange_failed',
      details: body,
    });

---

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

[vercel]

Deployment failed with the following error:

Creating the Deployment Timed Out.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
naap-platform	Ready	Preview	Jul 17, 2026 4:27pm

[coderabbitai]

📝 Walkthrough

Walkthrough

PymtHouse API-key exchange now uses the app-scoped RFC 8693 OIDC endpoint with form-encoded inputs. Composite presented keys are routed directly, while bare keys are exchanged for signer tokens. Tests, UI guidance, documentation, and Builder SDK pins were updated.

Changes

PymtHouse API-key flow

Layer / File(s)	Summary
App-scoped OIDC token exchange apps/web-next/src/lib/pymthouse-client.ts, apps/web-next/src/lib/pymthouse-client.test.ts, apps/web-next/src/lib/pymthouse-signer-exchange-config.ts	The client posts RFC 8693 form fields to /api/v1/apps/{clientId}/oidc/token, parses signer-token responses, and updates related errors, tests, and configuration documentation.
Composite signer endpoint resolution apps/web-next/src/lib/billing/pymthouse-adapter.ts, apps/web-next/src/lib/billing/pymthouse-adapter.test.ts	The adapter uses isCompositeApiKey to forward composite keys directly and exchanges bare keys for signer access tokens, with updated resolver coverage.
Presented-key UI and integration contract plugins/developer-api/frontend/src/pages/DeveloperView.tsx, docs/pymthouse-integration.md, apps/web-next/package.json, plugins/developer-api/*/package.json	The UI and documentation describe composite or bare presented keys, and Builder SDK dependencies are pinned to version 0.6.0.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DeveloperView
  participant PymthouseAdapter
  participant exchangeApiKeyForSignerSession
  participant PymtHouseOIDCTokenEndpoint
  participant SignerDMZ
  DeveloperView->>PymthouseAdapter: provide presented API key
  PymthouseAdapter->>PymthouseAdapter: classify composite or bare key
  PymthouseAdapter->>SignerDMZ: route composite key as bearer
  PymthouseAdapter->>exchangeApiKeyForSignerSession: exchange bare key
  exchangeApiKeyForSignerSession->>PymtHouseOIDCTokenEndpoint: POST RFC 8693 form data
  PymtHouseOIDCTokenEndpoint-->>PymthouseAdapter: return signer access token
  PymthouseAdapter->>SignerDMZ: use signer token

Loading

Possibly related PRs

• livepeer/naap#383: Refactors the related PymtHouse API-key-to-signer exchange flow.
• livepeer/naap#405: Introduces related remote-signer endpoint resolution changes.
• livepeer/naap#421: Updates composite-key handling in the same adapter and tests.

Suggested labels: scope/packages

Suggested reviewers: seanhanca

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately captures the main change: the builder-sdk upgrade and the move to RFC 8693 API key exchange.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/pymthouse-builder-sdk

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install timed out. The project may have too many dependencies for the sandbox.

---

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.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

apps/web-next/src/lib/pymthouse-client.ts (1)

431-439: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Defensively check JSON response format to prevent runtime errors.

If the token exchange endpoint (or a proxy/gateway in front of it) returns a JSON literal like null instead of an object, typeof body === 'object' remains true. Subsequent access to properties like body.error_description or body.token will throw a TypeError and crash the thread.

Validating that the parsed response is a non-null, non-array object inside the try block ensures that unexpected payloads safely trigger the generic PmtHouseError catch block.

🛡️ Proposed defensive check

   let body: Record<string, unknown>;
   try {
-    body = (await response.json()) as Record<string, unknown>;
+    const parsed = await response.json();
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('Response is not a JSON object');
+    }
+    body = parsed as Record<string, unknown>;
   } catch {
     throw new PmtHouseError('API key token exchange returned invalid JSON', {
       status: 502,

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/web-next/src/lib/pymthouse-client.ts` around lines 431 - 439, Update the
JSON parsing in the token exchange response flow to validate that the parsed
value is a non-null, non-array object before assigning it to body. Treat null,
arrays, and other JSON primitives as invalid responses so they follow the
existing PmtHouseError path instead of reaching body.error_description or
body.token access.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@apps/web-next/src/lib/pymthouse-client.ts`:
- Around line 431-439: Update the JSON parsing in the token exchange response
flow to validate that the parsed value is a non-null, non-array object before
assigning it to body. Treat null, arrays, and other JSON primitives as invalid
responses so they follow the existing PmtHouseError path instead of reaching
body.error_description or body.token access.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2098f3a2-9db3-4232-aea9-191cb0770e0c

📥 Commits

Reviewing files that changed from the base of the PR and between 411c310 and 7fe4dd2.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json, !package-lock.json

📒 Files selected for processing (10)

• apps/web-next/package.json
• apps/web-next/src/lib/billing/pymthouse-adapter.test.ts
• apps/web-next/src/lib/billing/pymthouse-adapter.ts
• apps/web-next/src/lib/pymthouse-client.test.ts
• apps/web-next/src/lib/pymthouse-client.ts
• apps/web-next/src/lib/pymthouse-signer-exchange-config.ts
• docs/pymthouse-integration.md
• plugins/developer-api/backend/package.json
• plugins/developer-api/frontend/package.json
• plugins/developer-api/frontend/src/pages/DeveloperView.tsx