The way out is a deep link, not the dashboard lobby

The exhausted-credits message pointed at DASHBOARD_URL and left the
reader to find billing, find the button, find the modal. The app gives
that modal a URL (/billing?topup=open, since app PR #1972), so the
message now hands over the purchase directly, and names /plans for the
upgrade path. Constants live in open-url.ts beside the other canonical
URLs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: pablomogamon

src/core/errors.ts

@@ -5,7 +5,7 @@
  * a `next_action`, and optional `suggested_commands`. Agents (and humans) can
  * react to the code and follow the suggested command without guessing.
  */
-import { DASHBOARD_URL } from "./open-url.ts";
+import { BILLING_TOPUP_URL, PLANS_URL } from "./open-url.ts";
 
 export type ErrorCode =
   | "AUTH_MISSING"
@@ -96,7 +96,7 @@ export function quotaExhausted(
   const renewLine = "Credits renew at the end of the billing period — run `zenrows usage` for the date.";
   const claimLine = claimUrl
     ? `You are on the Zenrows Free plan. Claim your account to keep your usage and add credits: ${claimUrl}. ${renewLine}`
-    : `You are out of Zenrows credits. ${renewLine} To carry on now, add credits or upgrade your plan: ${DASHBOARD_URL}`;
+    : `You are out of Zenrows credits. ${renewLine} To carry on now, add a credit pack (${BILLING_TOPUP_URL} opens the purchase directly) or upgrade your plan: ${PLANS_URL}`;
   const detail = opts.detail ? `${opts.detail.replace(/\.\s*$/, "")}. ` : "";
   return new ToolkitError({
     code: "POLICY_MAX_CREDITS_EXCEEDED",

src/core/open-url.ts

@@ -10,6 +10,9 @@ export const AGENT_SIGNUP_API_URL = "https://app.zenrows.com/api/agent/signup";
 /** Well-known path advertising the agent-auth endpoints (signup discovery). */
 export const WELL_KNOWN_PROTECTED_RESOURCE = "/.well-known/oauth-protected-resource";
 export const DASHBOARD_URL = "https://app.zenrows.com/dashboard";
+/** Lands on Billing with the credit-pack purchase modal already open (app PR #1972). */
+export const BILLING_TOPUP_URL = "https://app.zenrows.com/billing?topup=open";
+export const PLANS_URL = "https://app.zenrows.com/plans";
 export const DOCS_URL = "https://docs.zenrows.com";
 
 /** Append query params to a URL (used to attach anonymous `utm_*` attribution). */

tests/errors.test.ts

@@ -16,6 +16,12 @@ test("quotaExhausted says the allowance renews, on both account states", () => {
   for (const claim of ["https://x/claim/t", undefined]) {
     const err = quotaExhausted("https://api.zenrows.com/v1/?url=x", claim);
     assert.match(err.next_action, /renew/i);
+    if (!claim) {
+      // The route out is a deep link that lands with the purchase already open,
+      // not a generic dashboard URL the reader has to navigate from.
+      assert.ok(err.next_action.includes("https://app.zenrows.com/billing?topup=open"));
+      assert.ok(err.next_action.includes("https://app.zenrows.com/plans"));
+    }
     assert.ok(
       err.suggested_commands?.includes("zenrows usage"),
       "the exact renewal date is one command away, so point at it in both states",