feat(cli,sdk): redeem promo codes via billing top-up --code (RND-557)

[mmurrs]

Summary

Adds --code to ecloud billing top-up so existing subscribers can apply a Stripe promo code. Today there's no way to do this — the Stripe Checkout "Add code" box only shows on initial subscribe.

Usage (agent-friendly, non-interactive, no prompts):

$ ecloud billing top-up --code LAUNCH50

Redeem promotion code
─────────────────────────────────────────────

  Wallet:  0x6d4f13BD87DD441B3Fc8d94349C72EeFe27684e8
  Code:    LAUNCH50

  ✓ Redeemed LAUNCH50: $50.00 in credits
  Balance: $55.00
  Credits expire: 7/28/2026

Pairs with API PR: https://github.com/Layr-Labs/ecloud-billing-api/pull/41

Scope

 packages/cli/src/commands/billing/__tests__/top-up.test.ts | 31 +++++++++++++++
 packages/cli/src/commands/billing/top-up.ts                | 47 +++++++++++++++++++++-
 packages/sdk/src/client/common/types/index.ts              | 11 ++++++
 packages/sdk/src/client/common/utils/billingapi.ts         | 10 ++++-
 packages/sdk/src/client/modules/billing/index.ts           | 23 ++++++++++-
 5 files changed, 121 insertions(+), 1 deletion(-)

No changes to subscribe, status, cancel, or the existing USDC top-up flow. --code short-circuits before any on-chain interaction, so nothing in the USDC path is touched.

How to validate

Unit tests:

pnpm --filter @layr-labs/ecloud-cli test

All 55 tests pass (including 2 new --code cases).

Manual dry-run (no Stripe needed):

ecloud billing top-up --code ANY --help    # shows flag description

End-to-end (against Stripe test mode + local billing-api from #41):

1. Check out feat/redeem-code on ecloud-billing-api and make run with a Stripe test key.
2. Create a Coupon ($5 off, once) and a Promotion Code (e.g., TEST5, max_redemptions=1) in the Stripe Dashboard (test mode).
3. Build the CLI: pnpm --filter @layr-labs/ecloud-cli build
4. Run against a subscribed wallet:

   ecloud billing top-up --code TEST5
   

   Expect: ✓ Redeemed TEST5: $5.00 in credits + new balance + expiry.
5. Second attempt (same wallet, same code) → Stripe idempotency re-returns the same grant silently.
6. Different wallet, same code → friendly error: Code "TEST5" is not valid, inactive, or already redeemed. (because Promotion Code got deactivated after the first burn).
7. Percent-off code → Code "..." is not a fixed-amount credit code (percent-off codes are not supported).
8. Confirm via ecloud billing status — Remaining Credits should reflect the new amount.

Not in this PR

• New menu / interactive picker — deliberately kept flag-driven for CLI + agent ergonomics. Can layer an inquirer prompt later.
• CC top-up — separate open work.

Linear

RND-557 — https://linear.app/eigenlabs/issue/RND-557/add-couponcredit-code-redemption-to-ecloud-billing-top-up

🤖 Generated with Claude Code