fix(sdk): normalize wire-vs-type drift in subdomains/faucet/usage (#164)

* fix(sdk): normalize wire-vs-type drift in subdomains/faucet/usage

Three SDK methods declared one return shape and returned another at
runtime in 1.51.0, surfaced in run402#163:

- `subdomains.list` returned the gateway envelope `{ subdomains: [...] }`
  but was typed as `SubdomainSummary[]` — crashed the shipped
  `list_subdomains` MCP tool with TypeError on iteration.
- `getUsage` declared `lease_expires_at: string` but the gateway omits
  the field entirely. Relaxed to `?: string | null` here; gateway-side
  fix filed in run402-private#143.
- `allowance.faucet` declared camelCase `transactionHash`/`amount` but
  the gateway returns snake_case `transaction_hash`/`amount_usd_micros`,
  so callers saw `undefined` in log lines. Now normalized at the SDK
  boundary; `amountUsdMicros` added for callers wanting the raw number.

Test mocks updated to mirror the actual wire shapes so the next
regression gets caught before shipping — the previous mocks agreed with
the typed shape, not reality, which is how the drift slipped through.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(test): align cli-e2e mocks with real gateway shapes

The e2e mocks for `GET /subdomains/v1` and `POST /faucet/v1` returned
the SDK's old typed shape rather than what the live gateway emits, so
they couldn't catch the drifts fixed in the previous commit. After the
SDK normalization, the subdomains mock no longer matched the unwrap
path and `subdomains list` failed in CI.

- `/subdomains/v1` GET → `{ subdomains: [...] }` (was a bare array).
- `/faucet/v1` POST → `{ transaction_hash, amount_usd_micros, ... }`
  (was `{ tx_hash, amount, ... }`).

Same principle as the SDK unit-test mock updates: tests verify reality,
not what the type says.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MajorTal

cli-e2e.test.mjs

@@ -138,9 +138,9 @@ function mockFetch(input, init) {
   // Strip query string for route matching
   const pathNoQuery = path.split("?")[0];
 
-  // Faucet
+  // Faucet — wire shape: snake_case + amount in micros (SDK normalizes).
   if (path === "/faucet/v1" && method === "POST") {
-    return Promise.resolve(json({ tx_hash: "0xabc123", amount: "250000", token: "USDC", network: "base-sepolia" }));
+    return Promise.resolve(json({ transaction_hash: "0xabc123", amount_usd_micros: 250000, token: "USDC", network: "base-sepolia" }));
   }
 
   // Tiers
@@ -344,7 +344,8 @@ function mockFetch(input, init) {
     return Promise.resolve(json({ name: "my-app", url: "https://my-app.run402.com", deployment_id: "dpl_test456" }, 201));
   }
   if (path === "/subdomains/v1" && method === "GET") {
-    return Promise.resolve(json([{ name: "my-app", url: "https://my-app.run402.com" }]));
+    // Wire shape: gateway responds `{ subdomains: [...] }`; SDK unwraps.
+    return Promise.resolve(json({ subdomains: [{ name: "my-app", url: "https://my-app.run402.com", deployment_id: "dpl_test456", deployment_url: "https://dpl_test456.run402.com" }] }));
   }
   if (path.match(/^\/subdomains\/v1\//) && method === "DELETE") {
     return Promise.resolve(json({ status: "ok" }));

sdk/src/namespaces/allowance.test.ts

@@ -13,13 +13,17 @@ import assert from "node:assert/strict";
 import { Run402 } from "../index.js";
 import type { AllowanceData, CredentialsProvider } from "../credentials.js";
 
-function makeCreds(allowance: AllowanceData | null): CredentialsProvider {
-  return {
+function makeCreds(allowance: AllowanceData | null, opts: { saveAllowance?: boolean } = {}): CredentialsProvider {
+  const provider: CredentialsProvider = {
     async getAuth() { return null; },
     async getProject() { return null; },
     async readAllowance() { return allowance; },
     getAllowancePath() { return "/tmp/allowance.json"; },
   };
+  if (opts.saveAllowance) {
+    provider.saveAllowance = async () => {};
+  }
+  return provider;
 }
 
 function sdk(creds: CredentialsProvider): Run402 {
@@ -28,6 +32,10 @@ function sdk(creds: CredentialsProvider): Run402 {
   return new Run402({ apiBase: "https://api.test", credentials: creds, fetch: stubFetch });
 }
 
+function sdkWithFetch(creds: CredentialsProvider, fetchImpl: typeof globalThis.fetch): Run402 {
+  return new Run402({ apiBase: "https://api.test", credentials: creds, fetch: fetchImpl });
+}
+
 describe("allowance.status", () => {
   it("returns faucet_used=true when the on-disk allowance's internal funded marker is set", async () => {
     const result = await sdk(makeCreds({
@@ -66,3 +74,36 @@ describe("allowance.status", () => {
     assert.ok(!Object.prototype.hasOwnProperty.call(result, "funded"));
   });
 });
+
+describe("allowance.faucet", () => {
+  // Regression test for GH-163: the live gateway responds with snake_case keys
+  // and `amount_usd_micros` (number). The SDK must normalize to the typed
+  // camelCase shape so callers don't see `undefined` for transactionHash/amount.
+  it("normalizes the snake_case + micros wire shape into the typed camelCase result", async () => {
+    const wireBody = {
+      transaction_hash: "0xabc123",
+      amount_usd_micros: 250000,
+      token: "USDC",
+      network: "base-sepolia",
+    };
+    const fetchImpl: typeof globalThis.fetch = async () =>
+      new Response(JSON.stringify(wireBody), { status: 200, headers: { "Content-Type": "application/json" } });
+
+    const creds = makeCreds({
+      address: "0xAbC",
+      privateKey: "0xpk",
+      created: "2026-01-01T00:00:00.000Z",
+    }, { saveAllowance: true });
+
+    const result = await sdkWithFetch(creds, fetchImpl).allowance.faucet();
+
+    assert.equal(result.transactionHash, "0xabc123",
+      "wire's `transaction_hash` must surface as `transactionHash`");
+    assert.equal(result.amountUsdMicros, 250000,
+      "wire's `amount_usd_micros` must surface as `amountUsdMicros`");
+    assert.equal(result.amount, "0.25",
+      "amount must be a display-formatted string derived from micros");
+    assert.equal(result.token, "USDC");
+    assert.equal(result.network, "base-sepolia");
+  });
+});

sdk/src/namespaces/allowance.ts

@@ -35,7 +35,17 @@ export interface AllowanceCreateResult {
 
 export interface FaucetResult {
   transactionHash: string;
+  /** Display-formatted amount, e.g. `"0.25"`. Computed from `amountUsdMicros`. */
   amount: string;
+  /** Raw amount in micro-USD (1_000_000 = $1.00). */
+  amountUsdMicros: number;
+  token: string;
+  network: string;
+}
+
+interface FaucetWireBody {
+  transaction_hash: string;
+  amount_usd_micros: number;
   token: string;
   network: string;
 }
@@ -130,12 +140,21 @@ export class Allowance {
       resolvedAddress = data.address;
     }
 
-    const result = await this.client.request<FaucetResult>("/faucet/v1", {
+    // Wire shape is snake_case (`transaction_hash`, `amount_usd_micros`);
+    // normalize to the typed camelCase surface (regression: GH-163).
+    const wire = await this.client.request<FaucetWireBody>("/faucet/v1", {
       method: "POST",
       body: { address: resolvedAddress },
       withAuth: false,
       context: "requesting faucet funds",
     });
+    const result: FaucetResult = {
+      transactionHash: wire.transaction_hash,
+      amountUsdMicros: wire.amount_usd_micros,
+      amount: (wire.amount_usd_micros / 1_000_000).toFixed(2),
+      token: wire.token,
+      network: wire.network,
+    };
 
     // Best-effort update of the local allowance's funded/lastFaucet fields.
     const reader = this.client.credentials.readAllowance;

sdk/src/namespaces/projects.test.ts

@@ -280,6 +280,8 @@ describe("projects.list", () => {
 
 describe("projects.getUsage", () => {
   it("GETs /projects/v1/admin/:id/usage with service key", async () => {
+    // Mirrors the live gateway shape — `lease_expires_at` is intentionally
+    // absent because the endpoint doesn't compute it (see GH-163).
     const { fetch, calls } = mockFetch(() =>
       jsonResponse({
         project_id: "prj_known",
@@ -288,7 +290,6 @@ describe("projects.getUsage", () => {
         api_calls_limit: 1000,
         storage_bytes: 1024,
         storage_limit_bytes: 1048576,
-        lease_expires_at: "2026-05-01T00:00:00Z",
         status: "active",
       }),
     );
@@ -299,6 +300,8 @@ describe("projects.getUsage", () => {
     assert.equal(calls[0]!.headers["Authorization"], "Bearer service_xxx");
     assert.equal(result.tier, "prototype");
     assert.equal(result.api_calls, 10);
+    assert.equal(result.lease_expires_at, undefined,
+      "gateway omits lease_expires_at; type is optional so callers don't read a non-existent string");
   });
 
   it("throws ProjectNotFound for unknown ids before hitting the network", async () => {

sdk/src/namespaces/projects.types.ts

@@ -53,7 +53,12 @@ export interface UsageReport {
   api_calls_limit: number;
   storage_bytes: number;
   storage_limit_bytes: number;
-  lease_expires_at: string;
+  /**
+   * Optional: the `/projects/v1/admin/:id/usage` endpoint does not currently
+   * include the lease expiry. Read it from `tier.status()` if you need it.
+   * `null` is reserved for unleased accounts (see GH-163).
+   */
+  lease_expires_at?: string | null;
   status: string;
 }
 

sdk/src/namespaces/secrets.test.ts

@@ -92,11 +92,21 @@ describe("subdomains", () => {
     assert.equal(calls[0]!.method, "DELETE");
   });
 
-  it("list requires a projectId and GETs with bearer", async () => {
-    const { fetch, calls } = mockFetch(() => json([]));
-    await sdk(fetch).subdomains.list("prj_k");
+  it("list requires a projectId and GETs with bearer, unwrapping the gateway envelope", async () => {
+    // Gateway shape is `{ subdomains: [...] }`; SDK must hand back a bare array.
+    const { fetch, calls } = mockFetch(() =>
+      json({
+        subdomains: [
+          { name: "demo", url: "https://demo.run402.com", deployment_id: "dep_1", deployment_url: "https://x.run402.com" },
+        ],
+      }),
+    );
+    const result = await sdk(fetch).subdomains.list("prj_k");
     assert.equal(calls[0]!.method, "GET");
     assert.equal(calls[0]!.headers["Authorization"], "Bearer s");
+    assert.ok(Array.isArray(result), "list() must return a bare array, not the envelope");
+    assert.equal(result.length, 1);
+    assert.equal(result[0]!.name, "demo");
   });
 });
 

sdk/src/namespaces/subdomains.ts

@@ -74,9 +74,15 @@ export class Subdomains {
     const project = await this.client.getProject(projectId);
     if (!project) throw new ProjectNotFound(projectId, "listing subdomains");
 
-    return this.client.request<SubdomainSummary[]>("/subdomains/v1", {
-      headers: { Authorization: `Bearer ${project.service_key}` },
-      context: "listing subdomains",
-    });
+    // Gateway responds `{ subdomains: [...] }`; unwrap so callers get the
+    // array shape the type promises (regression: GH-163).
+    const body = await this.client.request<{ subdomains: SubdomainSummary[] }>(
+      "/subdomains/v1",
+      {
+        headers: { Authorization: `Bearer ${project.service_key}` },
+        context: "listing subdomains",
+      },
+    );
+    return body.subdomains ?? [];
   }
 }

src/tools/init.test.ts

@@ -45,8 +45,9 @@ function mockFetch(opts: {
     const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
 
     if (url.includes("/faucet/v1")) {
+      // Wire shape (snake_case + micros) — SDK normalizes for callers.
       return new Response(
-        JSON.stringify(opts.faucetBody ?? { transactionHash: "0xabc", amount: "0.25", token: "USDC", network: "base-sepolia" }),
+        JSON.stringify(opts.faucetBody ?? { transaction_hash: "0xabc", amount_usd_micros: 250000, token: "USDC", network: "base-sepolia" }),
         { status: opts.faucetOk !== false ? 200 : 429, headers: { "Content-Type": "application/json" } },
       );
     }
@@ -104,7 +105,7 @@ describe("init tool", () => {
       funded: false,
       rail: "x402",
     });
-    mockFetch({ faucetOk: true, faucetBody: { transactionHash: "0xabc", amount: "0.25", token: "USDC", network: "base-sepolia" } });
+    mockFetch({ faucetOk: true, faucetBody: { transaction_hash: "0xabc", amount_usd_micros: 250000, token: "USDC", network: "base-sepolia" } });
 
     const result = await handleInit({});
     const text = result.content[0]!.text;