@base44-preview/sdk 0.8.46-pr.278.d5b4fe4 → 0.8.47-pr.279.adde4da

package/dist/client.js

@@ -5,6 +5,7 @@ import { createAuthModule } from "./modules/auth.js";
 import { createSsoModule } from "./modules/sso.js";
 import { createConnectorsModule, createUserConnectorsModule, } from "./modules/connectors.js";
 import { getAccessToken } from "./utils/auth-utils.js";
+import { createFetchWithAuth } from "./utils/fetch-with-auth.js";
 import { createFunctionsModule } from "./modules/functions.js";
 import { createAgentsModule } from "./modules/agents.js";
 import { createAiGatewayModule } from "./modules/ai-gateway.js";
@@ -260,6 +261,15 @@ export function createClient(config) {
     // Assemble and return the client
     const client = {
         ...userModules,
+        /** See {@link Base44Client.fetchWithAuth}. */
+        fetchWithAuth: createFetchWithAuth({
+            axios: axiosClient,
+            serviceRoleAxios: serviceRoleAxiosClient,
+            appId: String(appId),
+            serverUrl,
+            functionsVersion,
+            platformHeaders: optionalHeaders,
+        }),
         /**
          * Sets a new authentication token for all subsequent requests.
          *

package/dist/client.types.d.ts

@@ -10,6 +10,7 @@ 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";
+import type { FetchWithAuthInit } from "./utils/fetch-with-auth.js";
 /**
  * Options for creating a Base44 client.
  */
@@ -139,6 +140,60 @@ export interface Base44Client {
     integrations: IntegrationsModule;
     /** Cleanup function to disconnect WebSocket connections. Call when you're done with the client. */
     cleanup: () => void;
+    /**
+     * Calls one of your app's own server routes with this client's credentials attached.
+     *
+     * Base44 keeps a user's access token in the browser's local storage, and the platform puts its own headers on a server request — so a plain `fetch()` to your app's routes carries neither, and the route sees an anonymous caller with no way to build a client. `fetchWithAuth()` is the same `fetch()` with whatever this client holds added, which is what lets the route act on behalf of the caller.
+     *
+     * What that means depends on where the client came from, because a client can only send what it has:
+     *
+     * - In a browser, from {@linkcode createClient | createClient()}: the signed-in user's `Authorization: Bearer <token>`. When nobody is signed in the request goes without it, so routes open to anonymous callers keep working.
+     * - In one of your server routes, from {@linkcode createClientFromRequest | createClientFromRequest()}: everything that function reads back — the caller's token, `Base44-App-Id`, `Base44-Api-Url`, `Base44-Functions-Version`, the signed `Base44-State`, `X-Data-Env`, and the app's per-request service credential. The callee's own `createClientFromRequest()` then rebuilds the client you are holding, service role included.
+     *
+     * That second case is why route-to-route calls need this. A sub-request carries nothing from the request that triggered it — your framework builds it from your arguments alone — so a route reached by a plain `fetch()` sees no headers at all and its `createClientFromRequest()` throws on the missing `Base44-App-Id`.
+     *
+     * Requests are restricted to your app's own origin, which is what keeps these credentials inside your app: pass a relative path beginning with a single `/`, such as `/api/orders`. An absolute URL, a protocol-relative `//host`, or anything else a URL parser would read as another origin throws. To call a Base44 backend function, use {@linkcode FunctionsModule.fetch | functions.fetch()}; for another origin, use plain `fetch()`.
+     *
+     * Two routes that need the same logic should call a shared function rather than each other — cheaper than an HTTP round trip, and it needs no headers at all. Hop when the hop is the point: rendering a page server-side, or going through a route for its own caching and route rules.
+     *
+     * @param path - A relative path on your app's own origin, such as `/api/orders`.
+     * @param init - Optional [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit) options such as `method`, `headers`, `body`, and `signal`, plus `fetch`: the transport that resolves a root-relative path against your app's routes. It defaults to the global `fetch`, which does that in a browser but not on a server — in Nitro pass its own (`import { fetch } from "nitro"`), which dispatches in-process with no network hop. Any header you set yourself is kept, so you can deliberately hand the callee a different identity.
+     * @returns Promise resolving to a native [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response).
+     * @throws {Error} When `path` is not a relative path on your app's own origin.
+     *
+     * @example
+     * ```typescript
+     * // Browser: call your app's own server route as the signed-in user
+     * const response = await base44.fetchWithAuth('/api/orders');
+     * const orders = await response.json();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // POST with a JSON body
+     * const response = await base44.fetchWithAuth('/api/orders', {
+     *   method: 'POST',
+     *   headers: { 'Content-Type': 'application/json' },
+     *   body: JSON.stringify({ productId: 'abc', quantity: 2 }),
+     * });
+     *
+     * if (!response.ok) {
+     *   throw new Error(`Request failed: ${response.status}`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Server-side render: reach the app's own route as this request
+     * import { fetch } from 'nitro';
+     * import { createClientFromRequest } from '@base44/sdk';
+     *
+     * const base44 = createClientFromRequest(event.req);
+     * const response = await base44.fetchWithAuth('/api/items', { fetch });
+     * const items = await response.json();
+     * ```
+     */
+    fetchWithAuth(path: string, init?: FetchWithAuthInit): Promise<Response>;
     /**
      * Sets a new authentication token for all subsequent requests.
      *

package/dist/utils/fetch-with-auth.d.ts

@@ -0,0 +1,46 @@
+import type { AxiosInstance } from "axios";
+/** `fetch`-compatible transport that can resolve a root-relative path. */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** Options for {@link Base44Client.fetchWithAuth}. */
+export interface FetchWithAuthInit extends RequestInit {
+    /**
+     * The `fetch` that resolves a root-relative path against your app's own
+     * routes. Defaults to the global `fetch`, which does that in a browser but
+     * not on a server, where a path with no origin has nothing to resolve
+     * against. In Nitro pass its own, which routes a leading-slash path
+     * in-process: `import { fetch } from "nitro"`.
+     */
+    fetch?: FetchLike;
+}
+/**
+ * Builds the client's `fetchWithAuth`: a `fetch` to the app's own origin that
+ * carries whatever credentials this client holds.
+ *
+ * That is the user's access token in a browser, and from
+ * `createClientFromRequest()` the full set that function reads back — so a
+ * route reached this way rebuilds the caller's client, service role included.
+ * The service credential is minted per request for the app as a whole, not for
+ * one route, so a handler in the same worker already runs with that authority;
+ * reaching it through a route hop is the privilege it would have had by
+ * importing a shared function. What must never happen is a credential leaving
+ * the app, and the relative-path rule, not a shorter header list, is what
+ * prevents that.
+ *
+ * @param axios - The user-scoped instance. Its `Authorization` default is the
+ * live token: it follows `setToken()` and is deleted on `logout()`, so a
+ * request never carries a token the user no longer has. From
+ * `createClientFromRequest()` it holds the caller's own token.
+ * @param serviceRoleAxios - The service-role instance, holding the app's
+ * per-request credential as its own `Authorization` default. A browser client
+ * has none, so nothing is sent.
+ * @internal
+ */
+export declare function createFetchWithAuth({ axios, serviceRoleAxios, appId, serverUrl, functionsVersion, platformHeaders, }: {
+    axios: AxiosInstance;
+    serviceRoleAxios: AxiosInstance;
+    appId: string;
+    serverUrl: string;
+    functionsVersion?: string;
+    platformHeaders?: Record<string, string>;
+}): (path: string, init?: FetchWithAuthInit) => Promise<Response>;
+export {};

package/dist/utils/fetch-with-auth.js

@@ -0,0 +1,77 @@
+/**
+ * Builds the client's `fetchWithAuth`: a `fetch` to the app's own origin that
+ * carries whatever credentials this client holds.
+ *
+ * That is the user's access token in a browser, and from
+ * `createClientFromRequest()` the full set that function reads back — so a
+ * route reached this way rebuilds the caller's client, service role included.
+ * The service credential is minted per request for the app as a whole, not for
+ * one route, so a handler in the same worker already runs with that authority;
+ * reaching it through a route hop is the privilege it would have had by
+ * importing a shared function. What must never happen is a credential leaving
+ * the app, and the relative-path rule, not a shorter header list, is what
+ * prevents that.
+ *
+ * @param axios - The user-scoped instance. Its `Authorization` default is the
+ * live token: it follows `setToken()` and is deleted on `logout()`, so a
+ * request never carries a token the user no longer has. From
+ * `createClientFromRequest()` it holds the caller's own token.
+ * @param serviceRoleAxios - The service-role instance, holding the app's
+ * per-request credential as its own `Authorization` default. A browser client
+ * has none, so nothing is sent.
+ * @internal
+ */
+export function createFetchWithAuth({ axios, serviceRoleAxios, appId, serverUrl, functionsVersion, platformHeaders, }) {
+    const inherited = new Headers(platformHeaders);
+    const bearer = (client) => {
+        const header = client.defaults.headers.common["Authorization"];
+        return typeof header === "string" && header.startsWith("Bearer ")
+            ? header
+            : null;
+    };
+    return async function fetchWithAuth(path, init = {}) {
+        assertOwnOriginPath(path);
+        const { fetch: transport = fetch, ...requestInit } = init;
+        const headers = new Headers(init.headers);
+        // A caller-supplied value always wins, so a route can hand the callee a
+        // different identity on purpose (say, dropping Authorization to render a
+        // page as anonymous).
+        const inherit = (name, value) => {
+            if (value && !headers.has(name))
+                headers.set(name, value);
+        };
+        // Exactly what createClientFromRequest reads, so the callee can rebuild
+        // this client. Keep the two in step.
+        inherit("Authorization", bearer(axios));
+        inherit("Base44-Service-Authorization", bearer(serviceRoleAxios));
+        inherit("Base44-App-Id", appId);
+        inherit("Base44-Api-Url", serverUrl);
+        inherit("Base44-Functions-Version", functionsVersion);
+        inherit("Base44-State", inherited.get("Base44-State"));
+        inherit("X-Data-Env", inherited.get("X-Data-Env"));
+        // The path is passed through untouched: resolving it here would need a
+        // document, and a root-relative path is already what a runtime that
+        // dispatches in-process (Nitro's `fetch`) expects. `host` is deliberately
+        // never sent — such a runtime synthesizes the sub-request's origin from it,
+        // so forwarding the inbound one would point the hop at another host.
+        return transport(path, { ...requestInit, headers });
+    };
+}
+function assertOwnOriginPath(path) {
+    if (typeof path !== "string" || path === "") {
+        throw new Error("fetchWithAuth() requires a path, such as '/api/orders'.");
+    }
+    // Check what a URL parser would see, not the raw string: it drops every ASCII
+    // tab/newline anywhere in the input and trims leading C0/space, so
+    // "/<tab>/evil.example" would pass a naive prefix check and then resolve to
+    // another host.
+    const asParsed = path.replace(/[\t\n\r]/g, "").replace(/^[\x00-\x20]+/, "");
+    // One leading slash is the whole rule: it cannot carry a scheme, and it rules
+    // out the two forms that reach another origin — "//host" and, since URL
+    // parsing treats a backslash as a slash, "/\host".
+    if (!asParsed.startsWith("/") ||
+        asParsed.startsWith("//") ||
+        asParsed.startsWith("/\\")) {
+        throw new Error(`fetchWithAuth() only sends requests to your app's own origin, so your app's credentials never reach a third party. "${path}" is not a path on it — pass a relative path such as '/api/orders'. Use base44.functions.fetch() to call a Base44 backend function, or plain fetch() for another origin.`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.46-pr.278.d5b4fe4",
+  "version": "0.8.47-pr.279.adde4da",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",