From b5fe7ea8a7df59fe15820b26c2fc77b77fee3826 Mon Sep 17 00:00:00 2001 From: Sam Markowitz Date: Tue, 17 Mar 2026 12:57:36 +0200 Subject: [PATCH] docs: add functions.fetch() JSDoc and fix external link stripping Add @example blocks and improved descriptions for the fetch() method. Update invoke() to mention it uses POST and cross-reference fetch(). Fix removeNonExposedTypeLinks stripping external URLs (e.g. MDN links). Add functions method ordering to method-order.json. Made-with: Cursor --- .../file-processing/file-processing.js | 5 ++ .../method-order.json | 20 +++++ src/modules/functions.types.ts | 73 +++++++++++++++---- 3 files changed, 85 insertions(+), 13 deletions(-) create mode 100644 scripts/mintlify-post-processing/method-order.json diff --git a/scripts/mintlify-post-processing/file-processing/file-processing.js b/scripts/mintlify-post-processing/file-processing/file-processing.js index 4589768..f3a1e69 100755 --- a/scripts/mintlify-post-processing/file-processing/file-processing.js +++ b/scripts/mintlify-post-processing/file-processing/file-processing.js @@ -1834,6 +1834,11 @@ function removeNonExposedTypeLinks(content, exposedTypeNames) { const updatedContent = content.replace( linkRegex, (match, backtick, typeName, linkPath) => { + // Preserve external links (e.g. MDN docs) — only strip internal type refs + if (/^https?:\/\//.test(linkPath)) { + return match; + } + // Check if this looks like a type doc link (path ends with the type name) const pathEnd = linkPath .split("/") diff --git a/scripts/mintlify-post-processing/method-order.json b/scripts/mintlify-post-processing/method-order.json new file mode 100644 index 0000000..8c05055 --- /dev/null +++ b/scripts/mintlify-post-processing/method-order.json @@ -0,0 +1,20 @@ +{ + "entities": [ + "get", + "list", + "filter", + "create", + "bulkCreate", + "importEntities", + "update", + "updateMany", + "bulkUpdate", + "delete", + "deleteMany", + "subscribe" + ], + "functions": [ + "invoke", + "fetch" + ] +} diff --git a/src/modules/functions.types.ts b/src/modules/functions.types.ts index 5e3d776..b4e8b30 100644 --- a/src/modules/functions.types.ts +++ b/src/modules/functions.types.ts @@ -20,7 +20,9 @@ export type FunctionName = keyof FunctionNameRegistry extends never /** * Options for {@linkcode FunctionsModule.fetch}. * - * Uses native `fetch` options directly. + * Alias of the native [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit) type. + * Any option accepted by the browser `fetch` API is valid (`method`, `headers`, `body`, `signal`, etc.). + * Auth headers are merged in automatically; you do not need to set them. */ export type FunctionsFetchInit = RequestInit; @@ -53,11 +55,13 @@ export interface FunctionsModule { /** * Invokes a custom backend function by name. * - * Calls a custom backend function deployed to the app. + * Sends a POST request to a custom backend function deployed to the app. * The function receives the provided data as named parameters and returns * the result. If any parameter is a `File` object, the request will automatically be * sent as `multipart/form-data`. Otherwise, it will be sent as JSON. * + * For streaming responses, non-POST methods, or raw response access, use {@linkcode fetch | fetch()} instead. + * * @param functionName - The name of the function to invoke. * @param data - An object containing named parameters for the function. * @returns Promise resolving to the function's response. The `data` property contains the data returned by the function, if there is any. @@ -91,19 +95,62 @@ export interface FunctionsModule { /** * Performs a direct HTTP request to a backend function path and returns the native `Response`. * - * Use this method when you need low-level control over the request/response that the higher-level - * `invoke()` abstraction doesn't provide, such as: - * - Streaming responses (SSE, chunked text, NDJSON) - * - Custom HTTP methods (PUT, PATCH, DELETE, etc.) - * - Custom headers or request configuration - * - Access to raw response metadata (status, headers) - * - Direct control over request/response bodies + * Use `fetch()` when you need low-level control that {@linkcode invoke | invoke()} doesn't provide, such as: + * - Streaming responses, like SSE, chunked text, or NDJSON + * - Custom HTTP methods, like PUT, PATCH, or DELETE + * - Raw response access, including status codes, headers, and binary bodies + * + * @param path - Function path. Leading slash is optional, so `/chat` and `chat` are equivalent. For example, `'/streaming_demo'` or `'reports/export'`. + * @param init - Optional [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit) options such as `method`, `headers`, `body`, and `signal`. Auth headers are added automatically. + * @returns Promise resolving to a native [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response). + * + * @example + * ```typescript + * // Stream an SSE response + * const response = await base44.functions.fetch('/chat', { + * method: 'POST', + * headers: { 'Content-Type': 'application/json' }, + * body: JSON.stringify({ prompt: 'Hello!' }), + * }); + * + * const reader = response.body!.getReader(); + * const decoder = new TextDecoder(); * - * Requests are sent to `/api/functions/`. + * while (true) { + * const { done, value } = await reader.read(); + * if (done) break; + * console.log(decoder.decode(value, { stream: true })); + * } + * ``` * - * @param path - Function path, e.g. `/streaming_demo` or `/streaming_demo/deep/path` - * @param init - Native fetch options. - * @returns Promise resolving to a native fetch `Response` + * @example + * ```typescript + * // PUT request + * const response = await base44.functions.fetch('/users/profile', { + * method: 'PUT', + * headers: { 'Content-Type': 'application/json' }, + * body: JSON.stringify({ name: 'Jane', role: 'admin' }), + * }); + * + * if (!response.ok) { + * throw new Error(`Request failed: ${response.status}`); + * } + * + * const updated = await response.json(); + * ``` + * + * @example + * ```typescript + * // Download a binary file + * const response = await base44.functions.fetch('/export/report'); + * const blob = await response.blob(); + * + * const url = URL.createObjectURL(blob); + * const a = document.createElement('a'); + * a.href = url; + * a.download = 'report.pdf'; + * a.click(); + * ``` */ fetch(path: string, init?: FunctionsFetchInit): Promise; }