feat(app): add base44.app.getPublicSettings() (#268)

The generated app templates read the app's access policy by hand-rolling an
axios client from a deep, non-public path:

    import { createAxiosClient } from '@base44/sdk/dist/utils/axios-client';

That path is not formal API — it resolves today only because the package ships
no exports map, and it breaks silently the moment one is added. It also forces
the template to hold the access token itself and to know the API route.

base44.app.getPublicSettings() moves both concerns into the SDK: the request
goes out on the client's own axios instance, so it carries the client's token
and the caller handles neither. Gating still surfaces as a Base44Error with
status 403 and data.extra_data.reason, which is what the templates branch on.

The public_settings union moves out of AppLike so the response type and the app
record share one definition.

Co-authored-by: David Susskind <dev@example.com>

Author: davidsu

scripts/mintlify-post-processing/types-to-expose.json

@@ -6,6 +6,8 @@
   "AiGatewayModule",
   "AnalyticsModule",
   "AppLogsModule",
+  "AppModule",
+  "AppPublicSettingsResponse",
   "AuthModule",
   "ConnectorApiRequest",
   "ConnectorApiResponse",

src/client.ts

@@ -12,6 +12,7 @@ import { createFunctionsModule } from "./modules/functions.js";
 import { createAgentsModule } from "./modules/agents.js";
 import { createAiGatewayModule } from "./modules/ai-gateway.js";
 import { createAppLogsModule } from "./modules/app-logs.js";
+import { createAppModule } from "./modules/app.js";
 import { createUsersModule } from "./modules/users.js";
 import { RoomsSocket, RoomsSocketConfig } from "./utils/socket-utils.js";
 import type {
@@ -240,6 +241,7 @@ export function createClient(config: CreateClientConfig): Base44Client {
     }),
     aiGateway: createAiGatewayModule({ serverUrl, token, appId }),
     appLogs: createAppLogsModule(axiosClient, appId),
+    app: createAppModule(axiosClient, appId),
     users: createUsersModule(axiosClient, appId),
     analytics: createAnalyticsModule({
       axiosClient,

src/client.types.ts

@@ -10,6 +10,7 @@ import type { FunctionsModule } from "./modules/functions.types.js";
 import type { AgentsModule } from "./modules/agents.types.js";
 import type { AiGatewayModule } from "./modules/ai-gateway.types.js";
 import type { AppLogsModule } from "./modules/app-logs.types.js";
+import type { AppModule } from "./modules/app.types.js";
 import type { AnalyticsModule } from "./modules/analytics.types.js";
 import type { ActorsModule } from "./modules/actors.types.js";
 
@@ -107,6 +108,8 @@ export interface Base44Client {
   analytics: AnalyticsModule;
   /** {@link AppLogsModule | App logs module} for tracking app usage. */
   appLogs: AppLogsModule;
+  /** {@link AppModule | App module} for reading the app's own public configuration. */
+  app: AppModule;
   /** {@link ActorsModule | Actors module} for subscribing to and sending messages via Cloudflare Durable Object-backed Actors. */
   actors: ActorsModule;
   /** {@link AuthModule | Auth module} for user authentication and management. */

src/index.ts

@@ -106,6 +106,11 @@ export type {
 } from "./modules/ai-gateway.types.js";
 
 export type { AppLogsModule } from "./modules/app-logs.types.js";
+export type {
+  AppModule,
+  AppPublicSettings,
+  AppPublicSettingsResponse,
+} from "./modules/app.types.js";
 
 export type {
   ActorsModule,

src/modules/app.ts

@@ -0,0 +1,21 @@
+import { AxiosInstance } from "axios";
+import { AppModule } from "./app.types";
+
+/**
+ * Creates the app module for the Base44 SDK.
+ *
+ * @param axios - Axios instance
+ * @param appId - Application ID
+ * @returns App module for reading the app's own configuration
+ * @internal
+ */
+export function createAppModule(
+  axios: AxiosInstance,
+  appId: string
+): AppModule {
+  return {
+    async getPublicSettings() {
+      return axios.get(`/apps/public/prod/public-settings/by-id/${appId}`);
+    },
+  };
+}

src/modules/app.types.ts

@@ -1,3 +1,63 @@
+/**
+ * The app's access policy: whether the app is reachable without an account, and
+ * who may sign in.
+ */
+export type AppPublicSettings =
+  | "private_with_login"
+  | "public_with_login"
+  | "public_without_login"
+  | "workspace_with_login"
+  | string;
+
+/**
+ * The app's public configuration, as returned by {@link AppModule.getPublicSettings}.
+ */
+export interface AppPublicSettingsResponse {
+  /** The app's ID. */
+  id: string;
+  /** The app's access policy. */
+  public_settings: AppPublicSettings;
+}
+
+/**
+ * App module for reading the app's own public configuration.
+ *
+ * Use it to discover how the app is gated before rendering it, so a private app
+ * can send the visitor to login instead of rendering an empty shell.
+ *
+ * ## Authentication Modes
+ *
+ * This module is available to use with a client in all authentication modes. The
+ * client's token, when it has one, is sent with the request — a signed-in visitor
+ * who has no access to the app is reported differently from an anonymous one.
+ */
+export interface AppModule {
+  /**
+   * Get the app's public configuration.
+   *
+   * Rejects with a {@linkcode Base44Error} when the visitor may not open the app:
+   * `status` is `403` and `data.extra_data.reason` says why — `"auth_required"`
+   * when the visitor must sign in, `"user_not_registered"` when the signed-in
+   * visitor has no access to this app.
+   *
+   * @returns Promise resolving to the app's ID and access policy.
+   *
+   * @example
+   * ```typescript
+   * // Decide what to render before the app boots
+   * try {
+   *   const { public_settings } = await base44.app.getPublicSettings();
+   *   console.log('App access policy:', public_settings);
+   * } catch (error) {
+   *   if (error.status === 403) {
+   *     console.log('Blocked because:', error.data?.extra_data?.reason);
+   *   }
+   * }
+   * ```
+   */
+  getPublicSettings(): Promise<AppPublicSettingsResponse>;
+}
+
 /**
  * @internal
  */
@@ -59,12 +119,7 @@ export interface AppLike {
   agents?: Record<string, any>;
   logo_url?: string;
   slug?: string;
-  public_settings?:
-    | "private_with_login"
-    | "public_with_login"
-    | "public_without_login"
-    | "workspace_with_login"
-    | string;
+  public_settings?: AppPublicSettings;
   is_blocked?: boolean;
   github_repo_url?: string;
   main_page?: string;

tests/unit/app.test.ts

@@ -0,0 +1,79 @@
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import nock from "nock";
+import { Base44Error, createClient } from "../../src/index.ts";
+
+describe("App module", () => {
+  const appId = "test-app-id";
+  const serverUrl = "https://base44.app";
+  const token = "user-token-456";
+  const publicSettingsPath = `/api/apps/public/prod/public-settings/by-id/${appId}`;
+  let base44: ReturnType<typeof createClient>;
+  let scope: nock.Scope;
+
+  beforeEach(() => {
+    base44 = createClient({ serverUrl, appId, token });
+    scope = nock(serverUrl);
+  });
+
+  afterEach(() => {
+    nock.cleanAll();
+  });
+
+  test("getPublicSettings returns the app id and its access policy", async () => {
+    scope
+      .get(publicSettingsPath)
+      .reply(200, { id: appId, public_settings: "public_without_login" });
+
+    const settings = await base44.app.getPublicSettings();
+
+    expect(settings).toEqual({
+      id: appId,
+      public_settings: "public_without_login",
+    });
+    expect(scope.isDone()).toBe(true);
+  });
+
+  test("getPublicSettings authenticates with the client's token, so callers never handle it", async () => {
+    scope
+      .get(publicSettingsPath)
+      .matchHeader("Authorization", `Bearer ${token}`)
+      .reply(200, { id: appId, public_settings: "private_with_login" });
+
+    await base44.app.getPublicSettings();
+
+    expect(scope.isDone()).toBe(true);
+  });
+
+  test("getPublicSettings sends no Authorization header for an anonymous client", async () => {
+    const anonymous = createClient({ serverUrl, appId });
+
+    scope
+      .get(publicSettingsPath)
+      .matchHeader("Authorization", (value) => value === undefined)
+      .reply(200, { id: appId, public_settings: "public_without_login" });
+
+    await anonymous.app.getPublicSettings();
+
+    expect(scope.isDone()).toBe(true);
+  });
+
+  test.each([
+    ["auth_required", "the visitor must sign in"],
+    ["user_not_registered", "the visitor has no access to this app"],
+  ])(
+    "getPublicSettings surfaces a 403 %s as a Base44Error carrying the reason",
+    async (reason) => {
+      scope
+        .get(publicSettingsPath)
+        .reply(403, { extra_data: { app_id: appId, reason } });
+
+      const error = await base44.app
+        .getPublicSettings()
+        .catch((rejection) => rejection);
+
+      expect(error).toBeInstanceOf(Base44Error);
+      expect(error.status).toBe(403);
+      expect(error.data.extra_data.reason).toBe(reason);
+    }
+  );
+});