set backend url

Author: semihcihan

.env.example

@@ -7,7 +7,8 @@
 # ASO_SIRP_USE_RUBY_PROOF=0
 # Optional override for auto-generated anonymous backend client id
 # ASO_CLIENT_ID=
-# Optional backend API base URL
+# Optional backend API base URL override.
+# Default: https://aso-difficulty-api.umitsemihcihan.workers.dev
 # ASO_BACKEND_BASE_URL=
 
 # Optional ASO resilience tuning

cli/services/backend/aso-backend-client.test.ts

@@ -8,6 +8,8 @@ import { AsoBackendClient } from "./aso-backend-client";
 jest.mock("axios");
 
 describe("aso-backend-client", () => {
+  const defaultBackendUrl =
+    "https://aso-difficulty-api.umitsemihcihan.workers.dev";
   const mockedAxios = jest.mocked(axios);
   const originalEnv = process.env;
   const testHome = path.join(
@@ -36,7 +38,13 @@ describe("aso-backend-client", () => {
     expect(context.entitlements.topApps).toBe(true);
   });
 
-  it("returns paywalled result when backend is not configured", async () => {
+  it("uses default backend when backend url env is not configured", async () => {
+    mockedAxios.post.mockResolvedValueOnce({
+      data: {
+        difficultyScore: 37,
+      },
+    } as any);
+
     const service = new AsoBackendClient();
     const score = await service.scoreDifficulty({
       keyword: "term",
@@ -48,13 +56,14 @@ describe("aso-backend-client", () => {
     });
 
     expect(score).toEqual({
-      difficultyScore: null,
-      difficultyState: "paywalled",
-      code: "ENTITLEMENT_UNAVAILABLE",
-      feature: "difficulty",
-      message: "Difficulty scoring backend is not configured.",
-      upgradeUrl: null,
+      difficultyScore: 37,
+      difficultyState: "ready",
     });
+    expect(mockedAxios.post).toHaveBeenCalledWith(
+      `${defaultBackendUrl}/v1/aso/difficulty/score`,
+      expect.any(Object),
+      expect.any(Object)
+    );
   });
 
   it("maps backend plan-required errors to paywalled result", async () => {

cli/services/backend/aso-backend-client.ts

@@ -14,6 +14,8 @@ import type {
 } from "./aso-backend-types";
 
 const DEFAULT_CONTEXT_TTL_SECONDS = 86400;
+const DEFAULT_ASO_BACKEND_BASE_URL =
+  "https://aso-difficulty-api.umitsemihcihan.workers.dev";
 
 type CachedContextEnvelope = {
   context: AsoBackendContext;
@@ -159,11 +161,12 @@ export class AsoBackendClient {
     return headers;
   }
 
-  private get baseUrl(): string | null {
+  private get baseUrl(): string {
     const raw = process.env.ASO_BACKEND_BASE_URL;
-    if (!raw) return null;
-    const trimmed = raw.trim();
-    return trimmed === "" ? null : trimmed.replace(/\/+$/, "");
+    const trimmed = typeof raw === "string" ? raw.trim() : "";
+    const resolved =
+      trimmed === "" ? DEFAULT_ASO_BACKEND_BASE_URL : trimmed;
+    return resolved.replace(/\/+$/, "");
   }
 
   private get cacheTtlSeconds(): number {
@@ -218,9 +221,6 @@ export class AsoBackendClient {
   }
 
   private async fetchContextFromBackend(): Promise<AsoBackendContext> {
-    if (!this.baseUrl) {
-      return buildDefaultContext();
-    }
     const response = await axios.get(`${this.baseUrl}/v1/client/context`, {
       headers: this.buildBackendHeaders(),
       timeout: 15000,
@@ -354,13 +354,6 @@ export class AsoBackendClient {
   }
 
   async scoreDifficulty(payload: DifficultyScorePayload): Promise<DifficultyScoreResult> {
-    if (!this.baseUrl) {
-      return this.buildPaywalledDifficultyResult({
-        code: "ENTITLEMENT_UNAVAILABLE",
-        message: "Difficulty scoring backend is not configured.",
-      });
-    }
-
     try {
       const response = await axios.post(
         `${this.baseUrl}/v1/aso/difficulty/score`,

docs/aso-runtime-flows.md

@@ -9,6 +9,8 @@ Runtime flow contracts across CLI commands, local dashboard API, and ASO service
 
 ## Operational Prerequisite
 - Apple Search Ads setup is required only for ASO command flows (`aso ...`).
+- Difficulty/context backend defaults to `https://aso-difficulty-api.umitsemihcihan.workers.dev`.
+- `ASO_BACKEND_BASE_URL` is an optional override for non-production backends.
 - Required setup items:
   - Apple Search Ads account
   - Linked App Store Connect account in Apple Search Ads

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "aso-cli",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Local App Store Optimization CLI",
   "main": "cli/dist/cli.js",
   "bin": {