[purpshell]

Insufficient prepaid funding now produces the payment_required category, preserves the API error code and request ID, and exits with code 4 without retrying the operation. The README documents fractional credit quantities and the explicit quote → review → confirm flow for tier changes.

Rebased onto CLI dev 41547aa (after #7). The SDK pin is unchanged from dev: github:polymorfa/sdks#08452992a32a392de5fc3d0fa3954ba6addd7f32. That SDK revision (sdks#175) already includes the reviewed billing quote/confirmation and PolymorfaPaymentRequiredError changes from the now-closed sdks#94, so this PR no longer changes the dependency. Its API pin is 1600403db9dcf7996dbbb882375b1165859829d3.

Verification

Clean npm ci, then npm run verify: formatting, lint, typecheck, 260 tests in 30 files, build and package dry run all pass. npm run audit:prod found 0 vulnerabilities. That audit was rerun separately because the first attempt hit a transient registry DNS failure.

Surface impact

• API: unaffected. The CLI uses the existing Platform billing and tier-quote routes at API 1600403.
• SDKs: unaffected. The CLI uses the SDK error class and tier methods already on sdks dev.
• CLI: updated. Error presentation (src/errors/present.ts), the exit code, tests and README.
• Docs: updated in the CLI README. Public billing docs belong to the API repository and are unchanged by this consumer-side error mapping.
• Feature releases: unaffected. No flag, entitlement, rollout, deployment or npm release. Server billing authority stays definitive.

Summary by CodeRabbit

• New Features

  • API responses now preserve fractional prepaid balance values.
  • Payment-required failures provide a non-retryable status, exit code 4, and request identifiers.
  • Session workflows support quoting and retrieving tier changes.

• Documentation

  • Added guidance for prepaid billing, insufficient funds, expired quotes, tier changes, and supplying numeric or null values through --input.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 626936d9-fb5a-4752-abfc-c69fb4deef6b

📥 Commits

Reviewing files that changed from the base of the PR and between 382afc7 and 1a81f94.

📒 Files selected for processing (4)

• README.md
• src/errors/present.ts
• test/commands/api.test.ts
• test/sdk/client.test.ts

Included review availability: 7 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 8 reviews per hour.

---

📝 Walkthrough

Walkthrough

The CLI now presents payment-required errors with exit code 4 and preserved metadata. Tests cover fractional balances, HTTP 402 responses, retry behavior, and tier-change retrieval. The README documents prepaid billing and tier-quote workflows.

Changes

Prepaid billing behavior

Layer / File(s)	Summary
Client surface validation test/sdk/client.test.ts	The client test asserts that sessions expose retrieveTierChange.
Payment-required error presentation and API validation src/errors/present.ts, test/commands/api.test.ts	Payment-required errors use the payment_required category, exit code 4, preserved error metadata, and retryable: false. API tests cover fractional balances and HTTP 402 responses without retries.
Prepaid billing API documentation README.md	The README documents fractional credits, payment-required responses, expired tier quotes, the tier-quote workflow, and JSON input requirements.

Priority: ➖ Normal

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

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant APICommand
  participant PolymorfaSDK
  participant presentError
  APICommand->>PolymorfaSDK: send API request
  PolymorfaSDK-->>APICommand: return HTTP 402 entitlement error
  APICommand->>presentError: present payment-required error
  presentError-->>APICommand: return category and exit code 4

Loading

Merge Risk: ⚪ Minimal · up to 1a81f

The prepaid funding error handling, tests, and documentation changes have no identified merge-blocking issue.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 3 files. (1 skipped: 1 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: handling prepaid billing errors with the reviewed Platform SDK.
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.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

Warning

Git: CodeRabbit could not clone the repository, so clone-backed analysis was skipped and this review may be incomplete. Verify repository clone access, such as SSH credentials, before requesting another full review. If clone access is intentionally unavailable, use path_filters to narrow the review scope.

---

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