Merge branch 'codex/bugs-gh-267-sdk-limits'

Author: MajorTal

sdk/src/namespaces/billing.test.ts

@@ -8,6 +8,7 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 
 import { Run402 } from "../index.js";
+import { LocalError } from "../errors.js";
 import type { CredentialsProvider } from "../credentials.js";
 
 interface FetchCall {
@@ -189,6 +190,36 @@ describe("billing.history", () => {
     assert.equal(calls[0]!.url, "https://api.example.test/billing/v1/accounts/0xabc/history?limit=50");
   });
 
+  it("appends ?limit=1 when the minimum valid limit is provided", async () => {
+    const { fetch, calls } = mockFetch(() =>
+      jsonResponse({ identifier: "0xabc", identifier_type: "wallet", entries: [] }),
+    );
+    const sdk = makeSdk(fetch);
+    await sdk.billing.history("0xABC", 1);
+
+    assert.equal(calls[0]!.url, "https://api.example.test/billing/v1/accounts/0xabc/history?limit=1");
+  });
+
+  it("throws LocalError and does not request for invalid limits", async () => {
+    const invalidLimits = [0, -1, 1.5, Number.NaN, Number.MAX_SAFE_INTEGER + 1];
+
+    for (const limit of invalidLimits) {
+      const { fetch, calls } = mockFetch(() => {
+        throw new Error(`unexpected fetch for limit ${String(limit)}`);
+      });
+      const sdk = makeSdk(fetch);
+
+      await assert.rejects(
+        sdk.billing.history("0xABC", limit),
+        (err: unknown) =>
+          err instanceof LocalError &&
+          err.context === "fetching billing history" &&
+          /limit.*positive safe integer/i.test(err.message),
+      );
+      assert.equal(calls.length, 0, `limit ${String(limit)} should not request`);
+    }
+  });
+
   it("offers getHistory as a generic identifier alias", async () => {
     const { fetch, calls } = mockFetch(() =>
       jsonResponse({ identifier: "user@example.com", identifier_type: "email", entries: [] }),

sdk/src/namespaces/billing.ts

@@ -6,6 +6,7 @@
 
 import type { Client } from "../kernel.js";
 import { LocalError } from "../errors.js";
+import { assertPositiveSafeInteger } from "../validation.js";
 import type { ProjectTier } from "./projects.types.js";
 
 export interface BillingBalance {
@@ -102,7 +103,10 @@ export class Billing {
   /** Fetch billing history by wallet or email identifier. */
   async getHistory(identifier: BillingAccountIdentifier, limit?: number): Promise<BillingHistoryResult> {
     const encoded = encodeBillingIdentifier(identifier);
-    const path = limit
+    if (limit !== undefined) {
+      assertPositiveSafeInteger(limit, "limit", "fetching billing history");
+    }
+    const path = limit !== undefined
       ? `/billing/v1/accounts/${encoded}/history?limit=${encodeURIComponent(String(limit))}`
       : `/billing/v1/accounts/${encoded}/history`;
     return this.client.request<BillingHistoryResult>(path, {

sdk/src/namespaces/blobs.test.ts

@@ -8,7 +8,7 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 
 import { Run402 } from "../index.js";
-import { ProjectNotFound, ApiError } from "../errors.js";
+import { ProjectNotFound, ApiError, LocalError } from "../errors.js";
 import type { CredentialsProvider } from "../credentials.js";
 
 interface FetchCall {
@@ -403,6 +403,26 @@ describe("blobs.ls", () => {
     await sdk.blobs.ls("prj_known");
     assert.equal(calls[0]!.url, "https://api.example.test/storage/v1/blobs");
   });
+
+  it("throws LocalError and does not request for invalid limits", async () => {
+    const invalidLimits = [0, -1, 1.5, Number.NaN, Number.MAX_SAFE_INTEGER + 1];
+
+    for (const limit of invalidLimits) {
+      const { fetch, calls } = mockFetch(() => {
+        throw new Error(`unexpected fetch for limit ${String(limit)}`);
+      });
+      const sdk = makeSdk(fetch);
+
+      await assert.rejects(
+        sdk.blobs.ls("prj_known", { limit }),
+        (err: unknown) =>
+          err instanceof LocalError &&
+          err.context === "listing blobs" &&
+          /limit.*positive safe integer/i.test(err.message),
+      );
+      assert.equal(calls.length, 0, `limit ${String(limit)} should not request`);
+    }
+  });
 });
 
 describe("blobs.rm", () => {
@@ -923,4 +943,28 @@ describe("blobs.waitFresh", () => {
       ProjectNotFound,
     );
   });
+
+  it("throws LocalError and does not diagnose for invalid timeoutMs", async () => {
+    const invalidTimeouts = [0, -1, 1.5, Number.NaN, Number.MAX_SAFE_INTEGER + 1];
+
+    for (const timeoutMs of invalidTimeouts) {
+      const { fetch, calls } = mockFetch(() => {
+        throw new Error(`unexpected fetch for timeoutMs ${String(timeoutMs)}`);
+      });
+      const sdk = makeSdk(fetch);
+
+      await assert.rejects(
+        sdk.blobs.waitFresh("prj_known", {
+          url: "https://app.run402.com/_blob/k",
+          sha256: "ff",
+          timeoutMs,
+        }),
+        (err: unknown) =>
+          err instanceof LocalError &&
+          err.context === "waiting for CDN freshness" &&
+          /timeoutMs.*positive safe integer/i.test(err.message),
+      );
+      assert.equal(calls.length, 0, `timeoutMs ${String(timeoutMs)} should not request`);
+    }
+  });
 });

sdk/src/namespaces/blobs.ts

@@ -9,6 +9,7 @@
 
 import type { Client } from "../kernel.js";
 import { ApiError, LocalError, ProjectNotFound } from "../errors.js";
+import { assertPositiveSafeInteger } from "../validation.js";
 import type {
   BlobCacheKind,
   BlobCdnEnvelope,
@@ -488,11 +489,13 @@ export class Blobs {
     projectId: string,
     opts: BlobWaitFreshOptions,
   ): Promise<BlobWaitFreshResult> {
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    assertPositiveSafeInteger(timeoutMs, "timeoutMs", "waiting for CDN freshness");
+
     const project = await this.client.getProject(projectId);
     if (!project) throw new ProjectNotFound(projectId, "waiting for CDN freshness");
 
     const expected = opts.sha256.toLowerCase();
-    const timeoutMs = opts.timeoutMs ?? 60_000;
     const start = Date.now();
 
     let attempts = 0;
@@ -563,6 +566,10 @@ export class Blobs {
 
   /** List blobs with optional prefix + pagination. */
   async ls(projectId: string, opts: BlobLsOptions = {}): Promise<BlobLsResult> {
+    if (opts.limit !== undefined) {
+      assertPositiveSafeInteger(opts.limit, "limit", "listing blobs");
+    }
+
     const project = await this.client.getProject(projectId);
     if (!project) throw new ProjectNotFound(projectId, "listing blobs");
 

sdk/src/namespaces/email.test.ts

@@ -7,6 +7,7 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 
 import { Run402 } from "../index.js";
+import { LocalError } from "../errors.js";
 import type { CredentialsProvider } from "../credentials.js";
 
 interface FetchCall {
@@ -181,3 +182,36 @@ describe("email.send", () => {
     assert.equal(result.sent_at, "2026-05-01T18:30:14.904Z");
   });
 });
+
+describe("email.list", () => {
+  it("GETs mailbox messages with limit and after query params", async () => {
+    const { fetch, calls } = mockFetch(() => jsonResponse([]));
+    const sdk = makeSdk(makeCreds(), fetch);
+    await sdk.email.list("prj_known", { limit: 1, after: "msg_prev" });
+
+    const url = new URL(calls[0]!.url);
+    assert.equal(url.pathname, "/mailboxes/v1/mbx_known/messages");
+    assert.equal(url.searchParams.get("limit"), "1");
+    assert.equal(url.searchParams.get("after"), "msg_prev");
+  });
+
+  it("throws LocalError and does not request for invalid limits", async () => {
+    const invalidLimits = [0, -1, 1.5, Number.NaN, Number.MAX_SAFE_INTEGER + 1];
+
+    for (const limit of invalidLimits) {
+      const { fetch, calls } = mockFetch(() => {
+        throw new Error(`unexpected fetch for limit ${String(limit)}`);
+      });
+      const sdk = makeSdk(makeCreds(), fetch);
+
+      await assert.rejects(
+        sdk.email.list("prj_known", { limit }),
+        (err: unknown) =>
+          err instanceof LocalError &&
+          err.context === "listing emails" &&
+          /limit.*positive safe integer/i.test(err.message),
+      );
+      assert.equal(calls.length, 0, `limit ${String(limit)} should not request`);
+    }
+  });
+});

sdk/src/namespaces/email.ts

@@ -6,6 +6,7 @@
 
 import type { Client } from "../kernel.js";
 import { ApiError, LocalError, ProjectNotFound } from "../errors.js";
+import { assertPositiveSafeInteger } from "../validation.js";
 
 const SLUG_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 
@@ -353,6 +354,10 @@ export class Email {
 
   /** List messages in the project's mailbox. */
   async list(projectId: string, opts: ListEmailsOptions = {}): Promise<EmailSummary[]> {
+    if (opts.limit !== undefined) {
+      assertPositiveSafeInteger(opts.limit, "limit", "listing emails");
+    }
+
     const { id, serviceKey } = await this.resolveMailbox(projectId);
     const qs = new URLSearchParams();
     if (opts.limit !== undefined) qs.set("limit", String(opts.limit));

sdk/src/validation.ts

@@ -0,0 +1,11 @@
+import { LocalError } from "./errors.js";
+
+export function assertPositiveSafeInteger(
+  value: number,
+  name: string,
+  context: string,
+): void {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new LocalError(`${name} must be a positive safe integer.`, context);
+  }
+}