release: v1.0.0

docs/superpowers/specs/2026-04-23-top-up-credit-card-design.md

@@ -0,0 +1,211 @@
+# Top-Up Credit Card Support
+
+Add credit card purchasing to `ecloud billing top-up` alongside the existing USDC on-chain flow.
+
+## Motivation
+
+We're moving to a credit-based burndown system. Users need to purchase credits, and not everyone wants to use USDC on-chain. Adding credit card support via Stripe lets users top up with a familiar payment method.
+
+## API Routes
+
+Both routes live on the billing API server (`ECLOUD_BILLING_API_URL`), use the same EIP-712 signature auth as existing routes (`Authorization: Bearer <sig>`, `X-Account`, `X-Expiry`).
+
+### GET /v1/payment-methods
+
+Returns saved payment methods for the authenticated wallet.
+
+Request: no body, auth required.
+
+Response:
+```json
+{
+  "paymentMethods": [
+    {
+      "id": "029641fc-3e5c-11f1-986c-5601121cbf6d",
+      "stripePaymentMethodId": "pm_1ABC123...",
+      "createdAt": "2026-04-20T15:00:00Z"
+    }
+  ]
+}
+```
+
+### POST /v1/credits/purchase
+
+Two modes depending on whether `paymentMethodId` is provided.
+
+**Direct charge (card on file):**
+
+Request:
+```json
+{
+  "amountCents": 5000,
+  "paymentMethodId": "029641fc-3e5c-11f1-986c-5601121cbf6d"
+}
+```
+
+Response:
+```json
+{
+  "purchaseId": "a1b2c3d4-5e6f-11f1-986c-5601121cbf6d",
+  "amountCents": "5000"
+}
+```
+
+**Checkout session (no card on file):**
+
+Request:
+```json
+{
+  "amountCents": 5000
+}
+```
+
+Response:
+```json
+{
+  "checkoutSessionId": "cs_test_abc123...",
+  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_abc123...",
+  "amountCents": "5000"
+}
+```
+
+Minimum `amountCents`: 500 ($5.00).
+
+## Design
+
+### SDK: New methods on `BillingApiClient`
+
+File: `packages/sdk/src/client/common/utils/billingapi.ts`
+
+Add two methods to the existing `BillingApiClient` class:
+
+```typescript
+async getPaymentMethods(): Promise<PaymentMethodsResponse>
+```
+- `GET ${billingApiServerURL}/v1/payment-methods`
+- Uses `makeAuthenticatedRequest` with a dummy productId (e.g. `"compute"`) for signature generation since the auth scheme requires a product field.
+
+```typescript
+async purchaseCredits(amountCents: number, paymentMethodId?: string): Promise<CreditPurchaseResponse>
+```
+- `POST ${billingApiServerURL}/v1/credits/purchase`
+- Body: `{ amountCents }` or `{ amountCents, paymentMethodId }` depending on whether a payment method is provided.
+- Uses `makeAuthenticatedRequest`.
+
+### SDK: New types
+
+File: `packages/sdk/src/client/common/types/index.ts`
+
+```typescript
+export interface PaymentMethod {
+  id: string;
+  stripePaymentMethodId: string;
+  createdAt: string;
+}
+
+export interface PaymentMethodsResponse {
+  paymentMethods: PaymentMethod[];
+}
+
+export interface CreditPurchaseResponse {
+  purchaseId?: string;
+  checkoutSessionId?: string;
+  checkoutUrl?: string;
+  amountCents: string;
+}
+```
+
+`CreditPurchaseResponse` is a union-style interface: a direct charge returns `purchaseId` without checkout fields; a checkout session returns `checkoutSessionId` + `checkoutUrl` without `purchaseId`.
+
+### SDK: Export new methods from billing module
+
+File: `packages/sdk/src/client/modules/billing/index.ts`
+
+Expose the two new `BillingApiClient` methods through the `BillingModule` interface:
+
+```typescript
+export interface BillingModule {
+  // ... existing methods ...
+  getPaymentMethods: () => Promise<PaymentMethodsResponse>;
+  purchaseCredits: (amountCents: number, paymentMethodId?: string) => Promise<CreditPurchaseResponse>;
+}
+```
+
+Wire them to `billingApi.getPaymentMethods()` and `billingApi.purchaseCredits()` in `createBillingModule`.
+
+### CLI: Modified `top-up.ts` command
+
+File: `packages/cli/src/commands/billing/top-up.ts`
+
+#### New flag
+
+```
+--method  usdc | card  (optional, prompts if omitted)
+```
+
+#### Updated flow
+
+1. Show wallet address and current credit balance (unchanged).
+2. **Payment method selection:**
+   - If `--method usdc` -> go to USDC path.
+   - If `--method card` -> go to credit card path.
+   - If no flag -> prompt user to choose between "USDC (on-chain)" and "Credit card".
+3. **USDC path:** Unchanged from current implementation (steps 2-5 in existing code).
+4. **Credit card path:**
+   a. Prompt for dollar amount (whole dollars, minimum $5). Skipped if `--amount` flag is provided.
+   b. Convert to cents: `amountCents = dollars * 100`.
+   c. Call `billing.getPaymentMethods()`.
+   d. If payment methods exist:
+      - Show: "Use card on file (pm_...1ABC)?" with yes/no prompt.
+      - If yes: call `billing.purchaseCredits(amountCents, paymentMethod.id)`. This returns `{ purchaseId, amountCents }`. Proceed to poll for credits.
+      - If no: call `billing.purchaseCredits(amountCents)` without payment method ID. This returns a checkout URL. Open in browser with `open`. Proceed to poll for credits.
+   e. If no payment methods: call `billing.purchaseCredits(amountCents)` (no payment method ID). Open checkout URL in browser. Proceed to poll for credits.
+5. **Credit polling:** Same polling loop as today — poll `billing.getStatus()` until `remainingCredits` increases or timeout (3 minutes).
+
+#### Amount validation (credit card path)
+
+- Must be a whole dollar amount (integer).
+- Minimum: $5 (500 cents).
+- No maximum (Stripe handles limits).
+
+#### Non-interactive support
+
+For CI/scripting, all prompts can be skipped via flags:
+- `--method card --amount 50` skips the method and amount prompts.
+- Without a card on file, the checkout URL is printed to stdout (the `open` call will be attempted but the URL is always logged).
+- With a card on file and no flag to choose it, the command will still prompt. Full non-interactive card selection is out of scope for this change.
+
+### CLI: Update command description and examples
+
+Update `static description` and `static examples` to reflect the new credit card option.
+
+### Tests
+
+File: `packages/cli/src/commands/billing/__tests__/top-up.test.ts`
+
+Add test cases:
+- **Credit card, card on file, user accepts:** mock `getPaymentMethods` returning one card, mock `purchaseCredits` returning `{ purchaseId, amountCents }`, verify no browser open, verify credit polling.
+- **Credit card, card on file, user declines (wants new card):** mock `purchaseCredits` returning `{ checkoutUrl, ... }`, verify `open` is called with checkout URL.
+- **Credit card, no card on file:** mock `getPaymentMethods` returning empty array, mock `purchaseCredits` returning checkout URL, verify `open` is called.
+- **`--method card --amount 50` skips prompts:** verify `select` and `input` are not called.
+- **Amount below $5 minimum:** verify validation error.
+- **Existing USDC tests remain unchanged.**
+
+Mock `billing.getPaymentMethods` and `billing.purchaseCredits` on the same `mockBilling` object used by existing tests. Mock `open` as already done in `subscribe.test.ts`.
+
+## Files changed
+
+| File | Change |
+|------|--------|
+| `packages/sdk/src/client/common/types/index.ts` | Add `PaymentMethod`, `PaymentMethodsResponse`, `CreditPurchaseResponse` |
+| `packages/sdk/src/client/common/utils/billingapi.ts` | Add `getPaymentMethods()`, `purchaseCredits()` |
+| `packages/sdk/src/client/modules/billing/index.ts` | Expose new methods on `BillingModule` |
+| `packages/cli/src/commands/billing/top-up.ts` | Add `--method` flag, credit card flow, method selection prompt |
+| `packages/cli/src/commands/billing/__tests__/top-up.test.ts` | Add credit card test cases |
+
+## Out of scope
+
+- Listing/managing saved payment methods (separate command later).
+- Deleting payment methods.
+- Full non-interactive card selection (auto-picking a saved card without prompting).
+- Changing the subscribe command flow.

packages/cli/package.json

@@ -80,6 +80,15 @@
       "compute:env": {
         "hidden": true,
         "description": "Manage deployment environment [alias: env]"
+      },
+      "admin": {
+        "description": "Admin operations (requires admin privileges)"
+      },
+      "admin:coupons": {
+        "description": "Manage coupons"
+      },
+      "admin:admins": {
+        "description": "Manage admin users"
       }
     }
   },

packages/cli/src/client.ts

@@ -2,6 +2,7 @@ import {
   createComputeModule,
   createBillingModule,
   createBuildModule,
+  createAdminModule,
   getEnvironmentConfig,
   requirePrivateKey,
 } from "@layr-labs/ecloud-sdk";
@@ -67,6 +68,7 @@ export async function createBillingClient(flags: CommonFlags) {
     publicClient,
     environment,
     skipTelemetry: true,
+    privateKey: privateKey as Hex,
   });
 }
 
@@ -98,3 +100,31 @@ export async function createBuildClient(flags: CommonFlags) {
     skipTelemetry: true, // CLI already has telemetry, skip SDK telemetry
   });
 }
+
+export async function createAdminClient(flags: CommonFlags) {
+  flags = await validateCommonFlags(flags);
+
+  const environment = flags.environment;
+  const environmentConfig = getEnvironmentConfig(environment);
+  const rpcUrl = flags["rpc-url"] || environmentConfig.billingRPCURL || environmentConfig.defaultRPCURL;
+  const { key: privateKey, source } = await requirePrivateKey({
+    privateKey: flags["private-key"],
+  });
+
+  if (flags.verbose) {
+    console.log(`Using private key from: ${source}`);
+  }
+
+  const { walletClient, publicClient } = createViemClients({
+    privateKey: privateKey as Hex,
+    rpcUrl,
+    environment,
+  });
+
+  return createAdminModule({
+    verbose: flags.verbose,
+    walletClient,
+    publicClient,
+    environment,
+  });
+}

packages/cli/src/commands/admin/admins/add.ts

@@ -0,0 +1,34 @@
+import { Args, Command } from "@oclif/core";
+import { createAdminClient } from "../../../client";
+import { commonFlags } from "../../../flags";
+import chalk from "chalk";
+import { withTelemetry } from "../../../telemetry";
+
+export default class AdminAdminsAdd extends Command {
+  static description = "Add a new admin";
+
+  static examples = [
+    "<%= config.bin %> admin admins add 0x...",
+  ];
+
+  static args = {
+    address: Args.string({ description: "Wallet address to grant admin", required: true }),
+  };
+
+  static flags = {
+    ...commonFlags,
+  };
+
+  async run() {
+    return withTelemetry(this, async () => {
+      const { args, flags } = await this.parse(AdminAdminsAdd);
+      const admin = await createAdminClient(flags);
+
+      const { admin: newAdmin } = await admin.addAdmin(args.address);
+
+      this.log(`\n  ${chalk.green("✓")} Admin added`);
+      this.log(`  Address: ${chalk.cyan(newAdmin.address)}`);
+      this.log(`  ID:      ${newAdmin.id}\n`);
+    });
+  }
+}

packages/cli/src/commands/admin/admins/list.ts

@@ -0,0 +1,37 @@
+import { Command } from "@oclif/core";
+import { createAdminClient } from "../../../client";
+import { commonFlags } from "../../../flags";
+import chalk from "chalk";
+import { withTelemetry } from "../../../telemetry";
+
+export default class AdminAdminsList extends Command {
+  static description = "List all admins";
+
+  static examples = [
+    "<%= config.bin %> admin admins list",
+  ];
+
+  static flags = {
+    ...commonFlags,
+  };
+
+  async run() {
+    return withTelemetry(this, async () => {
+      const { flags } = await this.parse(AdminAdminsList);
+      const admin = await createAdminClient(flags);
+
+      const { admins } = await admin.listAdmins();
+
+      if (admins.length === 0) {
+        this.log("\n  No admins found.\n");
+        return;
+      }
+
+      this.log(`\n${chalk.bold("Admins")} (${admins.length}):\n`);
+      for (const a of admins) {
+        this.log(`  ${chalk.cyan(a.address)}  ${chalk.gray(a.createdAt)}`);
+      }
+      this.log();
+    });
+  }
+}

packages/cli/src/commands/admin/admins/remove.ts

@@ -0,0 +1,32 @@
+import { Args, Command } from "@oclif/core";
+import { createAdminClient } from "../../../client";
+import { commonFlags } from "../../../flags";
+import chalk from "chalk";
+import { withTelemetry } from "../../../telemetry";
+
+export default class AdminAdminsRemove extends Command {
+  static description = "Remove an admin";
+
+  static examples = [
+    "<%= config.bin %> admin admins remove 0x...",
+  ];
+
+  static args = {
+    address: Args.string({ description: "Wallet address to remove from admins", required: true }),
+  };
+
+  static flags = {
+    ...commonFlags,
+  };
+
+  async run() {
+    return withTelemetry(this, async () => {
+      const { args, flags } = await this.parse(AdminAdminsRemove);
+      const admin = await createAdminClient(flags);
+
+      await admin.removeAdmin(args.address);
+
+      this.log(`\n  ${chalk.green("✓")} Admin ${chalk.cyan(args.address)} removed.\n`);
+    });
+  }
+}