Canonical SignerSession envelope and v0.5.0 (drop legacy exchange fields)

[eliteprox]

Summary by CodeRabbit

• New Features

  • API key sign-in now supports a more direct signer-session exchange flow.
  • Signer routing responses now use a standardized signer_url field.

• Bug Fixes

  • Improved compatibility with older signer-session flows by falling back when the direct path isn’t available.
  • Tightened response handling to reject incomplete exchange payloads earlier.

• Documentation

  • Updated examples and guidance to match the latest API field names and routing behavior.
  • Removed outdated references to deprecated credit-related and proxy-route behavior.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2da95db2-8f73-47d9-9ca7-66e3c30c0f65

📥 Commits

Reviewing files that changed from the base of the PR and between 883e3ce and a1945d8.

📒 Files selected for processing (15)

• README.md
• package.json
• src/client.ts
• src/index.ts
• src/signer/api-key-exchange.ts
• src/signer/device-exchange.ts
• src/signer/direct-signer.ts
• src/signer/types.ts
• src/tokens.ts
• src/types.ts
• src/usage.ts
• test/signer/api-key-exchange.test.ts
• test/signer/device-exchange.test.ts
• test/signer/direct-signer.test.ts
• test/signer/gateway-token.test.ts

---

📝 Walkthrough

Walkthrough

The PR standardizes signer exchange responses on signer_url, adds a direct API-key signer-session minting path with fallback handling, and removes deprecated credits, usage, and routing aliases from the public surface and docs.

Changes

Signer exchange and public API cleanup

Layer / File(s)	Summary
Signer response contracts and docs README.md, src/client.ts, src/types.ts, src/signer/types.ts, src/signer/direct-signer.ts, test/signer/direct-signer.test.ts	TokenExchangeResponse and DeviceExchangeResponse switch to signer_url, signerUrlFromExchangeResponse reads the snake_case field, and the README and direct-signer test follow the updated shape.
Device exchange normalization src/signer/device-exchange.ts, test/signer/device-exchange.test.ts	Device-exchange helpers now require top-level access_token, normalize signer-session payloads into signer_url and issued_token_type, and the tests assert the updated canonical response.
Direct API-key signer-session flow src/signer/api-key-exchange.ts, test/signer/api-key-exchange.test.ts, test/signer/gateway-token.test.ts	API-key exchange rejects pmth_cs_ keys, adds mintSignerSessionFromApiKeyDirect, falls back on 404, and updates handler and tests to the /auth/api-key/signer-session flow.
Deprecated public aliases removed package.json, src/client.ts, src/index.ts, src/types.ts, src/usage.ts, README.md	Deprecated credits, usage, token, and routing aliases are removed from client exports and docs, and the package version bumps to 0.5.0.

Sequence Diagram(s)

sequenceDiagram
  participant createApiKeyExchangeHandler
  participant mintSignerSessionFromApiKeyDirect
  participant IssuerSignerSessionEndpoint as "/api/v1/apps/{publicClientId}/auth/api-key/signer-session"
  participant deviceExchangeResponseFromSignerSessionBody

  createApiKeyExchangeHandler->>mintSignerSessionFromApiKeyDirect: request direct signer-session mint
  mintSignerSessionFromApiKeyDirect->>IssuerSignerSessionEndpoint: Authorization: Bearer apiKey
  IssuerSignerSessionEndpoint-->>mintSignerSessionFromApiKeyDirect: signer-session JSON
  mintSignerSessionFromApiKeyDirect->>deviceExchangeResponseFromSignerSessionBody: normalize access_token and signer_url
  deviceExchangeResponseFromSignerSessionBody-->>createApiKeyExchangeHandler: DeviceExchangeResponse

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• pymthouse/builder-sdk#33: Introduced the direct signer DMZ/API-key exchange path that this PR continues by switching to signer_url and the signer-session endpoint.

Poem

Hop hop, the signer_url path now gleams,
I nibbled old aliases out of the streams.
Direct to the DMZ, I dash with a thump,
New tokens sparkle—carrot-bright and plump. 🐰

✨ 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 refactor/route-cleanup

---

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud